@erclx/canon 5.67.0 → 5.68.0

package/src/records/backup.ts

@@ -104,6 +104,17 @@ export const EXCLUDED_ENTRIES = [
   RECORDS_GIT_NAME,
 ] as const
 
+/** Media under a video workspace, remade from its plan and composition, so never backed up. */
+export const MEDIA_PATHSPECS = [
+  ':(exclude,glob)video/*/takes/**',
+  ':(exclude,glob)video/**/renders/**',
+  ':(exclude,glob)video/**/snapshots/**',
+  ':(exclude,glob)video/**/node_modules/**',
+  ':(exclude,glob,icase)video/**/*.mp4',
+  ':(exclude,glob,icase)video/**/*.webm',
+  ':(exclude,glob,icase)video/**/*.mov',
+] as const
+
 /**
  * Whether a top-level name stays out of every push, at either root.
  *
@@ -598,8 +609,8 @@ async function pendingFiles(
   if (scope.length === 0) return { added: [], pending: [] }
 
   const [others, modified] = await Promise.all([
-    records(root, ['ls-files', '-z', '-o', '--', ...scope]),
-    records(root, ['ls-files', '-z', '-m', '--', ...scope]),
+    records(root, ['ls-files', '-z', '-o', '--', ...scope, ...MEDIA_PATHSPECS]),
+    records(root, ['ls-files', '-z', '-m', '--', ...scope, ...MEDIA_PATHSPECS]),
   ])
   if (!others.ok) return failed('ls-files', others)
   if (!modified.ok) return failed('ls-files', modified)
@@ -699,7 +710,14 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
     // enclosing repository, and the pathspecs are the whole list, so nothing
     // outside them can enter the index however the ignore rules read. An
     // excluded name never reaches the list, whatever the records index holds.
-    const staged = await records(root, ['add', '-A', '-f', '--', ...scope])
+    const staged = await records(root, [
+      'add',
+      '-A',
+      '-f',
+      '--',
+      ...scope,
+      ...MEDIA_PATHSPECS,
+    ])
     if (!staged.ok) return failed('add', staged)
   }
 
@@ -837,7 +855,13 @@ export async function pullRecords(root: string): Promise<PullOutcome> {
   const { scope } = await scopedFolders(root)
 
   if (scope.length > 0) {
-    const dirty = await records(root, ['status', '--porcelain', '--', ...scope])
+    const dirty = await records(root, [
+      'status',
+      '--porcelain',
+      '--',
+      ...scope,
+      ...MEDIA_PATHSPECS,
+    ])
     if (!dirty.ok) return failed('status', dirty)
 
     if (dirty.text.length > 0) {

package/src/take/encode.ts

@@ -154,7 +154,44 @@ export async function probeFrames(clip: string): Promise<number> {
   return frames
 }
 
-function finished(proc: ChildProcess): Promise<void> {
+/**
+ * Reads the clip's closing frame as one JPEG. It selects the frame by index
+ * rather than seeking from the end, since a seek lands on whichever frame
+ * the container's timing puts nearest, which was measured missing the last.
+ */
+export async function lastFrame(clip: string, frames: number): Promise<Buffer> {
+  const proc = spawn(
+    'ffmpeg',
+    [
+      '-v',
+      'error',
+      '-i',
+      clip,
+      '-vf',
+      `select=eq(n\\,${frames - 1})`,
+      '-frames:v',
+      '1',
+      '-q:v',
+      '2',
+      '-f',
+      'image2pipe',
+      '-c:v',
+      'mjpeg',
+      '-',
+    ],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  )
+  const chunks: Buffer[] = []
+  proc.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk))
+  await finished(proc)
+  const jpeg = Buffer.concat(chunks)
+  if (jpeg.length === 0) {
+    throw new Error(`ffmpeg read no frame ${frames - 1} from ${clip}`)
+  }
+  return jpeg
+}
+
+export function finished(proc: ChildProcess): Promise<void> {
   let stderr = ''
   proc.stderr?.on('data', (chunk: Buffer) => {
     stderr += chunk.toString()

package/src/take/film.ts

@@ -44,6 +44,8 @@ export interface FilmedBeat {
   readonly clip: string
   readonly log: string
   readonly camera: string
+  /** The clip's closing frame, as a JPEG. */
+  readonly still: string
 }
 
 export type TakeResult =
@@ -131,7 +133,7 @@ async function filmBeat(
 
   let route: Route = beat.route
   let fallback: string | undefined
-  let filmed: { frames: number; events: readonly LogEvent[] }
+  let filmed: { frames: number; events: readonly LogEvent[]; still: Buffer }
   if (beat.route === 'step') {
     try {
       filmed = await filmStepped({ executable, url, beat, clip: target })
@@ -158,6 +160,8 @@ async function filmBeat(
   // 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`)
+  const stillPath = join(dir, 'still.jpg')
+  writeFileSync(join(out, stillPath), filmed.still)
 
   return {
     name: beat.name,
@@ -170,6 +174,7 @@ async function filmBeat(
     clip,
     log: logPath,
     camera: cameraPath,
+    still: stillPath,
   }
 }
 

package/src/take/pointer.ts

@@ -0,0 +1,168 @@
+import type { Point } from '@/take/log'
+
+/**
+ * Draws the cursor arrow and the click ring onto one decoded frame, in the
+ * shape groundwork track `193-ui-record` rendered them: a dark arrow outlined
+ * in white, and a blue ring that grows from its tip and fades out. Both stay
+ * one size whatever the frame shows, so the pointer reads the same in every
+ * beat of a reel. Drawn in TypeScript rather than a browser, so the reel needs
+ * no page and no seek, and a test can read the pixels it leaves.
+ */
+
+export interface Frame {
+  /** RGBA, four bytes a pixel, row by row. */
+  readonly data: Uint8Array
+  readonly width: number
+  readonly height: number
+}
+
+/** The arrow, relative to its tip, from the groundwork's 24 px cursor path. */
+const ARROW: readonly Point[] = [
+  { x: 0, y: 0 },
+  { x: 0, y: 17 },
+  { x: 4.5, y: 12.5 },
+  { x: 7.5, y: 19 },
+  { x: 10, y: 18 },
+  { x: 7, y: 11.5 },
+  { x: 13.5, y: 11.5 },
+]
+
+const ARROW_FILL = [17, 17, 17] as const
+const ARROW_STROKE = [255, 255, 255] as const
+const STROKE_HALF = 0.75
+
+/** The ring's outer radius at full size, and its stroke at that size. */
+export const RING_RADIUS = 18
+const RING_STROKE = 2
+const RING_COLOR = [37, 99, 235] as const
+/** The ring starts at this share of its size and grows by the expansion. */
+const RING_START = 0.4
+
+/**
+ * Draws the pointer with its tip at `at`, in the frame's own pixels, and the
+ * ring around it when `ring` is a 0 to 1 expansion. The ring sits under the
+ * arrow, and anything past the frame's edge is clipped.
+ */
+export function drawPointer(
+  frame: Frame,
+  at: Point,
+  ring: number | null,
+): void {
+  if (ring !== null) drawRing(frame, at, ring)
+  drawArrow(frame, at)
+}
+
+function drawRing(frame: Frame, at: Point, ring: number): void {
+  const scale = RING_START + ring
+  const stroke = RING_STROKE * scale
+  const middle = RING_RADIUS * scale - stroke / 2
+  const opacity = 1 - ring
+  if (opacity <= 0) return
+
+  const reach = RING_RADIUS * scale + 1
+  forEachPixel(frame, at, reach, reach, reach, reach, (px, py) => {
+    const distance = Math.hypot(px - at.x, py - at.y)
+    const coverage = clamp01(stroke / 2 + 0.5 - Math.abs(distance - middle))
+    return coverage > 0
+      ? { color: RING_COLOR, alpha: coverage * opacity }
+      : null
+  })
+}
+
+function drawArrow(frame: Frame, at: Point): void {
+  const reach = STROKE_HALF + 1
+  forEachPixel(frame, at, reach, 13.5 + reach, reach, 19 + reach, (px, py) => {
+    const d = signedDistance({ x: px - at.x, y: py - at.y })
+    // Coverage of the outlined shape, then of the fill inside the outline,
+    // each antialiased across one pixel.
+    const outer = clamp01(0.5 - (d - STROKE_HALF))
+    if (outer <= 0) return null
+    const inner = clamp01(0.5 - (d + STROKE_HALF))
+    return {
+      color: ARROW_STROKE,
+      alpha: outer,
+      over: ARROW_FILL,
+      overAlpha: inner,
+    }
+  })
+}
+
+interface Paint {
+  readonly color: readonly [number, number, number]
+  readonly alpha: number
+  /** A second color laid over the first, for the fill inside the outline. */
+  readonly over?: readonly [number, number, number]
+  readonly overAlpha?: number
+}
+
+/**
+ * Calls `paint` for each pixel center inside the box around `at`, clipped to
+ * the frame, and blends whatever it returns onto that pixel.
+ */
+function forEachPixel(
+  frame: Frame,
+  at: Point,
+  left: number,
+  right: number,
+  up: number,
+  down: number,
+  paint: (x: number, y: number) => Paint | null,
+): void {
+  const x0 = Math.max(0, Math.floor(at.x - left))
+  const x1 = Math.min(frame.width - 1, Math.ceil(at.x + right))
+  const y0 = Math.max(0, Math.floor(at.y - up))
+  const y1 = Math.min(frame.height - 1, Math.ceil(at.y + down))
+  for (let y = y0; y <= y1; y += 1) {
+    for (let x = x0; x <= x1; x += 1) {
+      const result = paint(x + 0.5, y + 0.5)
+      if (!result) continue
+      const i = (y * frame.width + x) * 4
+      blend(frame.data, i, result.color, result.alpha)
+      if (result.over && result.overAlpha) {
+        blend(frame.data, i, result.over, result.overAlpha)
+      }
+    }
+  }
+}
+
+function blend(
+  data: Uint8Array,
+  i: number,
+  color: readonly [number, number, number],
+  alpha: number,
+): void {
+  for (let c = 0; c < 3; c += 1) {
+    const base = data[i + c] ?? 0
+    data[i + c] = Math.round(base + ((color[c] ?? 0) - base) * alpha)
+  }
+}
+
+/** Distance from `p` to the arrow's outline, negative inside it. */
+function signedDistance(p: Point): number {
+  let nearest = Number.POSITIVE_INFINITY
+  let inside = false
+  for (let i = 0, j = ARROW.length - 1; i < ARROW.length; j = i, i += 1) {
+    const a = ARROW[j] ?? ARROW[0]
+    const b = ARROW[i] ?? ARROW[0]
+    if (!a || !b) continue
+    nearest = Math.min(nearest, segmentDistance(p, a, b))
+    if (
+      a.y > p.y !== b.y > p.y &&
+      p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x
+    ) {
+      inside = !inside
+    }
+  }
+  return inside ? -nearest : nearest
+}
+
+function segmentDistance(p: Point, a: Point, b: Point): number {
+  const dx = b.x - a.x
+  const dy = b.y - a.y
+  const k = clamp01(((p.x - a.x) * dx + (p.y - a.y) * dy) / (dx * dx + dy * dy))
+  return Math.hypot(p.x - (a.x + k * dx), p.y - (a.y + k * dy))
+}
+
+function clamp01(value: number): number {
+  return Math.min(Math.max(value, 0), 1)
+}

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

@@ -2,7 +2,7 @@ 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 { 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'
@@ -22,6 +22,8 @@ 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: {
@@ -71,7 +73,8 @@ export async function filmScreencast(request: {
     await page.screencast.stop()
 
     await transcode(webm, request.clip, FPS)
-    return { frames: await probeFrames(request.clip), events }
+    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 })

package/src/take/stepper.ts

@@ -46,6 +46,8 @@ export class StepperStalled extends Error {
 export interface SteppedTake {
   readonly frames: number
   readonly events: readonly LogEvent[]
+  /** The last frame encoded, as the JPEG the shell returned. */
+  readonly still: Buffer
 }
 
 export interface SteppedRequest {
@@ -140,7 +142,8 @@ export async function filmStepped(
     await recording.hold(HOLD_MS)
 
     await encoder.close()
-    return { frames, events }
+    if (!last) throw new Error('the take encoded no frame')
+    return { frames, events, still: last }
   } catch (error) {
     encoder.abort()
     throw error