@erclx/canon 5.69.0 → 5.70.0

package/src/sandbox/expect.ts

@@ -44,7 +44,15 @@ export interface AssertionResult {
  */
 export interface RunEnvelope {
   readonly isError: boolean
+  /** The runner cap ended the run, read from `subtype` rather than `turns`. */
+  readonly isTruncated: boolean
   readonly turns: number
+  /**
+   * The cap the run ran under. `num_turns` counts more than the cap does, so
+   * an untruncated run can report past it, and a ceiling at or above the cap
+   * is held by `isTruncated` instead. A non-finite value reads as absent.
+   */
+  readonly turnCap?: number
   readonly denials: number
   readonly reply?: string
 }
@@ -487,6 +495,23 @@ function checkReply(
   }
 }
 
+function isFiniteCap(turnCap: number | undefined): turnCap is number {
+  return turnCap !== undefined && Number.isFinite(turnCap)
+}
+
+function capped(turnCap: number | undefined): string {
+  return isFiniteCap(turnCap) ? ` of ${turnCap} turns` : ''
+}
+
+/**
+ * A ceiling below the cap was declared in `num_turns` and is compared in it. One
+ * at or above the cap skips with no result, since emitting a pass would let the
+ * envelope pass a run.
+ */
+function isBelowCap(maxTurns: number, turnCap: number | undefined): boolean {
+  return !isFiniteCap(turnCap) || maxTurns < turnCap
+}
+
 /**
  * The envelope never determines a pass. It can only fail a run the expectations
  * would otherwise have passed. Under `bypassPermissions` the denial count is
@@ -516,8 +541,15 @@ function checkEnvelope(
       message: `envelope: ${envelope.denials} permission denials`,
     })
   }
+  if (envelope.isTruncated) {
+    results.push({
+      ok: false,
+      message: `envelope: truncated by the runner cap${capped(envelope.turnCap)}`,
+    })
+  }
   if (
     expectation.maxTurns !== undefined &&
+    isBelowCap(expectation.maxTurns, envelope.turnCap) &&
     envelope.turns > expectation.maxTurns
   ) {
     results.push({

package/src/sandbox/headless/run.ts

@@ -45,9 +45,12 @@ import {
  *
  * `maxTurns` is the only budget. `max_turns` in an arm's `expect.toml` is a
  * ceiling asserted after the run, not a cap enforced during it, so a
- * declaration cannot raise what it runs under. An arm needing more than this
- * truncates, and a truncated run fails the same assertions a reasoning miss
- * does with nothing to separate them.
+ * declaration cannot raise what it runs under. A truncated run exits 1 with
+ * `subtype` `error_max_turns`, which `canon sandbox check` fails by name.
+ * `num_turns` counts more than this cap does, so a ceiling at or above it is
+ * held by the cap and compares nothing. The check reads the cap from its own
+ * environment, so a run under a raised cap, checked later by hand without the
+ * variable, reads the default.
  *
  * `bypassPermissions` is the only mode that lets a run write under `.claude/`,
  * which most arms need. The scoping the permission layer would have given

package/src/take/camera.ts

@@ -1,5 +1,6 @@
 import {
   type Box,
+  CLIP_SIZES,
   type LogEvent,
   type Point,
   type TakeLog,
@@ -21,7 +22,7 @@ import {
 /**
  * Turns a take's log into one camera per frame, preset O4 from groundwork
  * 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
+ * The preset is OpenScreen's timing aimed at each click, a fixed depth the clip's resolution caps, 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.
  */
@@ -31,6 +32,13 @@ export const CAMERA_VERSION = 1
 /** The depth every click zooms to, unless its target already fills the view. */
 const DEPTH = 1.8
 
+/**
+ * How far a clip with one pixel per CSS pixel zooms before it goes soft, which
+ * caps a screencast's depth well under `DEPTH` and leaves the stepper's 4K
+ * clip at it.
+ */
+const SHARP_DEPTH = 1.35
+
 /** How much of the zoomed view a target may fill, which caps the depth for a big one. */
 const FILL = 0.8
 
@@ -57,6 +65,13 @@ const EDGE = 0.9
 /** How long the click ring the edit draws takes to expand. */
 const RING_MS = 450
 
+/**
+ * How far a drag's ring grows before it holds for the drag, then runs on to 1
+ * from the release. A held value keeps the ring's one field, so every reader
+ * drawing a growing ring draws a held press with no change.
+ */
+const GRAB_RING = 0.3
+
 export interface CameraFrame {
   readonly ms: number
   /** How far the view is zoomed, 1 being the whole page. */
@@ -91,16 +106,30 @@ interface Window {
   readonly aims: Aim[]
 }
 
-export function cameraTrack(log: TakeLog): CameraTrack {
+export interface CameraOptions {
+  /**
+   * How much faster the edit plays the clip, so the track is built on the
+   * playback clock and a zoom settles at the speed a viewer sees. 1 by default.
+   */
+  readonly rate?: number
+}
+
+export function cameraTrack(
+  source: TakeLog,
+  options: CameraOptions = {},
+): CameraTrack {
+  const log = atRate(source, options.rate ?? 1)
   const { width, height } = log.viewport
+  const clip = log.clip ?? CLIP_SIZES[log.route]
+  const deepest = Math.min(DEPTH, (SHARP_DEPTH * clip.width) / width)
   const depthFor = (box: Box): number =>
     Math.min(
-      DEPTH,
+      deepest,
       (width * FILL) / Math.max(box.width, 1),
       (height * FILL) / Math.max(box.height, 1),
     )
 
-  const aims: Aim[] = log.events
+  const aims: Aim[] = (log.push === false ? [] : log.events)
     .flatMap((event): Aim[] => {
       if (event.kind === 'click') {
         return [
@@ -112,6 +141,19 @@ export function cameraTrack(log: TakeLog): CameraTrack {
           },
         ]
       }
+      if (event.kind === 'drag') {
+        // One aim over both ends, held to the release, so a short drag stays
+        // framed whole and a long one asks for a depth under MIN_ZOOM.
+        const box = union(event.box, event.drop)
+        return [
+          {
+            t: event.t,
+            until: event.t + event.ms,
+            at: { x: box.x + box.width / 2, y: box.y + box.height / 2 },
+            depth: depthFor(box),
+          },
+        ]
+      }
       if (event.kind === 'type') {
         const box = event.box
         return [
@@ -129,9 +171,26 @@ export function cameraTrack(log: TakeLog): CameraTrack {
     .sort((a, b) => a.t - b.t)
 
   const scrolls = log.events.filter((event) => event.kind === 'scroll')
-  // Read off every click rather than off the aims, which drop a click too large
+  // Read off every press rather than off the aims, which drop a click too large
   // to zoom and add a typing burst that is no press.
-  const clicks = log.events.filter((event) => event.kind === 'click')
+  const presses = log.events.flatMap((event) =>
+    event.kind === 'click'
+      ? [{ t: event.t, release: event.t }]
+      : event.kind === 'drag'
+        ? [{ t: event.t, release: event.t + event.ms }]
+        : [],
+  )
+  const ringAt = (ms: number): number | null => {
+    for (const press of presses) {
+      if (ms < press.t) continue
+      const grown = (ms - press.t) / RING_MS
+      if (ms <= press.release) return Math.min(GRAB_RING, grown)
+      const held = Math.min(GRAB_RING, (press.release - press.t) / RING_MS)
+      const ring = held + (ms - press.release) / RING_MS
+      if (ring <= 1) return ring
+    }
+    return null
+  }
   const windows = zoomWindows(aims, scrolls)
 
   const targetAt = (ms: number) => {
@@ -196,16 +255,14 @@ export function cameraTrack(log: TakeLog): CameraTrack {
       cursor.y + half.y * EDGE,
     )
 
-    const ring = clicks.find(
-      (click) => ms >= click.t && ms - click.t <= RING_MS,
-    )
+    const ring = ringAt(ms)
     frames.push({
       ms: round(ms, 2),
       scale: round(scale, 4),
       x: round(clamp(springs.x.value, half.x, width - half.x) - half.x, 2),
       y: round(clamp(springs.y.value, half.y, height - half.y) - half.y, 2),
       cursor: roundPoint(cursor),
-      ring: ring ? round((ms - ring.t) / RING_MS, 3) : null,
+      ring: ring === null ? null : round(ring, 3),
     })
   }
 
@@ -217,6 +274,27 @@ export function cameraTrack(log: TakeLog): CameraTrack {
   }
 }
 
+/** Reads a playback rate off a flag, which has to be a positive number. */
+export function readRate(value: string): number | undefined {
+  const rate = Number(value)
+  return Number.isFinite(rate) && rate > 0 ? rate : undefined
+}
+
+/** The log as a clip played `rate` times faster shows it, every time divided. */
+function atRate(log: TakeLog, rate: number): TakeLog {
+  if (rate === 1) return log
+  return {
+    ...log,
+    frames: Math.round(log.frames / rate),
+    events: log.events.map((event): LogEvent => {
+      const t = event.t / rate
+      return 'ms' in event
+        ? { ...event, t, ms: event.ms / rate }
+        : { ...event, t }
+    }),
+  }
+}
+
 /**
  * Groups aims into zooms. One holds from its first aim to the last plus the
  * hold, a scroll ends it since the content moves under the camera, and the next
@@ -295,6 +373,17 @@ function focusAt(
   return focus
 }
 
+function union(a: Box, b: Box): Box {
+  const x = Math.min(a.x, b.x)
+  const y = Math.min(a.y, b.y)
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y,
+  }
+}
+
 function clamp(value: number, low: number, high: number): number {
   return Math.min(Math.max(value, low), high)
 }

package/src/take/film.ts

@@ -4,6 +4,7 @@ import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
 import { cameraTrack } from '@/take/camera'
 import { FfmpegMissing, requireFfmpeg } from '@/take/encode'
 import {
+  CLIP_SIZES,
   FPS,
   LOG_VERSION,
   type LogEvent,
@@ -60,6 +61,10 @@ export type TakeResult =
       readonly reason: TakeRefusal
       readonly message: string
       readonly beat?: string
+      /** Why the refused beat had fallen back to a screencast, when it had. */
+      readonly fallback?: string
+      /** The page as the failing step met it, relative to the take's folder. */
+      readonly still?: string
     }
 
 export interface TakeRequest {
@@ -121,7 +126,15 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
         ),
       )
     } catch (error) {
-      return failed(classify(error), error, beat.name)
+      const cause = error instanceof FellBack ? error.error : error
+      const shot = cause instanceof TargetMissing ? cause.still : undefined
+      const still = shot ? join(dir, 'still.jpg') : undefined
+      if (shot && still) writeFileSync(join(out, still), shot)
+      return {
+        ...failed(classify(cause), cause, beat.name),
+        ...(error instanceof FellBack ? { fallback: error.fallback } : {}),
+        ...(still ? { still } : {}),
+      }
     }
   }
 
@@ -159,7 +172,11 @@ async function filmBeat(
       if (!(error instanceof StepperStalled)) throw error
       route = 'screencast'
       fallback = error.message
-      filmed = await filmScreencast({ url, beat, clip: target })
+      try {
+        filmed = await filmScreencast({ url, beat, clip: target })
+      } catch (cause) {
+        throw new FellBack(cause, fallback)
+      }
     }
   } else {
     filmed = await filmScreencast({ url, beat, clip: target })
@@ -170,6 +187,8 @@ async function filmBeat(
     viewport: VIEWPORT,
     fps: FPS,
     route,
+    clip: CLIP_SIZES[route],
+    ...(beat.push === false ? { push: false as const } : {}),
     frames: filmed.frames,
     events: filmed.events,
   }
@@ -196,6 +215,20 @@ async function filmBeat(
   }
 }
 
+/**
+ * A beat that failed in the screencast it fell back to, carrying why it fell
+ * back, since the fallback loads the page a second time and a single-use link
+ * is spent by then.
+ */
+class FellBack extends Error {
+  constructor(
+    readonly error: unknown,
+    readonly fallback: string,
+  ) {
+    super(error instanceof Error ? error.message : String(error))
+  }
+}
+
 function classify(error: unknown): TakeRefusal {
   if (error instanceof TargetMissing) return 'target-missing'
   if (error instanceof ShellMissing || isBrowserMissing(error)) {

package/src/take/fixtures/input.html

@@ -0,0 +1,138 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Input</title>
+    <!--
+      One target per input a take performs, each posting what the page saw to
+      /report with a sequence number, so a test reads the inputs in the order
+      the page received them after the take has closed the browser.
+
+      - #handle follows a pointer-event drag and reports where it dropped and
+        how many of its moves carried the held button
+      - #frame reports each dblclick
+      - #layer reports pointerdown, pointerup, and click with the Shift flag
+      - #field takes focus for key steps, and every keyup reports its value
+    -->
+    <style>
+      body {
+        margin: 0;
+        background: #f4f4f4;
+        font: 24px sans-serif;
+      }
+
+      #handle {
+        position: absolute;
+        left: 200px;
+        top: 200px;
+        width: 80px;
+        height: 80px;
+        /* Neutral, so the reel's blue ring reads over it at any alpha. */
+        background: #444;
+        touch-action: none;
+      }
+
+      #lane {
+        position: absolute;
+        left: 700px;
+        top: 160px;
+        width: 300px;
+        height: 160px;
+        border: 2px dashed #555;
+        box-sizing: border-box;
+      }
+
+      #frame,
+      #layer {
+        position: absolute;
+        top: 500px;
+        width: 200px;
+        height: 100px;
+        background: #ddd;
+        user-select: none;
+      }
+
+      #frame {
+        left: 200px;
+      }
+
+      #layer {
+        left: 700px;
+      }
+
+      #field {
+        position: absolute;
+        left: 200px;
+        top: 750px;
+        width: 400px;
+        height: 48px;
+        font: inherit;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="lane"></div>
+    <div id="handle"></div>
+    <div id="frame">Frame</div>
+    <div id="layer">Layer</div>
+    <input id="field" />
+    <script>
+      let seq = 0
+      const report = (entry) =>
+        fetch('/report', {
+          method: 'POST',
+          body: JSON.stringify({ seq: (seq += 1), ...entry }),
+          keepalive: true,
+        })
+
+      const handle = document.getElementById('handle')
+      const lane = document.getElementById('lane')
+      let drag = null
+      handle.addEventListener('pointerdown', (event) => {
+        handle.setPointerCapture(event.pointerId)
+        drag = { held: 0, hover: 0 }
+      })
+      handle.addEventListener('pointermove', (event) => {
+        if (!drag) return
+        if (event.buttons === 1) drag.held += 1
+        else drag.hover += 1
+        handle.style.left = `${event.clientX - 40}px`
+        handle.style.top = `${event.clientY - 40}px`
+      })
+      handle.addEventListener('pointerup', (event) => {
+        if (!drag) return
+        const box = lane.getBoundingClientRect()
+        const onTarget =
+          event.clientX >= box.left &&
+          event.clientX <= box.right &&
+          event.clientY >= box.top &&
+          event.clientY <= box.bottom
+        report({ type: 'drop', ...drag, onTarget, altKey: event.altKey })
+        drag = null
+      })
+
+      document
+        .getElementById('frame')
+        .addEventListener('dblclick', () => report({ type: 'dblclick' }))
+
+      const layer = document.getElementById('layer')
+      for (const type of ['pointerdown', 'pointerup', 'click']) {
+        layer.addEventListener(type, (event) =>
+          report({ type, shiftKey: event.shiftKey }),
+        )
+      }
+
+      const field = document.getElementById('field')
+      document.addEventListener('keydown', (event) =>
+        report({
+          type: 'keydown',
+          key: event.key,
+          ctrlKey: event.ctrlKey,
+        }),
+      )
+      document.addEventListener('keyup', (event) =>
+        report({ type: 'keyup', key: event.key, value: field.value }),
+      )
+    </script>
+  </body>
+</html>

package/src/take/keys.ts

@@ -0,0 +1,193 @@
+/**
+ * The keys a take plan may press, named as Playwright names them so the
+ * screencast passes a combination straight to `page.keyboard`, and each one's
+ * CDP descriptor so the stepper can send the same press as raw key events.
+ * A key outside this vocabulary refuses at plan read, since the stepper has no
+ * descriptor to send for it.
+ */
+
+export const MODIFIERS = ['Alt', 'Control', 'Meta', 'Shift'] as const
+
+export type Modifier = (typeof MODIFIERS)[number]
+
+/** A combination: the modifiers held, in order, around one key. */
+export interface Chord {
+  readonly modifiers: readonly Modifier[]
+  readonly key: string
+}
+
+/** The fields `Input.dispatchKeyEvent` needs to press one key. */
+export interface KeyDescriptor {
+  readonly key: string
+  readonly code: string
+  readonly keyCode: number
+  /** What the key types, absent for a key that types nothing. */
+  readonly text?: string
+  /** 1 for a modifier, which sits on the left of the keyboard. */
+  readonly location: number
+}
+
+/** CDP's modifier bit field: "Alt=1, Ctrl=2, Meta/Command=4, Shift=8". */
+const MODIFIER_BITS: Record<Modifier, number> = {
+  Alt: 1,
+  Control: 2,
+  Meta: 4,
+  Shift: 8,
+}
+
+const MODIFIER_KEY_CODES: Record<Modifier, number> = {
+  Alt: 18,
+  Control: 17,
+  Meta: 91,
+  Shift: 16,
+}
+
+const NAMED: Record<string, { code?: string; keyCode: number; text?: string }> =
+  {
+    Enter: { keyCode: 13, text: '\r' },
+    Tab: { keyCode: 9 },
+    Escape: { keyCode: 27 },
+    Backspace: { keyCode: 8 },
+    Delete: { keyCode: 46 },
+    Insert: { keyCode: 45 },
+    Space: { keyCode: 32, text: ' ' },
+    Home: { keyCode: 36 },
+    End: { keyCode: 35 },
+    PageUp: { keyCode: 33 },
+    PageDown: { keyCode: 34 },
+    ArrowLeft: { keyCode: 37 },
+    ArrowUp: { keyCode: 38 },
+    ArrowRight: { keyCode: 39 },
+    ArrowDown: { keyCode: 40 },
+    ...Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`F${i + 1}`, { keyCode: 112 + i }]),
+    ),
+  }
+
+/** The US layout's punctuation, each with its shifted twin on the same key. */
+const PUNCTUATION: readonly (readonly [string, string, string, number])[] = [
+  ['`', '~', 'Backquote', 192],
+  ['-', '_', 'Minus', 189],
+  ['=', '+', 'Equal', 187],
+  ['[', '{', 'BracketLeft', 219],
+  [']', '}', 'BracketRight', 221],
+  ['\\', '|', 'Backslash', 220],
+  [';', ':', 'Semicolon', 186],
+  ["'", '"', 'Quote', 222],
+  [',', '<', 'Comma', 188],
+  ['.', '>', 'Period', 190],
+  ['/', '?', 'Slash', 191],
+]
+
+const SHIFTED_DIGITS = ')!@#$%^&*('
+
+/**
+ * With `shift` set, a printable key types its shifted twin, as Playwright's
+ * keyboard swaps to it while Shift is held, so `Shift+a` types `A` on both
+ * routes.
+ */
+export function describeKey(
+  key: string,
+  options: { readonly shift?: boolean } = {},
+): KeyDescriptor | undefined {
+  return describeTyped(options.shift ? shiftedTwin(key) : key)
+}
+
+function shiftedTwin(key: string): string {
+  if (/^[a-z]$/.test(key)) return key.toUpperCase()
+  if (/^[0-9]$/.test(key)) return SHIFTED_DIGITS[Number(key)] ?? key
+  const row = PUNCTUATION.find(([plain]) => key === plain)
+  return row ? row[1] : key
+}
+
+function describeTyped(key: string): KeyDescriptor | undefined {
+  if (isModifier(key)) {
+    return {
+      key,
+      code: `${key}Left`,
+      keyCode: MODIFIER_KEY_CODES[key],
+      location: 1,
+    }
+  }
+  const named = NAMED[key]
+  if (named) {
+    return {
+      key: key === 'Space' ? ' ' : key,
+      code: named.code ?? key,
+      keyCode: named.keyCode,
+      ...(named.text ? { text: named.text } : {}),
+      location: 0,
+    }
+  }
+  if (key.length !== 1) return undefined
+
+  if (/^[a-z]$/i.test(key)) {
+    const upper = key.toUpperCase()
+    return printable(key, `Key${upper}`, upper.charCodeAt(0))
+  }
+  if (/^[0-9]$/.test(key)) {
+    return printable(key, `Digit${key}`, key.charCodeAt(0))
+  }
+  const shiftedDigit = SHIFTED_DIGITS.indexOf(key)
+  if (shiftedDigit >= 0) {
+    return printable(key, `Digit${shiftedDigit}`, 48 + shiftedDigit)
+  }
+  if (key === ' ') return printable(key, 'Space', 32)
+  const row = PUNCTUATION.find(
+    ([plain, shifted]) => key === plain || key === shifted,
+  )
+  return row ? printable(key, row[2], row[3]) : undefined
+}
+
+export type KeysRead =
+  | { readonly kind: 'parsed'; readonly chord: Chord }
+  | { readonly kind: 'refused'; readonly detail: string }
+
+/**
+ * Reads a combination such as `Control+K`, the modifiers first and the key
+ * last. A trailing `+` after a separator is the plus key itself.
+ */
+export function parseKeys(keys: string): KeysRead {
+  const parts =
+    keys === '+'
+      ? ['+']
+      : keys.endsWith('++')
+        ? [...keys.slice(0, -2).split('+'), '+']
+        : keys.split('+')
+  const key = parts.at(-1) ?? ''
+  const held = parts.slice(0, -1)
+
+  if (!key) return { kind: 'refused', detail: `${keys || 'it'} names no key` }
+  const modifiers: Modifier[] = []
+  for (const name of held) {
+    if (!isModifier(name)) {
+      return {
+        kind: 'refused',
+        detail: `${keys} holds ${name || 'nothing'}, which is not ${MODIFIERS.join(', ')}`,
+      }
+    }
+    if (modifiers.includes(name)) {
+      return { kind: 'refused', detail: `${keys} holds ${name} twice` }
+    }
+    modifiers.push(name)
+  }
+  if (!describeKey(key)) {
+    return {
+      kind: 'refused',
+      detail: `${keys} presses ${key}, which is not a modifier, one character, or a named key`,
+    }
+  }
+  return { kind: 'parsed', chord: { modifiers, key } }
+}
+
+export function modifierBits(modifiers: readonly Modifier[]): number {
+  return modifiers.reduce((bits, name) => bits | MODIFIER_BITS[name], 0)
+}
+
+export function isModifier(name: unknown): name is Modifier {
+  return MODIFIERS.includes(name as Modifier)
+}
+
+function printable(key: string, code: string, keyCode: number): KeyDescriptor {
+  return { key, code, keyCode, text: key, location: 0 }
+}