recordable 0.1.0

package/dist/compose/session.js

@@ -0,0 +1,122 @@
+import puppeteer from "puppeteer";
+import { join } from "node:path";
+import { sleep } from "../utils.js";
+import { getOutputPath } from "../fs.js";
+import { RecordableError } from "../errors.js";
+import { stitch } from "../video/stitch.js";
+import { addAudio } from "./mix.js";
+export class Session {
+    comp;
+    browser = null;
+    outputPath = "";
+    finalised = false;
+    constructor(comp) {
+        this.comp = comp;
+    }
+    /** Execute the queued action sequence, then finalise the recording. */
+    async run() {
+        const { log, recorder, runtime } = this.comp;
+        log("Start", "recording…");
+        let ok = true;
+        this.outputPath = getOutputPath(this.comp.cfg);
+        recorder.init();
+        const cfg = this.comp.cfg;
+        try {
+            this.browser = await puppeteer.launch({
+                headless: cfg.headless,
+                args: [
+                    `--window-size=${cfg.viewport.width},${cfg.viewport.height}`,
+                    ...cfg.launchArgs,
+                ],
+            });
+        }
+        catch (err) {
+            throw new RecordableError("BROWSER_LAUNCH", `Could not launch Chromium: ${err.message}. ` +
+                `In CI/containers add launchArgs: ["--no-sandbox"].`, { cause: err });
+        }
+        const page = await this.browser.newPage();
+        await page.setViewport({ ...cfg.viewport, deviceScaleFactor: 1 });
+        // A navigation wipes the in-page cursor overlay and any zoom transform.
+        // Re-inject (at the carried position) and reset zoom on every main-frame nav,
+        // so click-triggered navigations stay covered without an explicit re-inject.
+        if (cfg.cursor) {
+            page.on("framenavigated", (frame) => {
+                if (frame !== page.mainFrame())
+                    return;
+                runtime.resetZoomState();
+                // Only mask the real pointer while recording — a paused / wait-for-user
+                // step is driven by hand, so the `cursor: none` overlay stays off.
+                if (!this.comp.recording)
+                    return;
+                void runtime.injectCursor(page).catch(() => { });
+            });
+        }
+        // Finalise the recording and close the browser on SIGINT / SIGTERM.
+        const onSignal = () => {
+            log("Signal", "finalising recording…");
+            this._cleanup().finally(() => process.exit(0));
+        };
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+        try {
+            for (const item of this.comp.queue) {
+                // Lazily begin a segment before the first capture-worthy action while
+                // recording is intended — keeps a leading pause() from making an empty clip.
+                if (!item.control && this.comp.recording && !recorder.capturing) {
+                    await recorder.begin(page);
+                }
+                await item.run(page);
+                if (this.comp.cfg.actionDelay > 0)
+                    await sleep(this.comp.cfg.actionDelay);
+            }
+        }
+        catch (err) {
+            ok = false;
+            log.error(String(err));
+        }
+        finally {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            await this._cleanup();
+            log("Output", this.outputPath);
+            // Bookends the "Start" line; green only when the run actually succeeded.
+            if (ok)
+                log.success("Done", "recording complete");
+        }
+    }
+    async _cleanup() {
+        await this._finalize();
+        await this.comp.recorder.dispose();
+        if (this.browser) {
+            await this.browser.close().catch(() => { });
+            this.browser = null;
+        }
+    }
+    /** Seal the recording: stitch the captured/inserted segments (video layer),
+     *  then mix the audio track onto them (audio layer). The video defines the
+     *  length. Idempotent — a signal handler and the normal path both call it. */
+    async _finalize() {
+        if (this.finalised)
+            return;
+        this.finalised = true;
+        const { recorder, audioTrack, cfg, log } = this.comp;
+        await recorder.end();
+        const segs = recorder.segments;
+        if (segs.length === 0) {
+            log("Record", "nothing was recorded — no output written");
+            recorder.removeTmp();
+            return;
+        }
+        // With audio, render the silent video to a temp file then mix onto it;
+        // otherwise stitch straight to the output.
+        const needAudio = audioTrack.length > 0;
+        const videoOut = needAudio
+            ? join(recorder.tmpDir, "video.mp4")
+            : this.outputPath;
+        await stitch(segs, cfg, log, videoOut, recorder.tmpDir);
+        if (needAudio)
+            await addAudio(videoOut, audioTrack.list(), this.outputPath, log);
+        recorder.removeTmp();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/compose/session.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,93 @@
+import * as z from "zod";
+/** strictObject so an unknown key (usually a typo) fails validation, matching
+ *  the `additionalProperties: false` of the generated config schema. */
+export declare const ConfigSchema: 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>;
+/** Public config input — every field optional (defaults fill the rest). */
+export type RecordableConfig = z.input<typeof ConfigSchema>;
+/** The full config with every field resolved — what the running instance holds. */
+export type ResolvedConfig = z.output<typeof ConfigSchema>;
+/** Default values for every config option (the schema's defaults, resolved). */
+export declare const DEFAULT_CONFIG: ResolvedConfig;
+/**
+ * Voiceover settings, carried in Markdown frontmatter (non-secret only — the API
+ * key comes from the environment). Consumed by the optional voiceover add-on;
+ * core only needs the type to round-trip frontmatter.
+ */
+export interface VoiceoverConfig {
+    /** TTS backend. Omit to take `RECORDABLE_TTS_PROVIDER` (default: elevenlabs). */
+    provider?: string;
+    /** Voice to synthesize with. Omit to take `RECORDABLE_VOICE_ID`. */
+    voiceId?: string;
+    /** Omit to take `RECORDABLE_MODEL_ID`, else the provider default. */
+    modelId?: string;
+    /** Prefer `ELEVENLABS_API_KEY` in the environment over inlining a key here. */
+    apiKey?: string;
+    voiceSettings?: Record<string, number>;
+    format?: string;
+}
+/** Options for `Recordable.insert`. Cross-fade durations are in milliseconds. */
+export interface InsertOptions {
+    /**
+     * Cross-fade *into* the clip over this many ms — dissolves from the preceding
+     * recorded segment, or fades up from black when the clip is first (an intro).
+     * Default: 0 (hard cut).
+     */
+    fadeIn?: number;
+    /**
+     * Cross-fade *out of* the clip over this many ms — dissolves into the
+     * following recorded segment, or fades to black when the clip is last (an
+     * outro). Default: 0 (hard cut).
+     */
+    fadeOut?: number;
+}
+/** Options for `Recordable.audio`. */
+export interface AudioOptions {
+    /**
+     * Block the chain until the clip finishes playing (an implicit `wait` for the
+     * clip's duration), so following actions land after it. Default: true. Set
+     * false for voiceover, where the clip plays *over* interleaved actions whose
+     * timing you (or the compiler) control with explicit `wait`s.
+     */
+    wait?: boolean;
+    /** Linear gain applied to the clip (1 = unchanged). Default: 1. */
+    volume?: number;
+}
+/** Options for `Recordable.waitFor`. */
+export interface WaitForOptions {
+    /**
+     * What to wait for:
+     * - `"visible"` (default) — element is present *and* rendered
+     * - `"hidden"`            — element is absent or not rendered
+     * - `"present"`           — element is attached to the DOM (may be hidden)
+     */
+    state?: "visible" | "hidden" | "present";
+    /** Timeout in ms. Default: the `visitTimeout` config value. */
+    timeout?: number;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAUzB;wEACwE;AACxE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkDvB,CAAC;AAEH,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAE5D,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAE3D,gFAAgF;AAChF,eAAO,MAAM,cAAc,EAAE,cAAuC,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IACzC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/config.js

@@ -0,0 +1,64 @@
+import * as z from "zod";
+// ─── Config ──────────────────────────────────────────────────────────────────
+//
+// `ConfigSchema` is the single source of truth for the recording config: the
+// public input type, the fully-resolved type, the default values, and the
+// generated JSON Schema (`schema.ts`) are all derived from it. Each field's
+// `.default(...)` is the default; the doc comment above it is the user-facing
+// documentation.
+/** strictObject so an unknown key (usually a typo) fails validation, matching
+ *  the `additionalProperties: false` of the generated config schema. */
+export const ConfigSchema = z.strictObject({
+    /** Browser viewport dimensions. Default: 1920×1080 */
+    viewport: z
+        .strictObject({ width: z.number(), height: z.number() })
+        .default({ width: 1920, height: 1080 }),
+    /** Recording frame rate. Default: 30 */
+    fps: z.number().default(30),
+    /** Output directory. Relative paths resolve against `baseDir`. Default: output */
+    outputDir: z.string().default("output"),
+    /** Base filename (without extension or timestamp). Default: recordable */
+    outputName: z.string().default("recordable"),
+    /** Prepend an ISO timestamp to the filename. Default: true */
+    outputTimestamp: z.boolean().default(true),
+    /** Where generated voiceover audio is written (voiceover documents only).
+     *  Relative paths resolve against `baseDir`. Default: assets */
+    assetsDir: z.string().default("assets"),
+    /** Run without a visible browser window. Default: false */
+    headless: z.boolean().default(false),
+    /** Extra Chromium flags appended to the launch args, e.g. `["--no-sandbox"]`
+     *  for CI / containers / sandboxed environments. Default: [] */
+    launchArgs: z.array(z.string()).default([]),
+    /** Typing speed in characters per second. Higher = faster. Default: 7 */
+    typingSpeed: z.number().default(7),
+    /** Constant Rate Factor — lower = better quality, larger file. Default: 18 */
+    videoCrf: z.number().default(18),
+    /** FFmpeg video codec. Default: libx264 */
+    videoCodec: z.string().default("libx264"),
+    /** FFmpeg encoding preset. Default: ultrafast */
+    videoPreset: z.string().default("ultrafast"),
+    /** Default zoom transition duration in ms. Default: 600 */
+    zoomDuration: z.number().default(600),
+    /** Automatic pause inserted between every action in ms. Default: 300 */
+    actionDelay: z.number().default(300),
+    /** Suppress all console output. Default: false */
+    silent: z.boolean().default(false),
+    /** Automatically scroll an element into view before clicking or typing. Default: true */
+    autoScroll: z.boolean().default(true),
+    /** Minimum viewport margin (px) kept above/below element when auto-scrolling. Default: 120 */
+    scrollMargin: z.number().default(120),
+    /** Auto-scroll speed in px/s — faster = snappier short scrolls. Default: 1500 */
+    scrollSpeed: z.number().default(1500),
+    /** Default `scroll` action transition duration in ms. Default: 1200 */
+    scrollDuration: z.number().default(1200),
+    /** Show an animated cursor overlay that moves to elements before interacting. Default: true */
+    cursor: z.boolean().default(true),
+    /** Timeout in ms for page navigation. Default: 30000 */
+    visitTimeout: z.number().default(30_000),
+    /** Directory that relative `visit` URLs, `outputDir`, and `assetsDir` resolve
+     *  against (e.g. the script file's folder). Default: "" → resolve against cwd. */
+    baseDir: z.string().default(""),
+});
+/** Default values for every config option (the schema's defaults, resolved). */
+export const DEFAULT_CONFIG = ConfigSchema.parse({});
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/** Stable, machine-readable failure categories. */
+export type ErrorCode = "CONFIG_INVALID" | "FILE_NOT_FOUND" | "FFMPEG_FAILED" | "TTS_FAILED" | "BROWSER_LAUNCH";
+/** An expected, user-facing failure. `message` should say what went wrong *and*
+ *  how to fix it; `cause` keeps the original error for debugging. */
+export declare class RecordableError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** True for our own expected failures — the CLI prints these without a stack. */
+export declare function isRecordableError(err: unknown): err is RecordableError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,mDAAmD;AACnD,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,YAAY,GACZ,gBAAgB,CAAC;AAErB;qEACqE;AACrE,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,SAAS;gBAAf,IAAI,EAAE,SAAS,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAKpC;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAEtE"}

package/dist/errors.js

@@ -0,0 +1,21 @@
+// ─── Errors ──────────────────────────────────────────────────────────────────
+//
+// One error type for every *expected* failure — bad config, a missing file, an
+// ffmpeg/TTS/browser failure. Carrying a `code` lets the CLI print a clean,
+// actionable line (no stack trace) and lets callers branch on the cause. Genuine
+// bugs stay plain `Error`s so their stack still surfaces.
+/** An expected, user-facing failure. `message` should say what went wrong *and*
+ *  how to fix it; `cause` keeps the original error for debugging. */
+export class RecordableError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.code = code;
+        this.name = "RecordableError";
+    }
+}
+/** True for our own expected failures — the CLI prints these without a stack. */
+export function isRecordableError(err) {
+    return err instanceof RecordableError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0DAA0D;AAU1D;qEACqE;AACrE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B;IADX,YACW,IAAe,EACxB,OAAe,EACf,UAA+B,EAAE;QAEjC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAJf,SAAI,GAAJ,IAAI,CAAW;QAKxB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,GAAG,YAAY,eAAe,CAAC;AACxC,CAAC"}

package/dist/ffmpeg.d.ts

@@ -0,0 +1,8 @@
+/** Probe a clip's duration in seconds by parsing ffmpeg's stderr banner. 0 if unreadable. */
+export declare function getDuration(path: string): Promise<number>;
+export declare const FFMPEG_PATH: string;
+/** Run ffmpeg to completion. Resolves on exit code 0; on a non-zero exit or a
+ *  spawn failure rejects with a {@link RecordableError} carrying the stderr tail,
+ *  so the real cause (bad filter, missing codec, unreadable input) is visible. */
+export declare function runFfmpeg(args: string[]): Promise<void>;
+//# sourceMappingURL=ffmpeg.d.ts.map

package/dist/ffmpeg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../src/ffmpeg.ts"],"names":[],"mappings":"AAIA,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAazD;AAYD,eAAO,MAAM,WAAW,QAAsB,CAAC;AAS/C;;kFAEkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBvD"}

package/dist/ffmpeg.js

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { RecordableError } from "./errors.js";
+/** Probe a clip's duration in seconds by parsing ffmpeg's stderr banner. 0 if unreadable. */
+export function getDuration(path) {
+    return new Promise((resolve) => {
+        const proc = spawn(FFMPEG_PATH, ["-i", path], {
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        let err = "";
+        proc.stderr?.on("data", (d) => (err += String(d)));
+        proc.on("error", () => resolve(0));
+        proc.on("close", () => {
+            const m = err.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/);
+            resolve(m ? +m[1] * 3600 + +m[2] * 60 + parseFloat(m[3]) : 0);
+        });
+    });
+}
+// Prefer the ffmpeg binary bundled by @ffmpeg-installer/ffmpeg; fall back to a
+// system `ffmpeg` on PATH if it isn't present for some reason.
+function resolveFfmpegPath() {
+    try {
+        return createRequire(import.meta.url)("@ffmpeg-installer/ffmpeg").path;
+    }
+    catch {
+        return "ffmpeg";
+    }
+}
+export const FFMPEG_PATH = resolveFfmpegPath();
+/** Tail of an ffmpeg stderr stream — the last `max` non-blank lines, where the
+ *  actual error usually lives (the rest is the version/config banner). */
+function tail(text, max = 8) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim());
+    return lines.slice(-max).join("\n");
+}
+/** Run ffmpeg to completion. Resolves on exit code 0; on a non-zero exit or a
+ *  spawn failure rejects with a {@link RecordableError} carrying the stderr tail,
+ *  so the real cause (bad filter, missing codec, unreadable input) is visible. */
+export function runFfmpeg(args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(FFMPEG_PATH, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let err = "";
+        proc.stderr?.on("data", (d) => (err += String(d)));
+        proc.on("error", (e) => reject(new RecordableError("FFMPEG_FAILED", `Could not run ffmpeg: ${e.message}`, {
+            cause: e,
+        })));
+        proc.on("close", (code) => {
+            if (code === 0)
+                return resolve();
+            const detail = tail(err);
+            reject(new RecordableError("FFMPEG_FAILED", `ffmpeg exited with code ${code}${detail ? `:\n${detail}` : ""}`));
+        });
+    });
+}
+//# sourceMappingURL=ffmpeg.js.map

package/dist/ffmpeg.js.map

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

package/dist/formats/json.d.ts

@@ -0,0 +1,12 @@
+import { Recordable } from "../compose/recordable.js";
+import type { RecordableConfig } from "../config.js";
+import type { Script } from "../script.js";
+/**
+ * Build a {@link Recordable} from a JSON script without running it — a thin
+ * wrapper over `new Recordable(configOverride).fromJSON(script)`. `configOverride`
+ * (the explicit/programmatic config) wins over the script's own `config`.
+ */
+export declare function fromJSON(script: Script | string, configOverride?: RecordableConfig): Recordable;
+/** Build a {@link Recordable} from a JSON script and run it to completion. */
+export declare function runScript(script: Script | string, configOverride?: RecordableConfig): Promise<void>;
+//# sourceMappingURL=json.d.ts.map

package/dist/formats/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/formats/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAS3C;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,cAAc,GAAE,gBAAqB,GACpC,UAAU,CAEZ;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,cAAc,CAAC,EAAE,gBAAgB,GAChC,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/formats/json.js

@@ -0,0 +1,20 @@
+import { Recordable } from "../compose/recordable.js";
+// ─── JSON authoring format ───────────────────────────────────────────────────
+//
+// The declarative JSON entry points: turn a `Script` (a bare action array, a
+// `{ config, actions }` object, or a raw JSON string) into a Recordable. The
+// shared action model — the ACTIONS manifest, validation, and call→action
+// mapping — lives in `../actions.ts`; this file is just the JSON doorway.
+/**
+ * Build a {@link Recordable} from a JSON script without running it — a thin
+ * wrapper over `new Recordable(configOverride).fromJSON(script)`. `configOverride`
+ * (the explicit/programmatic config) wins over the script's own `config`.
+ */
+export function fromJSON(script, configOverride = {}) {
+    return new Recordable(configOverride).fromJSON(script);
+}
+/** Build a {@link Recordable} from a JSON script and run it to completion. */
+export function runScript(script, configOverride) {
+    return fromJSON(script, configOverride).run();
+}
+//# sourceMappingURL=json.js.map

package/dist/formats/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/formats/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAItD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,0EAA0E;AAE1E;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAuB,EACvB,iBAAmC,EAAE;IAErC,OAAO,IAAI,UAAU,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CACvB,MAAuB,EACvB,cAAiC;IAEjC,OAAO,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,GAAG,EAAE,CAAC;AAChD,CAAC"}

package/dist/formats/markdown/method.d.ts

@@ -0,0 +1,25 @@
+/** One parsed method call: the method name and its evaluated arguments. */
+export interface MethodCall {
+    name: string;
+    args: unknown[];
+}
+/** True if a string looks like a method call — `ident(` at the start. */
+export declare function isMethodCall(src: string): boolean;
+/**
+ * Parse a string holding exactly one method call (`name(args)`). The name leads,
+ * its argument list is delimited by the first `(` and the trailing `)`, and the
+ * arguments are parsed as JSON5. Throws if the string is not a single call.
+ */
+export declare function parseMethodCall(src: string): MethodCall;
+/**
+ * Parse a fenced code block: one method call per non-blank line, in order. Each
+ * line is an independent call (no line may carry two), which is what makes
+ * splitting on newlines sufficient.
+ */
+export declare function parseMethodCalls(src: string): MethodCall[];
+/**
+ * Parse the comma-separated argument list inside a call's parens. The list is a
+ * JS array literal minus its brackets, so we wrap and parse it as JSON5.
+ */
+export declare function parseArgList(src: string): unknown[];
+//# sourceMappingURL=method.d.ts.map

package/dist/formats/markdown/method.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../src/formats/markdown/method.ts"],"names":[],"mappings":"AAgBA,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAUvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAM1D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE,CAUnD"}

package/dist/formats/markdown/method.js

@@ -0,0 +1,48 @@
+import JSON5 from "json5";
+/** True if a string looks like a method call — `ident(` at the start. */
+export function isMethodCall(src) {
+    return /^\s*[A-Za-z_]\w*\s*\(/.test(src);
+}
+/**
+ * Parse a string holding exactly one method call (`name(args)`). The name leads,
+ * its argument list is delimited by the first `(` and the trailing `)`, and the
+ * arguments are parsed as JSON5. Throws if the string is not a single call.
+ */
+export function parseMethodCall(src) {
+    const s = src.trim();
+    const head = /^([A-Za-z_]\w*)\s*\(/.exec(s);
+    if (!head)
+        throw new Error(`Not a method call: ${src.trim()}`);
+    if (!s.endsWith(")"))
+        throw new Error(`A method call must end with ")": ${src.trim()}`);
+    const open = head[0].length - 1; // index of the first "("
+    const close = s.length - 1; // index of the trailing ")"
+    return { name: head[1], args: parseArgList(s.slice(open + 1, close)) };
+}
+/**
+ * Parse a fenced code block: one method call per non-blank line, in order. Each
+ * line is an independent call (no line may carry two), which is what makes
+ * splitting on newlines sufficient.
+ */
+export function parseMethodCalls(src) {
+    return src
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "")
+        .map(parseMethodCall);
+}
+/**
+ * Parse the comma-separated argument list inside a call's parens. The list is a
+ * JS array literal minus its brackets, so we wrap and parse it as JSON5.
+ */
+export function parseArgList(src) {
+    if (src.trim() === "")
+        return [];
+    try {
+        return JSON5.parse(`[${src}]`);
+    }
+    catch (e) {
+        throw new Error(`Invalid arguments "${src.trim()}": ${e.message}`, { cause: e });
+    }
+}
+//# sourceMappingURL=method.js.map

package/dist/formats/markdown/method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method.js","sourceRoot":"","sources":["../../../src/formats/markdown/method.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAsB1B,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,MAAM,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAEpE,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,yBAAyB;IAC1D,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,4BAA4B;IACxD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG;SACP,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;SAC7B,GAAG,CAAC,eAAe,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,CAAC,IAAI,EAAE,MAAO,CAAW,CAAC,OAAO,EAAE,EAC5D,EAAE,KAAK,EAAE,CAAC,EAAE,CACb,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/formats/markdown/parse.d.ts

@@ -0,0 +1,44 @@
+import { type Action } from "../../actions.js";
+import type { RecordableConfig, VoiceoverConfig } from "../../config.js";
+/** A marker: one call lifted out of narration, with its position in the prose. */
+export interface Marker {
+    step: Action;
+    /** Character offset of the marker within the stripped narration (markers removed). */
+    offset: number;
+}
+/** A prose paragraph: the narration TTS will read, plus its inline markers. */
+export interface NarrationBlock {
+    type: "narration";
+    narration: string;
+    markers: Marker[];
+}
+/** A fenced code block: a pure ordered action list, no narration or timing. */
+export interface ActionsBlock {
+    type: "actions";
+    actions: Action[];
+}
+export type MarkdownBlock = NarrationBlock | ActionsBlock;
+/** The fully parsed document: recording config, optional voiceover, blocks. */
+export interface ParsedMarkdown {
+    config: RecordableConfig;
+    voiceover?: VoiceoverConfig;
+    blocks: MarkdownBlock[];
+}
+/**
+ * Parse a Markdown document into config + ordered blocks. Pure: no audio, no
+ * network. Frontmatter (YAML, via gray-matter) carries recording config and an
+ * optional `voiceover` block; everything else is body content.
+ */
+export declare function parseMarkdown(md: string): ParsedMarkdown;
+/**
+ * Turn one prose paragraph into narration + markers. Call-shaped backtick spans
+ * are lifted out as markers; their character offset into the *stripped*
+ * narration (what TTS reads) is preserved for the compiler. Non-call backtick
+ * spans stay in the prose verbatim. Whitespace is collapsed without shifting any
+ * recorded offset.
+ */
+export declare function narrationBlock(raw: string): NarrationBlock;
+/** Extract a plain action list from parsed blocks (markers in order, narration
+ *  and timing discarded; no audio). */
+export declare function extractActions(blocks: MarkdownBlock[]): Action[];
+//# sourceMappingURL=parse.d.ts.map

package/dist/formats/markdown/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/formats/markdown/parse.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA0BzE,kFAAkF;AAClF,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,YAAY,CAAC;AAE1D,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAqBxD;AA0BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAE1D;AAuDD;uCACuC;AACvC,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAOhE"}