@erclx/canon 4.92.0 → 4.94.0

package/governance/rules/lib/305-e2e-reliability.md

@@ -1,8 +1,7 @@
 ---
 description: Enforce settled waits and falsifiable guards in end-to-end tests
 paths:
-  - 'e2e/*.ts'
-  - 'e2e/**/*.ts'
+  - '**/e2e/**/*.ts'
 ---
 
 # End-to-end reliability standards
@@ -14,6 +13,8 @@ paths:
 - Bound every settle with an explicit timeout.
 - Do not raise a timeout to clear a failure that reproduces under load. Replace the wait with a settle.
 - Do not read a value once after a pause. Poll it.
+- Settle a smooth scroll on the `scrollend` event. Fall back to a stillness window only when the target was already in view.
+- Run with motion reduced unless the test asserts motion, and opt back in per test.
 
 ## Falsifiable guards
 

package/governance/rules/lib/306-test-scope.md

@@ -1,8 +1,7 @@
 ---
 description: Enforce which specs and which engines an end-to-end run covers at each point in the loop
 paths:
-  - 'e2e/*.ts'
-  - 'e2e/**/*.ts'
+  - '**/e2e/**/*.ts'
 ---
 
 # Test scope standards

package/governance/rules/lib/330-testing-py.md

@@ -8,6 +8,10 @@ paths:
 
 # Python testing tooling
 
+## Layer
+
+- Load the `canon:test-craft` skill to pick the layer a test belongs at before choosing the tooling below, and report it rather than proceeding silently when the skill does not resolve.
+
 ## Framework
 
 - Use `pytest` for all tests. Do not use `unittest.TestCase`.

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]
+rules = ["210-astro", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.92.0",
+  "version": "4.94.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -19,7 +19,8 @@
     "tsconfig.json",
     "!scripts/sandbox",
     "!scripts/eval",
-    "!**/*.test.ts"
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/core/regen-hero.sh

@@ -18,10 +18,11 @@
 # 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
-# images with `canon capture assets/captures --selector .window --out assets`
+# images with `canon capture assets/captures --selector .window --out assets/evidence`
 # after this script reports a change. The markup and the image sit in two
-# folders, so that run reads the sources here and sends every PNG and stamp back
-# up to assets/, where the documents point. The selector has no default, since
+# folders, so that run reads the sources here and sends every PNG and stamp to
+# assets/evidence/, where the documents point and where `canon pr evidence`
+# compares a changed image. The selector has no default, since
 # the element a capture crops to belongs to the page rather than to the command,
 # and `.window` is the class this repository's own sources declare.
 # That capture also writes a .stamp beside each PNG, which records the digest of

package/src/capture/render.ts

@@ -25,6 +25,7 @@ import { formatStamp, hashSource, stampPath } from '@/capture/stamp'
  */
 
 const DEVICE_SCALE_FACTOR = 2
+const DEFAULT_VIEWPORT_HEIGHT = 720
 const FONT_PROBE_SIZE = 72
 const FONT_PROBE_TEXT = 'canon capture 0123456789'
 const ABSENT_FAMILY = '__canon_absent_family__'
@@ -32,6 +33,7 @@ const ABSENT_FAMILY = '__canon_absent_family__'
 export interface CaptureOptions {
   selector: string
   outDir?: string
+  width?: number
 }
 
 export type CaptureResult =
@@ -54,7 +56,9 @@ export async function captureSources(
   const browser = await chromium.launch()
   try {
     return await Promise.all(
-      sources.map((source) => captureOne(browser, source, options.selector)),
+      sources.map((source) =>
+        captureOne(browser, source, options.selector, options.width),
+      ),
     )
   } finally {
     await browser.close()
@@ -69,9 +73,19 @@ async function captureOne(
   browser: Browser,
   source: CaptureSource,
   selector: string,
+  width: number | undefined,
 ): Promise<CaptureResult> {
+  /**
+   * A viewport rather than a wrapper, since a media query answers to the
+   * viewport. Absent leaves the option out so the browser default stands and
+   * every committed capture renders as before. The height is Playwright's own
+   * default, which keeps `vh` units where they were.
+   */
   const page = await browser.newPage({
     deviceScaleFactor: DEVICE_SCALE_FACTOR,
+    ...(width === undefined
+      ? {}
+      : { viewport: { width, height: DEFAULT_VIEWPORT_HEIGHT } }),
   })
   try {
     await page.goto(

package/src/claude/cases/misc.ts

@@ -54,6 +54,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       "I'm about to write the retry helper we settled on and nothing covers it yet, so get the failing case in first.",
     expect: 'test-first',
   },
+  {
+    prompt:
+      'The loading state already shipped. Should its test be an e2e test or a component one, and is the one I wrote any good?',
+    expect: 'test-craft',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/src/cli.ts

@@ -121,7 +121,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon design board`,
     `${GREY}│${NC}    canon slides render`,
     `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets`,
+    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets/evidence`,
     `${GREY}│${NC}    canon serve .canon/teach`,
     `${GREY}│${NC}    canon inventory focus --json`,
     `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,

package/src/commands/capture.ts

@@ -54,10 +54,14 @@ export function register(program: Command): void {
       'Output directory for a file source, or the destination PNG for a URL source; defaults beside the source',
     )
     .option('-s, --selector <selector>', 'Element to capture')
+    .option(
+      '--width <px>',
+      'Viewport width in pixels, so a media query resolves at that width',
+    )
     .action(
       async (
         source: string,
-        opts: { out?: string; selector?: string },
+        opts: { out?: string; selector?: string; width?: string },
       ): Promise<void> => {
         /**
          * Refused rather than defaulted, and refused ahead of every other
@@ -75,6 +79,15 @@ export function register(program: Command): void {
         }
         const selector = opts.selector
 
+        const width = parseWidth(opts.width)
+        if (Number.isNaN(width)) {
+          frameError(
+            `--width takes a whole number of pixels of 1 or more, got ${opts.width}.`,
+          )
+          process.exitCode = 1
+          return
+        }
+
         const isUrl = isUrlSource(source)
         const sourcePath = isUrl ? source : resolve(process.cwd(), source)
         if (!isUrl && !existsSync(sourcePath)) {
@@ -89,6 +102,7 @@ export function register(program: Command): void {
           const renderer = await import('@/capture/render')
           results = await renderer.captureSources(sourcePath, {
             selector,
+            width,
             outDir: opts.out ? resolve(process.cwd(), opts.out) : undefined,
           })
         } catch (error) {
@@ -122,6 +136,16 @@ export function register(program: Command): void {
     )
 }
 
+/**
+ * Undefined for an absent flag and `NaN` for a value that is not a positive
+ * integer, so the caller can tell no width from a bad one.
+ */
+function parseWidth(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined
+  const value = Number(raw)
+  return Number.isInteger(value) && value >= 1 ? value : Number.NaN
+}
+
 /**
  * Closes an open frame around a failure that stopped the whole run rather than
  * one source. Two of them are setup states rather than defects and each names

package/src/commands/serve.ts

@@ -7,6 +7,7 @@ const DEFAULT_DIR = '.'
 
 interface ServeCommandOptions {
   readonly entry?: string
+  readonly index?: boolean
   readonly json?: boolean
   readonly port?: string
 }
@@ -19,6 +20,10 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--port <number>', `Port to try first, default ${DEFAULT_PORT}`)
     .option('--entry <path>', 'Page the printed link opens, default index.html')
+    .option(
+      '--index',
+      'List a directory that has no index.html instead of answering 404',
+    )
     .option('--json', 'Emit a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -39,6 +44,7 @@ export function register(program: Command): void {
         '  canon serve .canon/teach',
         '  canon serve .canon/teach --entry 03-fde-system-design/index.html',
         '  canon serve dist --port 4000 --json',
+        '  canon serve .canon/groundwork --index',
         '',
       ].join('\n'),
     )
@@ -61,7 +67,11 @@ async function runServe(
     )
   }
 
-  const outcome = startServer(dir, { port, entry: opts.entry })
+  const outcome = startServer(dir, {
+    port,
+    entry: opts.entry,
+    index: opts.index,
+  })
   const code = report(outcome, emitJson)
   if (!outcome.ok) return code
 

package/src/design/components.ts

@@ -225,11 +225,16 @@ const TEACH_CHROME: Component = {
     '--teach-chrome',
     '--teach-shadow',
     '--color-teach-accent-bg',
+    '--type-body-family',
+    '--type-code-family',
+    '--t3',
+    '--t4',
+    '--t5',
   ],
   rules: `:root {
-  --teach-sans: 'Nunito', ui-rounded, 'Segoe UI', system-ui, sans-serif;
-  --teach-hand: 'Virgil', 'Nunito', cursive;
-  --teach-mono: 'Cascadia Code', ui-monospace, monospace;
+  --teach-sans: var(--type-body-family);
+  --teach-hand: 'Virgil', 'Excalifont', cursive;
+  --teach-mono: var(--type-code-family);
   --teach-measure: 52rem;
   --teach-chrome: 52rem;
   --teach-mast-h: 4.4rem;
@@ -268,7 +273,7 @@ body {
   background: var(--color-background);
   color: var(--color-text-body);
   font-family: var(--teach-sans);
-  font-size: 1.125rem;
+  font-size: var(--t3);
   line-height: 1.62;
   -webkit-font-smoothing: antialiased;
 }
@@ -297,7 +302,7 @@ main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.
   justify-content: space-between;
   align-items: center;
   gap: 1rem;
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   color: var(--color-muted);
 }
 
@@ -332,7 +337,7 @@ main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.
   border-radius: 8px;
   text-decoration: none;
   color: var(--color-text-body);
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   font-weight: 600;
   line-height: 1.3;
   box-shadow: var(--teach-shadow);
@@ -370,14 +375,14 @@ main { max-width: calc(var(--teach-measure) + 3rem); margin: 0 auto; padding: 2.
    value for a character even a decorative one. */
 .crumb-sep {
   color: var(--color-muted);
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   user-select: none;
 }
 
 /* One arrow, on the first segment, since that is the only one that goes up. */
 .crumb-back {
   margin-right: 0.3rem;
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   line-height: 1;
 }
 
@@ -612,6 +617,9 @@ const TEACH_ARTICLE: Component = {
     '--color-accent',
     '--teach-hand',
     '--teach-mono',
+    '--t4',
+    '--t5',
+    '--t6',
   ],
   rules: `/* ---- Type ---- */
 
@@ -664,7 +672,7 @@ em { font-style: italic; }
   font-weight: 700;
   letter-spacing: 0.06em;
   text-transform: uppercase;
-  font-size: 0.6875rem;
+  font-size: var(--t6);
   margin-bottom: 0.2rem;
 }
 
@@ -680,7 +688,7 @@ code {
 
 pre {
   font-family: var(--teach-mono);
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   line-height: 1.7;
   background: var(--color-surface);
   padding: 1.15rem 1.3rem;
@@ -745,12 +753,12 @@ tbody tr.mark td { background: var(--color-teach-accent-bg); }
 }
 
 .toc a:hover { background: var(--color-surface); }
-.toc .num { font-family: var(--teach-mono); font-size: 0.8125rem; color: var(--color-accent); }
+.toc .num { font-family: var(--teach-mono); font-size: var(--t5); color: var(--color-accent); }
 .toc b { font-size: 1.0625rem; font-weight: 700; letter-spacing: -0.012em; }
 
 .toc .blurb {
   grid-column: 2;
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   line-height: 1.5;
   color: var(--color-text-secondary);
   margin-top: 0.1rem;
@@ -799,7 +807,7 @@ tbody tr.mark td { background: var(--color-teach-accent-bg); }
 ol.succ {
   margin: 0 0 2.5rem;
   padding-left: 1.35rem;
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   line-height: 1.6;
   color: var(--color-text-secondary);
 }
@@ -846,13 +854,13 @@ ol.succ li { margin-bottom: 0.4rem; }
 
 .road-n {
   font-family: var(--teach-mono);
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   color: var(--color-accent);
 }
 
 .road-b { display: block; }
 .road-b b { display: block; margin-bottom: 0.2rem; }
-.road-b span { color: var(--color-text-secondary); font-size: 0.9375rem; line-height: 1.55; }
+.road-b span { color: var(--color-text-secondary); font-size: var(--t4); line-height: 1.55; }
 
 .road-t {
   font-family: var(--teach-mono);
@@ -889,6 +897,8 @@ const TEACH_QUIZ: Component = {
     '--teach-mono',
     '--teach-shadow',
     '--color-teach-accent-bg',
+    '--t4',
+    '--t5',
   ],
   rules: `/* ---- Quiz ---- */
 
@@ -907,7 +917,7 @@ const TEACH_QUIZ: Component = {
   margin-bottom: 0.45rem;
   cursor: pointer;
   font-family: var(--teach-sans);
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   background: transparent;
   width: 100%;
   text-align: left;
@@ -967,7 +977,7 @@ const TEACH_QUIZ: Component = {
 
 .fb {
   display: none;
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   line-height: 1.55;
   color: var(--color-text-secondary);
   background: var(--color-surface);
@@ -983,7 +993,7 @@ footer {
   margin-top: 4rem;
   padding-top: 1.4rem;
   border-top: 1px solid var(--color-border);
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   line-height: 1.6;
   color: var(--color-muted);
 }`,
@@ -1004,6 +1014,8 @@ const TEACH_GLOSSARY: Component = {
     '--color-accent',
     '--teach-sans',
     '--teach-mono',
+    '--t4',
+    '--t5',
   ],
   rules: `/* ---- Glossary view, generated from the markdown source ---- */
 
@@ -1022,7 +1034,7 @@ h2 .count {
 .filter {
   width: 100%;
   font-family: var(--teach-sans);
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   color: var(--color-text-body);
   background: var(--color-background);
   border: 1px solid var(--color-border);
@@ -1064,7 +1076,7 @@ h2 .count {
   display: none;
   padding: 1.2rem 0;
   color: var(--color-muted);
-  font-size: 0.9375rem;
+  font-size: var(--t4);
 }
 
 .gloss.none .empty { display: block; }
@@ -1072,14 +1084,14 @@ h2 .count {
 .gterm {
   padding: 0.7rem 0;
   border-bottom: 1px solid var(--color-border);
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   line-height: 1.55;
 }
 
 .gloss-group {
   margin: 1.1rem 0 0.4rem;
   font-family: var(--teach-sans);
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   font-weight: 600;
   color: var(--color-muted);
   text-transform: uppercase;
@@ -1101,7 +1113,7 @@ h2 .count {
 ol.succ {
   margin: 0 0 2.5rem;
   padding-left: 1.35rem;
-  font-size: 0.9375rem;
+  font-size: var(--t4);
   line-height: 1.6;
   color: var(--color-text-secondary);
 }
@@ -1137,6 +1149,7 @@ const TEACH_OUTLINE: Component = {
     '--teach-sans',
     '--teach-measure',
     '--teach-mast-h',
+    '--t5',
   ],
   rules: `/* ---- In-lesson outline, in the gutter the measure leaves over ---- */
 
@@ -1151,7 +1164,7 @@ const TEACH_OUTLINE: Component = {
   width: calc(13rem + 8px);
   max-height: calc(100vh - var(--teach-mast-h) - 4rem);
   overflow-y: auto;
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   line-height: 1.45;
 }
 
@@ -1218,12 +1231,13 @@ const TEACH_REFERENCES: Component = {
     '--color-accent',
     '--teach-mono',
     '--color-teach-accent-bg',
+    '--t5',
   ],
   rules: `footer {
   margin-top: 4rem;
   padding-top: 1.4rem;
   border-top: 1px solid var(--color-border);
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   line-height: 1.6;
   color: var(--color-muted);
 }
@@ -1252,7 +1266,7 @@ ol.refs {
   counter-reset: r;
   padding: 0;
   margin: 0.9rem 0 1.1rem;
-  font-size: 0.8125rem;
+  font-size: var(--t5);
   line-height: 1.55;
 }
 

package/src/gate/measures.ts

@@ -142,7 +142,7 @@ export function auditsBaselineRel(root: string): string {
 }
 
 export const CAPTURE_STAMP_FAILURE =
-  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets and commit each frame with its image and its stamp.'
+  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets/evidence and commit each frame with its image and its stamp.'
 
 function parseJson(payload: string): unknown {
   try {
@@ -1118,11 +1118,12 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
 /**
  * A capture set spans two folders. The markup and the template beside it are
  * the authored half and sit under `assets/captures/`, while the image a
- * document points at and the stamp answering for it stay in `assets/`, which is
- * where `--out assets` sends them.
+ * document points at and the stamp answering for it sit under
+ * `assets/evidence/`, which is where `--out assets/evidence` sends them and where
+ * `canon pr evidence` looks for a changed image.
  */
 const CAPTURE_MARKUP_DIR = 'assets/captures'
-const CAPTURE_OUTPUT_DIR = 'assets'
+const CAPTURE_OUTPUT_DIR = 'assets/evidence'
 
 /**
  * Every capture under `assets/captures/`, named by the base its three files

package/src/gate/stages.ts

@@ -201,7 +201,7 @@ export const STAGES: readonly Stage[] = [
         kind: 'drift',
         pathspec: 'assets/captures/*.html',
         failure:
-          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets/captures --selector .window --out assets, and commit each assets/captures/*.html with its .png and .stamp.',
+          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets/captures --selector .window --out assets/evidence, and commit each assets/captures/*.html with its .png and .stamp.',
       },
       { kind: 'measure', measure: captureStamps },
     ],