@erclx/canon 5.15.0 → 5.16.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.15.0",
+  "version": "5.16.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/draft-wiki/SKILL.md

@@ -40,7 +40,7 @@ Do not widen the split to admit a subject. Adding a sibling folder is a change t
 The standard forbids working from training knowledge, so the draft is built on a read rather than on recall.
 
 - Fetch current information through the `claude-code-guide` agent for any subject that agent covers. Its answer is the source the page is written from.
-- Reach a subject the agent does not cover through the owner's own published documentation.
+- Reach a subject the agent does not cover through the owner's own published documentation. Invoke `canon:search-craft` with the skill tool before searching for it, since finding the owner's documentation is the field-and-authority step that skill carries, and report it rather than proceeding silently when the skill does not resolve.
 - Say the fetch failed and stop rather than substituting recall. A page sourced from memory is the failure the rule exists to prevent, and it ships looking identical to one that was checked.
 - Close the intro with the `Source:` sentence the standard requires, linking the canonical page where one exists and naming the owner alone where the subject has no single URL.
 - Stamp the read date on a source revised without notice, as `read <date>`. A claim traced to an undated read cannot be checked against what was actually read.

package/claude/skills/plan-groundwork/SKILL.md

@@ -24,7 +24,7 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 - A second exception, for what a spike reads as bulk input: write a large fixture under `.canon/tmp/runs/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`. An arm script and a checkout a claim rests on are not fixtures, and go inside the track under `scripts/` and `clones/`, per the standard.
 - What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
 - A `draft-and-pick` run invoked from inside a live track follows its own branch for this, writing to `evidence/` here rather than `.canon/tmp/<slug>/`.
-- Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
+- Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them. Invoke `canon:search-craft` with the skill tool before an outside search, and report it rather than proceeding silently when the skill does not resolve.
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
 - Treat the folder as gitignored, and backed only where a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there and refuse with `no-remote` otherwise, and neither protects against a compaction dropping this session's own reasoning before anyone has pushed, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
 

package/claude/skills/search-craft/REQUIREMENT.md

@@ -0,0 +1,57 @@
+---
+name: search-craft
+description: Why a session needs a thinking step before an outside search, deriving where a field's authorities live rather than taking the top-ranked result, and why that step is a method rather than a catalog of sites
+---
+
+# Search craft requirement
+
+## Gap
+
+Without this skill, a session reaching outside the project runs one generic `WebSearch` and takes what ranks highest. Nothing in the toolkit says how to search, and the two procedures that require an outside source, `plan-groundwork` and `draft-wiki`, give no route to one.
+
+The miss is measured. On 2026-10-02 two queries ran twice each with identical text, once open and once with `allowed_domains` set to authorities the session derived itself with no list to consult.
+
+- `css container queries browser support`: 1 of 9 open results came from MDN, and that one was a blog post rather than the reference page. The rest were third-party pages, three of them thin guides. Scoped to MDN, web.dev, and caniuse, 10 of 10 results were primary sources.
+- The two summaries disagreed on a fact. The open one said Firefox shipped style queries in version 128, and the scoped one, reading caniuse, said 151. A direct fetch of the caniuse table returned 151, so a session that searched once would have reported the wrong version.
+- `effect of minimum wage increase on employment evidence`: the open set mixed journals with advocacy groups and its summary leaned one way. Scoped to five authorities the session named, being a research bureau's working papers, the economists' professional association, a working-paper index, a policy institute, and a legislature's budget office, 7 of 9 results were working papers or official analysis, and the summary carried both the near-zero and the negative estimates.
+- 2 of the 9 scoped economics results came from a domain outside the allow list, so the filter is not strict.
+
+The authorities in both pairs were named by the session unprompted once it was asked to, which is the argument for a method over a list. Two queries at one run each show the effect exists and do not size it.
+
+Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit refused its JSON search with a 403 and refused `WebFetch`, while its RSS feed answered 200. X redirected `curl` to a login page and returned 402 to `WebFetch`, so no free route reaches it.
+
+## Must
+
+- Name the field, or two, before a query is written
+- Derive the field's authorities from the kind of body it trusts, and search for who they are first when unsure
+- Run the query scoped to those authorities and open beside it, prefer the scoped result on a conflict, and say in the output that the two disagreed
+- Use the open result for practitioner write-ups and news the authorities do not publish
+- Warn that the domain filter is not strict, so a scoped result has its domain checked before it is cited
+- Prefer a public API over a fetched and summarized page where one exists, since the API returns the dates, authors, and identifiers a citation needs
+- Carry a dated access note grown only from a failure a session hit, and stop to ask the operator before any paid or logged-in route
+- Close with the practice skill's excuses, red flags, and closing checklist, answering "the model already knows the good sites" and "one search was enough"
+- Be loaded from the sourcing steps of `plan-groundwork` and `draft-wiki`, each reporting when the skill does not resolve
+
+## Must not
+
+- Name a site as the destination for a category of question. An example authority appears only inside the method as an illustration of deriving one, marked as such. A line reading "for economics, use X" is the catalog the operator ruled out and a reviewer reads against this line.
+- Ship code. Access code a session needs repeatedly becomes a `canon` verb, never a script in the skill.
+- Restate citation format, which belongs to the surface writing the citation
+- Suggest scraping behind a login or a paywall
+
+## Out of scope
+
+- The form a citation takes: the procedure or standard writing it
+- A Claude Code subject: the `claude-code-guide` agent, which `draft-wiki` already routes to
+- Image generation, which makes a picture rather than finding a source
+- Loading on every web search rather than on a research-shaped request: a hook matching `WebSearch`, planned on its own
+- Whether a session already scopes searches without the skill, which only a run on a fresh research request without it would show
+
+## Measured
+
+2026-10-03, one Sonnet run of the toolkit's own sandbox scenario for this skill, a housing brief asking for linked notes and a prompt for the strongest evidence on whether rent control reduces housing supply. The skill sat in the project's skill folder and the run was allowed the skill, search, and fetch tools.
+
+- No `Skill` call fired, so the description did not route a plain research request to the body.
+- The run searched four times with no domain filter, naming authors and journals from recall, then fetched the papers' own pages. It never named the field, so the scenario's field pattern failed and the arm went red on one of its assertions.
+
+The arm shows the trigger is the gap rather than the body: a session that never loads the skill cannot follow it. The pointers from `plan-groundwork` and `draft-wiki` reach only those procedures, and the hook matching `WebSearch` is the route for every other search. One run on one model shows the miss exists and does not size it.

package/claude/skills/search-craft/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: search-craft
+description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is the `claude-code-guide` agent, or to generate an image, which is not search.
+---
+
+# Search craft
+
+A session reaching outside the project tends to run one generic search and take whatever ranks highest. Ranking rewards pages written to rank, so a field's thin "complete guide" pages and its advocates crowd out its reference material, and one search gives nothing to check a wrong fact against. This skill carries the step before the search: work out where the field's authoritative material lives, search there, and search openly beside it.
+
+The procedure that loaded this skill owns what the result is for and where it is written. Nothing here formats a citation or decides what a finding means.
+
+## Name the field
+
+- Name the field the question sits in before writing a query. Name two when the question straddles them, such as a pricing question that is both law and economics.
+- Name it at the level a practitioner would, being the discipline that argues about the answer, rather than the topic word in the question.
+- Say the field in the output, so a reader can tell a wrong answer from a search run in the wrong place.
+
+## Derive who the field trusts
+
+- Ask what kind of body the field treats as settling a question, then name the bodies of that kind. The kinds recur across fields:
+  - the standards body or specification that defines the thing
+  - the reference documentation its practitioners cite
+  - the peer-reviewed papers and working papers of its professional society
+  - the official statistics office or regulator that publishes the numbers
+  - the project's own repository, changelog, or issue tracker, for a piece of software
+- Derive the names. Never reach for a remembered list of sites per category, since a list rots with nobody noticing and the field's own kind of authority is what the derivation tests.
+- Search for the authorities first when unsure who they are, such as asking where the field's practitioners publish or what its practitioners cite, and scope the real search only after that answer is read.
+- As an illustration of deriving, not a list to reuse: a question on a browser feature's support sits in web platform engineering, whose authorities are the specification, the reference docs practitioners cite, and the compatibility tables built from browser releases. Each new question derives its own.
+
+## Search twice
+
+- Run the same query twice: once scoped to the derived authorities through `WebSearch`'s `allowed_domains`, and once open.
+- Prefer the scoped result when the two disagree on a fact, and say in the output that they disagreed and which one was kept. Never pick one silently.
+- Use the open result for what the authorities do not publish: practitioner write-ups, field reports, and news.
+- Check the domain of every scoped result before citing it. The filter is not strict, and a scoped run can return results from outside its list.
+- Fetch the authority's page itself to confirm a fact both searches summarized differently, since a search summary is a paraphrase and can carry the error.
+
+## Prefer a structured source
+
+- Prefer a source's public API over a fetched and summarized HTML page where one exists. An API returns the dates, authors, and identifiers a citation needs, and a summary of the page can drop or blur them.
+- Reach the API with a plain request when it needs no key, rather than writing a wrapper for one search.
+
+## Access note
+
+Each line is a claim measured once, and `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` records the date under its Gap. Sites change their blocking without notice, so re-check a line before relying on it. Add a line only for a failure a session actually hit, and record the date it hit in the requirement beside it.
+
+- Reddit answers its RSS feed and refuses its JSON search with a 403. `WebFetch` is refused for the site.
+- X answers nothing without paying or a login. `curl` redirects to a login page and `WebFetch` returns 402.
+- Stop and ask the operator before any route that pays, logs in, or works around a refusal. Never suggest scraping behind a login.
+
+## Excuses and rebuttals
+
+| Excuse                                   | Rebuttal                                                                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| The model already knows the good sites   | It does, and it does not use that knowledge unprompted. Left to rank, a search puts guides written to rank above a field's reference pages. |
+| One search was enough                    | One search gives nothing to check a wrong fact against. The scoped search is what catches the open summary's error.                         |
+| The open results look authoritative      | Ranking rewards pages written to rank, so advocates and thin guides sit beside the field's own record and tilt the summary.                 |
+| I scoped it, so every result is in scope | The domain filter is not strict, so a scoped search can return results from outside its list.                                               |
+| The summary already answers it           | A summary paraphrases. Fetch the page when two summaries disagree, since that is where the error sits.                                      |
+
+## Red flags
+
+- You are about to write a query and have not named the field.
+- Every source you are about to cite came from one open search.
+- You named an authority because it is a site you remember, not because it is the kind of body the field trusts.
+- The scoped and open results disagree and the output does not say so.
+- You are citing a scoped result whose domain you have not checked.
+- You are about to pay, log in, or scrape to reach a source and have not asked the operator.
+
+## Before handing over
+
+- The output names the field, or both fields, the question was searched in.
+- Every authority searched was derived from the kind of body the field trusts.
+- The query ran scoped and open, and every disagreement between them is stated with the side kept.
+- Every cited source's domain was checked, and a fact the summaries disagreed on was confirmed on the page itself.
+- No paid, logged-in, or scraped route was taken without the operator's answer.
+
+## What this delegates
+
+- The form a citation takes: the surface writing it, such as the standard the procedure writes to
+- A Claude Code subject: the `claude-code-guide` agent, which `draft-wiki` routes to
+- Generating an image: whatever draws the surface, since making one is not search
+- Access code a session needs repeatedly: a `canon` verb, never a script in this skill

package/docs/agents/canvas.md

@@ -0,0 +1,36 @@
+---
+title: Canvas
+description: The canvas server, its content format, and the verbs that list, arrange, select, and capture frames
+---
+
+# Canvas
+
+`canon canvas` serves a local canvas of pages and HTML frames and gives an agent the verbs the operator's mouse has. A page is a folder under `.canon/canvas/`, a frame is one HTML file in it, and `layout.json` beside them holds each frame's box.
+
+## Serve
+
+`canvas serve` serves the canvas on `127.0.0.1`, walks ports like `canon serve`, refuses a `Host` other than loopback on its own port, and runs until interrupted. Each frame gets the project's token stylesheet injected, being this toolkit's tokens in its own checkout, else `.claude/design/base.css` plus anything under `.claude/design/project/`, else none with a notice. An open canvas reloads a frame whose file changes.
+
+The write routes the shell posts to also refuse a request carrying an `Origin` other than the server's own, and a body that is not JSON.
+
+## List and add
+
+`canvas list --json` emits every page with its frames. `page add`, `page rename`, and `frame add` (`--width`, `--height`) each emit one record under `--json`, refusing a name that is not one path segment, a page that already exists, or a root that is not a directory, with the reason on stderr.
+
+## Arrange and select
+
+`frame move <page> <name> --x <px> --y <px>` rewrites one frame's position in `layout.json` and keeps its size. An omitted axis stays where the frame is. It refuses a frame or page that does not exist and a layout that does not parse.
+
+The shell writes through the same writer when the operator drags a frame. Both take a lock file beside the layout, read it, merge their change, and replace it, so a drag released while a verb writes loses neither position. A writer that cannot get the lock within two seconds refuses with reason `busy`.
+
+`canvas selection --json` emits `{ ok, selection }` with the page, frame, file, box, and path of the frame the operator selected, or `selection: null` when nothing is selected or the selected frame has since been removed. Read it when the operator says "this one".
+
+The operator can also pick one element inside a frame, by clicking it on the surface or in the frame's layers tree. The selection then carries `element`, recording the `index` in document order, `tag`, `classes`, and `text` excerpt as they were at the pick. An edit to the frame since can shift that index onto another element, so `stale` turns true once the file's content no longer matches what the pick was made against. Check it before acting on the index.
+
+A pick is refused as `address-mismatch` when the browser builds elements the file never states, such as a `tbody` a table leaves out or the document wrapper around a fragment. The shell sends its own element count beside the index, so a frame the two sides count differently is reported rather than recorded against the wrong element. A pick is refused as `stale-address` when the frame file changed between the frame being served and the pick arriving, since every served frame carries the hash of its file and the shell sends that hash back.
+
+## Capture
+
+`canvas capture <page>/<frame>` renders one frame as a PNG, and `canvas capture <page>` renders every frame on the page. Each goes through a server started for the call, so the injected tokens are in the image, and renders at the frame's own width from the layout, so a media query resolves there. It never captures the file on disk.
+
+`--out` is the PNG for a frame and a folder for a page, defaulting to session scratch. `--json` emits `{ ok, captures }` with the path and pixel size of each frame. Each PNG is the frame's whole document, so its height follows the document and not the frame's box. The font check `canon capture` makes applies, so a frame naming a font the machine lacks fails with that reason. A refused capture reports `no-page` or `no-frame` for a target that does not exist, `no-server` when the server for the call cannot start, and `capture-failed` for an error the engine throws, such as a browser that will not launch.

package/docs/agents/commands.md

@@ -34,7 +34,7 @@ One row per top-level command, in the order `canon --help` prints them. A domain
 | `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                   |
 | `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)           |
 | `canon teach <verb>`        | Open and author learning workspaces                                             |
-| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, and add pages and frames to it   |
+| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange them, and capture them   |
 | `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                      |
 | `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive              |
 | `canon intake <verb>`       | Report intake folders and write answers into them                               |
@@ -96,7 +96,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `demo`, in `demo.md`: `compile`, `run`, `frames`
 - `inventory`, described above: `run`
 - `teach`, in `teach.md`: `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`
-- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`
+- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `selection`, `capture`
 - `sandbox`, in `sandbox.md`: `reset`, `clean`, `check`, `coverage`
 - `tasks`, in `tasks.md`: `next-label`, `archive`, `decline`, `plan-citations`, `plan-answers`, `plan-branch`, `plan-reach`, `plan-link`, `pull-request`, `outcome`, `list`, `validate`
 - `intake`, in `intake.md`: `list`, `answer`
@@ -129,7 +129,7 @@ Subcommands no other page describes:
 - `claude skills rank` scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
 - `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
-- `canvas serve` serves the canvas on `127.0.0.1`, walks ports like `canon serve`, refuses a `Host` other than loopback on its own port, and runs until interrupted. A page is a folder under `.canon/canvas/`, a frame is one HTML file in it, and `layout.json` beside them holds each frame's box. Each frame gets the project's token stylesheet injected, being this toolkit's tokens in its own checkout, else `.claude/design/base.css` plus anything under `.claude/design/project/`, else none with a notice. An open canvas reloads a frame whose file changes. `canvas list --json` emits every page with its frames, and `page add`, `page rename`, and `frame add` (`--width`, `--height`) each emit one record under `--json`, refusing a name that is not one path segment, a page that already exists, or a root that is not a directory, with the reason on stderr.
+- `canvas`, with its verbs, content format, and write routes, is described in `canvas.md`.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
 - `repo metadata propose` compares a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing, and `repo metadata apply` writes an explicitly supplied set through `gh repo edit` (`--description`, `--homepage`, `--topics`).
 

package/docs/agents/index.md

@@ -10,6 +10,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 
 - [Architecture record](architecture-record.md): The five findings canon context audit reads off the architecture record, being the entry cap, revisit sentence, and length gates the record states for itself, the claim coverage report, and the word counts
 - [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
+- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, select, and capture frames
 - [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 top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report

package/docs/workflow/skill-map.md

@@ -50,6 +50,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:deprecation-migration` | When deleting or replacing code something may still call, to migrate its callers and prove none remain     |
 | `canon:code-craft`            | Before writing a function, class, or module, to pick the shape the next change needs                       |
 | `canon:review-craft`          | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:search-craft`          | Before searching outside the project, to derive where the field's authorities publish and search there too |
 | `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
 | `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
 | `canon:ui-checklist`          | After a UI change, to write what to look at and name what ships untested                                   |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.15.0",
+  "version": "5.16.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/lib/sandbox-git.sh

@@ -43,7 +43,7 @@ resolve_sandbox_git_identity() {
   SANDBOX_GIT_NAME="${SANDBOX_GIT_NAME:-$(git config --global user.name 2>/dev/null || true)}"
   SANDBOX_GIT_EMAIL="${SANDBOX_GIT_EMAIL:-$(git config --global user.email 2>/dev/null || true)}"
 
-  : "${SANDBOX_GIT_NAME:=aitk-sandbox}"
+  : "${SANDBOX_GIT_NAME:=canon-sandbox}"
   : "${SANDBOX_GIT_EMAIL:=sandbox@example.com}"
 
   export SANDBOX_GIT_NAME SANDBOX_GIT_EMAIL
@@ -57,7 +57,7 @@ configure_sandbox_git_identity() {
 
 # Every scenario that needs a remote points at the same throwaway repository, so
 # the name lives here rather than in each one.
-SANDBOX_ANCHOR_REPO="aitk-sandbox"
+SANDBOX_ANCHOR_REPO="canon-sandbox"
 
 # A scenario calls this from its own use_anchor hook rather than this file
 # defining the hook. manage-sandbox.sh keys off `type -t use_anchor`, so

package/src/canvas/address.ts

@@ -0,0 +1,184 @@
+/**
+ * The element address: a frame plus the element's index in document order.
+ * The shell counts it over the frame's parsed DOM and the server counts it over
+ * the file through `HTMLRewriter`, so the two have to count the same elements.
+ * This module imports nothing, which keeps it bundling into the shell, and the
+ * server half reaches `HTMLRewriter` as a Bun global only when called.
+ */
+
+/** Marks the token stylesheet the server injects, which the file never holds. */
+export const TOKENS_ATTRIBUTE = 'data-canvas-tokens'
+
+/** On that same element, the hash of the file the frame was served from. */
+export const HASH_ATTRIBUTE = 'data-canvas-hash'
+
+const EXCERPT_LENGTH = 80
+
+/** Elements whose content is raw text, which a browser never parses as markup. */
+const RAW_TEXT = new Set(['script', 'style', 'template', 'textarea', 'title'])
+
+export interface ElementAddress {
+  readonly index: number
+  readonly tag: string
+  /**
+   * Every element the shell counted. A browser implies elements the file never
+   * states, such as a `tbody` or the document wrapper, and each one shifts the
+   * count, so a total that differs from the server's is what exposes it.
+   */
+  readonly count: number
+  /**
+   * The served file's hash, so the server can refuse a pick made against a
+   * version of the frame the file has since moved past.
+   */
+  readonly hash?: string
+}
+
+export interface SourceElement {
+  readonly tag: string
+  readonly classes: readonly string[]
+  readonly text: string
+}
+
+export type AddressCheck =
+  | { readonly ok: true; readonly element: SourceElement }
+  | {
+      readonly ok: false
+      readonly reason: 'address-mismatch'
+      readonly detail: string
+    }
+
+export function excerpt(text: string): string {
+  return text.replace(/\s+/g, ' ').trim().slice(0, EXCERPT_LENGTH)
+}
+
+export function documentElements(doc: Document): Element[] {
+  return [...doc.querySelectorAll('*')].filter(
+    (element) => !element.hasAttribute(TOKENS_ATTRIBUTE),
+  )
+}
+
+export function addressOf(
+  doc: Document,
+  element: Element,
+): ElementAddress | undefined {
+  const all = documentElements(doc)
+  const index = all.indexOf(element)
+  if (index === -1) return undefined
+  const address = {
+    index,
+    tag: element.tagName.toLowerCase(),
+    count: all.length,
+  }
+  const hash = doc
+    .querySelector(`[${TOKENS_ATTRIBUTE}]`)
+    ?.getAttribute(HASH_ATTRIBUTE)
+  return hash ? { ...address, hash } : address
+}
+
+/** The element an address names, or nothing once the tag there differs. */
+export function elementAt(
+  doc: Document,
+  address: Pick<ElementAddress, 'index' | 'tag'>,
+): Element | undefined {
+  const element = documentElements(doc)[address.index]
+  return element?.tagName.toLowerCase() === address.tag ? element : undefined
+}
+
+interface Collected {
+  readonly tag: string
+  readonly classes: readonly string[]
+  text: string
+}
+
+/**
+ * Every element the file states, in document order. Text is gathered into
+ * each open element, which an element closed only by implication keeps open to
+ * the end, so its excerpt can run past where a browser would end it.
+ */
+export function sourceElements(html: string): SourceElement[] {
+  const elements: Collected[] = []
+  const open: number[] = []
+  let rawDepth = 0
+  /* A template's content is a fragment `querySelectorAll` never reaches. */
+  let templateDepth = 0
+
+  const appendText = (text: string) => {
+    for (const index of open) {
+      const element = elements[index]
+      if (element && element.text.length < EXCERPT_LENGTH * 4) {
+        element.text += text
+      }
+    }
+  }
+
+  new HTMLRewriter()
+    .on('*', {
+      element(element) {
+        const tag = element.tagName.toLowerCase()
+        if (templateDepth > 0) {
+          if (tag === 'template') {
+            templateDepth += 1
+            element.onEndTag(() => {
+              templateDepth -= 1
+            })
+          }
+          return
+        }
+        const index = elements.length
+        /* A tag boundary separates words the way a rendered block would. */
+        appendText(' ')
+        elements.push({
+          tag,
+          classes: (element.getAttribute('class') ?? '')
+            .split(/\s+/)
+            .filter(Boolean),
+          text: '',
+        })
+        if (!element.canHaveContent || element.selfClosing) return
+        const isRaw = RAW_TEXT.has(tag)
+        const isTemplate = tag === 'template'
+        open.push(index)
+        if (isRaw) rawDepth += 1
+        if (isTemplate) templateDepth += 1
+        element.onEndTag(() => {
+          const at = open.lastIndexOf(index)
+          if (at !== -1) open.splice(at, 1)
+          if (isRaw) rawDepth -= 1
+          if (isTemplate) templateDepth -= 1
+          appendText(' ')
+        })
+      },
+    })
+    .onDocument({
+      text(chunk) {
+        if (rawDepth === 0) appendText(chunk.text)
+      },
+    })
+    .transform(html)
+
+  return elements.map(({ tag, classes, text }) => ({
+    tag,
+    classes,
+    text: excerpt(text),
+  }))
+}
+
+/**
+ * Finds the element the shell addressed in the file, and refuses when the two
+ * counts disagree rather than naming whatever sits at that index on disk.
+ */
+export function resolveAddress(
+  html: string,
+  address: ElementAddress,
+): AddressCheck {
+  const elements = sourceElements(html)
+  const element = elements[address.index]
+  if (elements.length !== address.count || element?.tag !== address.tag) {
+    return {
+      ok: false,
+      reason: 'address-mismatch',
+      detail: `the browser counted ${address.count} elements and the file states ${elements.length}, so element ${address.index} cannot be matched`,
+    }
+  }
+  return { ok: true, element }
+}

package/src/canvas/capture.ts

@@ -0,0 +1,172 @@
+import { join } from 'node:path'
+import type { CaptureResult } from '@/capture/render'
+import { type ContentRefused, type Frame, readPage } from '@/canvas/content'
+import {
+  type CanvasOptions,
+  type CanvasOutcome,
+  FRAMES_PREFIX,
+  startCanvas,
+} from '@/canvas/server'
+import { recordDir } from '@/record-root'
+
+/**
+ * The element a frame is captured by. The document rather than its body, so a
+ * frame that paints its background on the root is not cropped to the body's
+ * box.
+ */
+export const CAPTURE_SELECTOR = 'html'
+
+export interface CaptureTarget {
+  readonly page: string
+  readonly frame: string
+  /** The served address, which is what carries the injected tokens. */
+  readonly url: string
+  /** The viewport width, so a media query resolves at the frame's own width. */
+  readonly width: number
+  readonly pngPath: string
+}
+
+export type TargetsOutcome =
+  | { readonly ok: true; readonly targets: readonly CaptureTarget[] }
+  | ContentRefused
+
+function refuse(
+  reason: ContentRefused['reason'],
+  detail: string,
+): ContentRefused {
+  return { ok: false, reason, detail }
+}
+
+function frameUrl(base: string, page: string, frame: Frame): string {
+  return `${base}${FRAMES_PREFIX.slice(1)}${encodeURIComponent(page)}/${encodeURIComponent(frame.file)}`
+}
+
+/**
+ * Turns `<page>` or `<page>/<frame>` into what to capture. Every target is a
+ * served address, never the file on disk, so a capture can only show what the
+ * canvas shows. The width comes from the layout and not from the window, so a
+ * frame narrower than its own breakpoint renders its narrow layout.
+ *
+ * `out` is the PNG for a frame and a folder for a page, the way a URL source
+ * reads `--out` in `canon capture`.
+ */
+export function resolveCaptureTargets(
+  root: string,
+  spec: string,
+  base: string,
+  out?: string,
+): TargetsOutcome {
+  const [pageName, frameName, ...extra] = spec.split('/')
+  if (!pageName || extra.length > 0 || frameName === '') {
+    return refuse('invalid-name', `${spec} is not <page> or <page>/<frame>`)
+  }
+
+  const page = readPage(root, pageName)
+  if (!page) return refuse('no-page', `page ${pageName} does not exist`)
+
+  const frames =
+    frameName === undefined
+      ? page.frames
+      : page.frames.filter((frame) => frame.name === frameName)
+  if (frames.length === 0) {
+    return frameName === undefined
+      ? refuse('no-frame', `page ${pageName} has no frames`)
+      : refuse('no-frame', `frame ${frameName} does not exist on ${pageName}`)
+  }
+
+  const scratch = recordDir(root, 'tmp', 'canvas-capture', pageName)
+  return {
+    ok: true,
+    targets: frames.map((frame) => ({
+      page: pageName,
+      frame: frame.name,
+      url: frameUrl(base, pageName, frame),
+      width: frame.width,
+      pngPath:
+        frameName !== undefined && out !== undefined
+          ? out
+          : join(out ?? scratch, `${frame.name}.png`),
+    })),
+  }
+}
+
+export type CaptureOutcome =
+  | {
+      readonly ok: true
+      readonly captures: readonly {
+        readonly target: CaptureTarget
+        readonly result: CaptureResult
+      }[]
+    }
+  | ContentRefused
+  | {
+      readonly ok: false
+      readonly reason: 'no-server' | 'capture-failed'
+      readonly detail: string
+    }
+
+type CaptureEngine = (typeof import('@/capture/render'))['captureSources']
+
+/** What a test stands in for, which the command never passes. */
+export interface CaptureDeps {
+  readonly start?: (root: string, options: CanvasOptions) => CanvasOutcome
+  readonly capture?: CaptureEngine
+}
+
+/**
+ * Serves the canvas for the length of the call and captures through it, so the
+ * run needs no `canon canvas serve` and still never reads the raw file. The
+ * port is whatever is free, which keeps it clear of a canvas already running.
+ * An error the engine throws, such as a browser that will not launch, comes
+ * back as `capture-failed` rather than escaping, so a caller reading the record
+ * can tell it from a root that is wrong.
+ */
+export async function captureCanvas(
+  root: string,
+  spec: string,
+  out?: string,
+  deps: CaptureDeps = {},
+): Promise<CaptureOutcome> {
+  /*
+   * Refused before the server starts, since starting it creates the canvas
+   * folder and a refused capture should leave the project as it found it.
+   */
+  const early = resolveCaptureTargets(root, spec, '')
+  if (!early.ok) return early
+
+  const start = deps.start ?? startCanvas
+  const server = start(root, { port: 0, shell: new Response('') })
+  if (!server.ok) {
+    return {
+      ok: false,
+      reason: 'no-server',
+      detail: `${server.detail}, so run canon canvas serve and capture again`,
+    }
+  }
+
+  try {
+    const resolved = resolveCaptureTargets(root, spec, server.url, out)
+    if (!resolved.ok) return resolved
+
+    const capture =
+      deps.capture ?? (await import('@/capture/render')).captureSources
+    const captures: { target: CaptureTarget; result: CaptureResult }[] = []
+    for (const target of resolved.targets) {
+      const [result] = await capture(target.url, {
+        selector: CAPTURE_SELECTOR,
+        width: target.width,
+        outDir: target.pngPath,
+      })
+      if (result) captures.push({ target, result })
+    }
+    return { ok: true, captures }
+  } catch (error) {
+    return {
+      ok: false,
+      reason: 'capture-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  } finally {
+    await server.stop()
+  }
+}