@milkstraw/traceframe 0.3.0 → 0.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+Browser capture is silent by default. Add an [external audio file](#add-audio) with explicit timing; tab audio and microphones are not captured automatically.
+
 https://github.com/user-attachments/assets/38e02cd5-a9ba-4f3c-938c-159955353141
 
 ## Prerequisites
@@ -16,7 +18,7 @@ To use system Chrome 150 or later, pass `--browser` or set `CHROME_PATH`, and in
 
 In a sandbox, such as a coding agent's, allow Playwright's browser download and let Chromium start.
 
-To record pages behind a login, pass a Playwright storage-state file with `--storage-state`. Keep it in `.auth/` or another ignored location.
+To record pages behind a login, pass a Playwright storage-state file with `--storage-state`. See [creating saved login state and switching accounts](docs/recording-flows.md#save-and-switch-login-state), and keep state in `.auth/` or another ignored location.
 
 ## Record a video
 
@@ -51,7 +53,7 @@ npx @milkstraw/traceframe record \
   --preset draft
 ```
 
-The [recording guide](docs/recording-flows.md) includes a runnable example and recipes for form input, asynchronous results, browser settings, and editing or sharing a recording.
+The [recording guide](docs/recording-flows.md) includes a runnable example and recipes for authentication, form input, asynchronous results, captions, browser settings, and inspecting, editing or sharing a recording.
 
 Both presets use a 1280×800 CSS viewport. `draft` produces 1280×800 at 30 FPS; `standard` (the default) produces 2560×1600 at 60 FPS. The output dimensions are the viewport times `--scale`, so `--preset draft --scale 2` gives 2560×1600 at 30 FPS. The command prints a JSON summary when it finishes.
 
@@ -145,20 +147,90 @@ await record({
 })
 ```
 
+### Record a page you already opened
+
+Use `recordPage` when your script already owns a Playwright page, including a page in a persistent extension context. Prepare navigation, authentication, application readiness and fonts before calling it. With a prepared `page`:
+
+```js
+import { recordPage } from '@milkstraw/traceframe'
+
+const save = page.getByRole('button', { name: 'Save', exact: true })
+await recordPage({
+  page,
+  output: './recording.mp4',
+  flow: async ({ click, wait, signal }) => {
+    await click(save)
+    await page.getByText('Saved', { exact: true }).waitFor({ signal })
+    await wait(3)
+  },
+})
+```
+
+The callback receives the same `page`, `signal` and five helpers as a flow file. It can close over your script's locators and state. See the [runnable existing-page example](examples/existing-page.mjs); in a clone, run `node examples/existing-page.mjs` to save `.traceframe/existing-page.mp4` using synthetic local content.
+
+Use Playwright 1.64.1 with Chromium, a fixed viewport, 100% browser zoom and an unscaled page. Traceframe checks the page's inner dimensions and visual viewport before starting capture, rejecting unsupported geometry with `CAPTURE_SIZE_MISMATCH`. `recordPage` keeps the page, context and browser open on success, failure and cancellation. It does not navigate, resize, run a `ready` hook, or change page timeouts. Your script owns setup and shutdown. The CLI and `record` continue to create and close their own browser.
+
+`page` and a function `flow` are required. `output`, `audio`, `postRoll`, `flowTimeout`, `runDirectory` and `signal` have the same meaning as in `record`, and the return value is the same recording summary. Set `initialPointer: { x, y }` to choose the starting cursor position. The page's viewport determines the dimensions; `scale` defaults to 1 and accepts 1 or 2, and `fps` defaults to 30 and accepts 30 or 60. Use these explicit settings instead of a preset. Browser setup options such as `url`, `browser`, `storageState`, viewport dimensions and `readyTimeout` are rejected.
+
+Traceframe moves the caller's pointer only after validating the first frame. To show the starting hover state from frame 0, move the page's mouse to your chosen `initialPointer` before calling `recordPage`.
+
+For 2× frames, launch the caller's browser with `chromium.launch({ args: ['--force-device-scale-factor=2'] })`, create its context with `deviceScaleFactor: 2`, and pass `scale: 2` to `recordPage`. The same launch argument works with `launchPersistentContext`. Setting `deviceScaleFactor` alone does not ensure 2× screencast frames. Traceframe checks the first JPEG's actual dimensions before running the callback and rejects mismatches with `CAPTURE_SIZE_MISMATCH`.
+
+Keep the viewport, zoom and visual scale fixed and the page open until `recordPage` settles; geometry is checked only at startup. Only that page is recorded; a tab closed during a take may lose its capture. Use the page exclusively for recording: concurrent screencasts, context `recordVideo` and tracing with screenshots can change frame dimensions or supply stale frames. A size check cannot detect every conflict. Overlapping `recordPage` calls on the same page reject with `PAGE_RECORDING_ACTIVE`.
+
+Await every helper. Helpers observe cancellation before further pointer or scroll actions, and release a mouse button that was already pressed; an already-issued action may still complete. Arbitrary callback code must cooperate with `signal`, including passing it to supported Playwright operations. A flow timeout does not forcibly terminate that code. Sequential takes are supported after a successful screencast stop, including ordinary flow failures and cooperative cancellation. If Playwright's FFmpeg is missing, Traceframe stops the partial capture before rejecting. Other startup or stop failures may need a new page or context; Traceframe leaves that recovery to the caller and does not stop a pre-existing caller screencast.
+
+Traceframe removes its own temporary outputs unless `runDirectory` is supplied. Playwright keeps original WebMs in its browser artifacts directory until the caller closes the browser, even after a take has been saved. For extension pages, use full Chromium; the headless shell alone does not load extensions. This path was checked on Linux with Playwright 1.64.1 and its bundled full Chromium using a synthetic extension.
+
+### Add audio
+
+Both `record` and `recordPage` accept `audio: { path: './sound.wav', offset: 0 }`. The CLI accepts the same settings:
+
+```sh
+npx @milkstraw/traceframe record --url http://localhost:3000 --flow ./flow.mjs \
+  --audio .traceframe/sound.wav --audio-offset 0.5 --out .traceframe/demo.mp4
+```
+
+`offset` is seconds from the first video frame to the first audio sample. Positive values add leading silence; negative values discard the beginning of the audio (in the CLI, use e.g. `--audio-offset=-0.25`). The default is 0. Short audio is padded with silence, and longer audio is trimmed to the video's end. Nothing is looped or stretched. The first audio stream is encoded as stereo AAC at 48 kHz, 192 kb/s; system FFmpeg must provide its standard `aac` encoder. Successful summaries include `audio: true`.
+
+The input must be a local file, such as WAV, MP3, M4A or audio WebM. Static inputs are checked before browser recording, so a missing file or missing audio stream cannot waste a take (`AUDIO_INVALID`). After capture, an audio start at or after the video's end rejects with `AUDIO_OUTSIDE_VIDEO`. A negative offset that discards the entire source produces a silent audio track.
+
+Traceframe reads the file without modifying or deleting it; use an input path different from the output and the reserved files in `runDirectory` (`capture.webm`, `render.filter`, `failure.png`). Keep recordings in an ignored directory.
+
+For audio recorded alongside the flow, supply an async function instead. It runs once after successful capture and post-roll, before rendering, so it can finalize the external recorder and return its file. `startedAt` is the first video frame's timestamp in epoch milliseconds:
+
+```js
+await recordPage({
+  page,
+  output: '.traceframe/demo.mp4',
+  flow,
+  audio: async ({ startedAt, signal }) => {
+    const { path, startedAt: audioStartedAt } = await finishAudioRecording({ signal })
+    return { path, offset: (audioStartedAt - startedAt) / 1000 }
+  },
+})
+```
+
+Here `finishAudioRecording` belongs to your script and reports the timestamp of its first recorded sample. Use timestamps on a shared clock, or determine the offset using an audiovisual marker. An offset corrects a constant alignment difference; it does not correct clock drift. Check markers near both ends of longer takes. See the [audio workflow](docs/recording-flows.md#align-external-audio).
+
+Your script owns the external recorder and its cleanup, including on flow failure or cancellation. The audio function is skipped if capture fails and must cooperate with `signal` when supplied. It may finish writing after capture; a static input must already exist before recording. Neither form captures browser or system sound by itself.
+
+### Errors and cancellation
+
 Traceframe's own errors are `TraceframeError` instances (exported by the package) with a `code`, such as `READY_FAILED` or `FLOW_TARGET_OBSCURED`. Other exceptions thrown by the flow become `FLOW_FAILED`, with the original thrown value in `cause`; existing Traceframe error codes and causes are preserved.
 
 When available, `error.diagnostics` contains:
 
 | Field | Meaning |
 | --- | --- |
-| `flowLocations` | Locations in the supplied flow file, as `{ file, line, column }` objects with an absolute path and 1-based line/column. Empty when the error stack has no matching frame. |
+| `flowLocations` | Locations in the supplied flow file, as `{ file, line, column }` objects with an absolute path and 1-based line/column. Empty for a callback or when the error stack has no matching frame. |
 | `recordingTime` | Elapsed seconds from the first captured frame for a capture-stage failure, measured before collecting failure artifacts. Omitted before the first frame and for later rendering failures. |
 | `capturePath` | Absolute path to the retained raw capture, only when `runDirectory` was supplied and saving succeeded. |
 | `screenshotPath` | Absolute path to the saved failure screenshot, only when `runDirectory` was supplied and the screenshot succeeded. |
 
 A flow timeout may have no flow location because it is raised outside the blocked operation. Screenshots are best effort and have a five-second collection budget. Partial captures are saved before browser shutdown, with no fixed time limit so slower encoders can finish. Diagnostic failures do not replace the original error.
 
-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.
+Pass `signal` to stop a recording early. Traceframe stops its recording/rendering work and removes its temporary files before rejecting with the signal's reason. `record` also closes its browser; `recordPage` leaves the caller's browser open. 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.
 
 A stuck recording encoder can delay saving and cancellation indefinitely. A second Ctrl-C forces the CLI to exit and can discard the unfinished capture. API callers that need a hard shutdown deadline should run recording in a separate process they can terminate.
 

package/docs/recording-flows.md

@@ -20,7 +20,48 @@ In a repository clone, run `npx traceframe record --url "file://$PWD/examples/re
 
 Inspect the running application at the recording viewport. Pick a short journey with a visible result and known demo data. Use role, label, or test-id locators; `locator.describe()` can make errors clearer.
 
-Put setup and page readiness in `ready({ page, signal })`. This runs after initial navigation and before recording. Use `--storage-state` for an existing login, and keep that file in an ignored directory. For headers, locale, or themes, see [optional startup settings](#optional-startup-settings).
+Put setup and page readiness in `ready({ page, signal })`. This runs after initial navigation and before recording. Use `--storage-state` for an existing login, as below. For headers, locale, or themes, see [optional startup settings](#optional-startup-settings).
+
+If your script already owns the page or an extension context, use [`recordPage`](../README.md#record-a-page-you-already-opened) with an inline callback. Prepare the page before calling it; the caller owns navigation and browser cleanup.
+
+## Save and switch login state
+
+Add `.auth/` to your project's `.gitignore`; saved state can grant access to the account. To create it interactively, install full Chromium and open Playwright's login window:
+
+```sh
+mkdir -p .auth
+npx playwright@1.64.1 install chromium
+npx playwright@1.64.1 codegen --save-storage=.auth/first-account.json http://localhost:3000
+```
+
+Sign in normally, wait for the authenticated screen, then close the browser window to save the state. This requires a desktop/display; the headless-shell-only installation used for recording is insufficient. Record with the same application origin, including its port:
+
+```sh
+npx @milkstraw/traceframe record \
+  --url http://localhost:3000 --flow ./flow.mjs \
+  --storage-state .auth/first-account.json --out ./recording.mp4
+```
+
+If a Playwright script already signs in, save state after checking that login finished and before closing its browser:
+
+```js
+await page.getByRole('heading', { name: 'Example workspace' }).waitFor()
+await page.context().storageState({ path: '.auth/first-account.json', indexedDB: true })
+```
+
+Storage state includes cookies and local storage. The scripted `indexedDB: true` also saves IndexedDB, which some apps use for authentication; the codegen command above does not include it.
+
+For a second account, save a separate file from a fresh login. To switch during a flow, first navigate the recorded page to `about:blank` to release its open IndexedDB connections. Apply the second account with Playwright 1.64.1's `setStorageState`, then return to the app on that same page and verify the account:
+
+```js
+await page.goto('about:blank')
+await page.context().setStorageState('.auth/second-account.json')
+await page.goto('http://localhost:3000')
+await page.getByRole('heading', { name: 'Second account' }).waitFor()
+await page.evaluate(() => document.fonts.ready)
+```
+
+Replace the URL and headings with your application's account-specific checks. `setStorageState` replaces cookies and origin storage, including local storage and IndexedDB, rather than just adding cookies. Neither saving nor replacing storage state handles `sessionStorage`; if the app uses it for authentication, restore or clear it separately for the relevant origins and follow the app's login requirements. Opening a replacement page would leave Traceframe recording the original page.
 
 ## Choose the right actions
 
@@ -121,12 +162,36 @@ Use `--preset draft` while writing the flow and the default preset for the final
 
 While writing the flow, pass `--run-dir` with an ignored folder, such as `.traceframe/runs/demo`. Use a separate directory for each take. A failed take keeps its partial `capture.webm` when saving succeeds and attempts a viewport screenshot, `failure.png`. The raw capture has no added cursor overlay and may include repeated final frames after the failure time.
 
-A failed take may already have submitted real jobs, so reset demo data before recording again. Check the important transitions and the final result. You can also check the file for decode errors:
+A failed take may already have submitted real jobs, so reset demo data before recording again. Check the finished file for decode errors:
 
 ```sh
 ffmpeg -v error -xerror -i ./recording.mp4 -f null -
 ```
 
+For a visual overview of the whole recording, sample roughly every two seconds into numbered contact sheets. Add `.traceframe/` to your project's `.gitignore` and use a new inspection directory for each take:
+
+```sh
+mkdir -p .traceframe/review/take-1
+ffmpeg -i ./recording.mp4 \
+  -vf "select='isnan(prev_selected_t)+gte(t-prev_selected_t,2)',scale=640:-1,drawtext=text='%{pts\:hms}':x=8:y=8:fontsize=20:fontcolor=white:box=1:boxcolor=black@0.6,tile=4x5:padding=4" \
+  -fps_mode vfr .traceframe/review/take-1/sheet-%03d.png
+```
+
+Each sheet holds 20 timestamped samples, covering about 40 seconds. The command continues through the entire input; the last sheet may have empty cells. Do not add `-frames:v 1`, which would stop after the first sheet.
+
+On FFmpeg 5.0, replace `-fps_mode vfr` with `-vsync vfr`.
+
+Timestamp labels require FFmpeg's `drawtext` filter and an available font. Homebrew's current standard `ffmpeg` omits that filter; run `brew install ffmpeg-full` and use `"$(brew --prefix ffmpeg-full)/bin/ffmpeg"` in place of `ffmpeg` in the command above. If `drawtext` is available but no default font is found, add `fontfile=/path/to/font.ttf:` before `text=`.
+
+Inspect every sheet, then extract important results, account changes and transitions at the video's full resolution. For example, inspect the frame at 12.4 seconds:
+
+```sh
+ffmpeg -ss 00:00:12.400 -i ./recording.mp4 \
+  -frames:v 1 -update 1 .traceframe/review/take-1/detail-12.400.png
+```
+
+Small text, focus rings and brief glitches can disappear in the reduced samples. Extract nearby frames around a suspicious transition and check caption reading pauses, pointer motion and result holds against the flow's timing. Contact sheets and successful decoding alone do not establish readable pacing or smooth motion. An agent preparing a demonstration should complete these checks before presenting it for the human's feature review.
+
 ## Diagnose a failed take
 
 The CLI keeps the original error message and adds available context on standard error. For example:
@@ -141,7 +206,15 @@ traceframe: [FLOW_FAILED] Expected the Saved status.
 
 Inspect the reported screenshot, then the capture near the reported time if needed. The time is measured from the first captured frame before diagnostic collection; it is not the raw file's duration. Correct the locator or application check and reset demo data before retrying.
 
-Only paths saved for the current attempt are reported. A closed or unresponsive page may prevent a screenshot or capture from being saved. Errors before the first frame have no recording time, and a flow timeout may have no source location. Without `--run-dir`, flow locations and timing are still reported when available, but temporary captures are removed and no failure screenshot is saved. The API exposes the same context through [`error.diagnostics`](../README.md#programmatic-usage).
+Only paths saved for the current attempt are reported. A closed or unresponsive page may prevent a screenshot or capture from being saved. Errors before the first frame have no recording time, and a flow timeout may have no source location. Without `--run-dir`, flow locations and timing are still reported when available, but temporary captures are removed and no failure screenshot is saved. The API exposes the same context through [`error.diagnostics`](../README.md#errors-and-cancellation).
+
+## Align external audio
+
+Capture the application's actual processed output with your own audio recorder, then pass its local file through [`audio`](../README.md#add-audio). Use the same prepared page with `recordPage` when the audio setup needs a caller-owned context. Audio recording remains your script's responsibility; Traceframe aligns and encodes the supplied file in the final MP4.
+
+Use a distinct sound and visible change as a synchronization marker. If the visible change lands at 2.00 seconds in the video and its sound starts at 2.08 seconds in the audio file, pass `offset: -0.08`. Measure on the actual recorded streams, accounting for capture-device and encoder latency. For a live recorder, the audio supplier's `startedAt` gives the video clock; the recorder's timestamp must refer to its first sample on a shared clock.
+
+Inspect the rendered result with audio enabled, and compare another marker near the end. If the difference grows, a constant offset is insufficient: correct the external recording's rate separately before adding it. Traceframe never changes audio speed or pitch. Trimmed audio ends with the video, including post-roll; shorter audio leaves silence. For independent takes, calculate alignment for each take and close the external recorder in your script's `finally` block.
 
 ## Edit the finished video
 
@@ -160,6 +233,8 @@ export default async function ({ page, click, wait }) {
 
 Log to `console.error`, because Traceframe prints its JSON summary on standard output. This command plays seconds 2 to 9 at 4× speed. Set `fps` to the video's frame rate: 60 for the default preset, 30 for draft.
 
+This command drops the audio track. To keep audio synchronized, apply the same cuts and speed changes to its timeline, including when speeding up silent intervals.
+
 ```sh
 ffmpeg -i recording.mp4 -filter_complex "[0:v]trim=0:2,setpts=PTS-STARTPTS[a];[0:v]trim=2:9,setpts=(PTS-STARTPTS)/4[b];[0:v]trim=9,setpts=PTS-STARTPTS[c];[a][b][c]concat=n=3,fps=60[v]" -map "[v]" -c:v libx264 -crf 18 -movflags +faststart faster.mp4
 ```

package/examples/existing-page.mjs

@@ -0,0 +1,30 @@
+import { chromium } from 'playwright'
+import { recordPage } from '@milkstraw/traceframe'
+
+const browser = await chromium.launch()
+try {
+  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } })
+  await page.goto(new URL('./recipes.html', import.meta.url).href)
+  await page.getByRole('heading', { name: 'Conversation demo' }).waitFor()
+  await page.evaluate(() => document.fonts.ready)
+
+  // These locators belong to the caller's existing script.
+  const message = page.getByRole('textbox', { name: 'Message' })
+  const replies = page.getByRole('list', { name: 'Replies' }).getByRole('listitem')
+  const summary = await recordPage({
+    page,
+    output: process.argv[2] ?? '.traceframe/existing-page.mp4',
+    flow: async ({ click, wait, signal }) => {
+      await click(message)
+      await message.pressSequentially('Record this existing page.', { delay: 45, signal })
+      await click(page.getByRole('button', { name: 'Send', exact: true }))
+      await replies.first().waitFor({ signal })
+      await wait(3)
+    },
+  })
+  // The page is still usable after recording.
+  await page.getByRole('status').filter({ hasText: 'Reply complete.' }).waitFor()
+  console.log(JSON.stringify(summary))
+} finally {
+  await browser.close()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milkstraw/traceframe",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Record scripted browser flows and render smooth cursor overlays into video.",
   "keywords": [
     "playwright",
@@ -26,6 +26,7 @@
   "files": [
     "src",
     "docs/recording-flows.md",
+    "examples/existing-page.mjs",
     "examples/recipes.html",
     "examples/recipes-flow.mjs"
   ],

package/src/capture.mjs

@@ -12,31 +12,43 @@ const PLAYWRIGHT_DEFAULT_TIMEOUT = 30_000
 const FIRST_FRAME_TIMEOUT = 10_000
 const FAILURE_SCREENSHOT_TIMEOUT = 5_000
 
-export async function captureFlow({ config, flow, directory, signal: callerSignal }) {
+export async function captureFlow({ config, flow, directory, page, 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
+  const browser = page ? undefined : await launchBrowser(config, { handleSignals: !callerSignal })
   let clock
   let recording = false
   let failed = false
   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)
+    if (browser) {
+      page = await browser.newPage({ viewport: config.viewport, deviceScaleFactor: config.scale, storageState: config.storageState })
+      await raceAbort(waitForReady(page, flow, config, signal), signal)
+      signal.throwIfAborted()
+      await page.mouse.move(trace.initialPointer.x, trace.initialPointer.y)
+    } else {
+      await assertPageGeometry(page, config, signal)
+    }
 
     const firstFrame = Promise.withResolvers()
-    await startScreencast(page, rawPath, config, ({ timestamp }) => firstFrame.resolve(timestamp))
+    signal.throwIfAborted()
+    await startScreencast(page, rawPath, config, firstFrame.resolve)
     recording = true
-    clock = await withDeadline(
+    const frame = await withDeadline(
       () => firstFrame.promise,
       FIRST_FRAME_TIMEOUT,
       new TraceframeError(`No screencast frame arrived within ${FIRST_FRAME_TIMEOUT / 1000} seconds.`, { code: 'FIRST_FRAME_TIMEOUT' }),
       signal,
     )
+    clock = frame.timestamp
+    if (!browser) {
+      assertFrameSize(frame, config)
+      signal.throwIfAborted()
+      // Rejected caller-page attempts must leave the caller's pointer alone.
+      await page.mouse.move(trace.initialPointer.x, trace.initialPointer.y)
+    }
     try {
       await withDeadline(
         (flowSignal) => flow.run({ page, signal: flowSignal, ...createFlowApi({ page, trace, clock, viewport: config.viewport, signal: flowSignal }) }),
@@ -53,7 +65,7 @@ export async function captureFlow({ config, flow, directory, signal: callerSigna
     // A failed stop must not be retried: Playwright may still be waiting to finish its artifact.
     recording = false
     await page.screencast.stop()
-    return { rawPath, trace }
+    return { rawPath, trace, startedAt: clock }
   } catch (error) {
     failed = true
     const recordingTime = clock === undefined ? undefined : Math.max(0, (Date.now() - clock) / 1000)
@@ -68,8 +80,46 @@ export async function captureFlow({ config, flow, directory, signal: callerSigna
     throw await addDiagnostics(error, { flow: config.flow, recordingTime, capturePath, screenshotPath })
   } finally {
     // A shutdown error must not hide the flow failure.
-    if (failed) await browser.close().catch(() => {})
-    else await browser.close()
+    if (browser) {
+      if (failed) await browser.close().catch(() => {})
+      else await browser.close()
+    }
+  }
+}
+
+async function assertPageGeometry(page, config, signal) {
+  const [width, height, scale, left, top] = await withDeadline(
+    () => page.evaluate(() => [innerWidth, innerHeight, visualViewport.scale, visualViewport.offsetLeft, visualViewport.offsetTop]),
+    FIRST_FRAME_TIMEOUT,
+    new TraceframeError(`Could not verify page geometry within ${FIRST_FRAME_TIMEOUT / 1000} seconds. Make sure the page is responsive.`, { code: 'CAPTURE_SIZE_MISMATCH' }),
+    signal,
+  )
+  if (width !== config.viewport.width || height !== config.viewport.height || scale !== 1 || left !== 0 || top !== 0) {
+    throw new TraceframeError(`Page geometry is ${width}×${height} with visual scale ${scale} and offset ${left},${top}; expected ${config.viewport.width}×${config.viewport.height} with scale 1 and no offset. Use 100% browser zoom and an unscaled page, and keep its geometry fixed during recording.`, { code: 'CAPTURE_SIZE_MISMATCH' })
+  }
+}
+
+function assertFrameSize(frame, config) {
+  // Playwright may pad the saved WebM. Check the actual JPEG, not DPR or the container size.
+  const size = jpegSize(frame.data)
+  if (size?.width !== config.video.width || size?.height !== config.video.height ||
+      frame.viewportWidth !== config.viewport.width || frame.viewportHeight !== config.viewport.height) {
+    const scaleHint = config.scale === 2 ? ' For scale 2, launch Chromium with --force-device-scale-factor=2; deviceScaleFactor alone is insufficient.' : ''
+    throw new TraceframeError(`Screencast frames are ${size ? `${size.width}×${size.height}` : 'not a readable JPEG'} for a ${frame.viewportWidth}×${frame.viewportHeight} viewport; expected ${config.video.width}×${config.video.height} for a ${config.viewport.width}×${config.viewport.height} viewport. Keep the viewport fixed and use the page exclusively for this recording.${scaleHint}`, { code: 'CAPTURE_SIZE_MISMATCH' })
+  }
+}
+
+function jpegSize(data) {
+  if (data.length < 2 || data.readUInt16BE(0) !== 0xffd8) return undefined
+  for (let offset = 2; offset + 8 < data.length;) {
+    const marker = data.readUInt16BE(offset)
+    // Chromium emits baseline JPEG; accept the other SOF encodings as well.
+    if (marker >= 0xffc0 && marker <= 0xffcf && ![0xffc4, 0xffc8, 0xffcc].includes(marker)) {
+      return { width: data.readUInt16BE(offset + 7), height: data.readUInt16BE(offset + 5) }
+    }
+    const length = data.readUInt16BE(offset + 2)
+    if (length < 2) return undefined
+    offset += length + 2
   }
 }
 
@@ -122,6 +172,8 @@ async function startScreencast(page, path, config, onFrame) {
     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
+    // Playwright added our frame client before looking for FFmpeg; no caller recorder was active.
+    await page.screencast.stop().catch(() => {})
     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 })
   }
 }
@@ -132,6 +184,7 @@ async function withDeadline(task, milliseconds, error, signal) {
   const timer = setTimeout(() => controller.abort(error), milliseconds)
   const deadline = AbortSignal.any([signal, controller.signal])
   try {
+    deadline.throwIfAborted()
     return await raceAbort(task(deadline), deadline)
   } finally {
     clearTimeout(timer)

package/src/cli.mjs

@@ -24,8 +24,10 @@ const OPTION_KEYS = {
   'ready-timeout': 'readyTimeout',
   'flow-timeout': 'flowTimeout',
   'run-dir': 'runDirectory',
+  audio: 'audio',
+  'audio-offset': 'audioOffset',
 }
-const NUMBER_KEYS = new Set(['viewportWidth', 'viewportHeight', 'scale', 'fps', 'postRoll', 'readyTimeout', 'flowTimeout'])
+const NUMBER_KEYS = new Set(['viewportWidth', 'viewportHeight', 'scale', 'fps', 'postRoll', 'readyTimeout', 'flowTimeout', 'audioOffset'])
 const HELP = `traceframe ${VERSION}
 
 Record a scripted Chromium flow and render a smooth cursor and click pulse.
@@ -46,6 +48,8 @@ Options:
   --ready-timeout <seconds>    Playwright default timeout during navigation and ready() (default: 30)
   --flow-timeout <seconds>     Time limit for the flow, including waits (default: 120)
   --run-dir <path>             Keep the raw capture, failure screenshot and FFmpeg filter
+  --audio <path>               Add an external audio file (AAC stereo in the MP4)
+  --audio-offset <seconds>     Audio start in the video; negative trims its start (default: 0)
   -h, --help                   Show this help
   -v, --version                Show the version
 
@@ -108,5 +112,9 @@ function parseCommand(args) {
   for (const [name, key] of Object.entries(OPTION_KEYS)) {
     if (values[name] !== undefined) options[key] = NUMBER_KEYS.has(key) ? Number(values[name]) : values[name]
   }
+  if (options.audio !== undefined || options.audioOffset !== undefined) {
+    options.audio = { path: options.audio, offset: options.audioOffset }
+    delete options.audioOffset
+  }
   return { options }
 }

package/src/config.mjs

@@ -16,43 +16,77 @@ export function createConfig(options = {}) {
     width: options.viewportWidth ?? preset.viewport.width,
     height: options.viewportHeight ?? preset.viewport.height,
   }
+  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 readyTimeout = options.readyTimeout ?? 30
+  check(Number.isFinite(readyTimeout) && readyTimeout > 0, 'Ready timeout must be more than 0 seconds.')
+
+  return {
+    ...recordingConfig(options, viewport, preset),
+    url: options.url,
+    flow: resolve(options.flow),
+    storageState: options.storageState,
+    browser: options.browser ?? process.env.CHROME_PATH,
+    readyTimeout,
+  }
+}
+
+export function createPageConfig(options = {}) {
+  const { page } = options
+  check(typeof page?.viewportSize === 'function' && page.screencast, 'A Playwright Page with screencast support is required.')
+  check(!page.isClosed(), 'The supplied page is closed.')
+  const viewport = page.viewportSize()
+  check(viewport, 'recordPage requires a fixed viewport. Set it when creating the page or context; viewport: null is not supported.')
+  for (const key of ['url', 'browser', 'storageState', 'readyTimeout', 'viewportWidth', 'viewportHeight', 'preset']) {
+    check(options[key] === undefined, `recordPage does not accept ${key}; prepare the page before recording and use scale/fps for video settings.`)
+  }
+  return recordingConfig(options, viewport, { scale: 1, fps: 30 })
+}
+
+function recordingConfig(options, viewport, defaults) {
   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
+  const scale = options.scale ?? defaults.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,
+    fps: options.fps ?? defaults.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.')
   const flowTimeout = options.flowTimeout ?? 120
   check(Number.isFinite(flowTimeout) && flowTimeout > 0, 'Flow timeout must be more than 0 seconds.')
+  const runDirectory = options.runDirectory ? resolve(options.runDirectory) : undefined
 
   return {
-    url: options.url,
-    flow: resolve(options.flow),
     output,
-    storageState: options.storageState,
-    browser: options.browser ?? process.env.CHROME_PATH,
-    viewport,
+    audio: typeof options.audio === 'function' ? options.audio : createAudioConfig(options.audio, output, runDirectory),
+    viewport: { ...viewport },
     video,
     scale,
     postRoll,
-    readyTimeout,
     flowTimeout,
-    runDirectory: options.runDirectory ? resolve(options.runDirectory) : undefined,
+    runDirectory,
+  }
+}
+
+export function createAudioConfig(audio, output, directory) {
+  if (audio === undefined) return undefined
+  check(typeof audio?.path === 'string' && audio.path.length > 0, 'Audio must specify a local file path (--audio <path>, or audio: { path }).')
+  const path = resolve(audio.path)
+  check(path !== output, 'Audio input and video output must use different paths.')
+  if (directory) {
+    check(!['capture.webm', 'render.filter', 'failure.png'].some((name) => path === resolve(directory, name)), `Audio input must not use a reserved recording file: ${path}`)
   }
+  const offset = audio.offset ?? 0
+  check(Number.isFinite(offset), 'Audio offset must be a finite number of seconds.')
+  return { path, offset }
 }
 
 function check(valid, message) {

package/src/diagnostics.mjs

@@ -7,20 +7,22 @@ import { TraceframeError } from './errors.mjs'
 export async function addDiagnostics(error, { flow, ...details }) {
   if (!(error instanceof Error)) return error
   try {
-    const paths = new Set([flow, await realpath(flow).catch(() => flow)])
-    const names = [...paths].flatMap((path) => [path, pathToFileURL(path).href])
-    const escaped = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-    const location = new RegExp(`^\\s+at (?:async )?(?:.+ \\()?(${escaped.join('|')}):(\\d+):(\\d+)\\)?$`)
     const flowLocations = []
-    const seenErrors = new Set()
-    const seenLocations = new Set()
-    for (let current = error; current instanceof Error && !seenErrors.has(current); current = current.cause) {
-      seenErrors.add(current)
-      for (const frame of String(current.stack ?? '').split('\n')) {
-        const match = frame.match(location)
-        if (!match || seenLocations.has(`${match[2]}:${match[3]}`)) continue
-        seenLocations.add(`${match[2]}:${match[3]}`)
-        flowLocations.push({ file: flow, line: Number(match[2]), column: Number(match[3]) })
+    if (flow) {
+      const paths = new Set([flow, await realpath(flow).catch(() => flow)])
+      const names = [...paths].flatMap((path) => [path, pathToFileURL(path).href])
+      const escaped = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+      const location = new RegExp(`^\\s+at (?:async )?(?:.+ \\()?(${escaped.join('|')}):(\\d+):(\\d+)\\)?$`)
+      const seenErrors = new Set()
+      const seenLocations = new Set()
+      for (let current = error; current instanceof Error && !seenErrors.has(current); current = current.cause) {
+        seenErrors.add(current)
+        for (const frame of String(current.stack ?? '').split('\n')) {
+          const match = frame.match(location)
+          if (!match || seenLocations.has(`${match[2]}:${match[3]}`)) continue
+          seenLocations.add(`${match[2]}:${match[3]}`)
+          flowLocations.push({ file: flow, line: Number(match[2]), column: Number(match[3]) })
+        }
       }
     }
     error.diagnostics = { flowLocations, ...Object.fromEntries(Object.entries(details).filter(([, value]) => value !== undefined)) }

package/src/ffmpeg.mjs

@@ -1,11 +1,12 @@
 import { execFile } from 'node:child_process'
+import { stat } from 'node:fs/promises'
 import { promisify } from 'node:util'
 
 import { TraceframeError } from './errors.mjs'
 
 const execFileAsync = promisify(execFile)
 
-export async function probeFfmpeg() {
+export async function probeFfmpeg({ audio = false } = {}) {
   const version = await runCommand('ffmpeg', ['-version'])
   const major = parseFfmpegMajor(version.stdout)
   if (!(major >= 5)) {
@@ -15,12 +16,27 @@ export async function probeFfmpeg() {
   if (!codecs.stdout.includes('libx264')) {
     throw new TraceframeError('System FFmpeg does not provide the libx264 encoder.', { code: 'FFMPEG_UNSUPPORTED' })
   }
+  if (audio && !/^\s*A\S*\s+aac\s/m.test(codecs.stdout)) {
+    throw new TraceframeError('System FFmpeg does not provide the AAC encoder required for audio.', { 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 })
+export async function probeAudio(path, signal) {
+  try {
+    if (!(await stat(path)).isFile()) throw new Error('The input is not a regular file.')
+    const { stdout } = await runCommand('ffprobe', ['-v', 'error', '-select_streams', 'a:0', '-show_entries', 'stream=index', '-of', 'json', path], { signal })
+    const { streams } = JSON.parse(stdout)
+    if (!streams.length) throw new Error('The file has no audio stream.')
+  } catch (cause) {
+    signal?.throwIfAborted()
+    throw new TraceframeError(`Could not read audio from ${path}: ${cause.message}`, { code: 'AUDIO_INVALID', cause })
+  }
+}
+
+export async function probeVideoDuration(path, signal) {
+  const { stdout } = await runCommand('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=duration', '-of', 'csv=p=0', path], { signal })
   return Number(stdout)
 }
 

package/src/flow.mjs

@@ -22,11 +22,16 @@ export async function loadFlow(path, viewport) {
     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) }
+  return { ...createFlow(module.default, viewport, module.initialPointer), ready: module.ready }
+}
+
+export function createFlow(run, viewport, initialPointer) {
+  if (typeof run !== 'function') throw new TraceframeError('Flow must be a function.', { code: 'INVALID_FLOW' })
+  const { x, y } = 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 } }
+  return { run, initialPointer: { x, y } }
 }
 
 // Events are timed in seconds from `clock`, the epoch milliseconds of the first video frame.
@@ -35,6 +40,7 @@ export function createFlowApi({ page, trace, clock, viewport, signal }) {
   const sleep = (milliseconds) => delay(milliseconds, undefined, { signal })
 
   const movePointer = async (point, duration) => {
+    signal?.throwIfAborted()
     assertBelowLimit(trace.moves, LIMITS.maxMoves, 'move')
     const from = pointer
     const to = { x: point.x, y: point.y }
@@ -48,24 +54,25 @@ export function createFlowApi({ page, trace, clock, viewport, signal }) {
       await sleep(Math.min(MOVE_SAMPLE_MS, total - elapsed))
       elapsed = Math.min(total, performance.now() - startedAt)
       const eased = easeOutCubic(elapsed / total)
+      signal?.throwIfAborted()
       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 moveTo = async (locator, duration, name, handles) => {
     const seconds = durationSeconds(duration ?? MOVE_SECONDS, `${name} duration`)
-    const target = await findTarget(locator)
+    const target = await findTarget(locator, signal, handles)
     // A person does not chase a target that shifts under a pointer already on it.
     if (pointInsideBox(pointer, target.box)) return pointer
     let point = await aimPoint(target)
     if (!insideViewport(point, viewport)) {
-      const aim = await reveal(target.element, locator)
+      const aim = await reveal(target.element, locator, signal, handles)
       if (!aim.visible) throw new TraceframeError(`${locator} could not be revealed by scrolling.`, { code: 'FLOW_TARGET_OUTSIDE_VIEWPORT' })
       point = aim.point
     }
     await movePointer(point, seconds)
-    const after = await locator.boundingBox()
+    const after = await locator.boundingBox({ signal })
     if (!after || !pointInsideBox(point, after)) {
       throw new TraceframeError(`${locator} moved while the pointer was arriving.`, { code: 'FLOW_TARGET_MOVED' })
     }
@@ -73,21 +80,23 @@ export function createFlowApi({ page, trace, clock, viewport, signal }) {
   }
 
   return {
-    async hover(locator, options = {}) {
-      await moveTo(locator, options.duration, 'hover')
-    },
-    async click(locator, options = {}) {
+    hover: withHandles(async (handles, locator, options = {}) => {
+      await moveTo(locator, options.duration, 'hover', handles)
+    }),
+    click: withHandles(async (handles, 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')
+      const point = await moveTo(locator, options.duration, 'click', handles)
       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) => {
+      const element = await locator.elementHandle({ signal })
+      handles.push(element)
+      await element.waitForElementState('enabled', { signal }).catch((error) => {
         throw error.name === 'TimeoutError' ? new TraceframeError(`${locator} stayed disabled.`, { code: 'FLOW_TARGET_DISABLED', cause: error }) : error
       })
-      await assertReceivesPointer(element, locator, point)
+      await assertReceivesPointer(element, locator, point, handles)
       const at = secondsSince(clock)
+      signal?.throwIfAborted()
       await page.mouse.down()
       try {
         await sleep(PRESS_HOLD_MS)
@@ -101,23 +110,35 @@ export function createFlowApi({ page, trace, clock, viewport, signal }) {
         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 scroll(locator) {
-      const { shown } = await reveal((await findTarget(locator)).element, locator)
+    scroll: withHandles(async (handles, locator) => {
+      const { shown } = await reveal((await findTarget(locator, signal, handles)).element, locator, signal, handles)
       if (!shown) throw new TraceframeError(`${locator} could not be revealed by scrolling.`, { code: 'FLOW_TARGET_OUTSIDE_VIEWPORT' })
-    },
+    }),
     async wait(seconds) {
       await sleep(durationSeconds(seconds, 'wait', { allowZero: true }) * 1000)
     },
   }
 }
 
+// A helper may outlive a cancelled recording; release its handles when that helper actually settles.
+function withHandles(run) {
+  return async (...args) => {
+    const handles = []
+    try {
+      return await run(handles, ...args)
+    } finally {
+      await Promise.all(handles.map(handle => handle.dispose().catch(() => {})))
+    }
+  }
+}
+
 function insideViewport(point, viewport) {
   return point?.x >= 0 && point?.y >= 0 && point.x <= viewport.width && point.y <= viewport.height
 }
@@ -145,9 +166,10 @@ function assertBelowLimit(events, limit, type) {
   }
 }
 
-async function findTarget(locator) {
-  await locator.waitFor()
-  const element = await locator.elementHandle()
+async function findTarget(locator, signal, handles) {
+  await locator.waitFor({ signal })
+  const element = await locator.elementHandle({ signal })
+  handles.push(element)
   const box = await element.boundingBox()
   if (!box) throw new TraceframeError(`Could not find ${locator}.`, { code: 'FLOW_TARGET_MISSING' })
   return { element, box }
@@ -168,10 +190,10 @@ async function aimPoint({ element, box }) {
   return { x: box.x + offset.x * box.width, y: box.y + offset.y * box.height }
 }
 
-async function reveal(element, locator) {
+async function reveal(element, locator, signal, handles) {
   // Content that loads above the target during the scroll can push it out again.
   for (let attempt = 0; attempt < 2; attempt++) {
-    const target = await scrollIntoView(element, locator)
+    const target = await scrollIntoView(element, locator, signal, handles)
     const point = await aimPoint(target)
     const visibility = await target.element.evaluate((node, offset) => new Promise((resolve) => {
       new IntersectionObserver(([entry], observer) => {
@@ -191,10 +213,11 @@ async function reveal(element, locator) {
 
 // Awaiting the scroll waits for a scrolling panel. Chromium resolves a page scroll before it stops, and a sticky target
 // or iframe can stay put while its page scrolls, so also wait for every enclosing page to stop.
-async function scrollIntoView(element, locator) {
+async function scrollIntoView(element, locator, signal, handles) {
+  signal?.throwIfAborted()
   await element.evaluate((target) => target.scrollIntoView({ behavior: 'smooth', block: 'center' }))
   try {
-    await element.waitForElementState('stable')
+    await element.waitForElementState('stable', { signal })
     let frame = await element.ownerFrame()
     while (frame) {
       await frame.evaluate(() => new Promise((resolve) => {
@@ -208,14 +231,16 @@ async function scrollIntoView(element, locator) {
         requestAnimationFrame(check)
       }))
       if (!frame.parentFrame()) break
-      await (await frame.frameElement()).waitForElementState('stable')
+      const frameElement = await frame.frameElement()
+      handles.push(frameElement)
+      await frameElement.waitForElementState('stable', { signal })
       frame = frame.parentFrame()
     }
     // The page may replace the target while it scrolls, or remove or hide it, as a menu that closes on scroll does.
-    const target = await findTarget(locator).catch((error) => {
+    const target = await findTarget(locator, signal, handles).catch((error) => {
       throw error.name === 'TimeoutError' ? new TraceframeError(`${locator} disappeared when it was scrolled into view.`, { code: 'FLOW_TARGET_MISSING', cause: error }) : error
     })
-    await target.element.waitForElementState('stable')
+    await target.element.waitForElementState('stable', { signal })
     const box = await target.element.boundingBox()
     if (!box) throw new TraceframeError(`Could not find ${locator}.`, { code: 'FLOW_TARGET_MISSING' })
     return { element: target.element, box }
@@ -224,7 +249,7 @@ async function scrollIntoView(element, locator) {
   }
 }
 
-async function assertReceivesPointer(element, locator, point) {
+async function assertReceivesPointer(element, locator, point, handles) {
   const box = await element.boundingBox()
   if (!box || !pointInsideBox(point, box)) {
     throw new TraceframeError(`${locator} moved before the click.`, { code: 'FLOW_TARGET_MOVED' })
@@ -238,15 +263,16 @@ async function assertReceivesPointer(element, locator, point) {
     }
     return false
   }, relativePoint(point, box))
-  if (!receivesPointer || !(await framesReceivePointer(element, point))) {
+  if (!receivesPointer || !(await framesReceivePointer(element, point, handles))) {
     throw new TraceframeError(`${locator} is covered at the click point. If a dialog or toast covers it, wait until it closes; if a panel clips it or a sticky header or bar covers it, call scroll() on the target first.`, { code: 'FLOW_TARGET_OBSCURED' })
   }
 }
 
-async function framesReceivePointer(element, point) {
+async function framesReceivePointer(element, point, handles) {
   let frame = await element.ownerFrame()
   while (frame?.parentFrame()) {
     const frameElement = await frame.frameElement()
+    handles.push(frameElement)
     const box = await frameElement.boundingBox()
     if (!box) return false
     const hit = await frameElement.evaluate((target, { x, y }) => {

package/src/index.mjs

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

package/src/record.mjs

@@ -2,21 +2,45 @@ 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 { createAudioConfig, createConfig, createPageConfig } from './config.mjs'
 import { captureFlow } from './capture.mjs'
 import { addDiagnostics, retainedFile } from './diagnostics.mjs'
-import { probeFfmpeg } from './ffmpeg.mjs'
-import { loadFlow } from './flow.mjs'
+import { probeAudio, probeFfmpeg } from './ffmpeg.mjs'
+import { createFlow, loadFlow } from './flow.mjs'
 import { renderVideo } from './render.mjs'
+import { TraceframeError } from './errors.mjs'
+
+const activePages = new WeakSet()
 
 export async function record(options = {}) {
   const { signal } = options
   signal?.throwIfAborted()
   const config = createConfig(options)
-  const ffmpeg = await probeFfmpeg()
+  const ffmpeg = await probeFfmpeg({ audio: Boolean(config.audio) })
   const flow = await loadFlow(config.flow, config.viewport).catch(async (error) => {
     throw await addDiagnostics(error, { flow: config.flow })
   })
+  return recordFlow({ config, flow, ffmpeg, signal })
+}
+
+export async function recordPage(options = {}) {
+  const { page, signal } = options
+  signal?.throwIfAborted()
+  const config = createPageConfig(options)
+  const flow = createFlow(options.flow, config.viewport, options.initialPointer)
+  if (activePages.has(page)) throw new TraceframeError('This page is already being recorded by Traceframe.', { code: 'PAGE_RECORDING_ACTIVE' })
+  activePages.add(page)
+  try {
+    const ffmpeg = await probeFfmpeg({ audio: Boolean(config.audio) })
+    return await recordFlow({ config, flow, ffmpeg, signal, page })
+  } finally {
+    activePages.delete(page)
+  }
+}
+
+async function recordFlow({ config, flow, ffmpeg, signal, page }) {
+  let audio = typeof config.audio === 'function' ? undefined : config.audio
+  if (audio) await probeAudio(audio.path, signal)
   await mkdir(dirname(config.output), { recursive: true })
   const directory = config.runDirectory ?? await mkdtemp(join(tmpdir(), 'traceframe-'))
   await mkdir(directory, { recursive: true })
@@ -24,9 +48,15 @@ export async function record(options = {}) {
   let capture
   let failed = false
   try {
-    capture = await captureFlow({ config, flow, directory, signal })
+    capture = await captureFlow({ config, flow, directory, signal, page })
     const { rawPath, trace } = capture
-    const duration = await renderVideo({ rawPath, trace, directory, config, ffmpeg, signal })
+    if (typeof config.audio === 'function') {
+      signal?.throwIfAborted()
+      audio = createAudioConfig(await config.audio({ startedAt: capture.startedAt, signal }), config.output, directory)
+      if (!audio) throw new TraceframeError('The audio function must return { path, offset }.', { code: 'INVALID_CONFIG' })
+      await probeAudio(audio.path, signal)
+    }
+    const duration = await renderVideo({ rawPath, trace, directory, config, ffmpeg, signal, audio })
     return {
       output: config.output,
       width: config.video.width,
@@ -36,6 +66,7 @@ export async function record(options = {}) {
       moveCount: trace.moves.length,
       clickCount: trace.clicks.length,
       runDirectory: config.runDirectory,
+      ...(audio ? { audio: true } : {}),
     }
   } catch (error) {
     failed = true

package/src/render.mjs

@@ -2,7 +2,7 @@ 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 { probeVideoDuration, runCommand } from './ffmpeg.mjs'
 import { TraceframeError } from './errors.mjs'
 
 const ASSETS = join(import.meta.dirname, 'assets')
@@ -13,11 +13,14 @@ const CLICK = { duration: 0.24, scaleStart: 0.7, scaleEnd: 1.25 }
 // 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 }) {
+export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, signal, audio }) {
   const { fps } = config.video
   const outputDuration = Math.max(trace.end + config.postRoll, ...trace.clicks.map((click) => click.at + CLICK.duration))
+  if (audio && audio.offset >= outputDuration) {
+    throw new TraceframeError(`Audio offset ${audio.offset} seconds starts at or after the video's end (${number(outputDuration)} seconds). Reduce its offset.`, { code: 'AUDIO_OUTSIDE_VIDEO' })
+  }
   const filterPath = join(directory, 'render.filter')
-  await writeFile(filterPath, buildFilterScript({ trace, scale: config.scale }))
+  await writeFile(filterPath, buildFilterScript({ trace, scale: config.scale, audio }))
   const outputTemp = join(dirname(config.output), `.traceframe-${randomUUID()}.tmp.mp4`)
   const args = [
     '-y', '-hide_banner', '-loglevel', 'error',
@@ -25,9 +28,13 @@ export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, s
     '-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`))
+  if (audio) args.push('-i', audio.path)
   args.push(
     ffmpeg.filterComplexFileOption, filterPath,
     '-map', '[final]',
+  )
+  if (audio) args.push('-map', '[finalAudio]', '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2')
+  args.push(
     '-t', String(number(outputDuration)),
     '-r', String(fps),
     '-c:v', 'libx264', '-preset', 'fast', '-crf', '18',
@@ -37,7 +44,7 @@ export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, s
   )
   try {
     await runCommand('ffmpeg', args, { signal })
-    const duration = await probeDuration(outputTemp, signal)
+    const duration = await probeVideoDuration(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' })
     }
@@ -51,7 +58,7 @@ export async function renderVideo({ rawPath, trace, directory, config, ffmpeg, s
 }
 
 // Event times are seconds from the first frame of the raw video.
-export function buildFilterScript({ trace, scale }) {
+export function buildFilterScript({ trace, scale, audio }) {
   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]`]
@@ -75,6 +82,13 @@ export function buildFilterScript({ trace, scale }) {
     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]`)
+  if (audio) {
+    const input = clicks.length ? 3 : 2
+    const trim = number(Math.max(0, -audio.offset))
+    const delay = number(Math.max(0, audio.offset) * 1000)
+    // Reset the selected stream before trimming: its first sample may start after the container's video.
+    filters.push(`[${input}:a:0]asetpts=PTS-STARTPTS,atrim=start=${trim},asetpts=PTS-STARTPTS,adelay=${delay}:all=1,apad[finalAudio]`)
+  }
   return filters.join(';')
 }