@erclx/canon 5.52.0 → 5.53.0

package/src/demo/beats.ts

@@ -1,135 +0,0 @@
-/**
- * Reads the human-facing draft `script-screencast` writes. Nothing here knows
- * about a browser: the draft is prose aimed at a person, and turning it into
- * something executable is `@/demo/compile`'s job.
- */
-
-export interface Beat {
-  readonly index: number
-  readonly name: string
-  readonly onScreen: string
-  readonly action: string
-  readonly watchFor: string
-  readonly emphasis: string
-  readonly caption: string
-  readonly transitionOut?: string
-}
-
-export interface Draft {
-  readonly title: string
-  readonly beats: readonly Beat[]
-}
-
-export type DraftParse =
-  | { status: 'parsed'; draft: Draft }
-  | { status: 'failed'; reason: string }
-
-const TITLE = /^#\s+Screencast:\s*(.+)$/m
-const BEAT_SHEET = /^##\s+.*Beat sheet.*$/im
-const BEAT_HEADING = /^###\s+Beat\s+(\d+)\s*:\s*(.*)$/i
-const FIELD = /^-\s+([A-Za-z][A-Za-z\s]*?)\s*:\s*(.*)$/
-
-/**
- * Labels are matched case-insensitively with whitespace collapsed, because the
- * draft is hand-edited between being written and being compiled and a
- * capitalization change there is not a reason to refuse the whole file.
- */
-const FIELDS: Record<string, keyof Beat> = {
-  'on screen': 'onScreen',
-  action: 'action',
-  'watch for': 'watchFor',
-  emphasis: 'emphasis',
-  caption: 'caption',
-  'transition out': 'transitionOut',
-}
-
-export function parseDraft(markdown: string): DraftParse {
-  const sheet = beatSheetSection(markdown)
-  if (sheet === undefined) {
-    return {
-      status: 'failed',
-      reason: 'no "Beat sheet" section, so the draft carries no beats to run',
-    }
-  }
-
-  const beats = readBeats(sheet)
-  if (!beats.length) {
-    return {
-      status: 'failed',
-      reason: 'the beat sheet holds no "### Beat" heading',
-    }
-  }
-
-  return {
-    status: 'parsed',
-    draft: { title: TITLE.exec(markdown)?.[1]?.trim() ?? '', beats },
-  }
-}
-
-/**
- * Returns the lines between the beat sheet heading and the next `##`, so a
- * `### Beat` heading elsewhere in the draft cannot be read as a beat.
- */
-function beatSheetSection(markdown: string): string[] | undefined {
-  const lines = markdown.split('\n')
-  const start = lines.findIndex((line) => BEAT_SHEET.test(line))
-  if (start === -1) return undefined
-
-  const rest = lines.slice(start + 1)
-  const end = rest.findIndex((line) => /^##\s/.test(line))
-  return end === -1 ? rest : rest.slice(0, end)
-}
-
-function readBeats(lines: string[]): Beat[] {
-  const beats: Beat[] = []
-  let open: Partial<Beat> | undefined
-
-  for (const line of lines) {
-    const heading = BEAT_HEADING.exec(line)
-    if (heading) {
-      if (open) beats.push(sealBeat(open))
-      open = {
-        index: Number(heading[1]),
-        name: (heading[2] ?? '').trim(),
-      }
-      continue
-    }
-
-    if (!open) continue
-    const field = FIELD.exec(line)
-    if (!field) continue
-
-    const key = FIELDS[normalizeLabel(field[1] ?? '')]
-    if (key) open = { ...open, [key]: (field[2] ?? '').trim() }
-  }
-
-  if (open) beats.push(sealBeat(open))
-  return beats
-}
-
-/**
- * Fills the five required fields with empty strings rather than leaving them
- * undefined, so a downstream reader distinguishes "the operator left it blank"
- * from "the label was misspelt" by the presence of the key alone.
- *
- * `transitionOut` stays optional, because the draft adds it only when it is
- * not the default and an empty one would claim a decision nobody made.
- */
-function sealBeat(open: Partial<Beat>): Beat {
-  const beat: Beat = {
-    index: open.index ?? 0,
-    name: open.name ?? '',
-    onScreen: open.onScreen ?? '',
-    action: open.action ?? '',
-    watchFor: open.watchFor ?? '',
-    emphasis: open.emphasis ?? '',
-    caption: open.caption ?? '',
-  }
-  return open.transitionOut === undefined
-    ? beat
-    : { ...beat, transitionOut: open.transitionOut }
-}
-
-function normalizeLabel(label: string): string {
-  return label.trim().toLowerCase().replace(/\s+/g, ' ')
-}

package/src/demo/compile.ts

@@ -1,350 +0,0 @@
-import type { Beat, Draft } from '@/demo/beats'
-
-/**
- * Turns the human-facing draft into the machine-facing plan. The two are
- * separate artifacts on purpose: a beat carries no target, no wait condition,
- * and no timing, and putting those four fields on every beat would destroy the
- * property the draft was designed around. See
- * `.canon/groundwork/38-demo-recorder/06-decision.md`.
- *
- * A compiled plan is committed rather than scratch, because the timing below is
- * a starting point the operator tunes and the draft cannot reproduce a tuned
- * value.
- */
-
-/** Hand-tuned in spike 2 against one fixture. Nothing establishes them in general. */
-const POINTER_TRAVEL_MS = 400
-const TYPE_DELAY_MS = 110
-const HOLD_MS = 600
-const FINAL_HOLD_MS = 1200
-
-/**
- * A step is a round trip to the browser, so a fixed count reproduces the
- * defect under a new name if it does not respond to the round-trip cost
- * measured at drive time. The bounds guard the extremes a bad measurement
- * could produce: too few steps teleports rather than glides, and a
- * near-zero measured cost cannot be trusted enough to let the count run
- * away.
- *
- * Measured on 2026-08-26 against a served fixture, post-navigation: 10
- * rounds of `page.mouse.move` averaged 16.6 milliseconds a step, well short
- * of either bound at the 400 millisecond default (about 24 steps). A
- * machine landing under `POINTER_TRAVEL_MS / MAX_POINTER_STEPS`, 3.33
- * milliseconds a step here, hits the cap and stops responding to a faster
- * one still. Nothing measured here establishes where a real machine sits
- * relative to that boundary in general.
- */
-export const MIN_POINTER_STEPS = 6
-export const MAX_POINTER_STEPS = 120
-
-/**
- * Pure on purpose: the round-trip cost comes from a real browser and can
- * only be measured at drive time, so this takes it as an argument rather
- * than measuring it itself, which is what keeps it testable against a
- * stubbed cost.
- */
-export function deriveSteps(travelMs: number, roundTripMs: number): number {
-  if (roundTripMs <= 0) return MAX_POINTER_STEPS
-  const steps = Math.round(travelMs / roundTripMs)
-  return Math.min(MAX_POINTER_STEPS, Math.max(MIN_POINTER_STEPS, steps))
-}
-
-const VIEWPORT = { width: 1280, height: 720 } as const
-const ANNOTATIONS = {
-  durationMs: 900,
-  position: 'bottom-right',
-  fontSize: 22,
-} as const
-
-export type StepKind =
-  | 'navigate'
-  | 'click'
-  | 'fill'
-  | 'hover'
-  | 'scroll'
-  | 'wait'
-  | 'hold'
-
-/** Verbs that point at an element, so a plan without a target cannot run. */
-const TARGETED: ReadonlySet<StepKind> = new Set<StepKind>([
-  'click',
-  'fill',
-  'hover',
-  'scroll',
-])
-
-const VERBS: Record<string, StepKind> = {
-  navigate: 'navigate',
-  open: 'navigate',
-  visit: 'navigate',
-  load: 'navigate',
-  click: 'click',
-  press: 'click',
-  tap: 'click',
-  submit: 'click',
-  toggle: 'click',
-  type: 'fill',
-  fill: 'fill',
-  enter: 'fill',
-  input: 'fill',
-  hover: 'hover',
-  scroll: 'scroll',
-  wait: 'wait',
-  pause: 'wait',
-  settle: 'wait',
-}
-
-export interface DemoStep {
-  readonly beat: number
-  readonly name: string
-  readonly kind: StepKind
-  readonly target: string
-  readonly text: string
-  readonly waitFor: string
-  readonly holdMs: number
-  readonly caption: string
-  readonly still: boolean
-  readonly note?: string
-}
-
-export type ColorScheme = 'light' | 'dark'
-
-export interface DemoPlan {
-  readonly slug: string
-  readonly title: string
-  readonly url: string
-  readonly viewport: { readonly width: number; readonly height: number }
-  readonly colorScheme?: ColorScheme
-  readonly output: { readonly video: string; readonly still: string }
-  readonly pointer: { readonly travelMs: number; readonly typeDelayMs: number }
-  readonly annotations: typeof ANNOTATIONS
-  readonly steps: readonly DemoStep[]
-}
-
-export interface CompileOptions {
-  readonly slug: string
-  readonly outDir: string
-}
-
-export function compilePlan(draft: Draft, options: CompileOptions): DemoPlan {
-  const stillAt = heroIndex(draft.beats)
-  return {
-    slug: options.slug,
-    title: draft.title,
-    url: '',
-    viewport: VIEWPORT,
-    output: {
-      video: `${options.outDir}/${options.slug}/take/${options.slug}.webm`,
-      still: `${options.outDir}/${options.slug}/take/${options.slug}.png`,
-    },
-    pointer: { travelMs: POINTER_TRAVEL_MS, typeDelayMs: TYPE_DELAY_MS },
-    annotations: ANNOTATIONS,
-    steps: draft.beats.map((beat, position) =>
-      compileStep(beat, {
-        still: position === stillAt,
-        last: position === draft.beats.length - 1,
-      }),
-    ),
-  }
-}
-
-function compileStep(
-  beat: Beat,
-  place: { still: boolean; last: boolean },
-): DemoStep {
-  const verb = firstVerb(beat.action)
-  const kind = verb ? VERBS[verb] : undefined
-  const step: DemoStep = {
-    beat: beat.index,
-    name: beat.name,
-    kind: kind ?? 'hold',
-    target: '',
-    text: '',
-    waitFor: '',
-    holdMs: place.last ? FINAL_HOLD_MS : HOLD_MS,
-    caption: beat.caption,
-    still: place.still,
-  }
-
-  if (kind) return step
-  return {
-    ...step,
-    note: `no step maps to the verb "${beat.action.trim()}", so this beat only waits`,
-  }
-}
-
-/**
- * The draft specifies one verb per beat, and a hand-edited beat reads as a
- * phrase often enough that matching only the whole field would refuse work a
- * reader can see is a click. The first recognized word wins.
- */
-function firstVerb(action: string): string | undefined {
-  return action
-    .toLowerCase()
-    .split(/[^a-z]+/)
-    .find((word) => word in VERBS)
-}
-
-/**
- * The still is a landing frame, so it wants the beat the draft calls the hero
- * rather than an arbitrary one. Falling back to the last beat rather than the
- * first is deliberate: a demo's final state is the payoff, and a cold open is
- * usually an empty screen.
- */
-function heroIndex(beats: readonly Beat[]): number {
-  const named = beats.findIndex((beat) => /hero/i.test(beat.name))
-  return named === -1 ? beats.length - 1 : named
-}
-
-export type PlanParse =
-  | { status: 'parsed'; plan: DemoPlan }
-  | { status: 'failed'; reason: string }
-
-/**
- * Validates a plan read off disk. The file is hand-edited between being
- * compiled and being run, which is the whole reason it is committed rather than
- * regenerated, so every field is checked here rather than trusted.
- *
- * An absent field takes the seeded default and a present one is kept, so a
- * plan that dropped a timing block still runs while a tuned one is never
- * overwritten.
- */
-export function parsePlan(text: string): PlanParse {
-  let raw: unknown
-  try {
-    raw = JSON.parse(text)
-  } catch (error) {
-    return {
-      status: 'failed',
-      reason: error instanceof Error ? error.message : 'unreadable json',
-    }
-  }
-
-  if (!isRecord(raw)) return { status: 'failed', reason: 'not a json object' }
-  if (!Array.isArray(raw.steps))
-    return { status: 'failed', reason: 'steps is not an array' }
-  if (!raw.steps.length) return { status: 'failed', reason: 'steps is empty' }
-
-  const steps: DemoStep[] = []
-  for (const [index, entry] of raw.steps.entries()) {
-    const step = parseStep(entry, index)
-    if ('reason' in step) return { status: 'failed', reason: step.reason }
-    steps.push(step.step)
-  }
-
-  const colorScheme = parseColorScheme(raw.colorScheme)
-  if (colorScheme.status === 'failed') return colorScheme
-
-  const slug = asText(raw.slug)
-  const output = isRecord(raw.output) ? raw.output : {}
-  const pointer = isRecord(raw.pointer) ? raw.pointer : {}
-  const viewport = isRecord(raw.viewport) ? raw.viewport : {}
-
-  return {
-    status: 'parsed',
-    plan: {
-      slug,
-      title: asText(raw.title),
-      url: asText(raw.url),
-      viewport: {
-        width: asNumber(viewport.width, VIEWPORT.width),
-        height: asNumber(viewport.height, VIEWPORT.height),
-      },
-      ...(colorScheme.value && { colorScheme: colorScheme.value }),
-      output: {
-        video:
-          asText(output.video) ||
-          `demos/${slug || 'demo'}/take/${slug || 'demo'}.webm`,
-        still:
-          asText(output.still) ||
-          `demos/${slug || 'demo'}/take/${slug || 'demo'}.png`,
-      },
-      pointer: {
-        travelMs: asNumber(pointer.travelMs, POINTER_TRAVEL_MS),
-        typeDelayMs: asNumber(pointer.typeDelayMs, TYPE_DELAY_MS),
-      },
-      annotations: ANNOTATIONS,
-      steps,
-    },
-  }
-}
-
-function parseColorScheme(
-  value: unknown,
-):
-  | { status: 'ok'; value?: ColorScheme }
-  | { status: 'failed'; reason: string } {
-  if (value === undefined) return { status: 'ok' }
-  if (value === 'light' || value === 'dark') return { status: 'ok', value }
-  return {
-    status: 'failed',
-    reason: `colorScheme is ${JSON.stringify(value)}, which is not light or dark`,
-  }
-}
-
-function parseStep(
-  entry: unknown,
-  index: number,
-): { step: DemoStep } | { reason: string } {
-  if (!isRecord(entry)) return { reason: `steps[${index}] is not an object` }
-
-  const kind = asText(entry.kind)
-  if (!isStepKind(kind)) {
-    return {
-      reason: `steps[${index}].kind is "${kind}", which is not a step this can drive`,
-    }
-  }
-
-  const step: DemoStep = {
-    beat: asNumber(entry.beat, index + 1),
-    name: asText(entry.name),
-    kind,
-    target: asText(entry.target),
-    text: asText(entry.text),
-    waitFor: asText(entry.waitFor),
-    holdMs: asNumber(entry.holdMs, HOLD_MS),
-    caption: asText(entry.caption),
-    still: entry.still === true,
-  }
-  const note = asText(entry.note)
-  return { step: note ? { ...step, note } : step }
-}
-
-function isStepKind(value: string): value is StepKind {
-  return (
-    value === 'navigate' ||
-    value === 'click' ||
-    value === 'fill' ||
-    value === 'hover' ||
-    value === 'scroll' ||
-    value === 'wait' ||
-    value === 'hold'
-  )
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function asText(value: unknown): string {
-  return typeof value === 'string' ? value : ''
-}
-
-function asNumber(value: unknown, fallback: number): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
-}
-
-/**
- * Names every field a person still has to fill before the plan can drive
- * anything. Compile reports these and run refuses on them, so an unfilled plan
- * fails at the point it is written rather than part-way through a recording.
- */
-export function unresolved(plan: DemoPlan): string[] {
-  const missing: string[] = plan.url.trim() ? [] : ['url']
-  plan.steps.forEach((step, index) => {
-    if (TARGETED.has(step.kind) && !step.target.trim()) {
-      missing.push(`steps[${index}].target`)
-    }
-  })
-  return missing
-}

package/src/demo/container.ts

@@ -1,219 +0,0 @@
-import { existsSync, mkdirSync, rmSync } from 'node:fs'
-import { join, parse } from 'node:path'
-import { execa } from 'execa'
-
-/**
- * A post-step on the file `@/demo/drive` already wrote. It touches neither
- * the compiler nor the driving code, which is why deferring it out of the
- * feature that shipped first cost no rework.
- */
-
-const CONVERTER_BIN = 'ffmpeg'
-export const INSTALL_CONVERTER = 'ffmpeg (see https://ffmpeg.org/download.html)'
-
-export type ContainerResult =
-  | { status: 'converted'; mp4Path: string }
-  | { status: 'skipped'; reason: 'converter-missing' }
-  | { status: 'failed'; reason: string }
-
-export type GifResult =
-  | { status: 'converted'; gifPath: string }
-  | { status: 'skipped'; reason: 'converter-missing' }
-  | { status: 'failed'; reason: string }
-
-export type FramesResult =
-  | { status: 'extracted'; framePaths: string[] }
-  | { status: 'skipped'; reason: 'converter-missing' }
-  | { status: 'failed'; reason: string }
-
-export interface ExtractFramesOptions {
-  readonly fps?: number
-}
-
-/**
- * Writes mp4 beside the webm rather than instead of it, since both stated use
- * cases are a `<video>` tag on a page the operator controls, where webm
- * already plays, and the social platform case is what mp4 is for.
- *
- * A missing binary is reported as skipped rather than failed. The recording
- * already succeeded, and failing the run over an optional step would discard
- * a good artifact.
- */
-export async function convertToMp4(
-  webmPath: string,
-  bin: string = CONVERTER_BIN,
-): Promise<ContainerResult> {
-  const { dir, name } = parse(webmPath)
-  const mp4Path = join(dir, `${name}.mp4`)
-
-  const result = await execa(
-    bin,
-    [
-      '-y',
-      '-i',
-      webmPath,
-      '-c:v',
-      'libx264',
-      '-pix_fmt',
-      'yuv420p',
-      '-c:a',
-      'aac',
-      '-movflags',
-      '+faststart',
-      mp4Path,
-    ],
-    { reject: false },
-  )
-
-  if (result.failed && result.code === 'ENOENT') {
-    return { status: 'skipped', reason: 'converter-missing' }
-  }
-  if (result.exitCode !== 0) {
-    return {
-      status: 'failed',
-      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
-    }
-  }
-  return { status: 'converted', mp4Path }
-}
-
-/**
- * Opt-in rather than written beside every recording, because a gif is an order
- * of magnitude larger than the webm it derives from and only one destination
- * needs one: a README on a host that strips `<video>`, which GitHub does. The
- * mp4 above is unconditional for the opposite reason, being cheap and wanted
- * wherever the webm already plays.
- *
- * A palette is generated from the source and then applied, rather than letting
- * ffmpeg quantize per frame. A per-frame palette is what makes a screen
- * recording of flat UI colors band and shimmer, which is precisely the artifact
- * that would make a page look worse in the README than it does in a browser.
- *
- * Dithering is off because this command records applications rather than
- * photographs. A global palette already covers flat interface colors, so the
- * dither only writes noise the encoder then has to store: measured at 3.19MB
- * against 2.70MB on one recording, with the same text region cropped from both
- * and read as visually identical. Width is the larger lever at 2.38MB for 800
- * pixels, and it is not taken, since the terminal rows are what the recording
- * exists to have read. Frame rate is almost no lever at all.
- *
- * The missing-binary and failure handling matches `convertToMp4` exactly: the
- * recording already succeeded by the time this runs, so an optional step never
- * fails the run.
- */
-export async function convertToGif(
-  webmPath: string,
-  bin: string = CONVERTER_BIN,
-): Promise<GifResult> {
-  const { dir, name } = parse(webmPath)
-  const gifPath = join(dir, `${name}.gif`)
-
-  const result = await execa(
-    bin,
-    [
-      '-y',
-      '-i',
-      webmPath,
-      '-filter_complex',
-      '[0:v] fps=12,scale=960:-1:flags=lanczos,split [a][b];[a] palettegen [p];[b][p] paletteuse=dither=none',
-      gifPath,
-    ],
-    { reject: false },
-  )
-
-  if (result.failed && result.code === 'ENOENT') {
-    return { status: 'skipped', reason: 'converter-missing' }
-  }
-  if (result.exitCode !== 0) {
-    return {
-      status: 'failed',
-      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
-    }
-  }
-  return { status: 'converted', gifPath }
-}
-
-/**
- * Written beside the video by default, so frames fall under the same
- * `take` folder gitignore entry the still already uses with no new rule
- * needed. One frame a second by default, matched to the seconds-to-tens-of-
- * seconds length a tuned recording runs, without a smarter sampling strategy
- * nobody has asked for.
- *
- * The missing-binary and failure handling matches `convertToMp4` exactly: the
- * recording already succeeded by the time this runs, so an optional step
- * never fails the run.
- *
- * A prior extraction's frames are cleared before ffmpeg runs, not left for
- * `-y` to overwrite. ffmpeg's `-y` only overwrites the indices this run
- * produces, so a shorter re-extraction against the same video's stable
- * output path (the plan's declared `output.video`, unchanged across
- * re-records) would otherwise leave the previous run's tail in place,
- * sorted into the returned list as if it were still current.
- */
-export async function extractFrames(
-  videoPath: string,
-  outDir?: string,
-  opts: ExtractFramesOptions = {},
-  bin: string = CONVERTER_BIN,
-): Promise<FramesResult> {
-  const { dir, name } = parse(videoPath)
-  const targetDir = outDir ?? dir
-  const fps = opts.fps ?? 1
-  if (outDir) mkdirSync(outDir, { recursive: true })
-
-  if (existsSync(targetDir)) {
-    for (const stale of new Bun.Glob(`${name}-frame-*.png`).scanSync({
-      cwd: targetDir,
-      onlyFiles: true,
-    })) {
-      rmSync(join(targetDir, stale))
-    }
-  }
-
-  const pattern = join(targetDir, `${name}-frame-%03d.png`)
-  const result = await execa(
-    bin,
-    ['-y', '-i', videoPath, '-vf', `fps=${fps}`, pattern],
-    { reject: false },
-  )
-
-  if (result.failed && result.code === 'ENOENT') {
-    return { status: 'skipped', reason: 'converter-missing' }
-  }
-  if (result.exitCode !== 0) {
-    return {
-      status: 'failed',
-      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
-    }
-  }
-
-  return { status: 'extracted', framePaths: collectFrames(targetDir, name) }
-}
-
-/**
- * The glob-and-sort step `extractFrames` reads its result from, pulled out so
- * a test can drive it against a directory it wrote by hand rather than
- * through a real extraction, which is the only way to reach the four-digit
- * boundary below without an ffmpeg run long enough to produce one.
- *
- * ffmpeg's `%03d` pads to three characters and then widens rather than
- * truncating, so a run producing 1000 or more frames writes `-1000.png`
- * beside `-999.png`, and a lexicographic sort reads the wider name first.
- * `frameIndex` sorts on the parsed number instead.
- */
-export function collectFrames(targetDir: string, name: string): string[] {
-  return [
-    ...new Bun.Glob(`${name}-frame-*.png`).scanSync({
-      cwd: targetDir,
-      onlyFiles: true,
-    }),
-  ]
-    .sort((a, b) => frameIndex(a) - frameIndex(b))
-    .map((frame) => join(targetDir, frame))
-}
-
-function frameIndex(filename: string): number {
-  const match = filename.match(/-frame-(\d+)\.png$/)
-  return match ? Number(match[1]) : 0
-}