recordable 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cam Parry
+
+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

@@ -0,0 +1,303 @@
+# 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,
+complete with an animated cursor, smooth zooming/scrolling, and human-like typing.
+
+Because the recording is _code_, it's deterministic and re-runnable: regenerate the
+exact same capture whenever the UI changes — for product demos, onboarding clips,
+documentation GIFs, release notes, or visual regression footage.
+
+```ts
+import { Recordable } from "recordable";
+
+await new Recordable({ typingSpeed: 120 })
+  .pause() // skip the initial page load
+  .visit("https://example.com")
+  .resume()
+  .zoom(1.5, { origin: "#newsletter" })
+  .type("#email", "hello@example.com")
+  .click("text:Sign up")
+  .scroll("bottom")
+  .resetZoom()
+  .wait(1500)
+  .run(); // finalises automatically — no start()/stop()
+```
+
+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.
+
+## Features
+
+- **Fluent, queued API** — chain actions; nothing runs until `.run()`.
+- **Deterministic & repeatable** — the recording is code, so it reproduces exactly.
+- **Animated cursor overlay** with realistic movement and click feedback.
+- **Smooth zoom & scroll** that animate origin and scale together.
+- **Human-like typing** with jitter and natural pauses.
+- **Element targeting** by CSS selector or visible text (`text:` prefix).
+- **Off-camera segments** — `pause()`/`resume()` skip setup, navigations, or whole
+  screens; segments are auto-stitched into one seamless video.
+- **Manual steps / logins** — `resumeOnInput()` 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.
+
+## Install
+
+```sh
+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),
+so there's nothing else to install (a system `ffmpeg` on your `PATH` is used as a
+fallback).
+
+## Declarative scripts (JSON)
+
+You don't have to write TypeScript. A recording can be a plain **JSON** file — an
+array of `{ action, ... }` actions that map 1:1 onto the chainable API, optionally
+wrapped with a `config`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/paragramagency/recordable/main/recordable.schema.json",
+  "config": { "typingSpeed": 14 },
+  "actions": [
+    { "action": "pause" },
+    { "action": "visit", "url": "https://example.com" },
+    { "action": "resume" },
+    { "action": "zoom", "level": 1.5, "origin": "#newsletter" },
+    { "action": "type", "target": "#email", "text": "hello@example.com" },
+    { "action": "click", "target": "text:Sign up" },
+    { "action": "waitFor", "target": "text:Thanks", "state": "visible" },
+    { "action": "resetZoom" }
+  ]
+}
+```
+
+Each step's keys are the named arguments of the matching method — `type(target, text)`
+→ `{ "action": "type", "target": …, "text": … }`; `waitFor`'s `state`/`timeout` are
+top-level keys.
+
+**Editor support.** Add the `"$schema"` line above (a URL, or a relative path to a
+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):
+
+```ts
+import { runScript } from "recordable";
+import demo from "./demo.json" with { type: "json" };
+
+await runScript(demo);
+```
+
+### CLI
+
+Or run a JSON file directly — **no install required** via `npx`:
+
+```sh
+npx recordable demo.json
+```
+
+```
+recordable <script.json> [options]
+
+  --check          Validate the script and exit (no browser, no recording)
+  --headless       Run without a visible browser window
+  --silent         Suppress recorder console output
+  --out-dir <dir>  Output directory (overrides the script's config)
+  --name <name>    Output filename (without extension)
+  --no-timestamp   Don't prepend an ISO timestamp to the filename
+  -h, --help       Show this help
+```
+
+Relative `visit` URLs (e.g. `"./index.html"`) and a relative `outputDir` resolve
+against the script file, so a script, its mockups, and its output stay together
+regardless of where you run it from. `--out-dir` overrides the output location
+(taken relative to the current directory). `--check` validates a script in CI or
+while authoring without launching a browser.
+
+## Off-camera work & seamless segments
+
+`pause()` stops the camera but the chain keeps running, so anything up to the
+next `resume()` happens off-camera — page loads, data setup, even navigating to a
+different screen. Each recorded stretch is a segment, and they're concatenated
+(losslessly, by stream-copy where possible) into a single MP4 on `.run()`:
+
+```ts
+await new Recordable()
+  .visit("/dashboard")
+  .click("text:Reports") // recorded
+  .pause()
+  .visit("/admin") // off-camera: jump to another screen, reset state…
+  .click("text:Seed demo data")
+  .resume()
+  .click("text:Run report") // recorded again — stitched seamlessly to the above
+  .run();
+```
+
+## Recording behind a login (manual steps)
+
+Run **headful** (`headless: false`) so the Chrome window is interactive. Keep the
+camera off while you sign in by hand, then `resumeOnInput()` waits for you to
+click an **in-page ▶ Play button** (or press Enter) before recording resumes:
+
+```ts
+await new Recordable({ headless: false })
+  .pause() // camera off — the login isn't recorded
+  .visit("https://app.example.com/login")
+  .resumeOnInput("Log in, then click ▶ Play to start recording")
+  .visit("https://app.example.com/dashboard")
+  .click("text:New project")
+  .run();
+```
+
+- **`resumeOnInput(message?)`** injects a ▶ Play button into the page itself and
+  blocks until you click it (Enter in the terminal also works). The button is
+  re-injected across navigations, so it survives login redirects.
+- Prefer an automatic trigger? Use **`waitFor("#dashboard")`** after `resume()` to
+  carry on once a post-login element appears — no clicking required.
+
+Because the manual step sits inside a `pause()`, the sign-in never appears in the
+video.
+
+## Intros, outros & mid-rolls
+
+`insert(path)` splices an external video clip into the timeline at that point —
+its position decides the role: first call is an intro, last is an outro, anything
+in between is a mid-roll. The clip is normalized to the recording's resolution,
+fps, and codec so the join is seamless.
+
+```ts
+new Recordable()
+  .insert("intro.mp4", { fadeIn: 500, fadeOut: 600 }) // plays first
+  .visit("https://example.com")
+  .click("text:Get started")
+  .insert("feature-promo.mp4", { fadeIn: 600, fadeOut: 600 }) // mid-roll
+  .scroll("bottom")
+  .insert("outro.mp4", { fadeOut: 500 }) // plays last
+  .run();
+```
+
+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.)
+
+**Cross-fades.** Pass `fadeIn` / `fadeOut` (ms) to dissolve rather than hard-cut.
+A fade blends the clip with the **neighbouring recorded footage** (a true
+cross-dissolve), or fades from/to **black** at the timeline ends where there's no
+neighbour — so an intro's `fadeIn` fades up from black and dissolves into the page
+on `fadeOut`, while an outro's `fadeOut` dissolves down to black. Omit them for a
+hard cut. A cross-fade of _d_ ms overlaps the two pieces by _d_, shortening the
+timeline by that much at each faded boundary.
+
+## API
+
+Create an instance with optional [config](#configuration), chain actions, then
+`await .run()`.
+
+### 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.                                                                 |
+| `resumeOnInput(message?)` | Resume only after the user clicks the in-page ▶ Play button (or presses Enter).                                   |
+| `insert(path, opts?)`     | Splice an external clip (intro / outro / mid-roll) into the timeline; `opts.fadeIn`/`fadeOut` (ms) cross-fade it. |
+
+### Navigation & waiting
+
+| Method                   | Description                                                     |
+| ------------------------ | --------------------------------------------------------------- |
+| `visit(url, options?)`   | Navigate and wait for the page to settle.                       |
+| `waitFor(target, opts?)` | Wait for an element to become `visible` / `hidden` / `present`. |
+| `wait(ms)`               | Pause the sequence for `ms` milliseconds.                       |
+
+### Interactions
+
+| Method                              | Description                                                                                         |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `click(target)`                     | Click an element.                                                                                   |
+| `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>` (the OS-drawn option list isn't captured — see note below). |
+| `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
+> changing, but not the dropdown. For an on-camera dropdown, build a custom one from
+> `click()`s.
+
+### 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).           |
+
+### Targeting
+
+Anywhere a `target` is accepted you can pass:
+
+- a **CSS selector** — `"#id"`, `".card"`, `'[name="email"]'`
+- a **`text:` prefix** — `"text:Sign up"` matches by visible text
+
+## Configuration
+
+All options are optional; defaults shown.
+
+```ts
+new Recordable({
+  viewport: { width: 1920, height: 1080 },
+  fps: 30,
+  outputDir: "./output",
+  outputName: "recordable",
+  outputTimestamp: true, // prepend an ISO timestamp to the filename
+  headless: false,
+  typingSpeed: 7, // characters per second
+  videoCrf: 18, // lower = better quality, larger file
+  videoCodec: "libx264",
+  videoPreset: "ultrafast",
+  zoomDuration: 600, // ms
+  actionDelay: 300, // ms inserted between every action
+  silent: false,
+  autoScroll: true, // scroll elements into view before interacting
+  scrollMargin: 120, // px kept around an element when auto-scrolling
+  scrollSpeed: 1500, // px/s
+  scrollDuration: 1200, // ms for the scroll action's transition
+  cursor: true, // show the animated cursor overlay
+  visitTimeout: 30_000, // ms for navigation / waitFor
+});
+```
+
+## Development
+
+```sh
+npm install
+npm run build         # type-check + emit dist/ with .d.ts
+npm run gen:schema    # regenerate recordable.schema.json from the action manifest
+npx tsx my-script.ts  # run a recording script directly
+node dist/cli.js demo.json   # run a JSON script through the CLI locally
+```
+
+The JSON action set and its schema are both generated from one manifest in
+`src/actions.ts`; run `npm run gen:schema` after changing it.
+
+## License
+
+MIT © Cam Parry

package/dist/actions.d.ts

@@ -0,0 +1,140 @@
+import * as z from "zod";
+/**
+ * Per-action argument schema (the keyed args, excluding the `action`
+ * discriminator). strictObject so an unknown key (a typo) fails validation.
+ */
+declare const ACTIONS: {
+    pause: z.ZodObject<{}, z.core.$strict>;
+    resume: z.ZodObject<{}, z.core.$strict>;
+    resumeOnInput: z.ZodObject<{
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    insert: z.ZodObject<{
+        path: z.ZodString;
+        fadeIn: z.ZodOptional<z.ZodNumber>;
+        fadeOut: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    audio: z.ZodObject<{
+        path: z.ZodString;
+        wait: z.ZodOptional<z.ZodBoolean>;
+        volume: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    setConfig: z.ZodObject<{
+        config: z.ZodObject<{
+            viewport: z.ZodDefault<z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>>;
+            fps: z.ZodDefault<z.ZodNumber>;
+            outputDir: z.ZodDefault<z.ZodString>;
+            outputName: z.ZodDefault<z.ZodString>;
+            outputTimestamp: z.ZodDefault<z.ZodBoolean>;
+            assetsDir: z.ZodDefault<z.ZodString>;
+            headless: z.ZodDefault<z.ZodBoolean>;
+            launchArgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            typingSpeed: z.ZodDefault<z.ZodNumber>;
+            videoCrf: z.ZodDefault<z.ZodNumber>;
+            videoCodec: z.ZodDefault<z.ZodString>;
+            videoPreset: z.ZodDefault<z.ZodString>;
+            zoomDuration: z.ZodDefault<z.ZodNumber>;
+            actionDelay: z.ZodDefault<z.ZodNumber>;
+            silent: z.ZodDefault<z.ZodBoolean>;
+            autoScroll: z.ZodDefault<z.ZodBoolean>;
+            scrollMargin: z.ZodDefault<z.ZodNumber>;
+            scrollSpeed: z.ZodDefault<z.ZodNumber>;
+            scrollDuration: z.ZodDefault<z.ZodNumber>;
+            cursor: z.ZodDefault<z.ZodBoolean>;
+            visitTimeout: z.ZodDefault<z.ZodNumber>;
+            baseDir: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    visit: z.ZodObject<{
+        url: z.ZodString;
+        waitUntil: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        referer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    waitFor: z.ZodObject<{
+        target: z.ZodString;
+        state: z.ZodOptional<z.ZodEnum<{
+            visible: "visible";
+            hidden: "hidden";
+            present: "present";
+        }>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    click: z.ZodObject<{
+        target: z.ZodString;
+    }, z.core.$strict>;
+    hover: z.ZodObject<{
+        target: z.ZodString;
+    }, z.core.$strict>;
+    type: z.ZodObject<{
+        target: z.ZodString;
+        text: z.ZodString;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    clear: z.ZodObject<{
+        target: z.ZodString;
+    }, z.core.$strict>;
+    select: z.ZodObject<{
+        target: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>;
+    key: z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strict>;
+    mouse: z.ZodObject<{
+        target: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>;
+    scroll: z.ZodObject<{
+        target: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    zoom: z.ZodObject<{
+        level: z.ZodNumber;
+        origin: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    resetZoom: z.ZodObject<{
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    wait: z.ZodObject<{
+        ms: z.ZodNumber;
+    }, z.core.$strict>;
+};
+/** A single action: the action name plus its flat named arguments. */
+export type Action = {
+    action: string;
+    [key: string]: unknown;
+};
+/**
+ * Validate one keyed action against the manifest: the action must exist and its
+ * argument *values* (and key names) must match the action's schema — so a wrong
+ * type (`{ action: "zoom", level: "big" }`) or a typo'd key fails here. Shared by
+ * the JSON loader and the Markdown mapper.
+ */
+export declare function validateAction(step: Action): void;
+/**
+ * Turn one flat action into the positional argument list for its method.
+ *
+ * Optional positionals that are absent become `undefined` — JavaScript default
+ * parameters then apply, so a present later arg never lands in the wrong slot.
+ * Bag keys collapse into a single trailing options object.
+ */
+declare function buildArgs(step: Action, name: string): unknown[];
+/**
+ * Map a positional method call — `{ name, args }` as produced by the Markdown
+ * parser — onto a flat keyed {@link Action}, the same IR the JSON layer uses.
+ * Positional args are named by manifest order; a trailing options object is
+ * flattened to top-level keys. The result is validated, so value/key typos throw.
+ */
+export declare function callToAction(name: string, args: readonly unknown[]): Action;
+/** The action manifest, exported so schema/docs tooling can read it. */
+export { ACTIONS };
+/** Exported for unit tests: map a keyed action to its positional method args. */
+export { buildArgs };
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyD0B,CAAC;AAWxC,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"}

package/dist/actions.js

@@ -0,0 +1,184 @@
+import * as z from "zod";
+import { RecordableError } from "./errors.js";
+import { ConfigSchema } from "./config.js";
+// ─── Action model ────────────────────────────────────────────────────────────
+//
+// A single action is a flat `{ action, ...args }` object that maps ~1:1 onto the
+// chainable API. The ACTIONS manifest below is the single source of truth: one
+// Zod schema per action drives value-level validation, the published JSON Schema
+// (see schema.ts), and the Markdown marker mapping. The document that strings
+// actions together — the `Script` type and its helpers — lives in script.ts.
+const STATE = z.enum(["visible", "hidden", "present"]);
+const XY = z.strictObject({ x: z.number(), y: z.number() });
+/**
+ * Per-action argument schema (the keyed args, excluding the `action`
+ * discriminator). strictObject so an unknown key (a typo) fails validation.
+ */
+const ACTIONS = {
+    // Recording control
+    pause: z.strictObject({}),
+    resume: z.strictObject({}),
+    resumeOnInput: z.strictObject({ message: z.string().optional() }),
+    insert: z.strictObject({
+        path: z.string(),
+        fadeIn: z.number().optional(),
+        fadeOut: z.number().optional(),
+    }),
+    audio: z.strictObject({
+        path: z.string(),
+        wait: z.boolean().optional(),
+        volume: z.number().optional(),
+    }),
+    setConfig: z.strictObject({ config: ConfigSchema }),
+    // Navigation
+    visit: z.strictObject({
+        url: z.string(),
+        waitUntil: z.string().optional(),
+        timeout: z.number().optional(),
+        referer: z.string().optional(),
+    }),
+    waitFor: z.strictObject({
+        target: z.string(),
+        state: STATE.optional(),
+        timeout: z.number().optional(),
+    }),
+    // Interactions
+    click: z.strictObject({ target: z.string() }),
+    hover: z.strictObject({ target: z.string() }),
+    type: z.strictObject({
+        target: z.string(),
+        text: z.string(),
+        duration: z.number().optional(),
+    }),
+    clear: z.strictObject({ target: z.string() }),
+    select: z.strictObject({ target: z.string(), value: z.string() }),
+    key: z.strictObject({ key: z.string() }),
+    mouse: z.strictObject({ target: z.union([z.string(), XY]) }),
+    // Scrolling / zoom
+    scroll: z.strictObject({
+        target: z.union([z.string(), z.number()]),
+        duration: z.number().optional(),
+    }),
+    zoom: z.strictObject({
+        level: z.number(),
+        origin: z.string().optional(),
+        duration: z.number().optional(),
+    }),
+    resetZoom: z.strictObject({ duration: z.number().optional() }),
+    // Timing
+    wait: z.strictObject({ ms: z.number() }),
+};
+/**
+ * Keys that are optional yet passed *positionally* in Markdown method calls
+ * (rather than gathered into the trailing options bag) — the only per-action
+ * fact not derivable from the schema.
+ */
+const POSITIONAL_OPTIONAL = {
+    resumeOnInput: ["message"],
+};
+// ─── Manifest derivation ─────────────────────────────────────────────────────
+//
+// Positional/bag layout is derived from each action's Zod `.shape`: keys in
+// declaration order, with optionality read off `ZodOptional`.
+const shapeOf = (name) => ACTIONS[name].shape;
+/** All argument keys, in declaration order. */
+const keysInOrder = (name) => Object.keys(shapeOf(name));
+/** Whether `key` is optional for `name` (a `ZodOptional` in the shape). */
+const isOptional = (name, key) => shapeOf(name)[key] instanceof z.ZodOptional;
+/** Keys passed positionally: the required ones plus any flagged positional-optional. */
+const positionalKeys = (name) => keysInOrder(name).filter((k) => !isOptional(name, k) || POSITIONAL_OPTIONAL[name]?.includes(k));
+/** Keys gathered into the trailing options bag: optional and not positional. */
+const bagKeys = (name) => keysInOrder(name).filter((k) => isOptional(name, k) && !POSITIONAL_OPTIONAL[name]?.includes(k));
+/** One readable line per issue: `<path>: <message>`. */
+function formatIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+/**
+ * Validate one keyed action against the manifest: the action must exist and its
+ * argument *values* (and key names) must match the action's schema — so a wrong
+ * type (`{ action: "zoom", level: "big" }`) or a typo'd key fails here. Shared by
+ * the JSON loader and the Markdown mapper.
+ */
+export function validateAction(step) {
+    const schema = ACTIONS[step.action];
+    if (!schema) {
+        throw new RecordableError("CONFIG_INVALID", `Unknown action "${step.action}" — valid actions: ${Object.keys(ACTIONS).join(", ")}`);
+    }
+    const { action: _action, ...rest } = step;
+    const result = schema.safeParse(rest);
+    if (!result.success) {
+        throw new RecordableError("CONFIG_INVALID", `Action "${step.action}": ${formatIssues(result.error)}`);
+    }
+}
+/**
+ * Turn one flat action into the positional argument list for its method.
+ *
+ * Optional positionals that are absent become `undefined` — JavaScript default
+ * parameters then apply, so a present later arg never lands in the wrong slot.
+ * Bag keys collapse into a single trailing options object.
+ */
+function buildArgs(step, name) {
+    const args = [];
+    for (const key of positionalKeys(name))
+        args.push(step[key]);
+    const bag = bagKeys(name);
+    if (bag.length) {
+        const opts = {};
+        for (const key of bag)
+            if (key in step)
+                opts[key] = step[key];
+        args.push(Object.keys(opts).length ? opts : undefined);
+    }
+    // Trim trailing undefineds so the method's own defaults apply cleanly.
+    while (args.length && args[args.length - 1] === undefined)
+        args.pop();
+    return args;
+}
+/**
+ * Map a positional method call — `{ name, args }` as produced by the Markdown
+ * parser — onto a flat keyed {@link Action}, the same IR the JSON layer uses.
+ * Positional args are named by manifest order; a trailing options object is
+ * flattened to top-level keys. The result is validated, so value/key typos throw.
+ */
+export function callToAction(name, args) {
+    const schema = ACTIONS[name];
+    if (!schema) {
+        throw new Error(`Unknown action "${name}" — valid actions: ${Object.keys(ACTIONS).join(", ")}`);
+    }
+    const step = { action: name };
+    let i = 0;
+    for (const key of positionalKeys(name)) {
+        if (i < args.length)
+            step[key] = args[i++];
+        else if (!isOptional(name, key))
+            throw new Error(`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)}`);
+        }
+        for (const [k, v] of Object.entries(obj)) {
+            if (!bag.includes(k)) {
+                throw new Error(`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})`);
+    }
+    validateAction(step);
+    return step;
+}
+/** The action manifest, exported so schema/docs tooling can read it. */
+export { ACTIONS };
+/** Exported for unit tests: map a keyed action to its positional method args. */
+export { buildArgs };
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}