@erclx/canon 5.66.0 → 5.67.0

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

package/src/take/shell.ts

@@ -0,0 +1,287 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/**
+ * Launches chrome-headless-shell under begin-frame control and speaks raw CDP
+ * to one page in it. Playwright cannot ask for begin-frame control on a page it
+ * opens, and only the headless shell honors the flag, so this bypasses the
+ * engine and finds the shell Playwright installed beside Chromium.
+ *
+ * `playwright-core` exposes no path for the shell, so the path is rebuilt from
+ * its `browsers.json` revision and its cache layout. A Playwright upgrade that
+ * moves that layout surfaces here as `browser-missing` rather than as a crash.
+ */
+
+export class ShellMissing extends Error {}
+
+/** Each platform's folder and binary inside the shell's revision folder. */
+const SHELL_DIRS: Record<string, readonly [string, string]> = {
+  'linux-x64': ['chrome-headless-shell-linux64', 'chrome-headless-shell'],
+  'linux-arm64': ['chrome-headless-shell-linux-arm64', 'chrome-headless-shell'],
+  'darwin-x64': ['chrome-headless-shell-mac-x64', 'chrome-headless-shell'],
+  'darwin-arm64': ['chrome-headless-shell-mac-arm64', 'chrome-headless-shell'],
+}
+
+const FLAGS = [
+  '--enable-begin-frame-control',
+  '--run-all-compositor-stages-before-draw',
+  '--disable-threaded-animation',
+  '--disable-threaded-scrolling',
+  '--disable-checker-imaging',
+  '--hide-scrollbars',
+  '--force-device-scale-factor=2',
+  '--mute-audio',
+  '--no-first-run',
+]
+
+/** Resolves the installed shell, throwing `ShellMissing` naming where it looked. */
+export function findShell(env: NodeJS.ProcessEnv = process.env): string {
+  const require = createRequire(import.meta.url)
+  const engineRoot = dirname(require.resolve('playwright-core/package.json'))
+  const manifest = JSON.parse(
+    readFileSync(join(engineRoot, 'browsers.json'), 'utf8'),
+  ) as { browsers: { name: string; revision: string }[] }
+  const revision = manifest.browsers.find(
+    (browser) => browser.name === 'chromium-headless-shell',
+  )?.revision
+  const dirs = SHELL_DIRS[`${process.platform}-${process.arch}`]
+  if (!revision || !dirs) {
+    throw new ShellMissing(
+      `no chrome-headless-shell for ${process.platform}-${process.arch} in playwright-core's browsers.json`,
+    )
+  }
+
+  const path = join(
+    registryRoot(env, engineRoot),
+    `chromium_headless_shell-${revision}`,
+    ...dirs,
+  )
+  if (!existsSync(path)) {
+    throw new ShellMissing(
+      `chrome-headless-shell executable doesn't exist at ${path}`,
+    )
+  }
+  return path
+}
+
+/** Where Playwright keeps its browsers, read the way its own registry reads it. */
+function registryRoot(env: NodeJS.ProcessEnv, engineRoot: string): string {
+  const pinned = env.PLAYWRIGHT_BROWSERS_PATH
+  if (pinned === '0') return join(engineRoot, '.local-browsers')
+  if (pinned) return pinned
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Caches', 'ms-playwright')
+  }
+  return join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'ms-playwright')
+}
+
+type Listener = (params: Record<string, unknown>) => void
+
+export interface ShellPage {
+  send<T = Record<string, unknown>>(
+    method: string,
+    params?: Record<string, unknown>,
+  ): Promise<T>
+  /** Calls `listener` on every event of `method` from this page. */
+  on(method: string, listener: Listener): void
+  /** Runs an expression in the page and returns its value. */
+  evaluate<T>(expression: string): Promise<T>
+  /** Kills the shell and removes its profile, safe to call more than once. */
+  close(): void
+}
+
+/**
+ * Opens one page at `width` by `height` with begin-frame control. The launch
+ * owns its profile folder and kills the shell on process exit, so a killed take
+ * leaves no shell running and no profile behind.
+ */
+export async function openShell(
+  executable: string,
+  size: { readonly width: number; readonly height: number },
+): Promise<ShellPage> {
+  const profile = mkdtempSync(join(tmpdir(), 'canon-take-'))
+  const proc = spawn(
+    executable,
+    [
+      '--remote-debugging-port=0',
+      `--user-data-dir=${profile}`,
+      ...FLAGS,
+      'about:blank',
+    ],
+    { stdio: ['ignore', 'ignore', 'pipe'] },
+  )
+
+  let closed = false
+  const close = (): void => {
+    if (closed) return
+    closed = true
+    process.off('exit', close)
+    process.off('SIGINT', interrupt)
+    process.off('SIGTERM', interrupt)
+    socket?.close()
+    proc.kill('SIGKILL')
+    rmSync(profile, { recursive: true, force: true })
+  }
+  // A signal skips the exit event, so it closes the shell and then re-raises
+  // itself with the default handler restored, ending the process as it would have.
+  const interrupt = (signal: NodeJS.Signals): void => {
+    close()
+    process.kill(process.pid, signal)
+  }
+  process.on('exit', close)
+  process.once('SIGINT', interrupt)
+  process.once('SIGTERM', interrupt)
+
+  let socket: WebSocket | undefined
+  try {
+    socket = new WebSocket(await devtoolsUrl(proc))
+    await new Promise((done, fail) => {
+      socket?.addEventListener('open', done, { once: true })
+      socket?.addEventListener('error', fail, { once: true })
+    })
+    return await attach(socket, size, close)
+  } catch (error) {
+    close()
+    throw error
+  }
+}
+
+function devtoolsUrl(proc: ChildProcess): Promise<string> {
+  return new Promise((done, fail) => {
+    let output = ''
+    proc.stderr?.on('data', (chunk: Buffer) => {
+      output += chunk.toString()
+      const match = output.match(/DevTools listening on (ws:\S+)/)
+      if (match?.[1]) done(match[1])
+    })
+    proc.on('error', fail)
+    proc.on('exit', (code) =>
+      fail(new Error(`the shell exited ${code}: ${output.slice(-400)}`)),
+    )
+  })
+}
+
+async function attach(
+  socket: WebSocket,
+  size: { readonly width: number; readonly height: number },
+  close: () => void,
+): Promise<ShellPage> {
+  let nextId = 0
+  const pending = new Map<
+    number,
+    { resolve: (value: never) => void; reject: (error: Error) => void }
+  >()
+  const listeners: { method: string; sessionId: string; listener: Listener }[] =
+    []
+
+  socket.addEventListener('message', (event) => {
+    const message = JSON.parse(String(event.data)) as {
+      id?: number
+      method?: string
+      sessionId?: string
+      params?: Record<string, unknown>
+      result?: never
+      error?: { message: string; data?: string }
+    }
+    if (message.id !== undefined) {
+      const waiter = pending.get(message.id)
+      if (!waiter) return
+      pending.delete(message.id)
+      if (message.error) {
+        waiter.reject(
+          new Error(
+            `${message.error.message} ${message.error.data ?? ''}`.trim(),
+          ),
+        )
+      } else {
+        waiter.resolve(message.result as never)
+      }
+      return
+    }
+    for (const entry of listeners) {
+      if (
+        entry.method === message.method &&
+        entry.sessionId === message.sessionId
+      ) {
+        entry.listener(message.params ?? {})
+      }
+    }
+  })
+  socket.addEventListener('close', () => {
+    for (const waiter of pending.values()) {
+      waiter.reject(new Error('the shell closed its connection'))
+    }
+    pending.clear()
+  })
+
+  const raw = <T>(
+    method: string,
+    params: Record<string, unknown> = {},
+    sessionId?: string,
+  ): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+      nextId += 1
+      pending.set(nextId, {
+        resolve: resolve as (value: never) => void,
+        reject,
+      })
+      socket.send(
+        JSON.stringify({
+          id: nextId,
+          method,
+          params,
+          ...(sessionId ? { sessionId } : {}),
+        }),
+      )
+    })
+
+  const { browserContextId } = await raw<{ browserContextId: string }>(
+    'Target.createBrowserContext',
+  )
+  const { targetId } = await raw<{ targetId: string }>('Target.createTarget', {
+    url: 'about:blank',
+    browserContextId,
+    enableBeginFrameControl: true,
+    width: size.width,
+    height: size.height,
+  })
+  const { sessionId } = await raw<{ sessionId: string }>(
+    'Target.attachToTarget',
+    { targetId, flatten: true },
+  )
+
+  const send = <T>(method: string, params?: Record<string, unknown>) =>
+    raw<T>(method, params, sessionId)
+
+  await send('Page.enable')
+  await send('Runtime.enable')
+
+  return {
+    send,
+    on: (method, listener) => listeners.push({ method, sessionId, listener }),
+    evaluate: async <T>(expression: string): Promise<T> => {
+      const reply = await send<{
+        result: { value: T }
+        exceptionDetails?: {
+          text: string
+          exception?: { description?: string }
+        }
+      }>('Runtime.evaluate', {
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+      })
+      if (reply.exceptionDetails) {
+        throw new Error(
+          reply.exceptionDetails.exception?.description ??
+            reply.exceptionDetails.text,
+        )
+      }
+      return reply.result.value
+    },
+    close,
+  }
+}