@reelscript/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trevin Lee
+
+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,179 @@
+# reelscript
+
+![A demo rendered by reelscript: the cursor glides to a button, a modal opens, the view zooms in, a name is typed, and the zoom releases](docs/demo.gif)
+
+<sup>Made with reelscript, by reelscript: CI renders [examples/basic.ts](examples/basic.ts) inside the published container on every push to `main` and commits the result.</sup>
+
+**Product demos as code.** Write a script, render a demo, re-run it in CI when your UI changes.
+
+
+Screen-recording tools (Screen Studio, Arcade, Tango) all rot the same way: your product UI changes and your beautiful demo is now a lie, so you re-record it by hand. reelscript makes a demo a *build artifact*. The video is generated from a script, so when your UI updates you just re-run it.
+
+```ts
+import { createDemo } from "@reelscript/cli";
+
+const demo = createDemo({ theme: "macos", viewport: [1280, 800], fps: 60 });
+
+await demo.browser.goto("https://app.local");
+await demo.cursor.moveTo("#new-project", { ease: "smooth" });
+await demo.cursor.click();
+
+demo.zoom.to("#modal", { scale: 1.6 });
+demo.say("Give it a name, and hit Create.");
+await demo.type("#project-name", "Acme Q3 Launch", { wpm: 400 });
+await demo.cursor.moveTo("#create");
+await demo.cursor.click();
+demo.zoom.out();
+await demo.waitForNarration();
+
+await demo.render("out/demo.mp4");
+```
+
+## How it works
+
+- **Code-first, not a UI timeline.** The demo is a script you version, diff, and review.
+- **Deterministic offline rendering.** Every step is scripted, so frames are produced one at a time: drive a headless Chromium to the state for frame *n*, capture it, composite the animated cursor and zoom, and pipe it to ffmpeg. Perfect 60fps with no dropped frames, and it runs headless in CI.
+- **The page's clock is virtual.** reelscript replaces timers, `requestAnimationFrame`, `Date`, and `performance.now` inside the page and steps CSS transitions through the Web Animations API, advancing exactly one frame per rendered frame. A 200ms fade is 12 frames at 60fps no matter how slow capture is.
+- **Cinematic layer.** Eased cursor motion, click ripples, zoom-to-element, accelerated typing. The polish that makes a demo feel produced, done as math over frames rather than captured motion.
+- **Own the DOM.** Targets are CSS selectors, and `browser.mockAPI()` returns canned JSON so demos never depend on a live backend, real credentials, or flaky auth.
+- **Clean stage.** The `macos` theme composites the page into a browser window on a mocked macOS desktop, so there is nothing to tidy up before recording.
+- **A real desktop.** Windows have positions, sizes, focus, and z-order. Open a browser and a terminal side by side, click between them, and the one you click comes to the front. Selectors resolve in the focused window (or the one you name), typing goes to the focused window, and zoom targets can be in any window.
+- **Terminal windows.** `terminal.open()` puts a Terminal-style window on the desktop and `terminal.run()` types a command and streams its output. Declare the output in the script, or run the real command once with `reelscript record` and replay the recording frame-exact on every render.
+- **Narration as code.** `say()` speaks a line while the actions continue, sentences never overlap, and `waitForNarration()` paces the timeline to the voice. The default voice is Kokoro, an open-weights model that runs on CPU with no account, so it works offline and in CI. Plug in any engine through the `tts` option.
+
+## Install
+
+```sh
+npm install -D @reelscript/cli
+npx playwright install chromium
+```
+
+The package installs a `reelscript` command. Scripts are ES modules that use top-level `await`; set `"type": "module"` in your package.json, or the CLI will run them as modules for you. (The unscoped name is blocked by npm's similarity rule against `rescript`, hence the scope.)
+
+## Try it
+
+```sh
+git clone https://github.com/trevin-lee/reelscript && cd reelscript
+npm install
+npx playwright install chromium
+npm run example            # renders examples/basic.ts -> out/basic.mp4
+```
+
+The example drives a small dashboard app that ships with the repo, so it is fully self-contained. A 6.5s demo at 1424x992 / 60fps renders in about 15s on an M-series laptop.
+
+## Run in CI
+
+The container is the canonical render environment: Chromium, ffmpeg, the theme font, and the narration model are all baked in, so a script renders the same pixels on every machine and never downloads anything at run time.
+
+```sh
+docker run --rm -v "$PWD:/work" ghcr.io/trevin-lee/reelscript:main render demo.ts --out demo.mp4
+```
+
+Tags: `main` tracks the main branch, `sha-<commit>` pins a build, and each release adds `<version>` and `latest`. While the repository is private the image is too, so `docker login ghcr.io` with a GitHub token that has `read:packages` first.
+
+In GitHub Actions:
+
+```yaml
+jobs:
+  demo:
+    runs-on: ubuntu-latest
+    container: ghcr.io/trevin-lee/reelscript:main
+    steps:
+      - uses: actions/checkout@v5
+      - run: reelscript render demo.ts --out demo.mp4
+```
+
+Scripts may `import { createDemo } from "@reelscript/cli"` without installing the package locally; the CLI resolves it to its own copy.
+
+## CLI
+
+```sh
+reelscript render  <script.ts> [--out demo.mp4]        # render a script to video
+reelscript preview <script.ts> --at 2.5 [--out f.png]   # render the single frame at 2.5s
+```
+
+`preview` is the fast way to iterate on a moment of a demo without waiting for the whole video.
+
+## API
+
+| Call | What it does |
+| --- | --- |
+| `createDemo({ theme, viewport, desktop, fps, deterministic, gif, voice, tts, pronunciations })` | `theme`: `"macos"` or `"bare"`. `viewport` is the first window's content size, `desktop` the output size (default: the first window plus margins). Defaults: macos, 1280x800, 60fps, deterministic clock on, Kokoro voice `af_heart`. |
+| `demo.browser.goto(url, { settle })` | Navigate, then hold for `settle` ms (default 400). |
+| `demo.browser.mockAPI(pattern, json, { status })` | Fulfil matching requests with canned JSON. |
+| `demo.cursor.moveTo(target, { ease, duration, window })` | Glide to a selector or `{x, y}` in the focused window, or in `window`. Duration defaults from distance. Eases: `smooth`, `snappy`, `overshoot`, `linear`. |
+| `demo.cursor.click({ button })` | Click at the cursor, with a ripple. Focuses and raises the window under the cursor. |
+| `demo.zoom.to(target, { scale, duration, ease, window })` | Animate a zoom centred on a target. Runs alongside the actions that follow. |
+| `demo.zoom.out({ duration, ease })` | Return to 1x. |
+| `demo.type(selector, text, { wpm })` | Focus the field and type at `wpm` (default 300). |
+| `demo.press(key)` | Press a key or chord, e.g. `"Enter"`, `"Meta+K"`. |
+| `demo.wait(ms)` | Hold. |
+| `demo.browser.focus()`, `demo.terminal.focus()` | Bring a window to the front and direct typing to it. |
+| `demo.browser.place({ x, y, width, height })`, `demo.terminal.place(...)` | Move or resize a window. `x, y` is the frame origin in desktop pixels; `width, height` is the content size. |
+| `demo.terminal.open({ title, prompt, fontSize, x, y, width, height })` | Open a terminal window and focus it. The first window opened takes the main position; later ones cascade to the lower right unless placed. |
+| `demo.terminal.run(cmd, { output, duration, wpm, speed, maxGapMs })` | Type `cmd`. With `output`, stream that text. Without it, replay the recording for `cmd` from `recordings/`. |
+| `demo.say(text, { voice, speed })` | Queue narration. Starts immediately or after the previous sentence, while following actions run. |
+| `demo.waitForNarration()` | Hold until everything queued with `say()` has been spoken. |
+| `demo.render(path)` | Render to `.mp4` (H.264) or `.gif` (palette-optimized, 960px / 20fps by default, see `gif` option). Honours `REELSCRIPT_OUT` and `REELSCRIPT_SNAPSHOT_AT`, which the CLI uses. |
+
+## Status
+
+Early but working end to end. Roadmap, roughly in order:
+
+- An editor window built on VS Code's web workbench
+- Window open/close animations and drag-to-move
+- Pseudo-terminal recording for TTY-only tools
+- Captions generated from narration (SRT and burned-in)
+- Auto-zoom that follows the cursor, and zoom transitions with a bit of drift
+- `watch` mode with live preview while editing a script
+- Retina (2x) output
+- Transitions between scenes and callouts
+- Python bindings over the same timeline
+- A Linux desktop backend (Xvfb in a container) for demos of native apps, targeted by coordinates or accessibility names
+
+## Several windows
+
+```ts
+const demo = createDemo({ viewport: [1180, 720], desktop: [1600, 1000] });
+await demo.browser.goto("https://app.local");
+await demo.terminal.open({ title: "acme", x: 700, y: 560, width: 840, height: 360 });
+await demo.terminal.run("npm run deploy", { output: "Live at https://acme.app\n" });
+await demo.cursor.moveTo("#new-project", { window: "browser" }); // the browser is behind the terminal
+await demo.cursor.click();                                        // click raises it
+```
+
+Each window is its own Chromium page; the desktop composites them in z-order with the theme's frames and shadows. See [examples/desktop.ts](examples/desktop.ts).
+
+## Terminal demos
+
+```ts
+await demo.terminal.open({ title: "acme", prompt: "acme % " });
+await demo.terminal.run("npm install -D @reelscript/cli", { output: "\nadded 38 packages in 2s\n" });
+await demo.terminal.run("node --version"); // replayed from recordings/node-version-<hash>.json
+```
+
+Declared output never executes anything, so it renders identically everywhere. For real commands, run
+
+```sh
+reelscript record examples/terminal.ts
+```
+
+once (or in CI whenever your CLI changes): it executes every `terminal.run` that has no `output`, captures stdout and stderr with timestamps, and saves `recordings/<command-slug>.json` next to the script. Rendering replays the recording with long silences capped (`maxGapMs`) and optional `speed`, and never needs the tool installed. Commit the recordings; they're small JSON. Commands run through a shell with `FORCE_COLOR=1` and a 256-color `TERM`, without a pseudo-terminal, so tools that insist on a TTY for progress bars may print their non-interactive output.
+
+See [examples/terminal.ts](examples/terminal.ts).
+
+## Narration
+
+`say()` uses [Kokoro-82M](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX) through the optional `kokoro-js` dependency. The model (about 90 MB) downloads on first use into `~/.cache/reelscript` (override with `REELSCRIPT_CACHE`); `reelscript warmup` fetches it ahead of time, and the container image ships with it baked in. Synthesized clips are cached by text and voice, so re-renders don't re-synthesize unchanged lines. Voices include `af_heart`, `af_bella`, `am_michael`, `bf_emma`, `bm_george` and more.
+
+GIF output has no audio track; narration still paces the timeline. Render to `.mp4` for sound.
+
+To skip the model entirely, install with `npm install --omit=optional` and pass your own `tts` engine, or don't call `say()`.
+
+## Requirements
+
+Node 20+. ffmpeg is bundled via `ffmpeg-static`; set `REELSCRIPT_FFMPEG` to use your own.
+
+## License
+
+MIT

package/assets/fonts/LICENSE-Inter.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/LICENSE-JetBrainsMono.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * reelscript CLI
+ *
+ *   reelscript render  <script.ts> [--out demo.mp4]
+ *   reelscript preview <script.ts> --at 2.5 [--out frame.png]
+ *
+ * Scripts are ordinary TS/JS modules that build a Demo and call
+ * `demo.render(...)`. The CLI runs them with tsx, overriding the output via
+ * environment variables (see Demo.render).
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * reelscript CLI
+ *
+ *   reelscript render  <script.ts> [--out demo.mp4]
+ *   reelscript preview <script.ts> --at 2.5 [--out frame.png]
+ *
+ * Scripts are ordinary TS/JS modules that build a Demo and call
+ * `demo.render(...)`. The CLI runs them with tsx, overriding the output via
+ * environment variables (see Demo.render).
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire, register } from "node:module";
+// Let scripts import "@reelscript/cli" without a local install (see resolve-self.ts).
+register(new URL("./resolve-self.js", import.meta.url));
+const require = createRequire(import.meta.url);
+const version = require("../package.json").version;
+function usage() {
+    console.log(`reelscript ${version} — product demos as code
+
+usage:
+  reelscript render  <script> [--out demo.mp4]
+  reelscript preview <script> --at <seconds> [--out frame.png]
+  reelscript record  <script>            run terminal commands for real and save recordings
+  reelscript warmup                      download the narration model into the cache
+
+env:
+  REELSCRIPT_FFMPEG   path to ffmpeg (defaults to bundled ffmpeg-static)`);
+    process.exit(1);
+}
+function parse(argv) {
+    const [command, ...rest] = argv;
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a.startsWith("--")) {
+            const [k, v] = a.slice(2).split("=", 2);
+            flags[k] = v ?? rest[++i] ?? "";
+        }
+        else
+            positional.push(a);
+    }
+    return { command, flags, positional };
+}
+async function runScript(path) {
+    const script = resolve(path);
+    process.env.REELSCRIPT_SCRIPT = script;
+    const { tsImport } = await import("tsx/esm/api");
+    try {
+        await tsImport(pathToFileURL(script).href, import.meta.url);
+    }
+    catch (err) {
+        // A .ts/.js script in a project without "type": "module" is compiled as
+        // CommonJS, which forbids top-level await. Re-run it as an ES module via
+        // a temporary .mts copy beside the original so relative paths still work.
+        if (!(err instanceof Error) || !/Top-level await/.test(err.message))
+            throw err;
+        const { copyFileSync, unlinkSync } = await import("node:fs");
+        const { dirname, basename, join } = await import("node:path");
+        const tmp = join(dirname(script), `.${basename(script).replace(/\.[cm]?[jt]sx?$/, "")}.reelscript.mts`);
+        copyFileSync(script, tmp);
+        try {
+            await tsImport(pathToFileURL(tmp).href, import.meta.url);
+        }
+        finally {
+            unlinkSync(tmp);
+        }
+    }
+}
+async function main() {
+    const { command, flags, positional } = parse(process.argv.slice(2));
+    switch (command) {
+        case "render": {
+            const script = positional[0] ?? usage();
+            if (flags.out)
+                process.env.REELSCRIPT_OUT = resolve(flags.out);
+            await runScript(script);
+            break;
+        }
+        case "preview": {
+            const script = positional[0] ?? usage();
+            const at = Number(flags.at ?? "0");
+            process.env.REELSCRIPT_SNAPSHOT_AT = String(Math.round(at * 1000));
+            process.env.REELSCRIPT_OUT = resolve(flags.out ?? `preview-${at}s.png`);
+            await runScript(script);
+            break;
+        }
+        case "record": {
+            const script = positional[0] ?? usage();
+            process.env.REELSCRIPT_RECORD = "1";
+            await runScript(script);
+            break;
+        }
+        case "warmup": {
+            const { kokoro } = await import("./tts.js");
+            const t = Date.now();
+            await kokoro().synthesize("Ready.", {});
+            console.log(`narration model ready (${((Date.now() - t) / 1000).toFixed(1)}s)`);
+            break;
+        }
+        case "--version":
+        case "-v":
+            console.log(version);
+            break;
+        default:
+            usage();
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/clock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Page clock shim, injected before any page script runs.
+ *
+ * Replaces the page's notion of time (timers, requestAnimationFrame, Date,
+ * performance.now) with a virtual clock that only moves when the renderer
+ * calls `window.__reelscript_advance(ms)`, and steps CSS transitions /
+ * animations by the same amount through the Web Animations API. Chromium's
+ * own compositor keeps running on real time, so screenshots and input
+ * dispatch never stall — only the *content's* clock is deterministic.
+ */
+export declare const CLOCK_SHIM: string;

package/dist/clock.js

@@ -0,0 +1,88 @@
+/**
+ * Page clock shim, injected before any page script runs.
+ *
+ * Replaces the page's notion of time (timers, requestAnimationFrame, Date,
+ * performance.now) with a virtual clock that only moves when the renderer
+ * calls `window.__reelscript_advance(ms)`, and steps CSS transitions /
+ * animations by the same amount through the Web Animations API. Chromium's
+ * own compositor keeps running on real time, so screenshots and input
+ * dispatch never stall — only the *content's* clock is deterministic.
+ */
+export const CLOCK_SHIM = String.raw `
+(() => {
+  if (window.__reelscript_advance) return;
+  let now = 0;
+  let nextId = 1;
+  const timers = new Map();
+  const rafs = new Map();
+  const tracked = new WeakMap(); // Animation -> virtual currentTime
+  const epoch = Date.now();
+  const RealDate = Date;
+
+  const g = window;
+  g.setTimeout = (fn, delay = 0, ...args) => {
+    const id = nextId++;
+    timers.set(id, { at: now + Math.max(0, Number(delay) || 0), fn, args, every: 0 });
+    return id;
+  };
+  g.setInterval = (fn, delay = 0, ...args) => {
+    const id = nextId++;
+    const every = Math.max(1, Number(delay) || 0);
+    timers.set(id, { at: now + every, fn, args, every });
+    return id;
+  };
+  g.clearTimeout = g.clearInterval = (id) => { timers.delete(id); };
+  g.requestAnimationFrame = (fn) => { const id = nextId++; rafs.set(id, fn); return id; };
+  g.cancelAnimationFrame = (id) => { rafs.delete(id); };
+  g.requestIdleCallback = (fn) => g.setTimeout(() => fn({ didTimeout: false, timeRemaining: () => 8 }), 1);
+  g.cancelIdleCallback = g.clearTimeout;
+  Performance.prototype.now = () => now;
+  class VDate extends RealDate {
+    constructor(...a) { a.length === 0 ? super(epoch + now) : super(...a); }
+    static now() { return epoch + now; }
+  }
+  g.Date = VDate;
+
+  const call = (fn, args) => { try { typeof fn === "function" ? fn(...args) : new Function(String(fn))(); } catch (e) { console.error(e); } };
+
+  g.__reelscript_advance = (ms) => {
+    const target = now + ms;
+    // Fire timers in chronological order, including ones scheduled while firing.
+    for (let guard = 0; guard < 10000; guard++) {
+      let pick = null;
+      for (const [id, t] of timers) if (t.at <= target && (!pick || t.at < pick[1].at)) pick = [id, t];
+      if (!pick) break;
+      const [id, t] = pick;
+      now = t.at;
+      if (t.every) t.at += t.every; else timers.delete(id);
+      call(t.fn, t.args);
+    }
+    now = target;
+    // One animation frame per rendered frame.
+    const cbs = Array.from(rafs.values());
+    rafs.clear();
+    for (const cb of cbs) call(cb, [now]);
+    // Step every running CSS transition / animation by exactly ms.
+    for (const a of document.getAnimations()) {
+      let ct = tracked.get(a);
+      if (ct === undefined) {
+        // New since last frame: restart it on this frame boundary.
+        a.pause();
+        ct = 0;
+      } else {
+        ct += ms;
+      }
+      const timing = a.effect && a.effect.getComputedTiming();
+      const end = timing ? timing.endTime : Infinity;
+      if (ct >= end) {
+        tracked.delete(a);
+        a.playbackRate = 1;
+        a.finish();
+      } else {
+        a.currentTime = ct;
+        tracked.set(a, ct);
+      }
+    }
+  };
+})();
+`;

package/dist/cursor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cursor + click-feedback sprites, rasterized from SVG and cached by size.
+ * Coordinates: the sprite's hotspot (arrow tip) is at (hx, hy).
+ */
+export interface Sprite {
+    data: Buffer;
+    width: number;
+    height: number;
+    hx: number;
+    hy: number;
+}
+export declare function cursorSprite(heightPx: number): Promise<Sprite>;
+/** Translucent ring that expands from the click point. */
+export declare function rippleSprite(radius: number, opacity: number): Promise<Sprite>;