Stacked on #475 (`refactor/ui_web_architecture`): the conventions that keep the rebuilt `ui-web/` from drifting, written down in `ui-web/CONTRIBUTING.md` and enforced by gates. Twenty-two commits, each landed with every gate green. Three of them change what a DOM diff sees and are named below; the rest are DOM-invisible. - **One store shape.** `state/store.ts` exports `makeStore<T>()` with `get / set / subscribe / _resetForTests`; 33 hand-rolled stores migrated, `getState` / `put` / `commit` / `wipe` retired; the `store-shape` gate pins the eight modules that keep a different shape, each with its reason. - **One source seam.** `ds<K extends keyof Sources>(domain: K)` is key-typed, so a renamed or missing domain is a compile error; every `gateway()` call lives in a domain's `source.ts` (`rpc-names` enforces placement); `app/install.ts` is the only module that assigns `sources.*`; skills has its own `source.ts` and the shared `ext.list` read is `features/installed/source.ts`. - **No island bag.** `features/registry.ts`'s `islands` object is gone; page-wide code imports a domain's store directly, and the three callbacks `state/page.ts` needed are registered from `app/install.ts`. That one edge was 18% of the import graph's closure weight and held the tree's only module-evaluation-order hazard. The `import-direction` gate now pins the layering (`lib <- components <- chrome <- app`, `lib <- rpc <- state <- chrome, features, app`, `features -/-> features` except `source.ts`/`types.ts`) with today's upward and cross-domain edges as a down-or-gone list. Two of the four pinned import cycles are dissolved the way the gate prescribes (a state module declares a slot, the domain fills it): `state/page.ts` no longer reads `state/caps.ts`, `state/navfly.ts` no longer imports the rail store; 17 files sit in a cycle now, in two components, down from 21 in four. - **Language is resolved at boot** (localStorage, then config, then `<html lang>`), so `t(key)` is the only way to take a string; every island root subscribes to the language store and the hand-kept repaint list shrinks to the two imperative steps. `T()` and `lang.text()` are retired, and so are the 61 inert `data-i18n*` attributes the old document walk used to read. - **Each domain declares itself once.** `features/<domain>/manifest.ts` (aggregated in `features/manifests.ts`) and `state/pages.ts` drive the page sections, the Escape order, the body order, the rail buttons, the mounts and the region goldens; `domain-shape` and `domain-registration` gates hold the two tables together. - **Homes and names.** The desk is its own domain (`features/desk/`); `resume` lives with the session runtime; the composer's three sheets live in the composer; the session naming protocol is `state/session/naming.ts`; `features/xa/` is `features/extAgents/` with matching ids and exports; wiring modules are all `wire.ts`; page roots are all `<Domain>App`; `popover`, `pane`, `escapeOrder`, `installEntry` / `installSkill`, `Frame` replace the competing words; `useInTask` (not a hook) is `startTaskWith`; the `file-names` gate pins the case rules. - **Hooks and types.** `react-hooks/rules-of-hooks` is an error (the seven warnings were a misnamed verb and one hook after an early return, now `PlainCallRow`); `tsconfig` adds `noUnusedParameters` and the eight sites it named are gone; `npm run lint` is down to seven warnings, all `exhaustive-deps` effects that deliberately run once plus one guarded expression. - **Gates and tooling.** The stylesheet hash pin is retired (the eleven declaration-level CSS gates remain), the six CSS gates share one parser, `check-css` and `check-class-namespace` run under `npm test`; the class-namespace gate covers every domain with a per-domain prefix, reads class literals inside `className={...}` expressions as well as attributes, and pins today's debt as three down-or-gone lists (86 shared, 342 unprefixed, 91 unprefixed in expressions); fixture responders return `Wire<ResultOf<M>>` instead of `as`-asserted literals (which exposed five fixture answers that did not match the contract), and the turn script fixture is a typed union with no cast left; the offline library's coverage of every called method is gated with a named exemption list; `boot-order` is three gates by concern; eslint with import sorting and unused checks (the tui's config) runs as `npm run lint` after a one-time 206-file sweep, and `make lint-ui` and the CI ui job run it. - **Docs and comments.** `ui-web/CONTRIBUTING.md` (layout, domain skeleton, store shape, rendering, source and fixtures, naming, CSS, tests and gates, tooling, the adding-a-domain checklist, and a table of every pinned exception), new `ui-web/CONTEXT.md` entries, a README whose layout table matches the tree, and `tests/test_living_docs.py` scanning all three. Every code comment that explained a decision by what the deleted script layers used to do now names the live owner or is gone. What a reader can see change: - The offline `?stub=1` page and the first live frame before the config answers now render in one resolved language instead of Chinese markup with English dynamic text; two tooltip strings in the boot golden moved with it, and the golden now records tooltip attributes by name rather than by sentence. - Domain ids follow their directory: `#extAgentsPage`, `#connectionsPage`, `#memoryPage`, `#playbooksPage` and their bodies and rail buttons. `page.css` referenced none of them; the knowledge page keeps `#kbPage` because the stylesheet pins it. - The 61 `data-i18n`, `-ph`, `-title`, `-aria` and `-tip` attributes are gone from the chrome markup. No selector, dataset read, stylesheet rule or gate named one; the 14 goldens that carried them change by exactly those attributes and nothing else (each new golden diffs clean against the old one with the attribute text stripped). Also restored: the cron page's run-history refetch on a language change, which the earlier `redrawAll` deletion had dropped. Outside `ui-web/`, three files: the `Makefile`'s `lint-ui` target and the CI ui job gain `npm run lint`, and `tests/test_living_docs.py` scans the three `ui-web/` documents. Not in this PR, each recorded in `CONTRIBUTING.md`'s exceptions table: i18n namespaces still use their old abbreviations because the catalogue (`i18n/messages.json`) is shared with the TUI and lives outside `ui-web/`; the two remaining import cycles (the six-file composer/transcript/workspace knot and the eleven-file session knot); the class names still defined in `page.css` rather than per domain; the three places `rpc-schema/openrpc.json` disagrees with its own descriptions, which is the backend's to settle. - [ ] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [x] Refactor - [ ] Other From the repo root, on the branch head: - `cd ui-web && npm run type-check && npm run lint` -> clean, 7 warnings (from 14 on the base's first lint run), 0 errors - `cd ui-web && HOME=$(mktemp -d) npx vitest run` -> 162 files, 2534 tests passed, 0 skipped (from 152 / 2494 on the base; one test whose subject was deleted went with it) - `make build-ui` -> `boot-snapshot: OK (284 nodes match golden)` and `boot-snapshot: OK (285 nodes match golden)` - `make lint-ui` -> `gen:check`, `npm run lint`, `type-check` all clean - `cd ui-web && node scripts/check-page.mjs && node scripts/check-css.mjs && node scripts/check-class-namespace.mjs && npm run gen:check` -> all OK - `uv run --frozen pytest tests/test_ui_agent_marks.py tests/test_ui_provider_marks.py tests/test_ui_css_token_gate.py tests/test_living_docs.py -q` -> 55 passed - `make check-source-language` over `origin/main..HEAD` -> exit 0 - `uv run --frozen pre-commit run --from-ref refactor/ui_web_architecture --to-ref HEAD` -> all passed - `git diff --stat refactor/ui_web_architecture..HEAD -- . ':!ui-web'` -> exactly `Makefile`, `.github/workflows/ci.yml`, `tests/test_living_docs.py` - Every new gate was mutation-checked (one-line breakage red, restored green); per-step happy-dom dumps of the body order, listener sequence, boot walk and language flips are byte-identical across the DOM-invisible steps and differ only as described above in the other three. - Not done: a real-browser pass. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed - Security: none; no protocol or auth path changes. - Backward compatibility: build entry points, script paths CI calls, URL flags and DOM ids the stylesheet references are unchanged; renamed ids and the dropped `data-i18n*` attributes appear only in goldens. - Rollback: revert the squash merge into `refactor/ui_web_architecture`. --------- Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
171 lines
7.3 KiB
Python
171 lines
7.3 KiB
Python
"""Assemble ui-web/dist/index.html from the page skeleton, the stylesheet and the bundle.
|
|
|
|
Sources under ``src/``:
|
|
|
|
- ``page.html`` -- the document skeleton (markup only), with two markers:
|
|
``/*__STYLE__*/`` inside its ``<style>`` tag and
|
|
``/*__MODERN__*/`` inside its ``<script>`` tag.
|
|
- ``styles/page.css`` -- the page's own stylesheet, injected at the style marker.
|
|
- ``.modern/domains.css`` -- the domains' own stylesheets, which Vite collects
|
|
from every ``features/<domain>/styles.css`` an App imports;
|
|
injected into the same ``<style>`` block, after page.css.
|
|
Vite closes that asset with a ``/*$vite$:N*/`` marker
|
|
comment of its own, which rides along as written.
|
|
- ``.modern/modern.iife.js`` -- the bundle Vite builds from ``src/main.tsx``,
|
|
injected at the script marker.
|
|
|
|
Three substitutions and a copy, and no assembly of its own: every line of
|
|
JavaScript the page runs comes from that one bundle, which Vite builds from
|
|
``src/main.tsx``. The message catalogue is in it too (``src/i18n/t.ts``
|
|
imports ``i18n/messages.json``).
|
|
|
|
Run:
|
|
|
|
python ui-web/build.py
|
|
"""
|
|
|
|
import hashlib
|
|
import shutil
|
|
import subprocess
|
|
from pathlib import Path
|
|
|
|
ROOT = Path(__file__).resolve().parent
|
|
STYLE_MARK = "/*__STYLE__*/"
|
|
MODERN_MARK = "/*__MODERN__*/"
|
|
#: Replaced with a digest of the asset tree, which the page hands to the icon
|
|
#: helpers as a query on every asset URL.
|
|
#:
|
|
#: These files live at one unversioned path each, so a replaced drawing lands at
|
|
#: exactly the URL its predecessor is cached under -- and a client that decided
|
|
#: the old one was fresh keeps showing it through a rebuild, a restart and a
|
|
#: hard reload. A digest in the URL makes a changed file a different URL, which
|
|
#: no cache can answer from what it already has.
|
|
ASSETV_MARK = "__ASSETV__"
|
|
|
|
|
|
def _assets_stamp() -> str:
|
|
"""A short digest of everything under ``src/assets``, or "dev" if it is gone.
|
|
|
|
Content, not mtime: a rebuild that changes nothing should not invalidate
|
|
every icon in every client, and a checkout that restores an old file should
|
|
go back to that file's old URL.
|
|
"""
|
|
src_assets = ROOT / "src" / "assets"
|
|
if not src_assets.is_dir():
|
|
return "dev"
|
|
digest = hashlib.sha1(usedforsecurity=False)
|
|
for path in sorted(src_assets.rglob("*")):
|
|
if path.is_file():
|
|
digest.update(path.relative_to(src_assets).as_posix().encode("utf-8"))
|
|
digest.update(path.read_bytes())
|
|
return digest.hexdigest()[:10]
|
|
|
|
|
|
#: The two load modes, each with its own golden. Stub mode is the page on its
|
|
#: own fixtures (``?stub=1``); live mode is the page a reader gets when the
|
|
#: gateway is not there, which settles into a different tree and would
|
|
#: otherwise be unguarded -- a live-only boot break passes the stub snapshot
|
|
#: untouched.
|
|
_BOOT_SNAPSHOTS = (
|
|
("http://127.0.0.1:18792/?stub=1", "boot-stub.txt"),
|
|
("http://127.0.0.1:18792/", "boot-live-noserver.txt"),
|
|
)
|
|
|
|
|
|
def _domain_styles() -> str:
|
|
"""The domains' collected stylesheet, held to the domains that declare one.
|
|
|
|
A page with exactly one ``<style>`` block is the served contract
|
|
(``scripts/check-page.mjs``), so this is inlined rather than linked. Checked
|
|
both ways: a tree with a ``features/<domain>/styles.css`` and no built asset
|
|
would ship those domains unstyled with no error, and an asset with no source
|
|
is a stale ``.modern/``.
|
|
"""
|
|
declared = sorted((ROOT / "src" / "features").glob("*/styles.css"))
|
|
built = ROOT / ".modern" / "domains.css"
|
|
if declared and not built.is_file():
|
|
names = ", ".join(p.parent.name for p in declared)
|
|
raise SystemExit(
|
|
f"ui-web/.modern/domains.css not found, but {names} declare a styles.css -- "
|
|
"run `npm run --prefix ui-web build` before ui-web/build.py"
|
|
)
|
|
if built.is_file() and not declared:
|
|
raise SystemExit(
|
|
"ui-web/.modern/domains.css exists but no features/<domain>/styles.css does; "
|
|
"delete ui-web/.modern and rebuild"
|
|
)
|
|
if not declared:
|
|
return ""
|
|
return "\n" + built.read_text(encoding="utf-8").rstrip("\n")
|
|
|
|
|
|
def main() -> None:
|
|
page = (ROOT / "src" / "page.html").read_text(encoding="utf-8")
|
|
style = (ROOT / "src" / "styles" / "page.css").read_text(encoding="utf-8")
|
|
style = style[:-1] if style.endswith("\n") else style
|
|
style += _domain_styles()
|
|
# The island bundle (React features) is built by Vite, not committed:
|
|
# page assembly now has a node step ahead of this python one. Absence is
|
|
# an error rather than a warning because a page without the bundle ships
|
|
# working navigation to a blank schedules page.
|
|
modern_path = ROOT / ".modern" / "modern.iife.js"
|
|
if not modern_path.is_file():
|
|
raise SystemExit(
|
|
"ui-web/.modern/modern.iife.js not found -- run `npm ci --prefix ui-web` "
|
|
"then `npm run --prefix ui-web build` before ui-web/build.py"
|
|
)
|
|
modern = modern_path.read_text(encoding="utf-8")
|
|
modern = modern[:-1] if modern.endswith("\n") else modern
|
|
for mark, text in ((STYLE_MARK, style), (MODERN_MARK, modern)):
|
|
if page.count(mark) != 1:
|
|
raise SystemExit(f"page.html: expected exactly one {mark} marker")
|
|
page = page.replace(mark, text, 1)
|
|
out = page.replace(ASSETV_MARK, _assets_stamp(), 1)
|
|
dist = ROOT / "dist"
|
|
dist.mkdir(exist_ok=True)
|
|
# newline="" so the bytes are the same on every platform: the default
|
|
# translates "\n" to "\r\n" on Windows, which would hand a checkout there a
|
|
# differently-hashed page than the one CI and the wheel carry.
|
|
(dist / "index.html").write_text(out, encoding="utf-8", newline="")
|
|
print(f"built dist/index.html ({len(out):,} bytes)", flush=True)
|
|
|
|
# Static assets stay files rather than data: URIs -- inlining 320 KB of
|
|
# artwork would grow the page by a third again in base64 and re-download it
|
|
# on every load. The server mounts dist/assets at /assets, and the release
|
|
# wheel force-includes the whole dist directory.
|
|
src_assets = ROOT / "src" / "assets"
|
|
if src_assets.is_dir():
|
|
out_assets = dist / "assets"
|
|
shutil.rmtree(out_assets, ignore_errors=True)
|
|
shutil.copytree(src_assets, out_assets)
|
|
shutil.copy2(ROOT / "icon" / "raven.svg", out_assets / "raven.svg")
|
|
total = sum(p.stat().st_size for p in out_assets.rglob("*") if p.is_file())
|
|
print(f"copied dist/assets ({total:,} bytes)", flush=True)
|
|
for url, golden in _BOOT_SNAPSHOTS:
|
|
_check_boot_snapshot(dist / "index.html", url, golden)
|
|
|
|
|
|
def _check_boot_snapshot(index: Path, url: str, golden: str) -> None:
|
|
"""Refuse a page whose booted DOM shape moved; see scripts/boot-snapshot.mjs."""
|
|
node = shutil.which("node")
|
|
if node is None:
|
|
raise SystemExit("ui-web/build.py: node is not on PATH; the boot snapshot gate needs it")
|
|
result = subprocess.run(
|
|
[
|
|
node,
|
|
str(ROOT / "scripts" / "boot-snapshot.mjs"),
|
|
str(index),
|
|
"--url",
|
|
url,
|
|
"--golden",
|
|
str(ROOT / "scripts" / "__golden__" / golden),
|
|
],
|
|
check=False,
|
|
)
|
|
if result.returncode != 0:
|
|
raise SystemExit(f"ui-web/build.py: booted DOM shape differs from scripts/__golden__/{golden}")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|