recordable 0.1.0

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

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

package/dist/browser/runtime.js

@@ -0,0 +1,271 @@
+import { sleep, truncate } from "../utils.js";
+import { resolveTarget } from "../targets.js";
+import { getElementCenter, originToCoords, scrollIntoView, smoothScrollToTarget, } from "./dom.js";
+import { Cursor } from "./cursor.js";
+import { jitter, typingDuration, typingGaps, NAV_PROBE_MS, PRE_CLICK_MS, } from "../timing.js";
+import { playButtonScript, PLAY_BINDING, PLAY_BUTTON_ID, } from "./play-button.js";
+// ─── Compose layer: the runtime ──────────────────────────────────────────────
+//
+// *How* each action is performed on a live page — clicks, typing, scrolling,
+// zooming, the cursor overlay, the resume gate. It owns the cursor and the zoom
+// transform state (both per-page concerns); the builder enqueues calls to these
+// methods, and the session drives them. No queue, no recorder, no recording flag
+// here — purely page interaction.
+export class Runtime {
+    getCfg;
+    log;
+    cursor = new Cursor();
+    zoom = { tx: 0, ty: 0, s: 1 };
+    // Play-button bridge state (the resume gate).
+    playResolver = null;
+    playBindingExposed = false;
+    constructor(getCfg, log) {
+        this.getCfg = getCfg;
+        this.log = log;
+    }
+    /** The current zoom transform — the session re-reads it when re-injecting the
+     *  cursor overlay across navigations. */
+    get zoomState() {
+        return this.zoom;
+    }
+    /** Drop any zoom transform (a fresh document carries none). */
+    resetZoomState() {
+        this.zoom = { tx: 0, ty: 0, s: 1 };
+    }
+    /** (Re-)inject the cursor overlay at the carried position, if enabled. */
+    async injectCursor(page) {
+        if (this.getCfg().cursor)
+            await this.cursor.inject(page, this.zoom);
+    }
+    // ─── Navigation ────────────────────────────────────────────────────────────
+    async visit(page, url, options) {
+        this.log("Visit", url);
+        await page.goto(url, {
+            waitUntil: "networkidle2",
+            timeout: this.getCfg().visitTimeout,
+            ...options,
+        });
+        // A fresh document carries no zoom transform — drop any stale state so the
+        // overlay (and later moves) position against the new page's viewport.
+        this.resetZoomState();
+        await this.injectCursor(page);
+    }
+    async waitFor(page, target, options = {}) {
+        const { state = "visible", timeout = this.getCfg().visitTimeout } = options;
+        this.log("WaitFor", `${target} (${state})`);
+        await page.waitForSelector(resolveTarget(target), {
+            timeout,
+            visible: state === "visible",
+            hidden: state === "hidden",
+        });
+        await this.injectCursor(page);
+    }
+    // ─── Interactions ──────────────────────────────────────────────────────────
+    async click(page, target) {
+        this.log("Click", target);
+        await this._click(page, target);
+    }
+    async hover(page, target) {
+        this.log("Hover", target);
+        if (this.getCfg().autoScroll)
+            await this._scrollIntoView(page, target);
+        const { x, y } = await getElementCenter(page, target);
+        await this._moveTo(page, x, y);
+    }
+    async type(page, target, text, options = {}) {
+        this.log("Type", `${target}  "${truncate(text)}"`);
+        await this._click(page, target);
+        const total = options.duration ?? typingDuration(text, this.getCfg().typingSpeed);
+        const gaps = typingGaps(text, this.getCfg().typingSpeed, total);
+        if (gaps.length === 0)
+            return;
+        await sleep(gaps[0]); // lead beat before the first keystroke
+        let i = 1;
+        for (const char of text) {
+            await page.keyboard.type(char);
+            await sleep(gaps[i++] ?? 0);
+        }
+    }
+    async clear(page, target) {
+        this.log("Clear", target);
+        await this._click(page, target);
+        const mod = process.platform === "darwin" ? "Meta" : "Control";
+        await page.keyboard.down(mod);
+        await page.keyboard.press("KeyA");
+        await page.keyboard.up(mod);
+        await page.keyboard.press("Backspace");
+    }
+    async select(page, target, value) {
+        this.log("Select", `${target}  ${value}`);
+        if (this.getCfg().autoScroll)
+            await this._scrollIntoView(page, target);
+        const { x, y } = await getElementCenter(page, target);
+        if (this.getCfg().cursor) {
+            await this.cursor.moveTo(page, x, y, this.zoom);
+            await sleep(jitter(PRE_CLICK_MS));
+            await this.cursor.clickEffect(page);
+        }
+        await page.select(target, value);
+    }
+    async key(page, key) {
+        this.log("Key", key);
+        await page.keyboard.press(key);
+    }
+    async mouse(page, target) {
+        const { x, y } = typeof target === "string"
+            ? await getElementCenter(page, target)
+            : target;
+        this.log("Mouse", typeof target === "string" ? target : `(${x}, ${y})`);
+        await this._moveTo(page, x, y);
+    }
+    // ─── Scrolling ─────────────────────────────────────────────────────────────
+    async scroll(page, target, options = {}) {
+        this.log("Scroll", String(target));
+        await smoothScrollToTarget(page, target, options.duration ?? this.getCfg().scrollDuration);
+    }
+    // ─── Zoom ──────────────────────────────────────────────────────────────────
+    async zoomTo(page, level, options = {}) {
+        const { origin = "center", duration } = options;
+        this.log("Zoom", `${level}x  ${origin}`);
+        const dur = duration ?? this.getCfg().zoomDuration;
+        const { x, y } = await originToCoords(page, origin);
+        // Express zoom as translate()+scale() on a 0,0 origin so that a single CSS
+        // `transform` transition smoothly animates both level and origin.
+        const tx = x * (1 - level);
+        const ty = y * (1 - level);
+        this.zoom = { tx, ty, s: level };
+        await page.evaluate(({ tx, ty, level, dur }) => new Promise((resolve) => {
+            const root = document.documentElement;
+            root.style.transformOrigin = "0 0";
+            root.style.transition = `transform ${dur}ms ease-in-out`;
+            root.style.transform = `translate(${tx}px, ${ty}px) scale(${level})`;
+            setTimeout(resolve, dur + 50);
+        }), { tx, ty, level, dur });
+    }
+    async resetZoom(page, options = {}) {
+        this.log("Zoom", "reset");
+        this.resetZoomState();
+        const dur = options.duration ?? this.getCfg().zoomDuration;
+        await page.evaluate((dur) => new Promise((resolve) => {
+            const root = document.documentElement;
+            root.style.transition = `transform ${dur}ms ease-in-out`;
+            root.style.transform = "none";
+            setTimeout(() => {
+                root.style.transition = "";
+                root.style.transformOrigin = "";
+                resolve();
+            }, dur + 50);
+        }), dur);
+    }
+    // ─── Private interaction helpers ─────────────────────────────────────────────
+    /** Click a target's centre. Uses page.mouse.click() not ElementHandle.click()
+     *  to avoid Puppeteer's built-in scrollIntoView overriding our centred scroll. */
+    async _click(page, target) {
+        if (this.getCfg().autoScroll)
+            await this._scrollIntoView(page, target);
+        const { x, y } = await getElementCenter(page, target);
+        if (this.getCfg().cursor) {
+            await this.cursor.moveTo(page, x, y, this.zoom);
+            await sleep(jitter(PRE_CLICK_MS));
+            await this.cursor.clickEffect(page);
+        }
+        await this._clickPoint(page, x, y);
+    }
+    /**
+     * Click at viewport coords and, if the click triggers a navigation, wait for the
+     * new page to settle before returning — so a navigating `click()` behaves like a
+     * `visit()` and the next action lands on the loaded page rather than racing it.
+     * In-page clicks pay only a short probe.
+     */
+    async _clickPoint(page, x, y) {
+        let navStarted = false;
+        const onNav = (frame) => {
+            if (frame === page.mainFrame())
+                navStarted = true;
+        };
+        page.on("framenavigated", onNav);
+        try {
+            await page.mouse.click(x, y);
+            // Give a navigation a brief moment to commit; most clicks don't navigate,
+            // so we can't block on a full navigation wait unconditionally.
+            await sleep(NAV_PROBE_MS);
+            if (navStarted) {
+                await page
+                    .waitForNetworkIdle({
+                    idleTime: 500,
+                    timeout: this.getCfg().visitTimeout,
+                })
+                    .catch(() => { });
+            }
+        }
+        finally {
+            page.off("framenavigated", onNav);
+        }
+    }
+    /** Move to viewport coords, animating the overlay when the cursor is enabled. */
+    async _moveTo(page, x, y) {
+        if (this.getCfg().cursor)
+            await this.cursor.moveTo(page, x, y, this.zoom);
+        else
+            await page.mouse.move(x, y);
+    }
+    /** Scroll a target into view using the configured margin/speed. */
+    _scrollIntoView(page, target) {
+        const cfg = this.getCfg();
+        return scrollIntoView(page, target, cfg.scrollMargin, cfg.scrollSpeed);
+    }
+    // ─── Resume gate (▶ Play button) ─────────────────────────────────────────────
+    /**
+     * Block until the user resumes — by clicking the in-page ▶ Play button, or by
+     * pressing Enter in the *terminal*. The in-page button is click-only so the live
+     * page keeps its own keyboard (Enter to submit a form, etc.); the terminal
+     * fallback means a resume is still reachable if the button fails to render.
+     */
+    async waitForPlay(page, message) {
+        let settle;
+        const played = new Promise((resolve) => (settle = resolve));
+        // Bridge page → Node: the button's click handler calls window[PLAY_BINDING],
+        // which fires this exposed function. Exposed functions survive navigations, so
+        // expose once and reuse across calls.
+        this.playResolver = settle;
+        if (!this.playBindingExposed) {
+            await page.exposeFunction(PLAY_BINDING, () => this.playResolver?.());
+            this.playBindingExposed = true;
+        }
+        // Terminal fallback: resume on Enter from stdin (TTY only). Works even if the
+        // in-page button never renders.
+        const stdin = process.stdin;
+        const onStdin = (chunk) => {
+            if (chunk.includes(0x0a) || chunk.includes(0x0d))
+                settle();
+        };
+        const stdinFallback = Boolean(stdin.isTTY);
+        if (stdinFallback) {
+            stdin.resume();
+            stdin.on("data", onStdin);
+        }
+        // Inject the button now, and on every future document so it survives the
+        // navigations of a login flow. A failure here is non-fatal — the terminal
+        // fallback still resumes — but surface it so a broken button is visible.
+        const script = playButtonScript(message, PLAY_BUTTON_ID, PLAY_BINDING);
+        const { identifier } = await page.evaluateOnNewDocument(script);
+        await page
+            .evaluate(script)
+            .catch((e) => this.log.warn(`could not inject ▶ Play button: ${String(e)}`));
+        this.log("Resume", stdinFallback
+            ? "waiting for ▶ Play (or press Enter here)…"
+            : "waiting for ▶ Play…");
+        await played;
+        // Clean up: stop the stdin listener, stop re-injecting, remove the button.
+        this.playResolver = null;
+        if (stdinFallback) {
+            stdin.off("data", onStdin);
+            stdin.pause();
+        }
+        await page.removeScriptToEvaluateOnNewDocument(identifier).catch(() => { });
+        await page
+            .evaluate((id) => document.getElementById(id)?.remove(), PLAY_BUTTON_ID)
+            .catch(() => { });
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/browser/runtime.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve, basename, dirname } from "node:path";
+import { parseArgs } from "node:util";
+import { Recordable } from "./index.js";
+import { createLogger } from "./logger.js";
+import { isRecordableError } from "./errors.js";
+// CLI-level messages always print (the recorder's own `silent` governs run output).
+const log = createLogger(() => false);
+// ─── recordable CLI ──────────────────────────────────────────────────────────
+//
+//   recordable <script.json | script.md> [options]
+//
+// A thin wrapper over the programmatic API: read the file, then
+// `new Recordable({ baseDir, ...flags }).fromJSON|fromMarkdown(contents).run()`.
+// Dispatches by extension; `baseDir` (the script's folder) handles relative path
+// resolution, the sibling `.env`, and assets/output defaults. Designed for
+// `npx recordable demo.md`.
+const USAGE = `recordable — record a declarative script
+
+Usage:
+  recordable <script.json | script.md> [options]
+
+Options:
+  --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)
+  --name <name>    Output filename (without extension)
+  --no-timestamp   Don't prepend an ISO timestamp to the filename
+  -h, --help       Show this help
+
+A .json script is an array of { "action", ... } actions, or { "config", "actions" }.
+A .md file authors the same actions as markers in prose; with a "voiceover"
+frontmatter block it generates narration audio (needs ELEVENLABS_API_KEY, loaded
+from a .env beside the file) into a sibling assets/ folder. Provider/voice/model
+default from RECORDABLE_TTS_PROVIDER / RECORDABLE_VOICE_ID / RECORDABLE_MODEL_ID,
+which the frontmatter overrides. Config precedence: defaults < file < flags.
+
+Relative "visit" URLs (e.g. "./index.html") and a relative "outputDir" resolve
+against the script file, so a script and its output stay together. --out-dir
+overrides (relative to the current directory).`;
+/** Parse argv with Node's built-in parser — strict, so bad flags throw. */
+function parseCliArgs(argv) {
+    const { values, positionals } = (() => {
+        try {
+            return parseArgs({
+                args: argv,
+                allowPositionals: true,
+                options: {
+                    check: { type: "boolean" },
+                    headless: { type: "boolean" },
+                    silent: { type: "boolean" },
+                    "no-timestamp": { type: "boolean" },
+                    "out-dir": { type: "string" },
+                    name: { type: "string" },
+                    help: { type: "boolean", short: "h" },
+                },
+            });
+        }
+        catch (err) {
+            fail(err.message);
+        }
+    })();
+    if (values.help) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    if (positionals.length > 1)
+        fail(`unexpected extra argument: ${positionals[1]}`);
+    const config = {};
+    if (values.headless)
+        config.headless = true;
+    if (values.silent)
+        config.silent = true;
+    if (values["no-timestamp"])
+        config.outputTimestamp = false;
+    // Resolve --out-dir against cwd now so baseDir resolution leaves it alone.
+    if (values["out-dir"])
+        config.outputDir = resolve(values["out-dir"]);
+    if (values.name)
+        config.outputName = values.name;
+    return { file: positionals[0], check: Boolean(values.check), config };
+}
+function fail(message) {
+    log.error(message);
+    process.exit(1);
+}
+async function main() {
+    const args = parseCliArgs(process.argv.slice(2));
+    if (!args.file)
+        fail("no script file given (try --help)");
+    const file = resolve(args.file);
+    const isMarkdown = /\.(md|markdown)$/i.test(file);
+    // baseDir = the script's folder: resolves its relative paths, loads a sibling
+    // .env, and defaults assets/output to <baseDir>/assets and <baseDir>/output.
+    const config = { baseDir: dirname(file), ...args.config };
+    let contents;
+    try {
+        contents = readFileSync(file, "utf8");
+    }
+    catch {
+        fail(`${basename(file)}: file not found`);
+    }
+    // Build the recording — same call a script makes. This parses + validates
+    // (bad actions/keys throw) but never launches a browser or synthesizes audio;
+    // that all happens in run(), so --check can build and stop here.
+    let rec;
+    try {
+        rec = isMarkdown
+            ? new Recordable(config).fromMarkdown(contents)
+            : new Recordable(config).fromJSON(contents);
+    }
+    catch (err) {
+        fail(`${basename(file)}: ${err.message}`);
+    }
+    if (args.check) {
+        log("OK", `${basename(file)} is valid`);
+        return;
+    }
+    await rec.run();
+}
+main().catch((err) => {
+    // Expected failures (bad config, missing file, ffmpeg/TTS/browser) print a
+    // clean line; anything else is a bug, so keep its stack for debugging.
+    if (isRecordableError(err))
+        fail(err.message);
+    log.error(String(err?.stack ?? err));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/compose/mix.d.ts

@@ -0,0 +1,13 @@
+import { type AudioClip } from "../audio/track.js";
+import type { Logger } from "../logger.js";
+/**
+ * Add the audio `clips` onto the silent `videoPath`, writing `out`. Each clip is
+ * delayed to its `startMs` (`adelay`), gained (`volume`), then `amix`ed; the
+ * video is stream-copied and `-t` clamps the result to the video length.
+ *
+ * Per the timing contract the video defines the length: a clip that runs past
+ * the end is the author's cue to add a trailing `wait()`, so we warn and let
+ * `-t` truncate it rather than padding the video.
+ */
+export declare function addAudio(videoPath: string, clips: readonly AudioClip[], out: string, log: Logger): Promise<void>;
+//# sourceMappingURL=mix.d.ts.map

package/dist/compose/mix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mix.d.ts","sourceRoot":"","sources":["../../src/compose/mix.ts"],"names":[],"mappings":"AACA,OAAO,EAAmC,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAU3C;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/dist/compose/mix.js

@@ -0,0 +1,50 @@
+import { getDuration, runFfmpeg } from "../ffmpeg.js";
+import { audioFilterGraph, audioOverruns } from "../audio/track.js";
+// ─── Compose layer: combining audio onto the video ───────────────────────────
+//
+// `addAudio` lays the finished audio track onto the silent video — combining the
+// two streams (the operation a pro A/V tool would call "muxing"). It lives in the
+// compose layer because it joins layers; the audio layer only models the clips.
+// Each clip is delayed to its position, gained, and mixed; the video is copied
+// untouched.
+/**
+ * Add the audio `clips` onto the silent `videoPath`, writing `out`. Each clip is
+ * delayed to its `startMs` (`adelay`), gained (`volume`), then `amix`ed; the
+ * video is stream-copied and `-t` clamps the result to the video length.
+ *
+ * Per the timing contract the video defines the length: a clip that runs past
+ * the end is the author's cue to add a trailing `wait()`, so we warn and let
+ * `-t` truncate it rather than padding the video.
+ */
+export async function addAudio(videoPath, clips, out, log) {
+    const videoMs = (await getDuration(videoPath)) * 1000;
+    for (const { path, overMs } of audioOverruns(clips, videoMs)) {
+        log("Audio", `warning: "${path}" runs ${overMs}ms past the video end and will be cut — ` +
+            `add a trailing wait() to give it room`);
+    }
+    const { filters, mapLabel } = audioFilterGraph(clips);
+    await runFfmpeg([
+        "-y",
+        "-i",
+        videoPath,
+        ...clips.flatMap((c) => ["-i", c.path]),
+        "-filter_complex",
+        filters.join(";"),
+        "-map",
+        "0:v",
+        "-map",
+        `[${mapLabel}]`,
+        "-c:v",
+        "copy",
+        "-c:a",
+        "aac",
+        // The video defines the length: `-t` clamps the output to it, so short audio
+        // leaves trailing silence and an overrun is cut (not padded). (`-shortest`
+        // would wrongly truncate the video when the audio is shorter.)
+        "-t",
+        (videoMs / 1000).toFixed(3),
+        out,
+    ]);
+    log("Audio", `mixed ${clips.length} audio clip(s)`);
+}
+//# sourceMappingURL=mix.js.map

package/dist/compose/mix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mix.js","sourceRoot":"","sources":["../../src/compose/mix.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAkB,MAAM,mBAAmB,CAAC;AAGpF,gFAAgF;AAChF,EAAE;AACF,iFAAiF;AACjF,kFAAkF;AAClF,gFAAgF;AAChF,+EAA+E;AAC/E,aAAa;AAEb;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAAiB,EACjB,KAA2B,EAC3B,GAAW,EACX,GAAW;IAEX,MAAM,OAAO,GAAG,CAAC,MAAM,WAAW,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC;IACtD,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QAC7D,GAAG,CACD,OAAO,EACP,aAAa,IAAI,UAAU,MAAM,0CAA0C;YACzE,uCAAuC,CAC1C,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,SAAS,CAAC;QACd,IAAI;QACJ,IAAI;QACJ,SAAS;QACT,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACvC,iBAAiB;QACjB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QACjB,MAAM;QACN,KAAK;QACL,MAAM;QACN,IAAI,QAAQ,GAAG;QACf,MAAM;QACN,MAAM;QACN,MAAM;QACN,KAAK;QACL,6EAA6E;QAC7E,2EAA2E;QAC3E,+DAA+D;QAC/D,IAAI;QACJ,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3B,GAAG;KACJ,CAAC,CAAC;IACH,GAAG,CAAC,OAAO,EAAE,SAAS,KAAK,CAAC,MAAM,gBAAgB,CAAC,CAAC;AACtD,CAAC"}