@erclx/canon 5.65.0 → 5.67.0

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 }
+  })()`
+}

package/src/take/plan.ts

@@ -0,0 +1,193 @@
+/**
+ * The take plan: the beats a take films, each a list of steps. It reuses
+ * `canon drive`'s kind names for the steps the two share and adds `move`,
+ * since a take films the pointer's travel and a drive skips it. `tab` is left
+ * out because a take draws its cursor from the log, and focus moved by the
+ * keyboard leaves nothing in the log to draw.
+ */
+
+/** How a beat is filmed: frame stepping, or Playwright's real-time screencast. */
+export const ROUTES = ['step', 'screencast'] as const
+
+export type Route = (typeof ROUTES)[number]
+
+export type TakeStep =
+  | { readonly kind: 'move'; readonly target: string }
+  | { readonly kind: 'move'; readonly x: number; readonly y: number }
+  | { readonly kind: 'click'; readonly target: string }
+  | { readonly kind: 'fill'; readonly target: string; readonly text: string }
+  | { readonly kind: 'scroll'; readonly target: string; readonly dy: number }
+  | { readonly kind: 'wait'; readonly ms: number }
+
+export interface Beat {
+  readonly name: string
+  /**
+   * The route asked for. A `step` beat that frame stepping cannot drive falls
+   * back to `screencast` on its own, and the take's record says which ran.
+   */
+  readonly route: Route
+  /** Runs after the page loads and before the first frame is kept. */
+  readonly setup: readonly TakeStep[]
+  readonly steps: readonly TakeStep[]
+}
+
+export interface TakePlan {
+  readonly beats: readonly Beat[]
+}
+
+export type TakePlanRefusal =
+  | 'unreadable-plan'
+  | 'no-beats'
+  | 'bad-beat'
+  | 'no-steps'
+  | 'unknown-route'
+  | 'bad-step'
+
+export type TakePlanRead =
+  | { readonly kind: 'read'; readonly plan: TakePlan }
+  | {
+      readonly kind: 'refused'
+      readonly reason: TakePlanRefusal
+      readonly detail: string
+    }
+
+class Refusal extends Error {
+  constructor(
+    readonly reason: TakePlanRefusal,
+    detail: string,
+  ) {
+    super(detail)
+  }
+}
+
+/**
+ * Reads a take plan out of a JSON document, the same form `canon drive` reads
+ * its run in, refusing the first thing a take could not perform.
+ */
+export function readTakePlan(source: string): TakePlanRead {
+  let document: unknown
+  try {
+    document = JSON.parse(source)
+  } catch (error) {
+    return {
+      kind: 'refused',
+      reason: 'unreadable-plan',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  try {
+    return { kind: 'read', plan: readPlan(document) }
+  } catch (error) {
+    if (!(error instanceof Refusal)) throw error
+    return { kind: 'refused', reason: error.reason, detail: error.message }
+  }
+}
+
+function readPlan(document: unknown): TakePlan {
+  if (!isRecord(document)) {
+    throw new Refusal('unreadable-plan', 'the document is not an object')
+  }
+  const { beats } = document
+  if (!Array.isArray(beats) || beats.length === 0) {
+    throw new Refusal(
+      'no-beats',
+      'beats carries no entry, so nothing is filmed',
+    )
+  }
+  return { beats: beats.map((entry, index) => readBeat(entry, index)) }
+}
+
+function readBeat(entry: unknown, index: number): Beat {
+  const at = `beat ${index + 1}`
+  if (!isRecord(entry)) throw new Refusal('bad-beat', `${at} is not an object`)
+
+  const name = typeof entry.name === 'string' ? entry.name : ''
+  if (!name) {
+    throw new Refusal(
+      'bad-beat',
+      `${at} carries no name, and its clip is named by it`,
+    )
+  }
+
+  const route = entry.route ?? 'step'
+  if (!ROUTES.includes(route as Route)) {
+    throw new Refusal(
+      'unknown-route',
+      `${name} names route ${String(route)}. This build records on: ${ROUTES.join(', ')}.`,
+    )
+  }
+
+  if (!Array.isArray(entry.steps) || entry.steps.length === 0) {
+    throw new Refusal(
+      'no-steps',
+      `${name} names no step, so its take would film nothing`,
+    )
+  }
+  if (entry.setup !== undefined && !Array.isArray(entry.setup)) {
+    throw new Refusal('bad-beat', `${name} carries a setup that is not a list`)
+  }
+
+  return {
+    name,
+    route: route as Route,
+    setup: (entry.setup ?? []).map((step: unknown, i: number) =>
+      readStep(step, `${name}, setup step ${i + 1}`),
+    ),
+    steps: entry.steps.map((step: unknown, i: number) =>
+      readStep(step, `${name}, step ${i + 1}`),
+    ),
+  }
+}
+
+function readStep(entry: unknown, at: string): TakeStep {
+  if (!isRecord(entry)) throw new Refusal('bad-step', `${at} is not an object`)
+
+  const target = typeof entry.target === 'string' ? entry.target : undefined
+  const needTarget = (): string => {
+    if (target) return target
+    throw new Refusal('bad-step', `${at} is a ${entry.kind} with no target`)
+  }
+
+  switch (entry.kind) {
+    case 'move':
+      if (target) return { kind: 'move', target }
+      if (isNumber(entry.x) && isNumber(entry.y)) {
+        return { kind: 'move', x: entry.x, y: entry.y }
+      }
+      throw new Refusal(
+        'bad-step',
+        `${at} is a move with neither a target nor an x and y`,
+      )
+    case 'click':
+      return { kind: 'click', target: needTarget() }
+    case 'fill':
+      if (typeof entry.text !== 'string') {
+        throw new Refusal('bad-step', `${at} is a fill with no text`)
+      }
+      return { kind: 'fill', target: needTarget(), text: entry.text }
+    case 'scroll':
+      if (!isNumber(entry.dy)) {
+        throw new Refusal('bad-step', `${at} is a scroll with no dy in pixels`)
+      }
+      return { kind: 'scroll', target: needTarget(), dy: entry.dy }
+    case 'wait':
+      if (!isNumber(entry.ms) || entry.ms < 0) {
+        throw new Refusal('bad-step', `${at} is a wait with no ms`)
+      }
+      return { kind: 'wait', ms: entry.ms }
+    default:
+      throw new Refusal(
+        'bad-step',
+        `${at} names kind ${String(entry.kind)}, which is not move, click, fill, scroll, or wait`,
+      )
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}

package/src/take/screencast.ts

@@ -0,0 +1,94 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { chromium } from 'playwright-core'
+import { probeFrames, transcode } 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 { HOLD_MS } from '@/take/stepper'
+
+/**
+ * Films a beat in real time through Playwright's screencast, for a page frame
+ * stepping cannot drive. It runs at the viewport's own 1920x1080, so it goes
+ * soft under a zoom where a stepped take stays sharp, and its frames land when
+ * the page paints rather than one per step.
+ */
+
+const FRAME_MS = 1000 / FPS
+
+const SETTLE_MS = 2500
+
+export interface ScreencastTake {
+  readonly frames: number
+  readonly events: readonly LogEvent[]
+}
+
+export async function filmScreencast(request: {
+  readonly url: string
+  readonly beat: Beat
+  readonly clip: string
+}): Promise<ScreencastTake> {
+  const scratch = mkdtempSync(join(tmpdir(), 'canon-take-cast-'))
+  const browser = await chromium.launch()
+  try {
+    const page = await browser.newPage({ viewport: VIEWPORT })
+    await page.goto(request.url, { waitUntil: 'load' })
+    await page.waitForTimeout(SETTLE_MS)
+
+    const stageOn = (clock: () => number): Stage => ({
+      now: clock,
+      hold: (ms) => page.waitForTimeout(ms),
+      pointer: async (input) => {
+        const sent = clock()
+        await send(page.mouse, input)
+        const spent = clock() - sent
+        if (spent < FRAME_MS) await page.waitForTimeout(FRAME_MS - spent)
+      },
+      key: async (text) => {
+        await page.keyboard.insertText(text)
+        await page.waitForTimeout(FRAME_MS)
+      },
+      evaluate: (expression) => page.evaluate(expression),
+    })
+
+    const live = stageOn(() => performance.now())
+    await performSteps(live, request.beat.setup, { pointer: START })
+    if (request.beat.setup.length > 0) await live.hold(1000)
+    await page.mouse.move(START.x, START.y)
+
+    const webm = join(scratch, 'take.webm')
+    const events: LogEvent[] = []
+    await page.screencast.start({ path: webm, size: VIEWPORT, fps: FPS })
+    const started = performance.now()
+    const recording = stageOn(() => performance.now() - started)
+    await recording.hold(HOLD_MS)
+    await performSteps(recording, request.beat.steps, {
+      pointer: START,
+      log: events,
+    })
+    await recording.hold(HOLD_MS)
+    await page.screencast.stop()
+
+    await transcode(webm, request.clip, FPS)
+    return { frames: await probeFrames(request.clip), events }
+  } finally {
+    await browser.close()
+    rmSync(scratch, { recursive: true, force: true })
+  }
+}
+
+type Mouse = import('playwright-core').Mouse
+
+async function send(mouse: Mouse, input: PointerInput): Promise<void> {
+  switch (input.type) {
+    case 'move':
+      return mouse.move(input.x, input.y)
+    case 'down':
+      return mouse.down()
+    case 'up':
+      return mouse.up()
+    case 'wheel':
+      return mouse.wheel(0, input.dy)
+  }
+}