@erclx/canon 5.69.0 → 5.70.0

package/src/take/stepper.ts

@@ -1,6 +1,13 @@
 import { openFrameEncoder } from '@/take/encode'
+import { describeKey, modifierBits } from '@/take/keys'
 import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
-import { type PointerInput, type Stage, performSteps } from '@/take/perform'
+import {
+  type KeyInput,
+  type PointerInput,
+  type Stage,
+  TargetMissing,
+  performSteps,
+} from '@/take/perform'
 import type { Beat } from '@/take/plan'
 import { type ShellPage, openShell } from '@/take/shell'
 
@@ -36,6 +43,9 @@ const LOAD_CAP_MS = 15_000
 const SETTLE_MS = 2500
 const LOADING_FRAME_CAP_MS = 250
 
+/** How long a refusal waits on the frame it shows, since the page may be wedged. */
+const STILL_CAP_MS = 2000
+
 /** A frame that took longer than `STALL_MS`, so the beat is filmed another way. */
 export class StepperStalled extends Error {
   constructor(
@@ -68,6 +78,7 @@ export async function filmStepped(
   const page = await openShell(request.executable, VIEWPORT)
   const encoder = openFrameEncoder(request.clip, FPS)
   const stallMs = request.stallMs ?? STALL_MS
+  let still: (() => Promise<Buffer | undefined>) | undefined
   try {
     let ticks = await load(page, request.url)
     const beginFrame = (screenshot: boolean) =>
@@ -81,6 +92,7 @@ export async function filmStepped(
             : {}),
         },
       )
+    still = () => frameStill(beginFrame)
     await pump(beginFrame, SETTLE_MS)
 
     const live = liveStage(page, beginFrame, stallMs)
@@ -128,16 +140,14 @@ export async function filmStepped(
       hold: async (ms) => {
         for (let i = 0; i < Math.round(ms / FRAME_MS); i += 1) await frame()
       },
-      pointer: async (input) => {
-        const sent = page.send('Input.dispatchMouseEvent', mouseEvent(input))
-        await frame()
-        await sent
-      },
-      key: async (text) => {
-        const sent = page.send('Input.insertText', { text })
-        await frame()
-        await sent
-      },
+      pointer: (input) =>
+        stepThen(
+          page.send('Input.dispatchMouseEvent', mouseEvent(input)),
+          frame,
+        ),
+      key: (text) => stepThen(page.send('Input.insertText', { text }), frame),
+      press: (input) =>
+        stepThen(page.send('Input.dispatchKeyEvent', keyEvent(input)), frame),
       evaluate: (expression) => page.evaluate(expression),
     }
 
@@ -153,12 +163,31 @@ export async function filmStepped(
     return { frames, events, still: last }
   } catch (error) {
     encoder.abort()
+    if (error instanceof TargetMissing && still) error.still = await still()
     throw error
   } finally {
     page.close()
   }
 }
 
+/**
+ * Begins one frame with a screenshot for a refusal to show, through the same
+ * begin-frame call every kept frame uses, since a separate capture call can
+ * wait on a frame that never begins. Best effort, so a page that answers with
+ * nothing leaves the refusal standing without a still.
+ */
+async function frameStill(
+  beginFrame: (screenshot: boolean) => Promise<{ screenshotData?: string }>,
+): Promise<Buffer | undefined> {
+  const reply = await Promise.race([
+    beginFrame(true).catch(() => undefined),
+    sleep(STILL_CAP_MS),
+  ])
+  return reply?.screenshotData
+    ? Buffer.from(reply.screenshotData, 'base64')
+    : undefined
+}
+
 /**
  * Navigates and resolves with Chromium's monotonic clock in milliseconds, read
  * off the load event's own timestamp. The runtime's clock cannot stand in for
@@ -217,7 +246,7 @@ function liveStage(
     pointer: (input) => {
       const sent = page.send('Input.dispatchMouseEvent', mouseEvent(input))
       return withinStall(
-        beginFrame(false).then(() => sent),
+        Promise.all([beginFrame(false), sent]),
         0,
         stallMs,
       ).then(() => {})
@@ -225,7 +254,15 @@ function liveStage(
     key: (text) => {
       const sent = page.send('Input.insertText', { text })
       return withinStall(
-        beginFrame(false).then(() => sent),
+        Promise.all([beginFrame(false), sent]),
+        0,
+        stallMs,
+      ).then(() => {})
+    },
+    press: (input) => {
+      const sent = page.send('Input.dispatchKeyEvent', keyEvent(input))
+      return withinStall(
+        Promise.all([beginFrame(false), sent]),
         0,
         stallMs,
       ).then(() => {})
@@ -234,18 +271,83 @@ function liveStage(
   }
 }
 
+/**
+ * A pointer input as CDP takes it. `buttons` carries the held button through a
+ * drag's moves, or the page reads them as a hover, and `modifiers` carries the
+ * held keys as a bit field beside the key events that pressed them.
+ */
 function mouseEvent(input: PointerInput): Record<string, unknown> {
   const at = { x: input.x, y: input.y }
+  if (input.type === 'wheel') {
+    return { type: 'mouseWheel', ...at, deltaX: 0, deltaY: input.dy }
+  }
+  const modifiers = modifierBits(input.modifiers ?? [])
   switch (input.type) {
     case 'move':
-      return { type: 'mouseMoved', ...at, button: 'none' }
+      return input.held
+        ? { type: 'mouseMoved', ...at, button: 'left', buttons: 1, modifiers }
+        : { type: 'mouseMoved', ...at, button: 'none', buttons: 0, modifiers }
     case 'down':
-      return { type: 'mousePressed', ...at, button: 'left', clickCount: 1 }
     case 'up':
-      return { type: 'mouseReleased', ...at, button: 'left', clickCount: 1 }
-    case 'wheel':
-      return { type: 'mouseWheel', ...at, deltaX: 0, deltaY: input.dy }
+      return {
+        type: input.type === 'down' ? 'mousePressed' : 'mouseReleased',
+        ...at,
+        button: 'left',
+        buttons: input.type === 'down' ? 1 : 0,
+        clickCount: input.clickCount,
+        modifiers,
+      }
+  }
+}
+
+/**
+ * A key input as CDP takes it. A key that types sends `keyDown` with its text
+ * only when no modifier but Shift is held, as Chromium's own keyboard does, so
+ * `Control+K` in a focused field inserts no K.
+ */
+function keyEvent(input: KeyInput): Record<string, unknown> {
+  const descriptor = describeKey(input.key, {
+    shift: input.modifiers.includes('Shift'),
+  })
+  if (!descriptor) throw new Error(`no key descriptor for ${input.key}`)
+  const event = {
+    key: descriptor.key,
+    code: descriptor.code,
+    windowsVirtualKeyCode: descriptor.keyCode,
+    nativeVirtualKeyCode: descriptor.keyCode,
+    location: descriptor.location,
+    modifiers: modifierBits(input.modifiers),
+  }
+  if (input.type === 'up') return { type: 'keyUp', ...event }
+  const types =
+    descriptor.text !== undefined &&
+    input.modifiers.every((modifier) => modifier === 'Shift')
+  return types
+    ? {
+        type: 'keyDown',
+        ...event,
+        text: descriptor.text,
+        unmodifiedText: descriptor.text,
+      }
+    : { type: 'rawKeyDown', ...event }
+}
+
+/**
+ * Steps a frame, then awaits the input sent ahead of it. When the step fails,
+ * the input is left settling against a shell about to close, so its rejection
+ * is handled here rather than surfacing as an unhandled one.
+ */
+async function stepThen(
+  sent: Promise<unknown>,
+  step: () => Promise<void>,
+): Promise<void> {
+  try {
+    await step()
+  } catch (error) {
+    sent.catch(() => {})
+    throw error
   }
+  await sent
 }
 
 async function withinStall<T>(
@@ -257,6 +359,8 @@ async function withinStall<T>(
   const stalled = new Promise<never>((_, fail) => {
     timer = setTimeout(() => fail(new StepperStalled(frame, stallMs)), stallMs)
   })
+  // A stall leaves the work pending until the shell closes and rejects it.
+  work.catch(() => {})
   try {
     return await Promise.race([work, stalled])
   } finally {

package/docs/target/migrations.md

@@ -1,205 +0,0 @@
----
-title: Target migrations
-description: One-time moves a project scaffolded under an older toolkit runs before its next sync
-category: Agent surface
----
-
-# Target migrations
-
-Each section is a move a project runs once, when it was scaffolded before the change it names. Run `canon upgrade` first, then `canon migrate status --json` to list the moves a project still needs in the order to run them. The recurring sync that follows is in [target sync](sync.md).
-
-`canon:target-update` is the guided path through both. It runs the moves in that order once you approve its preview.
-
-## Move the records first, once
-
-Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.
-
-```bash
-canon tooling sync claude . --write
-canon migrate records --json
-canon migrate records --write --json
-```
-
-The first line takes the `.canon/` ignore entry. The second reports and the third applies, repointing files that cite a moved folder and deleting a `.gitignore` line `.canon/` covers, as `dropped`. A line naming an old path keeps it via `canon-keep-record-root` on that line or the nearest non-blank one above.
-
-Then sweep the citations inside the records, which the verb above never reaches.
-
-```bash
-canon migrate record-tree --json
-canon migrate record-tree --write --json
-```
-
-It covers `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. Read the report before `--write`. The record tree is untracked, and a wrong rewrite has no undo.
-
-## Back records up off this machine, once
-
-Run `canon records push` once a private repository exists. It prints the one-time setup command when it finds none, and `canon init` prints the same reminder.
-
-## Move rules off the flat layout, once
-
-Installed rules moved from `.claude/rules/<subdir>/` to `.claude/rules/canon/<subdir>/`. On the flat layout `canon gov sync` exits 0 reporting `No governance surfaces found in target`, and `canon gov install` lands a second copy.
-
-```bash
-canon migrate rule-layout --json
-canon migrate rule-layout --write --json
-```
-
-Run it once, ahead of `canon gov sync` or `canon gov install`.
-
-## Rename the skill citations, once
-
-Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` is now `canon:context-fold`. Five drafters merged into `write-doc`, seven `draft-` skills took verb-first names, and four joined their family. No old name keeps a pointer, and `canon migrate skill-names --write` moves a project. <!-- canon-keep-retired -->
-
-| Old name           | New name                                        |
-| ------------------ | ----------------------------------------------- |
-| `draft-doc`        | `write-doc` <!-- canon-keep-retired -->         |
-| `draft-figure`     | `draw-figure` <!-- canon-keep-retired -->       |
-| `draft-identity`   | `design-identity` <!-- canon-keep-retired -->   |
-| `draft-slides`     | `make-deck` <!-- canon-keep-retired -->         |
-| `draft-and-pick`   | `design-pick` <!-- canon-keep-retired -->       |
-| `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
-| `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
-| `pick-by-eye`      | `design-pick` <!-- canon-keep-retired -->       |
-| `ui-record`        | `ui-film` <!-- canon-keep-retired -->           |
-| `ux-audit`         | `ui-audit` <!-- canon-keep-retired -->          |
-| `ux-measure`       | `ui-measure` <!-- canon-keep-retired -->        |
-
-Replace a citation of a skill with no successor by hand, or delete the sentence.
-
-- `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare mention by hand. <!-- canon-keep-retired -->
-- `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request, so replace a bare mention by hand. <!-- canon-keep-retired -->
-- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
-- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, and `canon-feedback-triage` have no successor <!-- canon-keep-retired -->
-- `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, `ux-walkthrough`, and `plan-ready` have no successor <!-- canon-keep-retired -->
-
-The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
-
-- `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
-- `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
-
-Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack, naming a held hook with `--replace`.
-
-```bash
-canon gov sync
-canon tooling sync <stack> . --write
-canon migrate skill-names --json
-canon migrate skill-names --write --json
-```
-
-## Rename the pull request template headings, once
-
-The template headings are now `## Key changes` and `## Technical context`, and `canon labels scan` compares case exactly. Rename them in `.github/pull_request_template.md`, or delete it and run `canon tooling sync base . --write`.
-
-## Move the surfaces off `.claude/`, once
-
-`context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, now `canon/config/`, moved under `canon/`. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them.
-
-```bash
-canon migrate surface-roots --json
-canon migrate surface-roots --write --json
-```
-
-It moves each surface with `git mv` and repoints every tracked citation. No other command notices a surface left at `.claude/`.
-
-## Delete the retired snippets, once
-
-A project scaffolded while snippets installed may hold `.claude/snippets/` or a root `snippets/`.
-
-```bash
-canon sync --check . --json | jq '.reverse'
-```
-
-- `dropped` is the toolkit's copy, unchanged, so delete it
-- `unattributed` is often an edited copy, so read what changed first
-- `project` is the project's own content, so leave it
-
-From the registry the walk reports `historyUnavailable`, so check both paths by hand.
-
-## Stop calling the standards verb, once
-
-`canon standards <name>` is gone, and a call now fails with a too-many-arguments error. Replace each call with the skill that owns the standard, at `references/<name>.md`. <!-- canon-allow-reference: verb retired -->
-
-| Skill             | Standards                                                     |
-| ----------------- | ------------------------------------------------------------- |
-| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
-| `context-fold`    | `context`                                                     |
-| `canvas-board`    | `canvas`, `design` <!-- canon-keep-retired -->                |
-| `docs-sync`       | `docs`, `readme`                                              |
-| `draw-figure`     | `figures`, `mermaid`                                          |
-| `create-rule`     | `rule`                                                        |
-| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
-| `git-branch`      | `branch`, `slug`                                              |
-| `git-commit`      | `commit`, `versioning`                                        |
-| `git-pr`          | `pr`, `publish`                                               |
-| `markdown-craft`  | `markdown`                                                    |
-| `teach-workspace` | `glossary`, `teach` <!-- canon-keep-retired -->               |
-| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
-| `plan-intake`     | `intake`                                                      |
-| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
-| `plan-ready`      | `ready` <!-- canon-keep-retired -->                           |
-| `write-doc`       | `requirements`, `wiki`                                        |
-| `session-map`     | `session`                                                     |
-
-The `standard` name became `skill-reference.md` in `create-skill`.
-
-## Keep or delete the wireframes folder, your call
-
-The wireframes record is retired, and nothing deletes what a project holds.
-
-- `canon/wireframes/` stays yours and unaudited. Keep it as notes or delete it.
-- Delete the `@canon/wireframes/index.md` line in your `CLAUDE.md` with the folder. `canon claude sync` does not rewrite it.
-- `canon gov sync` removes `.claude/rules/canon/standards/wireframes.md`
-
-## Keep or delete the retired product files, your call
-
-The learning workspace, deck renderer, app recorder, canvas, and design install are retired with their verbs, and nothing deletes what a project holds.
-
-- `.canon/teach/` holds HTML that opens as it is <!-- canon-keep-retired -->
-- `.canon/slides/` and a `demos/` folder hold sources nothing renders any more, so delete them once nothing cites them <!-- canon-keep-retired -->
-- Move the `.claude/design/project/` values, `fonts/`, and `fonts.css` to the stylesheet your `canon/DESIGN.md` lead names, then delete `.claude/design/`
-
-A reference to a retired skill takes a hand edit.
-
-- Replace a `canon:teach-workspace` reference with `canon:teach-craft` by hand, since `canon migrate skill-names` does not rewrite it <!-- canon-keep-retired -->
-- Delete a `canon:make-deck`, `canon:script-screencast`, `canon:record-screencast`, `canon:read-frames`, or `canon:video-craft` reference, since none has a successor <!-- canon-keep-retired -->
-- Delete a `canon:canvas-board` reference too. Frameboard, which `canon:design-pick` drives, reads each `.canon/canvas/` folder as a project, so move a kept page under one <!-- canon-keep-retired -->
-
-## Move decisions out of a held architecture record, once
-
-The toolkit no longer seeds `canon/ARCHITECTURE.md`, and a held file and its `CLAUDE.md` import stay. Move a trap a session would hit into that domain's `## Gotchas`, then delete the file and its `@canon/ARCHITECTURE.md` line.
-
-## Deny subagents and merges, and turn auto memory off, once
-
-The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
-
-```bash
-canon migrate session-defaults --json
-canon migrate session-defaults --write --json
-```
-
-The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
-
-The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.
-
-## Move the capture cases out of the harness, once
-
-A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. A harness you edited is held on `--write`, so the new one lands only once you pass `--replace e2e/screenshot.ts`.
-
-- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts`, then sync with `--replace e2e/screenshot.ts`.
-- Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
-- A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
-
-## Fold the ui rules onto one pointer, once
-
-Eleven ui rules moved unchanged into the `ui-craft` skill, being `a11y`, `keyboard`, `pointer`, `forms`, `motion`, `ux-controls`, `ux-completeness`, `surface-capture`, `copy`, `interface-casing`, and `link-behavior`. Update the plugin, then sync, which folds each one you hold and `design-taste.md` onto one `craft.md` pointer without local edits.
-
-```bash
-canon gov sync .
-```
-
-## Group a long paths section in `CLAUDE.md`, once
-
-The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
-
-- Regroup the section by hand under H3s, each opening on a one-sentence lead.
-- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.