@erclx/canon 5.66.0 → 5.67.0

package/src/take/film.ts

@@ -0,0 +1,206 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
+import { cameraTrack } from '@/take/camera'
+import { FfmpegMissing, requireFfmpeg } from '@/take/encode'
+import {
+  FPS,
+  LOG_VERSION,
+  type LogEvent,
+  type TakeLog,
+  VIEWPORT,
+} from '@/take/log'
+import { TargetMissing } from '@/take/perform'
+import type { Beat, Route, TakePlan } from '@/take/plan'
+import { filmScreencast } from '@/take/screencast'
+import { ShellMissing, findShell } from '@/take/shell'
+import { StepperStalled, filmStepped } from '@/take/stepper'
+
+/**
+ * Films every beat of a plan into its own folder and writes the record the
+ * edit reads. Each beat opens the page fresh, so a beat starts from the state
+ * its setup reaches rather than wherever the last one left the page.
+ */
+
+export const TAKE_VERSION = 1
+
+export type TakeRefusal =
+  | 'ffmpeg-missing'
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'target-missing'
+  | 'take-failed'
+
+export interface FilmedBeat {
+  readonly name: string
+  /** The beat's folder, relative to the take's. */
+  readonly dir: string
+  readonly requested: Route
+  readonly route: Route
+  /** Why a `step` beat was filmed by screencast instead, when it was. */
+  readonly fallback?: string
+  readonly frames: number
+  readonly seconds: number
+  readonly clip: string
+  readonly log: string
+  readonly camera: string
+}
+
+export type TakeResult =
+  | {
+      readonly status: 'filmed'
+      readonly out: string
+      readonly beats: readonly FilmedBeat[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: TakeRefusal
+      readonly message: string
+      readonly beat?: string
+    }
+
+export interface TakeRequest {
+  readonly url: string
+  readonly plan: TakePlan
+  readonly out: string
+  readonly env?: NodeJS.ProcessEnv
+}
+
+const REACH_TIMEOUT_MS = 5000
+
+export async function take(request: TakeRequest): Promise<TakeResult> {
+  const started = Date.now()
+  const out = resolve(request.out)
+
+  try {
+    await requireFfmpeg()
+  } catch (error) {
+    if (error instanceof FfmpegMissing) return failed('ffmpeg-missing', error)
+    throw error
+  }
+
+  let executable = ''
+  if (request.plan.beats.some((beat) => beat.route === 'step')) {
+    try {
+      executable = findShell(request.env)
+    } catch (error) {
+      if (error instanceof ShellMissing) return failed('browser-missing', error)
+      throw error
+    }
+  }
+
+  // Probes the origin rather than the address, since an address can carry a
+  // single-use ticket that a probe would spend before the browser opens it.
+  try {
+    await fetch(new URL(request.url).origin, {
+      signal: AbortSignal.timeout(REACH_TIMEOUT_MS),
+    })
+  } catch (error) {
+    return failed('server-unreachable', error)
+  }
+
+  mkdirSync(out, { recursive: true })
+  const beats: FilmedBeat[] = []
+  for (const [index, beat] of request.plan.beats.entries()) {
+    const dir = `${String(index + 1).padStart(2, '0')}-${slug(beat.name)}`
+    mkdirSync(join(out, dir), { recursive: true })
+    try {
+      beats.push(await filmBeat(request.url, beat, out, dir, executable))
+    } catch (error) {
+      return failed(classify(error), error, beat.name)
+    }
+  }
+
+  writeFileSync(
+    join(out, 'take.json'),
+    `${JSON.stringify({ version: TAKE_VERSION, url: request.url, beats }, null, 2)}\n`,
+  )
+  return { status: 'filmed', out, beats, durationMs: Date.now() - started }
+}
+
+async function filmBeat(
+  url: string,
+  beat: Beat,
+  out: string,
+  dir: string,
+  executable: string,
+): Promise<FilmedBeat> {
+  const clip = join(dir, 'clip.mp4')
+  const target = join(out, clip)
+
+  let route: Route = beat.route
+  let fallback: string | undefined
+  let filmed: { frames: number; events: readonly LogEvent[] }
+  if (beat.route === 'step') {
+    try {
+      filmed = await filmStepped({ executable, url, beat, clip: target })
+    } catch (error) {
+      if (!(error instanceof StepperStalled)) throw error
+      route = 'screencast'
+      fallback = error.message
+      filmed = await filmScreencast({ url, beat, clip: target })
+    }
+  } else {
+    filmed = await filmScreencast({ url, beat, clip: target })
+  }
+
+  const log: TakeLog = {
+    version: LOG_VERSION,
+    viewport: VIEWPORT,
+    fps: FPS,
+    route,
+    frames: filmed.frames,
+    events: filmed.events,
+  }
+  const logPath = join(dir, 'log.json')
+  writeFileSync(join(out, logPath), `${JSON.stringify(log, null, 2)}\n`)
+  // One line, since it carries a row per frame and nobody reads it by eye.
+  const cameraPath = join(dir, 'camera.json')
+  writeFileSync(join(out, cameraPath), `${JSON.stringify(cameraTrack(log))}\n`)
+
+  return {
+    name: beat.name,
+    dir,
+    requested: beat.route,
+    route,
+    ...(fallback ? { fallback } : {}),
+    frames: filmed.frames,
+    seconds: Number((filmed.frames / FPS).toFixed(2)),
+    clip,
+    log: logPath,
+    camera: cameraPath,
+  }
+}
+
+function classify(error: unknown): TakeRefusal {
+  if (error instanceof TargetMissing) return 'target-missing'
+  if (error instanceof ShellMissing || isBrowserMissing(error)) {
+    return 'browser-missing'
+  }
+  if (isServerUnreachable(error)) return 'server-unreachable'
+  return 'take-failed'
+}
+
+function failed(
+  reason: TakeRefusal,
+  error: unknown,
+  beat?: string,
+): TakeResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+    ...(beat ? { beat } : {}),
+  }
+}
+
+function slug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 40) || 'beat'
+  )
+}

package/src/take/fixtures/fade.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Fade</title>
+    <!--
+      A band that fades from black to white over exactly one second of page
+      time once the button is pressed, so its brightness frame by frame reads
+      how much page time each frame of a take advanced.
+    -->
+    <style>
+      body {
+        margin: 0;
+        background: #808080;
+      }
+
+      #go {
+        position: absolute;
+        left: 100px;
+        top: 100px;
+        width: 200px;
+        height: 60px;
+      }
+
+      #band {
+        position: absolute;
+        left: 0;
+        top: 300px;
+        width: 1920px;
+        height: 780px;
+        background-color: #000;
+        transition: background-color 1000ms linear;
+      }
+
+      #band.lit {
+        background-color: #fff;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="go">Go</button>
+    <div id="band"></div>
+    <script>
+      document.getElementById('go').addEventListener('click', () => {
+        document.getElementById('band').classList.add('lit')
+      })
+    </script>
+  </body>
+</html>

package/src/take/fixtures/fetch.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Fetch</title>
+    <!--
+      A button whose press starts a fetch the server answers slowly, the way
+      a page switch in an app loads what the next view shows. A take must keep
+      stepping frames while the fetch is in flight.
+    -->
+    <style>
+      body {
+        margin: 0;
+        background: #808080;
+      }
+
+      #go {
+        position: absolute;
+        left: 100px;
+        top: 100px;
+        width: 200px;
+        height: 60px;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="go">Load</button>
+    <p id="status">idle</p>
+    <script>
+      document.getElementById('go').addEventListener('click', () => {
+        document.getElementById('status').textContent = 'loading'
+        fetch('/slow').then(() => {
+          document.getElementById('status').textContent = 'loaded'
+        })
+      })
+    </script>
+  </body>
+</html>

package/src/take/log.ts

@@ -0,0 +1,109 @@
+import type { Route } from '@/take/plan'
+
+/**
+ * The click log a take writes beside its clip, and the pointer path both
+ * capture routes move along and the camera reads back. Every coordinate is in
+ * CSS pixels of the page, and every time is in milliseconds on the clip's own
+ * clock, so frame `n` sits at `n * 1000 / FPS` whatever route filmed it.
+ *
+ * The path lives here rather than in a capture route because the edit draws the
+ * cursor from this log, so the route moving the real pointer and the reader
+ * redrawing it have to agree on one curve.
+ */
+
+export const LOG_VERSION = 1
+
+export const FPS = 60
+
+/** The page a take films, in CSS pixels. The stepper renders it at twice this. */
+export const VIEWPORT = { width: 1920, height: 1080 } as const
+
+export interface Point {
+  readonly x: number
+  readonly y: number
+}
+
+export interface Box {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+export type LogEvent =
+  | {
+      readonly t: number
+      readonly kind: 'move'
+      readonly from: Point
+      readonly to: Point
+      readonly ms: number
+    }
+  | {
+      readonly t: number
+      readonly kind: 'click'
+      readonly at: Point
+      readonly box: Box
+    }
+  | {
+      readonly t: number
+      readonly kind: 'type'
+      readonly at: Point
+      readonly box: Box
+      readonly chars: number
+      /** From the first key to the last, so the camera holds for the burst. */
+      readonly ms: number
+    }
+  | {
+      readonly t: number
+      readonly kind: 'scroll'
+      readonly at: Point
+      readonly dx: number
+      readonly dy: number
+      readonly ms: number
+    }
+
+export interface TakeLog {
+  readonly version: typeof LOG_VERSION
+  readonly viewport: { readonly width: number; readonly height: number }
+  readonly fps: number
+  /** The route that filmed the clip, which can differ from the one asked for. */
+  readonly route: Route
+  readonly frames: number
+  readonly events: readonly LogEvent[]
+}
+
+/** Where the pointer rests before a take's first move. */
+export const START: Point = { x: VIEWPORT.width / 2, y: VIEWPORT.height / 2 }
+
+/**
+ * How long the pointer takes to travel, slower for longer reaches and never so
+ * quick that a viewer loses it. Carried over from the groundwork takes the
+ * camera presets were judged on.
+ */
+export function travelMs(from: Point, to: Point): number {
+  return Math.min(
+    1200,
+    Math.max(300, Math.hypot(to.x - from.x, to.y - from.y) * 0.9),
+  )
+}
+
+export function easeInOutCubic(t: number): number {
+  const x = Math.max(0, Math.min(1, t))
+  return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2
+}
+
+export function along(from: Point, to: Point, progress: number): Point {
+  const k = easeInOutCubic(progress)
+  return { x: from.x + (to.x - from.x) * k, y: from.y + (to.y - from.y) * k }
+}
+
+/** The pointer's position at a time on the clip's clock, read off the moves. */
+export function cursorAt(events: readonly LogEvent[], ms: number): Point {
+  let position = START
+  for (const event of events) {
+    if (event.kind !== 'move') continue
+    if (ms < event.t) break
+    position = along(event.from, event.to, (ms - event.t) / event.ms)
+  }
+  return position
+}

package/src/take/perform.ts

@@ -0,0 +1,200 @@
+import {
+  type Box,
+  FPS,
+  type LogEvent,
+  type Point,
+  along,
+  travelMs,
+} from '@/take/log'
+import type { TakeStep } from '@/take/plan'
+
+/**
+ * Performs a beat's steps through a stage and logs what the edit needs. The
+ * choreography sits here once, and each capture route supplies the stage, being
+ * how an input reaches the page and how clip time passes, so a beat moves the
+ * same way whichever route filmed it.
+ */
+
+const FRAME_MS = 1000 / FPS
+
+/** The gap between keys, slow enough that a viewer reads each one land. */
+const KEY_MS = 90
+
+/** How long a scroll's wheel travel runs. */
+const SCROLL_MS = 900
+
+export type PointerInput =
+  | {
+      readonly type: 'move' | 'down' | 'up'
+      readonly x: number
+      readonly y: number
+    }
+  | {
+      readonly type: 'wheel'
+      readonly x: number
+      readonly y: number
+      readonly dy: number
+    }
+
+export interface Stage {
+  /** Milliseconds on the clip's own clock. */
+  now(): number
+  /** Lets `ms` of clip time pass. */
+  hold(ms: number): Promise<void>
+  /** Sends one pointer input and lets one frame pass. */
+  pointer(input: PointerInput): Promise<void>
+  /** Types one character into the focused field and lets one frame pass. */
+  key(text: string): Promise<void>
+  /** Evaluates an expression in the page. */
+  evaluate<T>(expression: string): Promise<T>
+}
+
+/** A target that resolved to nothing, which refuses rather than films a guess. */
+export class TargetMissing extends Error {
+  constructor(readonly target: string) {
+    super(`nothing on the page matches ${target}`)
+  }
+}
+
+export interface Performance {
+  pointer: Point
+  /** Omitted for setup steps, which run before the clip starts. */
+  readonly log?: LogEvent[]
+}
+
+export async function performSteps(
+  stage: Stage,
+  steps: readonly TakeStep[],
+  state: Performance,
+): Promise<void> {
+  for (const step of steps) {
+    switch (step.kind) {
+      case 'move':
+        await moveTo(
+          stage,
+          state,
+          'target' in step ? center(await boxOf(stage, step.target)) : step,
+        )
+        break
+      case 'click':
+        await click(stage, state, await boxOf(stage, step.target))
+        break
+      case 'fill': {
+        const box = await boxOf(stage, step.target)
+        await click(stage, state, box)
+        const start = stage.now()
+        for (const character of step.text) {
+          await stage.key(character)
+          await stage.hold(KEY_MS - FRAME_MS)
+        }
+        state.log?.push({
+          t: start,
+          kind: 'type',
+          at: state.pointer,
+          box,
+          chars: step.text.length,
+          ms: stage.now() - start,
+        })
+        break
+      }
+      case 'scroll': {
+        const at = center(await boxOf(stage, step.target))
+        await moveTo(stage, state, at)
+        const frames = Math.round(SCROLL_MS / FRAME_MS)
+        state.log?.push({
+          t: stage.now(),
+          kind: 'scroll',
+          at,
+          dx: 0,
+          dy: step.dy,
+          ms: frames * FRAME_MS,
+        })
+        let sent = 0
+        for (let frame = 1; frame <= frames; frame += 1) {
+          const want = along(
+            { x: 0, y: 0 },
+            { x: 0, y: step.dy },
+            frame / frames,
+          ).y
+          await stage.pointer({ type: 'wheel', ...at, dy: want - sent })
+          sent = want
+        }
+        break
+      }
+      case 'wait':
+        await stage.hold(step.ms)
+        break
+    }
+  }
+}
+
+async function moveTo(
+  stage: Stage,
+  state: Performance,
+  to: Point,
+): Promise<void> {
+  const from = state.pointer
+  if (Math.hypot(to.x - from.x, to.y - from.y) < 1) return
+  const frames = Math.max(1, Math.round(travelMs(from, to) / FRAME_MS))
+  state.log?.push({
+    t: stage.now(),
+    kind: 'move',
+    from,
+    to,
+    ms: frames * FRAME_MS,
+  })
+  for (let frame = 1; frame <= frames; frame += 1) {
+    state.pointer = along(from, to, frame / frames)
+    await stage.pointer({ type: 'move', ...state.pointer })
+  }
+  state.pointer = to
+}
+
+async function click(
+  stage: Stage,
+  state: Performance,
+  box: Box,
+): Promise<void> {
+  const at = center(box)
+  await moveTo(stage, state, at)
+  state.log?.push({ t: stage.now(), kind: 'click', at, box })
+  await stage.pointer({ type: 'down', ...at })
+  await stage.pointer({ type: 'up', ...at })
+}
+
+function center(box: Box): Point {
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 }
+}
+
+async function boxOf(stage: Stage, target: string): Promise<Box> {
+  const box = await stage.evaluate<Box | null>(boxExpression(target))
+  if (!box) throw new TargetMissing(target)
+  return box
+}
+
+/**
+ * Finds a target's box in CSS pixels, reading `text=<words>` as the innermost
+ * element whose whole text is those words and anything else as a CSS selector.
+ * It runs inside the page so both routes resolve a target the same way, and a
+ * match with no size counts as missing, since a click on it would land on
+ * whatever sits behind.
+ */
+export function boxExpression(target: string): string {
+  return `(() => {
+    const target = ${JSON.stringify(target)}
+    let element = null
+    if (target.startsWith('text=')) {
+      const want = target.slice(5).trim()
+      const matches = [...document.querySelectorAll('body *')].filter(
+        (node) => node.textContent.trim() === want,
+      )
+      element = matches.find((node) => !matches.some((other) => other !== node && node.contains(other))) ?? null
+    } else {
+      element = document.querySelector(target)
+    }
+    if (!element) return null
+    const rect = element.getBoundingClientRect()
+    if (rect.width === 0 || rect.height === 0) return null
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+  })()`
+}