@milkstraw/traceframe 0.2.0 → 0.4.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.
 
+Recordings are silent; audio is not captured.
+
 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,13 +53,15 @@ 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.
 
 The cursor and click pulses are always drawn at the full frame rate. Chromium may capture page changes, such as scrolling and animations, at a lower rate at 2560×1600, depending on the machine. The video repeats the last page frame until the next one arrives.
 
-Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and FFmpeg filter file, including a partial capture if the flow fails during recording. Keep that directory out of Git, because the raw capture shows everything the page showed.
+Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and FFmpeg filter file, including a partial capture if the flow fails during recording. On a preparation or recording failure, Traceframe also tries to save a viewport screenshot as `failure.png`. Keep that directory out of Git, because captures and screenshots can contain private page data.
+
+When available, failure output includes the error code, flow-file locations, elapsed recording time, and paths to artifacts saved for that attempt. Without `--run-dir`, temporary captures are removed and no failure screenshot is saved. See [diagnosing a failed take](docs/recording-flows.md#diagnose-a-failed-take).
 
 ## Write a flow
 
@@ -143,9 +147,59 @@ await record({
 })
 ```
 
-Traceframe's own errors are `TraceframeError` instances (exported by the package) with a `code`, such as `READY_FAILED` or `FLOW_TARGET_OBSCURED`.
+### 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`, `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.
+
+### 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 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 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.
 
-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.
+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.
 
 ## Sample output
 

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
 
@@ -58,6 +99,42 @@ Before a follow-up, wait for the application to show that the current step is co
 
 Set a Playwright timeout explicitly when an individual operation may exceed its usual 30 seconds, such as `await newReply.waitFor({ timeout: 60_000 })`. Use Traceframe's `wait(seconds)` for reading time. Each helper wait is limited to 30 seconds, and the whole flow has a 120-second timeout that `--flow-timeout` (`flowTimeout` in the API) raises.
 
+## Add captions and reading time
+
+For a review video, explain what the viewer should notice. Show the caption, pause before moving the pointer, perform the action, then hold the result. Start with about 12 characters per second and a 2.5-second minimum for reading, followed by a 2.5–4 second result hold.
+
+Use Playwright's [`page.screencast.showOverlay()`](https://playwright.dev/docs/api/class-screencast#screencast-show-overlay) inside the flow. Keep the caption compact, centered, and clear of the controls and results being shown. Traceframe's covered-click check ignores this pointer-transparent caption; use `top: 32px` instead of `bottom: 32px` when it would hide controls or results near the bottom. Keep its handle and dispose of it after the result hold:
+
+```js
+const text = 'Open Actions to inspect the available options.'
+const caption = await page.screencast.showOverlay(`
+  <div style="position: fixed; left: 24px; right: 24px; bottom: 32px;
+    display: flex; justify-content: center; pointer-events: none;">
+    <div dir="auto" style="max-width: 720px; padding: 12px 20px; border-radius: 10px;
+      background: #18181b; color: #fff;
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.16);
+      font: 500 20px/1.45 system-ui, sans-serif;
+      text-align: center; text-wrap: balance;">
+      ${text}
+    </div>
+  </div>
+`)
+try {
+  await wait(Math.max(2.5, Array.from(text).length / 12))
+  await click(page.getByRole('button', { name: 'Actions', exact: true }))
+  await page.getByRole('menu').waitFor()
+  await wait(3)
+} finally {
+  await caption.dispose()
+}
+```
+
+Omit `duration` when actions should happen while the caption is visible. Playwright uses milliseconds for `duration`: awaiting `showOverlay(html, { duration: 3000 })` waits until the overlay is removed. The example uses fixed text; escape dynamic text before inserting it into HTML.
+
+Playwright restores overlays after a full-page navigation, but they can briefly disappear while the new document loads. Opening a native modal `<dialog>` can also briefly cover an existing caption. For a clean caption transition, finish the reading pause and dispose of the current caption before the action that navigates or opens the dialog, then show the next caption after the destination or dialog is ready.
+
+Keep captions short. Split longer text into separate captions so each reading pause stays within the helper's 30-second limit. Reading pauses and result holds count toward the flow timeout; for a longer video, raise it with, for example, `--flow-timeout 240` (seconds).
+
 ## Optional startup settings
 
 `page.emulateMedia({ colorScheme: 'dark' })` in `ready` updates CSS themes that follow the browser's color scheme. If the app reads the setting only at startup, set it before opening the app, as below.
@@ -83,14 +160,54 @@ The two `Emulation` calls set the locale that `navigator.language`, `Intl`, and
 
 Use `--preset draft` while writing the flow and the default preset for the final video.
 
-While writing the flow, pass `--run-dir` with an ignored folder, such as `.traceframe/runs/demo`. A failed take then keeps its partial `capture.webm`, which has no cursor overlay and stops where the flow failed.
+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:
+
+```text
+traceframe: [FLOW_FAILED] Expected the Saved status.
+  Flow: /project/review.mjs:18:9
+  Recording time: 12.35 s
+  Capture: /project/.traceframe/runs/demo/capture.webm
+  Screenshot: /project/.traceframe/runs/demo/failure.png
+```
+
+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#errors-and-cancellation).
+
 ## Edit the finished video
 
 Edit the finished MP4 with FFmpeg rather than changing the flow. Editing finished frames keeps the page and cursor together. Keep the original, and say when a clip's pacing was edited.

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.2.0",
+  "version": "0.4.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

@@ -1,51 +1,139 @@
 import { addAbortListener } from 'node:events'
+import { writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { setTimeout as delay } from 'node:timers/promises'
 import { chromium } from 'playwright'
 
 import { TraceframeError } from './errors.mjs'
+import { addDiagnostics, retainedFile } from './diagnostics.mjs'
 import { createFlowApi } from './flow.mjs'
 
 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))
-    const clock = await withDeadline(
+    signal.throwIfAborted()
+    await startScreencast(page, rawPath, config, firstFrame.resolve)
+    recording = true
+    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,
     )
-    await withDeadline(
-      (flowSignal) => flow.run({ page, signal: flowSignal, ...createFlowApi({ page, trace, clock, viewport: config.viewport, signal: flowSignal }) }),
-      config.flowTimeout * 1000,
-      new TraceframeError(`Flow exceeded the ${config.flowTimeout}-second flow timeout. Raise it with the flowTimeout option, or --flow-timeout.`, { code: 'FLOW_TOO_LONG' }),
-      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 }) }),
+        config.flowTimeout * 1000,
+        new TraceframeError(`Flow exceeded the ${config.flowTimeout}-second flow timeout. Raise it with the flowTimeout option, or --flow-timeout.`, { code: 'FLOW_TOO_LONG' }),
+        signal,
+      )
+    } catch (error) {
+      if (signal.aborted || error instanceof TraceframeError) throw error
+      throw new TraceframeError(error instanceof Error ? error.message : String(error), { code: 'FLOW_FAILED', cause: error })
+    }
     trace.end = (Date.now() - clock) / 1000
     await delay(config.postRoll * 1000, undefined, { signal })
+    // 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 }
   } 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
+    failed = true
+    const recordingTime = clock === undefined ? undefined : Math.max(0, (Date.now() - clock) / 1000)
+    // Let the encoder finish saving before closing the browser, including on slower machines.
+    const [capturePath, screenshotPath] = await Promise.all([
+      recording ? page.screencast.stop()
+        .then(() => config.runDirectory ? retainedFile(rawPath) : undefined)
+        .catch(() => undefined) : undefined,
+      config.runDirectory && page && !signal.aborted ? saveFailureScreenshot(page, directory, signal) : undefined,
+    ])
+    if (signal.aborted) throw error
+    throw await addDiagnostics(error, { flow: config.flow, recordingTime, capturePath, screenshotPath })
   } finally {
-    await browser.close()
+    // A shutdown error must not hide the flow failure.
+    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
+  }
+}
+
+async function saveFailureScreenshot(page, directory, signal) {
+  try {
+    return await withDeadline(async (diagnosticSignal) => {
+      const screenshot = await page.screenshot({ timeout: FAILURE_SCREENSHOT_TIMEOUT })
+      diagnosticSignal.throwIfAborted()
+      const path = join(directory, 'failure.png')
+      await writeFile(path, screenshot, { signal: diagnosticSignal })
+      return path
+    }, FAILURE_SCREENSHOT_TIMEOUT, new Error('Failure screenshot timed out.'), signal)
+  } catch {
+    return undefined
   }
 }
 
@@ -84,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 })
   }
 }
@@ -94,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

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module'
 import { parseArgs } from 'node:util'
 
 import { LIMITS } from './flow.mjs'
+import { formatFailure } from './diagnostics.mjs'
 import { record } from './record.mjs'
 
 const { version: VERSION } = createRequire(import.meta.url)('../package.json')
@@ -44,7 +45,7 @@ Options:
   --post-roll <seconds>        Tail after the flow (default: 0.3)
   --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 and FFmpeg filter in this directory
+  --run-dir <path>             Keep the raw capture, failure screenshot and FFmpeg filter
   -h, --help                   Show this help
   -v, --version                Show the version
 
@@ -74,7 +75,7 @@ try {
     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.stderr.write(formatFailure(error))
     process.exitCode = 1
   }
 }

package/src/config.mjs

@@ -16,40 +16,59 @@ 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.')
 
   return {
-    url: options.url,
-    flow: resolve(options.flow),
     output,
-    storageState: options.storageState,
-    browser: options.browser ?? process.env.CHROME_PATH,
-    viewport,
+    viewport: { ...viewport },
     video,
     scale,
     postRoll,
-    readyTimeout,
     flowTimeout,
     runDirectory: options.runDirectory ? resolve(options.runDirectory) : undefined,
   }

package/src/diagnostics.mjs

@@ -0,0 +1,52 @@
+import { realpath, stat } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+
+import { TraceframeError } from './errors.mjs'
+
+// Only report the supplied flow's locations, never the rest of a stack or error object.
+export async function addDiagnostics(error, { flow, ...details }) {
+  if (!(error instanceof Error)) return error
+  try {
+    const flowLocations = []
+    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)) }
+  } catch {
+    // A frozen error or an unavailable stack must not replace the original failure.
+  }
+  return error
+}
+
+export async function retainedFile(path) {
+  const info = await stat(path).catch(() => undefined)
+  return info?.isFile() && info.size > 0 ? path : undefined
+}
+
+export function formatFailure(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = error instanceof TraceframeError && error.code ? `[${error.code}] ` : ''
+  const lines = [`traceframe: ${code}${message.trimEnd()}`]
+  const diagnostics = error?.diagnostics
+  for (const { file, line, column } of diagnostics?.flowLocations ?? []) {
+    lines.push(`  Flow: ${file}:${line}:${column}`)
+  }
+  if (Number.isFinite(diagnostics?.recordingTime)) lines.push(`  Recording time: ${diagnostics.recordingTime.toFixed(2)} s`)
+  if (diagnostics?.capturePath) lines.push(`  Capture: ${diagnostics.capturePath}`)
+  if (diagnostics?.screenshotPath) lines.push(`  Screenshot: ${diagnostics.screenshotPath}`)
+  return `${lines.join('\n')}\n`
+}

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,24 +2,52 @@ 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 { 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 { 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 flow = await loadFlow(config.flow, config.viewport)
+  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()
+    return await recordFlow({ config, flow, ffmpeg, signal, page })
+  } finally {
+    activePages.delete(page)
+  }
+}
+
+async function recordFlow({ config, flow, ffmpeg, signal, page }) {
   await mkdir(dirname(config.output), { recursive: true })
   const directory = config.runDirectory ?? await mkdtemp(join(tmpdir(), 'traceframe-'))
   await mkdir(directory, { recursive: true })
 
+  let capture
+  let failed = false
   try {
-    const { rawPath, trace } = 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 })
     return {
       output: config.output,
@@ -32,8 +60,17 @@ export async function record(options = {}) {
       runDirectory: config.runDirectory,
     }
   } catch (error) {
+    failed = true
+    if (signal?.aborted) throw signal.reason
+    if (capture && config.runDirectory) {
+      await addDiagnostics(error, { flow: config.flow, capturePath: await retainedFile(capture.rawPath) })
+    }
     throw signal?.aborted ? signal.reason : error
   } finally {
-    if (!config.runDirectory) await rm(directory, { recursive: true, force: true })
+    if (!config.runDirectory) {
+      const cleanup = rm(directory, { recursive: true, force: true })
+      if (failed) await cleanup.catch(() => {})
+      else await cleanup
+    }
   }
 }