@erclx/canon 5.67.0 → 5.69.0

package/src/sandbox/headless/dispatch.ts

@@ -8,6 +8,11 @@ import {
 } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DISPATCH_SHIM = fileURLToPath(
+  new URL('dispatch-shim.sh', import.meta.url),
+)
 
 /*
  * The bound on a nested background dispatch, and the recording behind it.
@@ -31,9 +36,11 @@ import { join } from 'node:path'
  * The prevention. Writes a `claude` that refuses a background dispatch by flag
  * name and delegates everything else, for the runner to place first on the PATH
  * of the session it spawns. It stays a bash file, since it stands in for a
- * binary any shell in the session may exec.
+ * binary any shell in the session may exec. The refusal lives in
+ * `dispatch-shim.sh`, so the shell gate lints it, and the `claude` written here
+ * is a two-line wrapper that runs it with the real binary as its first argument.
  *
- * The real binary is baked into the file rather than passed through the
+ * The real binary is baked into the wrapper rather than passed through the
  * environment. An env var carrying it would sit in the spawned session's own
  * environment, which hands any arm the exact string that walks around the shim.
  *
@@ -46,22 +53,13 @@ import { join } from 'node:path'
  * backstops.
  */
 export function installDispatchShim(dir: string, real: string): void {
-  const shim = [
+  const wrapper = [
     '#!/usr/bin/env bash',
-    '# Generated by installDispatchShim in src/sandbox/headless/dispatch.ts.',
-    'for arg in "$@"; do',
-    '  case "$arg" in',
-    '  --bg | --background)',
-    '    echo "canon sandbox harness: refusing $arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2',
-    '    exit 64',
-    '    ;;',
-    '  esac',
-    'done',
-    `exec ${shellQuote(real)} "$@"`,
+    `exec bash ${shellQuote(DISPATCH_SHIM)} ${shellQuote(real)} "$@"`,
     '',
   ].join('\n')
 
-  writeFileSync(join(dir, 'claude'), shim, 'utf8')
+  writeFileSync(join(dir, 'claude'), wrapper, 'utf8')
   chmodSync(join(dir, 'claude'), 0o755)
 }
 

package/src/sandbox/stub-gh.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# stub gh
+dir="$STUB_GH_DIR"
+line="$(printf '%q ' "$@")"
+line="${line% }"
+printf '%s\n' "$line" >>"$dir/gh.log"
+
+case "$1" in
+api) exit 0 ;;
+pr)
+  case "$2" in
+  create)
+    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
+    count=$((count + 1))
+    echo "$count" >"$dir/pr-count"
+    echo "https://github.com/$GITHUB_ORG/$STUB_GH_REPO/pull/$count"
+    exit 0
+    ;;
+  close | list) exit 0 ;;
+  esac
+  ;;
+esac
+
+printf '%s\n' "$line" >>"$dir/gh-unknown.log"
+echo "stub gh: unknown call: $line" >&2
+exit 1

package/src/sandbox/stub-remote.ts

@@ -1,14 +1,15 @@
 import { execFileSync } from 'node:child_process'
 import {
   chmodSync,
+  copyFileSync,
   existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
   rmSync,
-  writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 const STUB_ORG = 'stub-org'
 const ANCHOR_REPO = 'canon-sandbox'
@@ -26,34 +27,11 @@ const PINNED_DATE = '2026-01-01T00:00:00Z'
  * Answers the `gh` calls the git scenarios make and fails on any other, so a new
  * call reaches a reader as a red arm rather than a silent pass. Every call is
  * logged as one line, quoted so an argument holding a space stays one argument.
+ * The pull request URL it prints reads `GITHUB_ORG` and `STUB_GH_REPO` from the
+ * environment `createStubRemote` returns, so it follows `STUB_ORG` and
+ * `ANCHOR_REPO`.
  */
-const STUB_GH = `#!/usr/bin/env bash
-# stub gh
-dir="$STUB_GH_DIR"
-line="$(printf '%q ' "$@")"
-line="\${line% }"
-printf '%s\\n' "$line" >>"$dir/gh.log"
-
-case "$1" in
-api) exit 0 ;;
-pr)
-  case "$2" in
-  create)
-    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
-    count=$((count + 1))
-    echo "$count" >"$dir/pr-count"
-    echo "https://github.com/${STUB_ORG}/${ANCHOR_REPO}/pull/$count"
-    exit 0
-    ;;
-  close | list) exit 0 ;;
-  esac
-  ;;
-esac
-
-printf '%s\\n' "$line" >>"$dir/gh-unknown.log"
-echo "stub gh: unknown call: $line" >&2
-exit 1
-`
+const STUB_GH = fileURLToPath(new URL('stub-gh.sh', import.meta.url))
 
 /**
  * Builds a local bare repository and a stub `gh` under `stubDir` and returns the
@@ -75,13 +53,14 @@ export function createStubRemote(stubDir: string): Record<string, string> {
   )
 
   const gh = join(bin, 'gh')
-  writeFileSync(gh, STUB_GH)
+  copyFileSync(STUB_GH, gh)
   chmodSync(gh, 0o755)
 
   return {
     PATH: `${bin}:${process.env.PATH ?? ''}`,
     STUB_GH_DIR: stubDir,
     GITHUB_ORG: STUB_ORG,
+    STUB_GH_REPO: ANCHOR_REPO,
     GIT_CONFIG_COUNT: '1',
     GIT_CONFIG_KEY_0: `url.${remotes}/.insteadOf`,
     GIT_CONFIG_VALUE_0: `https://github.com/${STUB_ORG}/`,

package/src/sync/engine.ts

@@ -545,7 +545,7 @@ function reportCoverage(coverage: readonly RuleCoverage[]): void {
   for (const entry of coverage) {
     logInfo(describeCoverage(entry))
     if (entry.ui) {
-      logInfo('  Audit those files with /canon:ux-audit.')
+      logInfo('  Audit those files with /canon:ui-audit.')
     }
   }
 }

package/src/take/camera.ts

@@ -20,8 +20,8 @@ import {
 
 /**
  * Turns a take's log into one camera per frame, preset O4 from groundwork
- * track `193-ui-record`: OpenScreen's timing aimed at each click, a fixed
- * depth, a focus that holds still until a click leaves the inner part of the
+ * track `193-ui-record`, a folder name kept as written (canon-keep-retired).
+ * The preset is OpenScreen's timing aimed at each click, a fixed depth, a focus that holds still until a click leaves the inner part of the
  * view, and a dead zone that keeps the cursor in frame. HyperFrames renders the
  * track as it stands, so it carries no curve a renderer would have to agree on.
  */

package/src/take/encode.ts

@@ -154,7 +154,44 @@ export async function probeFrames(clip: string): Promise<number> {
   return frames
 }
 
-function finished(proc: ChildProcess): Promise<void> {
+/**
+ * Reads the clip's closing frame as one JPEG. It selects the frame by index
+ * rather than seeking from the end, since a seek lands on whichever frame
+ * the container's timing puts nearest, which was measured missing the last.
+ */
+export async function lastFrame(clip: string, frames: number): Promise<Buffer> {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-v',
+      'error',
+      '-i',
+      clip,
+      '-vf',
+      `select=eq(n\\,${frames - 1})`,
+      '-frames:v',
+      '1',
+      '-q:v',
+      '2',
+      '-f',
+      'image2pipe',
+      '-c:v',
+      'mjpeg',
+      '-',
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  const chunks: Buffer[] = []
+  proc.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk))
+  await finished(proc)
+  const jpeg = Buffer.concat(chunks)
+  if (jpeg.length === 0) {
+    throw new Error(`ffmpeg read no frame ${frames - 1} from ${clip}`)
+  }
+  return jpeg
+}
+
+export function finished(proc: ChildProcess): Promise<void> {
   let stderr = ''
   proc.stderr?.on('data', (chunk: Buffer) => {
     stderr += chunk.toString()

package/src/take/film.ts

@@ -44,6 +44,8 @@ export interface FilmedBeat {
   readonly clip: string
   readonly log: string
   readonly camera: string
+  /** The clip's closing frame, as a JPEG. */
+  readonly still: string
 }
 
 export type TakeResult =
@@ -65,6 +67,8 @@ export interface TakeRequest {
   readonly plan: TakePlan
   readonly out: string
   readonly env?: NodeJS.ProcessEnv
+  /** How long one stepped frame may take before its beat falls back to a screencast. */
+  readonly stallMs?: number
 }
 
 const REACH_TIMEOUT_MS = 5000
@@ -106,7 +110,16 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
     const dir = `${String(index + 1).padStart(2, '0')}-${slug(beat.name)}`
     mkdirSync(join(out, dir), { recursive: true })
     try {
-      beats.push(await filmBeat(request.url, beat, out, dir, executable))
+      beats.push(
+        await filmBeat(
+          request.url,
+          beat,
+          out,
+          dir,
+          executable,
+          request.stallMs,
+        ),
+      )
     } catch (error) {
       return failed(classify(error), error, beat.name)
     }
@@ -125,16 +138,23 @@ async function filmBeat(
   out: string,
   dir: string,
   executable: string,
+  stallMs: number | undefined,
 ): Promise<FilmedBeat> {
   const clip = join(dir, 'clip.mp4')
   const target = join(out, clip)
 
   let route: Route = beat.route
   let fallback: string | undefined
-  let filmed: { frames: number; events: readonly LogEvent[] }
+  let filmed: { frames: number; events: readonly LogEvent[]; still: Buffer }
   if (beat.route === 'step') {
     try {
-      filmed = await filmStepped({ executable, url, beat, clip: target })
+      filmed = await filmStepped({
+        executable,
+        url,
+        beat,
+        clip: target,
+        stallMs,
+      })
     } catch (error) {
       if (!(error instanceof StepperStalled)) throw error
       route = 'screencast'
@@ -158,6 +178,8 @@ async function filmBeat(
   // One line, since it carries a row per frame and nobody reads it by eye.
   const cameraPath = join(dir, 'camera.json')
   writeFileSync(join(out, cameraPath), `${JSON.stringify(cameraTrack(log))}\n`)
+  const stillPath = join(dir, 'still.jpg')
+  writeFileSync(join(out, stillPath), filmed.still)
 
   return {
     name: beat.name,
@@ -170,6 +192,7 @@ async function filmBeat(
     clip,
     log: logPath,
     camera: cameraPath,
+    still: stillPath,
   }
 }
 

package/src/take/pointer.ts

@@ -0,0 +1,169 @@
+import type { Point } from '@/take/log'
+
+/**
+ * Draws the cursor arrow and the click ring onto one decoded frame, in the
+ * shape groundwork track `193-ui-record` rendered them (canon-keep-retired):
+ * a dark arrow outlined
+ * in white, and a blue ring that grows from its tip and fades out. Both stay
+ * one size whatever the frame shows, so the pointer reads the same in every
+ * beat of a reel. Drawn in TypeScript rather than a browser, so the reel needs
+ * no page and no seek, and a test can read the pixels it leaves.
+ */
+
+export interface Frame {
+  /** RGBA, four bytes a pixel, row by row. */
+  readonly data: Uint8Array
+  readonly width: number
+  readonly height: number
+}
+
+/** The arrow, relative to its tip, from the groundwork's 24 px cursor path. */
+const ARROW: readonly Point[] = [
+  { x: 0, y: 0 },
+  { x: 0, y: 17 },
+  { x: 4.5, y: 12.5 },
+  { x: 7.5, y: 19 },
+  { x: 10, y: 18 },
+  { x: 7, y: 11.5 },
+  { x: 13.5, y: 11.5 },
+]
+
+const ARROW_FILL = [17, 17, 17] as const
+const ARROW_STROKE = [255, 255, 255] as const
+const STROKE_HALF = 0.75
+
+/** The ring's outer radius at full size, and its stroke at that size. */
+export const RING_RADIUS = 18
+const RING_STROKE = 2
+const RING_COLOR = [37, 99, 235] as const
+/** The ring starts at this share of its size and grows by the expansion. */
+const RING_START = 0.4
+
+/**
+ * Draws the pointer with its tip at `at`, in the frame's own pixels, and the
+ * ring around it when `ring` is a 0 to 1 expansion. The ring sits under the
+ * arrow, and anything past the frame's edge is clipped.
+ */
+export function drawPointer(
+  frame: Frame,
+  at: Point,
+  ring: number | null,
+): void {
+  if (ring !== null) drawRing(frame, at, ring)
+  drawArrow(frame, at)
+}
+
+function drawRing(frame: Frame, at: Point, ring: number): void {
+  const scale = RING_START + ring
+  const stroke = RING_STROKE * scale
+  const middle = RING_RADIUS * scale - stroke / 2
+  const opacity = 1 - ring
+  if (opacity <= 0) return
+
+  const reach = RING_RADIUS * scale + 1
+  forEachPixel(frame, at, reach, reach, reach, reach, (px, py) => {
+    const distance = Math.hypot(px - at.x, py - at.y)
+    const coverage = clamp01(stroke / 2 + 0.5 - Math.abs(distance - middle))
+    return coverage > 0
+      ? { color: RING_COLOR, alpha: coverage * opacity }
+      : null
+  })
+}
+
+function drawArrow(frame: Frame, at: Point): void {
+  const reach = STROKE_HALF + 1
+  forEachPixel(frame, at, reach, 13.5 + reach, reach, 19 + reach, (px, py) => {
+    const d = signedDistance({ x: px - at.x, y: py - at.y })
+    // Coverage of the outlined shape, then of the fill inside the outline,
+    // each antialiased across one pixel.
+    const outer = clamp01(0.5 - (d - STROKE_HALF))
+    if (outer <= 0) return null
+    const inner = clamp01(0.5 - (d + STROKE_HALF))
+    return {
+      color: ARROW_STROKE,
+      alpha: outer,
+      over: ARROW_FILL,
+      overAlpha: inner,
+    }
+  })
+}
+
+interface Paint {
+  readonly color: readonly [number, number, number]
+  readonly alpha: number
+  /** A second color laid over the first, for the fill inside the outline. */
+  readonly over?: readonly [number, number, number]
+  readonly overAlpha?: number
+}
+
+/**
+ * Calls `paint` for each pixel center inside the box around `at`, clipped to
+ * the frame, and blends whatever it returns onto that pixel.
+ */
+function forEachPixel(
+  frame: Frame,
+  at: Point,
+  left: number,
+  right: number,
+  up: number,
+  down: number,
+  paint: (x: number, y: number) => Paint | null,
+): void {
+  const x0 = Math.max(0, Math.floor(at.x - left))
+  const x1 = Math.min(frame.width - 1, Math.ceil(at.x + right))
+  const y0 = Math.max(0, Math.floor(at.y - up))
+  const y1 = Math.min(frame.height - 1, Math.ceil(at.y + down))
+  for (let y = y0; y <= y1; y += 1) {
+    for (let x = x0; x <= x1; x += 1) {
+      const result = paint(x + 0.5, y + 0.5)
+      if (!result) continue
+      const i = (y * frame.width + x) * 4
+      blend(frame.data, i, result.color, result.alpha)
+      if (result.over && result.overAlpha) {
+        blend(frame.data, i, result.over, result.overAlpha)
+      }
+    }
+  }
+}
+
+function blend(
+  data: Uint8Array,
+  i: number,
+  color: readonly [number, number, number],
+  alpha: number,
+): void {
+  for (let c = 0; c < 3; c += 1) {
+    const base = data[i + c] ?? 0
+    data[i + c] = Math.round(base + ((color[c] ?? 0) - base) * alpha)
+  }
+}
+
+/** Distance from `p` to the arrow's outline, negative inside it. */
+function signedDistance(p: Point): number {
+  let nearest = Number.POSITIVE_INFINITY
+  let inside = false
+  for (let i = 0, j = ARROW.length - 1; i < ARROW.length; j = i, i += 1) {
+    const a = ARROW[j] ?? ARROW[0]
+    const b = ARROW[i] ?? ARROW[0]
+    if (!a || !b) continue
+    nearest = Math.min(nearest, segmentDistance(p, a, b))
+    if (
+      a.y > p.y !== b.y > p.y &&
+      p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x
+    ) {
+      inside = !inside
+    }
+  }
+  return inside ? -nearest : nearest
+}
+
+function segmentDistance(p: Point, a: Point, b: Point): number {
+  const dx = b.x - a.x
+  const dy = b.y - a.y
+  const k = clamp01(((p.x - a.x) * dx + (p.y - a.y) * dy) / (dx * dx + dy * dy))
+  return Math.hypot(p.x - (a.x + k * dx), p.y - (a.y + k * dy))
+}
+
+function clamp01(value: number): number {
+  return Math.min(Math.max(value, 0), 1)
+}

package/src/take/reel.ts

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process'
+import { readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { CameraTrack } from '@/take/camera'
+import { finished } from '@/take/encode'
+import type { FilmedBeat } from '@/take/film'
+import { FPS } from '@/take/log'
+import { type Frame, drawPointer } from '@/take/pointer'
+
+/**
+ * Joins a take's beats into one short reel for a pull request: each beat's
+ * clip shrunk to one width, every third frame kept, the pointer drawn from its
+ * camera track, encoded as an animated WebP that GitHub plays inline. It
+ * draws the pointer and nothing else, since the zoom, captions, and cuts are
+ * the edit's work for a launch video.
+ */
+
+export const REEL_WIDTH = 960
+
+/** How many take frames each reel frame stands for, 60 fps down to 20. */
+export const REEL_EVERY = 3
+
+export const REEL_FPS = FPS / REEL_EVERY
+
+/** WebP quality, measured at about 1.4 MB for a 9 s reel at this width. */
+const QUALITY = 60
+
+export interface ReelFrame extends Frame {
+  /** Which beat of the take, in plan order. */
+  readonly beat: number
+  /** The frame's place in its beat, which draws camera frame `index * REEL_EVERY`. */
+  readonly index: number
+}
+
+export interface Reel {
+  readonly file: string
+  readonly frames: number
+  readonly seconds: number
+  readonly bytes: number
+}
+
+/**
+ * Yields every reel frame in order with the pointer drawn on it. The decoder
+ * keeps frames by index rather than by timestamp, since an `fps` filter that
+ * rounds timestamps drifts the pointer off what it pressed.
+ */
+export async function* reelFrames(
+  out: string,
+  beats: readonly FilmedBeat[],
+): AsyncGenerator<ReelFrame> {
+  for (const [beat, filmed] of beats.entries()) {
+    const camera = JSON.parse(
+      readFileSync(join(out, filmed.camera), 'utf8'),
+    ) as CameraTrack
+    const { width, height } = reelSize(camera)
+    // The camera is in CSS pixels of the page, and every route's clip shrinks
+    // to the same width, so one factor places the pointer on either.
+    const factor = width / camera.viewport.width
+
+    let index = 0
+    for await (const data of decode(join(out, filmed.clip), width, height)) {
+      const at =
+        camera.frames[Math.min(index * REEL_EVERY, camera.frames.length - 1)]
+      const frame = { data, width, height, beat, index }
+      if (at) {
+        drawPointer(
+          frame,
+          { x: at.cursor.x * factor, y: at.cursor.y * factor },
+          at.ring,
+        )
+      }
+      yield frame
+      index += 1
+    }
+  }
+}
+
+/** Renders the reel of a filmed take to `file`, an animated WebP. */
+export async function renderReel(
+  out: string,
+  beats: readonly FilmedBeat[],
+  file: string,
+): Promise<Reel> {
+  const first = beats[0]
+  if (!first) throw new Error('a reel needs at least one filmed beat')
+  const { width, height } = reelSize(
+    JSON.parse(readFileSync(join(out, first.camera), 'utf8')) as CameraTrack,
+  )
+
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-y',
+      '-loglevel',
+      'error',
+      '-f',
+      'rawvideo',
+      '-pix_fmt',
+      'rgba',
+      '-s',
+      `${width}x${height}`,
+      '-framerate',
+      String(REEL_FPS),
+      '-i',
+      '-',
+      '-c:v',
+      'libwebp_anim',
+      '-quality',
+      String(QUALITY),
+      '-loop',
+      '0',
+      '-f',
+      'webp',
+      file,
+    ],
+    { stdio: ['pipe', 'ignore', 'pipe'] },
+  )
+  const done = finished(proc)
+  // Held so an encoder that dies mid-stream surfaces through `done` rather than
+  // as an unhandled rejection or a broken pipe thrown out of the stream.
+  done.catch(() => {})
+  proc.stdin?.on('error', () => {})
+
+  let frames = 0
+  try {
+    for await (const frame of reelFrames(out, beats)) {
+      // Raced against the exit, since a write waiting on a drain from an
+      // encoder that already died would wait forever.
+      await Promise.race([write(proc.stdin, frame.data), done])
+      frames += 1
+    }
+  } catch (error) {
+    proc.kill('SIGKILL')
+    throw error
+  }
+  proc.stdin?.end()
+  await done
+
+  return {
+    file,
+    frames,
+    seconds: Number((frames / REEL_FPS).toFixed(2)),
+    bytes: statSync(file).size,
+  }
+}
+
+function reelSize(camera: CameraTrack): { width: number; height: number } {
+  const height =
+    Math.round(
+      (REEL_WIDTH * camera.viewport.height) / camera.viewport.width / 2,
+    ) * 2
+  return { width: REEL_WIDTH, height }
+}
+
+/** Decodes every `REEL_EVERY`th frame of a clip as RGBA at the reel's size. */
+async function* decode(
+  clip: string,
+  width: number,
+  height: number,
+): AsyncGenerator<Uint8Array> {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-loglevel',
+      'error',
+      '-i',
+      clip,
+      '-vf',
+      `select='not(mod(n\\,${REEL_EVERY}))',scale=${width}:${height}:flags=area`,
+      '-fps_mode',
+      'passthrough',
+      '-f',
+      'rawvideo',
+      '-pix_fmt',
+      'rgba',
+      '-',
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  const done = finished(proc)
+  done.catch(() => {})
+
+  const size = width * height * 4
+  let pending: Buffer = Buffer.alloc(0)
+  let drained = false
+  try {
+    for await (const chunk of proc.stdout as AsyncIterable<Buffer>) {
+      pending = pending.length ? Buffer.concat([pending, chunk]) : chunk
+      while (pending.length >= size) {
+        // Copied out, since the frame is drawn on and outlives the chunk.
+        yield new Uint8Array(pending.subarray(0, size))
+        pending = pending.subarray(size)
+      }
+    }
+    drained = true
+  } finally {
+    // A reader that stopped early leaves FFmpeg decoding into a full pipe.
+    if (!drained) proc.kill('SIGKILL')
+  }
+  await done
+}
+
+function write(
+  stdin: NodeJS.WritableStream | null,
+  data: Uint8Array,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!stdin) {
+      reject(new Error('ffmpeg stopped reading frames'))
+      return
+    }
+    if (stdin.write(data)) resolve()
+    else stdin.once('drain', () => resolve())
+  })
+}