@milkstraw/traceframe 0.0.0-stage → 0.2.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# Traceframe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Traceframe records a scripted Chromium flow and renders an MP4 with a smooth cursor and click pulse. Everything runs locally: pages, flows, videos, and authentication state stay on your machine.
+
+https://github.com/user-attachments/assets/38e02cd5-a9ba-4f3c-938c-159955353141
+
+## Prerequisites
+
+Traceframe requires Node.js 22+ and system FFmpeg 5+ with `libx264` and `ffprobe` to render the MP4 (for example, `brew install ffmpeg` or `sudo apt install ffmpeg`). Playwright uses its own Chromium and FFmpeg builds to record the page. Install them with the exact Playwright version Traceframe uses; other cached versions are not used:
+
+```sh
+npx playwright@1.64.1 install --only-shell chromium ffmpeg
+```
+
+To use system Chrome 150 or later, pass `--browser` or set `CHROME_PATH`, and install Playwright's recording FFmpeg with `npx playwright@1.64.1 install ffmpeg`. Older Chrome versions can fail to scroll targets inside panels.
+
+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.
+
+## Record a video
+
+Run Traceframe with `npx` without adding it to your project's dependencies. Pass your application URL and your own [flow file](#write-a-flow):
+
+```sh
+npx @milkstraw/traceframe record \
+  --url http://localhost:3000 \
+  --flow ./flow.mjs \
+  --out ./recording.mp4
+```
+
+For regular use, you can install the command globally:
+
+```sh
+npm install -g @milkstraw/traceframe
+traceframe record --url http://localhost:3000 --flow ./flow.mjs --out ./recording.mp4
+```
+
+To check installation before touching your application, save this as `smoke.mjs`:
+
+```js
+export default async function ({ wait }) {
+  await wait(0.2)
+}
+```
+
+```sh
+npx @milkstraw/traceframe record \
+  --url 'data:text/html,<h1>Traceframe smoke</h1>' \
+  --flow ./smoke.mjs --out ./smoke.mp4 \
+  --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.
+
+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.
+
+## Write a flow
+
+The flow module exports a default function. Timing values are seconds:
+
+```js
+export async function ready({ page }) {
+  await page.getByRole('heading', { name: 'Example workspace' }).waitFor()
+}
+
+export default async function ({ page, click, wait }) {
+  await click(page.getByRole('button', { name: 'Open settings' }), { duration: 0.8 })
+  await wait(1)
+}
+```
+
+The optional `ready({ page, signal })` hook runs after initial navigation and before recording starts. Export `initialPointer = { x, y }` to choose where the cursor starts; by default it starts near the lower left.
+
+### Helpers
+
+The default function receives a Playwright `page`, an `AbortSignal` named `signal`, and five helpers:
+
+| Helper | Use |
+| --- | --- |
+| `move({ x, y }, { duration })` | Move the pointer to viewport coordinates. |
+| `hover(locator, { duration })` | Move the pointer to a locator. |
+| `click(locator, { duration, dwell })` | Move, pause, and click a locator. |
+| `scroll(locator)` | Center a target without moving the pointer. |
+| `wait(seconds)` | Pause for reading time. |
+
+A move takes 0.5 seconds by default. A click pauses on the target for 0.25 seconds (`dwell`) before pressing, and waits for a disabled target to become enabled. `click` and `hover` leave the pointer in place if it is already inside the target's box.
+
+Error messages name the locator; give it a clearer name with Playwright's `locator.describe('Save settings')`.
+
+### Scrolling
+
+`click` and `hover` scroll automatically only when their aim point starts outside the viewport. They scroll smoothly through the page, scrollable containers, and iframes, and wait for scrolling to stop before moving the pointer.
+
+`scroll(target)` smoothly centers the target vertically, even if it is already visible, and waits for scrolling to stop without moving the pointer. Use it to show a result or before clicking a target clipped by a scrollable panel or covered by a sticky header. Wait for a dialog or toast to close instead.
+
+Centering can leave a target partly visible or covered, for example by a sticky bar taller than half the height of the viewport or its scrolling panel. It cannot reveal content hidden by `overflow: clip`. `click` fails with `FLOW_TARGET_OBSCURED` if the target is still covered when it presses.
+
+### Timing and limits
+
+`--ready-timeout` (default: 30 seconds) sets Playwright's default timeout during initial navigation and `ready`, for operations that accept a timeout. It does not set a deadline for the whole hook.
+
+The default function may run for 120 seconds, including waits for your backend. For longer flows, pass `--flow-timeout 300` (`flowTimeout: 300` in the API). This does not change Playwright's action timeouts. Helper calls stop promptly when the flow timeout is reached.
+
+A flow may contain at most 100 moves and 100 clicks, and each `duration`, `dwell`, and `wait` is at most 30 seconds.
+
+### What appears in the video
+
+Playwright typing and scrolling appear in the captured page. Direct `page.mouse`, `locator.click()`, and dragging calls bypass Traceframe's cursor trace and click pulses, so use its pointer helpers for visible interactions. Only the starting page is recorded; new tabs and popups do not appear in the video.
+
+### Have an agent create the flow
+
+You can ask a coding agent to inspect your running UI and write the flow from a journey:
+
+```text
+Create a Traceframe flow for this user journey: open Settings, change the theme, and save it.
+Follow the Traceframe recording guide: https://github.com/milkstrawai/traceframe/blob/main/docs/recording-flows.md
+Inspect the running application, use stable role or test-id locators, add a ready hook,
+and use Traceframe's click, hover, move, scroll, and wait helpers for visible interactions.
+Write the result to flow.mjs and explain how to run it.
+```
+
+## Programmatic usage
+
+To call Traceframe from JavaScript, install it in your project:
+
+```sh
+npm install @milkstraw/traceframe
+```
+
+```js
+import { record } from '@milkstraw/traceframe'
+
+await record({
+  url: 'http://localhost:3000',
+  flow: './flow.mjs',
+  output: './recording.mp4',
+  preset: 'standard',
+})
+```
+
+Traceframe's own errors are `TraceframeError` instances (exported by the package) with a `code`, such as `READY_FAILED` or `FLOW_TARGET_OBSCURED`.
+
+Pass `signal` to stop a recording early. Traceframe closes the browser, stops FFmpeg, and removes its temporary files before rejecting with the signal's reason. When you pass a signal, Traceframe leaves Ctrl-C and other termination signals to you. The CLI does this for you: the first Ctrl-C stops and cleans up, and a second one exits at once.
+
+## Sample output
+
+The committed sample is generated from the [repository's fixture flow](examples/fixture-flow.mjs) with the `standard` preset (2560×1600 at 60 FPS) and is about 12 seconds long:
+
+[Download the sample video](https://github.com/milkstrawai/traceframe/blob/main/examples/sample-output.mp4)
+
+The cursor and click-pulse artwork and the fixture page's icons were made for Traceframe and are distributed under this repository's MIT license.
+
+The fixture page uses the [Inter](https://github.com/rsms/inter) font, included under the SIL Open Font License in `examples/fonts/OFL.txt`.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm run test:smoke
+TRACEFRAME_PRESET=standard npm run test:smoke
+npm run test:package
+```
+
+To release, set the version in `package.json` and `package-lock.json`, push all release changes to `main`, and publish a GitHub Release with the tag `v<version>` on the final tested commit containing those changes. The Release workflow reruns CI and stages the package on npm. A maintainer downloads it with `npm stage download <stage-id>`, checks that its files match `npm pack` at the tag, and approves it on npmjs.com with 2FA.
+
+After editing an SVG in `src/assets`, run `npm run build:assets` to rebuild its 1× and 2× PNGs.
+
+To re-record the committed sample:
+
+```sh
+npx traceframe record --url "file://$PWD/examples/fixture.html" --flow ./examples/fixture-flow.mjs --out ./examples/sample-output.mp4
+```

package/docs/recording-flows.md

@@ -0,0 +1,123 @@
+# Write a recording flow
+
+Use this guide yourself or give it to a coding agent with the journey you want to show. Traceframe provides pointer and scrolling helpers; the supplied Playwright page handles typing, file selection, and application checks.
+
+## Run the example
+
+The package includes [a complete flow](../examples/recipes-flow.mjs) and [its local page](../examples/recipes.html). It types English and Arabic, waits for two simulated replies, selects a fake file, and clicks a final action in a panel below the fold, which `click` scrolls into view first. After a global installation and the [prerequisites](../README.md#prerequisites), run:
+
+```sh
+TRACEFRAME_EXAMPLES="$(npm root -g)/@milkstraw/traceframe/examples"
+traceframe record \
+  --url "file://$TRACEFRAME_EXAMPLES/recipes.html" \
+  --flow "$TRACEFRAME_EXAMPLES/recipes-flow.mjs" \
+  --preset draft --out ./recipes.mp4
+```
+
+In a repository clone, run `npx traceframe record --url "file://$PWD/examples/recipes.html" --flow ./examples/recipes-flow.mjs --preset draft --out ./recipes.mp4` instead. These shell commands use macOS/Linux path syntax. The flow itself has no application dependencies, external services, or credentials.
+
+## Prepare the journey
+
+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).
+
+## Choose the right actions
+
+Use Traceframe's `click`, `hover`, and `move` for visible pointer actions. Direct `locator.click()` and `page.mouse` calls move the browser pointer without updating Traceframe's overlay or click pulses. Use Playwright for the other actions below; their page changes appear in the video.
+
+For a target clipped by a scrollable panel or covered by a sticky header, try `await scroll(target)` before the click. For a tooltip, a toast, or a closing dialog, wait until it is gone, or give the click a longer `dwell`. A covered click fails with an error that it "is covered at the click point" (`FLOW_TARGET_OBSCURED`); `hover` does not check for covers. See the [scrolling rules and limits](../README.md#scrolling).
+
+Both automatic scrolling and `scroll(target)` can move the outer page, which closes some lists. For those lists, use their own scrolling container through Playwright, for example `await list.evaluate((element) => element.scrollTo({ top: element.scrollHeight, behavior: 'smooth' }))` to show the final options, then click the option. Wait for any opening animation before scrolling.
+
+To show a result without a pointer action, use `await scroll(result)`. Centering a result taller than the view hides its start, so scroll to its heading or another element near its start instead.
+
+Focus a field visibly, then type with a delay in milliseconds:
+
+```js
+await click(message)
+await message.pressSequentially('A short question', { delay: 45 })
+```
+
+For an upload, hover the visible control, set the actual file input, and wait for the application's selected-file feedback. The visible label or drop zone and the input are often different elements:
+
+```js
+const dropZone = page.getByText('Choose a file', { exact: true })
+const fileInput = page.getByLabel('Choose a file')
+await hover(dropZone)
+await fileInput.setInputFiles('./sample.txt')
+await page.getByText('sample.txt').waitFor()
+await wait(0.6)
+```
+
+A relative path is resolved from the directory where you run Traceframe. File selection does not show an operating-system file picker. The complete example supplies an in-memory fake file so it can run on its own.
+
+## Wait for the current result
+
+Before a follow-up, wait for the application to show that the current step is complete. For a conversation that appends completed replies, the example waits for the next reply by index. For streamed answers, wait for that request's completion indicator instead; the first visible text or a previous reply is not completion.
+
+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.
+
+## 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.
+
+If the application needs request headers, a browser locale, or a color scheme from startup, record `--url about:blank` and open the application yourself in `ready`. Keep only the lines you need:
+
+```js
+export async function ready({ page }) {
+  await page.emulateMedia({ colorScheme: 'dark' })
+  await page.setExtraHTTPHeaders({ 'x-demo-access': 'demo' })
+  const cdp = await page.context().newCDPSession(page)
+  await cdp.send('Emulation.setLocaleOverride', { locale: 'ar-EG' })
+  await cdp.send('Emulation.setUserAgentOverride', { userAgent: '', acceptLanguage: 'ar-EG' })
+  await page.goto('http://localhost:3000')
+  await page.getByRole('heading', { name: 'Example workspace' }).waitFor()
+  await page.evaluate(() => document.fonts.ready)
+}
+```
+
+The two `Emulation` calls set the locale that `navigator.language`, `Intl`, and the `Accept-Language` header use; the empty `userAgent` keeps Chromium's own user agent and client hints. Traceframe waits for web fonts only on the `--url` page, so the last line waits for the application's fonts.
+
+## Record, inspect, and refine
+
+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.
+
+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:
+
+```sh
+ffmpeg -v error -xerror -i ./recording.mp4 -f null -
+```
+
+## 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.
+
+To speed up an idle stretch, such as a progress bar, you need its start and end times. Read them in a video player, or log them from the flow; logged times run up to about 0.1 seconds earlier than in the video:
+
+```js
+export default async function ({ page, click, wait }) {
+  const started = Date.now()
+  const mark = (label) => console.error(`${label}: ${((Date.now() - started) / 1000).toFixed(2)} s`)
+  // ...
+  mark('progress started')
+}
+```
+
+Log to `console.error`, because Traceframe prints its JSON summary on standard output. This command plays seconds 2 to 9 at 4× speed. Set `fps` to the video's frame rate: 60 for the default preset, 30 for draft.
+
+```sh
+ffmpeg -i recording.mp4 -filter_complex "[0:v]trim=0:2,setpts=PTS-STARTPTS[a];[0:v]trim=2:9,setpts=(PTS-STARTPTS)/4[b];[0:v]trim=9,setpts=PTS-STARTPTS[c];[a][b][c]concat=n=3,fps=60[v]" -map "[v]" -c:v libx264 -crf 18 -movflags +faststart faster.mp4
+```
+
+For an animated preview where an MP4 does not play inline, make a WebP. Not every FFmpeg build includes the WebP encoder.
+
+```sh
+ffmpeg -i recording.mp4 -vf "fps=12,scale=1280:-1" -c:v libwebp_anim -quality 75 -loop 0 preview.webp
+```
+
+## Optional sharing
+
+With push access to a repository, current [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/attaching-files-with-github-cli) can attach the MP4 to a comment so it plays there; check `gh pr comment --help` for your version. An MP4 hosted elsewhere shows as a link, not a player, so use the WebP preview there. Upload only when asked and after checking that the recording suits the destination; recording itself uploads nothing.

package/examples/recipes-flow.mjs

@@ -0,0 +1,27 @@
+export async function ready({ page }) {
+  await page.getByRole('heading', { name: 'Conversation demo' }).waitFor()
+}
+
+export default async function ({ page, click, hover, wait }) {
+  const message = page.getByRole('textbox', { name: 'Message' })
+  const replies = page.getByRole('list', { name: 'Replies' }).getByRole('listitem')
+  for (const [index, text] of ['Give me a short summary.', 'هل يمكنك التوضيح؟'].entries()) {
+    await click(message)
+    await message.pressSequentially(text, { delay: 45 })
+    await click(page.getByRole('button', { name: 'Send', exact: true }))
+    await replies.nth(index).waitFor({ timeout: 60_000 })
+    await wait(0.6)
+  }
+
+  const upload = page.getByText('Choose a sample file', { exact: true })
+  await hover(upload)
+  await page.getByLabel('Choose a sample file').setInputFiles({
+    name: 'sample.txt', mimeType: 'text/plain', buffer: Buffer.from('Example file for a local demo.\n'),
+  })
+  await page.getByText('Selected: sample.txt', { exact: true }).waitFor()
+  await wait(0.6)
+
+  await click(page.getByRole('button', { name: 'Finish demo', exact: true }))
+  await page.getByRole('button', { name: 'Demo complete', exact: true }).waitFor()
+  await wait(0.8)
+}

package/examples/recipes.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Traceframe recording recipes</title>
+    <style>
+      :root { color-scheme: light; font: 18px/1.5 system-ui, sans-serif; color: #172033; background: #f4f6fa; }
+      * { box-sizing: border-box; }
+      main { max-width: 900px; margin: 40px auto; padding: 32px; border: 1px solid #dce1eb; border-radius: 16px; background: #fff; }
+      h1 { margin: 0; font-size: 28px; }
+      h2 { margin: 20px 0 8px; font-size: 18px; }
+      p { margin: 8px 0 20px; }
+      form > label { display: block; margin-bottom: 8px; }
+      .compose { display: flex; gap: 12px; }
+      input, button { font: inherit; padding: 10px 16px; border: 1px solid #aeb7c8; border-radius: 8px; }
+      input { min-width: 0; flex: 1; }
+      button { color: #fff; background: #3454b5; cursor: pointer; }
+      button:hover { background: #284393; }
+      button:disabled { opacity: 0.6; }
+      #status { min-height: 27px; margin: 8px 0; }
+      #replies { min-height: 80px; padding-left: 28px; }
+      #replies li { margin: 8px 0; }
+      .upload { display: inline-block; padding: 12px 16px; border: 1px dashed #aeb7c8; border-radius: 8px; cursor: pointer; }
+      .upload:hover { background: #f4f6fa; }
+      .scroll-area { height: 160px; overflow: auto; border: 1px solid #dce1eb; border-radius: 8px; }
+      .scroll-content { height: 360px; display: flex; align-items: end; padding: 20px; }
+      .below-fold { margin-top: 480px; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Conversation demo</h1>
+      <p>Replies are simulated locally. No messages or files leave this page.</p>
+      <form id="conversation">
+        <label for="message">Message</label>
+        <div class="compose"><input id="message" dir="auto" required autocomplete="off"><button id="send">Send</button></div>
+      </form>
+      <p id="status" role="status">Ready for your question.</p>
+      <ol id="replies" aria-label="Replies"></ol>
+      <h2>Attach a file</h2>
+      <label class="upload" for="file">Choose a sample file</label><input id="file" type="file" hidden>
+      <p id="selected-file">No file selected.</p>
+      <h2 class="below-fold">Scroll to the last action</h2>
+      <section class="scroll-area" aria-label="More actions" tabindex="0">
+        <div class="scroll-content"><button id="finish" type="button">Finish demo</button></div>
+      </section>
+    </main>
+    <script>
+      const message = document.querySelector('#message')
+      const send = document.querySelector('#send')
+      const status = document.querySelector('#status')
+      const replies = document.querySelector('#replies')
+      document.querySelector('#conversation').addEventListener('submit', async (event) => {
+        event.preventDefault()
+        const text = message.value
+        message.value = ''
+        send.disabled = true
+        status.textContent = 'Preparing a reply…'
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+        const reply = document.createElement('li')
+        reply.dir = 'auto'
+        reply.textContent = `Reply ${replies.children.length + 1}: ${text}`
+        replies.append(reply)
+        status.textContent = 'Reply complete.'
+        send.disabled = false
+      })
+      document.querySelector('#file').addEventListener('change', (event) => {
+        document.querySelector('#selected-file').textContent = `Selected: ${event.target.files[0]?.name ?? 'none'}`
+      })
+      document.querySelector('#finish').addEventListener('click', (event) => { event.currentTarget.textContent = 'Demo complete' })
+    </script>
+  </body>
+</html>

package/package.json

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

package/src/assets/click-pulse.svg

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

package/src/assets/cursor.svg

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

package/src/capture.mjs

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

package/src/cli.mjs

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

package/src/config.mjs

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

package/src/errors.mjs

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

package/src/ffmpeg.mjs

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

package/src/flow.mjs

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

package/src/index.mjs

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

package/src/record.mjs

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

package/src/render.mjs

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