@erclx/canon 4.101.0 → 4.103.0

package/tooling/astro/manifest.toml

@@ -24,6 +24,7 @@ packages = [
 
 [scripts.override]
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 "dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
 "preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 

package/tooling/base/manifest.toml

@@ -18,9 +18,9 @@ packages = [
 
 [scripts]
 "check:spell" = "cspell '**' '.*/**' '.*' --no-progress --color --show-context"
-"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/"
+"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && find scripts -name '*.sh' -exec shfmt --diff --indent 2 {} +"
 "check:shell" = "find scripts -name '*.sh' -exec shellcheck --severity=warning {} +"
-"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/"
+"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && find scripts -name '*.sh' -exec shfmt --write --indent 2 {} +"
 "prepare" = "husky"
 "check" = "./scripts/verify.sh"
 

package/tooling/base/reference.md

@@ -35,7 +35,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
 - Formatting: Prettier for what it parses, shfmt for shell. Two formatters because Prettier has no shell parser.
 - Spelling: cspell over the whole tree, with project vocabulary split into a project-terms dictionary and a tech-stack one.
-- Shell: shfmt formats and shellcheck lints at warning severity. shfmt takes a directory argument, shellcheck has no directory mode and needs `find`.
+- Shell: shfmt formats and shellcheck lints at warning severity. Both take their files from `find scripts -name '*.sh'`, since `scripts/` can mix shell with TypeScript and shellcheck has no directory mode. A shell script with a shebang and no `.sh` extension is covered by neither, so give it the extension.
 - Commits: commitlint against conventional commits, wired through the husky `commit-msg` hook. Format is `<type>(<scope>): <subject>` in imperative mood with no trailing period.
 - Dev dependencies: `prettier`, `cspell`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
 

package/tooling/nextjs/manifest.toml

@@ -17,6 +17,7 @@ packages = [
 [scripts.override]
 "dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && next dev --port $((3000 + WORKTREE_PORT_OFFSET))"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 3000) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 3000) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 
 [gitignore]
 "# Next" = [".next/"]

package/tooling/web/configs/.github/workflows/readme-screenshot.yml

@@ -0,0 +1,110 @@
+name: README Screenshot
+# canon-no-seed: a stack-specific workflow with no root counterpart by design, since this repository reports its own capture in pr-visual-checks.yml and never commits it.
+
+# No `workflow_dispatch`: the job commits onto a pull request's head branch,
+# and a manual run has no pull request to commit onto.
+on:
+  pull_request:
+    paths:
+      # Project-specific. Replace the placeholder with the paths whose change
+      # moves the README frame, such as the component and styles it renders.
+      # The three entries below the placeholder keep the job firing on this
+      # file's own installation, which is what lets the first step refuse an
+      # unfilled template instead of the job never running.
+      - 'REPLACE_WITH_PROJECT_PATHS'
+      - 'scripts/readme-screenshot.sh'
+      - 'scripts/lib/preview-server.sh'
+      - '.github/workflows/readme-screenshot.yml'
+
+concurrency:
+  group: readme-screenshot-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  capture:
+    name: 🖼️ Refresh README Screenshot
+    runs-on: ubuntu-latest
+    # The default GITHUB_TOKEN cannot push to a fork's branch, so a PR from
+    # outside this repository is skipped rather than left to fail on the push
+    # step below.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Refuse An Unfilled Template
+        # A path list left at its placeholder never fires on the pages it was
+        # installed to watch, and that failure leaves no run, no diff, and no
+        # complaint. Failing here is what tells the project it has not
+        # finished installing.
+        run: |
+          if grep -q "^ *- 'REPLACE_WITH_PROJECT_PATHS'" .github/workflows/readme-screenshot.yml; then
+            echo "::error file=.github/workflows/readme-screenshot.yml::The paths list still holds REPLACE_WITH_PROJECT_PATHS. Replace it with the paths that move the README frame."
+            exit 1
+          fi
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Cache Playwright Browser
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-chromium-${{ hashFiles('**/package.json') }}
+
+      - name: Install Playwright System Dependencies
+        # Unconditional: the cache holds browser binaries and nothing apt
+        # wrote, so gating this on a cache hit leaves a warm run launching
+        # chromium without the libraries it needs.
+        run: bunx playwright install-deps chromium
+
+      - name: Install Playwright Browser
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: bunx playwright install chromium
+
+      - name: Capture README Screenshot
+        run: bun run readme-screenshot
+
+      - name: Check For Changes
+        id: diff
+        run: |
+          if git status --porcelain assets/evidence/readme | grep -q .; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit And Push
+        # Self-terminating: this push retriggers this same workflow on the PR,
+        # which captures again, finds no diff against what was just pushed,
+        # and stops here without pushing a second time.
+        if: steps.diff.outputs.changed == 'true'
+        # The hooks are off because this commit carries nothing they can read.
+        # `pre-push` runs the full verify, whose format step shells out to
+        # `shfmt`, which the runner does not install, so a push through them
+        # exits 127. The jobs in verify.yml already run those checks against
+        # the source, and what this step pushes is PNG bytes a capture
+        # produced.
+        env:
+          HUSKY: 0
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add assets/evidence/readme
+          git commit -m "chore(readme): refresh README screenshot"
+          git push origin "HEAD:${{ github.head_ref }}"

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

@@ -9,12 +9,33 @@ interface CaptureSection {
   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
+}
+
+/**
+ * The breakpoint buckets every case is crossed with, named by width. 320 is
+ * the base a page has to hold without wrapping or clipping. Committing every
+ * width multiplies the tracked frames by the width count, so only the base and
+ * the desktop width carry `evidence`.
+ */
+const VIEWPORTS: readonly Viewport[] = [
+  { name: '320', width: 320, height: 800, evidence: true },
+  { name: '768', width: 768, height: 800, evidence: false },
+  { name: '1280', width: 1280, height: 800, evidence: true },
+  { name: '1536', width: 1536, height: 800, evidence: false },
+]
+
 interface CaptureCase {
   section: string
   theme: string
   route: string
-  width: number
-  height: number
+  /** Names of viewports this case skips, for a route that reflows rather than breaks at that width. */
+  excludeViewports?: readonly string[]
   evidence?: boolean
   sections?: CaptureSection[]
   setup?: (page: Page) => Promise<void>
@@ -50,8 +71,6 @@ const CASES: CaptureCase[] = [
     section: 'home',
     theme: 'default',
     route: '/',
-    width: 1280,
-    height: 800,
     evidence: true,
     sections: HOME_SECTIONS,
   },
@@ -59,13 +78,28 @@ const CASES: CaptureCase[] = [
     section: 'home',
     theme: 'dark',
     route: '/',
-    width: 1280,
-    height: 800,
     sections: HOME_SECTIONS,
     setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
   },
 ]
 
+/** One case at one viewport, which is the unit a filter selects and a context is built for. */
+interface CaptureRun {
+  readonly captureCase: CaptureCase
+  readonly viewport: Viewport
+  readonly label: string
+}
+
+const ALL_RUNS: readonly CaptureRun[] = CASES.flatMap((captureCase) =>
+  VIEWPORTS.filter(
+    (viewport) => !captureCase.excludeViewports?.includes(viewport.name),
+  ).map((viewport) => ({
+    captureCase,
+    viewport,
+    label: `${captureCase.section}/${viewport.name}--${captureCase.theme}`,
+  })),
+)
+
 const args = process.argv.slice(2)
 const checkConsoleClean = args.includes('--check-console-clean')
 const requireBaseUrl = args.includes('--require-base-url')
@@ -87,6 +121,28 @@ try {
 
 const OUT_DIR = path.join('screenshots', hostname)
 
+const SCREENSHOT_FILTER = process.env.SCREENSHOT_FILTER?.trim() ?? ''
+
+const filterTerms = SCREENSHOT_FILTER.split(',')
+  .map((term) => term.trim())
+  .filter(Boolean)
+
+const RUNS =
+  filterTerms.length > 0
+    ? ALL_RUNS.filter((run) =>
+        filterTerms.some((term) => run.label.includes(term)),
+      )
+    : ALL_RUNS
+
+if (filterTerms.length > 0 && RUNS.length === 0) {
+  console.error(
+    `No cases matched SCREENSHOT_FILTER=${SCREENSHOT_FILTER}. Available labels:\n${ALL_RUNS.map(
+      (run) => `  ${run.label}`,
+    ).join('\n')}`,
+  )
+  process.exit(1)
+}
+
 /** Every wait on a lazy load is bounded explicitly. */
 const SETTLE_TIMEOUT = 15_000
 
@@ -198,12 +254,12 @@ const browser = await chromium.launch()
 const consoleErrors: string[] = []
 let ranCases = 0
 
-for (const captureCase of CASES) {
+for (const { captureCase, viewport, label } of RUNS) {
   if (captureCase.evidence && requireBaseUrl) continue
 
   ranCases++
   const context = await browser.newContext({
-    viewport: { width: captureCase.width, height: captureCase.height },
+    viewport: { width: viewport.width, height: viewport.height },
     // A page honoring the preference lands its own motion at the end state,
     // which is what a still frame has to show. Playwright reads it as a
     // context option, so it reaches no page written beside `viewport` above.
@@ -214,9 +270,7 @@ for (const captureCase of CASES) {
   if (checkConsoleClean) {
     page.on('console', (msg) => {
       if (msg.type() === 'error') {
-        consoleErrors.push(
-          `${captureCase.section}/${captureCase.theme}: ${msg.text()}`,
-        )
+        consoleErrors.push(`${label}: ${msg.text()}`)
       }
     })
   }
@@ -226,21 +280,21 @@ for (const captureCase of CASES) {
   await page.goto(`${BASE_URL}${captureCase.route}`)
   await page.waitForLoadState('networkidle')
 
-  const label = `${captureCase.section}/${captureCase.theme}`
   const sections = await settle(page, label, captureCase.sections ?? [])
 
   const sweepDir = path.join(OUT_DIR, captureCase.section)
   const evidenceDir = path.join('evidence', captureCase.section)
-  const file = `${captureCase.theme}.png`
+  const file = `${viewport.name}--${captureCase.theme}.png`
+  const writesEvidence = captureCase.evidence && viewport.evidence
 
   await shoot(page, sweepDir, file)
-  if (captureCase.evidence) await shoot(page, evidenceDir, file)
+  if (writesEvidence) await shoot(page, evidenceDir, file)
 
   if (sections.length > 0) await markFloatingChrome(page)
 
   for (const { name, selector } of sections) {
     await shoot(page, path.join(sweepDir, name), file, selector)
-    if (captureCase.evidence) {
+    if (writesEvidence) {
       await shoot(page, path.join(evidenceDir, name), file, selector)
     }
   }

package/tooling/web/configs/scripts/lib/preview-server.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Sourced, not executed. Builds the site, serves it in the background on
+# PREVIEW_PORT, and blocks until it answers or exits with an error. Shared by
+# scripts/screenshot.sh and scripts/readme-screenshot.sh so the two don't
+# carry two copies of the same startup boilerplate.
+set -euo pipefail
+
+: "${PREVIEW_PORT:=4173}"
+
+if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Port $PREVIEW_PORT already in use. Stop the listening process or set PREVIEW_PORT." >&2
+  exit 1
+fi
+
+bun run build
+bun run preview >/dev/null 2>&1 &
+PREVIEW_PID=$!
+# shellcheck disable=SC2154 # pid is bound by the for loop inside the single-quoted trap body, which shellcheck does not track there
+trap 'kill "$PREVIEW_PID" 2>/dev/null || true; if command -v lsof >/dev/null 2>&1; then for pid in $(lsof -ti tcp:"$PREVIEW_PORT" 2>/dev/null); do kill "$pid" 2>/dev/null || true; done; else echo "lsof not found on PATH; cannot confirm the preview port is clear of a detached grandchild." >&2; fi; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+
+for _ in $(seq 1 40); do
+  if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.25
+done
+
+if ! curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Preview server not responding on port $PREVIEW_PORT after 10s." >&2
+  exit 1
+fi

package/tooling/web/configs/scripts/readme-screenshot.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Project-specific. Both are placeholders the project fills in, and the script
+# refuses to run until it does, since a shipped default would capture the wrong
+# part of the page in every project but the one it was written for.
+README_FILTER='' # case label to capture, such as header/1280
+README_EVIDENCE_DIR='assets/evidence/readme'
+
+if [[ -z "$README_FILTER" ]]; then
+  echo "README_FILTER is unset in scripts/readme-screenshot.sh. Name the case label the README frame is captured from, such as header/1280." >&2
+  exit 1
+fi
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib/preview-server.sh"
+
+SCREENSHOT_BASE_URL="http://localhost:$PREVIEW_PORT" SCREENSHOT_FILTER="$README_FILTER" bun e2e/screenshot.ts
+
+# The filter's section and viewport name the folder and the file prefix the
+# capture wrote under screenshots/<hostname>/.
+frame_dir="screenshots/localhost/$(dirname "$README_FILTER")"
+frame_prefix="$(basename "$README_FILTER")"
+
+mkdir -p "$README_EVIDENCE_DIR"
+cp "$frame_dir/$frame_prefix--default.png" "$README_EVIDENCE_DIR/light.png"
+cp "$frame_dir/$frame_prefix--dark.png" "$README_EVIDENCE_DIR/dark.png"

package/tooling/web/configs/scripts/screenshot.sh

@@ -1,29 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-: "${PREVIEW_PORT:=4173}"
-
-if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
-  echo "Port $PREVIEW_PORT already in use. Stop the listening process or set PREVIEW_PORT." >&2
-  exit 1
-fi
-
-bun run build
-bun run preview >/dev/null 2>&1 &
-PREVIEW_PID=$!
-# shellcheck disable=SC2154 # pid is bound by the for loop inside the single-quoted trap body, which shellcheck does not track there
-trap 'kill "$PREVIEW_PID" 2>/dev/null || true; if command -v lsof >/dev/null 2>&1; then for pid in $(lsof -ti tcp:"$PREVIEW_PORT" 2>/dev/null); do kill "$pid" 2>/dev/null || true; done; else echo "lsof not found on PATH; cannot confirm the preview port is clear of a detached grandchild." >&2; fi; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
-
-for _ in $(seq 1 40); do
-  if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
-    break
-  fi
-  sleep 0.25
-done
-
-if ! curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
-  echo "Preview server not responding on port $PREVIEW_PORT after 10s." >&2
-  exit 1
-fi
+source "$(dirname "${BASH_SOURCE[0]}")/lib/preview-server.sh"
 
 SCREENSHOT_BASE_URL="http://localhost:$PREVIEW_PORT" bun e2e/screenshot.ts

package/tooling/web/manifest.toml

@@ -52,6 +52,7 @@ packages = [
 [scripts.override]
 "lint" = "eslint . --max-warnings 0"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 
 [gitignore]
 "# Build" = ["dist/"]

package/tooling/web/reference.md

@@ -12,7 +12,11 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` 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, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--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 themes sit together under its section folder, so the filename carries the theme alone. 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>/<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<theme>.png` where the case is flagged. 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. 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`.
+- `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. 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/ci/700-ci-workflow.md` states the test.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -106,6 +110,7 @@ Append rows:
 | `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. |
 
 `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.