@erclx/canon 4.7.0 → 4.8.0

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

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

package/docs/agents/capture.md

@@ -1,28 +1,30 @@
 ---
 title: Capture
-description: Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+description: Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 ---
 
 # Capture
 
-`canon capture [source]` renders HTML capture sources to PNG, which is how a committed documentation image regenerates from its committed source. 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 bare command.
+`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.
 
 ```bash
-canon capture
-canon capture assets/install.html
-canon capture assets --out .canon/review/captures
+canon capture --selector .window
+canon capture assets/install.html --selector .window
+canon capture assets --selector .window --out .canon/review/captures
 ```
 
-`assets/` now holds two sources, so a bare `canon capture` rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference.
+`--selector` is required and every example above passes it. The element a capture crops to belongs to the page, not to the command, so there is no value that could be right for an arbitrary project's markup. `.window` is what this repository's own two sources declare, and a project renders its own pages by naming whatever theirs declare.
 
-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/hero.html` when the check reports the HTML changed.
+`assets/` here holds two sources, so one run over the folder rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference.
+
+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/hero.html --selector .window` 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. Nothing hand-edits it, and 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.
 
 | Option             | Behavior                                          |
 | ------------------ | ------------------------------------------------- |
 | `--out <dir>`      | Write every PNG here instead of beside its source |
-| `--selector <sel>` | Element to capture (default: `.window`)           |
+| `--selector <sel>` | Element to capture, required and never defaulted  |
 
 ## What the command asserts
 
@@ -30,8 +32,12 @@ Each source renders at `deviceScaleFactor` 2 with a transparent background, and
 
 What is asserted is the font. The command reads the first family the captured element declares and fails when the browser did not resolve it, because a fallback face rewraps the block and silently changes the output. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
 
-The browser binary installs separately from the package. A fresh clone runs `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
+A run refuses before it reads anything else when `--selector` is absent, naming the flag and pointing at `--help`. Ordering it first is what keeps the message about the invocation: the source defaults to `assets`, so checking that first would answer `assets not found` from whatever directory the caller happened to be in and say nothing about the flag that was actually missing.
+
+The browser binary installs separately from the package. A first run does `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
+
+The command ships to targets, alongside `demo`, `inventory`, and `drive`. It was held back while its only caller was this repository regenerating its own committed images, which described the caller rather than the render. A project has generated pages of its own, and the command that would show them rendering and prove their fonts resolved was the one it could not run.
 
-The command is toolkit-only. Its render module holds every browser reference capture makes and `files` in `package.json` excludes it, so an installed `canon` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
+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.
 
-`canon demo` is the other browser command and it ships, because the reason capture stays here is that it regenerates images committed to this repository and a target has nothing to regenerate. See `demo.md`.
+`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, where the rest drive a running application.

package/docs/agents/commands.md

@@ -72,11 +72,11 @@ 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 HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
+| `canon capture [source]`      | Render HTML sources 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 upgrade`               | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                 |
 
-`canon serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and 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. 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.
+`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 stylesheet and 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. 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.
 
 A port already in use is the ordinary case rather than a refusal, so it walks forward to the next free one and reports which it took. That is why a caller reads `url` off the `--json` record instead of composing one from the port it asked for. Only contention is walked past. Any other bind failure refuses as `bind-failed` carrying the error's code, rather than being retried twenty times and reported as a range being full, which names a cause nothing checked.
 
@@ -96,7 +96,7 @@ routes = ["/", "/pricing", "/docs"]
 query = "button, a[href], input, select, textarea, [tabindex]"
 ```
 
-`canon drive` is the fourth and ships for the same reason the two before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
+`canon drive` is the fourth and ships for the same reason the three before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
 
 ## Domain commands
 

package/docs/agents/demo.md

@@ -75,7 +75,7 @@ Every refusal exits 1 and names its reason in the `--json` record, so a skill br
 
 ## The browser reaches every target
 
-Unlike `canon capture`, this command ships. Capture is toolkit-only because it regenerates images committed to this repository, and that reason does not transfer to a command whose whole purpose is running in someone else's project.
+This command was the first browser command to ship, and `canon capture` has since joined it. Capture was held back because its only caller was this repository regenerating its own committed images, which was a fact about that caller rather than about the render.
 
 The cost is stated rather than hidden: the browser binary installs separately, so a target runs `bunx playwright install chromium` once before a recording works at all. A run that cannot launch reports that command inside the frame and exits 1.
 

package/docs/agents/driver.md

@@ -49,7 +49,7 @@ Every step names what it did, and that name is carried onto each finding it prod
 
 Probes run after a step and never on arrival, so a run reaches the load state by opening with a `wait` step of its own, as the example above does. Nothing probes before the first step runs, which makes that leading step the only way to measure the page as it first painted, and naming it is what puts the load state on its own findings rather than under whatever ran next.
 
-Write one in any project that does not have `canon capture`, which is toolkit-only and renders a single state from a committed source. Where capture runs, it already answers about arrival and a leading `wait` duplicates it. Where it does not, this command is the only thing measuring the page at all, and a run without that step reports every driven state and nothing about the one a visitor sees first.
+Write one wherever no capture runs against the page. `canon capture` renders a single state from a source on disk, so where it runs it already answers about arrival and a leading `wait` duplicates it. Where it does not, this command is the only thing measuring the page at all, and a run without that step reports every driven state and nothing about the one a visitor sees first.
 
 Each height is driven in a context of its own from a fresh navigation, rather than by resizing the page the previous height already drove, since a sweep asks the same question of each height rather than a later question of an already-driven page.
 
@@ -98,6 +98,6 @@ It reports findings and never gates, and the exit code says only whether the dri
 
 An unreachable page refuses rather than returning an empty report, since nothing measured and nothing found read the same to anything counting findings.
 
-The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo` and `inventory` rather than staying toolkit-only like `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, which the package excludes, so the two surfaces move independently.
+The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo`, `inventory`, and `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, so the two surfaces move independently.
 
 See `commands.md` for where this sits among the browser commands, and `capture.md` for the single-state render it adds an axis to.

package/docs/agents/index.md

@@ -9,7 +9,7 @@ category: Agent surface
 CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
-- [Capture](capture.md): Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+- [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary

package/docs/agents/state-scoped-risk.md

@@ -30,7 +30,7 @@ Three root files are read whether or not the field names them, being `package.js
 
 ### What the corpus leaves out
 
-The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, `src/capture/`, and every test file.
+The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, and every test file. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
 
 A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the record's rule that content leaving the repository gates harder than content that stays.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -19,7 +19,6 @@
     "tsconfig.json",
     "!scripts/sandbox",
     "!scripts/eval",
-    "!src/capture",
     "!**/*.test.ts"
   ],
   "publishConfig": {

package/scripts/core/regen-hero.sh

@@ -4,15 +4,18 @@
 # 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
-# image with `canon capture assets/hero.html` after this script reports a change.
+# image with `canon capture assets/hero.html --selector .window` after this
+# script reports a change. 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 two sources declare.
 # That capture also writes assets/hero.stamp, which records the digest of the
 # markup it rendered and is what the Hero stage compares, so all three files
 # commit together. The frame carries no version. `package.json` is bumped on main by the release
 # tooling, so embedding it drifts every open branch on the next release and the
 # stage then fails for work that touched nothing.
 #
-# Clone-only. `src/capture` is excluded from the published tarball, and this
-# script reads the repository's own catalogs, so a registry install has neither.
+# Clone-only. `canon capture` ships now, but this script reads the repository's
+# own catalogs, which a registry install does not carry.
 set -e
 set -o pipefail
 

package/src/capture/render.ts

@@ -0,0 +1,166 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { chromium } from 'playwright-core'
+import type { Browser, Page } from 'playwright-core'
+import type { CaptureSource } from '@/capture/sources'
+import { primaryFontFamily, resolveCaptureSources } from '@/capture/sources'
+import { formatStamp, hashSource, stampPath } from '@/capture/stamp'
+
+/**
+ * Every browser reference the capture command makes lives in this module, and
+ * `src/commands/capture.ts` reaches it through a dynamic import so `src/cli.ts`
+ * never resolves the engine at startup.
+ *
+ * It ships, like `@/demo/drive`, `@/inventory/walk`, and `@/driver/drive`.
+ * Regenerating this repository's own committed images was the reason it stayed
+ * behind, and it was a reason about one caller rather than about the mechanism:
+ * a target renders its own generated pages and proves its own fonts resolved,
+ * which is the whole of what this module does.
+ *
+ * It imports `playwright-core` rather than `@playwright/test` for the same
+ * reason the three siblings do. The test runner is a development dependency the
+ * published tarball never carries, so the earlier import resolved here and
+ * threw `ERR_MODULE_NOT_FOUND` in every target install.
+ */
+
+const DEVICE_SCALE_FACTOR = 2
+const FONT_PROBE_SIZE = 72
+const FONT_PROBE_TEXT = 'canon capture 0123456789'
+const ABSENT_FAMILY = '__canon_absent_family__'
+
+export interface CaptureOptions {
+  selector: string
+  outDir?: string
+}
+
+export type CaptureResult =
+  | {
+      status: 'rendered'
+      htmlPath: string
+      pngPath: string
+      width: number
+      height: number
+    }
+  | { status: 'failed'; htmlPath: string; reason: string }
+
+export async function captureSources(
+  sourcePath: string,
+  options: CaptureOptions,
+): Promise<CaptureResult[]> {
+  const sources = resolveCaptureSources(sourcePath, options.outDir)
+  if (!sources.length) return []
+
+  const browser = await chromium.launch()
+  try {
+    return await Promise.all(
+      sources.map((source) => captureOne(browser, source, options.selector)),
+    )
+  } finally {
+    await browser.close()
+  }
+}
+
+/**
+ * Resolves to a failed result rather than throwing, so one source that cannot
+ * render does not drop the rest of the batch.
+ */
+async function captureOne(
+  browser: Browser,
+  source: CaptureSource,
+  selector: string,
+): Promise<CaptureResult> {
+  const page = await browser.newPage({
+    deviceScaleFactor: DEVICE_SCALE_FACTOR,
+  })
+  try {
+    await page.goto(pathToFileURL(source.htmlPath).href)
+    const element = page.locator(selector).first()
+    if ((await element.count()) === 0) {
+      return failed(source, `no element matched ${selector}`)
+    }
+
+    await page.evaluate(() => document.fonts.ready.then(() => undefined))
+    const family = primaryFontFamily(
+      await element.evaluate((node) => getComputedStyle(node).fontFamily),
+    )
+    if (family && !(await resolvesFont(page, family))) {
+      return failed(
+        source,
+        `${family} is not installed, so the capture would rewrap against a fallback`,
+      )
+    }
+
+    mkdirSync(dirname(source.pngPath), { recursive: true })
+    const png = await element.screenshot({ omitBackground: true })
+    writeFileSync(source.pngPath, png)
+    writeStamp(source, png)
+    return {
+      status: 'rendered',
+      htmlPath: source.htmlPath,
+      pngPath: source.pngPath,
+      width: png.readUInt32BE(16),
+      height: png.readUInt32BE(20),
+    }
+  } catch (error) {
+    return failed(
+      source,
+      error instanceof Error ? error.message : String(error),
+    )
+  } finally {
+    await page.close()
+  }
+}
+
+/**
+ * Runs inside the render rather than in a wrapper around it, so a capture
+ * cannot succeed and leave the provenance unrecorded. A throw here reaches the
+ * caller's catch and reports the source as failed, which is correct: a PNG
+ * whose stamp never landed is the state the verify stage exists to reject.
+ *
+ * The source is stored as a bare filename. An absolute path would record the
+ * machine that ran the capture into a tracked file and differ per checkout.
+ *
+ * The image digest is taken over the buffer the screenshot returned rather than
+ * by reading the file back, so the stamp describes the bytes this run wrote.
+ */
+function writeStamp(source: CaptureSource, png: Uint8Array): void {
+  writeFileSync(
+    stampPath(source.pngPath),
+    formatStamp({
+      source: basename(source.htmlPath),
+      sourceSha256: hashSource(readFileSync(source.htmlPath)),
+      imageSha256: hashSource(png),
+    }),
+  )
+}
+
+function failed(source: CaptureSource, reason: string): CaptureResult {
+  return { status: 'failed', htmlPath: source.htmlPath, reason }
+}
+
+/**
+ * Compares the family's text metrics against a family that cannot exist. Equal
+ * widths mean the browser fell through to its default for both, which is the
+ * only signal available: `document.fonts.check` reports every system family as
+ * present, including invented ones.
+ */
+async function resolvesFont(page: Page, family: string): Promise<boolean> {
+  return page.evaluate(
+    ({ family, absent, size, text }) => {
+      const context = document.createElement('canvas').getContext('2d')
+      if (!context) return false
+      const widthOf = (name: string): number => {
+        context.font = `${size}px "${name}"`
+        return context.measureText(text).width
+      }
+      return widthOf(family) !== widthOf(absent)
+    },
+    {
+      family,
+      absent: ABSENT_FAMILY,
+      size: FONT_PROBE_SIZE,
+      text: FONT_PROBE_TEXT,
+    },
+  )
+}

package/src/capture/sources.ts

@@ -0,0 +1,42 @@
+import { readdirSync, statSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+
+export interface CaptureSource {
+  htmlPath: string
+  pngPath: string
+}
+
+/**
+ * Pairs each HTML source with the PNG it renders to. A directory expands to
+ * every `.html` directly inside it, so adding a capture is a file drop rather
+ * than a flag. Omitting `outDir` writes the PNG beside its source.
+ */
+export function resolveCaptureSources(
+  sourcePath: string,
+  outDir?: string,
+): CaptureSource[] {
+  const htmlPaths = statSync(sourcePath).isDirectory()
+    ? readdirSync(sourcePath)
+        .filter((name) => extname(name) === '.html')
+        .sort()
+        .map((name) => join(sourcePath, name))
+    : [sourcePath]
+
+  return htmlPaths.map((htmlPath) => ({
+    htmlPath,
+    pngPath: join(
+      outDir ?? dirname(htmlPath),
+      `${basename(htmlPath, '.html')}.png`,
+    ),
+  }))
+}
+
+/**
+ * Reads the first family from a computed `font-family` value, which is the font
+ * the source asks for and the one a capture has to prove resolved. Quoting is
+ * the source's choice, so both spellings arrive here.
+ */
+export function primaryFontFamily(declaration: string): string {
+  const first = declaration.split(',')[0]?.trim() ?? ''
+  return first.replace(/^['"]|['"]$/g, '')
+}

package/src/capture/stamp.ts

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto'
+import { basename, dirname, extname, join } from 'node:path'
+
+const HASH_ALGORITHM = 'sha256'
+const STAMP_EXTENSION = '.stamp'
+
+/**
+ * Provenance for one rendered PNG: the markup it came from and a digest over
+ * each side of the pair. `assertStampField` in `src/gate/measures.ts` reads both
+ * digests back off the first whitespace-separated token, so the field names, the
+ * colon, and the space after it are a contract between the writer and the gate
+ * rather than formatting.
+ *
+ * Both sides are recorded because either can move alone. The markup digest
+ * catches an edit committed with no capture, and the image digest catches a PNG
+ * replaced under markup that never changed.
+ */
+export interface CaptureStamp {
+  readonly source: string
+  readonly sourceSha256: string
+  readonly imageSha256: string
+}
+
+/**
+ * A capture writes its stamp beside its PNG rather than beside its HTML,
+ * because `--out` moves the image away from the source and the stamp answers a
+ * question about the image.
+ */
+export function stampPath(pngPath: string): string {
+  return join(
+    dirname(pngPath),
+    `${basename(pngPath, extname(pngPath))}${STAMP_EXTENSION}`,
+  )
+}
+
+/**
+ * Digests the whole file rather than the counts inside it. A template edit
+ * changes what the image shows without moving any count, and the whole point of
+ * the stamp is that it needs no knowledge of what the markup renders.
+ */
+export function hashSource(bytes: Uint8Array): string {
+  return createHash(HASH_ALGORITHM).update(bytes).digest('hex')
+}
+
+export function formatStamp(stamp: CaptureStamp): string {
+  return [
+    `source: ${stamp.source}`,
+    `source-sha256: ${stamp.sourceSha256}`,
+    `image-sha256: ${stamp.imageSha256}`,
+    '',
+  ].join('\n')
+}

package/src/cli.ts

@@ -120,7 +120,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon design render`,
     `${GREY}│${NC}    canon slides render`,
     `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/install.html`,
+    `${GREY}│${NC}    canon capture assets/install.html --selector .window`,
     `${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

@@ -1,22 +1,37 @@
 import { existsSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
 import type { Command } from 'commander'
-import { frameError, intro, logError, logInfo, outro, pipeOutput } from '@/ui'
+import {
+  INSTALL_BROWSER,
+  isBrowserMissing,
+  isEngineMissing,
+} from '@/browser/engine'
+import {
+  frameError,
+  intro,
+  logError,
+  logInfo,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
 
 const DEFAULT_SOURCE = 'assets'
-const DEFAULT_SELECTOR = '.window'
 
 /**
- * Both aliases are type queries rather than imports, so `@/capture/render`
- * never appears in this module's runtime import list.
+ * Both aliases are type queries rather than imports, so naming the render
+ * module's types adds no static import of it. The only reference that survives
+ * to runtime is the `import()` inside the action.
  */
 type Renderer = typeof import('@/capture/render')
 type CaptureResult = Awaited<ReturnType<Renderer['captureSources']>>[number]
 
 /**
- * Holds wiring only. Every browser reference sits behind `loadRenderer`,
- * because `src/cli.ts` imports this module at startup and the render module is
- * excluded from the published package.
+ * Holds wiring only. Every browser reference sits behind a dynamic import,
+ * because `src/cli.ts` imports this module at startup and resolving the engine
+ * there would put a browser launch in front of every other command. That is the
+ * same reason `src/commands/demo.ts`, `src/commands/inventory.ts`, and
+ * `src/commands/driver.ts` state for themselves.
  */
 export function register(program: Command): void {
   program
@@ -24,20 +39,27 @@ export function register(program: Command): void {
     .description('Render HTML capture sources to PNG')
     .argument('[source]', 'HTML file or a directory of them', DEFAULT_SOURCE)
     .option('-o, --out <dir>', 'Output directory, defaults beside the source')
-    .option('-s, --selector <selector>', 'Element to capture', DEFAULT_SELECTOR)
+    .option('-s, --selector <selector>', 'Element to capture')
     .action(
       async (
         source: string,
-        opts: { out?: string; selector: string },
+        opts: { out?: string; selector?: string },
       ): Promise<void> => {
-        const renderer = await loadRenderer()
-        if (!renderer) {
+        /**
+         * Refused rather than defaulted, and refused ahead of every other
+         * check, so the message names the invocation rather than whatever the
+         * working directory happens to hold. The element a capture crops to is
+         * a property of the page's own markup, and the class this command used
+         * to assume is declared by two committed sources in one repository.
+         */
+        if (!opts.selector) {
           frameError(
-            'capture is toolkit-only and is absent from an installed canon',
+            '--selector names the element to capture and has no default. See canon capture --help.',
           )
           process.exitCode = 1
           return
         }
+        const selector = opts.selector
 
         const sourcePath = resolve(process.cwd(), source)
         if (!existsSync(sourcePath)) {
@@ -49,8 +71,9 @@ export function register(program: Command): void {
         intro('Capture')
         let results: CaptureResult[]
         try {
+          const renderer = await import('@/capture/render')
           results = await renderer.captureSources(sourcePath, {
-            selector: opts.selector,
+            selector,
             outDir: opts.out ? resolve(process.cwd(), opts.out) : undefined,
           })
         } catch (error) {
@@ -85,16 +108,28 @@ export function register(program: Command): void {
 }
 
 /**
- * Closes an open frame around a failure the render module raised for the whole
- * run rather than for one source, such as a browser binary that is not
- * installed. The engine's own message is readable, so it is passed through
- * intact instead of being summarized.
+ * 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
+ * the step that clears it: an engine package that never resolved, and a browser
+ * binary that was never downloaded. Every other failure passes through intact,
+ * since the engine's own message is readable and summarizing it loses what it
+ * said.
  */
 function reportInFrame(error: unknown): void {
+  if (isEngineMissing(error)) {
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    return
+  }
+
   const message = error instanceof Error ? error.message : String(error)
   const [first, ...rest] = message.split('\n')
   logError(first ?? 'capture failed')
   if (rest.length) pipeOutput(rest.join('\n'))
+  if (isBrowserMissing(error)) {
+    logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+  }
   outro()
 }
 
@@ -107,27 +142,3 @@ function displayPath(path: string): string {
   const fromCwd = relative(process.cwd(), path)
   return fromCwd.startsWith('..') ? path : fromCwd
 }
-
-/**
- * Reports absence only when the module or its engine cannot be resolved, which
- * is the published-package case. Any other import failure is a defect inside
- * the render module and propagates, rather than being reported as a feature
- * the package left out.
- */
-async function loadRenderer(): Promise<Renderer | undefined> {
-  try {
-    return await import('@/capture/render')
-  } catch (error) {
-    if (isModuleNotFound(error)) return undefined
-    throw error
-  }
-}
-
-function isModuleNotFound(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    error.code === 'ERR_MODULE_NOT_FOUND'
-  )
-}

package/src/demo/drive.ts

@@ -20,15 +20,12 @@ declare global {
  * the demo feature adds lives here, and `src/commands/demo.ts` reaches it
  * through a dynamic import so no other command resolves the engine at startup.
  *
- * Unlike `@/capture/render`, this module ships. The capture command is excluded
- * from the published package because it regenerates images committed to this
- * repository, and that reason does not transfer to a command whose whole
- * purpose is running in someone else's project.
- *
  * It imports `playwright-core` rather than `@playwright/test`, which stays a
- * development dependency for the capture module. Shipping puts the import in
- * every target's dependency tree, and a target needs the driver rather than a
- * test runner and an assertion library. Both are pinned to one version rather
+ * development dependency the published tarball never carries. Shipping puts the
+ * import in every target's dependency tree, and a target needs the driver
+ * rather than a test runner and an assertion library. Every browser module here
+ * takes the same import for that reason, `@/capture/render` included since it
+ * started shipping too. Both are pinned to one version rather
  * than a range, because `bunx playwright install chromium` fetches the browser
  * revision the installed engine expects and a float would leave a target
  * resolving a binary its engine cannot launch.

package/src/driver/drive.ts

@@ -23,19 +23,18 @@ import type {
  * `src/commands/driver.ts` reaches it through a dynamic import so no other
  * command resolves the engine at startup.
  *
- * Like `@/demo/drive` and `@/inventory/walk`, and unlike `@/capture/render`,
- * this module ships. A command whose whole purpose is measuring someone else's
- * page cannot stay toolkit-only, and nothing here reaches into `@/capture/`,
- * which `files` in `package.json` excludes from the published package, so the
- * two surfaces move independently.
+ * Like `@/demo/drive`, `@/inventory/walk`, and `@/capture/render`, this module
+ * ships. A command whose whole purpose is measuring someone else's page cannot
+ * stay toolkit-only, and nothing here reaches into `@/capture/`, so the two
+ * surfaces move independently.
  *
  * What separates it from `canon capture` is the axis it adds. A render answers
  * about a page as it loads, and every defect that exists only after a menu
  * opens, an answer is chosen, or the page scrolls is invisible to one. Probes
  * therefore run after a step rather than on arrival, and a run reaches the load
- * state by opening with a `wait` step of its own. That matters most where
- * capture does not run, since it is toolkit-only and this command is then the
- * only thing measuring the page at all.
+ * state by opening with a `wait` step of its own. That matters most where no
+ * capture runs against the page, since this command is then the only thing
+ * measuring it at all.
  */
 
 /** Each probe keyed by the name a caller writes in the run. */

package/src/gate/measures.ts

@@ -100,7 +100,7 @@ export const SANDBOX_UNDECLARED_CEILING = 47
 export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
 export const HERO_STAMP_FAILURE =
-  'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html and commit all three files together.'
+  'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html --selector .window and commit all three files together.'
 
 function parseJson(payload: string): unknown {
   try {

package/src/gate/stages.ts

@@ -189,7 +189,7 @@ export const STAGES: readonly Stage[] = [
         kind: 'drift',
         pathspec: 'assets/hero.html',
         failure:
-          'Hero counts drifted. Run bun run check, then canon capture assets/hero.html, and commit assets/hero.html with assets/hero.png and assets/hero.stamp.',
+          'Hero counts drifted. Run bun run check, then canon capture assets/hero.html --selector .window, and commit assets/hero.html with assets/hero.png and assets/hero.stamp.',
       },
       { kind: 'measure', measure: heroStamp },
     ],

package/src/inventory/walk.ts

@@ -15,9 +15,9 @@ import type { Subject } from '@/inventory/subjects'
  * and `src/commands/inventory.ts` reaches it through a dynamic import so no
  * other command resolves the engine at startup.
  *
- * Like `@/demo/drive` and unlike `@/capture/render`, this module ships, because
- * a command whose whole purpose is running inside someone else's project cannot
- * stay toolkit-only.
+ * Like `@/demo/drive`, `@/driver/drive`, and `@/capture/render`, this module
+ * ships, because a command whose whole purpose is running inside someone else's
+ * project cannot stay toolkit-only.
  */
 
 /**