@erclx/canon 5.66.0 → 5.68.0

package/src/take/reel.ts

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process'
+import { readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { CameraTrack } from '@/take/camera'
+import { finished } from '@/take/encode'
+import type { FilmedBeat } from '@/take/film'
+import { FPS } from '@/take/log'
+import { type Frame, drawPointer } from '@/take/pointer'
+
+/**
+ * Joins a take's beats into one short reel for a pull request: each beat's
+ * clip shrunk to one width, every third frame kept, the pointer drawn from its
+ * camera track, encoded as an animated WebP that GitHub plays inline. It
+ * draws the pointer and nothing else, since the zoom, captions, and cuts are
+ * the edit's work for a launch video.
+ */
+
+export const REEL_WIDTH = 960
+
+/** How many take frames each reel frame stands for, 60 fps down to 20. */
+export const REEL_EVERY = 3
+
+export const REEL_FPS = FPS / REEL_EVERY
+
+/** WebP quality, measured at about 1.4 MB for a 9 s reel at this width. */
+const QUALITY = 60
+
+export interface ReelFrame extends Frame {
+  /** Which beat of the take, in plan order. */
+  readonly beat: number
+  /** The frame's place in its beat, which draws camera frame `index * REEL_EVERY`. */
+  readonly index: number
+}
+
+export interface Reel {
+  readonly file: string
+  readonly frames: number
+  readonly seconds: number
+  readonly bytes: number
+}
+
+/**
+ * Yields every reel frame in order with the pointer drawn on it. The decoder
+ * keeps frames by index rather than by timestamp, since an `fps` filter that
+ * rounds timestamps drifts the pointer off what it pressed.
+ */
+export async function* reelFrames(
+  out: string,
+  beats: readonly FilmedBeat[],
+): AsyncGenerator<ReelFrame> {
+  for (const [beat, filmed] of beats.entries()) {
+    const camera = JSON.parse(
+      readFileSync(join(out, filmed.camera), 'utf8'),
+    ) as CameraTrack
+    const { width, height } = reelSize(camera)
+    // The camera is in CSS pixels of the page, and every route's clip shrinks
+    // to the same width, so one factor places the pointer on either.
+    const factor = width / camera.viewport.width
+
+    let index = 0
+    for await (const data of decode(join(out, filmed.clip), width, height)) {
+      const at =
+        camera.frames[Math.min(index * REEL_EVERY, camera.frames.length - 1)]
+      const frame = { data, width, height, beat, index }
+      if (at) {
+        drawPointer(
+          frame,
+          { x: at.cursor.x * factor, y: at.cursor.y * factor },
+          at.ring,
+        )
+      }
+      yield frame
+      index += 1
+    }
+  }
+}
+
+/** Renders the reel of a filmed take to `file`, an animated WebP. */
+export async function renderReel(
+  out: string,
+  beats: readonly FilmedBeat[],
+  file: string,
+): Promise<Reel> {
+  const first = beats[0]
+  if (!first) throw new Error('a reel needs at least one filmed beat')
+  const { width, height } = reelSize(
+    JSON.parse(readFileSync(join(out, first.camera), 'utf8')) as CameraTrack,
+  )
+
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-y',
+      '-loglevel',
+      'error',
+      '-f',
+      'rawvideo',
+      '-pix_fmt',
+      'rgba',
+      '-s',
+      `${width}x${height}`,
+      '-framerate',
+      String(REEL_FPS),
+      '-i',
+      '-',
+      '-c:v',
+      'libwebp_anim',
+      '-quality',
+      String(QUALITY),
+      '-loop',
+      '0',
+      '-f',
+      'webp',
+      file,
+    ],
+    { stdio: ['pipe', 'ignore', 'pipe'] },
+  )
+  const done = finished(proc)
+  // Held so an encoder that dies mid-stream surfaces through `done` rather than
+  // as an unhandled rejection or a broken pipe thrown out of the stream.
+  done.catch(() => {})
+  proc.stdin?.on('error', () => {})
+
+  let frames = 0
+  try {
+    for await (const frame of reelFrames(out, beats)) {
+      // Raced against the exit, since a write waiting on a drain from an
+      // encoder that already died would wait forever.
+      await Promise.race([write(proc.stdin, frame.data), done])
+      frames += 1
+    }
+  } catch (error) {
+    proc.kill('SIGKILL')
+    throw error
+  }
+  proc.stdin?.end()
+  await done
+
+  return {
+    file,
+    frames,
+    seconds: Number((frames / REEL_FPS).toFixed(2)),
+    bytes: statSync(file).size,
+  }
+}
+
+function reelSize(camera: CameraTrack): { width: number; height: number } {
+  const height =
+    Math.round(
+      (REEL_WIDTH * camera.viewport.height) / camera.viewport.width / 2,
+    ) * 2
+  return { width: REEL_WIDTH, height }
+}
+
+/** Decodes every `REEL_EVERY`th frame of a clip as RGBA at the reel's size. */
+async function* decode(
+  clip: string,
+  width: number,
+  height: number,
+): AsyncGenerator<Uint8Array> {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-loglevel',
+      'error',
+      '-i',
+      clip,
+      '-vf',
+      `select='not(mod(n\\,${REEL_EVERY}))',scale=${width}:${height}:flags=area`,
+      '-fps_mode',
+      'passthrough',
+      '-f',
+      'rawvideo',
+      '-pix_fmt',
+      'rgba',
+      '-',
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  const done = finished(proc)
+  done.catch(() => {})
+
+  const size = width * height * 4
+  let pending: Buffer = Buffer.alloc(0)
+  let drained = false
+  try {
+    for await (const chunk of proc.stdout as AsyncIterable<Buffer>) {
+      pending = pending.length ? Buffer.concat([pending, chunk]) : chunk
+      while (pending.length >= size) {
+        // Copied out, since the frame is drawn on and outlives the chunk.
+        yield new Uint8Array(pending.subarray(0, size))
+        pending = pending.subarray(size)
+      }
+    }
+    drained = true
+  } finally {
+    // A reader that stopped early leaves FFmpeg decoding into a full pipe.
+    if (!drained) proc.kill('SIGKILL')
+  }
+  await done
+}
+
+function write(
+  stdin: NodeJS.WritableStream | null,
+  data: Uint8Array,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!stdin) {
+      reject(new Error('ffmpeg stopped reading frames'))
+      return
+    }
+    if (stdin.write(data)) resolve()
+    else stdin.once('drain', () => resolve())
+  })
+}

package/src/take/screencast.ts

@@ -0,0 +1,97 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { chromium } from 'playwright-core'
+import { lastFrame, 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[]
+  /** The clip's closing frame as a JPEG. */
+  readonly still: Buffer
+}
+
+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)
+    const frames = await probeFrames(request.clip)
+    return { frames, events, still: await lastFrame(request.clip, frames) }
+  } 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,
+  }
+}