@erclx/canon 5.66.0 → 5.68.0

package/src/take/stepper.ts

@@ -0,0 +1,255 @@
+import { openFrameEncoder } from '@/take/encode'
+import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
+import { type PointerInput, type Stage, performSteps } from '@/take/perform'
+import type { Beat } from '@/take/plan'
+import { type ShellPage, openShell } from '@/take/shell'
+
+/**
+ * Films a beat by frame stepping. The page's clock is virtual and advances one
+ * 60 fps frame per step, so every transition, animation, and timer moves
+ * exactly one frame between screenshots however long a frame takes to render,
+ * and each screenshot comes back at twice the viewport, 3840x2160.
+ *
+ * Three orderings hold a take together, and each one broken deadlocks or
+ * freezes it rather than failing loudly:
+ *
+ * - An input is sent, a frame is stepped, and only then is the input awaited,
+ *   since under begin-frame control an input is acknowledged by a frame
+ * - 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
+ */
+
+const FRAME_MS = 1000 / FPS
+
+/** Budgets of 17, 17, and 16 ms average one 60 fps frame exactly. */
+const BUDGETS = [17, 17, 16] as const
+
+/** A frame slower than this means the page will not step, so the beat falls back. */
+export const STALL_MS = 2000
+
+/** The still the edit can cut on, before the beat's first action and after its last. */
+export const HOLD_MS = 600
+
+const LOAD_CAP_MS = 15_000
+const SETTLE_MS = 2500
+const LOADING_FRAME_CAP_MS = 250
+
+/** A frame that took longer than `STALL_MS`, so the beat is filmed another way. */
+export class StepperStalled extends Error {
+  constructor(readonly frame: number) {
+    super(`frame ${frame} took over ${STALL_MS / 1000} s under frame stepping`)
+  }
+}
+
+export interface SteppedTake {
+  readonly frames: number
+  readonly events: readonly LogEvent[]
+  /** The last frame encoded, as the JPEG the shell returned. */
+  readonly still: Buffer
+}
+
+export interface SteppedRequest {
+  readonly executable: string
+  readonly url: string
+  readonly beat: Beat
+  readonly clip: string
+}
+
+export async function filmStepped(
+  request: SteppedRequest,
+): Promise<SteppedTake> {
+  const page = await openShell(request.executable, VIEWPORT)
+  const encoder = openFrameEncoder(request.clip, FPS)
+  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 } }
+            : {}),
+        },
+      )
+    await pump(beginFrame, SETTLE_MS)
+
+    const live = liveStage(page, beginFrame)
+    await performSteps(live, request.beat.setup, { pointer: START })
+    if (request.beat.setup.length > 0) await live.hold(1000)
+    await live.pointer({ type: 'move', ...START })
+
+    await page.send('Emulation.setVirtualTimePolicy', { policy: 'pause' })
+
+    const events: LogEvent[] = []
+    let frames = 0
+    let budget = 0
+    let last: Buffer | undefined
+    const expired: (() => void)[] = []
+    page.on('Emulation.virtualTimeBudgetExpired', () => expired.shift()?.())
+
+    const frame = async (): Promise<void> => {
+      const advanced = new Promise<void>((done) => expired.push(done))
+      // Plain advance rather than pausing on pending fetches, which held the
+      // clock through every page switch that loads its view, past the stall
+      // limit. A refused advance never expires its budget, which the stall
+      // reports.
+      page
+        .send('Emulation.setVirtualTimePolicy', {
+          policy: 'advance',
+          budget: BUDGETS[budget++ % BUDGETS.length],
+        })
+        .catch(() => {})
+      const reply = await withinStall(
+        advanced.then(() => beginFrame(true)),
+        frames,
+      )
+      const data = reply.screenshotData
+        ? Buffer.from(reply.screenshotData, 'base64')
+        : last
+      if (!data) throw new Error('the first frame carried no screenshot')
+      last = data
+      await encoder.write(data)
+      frames += 1
+    }
+
+    const recording: Stage = {
+      now: () => frames * FRAME_MS,
+      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
+      },
+      evaluate: (expression) => page.evaluate(expression),
+    }
+
+    await recording.hold(HOLD_MS)
+    await performSteps(recording, request.beat.steps, {
+      pointer: START,
+      log: events,
+    })
+    await recording.hold(HOLD_MS)
+
+    await encoder.close()
+    if (!last) throw new Error('the take encoded no frame')
+    return { frames, events, still: last }
+  } catch (error) {
+    encoder.abort()
+    throw error
+  } finally {
+    page.close()
+  }
+}
+
+/**
+ * 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
+ * it: Node's `hrtime` shares the base on Linux, Bun's counts from its own
+ * start, and a frame stamped on the wrong base freezes every animation.
+ */
+async function load(page: ShellPage, url: string): Promise<number> {
+  const loaded = new Promise<number>((done) =>
+    page.on('Page.loadEventFired', ({ timestamp }) => {
+      if (typeof timestamp === 'number') done(timestamp * 1000)
+    }),
+  )
+  const navigated = await page.send<{ errorText?: string }>('Page.navigate', {
+    url,
+  })
+  if (navigated.errorText) {
+    throw new Error(`${navigated.errorText} at ${url}`)
+  }
+  const timestamp = await Promise.race([loaded, sleep(LOAD_CAP_MS)])
+  if (typeof timestamp !== 'number') {
+    throw new Error(
+      `${url} fired no load event within ${LOAD_CAP_MS / 1000} s, so no frame clock could be read`,
+    )
+  }
+  return timestamp
+}
+
+/** Begins frames in real time so loading, fonts, and layout settle. */
+async function pump(
+  beginFrame: (screenshot: boolean) => Promise<unknown>,
+  ms: number,
+): Promise<void> {
+  const end = Date.now() + ms
+  while (Date.now() < end) {
+    await Promise.race([
+      beginFrame(false).catch(() => {}),
+      sleep(LOADING_FRAME_CAP_MS),
+    ])
+    await sleep(12)
+  }
+}
+
+/**
+ * The stage setup runs on, before virtual time is paused. Its frames are begun
+ * without screenshots, since nothing before the first held frame is kept.
+ */
+function liveStage(
+  page: ShellPage,
+  beginFrame: (screenshot: boolean) => Promise<unknown>,
+): Stage {
+  const started = Date.now()
+  return {
+    now: () => Date.now() - started,
+    hold: (ms) => pump(beginFrame, ms),
+    pointer: (input) => {
+      const sent = page.send('Input.dispatchMouseEvent', mouseEvent(input))
+      return withinStall(
+        beginFrame(false).then(() => sent),
+        0,
+      ).then(() => {})
+    },
+    key: (text) => {
+      const sent = page.send('Input.insertText', { text })
+      return withinStall(
+        beginFrame(false).then(() => sent),
+        0,
+      ).then(() => {})
+    },
+    evaluate: (expression) => page.evaluate(expression),
+  }
+}
+
+function mouseEvent(input: PointerInput): Record<string, unknown> {
+  const at = { x: input.x, y: input.y }
+  switch (input.type) {
+    case 'move':
+      return { type: 'mouseMoved', ...at, button: 'none' }
+    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 }
+  }
+}
+
+async function withinStall<T>(work: Promise<T>, frame: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const stalled = new Promise<never>((_, fail) => {
+    timer = setTimeout(() => fail(new StepperStalled(frame)), STALL_MS)
+  })
+  try {
+    return await Promise.race([work, stalled])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((done) => setTimeout(done, ms))
+}

package/src/take/zoom/NOTICE.md

@@ -0,0 +1,45 @@
+# Vendored zoom notice
+
+The files in this folder carry the zoom timing of [OpenScreen](https://github.com/siddharthvaddem/openscreen) at commit `ca8104c279da0d4b4481ec992ff103949e22c772`, under the MIT license below.
+
+## What came from where
+
+| File              | Source in OpenScreen, under `src/components/video-editor/videoPlayback/`                                 |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `math-utils.ts`   | `mathUtils.ts`                                                                                           |
+| `region-utils.ts` | `zoomRegionUtils.ts`, with `TRANSITION_WINDOW_MS` and `ZOOM_IN_TRANSITION_WINDOW_MS` from `constants.ts` |
+| `spring.ts`       | `motionSmoothing.ts` and `zoomSpring.ts`                                                                 |
+
+## What changed
+
+- The file names are kebab-case, as this repository names every TypeScript file, and the code is reformatted to its style
+- `math-utils.ts` keeps `clamp01`, `cubicBezier`, and `easeOutScreenStudio`, and drops the easings nothing here calls
+- `region-utils.ts` keeps `computeRegionStrength`, the connected-pan easing, and the window and gap constants. It drops the dominant-region search, its cache, the 3D rotation, and the cursor-follow focus, since the camera here aims at clicks and holds its focus by its own rule.
+- The zoom-out window is 700 ms rather than 1015.05 ms, and the connected pan runs 600 ms rather than 1000 ms, both on the operator's eye in groundwork track `193-ui-record`. The zoom-in window keeps OpenScreen's 1522.575 ms.
+- `spring.ts` keeps the zoom spring's stiffness 320, damping 40, mass 0.92, its rest thresholds, the delta clamp, and the overshoot clamp from `stepAxis`. OpenScreen steps that spring through the `motion` package, and this solves it in closed form instead, so no dependency comes with it.
+
+## License
+
+```plaintext
+MIT License
+
+Copyright (c) 2025 Siddharth Vaddem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/src/take/zoom/math-utils.ts

@@ -0,0 +1,69 @@
+// Vendored from OpenScreen at ca8104c, MIT. See NOTICE.md beside this file.
+// Source: src/components/video-editor/videoPlayback/mathUtils.ts
+
+export function clamp01(value: number) {
+  return Math.max(0, Math.min(1, value))
+}
+
+function sampleCubicBezier(a1: number, a2: number, t: number) {
+  const oneMinusT = 1 - t
+  return (
+    3 * a1 * oneMinusT * oneMinusT * t + 3 * a2 * oneMinusT * t * t + t * t * t
+  )
+}
+
+function sampleCubicBezierDerivative(a1: number, a2: number, t: number) {
+  const oneMinusT = 1 - t
+  return (
+    3 * a1 * oneMinusT * oneMinusT +
+    6 * (a2 - a1) * oneMinusT * t +
+    3 * (1 - a2) * t * t
+  )
+}
+
+export function cubicBezier(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  t: number,
+) {
+  const targetX = clamp01(t)
+  let solvedT = targetX
+
+  for (let i = 0; i < 8; i += 1) {
+    const currentX = sampleCubicBezier(x1, x2, solvedT) - targetX
+    const currentDerivative = sampleCubicBezierDerivative(x1, x2, solvedT)
+
+    if (Math.abs(currentX) < 1e-6 || Math.abs(currentDerivative) < 1e-6) {
+      break
+    }
+
+    solvedT -= currentX / currentDerivative
+  }
+
+  let lower = 0
+  let upper = 1
+  solvedT = clamp01(solvedT)
+
+  for (let i = 0; i < 10; i += 1) {
+    const currentX = sampleCubicBezier(x1, x2, solvedT)
+    if (Math.abs(currentX - targetX) < 1e-6) {
+      break
+    }
+
+    if (currentX < targetX) {
+      lower = solvedT
+    } else {
+      upper = solvedT
+    }
+
+    solvedT = (lower + upper) / 2
+  }
+
+  return sampleCubicBezier(y1, y2, solvedT)
+}
+
+export function easeOutScreenStudio(t: number) {
+  return cubicBezier(0.16, 1, 0.3, 1, t)
+}

package/src/take/zoom/region-utils.ts

@@ -0,0 +1,55 @@
+// Vendored from OpenScreen at ca8104c, MIT. See NOTICE.md beside this file.
+// Source: src/components/video-editor/videoPlayback/zoomRegionUtils.ts and the
+// two window constants from constants.ts. The zoom-out window and the chained
+// pan's duration carry the operator's tuning, and NOTICE.md lists both.
+
+import {
+  clamp01,
+  cubicBezier,
+  easeOutScreenStudio,
+} from '@/take/zoom/math-utils'
+
+/** OpenScreen's 1015.05 ms, shortened to 700 ms for a quicker zoom-out. */
+export const TRANSITION_WINDOW_MS = 700
+/** OpenScreen's zoom-in window, 1.5 times its original 1015.05 ms window. */
+export const ZOOM_IN_TRANSITION_WINDOW_MS = 1015.05 * 1.5
+
+export const CHAINED_ZOOM_PAN_GAP_MS = 1500
+/** OpenScreen's 1000 ms, shortened to 600 ms. */
+export const CONNECTED_ZOOM_PAN_DURATION_MS = 600
+export const ZOOM_IN_OVERLAP_MS = 500
+
+export interface ZoomRegion {
+  startMs: number
+  endMs: number
+}
+
+export function lerp(start: number, end: number, amount: number) {
+  return start + (end - start) * amount
+}
+
+export function easeConnectedPan(value: number) {
+  return cubicBezier(0.1, 0.0, 0.2, 1.0, value)
+}
+
+export function computeRegionStrength(region: ZoomRegion, timeMs: number) {
+  const zoomInEnd = region.startMs + ZOOM_IN_OVERLAP_MS
+  const leadInStart = zoomInEnd - ZOOM_IN_TRANSITION_WINDOW_MS
+  const leadOutEnd = region.endMs + TRANSITION_WINDOW_MS
+
+  if (timeMs < leadInStart || timeMs > leadOutEnd) {
+    return 0
+  }
+
+  if (timeMs < zoomInEnd) {
+    const progress = (timeMs - leadInStart) / ZOOM_IN_TRANSITION_WINDOW_MS
+    return easeOutScreenStudio(progress)
+  }
+
+  if (timeMs <= region.endMs) {
+    return 1
+  }
+
+  const progress = clamp01((timeMs - region.endMs) / TRANSITION_WINDOW_MS)
+  return 1 - easeOutScreenStudio(progress)
+}

package/src/take/zoom/spring.ts

@@ -0,0 +1,133 @@
+// Adapted from OpenScreen at ca8104c, MIT. See NOTICE.md beside this file.
+// Source: getZoomSpringConfig, stepSpringValue, and clampDeltaMs in
+// src/components/video-editor/videoPlayback/motionSmoothing.ts, and stepAxis in
+// zoomSpring.ts. OpenScreen steps its spring through the `motion` package, and
+// this solves the same damped spring in closed form instead, so a target
+// inherits no dependency for one function.
+
+export interface SpringState {
+  value: number
+  velocity: number
+  initialized: boolean
+}
+
+export interface SpringConfig {
+  stiffness: number
+  damping: number
+  mass: number
+  restDelta: number
+  restSpeed: number
+}
+
+export const ZOOM_SPRING: SpringConfig = {
+  stiffness: 320,
+  damping: 40,
+  mass: 0.92,
+  restDelta: 0.0005,
+  restSpeed: 0.015,
+}
+
+export function createSpringState(initialValue = 0): SpringState {
+  return { value: initialValue, velocity: 0, initialized: false }
+}
+
+export function clampDeltaMs(deltaMs: number, fallbackMs = 1000 / 60) {
+  if (!Number.isFinite(deltaMs) || deltaMs <= 0) {
+    return fallbackMs
+  }
+
+  return Math.min(80, Math.max(1, deltaMs))
+}
+
+/**
+ * Advances one axis toward `target` by `deltaMs`. The first call snaps to the
+ * target, a spring at rest stays there, and a step that would cross a moving
+ * target lands on it with no velocity, which keeps a quick chase from wobbling
+ * on a reversal.
+ */
+export function stepSpring(
+  state: SpringState,
+  target: number,
+  deltaMs: number,
+  config: SpringConfig = ZOOM_SPRING,
+): number {
+  if (!state.initialized || !Number.isFinite(state.value)) {
+    state.value = target
+    state.velocity = 0
+    state.initialized = true
+    return state.value
+  }
+
+  if (
+    Math.abs(target - state.value) <= config.restDelta &&
+    Math.abs(state.velocity) <= config.restSpeed
+  ) {
+    state.value = target
+    state.velocity = 0
+    return state.value
+  }
+
+  const before = state.value
+  const [offset, velocity] = solve(
+    state.value - target,
+    state.velocity,
+    clampDeltaMs(deltaMs) / 1000,
+    config,
+  )
+  const after = target + offset
+
+  const crossed =
+    (before <= target && after > target) || (before >= target && after < target)
+  if (crossed) {
+    state.value = target
+    state.velocity = 0
+    return target
+  }
+
+  state.value = after
+  state.velocity = velocity
+  return after
+}
+
+/**
+ * The displacement and velocity of a damped spring `seconds` after it sat at
+ * `x0` from rest length moving at `v0`, for each of the three damping regimes.
+ */
+function solve(
+  x0: number,
+  v0: number,
+  seconds: number,
+  { stiffness, damping, mass }: SpringConfig,
+): [number, number] {
+  const omega = Math.sqrt(stiffness / mass)
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass))
+  const t = seconds
+
+  if (zeta < 1) {
+    const omegaD = omega * Math.sqrt(1 - zeta * zeta)
+    const decay = Math.exp(-zeta * omega * t)
+    const b = (v0 + zeta * omega * x0) / omegaD
+    const cos = Math.cos(omegaD * t)
+    const sin = Math.sin(omegaD * t)
+    const x = decay * (x0 * cos + b * sin)
+    const v =
+      decay *
+      (-zeta * omega * (x0 * cos + b * sin) + omegaD * (b * cos - x0 * sin))
+    return [x, v]
+  }
+
+  if (zeta === 1) {
+    const decay = Math.exp(-omega * t)
+    const b = v0 + omega * x0
+    return [(x0 + b * t) * decay, (b - omega * (x0 + b * t)) * decay]
+  }
+
+  const root = Math.sqrt(zeta * zeta - 1)
+  const r1 = -omega * (zeta - root)
+  const r2 = -omega * (zeta + root)
+  const c1 = (v0 - r2 * x0) / (r1 - r2)
+  const c2 = x0 - c1
+  const e1 = Math.exp(r1 * t)
+  const e2 = Math.exp(r2 * t)
+  return [c1 * e1 + c2 * e2, c1 * r1 * e1 + c2 * r2 * e2]
+}

package/src/tasks/archive.ts

@@ -7,6 +7,7 @@ import { regenOne } from '@/indexes/regen'
 import { rerenderRow } from '@/tasks/board'
 import { planBranch } from '@/tasks/branch'
 import { isUnder } from '@/tasks/paths'
+import { SESSION_MAP_PREFIX } from '@/records/session-map'
 import { recordDir, recordDirs } from '@/roots/record'
 
 const TASKS = 'tasks'
@@ -29,9 +30,6 @@ export const RESERVED_STEMS = [
   'session',
 ] as const
 
-/** The pre-compaction handoff takes one file per session, so its stems vary. */
-const SESSION_MAP_PREFIX = 'session-'
-
 export function isReservedStem(stem: string): boolean {
   const reserved: readonly string[] = RESERVED_STEMS
 

package/claude/skills/review-ui/scripts/pw.sh

@@ -1,60 +0,0 @@
-#!/usr/bin/env bash
-# Pins the agent browser CLI the UI pass drives through, so every call in a run
-# and every run on a machine reach one version. `open` is forced onto the
-# bundled Chromium, since the CLI's default channel is a branded Chrome most
-# machines lack, and it refuses rather than downloading when that browser is
-# absent, since a dispatched reviewer that installs mid-pass spends its budget
-# on the download.
-set -euo pipefail
-
-PW_CLI="@playwright/cli@0.1.22"
-# The Chromium revision that CLI version requires. It moves with the pin, and
-# it is separate from the revision any other Playwright on the machine uses.
-PW_CHROMIUM_REVISION="1247"
-
-die() {
-  echo "pw.sh: $*" >&2
-  exit 1
-}
-
-browsers_root() {
-  if [ -n "${PLAYWRIGHT_BROWSERS_PATH:-}" ]; then
-    echo "$PLAYWRIGHT_BROWSERS_PATH"
-  elif [ "$(uname -s 2>/dev/null || echo unknown)" = Darwin ]; then
-    echo "$HOME/Library/Caches/ms-playwright"
-  else
-    echo "$HOME/.cache/ms-playwright"
-  fi
-}
-
-command -v bunx >/dev/null 2>&1 || die "bunx is not on PATH, so the pinned CLI cannot run"
-
-# Global flags may lead the verb, as in `-s=<name> --raw open <url>`.
-args=("$@")
-verb_at=0
-for i in "${!args[@]}"; do
-  case "${args[$i]}" in
-  -*) ;;
-  *)
-    verb_at=$i
-    break
-    ;;
-  esac
-done
-
-if [ "${args[$verb_at]:-}" = open ]; then
-  if [ ! -d "$(browsers_root)/chromium-$PW_CHROMIUM_REVISION" ]; then
-    die "Chromium revision $PW_CHROMIUM_REVISION is not installed. Run once, outside the pass: bunx -y $PW_CLI install-browser chromium"
-  fi
-  has_browser=false
-  for arg in "${args[@]}"; do
-    case "$arg" in
-    --browser=* | --browser) has_browser=true ;;
-    esac
-  done
-  if [ "$has_browser" = false ]; then
-    args=("${args[@]:0:$((verb_at + 1))}" --browser=chromium "${args[@]:$((verb_at + 1))}")
-  fi
-fi
-
-exec bunx -y "$PW_CLI" "${args[@]}"