@swiftbrowser/web 0.1.0

package/README.md

@@ -0,0 +1,600 @@
+# SwiftBrowser web renderer
+
+Vite + TypeScript (no UI framework) renderer that applies the ops stream
+described in [`docs/ops-protocol.md`](../docs/ops-protocol.md) to the DOM inside
+an iPhone-shaped frame styled with iOS design tokens, lays the tree out with a
+SwiftUI-style layout engine, animates changes, forwards taps, text input,
+toggles, selections, geometry reports, the color scheme and the Dynamic Type
+size back to the Swift/Wasm app, and drives the app's cooperative executor
+(Phase 4) so `Task`, `.task` and sleeps reach the screen.
+
+```
+index.html          Landing page (served at /): one card per registered app with an Open link and a QR code
+app/index.html      The app page (served at /app/): toolbar, iPhone frame, #screen
+src/landing.ts      Landing page script: app cards (qrcode SVGs), build info from the `define`s
+src/landing.css     Landing page styles
+src/deviceMode.ts   Frame vs device mode decision, env(safe-area-inset-*) reader, viewport watcher
+src/vite-env.d.ts   Types of the build-time defines (__SB_APPS__, __SB_COMMIT__, …)
+src/protocol.ts     TypeScript mirror of the ops protocol (Op, element kinds, Style, Color, Animation, events)
+src/renderer.ts     Renderer: Map<id, HTMLElement> + LayoutNode tree, ops, navigation, sheets, layout on commit
+src/layout/         The layout engine (propose/report/place, text wrapping, Dynamic Type table); unit-tested with vitest
+src/layoutDom.ts    Applies a LayoutResult to the DOM: absolute positioning, text lines, chrome rects
+src/animation.ts    Animator: Web Animations for animated commits / animationToken subtrees, transitions, spring easing
+src/typography.ts   Page-side Dynamic Type helpers over src/layout/typography.ts (CSS variables per text style)
+src/symbols.ts      SF Symbol name → lucide glyph table for Image(systemName:)
+src/wasm.ts         loadApp(): WASI shim, _start, sb_ops_*, sb_event, sb_alloc + sb_event_json, sb_state_*, sb_run_jobs (JobScheduler)
+src/mock.ts         Counter, Todos, Gallery and Settings fixtures + in-page mock "Swift core" for ?mock=1
+src/main.ts         App page wiring: mode, theme toggle, Text size control, app label, boot, hot-reload state stash
+src/devEvents.ts    Payload types for the sb:build-* websocket events
+src/styles.css      iOS tokens, device frame, device mode, element styles
+node/               Node side: apps.ts (the AppSpec registry type), config.ts (Vite config from specs),
+                    examples.ts (Examples/* as specs, build-wasm.sh runner, descriptions),
+                    index.ts (createDevServer / buildSite, the package entry); compiled to node/dist/
+plugins/            Vite plugins over the registry: swift-wasm.ts serves /<name>.wasm, rebuilds on Swift changes
+                    and copies the modules into dist/; app-manifests.ts: one web app manifest (+ icon) per app
+                    (/manifests/<name>.webmanifest); asset-catalogs.ts: *.xcassets -> /catalog/<name>.json + files
+e2e/                Playwright tests (mock fixtures + the real Counter.wasm / Todos.wasm / Settings.wasm)
+public/             Counter.wasm / Todos.wasm / Gallery.wasm / Settings.wasm land here (git-ignored);
+                    also manifest.webmanifest, icon.svg, apple-touch-icon.png and the Cloudflare _headers
+vite.config.ts      `npm run dev` / `vite build` for the examples: createViteConfig(exampleAppSpecs())
+tsconfig.node-build.json  Emits node/dist/ (ESM + .d.ts) for `import ... from '@swiftbrowser/web'`
+```
+
+## Run
+
+```sh
+npm install
+npm run dev          # http://localhost:5173/                 landing page (list of examples)
+                     # http://localhost:5173/app/             loads /Counter.wasm
+                     # http://localhost:5173/app/?app=Todos   loads /Todos.wasm
+                     # http://localhost:5173/app/?mock=1      hardcoded Counter fixture, no wasm needed
+npm run build        # typechecks src/, writes dist/ (dist/index.html + dist/app/index.html) and node/dist/
+npm run build:node   # only node/dist/ (the programmatic API other packages import)
+npm run preview      # serves dist/
+npm run typecheck    # src/, e2e/, node/, plugins/ and the config files
+npm run test:unit    # vitest: the layout engine (src/layout/__tests__), the plugins and the registry
+npm run test:e2e     # Playwright; starts the dev server itself
+```
+
+## App registry and the programmatic API
+
+`vite.config.ts` no longer hardcodes the examples: `node/config.ts` builds the
+Vite config from a list of `AppSpec`s (`node/apps.ts`), one per app:
+
+```ts
+interface AppSpec {
+  name: string;          // URL-safe: ?app=<name>, /<name>.wasm, /catalog/<name>.json, /manifests/<name>.webmanifest
+  displayName?: string;  // landing card title + manifest name; defaults to name
+  description?: string;  // landing card subtitle + manifest description
+  wasm: string;          // absolute path of the built module (may not exist yet in dev)
+  catalogs: string[];    // absolute *.xcassets directories
+  watch?: string[];      // absolute directories whose **/*.swift changes trigger `build`
+  build?: () => Promise<void>; // rebuilds `wasm`; rejects with the compiler output
+  icon?: string;         // absolute path of a PNG; served at /manifests/<name>-icon.png
+}
+```
+
+The three plugins take the same list: `plugins/swift-wasm.ts` serves
+`/<name>.wasm` from `spec.wasm` (building it on the first request when it is
+missing), watches `spec.watch` and copies the module into `dist/` on build;
+`plugins/asset-catalogs.ts` builds `/catalog/<name>.json` from
+`spec.catalogs`; `plugins/app-manifests.ts` writes the manifest (and the icon)
+from `displayName`, `description` and `icon`.
+
+`node/examples.ts` turns `../Examples/*` into specs (`wasm` =
+`public/<Name>.wasm`, `build` = `bash scripts/build-wasm.sh <Name>` with
+`SB_WASM_OPT=0`, `watch` = `Sources/` + the example's directory), which is
+what `npm run dev` / `vite build` use.
+
+Other packages (the CLI) import the same machinery through the package entry,
+compiled by `npm run build:node` (`tsconfig.node-build.json` → `node/dist/`):
+
+```ts
+import { createDevServer, buildSite, type AppSpec } from '@swiftbrowser/web';
+
+const server = await createDevServer({ apps, port: 5173, host: true });  // started; server.printUrls()
+await buildSite({ apps, outDir: 'dist', commit, branch });              // complete static site
+```
+
+Both resolve the Vite root (`Web/`) relative to the module and ignore
+`vite.config.ts`.
+
+## Pages and URLs
+
+The site is a Vite multi-page app (`build.rollupOptions.input` in
+`vite.config.ts`, `appType: 'mpa'`):
+
+- `/` (`index.html` + `src/landing.ts`): "SwiftBrowser examples". The list of
+  apps comes from the app registry (`node/config.ts`, see "App registry"
+  below), injected with `define` as `__SB_APPS__` (`{ name, displayName,
+  description?, icon? }[]`); `vite.config.ts` registers every directory under
+  `../Examples`, with the descriptions in `node/examples.ts`. The card title
+  is `displayName` (the name by default), the subtitle the description or
+  "the <name> app". Every card has
+  an "Open" link to `/app/?app=<Name>` and an SVG QR code of the absolute URL
+  (`location.origin + '/app/?app=' + name`, generated in the browser with the
+  `qrcode` package) so a phone can scan it from a desktop. The footer shows
+  the build info, also from `define`: `__SB_COMMIT__` (`GITHUB_SHA`, else
+  `git rev-parse --short HEAD`, else `dev`; linked to the commit on GitHub
+  unless `dev`), `__SB_BRANCH__` (`GITHUB_REF_NAME`, else
+  `git rev-parse --abbrev-ref HEAD`) and `__SB_BUILT_AT__`.
+- `/app/` (`app/index.html` + `src/main.ts`): the renderer. `import.meta.env.BASE_URL`
+  stays `/`, so the modules are still fetched from `/<Name>.wasm` and the
+  dev-server plugin's rebuild registry (which watches those requests) works
+  unchanged.
+
+The app page's query parameters:
+
+- `?app=Name` loads `/Name.wasm` instead of `/Counter.wasm` (and passes `Name`
+  as `argv[0]`). The dev server remembers every app requested this way and
+  rebuilds all of them on Swift changes (see "Hot reload").
+- `?mock=1` renders a hardcoded screen and answers events in-page, so the
+  renderer can be worked on without a Swift toolchain. Two fixtures exist:
+  - `?mock=1` (or `?mock=1&app=Counter`): the Phase 1 Counter screen; `+`/`−`
+    answer with `update` ops.
+  - `?mock=1&app=Todos`: a Phase 2 `navstack` → `navscreen` ("Todos", large
+    title) → `list` with a "Today" `section` of three rows (a `toggle`, a
+    `navlink`, an `hstack` with an `image` and text) and a second section with
+    a `roundedBorder` `textfield` plus a `bordered` "Add" button wrapped in a
+    `styled { disabled }`. The mock flips `isOn` on toggle, pushes an inline
+    "Detail" `navscreen` on the navlink, pops it on a tap of the screen's own
+    id (the back button), echoes typed text back and enables "Add" once there
+    is text. `window.__sb.app().received` lists every event it got.
+  - `?mock=1&app=Gallery`: Phase 3. A `vstack` of one `text` per text style
+    (to check Dynamic Type), a `color` and two `shape`s (a filled circle, a
+    stroked capsule) in fixed frames, an `.animation(.spring)` subtree
+    (`styled { animation, animationToken }`) around a rounded rectangle, and
+    two buttons. "Toggle" bumps the `animationToken`, swaps the shape's fill
+    (red ↔ green), doubles the frame width (80 ↔ 160) and inserts or removes
+    an "Expanded" text with `transition: opacity`, all in a commit carrying
+    `animation: easeInOut 0.35`. "Show sheet" appends a root-level `sheet`
+    (`detents: ["large"]`) with a title and a "Done" button; "Done", a tap on
+    the scrim and a drag of more than 100px all remove it (the latter two by
+    sending a `tap` with the sheet's own id). Ids are in `GALLERY_IDS`.
+  - `?mock=1&app=Settings`: Phase 4. A `tabview` (`selected: 0`) with two
+    tabs: "Home" (`house`) holds a `navstack` → `navscreen` ("Home", large
+    title) → inset-grouped `list` with a "Geometry" section (a
+    `styled { frame: { height: 22 } }` → `geometry` → `text`, which the mock
+    rewrites to the reported `W × H`) and a "Rows" section of 20 rows, long
+    enough to scroll under the tab bar; "Settings" (`gear`) holds a `list`
+    with `style: "grouped"` containing a segmented `picker` ("Appearance":
+    Light/Dark/Auto), a menu `picker` ("Units": Metric/Imperial) and a
+    `toggle`. `select` on the tab view or a picker updates its `selected`,
+    `toggle` flips `isOn`, `geometry` updates the text. Ids are in
+    `SETTINGS_IDS`; every event lands in `window.__sb.app().received`.
+
+- `?mode=device` / `?mode=frame` forces device mode or the iPhone frame (see
+  "Device mode" below).
+
+The light/dark toggle in the toolbar flips `data-theme` on the device frame and
+is remembered in `localStorage` (`sb-theme`). It only affects the phone; the
+page chrome follows the OS `prefers-color-scheme`.
+
+The **Text size** select (`#type-size`, labelled "Text size") picks one of the
+12 Dynamic Type categories (`xSmall` … `accessibility5`, default `large`),
+remembered in `localStorage` (`sb-type-size`). It sets `data-type-size` on the
+device frame, writes `--sb-ts-<style>-size` / `-lh` / `-scale` CSS variables
+for every text style (`src/typography.ts`), re-runs the layout engine with the
+new `dynamicTypeSize`, and sends an `environment` event.
+
+## Device mode (real phones)
+
+`src/deviceMode.ts` decides between two modes when the app page loads (an
+inline script in `app/index.html` applies the same rule before the first paint
+so a phone never flashes the bezel):
+
+- **frame** (desktop, tests): the fake iPhone 15 Pro bezel with its drawn
+  status bar, Dynamic Island and home indicator, plus the toolbar. Exactly as
+  before.
+- **device**: `?mode=device`, or automatically when
+  `matchMedia('(pointer: coarse)').matches` (a coarse pointer at any width:
+  a tablet fills the viewport instead of showing the phone bezel; `?mode=frame`
+  wins over the automatic rule).
+
+In device mode `<html data-sb-mode="device">` hides the toolbar and the bezel
+chrome, `#screen` fills `100dvw × 100dvh` at (0, 0), the layout environment's
+`screen` is the viewport and its `safeArea` comes from the real
+`env(safe-area-inset-top/right/bottom/left)` values, exposed as
+`--sb-inset-top/right/bottom/left` on `:root` and read with
+`getComputedStyle` (`renderer.setSafeArea`). They are non-zero only in
+standalone (home screen) mode or landscape, which is what a native app would
+get. `resize`, `orientationchange` and `visualViewport` resizes re-run the
+engine (debounced 100ms, `renderer.viewportChanged`). The color scheme follows
+`prefers-color-scheme` (and its changes), the Dynamic Type size is `large`, and
+the `environment` event carries both as usual. `touch-action: manipulation`
+and `-webkit-text-size-adjust: 100%` stop double-tap zoom and text inflation;
+the viewport meta has `viewport-fit=cover`. Hot-reload state restore and the
+job scheduler are unaffected. `window.__sb.mode` reports the mode.
+
+`app/index.html` also declares `apple-mobile-web-app-capable`,
+`apple-mobile-web-app-status-bar-style: black-translucent` (the OS status bar
+stays transparent, the app's own background shows under it and the layout
+engine gets the bar as a safe-area inset; `default` draws an opaque light bar
+whatever the app's color scheme), light/dark `theme-color`s, a web app
+manifest and the icons `public/icon.svg` + `public/apple-touch-icon.png`
+(180×180, drawn with ImageMagick to match the SVG). In Safari, Share → Add to
+Home Screen then runs an app full screen.
+
+Safari takes a home-screen icon's launch URL and label from the manifest, not
+from the page URL, so there is one manifest per example: `plugins/app-manifests.ts`
+serves `/manifests/<Name>.webmanifest` (`start_url: /app/?app=<Name>`,
+`short_name: <Name>`, `display: standalone`) in the dev server and emits them
+in `vite build`, and an inline script in `app/index.html` points
+`<link rel="manifest">` and `apple-mobile-web-app-title` at the app named by
+`?app=`. `public/manifest.webmanifest` (`start_url: /app/`, the default app)
+remains for the landing page and for `/app/` without a parameter.
+
+## Deploying (Cloudflare Pages)
+
+`npm run build` writes a static site to `dist/`: `index.html`, `app/index.html`,
+hashed `assets/`, the `.wasm` modules and everything from `public/`. The
+GitHub workflow builds every example, runs `npm ci && npm run build` in `Web/`
+and deploys `Web/dist` with `wrangler pages deploy`. `public/_headers` tells
+Pages to serve `/*.wasm` with `Content-Type: application/wasm` and
+`Cache-Control: no-cache` (the modules are not content-hashed) and the hashed
+`/assets/*` as immutable. Apps are opened as
+`https://<site>/app/?app=<Name>`; the landing page lists and QR-codes them.
+
+## Getting `Counter.wasm` into `public/`
+
+The renderer fetches `/<App>.wasm`, which Vite serves from `Web/public/`.
+Those files are build products and are git-ignored (`public/*.wasm`); only
+`public/.gitkeep` is tracked.
+
+From the repo root:
+
+```sh
+scripts/build-wasm.sh          # swift build --swift-sdk <wasm sdk> -c release, wasm-opt -Os (when installed), then
+                               # copies Counter.wasm into Web/public/
+scripts/build-wasm.sh Todos    # same for the Todos example
+```
+
+## Hot reload
+
+`npm run dev` runs the `swiftWasm()` plugin from `plugins/swift-wasm.ts`:
+
+1. It watches `../Sources/**/*.swift` and `../Examples/**/*.swift` with the
+   dev server's own file watcher and debounces changes for 300ms.
+2. It runs `bash scripts/build-wasm.sh <App>` from the repo root for every app
+   requested since the server started (`Counter` by default; a `/Todos.wasm`
+   request adds `Todos`). Build output is logged to the terminal. `swift` is
+   resolved from `$SWIFT_TOOLCHAIN_BIN`, then
+   `/root/.local/share/swiftly/toolchains/6.4.0/usr/bin` if present, then `PATH`.
+3. While building, the page shows a "Rebuilding…" indicator in the toolbar
+   (websocket events `sb:build-start` / `sb:build-end`). On success the server
+   sends a `full-reload`; on failure it sends `sb:build-error` with the
+   compiler output, which the page shows in the error banner while the current
+   app keeps running.
+4. Before the reload (`vite:beforeFullReload`, plus `beforeunload`/`pagehide`
+   as a fallback for manual refreshes), `main.ts` reads the app's `@State`
+   snapshot through `sb_state_ptr`/`sb_state_len` and stores it in
+   `sessionStorage['sb-state:<App>']`. On boot the snapshot is removed from
+   storage and passed to the new module as the WASI environment variable
+   `SB_STATE=<json>`, e.g. `SB_STATE={"ContentView#0":3}`. Modules without the
+   snapshot exports (Phase 1) are reloaded without state.
+
+Mock mode never stashes state. `window.__sb.snapshotState()` returns the
+current snapshot for inspection.
+
+Until that script exists you can copy the file by hand:
+
+```sh
+cp "$(swift build --show-bin-path --swift-sdk swift-6.4.0-RELEASE_wasm -c release)/Counter.wasm" Web/public/
+```
+
+Then `npm run dev` and open http://localhost:5173/app/ (without `?mock=1`). If the
+file is missing, the page shows an error banner under the device explaining
+what it expected.
+
+## What the renderer expects from the Wasm module
+
+See `docs/ops-protocol.md`. In short, `src/wasm.ts`:
+
+1. fetches and compiles the module; it must import only `wasi_snapshot_preview1`;
+2. instantiates it with `@bjorn3/browser_wasi_shim` (`args: ["Counter"]`,
+   `env: []`, stdout/stderr forwarded to the browser console);
+3. calls `_start` (or `_initialize` for a reactor build). `_start` returning
+   normally **or** calling `proc_exit(0)` both count as success; any non-zero
+   exit code is an error. The instance stays alive afterwards;
+4. reads `sb_ops_ptr()`/`sb_ops_len()` as a UTF-8 JSON array out of
+   `exports.memory`, calls `sb_ops_clear()`, then applies the ops;
+5. on every tap (`button`, `navlink`, or the back button of a `navscreen`)
+   calls `sb_event(id)` and repeats step 4;
+6. for every other event (`text`, `toggle`, `environment`, `select`,
+   `geometry`) encodes the JSON event as UTF-8, calls `sb_alloc(len)`, writes
+   the bytes at the returned pointer, calls `sb_event_json(ptr, len)` and
+   repeats step 4. Modules that lack `sb_alloc`/`sb_event_json` (Phase 1)
+   skip these events; `environment` is sent once right after `_start` and
+   again whenever the theme toggle or the Text size control changes. It
+   always carries both fields:
+   `{"type":"environment","colorScheme":"light","dynamicTypeSize":"large"}`,
+   with `dynamicTypeSize` one of `xSmall`, `small`, `medium`, `large`,
+   `xLarge`, `xxLarge`, `xxxLarge`, `accessibility1` … `accessibility5`.
+   Phase 2 modules ignore the extra field. Events the renderer produces
+   before the handle exists (the `geometry` reports of the very first layout
+   pass, which runs inside `loadApp`) are queued and delivered right after
+   `environment`;
+7. (Phase 4) if the module exports `sb_run_jobs(now_ms: f64) -> f64`, calls
+   it with `performance.now()` right after the first ops were applied, after
+   every delivered event (after that event's ops were applied) and whenever
+   the delay it returned has elapsed; after every call it repeats step 4.
+   `src/wasm.ts`'s `JobScheduler` keeps a single pending `setTimeout` for
+   the next run (every call cancels and reschedules it; the delay is clamped
+   to at least 4 ms; a negative return schedules nothing until the next
+   event). `window.__sb.runJobs()` runs it on demand and returns the delay
+   (`null` for modules and mocks without the export, which keep working as
+   before).
+
+`memory.buffer` is re-read after every call into Wasm because growth detaches
+the previous `ArrayBuffer`.
+
+## Renderer notes
+
+### Ops and the element tree
+
+- `insert` with an element that is already attached is a move. `index` is the
+  position in the parent's child list *after* the op (the element is detached
+  first, then inserted before the current child at `index`).
+- `update` replaces props entirely: inline styles and data attributes produced
+  by the previous props are cleared first (the layout box is kept until the
+  commit re-lays out).
+- `remove` detaches the element and forgets it and every descendant.
+- `commit` runs the layout engine over the whole tree, positions every element
+  and hands the pass to the Animator; it then dispatches a `sb:commit`
+  CustomEvent on `#screen` (`detail.animation` is the commit's animation or
+  null). Everything else is applied eagerly, not batched.
+- Besides `elements` (id → HTMLElement) the renderer keeps `nodes` (id →
+  `LayoutNode { id, kind, props, children }`, the shape the engine reads) and
+  `parents`. `window.__sb.renderer.layoutResult` is the last `LayoutResult`.
+
+### Layout (Phase 3)
+
+Layout is not CSS. On every commit, and whenever the Dynamic Type size, the
+color scheme or the fonts change (`renderer.setEnvironment`,
+`renderer.fontsChanged`), the renderer calls
+`layoutTree(root.children, env, new CanvasTextMeasurer())` from `src/layout`
+(see the "Layout engine semantics" table in `docs/ops-protocol.md`) and
+`src/layoutDom.ts` applies the result:
+
+- Every protocol element is `position: absolute` with `left/top/width/height`
+  from its frame, relative to its parent element's box. `#screen` is a plain
+  `overflow: hidden` box; the safe areas are part of the engine's proposal.
+- `text` elements get the engine's exact lines joined with `\n` under
+  `white-space: pre`, the resolved `font` shorthand (`weight size/lineHeight
+  family`) and `text-align` from `multilineTextAlignment`. `lineLimit`
+  truncation (the `…`) comes from the engine too.
+- `image` elements are a square of the font's line height with the glyph at
+  `1em` (font-size from `result.fonts`).
+- `scrollview` and `list` get an inner content box (`.sb-scroll-content`,
+  `.sb-list-content`) sized from `contentSizes`; children are placed inside it
+  at scroll offset 0 and the box scrolls (`overflow: auto`, hidden scrollbars).
+  When the view reaches the bottom of the screen (and is not inside a sheet),
+  the bottom safe area (34px) is added to the content box's height, iOS's
+  content inset, so the last row can scroll clear of the home indicator (the
+  engine's frames are unchanged).
+- Compound kinds use the engine's `chrome` rects: `navscreen` {bar (status bar
+  + 44, padded so the 44px row is at the bottom), largeTitle (52px row, text
+  from `chromeText`), back, content}, `sheet` {grabber}, `toggle` {switch},
+  `section` {rows (the inset card), header, footer}, `navlink` rows {chevron},
+  `tabview` {bar, item0 … itemN-1}, `picker` {segment0 … / label, value}.
+  A `list` or `scrollview` under a tab bar gets a `bottomInset` rect (the
+  part of its frame the bar covers): its height replaces the 34px safe-area
+  content inset.
+  Section headers come upper-cased from the engine in the footnote font;
+  footers are drawn from the section's own `footer` prop (sentence case).
+- A list row's DOM box is the engine's full-width `row` rect (so the cell
+  background, the 16px-inset separator and the hit area match iOS); leaf rows
+  (`text`, `image`, `textfield`) pad their content frame back into place.
+  Rows whose own chrome replaced the `row` key (`toggle`, bordered `button`)
+  rebuild it from the card and the engine's rule `max(44, content + 2 × 11)`.
+- Layout-only style fields (`padding`, `frame`, `layoutPriority`, `fixedSize`,
+  `lineLimit`, `multilineTextAlignment`) leave data attributes
+  (`data-sb-padding`, `data-sb-frame`, `data-sb-line-limit`, …) and are read by
+  the engine from `nodes`; `font`, `foreground`, `background`, `cornerRadius`
+  (+ `overflow: hidden`), `opacity` and `disabled` are inline CSS as before.
+- Expected geometry with the real modules: Counter's three buttons are 88×44
+  at x = 48 / 152 / 256, y = 521 (16px gaps, centered); Todos' bar spans
+  y 0–103, the large title 103–155, the list starts at 155 and its rows are
+  44 high and inset 16; a pushed inline screen's bar row is y 59–103.
+
+### Fonts and Dynamic Type
+
+- `Style.font` fields are independent: `{ "weight": "bold" }` changes only the
+  weight. A `textStyle` resolves through Apple's Dynamic Type table in
+  `src/layout/typography.ts` (the single source of truth; `src/typography.ts`
+  re-exports it): Large is 34/28/22/20/17/17/16/15/13/12/11 for largeTitle …
+  caption2, line heights 41/34/28/25/22/22/21/20/18/16/13; other sizes use the
+  HIG point sizes with `round(size × 1.2)` line heights. `headline` implies
+  `semibold`. A fixed `size` does not scale unless `relativeTo` names a text
+  style, in which case it scales by that style's ratio to Large.
+- Styled boxes with a `textStyle` also carry `font-size: var(--sb-ts-<style>-size)`
+  (fallback: the Large value) so chrome and un-laid-out text follow the Text
+  size control; `--sb-font-size-body` on the device frame follows `body`.
+
+### Kinds
+
+- Semantic colors resolve to CSS variables (`--sb-color-primary`, `-secondary`,
+  `-accent`, `-system-background`, `-secondary-system-background`); `clear` is
+  `transparent`. Values for both schemes live in `styles.css` under
+  `.device[data-theme]`. An `a` on a semantic color is an opacity multiplier,
+  rendered as `color-mix(in srgb, var(--token) <a*100>%, transparent)`.
+- `Style.disabled` multiplies the box's opacity by 0.4 and sets
+  `pointer-events: none` (plus `data-sb-disabled` / `aria-disabled`).
+- `button.style` and `button.role` become `data-sb-style` / `data-sb-role`;
+  `bordered` is a gray capsule, `borderedProminent` a filled accent capsule
+  (label + 14/7 padding, 34px minimum, from the engine), `destructive` red
+  text. Phase 1 modules send `{}`, which reads as `automatic`.
+- `image`: `systemName` is looked up in `src/symbols.ts` (SF Symbol name →
+  lucide glyph, including `.fill` / `.circle` variants) and rendered as an
+  inline `<svg>` in `currentColor`. Unknown names draw a dashed square with
+  `title` set to the name, so gaps are visible.
+- `color` is a box filled with its color; `shape` draws `rectangle`,
+  `roundedRectangle` (`border-radius: cornerRadius`), `circle` / `ellipse`
+  (`50%`) and `capsule` (`9999px`). `fill` is the background; `fill: null`
+  without a stroke paints `currentColor` (a bare `Circle()`), with a stroke it
+  paints nothing (`Shape.stroke(_:)`); `stroke` is a solid border of
+  `lineWidth` (inside the frame, `box-sizing: border-box`). Both take exactly
+  the size the engine proposes (10pt on an unconstrained axis).
+- `list` / `section` render iOS inset-grouped: grouped background on the
+  list, white (dark: `#1C1C1E`) 10px-rounded cards inset 16px, 44px rows
+  with 16px content insets and separators inset 16px. Every direct child of a
+  section (and every non-`section` child of a list) is a row; a `navlink`
+  row shows a trailing chevron, a `toggle` row puts the switch at the
+  trailing inset.
+- Compound kinds (`navstack`, `navscreen`, `section`, `toggle`, `navlink`,
+  `list`, `scrollview`, `sheet`) own some chrome. Their protocol children go
+  into a slot element (`.sb-slot`), so `insert` indices are exact;
+  `Renderer.elements` still maps ids to the element itself.
+- `navstack` / `navscreen`: only the last screen is interactive
+  (`data-sb-nav-position`, `inert`); a new screen slides in from the right
+  over 0.35s and the one below parks at `translateX(-30%)`. A removed top
+  screen animates out through a visual clone stripped of element ids. Screens
+  at `depth > 0` show a back button (`chevron.left` + the previous screen's
+  current title) that sends a `tap` with the `navscreen`'s own id. A title
+  `update` on any screen also refreshes the back labels above it.
+- `textfield` is an `<input>` (34px `roundedBorder`, 22px `plain`); `input`
+  events send `{"type":"text"}`. An `update` whose `text` equals the current
+  value leaves `.value` (and the caret) alone. `toggle` renders a 51×31 switch
+  (`role="switch"`); clicking it flips the switch optimistically and sends
+  `{"type":"toggle"}`; Swift's `update` confirms the state.
+
+### Tab views, pickers, list styles and GeometryReader (Phase 4)
+
+- `tabview` fills the screen like a `navstack` (safe areas ignored). Its
+  `tab` children go into `.sb-tabview-content` and all share the tab view's
+  frame; the bar (`.sb-tabbar`, the engine's `bar` rect: 49 + the bottom
+  safe area when the tab view reaches the screen bottom) is drawn on top with
+  a translucent system background (`rgba(249,249,249,0.94)`, dark
+  `rgba(29,29,29,0.94)`), a hairline on top and one `.sb-tabbar-item` per
+  tab at the engine's `item<i>` rect (equal widths, 49 high): the tab's
+  `systemImage` through the symbol table at 24px over a 10px title, accent
+  when selected (`aria-selected`), secondary otherwise. Tapping an item sends
+  `{"type":"select","id":<tabview id>,"value":<index>}` and nothing else:
+  the `selected` prop is authoritative, the `update` switches tabs. Only the
+  selected tab's content is laid out; the other tabs keep their DOM (and
+  scroll positions) under `data-sb-tab-hidden` (`visibility: hidden`,
+  `inert`, `aria-hidden`), driven by `LayoutResult.hidden`.
+- Tab content is placed like a navscreen's: a `navstack` fills the whole tab
+  (its screens reserve the status bar and their lists run under the
+  translucent bar); a `list`/`scrollview` starts below the status bar and
+  also runs to the bottom; anything else is centered between the status bar
+  and the bar. Scrolling views under the bar get the bar height (83) as
+  scrollable content inset instead of the 34px safe area (engine chrome
+  `bottomInset`), so the last row scrolls clear of the bar like iOS.
+- `picker` `segmented`: an iOS segmented control, 32 high, width = proposal
+  (or every label + 20): `.sb-segment-track` (`rgba(118,118,128,0.12)`, 8px
+  radius; dark `rgba(118,118,128,0.24)`) at the control's frame and one
+  `.sb-segment` radio button per option at the engine's `segment<i>` rect
+  (13px semibold); the checked one carries a white pill (dark `#636366`)
+  inset 2px with a soft shadow. Tapping a segment moves the pill
+  optimistically and sends `select` with the index; Swift's `update`
+  confirms. In a list row the row is 44 high with the control centered.
+- `picker` `menu`: 44 high in a list row, 34 elsewhere; `role="button"` with
+  `.sb-picker-label` at the engine's `label` rect (leading) and
+  `.sb-picker-value` (the selected option plus `chevron.up.chevron.down`,
+  secondary color) at `value` (trailing). Tapping it (or Enter/Space) opens
+  `.sb-picker-menu` appended to `#screen`: 250 wide, 13px radius, system
+  background, one 44px `menuitemradio` row per option with a checkmark on
+  the current one, anchored under the control (above it when there is no
+  room, trailing edges aligned, 8px from the screen edges). Choosing a row
+  sends `select` and closes the menu; Escape or a tap anywhere outside
+  closes it (a tap inside the screen is swallowed so the control under it
+  does not fire); an `update` or removal of the picker closes it too.
+  `renderer.openMenuElement` exposes the open menu.
+- `list.style`: `insetGrouped` (default; Phase 2 modules send `{}`) is the
+  existing card layout; `grouped` (`Form`) makes sections full width with no
+  corner radius, a hairline above and below each card and the usual 16px
+  content inset and 35px between sections; `plain` drops the cards, the top
+  gap and the gaps between sections and uses the system background. The
+  list carries `data-sb-list-style`.
+- `geometry` (`GeometryReader`) is a plain box the engine sizes to its
+  proposal (10 on an unconstrained axis, so one in a list row needs a frame
+  height) and whose child is proposed that size and placed top leading.
+  After every layout pass the renderer compares each `geometry` element's
+  frame (rounded to whole px) with the size it last reported and queues
+  `{"type":"geometry","id":N,"width":w,"height":h}` for the changed ones; the
+  batch is sent once the ops being applied are done (so Swift's answering
+  commit re-enters the renderer cleanly) and never when the size is
+  unchanged, which is what lets the re-render loop converge. Elements in a
+  hidden tab are not laid out and therefore not reported.
+
+### Sheets (Phase 3)
+
+A root-level `sheet` (child of id 0) is a full-screen layer (`role="dialog"`):
+a scrim (`rgba(0,0,0,0.4)`) over the presenting tree and a card at the
+engine's frame (large: screen height − status bar − 10; medium: half the
+screen) with 10px top corners, a 36×5 grabber 8px from the top, and the
+sheet background (`#FFFFFF`, dark: `#1C1C1E`, the elevated background). The
+card slides up over 0.4s on insert (`sb-sheet-in`); on remove a clone
+(`.sb-sheet--out`, no element ids) slides down and fades its scrim, then goes.
+While the top sheet is `large`, `#screen` carries `data-sb-sheet="large"` and
+the other root children scale to 0.92 behind the scrim; a `medium` sheet only
+dims. Sheets stack: only the last is interactive (`data-sb-sheet-position`,
+`inert`), sheets below park slightly scaled. A tap on the scrim, or a
+downward drag of the card past 100px (pointer events; shorter drags spring
+back), sends `{"type":"tap","id":<sheet id>}`: the dismiss request Swift
+answers by removing the element. `detents` only matters by its first entry.
+
+### Animation (Phase 3)
+
+`src/animation.ts` animates a pass with the Web Animations API when the
+`commit` carries an `animation` (`withAnimation`) or a `styled` element's
+`animationToken` changed in an `update` (`.animation(_:value:)`). A token
+subtree uses its own `animation` (it overrides the commit's, like SwiftUI's
+transaction override); everything else in an animated commit uses the commit's.
+
+- Style changes of updated elements tween from their computed value before the
+  pass: `opacity`, `background-color`, `color`, `border-radius`, `font-size`.
+- Frame changes tween `left/top/width/height` for every element whose layout
+  box moved or resized in the pass (the engine's frames before and after).
+- Inserted subtree roots play their `transition` forwards, removed elements
+  leave a visual clone (`.sb-exit-clone`, stripped of ids, absolutely
+  positioned at the old frame on `#screen`) that plays it backwards and is
+  dropped when done. `opacity` fades; `scale` scales from `scale` (default
+  0.5) with a fade; `slide` enters from the leading edge and exits through the
+  trailing edge; `move(edge)` translates by the element's own size from that
+  edge; `identity` does nothing; arrays combine. Without a `transition`,
+  inserted/removed views fade (SwiftUI's default). The transition is looked up
+  on the removed/inserted root or down a single-child chain of `styled` boxes
+  under it (`Text.transition(.opacity).padding()`). `navscreen` and `sheet`
+  keep their own CSS enter/exit instead.
+- `Animation` → CSS timing: `default` and `easeInOut` →
+  `cubic-bezier(0.42, 0, 0.58, 1)`, `easeIn` → `cubic-bezier(0.42, 0, 1, 1)`,
+  `easeOut` → `cubic-bezier(0, 0, 0.58, 1)`, `linear`; `duration` defaults to
+  0.35s, `delay` to 0. `spring` becomes a `linear()` easing sampled at 60
+  points from a damped spring with ω = 2π / duration and damping ratio
+  1 − bounce (bounce 0: critically damped; 0.3: overshoots ~4.6%), run over
+  the perceptual `duration` (default 0.5s); browsers without `linear()` fall
+  back to easeInOut. `window.__sb.animation.{easingFor, timingFor,
+  springEasing}` expose the mapping.
+
+- `window.__sb.renderer` exposes the live `Renderer` (used by the e2e tests
+  and handy in the console: `__sb.renderer.applyOps([...])`);
+  `window.__sb.sentEvents` lists the JSON events delivered to the app,
+  `window.__sb.colorScheme()` the current appearance,
+  `window.__sb.typeSize()` the current Dynamic Type size,
+  `window.__sb.runJobs()` runs the app's executor (Phase 4) and
+  `window.__sb.JobScheduler` is the executor driver class for tests.
+
+## Testing
+
+`npm run test:unit` runs the layout engine's vitest suite (Node, no browser).
+`npm run test:e2e` runs Playwright with Chromium. The config boots
+`npm run dev -- --port 5173 --strictPort` itself. `e2e/renderer.spec.ts`
+covers the Counter mock and op semantics, `e2e/phase2.spec.ts` the Phase 2
+kinds against the Todos mock, `e2e/phase3.spec.ts` Dynamic Type, color/shape,
+sheets and animation against the Gallery mock, `e2e/phase4.spec.ts` tab
+views, pickers, list styles, geometry reports and the executor loop
+(`JobScheduler` against a stub) against the Settings mock, and
+`e2e/counter.spec.ts` / `e2e/todos.spec.ts` / `e2e/settings.spec.ts` drive
+the real `public/Counter.wasm` / `Todos.wasm` / `Settings.wasm`, including
+the geometry the engine guarantees (bounding boxes, not CSS flex properties)
+and, for Settings, the clock task that only advances while `sb_run_jobs` is
+driven. `e2e/landing.spec.ts` checks the landing page (cards, Open links, QR
+SVGs, build info) and `e2e/device-mode.spec.ts` runs a 393×852 touch viewport
+through `?mode=device` (no frame, full-screen `#screen`, real taps, resize
+and color-scheme changes), the automatic rule and `?mode=frame`. The specs
+open `/app/…`; the dev server is started at `/app/?mock=1`. Chromium is expected under
+`$PLAYWRIGHT_BROWSERS_PATH/chromium`; set `SB_CHROMIUM_PATH` to point at a
+different binary, or unset `PLAYWRIGHT_BROWSERS_PATH` to let Playwright use its
+own download.