@milkstraw/traceframe 0.3.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,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,57 @@ 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`, `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 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,7 @@ 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).
 
 ## Edit the finished video
 

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.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

@@ -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 }) }),
@@ -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/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

@@ -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/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,12 +2,15 @@ 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
@@ -17,6 +20,25 @@ export async function record(options = {}) {
   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 })
@@ -24,7 +46,7 @@ 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 })
     return {