@milkstraw/traceframe 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Traceframe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# Traceframe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Traceframe records a scripted Chromium flow and renders an MP4 with a smooth cursor and click pulse. Everything runs locally: pages, flows, videos, and authentication state stay on your machine.
+
+https://github.com/user-attachments/assets/38e02cd5-a9ba-4f3c-938c-159955353141
+
+## Install
+
+```sh
+npm install @milkstraw/traceframe
+```
+
+Traceframe requires Node.js 22+, FFmpeg 5+ with `libx264` and `ffprobe` (for example, `brew install ffmpeg` or `sudo apt install ffmpeg`), and Playwright's Chromium:
+
+```sh
+npx playwright@1.64.1 install --only-shell chromium
+```
+
+To use a system Chrome instead, pass `--browser` or set `CHROME_PATH`. Playwright still needs its own FFmpeg build to record the page, so install it with `npx playwright@1.64.1 install ffmpeg`.
+
+To record pages behind a login, pass a Playwright storage-state file with `--storage-state`. Keep it in `.auth/` or another ignored location.
+
+## Record a video
+
+The included fixture is available in a repository clone. It is not included in the installed package.
+
+```sh
+git clone https://github.com/milkstrawai/traceframe.git
+cd traceframe
+npm ci
+npx traceframe record \
+  --url "file://$PWD/examples/fixture.html" \
+  --flow ./examples/fixture-flow.mjs \
+  --out ./sample.mp4 \
+  --preset draft
+```
+
+For an installed package, pass your application URL and your own flow file:
+
+```sh
+npx traceframe record \
+  --url http://localhost:3000 \
+  --flow ./flow.mjs \
+  --out ./recording.mp4
+```
+
+The `draft` preset uses a 1280×800 CSS viewport and produces 1280×800 at 30 FPS. The `standard` preset uses the same CSS viewport and encodes it at 2560×1600 at 60 FPS. The cursor and click pulses are always drawn at the full frame rate, but Chromium may capture page changes, such as scrolling and animations, at a lower rate at 2560×1600, depending on the machine. When that happens, the video repeats the last page frame until the next one arrives. The video is always the viewport size times `--scale`, so `--preset draft --scale 2` gives 2560×1600 at 30 FPS. The command prints a JSON summary when it finishes.
+
+Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and the FFmpeg filter file.
+
+## Have an agent create the flow
+
+For a real application, ask your coding agent to inspect the running UI and create the flow from the user journey. This keeps selectors tied to the product and avoids manually guessing coordinates. For example:
+
+```text
+Create a Traceframe flow for this user journey: open Settings, change the theme, and save it.
+Inspect the running application, use stable role or test-id locators, add a ready hook,
+and use Traceframe's click, hover, move, and wait helpers for visible interactions.
+Write the result to flow.mjs and explain how to run it.
+```
+
+The flow module exports a default function. Timing values are seconds:
+
+```js
+export async function ready({ page }) {
+  await page.getByRole('heading', { name: 'Example workspace' }).waitFor()
+}
+
+export default async function ({ page, click, wait }) {
+  await click(page.getByRole('button', { name: 'Open settings' }), { duration: 0.8 })
+  await wait(1)
+}
+```
+
+`ready({ page, signal })` runs before recording starts. `--ready-timeout` (30 seconds by default) is Playwright's timeout for the page load and for each Playwright call in `ready`; it does not limit other work in the hook. A flow can also export `initialPointer = { x, y }` to choose where the cursor starts. By default it starts near the lower left.
+
+The default function receives `page`, `signal`, and four helpers: `move({ x, y }, { duration })`, `hover(locator, { duration })`, `click(locator, { duration, dwell })`, and `wait(seconds)`. A move takes 0.5 seconds unless you pass `duration`, and a click rests on the target for 0.25 seconds (`dwell`) before it presses. If the target is disabled, the click waits for it to become enabled. A flow may contain at most 100 moves, 100 clicks, and 120 seconds of work, and each `duration`, `dwell`, and `wait` is at most 30 seconds. Error messages name the locator; give it a clearer name with Playwright's `locator.describe('Save settings')`.
+
+`click` and `hover` use real Playwright mouse events and add their movement to the overlay timeline. If the pointer is already inside the target, it stays where it is, so a hover effect that moves or resizes the target does not pull the cursor along. A click holds the mouse button for about 100 ms, as a person would, so press styles such as `:active` show in the video. Headless Chromium draws pages without a GPU, so on heavy pages, such as ones with blurred backgrounds, hover effects can appear a little after the cursor passes. A longer `duration`, or a `move` around hover-reactive elements, keeps this from showing. Typing, scrolling, dragging, multiple tabs, and direct `page.mouse` or `locator.click()` calls are not currently represented in that timeline. A flow receives an `AbortSignal`; helper calls stop promptly when the duration limit is reached.
+
+## Programmatic usage
+
+```js
+import { record } from '@milkstraw/traceframe'
+
+await record({
+  url: 'http://localhost:3000',
+  flow: './flow.mjs',
+  output: './recording.mp4',
+  preset: 'standard',
+})
+```
+
+Traceframe's own errors are `TraceframeError` instances (exported by the package) with a `code`, such as `READY_FAILED` or `FLOW_TARGET_OBSCURED`.
+
+Pass `signal` to stop a recording early. Traceframe closes the browser, stops FFmpeg, and removes its temporary files before rejecting with the signal's reason. When you pass a signal, Traceframe leaves Ctrl-C and other termination signals to you. The CLI does this for you: the first Ctrl-C stops and cleans up, and a second one exits at once.
+
+## Sample output
+
+The committed sample is generated from the included fixture flow with the `standard` preset (2560×1600 at 60 FPS) and is about 12 seconds long:
+
+[Download the sample video](https://github.com/milkstrawai/traceframe/blob/main/examples/sample-output.mp4)
+
+The cursor and click-pulse artwork and the example page's icons were made for Traceframe and are distributed under this repository's MIT license.
+
+The example page uses the [Inter](https://github.com/rsms/inter) font, included under the SIL Open Font License in `examples/fonts/OFL.txt`.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm run test:smoke
+TRACEFRAME_PRESET=standard npm run test:smoke
+npm run test:package
+```
+
+After editing an SVG in `src/assets`, run `npm run build:assets` to rebuild its 1× and 2× PNGs.
+
+To re-record the committed sample:
+
+```sh
+npx traceframe record --url "file://$PWD/examples/fixture.html" --flow ./examples/fixture-flow.mjs --out ./examples/sample-output.mp4
+```

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@milkstraw/traceframe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Record scripted browser flows and render smooth cursor overlays into video.",
+  "keywords": [
+    "playwright",
+    "screen-recording",
+    "video",
+    "demo",
+    "cursor",
+    "browser-automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/milkstrawai/traceframe.git"
+  },
+  "homepage": "https://github.com/milkstrawai/traceframe#readme",
+  "bugs": "https://github.com/milkstrawai/traceframe/issues",
+  "type": "module",
+  "bin": {
+    "traceframe": "src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:smoke": "node scripts/smoke.mjs",
+    "test:package": "node scripts/package-smoke.mjs",
+    "build:assets": "node scripts/build-assets.mjs"
+  },
+  "dependencies": {
+    "playwright": "1.64.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/assets/click-pulse.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 30 30">
+  <circle cx="15" cy="15" r="8" fill="none" stroke="#fff" stroke-width="5" opacity=".82"/>
+  <circle cx="15" cy="15" r="8" fill="none" stroke="#14191e" stroke-width="3" opacity=".78"/>
+</svg>

package/src/assets/cursor.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <path d="M6.6 1.6Q6.6 1.05 7.05 1.42L21.2 12.55Q22.15 13.3 21.7 14.05Q21.45 14.4 20.95 14.4H15.35L18.25 19.95Q18.65 20.72 17.9 21.1L16.05 22.05Q15.3 22.45 14.9 21.7L11.85 16L8.35 19.45Q7.85 19.95 7.35 19.65Q6.9 19.4 6.9 18.8Z" fill="#000000" stroke="#FFFFFF" stroke-width="1.5" stroke-linejoin="round" stroke-linecap="round" vector-effect="non-scaling-stroke" transform="translate(6.6 1.6) scale(0.78 0.84) translate(-6.6 -1.6)"/>
+</svg>

package/src/capture.mjs

@@ -0,0 +1,111 @@
+import { addAbortListener } from 'node:events'
+import { join } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { chromium } from 'playwright'
+
+import { TraceframeError } from './errors.mjs'
+import { createFlowApi, LIMITS } from './flow.mjs'
+
+const PLAYWRIGHT_DEFAULT_TIMEOUT = 30_000
+const FIRST_FRAME_TIMEOUT = 10_000
+
+export async function captureFlow({ config, flow, directory, signal: callerSignal }) {
+  const signal = callerSignal ?? new AbortController().signal
+  const rawPath = join(directory, 'capture.webm')
+  const trace = { initialPointer: flow.initialPointer, moves: [], clicks: [] }
+
+  signal.throwIfAborted()
+  const browser = await launchBrowser(config, { handleSignals: !callerSignal })
+  let page
+  try {
+    page = await browser.newPage({ viewport: config.viewport, deviceScaleFactor: config.scale, storageState: config.storageState })
+    await raceAbort(waitForReady(page, flow, config, signal), signal)
+    await page.mouse.move(trace.initialPointer.x, trace.initialPointer.y)
+
+    const firstFrame = Promise.withResolvers()
+    await startScreencast(page, rawPath, config, ({ timestamp }) => firstFrame.resolve(timestamp))
+    const clock = await withDeadline(
+      () => firstFrame.promise,
+      FIRST_FRAME_TIMEOUT,
+      new TraceframeError(`No screencast frame arrived within ${FIRST_FRAME_TIMEOUT / 1000} seconds.`, { code: 'FIRST_FRAME_TIMEOUT' }),
+      signal,
+    )
+    await withDeadline(
+      (flowSignal) => flow.run({ page, signal: flowSignal, ...createFlowApi({ page, trace, clock, viewport: config.viewport, signal: flowSignal }) }),
+      LIMITS.maxDuration * 1000,
+      new TraceframeError(`Flow exceeded the ${LIMITS.maxDuration}-second duration limit.`, { code: 'FLOW_TOO_LONG' }),
+      signal,
+    )
+    trace.end = (Date.now() - clock) / 1000
+    await delay(config.postRoll * 1000, undefined, { signal })
+    await page.screencast.stop()
+    return { rawPath, trace }
+  } catch (error) {
+    // Closing the browser alone discards the screencast. Stop it so a run directory keeps what was recorded.
+    await page?.screencast.stop().catch(() => {})
+    throw error
+  } finally {
+    await browser.close()
+  }
+}
+
+async function launchBrowser(config, { handleSignals }) {
+  try {
+    return await chromium.launch({
+      executablePath: config.browser,
+      args: config.scale === 2 ? ['--force-device-scale-factor=2'] : [],
+      handleSIGINT: handleSignals,
+      handleSIGTERM: handleSignals,
+      handleSIGHUP: handleSignals,
+    })
+  } catch (error) {
+    if (!/Executable doesn't exist/i.test(error.message)) throw error
+    const message = config.browser
+      ? `Configured browser executable is unavailable: ${config.browser}`
+      : 'Playwright Chromium is not installed. Run `npx playwright@1.64.1 install --only-shell chromium` or pass --browser to a Chrome executable.'
+    throw new TraceframeError(message, { code: 'PLAYWRIGHT_RUNTIME_MISSING', cause: error })
+  }
+}
+
+async function waitForReady(page, flow, config, signal) {
+  try {
+    page.setDefaultTimeout(config.readyTimeout * 1000)
+    await page.goto(config.url)
+    await page.evaluate(() => document.fonts.ready)
+    await flow.ready?.({ page, signal })
+    page.setDefaultTimeout(PLAYWRIGHT_DEFAULT_TIMEOUT)
+  } catch (error) {
+    throw new TraceframeError(`Ready check failed: ${error instanceof Error ? error.message : error}`, { code: 'READY_FAILED', cause: error })
+  }
+}
+
+async function startScreencast(page, path, config, onFrame) {
+  try {
+    await page.screencast.start({ path, size: { width: config.video.width, height: config.video.height }, fps: config.video.fps, quality: 95, onFrame })
+  } catch (error) {
+    if (!/Executable doesn't exist/i.test(error.message)) throw error
+    throw new TraceframeError("Playwright's FFmpeg is not installed. It is needed to record, even with --browser. Run `npx playwright@1.64.1 install ffmpeg`.", { code: 'PLAYWRIGHT_RUNTIME_MISSING', cause: error })
+  }
+}
+
+// Settles with the task, or rejects at the deadline or on abort, even if the task ignores its signal.
+async function withDeadline(task, milliseconds, error, signal) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(error), milliseconds)
+  const deadline = AbortSignal.any([signal, controller.signal])
+  try {
+    return await raceAbort(task(deadline), deadline)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+async function raceAbort(promise, signal) {
+  const aborted = Promise.withResolvers()
+  const listener = addAbortListener(signal, () => aborted.reject(signal.reason))
+  try {
+    return await Promise.race([promise, aborted.promise])
+  } finally {
+    listener[Symbol.dispose]()
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module'
+import { parseArgs } from 'node:util'
+
+import { LIMITS } from './flow.mjs'
+import { record } from './record.mjs'
+
+const { version: VERSION } = createRequire(import.meta.url)('../package.json')
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }
+const OPTION_KEYS = {
+  url: 'url',
+  flow: 'flow',
+  out: 'output',
+  preset: 'preset',
+  browser: 'browser',
+  'storage-state': 'storageState',
+  'viewport-width': 'viewportWidth',
+  'viewport-height': 'viewportHeight',
+  scale: 'scale',
+  fps: 'fps',
+  'post-roll': 'postRoll',
+  'ready-timeout': 'readyTimeout',
+  'run-dir': 'runDirectory',
+}
+const NUMBER_KEYS = new Set(['viewportWidth', 'viewportHeight', 'scale', 'fps', 'postRoll', 'readyTimeout'])
+const HELP = `traceframe ${VERSION}
+
+Record a scripted Chromium flow and render a smooth cursor and click pulse.
+
+Usage:
+  traceframe record --url <url> --flow <flow.mjs> [--out <video.mp4>] [options]
+
+Options:
+  --preset <standard|draft>    standard: 1280x800 CSS viewport, 2560x1600 at 60 FPS (default)
+                               draft: 1280x800 CSS viewport, 1280x800 at 30 FPS
+  --browser <path>             Chromium executable (or set CHROME_PATH)
+  --storage-state <path>       Playwright storage state JSON
+  --viewport-width <pixels>    CSS viewport width
+  --viewport-height <pixels>   CSS viewport height
+  --scale <1|2>                Device scale factor; the video is the viewport times this
+  --fps <30|60>                Encoded frame rate
+  --post-roll <seconds>        Tail after the flow (default: 0.3)
+  --ready-timeout <seconds>    Playwright timeout for the page load and calls in ready() (default: 30)
+  --run-dir <path>             Keep the raw capture and FFmpeg filter in this directory
+  -h, --help                   Show this help
+  -v, --version                Show the version
+
+The flow module must export a default function. It may also export
+ready({ page, signal }) to establish state before capture and initialPointer
+{ x, y } to set where the cursor starts.
+The flow helpers are move(), hover(), click(), and wait(). A flow may contain
+at most ${LIMITS.maxMoves} move events, ${LIMITS.maxClicks} click events, and ${LIMITS.maxDuration} seconds of work.
+Each duration, dwell, and wait is at most ${LIMITS.maxActionDuration} seconds.
+`
+
+const interruption = new AbortController()
+let interruptedBy
+for (const [signal, exitCode] of Object.entries(SIGNAL_EXIT_CODES)) {
+  process.on(signal, () => {
+    if (interruption.signal.aborted) process.exit(exitCode)
+    interruptedBy = signal
+    process.stderr.write(`traceframe: Stopping and cleaning up.${signal === 'SIGINT' ? ' Press Ctrl-C again to exit now.' : ''}\n`)
+    interruption.abort()
+  })
+}
+
+try {
+  await main()
+} catch (error) {
+  if (interruptedBy) {
+    process.stderr.write('traceframe: Recording was interrupted.\n')
+    process.exitCode = SIGNAL_EXIT_CODES[interruptedBy]
+  } else {
+    process.stderr.write(`traceframe: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  }
+}
+
+async function main() {
+  const parsed = parseCommand(process.argv.slice(2))
+  if (parsed.help) return process.stdout.write(HELP)
+  if (parsed.version) return process.stdout.write(`${VERSION}\n`)
+  const summary = await record({ ...parsed.options, signal: interruption.signal })
+  process.stdout.write(`${JSON.stringify(summary)}\n`)
+}
+
+function parseCommand(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+      ...Object.fromEntries(Object.keys(OPTION_KEYS).map((name) => [name, { type: 'string' }])),
+    },
+  })
+  if (values.help || args.length === 0) return { help: true }
+  if (values.version) return { version: true }
+  const [command, ...rest] = positionals
+  if (command !== 'record') throw new Error('Expected the record command. Use "traceframe record --help".')
+  if (rest.length) throw new Error(`Unexpected argument: ${rest[0]}`)
+
+  const options = {}
+  for (const [name, key] of Object.entries(OPTION_KEYS)) {
+    if (values[name] !== undefined) options[key] = NUMBER_KEYS.has(key) ? Number(values[name]) : values[name]
+  }
+  return { options }
+}

package/src/config.mjs

@@ -0,0 +1,57 @@
+import { resolve } from 'node:path'
+
+import { TraceframeError } from './errors.mjs'
+
+const PRESETS = {
+  standard: { viewport: { width: 1280, height: 800 }, scale: 2, fps: 60 },
+  draft: { viewport: { width: 1280, height: 800 }, scale: 1, fps: 30 },
+}
+
+export function createConfig(options = {}) {
+  const presetName = options.preset ?? 'standard'
+  check(Object.hasOwn(PRESETS, presetName), `Unknown preset: ${presetName}`)
+  const preset = PRESETS[presetName]
+
+  const viewport = {
+    width: options.viewportWidth ?? preset.viewport.width,
+    height: options.viewportHeight ?? preset.viewport.height,
+  }
+  check(Number.isInteger(viewport.width) && viewport.width > 0, 'Viewport width must be a positive integer.')
+  check(Number.isInteger(viewport.height) && viewport.height > 0, 'Viewport height must be a positive integer.')
+  const scale = options.scale ?? preset.scale
+  check(scale === 1 || scale === 2, 'Scale must be 1 or 2.')
+  const video = {
+    width: viewport.width * scale,
+    height: viewport.height * scale,
+    fps: options.fps ?? preset.fps,
+  }
+  check(video.fps === 30 || video.fps === 60, 'FPS must be 30 or 60.')
+  check(video.width % 2 === 0 && video.height % 2 === 0, 'At scale 1, the viewport width and height must be even.')
+
+  check(options.flow, 'A flow file is required (the flow option, or --flow).')
+  check(options.url, 'A URL is required (the url option, or --url).')
+  const output = resolve(options.output ?? 'traceframe.mp4')
+  check(output.toLowerCase().endsWith('.mp4'), 'Output path must use the .mp4 extension.')
+  const postRoll = options.postRoll ?? 0.3
+  check(Number.isFinite(postRoll) && postRoll >= 0, 'Post-roll must be 0 or more seconds.')
+  const readyTimeout = options.readyTimeout ?? 30
+  check(Number.isFinite(readyTimeout) && readyTimeout > 0, 'Ready timeout must be more than 0 seconds.')
+
+  return {
+    url: options.url,
+    flow: resolve(options.flow),
+    output,
+    storageState: options.storageState,
+    browser: options.browser ?? process.env.CHROME_PATH,
+    viewport,
+    video,
+    scale,
+    postRoll,
+    readyTimeout,
+    runDirectory: options.runDirectory ? resolve(options.runDirectory) : undefined,
+  }
+}
+
+function check(valid, message) {
+  if (!valid) throw new TraceframeError(message, { code: 'INVALID_CONFIG' })
+}

package/src/errors.mjs

@@ -0,0 +1,7 @@
+export class TraceframeError extends Error {
+  constructor(message, { code, ...options } = {}) {
+    super(message, options)
+    this.name = 'TraceframeError'
+    this.code = code
+  }
+}

package/src/ffmpeg.mjs

@@ -0,0 +1,54 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+import { TraceframeError } from './errors.mjs'
+
+const execFileAsync = promisify(execFile)
+
+export async function probeFfmpeg() {
+  const version = await runCommand('ffmpeg', ['-version'])
+  const major = parseFfmpegMajor(version.stdout)
+  if (!(major >= 5)) {
+    throw new TraceframeError(`FFmpeg 5 or newer is required. Found: ${version.stdout.split('\n')[0].trim()}`, { code: 'FFMPEG_UNSUPPORTED' })
+  }
+  const codecs = await runCommand('ffmpeg', ['-hide_banner', '-encoders'])
+  if (!codecs.stdout.includes('libx264')) {
+    throw new TraceframeError('System FFmpeg does not provide the libx264 encoder.', { code: 'FFMPEG_UNSUPPORTED' })
+  }
+  await runCommand('ffprobe', ['-version'])
+  return { filterComplexFileOption: filterComplexFileOption(major) }
+}
+
+export async function probeDuration(path, signal) {
+  const { stdout } = await runCommand('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', path], { signal })
+  return Number(stdout)
+}
+
+export async function runCommand(command, args, options = {}) {
+  const run = execFileAsync(command, args, options)
+  const closed = new Promise((resolve) => run.child.once('close', resolve))
+  try {
+    return await run
+  } catch (error) {
+    // An abort rejects at once, but the process may take a moment to exit. Wait so cleanup does not race it.
+    if (options.signal?.aborted) await closed
+    if (error.code === 'ENOENT') {
+      throw new TraceframeError(`${command} was not found. Install FFmpeg 5 or newer with libx264, and make sure ffmpeg and ffprobe are on your PATH.`, { code: 'FFMPEG_MISSING' })
+    }
+    const rawDetail = error.stderr?.trim() || error.stdout?.trim() || error.message
+    const detail = rawDetail.length > 2_000 ? `${rawDetail.slice(0, 1_900)}\n… output truncated` : rawDetail
+    throw new TraceframeError(`${command} failed: ${detail}`, { code: 'COMMAND_FAILED', cause: error })
+  }
+}
+
+export function parseFfmpegMajor(output) {
+  const release = output.match(/ffmpeg version [nN]?(\d+)\./)
+  if (release) return Number(release[1])
+  // Snapshot builds print no release number. libavutil 57 shipped with FFmpeg 5, 58 with 6, 59 with 7, and so on.
+  const libavutil = output.match(/libavutil\s+(\d+)\./)
+  return libavutil ? Number(libavutil[1]) - 52 : undefined
+}
+
+export function filterComplexFileOption(major) {
+  return major >= 7 ? '-/filter_complex' : '-filter_complex_script'
+}

package/src/flow.mjs

@@ -0,0 +1,197 @@
+import { setTimeout as delay } from 'node:timers/promises'
+import { pathToFileURL } from 'node:url'
+
+import { TraceframeError } from './errors.mjs'
+
+export const LIMITS = {
+  maxDuration: 120,
+  maxMoves: 100,
+  maxClicks: 100,
+  maxActionDuration: 30,
+}
+const MOVE_SECONDS = 0.5
+const DWELL_SECONDS = 0.25
+// People hold a mouse button for about 100 ms, long enough for press styles such as :active to show.
+const PRESS_HOLD_MS = 100
+const MOVE_SAMPLE_MS = 1000 / 30
+
+export async function loadFlow(path, viewport) {
+  let module
+  try {
+    module = await import(pathToFileURL(path).href)
+  } catch (error) {
+    throw new TraceframeError(`Could not load flow: ${path}: ${error instanceof Error ? error.message : error}`, { code: 'INVALID_FLOW', cause: error })
+  }
+  if (typeof module.default !== 'function') throw new TraceframeError('Flow must export a default function.', { code: 'INVALID_FLOW' })
+  const { x, y } = module.initialPointer ?? { x: Math.round(viewport.width / 4), y: Math.max(0, viewport.height - 80) }
+  if (!insideViewport({ x, y }, viewport)) {
+    throw new TraceframeError('Flow initialPointer must be a point inside the viewport.', { code: 'INVALID_FLOW' })
+  }
+  return { run: module.default, ready: module.ready, initialPointer: { x, y } }
+}
+
+// Events are timed in seconds from `clock`, the epoch milliseconds of the first video frame.
+export function createFlowApi({ page, trace, clock, viewport, signal }) {
+  let pointer = trace.initialPointer
+  const sleep = (milliseconds) => delay(milliseconds, undefined, { signal })
+
+  const movePointer = async (point, duration) => {
+    assertBelowLimit(trace.moves, LIMITS.maxMoves, 'move')
+    const from = pointer
+    const to = { x: point.x, y: point.y }
+    trace.moves.push({ at: secondsSince(clock), duration, from, to })
+
+    // Each sample follows the clock, so a late sample skips ahead instead of slowing the move down.
+    const total = duration * 1000
+    const startedAt = performance.now()
+    let elapsed = 0
+    while (elapsed < total) {
+      await sleep(Math.min(MOVE_SAMPLE_MS, total - elapsed))
+      elapsed = Math.min(total, performance.now() - startedAt)
+      const eased = easeOutCubic(elapsed / total)
+      await page.mouse.move(from.x + (to.x - from.x) * eased, from.y + (to.y - from.y) * eased)
+    }
+    pointer = to
+  }
+
+  const moveTo = async (locator, duration, name) => {
+    const seconds = durationSeconds(duration ?? MOVE_SECONDS, `${name} duration`)
+    await locator.waitFor()
+    const box = await locator.boundingBox()
+    if (!box) throw new TraceframeError(`Could not find ${locator}.`, { code: 'FLOW_TARGET_MISSING' })
+    // A person does not chase a target that shifts under a pointer already inside it.
+    if (pointInsideBox(pointer, box)) return pointer
+    const point = await aimPoint(locator, box)
+    if (!insideViewport(point, viewport)) {
+      throw new TraceframeError(`${locator} is outside the viewport. Scroll explicitly before moving to it.`, { code: 'FLOW_TARGET_OUTSIDE_VIEWPORT' })
+    }
+    await movePointer(point, seconds)
+    const after = await locator.boundingBox()
+    if (!after || !pointInsideBox(point, after)) {
+      throw new TraceframeError(`${locator} moved while the pointer was arriving.`, { code: 'FLOW_TARGET_MOVED' })
+    }
+    return point
+  }
+
+  return {
+    async hover(locator, options = {}) {
+      await moveTo(locator, options.duration, 'hover')
+    },
+    async click(locator, options = {}) {
+      assertBelowLimit(trace.clicks, LIMITS.maxClicks, 'click')
+      const dwell = durationSeconds(options.dwell ?? DWELL_SECONDS, 'click dwell', { allowZero: true })
+      const point = await moveTo(locator, options.duration, 'click')
+      await sleep(dwell * 1000)
+      // Hold on to this element: a control may rename or hide itself once it is pressed.
+      const element = await locator.elementHandle()
+      await element.waitForElementState('enabled').catch((error) => {
+        throw error.name === 'TimeoutError' ? new TraceframeError(`${locator} stayed disabled.`, { code: 'FLOW_TARGET_DISABLED', cause: error }) : error
+      })
+      await assertReceivesPointer(element, locator, point)
+      const at = secondsSince(clock)
+      await page.mouse.down()
+      try {
+        await sleep(PRESS_HOLD_MS)
+        // A press style such as :active { scale: 0.95 } can shrink the target out from under a pointer near its edge.
+        // A target that disappears when pressed, such as an option that closes its list, has already taken the press.
+        const pressed = await element.boundingBox()
+        if (pressed && !pointInsideBox(point, pressed)) {
+          throw new TraceframeError(`${locator} moved away from the pointer when pressed. Click nearer its center.`, { code: 'FLOW_TARGET_MOVED' })
+        }
+      } finally {
+        await page.mouse.up()
+      }
+      trace.clicks.push({ at, point })
+    },
+    async move(point, options = {}) {
+      if (!insideViewport(point, viewport)) {
+        throw new TraceframeError('move requires an { x, y } point inside the viewport.', { code: 'INVALID_FLOW' })
+      }
+      await movePointer(point, durationSeconds(options.duration ?? MOVE_SECONDS, 'move duration'))
+    },
+    async wait(seconds) {
+      await sleep(durationSeconds(seconds, 'wait', { allowZero: true }) * 1000)
+    },
+  }
+}
+
+function insideViewport(point, viewport) {
+  return point?.x >= 0 && point?.y >= 0 && point.x <= viewport.width && point.y <= viewport.height
+}
+
+function secondsSince(clock) {
+  return (Date.now() - clock) / 1000
+}
+
+// render.mjs draws the cursor along the same curve.
+function easeOutCubic(progress) {
+  return 1 - (1 - progress) ** 3
+}
+
+function durationSeconds(value, name, { allowZero = false } = {}) {
+  if (!Number.isFinite(value) || (allowZero ? value < 0 : value <= 0) || value > LIMITS.maxActionDuration) {
+    const range = allowZero ? 'between 0 and' : 'more than 0 and at most'
+    throw new TraceframeError(`The ${name} must be ${range} ${LIMITS.maxActionDuration} seconds.`, { code: 'INVALID_FLOW' })
+  }
+  return value
+}
+
+function assertBelowLimit(events, limit, type) {
+  if (events.length >= limit) {
+    throw new TraceframeError(`Flow has more than ${limit} ${type} events.`, { code: 'FLOW_LIMIT' })
+  }
+}
+
+function pointInsideBox(point, box) {
+  return point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height
+}
+
+// Aim at the middle of the first line box, as Playwright does, so a link that wraps onto two lines is not missed.
+async function aimPoint(locator, box) {
+  const offset = await locator.evaluate((element) => {
+    const bounds = element.getBoundingClientRect()
+    const first = element.getClientRects()[0] ?? bounds
+    // As fractions of the element's size, because a scaled iframe makes the page box a different size than the element's own.
+    return { x: (first.left + first.width / 2 - bounds.left) / bounds.width, y: (first.top + first.height / 2 - bounds.top) / bounds.height }
+  })
+  return { x: box.x + offset.x * box.width, y: box.y + offset.y * box.height }
+}
+
+async function assertReceivesPointer(element, locator, point) {
+  const box = await element.boundingBox()
+  if (!box || !pointInsideBox(point, box)) {
+    throw new TraceframeError(`${locator} moved before the click.`, { code: 'FLOW_TARGET_MOVED' })
+  }
+  const receivesPointer = await element.evaluate((target, { x, y }) => {
+    const rect = target.getBoundingClientRect()
+    let current = target.getRootNode().elementFromPoint(rect.left + x * rect.width, rect.top + y * rect.height)
+    while (current) {
+      if (current === target || target.contains(current)) return true
+      current = current.assignedSlot ?? current.parentElement ?? current.getRootNode().host ?? null
+    }
+    return false
+  }, relativePoint(point, box))
+  if (!receivesPointer || !(await framesReceivePointer(element, point))) {
+    throw new TraceframeError(`${locator} is covered at the click point.`, { code: 'FLOW_TARGET_OBSCURED' })
+  }
+}
+
+async function framesReceivePointer(element, point) {
+  let frame = await element.ownerFrame()
+  while (frame?.parentFrame()) {
+    const frameElement = await frame.frameElement()
+    const box = await frameElement.boundingBox()
+    if (!box) return false
+    const hit = await frameElement.evaluate((target, { x, y }) => {
+      const rect = target.getBoundingClientRect()
+      return target.getRootNode().elementFromPoint(rect.left + x * rect.width, rect.top + y * rect.height) === target
+    }, relativePoint(point, box))
+    if (!hit) return false
+    frame = frame.parentFrame()
+  }
+  return true
+}
+
+function relativePoint(point, box) {
+  return { x: (point.x - box.x) / box.width, y: (point.y - box.y) / box.height }
+}

package/src/index.mjs

@@ -0,0 +1,2 @@
+export { record } from './record.mjs'
+export { TraceframeError } from './errors.mjs'

package/src/record.mjs

@@ -0,0 +1,39 @@
+import { mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { createConfig } from './config.mjs'
+import { captureFlow } from './capture.mjs'
+import { probeFfmpeg } from './ffmpeg.mjs'
+import { loadFlow } from './flow.mjs'
+import { renderVideo } from './render.mjs'
+
+export async function record(options = {}) {
+  const { signal } = options
+  signal?.throwIfAborted()
+  const config = createConfig(options)
+  const ffmpeg = await probeFfmpeg()
+  const flow = await loadFlow(config.flow, config.viewport)
+  await mkdir(dirname(config.output), { recursive: true })
+  const directory = config.runDirectory ?? await mkdtemp(join(tmpdir(), 'traceframe-'))
+  await mkdir(directory, { recursive: true })
+
+  try {
+    const { rawPath, trace } = await captureFlow({ config, flow, directory, signal })
+    const duration = await renderVideo({ rawPath, trace, directory, config, ffmpeg, signal })
+    return {
+      output: config.output,
+      width: config.video.width,
+      height: config.video.height,
+      fps: config.video.fps,
+      duration,
+      moveCount: trace.moves.length,
+      clickCount: trace.clicks.length,
+      runDirectory: config.runDirectory,
+    }
+  } catch (error) {
+    throw signal?.aborted ? signal.reason : error
+  } finally {
+    if (!config.runDirectory) await rm(directory, { recursive: true, force: true })
+  }
+}

package/src/render.mjs

@@ -0,0 +1,93 @@
+import { rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+import { probeDuration, runCommand } from './ffmpeg.mjs'
+import { TraceframeError } from './errors.mjs'
+
+const ASSETS = join(import.meta.dirname, 'assets')
+// The arrow tip in cursor.svg.
+const CURSOR_HOTSPOT = { x: 6.6, y: 1.6 }
+const CLICK = { duration: 0.24, scaleStart: 0.7, scaleEnd: 1.25 }
+// eof_action=pass lets the main video drive each overlay instead of waiting on the looping image inputs; without it, rendering is many times slower.
+// format=yuv444 places overlays on whole pixels. The default yuv420 snaps them to even pixels, and RGB costs more for the same result.
+const OVERLAY = 'eof_action=pass:format=yuv444'
+
+export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, signal }) {
+  const { fps } = config.video
+  const outputDuration = Math.max(trace.end + config.postRoll, ...trace.clicks.map((click) => click.at + CLICK.duration))
+  const filterPath = join(directory, 'render.filter')
+  await writeFile(filterPath, buildFilterScript({ trace, scale: config.scale }))
+  const outputTemp = join(dirname(config.output), `.traceframe-${randomUUID()}.tmp.mp4`)
+  const args = [
+    '-y', '-hide_banner', '-loglevel', 'error',
+    '-i', rawPath,
+    '-loop', '1', '-framerate', String(fps), '-i', join(ASSETS, `cursor-${config.scale}x.png`),
+  ]
+  if (trace.clicks.length) args.push('-loop', '1', '-framerate', String(fps), '-t', String(CLICK.duration + 1 / fps), '-i', join(ASSETS, `click-pulse-${config.scale}x.png`))
+  args.push(
+    ffmpeg.filterComplexFileOption, filterPath,
+    '-map', '[final]',
+    '-t', String(number(outputDuration)),
+    '-r', String(fps),
+    '-c:v', 'libx264', '-preset', 'fast', '-crf', '18',
+    '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-color_range', 'tv',
+    '-g', String(fps * 2),
+    '-movflags', '+faststart', outputTemp,
+  )
+  try {
+    await runCommand('ffmpeg', args, { signal })
+    const duration = await probeDuration(outputTemp, signal)
+    if (!(Math.abs(duration - outputDuration) <= 1.5 / fps)) {
+      throw new TraceframeError(`The rendered video is ${duration.toFixed(2)} seconds long, but the recording is ${outputDuration.toFixed(2)} seconds.`, { code: 'OUTPUT_MISMATCH' })
+    }
+    signal?.throwIfAborted()
+    await rename(outputTemp, config.output)
+    return duration
+  } catch (error) {
+    await rm(outputTemp, { force: true })
+    throw error
+  }
+}
+
+// Event times are seconds from the first frame of the raw video.
+export function buildFilterScript({ trace, scale }) {
+  const { clicks, moves } = trace
+  // Playwright ends the raw video by the time it received the last frame, so a page that stays still can end it a little before the post-roll. The page did not change, so repeat its last frame.
+  const filters = [`[0:v]setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=1[video0]`]
+  if (clicks.length) filters.push(`[2:v]format=rgba,split=${clicks.length}${clicks.map((_, index) => `[pulse${index}]`).join('')}`)
+  clicks.forEach((click, index) => filters.push(...clickFilter(click, index, scale)))
+
+  const cursorLabels = moves.map((_, index) => `[cursor${index}]`).join('')
+  filters.push(`[1:v]format=rgba,split=${moves.length + 1}${cursorLabels}[cursor${moves.length}]`)
+  const coordinate = (value, hotspot) => number(value * scale - hotspot * scale)
+  const initialEnable = moves.length ? `:enable='lt(t,${number(moves[0].at)})'` : ''
+  filters.push(`[video${clicks.length}][cursor0]overlay=x='${coordinate(trace.initialPointer.x, CURSOR_HOTSPOT.x)}':y='${coordinate(trace.initialPointer.y, CURSOR_HOTSPOT.y)}':${OVERLAY}${initialEnable}[cursorVideo0]`)
+  moves.forEach((move, index) => {
+    const start = number(move.at)
+    const end = index + 1 < moves.length ? number(moves[index + 1].at) : undefined
+    // Each window excludes its end, so the frame where one move hands over to the next does not draw the cursor twice.
+    const enable = end === undefined ? `gte(t,${start})` : `gte(t,${start})*lt(t,${end})`
+    // The same curve as easeOutCubic in flow.mjs, so the drawn cursor follows the real pointer.
+    const eased = `(1-pow(1-clip((t-${start})/${number(move.duration)},0,1),3))`
+    const x = `${coordinate(move.from.x, CURSOR_HOTSPOT.x)}+${number((move.to.x - move.from.x) * scale)}*${eased}`
+    const y = `${coordinate(move.from.y, CURSOR_HOTSPOT.y)}+${number((move.to.y - move.from.y) * scale)}*${eased}`
+    filters.push(`[cursorVideo${index}][cursor${index + 1}]overlay=x='${x}':y='${y}':${OVERLAY}:enable='${enable}'[cursorVideo${index + 1}]`)
+  })
+  filters.push(`[cursorVideo${moves.length}]colorspace=ispace=bt470bg:iprimaries=bt709:itrc=bt709:all=bt709:format=yuv420p[final]`)
+  return filters.join(';')
+}
+
+function clickFilter(click, index, scale) {
+  const start = number(click.at)
+  const end = number(start + CLICK.duration)
+  const growth = `(${CLICK.scaleStart}+${CLICK.scaleEnd - CLICK.scaleStart}*clip((t-${start})/${CLICK.duration},0,1))`
+  return [
+    `[pulse${index}]setpts=PTS-STARTPTS+${start}/TB,scale=w='iw*${growth}':h='ih*${growth}':eval=frame,fade=t=out:st=${start}:d=${CLICK.duration}:alpha=1[click${index}]`,
+    `[video${index}][click${index}]overlay=x='${number(click.point.x * scale)}-w/2':y='${number(click.point.y * scale)}-h/2':${OVERLAY}:enable='between(t,${start},${end})'[video${index + 1}]`,
+  ]
+}
+
+function number(value) {
+  return Number(value.toFixed(6))
+}