@erclx/canon 5.19.0 → 5.20.0

package/governance/rules/{canon/640-architecture.md → standards/architecture.md}

@@ -1,5 +1,6 @@
 ---
-description: Route canon/ARCHITECTURE.md edits to the architecture standard for system decisions and risks
+# Generated by `canon gov regen` from standards/architecture.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/ARCHITECTURE.md
 paths:
   - 'canon/ARCHITECTURE.md'
   - '.claude/ARCHITECTURE.md'
@@ -9,5 +10,5 @@ paths:
 
 ## Authority
 
-- Follow the architecture standard for the overview, named decision entries, and risks. It is the single source. Read it with `canon standards architecture`.
+- Follow the architecture standard for shape and content rules for canon/ARCHITECTURE.md. It is the single source. Read it with `canon standards architecture`.
 - Add a decision here only when it fills one of the standard's slots, and write any other decision into the context entry for the domain it constrains. At the record's stated cap, merge or retire an entry before adding one.

package/governance/rules/standards/context.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/context.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/context/<domain>.md entries
+paths:
+  - 'canon/context/**'
+  - '.claude/context/**'
+---
+
+# Context entry standards
+
+## Authority
+
+- Follow the context standard for shape and content rules for canon/context/<domain>.md entries. It is the single source. Read it with `canon standards context`.
+- Before non-trivial work in a domain, read its `canon/context/<domain>.md` entry. Use `canon/context/index.md` to find it.
+- Leave the entry conforming when work in its domain changes what it describes.

package/governance/rules/standards/design.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/design.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/DESIGN.md
+paths:
+  - 'canon/DESIGN.md'
+  - '.claude/DESIGN.md'
+---
+
+# Design standards
+
+## Authority
+
+- Follow the design standard for shape and content rules for canon/DESIGN.md. It is the single source. Read it with `canon standards design`.

package/governance/rules/standards/diagrams.md

@@ -0,0 +1,17 @@
+---
+# Generated by `canon gov regen` from standards/diagrams.md. Edit that frontmatter, not this file.
+description: Shape and content rules for .canon/diagrams/<kind>.md files
+paths:
+  - '.canon/diagrams/**'
+  - '.claude/DIAGRAMS.md'
+---
+
+# Diagram standards
+
+## Authority
+
+- Follow the diagrams standard for shape and content rules for .canon/diagrams/<kind>.md files. It is the single source. Read it with `canon standards diagrams`.
+- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. The mermaid standard routes them.
+- A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
+- Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
+- Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it

package/governance/rules/standards/groundwork.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/groundwork.md. Edit that frontmatter, not this file.
+description: Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+paths:
+  - '.canon/groundwork/**'
+---
+
+# Groundwork standards
+
+## Authority
+
+- Follow the groundwork standard for folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track. It is the single source. Read it with `canon standards groundwork`.
+- Follow the groundwork spikes standard for `08-spikes.md` and the folders holding what a spike produced. Read it with `canon standards groundwork-spikes`.

package/governance/rules/standards/intake.md

@@ -0,0 +1,12 @@
+---
+# Generated by `canon gov regen` from standards/intake.md. Edit that frontmatter, not this file.
+description: Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
+paths:
+  - '.canon/intake/**'
+---
+
+# Intake standards
+
+## Authority
+
+- Follow the intake standard for folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval. It is the single source. Read it with `canon standards intake`.

package/governance/rules/standards/markdown.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/markdown.md. Edit that frontmatter, not this file.
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
+paths:
+  - '**/*.md'
+---
+
+# Markdown standards
+
+## Authority
+
+- Follow the markdown standard for headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording. It is the single source. Read it with `canon standards markdown`.
+- Read it before a substantial markdown edit. Do not work the banned characters from memory.
+- Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+- Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.

package/governance/rules/standards/memory.md

@@ -0,0 +1,12 @@
+---
+# Generated by `canon gov regen` from standards/memory.md. Edit that frontmatter, not this file.
+description: Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+paths:
+  - '.canon/memory/**'
+---
+
+# Memory standards
+
+## Authority
+
+- Follow the memory standard for filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire. It is the single source. Read it with `canon standards memory`.

package/governance/rules/standards/mermaid.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/mermaid.md. Edit that frontmatter, not this file.
+description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
+paths:
+  - '**/*.md'
+---
+
+# Mermaid standards
+
+## Authority
+
+- Follow the mermaid standard for direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram. It is the single source. Read it with `canon standards mermaid`.
+- Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.
+- Read it before drafting the fence. Do not work the layout or the budgets from memory.
+- Which diagram a document carries and what question it answers is a separate topic. The diagrams standard routes it.

package/governance/rules/{canon/658-plan.md → standards/plan.md}

@@ -1,22 +1,18 @@
 ---
-description: Route .canon/plans/ edits to the plan standard for sections, the answer contract, and the archive move
+# Generated by `canon gov regen` from standards/plan.md. Edit that frontmatter, not this file.
+description: Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
 paths:
   - '.canon/plans/**'
 ---
 
 # Plan standards
 
-## The answer contract
+## Authority
 
+- Follow the plan standard for filename and slug, the required sections, and the suggested-and-answer contract for a feature plan. It is the single source. Read it with `canon standards plan`.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.
 - Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.
 - Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`.
-
-## Archiving
-
 - Move a shipped plan to `.canon/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
-
-## Authority
-
-- Follow the plan standard for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source. Read it with `canon standards plan`.
+- Follow the plan lifecycle standard for when a plan is written, how it is amended, and its move to the archive. Read it with `canon standards plan-lifecycle`.

package/governance/rules/standards/readme.md

@@ -0,0 +1,12 @@
+---
+# Generated by `canon gov regen` from standards/readme.md. Edit that frontmatter, not this file.
+description: Readme voice, structure, and content conventions
+paths:
+  - '**/README.md'
+---
+
+# Readme standards
+
+## Authority
+
+- Follow the readme standard for readme voice, structure, and content conventions. It is the single source. Read it with `canon standards readme`.

package/governance/rules/standards/ready.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/ready.md. Edit that frontmatter, not this file.
+description: Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
+paths:
+  - '.canon/ready/**'
+---
+
+# Ready standards
+
+## Authority
+
+- Follow the ready standard for folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff. It is the single source. Read it with `canon standards ready`.
+- Load the `canon:draft-ready` skill to write a ready folder, its overview, the thin plan, and the task row. It owns the procedure. Report it rather than proceeding silently when it does not resolve, since it ships with the plugin and this rule ships with the CLI.

package/governance/rules/standards/requirements.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/requirements.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/REQUIREMENTS.md
+paths:
+  - 'canon/REQUIREMENTS.md'
+  - '.claude/REQUIREMENTS.md'
+---
+
+# Requirements standards
+
+## Authority
+
+- Follow the requirements standard for shape and content rules for canon/REQUIREMENTS.md. It is the single source. Read it with `canon standards requirements`.

package/governance/rules/standards/rule.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/rule.md. Edit that frontmatter, not this file.
+description: Rule frontmatter, body shape, and voice for .claude/rules files
+paths:
+  - '.claude/rules/**/*.md'
+---
+
+# Governance rule standards
+
+## Authority
+
+- Follow the rule standard for rule frontmatter, body shape, and voice for .claude/rules files. It is the single source. Read it with `canon standards rule`.
+- Read it before writing or editing a rule. Do not work the shape from memory.

package/governance/rules/standards/session.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/session.md. Edit that frontmatter, not this file.
+description: Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+paths:
+  - '.canon/tasks/session-*.md'
+---
+
+# Session map standards
+
+## Authority
+
+- Follow the session standard for filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it. It is the single source. Read it with `canon standards session`.
+- Follow this rule rather than the tasks rule for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.

package/governance/rules/{claude/570-skill.md → standards/skill.md}

@@ -1,5 +1,6 @@
 ---
-description: Route skill edits to the authoring standard and the requirement consult-first workflow
+# Generated by `canon gov regen` from standards/skill.md. Edit that frontmatter, not this file.
+description: Skill structure and authoring rules for Claude Code
 paths:
   - '.claude/skills/**/SKILL.md'
   - 'claude/skills/**/SKILL.md'
@@ -7,19 +8,14 @@ paths:
   - 'claude/skills/**/REQUIREMENT.md'
 ---
 
-# Skill standards
+# Claude skill standards
 
-## Before editing
+## Authority
 
+- Follow the skill standard for skill structure and authoring rules for Claude Code. It is the single source. Read it with `canon standards skill`.
 - Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
 - Report it rather than proceeding silently when `canon:create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
-
-## After editing
-
 - Re-read a skill body this session edited before invoking that skill again in the same session
 - Do not read a resolved file path in a held body as evidence the body is current
-
-## Authority
-
-- Follow the skill standard for skill structure, frontmatter fields, and invocation rules. It is the single source. Read it with `canon standards skill`.
 - Follow the skill requirement standard for the shape a `REQUIREMENT.md` states. Read it with `canon standards skill-requirement`.
+- Follow the skill path standard for which root a path in a body resolves against and how a body cites a standard. Read it with `canon standards skill-paths`.

package/governance/rules/standards/standard.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/standard.md. Edit that frontmatter, not this file.
+description: Shape and content rules for authoring a standard
+paths:
+  - 'standards/**/*.md'
+---
+
+# Standard standards
+
+## Authority
+
+- Follow the standard standard for shape and content rules for authoring a standard. It is the single source. Read it with `canon standards standard`.
+- Read it before writing or editing a standard. Do not work the shape from memory.

package/governance/rules/standards/tasks.md

@@ -0,0 +1,15 @@
+---
+# Generated by `canon gov regen` from standards/tasks.md. Edit that frontmatter, not this file.
+description: Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
+paths:
+  - '.canon/tasks/**'
+---
+
+# Tasks standards
+
+## Authority
+
+- Follow the tasks standard for folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/. It is the single source. Read it with `canon standards tasks`.
+- Follow the board standard for `priority.md` and `backlog.md`, their readiness groups, and row order. Read it with `canon standards board`.
+- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.
+- Follow the task decline standard for a task decided against. Read it with `canon standards tasks-decline`.

package/governance/rules/{canon/661-teach.md → standards/teach.md}

@@ -1,5 +1,6 @@
 ---
-description: Route .canon/teach/ edits to the teach standard for layout, ordinal naming, and the mission and record formats, in the projects that open a learning workspace
+# Generated by `canon gov regen` from standards/teach.md. Edit that frontmatter, not this file.
+description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 paths:
   - '.canon/teach/**'
 ---
@@ -8,6 +9,6 @@ paths:
 
 ## Authority
 
-- Follow the teach standard for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source. Read it with `canon standards teach`.
+- Follow the teach standard for workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace. It is the single source. Read it with `canon standards teach`.
 - Follow the glossary standard for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it with `canon standards glossary`.
 - Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/governance/rules/standards/wiki.md

@@ -0,0 +1,13 @@
+---
+# Generated by `canon gov regen` from standards/wiki.md. Edit that frontmatter, not this file.
+description: Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
+paths:
+  - 'wiki/**/*.md'
+---
+
+# Wiki standards
+
+## Authority
+
+- Follow the wiki standard for folder split, frontmatter, naming convention, and sourcing for a wiki reference page. It is the single source. Read it with `canon standards wiki`.
+- Read it before drafting a page. Do not work the placement criterion or the naming convention from memory.

package/governance/rules/standards/wireframes.md

@@ -0,0 +1,14 @@
+---
+# Generated by `canon gov regen` from standards/wireframes.md. Edit that frontmatter, not this file.
+description: Shape and content rules for canon/wireframes/<surface>.md files
+paths:
+  - 'canon/wireframes/**'
+  - '.claude/wireframes/**'
+---
+
+# Wireframe standards
+
+## Authority
+
+- Follow the wireframes standard for shape and content rules for canon/wireframes/<surface>.md files. It is the single source. Read it with `canon standards wireframes`.
+- Read it before adding or revising a surface.

package/governance/rules/writing/800-prose.md

@@ -12,4 +12,4 @@ paths:
 - Load it before drafting a passage, not after revising one.
 - Report it rather than proceeding silently when the skill does not resolve.
 - Do not work these rules from memory.
-- Punctuation, formatting, and file references are a separate topic. `801-markdown` routes them.
+- Punctuation, formatting, and file references are a separate topic. The markdown rule routes them.

package/governance/stacks/base.toml

@@ -5,5 +5,7 @@ extends = ""
 # session conduct and `.claude/` authoring rules, `tooling` the dev setup and
 # CI workflow rules, and `writing` the prose and document-shape rules. The
 # `code` group is left to the stacks that write code, so a docs or writing
-# project loads no rule it can never apply.
-rules = ["canon", "claude", "tooling", "writing", "120-bash"]
+# project loads no rule it can never apply. `standards` holds one rule per
+# standard routing its paths to it, generated by `canon gov regen` from each
+# standard's frontmatter rather than authored.
+rules = ["canon", "claude", "standards", "tooling", "writing", "120-bash"]

package/package.json

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

package/src/canvas/capture.ts

@@ -1,6 +1,12 @@
-import { join } from 'node:path'
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import type { CaptureResult } from '@/capture/render'
-import { type ContentRefused, type Frame, readPage } from '@/canvas/content'
+import {
+  type ContentRefused,
+  canvasDir,
+  type Frame,
+  readPage,
+} from '@/canvas/content'
 import {
   type CanvasOptions,
   type CanvasOutcome,
@@ -134,6 +140,34 @@ export async function captureCanvas(
   const early = resolveCaptureTargets(root, spec, '')
   if (!early.ok) return early
 
+  return serveFor(root, deps, async (base, capture) => {
+    const resolved = resolveCaptureTargets(root, spec, base, out)
+    if (!resolved.ok) return resolved
+
+    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 }
+  })
+}
+
+type ServeRefused = {
+  readonly ok: false
+  readonly reason: 'no-server' | 'capture-failed'
+  readonly detail: string
+}
+
+async function serveFor<T>(
+  root: string,
+  deps: CaptureDeps,
+  run: (base: string, capture: CaptureEngine) => Promise<T>,
+): Promise<T | ServeRefused> {
   const start = deps.start ?? startCanvas
   const server = start(root, { port: 0, shell: new Response('') })
   if (!server.ok) {
@@ -145,21 +179,9 @@ export async function captureCanvas(
   }
 
   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 }
+    return await run(server.url, capture)
   } catch (error) {
     return {
       ok: false,
@@ -170,3 +192,194 @@ export async function captureCanvas(
     await server.stop()
   }
 }
+
+/** The element a composite is captured by, holding every frame and no chrome. */
+export const COMPOSITE_SELECTOR = '#canvas-composite'
+
+/**
+ * The container holds no text, so its family exists only for the engine's
+ * font probe, which rejects a family the machine lacks. The browser default is
+ * Times New Roman, which a Linux runner often lacks, and `system-ui` is the one
+ * every platform maps. Each frame keeps its own fonts inside its iframe.
+ */
+const COMPOSITE_FONT = 'system-ui'
+
+export interface Placement {
+  readonly frame: string
+  readonly url: string
+  readonly left: number
+  readonly top: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface Composite {
+  readonly placements: readonly Placement[]
+  readonly width: number
+  readonly height: number
+  readonly html: string
+}
+
+/**
+ * One document showing every frame of a page at its layout position. Offsets
+ * run from the top left of the union of the boxes, so a negative coordinate
+ * never clips and a lone frame fills the container exactly. Each iframe takes
+ * its box, so a document taller than its frame clips as it does on the board,
+ * and frames paint in the order given, which is the board's.
+ */
+export function buildComposite(
+  page: string,
+  frames: readonly Frame[],
+  base: string,
+): Composite {
+  const left = Math.min(...frames.map((frame) => frame.x))
+  const top = Math.min(...frames.map((frame) => frame.y))
+  const right = Math.max(...frames.map((frame) => frame.x + frame.width))
+  const bottom = Math.max(...frames.map((frame) => frame.y + frame.height))
+  const width = right - left
+  const height = bottom - top
+
+  const placements = frames.map((frame) => ({
+    frame: frame.name,
+    url: frameUrl(base, page, frame),
+    left: frame.x - left,
+    top: frame.y - top,
+    width: frame.width,
+    height: frame.height,
+  }))
+
+  const iframes = placements.map(
+    (p) =>
+      `<iframe title="${escapeAttribute(p.frame)}" src="${escapeAttribute(p.url)}" style="left:${p.left}px;top:${p.top}px;width:${p.width}px;height:${p.height}px"></iframe>`,
+  )
+  const html = [
+    '<!doctype html>',
+    '<html><head><meta charset="utf-8">',
+    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative;font-family:${COMPOSITE_FONT}}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
+    '</head><body>',
+    `<div id="canvas-composite" style="width:${width}px;height:${height}px">`,
+    ...iframes,
+    '</div></body></html>',
+    '',
+  ].join('\n')
+
+  return { placements, width, height, html }
+}
+
+function escapeAttribute(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;')
+}
+
+/**
+ * Where the generated document is served from, inside the canvas folder so it
+ * shares the frames' origin. Chromium skips painting a cross-origin iframe
+ * outside the viewport, and the engine's viewport is 720 pixels tall, so a
+ * document on another origin captured every frame below that line blank. A dot
+ * folder is no page name, so the board never lists it.
+ */
+const COMPOSITE_FOLDER = '.composite'
+
+export interface CompositeTarget {
+  readonly page: string
+  readonly composite: Composite
+  readonly htmlPath: string
+  /** The served address of the document at `htmlPath`. */
+  readonly url: string
+  readonly pngPath: string
+}
+
+export type CompositeTargetOutcome =
+  | { readonly ok: true; readonly target: CompositeTarget }
+  | ContentRefused
+
+/**
+ * Turns `<page>` into one composite. `out` is the PNG, and without it the PNG
+ * lands at `<page>.png` beside the per-frame folder of the same name, so the
+ * two captures of one page never collide.
+ */
+export function resolveCompositeTarget(
+  root: string,
+  spec: string,
+  base: string,
+  out?: string,
+): CompositeTargetOutcome {
+  if (spec.includes('/')) {
+    return refuse(
+      'invalid-name',
+      `--composite takes a page, not ${spec}, so capture <page> or drop the flag`,
+    )
+  }
+
+  const page = readPage(root, spec)
+  if (!page) return refuse('no-page', `page ${spec} does not exist`)
+  if (page.frames.length === 0) {
+    return refuse('no-frame', `page ${spec} has no frames`)
+  }
+
+  const file = `${spec}.html`
+  return {
+    ok: true,
+    target: {
+      page: spec,
+      composite: buildComposite(spec, page.frames, base),
+      htmlPath: join(canvasDir(root), COMPOSITE_FOLDER, file),
+      url: `${base}${FRAMES_PREFIX.slice(1)}${COMPOSITE_FOLDER}/${encodeURIComponent(file)}`,
+      pngPath:
+        out ?? join(recordDir(root, 'tmp', 'canvas-capture'), `${spec}.png`),
+    },
+  }
+}
+
+export type CompositeOutcome =
+  | {
+      readonly ok: true
+      readonly composite: {
+        readonly target: CompositeTarget
+        readonly result: CaptureResult
+      }
+    }
+  | ContentRefused
+  | ServeRefused
+
+/**
+ * Captures a page as one PNG through the served canvas, the way `captureCanvas`
+ * captures each frame. The viewport is the container's width, so no frame's
+ * media query resolves against a window narrower than the frame itself. The
+ * page load the engine waits on waits on every iframe.
+ */
+export async function captureComposite(
+  root: string,
+  spec: string,
+  out?: string,
+  deps: CaptureDeps = {},
+): Promise<CompositeOutcome> {
+  const early = resolveCompositeTarget(root, spec, '')
+  if (!early.ok) return early
+
+  return serveFor(root, deps, async (base, capture) => {
+    const resolved = resolveCompositeTarget(root, spec, base, out)
+    if (!resolved.ok) return resolved
+
+    const { target } = resolved
+    mkdirSync(dirname(target.htmlPath), { recursive: true })
+    writeFileSync(target.htmlPath, target.composite.html)
+    let result: CaptureResult | undefined
+    try {
+      ;[result] = await capture(target.url, {
+        selector: COMPOSITE_SELECTOR,
+        width: target.composite.width,
+        outDir: target.pngPath,
+      })
+    } finally {
+      rmSync(target.htmlPath, { force: true })
+    }
+    if (!result) {
+      return {
+        ok: false,
+        reason: 'capture-failed',
+        detail: `the engine rendered nothing for ${spec}`,
+      }
+    }
+    return { ok: true, composite: { target, result } }
+  })
+}