@erclx/canon 4.99.0 → 4.100.0

package/README.md

@@ -1,6 +1,9 @@
 <div align="center">
 
-<img src="assets/brand/mark-accent.svg" alt="canon" width="56" height="56">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-accent.svg">
+  <img src="assets/brand/mark-accent-light.svg" alt="canon" width="56" height="56">
+</picture>
 
 # canon
 
@@ -14,7 +17,10 @@ canon is a CLI and Claude Code plugin that stops your AI conventions drifting ap
 
 </div>
 
-![The first screen of the canon landing page, a project before and after one canon init, with the file counts each step lays down](assets/evidence/arrival.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/arrival.png">
+  <img src="assets/evidence/arrival-light.png" alt="The first screen of the canon landing page, a project before and after one canon init, with the file counts each step lays down">
+</picture>
 
 The page is one real session the toolkit ran on itself, and every count on it is read from the repo when the page builds.
 
@@ -39,7 +45,10 @@ claude plugin marketplace add https://github.com/erclx/canon
 claude plugin install canon@canon
 ```
 
-![Adding the canon marketplace and installing the plugin in Claude Code](assets/evidence/install.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
+  <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
+</picture>
 
 The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
 
@@ -67,15 +76,24 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
 | Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
 
-![The canon catalog as a ledger of five rows, with the count each ships and a few real names: skills, rules, standards, commands, and stacks](assets/evidence/catalog.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/catalog.png">
+  <img src="assets/evidence/catalog-light.png" alt="The canon catalog as a ledger of five rows, with the count each ships and a few real names: skills, rules, standards, commands, and stacks">
+</picture>
 
 Every count in that image is read from the catalogs when it is built, so they're what the repo ships today. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one. Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
 Two of the outputs are documents you open rather than files you run. A `SLIDES.md` renders to a deck, and a learning workspace renders to a small site.
 
-![A slide from the showcase deck rendered by canon slides render, a bulleted list under a heading on a dark warm background](examples/slides/evidence/showcase-dark-04.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="examples/slides/evidence/showcase-dark-04.png">
+  <img src="examples/slides/evidence/showcase-light-04.png" alt="A slide from the showcase deck rendered by canon slides render, a bulleted list under a heading on a warm background">
+</picture>
 
-![The learning workspace listing rendered by canon teach, three workspaces with their lesson and term counts, one still a stub](examples/teach/evidence/root-listing.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="examples/teach/evidence/root-listing.png">
+  <img src="examples/teach/evidence/root-listing-light.png" alt="The learning workspace listing rendered by canon teach, three workspaces with their lesson and term counts, one still a stub">
+</picture>
 
 ## It runs on itself
 

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

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

package/docs/agents/capture.md

@@ -18,9 +18,13 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds three sources and the template each is written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the three sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+A capture set here spans two folders. `assets/captures/` holds five sources and the three templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
 
-Two of the three take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
+Two of the three templates take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
+
+The README shows each still in two themes through `<picture>`, so a frame is a pair named `<name>` and `<name>-light`. `catalog` and `install` take the light half from the same template, which `regen-hero.sh` fills a second time with the plain color roles pointed at the light ones, and each half is its own capture set with its own stamp. `arrival-light.png` is the same `.fold` capture of the same address taken without forcing dark, so it is retaken by hand alongside `arrival.png`, and nothing catches one drifting from the other.
+
+A stamp for a URL source digests the address string rather than the page it served, so two themes of one address carry one `source-sha256` and only `image-sha256` tells the frames apart. That holds for `examples/teach/evidence/root-listing-light.png`, which is retaken by serving a copy of the fixture with `data-theme="light"` on its `<html>` element at the same address, since the page follows the dark default and the command takes no scheme.
 
 `assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.99.0",
+  "version": "4.100.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -15,6 +15,10 @@
 # component half is left out on purpose: it is a scrollbar and a status marker,
 # and a static capture frame renders neither.
 #
+# A frame a README shows in both themes fills once more against the light roles
+# and writes `<name>-light.html` beside the dark one, so each theme is its own
+# capture set with its own stamp.
+#
 # 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
@@ -393,9 +397,38 @@ if (templates.length === 0) {
   process.exit(1)
 }
 
-for (const template of templates) {
+// The frames a README serves in both themes. The emitter already carries a
+// `--color-light-*` role beside each `--color-*` one, so the light frame is the
+// same template with the plain roles pointed at the light ones rather than a
+// second copy of any hex value. The hero is a landing-page frame no README
+// shows, so it stays dark.
+const LIGHT_TEMPLATES = new Set(["catalog.html.tmpl", "install.html.tmpl"])
+
+const lightRoles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map((match) => match[1])
+if (lightRoles.length === 0) {
+  console.error("regen-hero: token css carries no --color-light-* roles, refusing to write a light frame")
+  process.exit(1)
+}
+const lightTokenCss = [
+  tokenCss,
+  "",
+  "      :root {",
+  ...lightRoles.map((role) => `        --color-${role}: var(--color-light-${role});`),
+  "        --frame-shadow: rgb(0 0 0 / 16%);",
+  "      }",
+].join("\n")
+
+const frames = templates.flatMap((template) => {
+  const base = template.replace(/\.html\.tmpl$/, "")
+  const dark = { template, out: `${base}.html`, tokens: tokenCss }
+  return LIGHT_TEMPLATES.has(template)
+    ? [dark, { template, out: `${base}-light.html`, tokens: lightTokenCss }]
+    : [dark]
+})
+
+for (const { template, out, tokens } of frames) {
   let html = await Bun.file(ASSET_DIR + "/" + template).text()
-  for (const [key, value] of Object.entries(values)) {
+  for (const [key, value] of Object.entries({ ...values, TOKENS: tokens })) {
     html = html.replaceAll(`{{${key}}}`, value)
   }
 
@@ -405,6 +438,6 @@ for (const template of templates) {
     process.exit(1)
   }
 
-  await Bun.write(ASSET_DIR + "/" + template.replace(/\.tmpl$/, ""), html)
+  await Bun.write(ASSET_DIR + "/" + out, html)
 }
 '

package/tooling/web/configs/e2e/screenshot.ts

@@ -3,6 +3,12 @@ import { chromium } from '@playwright/test'
 import { mkdir } from 'fs/promises'
 import path from 'path'
 
+/** One addressable part of a route, captured beside the whole-page frame. */
+interface CaptureSection {
+  name: string
+  selector: string
+}
+
 interface CaptureCase {
   section: string
   theme: string
@@ -10,9 +16,35 @@ interface CaptureCase {
   width: number
   height: number
   evidence?: boolean
+  sections?: CaptureSection[]
   setup?: (page: Page) => Promise<void>
 }
 
+/**
+ * The landing page's own beats, top to bottom. Every entry is a section a
+ * reviewer reads on its own, so a diff lands on the part that moved rather
+ * than on one image of the whole page.
+ */
+const HOME_SECTIONS: CaptureSection[] = [
+  { name: 'top', selector: '#top' },
+  { name: 'proof', selector: '#proof' },
+  { name: 'ask', selector: '#ask' },
+  { name: 'rules', selector: '#rules' },
+  { name: 'skills', selector: '#skills' },
+  { name: 'plan', selector: '#plan' },
+  { name: 'dispatch', selector: '#dispatch' },
+  { name: 'workers', selector: '#workers' },
+  { name: 'gate', selector: '#gate' },
+  { name: 'memory', selector: '#memory' },
+  { name: 'evidence', selector: '#evidence' },
+  { name: 'loop', selector: '#loop' },
+  { name: 'merge', selector: '#merge' },
+  { name: 'provenance', selector: '#provenance' },
+  { name: 'start', selector: '#start' },
+  { name: 'field', selector: '#field' },
+  { name: 'close', selector: '#close' },
+]
+
 const CASES: CaptureCase[] = [
   {
     section: 'home',
@@ -21,6 +53,7 @@ const CASES: CaptureCase[] = [
     width: 1280,
     height: 800,
     evidence: true,
+    sections: HOME_SECTIONS,
   },
   {
     section: 'home',
@@ -28,6 +61,7 @@ const CASES: CaptureCase[] = [
     route: '/',
     width: 1280,
     height: 800,
+    sections: HOME_SECTIONS,
     setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
   },
 ]
@@ -53,6 +87,108 @@ try {
 
 const OUT_DIR = path.join('screenshots', hostname)
 
+/** Every wait on a lazy load is bounded explicitly. */
+const SETTLE_TIMEOUT = 15_000
+
+/** Marks the chrome a section frame drops, set on the page and read by the screenshot's own stylesheet. */
+const FLOATING_ATTRIBUTE = 'data-capture-floating'
+
+/**
+ * Brings the page to the state a reader arrives at, before anything is shot.
+ * A figure gated on an IntersectionObserver and a frame marked `loading=lazy`
+ * both stay at their start state until something scrolls past them, and a full
+ * page capture scrolls nothing, so each named section is scrolled into view
+ * once and the page then returns to the top. Fonts, images and frames settle
+ * afterwards, since the scroll is what starts the lazy loads.
+ */
+async function settle(
+  page: Page,
+  label: string,
+  sections: readonly CaptureSection[],
+): Promise<CaptureSection[]> {
+  const present: CaptureSection[] = []
+  for (const section of sections) {
+    const element = page.locator(section.selector)
+    // Read the count before scrolling, since a selector matching nothing
+    // otherwise costs the default timeout once per section. A miss is
+    // reported and skipped rather than raised, because `CASES` is a template
+    // a project rewrites and a target that syncs this file before editing its
+    // own list would otherwise capture nothing at all. The project owning the
+    // selectors is the one that tests them, which is what the section spec
+    // beside its own page does.
+    if ((await element.count()) === 0) {
+      console.warn(
+        `${label}: no element matches ${section.selector}, named as section "${section.name}". Skipped.`,
+      )
+      continue
+    }
+    present.push(section)
+    await element.scrollIntoViewIfNeeded()
+  }
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await page.evaluate(() => document.fonts.ready.then(() => undefined))
+  // Settle on what the scroll started rather than on a second `networkidle`,
+  // which is a lifecycle event of the navigation and does not re-arm for a
+  // load a scroll triggered afterwards.
+  await page.waitForFunction(
+    () => {
+      if (document.readyState !== 'complete') return false
+      for (const image of document.images) if (!image.complete) return false
+      for (const frame of document.querySelectorAll('iframe')) {
+        try {
+          const inner = frame.contentDocument
+          if (inner !== null && inner.readyState !== 'complete') return false
+        } catch {
+          // Cross-origin, so there is no readyState to read and nothing here
+          // can wait on it.
+        }
+      }
+      return true
+    },
+    undefined,
+    { timeout: SETTLE_TIMEOUT },
+  )
+  return present
+}
+
+/**
+ * Marks every element the page floats over its own content, which is chrome
+ * such as a sticky bar or a fixed dialog. A section taller than the viewport
+ * is scrolled into view to be shot, and the chrome rides that scroll into the
+ * middle of the frame, painting over the part the frame exists to show. The
+ * mark is an attribute rather than a style, so the rule that acts on it is
+ * carried by the screenshot itself and no state is left behind to restore.
+ *
+ * Marking costs the whole-page frame nothing, since that one is shot before
+ * this runs and carries the chrome where a reader meets it.
+ */
+async function markFloatingChrome(page: Page) {
+  await page.evaluate((attribute) => {
+    for (const node of document.querySelectorAll('body *')) {
+      const { position } = getComputedStyle(node)
+      if (position === 'sticky' || position === 'fixed') {
+        node.setAttribute(attribute, '')
+      }
+    }
+  }, FLOATING_ATTRIBUTE)
+}
+
+async function shoot(page: Page, dir: string, file: string, selector?: string) {
+  await mkdir(dir, { recursive: true })
+  const target = path.join(dir, file)
+  if (selector === undefined) {
+    await page.screenshot({ path: target, fullPage: true })
+  } else {
+    // Floating chrome keeps the space it already occupies, so dropping it out
+    // of its own layer moves nothing and leaves every box the size it was.
+    await page.locator(selector).screenshot({
+      path: target,
+      style: `[${FLOATING_ATTRIBUTE}] { position: static !important; }`,
+    })
+  }
+  console.log(`captured ${target}`)
+}
+
 const browser = await chromium.launch()
 const consoleErrors: string[] = []
 let ranCases = 0
@@ -63,6 +199,10 @@ for (const captureCase of CASES) {
   ranCases++
   const context = await browser.newContext({
     viewport: { width: captureCase.width, height: captureCase.height },
+    // A page honoring the preference lands its own motion at the end state,
+    // which is what a still frame has to show. Playwright reads it as a
+    // context option, so it reaches no page written beside `viewport` above.
+    reducedMotion: 'reduce',
   })
   const page = await context.newPage()
 
@@ -81,19 +221,23 @@ for (const captureCase of CASES) {
   await page.goto(`${BASE_URL}${captureCase.route}`)
   await page.waitForLoadState('networkidle')
 
-  const sectionDir = path.join(OUT_DIR, captureCase.section)
-  await mkdir(sectionDir, { recursive: true })
+  const label = `${captureCase.section}/${captureCase.theme}`
+  const sections = await settle(page, label, captureCase.sections ?? [])
+
+  const sweepDir = path.join(OUT_DIR, captureCase.section)
+  const evidenceDir = path.join('evidence', captureCase.section)
+  const file = `${captureCase.theme}.png`
+
+  await shoot(page, sweepDir, file)
+  if (captureCase.evidence) await shoot(page, evidenceDir, file)
 
-  const file = path.join(sectionDir, `${captureCase.theme}.png`)
-  await page.screenshot({ path: file, fullPage: true })
-  console.log(`captured ${file}`)
+  if (sections.length > 0) await markFloatingChrome(page)
 
-  if (captureCase.evidence) {
-    const evidenceDir = path.join('evidence', captureCase.section)
-    await mkdir(evidenceDir, { recursive: true })
-    const evidenceFile = path.join(evidenceDir, `${captureCase.theme}.png`)
-    await page.screenshot({ path: evidenceFile, fullPage: true })
-    console.log(`captured ${evidenceFile}`)
+  for (const { name, selector } of sections) {
+    await shoot(page, path.join(sweepDir, name), file, selector)
+    if (captureCase.evidence) {
+      await shoot(page, path.join(evidenceDir, name), file, selector)
+    }
   }
 
   await context.close()

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
+- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<theme>.png` where the case is flagged. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -112,7 +112,7 @@ Append rows:
 
 `governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
 
-The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there.
+The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there. A case naming sections commits a folder per section under that baseline rather than one file per theme, which is what lets a pull request comparison land on the part of the page that moved instead of on one image of the whole of it. The count is the section list times the themes, so a list is worth sizing against how many frames each later change has to regenerate and a reviewer has to read.
 
 ## Gitignore (extend)