recordable 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # recordable
 
+[![npm version](https://img.shields.io/npm/v/recordable.svg)](https://www.npmjs.com/package/recordable)
+
 Programmatic, repeatable browser screen recording. Describe a session as a fluent
 chain of actions — `visit`, `click`, `type`, `zoom`, `scroll` — and `recordable`
 drives a real [Puppeteer](https://pptr.dev/) browser and captures a clean MP4,
@@ -22,12 +24,14 @@ await new Recordable({ typingSpeed: 120 })
   .scroll("bottom")
   .resetZoom()
   .wait(1500)
-  .run(); // finalises automatically — no start()/stop()
+  .run(); // finalises automatically — bookends are optional
 ```
 
-Recording is **on by default** and finalises when `.run()` ends — there's no
-`start()`/`stop()`. Use `pause()` / `resume()` to carve out anything you don't
-want on camera; every captured segment is stitched into one seamless MP4.
+Recording is **on by default** and finalises when `.run()` ends. Use `pause()` /
+`resume()` to carve out anything you don't want on camera; every captured segment
+is stitched into one seamless MP4. Need explicit bookends or several output files?
+`start()` / `end()` / `split()` move the file boundaries (see
+[Multiple output files](#multiple-output-files-start--end--split)).
 
 ## Features
 
@@ -45,9 +49,10 @@ want on camera; every captured segment is stitched into one seamless MP4.
 - **Manual steps / logins** — `resumeOnPlay()` waits for an in-page ▶ Play button
   (see below), so you can sign in by hand before recording.
 - **Auto-scroll** to bring elements into view before interacting.
-- **Declarative JSON scripts + CLI** — author a recording as JSON (with a published
-  schema for editor autocomplete) and run it with `npx recordable demo.json`, no
-  install or TypeScript required.
+- **Declarative scripts (JSON _or_ Markdown) + CLI** — author a recording as data,
+  not code, and run it with `npx recordable demo.json` / `demo.md`, no install or
+  TypeScript required. JSON ships a published schema for editor autocomplete;
+  Markdown adds prose narration for voiceover.
 
 ## Install
 
@@ -57,7 +62,7 @@ npm install recordable
 
 Frames are captured via the Chrome DevTools Protocol and encoded with **FFmpeg** —
 there's no external screen-recorder dependency. The ffmpeg binary ships via
-[`@ffmpeg-installer/ffmpeg`](https://www.npmjs.com/package/@ffmpeg-installer/ffmpeg),
+[`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static),
 so there's nothing else to install (a system `ffmpeg` on your `PATH` is used as a
 fallback).
 
@@ -93,27 +98,132 @@ local copy) and your editor gives you autocomplete, required-key checking, and
 typo catching for every action — no TypeScript needed. The schema is published as
 `recordable.schema.json`.
 
-Run a script from code with `runScript` (or `fromJSON` to build without running):
+Run a JSON script from code by handing it to a `Recordable` — a parsed object or
+the raw file string both work:
+
+```ts
+import { readFileSync } from "node:fs";
+import { Recordable } from "recordable";
+
+const script = readFileSync("./demo.json", "utf8");
+await new Recordable({ baseDir: "." }).fromJSON(script).run();
+```
+
+`baseDir` is the script's folder — `recordable` resolves relative `visit` URLs
+and a relative `outputDir` against it. (Standalone `runScript` / `fromJSON`
+helpers are also exported if you prefer a single call.)
+
+## Declarative scripts (Markdown)
+
+Markdown is the richest authoring surface — the **same actions as JSON**, written
+as backtick method-call spans, with optional narration prose woven around them for
+voiceover. YAML frontmatter carries the [config](#configuration); an optional
+`voiceover` block opts into narration audio (`voiceover: true` reads provider /
+voice from the environment, or pass an object to set them inline).
+
+Two flavours, mixable in one document:
+
+**1. A fenced action list** — one call per line, no prose. The closest Markdown
+gets to JSON; compiles to the exact same actions:
+
+````md
+---
+viewport: { width: 1280, height: 800 }
+---
+
+```
+pause()
+visit("./index.html")
+resume()
+zoom(1.4, { origin: "#email" })
+type("#email", "hello@example.com")
+click("text:Sign up", { waitForNav: true })
+waitFor("text:Thanks", { state: "visible" })
+resetZoom()
+```
+````
+
+**2. Inline markers in prose** — drop call spans into narration; each fires at its
+position in the spoken line. With `voiceover` on, the prose is read aloud and waits
+are timed to the narration:
+
+```md
+---
+typingSpeed: 16
+voiceover: true
+---
+
+`visit("./signin.html")` Welcome — first we sign in with our work account
+`type("#email", "maya@example.com")` then our password
+`type("#password", "•••••")` `click("#signInBtn", { waitForNav: true })` — and
+we're straight into the dashboard.
+```
+
+Each backtick span holds exactly one call; its arguments are the method's
+arguments, identical to the chainable API and the JSON `action` keys. Whole-line
+`//` comments are stripped before parsing, so toggle-comment in your editor is
+safe. Run a Markdown file through the [CLI](#cli) (`npx recordable demo.md`) or
+from code:
 
 ```ts
-import { runScript } from "recordable";
-import demo from "./demo.json" with { type: "json" };
+import { readFileSync } from "node:fs";
+import { Recordable } from "recordable";
 
-await runScript(demo);
+const md = readFileSync("./demo.md", "utf8");
+await new Recordable({ baseDir: "." }).fromMarkdown(md).run();
 ```
 
-### CLI
+## Voiceover
 
-Or run a JSON file directly — **no install required** via `npx`:
+A Markdown script can narrate itself. The prose around your inline markers becomes
+spoken audio (text-to-speech), and the markers are **timed to the narration** — each
+action fires at its position in the spoken line, so the demo and the voice stay in
+sync without hand-tuned `wait`s.
+
+Opt in from frontmatter. With credentials in the environment, `voiceover: true` is
+all a document needs; spell out a `voiceover` object to set provider / voice / model
+inline (it overrides the environment):
+
+```yaml
+voiceover: true
+```
+
+```yaml
+voiceover:
+  provider: elevenlabs # or `mock` for silent, offline audio
+  voiceId: EXAVITQu4vr4xnSDxMaL
+  modelId: eleven_multilingual_v2
+```
+
+**Credentials & defaults** come from a `.env` loaded automatically from **beside the
+document** (copy [`.env.example`](.env.example)):
+
+```sh
+ELEVENLABS_API_KEY=...                   # required for real synthesis
+RECORDABLE_TTS_PROVIDER=elevenlabs       # or `mock` for silent, offline audio
+RECORDABLE_VOICE_ID=...                  # default voice when frontmatter omits it
+RECORDABLE_MODEL_ID=eleven_multilingual_v2
+```
+
+Generated audio is written to the `assetsDir` (default `assets/`, beside the output)
+and cached, so re-running an unchanged script doesn't re-synthesize. Validate a
+voiceover script without hitting the TTS API — or a browser — with `recordable
+demo.md --check`. For a music bed or a hand-recorded narration file, drop it straight
+onto the timeline with `audio(path, opts?)` (see the [API](#recording)).
+
+## CLI
+
+Run a JSON **or** Markdown file directly — **no install required** via `npx`:
 
 ```sh
 npx recordable demo.json
+npx recordable demo.md
 ```
 
 ```
-recordable <script.json> [options]
+recordable <script.json | script.md> [options]
 
-  --check          Validate the script and exit (no browser, no recording)
+  --check          Validate the script and exit (no browser, no audio, no recording)
   --headless       Run without a visible browser window
   --silent         Suppress recorder console output
   --out-dir <dir>  Output directory (overrides the script's config)
@@ -195,8 +305,9 @@ new Recordable()
 ```
 
 No `pause()`/`resume()` needed — `insert` seals the current segment and recording
-resumes into a fresh one on the next action automatically. (Audio on the clip is
-currently dropped; voiceover support is on the roadmap.)
+resumes into a fresh one on the next action automatically. (Audio on the inserted
+clip itself is currently dropped — narration voiceover is a separate, supported
+feature, authored in [Markdown](#declarative-scripts-markdown).)
 
 **Cross-fades.** Pass `fadeIn` / `fadeOut` (ms) to dissolve rather than hard-cut.
 A fade blends the clip with the **neighbouring recorded footage** (a true
@@ -206,6 +317,39 @@ on `fadeOut`, while an outro's `fadeOut` dissolves down to black. Omit them for
 hard cut. A cross-fade of _d_ ms overlaps the two pieces by _d_, shortening the
 timeline by that much at each faded boundary.
 
+## Multiple output files (`start` / `end` / `split`)
+
+`pause()`/`resume()` carve off-camera gaps **within one file**. To produce
+**separate files**, move the file boundaries with `start()` / `end()` / `split()`:
+
+```ts
+await new Recordable({ outputName: "demo" })
+  .start("intro") // open the first file (content before it is off-camera)
+  .visit("https://example.com")
+  .click("text:Get started")
+  .split("checkout") // close "intro", open the next — camera keeps rolling
+  .click("text:Buy")
+  .end() // close "checkout"; the teardown below runs off-camera
+  .click("text:Sign out")
+  .run(); // → demo-intro.mp4, demo-checkout.mp4
+```
+
+- **Boundaries default to the script edges.** With no `start()`, recording opens
+  at the top; with no `end()`, it closes at the bottom — so a plain script is one
+  file, exactly as before. Add only the bookend you need.
+- **`pause`/`resume` ≠ `start`/`end`.** `resume()` continues the _same_ file (the
+  gap is stitched out); `start()`/`split()` open a _new_ file. `split() ≡ end() +
+start()` fused with no gap; for two files _with_ an off-camera gap between them,
+  use `end()` … `start()`.
+- **Naming.** Each file is `${outputName}-${label ?? index}.mp4`; a label always
+  wins. A single unlabelled file stays `${outputName}.mp4`.
+- **Audio is per-file** — each output is standalone with its own zero-based
+  timeline; a clip is assigned to the file containing its start.
+
+`run()` resolves to a `RecordableResult` — `{ status, files: [{ path, label,
+index, durationMs, bytes }], outputDir, durationMs, elapsedMs, warnings }` — so
+you can find every file that was written. Hard failures throw instead.
+
 ## API
 
 Create an instance with optional [config](#configuration), chain actions, then
@@ -213,16 +357,22 @@ Create an instance with optional [config](#configuration), chain actions, then
 
 ### Recording
 
-Recording is on by default and finalises automatically on `.run()`. These control
-what lands on camera:
-
-| Method                   | Description                                                                                                       |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `pause()`                | Stop capturing; the chain keeps running off-camera.                                                               |
-| `resume()`               | Resume capturing in a fresh segment, immediately.                                                                 |
-| `waitForPlay(message?)`  | Block until the user clicks the in-page ▶ Play button (or presses Enter); leaves recording state untouched.       |
-| `resumeOnPlay(message?)` | Wait for ▶ Play, then resume capturing — `waitForPlay().resume()`.                                                |
-| `insert(path, opts?)`    | Splice an external clip (intro / outro / mid-roll) into the timeline; `opts.fadeIn`/`fadeOut` (ms) cross-fade it. |
+Recording is on by default and finalises automatically on `.run()`, which resolves
+to a [`RecordableResult`](#multiple-output-files-start--end--split). `pause`/`resume`
+control what lands on camera _within_ a file; `start`/`end`/`split` move the file
+boundaries to produce [separate files](#multiple-output-files-start--end--split):
+
+| Method                   | Description                                                                                                                                                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `pause()`                | Stop capturing; the chain keeps running off-camera.                                                                                                                                                          |
+| `resume()`               | Resume capturing in a fresh segment, immediately.                                                                                                                                                            |
+| `start(name?)`           | Open an output file (opening boundary); content before the first `start()` is off-camera. `name` labels the file.                                                                                            |
+| `end()`                  | Close the current output file (closing boundary); content after it runs off-camera.                                                                                                                          |
+| `split(name?)`           | Close the current file and open the next in one move, camera still rolling — `end()` + `start()` with no gap.                                                                                                |
+| `waitForPlay(message?)`  | Block until the user clicks the in-page ▶ Play button (or presses Enter); leaves recording state untouched.                                                                                                  |
+| `resumeOnPlay(message?)` | Wait for ▶ Play, then resume capturing — `waitForPlay().resume()`.                                                                                                                                           |
+| `insert(path, opts?)`    | Splice an external clip (intro / outro / mid-roll) into the timeline; `opts.fadeIn`/`fadeOut` (ms) cross-fade it.                                                                                            |
+| `audio(path, opts?)`     | Lay an existing audio file (mp3/wav) onto the timeline here — narration, music bed, SFX. Blocks until the clip ends by default (`opts.wait: false` plays it over following actions); `opts.volume` gains it. |
 
 ### Navigation & waiting
 
@@ -234,15 +384,15 @@ what lands on camera:
 
 ### Interactions
 
-| Method                              | Description                                                                                                                                    |
-| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Method                                          | Description                                                                                                                                                                                                             |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `click(target, { waitForNav?, followNewTab? })` | Click an element. Returns immediately by default; pass `{ waitForNav: true }` when the click triggers a full-page navigation, or `{ followNewTab: true }` to keep recording in a tab the click opens (see notes below). |
-| `hover(target)`                     | Move onto an element to reveal `:hover` state (no click).                                                                                      |
-| `type(target, text, { duration? })` | Type into a field with human-like timing; `duration` (ms) spreads keystrokes evenly with no jitter.                                            |
-| `clear(target)`                     | Select-all + delete the contents of a field.                                                                                                   |
-| `select(target, value)`             | Choose an option in a native `<select>` by `value`, or by `:option-index(N)` / `:option-label(Text)` (see note below; OS-drawn list isn't captured). |
-| `key(key)`                          | Press a key, e.g. `"Escape"`, `"Enter"`, `"Tab"`.                                                                                              |
-| `mouse(target \| {x, y})`           | Move the cursor to an element or coordinates.                                                                                                  |
+| `hover(target)`                                 | Move onto an element to reveal `:hover` state (no click).                                                                                                                                                               |
+| `type(target, text, { duration? })`             | Type into a field with human-like timing; `duration` (ms) spreads keystrokes evenly with no jitter.                                                                                                                     |
+| `clear(target)`                                 | Select-all + delete the contents of a field.                                                                                                                                                                            |
+| `select(target, value)`                         | Choose an option in a native `<select>` by `value`, or by `:option-index(N)` / `:option-label(Text)` (see note below; OS-drawn list isn't captured).                                                                    |
+| `key(key)`                                      | Press a key, e.g. `"Escape"`, `"Enter"`, `"Tab"`.                                                                                                                                                                       |
+| `mouse(target \| {x, y})`                       | Move the cursor to an element or coordinates.                                                                                                                                                                           |
 
 > The browser draws an open `<select>`'s option list with the OS, outside the page,
 > so the screencast can't capture it — `select()` shows the cursor and the value
@@ -267,12 +417,12 @@ what lands on camera:
 
 ### Camera
 
-| Method                                | Description                                                       |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `scroll(target, { duration? })`       | Smooth-scroll to `"top"`/`"bottom"`, a selector, or a Y position. |
-| `zoom(level, { origin?, duration? })` | Smoothly scale from an origin (keyword, `%`, or selector).        |
-| `resetZoom({ duration? })`            | Smoothly return to 1×.                                            |
-| `setConfig(config)`                   | Merge config mid-sequence (takes effect at that point).           |
+| Method                                      | Description                                                                                                                                               |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scroll(target, { container?, duration? })` | Smooth-scroll to `"top"`/`"bottom"`, a selector, or a Y position. `container` scrolls a named overflow pane (modal, sidebar, list) instead of the window. |
+| `zoom(level, { origin?, duration? })`       | Smoothly scale from an origin (keyword, `%`, or selector).                                                                                                |
+| `resetZoom({ duration? })`                  | Smoothly return to 1×.                                                                                                                                    |
+| `setConfig(config)`                         | Merge config mid-sequence (takes effect at that point).                                                                                                   |
 
 ### Targeting
 
@@ -305,11 +455,13 @@ new Recordable({
   viewport: { width: 1920, height: 1080 },
   pageZoom: 1, // browser page zoom (Ctrl +/−); <1 reflows to fit more on screen
   fps: 30,
-  outputDir: "./output",
+  outputDir: "output", // relative paths resolve against baseDir
   outputName: "recordable",
   outputTimestamp: true, // prepend an ISO timestamp to the filename
+  assetsDir: "assets", // where generated voiceover audio is written (relative to baseDir)
   headless: false,
-  language: "", // BCP-47 locale, e.g. "fr-FR" (--lang + Accept-Language); "" = system
+  launchArgs: [], // extra Chromium flags, e.g. ["--no-sandbox"] for CI/containers
+  language: "", // BCP-47 locale, e.g. "fr-FR" (--lang + --accept-lang + Accept-Language); "" = system
   typingSpeed: 7, // characters per second
   videoCrf: 18, // lower = better quality, larger file
   videoCodec: "libx264",
@@ -323,6 +475,7 @@ new Recordable({
   scrollDuration: 1200, // ms for the scroll action's transition
   cursor: true, // show the animated cursor overlay
   visitTimeout: 30_000, // ms for navigation / waitFor
+  baseDir: "", // dir that relative visit URLs, outputDir & assetsDir resolve against; "" = cwd
 });
 ```
 
@@ -336,6 +489,7 @@ npm test              # unit + ffmpeg I/O tests
 npm run test:e2e      # opt-in end-to-end pipeline run (launches a browser)
 npx tsx my-script.ts  # run a recording script directly
 node dist/cli.js demo.json   # run a JSON script through the CLI locally
+node dist/cli.js demo.md      # run a Markdown script through the CLI locally
 ```
 
 The JSON action set and its schema are both generated from one manifest in

package/dist/actions.d.ts

@@ -4,6 +4,13 @@ import * as z from "zod";
  * discriminator). strictObject so an unknown key (a typo) fails validation.
  */
 declare const ACTIONS: {
+    start: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    end: z.ZodObject<{}, z.core.$strict>;
+    split: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
     pause: z.ZodObject<{}, z.core.$strict>;
     resume: z.ZodObject<{}, z.core.$strict>;
     waitForPlay: z.ZodObject<{
@@ -100,6 +107,7 @@ declare const ACTIONS: {
     }, z.core.$strict>;
     scroll: z.ZodObject<{
         target: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        container: z.ZodOptional<z.ZodString>;
         duration: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     zoom: z.ZodObject<{

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAezB;;;GAGG;AACH,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+D0B,CAAC;AAYxC,sEAAsE;AACtE,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAuChE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAgBjD;AAED;;;;;;GAMG;AACH,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAcxD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CA2C3E;AAED,wEAAwE;AACxE,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAezB;;;GAGG;AACH,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmE0B,CAAC;AAcxC,sEAAsE;AACtE,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAuChE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAgBjD;AAED;;;;;;GAMG;AACH,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAcxD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAkD3E;AAED,wEAAwE;AACxE,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/actions.js

@@ -16,6 +16,9 @@ const XY = z.strictObject({ x: z.number(), y: z.number() });
  */
 const ACTIONS = {
     // Recording control
+    start: z.strictObject({ name: z.string().optional() }),
+    end: z.strictObject({}),
+    split: z.strictObject({ name: z.string().optional() }),
     pause: z.strictObject({}),
     resume: z.strictObject({}),
     waitForPlay: z.strictObject({ message: z.string().optional() }),
@@ -63,6 +66,7 @@ const ACTIONS = {
     // Scrolling / zoom
     scroll: z.strictObject({
         target: z.union([z.string(), z.number()]),
+        container: z.string().optional(),
         duration: z.number().optional(),
     }),
     zoom: z.strictObject({
@@ -80,6 +84,8 @@ const ACTIONS = {
  * fact not derivable from the schema.
  */
 const POSITIONAL_OPTIONAL = {
+    start: ["name"],
+    split: ["name"],
     waitForPlay: ["message"],
     resumeOnPlay: ["message"],
 };
@@ -155,7 +161,7 @@ function buildArgs(step, name) {
 export function callToAction(name, args) {
     const schema = ACTIONS[name];
     if (!schema) {
-        throw new Error(`Unknown action "${name}" — valid actions: ${Object.keys(ACTIONS).join(", ")}`);
+        throw new RecordableError("CONFIG_INVALID", `Unknown action "${name}" — valid actions: ${Object.keys(ACTIONS).join(", ")}`);
     }
     const step = { action: name };
     let i = 0;
@@ -163,23 +169,23 @@ export function callToAction(name, args) {
         if (i < args.length)
             step[key] = args[i++];
         else if (!isOptional(name, key))
-            throw new Error(`Action "${name}" is missing required "${key}"`);
+            throw new RecordableError("CONFIG_INVALID", `Action "${name}" is missing required "${key}"`);
     }
     const bag = bagKeys(name);
     if (i < args.length && bag.length) {
         const obj = args[i++];
         if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
-            throw new Error(`Action "${name}": expected a trailing options object, got ${JSON.stringify(obj)}`);
+            throw new RecordableError("CONFIG_INVALID", `Action "${name}": expected a trailing options object, got ${JSON.stringify(obj)}`);
         }
         for (const [k, v] of Object.entries(obj)) {
             if (!bag.includes(k)) {
-                throw new Error(`Action "${name}": unknown key "${k}" — valid keys: ${bag.join(", ")}`);
+                throw new RecordableError("CONFIG_INVALID", `Action "${name}": unknown key "${k}" — valid keys: ${bag.join(", ")}`);
             }
             step[k] = v;
         }
     }
     if (i < args.length) {
-        throw new Error(`Action "${name}": too many arguments (expected at most ${i}, got ${args.length})`);
+        throw new RecordableError("CONFIG_INVALID", `Action "${name}": too many arguments (expected at most ${i}, got ${args.length})`);
     }
     validateAction(step);
     return step;

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,gFAAgF;AAChF,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,iFAAiF;AACjF,8EAA8E;AAC9E,6EAA6E;AAE7E,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AACvD,MAAM,EAAE,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,OAAO,GAAG;IACd,oBAAoB;IACpB,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC;IAC1B,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC/D,YAAY,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;IAChE,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC;QACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC;QACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC9B,CAAC;IACF,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAEnD,aAAa;IACb,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC;QACpB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;QACf,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAChC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;IACF,OAAO,EAAE,CAAC,CAAC,YAAY,CAAC;QACtB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE;QACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;IAEF,eAAe;IACf,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;KACrC,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC;QACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAChC,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IACjE,GAAG,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IACxC,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;IAE5D,mBAAmB;IACnB,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACzC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAChC,CAAC;IACF,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC;QACnB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAChC,CAAC;IACF,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;IAE9D,SAAS;IACT,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;CACH,CAAC;AAExC;;;;GAIG;AACH,MAAM,mBAAmB,GAAsC;IAC7D,WAAW,EAAE,CAAC,SAAS,CAAC;IACxB,YAAY,EAAE,CAAC,SAAS,CAAC;CAC1B,CAAC;AAKF,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,8DAA8D;AAE9D,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAE,CAC9B,OAAuC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAEjE,2EAA2E;AAC3E,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAW,EAAE,EAAE,CAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC;AAE9C,wFAAwF;AACxF,MAAM,cAAc,GAAG,CAAC,IAAY,EAAE,EAAE,CACtC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CACtB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CACtE,CAAC;AAEJ,gFAAgF;AAChF,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAE,CAC/B,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CACtB,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CACtE,CAAC;AAEJ,wDAAwD;AACxD,SAAS,YAAY,CAAC,KAAiB;IACrC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,MAAM,GAAI,OAAuC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,mBAAmB,IAAI,CAAC,MAAM,sBAAsB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,WAAW,IAAI,CAAC,MAAM,MAAM,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACzD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,IAAY;IAC3C,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAE7D,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,KAAK,MAAM,GAAG,IAAI,GAAG;YAAE,IAAI,GAAG,IAAI,IAAI;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACzD,CAAC;IAED,uEAAuE;IACvE,OAAO,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IACtE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAwB;IACjE,MAAM,MAAM,GAAI,OAAuC,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,sBAAsB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEV,KAAK,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;aACtC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,0BAA0B,GAAG,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,8CAA8C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CACnF,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,mBAAmB,CAAC,mBAAmB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvE,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,2CAA2C,CAAC,SAAS,IAAI,CAAC,MAAM,GAAG,CACnF,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/audio/track.d.ts

@@ -24,6 +24,16 @@ export declare class AudioTrack {
         durationMs: number;
     }>;
 }
+/**
+ * Partition clips across a run's output files (ROADMAP §6: per-file audio). A
+ * clip is assigned to the file *containing its start* — the last file whose
+ * global `startMs` is at or before the clip — then rebased to that file's own
+ * zero-based timeline. A clip overrunning its file's end is left for the mixer
+ * to trim (and warn). Returns one clip list per file, aligned to `files`.
+ */
+export declare function partitionAudioByFiles(clips: readonly AudioClip[], files: readonly {
+    startMs: number;
+}[]): AudioClip[][];
 /**
  * Build the `filter_complex` chain that delays each clip to its `startMs`,
  * applies volume, and mixes them. Input index `i+1` (input 0 is the video).

package/dist/audio/track.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/audio/track.ts"],"names":[],"mappings":"AAYA,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;uEACuE;AACvE,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IAEzC,oCAAoC;IACpC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,kEAAkE;IAClE,IAAI,IAAI,SAAS,SAAS,EAAE;IAI5B;;;OAGG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAOpD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAeA;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,MAAM,EACf,KAAK,SAAK,GACT;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAOpC"}
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/audio/track.ts"],"names":[],"mappings":"AAYA,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;uEACuE;AACvE,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IAEzC,oCAAoC;IACpC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,kEAAkE;IAClE,IAAI,IAAI,SAAS,SAAS,EAAE;IAI5B;;;OAGG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,KAAK,EAAE,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GACpC,SAAS,EAAE,EAAE,CAUf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAeA;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,MAAM,EACf,KAAK,SAAK,GACT;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAOpC"}

package/dist/audio/track.js

@@ -25,6 +25,25 @@ export class AudioTrack {
         return { startMs, durationMs };
     }
 }
+/**
+ * Partition clips across a run's output files (ROADMAP §6: per-file audio). A
+ * clip is assigned to the file *containing its start* — the last file whose
+ * global `startMs` is at or before the clip — then rebased to that file's own
+ * zero-based timeline. A clip overrunning its file's end is left for the mixer
+ * to trim (and warn). Returns one clip list per file, aligned to `files`.
+ */
+export function partitionAudioByFiles(clips, files) {
+    const groups = files.map(() => []);
+    for (const c of clips) {
+        let idx = 0;
+        for (let i = 0; i < files.length; i++)
+            if (files[i].startMs <= c.startMs)
+                idx = i;
+        if (groups[idx])
+            groups[idx].push({ ...c, startMs: c.startMs - files[idx].startMs });
+    }
+    return groups;
+}
 /**
  * Build the `filter_complex` chain that delays each clip to its `startMs`,
  * applies volume, and mixes them. Input index `i+1` (input 0 is the video).

package/dist/audio/track.js.map

@@ -1 +1 @@
-{"version":3,"file":"track.js","sourceRoot":"","sources":["../../src/audio/track.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAkB/C;uEACuE;AACvE,MAAM,OAAO,UAAU;IACJ,KAAK,GAAgB,EAAE,CAAC;IAEzC,oCAAoC;IACpC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,kEAAkE;IAClE,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CACP,IAAY,EACZ,OAAe,EACf,UAA+B,EAAE;QAEjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YACnB,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,0BAA0B,IAAI,EAAE,CAAC,CAAC;QAChF,MAAM,UAAU,GAAG,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACpD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACjC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA2B;IAI1D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACjC,MAAM,KAAK,GAAG,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAE3D,OAAO,CAAC,IAAI,CACV,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,eAAe,KAAK,CAAC,MAAM,oBAAoB,CAClE,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA2B,EAC3B,OAAe,EACf,KAAK,GAAG,EAAE;IAEV,MAAM,IAAI,GAAuC,EAAE,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC;QAC9D,IAAI,MAAM,GAAG,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"track.js","sourceRoot":"","sources":["../../src/audio/track.ts"],"names":[],"mappings":"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"}

package/dist/browser/cursor.d.ts

@@ -17,7 +17,7 @@ export declare class Cursor {
     park(): void;
     /** Restore the parked position (if any) and re-inject — called on resume so the
      *  new segment opens with the cursor where the previous one ended. */
-    unpark(page: Page, zoom?: ZoomState, pageZoom?: number): Promise<void>;
+    unpark(page: Page, zoom?: ZoomState): Promise<void>;
     /**
      * Ensure the cursor overlay exists and sits at the carried position, then sync
      * the real mouse there. Safe to call repeatedly: it creates the overlay if the
@@ -25,18 +25,20 @@ export declare class Cursor {
      * repositions it — so a resume() can restore the cursor even when the overlay
      * survived the off-camera gap.
      */
-    inject(page: Page, zoom?: ZoomState, pageZoom?: number): Promise<void>;
+    inject(page: Page, zoom?: ZoomState): Promise<void>;
     /** Ease the overlay (and the real mouse) to viewport coords `toX,toY`. */
-    moveTo(page: Page, toX: number, toY: number, zoom: ZoomState, pageZoom?: number): Promise<void>;
+    moveTo(page: Page, toX: number, toY: number, zoom: ZoomState): Promise<void>;
     /**
      * Convert viewport coords → document coords for the overlay's transform.
      * When documentElement has a CSS transform (zoom), position:fixed children
      * are positioned relative to that ancestor (not the viewport) and scroll with
      * the page, so we add scroll and apply the inverse zoom transform.
      *
-     * `pageZoom` is the static CSS `zoom` on documentElement (the pageZoom config).
-     * The overlay inherits that zoom, so its translate renders `pageZoom`× larger —
-     * divide it out so the cursor still lands on the target's visual position.
+     * Note: the `pageZoom` config (genuine browser zoom via chrome.tabs.setZoom)
+     * needs no handling here. Page zoom rescales the CSS pixel itself, so the
+     * overlay, the content, and Puppeteer's `boundingBox()`/`mouse` coords all share
+     * one post-zoom coordinate space — feeding the overlay those raw coords keeps it
+     * aligned with the target automatically.
      */
     private _toDocCoords;
     /** Briefly scale the cursor down to signal a press. */

package/dist/browser/cursor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/browser/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAOtC,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAIjB,OAAO,CAAC,GAAG,CAAkB;IAK7B,OAAO,CAAC,MAAM,CAAyC;IAEvD,4EAA4E;IAC5E,IAAI,IAAI,IAAI;IAIZ;0EACsE;IAChE,MAAM,CACV,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,SAAkC,EACxC,QAAQ,SAAI,GACX,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;OAMG;IACG,MAAM,CACV,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,SAAkC,EACxC,QAAQ,SAAI,GACX,OAAO,CAAC,IAAI,CAAC;IAiEhB,0EAA0E;IACpE,MAAM,CACV,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,EACf,QAAQ,SAAI,GACX,OAAO,CAAC,IAAI,CAAC;IAiChB;;;;;;;;;OASG;YACW,YAAY;IAiB1B,uDAAuD;IACjD,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAa7C"}
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/browser/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAiBtC,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAIjB,OAAO,CAAC,GAAG,CAAkB;IAK7B,OAAO,CAAC,MAAM,CAAyC;IAEvD,4EAA4E;IAC5E,IAAI,IAAI,IAAI;IAIZ;0EACsE;IAChE,MAAM,CACV,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,SAAkC,GACvC,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;OAMG;IACG,MAAM,CACV,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,SAAkC,GACvC,OAAO,CAAC,IAAI,CAAC;IA2EhB,0EAA0E;IACpE,MAAM,CACV,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,IAAI,CAAC;IAoChB;;;;;;;;;;;OAWG;YACW,YAAY;IAa1B,uDAAuD;IACjD,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAa7C"}