reframe-video 0.1.0

package/dist/cli.js

@@ -0,0 +1,1205 @@
+#!/usr/bin/env tsx
+
+// ../render-cli/src/cli.ts
+import { mkdtemp as mkdtemp2, readFile as readFile3, rm as rm2 } from "node:fs/promises";
+import { tmpdir as tmpdir3 } from "node:os";
+import { basename, join as join5, resolve as resolve3 } from "node:path";
+
+// ../core/src/ir.ts
+var DEFAULT_TO_DURATION = 0.5;
+var DEFAULT_TWEEN_DURATION = 0.5;
+
+// ../core/src/compile.ts
+var key = (target, prop) => `${target}.${prop}`;
+function compileScene(ir) {
+  const nodeById = /* @__PURE__ */ new Map();
+  const nodeOrder = [];
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      nodeById.set(node.id, node);
+      nodeOrder.push(node.id);
+      if (node.type === "group") collect(node.children);
+    }
+  };
+  collect(ir.nodes);
+  const initialValues = /* @__PURE__ */ new Map();
+  for (const [id, node] of nodeById) {
+    for (const [prop, value] of Object.entries(node.props)) {
+      if (typeof value === "number" || typeof value === "string") {
+        initialValues.set(key(id, prop), value);
+      }
+    }
+  }
+  if (ir.initial !== void 0) {
+    const override = ir.states?.[ir.initial] ?? {};
+    for (const [id, props] of Object.entries(override)) {
+      for (const [prop, value] of Object.entries(props)) {
+        initialValues.set(key(id, prop), value);
+      }
+    }
+  }
+  const segments = /* @__PURE__ */ new Map();
+  const current = new Map(initialValues);
+  const pushSegment = (seg) => {
+    const k = key(seg.target, seg.prop);
+    let list = segments.get(k);
+    if (!list) segments.set(k, list = []);
+    list.push(seg);
+    current.set(k, seg.to);
+  };
+  const currentValue = (target, prop) => {
+    const v = current.get(key(target, prop));
+    if (v !== void 0) return v;
+    if (prop === "opacity" || prop === "scale" || prop === "progress") return 1;
+    if (prop === "rotation") return 0;
+    throw new Error(`cannot animate "${prop}" of "${target}": no base value to start from`);
+  };
+  const labelTimes = /* @__PURE__ */ new Map();
+  const walk = (tl, start) => {
+    const end = walkInner(tl, start);
+    if ("label" in tl && tl.label !== void 0) labelTimes.set(tl.label, { t0: start, t1: end });
+    return end;
+  };
+  const walkInner = (tl, start) => {
+    switch (tl.kind) {
+      case "seq": {
+        let t = start;
+        for (const child of tl.children) t = walk(child, t);
+        return t;
+      }
+      case "par": {
+        let end = start;
+        for (const child of tl.children) end = Math.max(end, walk(child, start));
+        return end;
+      }
+      case "stagger": {
+        let end = start;
+        tl.children.forEach((child, i) => {
+          end = Math.max(end, walk(child, start + i * tl.interval));
+        });
+        return end;
+      }
+      case "wait":
+        return start + tl.duration;
+      case "tween": {
+        const duration = tl.duration ?? DEFAULT_TWEEN_DURATION;
+        for (const [prop, toValue] of Object.entries(tl.props)) {
+          pushSegment({
+            target: tl.target,
+            prop,
+            t0: start,
+            t1: start + duration,
+            from: currentValue(tl.target, prop),
+            to: toValue,
+            ...tl.ease !== void 0 && { ease: tl.ease }
+          });
+        }
+        return start + duration;
+      }
+      case "to": {
+        const override = ir.states?.[tl.state] ?? {};
+        const duration = tl.duration ?? DEFAULT_TO_DURATION;
+        const staggerInterval = tl.stagger ?? 0;
+        const targets = nodeOrder.filter(
+          (id) => id in override && (tl.filter === void 0 || tl.filter.includes(id))
+        );
+        targets.forEach((id, i) => {
+          const t0 = start + i * staggerInterval;
+          for (const [prop, toValue] of Object.entries(override[id])) {
+            pushSegment({
+              target: id,
+              prop,
+              t0,
+              t1: t0 + duration,
+              from: currentValue(id, prop),
+              to: toValue,
+              ...tl.ease !== void 0 && { ease: tl.ease }
+            });
+          }
+        });
+        const last = Math.max(0, targets.length - 1);
+        return start + duration + last * staggerInterval;
+      }
+    }
+  };
+  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
+  return {
+    ir,
+    duration: ir.duration ?? inferredEnd,
+    segments,
+    initialValues,
+    nodeById,
+    nodeOrder,
+    labelTimes
+  };
+}
+
+// ../core/src/validate.ts
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "anchor"];
+var PROPS_BY_TYPE = {
+  rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
+  ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  group: COMMON_PROPS
+};
+var SceneValidationError = class extends Error {
+  constructor(problems) {
+    super(`Scene validation failed:
+${problems.map((p) => `  - ${p}`).join("\n")}`);
+    this.problems = problems;
+    this.name = "SceneValidationError";
+  }
+  problems;
+};
+function validateScene(ir) {
+  const problems = [];
+  const nodeById = /* @__PURE__ */ new Map();
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      if (nodeById.has(node.id)) {
+        problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
+      }
+      nodeById.set(node.id, node);
+      if (node.type === "group") collect(node.children);
+    }
+  };
+  collect(ir.nodes);
+  const checkProps = (where, nodeId, props) => {
+    const node = nodeById.get(nodeId);
+    if (!node) {
+      problems.push(
+        `${where} targets unknown node "${nodeId}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+      );
+      return;
+    }
+    const allowed = PROPS_BY_TYPE[node.type];
+    for (const key2 of Object.keys(props)) {
+      if (!allowed.includes(key2)) {
+        problems.push(
+          `${where}: "${key2}" is not a prop of ${node.type} "${nodeId}" \u2014 valid props: ${allowed.join(", ")}`
+        );
+      }
+    }
+  };
+  const states = ir.states ?? {};
+  for (const [stateName, overrides] of Object.entries(states)) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      checkProps(`state "${stateName}"`, nodeId, props);
+    }
+  }
+  if (ir.initial !== void 0 && !(ir.initial in states)) {
+    problems.push(
+      `initial state "${ir.initial}" is not defined \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+    );
+  }
+  const labels = /* @__PURE__ */ new Set();
+  const checkTimeline = (tl, path) => {
+    if ("label" in tl && tl.label !== void 0) {
+      if (labels.has(tl.label)) {
+        problems.push(
+          `${path}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
+        );
+      }
+      labels.add(tl.label);
+    }
+    switch (tl.kind) {
+      case "seq":
+      case "par":
+        tl.children.forEach((c, i) => checkTimeline(c, `${path}.${tl.kind}[${i}]`));
+        break;
+      case "stagger":
+        if (tl.interval < 0) problems.push(`${path}: stagger interval must be >= 0`);
+        tl.children.forEach((c, i) => checkTimeline(c, `${path}.stagger[${i}]`));
+        break;
+      case "to":
+        if (!(tl.state in states)) {
+          problems.push(
+            `${path}: to("${tl.state}") references an undefined state \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+          );
+        }
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path}: to("${tl.state}") duration must be > 0`);
+        }
+        for (const id of tl.filter ?? []) {
+          if (!nodeById.has(id)) problems.push(`${path}: filter contains unknown node "${id}"`);
+        }
+        break;
+      case "tween":
+        checkProps(path, tl.target, tl.props);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path}: tween duration must be > 0`);
+        }
+        break;
+      case "wait":
+        if (tl.duration < 0) problems.push(`${path}: wait duration must be >= 0`);
+        break;
+    }
+  };
+  if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const [i, b] of (ir.behaviors ?? []).entries()) {
+    checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
+  }
+  if (ir.duration !== void 0 && ir.duration <= 0) {
+    problems.push("scene duration must be > 0");
+  }
+  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
+  for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
+    if (typeof cue.at === "string" && !labels.has(cue.at)) {
+      problems.push(
+        `audio.cues[${i}]: unknown timeline label "${cue.at}" \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+    if (typeof cue.at === "number" && cue.at < 0) {
+      problems.push(`audio.cues[${i}]: "at" must be >= 0`);
+    }
+    if (cue.sfx === void 0 === (cue.file === void 0)) {
+      problems.push(`audio.cues[${i}]: exactly one of "sfx" or "file" is required`);
+    }
+    if (cue.sfx !== void 0 && !SFX_NAMES.includes(cue.sfx)) {
+      problems.push(`audio.cues[${i}]: unknown sfx "${cue.sfx}" \u2014 valid: ${SFX_NAMES.join(", ")}`);
+    }
+    if (cue.gain !== void 0 && cue.gain < 0) {
+      problems.push(`audio.cues[${i}]: gain must be >= 0`);
+    }
+  }
+  const duck = ir.audio?.bgm?.duck;
+  if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
+    problems.push("audio.bgm.duck.depth must be in [0, 1]");
+  }
+  if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
+    problems.push('audio.bgm: use either "file" or "synth", not both');
+  }
+  if (problems.length > 0) throw new SceneValidationError(problems);
+}
+
+// ../core/src/compose.ts
+var SCENE_PATCHABLE = ["background", "duration", "fps"];
+function composeScene(base, ...overlays) {
+  const ir = structuredClone(base);
+  const report = { applied: [], orphans: [], warnings: [] };
+  overlays.forEach((overlay, index) => {
+    const layer = overlay.name ?? `overlay-${index}`;
+    if (overlay.target !== void 0 && overlay.target !== ir.id) {
+      report.warnings.push(
+        `${layer}: authored against scene "${overlay.target}" but composing onto "${ir.id}"`
+      );
+    }
+    applyOverlay(ir, overlay, layer, report);
+  });
+  validateScene(ir);
+  return { ir, report };
+}
+function applyOverlay(ir, overlay, layer, report) {
+  const nodeById = /* @__PURE__ */ new Map();
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      nodeById.set(node.id, node);
+      if (node.type === "group") collect(node.children);
+    }
+  };
+  collect(ir.nodes);
+  const knownIds = () => [...nodeById.keys()].join(", ");
+  const orphan = (address, reason) => report.orphans.push({ layer, address, reason });
+  const applied = (address, action) => report.applied.push({ layer, address, action });
+  const patchProps = (address, node, target, patch) => {
+    const allowed = PROPS_BY_TYPE[node.type];
+    for (const [prop, value] of Object.entries(patch)) {
+      if (!allowed.includes(prop)) {
+        orphan(
+          `${address}.${prop}`,
+          `"${prop}" is not a prop of ${node.type} "${node.id}" \u2014 the base may have changed this node's type; valid props: ${allowed.join(", ")}`
+        );
+        continue;
+      }
+      if (value === null) {
+        delete target[prop];
+        applied(`${address}.${prop}`, "unset");
+      } else {
+        target[prop] = value;
+        applied(`${address}.${prop}`, "set");
+      }
+    }
+  };
+  if (overlay.scene) {
+    for (const key2 of SCENE_PATCHABLE) {
+      const value = overlay.scene[key2];
+      if (value !== void 0) {
+        ir[key2] = value;
+        applied(`scene.${key2}`, "set");
+      }
+    }
+  }
+  for (const [id, patch] of Object.entries(overlay.nodes ?? {})) {
+    const node = nodeById.get(id);
+    if (!node) {
+      orphan(
+        `nodes.${id}`,
+        `unknown node "${id}" \u2014 known ids: ${knownIds()}; did the base regeneration rename it?`
+      );
+      continue;
+    }
+    patchProps(`nodes.${id}`, node, node.props, patch);
+  }
+  for (const [stateName, statePatch] of Object.entries(overlay.states ?? {})) {
+    const state = ir.states?.[stateName];
+    if (!state) {
+      orphan(
+        `states.${stateName}`,
+        `unknown state "${stateName}" \u2014 defined states: ${Object.keys(ir.states ?? {}).join(", ") || "(none)"}`
+      );
+      continue;
+    }
+    for (const [id, patch] of Object.entries(statePatch)) {
+      const node = nodeById.get(id);
+      if (!node) {
+        orphan(
+          `states.${stateName}.${id}`,
+          `unknown node "${id}" \u2014 known ids: ${knownIds()}; did the base regeneration rename it?`
+        );
+        continue;
+      }
+      const target = state[id] ??= {};
+      patchProps(`states.${stateName}.${id}`, node, target, patch);
+    }
+  }
+  if (overlay.behaviors?.remove || overlay.behaviors?.set) {
+    ir.behaviors ??= [];
+    for (const { target, prop } of overlay.behaviors.remove ?? []) {
+      const index = ir.behaviors.findIndex((b) => b.target === target && b.prop === prop);
+      if (index < 0) {
+        orphan(
+          `behaviors.remove.${target}.${prop}`,
+          `no behavior on "${target}.${prop}" to remove`
+        );
+        continue;
+      }
+      ir.behaviors.splice(index, 1);
+      applied(`behaviors.${target}.${prop}`, "behavior-remove");
+    }
+    for (const behavior of overlay.behaviors.set ?? []) {
+      if (!nodeById.has(behavior.target)) {
+        orphan(
+          `behaviors.set.${behavior.target}.${behavior.prop}`,
+          `unknown node "${behavior.target}" \u2014 known ids: ${knownIds()}`
+        );
+        continue;
+      }
+      const index = ir.behaviors.findIndex(
+        (b) => b.target === behavior.target && b.prop === behavior.prop
+      );
+      if (index >= 0) ir.behaviors[index] = structuredClone(behavior);
+      else ir.behaviors.push(structuredClone(behavior));
+      applied(`behaviors.${behavior.target}.${behavior.prop}`, "behavior-set");
+    }
+  }
+  if (overlay.timeline) {
+    const byLabel = /* @__PURE__ */ new Map();
+    const walkTimeline = (tl) => {
+      if ("label" in tl && tl.label !== void 0) byLabel.set(tl.label, tl);
+      if ("children" in tl) tl.children.forEach(walkTimeline);
+    };
+    if (ir.timeline) walkTimeline(ir.timeline);
+    const PATCHABLE = {
+      to: ["duration", "ease", "stagger"],
+      tween: ["duration", "ease"],
+      wait: ["duration"]
+    };
+    let timingPatched = false;
+    for (const [label, patch] of Object.entries(overlay.timeline)) {
+      const step = byLabel.get(label);
+      if (!step) {
+        orphan(
+          `timeline.${label}`,
+          `unknown timeline label "${label}" \u2014 known labels: ${[...byLabel.keys()].join(", ") || "(none)"}; did the base regeneration drop it?`
+        );
+        continue;
+      }
+      const allowed = PATCHABLE[step.kind] ?? [];
+      for (const [key2, value] of Object.entries(patch)) {
+        if (value === void 0) continue;
+        if (!allowed.includes(key2)) {
+          orphan(
+            `timeline.${label}.${key2}`,
+            `"${key2}" is not patchable on a ${step.kind} step \u2014 patchable: ${allowed.join(", ")}`
+          );
+          continue;
+        }
+        step[key2] = value;
+        applied(`timeline.${label}.${key2}`, "set");
+        if (key2 === "duration" || key2 === "stagger") timingPatched = true;
+      }
+    }
+    if (timingPatched && overlay.scene?.duration === void 0) {
+      delete ir.duration;
+      ir.duration = compileScene(ir).duration;
+    }
+  }
+  for (const node of overlay.addNodes ?? []) {
+    ir.nodes.push(structuredClone(node));
+    nodeById.set(node.id, node);
+    applied(`addNodes.${node.id}`, "add-node");
+  }
+}
+function formatComposeReport(report) {
+  const lines = [];
+  lines.push(
+    `compose: ${report.applied.length} applied, ${report.orphans.length} orphaned, ${report.warnings.length} warnings`
+  );
+  for (const a of report.applied) lines.push(`  \u2713 [${a.layer}] ${a.address} (${a.action})`);
+  for (const o of report.orphans) lines.push(`  \u2717 [${o.layer}] ${o.address}: ${o.reason}`);
+  for (const w of report.warnings) lines.push(`  ! ${w}`);
+  return lines.join("\n");
+}
+
+// ../core/src/audio.ts
+var SFX_DURATION = {
+  whoosh: 0.35,
+  pop: 0.12,
+  tick: 0.03,
+  rise: 0.5,
+  shimmer: 0.9,
+  thud: 0.25
+};
+var FILE_CUE_DURATION = 0.4;
+function resolveAudioPlan(compiled) {
+  const audio = compiled.ir.audio;
+  if (!audio || !audio.bgm && (audio.cues ?? []).length === 0) return null;
+  const warnings = [];
+  const duration = compiled.duration;
+  const cues = [];
+  for (const [index, cue] of (audio.cues ?? []).entries()) {
+    let anchor;
+    if (typeof cue.at === "number") {
+      anchor = cue.at;
+    } else {
+      const span = compiled.labelTimes.get(cue.at);
+      if (!span) {
+        warnings.push(`cue[${index}]: unknown label "${cue.at}" \u2014 cue dropped`);
+        continue;
+      }
+      anchor = span.t0;
+    }
+    const t = Math.max(0, anchor + (cue.offset ?? 0));
+    const cueDuration = cue.sfx ? SFX_DURATION[cue.sfx] : FILE_CUE_DURATION;
+    if (t >= duration) {
+      warnings.push(`cue[${index}] at ${t.toFixed(2)}s starts past the scene end (${duration.toFixed(2)}s) \u2014 dropped`);
+      continue;
+    }
+    if (t + cueDuration > duration) {
+      warnings.push(`cue[${index}] at ${t.toFixed(2)}s extends past the scene end \u2014 it will be truncated`);
+    }
+    cues.push({
+      t,
+      gain: cue.gain ?? 1,
+      duration: cueDuration,
+      source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
+    });
+  }
+  cues.sort((a, b) => a.t - b.t);
+  const duckWindows = [];
+  for (const cue of cues) {
+    const window2 = { t0: cue.t, t1: Math.min(duration, cue.t + cue.duration) };
+    const last = duckWindows[duckWindows.length - 1];
+    if (last && window2.t0 <= last.t1 + 0.1) last.t1 = Math.max(last.t1, window2.t1);
+    else duckWindows.push(window2);
+  }
+  let bgm = null;
+  if (audio.bgm) {
+    const b = audio.bgm;
+    const duck = b.duck === false ? null : {
+      depth: b.duck?.depth ?? 0.5,
+      attack: b.duck?.attack ?? 0.05,
+      release: b.duck?.release ?? 0.25
+    };
+    bgm = {
+      source: b.file ? { kind: "file", path: b.file } : { kind: "synth", name: b.synth ?? "ambient-pad" },
+      gain: b.gain ?? 0.5,
+      fadeIn: b.fadeIn ?? 0,
+      fadeOut: b.fadeOut ?? 0,
+      duck
+    };
+  }
+  return { duration, bgm, cues, duckWindows, warnings };
+}
+
+// ../core/src/interpolate.ts
+var EASE_TABLE = {
+  linear: (u) => u,
+  easeInQuad: (u) => u * u,
+  easeOutQuad: (u) => 1 - (1 - u) * (1 - u),
+  easeInOutQuad: (u) => u < 0.5 ? 2 * u * u : 1 - (-2 * u + 2) ** 2 / 2,
+  easeInCubic: (u) => u ** 3,
+  easeOutCubic: (u) => 1 - (1 - u) ** 3,
+  easeInOutCubic: (u) => u < 0.5 ? 4 * u ** 3 : 1 - (-2 * u + 2) ** 3 / 2,
+  easeInQuart: (u) => u ** 4,
+  easeOutQuart: (u) => 1 - (1 - u) ** 4,
+  easeInOutQuart: (u) => u < 0.5 ? 8 * u ** 4 : 1 - (-2 * u + 2) ** 4 / 2,
+  easeInExpo: (u) => u === 0 ? 0 : 2 ** (10 * u - 10),
+  easeOutExpo: (u) => u === 1 ? 1 : 1 - 2 ** (-10 * u),
+  easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2
+};
+var EASE_NAMES = Object.keys(EASE_TABLE);
+
+// ../render-cli/src/audio/index.ts
+import { dirname as dirname2 } from "node:path";
+
+// ../render-cli/src/audio/sfx.ts
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../render-cli/src/audio/wav.ts
+var SAMPLE_RATE = 44100;
+function encodeWavMono16(samples, sampleRate = SAMPLE_RATE) {
+  const dataBytes = samples.length * 2;
+  const buffer2 = Buffer.alloc(44 + dataBytes);
+  buffer2.write("RIFF", 0);
+  buffer2.writeUInt32LE(36 + dataBytes, 4);
+  buffer2.write("WAVE", 8);
+  buffer2.write("fmt ", 12);
+  buffer2.writeUInt32LE(16, 16);
+  buffer2.writeUInt16LE(1, 20);
+  buffer2.writeUInt16LE(1, 22);
+  buffer2.writeUInt32LE(sampleRate, 24);
+  buffer2.writeUInt32LE(sampleRate * 2, 28);
+  buffer2.writeUInt16LE(2, 32);
+  buffer2.writeUInt16LE(16, 34);
+  buffer2.write("data", 36);
+  buffer2.writeUInt32LE(dataBytes, 40);
+  for (let i = 0; i < samples.length; i++) {
+    const s = Math.max(-1, Math.min(1, samples[i]));
+    buffer2.writeInt16LE(Math.round(s * 32767), 44 + i * 2);
+  }
+  return buffer2;
+}
+
+// ../render-cli/src/audio/synth.ts
+function hash01(n, seed) {
+  let h = n * 374761393 + seed * 668265263 | 0;
+  h = h ^ h >>> 13 | 0;
+  h = Math.imul(h, 1274126177);
+  h = (h ^ h >>> 16) >>> 0;
+  return h / 4294967295;
+}
+var noise = (n, seed) => hash01(n, seed) * 2 - 1;
+var TAU = Math.PI * 2;
+var expDecay = (t, dur, k = 5) => Math.exp(-k * t / dur);
+function buffer(duration) {
+  const n = Math.round(duration * SAMPLE_RATE);
+  return { out: new Float32Array(n), n };
+}
+function whoosh(seed) {
+  const dur = 0.35;
+  const { out, n } = buffer(dur);
+  let lp = 0;
+  let lp2 = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    const u = t / dur;
+    const center = 1200 * Math.pow(300 / 1200, u);
+    const alpha = Math.min(1, TAU * center / SAMPLE_RATE);
+    lp += alpha * (noise(i, seed) - lp);
+    lp2 += alpha * 0.5 * (lp - lp2);
+    const env = u < 0.3 ? u / 0.3 : expDecay(t - 0.3 * dur, dur * 0.7, 4);
+    out[i] = (lp - lp2) * env * 2.2;
+  }
+  return out;
+}
+function pop(seed) {
+  const dur = 0.12;
+  const { out, n } = buffer(dur);
+  let phase = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    const freq = 600 * Math.pow(150 / 600, t / 0.08);
+    phase += TAU * freq / SAMPLE_RATE;
+    const transient = t < 2e-3 ? noise(i, seed) * 0.5 : 0;
+    out[i] = (Math.sin(phase) + transient) * expDecay(t, dur, 6) * 0.8;
+  }
+  return out;
+}
+function tick(seed) {
+  const dur = 0.03;
+  const { out, n } = buffer(dur);
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    const sine = t < 4e-3 ? Math.sin(TAU * 4e3 * t) : 0;
+    out[i] = (sine * 0.6 + noise(i, seed) * 0.35) * expDecay(t, dur, 8);
+  }
+  return out;
+}
+function rise(seed) {
+  const dur = 0.5;
+  const { out, n } = buffer(dur);
+  let phase = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    const u = t / dur;
+    const freq = 220 * Math.pow(880 / 220, u);
+    phase += TAU * freq / SAMPLE_RATE;
+    const env = Math.sin(Math.PI * Math.min(1, u * 1.05)) ** 1.5;
+    out[i] = (Math.sin(phase) + 0.3 * Math.sin(2 * phase)) * env * 0.45;
+  }
+  return out;
+}
+function shimmer(seed) {
+  const dur = 0.9;
+  const { out, n } = buffer(dur);
+  const partials = Array.from({ length: 5 }, (_, p) => ({
+    freq: 2e3 + hash01(p, seed + 7) * 2e3,
+    am: 0.5 + hash01(p, seed + 8) * 1.5,
+    phase: hash01(p, seed + 9) * TAU
+  }));
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    const u = t / dur;
+    const env = Math.sin(Math.PI * u) ** 1.2;
+    let s = 0;
+    for (const part of partials) {
+      s += Math.sin(TAU * part.freq * t + part.phase) * (0.6 + 0.4 * Math.sin(TAU * part.am * t));
+    }
+    out[i] = s / 5 * env * 0.5;
+  }
+  return out;
+}
+function thud(seed) {
+  const dur = 0.25;
+  const { out, n } = buffer(dur);
+  let phase = 0;
+  let lp = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    const freq = 90 * Math.pow(45 / 90, t / 0.15);
+    phase += TAU * freq / SAMPLE_RATE;
+    lp += 0.02 * (noise(i, seed) - lp);
+    const attack = t < 0.01 ? lp * 3 : 0;
+    out[i] = (Math.sin(phase) * 0.9 + attack) * expDecay(t, dur, 5);
+  }
+  return out;
+}
+var RECIPES = {
+  whoosh,
+  pop,
+  tick,
+  rise,
+  shimmer,
+  thud
+};
+function synthSfx(name, params = {}) {
+  const samples = RECIPES[name](params.seed ?? 0);
+  if (params.gainDb) {
+    const g = Math.pow(10, params.gainDb / 20);
+    for (let i = 0; i < samples.length; i++) samples[i] *= g;
+  }
+  return samples;
+}
+function synthAmbientPad(duration, seed = 0) {
+  const { out, n } = buffer(duration);
+  const voices = [110, 165, 220].flatMap((f, v) => [
+    { freq: f * (1 + (hash01(v, seed + 3) - 0.5) * 4e-3), am: 0.05 + hash01(v, seed + 4) * 0.08, phase: hash01(v, seed + 5) * TAU },
+    { freq: f * (1 - (hash01(v, seed + 6) - 0.5) * 4e-3), am: 0.05 + hash01(v, seed + 7) * 0.08, phase: hash01(v, seed + 8) * TAU }
+  ]);
+  for (let i = 0; i < n; i++) {
+    const t = i / SAMPLE_RATE;
+    let s = 0;
+    for (const voice of voices) {
+      s += Math.sin(TAU * voice.freq * t + voice.phase) * (0.75 + 0.25 * Math.sin(TAU * voice.am * t));
+    }
+    out[i] = s / voices.length * 0.7;
+  }
+  return out;
+}
+
+// ../render-cli/src/audio/sfx.ts
+var ROOT = true ? resolve(dirname(fileURLToPath(import.meta.url)), "..") : resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+var VENDORED = join(ROOT, "assets", "sfx");
+var CACHE = join(tmpdir(), "reframe-sfx-cache");
+function fnv1a(text) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16);
+}
+async function writeCached(key2, make) {
+  const path = join(CACHE, `${key2}.wav`);
+  if (existsSync(path)) return path;
+  await mkdir(CACHE, { recursive: true });
+  const temp = `${path}.${process.pid}.${fnv1a(String(performance.now()))}.tmp`;
+  await writeFile(temp, encodeWavMono16(make()));
+  await rename(temp, path);
+  return path;
+}
+async function resolveCueFile(cue, sceneDir) {
+  if (cue.source.kind === "file") {
+    const p = cue.source.path;
+    for (const candidate of [
+      isAbsolute(p) ? p : null,
+      resolve(sceneDir, p),
+      join(VENDORED, p)
+    ]) {
+      if (candidate && existsSync(candidate)) return candidate;
+    }
+    throw new Error(
+      `audio cue file "${p}" not found (tried absolute, scene-relative, assets/sfx/)`
+    );
+  }
+  const vendored = join(VENDORED, `${cue.source.name}.wav`);
+  if (existsSync(vendored)) return vendored;
+  const { name, params } = cue.source;
+  return writeCached(`${name}-${fnv1a(JSON.stringify(params))}`, () => synthSfx(name, params));
+}
+async function resolveBgmFile(source, duration, sceneDir) {
+  if (source.kind === "file") {
+    const p = source.path;
+    for (const candidate of [isAbsolute(p) ? p : null, resolve(sceneDir, p), join(VENDORED, p)]) {
+      if (candidate && existsSync(candidate)) return candidate;
+    }
+    throw new Error(`bgm file "${p}" not found`);
+  }
+  return writeCached(`ambient-pad-${duration.toFixed(2)}`, () => synthAmbientPad(duration));
+}
+
+// ../render-cli/src/audio/mux.ts
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join2 } from "node:path";
+var FORMAT = "aformat=sample_rates=44100:channel_layouts=stereo";
+function buildFilterGraph(plan, inputs) {
+  const lines = [];
+  const mixIn = ["[anchor]"];
+  lines.push(`anullsrc=r=44100:cl=stereo,atrim=duration=${plan.duration.toFixed(3)}[anchor]`);
+  let inputIndex = 1;
+  if (plan.bgm && inputs.bgmFile) {
+    const b = plan.bgm;
+    const chain = [FORMAT, `volume=${b.gain}`];
+    if (b.fadeIn > 0) chain.push(`afade=t=in:st=0:d=${b.fadeIn}`);
+    if (b.fadeOut > 0) {
+      chain.push(`afade=t=out:st=${Math.max(0, plan.duration - b.fadeOut).toFixed(3)}:d=${b.fadeOut}`);
+    }
+    if (b.duck) {
+      for (const w of plan.duckWindows) {
+        const { attack, release, depth } = b.duck;
+        const t0 = (w.t0 - attack).toFixed(3);
+        const t1 = (w.t1 + release).toFixed(3);
+        chain.push(
+          `volume='1-${depth}*max(0\\,min(1\\,min((t-${t0})/${attack}\\,(${t1}-t)/${release})))':eval=frame`
+        );
+      }
+    }
+    lines.push(`[${inputIndex}:a]${chain.join(",")}[bgm]`);
+    mixIn.push("[bgm]");
+    inputIndex++;
+  }
+  plan.cues.forEach((cue, i) => {
+    const delayMs = Math.round(cue.t * 1e3);
+    lines.push(`[${inputIndex}:a]${FORMAT},volume=${cue.gain},adelay=${delayMs}:all=1[c${i}]`);
+    mixIn.push(`[c${i}]`);
+    inputIndex++;
+  });
+  lines.push(
+    `${mixIn.join("")}amix=inputs=${mixIn.length}:duration=first:normalize=0,alimiter=limit=0.891,aresample=async=1:first_pts=0[aout]`
+  );
+  return lines.join(";\n");
+}
+async function muxAudio(videoIn, plan, inputs, outFile) {
+  const work = await mkdtemp(join2(tmpdir2(), "reframe-mux-"));
+  try {
+    const graphFile = join2(work, "graph.txt");
+    await writeFile2(graphFile, buildFilterGraph(plan, inputs));
+    const args = [
+      "-y",
+      "-i",
+      videoIn,
+      ...plan.bgm && inputs.bgmFile ? ["-i", inputs.bgmFile] : [],
+      ...inputs.cueFiles.flatMap((f) => ["-i", f]),
+      "-filter_complex_script",
+      graphFile,
+      "-map",
+      "0:v",
+      "-map",
+      "[aout]",
+      "-c:v",
+      "copy",
+      "-c:a",
+      "aac",
+      "-b:a",
+      "192k",
+      "-ar",
+      "44100",
+      "-shortest",
+      outFile
+    ];
+    await new Promise((resolvePromise, reject) => {
+      const proc = spawn("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
+      let stderr = "";
+      proc.stderr.on("data", (d) => stderr += d.toString());
+      proc.on("close", (code) => {
+        if (code === 0) resolvePromise();
+        else reject(new Error(`ffmpeg mux exited ${code}:
+${stderr.slice(-2e3)}`));
+      });
+      proc.on("error", reject);
+    });
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+// ../render-cli/src/audio/index.ts
+async function buildAudioTrack(plan, scenePath, videoIn, outFile) {
+  const sceneDir = dirname2(scenePath);
+  const cueFiles = await Promise.all(plan.cues.map((cue) => resolveCueFile(cue, sceneDir)));
+  const bgmFile = plan.bgm ? await resolveBgmFile(plan.bgm.source, plan.duration, sceneDir) : null;
+  await muxAudio(videoIn, plan, { cueFiles, bgmFile }, outFile);
+}
+
+// ../render-cli/src/encode.ts
+import { spawn as spawn2 } from "node:child_process";
+async function encodeMp4(framesDir, fps, outFile) {
+  const args = [
+    "-y",
+    "-framerate",
+    String(fps),
+    "-i",
+    `${framesDir}/%05d.png`,
+    "-c:v",
+    "libx264",
+    "-preset",
+    "slow",
+    "-crf",
+    "18",
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+    outFile
+  ];
+  await new Promise((resolve4, reject) => {
+    const proc = spawn2("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.on("data", (d) => stderr += d.toString());
+    proc.on("close", (code) => {
+      if (code === 0) resolve4();
+      else reject(new Error(`ffmpeg exited with ${code}:
+${stderr.slice(-2e3)}`));
+    });
+    proc.on("error", reject);
+  });
+}
+
+// ../render-cli/src/frameLoop.ts
+import { mkdir as mkdir2, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join4, dirname as dirname4 } from "node:path";
+import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
+import { build } from "esbuild";
+import { chromium } from "playwright";
+
+// ../render-cli/src/fonts.ts
+import { readFile } from "node:fs/promises";
+import { dirname as dirname3, join as join3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var FONTS_DIR = true ? join3(dirname3(fileURLToPath2(import.meta.url)), "..", "assets", "fonts") : join3(dirname3(fileURLToPath2(import.meta.url)), "..", "..", "..", "assets", "fonts");
+var WEIGHTS = [400, 700, 800];
+var cssCache = null;
+async function fontFaceCss() {
+  if (cssCache) return cssCache;
+  const rules = await Promise.all(
+    WEIGHTS.map(async (weight) => {
+      const data = await readFile(join3(FONTS_DIR, `inter-${weight}.woff2`));
+      return `@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: ${weight};
+  src: url(data:font/woff2;base64,${data.toString("base64")}) format("woff2");
+}`;
+    })
+  );
+  cssCache = rules.join("\n");
+  return cssCache;
+}
+
+// ../render-cli/src/vclock.ts
+var VCLOCK_SOURCE = String.raw`
+(() => {
+  let now = 0;
+  let nextId = 1;
+  let rafQueue = [];
+  const timers = [];
+
+  Date.now = () => now;
+  performance.now = () => now;
+
+  window.requestAnimationFrame = (cb) => {
+    const id = nextId++;
+    rafQueue.push({ id, cb });
+    return id;
+  };
+  window.cancelAnimationFrame = (id) => {
+    rafQueue = rafQueue.filter((r) => r.id !== id);
+  };
+
+  const addTimer = (cb, delay, args, interval) => {
+    const id = nextId++;
+    timers.push({
+      id,
+      cb: () => cb(...args),
+      due: now + Math.max(Number(delay) || 0, 0),
+      interval: interval ? Math.max(Number(delay) || 0, 1) : undefined,
+    });
+    return id;
+  };
+  const removeTimer = (id) => {
+    const i = timers.findIndex((t) => t.id === id);
+    if (i >= 0) timers.splice(i, 1);
+  };
+  window.setTimeout = (cb, delay = 0, ...args) =>
+    typeof cb === "function" ? addTimer(cb, delay, args, false) : 0;
+  window.setInterval = (cb, delay = 0, ...args) =>
+    typeof cb === "function" ? addTimer(cb, delay, args, true) : 0;
+  window.clearTimeout = removeTimer;
+  window.clearInterval = removeTimer;
+
+  window.__vclock = {
+    now: () => now,
+    advanceTo(targetMs) {
+      // Fire due timers in order, letting fired callbacks schedule new ones.
+      for (;;) {
+        timers.sort((a, b) => a.due - b.due);
+        const next = timers[0];
+        if (!next || next.due > targetMs) break;
+        now = next.due;
+        if (next.interval !== undefined) next.due += next.interval;
+        else timers.shift();
+        next.cb();
+      }
+      now = targetMs;
+      // One rAF batch per frame; callbacks registered during the batch run
+      // on the next advanceTo (matching real browser semantics).
+      const batch = rafQueue;
+      rafQueue = [];
+      for (const { cb } of batch) cb(now);
+    },
+  };
+})();
+`;
+
+// ../render-cli/src/frameLoop.ts
+async function injectFonts(page) {
+  await page.addStyleTag({ content: await fontFaceCss() });
+  await page.evaluate(async () => {
+    await Promise.all([...document.fonts].map((f) => f.load()));
+    await document.fonts.ready;
+  });
+}
+var framePath = (dir, i) => join4(dir, `${String(i).padStart(5, "0")}.png`);
+async function withPage(size, fn) {
+  const browser = await chromium.launch({
+    args: ["--force-color-profile=srgb", "--font-render-hinting=none"]
+  });
+  try {
+    const page = await browser.newPage({ viewport: size, deviceScaleFactor: 1 });
+    return await fn(page);
+  } finally {
+    await browser.close();
+  }
+}
+var bundleCache = null;
+async function browserBundle() {
+  if (bundleCache) return bundleCache;
+  if (true) {
+    const { readFile: readFile4 } = await import("node:fs/promises");
+    bundleCache = await readFile4(
+      join4(dirname4(fileURLToPath3(import.meta.url)), "browserEntry.js"),
+      "utf8"
+    );
+    return bundleCache;
+  }
+  const entry = join4(dirname4(fileURLToPath3(import.meta.url)), "browserEntry.ts");
+  const result = await build({
+    entryPoints: [entry],
+    bundle: true,
+    write: false,
+    format: "iife",
+    target: "es2022"
+  });
+  bundleCache = result.outputFiles[0].text;
+  return bundleCache;
+}
+async function captureIr(ir, opts) {
+  await mkdir2(opts.framesDir, { recursive: true });
+  const bundle = await browserBundle();
+  return withPage(ir.size, async (page) => {
+    await page.setContent(
+      `<!DOCTYPE html><html><body style="margin:0;background:#000"></body></html>`
+    );
+    await injectFonts(page);
+    await page.addScriptTag({ content: bundle });
+    const info = await page.evaluate(
+      (sceneIr) => window.__reframe.init(sceneIr),
+      ir
+    );
+    const fps = opts.fps ?? info.fps;
+    const duration = opts.duration ?? info.duration;
+    const frameCount = Math.max(1, Math.round(duration * fps));
+    for (let f = 0; f < frameCount; f++) {
+      const dataUrl = await page.evaluate((t) => window.__reframe.renderFrame(t), f / fps);
+      await writeFile3(framePath(opts.framesDir, f), Buffer.from(dataUrl.slice(22), "base64"));
+    }
+    return { framesDir: opts.framesDir, frameCount, fps };
+  });
+}
+async function captureHtml(htmlPath, opts) {
+  await mkdir2(opts.framesDir, { recursive: true });
+  const size = { width: opts.width ?? 1920, height: opts.height ?? 1080 };
+  return withPage(size, async (page) => {
+    await page.addInitScript(VCLOCK_SOURCE);
+    await page.goto(pathToFileURL(htmlPath).href);
+    await injectFonts(page);
+    const stage = page.locator("#stage");
+    const hasStage = await stage.count() > 0;
+    const frameCount = Math.max(1, Math.round(opts.duration * opts.fps));
+    for (let f = 0; f < frameCount; f++) {
+      await page.evaluate(
+        (ms) => window.__vclock.advanceTo(ms),
+        f / opts.fps * 1e3
+      );
+      const path = framePath(opts.framesDir, f);
+      if (hasStage) await stage.screenshot({ path, animations: "allow" });
+      else await page.screenshot({ path, animations: "allow" });
+    }
+    return { framesDir: opts.framesDir, frameCount, fps: opts.fps };
+  });
+}
+
+// ../render-cli/src/loadScene.ts
+import { build as build2 } from "esbuild";
+import { readFile as readFile2 } from "node:fs/promises";
+import { dirname as dirname5, resolve as resolve2 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+var HERE = dirname5(fileURLToPath4(import.meta.url));
+var CORE_ENTRY = true ? resolve2(HERE, "index.js") : resolve2(HERE, "..", "..", "core", "src", "index.ts");
+async function loadScene(path) {
+  if (path.endsWith(".json")) {
+    const ir = JSON.parse(await readFile2(path, "utf8"));
+    validateScene(ir);
+    return ir;
+  }
+  let code;
+  try {
+    const out = await build2({
+      entryPoints: [path],
+      bundle: true,
+      format: "esm",
+      platform: "neutral",
+      write: false,
+      logLevel: "silent",
+      sourcemap: "inline",
+      // both specifiers accepted: the guide's canonical "@reframe/core" and
+      // the published package name
+      alias: { "@reframe/core": CORE_ENTRY, "reframe-video": CORE_ENTRY }
+    });
+    code = out.outputFiles[0].text;
+  } catch (err) {
+    throw new Error(
+      `failed to bundle ${path}:
+${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const mod = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
+  if (!mod.default) throw new Error(`${path} must default-export a scene`);
+  return mod.default;
+}
+
+// ../render-cli/src/cli.ts
+function parseArgs(argv) {
+  const [mode, input, ...rest] = argv;
+  if (mode !== "ir" && mode !== "html" || !input) {
+    console.error(
+      "usage: reframe-render ir <scene.ts|json> [-o out.mp4] [--fps N] [--keep-frames] [--frames-dir d]\n       reframe-render html <page.html> --duration S [-o out.mp4] [--fps N] [--keep-frames] [--frames-dir d]"
+    );
+    process.exit(2);
+  }
+  const args = {
+    mode,
+    input: resolve3(input),
+    out: `${basename(input).replace(/\.[^.]+$/, "")}.mp4`,
+    keepFrames: false,
+    overlays: [],
+    noAudio: false
+  };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "-o") args.out = rest[++i];
+    else if (a === "--fps") args.fps = Number(rest[++i]);
+    else if (a === "--duration") args.duration = Number(rest[++i]);
+    else if (a === "--keep-frames") args.keepFrames = true;
+    else if (a === "--frames-dir") args.framesDir = resolve3(rest[++i]);
+    else if (a === "--overlay") args.overlays.push(resolve3(rest[++i]));
+    else if (a === "--no-audio") args.noAudio = true;
+    else {
+      console.error(`unknown flag ${a}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const framesDir = args.framesDir ?? await mkdtemp2(join5(tmpdir3(), "reframe-frames-"));
+  let result;
+  let audioJob = null;
+  if (args.mode === "ir") {
+    let ir = await loadScene(args.input);
+    if (args.overlays.length > 0) {
+      const docs = await Promise.all(
+        args.overlays.map(async (p) => JSON.parse(await readFile3(p, "utf8")))
+      );
+      const composed = composeScene(ir, ...docs);
+      console.error(formatComposeReport(composed.report));
+      ir = composed.ir;
+    }
+    if (!args.noAudio) {
+      const plan = resolveAudioPlan(compileScene(ir));
+      if (plan) {
+        for (const w of plan.warnings) console.error(`audio: ${w}`);
+        audioJob = { plan, videoOut: `${args.out}.video.mp4` };
+      }
+    }
+    result = await captureIr(ir, {
+      framesDir,
+      ...args.fps !== void 0 && { fps: args.fps },
+      ...args.duration !== void 0 && { duration: args.duration }
+    });
+  } else {
+    if (args.duration === void 0 || Number.isNaN(args.duration)) {
+      throw new Error("html mode requires --duration <seconds>");
+    }
+    result = await captureHtml(args.input, {
+      framesDir,
+      fps: args.fps ?? 30,
+      duration: args.duration
+    });
+  }
+  await encodeMp4(result.framesDir, result.fps, audioJob ? audioJob.videoOut : args.out);
+  if (audioJob) {
+    await buildAudioTrack(audioJob.plan, args.input, audioJob.videoOut, args.out);
+    await rm2(audioJob.videoOut, { force: true });
+  }
+  if (!args.keepFrames && args.framesDir === void 0) {
+    await rm2(framesDir, { recursive: true, force: true });
+  }
+  console.log(
+    `${args.out} (${result.frameCount} frames @ ${result.fps}fps${audioJob ? `, ${audioJob.plan.cues.length} audio cues` : ""})`
+  );
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});