@erclx/canon 4.7.0 → 4.8.1

package/docs/agents/tasks.md

@@ -22,9 +22,13 @@ canon tasks archive --pull-request 673 --json
 | `--json`             | Emit a machine-readable record on stdout                     |
 | `--root <path>`      | Board root, defaulting to the main worktree                  |
 
-Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `plan-unswept`, or `bad-input`.
+Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, or `bad-input`.
 
-`plan-unswept` fires on the last task pointing at a live plan, never on every task pointing at one. The gate counts the other live tasks whose `Plan:` line resolves onto the same file, so a plan several tasks share archives its tasks freely and only the final one is held until `claude-docs` sweeps the plan. Reading the folder alone refused all of them, which deadlocked the board against a sweep correctly declining to move a plan another live task cites.
+The task carries its plan with it. When the closing task is the last live one whose `Plan:` line resolves onto that file, the plan moves to `.canon/plans/archive/` under its own name and the archived task's line is rewritten as `Plan: [feature-<slug>](../../plans/archive/feature-<slug>.md)`, a folder deeper than the live task wrote it. The `plan` field on the success record carries that `from` and `to`, and is `null` when nothing moved.
+
+A plan several tasks share stays where it is, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.
+
+The merge is what settles a plan. `.husky/post-merge` reads the pull request number off the squash subject and calls this verb, so both halves close in one act with nobody naming a file. That is why the move sits inside this verb rather than in a second call the hook would make after it, which could leave the task archived and the plan live.
 
 `bad-input` covers a malformed command line, which all three task verbs answer the same way. It is separate from `ambiguous` and `no-match` because those describe the board, and a caller that passed two selectors would otherwise be sent to repair a task citation that is fine.
 
@@ -53,7 +57,7 @@ The record carries `location`, one of `unstated`, `live`, `archived`, or `outsid
 
 The target resolves against the board folder and against the project root both, so `../plans/x.md` and `.canon/plans/x.md` land on the same file and one plan two tasks spelled differently counts once. Containment is tested at both record roots rather than at the one this tree resolves at, since a line somebody wrote against a root the tree has since left is still a path into the plans folder, and reading it as outside would report a shipped plan as still live. `docs/agents/records.md` states the read order.
 
-`canon tasks archive` gates on this same answer, so a caller wanting the count reads it here rather than scanning the board. The `claude-docs` plans sweep is the exception and still states the rule in its own body, because a plugin skill reaches a target on merge while the CLI reaches one on release, so a sweep calling a verb the installed `canon` predates gets no record back and archives nothing.
+`canon tasks archive` decides its plan move on this same answer, so a caller wanting the count reads it here rather than scanning the board.
 
 Branch on `reason` rather than on the exit code, which is the rule the archive section above already states and which this verb needs for a second reason. An operator's shell profile may wrap `canon` in a function that runs the binary and then another command and takes the second status, which masks every non-zero exit rather than only an absent verb. The binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike, so the record is the only signal that survives the wrapper.
 
@@ -159,7 +163,7 @@ Seven checks run. Plan and Collisions reach one half each of the `## Run now` te
 | Check      | What it reports                                                                                                      |
 | ---------- | -------------------------------------------------------------------------------------------------------------------- |
 | Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed |
-| Plan       | A `## Run now` row whose Plan column carries no link, or one resolving to no file                                    |
+| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line     |
 | Mapping    | A row or backlog line naming no task file, and a task file neither surface names                                     |
 | Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                          |
 | Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits                                  |
@@ -168,6 +172,8 @@ Seven checks run. Plan and Collisions reach one half each of the `## Run now` te
 
 Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
 
+The Plan check reads the row and the task file both, because the two are written by different hands and only the task's own `Plan:` line reaches the archive. A row carrying a plan whose task states none is `plan-uncited`, and a pair naming two different plans is `plan-mismatched`. Both sides resolve against the board and against the project root before they compare, so a row writing `../plans/x.md` and a task writing `.canon/plans/x.md` name one file rather than two.
+
 Mapping spans two surfaces, because a task sits on `priority.md` when it would plausibly be planned soon and on `backlog.md` otherwise. A task file either surface names is accounted for, a file neither names is `row-missing`, and a file both name is `row-duplicated` for the reason a task in two groups is: it claims two things about itself and only one can hold. One check across both is what lets a task move between them without the move reading as a dropped file.
 
 A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name is still reported as reaching neither surface. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.

package/docs/ai-workflow.md

@@ -108,12 +108,10 @@ A person points it at a private repository once and both verbs refuse until they
 
 `canon records size` reports what each of these folders holds, heaviest first, along with `.canon/tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
 
-A plan that ships is archived, never deleted. `canon:claude-docs` moves it to `.canon/plans/archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
+A plan that ships is archived, never deleted. `canon tasks archive` moves it to `.canon/plans/archive/` alongside the task it belonged to and retargets that task's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
 A branch review report takes the other route and is swept rather than archived. `claude-review` writes it to `.canon/review/branch/`, the session addressing it reads it once, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so `claude-docs` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
 
-The plans sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
-
 `canon:claude-docs` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
 
 `.canon/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders.
@@ -126,7 +124,7 @@ Past that shape, it checks what a surviving row claims against what the tree hol
 
 `canon:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.canon/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
-Archiving a task leaves its plan alone, because `canon:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
+Archiving a task carries its plan with it, in the same act. The merge is what settles a plan, and the hook below reaches the archive with nobody watching, so a second call after it would be a second failure point leaving the task archived and the plan live. A task whose plan a sibling still cites archives on its own and leaves the plan live, since moving it on the first task to close strands every other pointer at a path that has gone.
 
 Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `canon:claude-autoship` or `canon:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
 

package/docs/zshrc-aliases.md

@@ -12,6 +12,8 @@ Claude Code auto-discovers the toolkit plugin from `claude/.claude-plugin/plugin
 
 `bun run bootstrap` installs this block. It owns the canonical copy in `scripts/core/bootstrap.sh`, appends it to `~/.zshrc` wrapped in the two marker comments below, and sets `TOOLKIT` to the cloned path. The markers are how a re-run recognizes its own block and skips.
 
+Skipping means a re-run never updates a block already installed, so a shell that ran the bootstrap before the canonical block grew keeps whatever it got that day. To pick up an alias added since, delete the marked block and re-run the bootstrap, or paste the new lines into the block by hand.
+
 A block installed by hand before the managed one has no markers. Bootstrap detects that case through the `alias clp=` line instead, warns, and leaves the block untouched rather than appending a second copy. To switch over, delete the hand-rolled block and re-run the bootstrap.
 
 ```zsh
@@ -27,26 +29,34 @@ alias cls='cl --model sonnet'
 alias clp='claude --plugin-dir $TOOLKIT/claude'
 alias clpc='clp -c'
 alias clps='clp --model sonnet'
+alias clpa='clp agents'
+alias clpac='clpa --cwd .'
 # <<< canon aliases <<<
 ```
 
-The block sits after any `PATH` mutations and the `claude` CLI install. Zsh expands aliases recursively on the first word, so `clr`, `clc`, `clw`, and `cls` inherit their base through `cl`, and `clpc` and `clps` inherit `--plugin-dir` through `clp`. `$TOOLKIT` expands at invocation time, so updating the variable and re-sourcing reroutes all `clp` calls without touching the alias definitions.
+The block sits after any `PATH` mutations and the `claude` CLI install. Zsh expands aliases recursively on the first word, so `clr`, `clc`, `clw`, and `cls` inherit their base through `cl`, and `clpc`, `clps`, and `clpa` inherit `--plugin-dir` through `clp`. `clpac` inherits it one level further, through `clpa`. `$TOOLKIT` expands at invocation time, so updating the variable and re-sourcing reroutes all `clp` calls without touching the alias definitions.
+
+To opt out, delete the block between the two markers. Bootstrap re-adds it on the next run, so skip that step by running `bun install` and `bun link` yourself instead.
 
 ## What each one does
 
-`cl` through `cls` carry no explicit plugin dir. Use them inside the toolkit repository, where Claude Code auto-discovers the plugin from `claude/.claude-plugin/plugin.json`. Loading `--plugin-dir` on top of auto-discovery registers every skill twice and produces duplicate entries in the slash command list.
+`cl`, `clw`, and `cls` carry no explicit plugin dir and start a fresh session. Use them inside the toolkit repository, where Claude Code auto-discovers the plugin from `claude/.claude-plugin/plugin.json`. Loading `--plugin-dir` on top of auto-discovery registers every skill twice and produces duplicate entries in the slash command list.
+
+`clr` and `clc` resume a session rather than launching one, so auto-discovery never fires for them. A resume restores whatever plugin registration the session started with and recomputes nothing, which a bare `claude --resume` demonstrated by holding a stale registration through a full process restart until `--plugin-dir` was passed on the resume itself.
 
 - `cl`: plain session in the current directory
-- `clr`: opens the `/resume` picker scoped to the current directory. Trailing arguments filter by name. `clr auth` limits results to sessions containing "auth".
-- `clc`: jumps straight into the most recent session for the current directory. No picker. Faster than `clr` when the terminal closed and you want back into the same session.
+- `clr`: opens the `/resume` picker scoped to the current directory. Trailing arguments filter by name. `clr auth` limits results to sessions containing "auth". Resuming does not reload the plugin, so reach for `clpc` when the session needs it.
+- `clc`: jumps straight into the most recent session for the current directory. No picker. Faster than `clr` when the terminal closed and you want back into the same session. Resuming does not reload the plugin here either.
 - `clw`: creates a worktree under `.claude/worktrees/<name>/` on a fresh branch and starts a Claude Code session in it. Pass the worktree name as the trailing arg: `clw feat-auth`.
 - `cls`: pins the session to Sonnet instead of the default Opus. Use for routine work where Opus cost is not justified.
 
-`clp`, `clpc`, and `clps` bake in `--plugin-dir`. Use them outside the toolkit repository, where auto-discovery does not fire.
+The `clp` family bakes in `--plugin-dir`. Use it outside the toolkit repository, where auto-discovery does not fire, and for any resume that needs the plugin.
 
 - `clp`: session with the toolkit plugin loaded explicitly
-- `clpc`: jumps straight into the most recent session for the current directory with the plugin loaded. The `clp` mirror of `clc`.
+- `clpc`: jumps straight into the most recent session for the current directory with the plugin loaded. The `clp` mirror of `clc`, and the one resume that carries the plugin.
 - `clps`: `clp` pinned to Sonnet
+- `clpa`: opens the agent view with the plugin loaded, covering background sessions from every directory
+- `clpac`: the same view filtered to background sessions started under the current directory
 
 ## When to use which
 
@@ -58,7 +68,9 @@ Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session w
 
 Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md) for fan-out rules.
 
-Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Outside the toolkit repo, `clpc` is the same shortcut as `clc` with the plugin loaded.
+Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Reach for `clpc` over `clc` wherever the resumed session needs the plugin, inside the toolkit repository as well as outside it, since neither resume re-runs discovery.
+
+Use `clpa` to see what is running across every directory, and `clpac` when only the current project matters.
 
 ## Why not a function
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.7.0",
+  "version": "4.8.1",
   "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/bootstrap.sh

@@ -36,12 +36,16 @@ alias cls='cl --model sonnet'
 alias clp='claude --plugin-dir \$TOOLKIT/claude'
 alias clpc='clp -c'
 alias clps='clp --model sonnet'
+alias clpa='clp agents'
+alias clpac='clpa --cwd .'
 $MARKER_CLOSE
 EOF
 }
 
 install_aliases() {
   log_step "Installing Claude Code shell aliases"
+  log_info "This step manages a marked alias block in $ZSHRC, the only file outside the repo this script writes."
+  log_info "Delete the block and its two marker comments to remove the aliases. Re-running never adds a second copy."
 
   if [ -f "$ZSHRC" ] && grep -qF "$MARKER_OPEN" "$ZSHRC"; then
     log_info "Aliases already present in $ZSHRC, skipping"

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'
-  )
-}