@erclx/canon 5.43.0 → 5.45.0

package/tooling/claude/seeds/.claude/hooks/search-reminder.sh

@@ -18,14 +18,9 @@ session=$(printf '%s' "$input" | jq -r '.session_id // empty')
 [ -n "$session" ] || exit 0
 
 key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
-# The marker is scratch, so it follows the scratch folder to whichever record
-# root the project carries rather than creating a second one beside it.
+# The marker is scratch, so it lives under `.canon/tmp/`.
 project="${CLAUDE_PROJECT_DIR:-.}"
-if [ -d "$project/.canon" ]; then
-  marker_dir="$project/.canon/tmp/hooks/search-reminder"
-else
-  marker_dir="$project/.claude/.tmp/hooks/search-reminder"
-fi
+marker_dir="$project/.canon/tmp/hooks/search-reminder"
 marker="$marker_dir/$key"
 [ -f "$marker" ] && exit 0
 mkdir -p "$marker_dir"

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -18,11 +18,9 @@ case "$file" in
 *) exit 0 ;;
 esac
 
-# Three record folders, at either root. A skip list fixed at the old spelling
-# audits a project's own session records the moment the move reaches it, which
-# reports findings against prose nobody publishes.
+# Session record folders are skipped, since they hold prose nobody publishes.
 case "$file" in
-*.claude/.tmp/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
+*.claude/review/* | *.claude/plans/*) exit 0 ;;
 *.canon/tmp/* | *.canon/review/* | *.canon/plans/*) exit 0 ;;
 esac
 

package/tooling/claude/seeds/.claude/settings.json

@@ -54,6 +54,10 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/records-index.sh"
           },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/board-validate.sh"
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/path-form.sh"

package/tooling/nextjs/reference.md

@@ -64,12 +64,6 @@ Next has no config-file port hook, unlike `server.port` in `astro.config.mjs` or
 
 `create-next-app`'s default `tsconfig.json` needs no changes beyond project-specific path aliases, so a golden copy would ship nothing the scaffold does not already write.
 
-## Gitignore (extend)
-
-These `[gitignore]` groups mirror the manifest.
-
-- `"# Next" = [".next/"]`
-
 ## Development docs (extend)
 
 Append these rows to the `## Scripts` table.

package/tooling/php/reference.md

@@ -59,10 +59,6 @@ The manifest prepares a scaffold that lacks a `package.json`.
 - The manifest's `[verify] prepare` runs checklist steps 2 and 5 for `canon tooling verify php`, being `bun init -y` and the `composer require --dev` line.
 - The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
-## Gitignore
-
-- `# PHP`: `vendor/`, `.php-cs-fixer.cache`, `.phpunit.cache/`, `.phpunit.result.cache`
-
 ## CI
 
 - Install PHP with `shivammathur/setup-php` and `tools: composer`.

package/tooling/web/configs/.github/workflows/verify.yml

@@ -62,9 +62,37 @@ jobs:
       - name: Install Dependencies
         run: bun install --frozen-lockfile
 
+      - name: Detect Browser Tests
+        id: browser
+        run: |
+          if jq -e '.scripts["test:browser"]' package.json >/dev/null; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install Playwright System Dependencies
+        if: steps.browser.outputs.enabled == 'true'
+        timeout-minutes: 10
+        run: bunx playwright install-deps chromium
+
+      - name: Cache Playwright Browsers
+        id: playwright-cache
+        if: steps.browser.outputs.enabled == 'true'
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('**/package.json') }}
+
+      - name: Install Playwright Chromium
+        if: steps.browser.outputs.enabled == 'true' && steps.playwright-cache.outputs.cache-hit != 'true'
+        run: bunx playwright install chromium
+
       - name: Run Tests
         run: bun run test:coverage
 
+      - name: Run Browser Tests
+        if: steps.browser.outputs.enabled == 'true'
+        run: bun run test:browser
+
   build-verify:
     name: 🏗️ Build
     runs-on: ubuntu-latest

package/tooling/web/configs/.oxlintrc.json

@@ -183,6 +183,13 @@
         "browser": true
       }
     },
+    {
+      "files": ["**/components/ui/**"],
+      "plugins": ["react"],
+      "rules": {
+        "react/only-export-components": "off"
+      }
+    },
     {
       "files": ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
       "rules": {

package/tooling/web/configs/e2e/capture-types.ts

@@ -0,0 +1,35 @@
+import type { Page } from '@playwright/test'
+
+/** One addressable part of a route, captured beside the whole-page frame. */
+export interface CaptureSection {
+  name: string
+  selector: string
+}
+
+export interface Viewport {
+  readonly name: string
+  readonly width: number
+  readonly height: number
+  /** Whether a case flagged `evidence: true` also writes its frames at this width. */
+  readonly evidence: boolean
+}
+
+export interface CaptureCase {
+  section: string
+  theme: string
+  route: string
+  /** Names of viewports this case skips, for a route that reflows rather than breaks at that width. */
+  excludeViewports?: readonly string[]
+  evidence?: boolean
+  /** Selectors painted over in every frame the case writes, for a value that moves between runs with no code change. */
+  mask?: readonly string[]
+  sections?: CaptureSection[]
+  setup?: (page: Page) => Promise<void>
+}
+
+/** What the harness loads from the project's `e2e/capture/cases.ts`. */
+export interface CaptureModule {
+  CASES: CaptureCase[]
+  /** Where a case flagged `evidence: true` writes its frames, relative to the working directory. */
+  EVIDENCE_ROOT: string
+}

package/tooling/web/configs/e2e/screenshot.ts

@@ -1,21 +1,15 @@
 import type { Locator, Page } from '@playwright/test'
 import { chromium } from '@playwright/test'
+import { existsSync } from 'fs'
 import { mkdir } from 'fs/promises'
 import path from 'path'
-
-/** One addressable part of a route, captured beside the whole-page frame. */
-interface CaptureSection {
-  name: string
-  selector: string
-}
-
-interface Viewport {
-  readonly name: string
-  readonly width: number
-  readonly height: number
-  /** Whether a case flagged `evidence: true` also writes its frames at this width. */
-  readonly evidence: boolean
-}
+import { pathToFileURL } from 'url'
+import type {
+  CaptureCase,
+  CaptureModule,
+  CaptureSection,
+  Viewport,
+} from './capture-types'
 
 /**
  * The breakpoint buckets every case is crossed with, named by width. 320 is
@@ -30,61 +24,18 @@ const VIEWPORTS: readonly Viewport[] = [
   { name: '1536', width: 1536, height: 800, evidence: false },
 ]
 
-interface CaptureCase {
-  section: string
-  theme: string
-  route: string
-  /** Names of viewports this case skips, for a route that reflows rather than breaks at that width. */
-  excludeViewports?: readonly string[]
-  evidence?: boolean
-  /** Selectors painted over in every frame the case writes, for a value that moves between runs with no code change. */
-  mask?: readonly string[]
-  sections?: CaptureSection[]
-  setup?: (page: Page) => Promise<void>
-}
+const CASES_FILE = path.resolve('e2e/capture/cases.ts')
 
-/**
- * The landing page's own beats, top to bottom. Every entry is a section a
- * reviewer reads on its own, so a diff lands on the part that moved rather
- * than on one image of the whole page.
- */
-const HOME_SECTIONS: CaptureSection[] = [
-  { name: 'top', selector: '#top' },
-  { name: 'proof', selector: '#proof' },
-  { name: 'ask', selector: '#ask' },
-  { name: 'rules', selector: '#rules' },
-  { name: 'skills', selector: '#skills' },
-  { name: 'plan', selector: '#plan' },
-  { name: 'dispatch', selector: '#dispatch' },
-  { name: 'workers', selector: '#workers' },
-  { name: 'gate', selector: '#gate' },
-  { name: 'evidence', selector: '#evidence' },
-  { name: 'loop', selector: '#loop' },
-  { name: 'merge', selector: '#merge' },
-  { name: 'provenance', selector: '#provenance' },
-  { name: 'start', selector: '#start' },
-  { name: 'field', selector: '#field' },
-  { name: 'close', selector: '#close' },
-]
+if (!existsSync(CASES_FILE)) {
+  console.error(
+    'e2e/capture/cases.ts is missing. Run canon tooling sync to seed it.',
+  )
+  process.exit(1)
+}
 
-const CASES: CaptureCase[] = [
-  {
-    section: 'home',
-    theme: 'default',
-    route: '/',
-    evidence: true,
-    mask: ['.version'],
-    sections: HOME_SECTIONS,
-  },
-  {
-    section: 'home',
-    theme: 'dark',
-    route: '/',
-    mask: ['.version'],
-    sections: HOME_SECTIONS,
-    setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
-  },
-]
+const { CASES, EVIDENCE_ROOT } = (await import(
+  pathToFileURL(CASES_FILE).href
+)) as CaptureModule
 
 /** One case at one viewport, which is the unit a filter selects and a context is built for. */
 interface CaptureRun {
@@ -170,9 +121,9 @@ async function settle(
     const element = page.locator(section.selector)
     // Read the count before scrolling, since a selector matching nothing
     // otherwise costs the default timeout once per section. A miss is
-    // reported and skipped rather than raised, because `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. The project owning the
+    // reported and skipped rather than raised, because the seeded `CASES` name
+    // sections a fresh target's page may not have, and it would otherwise
+    // capture nothing at all. The project owning the
     // selectors is the one that tests them, which is what the section spec
     // beside its own page does.
     if ((await element.count()) === 0) {
@@ -240,7 +191,7 @@ async function markFloatingChrome(page: Page) {
 /**
  * Turns a case's mask selectors into the locators every frame paints over. A
  * selector matching nothing is reported and kept out rather than raised, for
- * the same template reason `settle` gives for a missing section.
+ * the same reason `settle` gives for a missing section.
  */
 async function resolveMask(
   page: Page,
@@ -318,7 +269,7 @@ for (const { captureCase, viewport, label } of RUNS) {
   const mask = await resolveMask(page, label, captureCase.mask ?? [])
 
   const sweepDir = path.join(OUT_DIR, captureCase.section)
-  const evidenceDir = path.join('evidence', captureCase.section)
+  const evidenceDir = path.join(EVIDENCE_ROOT, captureCase.section)
   const file = `${viewport.name}--${captureCase.theme}.png`
   const writesEvidence = captureCase.evidence && viewport.evidence
 

package/tooling/web/manifest.toml

@@ -47,7 +47,7 @@ packages = [
 
 [gitignore]
 "# Build" = ["dist/"]
-"# Coverage" = ["coverage/"]
+"# Coverage" = ["coverage/", ".vitest/"]
 "# Playwright" = [
   "test-results/",
   "playwright-report/",

package/tooling/web/reference.md

@@ -4,139 +4,118 @@
 
 ## Overview
 
-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.
+The web layer covers the tooling shared across Vite + React, Astro, and Next.js. It sets lint, unit and end-to-end tests, Tailwind, screenshots, ports, and CI, and each framework stack adds its own wiring on top.
 
-## What ships as golden configs
-
-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.
+## oxlint
 
-### Lint and test setup
+- Run the recommended, React, and test-scoped vitest rules, with `check-file` and `simple-import-sort` as JS plugins
+- Pin oxlint exactly, since its JS plugin host is alpha and a minor release could break `check-file` or `simple-import-sort`
+- Keep import sorting on `simple-import-sort`, because oxfmt's built-in sort orders differently and would rewrite every import block
+- Expect sync to force-replace `lint` and `lint:fix`, so a target stops running ESLint. Astro keeps ESLint, which its own reference covers.
+- Delete a leftover `eslint.config.js` or `eslint.config.mjs` and `bun remove` the ESLint packages by hand after that sync, since sync deletes nothing a stack stopped shipping
 
-Two configs carry the lint and unit-test baseline.
+## Vitest
 
-- `.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.
+- Use jsdom, globals on, and `src/test/setup.ts`, which imports `@testing-library/jest-dom/vitest` and runs `cleanup` after each test
+- Test components with `@testing-library/react` and `@testing-library/user-event`
 
-### Screenshot cases
+## Playwright
 
-`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.
+- Keep end-to-end specs in `e2e/`, running Chromium alone for a Chrome extension and every browser for a web app
 
-- 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.
+## Tailwind
 
-### Sections and masks
+- Use v4 through `@tailwindcss/vite`, never the v3 integration
+- Add shadcn through the sequence under `## Adding shadcn`, since a bare `init` overwrites `src/styles/global.css` and waits on prompts
 
-A case may name `sections`, one `{ name, selector }` per addressable part of the route. Each writes its own frame beside the whole-page one.
+## Adding shadcn
 
-- 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.
+1. Copy `src/styles/global.css` aside, since init overwrites it.
+2. Confirm `global.css` starts with `@import 'tailwindcss';`, which init reads to find Tailwind v4, and that the `@/*` alias sits in both `tsconfig.json` and `vite.config.ts`.
+3. Take a preset name from `bunx shadcn@latest init --help`, since `-p` names a preset and not a primary color, and the default drifts between releases.
+4. Run `bunx shadcn@latest init -t vite -b radix -p <preset> -y </dev/null` with a timeout. The stdin redirect stops a non-TTY session from hanging on a prompt.
+5. Expect `components.json`, `src/lib/utils.ts`, and `src/components/ui/button.tsx`. Init installs the `cn` package for the helper and merges its theme into `global.css`, so reapply any copied styles.
 
-### Settling before a shot
+## TypeScript and layout
 
-Every case settles before anything is shot.
+- Keep app code in `src/`, Playwright in `e2e/`, shell in `scripts/`, and the Vitest globals in `src/test/setup.ts`
+- Map the `@` alias to `./src` in both tsconfig and the framework's build config
+- Keep the tsconfig at the root with `noEmit: true` in a Vite stack. Astro keeps the scaffold default from `@astrojs/check`.
+- Typecheck with `tsc --noEmit`, never `tsc -b`, since composite mode emits `.js` next to `.ts` and the linter lints it
 
-- 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.
+## Screenshot cases
 
-### Run flags
+- Edit the `CASES` in the seeded `e2e/capture/cases.ts`, one entry per output file naming a section, a theme, and a route, since sync overwrites the `e2e/screenshot.ts` harness
+- Move cases from `e2e/screenshot.ts` to `e2e/capture/cases.ts` before a sync, and set `EVIDENCE_ROOT = 'evidence'` to keep an existing baseline
+- Expect each case crossed with `VIEWPORTS`, written to `screenshots/<hostname>/<section>/<width>--<theme>.png`, so local and deployed runs stay apart
+- `VIEWPORTS` holds 320, 768, 1280, and 1536. Width 320 is the base a page has to hold without wrapping or clipping.
+- Set `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking
 
-Three controls narrow or harden a run.
+## Screenshot sections and masks
 
-- `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.
+- Set `evidence: true` to also write `<EVIDENCE_ROOT>/<section>/<width>--<theme>.png` at 320 and 1280 alone. `EVIDENCE_ROOT` defaults to `e2e/evidence`.
+- Name `sections` on a case, one `{ name, selector }` per addressable part of the route, each written as its own frame beside the whole-page one
+- Expect a section frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png`, plus the same path under `EVIDENCE_ROOT` where flagged
+- Expect a selector matching nothing to be reported and skipped, since a seeded list may name sections the page lacks, and test that they resolve in the project owning the selectors
+- List under `mask` the selectors painted over in every frame, for a value that moves with no code change, so a double capture compares the rest
 
-### Scripts and workflows
+## Screenshot settling
 
-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.
+- Expect `reducedMotion: 'reduce'`, and each named section scrolled into view so an `IntersectionObserver` fires and `loading="lazy"` frames load before the page returns to the top
+- Expect fonts, images, and same-origin frames waited out on a bounded condition, since a second `networkidle` does not re-arm for a load a scroll started
+- Expect a section frame to drop floating chrome (`position: sticky` or `fixed`), while the whole-page frame is shot first and keeps its chrome
 
-- `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`.
+## Screenshot run flags
 
-## What stays in per-stack adapters
+- `SCREENSHOT_FILTER` keeps cases whose `<section>/<width>--<theme>` label contains a comma-separated term, and exits 1 listing 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, every flagged case is skipped so a production smoke run writes nothing to the committed path, and zero cases run exits 1
 
-Framework glue lives in `tooling/vite-react/configs/` or `tooling/astro/configs/`, because merge helpers and config shapes differ.
+## Screenshot evidence
 
-- `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.
+- Expect the sweep under `screenshots/` to be ignored and only a flagged case's `EVIDENCE_ROOT` output tracked, so a target's first capture is the baseline it commits
+- Size a case's `sections` list against the frames each later change regenerates, since a case naming sections commits a folder per section
+- Run the capture after a surface changes, component files included, per `governance/rules/ui/surface-capture.md`, unless the production build strips the component out
 
-## File layout
+## Screenshot scripts and workflows
 
-- `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 sits at root with `noEmit: true` in Vite stacks. Astro keeps the scaffold default from `@astrojs/check`.
+- `scripts/screenshot.sh` sources `scripts/lib/preview-server.sh`, 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/`, and exits 1 until a project fills `README_FILTER`
+- `.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`. `unit-tests` installs Chromium and runs `test:browser` only when the project defines that script.
+- Read `governance/rules/tooling/ci-workflow.md` for when a workflow's commit-back is right and when a report is
 
 ## 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.
+- Derive every served port from `scripts/worktree-port.sh`, never a port literal in a script string, since two worktrees of one repository otherwise attach to one server
 - 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
-
-Negative knowledge that costs a failed run to relearn.
-
-| 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. |
+- Expect an offset from a band of 50 hashed from the worktree folder name, and set `WORKTREE_PORT_OFFSET` by hand to break a tie between two worktrees
+- Set `strictPort` on every dev and preview server, and Playwright `reuseExistingServer: false`, since a walked or reused server passes against the wrong code
+- Call the helper as `VAR=$(bash scripts/worktree-port.sh) && export VAR && <server>`, since an assignment prefix discards the substitution's exit and starts the server at offset zero
 
-## Tool pairing
+## Ports in a removed worktree
 
-- 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.
+- Expect a non-zero exit and no port from a folder left under `.claude/worktrees/` once its worktree is gone, since git reports the parent repository from inside one
+- Expect a folder whose own `.git` was deleted to refuse only under that directory, since location alone separates it from an ordinary subdirectory
+- Expect a folder whose `.git` names a pruned administrative directory to refuse wherever it sits
+- Set `WORKTREE_PORT_OFFSET` by hand to serve from such a folder anyway, since it is the one override and is checked before any directory test
 
-## oxlint
+## lint-staged (extend)
 
-- 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.
+- 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}`
 
-## lint-staged (extend)
+## Verify script
 
-- 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}`.
+- Expect `scripts/verify.json` to require `typecheck`, `lint`, `test:run`, and `build`, which base's `scripts/verify.ts` runs in its fixed order
+- That order is typecheck, lint, format, shell where the `shell` stack declares it, unit tests, build, markdown bans, then the card exclusion check
+- Expect the card stage to run `scripts/check-card-exclusion.sh` whenever that file is installed, so a project with no card route runs one less stage with no override
 
 ## CI docs (extend)
 
-Extend `canon/context/development/ci.md` so the `## Checks` table reflects the web jobs. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+- Extend the `## Checks` table in `canon/context/development/ci.md` with the web jobs <!-- audit-ignore-citations: canon/context/development/ci.md -->
+- Document under `## Running CI locally` that `bun run check:full` runs verify plus `test:e2e`
 
 | Check     | Command                 | What it asserts                             |
 | --------- | ----------------------- | ------------------------------------------- |
@@ -146,11 +125,10 @@ Extend `canon/context/development/ci.md` so the `## Checks` table reflects the w
 | 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`, and `typecheck` rows.
+- Extend the `## Scripts` table in the `development` context entry under `canon/context/` with every web script
+- Expect each framework stack to add its `dev`, `build`, `preview`, and `typecheck` rows
 
 | Command                     | Purpose                                 |
 | --------------------------- | --------------------------------------- |
@@ -164,28 +142,3 @@ Extend the `development` context entry under `canon/context/` so the `## Scripts
 | `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.    |
-
-### Screenshot contract
-
-`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 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)
-
-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`. 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.
-
-- 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/tooling/web/seeds/e2e/capture/cases.ts

@@ -0,0 +1,47 @@
+import type { CaptureCase, CaptureSection } from '../capture-types'
+
+/** Where a case flagged `evidence: true` writes its committed frames. */
+export const EVIDENCE_ROOT = 'e2e/evidence'
+
+/**
+ * The landing page's own beats, top to bottom. Every entry is a section a
+ * reviewer reads on its own, so a diff lands on the part that moved rather
+ * than on one image of the whole page.
+ */
+const HOME_SECTIONS: CaptureSection[] = [
+  { name: 'top', selector: '#top' },
+  { name: 'proof', selector: '#proof' },
+  { name: 'ask', selector: '#ask' },
+  { name: 'rules', selector: '#rules' },
+  { name: 'skills', selector: '#skills' },
+  { name: 'plan', selector: '#plan' },
+  { name: 'dispatch', selector: '#dispatch' },
+  { name: 'workers', selector: '#workers' },
+  { name: 'gate', selector: '#gate' },
+  { name: 'evidence', selector: '#evidence' },
+  { name: 'loop', selector: '#loop' },
+  { name: 'merge', selector: '#merge' },
+  { name: 'provenance', selector: '#provenance' },
+  { name: 'start', selector: '#start' },
+  { name: 'field', selector: '#field' },
+  { name: 'close', selector: '#close' },
+]
+
+export const CASES: CaptureCase[] = [
+  {
+    section: 'home',
+    theme: 'default',
+    route: '/',
+    evidence: true,
+    mask: ['.version'],
+    sections: HOME_SECTIONS,
+  },
+  {
+    section: 'home',
+    theme: 'dark',
+    route: '/',
+    mask: ['.version'],
+    sections: HOME_SECTIONS,
+    setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
+  },
+]