@erclx/canon 4.5.0 → 4.6.0

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

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

package/docs/agents/commands.md

@@ -70,6 +70,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon audits list`           | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                             |
 | `canon gate run`              | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                           |
 | `canon inventory [subject]`   | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                  |
+| `canon drive <url> <run>`     | Walk a page through named interactions and measure each state it reaches, reporting findings rather than gating (`--json`)                                            |
 | `canon capture [source]`      | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
 | `canon serve [dir]`           | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                               |
 | `canon upgrade`               | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                 |
@@ -94,6 +95,8 @@ routes = ["/", "/pricing", "/docs"]
 query = "button, a[href], input, select, textarea, [tabindex]"
 ```
 
+`canon drive` is the fourth and ships for the same reason the two before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
+
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.

package/docs/agents/driver.md

@@ -0,0 +1,103 @@
+---
+title: Driver
+description: Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
+---
+
+# Driver
+
+`canon drive <url> <run>` walks a page through a sequence of interactions and measures every state it reaches. A render answers about a page as it loads, so a defect that exists only after a menu opens, an answer is chosen, or the page scrolls is invisible to one. That second axis is what this adds.
+
+```bash
+canon drive http://localhost:4173 run.json
+canon drive http://localhost:4173 run.json --json
+```
+
+| Option   | Behavior                                |
+| -------- | --------------------------------------- |
+| `--json` | Add a machine-readable record on stdout |
+
+## The run file
+
+The run is a JSON file rather than a key in a project config, because a route catalog is state a project holds and an interaction sequence is a script written for one question. It carries the viewport, the probes to run by default, and the steps.
+
+```json
+{
+  "viewport": { "width": 1440, "heights": [900, 1200, 1500] },
+  "probes": ["focus", "details"],
+  "steps": [
+    { "name": "on load", "kind": "wait", "ms": 0 },
+    { "name": "open the menu", "kind": "click", "target": "#menu summary" },
+    {
+      "name": "reach the diagram",
+      "kind": "scroll",
+      "target": "figure",
+      "probes": ["diagram-geometry", "diagram-strokes"]
+    }
+  ]
+}
+```
+
+Every step names what it did, and that name is carried onto each finding it produced, alongside the viewport. A step naming its own `probes` overrides the run-level list for that step alone. Omitting `probes` at the run level runs all four.
+
+| Step kind | Fields             | What it does                                   |
+| --------- | ------------------ | ---------------------------------------------- |
+| `click`   | `target`           | Presses the first element the selector matches |
+| `scroll`  | `target`           | Brings the first match into view               |
+| `fill`    | `target`, `text`   | Types into the first match                     |
+| `tab`     | `count` (optional) | Advances keyboard focus, once by default       |
+| `wait`    | `ms`               | Holds, for a state the page reaches alone      |
+
+Probes run after a step and never on arrival, so a run reaches the load state by opening with a `wait` step of its own, as the example above does. Nothing probes before the first step runs, which makes that leading step the only way to measure the page as it first painted, and naming it is what puts the load state on its own findings rather than under whatever ran next.
+
+Write one in any project that does not have `canon capture`, which is toolkit-only and renders a single state from a committed source. Where capture runs, it already answers about arrival and a leading `wait` duplicates it. Where it does not, this command is the only thing measuring the page at all, and a run without that step reports every driven state and nothing about the one a visitor sees first.
+
+Each height is driven in a context of its own from a fresh navigation, rather than by resizing the page the previous height already drove, since a sweep asks the same question of each height rather than a later question of an already-driven page.
+
+## The probes
+
+Four probes, a fixed catalog rather than a subject system a project extends. Each carries a class of false finding that a throwaway version of this command produced before it produced true ones, and a probe a project authored for itself would re-pay those.
+
+| Probe              | What it reports                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| `focus`            | An element that takes keyboard focus and changes nothing visible                           |
+| `details`          | A `details` panel off the viewport, or a row under the tap minimum, both read open         |
+| `diagram-geometry` | An SVG label outside its frame, covered by a filled shape, or colliding with another label |
+| `diagram-strokes`  | An SVG label a stroke crosses, sampled along the stroke's own geometry                     |
+
+`focus` presses Tab before it reads anything. `:focus-visible` does not match a scripted `.focus()` once the page has taken a pointer interaction, and a driver clicks by definition, so a reader without that press reports every correctly styled element as unstyled. It also ignores an outline width, color, or offset moving underneath an outline that resolves to `none`, which paints nothing.
+
+`details` discovers every `details` on the page rather than taking a selector, measures each shut and again open, and judges only the open reading. A shut menu still reports a layout box and the box describes the trigger rather than the panel, so the shut numbers travel in the record as context. Discovery is automatic because the one real menu defect in the originating run was missed by a hand-picked probe: nobody thought to name that menu.
+
+Both diagram probes read after `document.fonts.ready` and never compute from the markup. A generated page is routinely authored against one font and restyled to another, so a label that cleared a line at its authored width can overlap it once rendered. Every rect either probe compares is inset vertically and never horizontally, since a text rect is loose above and below the glyphs and tight to them left and right, and a horizontal inset passes a real overrun.
+
+`diagram-strokes` is separate from `diagram-geometry` because a bounding box cannot answer for a stroke. A probe comparing filled boxes filters out every `line` and every `fill="none"` panel border before it compares, and a diagonal connector's box covers most of a diagram while the stroke itself touches almost none of it. Both paint orders are findings: a stroke drawn after a label crosses the glyphs out, and one drawn before it shows through them, since SVG text carries no plate of its own.
+
+## Viewport heights are never defaulted
+
+A run with no `viewport.heights` refuses. The heights that separate a passing render from a failing one belong to the layout being driven, and the only evidence behind any default this could ship is one fixture's failure range, too narrow a sample to hand every later caller a number they never chose. A scroll rail that skipped its middle sections passed at 900 and failed at 1200 and 1500, so one height reports clean over a live defect.
+
+## What it reports
+
+It reports findings and never gates, and the exit code says only whether the drive completed. Every probe here carries a class of false finding already paid for once, so a command ending a build on its own reading makes a claim this catalog has not earned. A caller that wants a verdict reads `findings` off the `--json` record and decides for itself.
+
+| Reason               | What it means                                          |
+| -------------------- | ------------------------------------------------------ |
+| `no-run-file`        | Nothing readable at the path given                     |
+| `unreadable-plan`    | The run file is not valid JSON                         |
+| `no-steps`           | The run names no step                                  |
+| `no-probes`          | The run names an empty probe list                      |
+| `unknown-probe`      | The run names a probe this build does not ship         |
+| `bad-step`           | A step is missing what the driver needs to perform it  |
+| `no-viewport`        | The run declares no viewport                           |
+| `no-width`           | The viewport has no width to wrap at                   |
+| `no-heights`         | The viewport names no height, which is never defaulted |
+| `engine-missing`     | The browser engine is not installed in this project    |
+| `browser-missing`    | The engine is installed and its browser binary is not  |
+| `server-unreachable` | Nothing answered at the URL, so no state was reached   |
+| `drive-failed`       | The drive failed against a reachable page              |
+
+An unreachable page refuses rather than returning an empty report, since nothing measured and nothing found read the same to anything counting findings.
+
+The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo` and `inventory` rather than staying toolkit-only like `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, which the package excludes, so the two surfaces move independently.
+
+See `commands.md` for where this sits among the browser commands, and `capture.md` for the single-state render it adds an axis to.

package/docs/agents/index.md

@@ -18,6 +18,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, the pointer the recording paints, and what each refusal reports
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
+- [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project

package/package.json

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

package/src/browser/engine.ts

@@ -1,13 +1,15 @@
 /**
  * What every browser-driving command needs to know before it can report a
- * failure honestly: how the binary is installed, and how each of the two ways
- * it can be absent reads when it is thrown.
+ * failure honestly: how the binary is installed, how each of the two ways it
+ * can be absent reads when it is thrown, and the one press that decides whether
+ * a focus reading means anything.
  *
- * The two are different states with different remedies. A package that never
- * resolved means the target installed the CLI without the engine, and a binary
- * that was never downloaded means the engine is present and its browser is not.
- * Both were spelled inside `src/demo/` when `demo` was the only command driving
- * a browser, and a second command is what makes them shared rather than local.
+ * The two absences are different states with different remedies. A package that
+ * never resolved means the target installed the CLI without the engine, and a
+ * binary that was never downloaded means the engine is present and its browser
+ * is not. Both were spelled inside `src/demo/` when `demo` was the only command
+ * driving a browser, and a second command is what makes them shared rather than
+ * local.
  */
 
 /** Fetches the browser revision the pinned engine expects. */
@@ -38,3 +40,44 @@ export function isEngineMissing(error: unknown): boolean {
     error.code === 'ERR_MODULE_NOT_FOUND'
   )
 }
+
+/**
+ * Separates a server nobody started from a page that failed for its own
+ * reasons. The first is a precondition no browser command can create for
+ * itself, and reporting it as an empty reading says the site gives no answers
+ * when nothing was ever asked.
+ *
+ * It moved here alongside the modality press, when `@/driver/drive` became the
+ * second module needing it.
+ */
+export function isServerUnreachable(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /ERR_CONNECTION_REFUSED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_RESET|ERR_EMPTY_RESPONSE/i.test(
+    text,
+  )
+}
+
+/**
+ * The narrowest shape the press below needs, declared here rather than imported
+ * as `Page`, so this module keeps its type surface free of the engine and every
+ * command reading a refusal string still loads without resolving it.
+ */
+export interface KeyboardPage {
+  readonly keyboard: { press(key: string): Promise<void> }
+}
+
+/**
+ * Puts the page in keyboard modality, which is the precondition for reading a
+ * `:focus-visible` rule at all. A scripted `.focus()` on its own leaves the
+ * browser in pointer modality, where that rule does not match, so a reader
+ * calling it alone reports every correctly styled element as unstyled.
+ *
+ * It moved here when `@/driver/probes/focus` became the second call site,
+ * matching how the launch-failure split moved out of `src/demo/` once
+ * `canon inventory` became the second command driving a browser. One press
+ * covers the page rather than the element that happens to hold focus, so it
+ * survives the blur every reader takes next.
+ */
+export async function enterKeyboardModality(page: KeyboardPage): Promise<void> {
+  await page.keyboard.press('Tab')
+}

package/src/cli.ts

@@ -18,6 +18,7 @@ import { register as capture } from '@/commands/capture'
 import { register as serve } from '@/commands/serve'
 import { register as demo } from '@/commands/demo'
 import { register as inventory } from '@/commands/inventory'
+import { register as driver } from '@/commands/driver'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -70,6 +71,7 @@ function showHelp(): void {
     `${GREY}│${NC}    serve [dir]        ${GREY}# Serve a directory over localhost and print the preview link${NC}`,
     `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
     `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
+    `${GREY}│${NC}    drive <url> <run>  ${GREY}# Walk a page through named interactions and measure each state${NC}`,
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/feedback/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
@@ -121,6 +123,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon capture assets/install.html`,
     `${GREY}│${NC}    canon serve .claude/teach`,
     `${GREY}│${NC}    canon inventory focus --json`,
+    `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,
     `${GREY}│${NC}    pbpaste | canon feedback`,
     `${GREY}│${NC}    canon transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    canon tasks archive --pull-request 673 --json`,
@@ -177,6 +180,7 @@ capture(program)
 serve(program)
 demo(program)
 inventory(program)
+driver(program)
 feedback(program)
 transcripts(program)
 tasks(program)

package/src/commands/driver.ts

@@ -0,0 +1,266 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import type { DriverRefusal } from '@/driver/drive'
+import { describeViewport } from '@/driver/probes/viewport'
+import { PROBE_NAMES, readDriverPlan } from '@/driver/steps'
+import type { PlanRefusal } from '@/driver/steps'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadDriver`, because
+ * `src/cli.ts` imports this module at startup and resolving the engine there
+ * would put a browser launch in front of every other command.
+ */
+type Driver = typeof import('@/driver/drive')
+
+interface RunOptions {
+  readonly json?: boolean
+}
+
+/**
+ * Spelled here rather than through `plural`, which appends a bare `s` and gets
+ * the plural of this noun wrong.
+ */
+function passes(count: number): string {
+  return `${count} ${count === 1 ? 'pass' : 'passes'}`
+}
+
+/** What a reader does about each way the run document produced no drive. */
+const PLAN_REFUSALS: Record<PlanRefusal, string> = {
+  'unreadable-plan':
+    'The run file is not valid JSON, so no step could be read.',
+  'no-steps': 'The run names no step, so there is nothing to drive.',
+  'no-probes': 'The run names no probe, so every step would measure nothing.',
+  'unknown-probe': 'The run names a probe this build does not ship.',
+  'bad-step': 'A step is missing something the driver needs to perform it.',
+  'no-viewport': 'The run declares no viewport to render at.',
+  'no-width': 'The run declares no viewport width.',
+  'no-heights':
+    'The run names no viewport height, and this command defaults none.',
+}
+
+const DRIVE_REFUSALS: Record<DriverRefusal, string> = {
+  'browser-missing': 'The browser binary is not installed in this project.',
+  'server-unreachable': 'Nothing answered at the URL, so no state was reached.',
+  'drive-failed': 'The drive failed against a reachable page.',
+}
+
+export function register(program: Command): void {
+  program
+    .command('drive')
+    .description(
+      'Walk a page through named interactions and measure each state',
+    )
+    .argument('<url>', 'Address to drive')
+    .argument(
+      '<run>',
+      'JSON file naming the viewports, the probes, and the steps',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A render answers about a page as it loads. Every defect that exists',
+        'only after a menu opens, an answer is chosen, or the page scrolls is',
+        'invisible to one, which is the axis this adds. Probes run after each',
+        'step and never on arrival, so a run reaches the load state by opening',
+        'with a wait step of its own. Write one wherever canon capture does not',
+        'run, since nothing else there measures the page as it first painted.',
+        '',
+        'The run file carries the viewport, the default probe list, and the',
+        'steps. A step names its own probes to override the default. Viewport',
+        'heights are never defaulted: the heights a defect hides at are a',
+        'property of the layout rather than of this command.',
+        '',
+        '  {',
+        '    "viewport": { "width": 1440, "heights": [900, 1200, 1500] },',
+        '    "probes": ["focus", "details"],',
+        '    "steps": [',
+        '      { "name": "open the menu", "kind": "click", "target": "#menu" },',
+        '      { "name": "reach the diagram", "kind": "scroll", "target": "figure",',
+        '        "probes": ["diagram-geometry", "diagram-strokes"] }',
+        '    ]',
+        '  }',
+        '',
+        'It reports findings and never gates. Every probe here carries a class',
+        'of false finding a throwaway version already produced, so a run that',
+        'ends the build on its own reading is a claim this catalog has not',
+        'earned. Branch on the JSON record instead.',
+        '',
+        'Needs a reachable page and a browser binary. Install the browser with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Probes:',
+        ...PROBE_NAMES.map((name) => `  ${name}`),
+        '',
+        'Step kinds:',
+        '  click <target>   press the first element the selector matches',
+        '  scroll <target>  bring the first match into view',
+        '  fill <target>    type text into the first match',
+        '  tab [count]      advance keyboard focus',
+        '  wait <ms>        hold, for a state the page reaches on its own',
+        '',
+        'Exit codes:',
+        '  0  the drive completed, with its findings reported',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon drive http://localhost:4173 run.json',
+        '  canon drive http://localhost:4173 run.json --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (url: string, run: string, opts: RunOptions) => {
+      process.exitCode = await runDriver(url, run, opts)
+    })
+}
+
+async function runDriver(
+  url: string,
+  runPath: string,
+  opts: RunOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const path = resolve(runPath)
+
+  intro(`canon drive ${url}`)
+
+  let source: string
+  try {
+    source = readFileSync(path, 'utf8')
+  } catch (error) {
+    return refuse(
+      emitJson,
+      url,
+      'no-run-file',
+      `No run file at ${path}. ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+
+  const read = readDriverPlan(source)
+  if (read.kind === 'refused') {
+    return refuse(
+      emitJson,
+      url,
+      read.reason,
+      `${PLAN_REFUSALS[read.reason]} ${read.detail}`,
+    )
+  }
+
+  const { plan } = read
+
+  logStep('Scope')
+  logInfo(
+    `${plural(plan.steps.length, 'step')} at ${plan.viewports.map(describeViewport).join(', ')}, measuring ${plan.probes.join(', ')}`,
+  )
+
+  const driver = await loadDriver()
+  if (!driver) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(emitJson, {
+      url,
+      run: path,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  const result = await driver.drive({ url, plan })
+
+  if (result.status === 'failed') {
+    logStep('Refused')
+    logWarn(DRIVE_REFUSALS[result.reason])
+    if (result.reason === 'server-unreachable') {
+      logWarn(`Start whatever serves ${url}, then run this again.`)
+    }
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+    }
+    logWarn(result.message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, {
+      url,
+      run: path,
+      reason: result.reason,
+      message: result.message,
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  logStep('Passes')
+  for (const pass of result.passes) {
+    logInfo(
+      `${pass.viewport}  ${pass.step}  ${plural(pass.probes, 'probe')}  ${plural(pass.findings, 'finding')}`,
+    )
+  }
+
+  logStep('Findings')
+  if (result.findings.length === 0) {
+    logInfo(
+      `nothing across ${passes(result.passes.length)}, which is a reading rather than a pass mark`,
+    )
+  } else {
+    logInfo(
+      `${plural(result.findings.length, 'finding')} across ${passes(result.passes.length)}`,
+    )
+    for (const finding of result.findings) {
+      logInfo(`  ${finding.probe}  ${finding.selector}`)
+      logInfo(`      ${finding.detail}`)
+      logInfo(`      after ${finding.step} at ${finding.viewport}`)
+      logInfo(`      ${finding.measured}`)
+    }
+  }
+  outro()
+
+  emit(emitJson, {
+    url,
+    run: path,
+    viewports: plan.viewports,
+    passes: result.passes,
+    findings: result.findings,
+    durationMs: result.durationMs,
+  })
+  return 0
+}
+
+/**
+ * Frames a refusal on stderr and puts the record on stdout, so an operator
+ * reading the terminal sees the reason rather than a command that appeared to
+ * do nothing.
+ */
+function refuse(
+  emitJson: boolean,
+  url: string,
+  reason: string,
+  message: string,
+): number {
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  emit(emitJson, { url, reason, message })
+  return 1
+}
+
+async function loadDriver(): Promise<Driver | undefined> {
+  try {
+    return await import('@/driver/drive')
+  } catch (error) {
+    if (isEngineMissing(error)) return undefined
+    throw error
+  }
+}
+
+function emit(json: boolean, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}