@erclx/canon 5.69.0 → 5.71.0

package/src/commands/sandbox.ts

@@ -25,7 +25,7 @@ import {
   type RunEnvelope,
   type Verdict,
 } from '@/sandbox/expect'
-import { runHeadless } from '@/sandbox/headless/run'
+import { runHeadless, runSettings } from '@/sandbox/headless/run'
 import { runSandbox } from '@/sandbox/provision'
 import {
   EXPECTED_FILE,
@@ -120,7 +120,12 @@ function showProvisionHelp(): void {
 }
 
 /** A run that reported nothing counts as clean, so only real signals fail. */
-const CLEAN_ENVELOPE: RunEnvelope = { isError: false, turns: 0, denials: 0 }
+const CLEAN_ENVELOPE: RunEnvelope = {
+  isError: false,
+  isTruncated: false,
+  turns: 0,
+  denials: 0,
+}
 
 interface CheckOptions {
   readonly envelope?: string
@@ -190,6 +195,8 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
 
     return {
       isError: parsed.is_error === true,
+      isTruncated: parsed.subtype === 'error_max_turns',
+      turnCap: Number(runSettings(process.env).maxTurns),
       turns: typeof parsed.num_turns === 'number' ? parsed.num_turns : 0,
       denials: Array.isArray(denials) ? denials.length : 0,
       reply: typeof parsed.result === 'string' ? parsed.result : undefined,

package/src/commands/take.ts

@@ -1,7 +1,9 @@
-import { readFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import { cameraTrack, readRate } from '@/take/camera'
+import { readTakeLog } from '@/take/log'
 import { readTakePlan } from '@/take/plan'
 import type { TakePlanRefusal } from '@/take/plan'
 import type { TakeRefusal } from '@/take/film'
@@ -24,11 +26,17 @@ import {
 type Take = typeof import('@/take/film')
 
 interface RunOptions {
-  readonly out: string
+  readonly out?: string
   readonly reel?: string
   readonly json?: boolean
 }
 
+interface CameraOptions {
+  readonly out?: string
+  readonly rate?: string
+  readonly json?: boolean
+}
+
 const INSTALL_FFMPEG =
   'install FFmpeg from your package manager, such as apt install ffmpeg or brew install ffmpeg'
 
@@ -40,7 +48,8 @@ const PLAN_REFUSALS: Record<TakePlanRefusal, string> = {
   'bad-beat':
     'A beat is missing its name or carries a setup that is not a list.',
   'no-steps': 'A beat names no step, so its take would film nothing.',
-  'unknown-route': 'A beat names a route this build does not record on.',
+  'unknown-route':
+    'The plan or a beat names a route this build does not record on.',
   'bad-step': 'A step is missing something the take needs to perform it.',
 }
 
@@ -53,14 +62,19 @@ const TAKE_REFUSALS: Record<TakeRefusal, string> = {
 }
 
 export function register(program: Command): void {
-  program
+  const take = program
     .command('take')
     .description(
       'Film a web app beat by beat with a click log and camera track',
     )
     .argument('<url>', 'Address to film')
     .argument('<plan>', 'JSON file naming the beats and their steps')
-    .requiredOption('--out <dir>', 'Folder the clips, logs, and tracks land in')
+    // Checked in the action rather than required here, since commander checks
+    // a parent's required options on every subcommand, `camera` included.
+    .option('--out <dir>', 'Folder the clips, logs, and tracks land in')
+    // Keeps this command's options ahead of `camera`, which reuses --out and
+    // --json for its own.
+    .enablePositionalOptions()
     .helpOption('-h, --help', 'Show this help message')
     .option(
       '--reel <file>',
@@ -106,12 +120,33 @@ export function register(program: Command): void {
         'Step kinds:',
         '  move <target>|<x,y>    glide the pointer to a target or a point',
         '  click <target>         glide to the target and press it',
+        '  dblclick <target>      glide to the target and press it twice',
+        '  drag <from> <to>       press the from target, glide held, release on to',
+        '  key <keys>             press a combination such as Control+K',
         '  fill <target> <text>   press the target and type the text',
         '  scroll <target> <dy>   glide to the target and wheel dy pixels',
         '  wait <ms>              hold, for a state the page reaches on its own',
         '',
-        'A target is a CSS selector, or text=<words> for the innermost element',
-        'whose whole text is those words. Setup steps run before the first kept',
+        'click, dblclick, and drag take modifiers, a list of Alt, Control, Meta,',
+        'and Shift held through the press, as in "modifiers": ["Shift"]. keys',
+        'names those modifiers joined by + ahead of one character or a named key:',
+        'Enter, Tab, Escape, Backspace, Delete, Insert, Space, Home, End, PageUp,',
+        'PageDown, the four arrows as ArrowUp and the like, and F1 to F12. A key',
+        'moves no pointer, so the camera neither aims at it nor ends a zoom.',
+        '',
+        'drag drives pointer events, the kind a canvas board listens for. It',
+        'starts no native HTML5 drag of a draggable element on the stepped route,',
+        'so a beat needing one films the same only on the screencast route.',
+        '',
+        'A top-level route sets the route of every beat that names none of its',
+        'own. A beat carrying push: false keeps its camera on the whole page,',
+        'with the cursor and click ring still in the track, and its log.json',
+        'records push: false. Each log.json carries clip, the clip size in',
+        'pixels, which caps the zoom depth so a 1920-wide screencast stays sharp.',
+        '',
+        'A target is a CSS selector, or text=<words> for the first innermost',
+        'element with a size whose whole text is those words, so a hidden copy',
+        'earlier in the page is skipped. Setup steps run before the first kept',
         'frame. Every beat opens and closes on a 0.6 s hold.',
         '',
         'Needs a reachable page, FFmpeg, and the headless shell. Install with:',
@@ -123,7 +158,8 @@ export function register(program: Command): void {
         '  no-beats            the plan names no beat',
         '  bad-beat            a beat has no name or a setup that is not a list',
         '  no-steps            a beat names no step',
-        '  unknown-route       a beat names a route other than step or screencast',
+        '  unknown-route       the plan or a beat names a route other than step or',
+        '                      screencast',
         '  bad-step            a step is missing what the take needs to perform it',
         '  engine-missing      the browser engine is not installed in this project',
         '  ffmpeg-missing      FFmpeg is not on the PATH',
@@ -133,6 +169,13 @@ export function register(program: Command): void {
         '  take-failed         the take failed against a reachable page',
         '  reel-failed         every beat was filmed and the reel did not encode',
         '',
+        'A refusal in a beat carries beat. target-missing carries still when the',
+        "page answered a capture, the beat folder's still.jpg as the step met it. A",
+        'beat that fell back to the screencast before refusing carries fallback,',
+        'the reason it fell back. The screencast opens the address a second time,',
+        'so a single-use link is spent by then: check the access before the',
+        'selector.',
+        '',
         'Exit codes:',
         '  0  every beat was filmed, and the reel written when asked for',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -144,15 +187,113 @@ export function register(program: Command): void {
         '',
       ].join('\n'),
     )
-    .action(async (url: string, plan: string, opts: RunOptions) => {
-      process.exitCode = await runTake(url, plan, opts)
+    .action(
+      async (url: string, plan: string, opts: RunOptions, command: Command) => {
+        if (!opts.out)
+          command.error("error: required option '--out <dir>' not specified")
+        process.exitCode = await runTake(url, plan, { ...opts, out: opts.out })
+      },
+    )
+
+  take
+    .command('camera')
+    .description("Build a camera track from a take's log.json")
+    .argument('<log>', "A beat's log.json, as a take wrote it")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--out <file>', 'Write the track to a file rather than stdout')
+    .option(
+      '--rate <n>',
+      'How many times faster the edit plays the clip, 1 by default',
+    )
+    .option('--json', 'Add a machine-readable record on stdout with --out')
+    .addHelpText(
+      'after',
+      [
+        '',
+        "Builds the same camera track a take writes beside each beat's clip, from",
+        'the log alone, so a track can be rebuilt for a clip the edit plays at',
+        'another speed. With no --out the track is the data on stdout, one line,',
+        'and a refusal under --json is the record there instead.',
+        '',
+        '--rate <n> builds the track on the playback clock of a clip sped up n',
+        'times, dividing every time in the log by n, so a zoom settles at the',
+        'speed a viewer sees rather than pumping several times a beat.',
+        '',
+        "The zoom depth is capped by the clip's resolution, read from the log's",
+        'clip field, or from its route on a log written before that field. A log',
+        'carrying push: false holds the whole page with the cursor and ring.',
+        '',
+        'Reasons:',
+        '  no-log-file     nothing readable at the log path',
+        "  unreadable-log  the file is not a take's log.json",
+        '  bad-rate        --rate is not a positive number',
+        '',
+        'Exit codes:',
+        '  0  the track was written',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        "  canon take camera takes/01-open/log.json | jq '.frames | length'",
+        '  canon take camera takes/01-open/log.json --rate 2 --out camera-2x.json',
+        '',
+      ].join('\n'),
+    )
+    .action((log: string, opts: CameraOptions) => {
+      process.exitCode = runCamera(log, opts)
     })
 }
 
+function runCamera(logPath: string, opts: CameraOptions): number {
+  const emitJson = opts.json ?? false
+  const path = resolve(logPath)
+  const refuseCamera = (reason: string, message: string): number => {
+    logWarn(message)
+    emit(emitJson, { log: path, reason, message })
+    return 1
+  }
+
+  const rate = opts.rate === undefined ? 1 : readRate(opts.rate)
+  if (rate === undefined) {
+    return refuseCamera(
+      'bad-rate',
+      `--rate ${opts.rate} is not a positive number, such as 1.5 or 2.`,
+    )
+  }
+
+  let source: string
+  try {
+    source = readFileSync(path, 'utf8')
+  } catch (error) {
+    return refuseCamera(
+      'no-log-file',
+      `No log file at ${path}. ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+  const read = readTakeLog(source)
+  if (read.kind === 'refused') {
+    return refuseCamera(
+      'unreadable-log',
+      `${path} is not a take's log.json, being the file beside a beat's clip.mp4. ${read.detail}`,
+    )
+  }
+
+  const track = cameraTrack(read.log, { rate })
+  const line = `${JSON.stringify(track)}\n`
+  if (!opts.out) {
+    process.stdout.write(line)
+    return 0
+  }
+  const out = resolve(opts.out)
+  writeFileSync(out, line)
+  logInfo(`${out}  ${plural(track.frames.length, 'frame')}  rate ${rate}`)
+  emit(emitJson, { log: path, out, frames: track.frames.length, rate })
+  return 0
+}
+
 async function runTake(
   url: string,
   planPath: string,
-  opts: RunOptions,
+  opts: RunOptions & { readonly out: string },
 ): Promise<number> {
   const emitJson = opts.json ?? false
   const path = resolve(planPath)
@@ -209,6 +350,11 @@ async function runTake(
     logStep('Refused')
     logWarn(TAKE_REFUSALS[result.reason])
     if (result.beat) logWarn(`in beat ${result.beat}`)
+    if (result.fallback) {
+      logWarn(
+        `after falling back to a screencast, which opened the address again: ${result.fallback}`,
+      )
+    }
     if (result.reason === 'server-unreachable') {
       logWarn(`Start whatever serves ${url}, then run this again.`)
     }
@@ -224,6 +370,8 @@ async function runTake(
       reason: result.reason,
       message: result.message,
       ...(result.beat ? { beat: result.beat } : {}),
+      ...(result.fallback ? { fallback: result.fallback } : {}),
+      ...(result.still ? { still: result.still } : {}),
       ...(result.reason === 'browser-missing'
         ? { install: INSTALL_BROWSER }
         : {}),

package/src/commands/tasks.ts

@@ -57,7 +57,10 @@ import {
   type RecordRefused,
   type RecordSelector,
   recordPullRequest,
+  recordSession,
+  type SessionOutcome,
 } from '@/tasks/record'
+import { resolveSessions } from '@/sessions/resolve'
 import {
   type BoardGroup,
   type Finding,
@@ -142,6 +145,13 @@ interface PullRequestCommandOptions {
   readonly root?: string
 }
 
+interface SessionCommandOptions {
+  readonly json?: boolean
+  readonly plan?: string
+  readonly name?: string
+  readonly root?: string
+}
+
 interface PlanLinkCommandOptions {
   readonly add?: boolean
   readonly waiting?: string
@@ -617,6 +627,63 @@ export function register(program: Command): void {
       },
     )
 
+  tasks
+    .command('session')
+    .description('Record a session that worked a task on its Sessions: line')
+    .argument(
+      '<sessionId>',
+      'Full sessionId, as canon sessions list --json carries it',
+    )
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option(
+      '--name <name>',
+      'Name to record, read off the live roster when omitted',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  an id that is not a full sessionId, or an empty name',
+        '  no-name    the roster lists no live session with the id, and no',
+        '             --name was passed',
+        '',
+        'Exit codes:',
+        '  0  the session was added, appended, or already listed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It writes Sessions: <name> (<sessionId>) below the origin, Pull',
+        'request:, and Pending branch: lines, and appends to the line when one',
+        'exists. The id is the key, so a session already listed is reported',
+        'unchanged under the name it was first recorded with. A cloud',
+        'session_ id is accepted, and takes --name since the roster never',
+        'lists it. Safe from a linked worktree, since it resolves the board',
+        'root in-process.',
+        '',
+        'Examples:',
+        '  canon tasks session 0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0 v28.1-trigger-escalation',
+        '  canon tasks session 0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0 --plan task-sessions-line --json',
+        '  canon tasks session session_01AbC v28.1-trigger-escalation --name cloud-canon-a',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        sessionId: string,
+        task: string | undefined,
+        opts: SessionCommandOptions,
+      ) => {
+        process.exitCode = await runSession(sessionId, task, opts)
+      },
+    )
+
   tasks
     .command('plan-link')
     .description("Write or correct a task's Plan: line to point at a plan")
@@ -1259,6 +1326,72 @@ async function runPullRequest(
   return reportPullRequest(outcome, emitJson, root)
 }
 
+async function runSession(
+  sessionId: string,
+  task: string | undefined,
+  opts: SessionCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord(
+      'canon tasks session',
+      selector,
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const name = opts.name ?? (await rosterName(sessionId))
+  const outcome = await recordSession(root, selector, sessionId, name)
+
+  return reportSession(outcome, emitJson, root)
+}
+
+/** The live roster's name for an id, or undefined once the session has exited. */
+async function rosterName(sessionId: string): Promise<string | undefined> {
+  const report = await resolveSessions()
+  if (report.kind === 'absent') return undefined
+
+  return report.sessions.find((session) => session.sessionId === sessionId)
+    ?.name
+}
+
+function reportSession(
+  outcome: SessionOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('canon tasks session', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        sessionId: outcome.sessionId,
+        name: outcome.name,
+        action: outcome.action,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon tasks session')
+  logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
+  logInfo(`${outcome.stem} names ${outcome.name} (${outcome.sessionId})`)
+  if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}
+
 const RENAME_PATTERN = /^Branch: renamed refs\/heads\/(.+) to refs\/heads\//
 
 /**

package/src/design/favicon.ts

@@ -1,37 +1,109 @@
-export interface FaviconColors {
+export interface ThemePair {
   readonly light: string
   readonly dark: string
 }
 
-/** The favicon's own fills, chosen for tab size and apart from the page accent tokens. */
+export interface FaviconColors {
+  /** The tile the mark sits on, dark wherever no theme applies. */
+  readonly tile: ThemePair
+  /** The tile's edge, drawn on light alone. */
+  readonly edge: string
+  /** The c, in the text ink of each theme. */
+  readonly c: ThemePair
+  /** The pip, in the brand pair rather than the page accent. */
+  readonly pip: ThemePair
+}
+
+/** The mark's own colors, picked on the board and kept apart from the page accent tokens. */
 export const FAVICON_COLORS: FaviconColors = {
-  light: '#c42938',
-  dark: '#e54e40',
+  tile: { light: '#fbfaf8', dark: '#1b1a18' },
+  edge: '#dcdad6',
+  c: { light: '#2c2c29', dark: '#d9d7d4' },
+  pip: { light: '#c2380e', dark: '#ff6b42' },
 }
 
-/**
- * The shapes only, with the source's authoring comment dropped. Both fills are
- * replaced by a rule rather than an attribute so one branch can flip both.
- */
-export function renderFavicon(mark: string, colors: FaviconColors): string {
-  const shapes = mark
+/** The mark spans 96 of a 132 tile, with the tile's corner at 28% of its side. */
+const MARK_IN_TILE = 96 / 132
+const TILE_RADIUS = 0.28
+/** About one pixel at a 32 pixel tab icon, drawn inside the tile's bounds. */
+const EDGE_WIDTH = 4
+
+/** The source's shapes, with its authoring comment and `currentColor` fills dropped. */
+function markShapes(mark: string): string {
+  return mark
     .replace(/<!--[\s\S]*?-->/, '')
     .trim()
     .replace(/^<svg[^>]*>/, '')
     .replace(/<\/svg>$/, '')
     .replaceAll(' fill="currentColor"', '')
     .trim()
+}
 
-  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
+function markView(mark: string): [number, number, number, number] {
+  const view = /viewBox="([^"]+)"/
+    .exec(mark)?.[1]
+    .trim()
+    .split(/[\s,]+/)
+  const numbers = view?.map(Number) ?? []
+  if (numbers.length !== 4 || numbers.some((n) => !Number.isFinite(n))) {
+    throw new Error('the mark carries no viewBox of four numbers')
+  }
+  return numbers as [number, number, number, number]
+}
+
+const round = (n: number): number => Math.round(n * 100) / 100
+
+/**
+ * The mark on its tile. The base rules draw the dark set, which a renderer
+ * ignoring the media query shows, and a light preference swaps in the light
+ * set. A browser reports light when no scheme is set, so a tab there shows the
+ * light tile. Every fill is a rule rather than an attribute so the light branch
+ * can flip them all.
+ */
+export function renderFavicon(mark: string, colors: FaviconColors): string {
+  const [x, y, width, height] = markView(mark)
+  const side = Math.max(width, height) / MARK_IN_TILE
+  const left = round(x + width / 2 - side / 2)
+  const top = round(y + height / 2 - side / 2)
+  const inset = EDGE_WIDTH / 2
+  const shapes = markShapes(mark)
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${left} ${top} ${round(side)} ${round(side)}">
   <style>
-    path, rect { fill: ${colors.light}; }
-    @media (prefers-color-scheme: dark) { path, rect { fill: ${colors.dark}; } }
+    .tile { fill: ${colors.tile.dark}; stroke: ${colors.tile.dark}; }
+    .c { fill: ${colors.c.dark}; }
+    .pip { fill: ${colors.pip.dark}; }
+    @media (prefers-color-scheme: light) {
+      .tile { fill: ${colors.tile.light}; stroke: ${colors.edge}; }
+      .c { fill: ${colors.c.light}; }
+      .pip { fill: ${colors.pip.light}; }
+    }
   </style>
+  <rect class="tile" x="${round(left + inset)}" y="${round(top + inset)}" width="${round(side - EDGE_WIDTH)}" height="${round(side - EDGE_WIDTH)}" rx="${round(side * TILE_RADIUS - inset)}" stroke-width="${EDGE_WIDTH}" />
+  <g class="c">
   ${shapes.replace(/\n\s*/g, '\n  ')}
+  </g>
 </svg>
 `
 }
 
+/**
+ * The bare mark in fixed fills, for a surface that loads it as an image and
+ * so has neither a CSS context for `currentColor` nor a theme of its own.
+ */
+export function renderMark(
+  mark: string,
+  fills: { readonly c: string; readonly pip: string },
+): string {
+  const svg = mark.replace(/<!--[\s\S]*?-->/, '').trim()
+  const pipFill = /(<[a-z]+ [^>]*class="pip"[^>]*?) fill="[^"]*"/
+  if (!pipFill.test(svg)) {
+    throw new Error('the mark carries no filled .pip shape')
+  }
+  const pip = svg.replace(pipFill, `$1 fill="${fills.pip}"`)
+  return `${pip.replaceAll('currentColor', fills.c)}\n`
+}
+
 /**
  * The `<link rel="icon">` a page carries the rendered favicon in, inlined so a
  * generated page needs no sibling file and no href that varies with its depth.

package/src/design/reference.ts

@@ -0,0 +1,98 @@
+/**
+ * The pure half of `scripts/core/design-sync.ts`, ported from Frameboard's
+ * own sync. Frameboard frames load a shared kit, while this board's frames
+ * load their project's `../assets/`, so each project's assets land under
+ * `kit/<project>/assets/` in `canon/design/`, mirroring the board, and no two
+ * projects can overwrite one another's files of the same name.
+ */
+
+/** A `frames.json` entry the sync cannot capture, named so the file can be fixed. */
+export class MappingError extends Error {}
+
+const REFERENCE = /^[a-z0-9]+(-[a-z0-9]+)*\/[a-z0-9]+(-[a-z0-9]+)*$/
+const BOARD_REF = /^[^/\s]+\/[^/\s]+\/[^/\s]+$/
+// A link starts at a quote or `url(`, so `../../assets/` is left alone, and a
+// file name stops at `#` or `?`, which address a part of the file.
+const BOARD_LINK = /(["'(]\s*)\.\.\/assets\//g
+const BOARD_ASSET = /["'(]\s*\.\.\/assets\/([^"'()\s#?]+)/g
+
+/**
+ * Reads `frames.json`, mapping each reference, `<group>/<name>`, to the
+ * board frame `<project>/<page>/<frame>` it is captured from. An entry in
+ * any other shape throws rather than filing into the wrong folder.
+ */
+export function parseFrameMap(json: string): Map<string, string> {
+  const parsed: unknown = JSON.parse(json)
+  const frames =
+    typeof parsed === 'object' && parsed !== null && 'frames' in parsed
+      ? parsed.frames
+      : undefined
+  if (typeof frames !== 'object' || frames === null) {
+    throw new MappingError('frames.json needs a frames object.')
+  }
+  const map = new Map<string, string>()
+  for (const [reference, ref] of Object.entries(frames)) {
+    if (!REFERENCE.test(reference)) {
+      throw new MappingError(
+        `frames.json entry "${reference}" needs a kebab-case <group>/<name>.`,
+      )
+    }
+    if (typeof ref !== 'string' || !BOARD_REF.test(ref)) {
+      throw new MappingError(
+        `frames.json entry "${reference}" needs a board frame as <project>/<page>/<frame>.`,
+      )
+    }
+    map.set(reference, ref)
+  }
+  return map
+}
+
+/** The mapped board frames the board does not hold. */
+export function missingFrames(
+  map: ReadonlyMap<string, string>,
+  board: ReadonlySet<string>,
+): string[] {
+  return [...map.values()].filter((ref) => !board.has(ref))
+}
+
+/**
+ * What the folder holds of a board frame: its project asset links moved to
+ * the project's kit, every other link left as the frame wrote it. The HTML
+ * is not reformatted, since the formatter ignores the folder and the sync is
+ * its one writer.
+ */
+export function toReference(html: string, project: string): string {
+  return html.replaceAll(BOARD_LINK, `$1../kit/${project}/assets/`)
+}
+
+/** The project assets a frame loads, by their path under `assets/`, each once. */
+export function boardAssets(html: string): string[] {
+  return [...new Set([...html.matchAll(BOARD_ASSET)].map((match) => match[1]))]
+}
+
+export interface Drift {
+  readonly changed: readonly string[]
+  /** PNGs whose bytes differ, a warning since a PNG varies with the browser build. */
+  readonly pngDiffers: readonly string[]
+  readonly missing: readonly string[]
+  readonly stray: readonly string[]
+}
+
+/** Compares what a sync would write against the files the folder holds, the HTML as the source and a PNG as derived. */
+export function classifyDrift(
+  expected: ReadonlyMap<string, string | Uint8Array>,
+  tracked: ReadonlyMap<string, string | Uint8Array>,
+): Drift {
+  const changed: string[] = []
+  const pngDiffers: string[] = []
+  const missing: string[] = []
+  for (const [path, data] of expected) {
+    const copy = tracked.get(path)
+    if (copy === undefined) missing.push(path)
+    else if (!Buffer.from(copy).equals(Buffer.from(data))) {
+      ;(path.endsWith('.png') ? pngDiffers : changed).push(path)
+    }
+  }
+  const stray = [...tracked.keys()].filter((path) => !expected.has(path))
+  return { changed, pngDiffers, missing, stray }
+}