@erclx/canon 5.39.0 → 5.41.0

package/tooling/shell/reference.md

@@ -6,13 +6,13 @@ The shell stack is an add-on that formats and lints the shell scripts a project
 
 ## Install
 
-- Install `shfmt` and `shellcheck` by hand, through `sudo apt-get install shfmt shellcheck` or `brew install shfmt shellcheck`. Injection runs only `bun add -D`, and neither tool ships through the registry.
+- Install `shfmt` and `shellcheck` by hand with `sudo apt-get install shfmt shellcheck` or `brew install shfmt shellcheck`. Injection runs only `bun add -D`, and neither ships through the registry.
 - `scripts/verify.ts` probes both before the `Shell` phase and names the install command when one is missing, rather than letting `find` report a missing executable.
 
 ## shfmt
 
 - Indent with 2 spaces, set through `--indent 2` on every call.
-- `.editorconfig` carries an `[*.sh]` block with `indent_style = space` and `indent_size = 2`, so the editor and shfmt agree. Dropping the block because shfmt already sets indentation produces spurious diffs.
+- `.editorconfig` carries an `[*.sh]` block with `indent_style = space` and `indent_size = 2`, so the editor and shfmt agree. Dropping it because shfmt sets indentation produces spurious diffs.
 
 ## shellcheck
 
@@ -27,16 +27,17 @@ The shell stack is an add-on that formats and lints the shell scripts a project
 
 ## Verify
 
-- `scripts/verify.ts` runs `check:shell` in its `Shell` phase wherever `package.json` declares it, between the format check and the unit tests. No stack's `scripts/verify.json` requires it, so a folder that never synced this stack skips the phase.
+`scripts/verify.ts` runs `check:shell` in its `Shell` phase wherever `package.json` declares it, between the format check and the unit tests. No stack's `scripts/verify.json` requires it, so a folder that never synced this stack skips the phase.
 
 ## lint-staged
 
-- `.lintstagedrc` is a base seed this stack cannot reach once written. Add a `**/*.sh` entry by hand, running `shfmt --write --indent 2` then `shellcheck --severity=warning`, to run the checks on commit.
+- `.lintstagedrc` is a base seed this stack cannot reach once written. Add a `**/*.sh` entry by hand to run the checks on commit.
+- That entry runs `shfmt --write --indent 2` then `shellcheck --severity=warning`.
 - Do NOT copy that glob into a `package.json` script. lint-staged expands its own globs and passes matched files as arguments, which a bare shell script does not.
 
 ## CI
 
-- `.github/workflows/shell.yml` runs on pull requests targeting `main` and on `workflow_dispatch`: checkout, setup Bun, `bun install --frozen-lockfile`, install both tools through apt, then `check:shell`.
+`.github/workflows/shell.yml` runs on pull requests targeting `main` and on `workflow_dispatch`. Its steps are checkout, setup Bun, `bun install --frozen-lockfile`, installing both tools through apt, then `check:shell`.
 
 ## CLI
 

package/tooling/vite-react/reference.md

@@ -4,44 +4,72 @@
 
 ## Overview
 
-The vite-react stack covers Vite + React + TypeScript projects: web apps and Chrome extensions. It ships golden configs for `vite.config.ts`, `vitest.config.ts` (merging from vite config), `playwright.config.ts`, and a unified `tsconfig.json` with `@/` path alias. Shared web tooling (oxlint, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
+The vite-react stack covers Vite + React + TypeScript web apps and Chrome extensions. It ships golden configs for `vite.config.ts`, `vitest.config.ts`, `playwright.config.ts`, and a unified `tsconfig.json` with an `@/` path alias. Shared web tooling (oxlint, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
 
 ## Scaffold checklist
 
 1. Scaffold with `bunx create-vite@latest <name> --template react-ts` (web apps) or `bunx create-crxjs@latest` (Chrome extensions).
-2. Install base and web tooling: `canon tooling sync web . --write`
-3. Install vite-react deps and configs: `canon tooling sync vite-react . --write`
+2. Install base and web tooling with `canon tooling sync web . --write`.
+3. Install vite-react deps and configs with `canon tooling sync vite-react . --write`.
 4. Extend the `ci` and `development` context entries under `canon/context/` per the web reference's extend sections plus the vite-react rows below.
 5. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
 ## What ships as golden configs
 
-- `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path. Dev port `5173` and preview port `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
-- `vitest.config.ts`: merges from `vite.config.ts` (imported with its `.ts` extension, which Vite 8 requires), jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
-- `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, trace under `use`.
-- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom/vitest` in types.
+- `vite.config.ts` adds `@vitejs/plugin-react`, `@tailwindcss/vite`, the `@` alias to `./src`, and `VITE_BASE_URL` for the base path.
+- It serves dev on port `5173` and preview on `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
+- `vitest.config.ts` merges from `vite.config.ts`, imported with its `.ts` extension, which Vite 8 requires. It sets jsdom, globals, the setup file, `passWithNoTests: true`, and v8 coverage.
+- `playwright.config.ts` runs all browsers, with `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, and trace under `use`.
+- `tsconfig.json` is unified, with `noEmit: true`, `skipLibCheck: true`, `@/` paths, and `vitest/globals` and `@testing-library/jest-dom/vitest` in types.
 
 ## Chrome extension variant
 
-When scaffolding a Chrome extension, override the installed golden configs:
+When scaffolding a Chrome extension, override the installed golden configs.
 
-- `vite.config.ts`: use `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Keep the derived `server.port` and `server.strictPort: true`, set `server.hmr.clientPort` to the same derived value, and add `chrome-extension://` to CORS origins. Drop `VITE_BASE_URL`.
-- `vitest.config.ts`: use a standalone `defineConfig` (no `mergeConfig`). crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly. Add `**/release/**` to excludes and `manifest.config.ts`, `**/*.d.ts` to coverage excludes.
-- `playwright.config.ts`: chromium-only (Firefox and WebKit cannot run extensions). Bundled `chromium` channel. No `baseURL` or `webServer`. Tests load the built extension directly from `dist/`.
-- `e2e/fixtures.ts`: extend Playwright base `test` with `context` (persistent context loading the extension from `dist/`) and `extensionId` (extracted from service worker URL). Rename `use` to `apply` to avoid oxlint's `react/rules-of-hooks`. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
-- `manifest.config.ts`: use `defineManifest` from `@crxjs/vite-plugin`. Read `name` and `version` from `package.json`. Entry points `src/popup/index.html`, `src/sidepanel/index.html`, `src/background/index.ts`, `src/content/main.tsx`. Permissions `sidePanel`, `contentSettings`, `storage`. Icon `public/logo.png` at size 48.
-- `screenshot` script: `bun run build && bun e2e/screenshot.ts` (no preview server).
-- Additional gitignore entries: `*.crx`, `*.pem`, `release/`.
+### Build config
+
+The crxjs plugin replaces the plain React build.
+
+- `vite.config.ts` uses `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Drop `VITE_BASE_URL`.
+- Keep the derived `server.port` and `server.strictPort: true`, set `server.hmr.clientPort` to the same derived value, and add `chrome-extension://` to CORS origins.
+
+### Test configs
+
+The plugin also changes how Vitest and Playwright run.
+
+- `vitest.config.ts` uses a standalone `defineConfig` with no `mergeConfig`, since the crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly.
+- It also adds `**/release/**` to excludes, and `manifest.config.ts` and `**/*.d.ts` to coverage excludes.
+- `playwright.config.ts` is chromium-only, since Firefox and WebKit cannot run extensions.
+- It uses the bundled `chromium` channel with no `baseURL` or `webServer`, and tests load the built extension from `dist/`.
+
+### Fixtures and manifest
+
+The extension needs a fixture file and a manifest config.
+
+- `e2e/fixtures.ts` extends Playwright's base `test` with `context`, a persistent context loading the extension from `dist/`, and `extensionId`, extracted from the service worker URL.
+- Rename `use` to `apply` in that file to avoid oxlint's `react/rules-of-hooks`. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
+- `manifest.config.ts` uses `defineManifest` from `@crxjs/vite-plugin` and reads `name` and `version` from `package.json`.
+- Its entry points are `src/popup/index.html`, `src/sidepanel/index.html`, `src/background/index.ts`, and `src/content/main.tsx`.
+- Its permissions are `sidePanel`, `contentSettings`, and `storage`, with icon `public/logo.png` at size 48.
+
+### Scripts and ignores
+
+The extension build changes one script and adds ignores.
+
+- The `screenshot` script is `bun run build && bun e2e/screenshot.ts`, with no preview server.
+- Add `*.crx`, `*.pem`, and `release/` to gitignore.
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run dev` | Start the Vite dev server on port 5173, plus this worktree's port offset. |
-| `bun run build` | Typecheck then build the production bundle. |
-| `bun run preview` | Serve the built bundle locally. |
-| `bun run typecheck` | Run `tsc --noEmit`. |
+| Command             | Purpose                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `bun run dev`       | Start the Vite dev server on 5173 plus this worktree's offset. |
+| `bun run build`     | Typecheck then build the production bundle.                    |
+| `bun run preview`   | Serve the built bundle locally.                                |
+| `bun run typecheck` | Run `tsc --noEmit`.                                            |
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/ci.md -->
+In `canon/context/development/ci.md`, the Typecheck row asserts `` `tsc --noEmit` passes ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->

package/tooling/web/reference.md

@@ -4,128 +4,188 @@
 
 ## Overview
 
-The web layer covers web-universal tooling shared across Vite + React, Astro, and any future web stack. It ships golden configs for oxlint, Vitest, Playwright, Tailwind v4, screenshots, VS Code integration, and CI. Framework-specific wiring (Vite plugins, Astro islands, Next.js config) lives in per-stack adapter folders that extend this layer.
+The web layer covers the tooling shared across Vite + React, Astro, and any future web stack. It ships golden configs for oxlint, Vitest, Playwright, Tailwind v4, screenshots, VS Code integration, and CI. Framework wiring (Vite plugins, Astro islands, Next.js config) lives in per-stack adapter folders that extend this layer.
 
 ## What ships as golden configs
 
-Golden config files live in `tooling/web/configs/` and are copied into the target on `canon tooling sync web . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
+Golden configs live in `tooling/web/configs/`. `canon tooling sync web . --write` copies them into the target and replaces whatever sits at those paths. They are the source of truth, so this reference covers rationale and the configs show the setup.
 
-- `.oxlintrc.json`: migrated from the ESLint config it replaced. Runs the recommended JS and TypeScript rules, the React hooks and refresh rules, test-scoped vitest rules plus `no-focused-tests`, and `check-file` and `simple-import-sort` as JS plugins.
-- `src/test/setup.ts`: `@testing-library/jest-dom/vitest` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
-- `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
-- `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.
-- `scripts/readme-screenshot.sh`: captures one case under `SCREENSHOT_FILTER` and copies its light and dark frames to `assets/evidence/readme/`. `README_FILTER` ships empty with `header/1280` as its example, and the script exits 1 until a project fills it, since a shipped default would capture the wrong part of the page in every project but one. Its copy reads from `screenshots/<hostname>/`, which is where the harness writes.
-- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/ci-workflow.md` states the test.
-- `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
-- `scripts/verify.json`: the phases base's verify runner requires here, being typecheck, lint, unit tests, and build. `## Verify script` covers the order and the card exclusion stage.
-- `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone. It refuses a folder left under the worktrees directory after its worktree was removed, rather than printing a port for it.
+### Lint and test setup
+
+Two configs carry the lint and unit-test baseline.
+
+- `.oxlintrc.json` is migrated from the ESLint config it replaced. It runs the recommended, React, and test-scoped vitest rules, with `check-file` and `simple-import-sort` as JS plugins.
+- `src/test/setup.ts` imports `@testing-library/jest-dom/vitest` and runs `cleanup` after each test.
+
+### Screenshot cases
+
+`e2e/screenshot.ts` is the capture template. One `CASES` record carries an entry per output file, each naming a section, a theme, and a route, and per-project cases extend it.
+
+- The loop crosses every case with `VIEWPORTS` and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`. The hostname of `SCREENSHOT_BASE_URL` keeps a local run and a deployed run apart.
+- `VIEWPORTS` holds 320, 768, 1280, and 1536. Width 320 is the base a page has to hold without wrapping or clipping.
+- `excludeViewports` skips a width, for a route whose long-form prose reflows at 320 instead of breaking.
+- `evidence: true` also writes `evidence/<section>/<width>--<theme>.png` at 320 and 1280 alone, keeping the tracked set at twice the sections rather than four times.
+
+### Sections and masks
+
+A case may name `sections`, one `{ name, selector }` per addressable part of the route. Each writes its own frame beside the whole-page one.
+
+- A section frame lands at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png`, plus the same path under `evidence/` where the case and width are flagged.
+- A selector matching nothing is reported and skipped, since a target syncing the template before editing its list would otherwise capture nothing.
+- Testing that every section resolves belongs to the project owning the selectors.
+- `mask` lists selectors painted over in every frame, for a value that moves with no code change, so a double capture compares the rest.
+
+### Settling before a shot
+
+Every case settles before anything is shot.
+
+- The context uses `reducedMotion: 'reduce'`, and each named section scrolls into view so an `IntersectionObserver` fires and `loading="lazy"` frames load. The page then returns to the top.
+- Fonts, images, and same-origin frames are waited out on a bounded condition. A second `networkidle` does not re-arm for a load a scroll started.
+- A section frame drops floating chrome (`position: sticky` or `fixed`), which would otherwise ride the scroll into the frame. The whole-page frame is shot first and keeps its chrome.
+
+### Run flags
+
+Three controls narrow or harden a run.
+
+- `SCREENSHOT_FILTER` keeps cases whose `<section>/<width>--<theme>` label contains a comma-separated term. It exits 1 and lists the labels on no match.
+- `--check-console-clean` exits 1 with the list if any `console` error fired, turning the capture into a smoke check.
+- `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, so a deployment script cannot capture `localhost`.
+- With a base URL, it skips every flagged case so a production smoke run writes nothing to the committed path, and exits 1 when zero cases run.
+
+### Scripts and workflows
+
+The wrappers around the capture and the verify run. `governance/rules/tooling/ci-workflow.md` states when a workflow's commit-back is right and when a report is.
+
+- `scripts/screenshot.sh` sources `scripts/lib/preview-server.sh`, never executed itself. It builds, serves on `PREVIEW_PORT`, waits for the port, and traps the whole process group on exit.
+- `scripts/readme-screenshot.sh` captures one case under `SCREENSHOT_FILTER` into `assets/evidence/readme/`. `README_FILTER` ships empty, so it exits 1 until a project fills it.
+- `.github/workflows/readme-screenshot.yml` ships its path list as `REPLACE_WITH_PROJECT_PATHS`, and its first step exits 1 while that stays.
+- `.github/workflows/verify.yml` runs `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests`.
 
 ## What stays in per-stack adapters
 
-Framework glue lives in `tooling/vite-react/configs/` or `tooling/astro/configs/` because the merge helpers and config shapes differ:
+Framework glue lives in `tooling/vite-react/configs/` or `tooling/astro/configs/`, because merge helpers and config shapes differ.
 
-- `vite.config.ts` or `astro.config.mjs`: the framework's config.
-- `vitest.config.ts`: uses `mergeConfig` in Vite stacks, `getViteConfig` from `astro/config` in Astro.
-- `playwright.config.ts`: `webServer` command differs per stack.
-- `tsconfig.json`: `extends` target differs. Astro uses `astro/tsconfigs/strict`. Vite projects use scaffold defaults.
+- `vite.config.ts` or `astro.config.mjs` holds the framework's config.
+- `vitest.config.ts` uses `mergeConfig` in Vite stacks and `getViteConfig` from `astro/config` in Astro.
+- `playwright.config.ts` differs in its `webServer` command.
+- `tsconfig.json` differs in its `extends` target. Astro uses `astro/tsconfigs/strict` and Vite projects use scaffold defaults.
 
 ## File layout
 
-- `src/` for app code, `e2e/` for Playwright, `scripts/` for shell, `src/test/setup.ts` for Vitest globals.
+- `src/` holds app code, `e2e/` Playwright, `scripts/` shell, and `src/test/setup.ts` the Vitest globals.
 - Path alias `@` maps to `./src` in both tsconfig and the framework's build config.
-- Tsconfig is unified at root with `noEmit: true` in Vite stacks. Astro uses the scaffold default from `@astrojs/check`.
+- Tsconfig sits at root with `noEmit: true` in Vite stacks. Astro keeps the scaffold default from `@astrojs/check`.
 
 ## Ports
 
 Two worktrees of one repository run the same stack, so a fixed port makes the second one attach to the first.
 
+### Deriving the port
+
+The helper owns the offset, and a config only adds it.
+
 - Derive every served port from `scripts/worktree-port.sh`. Never write a port literal into a script string.
-- Read `WORKTREE_PORT_OFFSET` in a config and add it to the stack's default port. Unset yields the default, so a plain clone keeps the port it has always served on.
-- Draw the offset from a band of 50, hashed from the worktree folder name. Two worktrees can hash to one offset, so set `WORKTREE_PORT_OFFSET` by hand to break a tie.
-- Expect a non-zero exit and no port from a folder left under `.claude/worktrees/` once its worktree is gone. Git reports the parent repository from inside one, so the helper cannot read it as a worktree and every base it serves would land on the main checkout's port. Both shapes refuse, and they reach differently. A folder whose own `.git` was deleted refuses only under that directory, since location is the only thing separating it from an ordinary subdirectory the base port is correct for. A folder whose `.git` names a pruned administrative directory refuses wherever it sits, because a pointer to nothing is broken regardless of where the folder is.
-- Call it as `VAR=$(bash scripts/worktree-port.sh) && export VAR && <server>`, never as the shorter `VAR=$(bash scripts/worktree-port.sh) <server>`. An assignment prefix discards the exit status of its own substitution, so the shorter form starts the server with `VAR` set to the empty string, every config reads that back as an offset of zero, and the refusal lands on the port it was raised to protect. The assignment alone carries the status, which is what the `&&` reads.
-- Set `WORKTREE_PORT_OFFSET` by hand to serve from such a folder anyway. That is the one override, and it is checked before any directory test.
-- Force-replace `dev` and `preview` through `[scripts.override]`. Both stacks' scaffolds define those keys, and a plain `[scripts]` entry never replaces a key the scaffold already wrote.
-- Set `strictPort` on every dev and preview server. A server that walks to the next free port serves where nothing is looking for it.
-- Set Playwright `reuseExistingServer: false`. Reuse attaches to whatever answers on the port, which reports a pass against another branch's code and prints nothing to say so.
+- Read `WORKTREE_PORT_OFFSET` in a config and add it to the stack's default port. Unset yields the default, so a plain clone keeps its port.
+- The offset comes from a band of 50 hashed from the worktree folder name. Two worktrees can collide, so set `WORKTREE_PORT_OFFSET` by hand to break a tie.
+- Force-replace `dev` and `preview` through `[scripts.override]`, since a plain `[scripts]` entry never replaces a key the scaffold wrote.
+- Set `strictPort` on every dev and preview server, and Playwright `reuseExistingServer: false`. A server that walks to another port, or a reused one, passes against the wrong code silently.
+
+### Calling the helper
+
+Call it as `VAR=$(bash scripts/worktree-port.sh) && export VAR && <server>`, never as `VAR=$(bash scripts/worktree-port.sh) <server>`. An assignment prefix discards the exit status of its own substitution. The shorter form starts the server with `VAR` empty, which every config reads as offset zero.
+
+### Refusal in a removed worktree
+
+Expect a non-zero exit and no port from a folder left under `.claude/worktrees/` once its worktree is gone. Git reports the parent repository from inside one, so every base served would land on the main checkout's port.
+
+- A folder whose own `.git` was deleted refuses only under that directory, since location alone separates it from an ordinary subdirectory.
+- A folder whose `.git` names a pruned administrative directory refuses wherever it sits.
+- Set `WORKTREE_PORT_OFFSET` by hand to serve from such a folder anyway. It is the one override and is checked before any directory test.
 
 ## Anti-patterns
 
-Sticky negative knowledge. Do not relearn.
+Negative knowledge that costs a failed run to relearn.
 
-- Do NOT use `tsc -b` in a Vite project. Composite mode emits `.js` next to `.ts` and the linter lints the emitted files. Use `tsc --noEmit`.
-- Do NOT trust `vite-react`'s scaffolded `lint` script. It ships a bare `"lint": "oxlint"`, which exits 0 on warnings. `[scripts.override]` forces `--max-warnings 0` over it, and the golden `.oxlintrc.json` overwrites the scaffold's bare one.
-- Do NOT rely on bare-folder exclude globs like `exclude: ["e2e"]`. Use `"e2e/**/*"`.
-- Do NOT ship Vitest with no-tests-fail. Fresh scaffolds have zero tests. Use `passWithNoTests: true` or equivalent until the project has at least one test.
-- Do NOT put Playwright `trace` at the top level of `defineConfig`. It lives under `use`.
-- Do NOT skip `skipLibCheck: true` in Vite + React tsconfig. `@testing-library/jest-dom` and Vite's `module-runner` produce type conflicts otherwise.
-- Do NOT run `bunx shadcn@latest init` over a pre-existing `src/styles/global.css`. Shadcn silently overwrites it. Back up first or run shadcn init before writing custom global styles. Use flags `-t <template> -b <base> -p <primary> -y` to avoid interactive prompts.
+| Do NOT                                          | Why and what to do                                                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Use `exclude: ["e2e"]`                          | Bare-folder globs miss. Use `"e2e/**/*"`.                                                              |
+| Put Playwright `trace` at the top of the config | It lives under `use`.                                                                                  |
+| Ship Vitest failing on no tests                 | Fresh scaffolds have none. Use `passWithNoTests: true` until one exists.                               |
+| Skip `skipLibCheck: true` in Vite + React       | `@testing-library/jest-dom` and Vite's `module-runner` conflict otherwise.                             |
+| Use `tsc -b` in a Vite project                  | Composite mode emits `.js` next to `.ts` and the linter lints it. Use `tsc --noEmit`.                  |
+| Trust `vite-react`'s scaffolded `lint` script   | Its bare `oxlint` exits 0 on warnings. `[scripts.override]` forces `--max-warnings 0` over it.         |
+| Run `bunx shadcn@latest init` over `global.css` | It silently overwrites `src/styles/global.css`. Back up first, and pass `-t -b -p -y` to skip prompts. |
 
 ## Tool pairing
 
-- Unit tests: Vitest with jsdom, globals on, setup file at `src/test/setup.ts`, `@testing-library/react`, `@testing-library/user-event`.
-- E2E: Playwright in `e2e/`. Chromium-only for Chrome extensions, all browsers for web apps.
-- Tailwind: v4 via `@tailwindcss/vite`. Never the v3 integration.
-- Lint: oxlint at an exact pin, since its JS plugin host is alpha and a minor release could break `check-file` or `simple-import-sort`. Astro keeps ESLint, which its own reference covers.
+- Unit tests use Vitest with jsdom, globals on, `src/test/setup.ts`, `@testing-library/react`, and `@testing-library/user-event`.
+- E2E uses Playwright in `e2e/`, Chromium only for Chrome extensions and all browsers for web apps.
+- Tailwind is v4 through `@tailwindcss/vite`, never the v3 integration.
+- Lint is oxlint at an exact pin, since its JS plugin host is alpha and a minor release could break `check-file` or `simple-import-sort`. Astro keeps ESLint, which its own reference covers.
 
 ## oxlint
 
-- Set `lint` and `lint:fix` through `[scripts.override]`, so an already-synced target stops running ESLint on its next sync.
-- Delete a leftover `eslint.config.js` or `eslint.config.mjs`, and `bun remove` the ESLint packages this stack stopped shipping, by hand after that sync. Sync deletes nothing a stack stopped shipping.
-- Keep import sorting on `simple-import-sort` rather than oxfmt's built-in sort, which orders imports differently and would rewrite every import block.
+- Set `lint` and `lint:fix` through `[scripts.override]`, so a synced target stops running ESLint on its next sync.
+- After that sync, delete a leftover `eslint.config.js` or `eslint.config.mjs` and `bun remove` the ESLint packages by hand. Sync deletes nothing a stack stopped shipping.
+- Keep import sorting on `simple-import-sort`, because oxfmt's built-in sort orders differently and would rewrite every import block.
 
 ## lint-staged (extend)
 
-- Add `**/*.{js,jsx,ts,tsx}` glob running `oxlint --fix --max-warnings 0`, and `oxfmt --no-error-on-unmatched-pattern`.
-- Extend the oxfmt glob to include `css`: `**/*.{json,css,md}`.
+- Add `**/*.{js,jsx,ts,tsx}` running `oxlint --fix --max-warnings 0` and `oxfmt --no-error-on-unmatched-pattern`.
+- Extend the oxfmt glob to include `css`, giving `**/*.{json,css,md}`.
 
 ## CI docs (extend)
 
-Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs. <!-- audit-ignore-citations: canon/context/ci.md -->
-
-Append rows:
+Extend `canon/context/development/ci.md` so the `## Checks` table reflects the web jobs. <!-- audit-ignore-citations: canon/context/development/ci.md -->
 
-| Typecheck | `bun run typecheck` | framework-specific typecheck passes |
-| Lint | `bun run lint` | oxlint passes with zero warnings |
-| Tests | `bun run test:coverage` | Vitest passes with coverage thresholds |
-| Build | `bun run build` | Production build succeeds |
-| E2E | `bun run test:e2e` | Playwright passes against the built preview |
+| Check     | Command                 | What it asserts                             |
+| --------- | ----------------------- | ------------------------------------------- |
+| Typecheck | `bun run typecheck`     | framework-specific typecheck passes         |
+| Lint      | `bun run lint`          | oxlint passes with zero warnings            |
+| Tests     | `bun run test:coverage` | Vitest passes with coverage thresholds      |
+| Build     | `bun run build`         | Production build succeeds                   |
+| E2E       | `bun run test:e2e`      | Playwright passes against the built preview |
 
 Under `## Running CI locally`, document that `bun run check:full` runs verify plus `test:e2e`.
 
 ## Development docs (extend)
 
-Extend the `development` context entry under `canon/context/` so the `## Scripts` table lists every web script. Stack adapters add their `dev`, `build`, `preview`, `typecheck` rows.
-
-Append rows:
+Extend the `development` context entry under `canon/context/` so the `## Scripts` table lists every web script. Stack adapters add their `dev`, `build`, `preview`, and `typecheck` rows.
 
-| `bun run lint` | Run oxlint with zero warnings allowed. |
-| `bun run lint:fix` | Auto-fix oxlint issues. |
-| `bun run test` | Run Vitest in watch mode. |
-| `bun run test:run` | Run Vitest once with verbose reporter. |
-| `bun run test:coverage` | Run Vitest with coverage. |
-| `bun run test:e2e` | Run Playwright E2E tests. |
-| `bun run test:e2e:changed` | Run Playwright E2E tests for specs the import graph reaches from the current diff. |
-| `bun run screenshot` | Build, preview, then capture screenshots. |
-| `bun run readme-screenshot` | Build, preview, then capture the README frame into `assets/evidence/readme/`. |
-| `bun run smoke:prod` | Capture against `SCREENSHOT_BASE_URL`, requiring it set and failing on any console error. |
+| Command                     | Purpose                                 |
+| --------------------------- | --------------------------------------- |
+| `bun run lint`              | Run oxlint, no warnings allowed.        |
+| `bun run lint:fix`          | Auto-fix oxlint issues.                 |
+| `bun run test`              | Run Vitest in watch mode.               |
+| `bun run test:run`          | Run Vitest once, verbose.               |
+| `bun run test:coverage`     | Run Vitest with coverage.               |
+| `bun run test:e2e`          | Run Playwright E2E tests.               |
+| `bun run test:e2e:changed`  | Run specs the diff's import graph hits. |
+| `bun run screenshot`        | Build, preview, capture screenshots.    |
+| `bun run readme-screenshot` | Capture the README frame.               |
+| `bun run smoke:prod`        | Capture against a required base URL.    |
 
-`canon tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
+### Screenshot contract
 
-`governance/rules/ui/surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
+`canon tooling verify <stack>` is the only automated caller of `bun run screenshot`. It runs the script for any stack whose `package.json` declares it and asserts that PNG files land under `screenshots/`.
 
-The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there. A case naming sections commits a folder per section under that baseline rather than one file per theme, which is what lets a pull request comparison land on the part of the page that moved instead of on one image of the whole of it. The count is the section list times the themes, so a list is worth sizing against how many frames each later change has to regenerate and a reviewer has to read.
+- The count is a recursive find with no depth limit, so the seed's section folders satisfy it. Do not flatten the layout to protect that check.
+- `governance/rules/ui/surface-capture.md` asks a session to run the capture after a surface changes, component files included, with an exemption for a component the production build strips out.
+- The sweep under `screenshots/` is ignored and only a flagged case's `evidence/` output tracks, so a target's first capture is the baseline it commits.
+- A case naming sections commits a folder per section, so size the list against the frames each later change regenerates.
 
 ## Gitignore (extend)
 
-`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+These `[gitignore]` groups mirror the manifest.
 
 - `"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/"]`
 - `"# Screenshots" = ["screenshots/"]`
 
 ## Verify script
 
-The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`, and base's `scripts/verify.ts` runs them in its fixed order: typecheck, lint, format, shell where the `shell` stack declares it, unit tests, build, markdown bans, then the card exclusion check where one is installed. astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
+The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`. Base's `scripts/verify.ts` runs them in its fixed order, being typecheck, lint, format, shell where the `shell` stack declares it, unit tests, build, markdown bans, then the card exclusion check where installed.
 
-The card stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which keeps the social card route's build exclusion on the default path rather than behind a flag. It tests for the script rather than the stack, so a project with no card route runs one less stage with no override, and the stack shipping a card route owns what the check reads, being the build the stage before it produced. The astro reference carries the route itself.
+- Astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
+- The card stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, keeping the social card route's build exclusion on the default path rather than behind a flag.
+- It tests for the script rather than the stack, so a project with no card route runs one less stage with no override.
+- The stack shipping a card route owns what the check reads, being the build the stage before it produced. The astro reference carries the route itself.

package/docs/agents/canvas.md

@@ -1,86 +0,0 @@
----
-title: Canvas
-description: The canvas server, its content format, and the verbs that list, arrange, fit, select, edit, mark, and capture frames
----
-
-# Canvas
-
-`canon canvas` serves a local canvas of pages and HTML frames and gives an agent the verbs the operator's mouse has. A page is a folder under `.canon/canvas/`, a frame is one HTML file in it, and `layout.json` beside them holds each frame's box. `claude/skills/canvas-board/references/canvas.md` fixes that content format, and the `canvas-board` skill carries the procedure a session follows to drive the canvas.
-
-## Serve
-
-`canvas serve` serves the canvas on `127.0.0.1`, walks ports like `canon serve`, refuses a `Host` other than loopback on its own port, and runs until interrupted. Each frame gets the project's token stylesheet injected, being this toolkit's tokens in its own checkout, else `.claude/design/base.css` plus anything under `.claude/design/project/`, else none with a notice. An open canvas reloads a frame whose file changes.
-
-The toolkit's own tokens arrive with the font faces they name embedded, so a frame renders in them on a machine that never installed them. An installed base gets the same treatment: each vendored face its sheets name is embedded, unless a project rule declares that family itself.
-
-A project's own `@font-face` rules under `.claude/design/project/` have each `url()` inlined as a `data:` URI. A rule whose file is missing, or whose path leads out of `.claude/design/project/` after links resolve, is dropped and the frame still renders. `canvas serve` warns once per dropped rule and names each under `tokens.dropped` in its `--json` record. The confinement check reads each `url()` after percent-decoding it. `canon design fonts add` writes those rules.
-
-Before it binds a port, `canvas serve` checks that `preact` and `@preact/signals` resolve from the package the CLI runs from, never from the served project. When either is missing it refuses with reason `missing-client-deps` and names `bun install` in the detail, rather than serving a shell that loads as a blank page.
-
-The write routes the shell posts to also refuse a request carrying an `Origin` other than the server's own, and a body that is not JSON.
-
-## List and add
-
-`canvas list --json` emits every page with its frames. `page add`, `page rename`, and `frame add` (`--width`, `--height`) each emit one record under `--json`, refusing a name that is not one path segment, a page that already exists, or a root that is not a directory, with the reason on stderr.
-
-## Arrange and select
-
-`frame move <page> <name> --x <px> --y <px>` rewrites one frame's position in `layout.json` and keeps its size. An omitted axis stays where the frame is. It refuses a frame or page that does not exist and a layout that does not parse.
-
-`frame resize <page> <name> --width <px> --height <px>` rewrites one frame's whole box in one write, and `--x` and `--y` move it at the same time. An omitted flag keeps the frame's current value. It refuses a width or height that is not a positive number as `invalid-size`, a position that is not a number as `invalid-position`, and a missing frame, a missing page, or a layout that does not parse as `frame move` does.
-
-`canvas arrange <page>` re-lays a page's frames. It keeps the rows they already sit in, where boxes whose vertical spans overlap share a row, orders each row left to right by `x`, places the boxes on the 80px frame gap from the page's leftmost edge, and stacks the rows on their tallest box plus the gap from the page's top edge. It also drops every layout entry whose frame file is gone. `--check` writes nothing. `--json` emits `{ ok, page, written, moved, dropped }`, where `moved` lists each frame with its `from` and `to` position and `dropped` lists the entries with no file. Sizes never change. Under `--check` it exits 2 when a frame would move or an entry would drop, and it refuses a missing page as `no-page` and a layout that does not parse as `malformed-layout`.
-
-`canvas fit <page>/<frame>` and `canvas fit <page>` set each frame's height to its content. The content is measured in the capture browser at the frame's box width, through the served address, after fonts and the load event settle, and the height is that measure rounded up with no margin. The write goes through the same writer as `frame resize`. `--check` writes nothing. `--json` emits `{ ok, written, frames }`, one row per frame carrying `height`, `fitted`, `wide`, `font`, `viewport`, `family`, and `owed`. `wide` is true when the content is wider than the box, which fit reports and never widens, since the width is the frame's declared render width. `font` is true when the first family of the body text is not one the served sheet declares a face for, being the toolkit faces `Geist Variable`, `Noto Sans Mono`, and the hand-drawn pair, plus any face the project declares, because a height fitted against a machine family may not hold in another browser. `viewport` is true when the frame's height depends on the viewport, as a height in `vh` does. The lowest element edge is read with the viewport at the box height and at twice it, and an edge that moved means the content measure is not the height a viewer draws, so its height is kept and nothing is written for it. Under `--check` it exits 2 when any row is owed, and it refuses as `no-page`, `no-frame`, `no-server`, or `capture-failed` the way `canvas capture` does. Rows below a frame that grew do not move, so run `canvas arrange` after a fit.
-
-The shell writes through the same writer when the operator drags a frame or one of its corner handles. Both take a lock file beside the layout, read it, merge their change, and replace it, so a drag released while a verb writes loses neither position. A writer that cannot get the lock within two seconds refuses with reason `busy`.
-
-`canvas selection --json` emits `{ ok, selection }` with the page, frame, file, box, and path of the frame the operator selected, or `selection: null` when nothing is selected or the selected frame has since been removed. Read it when the operator says "this one".
-
-The operator can also pick one element inside a frame, by clicking it on the surface or in the frame's layers tree. The selection then carries `element`, recording the `index` in document order, `tag`, `classes`, and `text` excerpt as they were at the pick. An edit to the frame since can shift that index onto another element, so `stale` turns true once the file's content no longer matches what the pick was made against. Check it before acting on the index.
-
-A pick is refused as `address-mismatch` when the browser builds elements the file never states, such as a `tbody` a table leaves out or a `body` after a `head` the file states. A fragment is picked like a whole document, since the server writes the missing `html`, `head`, and `body` into the served frame and the shell leaves them out of its count. The shell sends its own element count beside the index, so a frame the two sides count differently is reported rather than recorded against the wrong element. A pick is refused as `stale-address` when the frame file changed between the frame being served and the pick arriving, since every served frame carries the hash of its file and the shell sends that hash back.
-
-## Edit
-
-`canvas edit <page>/<frame> --element <index> --set <property>=<value>` sets one property of the element at that index, the same index `canvas selection` reports. The properties are `text`, `color`, `background-color`, `font-size`, `font-weight`, `font-family`, `line-height`, `letter-spacing`, `text-align`, `width`, `height`, `padding`, `gap`, `display`, `flex-direction`, `justify-content`, `align-items`, `flex-wrap`, `opacity`, `border-radius`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, and `border-bottom-left-radius`. A style property is written into the element's inline `style`, replacing that property and leaving the others as they were, and an empty value drops it. Writing `border-radius` or `padding` also drops that shorthand's longhands from the same `style`, so no corner or side left over overrides the new value. Writing a longhand leaves its shorthand in place, since the longhand comes later and wins.
-
-`text` replaces the text of an element holding text alone and refuses one holding other elements as `not-text-only`. Every byte outside the element stays as it was. `--json` emits the page, frame, file, path, and the file's new `hash`.
-
-The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. Dragging a selected element's corner handle writes `width` and then `height` in pixels through that writer, the second edit carrying the hash the first answered. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
-
-Size, padding, opacity, radius, and the type properties show in the inspector for every element. Family and font size list the sheet's `font-family` and `font-size` token groups first and write a pick as `var(--<name>)`, the same as a color. The flex fields show only on a flex container, a grid container gets none, and the inspector sets `display` only to `flex`, so any other `display` change goes through the verb.
-
-A color picked from the project's tokens is written as `var(--<name>)`, and below full opacity as a `color-mix()` of that `var()` with `transparent` at the opacity percent, so it keeps following the theme. A browser older than 2023 drops a `color-mix()` value, which leaves the property unset there. A hex is written as six digits, or eight below full opacity. The inspector's full color picker writes a hex for any color it sets, so the field marks the value raw, and only its alpha keeps a token through the `color-mix()` form.
-
-Inline style beats a class, so an operator's edit masks a class change Claude makes later. Read a frame's inline styles before restyling it, and remove one the change should replace. The inspector marks a color, a background, or a family or font size the sheet has tokens for, set inline, with the word `raw` when its value names no `var()` and is not `currentColor` or a CSS-wide keyword, since that value stays fixed when the theme changes. A property outside the set, or a value carrying `;`, `{`, `}`, `<`, `>`, or a line break, is refused as `invalid-edit`.
-
-The Theme tab in the shell lists what the token stylesheet defines, grouped as color, spacing, radius, font family, font size, and other. The page record at `/api/pages` carries the same list as `tokens.groups`.
-
-## Undo in the shell
-
-The operator undoes and redoes their own shell edits, frame moves, and frame resizes from Ctrl or Cmd with Z, Shift with it or Ctrl with Y, or the tool strip's buttons. The history lives in the `canvas serve` process and covers shell edits alone, so a `canvas edit`, `canvas frame move`, or `canvas frame resize` never enters it, and their `--json` records are unchanged. A restart clears it.
-
-An undo writes the recorded state back only while the element or frame still holds what the operator's edit left. When Claude has since rewritten what that edit changed, being the element's inline style or, for a text edit, its text, or has added or removed an element in that frame, the operator's entry is dropped and nothing is written, and the shell says so. A write that changes another element's style or text, or another part of the same element, leaves the entry live. The page record at `/api/pages` carries `history` as `{ canUndo, canRedo }`.
-
-The tool strip also holds a toggle, bound to backslash, that hides both side panels to show the whole surface, and each panel resizes from a handle on its inner edge. Both are remembered in the browser and write nothing to the project.
-
-## Mark a frame being edited
-
-`canvas editing <page>/<frame>` marks a frame as being edited, so an open canvas shows who is working on it before the write lands. The shell draws the mark as `<by> editing` on that frame's label with a dashed outline around it, and drops it on the reread after `--done` or at the mark's `until` with no reread. Run it before writing a frame and again with `--done` once the edits are written. A bare `canvas editing` lists the live marks, and `--json` emits `{ ok, editing }` after each of the three, with each mark carrying `page`, `frame`, `by`, `since`, and `until`.
-
-The label is `--by <name>` when given. Without it, the verb reads the caller's name off the session roster, and falls back to `a session` when the environment names no session or the roster holds none matching it.
-
-The marks live in `.canon/canvas/editing.json`, keyed by `<page>/<frame>`. Each write takes the record's lock and merges its one key, so two sessions marking two frames both keep their marks. A mark lapses five minutes after it was written, and marking the frame again renews it, so a session that never clears its mark misleads the operator for five minutes at most. A read leaves out a lapsed mark and a mark on a frame since removed, and a record that does not parse reads as holding none and is replaced by the next mark.
-
-A mark refuses `no-page` or `no-frame` for a target not on disk, and `invalid-name` for a target that is not `<page>/<frame>` or for `--done` with no target. `--done` on a frame holding no mark succeeds and writes nothing. The mark gates no write, so an inspector edit to a marked frame still lands, and the hash check still refuses one made against a file the session rewrote. The page record at `/api/pages` carries the live marks as `editing`, each with `page`, `frame`, `by`, and `until`.
-
-## Capture
-
-`canvas capture <page>/<frame>` renders one frame as a PNG, and `canvas capture <page>` renders every frame on the page. Each goes through a server started for the call, so the injected tokens are in the image, and renders at the frame's own width from the layout, so a media query resolves there. It never captures the file on disk.
-
-`--out` is the PNG for a frame and a folder for a page, defaulting to session scratch. `--json` emits `{ ok, captures }` with the path and pixel size of each frame. Each PNG is the frame's whole document, so its height follows the document and not the frame's box. The font check `canon capture` makes applies, so a frame naming a font the machine lacks fails with that reason. A refused capture reports `no-page` or `no-frame` for a target that does not exist, `no-server` when the server for the call cannot start, and `capture-failed` for an error the engine throws, such as a browser that will not launch.
-
-`canvas capture <page> --composite` renders the whole page as one PNG, with every frame at its layout position and its own width. The image is the union of the frame boxes with no padding, transparent where no frame sits, and frames that overlap paint in the board's order. It shows the frames only, with no captions and no selection outline. Each frame is clipped to its box as it is on the board, so its height can differ from the per-frame PNG, and each shows in its default theme, since the board's theme toggle is client state the capture never sees. The font check covers the composite page and not the documents inside its frames.
-
-Under `--composite`, `--out` is the PNG itself, defaulting to `<page>.png` beside the per-frame folder in session scratch. `--json` emits `{ ok, composite }` carrying the page, the path, and the pixel size. The flag takes a page alone, and a `<page>/<frame>` target is refused as `invalid-name`. For the length of the call the generated page sits at `.canon/canvas/.composite/`, so it shares an origin with the frames, and the capture removes it after.