videowright 0.1.0

package/dist/cli/script_cmd.js

@@ -0,0 +1,88 @@
+/**
+ * `videowright script` — load a timeline and segments in Node, produce the
+ * voiceover script as Markdown.
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { script } from "../script/script.js";
+import { discoverProject } from "./discover_project.js";
+import { loadModule } from "./ts_loader.js";
+/**
+ * Build a SegmentLoaderMap by walking the cwd/segments/ directory in Node.
+ * Each segments/<id>/index.ts becomes an entry in the map.
+ * Directories without an index.ts are warned about.
+ */
+export function buildNodeSegmentLoaderMap(cwd) {
+    const segmentsDir = join(cwd, "segments");
+    const map = new Map();
+    if (!existsSync(segmentsDir))
+        return map;
+    let entries;
+    try {
+        entries = readdirSync(segmentsDir);
+    }
+    catch {
+        return map;
+    }
+    const skipped = [];
+    for (const entry of entries) {
+        const entryPath = join(segmentsDir, entry);
+        // Only consider directories
+        try {
+            if (!statSync(entryPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const indexPath = join(entryPath, "index.ts");
+        if (existsSync(indexPath)) {
+            const absPath = resolve(indexPath);
+            map.set(entry, async () => {
+                const mod = await loadModule(absPath);
+                return { default: mod.default };
+            });
+        }
+        else {
+            skipped.push(entry);
+        }
+    }
+    if (skipped.length > 0) {
+        console.warn(`buildNodeSegmentLoaderMap: skipped directories without index.ts: ${skipped.join(", ")}`);
+    }
+    return map;
+}
+/**
+ * Run the script flow. Returns the markdown and optional write path.
+ */
+export async function runScript(opts) {
+    const { cwd, positional, write, verbose } = opts;
+    const { configPath, timelinePath } = discoverProject(cwd, positional, "script");
+    if (verbose) {
+        console.log(`config: ${configPath}`);
+        console.log(`timeline: ${timelinePath}`);
+    }
+    // 3. Load config + timeline (config loaded to validate; not used directly here)
+    await loadModule(configPath);
+    const timelineMod = await loadModule(timelinePath);
+    const timeline = timelineMod.default;
+    // 4. Build segment loader map from filesystem
+    const segmentLoaders = buildNodeSegmentLoaderMap(cwd);
+    // 5. Generate script
+    const markdown = await script(timeline, segmentLoaders);
+    // 6. Write or return
+    let writtenTo;
+    if (write) {
+        // Infer video folder from timeline path: parent dir of timeline.ts
+        const videoDir = dirname(timelinePath);
+        const voiceoverScriptDir = join(videoDir, "voiceover_script");
+        if (!existsSync(voiceoverScriptDir)) {
+            mkdirSync(voiceoverScriptDir, { recursive: true });
+        }
+        const outputPath = join(voiceoverScriptDir, "script.md");
+        writeFileSync(outputPath, markdown, "utf-8");
+        writtenTo = outputPath;
+    }
+    return { markdown, writtenTo };
+}
+//# sourceMappingURL=script_cmd.js.map

package/dist/cli/script_cmd.js.map

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

package/dist/cli/time_shim.d.ts

@@ -0,0 +1,44 @@
+/**
+ * JS time injection shim for deterministic rendering.
+ *
+ * This module exports the shim source code as a string. The render driver
+ * injects it into the page via `page.addInitScript()` BEFORE navigation,
+ * so it runs in every frame context before any user code.
+ *
+ * ## Two-mode design
+ *
+ * The shim operates in two modes:
+ *
+ * 1. **Passthrough mode** (default, during boot): Virtual clock advances at
+ *    wall-clock rate. setTimeout, setInterval, requestAnimationFrame all
+ *    delegate to the REAL browser implementations so that Vite HMR, module
+ *    loading, library init (lottie-web, echarts, three.js), and the render
+ *    entry boot() function can complete normally. `performance.now()` and
+ *    `Date.now()` return real elapsed time since shim install. Real timer
+ *    IDs and metadata are tracked so they can be converted to virtual
+ *    timers at mode switch (preserving pending callbacks).
+ *
+ * 2. **Driver-controlled mode** (during render capture): The driver controls
+ *    advancement via `__VW_ADVANCE_CLOCK__(deltaMs)`. Timers and RAF
+ *    callbacks only fire when the driver advances time. WAAPI animations
+ *    are paused and driven by explicit currentTime updates.
+ *
+ * The shim starts in passthrough mode. When the Node driver is ready to
+ * start capture (after `__VW_RENDER_READY__` is set), it calls
+ * `window.__VW_ENGAGE_VIRTUAL_TIME__()` to switch to driver-controlled
+ * mode. From that point, real timers stop firing and the driver advances
+ * virtual time explicitly.
+ *
+ * The shim overrides:
+ * - Date (no-arg constructor), Date.now
+ * - performance.now
+ * - setTimeout, setInterval, clearTimeout, clearInterval
+ * - requestAnimationFrame, cancelAnimationFrame
+ * - Element.prototype.animate (for WAAPI determinism)
+ *
+ * It exposes:
+ * - window.__VW_ADVANCE_CLOCK__(deltaMs) — advance the virtual clock, fire timers/RAFs, update WAAPI
+ * - window.__VW_ENGAGE_VIRTUAL_TIME__() — switch from passthrough to driver-controlled mode
+ */
+export declare const TIME_SHIM_SOURCE = "\n(function() {\n  // Preserve real implementations\n  var RealDate = Date;\n  var realDateNow = Date.now.bind(Date);\n  var realPerfNow = performance.now.bind(performance);\n  var realSetTimeout = window.setTimeout.bind(window);\n  var realClearTimeout = window.clearTimeout.bind(window);\n  var realSetInterval = window.setInterval.bind(window);\n  var realClearInterval = window.clearInterval.bind(window);\n  var realRAF = window.requestAnimationFrame.bind(window);\n  var realCAF = window.cancelAnimationFrame.bind(window);\n  var realElementAnimate = Element.prototype.animate;\n\n  // ----- Mode state -----\n  // 'passthrough' = boot phase, real timers run normally\n  // 'driver'      = render capture, driver controls time\n  var mode = 'passthrough';\n\n  // ----- Passthrough bookkeeping -----\n  // Wall-clock reference captured at shim install time\n  var shimInstallPerf = realPerfNow();\n  var shimInstallDate = realDateNow();\n  // Track real timer/RAF IDs with metadata so we can convert them at mode switch\n  var realTimerMeta = new Map();      // real setTimeout ID -> { cb, args, fireAtRealMs }\n  var realIntervalMeta = new Map();   // real setInterval ID -> { cb, args, intervalMs, nextFireRealMs }\n  var realRafMeta = new Map();        // real RAF ID -> { cb }\n\n  // ----- Driver-mode state -----\n  var virtualMs = 0;\n  var nextTimerId = 1;\n  var timers = new Map();     // id -> { fireAt, cb, args, repeat? }\n  var rafCallbacks = [];      // [{ id, cb }]\n  var trackedAnimations = []; // [{ animation, startVirtualMs }]\n\n  // ----- performance.now -----\n  performance.now = function() {\n    if (mode === 'passthrough') {\n      return realPerfNow() - shimInstallPerf;\n    }\n    return virtualMs;\n  };\n\n  // ----- Date -----\n  function VirtualDate() {\n    if (arguments.length === 0) {\n      if (mode === 'passthrough') {\n        return new RealDate(realDateNow());\n      }\n      return new RealDate(shimInstallDate + virtualMs);\n    }\n    switch (arguments.length) {\n      case 1: return new RealDate(arguments[0]);\n      case 2: return new RealDate(arguments[0], arguments[1]);\n      case 3: return new RealDate(arguments[0], arguments[1], arguments[2]);\n      case 4: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3]);\n      case 5: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);\n      case 6: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4], arguments[5]);\n      default: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4], arguments[5], arguments[6]);\n    }\n  }\n  VirtualDate.now = function() {\n    if (mode === 'passthrough') {\n      return realDateNow();\n    }\n    return Math.floor(shimInstallDate + virtualMs);\n  };\n  VirtualDate.parse = RealDate.parse;\n  VirtualDate.UTC = RealDate.UTC;\n  VirtualDate.prototype = RealDate.prototype;\n  window.Date = VirtualDate;\n\n  // ----- setTimeout / clearTimeout -----\n  window.setTimeout = function(cb, ms) {\n    if (typeof cb !== 'function') return 0;\n    var delay = (ms || 0);\n    var args = Array.prototype.slice.call(arguments, 2);\n    if (mode === 'passthrough') {\n      var fireAtRealMs = realPerfNow() + delay;\n      // Wrap the callback so that if the real timer fires before engagement,\n      // its metadata is removed -- preventing a double-fire at engagement.\n      var realId = realSetTimeout(function() { realTimerMeta.delete(realId); cb.apply(null, args); }, delay);\n      realTimerMeta.set(realId, { cb: cb, args: args, fireAtRealMs: fireAtRealMs });\n      return realId;\n    }\n    var id = nextTimerId++;\n    timers.set(id, { fireAt: virtualMs + delay, cb: cb, args: args });\n    return id;\n  };\n  window.clearTimeout = function(id) {\n    if (mode === 'passthrough') {\n      realTimerMeta.delete(id);\n      realClearTimeout(id);\n      return;\n    }\n    timers.delete(id);\n  };\n\n  // ----- setInterval / clearInterval -----\n  window.setInterval = function(cb, ms) {\n    if (typeof cb !== 'function') return 0;\n    if (mode === 'passthrough') {\n      var intervalMs = Math.max(ms || 0, 1);\n      var args = Array.prototype.slice.call(arguments, 2);\n      var meta = { cb: cb, args: args, intervalMs: intervalMs, nextFireRealMs: realPerfNow() + intervalMs };\n      // Wrap the callback to update nextFireRealMs each time the real interval\n      // fires, so that at engagement we compute an accurate remaining time\n      // instead of using the stale initial registration time.\n      var realId = realSetInterval(function() { meta.nextFireRealMs = realPerfNow() + intervalMs; cb.apply(null, args); }, intervalMs);\n      realIntervalMeta.set(realId, meta);\n      return realId;\n    }\n    var interval = Math.max(ms || 0, 1);\n    var id = nextTimerId++;\n    var args = Array.prototype.slice.call(arguments, 2);\n    timers.set(id, { fireAt: virtualMs + interval, cb: cb, args: args, repeat: interval });\n    return id;\n  };\n  window.clearInterval = function(id) {\n    if (mode === 'passthrough') {\n      realIntervalMeta.delete(id);\n      realClearInterval(id);\n      return;\n    }\n    timers.delete(id);\n  };\n\n  // ----- requestAnimationFrame / cancelAnimationFrame -----\n  window.requestAnimationFrame = function(cb) {\n    if (mode === 'passthrough') {\n      // Wrap the callback so that if the real rAF fires before engagement,\n      // its metadata is removed -- preventing a double-fire at engagement.\n      var realId = realRAF(function(timestamp) { realRafMeta.delete(realId); cb(timestamp); });\n      realRafMeta.set(realId, { cb: cb });\n      return realId;\n    }\n    var id = nextTimerId++;\n    rafCallbacks.push({ id: id, cb: cb });\n    return id;\n  };\n  window.cancelAnimationFrame = function(id) {\n    if (mode === 'passthrough') {\n      realRafMeta.delete(id);\n      realCAF(id);\n      return;\n    }\n    for (var i = 0; i < rafCallbacks.length; i++) {\n      if (rafCallbacks[i].id === id) {\n        rafCallbacks.splice(i, 1);\n        break;\n      }\n    }\n  };\n\n  // ----- WAAPI: Element.prototype.animate -----\n  Element.prototype.animate = function(keyframes, options) {\n    var anim = realElementAnimate.call(this, keyframes, options);\n    if (mode === 'passthrough') {\n      // Let the animation run normally during boot; it will be captured\n      // at mode-switch time if still running.\n      return anim;\n    }\n    // Driver mode: pause and drive via currentTime\n    return trackAnimation(anim, options);\n  };\n\n  function trackAnimation(anim, options) {\n    anim.pause();\n    anim.currentTime = 0;\n    var entry = { animation: anim, startVirtualMs: virtualMs };\n    trackedAnimations.push(entry);\n    var duration = 0;\n    if (typeof options === 'number') {\n      duration = options;\n    } else if (options && typeof options.duration === 'number') {\n      duration = options.duration;\n    }\n    var delay = 0;\n    if (options && typeof options === 'object' && typeof options.delay === 'number') {\n      delay = options.delay;\n    }\n    var totalDuration = delay + duration;\n    entry.totalDuration = totalDuration;\n    entry.resolved = false;\n    var finishedPromise = new Promise(function(resolve) {\n      entry.resolve = resolve;\n    });\n    Object.defineProperty(anim, 'finished', {\n      get: function() { return finishedPromise; },\n      configurable: true\n    });\n    return anim;\n  }\n\n  // ----- Mode switch: passthrough -> driver -----\n  window.__VW_ENGAGE_VIRTUAL_TIME__ = function() {\n    if (mode === 'driver') return; // already engaged\n\n    // Set virtual time to current real elapsed so animations don't jump\n    var nowReal = realPerfNow();\n    virtualMs = nowReal - shimInstallPerf;\n\n    // Convert pending real setTimeouts to virtual timers instead of discarding\n    realTimerMeta.forEach(function(meta, realId) {\n      realClearTimeout(realId);\n      var remaining = Math.max(0, meta.fireAtRealMs - nowReal);\n      var id = nextTimerId++;\n      timers.set(id, { fireAt: virtualMs + remaining, cb: meta.cb, args: meta.args });\n    });\n    realTimerMeta.clear();\n\n    // Convert pending real setIntervals to virtual intervals\n    realIntervalMeta.forEach(function(meta, realId) {\n      realClearInterval(realId);\n      var remaining = Math.max(0, meta.nextFireRealMs - nowReal);\n      var id = nextTimerId++;\n      timers.set(id, { fireAt: virtualMs + remaining, cb: meta.cb, args: meta.args, repeat: meta.intervalMs });\n    });\n    realIntervalMeta.clear();\n\n    // Convert pending real rAF callbacks into virtual RAF queue\n    realRafMeta.forEach(function(meta, realId) {\n      realCAF(realId);\n      var id = nextTimerId++;\n      rafCallbacks.push({ id: id, cb: meta.cb });\n    });\n    realRafMeta.clear();\n\n    // Capture any WAAPI animations still running from boot and pause+track them\n    try {\n      var liveAnims = document.getAnimations();\n      for (var i = 0; i < liveAnims.length; i++) {\n        var a = liveAnims[i];\n        if (a.playState === 'running' || a.playState === 'paused') {\n          var ct = a.currentTime || 0;\n          a.pause();\n          a.currentTime = ct;\n          var entry = {\n            animation: a,\n            startVirtualMs: virtualMs - ct,\n            totalDuration: undefined,\n            resolved: false,\n            resolve: undefined\n          };\n          // Try to read duration from the animation effect\n          try {\n            var timing = a.effect && a.effect.getTiming ? a.effect.getTiming() : null;\n            if (timing) {\n              var dur = typeof timing.duration === 'number' ? timing.duration : 0;\n              var del = typeof timing.delay === 'number' ? timing.delay : 0;\n              entry.totalDuration = del + dur;\n            }\n          } catch(e) {}\n          var finishedPromise = new Promise(function(resolve) {\n            entry.resolve = resolve;\n          });\n          Object.defineProperty(a, 'finished', {\n            get: function() { return finishedPromise; },\n            configurable: true\n          });\n          trackedAnimations.push(entry);\n        }\n      }\n    } catch(e) {\n      // document.getAnimations may not be available in all contexts\n    }\n\n    mode = 'driver';\n  };\n\n  // ----- Clock advance driver -----\n  window.__VW_ADVANCE_CLOCK__ = async function(deltaMs) {\n    if (mode === 'passthrough') return; // no-op during boot\n\n    var target = virtualMs + deltaMs;\n\n    // Fire timers in chronological order up to target.\n    // The function is async so that microtasks (e.g. Promise resolutions from\n    // ctx.hold) drain between timer fires. This ensures awaiting code resumes\n    // at virtualMs = fireAt (the timer's actual scheduled time) rather than at\n    // the frame boundary (target), eliminating per-hold rounding drift.\n    var safety = 10000;\n    while (safety-- > 0) {\n      var earliestId = null;\n      var earliestTimer = null;\n      timers.forEach(function(t, id) {\n        if (t.fireAt <= target && (earliestTimer === null || t.fireAt < earliestTimer.fireAt)) {\n          earliestId = id;\n          earliestTimer = t;\n        }\n      });\n      if (!earliestTimer) break;\n\n      virtualMs = earliestTimer.fireAt;\n      if (earliestTimer.repeat !== undefined) {\n        timers.set(earliestId, {\n          fireAt: virtualMs + earliestTimer.repeat,\n          cb: earliestTimer.cb,\n          args: earliestTimer.args,\n          repeat: earliestTimer.repeat\n        });\n      } else {\n        timers.delete(earliestId);\n      }\n      try { earliestTimer.cb.apply(null, earliestTimer.args || []); } catch(e) { console.error('[VW shim] timer error:', e); }\n\n      // Drain microtasks so awaiting code (e.g. ctx.hold Promise resolution)\n      // resumes at virtualMs = fireAt and registers its next timer relative to\n      // fireAt, not target. Multiple awaits handle chained async continuations.\n      for (var d = 0; d < 8; d++) await Promise.resolve();\n    }\n\n    // Final advance to target\n    virtualMs = target;\n\n    // Fire all queued RAF callbacks\n    var queued = rafCallbacks.splice(0);\n    for (var i = 0; i < queued.length; i++) {\n      try { queued[i].cb(virtualMs); } catch(e) { console.error('[VW shim] RAF error:', e); }\n    }\n\n    // Update WAAPI animations\n    for (var j = trackedAnimations.length - 1; j >= 0; j--) {\n      var entry = trackedAnimations[j];\n      var anim = entry.animation;\n      // Skip cancelled animations\n      if (anim.playState === 'idle') {\n        trackedAnimations.splice(j, 1);\n        continue;\n      }\n      var elapsed = virtualMs - entry.startVirtualMs;\n      try {\n        anim.currentTime = elapsed;\n      } catch(e) {\n        trackedAnimations.splice(j, 1);\n        continue;\n      }\n      // Check if animation is complete\n      if (entry.totalDuration !== undefined && elapsed >= entry.totalDuration && !entry.resolved) {\n        entry.resolved = true;\n        if (entry.resolve) entry.resolve(anim);\n        trackedAnimations.splice(j, 1);\n      }\n    }\n  };\n})();\n";
+//# sourceMappingURL=time_shim.d.ts.map

package/dist/cli/time_shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time_shim.d.ts","sourceRoot":"","sources":["../../src/cli/time_shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,eAAO,MAAM,gBAAgB,i7ZA0V5B,CAAC"}

package/dist/cli/time_shim.js

@@ -0,0 +1,390 @@
+/**
+ * JS time injection shim for deterministic rendering.
+ *
+ * This module exports the shim source code as a string. The render driver
+ * injects it into the page via `page.addInitScript()` BEFORE navigation,
+ * so it runs in every frame context before any user code.
+ *
+ * ## Two-mode design
+ *
+ * The shim operates in two modes:
+ *
+ * 1. **Passthrough mode** (default, during boot): Virtual clock advances at
+ *    wall-clock rate. setTimeout, setInterval, requestAnimationFrame all
+ *    delegate to the REAL browser implementations so that Vite HMR, module
+ *    loading, library init (lottie-web, echarts, three.js), and the render
+ *    entry boot() function can complete normally. `performance.now()` and
+ *    `Date.now()` return real elapsed time since shim install. Real timer
+ *    IDs and metadata are tracked so they can be converted to virtual
+ *    timers at mode switch (preserving pending callbacks).
+ *
+ * 2. **Driver-controlled mode** (during render capture): The driver controls
+ *    advancement via `__VW_ADVANCE_CLOCK__(deltaMs)`. Timers and RAF
+ *    callbacks only fire when the driver advances time. WAAPI animations
+ *    are paused and driven by explicit currentTime updates.
+ *
+ * The shim starts in passthrough mode. When the Node driver is ready to
+ * start capture (after `__VW_RENDER_READY__` is set), it calls
+ * `window.__VW_ENGAGE_VIRTUAL_TIME__()` to switch to driver-controlled
+ * mode. From that point, real timers stop firing and the driver advances
+ * virtual time explicitly.
+ *
+ * The shim overrides:
+ * - Date (no-arg constructor), Date.now
+ * - performance.now
+ * - setTimeout, setInterval, clearTimeout, clearInterval
+ * - requestAnimationFrame, cancelAnimationFrame
+ * - Element.prototype.animate (for WAAPI determinism)
+ *
+ * It exposes:
+ * - window.__VW_ADVANCE_CLOCK__(deltaMs) — advance the virtual clock, fire timers/RAFs, update WAAPI
+ * - window.__VW_ENGAGE_VIRTUAL_TIME__() — switch from passthrough to driver-controlled mode
+ */
+export const TIME_SHIM_SOURCE = `
+(function() {
+  // Preserve real implementations
+  var RealDate = Date;
+  var realDateNow = Date.now.bind(Date);
+  var realPerfNow = performance.now.bind(performance);
+  var realSetTimeout = window.setTimeout.bind(window);
+  var realClearTimeout = window.clearTimeout.bind(window);
+  var realSetInterval = window.setInterval.bind(window);
+  var realClearInterval = window.clearInterval.bind(window);
+  var realRAF = window.requestAnimationFrame.bind(window);
+  var realCAF = window.cancelAnimationFrame.bind(window);
+  var realElementAnimate = Element.prototype.animate;
+
+  // ----- Mode state -----
+  // 'passthrough' = boot phase, real timers run normally
+  // 'driver'      = render capture, driver controls time
+  var mode = 'passthrough';
+
+  // ----- Passthrough bookkeeping -----
+  // Wall-clock reference captured at shim install time
+  var shimInstallPerf = realPerfNow();
+  var shimInstallDate = realDateNow();
+  // Track real timer/RAF IDs with metadata so we can convert them at mode switch
+  var realTimerMeta = new Map();      // real setTimeout ID -> { cb, args, fireAtRealMs }
+  var realIntervalMeta = new Map();   // real setInterval ID -> { cb, args, intervalMs, nextFireRealMs }
+  var realRafMeta = new Map();        // real RAF ID -> { cb }
+
+  // ----- Driver-mode state -----
+  var virtualMs = 0;
+  var nextTimerId = 1;
+  var timers = new Map();     // id -> { fireAt, cb, args, repeat? }
+  var rafCallbacks = [];      // [{ id, cb }]
+  var trackedAnimations = []; // [{ animation, startVirtualMs }]
+
+  // ----- performance.now -----
+  performance.now = function() {
+    if (mode === 'passthrough') {
+      return realPerfNow() - shimInstallPerf;
+    }
+    return virtualMs;
+  };
+
+  // ----- Date -----
+  function VirtualDate() {
+    if (arguments.length === 0) {
+      if (mode === 'passthrough') {
+        return new RealDate(realDateNow());
+      }
+      return new RealDate(shimInstallDate + virtualMs);
+    }
+    switch (arguments.length) {
+      case 1: return new RealDate(arguments[0]);
+      case 2: return new RealDate(arguments[0], arguments[1]);
+      case 3: return new RealDate(arguments[0], arguments[1], arguments[2]);
+      case 4: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3]);
+      case 5: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
+      case 6: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4], arguments[5]);
+      default: return new RealDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4], arguments[5], arguments[6]);
+    }
+  }
+  VirtualDate.now = function() {
+    if (mode === 'passthrough') {
+      return realDateNow();
+    }
+    return Math.floor(shimInstallDate + virtualMs);
+  };
+  VirtualDate.parse = RealDate.parse;
+  VirtualDate.UTC = RealDate.UTC;
+  VirtualDate.prototype = RealDate.prototype;
+  window.Date = VirtualDate;
+
+  // ----- setTimeout / clearTimeout -----
+  window.setTimeout = function(cb, ms) {
+    if (typeof cb !== 'function') return 0;
+    var delay = (ms || 0);
+    var args = Array.prototype.slice.call(arguments, 2);
+    if (mode === 'passthrough') {
+      var fireAtRealMs = realPerfNow() + delay;
+      // Wrap the callback so that if the real timer fires before engagement,
+      // its metadata is removed -- preventing a double-fire at engagement.
+      var realId = realSetTimeout(function() { realTimerMeta.delete(realId); cb.apply(null, args); }, delay);
+      realTimerMeta.set(realId, { cb: cb, args: args, fireAtRealMs: fireAtRealMs });
+      return realId;
+    }
+    var id = nextTimerId++;
+    timers.set(id, { fireAt: virtualMs + delay, cb: cb, args: args });
+    return id;
+  };
+  window.clearTimeout = function(id) {
+    if (mode === 'passthrough') {
+      realTimerMeta.delete(id);
+      realClearTimeout(id);
+      return;
+    }
+    timers.delete(id);
+  };
+
+  // ----- setInterval / clearInterval -----
+  window.setInterval = function(cb, ms) {
+    if (typeof cb !== 'function') return 0;
+    if (mode === 'passthrough') {
+      var intervalMs = Math.max(ms || 0, 1);
+      var args = Array.prototype.slice.call(arguments, 2);
+      var meta = { cb: cb, args: args, intervalMs: intervalMs, nextFireRealMs: realPerfNow() + intervalMs };
+      // Wrap the callback to update nextFireRealMs each time the real interval
+      // fires, so that at engagement we compute an accurate remaining time
+      // instead of using the stale initial registration time.
+      var realId = realSetInterval(function() { meta.nextFireRealMs = realPerfNow() + intervalMs; cb.apply(null, args); }, intervalMs);
+      realIntervalMeta.set(realId, meta);
+      return realId;
+    }
+    var interval = Math.max(ms || 0, 1);
+    var id = nextTimerId++;
+    var args = Array.prototype.slice.call(arguments, 2);
+    timers.set(id, { fireAt: virtualMs + interval, cb: cb, args: args, repeat: interval });
+    return id;
+  };
+  window.clearInterval = function(id) {
+    if (mode === 'passthrough') {
+      realIntervalMeta.delete(id);
+      realClearInterval(id);
+      return;
+    }
+    timers.delete(id);
+  };
+
+  // ----- requestAnimationFrame / cancelAnimationFrame -----
+  window.requestAnimationFrame = function(cb) {
+    if (mode === 'passthrough') {
+      // Wrap the callback so that if the real rAF fires before engagement,
+      // its metadata is removed -- preventing a double-fire at engagement.
+      var realId = realRAF(function(timestamp) { realRafMeta.delete(realId); cb(timestamp); });
+      realRafMeta.set(realId, { cb: cb });
+      return realId;
+    }
+    var id = nextTimerId++;
+    rafCallbacks.push({ id: id, cb: cb });
+    return id;
+  };
+  window.cancelAnimationFrame = function(id) {
+    if (mode === 'passthrough') {
+      realRafMeta.delete(id);
+      realCAF(id);
+      return;
+    }
+    for (var i = 0; i < rafCallbacks.length; i++) {
+      if (rafCallbacks[i].id === id) {
+        rafCallbacks.splice(i, 1);
+        break;
+      }
+    }
+  };
+
+  // ----- WAAPI: Element.prototype.animate -----
+  Element.prototype.animate = function(keyframes, options) {
+    var anim = realElementAnimate.call(this, keyframes, options);
+    if (mode === 'passthrough') {
+      // Let the animation run normally during boot; it will be captured
+      // at mode-switch time if still running.
+      return anim;
+    }
+    // Driver mode: pause and drive via currentTime
+    return trackAnimation(anim, options);
+  };
+
+  function trackAnimation(anim, options) {
+    anim.pause();
+    anim.currentTime = 0;
+    var entry = { animation: anim, startVirtualMs: virtualMs };
+    trackedAnimations.push(entry);
+    var duration = 0;
+    if (typeof options === 'number') {
+      duration = options;
+    } else if (options && typeof options.duration === 'number') {
+      duration = options.duration;
+    }
+    var delay = 0;
+    if (options && typeof options === 'object' && typeof options.delay === 'number') {
+      delay = options.delay;
+    }
+    var totalDuration = delay + duration;
+    entry.totalDuration = totalDuration;
+    entry.resolved = false;
+    var finishedPromise = new Promise(function(resolve) {
+      entry.resolve = resolve;
+    });
+    Object.defineProperty(anim, 'finished', {
+      get: function() { return finishedPromise; },
+      configurable: true
+    });
+    return anim;
+  }
+
+  // ----- Mode switch: passthrough -> driver -----
+  window.__VW_ENGAGE_VIRTUAL_TIME__ = function() {
+    if (mode === 'driver') return; // already engaged
+
+    // Set virtual time to current real elapsed so animations don't jump
+    var nowReal = realPerfNow();
+    virtualMs = nowReal - shimInstallPerf;
+
+    // Convert pending real setTimeouts to virtual timers instead of discarding
+    realTimerMeta.forEach(function(meta, realId) {
+      realClearTimeout(realId);
+      var remaining = Math.max(0, meta.fireAtRealMs - nowReal);
+      var id = nextTimerId++;
+      timers.set(id, { fireAt: virtualMs + remaining, cb: meta.cb, args: meta.args });
+    });
+    realTimerMeta.clear();
+
+    // Convert pending real setIntervals to virtual intervals
+    realIntervalMeta.forEach(function(meta, realId) {
+      realClearInterval(realId);
+      var remaining = Math.max(0, meta.nextFireRealMs - nowReal);
+      var id = nextTimerId++;
+      timers.set(id, { fireAt: virtualMs + remaining, cb: meta.cb, args: meta.args, repeat: meta.intervalMs });
+    });
+    realIntervalMeta.clear();
+
+    // Convert pending real rAF callbacks into virtual RAF queue
+    realRafMeta.forEach(function(meta, realId) {
+      realCAF(realId);
+      var id = nextTimerId++;
+      rafCallbacks.push({ id: id, cb: meta.cb });
+    });
+    realRafMeta.clear();
+
+    // Capture any WAAPI animations still running from boot and pause+track them
+    try {
+      var liveAnims = document.getAnimations();
+      for (var i = 0; i < liveAnims.length; i++) {
+        var a = liveAnims[i];
+        if (a.playState === 'running' || a.playState === 'paused') {
+          var ct = a.currentTime || 0;
+          a.pause();
+          a.currentTime = ct;
+          var entry = {
+            animation: a,
+            startVirtualMs: virtualMs - ct,
+            totalDuration: undefined,
+            resolved: false,
+            resolve: undefined
+          };
+          // Try to read duration from the animation effect
+          try {
+            var timing = a.effect && a.effect.getTiming ? a.effect.getTiming() : null;
+            if (timing) {
+              var dur = typeof timing.duration === 'number' ? timing.duration : 0;
+              var del = typeof timing.delay === 'number' ? timing.delay : 0;
+              entry.totalDuration = del + dur;
+            }
+          } catch(e) {}
+          var finishedPromise = new Promise(function(resolve) {
+            entry.resolve = resolve;
+          });
+          Object.defineProperty(a, 'finished', {
+            get: function() { return finishedPromise; },
+            configurable: true
+          });
+          trackedAnimations.push(entry);
+        }
+      }
+    } catch(e) {
+      // document.getAnimations may not be available in all contexts
+    }
+
+    mode = 'driver';
+  };
+
+  // ----- Clock advance driver -----
+  window.__VW_ADVANCE_CLOCK__ = async function(deltaMs) {
+    if (mode === 'passthrough') return; // no-op during boot
+
+    var target = virtualMs + deltaMs;
+
+    // Fire timers in chronological order up to target.
+    // The function is async so that microtasks (e.g. Promise resolutions from
+    // ctx.hold) drain between timer fires. This ensures awaiting code resumes
+    // at virtualMs = fireAt (the timer's actual scheduled time) rather than at
+    // the frame boundary (target), eliminating per-hold rounding drift.
+    var safety = 10000;
+    while (safety-- > 0) {
+      var earliestId = null;
+      var earliestTimer = null;
+      timers.forEach(function(t, id) {
+        if (t.fireAt <= target && (earliestTimer === null || t.fireAt < earliestTimer.fireAt)) {
+          earliestId = id;
+          earliestTimer = t;
+        }
+      });
+      if (!earliestTimer) break;
+
+      virtualMs = earliestTimer.fireAt;
+      if (earliestTimer.repeat !== undefined) {
+        timers.set(earliestId, {
+          fireAt: virtualMs + earliestTimer.repeat,
+          cb: earliestTimer.cb,
+          args: earliestTimer.args,
+          repeat: earliestTimer.repeat
+        });
+      } else {
+        timers.delete(earliestId);
+      }
+      try { earliestTimer.cb.apply(null, earliestTimer.args || []); } catch(e) { console.error('[VW shim] timer error:', e); }
+
+      // Drain microtasks so awaiting code (e.g. ctx.hold Promise resolution)
+      // resumes at virtualMs = fireAt and registers its next timer relative to
+      // fireAt, not target. Multiple awaits handle chained async continuations.
+      for (var d = 0; d < 8; d++) await Promise.resolve();
+    }
+
+    // Final advance to target
+    virtualMs = target;
+
+    // Fire all queued RAF callbacks
+    var queued = rafCallbacks.splice(0);
+    for (var i = 0; i < queued.length; i++) {
+      try { queued[i].cb(virtualMs); } catch(e) { console.error('[VW shim] RAF error:', e); }
+    }
+
+    // Update WAAPI animations
+    for (var j = trackedAnimations.length - 1; j >= 0; j--) {
+      var entry = trackedAnimations[j];
+      var anim = entry.animation;
+      // Skip cancelled animations
+      if (anim.playState === 'idle') {
+        trackedAnimations.splice(j, 1);
+        continue;
+      }
+      var elapsed = virtualMs - entry.startVirtualMs;
+      try {
+        anim.currentTime = elapsed;
+      } catch(e) {
+        trackedAnimations.splice(j, 1);
+        continue;
+      }
+      // Check if animation is complete
+      if (entry.totalDuration !== undefined && elapsed >= entry.totalDuration && !entry.resolved) {
+        entry.resolved = true;
+        if (entry.resolve) entry.resolve(anim);
+        trackedAnimations.splice(j, 1);
+      }
+    }
+  };
+})();
+`;
+//# sourceMappingURL=time_shim.js.map

package/dist/cli/time_shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time_shim.js","sourceRoot":"","sources":["../../src/cli/time_shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0V/B,CAAC"}

package/dist/cli/ts_loader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime TS module loader for Node using tsx.
+ * Used by the CLI to import .ts config and timeline files without a build step.
+ */
+/**
+ * Dynamically import a TypeScript module from Node at runtime.
+ * Returns the module's namespace (use .default for default exports).
+ *
+ * ## tsx double-wrap heuristic
+ *
+ * When tsx loads a CommonJS-style module (or a module with `export default`),
+ * it may produce a namespace like:
+ *
+ *   { default: { __esModule: true, default: <actual-value> } }
+ *
+ * This happens because tsx transpiles `export default X` to
+ * `module.exports.default = X` + `module.exports.__esModule = true`, then
+ * the ESM interop layer wraps the whole `module.exports` as the default export.
+ *
+ * We detect this pattern (an object default with both __esModule and default keys)
+ * and unwrap it so callers always see `{ default: <actual-value>, ... }`.
+ *
+ * If tsx changes this behavior in future versions, the detection is conservative:
+ * we only unwrap when both sentinel keys are present, so a legitimate object
+ * with those keys would be the only false positive (extremely unlikely in practice).
+ */
+export declare function loadModule(modulePath: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=ts_loader.d.ts.map

package/dist/cli/ts_loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts_loader.d.ts","sourceRoot":"","sources":["../../src/cli/ts_loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyDH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAmBrF"}