@erclx/canon 4.92.0 → 4.93.0

package/README.md

@@ -6,7 +6,7 @@
 
 canon is a CLI and Claude Code plugin that stops your AI conventions drifting apart across repositories. It keeps one authoritative copy and installs it into each project on demand.
 
-![The canon catalog, listing skills, governance rules, and standards with the count each ships, the workflow skills named, and a sample of the rule and standard names](assets/hero.png)
+![The canon catalog, listing skills, governance rules, and standards with the count each ships, the workflow skills named, and a sample of the rule and standard names](assets/evidence/hero.png)
 
 The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today. See it live at [canon.erclx.dev](https://canon.erclx.dev).
 
@@ -39,7 +39,7 @@ claude plugin marketplace add https://github.com/erclx/canon
 claude plugin install canon@canon
 ```
 
-![Adding the canon marketplace and installing the plugin in Claude Code](assets/install.png)
+![Adding the canon marketplace and installing the plugin in Claude Code](assets/evidence/install.png)
 
 The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
 
@@ -67,19 +67,19 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 Those domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
 
-![canon tooling list and canon standards list side by side, the first showing five stacks with their dependency and script counts, the second showing standards against the artifact each governs](assets/install-surface.png)
+![canon tooling list and canon standards list side by side, the first showing five stacks with their dependency and script counts, the second showing standards against the artifact each governs](assets/evidence/install-surface.png)
 
 A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
 
 Governance is the third shape, and it is worth seeing rather than reading about, because the glob beside each rule is what decides whether it reaches a session at all.
 
-![canon gov list, showing seven stacks with the rules each carries and a sample of rules beside the path glob that loads each one](assets/governance.png)
+![canon gov list, showing seven stacks with the rules each carries and a sample of rules beside the path glob that loads each one](assets/evidence/governance.png)
 
 Stacks compose, so a react project inherits node and node inherits base. A rule with a glob loads only when a matching path is edited, and a rule with none loads every session. Both counts and every row above are read from the catalogs when the image is built.
 
 The toolkit tracks its own work the same way, in a task board no catalog can read back.
 
-![the task board's Run now table, one row per task in flight, each naming the files it touches and the plan it runs under](assets/task-board.png)
+![the task board's Run now table, one row per task in flight, each naming the files it touches and the plan it runs under](assets/evidence/task-board.png)
 
 `.canon/tasks/` is gitignored session scratch, so unlike the two frames above, this one is a hand-taken snapshot rather than something the build reads live, and it goes stale the moment the board moves.
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.92.0",
+  "version": "4.93.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -73,7 +73,7 @@ The stepper hides and shows and sets nothing else, so how a selected option look
 
 ## The block list
 
-`canon teach render` takes a JSON array of blocks and renders it through the same components the fixture lesson is generated from. Four types, and every structural body composes from them:
+`canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Four types, and every structural body composes from them:
 
 - `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
 - `{"type":"paragraph","text":"<text>","lede":true}`: a `<p>`, marked `lede` for the dek that opens the lesson.

package/docs/agents/capture.md

@@ -5,11 +5,11 @@ description: Rendering HTML sources to PNG, what the command asserts about fonts
 
 # Capture
 
-`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command. That default is a generic starting point rather than a convention every target shares, and it stays because a missing folder still refuses loud, naming the argument, rather than failing silently. This repository no longer takes it: its own sources moved to `assets/captures/` and its images stayed in `assets/`, so a run here names the source explicitly and sends the output where that run wants it, `--out assets` to rebuild the committed images and somewhere disposable to preview them.
+`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command. That default is a generic starting point rather than a convention every target shares, and it stays because a missing folder still refuses loud, naming the argument, rather than failing silently. This repository no longer takes it: its own sources moved to `assets/captures/` and its images moved to `assets/evidence/`, so a run here names the source explicitly and sends the output where that run wants it, `--out assets/evidence` to rebuild the committed images and somewhere disposable to preview them.
 
 ```bash
 canon capture --selector .window
-canon capture assets/captures/install.html --selector .window --out assets
+canon capture assets/captures/install.html --selector .window --out assets/evidence
 canon capture assets/captures --selector .window --out .canon/review/captures
 canon capture https://example.com --selector .window --out preview.png
 ```
@@ -18,13 +18,13 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds five sources and the template each is written from, and `assets/` holds the five images a document points at with the stamp answering for each. One run over the source folder rebuilds every image, and it takes `--out assets` to put each PNG where its document points rather than beside the markup it rendered. None of the five is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+A capture set here spans two folders. `assets/captures/` holds five sources and the template each is written from, and `assets/evidence/` holds the five images a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the five is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
 
 Three of the five take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` and `task-board.html` are the two exceptions: the first holds terminal text from a real run and the second holds a hand-frozen snapshot of a gitignored board, each in its template rather than derived from a live catalog at build time.
 
-`assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/` no longer mixes markup in with the images.
+`assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
 
-Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/captures --selector .window --out assets` when the check reports the HTML changed.
+Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/captures --selector .window --out assets/evidence` when the check reports the HTML changed.
 
 Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. A capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
 
@@ -34,6 +34,7 @@ Neither digest is ever written by hand. A digest is what the gate compares, so a
 | ------------------ | ------------------------------------------------------------------------------------------------------ |
 | `--out <dir>`      | Write every PNG here instead of beside its source. For a URL source, names the destination PNG itself. |
 | `--selector <sel>` | Element to capture, required and never defaulted                                                       |
+| `--width <px>`     | Render at this viewport width so a media query resolves there. One whole number of 1 or more.          |
 
 ## What the command asserts
 
@@ -50,3 +51,9 @@ The command ships to targets, alongside `demo`, `inventory`, and `drive`. It was
 Shipping it also fixed what the exclusion was hiding. The render module imported the `@playwright/test` development dependency, which no published tarball carries. Every browser reference still sits behind a dynamic import, so a browser loads for this command rather than in front of every other one.
 
 `demo.md` and `driver.md` cover two of the other three browser commands. What separates this one is that a capture renders a single state, from a file on disk or a named `http(s)://` URL, where the rest drive a running application.
+
+## Capturing at a width
+
+`--width` sets the browser viewport and leaves the page alone. A media query answers to the viewport, so a wrapper narrowed to 390px renders a thin column of the desktop layout and proves nothing about the mobile one. The height stays at Playwright's default of 720, which keeps `vh` units where they are without the flag. A run that passes no `--width` passes no viewport option at all, so every committed image renders as before and no stamp digest moves.
+
+The flag takes one integer and no list. A sweep across breakpoints is one run per width, and the caller picks `--out` for each, since two widths written into one directory overwrite each other under the source's name. A value that is not a whole number of 1 or more refuses ahead of the browser import, naming the flag.

package/docs/agents/commands.md

@@ -103,8 +103,8 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon gate run`                 | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                                                                                                                                                                                  |
 | `canon inventory [subject]`      | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                                                                                                                                                                         |
 | `canon drive <url> <run>`        | Walk a page through named interactions and measure each state it reaches, reporting findings rather than gating (`--json`)                                                                                                                                                                                                   |
-| `canon capture [source]`         | Render an HTML source or an `http(s)://` URL to PNG and prove the font each one declares resolved (`--selector` required, `--out`)                                                                                                                                                                                           |
-| `canon serve [dir]`              | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                                                                                                                                                                                      |
+| `canon capture [source]`         | Render an HTML source or an `http(s)://` URL to PNG and prove the font each one declares resolved (`--selector` required, `--out`, `--width`)                                                                                                                                                                                |
+| `canon serve [dir]`              | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--index`, `--json`)                                                                                                                                                                           |
 | `canon upgrade`                  | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                                                                                                                                                                        |
 
 `canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. A teach lesson's stylesheet is embedded rather than linked, so only its script still needs a server. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
@@ -113,7 +113,7 @@ A port already in use is the ordinary case rather than a refusal, so it walks fo
 
 A request naming a directory is redirected to its trailing-slash form rather than answered in place. A browser resolves a relative asset against the last slash of the URL it is on, so answering `/lesson` directly leaves the page asking for `/course.css` instead of `/lesson/course.css`, and it renders unstyled through the server that exists to prevent exactly that.
 
-Containment is tested after symlinks are followed rather than on the path as written, and the test sits immediately before the read rather than beside the request that produced it. Resolving a request lexically clears a link pointing outside the served root, and this repository is a live instance of that shape, since `claude/standards` and `claude/snippets` are links out of `claude/`. Position is what makes the property hold: a directory request appends its index after the request path has been checked, so a check placed earlier leaves that index untested. An `--entry` that escapes the root refuses with `no-entry` before a port is taken, because `url` is the field a caller hands to a reader.
+Containment is tested after symlinks are followed rather than on the path as written, and the test sits immediately before the read rather than beside the request that produced it. Resolving a request lexically clears a link pointing outside the served root, and this repository is a live instance of that shape, since `claude/standards` and `claude/snippets` are links out of `claude/`. Position is what makes the property hold: a directory request appends its index after the request path has been checked, so a check placed earlier leaves that index untested. `--index` answers a directory holding no `index.html` with a listing read per request, where the default stays a 404. Every entry the listing names takes the same containment test a request for it would, so a link out of the root is absent rather than greyed, and dotfiles are hidden. With no `--entry` and no root `index.html`, the printed link is `/` and `entryExists` reads true. An `--entry` that escapes the root refuses with `no-entry` before a port is taken, because `url` is the field a caller hands to a reader.
 
 `canon demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
 

package/docs/agents/rule-citations.md

@@ -73,7 +73,7 @@ A rule under `governance/rules/` installs into a target, and its `paths:` entrie
 
 `internal/rules/` ships nowhere. The tree it governs is the tree present, which makes the question answerable, and all 14 of its globs across 7 rules match at the commit this shipped on.
 
-What that leaves unreached is a glob that matches real files and still reaches none of the work it was scoped at. `governance/rules/lib/305-e2e-reliability.md` scopes itself at `e2e/*.ts` and `e2e/**/*.ts`, and no probe in this repository is written under `e2e/`, so the rule asking a session to watch a new guard fail never fired for the session writing guards. Resolution is mechanical and reach is a judgment about where the work happens, so only the first is here.
+What that leaves unreached is a glob that matches real files and still reaches none of the work it was scoped at. `governance/rules/lib/305-e2e-reliability.md` scoped itself at `e2e/*.ts` and `e2e/**/*.ts` and now reads `**/e2e/**/*.ts`. No probe in this repository is written under `e2e/`, so the rule asking a session to watch a new guard fail never fired for the session writing guards. Resolution is mechanical and reach is a judgment about where the work happens, so only the first is here.
 
 ## The exemption marker
 

package/docs/agents/teach.md

@@ -141,7 +141,7 @@ The order is drawn here rather than instructed, and that is the point of the ver
 
 ## Render
 
-`canon teach render` renders a lesson body's structural blocks to HTML, through the components `src/teach/render-fixture.tsx` composes by hand. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+`canon teach render` renders a lesson body's structural blocks to HTML, through the three lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
 
 ```bash
 echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json

package/governance/rules/lib/305-e2e-reliability.md

@@ -1,8 +1,7 @@
 ---
 description: Enforce settled waits and falsifiable guards in end-to-end tests
 paths:
-  - 'e2e/*.ts'
-  - 'e2e/**/*.ts'
+  - '**/e2e/**/*.ts'
 ---
 
 # End-to-end reliability standards
@@ -14,6 +13,8 @@ paths:
 - Bound every settle with an explicit timeout.
 - Do not raise a timeout to clear a failure that reproduces under load. Replace the wait with a settle.
 - Do not read a value once after a pause. Poll it.
+- Settle a smooth scroll on the `scrollend` event. Fall back to a stillness window only when the target was already in view.
+- Run with motion reduced unless the test asserts motion, and opt back in per test.
 
 ## Falsifiable guards
 

package/governance/rules/lib/306-test-scope.md

@@ -1,8 +1,7 @@
 ---
 description: Enforce which specs and which engines an end-to-end run covers at each point in the loop
 paths:
-  - 'e2e/*.ts'
-  - 'e2e/**/*.ts'
+  - '**/e2e/**/*.ts'
 ---
 
 # Test scope standards

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]
+rules = ["210-astro", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.92.0",
+  "version": "4.93.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -19,7 +19,8 @@
     "tsconfig.json",
     "!scripts/sandbox",
     "!scripts/eval",
-    "!**/*.test.ts"
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/core/regen-hero.sh

@@ -18,10 +18,11 @@
 # Only the HTML regenerates here. The PNG beside it is a chromium render whose
 # bytes move with the browser version, so asserting it in verify.sh would fail
 # on a machine whose chromium differs rather than on a stale count. Rebuild the
-# images with `canon capture assets/captures --selector .window --out assets`
+# images with `canon capture assets/captures --selector .window --out assets/evidence`
 # after this script reports a change. The markup and the image sit in two
-# folders, so that run reads the sources here and sends every PNG and stamp back
-# up to assets/, where the documents point. The selector has no default, since
+# folders, so that run reads the sources here and sends every PNG and stamp to
+# assets/evidence/, where the documents point and where `canon pr evidence`
+# compares a changed image. The selector has no default, since
 # the element a capture crops to belongs to the page rather than to the command,
 # and `.window` is the class this repository's own sources declare.
 # That capture also writes a .stamp beside each PNG, which records the digest of

package/src/capture/render.ts

@@ -25,6 +25,7 @@ import { formatStamp, hashSource, stampPath } from '@/capture/stamp'
  */
 
 const DEVICE_SCALE_FACTOR = 2
+const DEFAULT_VIEWPORT_HEIGHT = 720
 const FONT_PROBE_SIZE = 72
 const FONT_PROBE_TEXT = 'canon capture 0123456789'
 const ABSENT_FAMILY = '__canon_absent_family__'
@@ -32,6 +33,7 @@ const ABSENT_FAMILY = '__canon_absent_family__'
 export interface CaptureOptions {
   selector: string
   outDir?: string
+  width?: number
 }
 
 export type CaptureResult =
@@ -54,7 +56,9 @@ export async function captureSources(
   const browser = await chromium.launch()
   try {
     return await Promise.all(
-      sources.map((source) => captureOne(browser, source, options.selector)),
+      sources.map((source) =>
+        captureOne(browser, source, options.selector, options.width),
+      ),
     )
   } finally {
     await browser.close()
@@ -69,9 +73,19 @@ async function captureOne(
   browser: Browser,
   source: CaptureSource,
   selector: string,
+  width: number | undefined,
 ): Promise<CaptureResult> {
+  /**
+   * A viewport rather than a wrapper, since a media query answers to the
+   * viewport. Absent leaves the option out so the browser default stands and
+   * every committed capture renders as before. The height is Playwright's own
+   * default, which keeps `vh` units where they were.
+   */
   const page = await browser.newPage({
     deviceScaleFactor: DEVICE_SCALE_FACTOR,
+    ...(width === undefined
+      ? {}
+      : { viewport: { width, height: DEFAULT_VIEWPORT_HEIGHT } }),
   })
   try {
     await page.goto(

package/src/cli.ts

@@ -121,7 +121,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon design board`,
     `${GREY}│${NC}    canon slides render`,
     `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets`,
+    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets/evidence`,
     `${GREY}│${NC}    canon serve .canon/teach`,
     `${GREY}│${NC}    canon inventory focus --json`,
     `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,

package/src/commands/capture.ts

@@ -54,10 +54,14 @@ export function register(program: Command): void {
       'Output directory for a file source, or the destination PNG for a URL source; defaults beside the source',
     )
     .option('-s, --selector <selector>', 'Element to capture')
+    .option(
+      '--width <px>',
+      'Viewport width in pixels, so a media query resolves at that width',
+    )
     .action(
       async (
         source: string,
-        opts: { out?: string; selector?: string },
+        opts: { out?: string; selector?: string; width?: string },
       ): Promise<void> => {
         /**
          * Refused rather than defaulted, and refused ahead of every other
@@ -75,6 +79,15 @@ export function register(program: Command): void {
         }
         const selector = opts.selector
 
+        const width = parseWidth(opts.width)
+        if (Number.isNaN(width)) {
+          frameError(
+            `--width takes a whole number of pixels of 1 or more, got ${opts.width}.`,
+          )
+          process.exitCode = 1
+          return
+        }
+
         const isUrl = isUrlSource(source)
         const sourcePath = isUrl ? source : resolve(process.cwd(), source)
         if (!isUrl && !existsSync(sourcePath)) {
@@ -89,6 +102,7 @@ export function register(program: Command): void {
           const renderer = await import('@/capture/render')
           results = await renderer.captureSources(sourcePath, {
             selector,
+            width,
             outDir: opts.out ? resolve(process.cwd(), opts.out) : undefined,
           })
         } catch (error) {
@@ -122,6 +136,16 @@ export function register(program: Command): void {
     )
 }
 
+/**
+ * Undefined for an absent flag and `NaN` for a value that is not a positive
+ * integer, so the caller can tell no width from a bad one.
+ */
+function parseWidth(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined
+  const value = Number(raw)
+  return Number.isInteger(value) && value >= 1 ? value : Number.NaN
+}
+
 /**
  * Closes an open frame around a failure that stopped the whole run rather than
  * one source. Two of them are setup states rather than defects and each names

package/src/commands/serve.ts

@@ -7,6 +7,7 @@ const DEFAULT_DIR = '.'
 
 interface ServeCommandOptions {
   readonly entry?: string
+  readonly index?: boolean
   readonly json?: boolean
   readonly port?: string
 }
@@ -19,6 +20,10 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--port <number>', `Port to try first, default ${DEFAULT_PORT}`)
     .option('--entry <path>', 'Page the printed link opens, default index.html')
+    .option(
+      '--index',
+      'List a directory that has no index.html instead of answering 404',
+    )
     .option('--json', 'Emit a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -39,6 +44,7 @@ export function register(program: Command): void {
         '  canon serve .canon/teach',
         '  canon serve .canon/teach --entry 03-fde-system-design/index.html',
         '  canon serve dist --port 4000 --json',
+        '  canon serve .canon/groundwork --index',
         '',
       ].join('\n'),
     )
@@ -61,7 +67,11 @@ async function runServe(
     )
   }
 
-  const outcome = startServer(dir, { port, entry: opts.entry })
+  const outcome = startServer(dir, {
+    port,
+    entry: opts.entry,
+    index: opts.index,
+  })
   const code = report(outcome, emitJson)
   if (!outcome.ok) return code
 

package/src/gate/measures.ts

@@ -142,7 +142,7 @@ export function auditsBaselineRel(root: string): string {
 }
 
 export const CAPTURE_STAMP_FAILURE =
-  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets and commit each frame with its image and its stamp.'
+  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets/evidence and commit each frame with its image and its stamp.'
 
 function parseJson(payload: string): unknown {
   try {
@@ -1118,11 +1118,12 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
 /**
  * A capture set spans two folders. The markup and the template beside it are
  * the authored half and sit under `assets/captures/`, while the image a
- * document points at and the stamp answering for it stay in `assets/`, which is
- * where `--out assets` sends them.
+ * document points at and the stamp answering for it sit under
+ * `assets/evidence/`, which is where `--out assets/evidence` sends them and where
+ * `canon pr evidence` looks for a changed image.
  */
 const CAPTURE_MARKUP_DIR = 'assets/captures'
-const CAPTURE_OUTPUT_DIR = 'assets'
+const CAPTURE_OUTPUT_DIR = 'assets/evidence'
 
 /**
  * Every capture under `assets/captures/`, named by the base its three files

package/src/gate/stages.ts

@@ -201,7 +201,7 @@ export const STAGES: readonly Stage[] = [
         kind: 'drift',
         pathspec: 'assets/captures/*.html',
         failure:
-          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets/captures --selector .window --out assets, and commit each assets/captures/*.html with its .png and .stamp.',
+          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets/captures --selector .window --out assets/evidence, and commit each assets/captures/*.html with its .png and .stamp.',
       },
       { kind: 'measure', measure: captureStamps },
     ],

package/src/serve/static.ts

@@ -1,4 +1,4 @@
-import { existsSync, realpathSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
 
 /**
@@ -81,6 +81,66 @@ export type ServeOutcome = ServeStarted | ServeRefused
 export interface ServeOptions {
   readonly port?: number
   readonly entry?: string
+  /** Answers a directory request with no index page by listing it. Off by default. */
+  readonly index?: boolean
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+}
+
+interface ListingEntry {
+  readonly name: string
+  readonly isDirectory: boolean
+}
+
+/**
+ * Reads the entries a listing may name. Each one takes the same containment
+ * test a request for it would, since a listed name is itself a fact about a
+ * place outside the root. Dotfiles are hidden because a listing is for
+ * navigating pages, and a hidden file is still reachable by its URL.
+ */
+function listEntries(root: string, directory: string): ListingEntry[] {
+  return readdirSync(directory)
+    .filter((name) => !name.startsWith('.'))
+    .filter((name) => !escapesThroughLink(root, join(directory, name)))
+    .map((name) => ({
+      name,
+      isDirectory:
+        statSync(join(directory, name), {
+          throwIfNoEntry: false,
+        })?.isDirectory() ?? false,
+    }))
+    .sort(
+      (a, b) =>
+        Number(b.isDirectory) - Number(a.isDirectory) ||
+        a.name.localeCompare(b.name),
+    )
+}
+
+function renderListing(
+  pathname: string,
+  entries: readonly ListingEntry[],
+  hasParent: boolean,
+): string {
+  const rows = entries.map(({ name, isDirectory }) => {
+    const label = isDirectory ? `${name}/` : name
+    return `<li><a href="${escapeHtml(encodeURIComponent(name))}${isDirectory ? '/' : ''}">${escapeHtml(label)}</a></li>`
+  })
+  if (hasParent) rows.unshift('<li><a href="../">../</a></li>')
+  return `<!doctype html>
+<meta charset="utf-8">
+<title>Index of ${escapeHtml(pathname)}</title>
+<h1>Index of ${escapeHtml(pathname)}</h1>
+<ul>
+${rows.join('\n')}
+</ul>
+`
 }
 
 function refuse(reason: ServeRefusal, detail: string): ServeRefused {
@@ -165,13 +225,14 @@ export function shouldWalkPast(error: unknown): boolean {
 function listen(
   root: string,
   first: number,
+  index: boolean,
 ): { server: ReturnType<typeof Bun.serve>; port: number } | undefined {
   for (let port = first; port < first + PORT_ATTEMPTS; port++) {
     try {
       const server = Bun.serve({
         hostname: SERVE_HOST,
         port,
-        fetch: (request) => respond(root, request),
+        fetch: (request) => respond(root, request, index),
       })
       /**
        * The bound port rather than the requested one. Port 0 asks the OS to
@@ -196,6 +257,7 @@ function listen(
 export async function respond(
   root: string,
   request: Request,
+  index = false,
 ): Promise<Response> {
   const { pathname, search } = new URL(request.url)
   const forbidden = () =>
@@ -229,7 +291,19 @@ export async function respond(
         headers: { location: `${pathname}/${search}` },
       })
     }
-    path = join(path, DEFAULT_ENTRY)
+    const indexPage = join(path, DEFAULT_ENTRY)
+    if (index && !existsSync(indexPage)) {
+      return new Response(
+        renderListing(pathname, listEntries(root, path), path !== root),
+        {
+          headers: {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+          },
+        },
+      )
+    }
+    path = indexPage
   }
 
   /**
@@ -291,7 +365,7 @@ export function startServer(
    */
   let bound: ReturnType<typeof listen>
   try {
-    bound = listen(root, first)
+    bound = listen(root, first, options.index ?? false)
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
     return refuse(
@@ -307,14 +381,24 @@ export function startServer(
     )
   }
 
+  /**
+   * A listing answers `/` where no index page exists, so under the flag the
+   * default entry is the root itself. An explicit `--entry` keeps its own link
+   * and its own warning.
+   */
+  const listsRoot =
+    (options.index ?? false) &&
+    options.entry === undefined &&
+    !existsSync(entryPath)
+
   return {
     ok: true,
     root,
     host: SERVE_HOST,
     port: bound.port,
     entry,
-    url: `http://${SERVE_HOST}:${bound.port}/${entry}`,
-    entryExists: existsSync(entryPath),
+    url: `http://${SERVE_HOST}:${bound.port}/${listsRoot ? '' : entry}`,
+    entryExists: listsRoot || existsSync(entryPath),
     stop: async () => {
       await bound.server.stop(true)
     },

package/src/teach/render.ts

@@ -109,8 +109,8 @@ function renderBlock(
 
 /**
  * Renders a lesson body's structural blocks through the same components
- * `render-fixture.tsx` composes by hand, so a real lesson and the committed
- * fixture share one rendering mechanism. Every block past the first refusal
+ * `lesson.test.tsx` composes as JSX, so a real lesson and the component test
+ * share one rendering mechanism. Every block past the first refusal
  * goes unread, matching how a malformed JSON parse refuses the whole call.
  */
 export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {

package/tooling/astro/configs/playwright.config.ts

@@ -13,6 +13,8 @@ export default defineConfig({
   use: {
     trace: 'on-first-retry',
     baseURL,
+    // Nothing to wait out unless a test asserts motion. Opt back in per test with page.emulateMedia({ reducedMotion: 'no-preference' }).
+    reducedMotion: 'reduce',
   },
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },

package/tooling/nextjs/configs/playwright.config.ts

@@ -11,6 +11,8 @@ export default defineConfig({
   use: {
     trace: 'on-first-retry',
     baseURL,
+    // Nothing to wait out unless a test asserts motion. Opt back in per test with page.emulateMedia({ reducedMotion: 'no-preference' }).
+    reducedMotion: 'reduce',
   },
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },

package/tooling/vite-react/configs/playwright.config.ts

@@ -13,6 +13,8 @@ export default defineConfig({
   use: {
     trace: 'on-first-retry',
     baseURL,
+    // Nothing to wait out unless a test asserts motion. Opt back in per test with page.emulateMedia({ reducedMotion: 'no-preference' }).
+    reducedMotion: 'reduce',
   },
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },

package/src/teach/render-fixture.tsx

@@ -1,95 +0,0 @@
-/** @jsxImportSource ./html */
-import { mkdir, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { TEACH_STYLESHEET_COMPONENTS } from '@/design/components'
-import { buildDesignCss } from '@/design/css'
-import { TEACH_FONT_FACES } from '@/teach/fonts'
-import { Heading } from '@/teach/components/heading'
-import { List } from '@/teach/components/list'
-import { Paragraph } from '@/teach/components/paragraph'
-import { render } from '@/teach/html/jsx-runtime'
-
-/**
- * Regenerates the committed fixture lesson under
- * `examples/teach/00-fixture/`, the same shape `examples/slides/showcase.md`
- * takes against its own hand-rendered snapshot. Run with
- * `bun src/teach/render-fixture.tsx` after a component changes shape.
- */
-
-const FIXTURE_ROOT = join(
-  import.meta.dir,
-  '..',
-  '..',
-  'examples',
-  'teach',
-  '00-fixture',
-)
-const LESSON_TITLE = 'Compass bearings'
-const LESSON_FILE = '0001-compass-bearings.html'
-
-const STEPS = [
-  'Point the direction-of-travel arrow at the landmark.',
-  'Rotate the bezel until the orienting arrow lines up with the needle.',
-  'Read the bearing where the direction-of-travel arrow meets the bezel.',
-]
-
-const body = (
-  <>
-    <Heading level={1}>{LESSON_TITLE}</Heading>
-    <Paragraph lede>
-      A bearing is the compass direction from where you stand to whatever you
-      are aiming at, measured clockwise from north.
-    </Paragraph>
-    <Paragraph>
-      Hold the compass level and let the needle settle before reading anything
-      off it. A bearing taken while walking or tilted reads confidently and
-      wrong.
-    </Paragraph>
-    <Paragraph>
-      Three steps turn a sighted landmark into a number you can act on:
-    </Paragraph>
-    <List ordered items={STEPS} />
-    <Paragraph>
-      The same three steps run in reverse turn a bearing on a map into a
-      direction to walk, which is the only reason to learn them in this order.
-    </Paragraph>
-  </>
-)
-
-function page(title: string, main: string): string {
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${title}</title>
-<link rel="stylesheet" href="../assets/course.css">
-</head>
-<body>
-<main class="wide-body">
-${main}
-</main>
-</body>
-</html>
-`
-}
-
-async function main(): Promise<void> {
-  await mkdir(join(FIXTURE_ROOT, 'lessons'), { recursive: true })
-  await mkdir(join(FIXTURE_ROOT, 'assets'), { recursive: true })
-
-  await writeFile(
-    join(FIXTURE_ROOT, 'assets', 'course.css'),
-    buildDesignCss(undefined, {
-      embedFonts: TEACH_FONT_FACES,
-      components: TEACH_STYLESHEET_COMPONENTS,
-    }),
-  )
-
-  await writeFile(
-    join(FIXTURE_ROOT, 'lessons', LESSON_FILE),
-    page(LESSON_TITLE, render(body)),
-  )
-}
-
-await main()