@erclx/canon 5.74.0 → 5.75.0

package/src/migrate/session-defaults.ts

@@ -1,7 +1,8 @@
 /**
  * Adds the session defaults the seeded `.claude/settings.json` carries to a
- * target that was seeded before them: the subagent deny, the memory default, and
- * the merge deny entries.
+ * target that was seeded before them: the subagent deny, the memory default,
+ * the merge deny entries, and the plan guard's PreToolUse wiring where the
+ * project holds the guard script.
  *
  * `canon claude init` copies a seed only when the file is absent, so a target
  * holding its own settings never sees a later seed change. This verb adds each
@@ -28,6 +29,26 @@ export const MERGE_DENIED: readonly string[] = [
   'Bash(gh pr merge:*)',
 ]
 
+/** The command the seed wires, as the seeded settings spell it. */
+export const PLAN_GUARD_COMMAND =
+  '"$CLAUDE_PROJECT_DIR"/.claude/hooks/plan-guard.sh'
+
+const PLAN_GUARD_SCRIPT = 'plan-guard.sh'
+
+/**
+ * Each tool the guard acts on, beside the seeded matcher that carries it. A
+ * guard wired by hand under any matcher covering the tool counts as wired.
+ */
+const PLAN_GUARD_WIRING: readonly { tool: string; matcher: string }[] = [
+  { tool: 'Bash', matcher: 'Bash' },
+  { tool: 'Write', matcher: 'Write|Edit' },
+]
+
+export interface SessionDefaultsOptions {
+  /** True when the project holds `.claude/hooks/plan-guard.sh` to wire. */
+  readonly planGuard?: boolean
+}
+
 export interface SessionDefaultsPlan {
   readonly keys: readonly SettingsKey[]
   readonly next: SettingsRecord
@@ -66,6 +87,7 @@ function isRecord(value: unknown): value is SettingsRecord {
  */
 export function planSessionDefaults(
   current: SettingsRecord,
+  { planGuard = false }: SessionDefaultsOptions = {},
 ): SessionDefaultsPlan {
   const next: SettingsRecord = { ...current }
   const permissions = isRecord(current.permissions) ? current.permissions : {}
@@ -81,9 +103,16 @@ export function planSessionDefaults(
   const memoryAbsent = !('autoMemoryEnabled' in current)
   if (memoryAbsent) next.autoMemoryEnabled = false
 
+  const preToolUse = planGuard ? wirePlanGuard(current.hooks) : undefined
+  if (preToolUse !== undefined) {
+    const hooks = isRecord(current.hooks) ? current.hooks : {}
+    next.hooks = { ...hooks, PreToolUse: preToolUse }
+  }
+
   const keys: SettingsKey[] = [
     { label: 'permissions.deny', changed: missing.length > 0 },
     { label: 'autoMemoryEnabled', changed: memoryAbsent },
+    { label: 'hooks.PreToolUse', changed: preToolUse !== undefined },
   ]
   return {
     keys,
@@ -97,10 +126,72 @@ export function planSessionDefaults(
   }
 }
 
+/**
+ * Claude Code reads an absent, empty, or `*` matcher as every tool, one of
+ * only name characters as exact names split on `|` or `,`, and any other as
+ * an unanchored regular expression, per its hooks reference.
+ */
+function matcherCovers(matcher: unknown, tool: string): boolean {
+  if (matcher === undefined || matcher === '' || matcher === '*') return true
+  if (typeof matcher !== 'string') return false
+  if (/^[\w\s,|-]+$/.test(matcher)) {
+    return matcher.split(/[|,]/).some((name) => name.trim() === tool)
+  }
+  try {
+    return new RegExp(matcher).test(tool)
+  } catch {
+    return false
+  }
+}
+
+function runsPlanGuard(group: unknown, tool: string): boolean {
+  if (!isRecord(group) || !Array.isArray(group.hooks)) return false
+  if (!matcherCovers(group.matcher, tool)) return false
+  return group.hooks.some(
+    (hook) =>
+      isRecord(hook) &&
+      typeof hook.command === 'string' &&
+      hook.command.includes(PLAN_GUARD_SCRIPT),
+  )
+}
+
+/**
+ * Returns the PreToolUse list with the guard appended to each seeded matcher
+ * lacking it, or undefined when every tool already runs it. An existing group
+ * under the seeded matcher takes the entry, keeping its own hooks first.
+ */
+function wirePlanGuard(hooks: unknown): unknown[] | undefined {
+  const current =
+    isRecord(hooks) && Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  const lacking = PLAN_GUARD_WIRING.filter(
+    ({ tool }) => !current.some((group) => runsPlanGuard(group, tool)),
+  )
+  if (lacking.length === 0) return undefined
+
+  const entry = { type: 'command', command: PLAN_GUARD_COMMAND }
+  const next = [...current]
+  for (const { matcher } of lacking) {
+    const at = next.findIndex(
+      (group) =>
+        isRecord(group) &&
+        group.matcher === matcher &&
+        Array.isArray(group.hooks),
+    )
+    const group = next[at]
+    if (isRecord(group) && Array.isArray(group.hooks)) {
+      next[at] = { ...group, hooks: [...group.hooks, entry] }
+    } else {
+      next.push({ matcher, hooks: [entry] })
+    }
+  }
+  return next
+}
+
 /**
  * Refuses rather than plans whenever a write could replace something the
  * person owns: the toolkit's own settings, a file `JSON.parse` cannot read,
- * or a `permissions` or `deny` value of an unexpected shape.
+ * or a `permissions`, `deny`, `hooks`, or `PreToolUse` value of an
+ * unexpected shape.
  */
 export async function readSessionDefaults(
   root: string,
@@ -138,11 +229,30 @@ export async function readSessionDefaults(
     }
   }
 
+  const planGuard = existsSync(
+    join(root, '.claude', 'hooks', PLAN_GUARD_SCRIPT),
+  )
+  const { hooks } = read.value
+  if (planGuard && hooks !== undefined && !isRecord(hooks)) {
+    return { kind: 'refused', reason: `${path}: hooks is not an object` }
+  }
+  if (
+    planGuard &&
+    isRecord(hooks) &&
+    hooks.PreToolUse !== undefined &&
+    !Array.isArray(hooks.PreToolUse)
+  ) {
+    return {
+      kind: 'refused',
+      reason: `${path}: hooks.PreToolUse is not a list`,
+    }
+  }
+
   return {
     kind: 'planned',
     path,
     indent: read.indent,
-    plan: planSessionDefaults(read.value),
+    plan: planSessionDefaults(read.value, { planGuard }),
   }
 }
 

package/src/take/encode.ts

@@ -97,11 +97,17 @@ export function openFrameEncoder(out: string, fps: number): FrameEncoder {
   }
 }
 
-/** Re-encodes a recorded clip to the same H.264 output at a constant `fps`. */
+/**
+ * Re-encodes a recorded clip to the same H.264 output at a constant `fps`, cut
+ * at `ms`. Playwright's recorder pads its webm past the last frame by at least
+ * a second, so the cut is what ends the clip where the take's clock stopped.
+ * A shorter input stays as it is, since `-t` never extends one.
+ */
 export async function transcode(
   input: string,
   out: string,
   fps: number,
+  ms: number,
 ): Promise<void> {
   const proc = spawn(
     'ffmpeg',
@@ -111,6 +117,8 @@ export async function transcode(
       'error',
       '-i',
       input,
+      '-t',
+      (ms / 1000).toFixed(3),
       '-r',
       String(fps),
       ...OUTPUT,

package/src/take/film.ts

@@ -11,7 +11,7 @@ import {
   type TakeLog,
   VIEWPORT,
 } from '@/take/log'
-import { TargetMissing } from '@/take/perform'
+import { TargetMissing, TargetOffscreen, TargetRefused } from '@/take/perform'
 import type { Beat, Route, TakePlan } from '@/take/plan'
 import { filmScreencast } from '@/take/screencast'
 import { ShellMissing, findShell } from '@/take/shell'
@@ -30,6 +30,8 @@ export type TakeRefusal =
   | 'browser-missing'
   | 'server-unreachable'
   | 'target-missing'
+  | 'target-offscreen'
+  | 'over-cap'
   | 'take-failed'
 
 export interface FilmedBeat {
@@ -74,6 +76,8 @@ export interface TakeRequest {
   readonly env?: NodeJS.ProcessEnv
   /** How long one stepped frame may take before its beat falls back to a screencast. */
   readonly stallMs?: number
+  /** The filmed seconds the beats may sum to, past which the take refuses. */
+  readonly maxSeconds?: number
 }
 
 const REACH_TIMEOUT_MS = 5000
@@ -127,7 +131,7 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
       )
     } catch (error) {
       const cause = error instanceof FellBack ? error.error : error
-      const shot = cause instanceof TargetMissing ? cause.still : undefined
+      const shot = cause instanceof TargetRefused ? cause.still : undefined
       const still = shot ? join(dir, 'still.jpg') : undefined
       if (shot && still) writeFileSync(join(out, still), shot)
       return {
@@ -136,6 +140,16 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
         ...(still ? { still } : {}),
       }
     }
+    // Checked after each beat rather than once at the end, so a take refused
+    // on its first beat films nothing past it.
+    const frames = beats.reduce((sum, filmed) => sum + filmed.frames, 0)
+    if (request.maxSeconds !== undefined && frames > request.maxSeconds * FPS) {
+      return failed(
+        'over-cap',
+        `the beats through ${beat.name} run ${(frames / FPS).toFixed(2)} s, past the ${request.maxSeconds} s cap`,
+        beat.name,
+      )
+    }
   }
 
   writeFileSync(
@@ -231,6 +245,7 @@ class FellBack extends Error {
 
 function classify(error: unknown): TakeRefusal {
   if (error instanceof TargetMissing) return 'target-missing'
+  if (error instanceof TargetOffscreen) return 'target-offscreen'
   if (error instanceof ShellMissing || isBrowserMissing(error)) {
     return 'browser-missing'
   }

package/src/take/fixtures/busy.html

@@ -0,0 +1,107 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Busy</title>
+    <!--
+      A hero canvas that redraws every frame and spends busy=<ms> of main
+      thread work on each, so a frame takes about that long to render. A card
+      sits about 2900px down, below the window, and the rail link scrolls to it.
+      With timed=1 each frame spins on performance.now() instead, as the
+      groundwork page did, which never ends once the stepper pauses virtual
+      time.
+    -->
+    <style>
+      html {
+        scroll-behavior: smooth;
+      }
+
+      body {
+        margin: 0;
+        font-family: sans-serif;
+      }
+
+      nav {
+        position: fixed;
+        top: 10px;
+        right: 10px;
+        z-index: 2;
+      }
+
+      nav a {
+        display: block;
+        padding: 12px 20px;
+        background: #fff;
+      }
+
+      canvas {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+      }
+
+      section {
+        height: 900px;
+        border-top: 1px solid #ccc;
+        padding: 40px;
+      }
+
+      .card {
+        width: 400px;
+        height: 240px;
+        background: #ddd;
+      }
+
+      .card:hover {
+        background: #f60;
+      }
+    </style>
+  </head>
+  <body>
+    <nav><a id="rail" href="#cards">Cards</a></nav>
+    <canvas id="hero"></canvas>
+    <section>one</section>
+    <section>two</section>
+    <section id="cards"><div class="card" id="card">card</div></section>
+    <section>four</section>
+    <script>
+      const params = new URLSearchParams(location.search)
+      const busy = Number(params.get('busy') || 0)
+      const timed = params.get('timed') === '1'
+      const hero = document.getElementById('hero')
+      hero.width = innerWidth
+      hero.height = innerHeight
+      const context = hero.getContext('2d')
+      // The work is a count calibrated in real time on load, since a loop
+      // timed by performance.now() never ends under a paused virtual clock.
+      let sink = 0
+      const spin = (count) => {
+        for (let i = 0; i < count; i += 1) sink += Math.sqrt(i)
+      }
+      const measure = (ms) => {
+        let count = 0
+        const start = performance.now()
+        while (performance.now() - start < ms) {
+          spin(10000)
+          count += 10000
+        }
+        return count / ms
+      }
+      // Warmed first, so the count matches the optimized loop a frame runs.
+      measure(100)
+      const work = Math.round(busy * measure(200))
+      const draw = (time) => {
+        if (timed) {
+          const start = performance.now()
+          while (performance.now() - start < busy) {}
+        } else {
+          spin(work)
+        }
+        context.fillStyle = `hsl(${(time / 10) % 360}, 60%, 50%)`
+        context.fillRect(0, 0, hero.width, hero.height)
+        requestAnimationFrame(draw)
+      }
+      requestAnimationFrame(draw)
+    </script>
+  </body>
+</html>

package/src/take/perform.ts

@@ -3,6 +3,7 @@ import {
   FPS,
   type LogEvent,
   type Point,
+  VIEWPORT,
   along,
   travelMs,
 } from '@/take/log'
@@ -74,13 +75,40 @@ export interface Stage {
   evaluate<T>(expression: string): Promise<T>
 }
 
-/** A target that resolved to nothing, which refuses rather than films a guess. */
-export class TargetMissing extends Error {
+/** A target the pointer cannot reach, which refuses rather than films a guess. */
+export class TargetRefused extends Error {
   /** The page as it stood when the lookup failed, as a JPEG, when the route caught one. */
   still?: Buffer
 
-  constructor(readonly target: string) {
-    super(`nothing on the page matches ${target}`)
+  constructor(
+    readonly target: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** A target that resolved to nothing. */
+export class TargetMissing extends TargetRefused {
+  constructor(target: string) {
+    super(target, `nothing on the page matches ${target}`)
+  }
+}
+
+/**
+ * A target whose center lies outside the window, so the pointer would aim at
+ * a point the clip never shows, or for a scroll, a target with no part inside
+ * it. A setup step brings it into view first.
+ */
+export class TargetOffscreen extends TargetRefused {
+  constructor(
+    target: string,
+    readonly at: Point,
+  ) {
+    super(
+      target,
+      `${target} is centered at (${Math.round(at.x)}, ${Math.round(at.y)}), outside the ${VIEWPORT.width}x${VIEWPORT.height} window, so a setup step must bring it into view first`,
+    )
   }
 }
 
@@ -155,19 +183,12 @@ export async function performSteps(
         break
       }
       case 'scroll': {
-        const at = center(await boxOf(stage, step.target))
+        const at = await scrollPoint(stage, step.target)
         await moveTo(stage, state, at)
         const frames = Math.round(SCROLL_MS / FRAME_MS)
-        state.log?.push({
-          t: stage.now(),
-          kind: 'scroll',
-          at,
-          dx: 0,
-          dy: step.dy,
-          ms: frames * FRAME_MS,
-        })
+        const start = stage.now()
         let sent = 0
-        for (let frame = 1; frame <= frames; frame += 1) {
+        await paced(stage, frames, async (frame) => {
           const want = along(
             { x: 0, y: 0 },
             { x: 0, y: step.dy },
@@ -175,7 +196,15 @@ export async function performSteps(
           ).y
           await stage.pointer({ type: 'wheel', ...at, dy: want - sent })
           sent = want
-        }
+        })
+        state.log?.push({
+          t: start,
+          kind: 'scroll',
+          at,
+          dx: 0,
+          dy: step.dy,
+          ms: stage.now() - start,
+        })
         break
       }
       case 'wait':
@@ -194,21 +223,35 @@ async function moveTo(
   const from = state.pointer
   if (Math.hypot(to.x - from.x, to.y - from.y) < 1) return
   const frames = Math.max(1, Math.round(travelMs(from, to) / FRAME_MS))
-  state.log?.push({
-    t: stage.now(),
-    kind: 'move',
-    from,
-    to,
-    ms: frames * FRAME_MS,
-  })
   const pressed = held
     ? { held: true as const, ...withModifiers(held.modifiers) }
     : {}
-  for (let frame = 1; frame <= frames; frame += 1) {
+  const start = stage.now()
+  await paced(stage, frames, async (frame) => {
     state.pointer = along(from, to, frame / frames)
     await stage.pointer({ type: 'move', ...state.pointer, ...pressed })
-  }
+  })
   state.pointer = to
+  state.log?.push({ t: start, kind: 'move', from, to, ms: stage.now() - start })
+}
+
+/**
+ * Runs a motion planned as `frames` inputs, sending each at the frame the
+ * stage's clock has reached, so a page slower than a frame per input skips the
+ * points it is behind on and the motion still ends near its planned length. A
+ * clock advancing one frame per input, as the stepper's does, gets every frame.
+ */
+async function paced(
+  stage: Stage,
+  frames: number,
+  input: (frame: number) => Promise<void>,
+): Promise<void> {
+  const start = stage.now()
+  for (let frame = 0; frame < frames;) {
+    const reached = Math.round((stage.now() - start) / FRAME_MS)
+    frame = Math.min(frames, Math.max(frame + 1, reached + 1))
+    await input(frame)
+  }
 }
 
 async function click(
@@ -315,12 +358,43 @@ function center(box: Box): Point {
   return { x: box.x + box.width / 2, y: box.y + box.height / 2 }
 }
 
-async function boxOf(stage: Stage, target: string): Promise<Box> {
+function inWindow(at: Point): boolean {
+  return (
+    at.x >= 0 && at.x <= VIEWPORT.width && at.y >= 0 && at.y <= VIEWPORT.height
+  )
+}
+
+async function foundBox(stage: Stage, target: string): Promise<Box> {
   const box = await stage.evaluate<Box | null>(boxExpression(target))
   if (!box) throw new TargetMissing(target)
   return box
 }
 
+async function boxOf(stage: Stage, target: string): Promise<Box> {
+  const box = await foundBox(stage, target)
+  const at = center(box)
+  if (!inWindow(at)) throw new TargetOffscreen(target, at)
+  return box
+}
+
+/**
+ * Aims a wheel at the target's center, or, when that lies outside the window,
+ * at the center of the part the window shows. A wheel scrolls whatever sits
+ * under it, so any visible point of the target serves, and a page-tall element
+ * such as `body` has a center no setup step can bring into view.
+ */
+async function scrollPoint(stage: Stage, target: string): Promise<Point> {
+  const box = await foundBox(stage, target)
+  const at = center(box)
+  if (inWindow(at)) return at
+  const left = Math.max(box.x, 0)
+  const right = Math.min(box.x + box.width, VIEWPORT.width)
+  const top = Math.max(box.y, 0)
+  const bottom = Math.min(box.y + box.height, VIEWPORT.height)
+  if (right <= left || bottom <= top) throw new TargetOffscreen(target, at)
+  return { x: (left + right) / 2, y: (top + bottom) / 2 }
+}
+
 /**
  * Finds a target's box in CSS pixels, reading `text=<words>` as the first
  * innermost element with a size whose whole text is those words, so a hidden

package/src/take/screencast.ts

@@ -7,7 +7,7 @@ import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
 import {
   type PointerInput,
   type Stage,
-  TargetMissing,
+  TargetRefused,
   performSteps,
 } from '@/take/perform'
 import type { Beat } from '@/take/plan'
@@ -92,13 +92,14 @@ export async function filmScreencast(request: {
       log: events,
     })
     await recording.hold(HOLD_MS)
+    const filmedMs = recording.now()
     await page.screencast.stop()
 
-    await transcode(webm, request.clip, FPS)
+    await transcode(webm, request.clip, FPS, filmedMs)
     const frames = await probeFrames(request.clip)
     return { frames, events, still: await lastFrame(request.clip, frames) }
   } catch (error) {
-    if (error instanceof TargetMissing && still) error.still = await still()
+    if (error instanceof TargetRefused && still) error.still = await still()
     throw error
   } finally {
     await browser.close()

package/src/take/stepper.ts

@@ -5,7 +5,7 @@ import {
   type KeyInput,
   type PointerInput,
   type Stage,
-  TargetMissing,
+  TargetRefused,
   performSteps,
 } from '@/take/perform'
 import type { Beat } from '@/take/plan'
@@ -25,7 +25,10 @@ import { type ShellPage, openShell } from '@/take/shell'
  * - Frame time continues Chromium's monotonic clock, since a frame stamped on
  *   any other base leaves every CSS animation at its first frame
  * - No frame is begun before the load event, since one sent mid-navigation can
- *   go unanswered, and each loading frame is capped so a lost one cannot hang
+ *   go unanswered
+ * - A frame is begun only once the one before it settles, since Chromium
+ *   refuses a second while one is pending, and a frame left pending past the
+ *   stall limit falls the beat back rather than hanging it
  */
 
 const FRAME_MS = 1000 / FPS
@@ -41,7 +44,6 @@ export const HOLD_MS = 600
 
 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
@@ -81,19 +83,25 @@ export async function filmStepped(
   let still: (() => Promise<Buffer | undefined>) | undefined
   try {
     let ticks = await load(page, request.url)
-    const beginFrame = (screenshot: boolean) =>
-      page.send<{ screenshotData?: string }>(
-        'HeadlessExperimental.beginFrame',
-        {
-          frameTimeTicks: (ticks += FRAME_MS),
-          interval: FRAME_MS,
-          ...(screenshot
-            ? { screenshot: { format: 'jpeg', quality: 95 } }
-            : {}),
-        },
+    let outstanding: Promise<unknown> = Promise.resolve()
+    const beginFrame = (screenshot: boolean) => {
+      const reply = outstanding.then(() =>
+        page.send<{ screenshotData?: string }>(
+          'HeadlessExperimental.beginFrame',
+          {
+            frameTimeTicks: (ticks += FRAME_MS),
+            interval: FRAME_MS,
+            ...(screenshot
+              ? { screenshot: { format: 'jpeg', quality: 95 } }
+              : {}),
+          },
+        ),
       )
+      outstanding = reply.catch(() => {})
+      return reply
+    }
     still = () => frameStill(beginFrame)
-    await pump(beginFrame, SETTLE_MS)
+    await pump(beginFrame, SETTLE_MS, stallMs)
 
     const live = liveStage(page, beginFrame, stallMs)
     await performSteps(live, request.beat.setup, { pointer: START })
@@ -163,7 +171,7 @@ export async function filmStepped(
     return { frames, events, still: last }
   } catch (error) {
     encoder.abort()
-    if (error instanceof TargetMissing && still) error.still = await still()
+    if (error instanceof TargetRefused && still) error.still = await still()
     throw error
   } finally {
     page.close()
@@ -215,17 +223,22 @@ async function load(page: ShellPage, url: string): Promise<number> {
   return timestamp
 }
 
-/** Begins frames in real time so loading, fonts, and layout settle. */
+/**
+ * Begins frames in real time so loading, fonts, and layout settle. Each frame
+ * is awaited, so a slow page stretches the settle rather than overlapping it.
+ */
 async function pump(
   beginFrame: (screenshot: boolean) => Promise<unknown>,
   ms: number,
+  stallMs: number,
 ): Promise<void> {
   const end = Date.now() + ms
   while (Date.now() < end) {
-    await Promise.race([
+    await withinStall(
       beginFrame(false).catch(() => {}),
-      sleep(LOADING_FRAME_CAP_MS),
-    ])
+      0,
+      stallMs,
+    )
     await sleep(12)
   }
 }
@@ -242,7 +255,7 @@ function liveStage(
   const started = Date.now()
   return {
     now: () => Date.now() - started,
-    hold: (ms) => pump(beginFrame, ms),
+    hold: (ms) => pump(beginFrame, ms, stallMs),
     pointer: (input) => {
       const sent = page.send('Input.dispatchMouseEvent', mouseEvent(input))
       return withinStall(