@reelscript/cli 0.1.0

package/dist/cursor.js

@@ -0,0 +1,55 @@
+import sharp from "sharp";
+const ARROW_VIEW = { w: 20, h: 26 };
+function arrowSvg(px) {
+    const s = px / ARROW_VIEW.h;
+    const w = Math.ceil(ARROW_VIEW.w * s);
+    const h = Math.ceil(ARROW_VIEW.h * s);
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${ARROW_VIEW.w} ${ARROW_VIEW.h}">
+  <defs>
+    <filter id="sh" x="-30%" y="-30%" width="180%" height="180%">
+      <feGaussianBlur in="SourceAlpha" stdDeviation="0.9"/>
+      <feOffset dx="0.4" dy="1.1" result="b"/>
+      <feComponentTransfer><feFuncA type="linear" slope="0.45"/></feComponentTransfer>
+      <feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+  <path filter="url(#sh)" d="M1.5 1.5 L1.5 20.5 L6.2 16 L9.8 23.6 L13.2 22.1 L9.6 14.6 L16.5 14.6 Z"
+        fill="#111" stroke="#fff" stroke-width="1.4" stroke-linejoin="round"/>
+</svg>`;
+}
+const cache = new Map();
+export function cursorSprite(heightPx) {
+    const px = Math.max(8, Math.round(heightPx));
+    const key = `arrow:${px}`;
+    let p = cache.get(key);
+    if (!p) {
+        p = (async () => {
+            const svg = arrowSvg(px);
+            const { data, info } = await sharp(Buffer.from(svg)).png().toBuffer({ resolveWithObject: true });
+            const s = px / ARROW_VIEW.h;
+            return { data, width: info.width, height: info.height, hx: 1.5 * s, hy: 1.5 * s };
+        })();
+        cache.set(key, p);
+    }
+    return p;
+}
+/** Translucent ring that expands from the click point. */
+export function rippleSprite(radius, opacity) {
+    const r = Math.max(2, Math.round(radius));
+    const o = Math.round(opacity * 20) / 20;
+    const key = `ripple:${r}:${o}`;
+    let p = cache.get(key);
+    if (!p) {
+        p = (async () => {
+            const d = r * 2 + 4;
+            const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${d}" height="${d}">
+        <circle cx="${d / 2}" cy="${d / 2}" r="${r}" fill="#3b82f6" fill-opacity="${o * 0.35}"
+                stroke="#3b82f6" stroke-opacity="${o}" stroke-width="2"/>
+      </svg>`;
+            const { data, info } = await sharp(Buffer.from(svg)).png().toBuffer({ resolveWithObject: true });
+            return { data, width: info.width, height: info.height, hx: d / 2, hy: d / 2 };
+        })();
+        cache.set(key, p);
+    }
+    return p;
+}

package/dist/easing.d.ts

@@ -0,0 +1,6 @@
+export type Ease = "linear" | "smooth" | "snappy" | "overshoot";
+export declare const easings: Record<Ease, (t: number) => number>;
+export declare function clamp(v: number, min: number, max: number): number;
+export declare function lerp(a: number, b: number, t: number): number;
+/** Eased progress in [0,1] for a segment starting at `start` lasting `dur` ms. */
+export declare function progress(t: number, start: number, dur: number, ease: Ease): number;

package/dist/easing.js

@@ -0,0 +1,25 @@
+export const easings = {
+    linear: (t) => t,
+    // easeInOutCubic — the default "human hand" feel
+    smooth: (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
+    // easeOutExpo — fast start, gentle landing
+    snappy: (t) => (t >= 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+    // easeOutBack — slight overshoot past the target
+    overshoot: (t) => {
+        const c1 = 1.70158;
+        const c3 = c1 + 1;
+        return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+    },
+};
+export function clamp(v, min, max) {
+    return v < min ? min : v > max ? max : v;
+}
+export function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Eased progress in [0,1] for a segment starting at `start` lasting `dur` ms. */
+export function progress(t, start, dur, ease) {
+    if (dur <= 0)
+        return 1;
+    return easings[ease](clamp((t - start) / dur, 0, 1));
+}

package/dist/encoder.d.ts

@@ -0,0 +1,38 @@
+export interface EncoderOptions {
+    out: string;
+    width: number;
+    height: number;
+    fps: number;
+    /** x264 CRF; lower = higher quality. */
+    crf?: number;
+    ffmpegPath?: string;
+    /** GIF output settings (used when `out` ends in .gif). */
+    gif?: GifOptions;
+}
+export interface GifOptions {
+    /** Output width in px; height keeps the aspect ratio. Default: 960 */
+    width?: number;
+    /** GIF frame rate. Default: 20 */
+    fps?: number;
+}
+export declare function resolveFfmpeg(explicit?: string): string;
+/** Streams raw RGB frames into ffmpeg and produces an H.264 mp4. */
+export declare class Encoder {
+    private opts;
+    private proc;
+    private stderr;
+    private exit;
+    readonly frameBytes: number;
+    constructor(opts: EncoderOptions);
+    start(): void;
+    writeFrame(rgb: Buffer): Promise<void>;
+    finish(): Promise<void>;
+}
+export interface NarrationCue {
+    /** WAV file to play. */
+    file: string;
+    /** When it starts on the video timeline, in ms. */
+    atMs: number;
+}
+/** Remux a finished video with narration clips placed on the timeline (no video re-encode). */
+export declare function muxNarration(videoPath: string, cues: NarrationCue[], out: string, ffmpegPath?: string): Promise<void>;

package/dist/encoder.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { mkdirSync } from "node:fs";
+import { dirname, extname } from "node:path";
+import { once } from "node:events";
+/** Codec arguments chosen from the output extension. */
+function outputArgs(opts) {
+    const ext = extname(opts.out).toLowerCase();
+    if (ext === ".gif") {
+        const width = opts.gif?.width ?? 960;
+        const fps = opts.gif?.fps ?? 20;
+        // Two-pass palette in one graph: sample a palette from the scaled frames,
+        // then dither against it. Gives far better colour than ffmpeg's default GIF path.
+        const filter = [
+            `fps=${fps}`,
+            `scale=${width}:-1:flags=lanczos`,
+            "split[a][b]",
+            "[a]palettegen=stats_mode=diff[p]",
+            "[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle",
+        ].join(",");
+        return ["-filter_complex", filter, "-loop", "0"];
+    }
+    return [
+        "-c:v", "libx264",
+        "-preset", "medium",
+        "-crf", String(opts.crf ?? 18),
+        "-pix_fmt", "yuv420p",
+        "-movflags", "+faststart",
+    ];
+}
+export function resolveFfmpeg(explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.REELSCRIPT_FFMPEG)
+        return process.env.REELSCRIPT_FFMPEG;
+    try {
+        const require = createRequire(import.meta.url);
+        const p = require("ffmpeg-static");
+        if (p)
+            return p;
+    }
+    catch {
+        /* fall through to PATH */
+    }
+    return "ffmpeg";
+}
+/** Streams raw RGB frames into ffmpeg and produces an H.264 mp4. */
+export class Encoder {
+    opts;
+    proc = null;
+    stderr = "";
+    exit = null;
+    frameBytes;
+    constructor(opts) {
+        this.opts = opts;
+        this.frameBytes = opts.width * opts.height * 3;
+    }
+    start() {
+        const { out, width, height, fps } = this.opts;
+        mkdirSync(dirname(out), { recursive: true });
+        const args = [
+            "-y",
+            "-hide_banner",
+            "-loglevel", "error",
+            "-f", "rawvideo",
+            "-pix_fmt", "rgb24",
+            "-s", `${width}x${height}`,
+            "-r", String(fps),
+            "-i", "-",
+            ...outputArgs(this.opts),
+            out,
+        ];
+        const proc = spawn(resolveFfmpeg(this.opts.ffmpegPath), args, { stdio: ["pipe", "ignore", "pipe"] });
+        proc.stderr.on("data", (d) => (this.stderr += d.toString()));
+        this.exit = new Promise((resolve) => proc.on("close", resolve));
+        proc.on("error", (err) => {
+            this.stderr += `\nfailed to start ffmpeg: ${err.message}`;
+        });
+        this.proc = proc;
+    }
+    async writeFrame(rgb) {
+        if (!this.proc?.stdin)
+            throw new Error("encoder not started");
+        if (rgb.length !== this.frameBytes) {
+            throw new Error(`frame is ${rgb.length} bytes, expected ${this.frameBytes}`);
+        }
+        if (!this.proc.stdin.write(rgb)) {
+            await once(this.proc.stdin, "drain");
+        }
+    }
+    async finish() {
+        if (!this.proc?.stdin)
+            return;
+        this.proc.stdin.end();
+        const code = await this.exit;
+        if (code !== 0) {
+            throw new Error(`ffmpeg exited with code ${code}\n${this.stderr.trim()}`);
+        }
+    }
+}
+/** Remux a finished video with narration clips placed on the timeline (no video re-encode). */
+export async function muxNarration(videoPath, cues, out, ffmpegPath) {
+    const args = ["-y", "-hide_banner", "-loglevel", "error", "-i", videoPath];
+    for (const c of cues)
+        args.push("-i", c.file);
+    const delayed = cues.map((c, i) => `[${i + 1}:a]adelay=${Math.max(0, Math.round(c.atMs))}:all=1[a${i}]`);
+    const labels = cues.map((_, i) => `[a${i}]`).join("");
+    const filter = cues.length === 1
+        ? delayed[0]
+        : [...delayed, `${labels}amix=inputs=${cues.length}:normalize=0[mix]`].join(";");
+    const outLabel = cues.length === 1 ? "[a0]" : "[mix]";
+    args.push("-filter_complex", filter, "-map", "0:v", "-map", outLabel, "-c:v", "copy", "-c:a", "aac", "-b:a", "160k", "-ar", "48000", "-movflags", "+faststart", out);
+    const proc = spawn(resolveFfmpeg(ffmpegPath), args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (d) => (stderr += d.toString()));
+    const code = await new Promise((resolve, reject) => {
+        proc.on("error", reject);
+        proc.on("close", resolve);
+    });
+    if (code !== 0)
+        throw new Error(`ffmpeg (narration mux) exited with code ${code}\n${stderr.trim()}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+/**
+ * reelscript — product demos as code.
+ *
+ * Scripts build a timeline through the `Demo` API; `render()` executes it
+ * against a headless Chromium, samples the state at a fixed frame rate, and
+ * composites the animated cursor + zoom offline before encoding to mp4.
+ */
+import { type RenderResult } from "./renderer.js";
+import type { Action, Target } from "./timeline.js";
+import type { Ease } from "./easing.js";
+import type { ThemeName } from "./theme.js";
+import type { GifOptions } from "./encoder.js";
+import type { TtsEngine } from "./tts.js";
+export type { Action, Target } from "./timeline.js";
+export type { Ease } from "./easing.js";
+export type { ThemeName } from "./theme.js";
+export type { RenderOptions, RenderResult } from "./renderer.js";
+export type { GifOptions } from "./encoder.js";
+export type { TtsEngine, TtsAudio, TtsOptions } from "./tts.js";
+export { kokoro } from "./tts.js";
+export type { TermEvent, TermRecording } from "./terminal.js";
+export { recordCommand, scriptedEvents, playbackEvents } from "./terminal.js";
+export { render } from "./renderer.js";
+export interface DemoOptions {
+    /** Visual chrome around the recorded page. Default: "macos". */
+    theme?: ThemeName;
+    /** Content size of the first window, in CSS pixels. Default: [1280, 800]. */
+    viewport?: [number, number];
+    /** Desktop (output) size. Default: the first window plus the theme's margins. */
+    desktop?: [number, number];
+    /** Output frames per second. Default: 60. */
+    fps?: number;
+    /** Freeze the page clock and step it per frame for reproducible animations. Default: true. */
+    deterministic?: boolean;
+    /** Applied when rendering to a .gif path. Default: 960px wide at 20fps. */
+    gif?: GifOptions;
+    /** Default narration voice for say(). Default: "af_heart" (Kokoro). */
+    voice?: string;
+    /** Text-to-speech engine. Default: Kokoro via the optional kokoro-js dependency. */
+    tts?: TtsEngine;
+    /** Respell words the voice mispronounces, e.g. { Reelscript: "Reel script" }. */
+    pronunciations?: Record<string, string>;
+    /** Where terminal recordings are stored. Default: `recordings/` next to the script. */
+    recordingsDir?: string;
+    /** Print render progress to stderr. Default: true. */
+    verbose?: boolean;
+}
+export interface MoveOptions {
+    ease?: Ease;
+    /** Movement duration in ms. Default: derived from distance. */
+    duration?: number;
+    /** Window to resolve a selector in. Default: the focused window. */
+    window?: "browser" | "terminal";
+}
+/** Window position (frame origin, desktop pixels) and content size. */
+export interface WindowGeometry {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface ZoomOptions {
+    /** Default: 1.6 */
+    scale?: number;
+    /** Transition duration in ms. Default: 700 */
+    duration?: number;
+    ease?: Ease;
+    /** Window to resolve a selector in. Default: the focused window. */
+    window?: "browser" | "terminal";
+}
+export interface TypeOptions {
+    /** Typing speed in words per minute. Default: 300 */
+    wpm?: number;
+}
+export interface SayOptions {
+    voice?: string;
+    /** Speed multiplier. Default: 1 */
+    speed?: number;
+}
+export interface TerminalOptions {
+    /** Window title. Default: "zsh" */
+    title?: string;
+    /** Prompt string. Default: "~ % " */
+    prompt?: string;
+    /** Default: 15 */
+    fontSize?: number;
+}
+export interface RunOptions {
+    /** Output to show. Omit to replay a recording made with `reelscript record`. */
+    output?: string;
+    /** Spread declared output over this many ms. */
+    duration?: number;
+    /** Typing speed for the command. Default: 300 */
+    wpm?: number;
+    /** Playback speed for recorded output. Default: 1 */
+    speed?: number;
+    /** Cap silences in recorded output, in ms. Default: 700 */
+    maxGapMs?: number;
+}
+export interface GotoOptions {
+    /** ms to hold on the freshly loaded page. Default: 400 */
+    settle?: number;
+}
+export interface MockOptions {
+    status?: number;
+}
+declare class Cursor {
+    private demo;
+    constructor(demo: Demo);
+    /** Glide the cursor to a selector or point. */
+    moveTo(target: Target, opts?: MoveOptions): Promise<void>;
+    click(opts?: {
+        button?: "left" | "right";
+    }): Promise<void>;
+}
+declare class Zoom {
+    private demo;
+    constructor(demo: Demo);
+    /** Animate a zoom centered on a selector or point. Runs alongside following actions. */
+    to(target: Target, opts?: ZoomOptions): void;
+    out(opts?: Omit<ZoomOptions, "scale">): void;
+}
+declare class Win {
+    protected demo: Demo;
+    readonly id: "browser" | "terminal";
+    constructor(demo: Demo, id: "browser" | "terminal");
+    /** Bring this window to the front and direct typing to it. */
+    focus(): Promise<void>;
+    /** Move or resize this window. */
+    place(geometry: WindowGeometry): Promise<void>;
+}
+declare class Browser extends Win {
+    constructor(demo: Demo);
+    /** Navigate the browser window (opening it if needed) and bring it to the front. */
+    goto(url: string, opts?: GotoOptions): Promise<void>;
+    /** Intercept matching requests and return canned JSON — demos never hit a live backend. */
+    mockAPI(pattern: string, response: unknown, opts?: MockOptions): void;
+}
+declare class TerminalWindow extends Win {
+    constructor(demo: Demo);
+    /** Open a terminal window on the desktop (beside or over the browser) and focus it. */
+    open(opts?: TerminalOptions & WindowGeometry): Promise<void>;
+    /**
+     * Type a command and show its output. With `output`, nothing executes;
+     * without it, the output is replayed from a recording (see `reelscript record`).
+     */
+    run(command: string, opts?: RunOptions): Promise<void>;
+}
+export declare class Demo {
+    readonly options: DemoOptions;
+    readonly cursor: Cursor;
+    readonly zoom: Zoom;
+    readonly browser: Browser;
+    readonly terminal: TerminalWindow;
+    private actions;
+    constructor(options?: DemoOptions);
+    /** @internal */
+    _push(action: Action): void;
+    /** Type into a field with accelerated, evenly paced keystrokes. */
+    type(target: string, text: string, opts?: TypeOptions): Promise<void>;
+    /** Press a key or chord, e.g. "Enter" or "Meta+K". */
+    press(key: string): Promise<void>;
+    wait(ms: number): Promise<void>;
+    /**
+     * Narrate. Starts speaking now (or when the previous sentence finishes)
+     * while the following actions continue. Use waitForNarration() to hold
+     * the timeline until speech ends.
+     */
+    say(text: string, opts?: SayOptions): void;
+    /** Hold until all narration queued so far has finished. */
+    waitForNarration(): Promise<void>;
+    /** The recorded timeline (useful for tests and debugging). */
+    getTimeline(): readonly Action[];
+    /**
+     * Render the timeline to a video file. The container is chosen from the
+     * extension: .mp4 (H.264) or .gif (palette-optimized).
+     *
+     * Honors REELSCRIPT_OUT (override output path) and REELSCRIPT_SNAPSHOT_AT
+     * (render a single PNG at that time in ms) so the CLI can drive scripts.
+     */
+    /** Directory for terminal recordings: option, else `recordings/` beside the entry script. */
+    recordingsDir(): string;
+    /** Run every terminal command that has no declared output and save its recording. */
+    recordTerminals(): Promise<string[]>;
+    render(outPath: string): Promise<RenderResult>;
+}
+export declare function createDemo(options?: DemoOptions): Demo;

package/dist/index.js

@@ -0,0 +1,197 @@
+/**
+ * reelscript — product demos as code.
+ *
+ * Scripts build a timeline through the `Demo` API; `render()` executes it
+ * against a headless Chromium, samples the state at a fixed frame rate, and
+ * composites the animated cursor + zoom offline before encoding to mp4.
+ */
+import { render as renderTimeline } from "./renderer.js";
+import { recordCommand, saveRecording } from "./terminal.js";
+import { dirname, join, resolve } from "node:path";
+export { kokoro } from "./tts.js";
+export { recordCommand, scriptedEvents, playbackEvents } from "./terminal.js";
+export { render } from "./renderer.js";
+class Cursor {
+    demo;
+    constructor(demo) {
+        this.demo = demo;
+    }
+    /** Glide the cursor to a selector or point. */
+    async moveTo(target, opts = {}) {
+        this.demo._push({ kind: "cursor.moveTo", target, ...opts });
+    }
+    async click(opts = {}) {
+        this.demo._push({ kind: "cursor.click", ...opts });
+    }
+}
+class Zoom {
+    demo;
+    constructor(demo) {
+        this.demo = demo;
+    }
+    /** Animate a zoom centered on a selector or point. Runs alongside following actions. */
+    to(target, opts = {}) {
+        this.demo._push({ kind: "zoom.to", target, ...opts });
+    }
+    out(opts = {}) {
+        this.demo._push({ kind: "zoom.out", ...opts });
+    }
+}
+class Win {
+    demo;
+    id;
+    constructor(demo, id) {
+        this.demo = demo;
+        this.id = id;
+    }
+    /** Bring this window to the front and direct typing to it. */
+    async focus() {
+        this.demo._push({ kind: "window.focus", window: this.id });
+    }
+    /** Move or resize this window. */
+    async place(geometry) {
+        this.demo._push({ kind: "window.place", window: this.id, ...geometry });
+    }
+}
+class Browser extends Win {
+    constructor(demo) {
+        super(demo, "browser");
+    }
+    /** Navigate the browser window (opening it if needed) and bring it to the front. */
+    async goto(url, opts = {}) {
+        this.demo._push({ kind: "browser.goto", url, ...opts });
+    }
+    /** Intercept matching requests and return canned JSON — demos never hit a live backend. */
+    mockAPI(pattern, response, opts = {}) {
+        this.demo._push({ kind: "browser.mockAPI", pattern, response, ...opts });
+    }
+}
+class TerminalWindow extends Win {
+    constructor(demo) {
+        super(demo, "terminal");
+    }
+    /** Open a terminal window on the desktop (beside or over the browser) and focus it. */
+    async open(opts = {}) {
+        this.demo._push({ kind: "terminal.open", ...opts });
+    }
+    /**
+     * Type a command and show its output. With `output`, nothing executes;
+     * without it, the output is replayed from a recording (see `reelscript record`).
+     */
+    async run(command, opts = {}) {
+        this.demo._push({ kind: "terminal.run", command, ...opts });
+    }
+}
+export class Demo {
+    options;
+    cursor = new Cursor(this);
+    zoom = new Zoom(this);
+    browser = new Browser(this);
+    terminal = new TerminalWindow(this);
+    actions = [];
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** @internal */
+    _push(action) {
+        this.actions.push(action);
+    }
+    /** Type into a field with accelerated, evenly paced keystrokes. */
+    async type(target, text, opts = {}) {
+        this._push({ kind: "type", target, text, ...opts });
+    }
+    /** Press a key or chord, e.g. "Enter" or "Meta+K". */
+    async press(key) {
+        this._push({ kind: "press", key });
+    }
+    async wait(ms) {
+        this._push({ kind: "wait", ms });
+    }
+    /**
+     * Narrate. Starts speaking now (or when the previous sentence finishes)
+     * while the following actions continue. Use waitForNarration() to hold
+     * the timeline until speech ends.
+     */
+    say(text, opts = {}) {
+        this._push({ kind: "say", text, ...opts });
+    }
+    /** Hold until all narration queued so far has finished. */
+    async waitForNarration() {
+        this._push({ kind: "waitForNarration" });
+    }
+    /** The recorded timeline (useful for tests and debugging). */
+    getTimeline() {
+        return this.actions;
+    }
+    /**
+     * Render the timeline to a video file. The container is chosen from the
+     * extension: .mp4 (H.264) or .gif (palette-optimized).
+     *
+     * Honors REELSCRIPT_OUT (override output path) and REELSCRIPT_SNAPSHOT_AT
+     * (render a single PNG at that time in ms) so the CLI can drive scripts.
+     */
+    /** Directory for terminal recordings: option, else `recordings/` beside the entry script. */
+    recordingsDir() {
+        if (this.options.recordingsDir)
+            return resolve(this.options.recordingsDir);
+        const script = process.env.REELSCRIPT_SCRIPT || process.argv[1] || ".";
+        return join(dirname(resolve(script)), "recordings");
+    }
+    /** Run every terminal command that has no declared output and save its recording. */
+    async recordTerminals() {
+        const dir = this.recordingsDir();
+        const files = [];
+        for (const a of this.actions) {
+            if (a.kind !== "terminal.run" || a.output !== undefined)
+                continue;
+            process.stderr.write(`reelscript: recording "${a.command}"\n`);
+            const rec = await recordCommand(a.command);
+            files.push(saveRecording(dir, rec));
+        }
+        return files;
+    }
+    async render(outPath) {
+        if (process.env.REELSCRIPT_RECORD) {
+            const files = await this.recordTerminals();
+            process.stderr.write(files.length
+                ? `reelscript: saved ${files.length} recording${files.length === 1 ? "" : "s"} in ${this.recordingsDir()}\n`
+                : "reelscript: nothing to record (no terminal.run without output)\n");
+            return { out: "", frames: 0, durationMs: 0, width: 0, height: 0 };
+        }
+        const out = process.env.REELSCRIPT_OUT || outPath;
+        const snapRaw = process.env.REELSCRIPT_SNAPSHOT_AT;
+        const snapshotAt = snapRaw ? Number(snapRaw) : undefined;
+        const verbose = this.options.verbose ?? true;
+        const started = Date.now();
+        const result = await renderTimeline(this.actions, {
+            out,
+            fps: this.options.fps,
+            viewport: this.options.viewport,
+            desktop: this.options.desktop,
+            theme: this.options.theme,
+            deterministic: this.options.deterministic,
+            gif: this.options.gif,
+            tts: this.options.tts,
+            voice: this.options.voice,
+            pronunciations: this.options.pronunciations,
+            snapshotAt,
+            recordingsDir: this.recordingsDir(),
+            onStatus: verbose ? (m) => process.stderr.write(`reelscript: ${m}\n`) : undefined,
+            onProgress: verbose
+                ? ({ frame, timeMs }) => {
+                    if (frame > 0 && frame % 30 === 0) {
+                        process.stderr.write(`\rreelscript: frame ${frame}  t=${(timeMs / 1000).toFixed(2)}s`);
+                    }
+                }
+                : undefined,
+        });
+        if (verbose) {
+            const secs = ((Date.now() - started) / 1000).toFixed(1);
+            process.stderr.write(`\rreelscript: wrote ${result.out}  (${result.width}x${result.height}, ${result.frames} frames, ${(result.durationMs / 1000).toFixed(2)}s video, rendered in ${secs}s)\n`);
+        }
+        return result;
+    }
+}
+export function createDemo(options = {}) {
+    return new Demo(options);
+}

package/dist/renderer.d.ts

@@ -0,0 +1,48 @@
+import { type Action } from "./timeline.js";
+import { type ThemeName } from "./theme.js";
+import { type GifOptions } from "./encoder.js";
+import { type TtsEngine } from "./tts.js";
+export interface RenderOptions {
+    out: string;
+    fps?: number;
+    /** Content size of the first window. */
+    viewport?: [number, number];
+    /** Desktop (output) size. Default: first window plus theme margins. */
+    desktop?: [number, number];
+    theme?: ThemeName;
+    /** Settings applied when `out` ends in .gif. */
+    gif?: GifOptions;
+    /** Text-to-speech engine for say(). Default: Kokoro via kokoro-js. */
+    tts?: TtsEngine;
+    /** Default narration voice. Default: "af_heart" */
+    voice?: string;
+    /** Words to respell before synthesis, e.g. { Reelscript: "Reel script" }. */
+    pronunciations?: Record<string, string>;
+    onStatus?: (message: string) => void;
+    /** Where terminal recordings live (for terminal.run without declared output). */
+    recordingsDir?: string;
+    /**
+     * Replace the page's clock with a virtual one that advances exactly one
+     * frame per rendered frame, so CSS transitions, timers and rAF loops play
+     * at the correct speed regardless of how long each frame takes to capture.
+     * Default: true.
+     */
+    deterministic?: boolean;
+    /**
+     * Render up to this time (ms) and write that single frame as a PNG to `out`
+     * instead of encoding a video. Fast way to iterate on a moment of a demo.
+     */
+    snapshotAt?: number;
+    onProgress?: (info: {
+        frame: number;
+        timeMs: number;
+    }) => void;
+}
+export interface RenderResult {
+    out: string;
+    frames: number;
+    durationMs: number;
+    width: number;
+    height: number;
+}
+export declare function render(actions: Action[], options: RenderOptions): Promise<RenderResult>;