volito 0.1.0 → 0.3.0

package/dist/chunks/{chunk-CFDFWZAC.js → chunk-CUQY6YI3.js}

@@ -1,3 +1,9 @@
+import {
+  FfmpegMissing,
+  fontsDir,
+  probeFfmpeg
+} from "./chunk-ZFG3X3DU.js";
+
 // src/engine/graphics-runtime.ts
 var MG_RUNTIME = String.raw`
 var MG = (function () {
@@ -3660,6 +3666,36 @@ function motion($, t) {
     return [x, y];
   }
 
+  /** Moves that read as a spring (a pop in the sound design) rather than travel across the frame. */
+  var MM_SPRINGY = { pop: 1, zoom: 1, push: 1, grow: 1, spin: 1, swing: 1, elastic: 1, bounce: 1, squash: 1, stretch: 1, flip: 1, turn: 1, unfold: 1, "grow-x": 1, "grow-y": 1 };
+  /**
+   * Tells the sound trace what a part does, through the runtime's timing helpers (they leave the marks a
+   * sound design reads): a slam shakes, a spring pops, a move across the frame enters from a distance, a
+   * fade fades, a typewriter types, a glitch flashes, and every emphasis hit bumps. One cheap call a frame;
+   * nothing is drawn.
+   */
+  function note(s, tm, c, text) {
+    if (tm.mv.always || typeof $.enter !== "function") return;
+    var mv = s["in"];
+    if (mv === "slam") $.shake(t, tm.at + tm.dur * 0.55, 24);
+    else if (mv === "typewriter") $.typed(t, tm.at, text || "", speed / (s.stagger > 0 ? Number(s.stagger) : 0.055));
+    else if (mv === "scramble") $.typed(t, tm.at, text || "", (text ? Array.from(text).length : 8) / Math.max(0.1, tm.dur));
+    else if (mv === "glitch" || mv === "flicker") $.flash(t, tm.at, { a: 0 });
+    else if (mv === "fade" || mv === "blur" || mv === "appear" || mv === "float") $.fadeIn(t, tm.at);
+    else if (MM_SPRINGY[mv]) $.pop(t, tm.at);
+    else {
+      var p0 = tm.mv.pose(0, 0, c) || {};
+      var dx = p0.x || 0, dy = p0.y || 0;
+      if (!dx && !dy && tm.mv.box && c.box) dx = c.box.w * 0.5;
+      if (dx || dy) $.enter(t, tm.at, { dx: dx, dy: dy }); else $.pop(t, tm.at);
+    }
+    hits(s).forEach(function (h) {
+      var at = hitTime(h.at, tm.at);
+      if (!isFinite(at)) return;
+      if (h.fx === "shake") $.shake(t, at, 16); else if (h.fx === "flash") $.flash(t, at, { a: 0 }); else $.bump(t, at);
+    });
+  }
+
   var api = {};
   api.mood = mood;
   api.seed = seed;
@@ -3674,6 +3710,7 @@ function motion($, t) {
     var tm = timing(s);
     var pv = pivot(o.box, s.origin, o, tm.mv.origin);
     var c = context(s, tm, o.box, pv[0], pv[1], salt(name) % 97);
+    note(s, tm, c);
     return render(kids, poseAt(s, tm, c, t), c);
   };
 
@@ -3740,6 +3777,7 @@ function motion($, t) {
     if (!lay.units.length || lay.mode === "none") {
       var pv = pivot(lay.box, s.origin, o, tm.mv.origin);
       var c = context(s, tm, lay.box, pv[0], pv[1], salt(name) % 97);
+      note(s, tm, c, lay.text);
       return render($.text(lay.text, font), poseAt(s, tm, c, t), c);
     }
     var n = lay.units.length;
@@ -3764,6 +3802,9 @@ function motion($, t) {
         shown = pool.charAt(Math.floor(mmHash(i * 7.7 + Math.floor(t * 18) * 1.9 + vseed) * pool.length));
       }
       if (t >= ut.at) lastShown = u;
+      // The sound trace: typing and scrambles once for the whole text, else the first unit with its move and every other one a tick.
+      if (behave === "type" || behave === "scramble") { if (i === 0) note(s, tm, c2, lay.text); }
+      else if (rk === 0) note(s, ut, c2, u.text); else if (typeof $.bump === "function") $.bump(t, ut.at);
       out += render(draw(shown, u.x, u), poseAt(s, ut, c2, t), c2);
     });
     var typed = tm.at + n * (s.stagger > 0 ? Number(s.stagger) : 0.055) / speed;
@@ -4194,8 +4235,8 @@ function setGlyphSource(fn) {
 }
 function glyphsFor(spec2) {
   const { key, file } = glyphFaceFile(spec2);
-  const hit = cache.get(key);
-  if (hit) return hit;
+  const hit2 = cache.get(key);
+  if (hit2) return hit2;
   const t = source(key, file);
   if (t) cache.set(key, t);
   return t;
@@ -4206,6 +4247,72 @@ function glyphLibrary(tables) {
   return `var MM_GLYPHS = ${JSON.stringify(map)};`;
 }
 
+// src/player/states.ts
+var STATE_PLAYS = ["once", "loop", "hold"];
+var NAME = /^[A-Za-z][\w-]{0,40}$/;
+function parseStates(value, where = "states") {
+  if (value == null || value === "") return void 0;
+  let v = value;
+  if (typeof v === "string") {
+    try {
+      v = JSON.parse(v);
+    } catch {
+      throw new Error(`${where} must be a JSON object, like {"idle":{"from":0,"to":1,"play":"loop"}}`);
+    }
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error(`${where} must be a JSON object of states`);
+  const out = {};
+  for (const [name, raw] of Object.entries(v)) {
+    if (!NAME.test(name)) throw new Error(`${where}: "${name}" is not a state name (letters, digits, - and _)`);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where}.${name} must be an object like {"from":"hover","to":"press","play":"once"}`);
+    const d = raw;
+    const play = d.play ?? "once";
+    if (!STATE_PLAYS.includes(play)) throw new Error(`${where}.${name}.play is one of ${STATE_PLAYS.join(", ")}`);
+    for (const k of ["from", "to"]) if (d[k] !== void 0 && typeof d[k] !== "number" && typeof d[k] !== "string") throw new Error(`${where}.${name}.${k} is seconds or a beat name`);
+    out[name] = { ...d.from !== void 0 ? { from: d.from } : {}, ...d.to !== void 0 ? { to: d.to } : {}, play, ...typeof d.next === "string" ? { next: d.next } : {} };
+  }
+  for (const [name, d] of Object.entries(out)) if (d.next && !(d.next in out)) throw new Error(`${where}.${name}.next is "${d.next}", which is not a state (${Object.keys(out).join(", ")})`);
+  return Object.keys(out).length ? out : void 0;
+}
+function parseTriggers(value, states) {
+  if (value == null || value === "") return [];
+  if (typeof value !== "string") throw new Error('on takes "event: state" pairs, like "pointerenter: hover; click: press"');
+  const out = [];
+  for (const raw of value.split(/[;\n]+/)) {
+    const s = raw.trim();
+    if (!s) continue;
+    const m = /^([a-z][a-z-]*)\s*(?:\(([^)]*)\))?\s*:\s*([A-Za-z][\w-]*)$/i.exec(s);
+    if (!m) throw new Error(`on: "${s}" is not "event: state" (or "event(fromState): state")`);
+    const from = (m[2] ?? "").split(/[\s|,]+/).filter(Boolean);
+    const t = { event: m[1].toLowerCase(), from, to: m[3] };
+    if (states) {
+      for (const n of [t.to, ...t.from]) if (!(n in states)) throw new Error(`on: "${n}" is not a state (${Object.keys(states).join(", ")})`);
+    }
+    out.push(t);
+  }
+  return out;
+}
+function resolveTime(v, fallback, duration, beats) {
+  let t;
+  if (v === void 0) t = fallback;
+  else if (typeof v === "number") t = v;
+  else if (v === "start") t = 0;
+  else if (v === "end") t = duration;
+  else if (v in beats) t = beats[v];
+  else if (Number.isFinite(Number(v))) t = Number(v);
+  else throw new Error(`"${v}" is not a beat (${Object.keys(beats).join(", ") || "none"}), seconds, start or end`);
+  if (t < 0) t = duration + t;
+  return Math.max(0, Math.min(duration, t));
+}
+function resolveState(name, states, duration, beats = {}) {
+  const d = states[name];
+  if (!d) throw new Error(`no state "${name}" (states: ${Object.keys(states).join(", ")})`);
+  const start = resolveTime(d.from, 0, duration, beats);
+  const end = resolveTime(d.to, duration, duration, beats);
+  if (end < start) throw new Error(`state "${name}" ends (${end.toFixed(2)} s) before it starts (${start.toFixed(2)} s)`);
+  return { name, start, end, play: d.play ?? "once", ...d.next ? { next: d.next } : {} };
+}
+
 // src/three.ts
 var MOTION_3D = String.raw`
 // ———————— Volito 3D ————————
@@ -4557,6 +4664,19 @@ function manifestProblems(m) {
     if (p?.type === "choice" && !p.options?.length) out.push(`prop "${name}" is a choice with no options`);
     if (p?.when && !(p.when.prop in (m.props ?? {}))) out.push(`prop "${name}" depends on an unknown prop "${p.when.prop}"`);
   }
+  if (m.states !== void 0 || m.on !== void 0) {
+    try {
+      const states = parseStates(m.states, "states");
+      if (!states) out.push("on needs states");
+      else {
+        parseTriggers(m.on, states);
+        const dur = m.duration?.default ?? 0;
+        for (const name of Object.keys(states)) resolveState(name, states, dur, m.beats ?? {});
+      }
+    } catch (e) {
+      out.push(e.message);
+    }
+  }
   return out;
 }
 function makeItem(pack, manifest, frameCode, shared = "") {
@@ -4867,175 +4987,19 @@ ${parts.join("\n")}` : ""
   ].filter(Boolean).join("\n");
 }
 
-// src/node/paths.ts
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-var PACKAGE_NAME = "volito";
-var root = null;
-function packageRoot() {
-  if (root) return root;
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 6; i++) {
-    const pj = join(dir, "package.json");
-    if (existsSync(pj)) {
-      try {
-        if (JSON.parse(readFileSync(pj, "utf8")).name === PACKAGE_NAME) return root = dir;
-      } catch {
-      }
-    }
-    dir = dirname(dir);
-  }
-  throw new Error(`${PACKAGE_NAME}: cannot find its package folder from ${fileURLToPath(import.meta.url)}`);
-}
-var fontsDir = () => join(packageRoot(), "fonts");
-var packsDir = () => join(packageRoot(), "packs");
-var libsDir = () => join(packageRoot(), "libs");
-function packageVersion() {
-  return JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8")).version;
-}
-
-// src/node/packs.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync, statSync } from "node:fs";
-import { basename, join as join3, resolve } from "node:path";
-
-// src/node/setup.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { join as join2 } from "node:path";
-setGlyphSource((key, file) => {
-  const path = join2(fontsDir(), file);
-  return existsSync2(path) ? glyphTable(new TrueTypeFace(new Uint8Array(readFileSync2(path))), key) : void 0;
-});
-for (const name of LIBRARY_NAMES) {
-  const file = join2(libsDir(), `${name}.js`);
-  if (existsSync2(file)) registerLibrary(name, () => readFileSync2(file, "utf8"));
-}
-
-// src/node/packs.ts
-var readJson = (file) => {
-  try {
-    return JSON.parse(readFileSync3(file, "utf8"));
-  } catch (err) {
-    throw new MotionError(`${file}: ${err.message}`);
-  }
-};
-function loadPack(dir) {
-  const manifest = readJson(join3(dir, "pack.json"));
-  if (manifest.format !== MOTION_FORMAT) throw new MotionError(`${dir}: pack format ${manifest.format} \u2014 this version reads format ${MOTION_FORMAT}`);
-  const shared = manifest.shared ? readFileSync3(join3(dir, manifest.shared), "utf8") : "";
-  const entries = manifest.items.map((id) => {
-    const itemDir = join3(dir, id);
-    const m = readJson(join3(itemDir, "item.json"));
-    if (m.id !== id) throw new MotionError(`${itemDir}: item.json id "${m.id}" does not match its folder`);
-    return makeItem(manifest.id, m, readFileSync3(join3(itemDir, "frame.js"), "utf8"), shared);
-  });
-  return { ...manifest, entries };
-}
-var builtin = null;
-function builtinPacks() {
-  if (builtin) return builtin;
-  const dir = packsDir();
-  const order = ["essentials", "broadcast", "social", "data", "3d", "transitions", "annotate", "type", "backdrops", "promo"];
-  const rank = (d) => order.includes(d) ? order.indexOf(d) : order.length;
-  builtin = existsSync3(dir) ? readdirSync(dir).filter((d) => existsSync3(join3(dir, d, "pack.json"))).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).map((d) => loadPack(join3(dir, d))) : [];
-  return builtin;
-}
-function packsIn(dirs) {
-  const out = [];
-  for (const raw of dirs) {
-    const dir = resolve(raw);
-    if (existsSync3(join3(dir, "pack.json"))) out.push(loadPack(dir));
-    else if (existsSync3(dir) && statSync(dir).isDirectory()) {
-      for (const d of readdirSync(dir).sort()) if (existsSync3(join3(dir, d, "pack.json"))) out.push(loadPack(join3(dir, d)));
-    }
-  }
-  return out;
-}
-function library(extraDirs = []) {
-  const env = (process.env.VOLITO_PACKS ?? process.env.MONARC_MOTION_PACKS ?? "").split(":").filter(Boolean);
-  const packs = [...builtinPacks(), ...packsIn([...env, ...extraDirs])];
-  const seen = /* @__PURE__ */ new Set();
-  for (const p of packs) {
-    if (seen.has(p.id)) throw new MotionError(`two packs are named "${p.id}"`);
-    seen.add(p.id);
-  }
-  return { packs, items: packs.flatMap((p) => p.entries) };
-}
-function findItem(name, lib = library()) {
-  const n = name.trim();
-  const byRef = lib.items.find((i) => i.ref === n);
-  if (byRef) return byRef;
-  const path = resolve(n);
-  if (existsSync3(path)) {
-    if (statSync(path).isDirectory() && existsSync3(join3(path, "item.json"))) {
-      const m = readJson(join3(path, "item.json"));
-      const shared = existsSync3(join3(path, "shared.js")) ? readFileSync3(join3(path, "shared.js"), "utf8") : "";
-      return makeItem("local", m, readFileSync3(join3(path, "frame.js"), "utf8"), shared);
-    }
-    if (/\.(m?js|txt)$/.test(path)) return customItem(readFileSync3(path, "utf8"), { id: basename(path).replace(/\.[^.]+$/, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") });
-  }
-  const byId = lib.items.filter((i) => i.id === n);
-  if (byId.length === 1) return byId[0];
-  if (byId.length > 1) throw new MotionError(`"${n}" is in more than one pack: ${byId.map((i) => i.ref).join(", ")}`);
-  const q2 = n.toLowerCase();
-  const score = (i) => i.id.startsWith(q2) ? 0 : i.id.includes(q2) || q2.includes(i.id) ? 1 : i.name.toLowerCase().includes(q2) ? 2 : (i.tags ?? []).some((t) => t.includes(q2)) ? 3 : 9;
-  const near = lib.items.map((i) => ({ ref: i.ref, s: score(i) })).filter((r) => r.s < 9).sort((a, b) => a.s - b.s).map((r) => r.ref);
-  throw new MotionError(`no item "${n}"${near.length ? ` \u2014 did you mean ${near.slice(0, 4).join(", ")}?` : ""} (list them with: volito list)`);
-}
-function searchItems(q2 = {}, lib = library()) {
-  const words = (q2.search ?? "").toLowerCase().split(/\s+/).filter(Boolean);
-  return lib.items.filter((i) => {
-    if (q2.category && i.category !== q2.category) return false;
-    if (q2.pack && i.pack !== q2.pack) return false;
-    if (q2.placement && i.placement !== q2.placement) return false;
-    if (!words.length) return true;
-    const hay = [i.id, i.name, i.description, i.category, ...i.tags ?? []].join(" ").toLowerCase();
-    return words.every((w) => hay.includes(w));
-  });
-}
-
-// src/node/ffmpeg.ts
-import { execFileSync } from "node:child_process";
-var probed;
-function ffmpegPath() {
-  return process.env.VOLITO_FFMPEG || process.env.MONARC_MOTION_FFMPEG || "ffmpeg";
-}
-function probeFfmpeg() {
-  if (probed !== void 0) return probed;
-  const path = ffmpegPath();
-  try {
-    const out = execFileSync(path, ["-hide_banner", "-encoders"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15e3 });
-    const encoders = /* @__PURE__ */ new Set();
-    for (const line of out.split("\n")) {
-      const m = /^\s*[VAS][A-Z.]{5}\s+(\S+)/.exec(line);
-      if (m) encoders.add(m[1]);
-    }
-    probed = { path, encoders };
-  } catch {
-    probed = null;
-  }
-  return probed;
-}
-var FfmpegMissing = class extends Error {
-  constructor(what) {
-    super(`${what} needs ffmpeg \u2014 install it (macOS: brew install ffmpeg \xB7 Debian/Ubuntu: apt install ffmpeg \xB7 Windows: winget install ffmpeg) or set VOLITO_FFMPEG to its path. PNG sequences and stills need no ffmpeg.`);
-    this.name = "FfmpegMissing";
-  }
-};
-
 // src/node/sandbox.ts
 import vm from "node:vm";
 
 // src/node/fonts.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
-import { join as join4 } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import * as fontkit from "fontkit";
 var faces = null;
 function allFaces() {
   if (faces) return faces;
-  const index = join4(fontsDir(), "faces.json");
-  if (!existsSync4(index)) throw new Error(`Volito: no fonts at ${fontsDir()} \u2014 run "pnpm run fonts" (or reinstall the package)`);
-  faces = JSON.parse(readFileSync4(index, "utf8")).faces;
+  const index = join(fontsDir(), "faces.json");
+  if (!existsSync(index)) throw new Error(`Volito: no fonts at ${fontsDir()} \u2014 run "pnpm run fonts" (or reinstall the package)`);
+  faces = JSON.parse(readFileSync(index, "utf8")).faces;
   return faces;
 }
 var familiesOf = () => [...new Set(allFaces().map((f) => f.family))];
@@ -5068,8 +5032,8 @@ function subsetsOf(family) {
 var resolved = /* @__PURE__ */ new Map();
 function faceFor(family, cp) {
   const key = `${family}|${cp}`;
-  const hit = resolved.get(key);
-  if (hit !== void 0) return hit;
+  const hit2 = resolved.get(key);
+  if (hit2 !== void 0) return hit2;
   let face = null;
   const own = subsetsOf(family);
   const latin = own.find((s) => s.subset === "latin");
@@ -5100,18 +5064,18 @@ function fontFilesForDocument(doc) {
     }
   }
   const dir = fontsDir();
-  return allFaces().filter((f) => names.has(f.face)).map((f) => join4(dir, f.file));
+  return allFaces().filter((f) => names.has(f.face)).map((f) => join(dir, f.file));
 }
 function fontFilesFor(families) {
   const want = /* @__PURE__ */ new Set(["Inter", ...families]);
   const dir = fontsDir();
-  return allFaces().filter((f) => want.has(f.family) && f.subset === "latin").map((f) => join4(dir, f.file));
+  return allFaces().filter((f) => want.has(f.family) && f.subset === "latin").map((f) => join(dir, f.file));
 }
 var fontCache = /* @__PURE__ */ new Map();
 var loadFont = (file) => {
   let f = fontCache.get(file);
   if (!f) {
-    f = fontkit.create(readFileSync4(join4(fontsDir(), file)));
+    f = fontkit.create(readFileSync(join(fontsDir(), file)));
     fontCache.set(file, f);
   }
   return f;
@@ -5131,8 +5095,8 @@ function fontForChar(family, weight, italic, cp) {
 var measured = /* @__PURE__ */ new Map();
 function measureText(font, text) {
   const key = `${font}|${text}`;
-  const hit = measured.get(key);
-  if (hit !== void 0) return hit;
+  const hit2 = measured.get(key);
+  if (hit2 !== void 0) return hit2;
   const m = /^(italic\s+)?(\d+)\s+([\d.]+)px\s+'([^']+)'/.exec(font);
   if (!m) return Number.NaN;
   const family = allFaces().some((f) => f.family === m[4]) ? m[4] : "Inter";
@@ -5169,7 +5133,7 @@ function fontFaceCss(doc) {
     for (const f of allFaces()) if (f.subset !== "latin" && rangeCovers(f.range, cp)) subsets.add(f.subset);
   }
   const dir = fontsDir();
-  return allFaces().filter((f) => fams.has(f.family) && subsets.has(f.subset)).map((f) => `@font-face{font-family:'${f.family}';font-weight:${f.weight};font-style:${f.italic ? "italic" : "normal"};${f.range ? `unicode-range:${f.range};` : ""}src:url(data:font/ttf;base64,${readFileSync4(join4(dir, f.file)).toString("base64")}) format('truetype');}`).join("");
+  return allFaces().filter((f) => fams.has(f.family) && subsets.has(f.subset)).map((f) => `@font-face{font-family:'${f.family}';font-weight:${f.weight};font-style:${f.italic ? "italic" : "normal"};${f.range ? `unicode-range:${f.range};` : ""}src:url(data:font/ttf;base64,${readFileSync(join(dir, f.file)).toString("base64")}) format('truetype');}`).join("");
 }
 
 // src/node/sandbox.ts
@@ -5198,6 +5162,11 @@ self.postMessage = function (m) { self.__out = m; };
   globalThis.OffscreenCanvas = OffscreenCanvas;
 })();
 `;
+var RETURN_LINE = "return { frame: typeof frame === 'function' ? frame : null, setup: typeof setup === 'function' ? setup : null };";
+var RETURN_WITH_SOUND = "return { frame: typeof frame === 'function' ? frame : null, setup: typeof setup === 'function' ? setup : null, sound: typeof sound === 'function' ? sound : null };";
+function soundHookAvailable() {
+  return programWorkerSource2("function frame() { return ''; }").source.includes(RETURN_LINE);
+}
 var ProgramRunner = class _ProgramRunner {
   ctx;
   codeLine;
@@ -5211,7 +5180,9 @@ var ProgramRunner = class _ProgramRunner {
    * start. `lineOffset` is how many lines of the code come before the author's own (the kit, a pack's helpers).
    */
   static async create(program, env, timeoutMs = 5e3, lineOffset = 0) {
-    const { source: source2, codeLine } = programWorkerSource2(program.code);
+    const built = programWorkerSource2(program.code);
+    const codeLine = built.codeLine;
+    const source2 = built.source.includes(RETURN_LINE) ? built.source.replace(RETURN_LINE, RETURN_WITH_SOUND) : built.source;
     const measure = (font, text) => {
       try {
         const w = measureText(String(font), String(text));
@@ -5278,6 +5249,27 @@ var ProgramRunner = class _ProgramRunner {
     if (out.error) throw new ProgramError(out.error, this.mapLine(out.line));
     return { svg: out.svg ?? "", defs: out.defs ?? "", warnings: out.warnings ?? [], ms: performance.now() - started };
   }
+  /**
+   * The program's own sound design: what `function sound($)` returns, read once with `$` at t = 0 ($.dur,
+   * $.beat, $.at and $.data are there). `spec` is null when the program defines none; `error` when it threw.
+   */
+  sound(timeoutMs = 5e3) {
+    if (this.dead) throw this.dead;
+    let raw;
+    try {
+      raw = vm.runInContext(
+        "(function () { if (!__program.sound) return null; var $ = MG.make(__env, 0); $.state = __state; try { return JSON.stringify({ spec: __program.sound($) }); } catch (err) { return JSON.stringify({ error: String(err && err.message || err), line: __line(err) }); } })()",
+        this.ctx,
+        { timeout: timeoutMs }
+      );
+    } catch (err) {
+      return { spec: null, error: `sound: ${this.message(err)}` };
+    }
+    if (!raw) return { spec: null };
+    const out = JSON.parse(raw);
+    if (out.error) return { spec: null, error: new ProgramError(`sound: ${out.error}`, this.mapLine(out.line)).message };
+    return { spec: out.spec ?? null };
+  }
   /** Every frame run once with the runtime's trace on: when each element pops, slides, stamps or types in. */
   trace(fps, timeoutMs = 2e4) {
     const out = this.sendSync({ type: "trace", id: 1, fps }, timeoutMs);
@@ -5285,11 +5277,742 @@ var ProgramRunner = class _ProgramRunner {
   }
 };
 
+// src/sound.ts
+var SOUND_KINDS = ["whoosh", "hit", "stamp", "pop", "tick", "click", "riser", "fall", "sub", "shimmer", "ding", "swell", "zap", "type", "scratch", "tone", "chord"];
+var SOUND_NOTES = {
+  whoosh: "air sweeping past \u2014 a move across the frame (dur 0.45)",
+  hit: "an impact: a sub thump with a click \u2014 something lands",
+  stamp: "a heavy slam \u2014 bigger than hit",
+  pop: "a small bubble pop \u2014 something springs up",
+  tick: "a tiny click \u2014 one letter, one word, one step",
+  click: "a UI click \u2014 a button pressed",
+  riser: "noise and a tone climbing \u2014 tension into a moment (dur 1)",
+  fall: "the reverse \u2014 a downlifter after a moment (dur 0.8)",
+  sub: "a low drop under a big reveal",
+  shimmer: "high sparkle \u2014 a light sweep, particles (dur 1.2)",
+  ding: "a bell \u2014 a notification, a check, a logo lockup",
+  swell: "soft air rising \u2014 a fade, a gentle entrance (dur 0.8)",
+  zap: "static and a chirp \u2014 a glitch (dur 0.28)",
+  type: "typing: keys ticking for dur seconds (dur 0.8)",
+  scratch: "pencil or marker on paper for dur seconds (dur 0.8)",
+  tone: 'a note (note: "A4", or pitch in semitones from A4) for dur seconds',
+  chord: "a chord in the bed's key for dur seconds"
+};
+var SR = 48e3;
+var TAU = Math.PI * 2;
+var clamp = (v, a, b) => v < a ? a : v > b ? b : v;
+var semis = (n) => Math.pow(2, n / 12);
+function rng(seed) {
+  let a = (Math.floor(seed * 1000003) ^ 2654435769) >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = a;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+var Svf = class {
+  ic1 = 0;
+  ic2 = 0;
+  a1 = 0;
+  a2 = 0;
+  a3 = 0;
+  k = 1;
+  lp = 0;
+  bp = 0;
+  hp = 0;
+  set(cutoff, q2) {
+    const g = Math.tan(Math.PI * clamp(cutoff, 10, SR * 0.45) / SR);
+    this.k = 1 / Math.max(0.1, q2);
+    this.a1 = 1 / (1 + g * (g + this.k));
+    this.a2 = g * this.a1;
+    this.a3 = g * this.a2;
+  }
+  run(x) {
+    const v3 = x - this.ic2;
+    const v1 = this.a1 * this.ic1 + this.a2 * v3;
+    const v2 = this.ic2 + this.a2 * this.ic1 + this.a3 * v3;
+    this.ic1 = 2 * v1 - this.ic1;
+    this.ic2 = 2 * v2 - this.ic2;
+    this.lp = v2;
+    this.bp = v1;
+    this.hp = x - this.k * v1 - v2;
+  }
+};
+var NOTE_INDEX = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+function noteHz(note) {
+  const m = /^\s*([A-Ga-g])\s*([#b♯♭]?)\s*(-?\d)?\s*$/.exec(note);
+  if (!m) return null;
+  let n = NOTE_INDEX[m[1].toUpperCase()];
+  if (m[2] === "#" || m[2] === "\u266F") n += 1;
+  if (m[2] === "b" || m[2] === "\u266D") n -= 1;
+  const oct = m[3] === void 0 ? 4 : Number(m[3]);
+  return 440 * semis(n + (oct - 4) * 12 - 9);
+}
+function parseKey(key) {
+  const m = /^\s*([A-Ga-g])\s*([#b♯♭]?)\s*(m\b|min|minor|maj|major)?\s*$/i.exec(key ?? "");
+  if (!m) return { root: 0, mode: "minor" };
+  let n = NOTE_INDEX[m[1].toUpperCase()] - 9;
+  if (m[2] === "#" || m[2] === "\u266F") n += 1;
+  if (m[2] === "b" || m[2] === "\u266D") n -= 1;
+  const q2 = (m[3] ?? "").toLowerCase();
+  return { root: (n % 12 + 12) % 12, mode: q2.startsWith("maj") ? "major" : q2 ? "minor" : m[1] === m[1].toUpperCase() && !q2 ? "major" : "minor" };
+}
+function chordTones(root, mode, degree, centre) {
+  const scale = mode === "major" ? [0, 2, 4, 5, 7, 9, 11] : [0, 2, 3, 5, 7, 8, 10];
+  const d = degree - 1;
+  const notes = [scale[d], scale[(d + 2) % 7] + (d + 2 >= 7 ? 12 : 0), scale[(d + 4) % 7] + (d + 4 >= 7 ? 12 : 0)];
+  return notes.map((n) => {
+    let s = root + n + centre;
+    while (s > centre + 7) s -= 12;
+    while (s < centre - 7) s += 12;
+    return s;
+  });
+}
+var BASE_LEVEL = {
+  whoosh: 0.5,
+  hit: 0.95,
+  stamp: 1.05,
+  pop: 0.5,
+  tick: 0.34,
+  click: 0.3,
+  riser: 0.5,
+  fall: 0.45,
+  sub: 0.95,
+  shimmer: 0.32,
+  ding: 0.5,
+  swell: 0.32,
+  zap: 0.5,
+  type: 0.4,
+  scratch: 0.32,
+  tone: 0.42,
+  chord: 0.45
+};
+var DEFAULT_DUR = { whoosh: 0.45, riser: 1, fall: 0.8, shimmer: 1.2, swell: 0.8, zap: 0.28, type: 0.8, scratch: 0.8, tone: 0.6, chord: 1.2 };
+var alloc = (sec) => new Float32Array(Math.max(1, Math.round(sec * SR)));
+var envAD = (t, a, tau) => t < a ? t / a : Math.exp(-(t - a) / tau);
+function whoosh(dur, pitch, r) {
+  const buf = alloc(dur);
+  const f = new Svf();
+  const n = buf.length;
+  const base = 260 * semis(pitch) * (0.9 + 0.2 * r());
+  for (let i = 0; i < n; i++) {
+    const p = i / n;
+    const bell = Math.sin(Math.PI * p);
+    f.set(base * Math.pow(2, 3.4 * Math.pow(bell, 0.85)), 1.4);
+    f.run(r() * 2 - 1);
+    buf[i] = (f.bp * 1.7 + f.lp * 0.25) * Math.pow(bell, 1.6);
+  }
+  return { buf, send: 0.22, duck: 0 };
+}
+function hit(pitch, r, heavy) {
+  const dur = heavy ? 0.75 : 0.5;
+  const buf = alloc(dur);
+  const n = buf.length;
+  const body = new Svf();
+  body.set(heavy ? 900 : 1800, 0.9);
+  const click2 = new Svf();
+  click2.set(3200, 0.8);
+  const f0 = (heavy ? 120 : 170) * semis(pitch);
+  const f1 = (heavy ? 38 : 48) * semis(pitch);
+  let ph = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    const freq = f1 + (f0 - f1) * Math.exp(-t / (heavy ? 0.09 : 0.06));
+    ph += TAU * freq / SR;
+    const sub2 = Math.sin(ph) * envAD(t, 2e-3, heavy ? 0.22 : 0.14);
+    const w = r() * 2 - 1;
+    body.run(w);
+    click2.run(w);
+    const slap = body.lp * envAD(t, 1e-3, heavy ? 0.05 : 0.03) * (heavy ? 1 : 0.8);
+    const tk = click2.hp * (t < 4e-3 ? 1 - t / 4e-3 : 0) * 0.5;
+    const rattle = heavy ? Math.sin(TAU * 70 * t) * Math.sin(TAU * 11 * t) * Math.exp(-t / 0.12) * 0.25 : 0;
+    const x = sub2 + slap + tk + rattle;
+    buf[i] = Math.tanh(x * 1.5);
+  }
+  return { buf, send: heavy ? 0.4 : 0.3, duck: 1 };
+}
+function pop(pitch, r) {
+  const buf = alloc(0.2);
+  const n = buf.length;
+  const f1 = 330 * semis(pitch) * (0.95 + 0.1 * r());
+  const f0 = f1 * 3.4;
+  let ph = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    ph += TAU * (f1 + (f0 - f1) * Math.exp(-t / 0.018)) / SR;
+    buf[i] = Math.sin(ph) * envAD(t, 1e-3, 0.045) + (r() * 2 - 1) * (t < 15e-4 ? 0.5 : 0);
+  }
+  return { buf, send: 0.15, duck: 0.35 };
+}
+function tick(pitch, r, soft = false) {
+  const buf = alloc(0.06);
+  const n = buf.length;
+  const f = new Svf();
+  f.set((soft ? 2e3 : 2700) * semis(pitch), 7);
+  const fb = 1700 * semis(pitch);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    f.run(r() * 2 - 1);
+    buf[i] = f.bp * 2.2 * envAD(t, 5e-4, 9e-3) + Math.sin(TAU * fb * t) * envAD(t, 5e-4, 6e-3) * 0.5;
+  }
+  return { buf, send: 0.1, duck: 0 };
+}
+function click(pitch, r) {
+  const buf = alloc(0.05);
+  const n = buf.length;
+  const f = new Svf();
+  f.set(4200 * semis(pitch), 1);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    f.run(r() * 2 - 1);
+    buf[i] = f.hp * envAD(t, 3e-4, 3e-3) * 1.4 + Math.sin(TAU * 1400 * semis(pitch) * t) * envAD(t, 5e-4, 0.012) * 0.6;
+  }
+  return { buf, send: 0.08, duck: 0 };
+}
+function riser(dur, pitch, r, down) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const f = new Svf();
+  let ph = 0;
+  const lo = 110 * semis(pitch);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    let p = i / n;
+    if (down) p = 1 - p;
+    f.set(300 * Math.pow(2, 4.3 * p), 1.1);
+    f.run(r() * 2 - 1);
+    const trem = 0.7 + 0.3 * Math.sin(TAU * (3 + 22 * p * p) * t);
+    const amp = Math.pow(p, down ? 1.4 : 1.8);
+    ph += TAU * lo * Math.pow(2, 2 * p) / SR;
+    const tone2 = Math.sin(ph) * Math.pow(p, 2) * 0.4;
+    const edge = down ? Math.min(1, t / 0.01) : Math.min(1, (dur - t) / 0.012);
+    buf[i] = (f.hp * 1.1 * trem * amp + f.bp * 0.4 * amp + tone2) * edge;
+  }
+  return { buf, send: 0.3, duck: 0 };
+}
+function sub(pitch) {
+  const buf = alloc(0.75);
+  const n = buf.length;
+  const f0 = 72 * semis(pitch), f1 = 34 * semis(pitch);
+  let ph = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    ph += TAU * (f1 + (f0 - f1) * Math.exp(-t / 0.12)) / SR;
+    buf[i] = (Math.sin(ph) + Math.sin(2 * ph) * 0.2) * envAD(t, 5e-3, 0.26);
+  }
+  return { buf, send: 0.15, duck: 1 };
+}
+function shimmer(dur, pitch, r) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const parts = [];
+  for (let k = 0; k < 7; k++) {
+    const f = (1400 + 3800 * r()) * semis(pitch);
+    parts.push({ f, on: r() * dur * 0.35, tau: dur * (0.25 + 0.2 * r()), a: Math.sqrt(1400 / f), vib: 5 + 2 * r(), ph: r() * TAU });
+  }
+  const air = new Svf();
+  air.set(6e3, 0.7);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    let x = 0;
+    for (const p of parts) {
+      if (t < p.on) continue;
+      const dt = t - p.on;
+      x += Math.sin(p.ph + TAU * p.f * dt * (1 + 3e-3 * Math.sin(TAU * p.vib * dt))) * p.a * envAD(dt, 0.03, p.tau);
+    }
+    air.run(r() * 2 - 1);
+    buf[i] = x * 0.3 + air.hp * 0.05 * Math.sin(Math.PI * (i / n));
+  }
+  return { buf, send: 0.6, duck: 0 };
+}
+function ding(hz) {
+  const buf = alloc(1.8);
+  const n = buf.length;
+  const ratios = [1, 2, 3.01, 4.16, 5.43];
+  const amps = [1, 0.5, 0.3, 0.18, 0.1];
+  const scale = Math.sqrt(880 / hz);
+  const taus = [1.5, 0.8, 0.55, 0.38, 0.22].map((x) => x * scale);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    const bend = 1 + 0.01 * Math.exp(-t / 0.02);
+    let x = 0;
+    for (let k = 0; k < ratios.length; k++) x += Math.sin(TAU * hz * ratios[k] * bend * t) * amps[k] * envAD(t, 2e-3, taus[k]);
+    buf[i] = x * 0.5;
+  }
+  return { buf, send: 0.5, duck: 0.3 };
+}
+function swell(dur, pitch, r) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const f = new Svf();
+  const base = 110 * semis(pitch);
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    const p = i / n;
+    const bell = Math.pow(Math.sin(Math.PI * p), 2);
+    f.set(300 + 900 * Math.sin(Math.PI * Math.min(1, p * 1.3)), 0.8);
+    f.run(r() * 2 - 1);
+    buf[i] = f.lp * 0.7 * bell + Math.sin(TAU * base * t * (1 + 0.02 * Math.sin(TAU * 0.7 * t))) * 0.45 * bell;
+  }
+  return { buf, send: 0.45, duck: 0 };
+}
+function zap(dur, pitch, r) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const f = new Svf();
+  f.set(900, 0.8);
+  let gate = 1, next = 0, hold = 0, holdN = 0, ph = 0;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    if (i >= next) {
+      gate = r() < 0.55 ? 1 : 0;
+      next = i + Math.floor(SR / (45 + 60 * r()));
+    }
+    const dec = Math.max(1, Math.floor(1 + 14 * (i / n)));
+    if (holdN-- <= 0) {
+      hold = r() * 2 - 1;
+      holdN = dec;
+    }
+    f.run(hold);
+    ph += TAU * (180 + 2e3 * Math.exp(-t / 0.05)) * semis(pitch) / SR;
+    const chirp = (Math.sin(ph) > 0 ? 1 : -1) * 0.35 * Math.exp(-t / 0.06);
+    buf[i] = (f.hp * 1.2 * gate + chirp) * envAD(t, 1e-3, 0.12);
+  }
+  return { buf, send: 0.12, duck: 0.2 };
+}
+function typing(dur, pitch, r) {
+  const buf = alloc(dur + 0.08);
+  let t0 = 0;
+  while (t0 < dur) {
+    const k = tick(pitch + (r() - 0.5) * 5, r);
+    const start = Math.floor(t0 * SR);
+    const vel = 0.7 + 0.3 * r();
+    for (let i = 0; i < k.buf.length && start + i < buf.length; i++) buf[start + i] += k.buf[i] * vel;
+    for (let i = 0; i < 400 && start + i < buf.length; i++) buf[start + i] += Math.sin(TAU * 190 * (i / SR)) * envAD(i / SR, 5e-4, 4e-3) * 0.35 * vel;
+    t0 += 0.065 + 0.05 * r() + (r() < 0.12 ? 0.08 : 0);
+  }
+  return { buf, send: 0.1, duck: 0 };
+}
+function scratch(dur, pitch, r) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const f = new Svf();
+  let wob = 0.5;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    const p = i / n;
+    if (i % 240 === 0) wob += (r() - 0.5) * 0.5, wob = clamp(wob, 0.1, 1);
+    f.set(2200 * semis(pitch) * (0.8 + 0.4 * wob), 2.2);
+    f.run(r() * 2 - 1);
+    const grit = 0.75 + 0.25 * Math.sin(TAU * (28 + 30 * wob) * t);
+    buf[i] = f.bp * 1.6 * grit * wob * Math.pow(Math.sin(Math.PI * p), 0.5);
+  }
+  return { buf, send: 0.15, duck: 0 };
+}
+function tone(dur, hz, r) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const rel = dur * 0.3;
+  const ph0 = r() * TAU;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    const vib = 1 + 4e-3 * Math.sin(TAU * 5.5 * t);
+    const env = Math.min(1, t / 0.015) * (t > dur - rel ? (dur - t) / rel : 1);
+    buf[i] = (Math.sin(ph0 + TAU * hz * vib * t) + Math.sin(3 * (ph0 + TAU * hz * vib * t)) / 9) * env * 0.8;
+  }
+  return { buf, send: 0.35, duck: 0 };
+}
+function pad(dur, hzs, level, bright, r, attack, release) {
+  const buf = alloc(dur);
+  const n = buf.length;
+  const f = new Svf();
+  const voices = hzs.flatMap((hz) => [-1, 1].map((d) => ({ hz: hz * semis(d * (5 + 3 * r()) / 100), ph: r() })));
+  const subHz = Math.min(...hzs) / 2;
+  const lfo = r() * TAU;
+  for (let i = 0; i < n; i++) {
+    const t = i / SR;
+    let x = 0;
+    for (const v of voices) {
+      v.ph += v.hz / SR;
+      if (v.ph >= 1) v.ph -= 1;
+      x += v.ph * 2 - 1;
+    }
+    x /= voices.length;
+    x += Math.sin(TAU * subHz * t) * 0.35;
+    f.set(380 * Math.pow(2, 1.6 * bright) * (1 + 0.2 * Math.sin(lfo + TAU * 0.09 * t)), 0.7);
+    f.run(x);
+    const env = Math.min(1, t / attack) * Math.min(1, (dur - t) / release);
+    buf[i] = f.lp * level * env;
+  }
+  return buf;
+}
+function reverb(inL, inR, wet) {
+  const n = inL.length;
+  const mk = (delays, aps) => {
+    const combs = delays.map((d) => ({ buf: new Float32Array(d), i: 0, lp: 0 }));
+    const all = aps.map((d) => ({ buf: new Float32Array(d), i: 0 }));
+    return (x) => {
+      let y = 0;
+      for (const c of combs) {
+        const out = c.buf[c.i];
+        c.lp = out * 0.8 + c.lp * 0.2;
+        c.buf[c.i] = x + c.lp * 0.78;
+        c.i = (c.i + 1) % c.buf.length;
+        y += out;
+      }
+      y /= combs.length;
+      for (const a of all) {
+        const b = a.buf[a.i];
+        const v = y + b * 0.5;
+        a.buf[a.i] = v;
+        a.i = (a.i + 1) % a.buf.length;
+        y = b - 0.5 * v;
+      }
+      return y;
+    };
+  };
+  const L = mk([1215, 1293, 1390, 1476], [605, 480]);
+  const R = mk([1238, 1316, 1413, 1499], [628, 503]);
+  const oL = new Float32Array(n), oR = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const m = (inL[i] + inR[i]) * 0.5;
+    oL[i] = L(m) * wet;
+    oR[i] = R(m) * wet;
+  }
+  return [oL, oR];
+}
+function normalizeSoundSpec(raw, duration) {
+  const warnings = [];
+  const spec2 = {};
+  if (raw == null || raw === false) return { spec: spec2, warnings };
+  const obj = Array.isArray(raw) ? { cues: raw } : typeof raw === "object" ? raw : {};
+  const cues = [];
+  for (const c of Array.isArray(obj.cues) ? obj.cues : []) {
+    if (!c || typeof c !== "object") continue;
+    const q2 = c;
+    const kind = String(q2.kind ?? q2.sound ?? "");
+    if (!SOUND_KINDS.includes(kind)) {
+      warnings.push(`sound: "${kind}" is not a sound (${SOUND_KINDS.join(", ")})`);
+      continue;
+    }
+    const at = Number(q2.at);
+    if (!Number.isFinite(at)) {
+      warnings.push(`sound: a ${kind} cue has no time (at)`);
+      continue;
+    }
+    const cue = { at: clamp(at < 0 ? duration + at : at, 0, duration), kind };
+    if (Number.isFinite(Number(q2.dur)) && Number(q2.dur) > 0) cue.dur = clamp(Number(q2.dur), 0.02, 60);
+    if (Number.isFinite(Number(q2.level))) cue.level = clamp(Number(q2.level), 0, 2);
+    if (Number.isFinite(Number(q2.pitch))) cue.pitch = clamp(Number(q2.pitch), -36, 36);
+    if (Number.isFinite(Number(q2.pan))) cue.pan = clamp(Number(q2.pan), -1, 1);
+    if (Number.isFinite(Number(q2.seed))) cue.seed = Number(q2.seed);
+    if (typeof q2.note === "string" && noteHz(q2.note) !== null) cue.note = q2.note;
+    cues.push(cue);
+  }
+  if (cues.length) spec2.cues = cues;
+  if (obj.bed !== void 0) {
+    const b = obj.bed;
+    if (b === true || typeof b === "string") spec2.bed = b;
+    else if (b && typeof b === "object") {
+      const o = b;
+      const bed = {};
+      if (typeof o.key === "string") bed.key = o.key;
+      if (o.mode === "major" || o.mode === "minor") bed.mode = o.mode;
+      if (Number.isFinite(Number(o.from))) bed.from = Math.max(0, Number(o.from));
+      if (Number.isFinite(Number(o.to))) bed.to = Number(o.to) < 0 ? duration + Number(o.to) : Number(o.to);
+      if (Number.isFinite(Number(o.level))) bed.level = clamp(Number(o.level), 0, 1);
+      if (Number.isFinite(Number(o.tone))) bed.tone = clamp(Number(o.tone), 0, 1);
+      spec2.bed = bed;
+    } else spec2.bed = false;
+  }
+  if (obj.auto !== void 0) spec2.auto = Boolean(obj.auto);
+  if (Number.isFinite(Number(obj.level))) spec2.level = clamp(Number(obj.level), 0, 2);
+  if (Number.isFinite(Number(obj.room))) spec2.room = clamp(Number(obj.room), 0, 1);
+  return { spec: spec2, warnings };
+}
+function bedOf(b, duration) {
+  if (!b) return null;
+  const base = b === true ? {} : typeof b === "string" ? { ...parseKeyToBed(b) } : { ...b };
+  const k = parseKey(base.key);
+  return { key: base.key ?? "A", mode: base.mode ?? k.mode, from: clamp(base.from ?? 0, 0, duration), to: clamp(base.to ?? duration, 0, duration), level: base.level ?? 0.5, tone: base.tone ?? 0.4 };
+}
+function parseKeyToBed(key) {
+  const k = parseKey(key);
+  const name = /^\s*([A-Ga-g][#b♯♭]?)/.exec(key)?.[1] ?? "A";
+  return { key: name, mode: k.mode };
+}
+function cuesFromMarks(marks, duration) {
+  const list = marks.filter((m) => Number.isFinite(m[1]) && m[1] >= -0.01 && m[1] <= duration + 0.01).map((m) => ({ kind: m[0], at: Math.max(0, Math.round(m[1] * 1e3) / 1e3, 0), a: m[2], b: m[3] })).sort((x, y) => x.at - y.at);
+  const RANK = { stamp: 9, shake: 8, burst: 7, flash: 7, enter: 6, reveal: 6, typed: 6, write: 6, ink: 6, press: 6, underline: 5, strike: 5, count: 5, bar: 5, pop: 4, bump: 3, letter: 2, word: 2, fade: 1, exit: 1, beat: 0 };
+  const moments = [];
+  for (const m of list) {
+    if (m.kind === "beat") continue;
+    const last = moments[moments.length - 1];
+    if (last && Math.abs(last.at - m.at) < 0.012) {
+      last.n++;
+      if ((RANK[m.kind] ?? 0) > (RANK[last.kind] ?? 0)) Object.assign(last, { kind: m.kind, a: m.a, b: m.b });
+      continue;
+    }
+    moments.push({ ...m, n: 1 });
+  }
+  const cues = [];
+  const unit = /* @__PURE__ */ new Set(["letter", "word", "bump", "pop", "bar", "enter", "fade"]);
+  let i = 0;
+  while (i < moments.length) {
+    const m = moments[i];
+    let j = i;
+    if (unit.has(m.kind)) while (j + 1 < moments.length && unit.has(moments[j + 1].kind) && moments[j + 1].at - moments[j].at < 0.26 && moments[j + 1].at - m.at < 0.9) j++;
+    if (j - i + 1 >= 4) {
+      const n = j - i + 1;
+      cues.push(...cueFor(m, duration));
+      for (let k = i + 1; k <= j; k++) cues.push({ at: moments[k].at, kind: "tick", level: 0.75 - 0.35 * (k - i) / n, pitch: Math.min(10, (k - i) * (9 / n)), pan: ((k - i) / n - 0.5) * 0.5 });
+      i = j + 1;
+      continue;
+    }
+    cues.push(...cueFor(m, duration));
+    i++;
+  }
+  const strong = cues.filter((c) => c.kind !== "swell" && c.kind !== "tick");
+  const out = cues.filter((c) => c.kind !== "swell" ? true : !strong.some((s) => Math.abs(s.at - c.at) < 0.15));
+  if (out.length > 60) {
+    const ticks = out.filter((c) => c.kind === "tick");
+    const keepEvery = Math.ceil(ticks.length / Math.max(1, 60 - (out.length - ticks.length)));
+    let k = 0;
+    return out.filter((c) => c.kind !== "tick" || k++ % keepEvery === 0);
+  }
+  return out;
+}
+function cueFor(m, duration) {
+  const at = m.at;
+  switch (m.kind) {
+    case "stamp":
+      return [{ at, kind: "stamp" }];
+    case "shake":
+      return [{ at, kind: "hit", level: clamp(0.6 + (m.a ?? 18) / 60, 0.6, 1.1) }];
+    case "burst":
+      return [{ at, kind: "pop", level: 0.9 }, { at, kind: "shimmer", level: 0.8, dur: 1 }];
+    case "flash":
+      return [{ at, kind: "zap", level: 0.7 }];
+    case "enter": {
+      const dist = Math.hypot(m.a ?? 0, m.b ?? 40);
+      return dist < 12 ? [{ at, kind: "pop", level: 0.7 }] : [{ at, kind: "whoosh", level: clamp(0.45 + dist / 360, 0.45, 1), dur: clamp(0.3 + dist / 900, 0.3, 0.6), pan: (m.a ?? 0) > 0 ? 0.25 : (m.a ?? 0) < 0 ? -0.25 : 0 }];
+    }
+    case "reveal":
+      return [{ at, kind: "whoosh", pitch: 4, dur: 0.45, level: 0.8 }];
+    case "typed":
+      return [{ at, kind: "type", dur: clamp(m.a ?? 0.8, 0.15, 6) }];
+    case "write":
+    case "ink":
+      return [{ at, kind: "scratch", dur: clamp(m.a ?? 0.8, 0.15, 6), pitch: m.b ? 3 : 0 }];
+    case "press":
+      return [{ at, kind: "click" }];
+    case "underline":
+      return [{ at, kind: "whoosh", pitch: 12, dur: 0.3, level: 0.6 }];
+    case "strike":
+      return [{ at, kind: "whoosh", pitch: 2, dur: 0.3, level: 0.7 }, { at: at + 0.12, kind: "hit", level: 0.5 }];
+    case "count":
+      return [{ at, kind: "type", dur: clamp(m.a ?? 0.8, 0.2, 4), level: 0.6, pitch: 4 }];
+    case "bar":
+      return [{ at, kind: "pop", level: 0.7, pitch: 3 }];
+    case "pop":
+      return [{ at, kind: "pop", level: m.n > 1 ? 0.9 : 0.8 }];
+    case "bump":
+      return [{ at, kind: "tick", level: 0.8 }];
+    case "letter":
+      return [{ at, kind: "tick", level: 0.6 }];
+    case "word":
+      return [{ at, kind: "tick", level: 0.7, pitch: -4 }];
+    case "fade":
+      return [{ at, kind: "swell", level: 0.7 }];
+    case "exit":
+      return at > duration - 0.05 ? [] : [{ at, kind: "whoosh", level: 0.45, pitch: -5, dur: 0.35 }];
+    default:
+      return [];
+  }
+}
+function voiceFor(cue, bed, index) {
+  const seed = cue.seed ?? index * 7.13 + cue.at * 3.7 + cue.kind.length;
+  const r = rng(seed);
+  const pitch = cue.pitch ?? 0;
+  const dur = cue.dur ?? DEFAULT_DUR[cue.kind] ?? 0.5;
+  switch (cue.kind) {
+    case "whoosh":
+      return whoosh(dur, pitch, r);
+    case "hit":
+      return hit(pitch, r, false);
+    case "stamp":
+      return hit(pitch, r, true);
+    case "pop":
+      return pop(pitch, r);
+    case "tick":
+      return tick(pitch, r);
+    case "click":
+      return click(pitch, r);
+    case "riser":
+      return riser(dur, pitch, r, false);
+    case "fall":
+      return riser(dur, pitch, r, true);
+    case "sub":
+      return sub(pitch);
+    case "shimmer":
+      return shimmer(dur, pitch, r);
+    case "ding":
+      return ding((cue.note ? noteHz(cue.note) : null) ?? 880 * semis(pitch));
+    case "swell":
+      return swell(dur, pitch, r);
+    case "zap":
+      return zap(dur, pitch, r);
+    case "type":
+      return typing(dur, pitch, r);
+    case "scratch":
+      return scratch(dur, pitch, r);
+    case "tone":
+      return tone(dur, (cue.note ? noteHz(cue.note) : null) ?? 440 * semis(pitch), r);
+    case "chord": {
+      const k = parseKey(bed?.key ? `${bed.key}${bed.mode === "major" ? "" : "m"}` : "Am");
+      const centre = -12 + pitch;
+      const hz = cue.note ? [noteHz(cue.note), noteHz(cue.note) * semis(bed?.mode === "major" ? 4 : 3), noteHz(cue.note) * semis(7)] : chordTones(k.root, k.mode, 1, centre).map((s) => 440 * semis(s));
+      return { buf: pad(dur, hz, 1.1, bed?.tone ?? 0.5, r, Math.min(0.06, dur * 0.2), Math.max(0.05, dur * 0.3)), send: 0.4, duck: 0 };
+    }
+  }
+}
+function renderSound(spec2, duration, opts = {}) {
+  const sr = SR;
+  void opts;
+  const warnings = [];
+  const n = Math.max(1, Math.round(duration * sr));
+  const L = new Float32Array(n), R = new Float32Array(n), sL = new Float32Array(n), sR = new Float32Array(n);
+  const cues = (spec2.cues ?? []).filter((c) => c.at >= 0 && c.at <= duration).sort((a, b) => a.at - b.at);
+  const ducks = [];
+  cues.forEach((cue, idx) => {
+    const v = voiceFor(cue, bedOf(spec2.bed, duration), idx);
+    const level = BASE_LEVEL[cue.kind] * (cue.level ?? 1);
+    const pan = clamp(cue.pan ?? 0, -1, 1);
+    const gl = Math.cos((pan + 1) * Math.PI / 4) * Math.SQRT2 * 0.78;
+    const gr = Math.sin((pan + 1) * Math.PI / 4) * Math.SQRT2 * 0.78;
+    const start = Math.round(cue.at * sr);
+    for (let i = 0; i < v.buf.length; i++) {
+      const j = start + i;
+      if (j >= n) break;
+      const x = v.buf[i] * level;
+      L[j] += x * gl;
+      R[j] += x * gr;
+      sL[j] += x * gl * v.send;
+      sR[j] += x * gr * v.send;
+    }
+    if (v.duck > 0) ducks.push({ at: cue.at, depth: v.duck * clamp(cue.level ?? 1, 0, 1.2) });
+  });
+  const bed = bedOf(spec2.bed, duration);
+  if (bed && bed.to > bed.from + 0.2) {
+    const r = rng(11.7);
+    const k = parseKey(`${bed.key}${bed.mode === "major" ? "" : "m"}`);
+    const len = bed.to - bed.from;
+    const two = len > 5;
+    const split = two ? bed.from + len * 0.55 : bed.to;
+    const degreeB = bed.mode === "major" ? 4 : 6;
+    const lvl = 0.26 * bed.level;
+    const chords = [{ from: bed.from, to: two ? split + 0.6 : bed.to, tones: chordTones(k.root, k.mode, 1, -15) }];
+    if (two) chords.push({ from: split - 0.2, to: bed.to, tones: chordTones(k.root, k.mode, degreeB, -15) });
+    chords.forEach((ch, ci) => {
+      const hz = ch.tones.map((s) => 440 * semis(s));
+      hz.push(440 * semis(ch.tones[0] + 12));
+      const d = ch.to - ch.from;
+      const attack = ci === 0 ? Math.min(1.4, d * 0.35) : 0.7;
+      const release = Math.min(1.6, d * 0.4);
+      const mL = pad(d, hz, lvl, bed.tone, rng(3.3 + ci), attack, release);
+      const mR = pad(d, hz, lvl, bed.tone, rng(9.1 + ci), attack, release);
+      const start = Math.round(ch.from * sr);
+      for (let i = 0; i < mL.length; i++) {
+        const j = start + i;
+        if (j >= n) break;
+        const t = j / sr;
+        let g = 1;
+        for (const dk of ducks) {
+          const dt = t - dk.at;
+          if (dt >= 0 && dt < 1.2) g -= 0.4 * dk.depth * (dt < 6e-3 ? dt / 6e-3 : Math.exp(-(dt - 6e-3) / 0.33));
+        }
+        g = Math.max(0.35, g);
+        L[j] += mL[i] * g;
+        R[j] += mR[i] * g;
+        sL[j] += mL[i] * g * 0.3;
+        sR[j] += mR[i] * g * 0.3;
+      }
+    });
+    void r;
+  }
+  const room = spec2.room ?? 0.25;
+  if (room > 0) {
+    const [wL, wR] = reverb(sL, sR, 1.4 * room);
+    for (let i = 0; i < n; i++) {
+      L[i] += wL[i];
+      R[i] += wR[i];
+    }
+  }
+  const master = 0.85 * (spec2.level ?? 1);
+  const rel = Math.exp(-1 / (0.12 * sr));
+  const ceiling = 0.95;
+  let env = 0, peak = 0;
+  const fadeIn = Math.round(0.02 * sr), fadeOut = Math.round(0.06 * sr);
+  for (let i = 0; i < n; i++) {
+    let l = L[i] * master, r22 = R[i] * master;
+    const edge = (i < fadeIn ? i / fadeIn : 1) * (i > n - fadeOut ? (n - i) / fadeOut : 1);
+    l *= edge;
+    r22 *= edge;
+    const a = Math.max(Math.abs(l), Math.abs(r22));
+    env = Math.max(a, env * rel);
+    const g = env > ceiling ? ceiling / env : 1;
+    l = knee(l * g);
+    r22 = knee(r22 * g);
+    L[i] = l;
+    R[i] = r22;
+    peak = Math.max(peak, Math.abs(l), Math.abs(r22));
+  }
+  return { left: L, right: R, sampleRate: sr, cues, peak, bed, warnings };
+}
+function knee(x) {
+  const a = Math.abs(x);
+  if (a <= 0.8) return x;
+  return Math.sign(x) * (0.8 + 0.2 * Math.tanh((a - 0.8) / 0.2));
+}
+function wavEncode(left, right, sampleRate) {
+  const n = Math.min(left.length, right.length);
+  const data = new Uint8Array(44 + n * 4);
+  const dv = new DataView(data.buffer);
+  const str2 = (o2, s) => {
+    for (let i = 0; i < s.length; i++) data[o2 + i] = s.charCodeAt(i);
+  };
+  str2(0, "RIFF");
+  dv.setUint32(4, 36 + n * 4, true);
+  str2(8, "WAVE");
+  str2(12, "fmt ");
+  dv.setUint32(16, 16, true);
+  dv.setUint16(20, 1, true);
+  dv.setUint16(22, 2, true);
+  dv.setUint32(24, sampleRate, true);
+  dv.setUint32(28, sampleRate * 4, true);
+  dv.setUint16(32, 4, true);
+  dv.setUint16(34, 16, true);
+  str2(36, "data");
+  dv.setUint32(40, n * 4, true);
+  let o = 44;
+  for (let i = 0; i < n; i++) {
+    dv.setInt16(o, Math.round(clamp(left[i], -1, 1) * 32767), true);
+    dv.setInt16(o + 2, Math.round(clamp(right[i], -1, 1) * 32767), true);
+    o += 4;
+  }
+  return data;
+}
+function describeCues(cues) {
+  return cues.map((c) => `  ${c.at.toFixed(2).padStart(6)} s  ${c.kind.padEnd(8)}${c.dur ? ` ${c.dur.toFixed(2)} s` : ""}${c.level !== void 0 && c.level !== 1 ? ` \xD7${c.level.toFixed(2)}` : ""}${c.pitch ? ` ${c.pitch > 0 ? "+" : ""}${c.pitch} st` : ""}${c.note ? ` ${c.note}` : ""}${c.pan ? ` pan ${c.pan > 0 ? "R" : "L"}${Math.abs(c.pan).toFixed(1)}` : ""}`).join("\n");
+}
+
 // src/node/render.ts
 import { spawn } from "node:child_process";
-import { mkdirSync, statSync as statSync2, writeFileSync } from "node:fs";
-import { availableParallelism } from "node:os";
-import { dirname as dirname2, join as join5, resolve as resolve2 } from "node:path";
+import { mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { availableParallelism, tmpdir } from "node:os";
+import { dirname, join as join2, resolve } from "node:path";
 import { Resvg, renderAsync } from "@resvg/resvg-js";
 
 // src/node/outline.ts
@@ -5395,7 +6118,7 @@ function pathDataLength(d) {
   const tokens = d.match(/[MmLlHhVvCcSsQqTtAaZz]|-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/g) ?? [];
   let i = 0, cmd = "", x = 0, y = 0, sx = 0, sy = 0, len = 0;
   let cx = 0, cy = 0, qx = 0, qy = 0, prev = "";
-  const num2 = () => Number(tokens[i++]);
+  const num = () => Number(tokens[i++]);
   const seg = (nx, ny) => {
     len += Math.hypot(nx - x, ny - y);
     x = nx;
@@ -5455,23 +6178,23 @@ function pathDataLength(d) {
     const ox = rel ? x : 0, oy = rel ? y : 0;
     switch (cmd.toUpperCase()) {
       case "M":
-        x = num2() + ox;
-        y = num2() + oy;
+        x = num() + ox;
+        y = num() + oy;
         sx = x;
         sy = y;
         cmd = rel ? "l" : "L";
         break;
       case "L":
-        seg(num2() + ox, num2() + oy);
+        seg(num() + ox, num() + oy);
         break;
       case "H":
-        seg(num2() + ox, y);
+        seg(num() + ox, y);
         break;
       case "V":
-        seg(x, num2() + oy);
+        seg(x, num() + oy);
         break;
       case "C": {
-        const a = num2() + ox, b = num2() + oy, c = num2() + ox, e = num2() + oy, f = num2() + ox, g = num2() + oy;
+        const a = num() + ox, b = num() + oy, c = num() + ox, e = num() + oy, f = num() + ox, g = num() + oy;
         cx = c;
         cy = e;
         cubic(a, b, c, e, f, g);
@@ -5479,14 +6202,14 @@ function pathDataLength(d) {
       }
       case "S": {
         const r1x = /[CS]/i.test(prev) ? 2 * x - cx : x, r1y = /[CS]/i.test(prev) ? 2 * y - cy : y;
-        const c = num2() + ox, e = num2() + oy, f = num2() + ox, g = num2() + oy;
+        const c = num() + ox, e = num() + oy, f = num() + ox, g = num() + oy;
         cx = c;
         cy = e;
         cubic(r1x, r1y, c, e, f, g);
         break;
       }
       case "Q": {
-        const a = num2() + ox, b = num2() + oy, f = num2() + ox, g = num2() + oy;
+        const a = num() + ox, b = num() + oy, f = num() + ox, g = num() + oy;
         qx = a;
         qy = b;
         quad(a, b, f, g);
@@ -5496,12 +6219,12 @@ function pathDataLength(d) {
         const a = /[QT]/i.test(prev) ? 2 * x - qx : x, b = /[QT]/i.test(prev) ? 2 * y - qy : y;
         qx = a;
         qy = b;
-        quad(a, b, num2() + ox, num2() + oy);
+        quad(a, b, num() + ox, num() + oy);
         break;
       }
       case "A": {
-        const rx = num2(), ry = num2(), phi = num2(), large = num2(), sweep = num2();
-        arc(rx, ry, phi, large ? 1 : 0, sweep ? 1 : 0, num2() + ox, num2() + oy);
+        const rx = num(), ry = num(), phi = num(), large = num(), sweep = num();
+        arc(rx, ry, phi, large ? 1 : 0, sweep ? 1 : 0, num() + ox, num() + oy);
         break;
       }
       case "Z":
@@ -5621,6 +6344,15 @@ function frameAt(s, t, background, timeoutMs) {
   const doc = frameDocument(s.built.program, frame, s.width, s.height, { background });
   return { doc, fonts: fontFilesForDocument(doc), frame };
 }
+function framePixels(s, t) {
+  const f = frameAt(s, t, null);
+  try {
+    const img = new Resvg(f.doc, resvgOptions(f.fonts, s.width)).render();
+    return { data: img.pixels, width: img.width, height: img.height };
+  } catch (err) {
+    throw parseError(err);
+  }
+}
 function parseError(err) {
   return new MotionError(`the frame's SVG does not parse (${String(err?.message ?? err).slice(0, 200)}) \u2014 escape text with $.esc() and close every tag`);
 }
@@ -5643,8 +6375,8 @@ async function renderStill(item, opts = {}) {
   }
   const result = { format, data, width: s.width, height: s.height, t, warnings: s.warnings };
   if (opts.out) {
-    const file = resolve2(opts.out);
-    mkdirSync(dirname2(file), { recursive: true });
+    const file = resolve(opts.out);
+    mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, data);
     result.file = file;
   }
@@ -5688,6 +6420,54 @@ async function renderSheet(item, opts = {}) {
   return { png, times, warnings: s.warnings, width: W, height: H };
 }
 var EXT = { mov: ".mov", webm: ".webm", mp4: ".mp4", hevc: ".mov", gif: ".gif", png: "" };
+function designSound(s, opts, duration = s.built.duration) {
+  const warnings = [];
+  const own = s.runner.sound();
+  if (own.error) warnings.push(own.error);
+  const { spec: spec2, warnings: w } = normalizeSoundSpec(own.spec, duration);
+  warnings.push(...w);
+  if (typeof opts.sound === "object" && opts.sound) {
+    const o = normalizeSoundSpec(opts.sound, duration);
+    warnings.push(...o.warnings);
+    if (o.spec.cues) spec2.cues = [...spec2.cues ?? [], ...o.spec.cues];
+    if (o.spec.bed !== void 0) spec2.bed = o.spec.bed;
+    if (o.spec.auto !== void 0) spec2.auto = o.spec.auto;
+    if (o.spec.level !== void 0) spec2.level = o.spec.level;
+    if (o.spec.room !== void 0) spec2.room = o.spec.room;
+  }
+  if (opts.bed !== void 0) spec2.bed = opts.bed;
+  if (spec2.auto ?? !spec2.cues?.length) {
+    const tr = s.runner.trace(s.fps);
+    if (tr.error) warnings.push(tr.error);
+    spec2.cues = [...spec2.cues ?? [], ...cuesFromMarks(tr.marks, duration)].sort((a, b) => a.at - b.at);
+  }
+  if (!spec2.cues?.length && !spec2.bed) warnings.push("sound: nothing in this graphic moves in a way the sound design reads, so its track is silent \u2014 add a bed (--bed Dm) or a sound($) to the program");
+  return { spec: spec2, warnings };
+}
+async function renderSoundFile(item, opts = {}) {
+  const s = await openSession(item, opts);
+  const total = Math.max(1, Math.round(s.built.duration * s.fps));
+  const duration = total / s.fps;
+  const { spec: spec2, warnings } = designSound(s, { sound: opts.sound ?? true, bed: opts.bed }, duration);
+  const r = renderSound(spec2, duration);
+  const file = resolve(opts.out ?? join2(opts.outDir ?? ".", `${item.id}.wav`));
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, wavEncode(r.left, r.right, r.sampleRate));
+  return { cues: r.cues, bed: r.bed, peak: r.peak, duration, file, warnings: [...s.warnings, ...warnings, ...r.warnings] };
+}
+function audioArgs(format, encoders) {
+  switch (format) {
+    case "mov":
+      return ["-c:a", "pcm_s16le"];
+    case "mp4":
+    case "hevc":
+      return ["-c:a", "aac", "-b:a", "192k"];
+    case "webm":
+      return encoders.has("libopus") ? ["-c:a", "libopus", "-b:a", "128k"] : encoders.has("libvorbis") ? ["-c:a", "libvorbis"] : [];
+    default:
+      return [];
+  }
+}
 function formatFromPath(path) {
   const ext = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase();
   if (!ext) return "png";
@@ -5696,7 +6476,14 @@ function formatFromPath(path) {
 function defaultOutput(item, format, s) {
   return `${item.id}-${s.width}x${s.height}${format === "hevc" ? "-hevc" : ""}${EXT[format]}`;
 }
-function encoderArgs(format, s, alpha, encoders) {
+function encoderArgs(format, s, alpha, encoders, audio = null) {
+  const video = videoArgs(format, s, alpha, encoders);
+  const codec = audio ? audioArgs(format, encoders) : [];
+  if (!audio || !codec.length) return video;
+  const i = video.indexOf("-i") + 2;
+  return [...video.slice(0, i), "-i", audio, "-map", "0:v:0", "-map", "1:a:0", ...video.slice(i), ...codec];
+}
+function videoArgs(format, s, alpha, encoders) {
   const input = ["-hide_banner", "-loglevel", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${s.width}x${s.height}`, "-r", String(s.fps), "-i", "-"];
   switch (format) {
     case "mov":
@@ -5730,17 +6517,44 @@ async function renderVideo(item, opts = {}) {
     if (item.placement === "overlay" && format === "mp4") s.warnings.push("MP4 has no alpha: the overlay is drawn on black \u2014 pass --bg, or use mov/webm/hevc/png to keep it transparent");
   }
   const alpha = !bg;
-  const file = resolve2(opts.out ?? join5(opts.outDir ?? ".", defaultOutput(item, format, s)));
+  const file = resolve(opts.out ?? join2(opts.outDir ?? ".", defaultOutput(item, format, s)));
   if (format === "png") mkdirSync(file, { recursive: true });
-  else mkdirSync(dirname2(file), { recursive: true });
+  else mkdirSync(dirname(file), { recursive: true });
   const total = Math.max(1, Math.round(s.built.duration * s.fps));
   const concurrency = Math.max(1, Math.min(16, opts.concurrency ?? availableParallelism()));
   const holdAfter = s.built.program.holdAfter;
+  let audio = null;
+  let soundTmp = null;
+  let sound;
+  if (opts.sound || opts.bed !== void 0 || opts.soundOut) {
+    const duration = total / s.fps;
+    const { spec: spec2, warnings } = designSound(s, { sound: opts.sound ?? true, bed: opts.bed }, duration);
+    s.warnings.push(...warnings);
+    const r = renderSound(spec2, duration);
+    const wav = wavEncode(r.left, r.right, r.sampleRate);
+    sound = { cues: r.cues, bed: r.bed, peak: r.peak, duration, warnings: r.warnings };
+    if (opts.soundOut) {
+      sound.file = resolve(opts.soundOut);
+      mkdirSync(dirname(sound.file), { recursive: true });
+      writeFileSync(sound.file, wav);
+    }
+    if (!ff || format === "png" || format === "gif") s.warnings.push(`${format} carries no sound${sound.file ? "" : " \u2014 pass --sound-out file.wav to keep the track"}`);
+    else if (!audioArgs(format, ff.encoders).length) s.warnings.push(`this ffmpeg has no audio encoder for ${format} (libopus or libvorbis) \u2014 the video has no sound${sound.file ? "" : "; pass --sound-out file.wav to keep the track"}`);
+    else {
+      soundTmp = mkdtempSync(join2(tmpdir(), "volito-sound-"));
+      audio = join2(soundTmp, "sound.wav");
+      writeFileSync(audio, wav);
+    }
+  }
+  const cleanSound = () => {
+    if (soundTmp) rmSync(soundTmp, { recursive: true, force: true });
+    soundTmp = null;
+  };
   let enc = null;
   let encError = "";
   let encDone = null;
   if (ff) {
-    enc = spawn(ff.path, [...encoderArgs(format, s, alpha, ff.encoders), file], { stdio: ["pipe", "ignore", "pipe"] });
+    enc = spawn(ff.path, [...encoderArgs(format, s, alpha, ff.encoders, audio), file], { stdio: ["pipe", "ignore", "pipe"] });
     enc.stderr.on("data", (d) => {
       encError = (encError + d.toString()).slice(-4e3);
     });
@@ -5771,7 +6585,7 @@ async function renderVideo(item, opts = {}) {
   const flush = async (keep) => {
     while (queue.length > keep) {
       const buf = await queue.shift();
-      if (format === "png") writeFileSync(join5(file, `frame_${String(done + 1).padStart(5, "0")}.png`), buf);
+      if (format === "png") writeFileSync(join2(file, `frame_${String(done + 1).padStart(5, "0")}.png`), buf);
       else await write(buf);
       done++;
       opts.onProgress?.(done, total);
@@ -5801,19 +6615,21 @@ async function renderVideo(item, opts = {}) {
   } catch (err) {
     enc?.stdin?.destroy();
     enc?.kill("SIGKILL");
+    cleanSound();
     throw err;
   }
   if (enc) {
     enc.stdin.end();
     const code = await encDone;
+    cleanSound();
     if (code !== 0) throw new MotionError(`ffmpeg failed (${code}): ${encError.trim().slice(-600)}`);
   }
   let bytes = 0;
   try {
-    bytes = format === "png" ? 0 : statSync2(file).size;
+    bytes = format === "png" ? 0 : statSync(file).size;
   } catch {
   }
-  return { file, format, width: s.width, height: s.height, fps: s.fps, frames: total, duration: s.built.duration, drawn, bytes, ms: Math.round(performance.now() - started), warnings: s.warnings };
+  return { file, format, width: s.width, height: s.height, fps: s.fps, frames: total, duration: s.built.duration, drawn, bytes, ms: Math.round(performance.now() - started), warnings: s.warnings, ...sound ? { sound } : {} };
 }
 
 // src/node/check.ts
@@ -5865,194 +6681,6 @@ function describeReport(rep) {
   return lines.join("\n");
 }
 
-// src/node/inputs.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
-import { extname, resolve as resolve3 } from "node:path";
-var num = (v) => typeof v === "number" ? v : Number.parseFloat(String(v));
-function normalizeWords(input, offset = 0) {
-  const rows = Array.isArray(input) ? input : input && typeof input === "object" ? Array.isArray(input.words) ? input.words : Array.isArray(input.segments) ? input.segments.flatMap((s) => s.words ?? []) : [] : [];
-  const out = [];
-  for (const r of rows) {
-    const o = r ?? {};
-    const w = String(o.w ?? o.word ?? o.text ?? "").trim();
-    const s = num(o.s ?? o.start) - offset;
-    const e = num(o.e ?? o.end) - offset;
-    if (!w || !Number.isFinite(s)) continue;
-    if (s < -0.01) continue;
-    out.push({ w, s: Math.max(0, s), e: Number.isFinite(e) ? Math.max(s, e) : s + 0.3 });
-  }
-  return out.slice(0, 600);
-}
-function readWords(file, offset = 0) {
-  const path = resolve3(file);
-  if (!existsSync5(path)) throw new MotionError(`no transcript at ${path}`);
-  const words = normalizeWords(JSON.parse(readFileSync5(path, "utf8")), offset);
-  if (!words.length) throw new MotionError(`${path} has no timed words (expected [{w, s, e}] or Whisper JSON)`);
-  return words;
-}
-var MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml" };
-async function loadImage(src) {
-  if (src.startsWith("data:image/")) return src;
-  if (/^https?:\/\//i.test(src)) {
-    const res = await fetch(src);
-    if (!res.ok) throw new MotionError(`${src}: HTTP ${res.status}`);
-    const type2 = res.headers.get("content-type")?.split(";")[0] ?? MIME[extname(new URL(src).pathname).toLowerCase()] ?? "image/png";
-    if (!type2.startsWith("image/")) throw new MotionError(`${src} is not an image (${type2})`);
-    return `data:${type2};base64,${Buffer.from(await res.arrayBuffer()).toString("base64")}`;
-  }
-  const path = resolve3(src);
-  if (!existsSync5(path)) throw new MotionError(`no picture at ${path}`);
-  const type = MIME[extname(path).toLowerCase()];
-  if (!type) throw new MotionError(`${path}: pictures are PNG, JPEG, WebP, GIF or SVG`);
-  return `data:${type};base64,${readFileSync5(path).toString("base64")}`;
-}
-async function loadMedia(item, props = {}) {
-  const out = {};
-  for (const [name, spec2] of Object.entries(item.props)) {
-    const v = props[name] ?? spec2.default;
-    if (spec2.type !== "image" || typeof v !== "string" || !v.trim()) continue;
-    out[name] = await loadImage(v.trim());
-  }
-  return out;
-}
-function readStyleArg(arg) {
-  if (!arg) return void 0;
-  const path = resolve3(arg);
-  if (/\.(md|markdown|txt)$/i.test(arg) || existsSync5(path) && !/^[a-z0-9-]+$/i.test(arg)) {
-    if (!existsSync5(path)) throw new MotionError(`no style file at ${path}`);
-    return readFileSync5(path, "utf8");
-  }
-  return arg;
-}
-
-// src/guide.ts
-var MOTION_GUIDE = `Motion: any part, any move
-
-Every graphic is made of named parts (volito info <item> lists them). Each part enters, may idle
-while it holds, may take emphasis hits, and leaves \u2014 and every one of those is yours to change:
-
-  in / out      any move (volito moves): rise, slam, wipe, iris, glitch, scramble, typewriter,
-                spin, swing, stretch, smear, blur, flip, bounce \u2026 An exit plays the move backwards.
-  ease          brand, out, inOut, expo, back, elastic, bounce, snappy, punchy, bouncy, calm, wobbly,
-                spring(freq, damping), steps(n), cubic(x1,y1,x2,y2)
-  from          the side a move comes from (left, right, up, down, up-left \u2026); outFrom for the exit
-  dur, delay    seconds; at / outAt replace the item's own times (outAt negative = from the end)
-  distance      how far it travels (px at 1080) \xB7 intensity 0\u20132 scales distance, size and rotation
-  blur          true: motion blur on the way in and out \xB7 origin: the pivot (center, top-left, bottom \u2026)
-  idle          a loop while it holds: float, bob, pulse, breathe, wiggle, sway, drift, jitter, spin, heartbeat, shimmer
-  emphasis      hits: "pulse@1.2, shake@now, jump@beatName" (a time, a beat, or a spoken word)
-  split         text by lines, words or letters \xB7 order forward | reverse | center | edges | random \xB7 stagger s
-  keys          your own keyframes: [{"t":0,"x":-300,"op":0},{"t":0.8,"x":0,"op":1,"ease":"bouncy"}]
-                (t in clip seconds, x/y px at 1080, s scale, r degrees, skx, op, blur) \u2014 any path you like
-
-Set them per part, or for every part with "*":
-  CLI   --motion name.in=typewriter --motion "*.ease=bouncy" --motion plate.out=wipe --motion role.emphasis=pulse@2
-  API   { motion: { "*": { ease: "bouncy" }, name: { in: "typewriter" } } }
-
-Or let a mood choreograph it: --mood energetic | elegant | playful | cinematic | glitchy | minimal | retro | kinetic,
-and --seed <n> for a new take every number (a seed alone picks a mood too). Your own settings still win.
---speed 2 plays every move twice as fast.
-
-In your own code the same kit is there: const M = motion($, t);
-  M.part(name, { at, box: {x,y,w,h}, in, out, \u2026 }, ...markup)   a part, posed by its motion
-  M.text(name, { ...$.text options, at, in, split, \u2026 }, text)    text, whole or by unit
-  M.layout(text, textOptions, split) \u2192 { units: [{text, x, y, w, h, line, index, box}], box }
-  M.progress(name, { at, in, dur, ease }) \u2192 { in, out, at, end, outAt }  for things you draw yourself
-Give every part a box when you can: wipes, iris, shutter and blinds need it, and moods pick from more moves.`;
-var LIBRARY_GUIDE = `Libraries: layout, patterns, 3D and maps
-
-Layout (always there)
-  safeArea($) \u2192 {x, y, w, h, tall, square, wide}: the title-safe box (on 9:16 it clears the platforms' buttons)
-  fitFont($, str, role, size, maxW, extra) \u2192 a font in the brand's role, shrunk until str fits maxW
-  fitLines($, str, font, maxW, maxSize, minSize, maxLines) \u2192 {size, lines, font}: the biggest size that sets in \u2264 maxLines
-  landOn($, str, fallback, after) \u2192 when the first spoken word of str starts (0.08 s early), else fallback
-  widest($, lines, font) \xB7 avatar($, imageProp, cx, cy, r, {name, fill, ring}) \xB7 appIcon($, icon, x, y, size, {fill}) \xB7 initials(name)
-
-Patterns (always there) \u2014 sixteen animated grounds in the brand's colours, pure functions of t:
-  $.pattern(t, kind, {box, color, color2, a (strength), scale, speed, angle, at: [x, y], count, seed, r}) \u2192 markup
-  kinds: dots \xB7 plus \xB7 graph \xB7 hatch \xB7 stripes \xB7 checker \xB7 halftone \xB7 dither \xB7 waves \xB7 rings \xB7 mesh \xB7 confetti \xB7 bauhaus \xB7 tiles \xB7 pills \xB7 sunburst
-  A style whose texture names one draws it on every $.panel / $.texture ground. confetti, bauhaus and pills keep to the edges.
-
-Faces: Inter, Space Grotesk, Space Mono, Poppins, Playfair Display, Montserrat, Anton, Outfit, Gabarito, Caveat, Press Start 2P,
-  Permanent Marker, Patrick Hand, Fredoka, IM Fell English, Bebas Neue, DM Serif Display, Archivo Black, Syne, Unbounded,
-  Righteous, Orbitron, Pacifico, Fraunces, Bricolage Grotesque \u2014 name them "Family:weight" (e.g. "Fraunces:900", "Syne:800").
-
-3D \u2014 real depth, light and a camera, drawn as SVG paths (no GPU). Call it and the library comes with your program:
-  const S = scene3d($, { camera: { fov: 35, distance, yaw, pitch, roll, target: [x, y, z], x, y }, light: { dir: [x, y, z], ambient, spec, shine } });
-  Coordinates: x right, y down, z away from you, px at the target's depth (z = 0 draws at 1 px per unit by default).
-  Meshes: S.text(str, {face: $.font("display"), size, depth, color, side, back, anchor, ls, each: (i, n, ch) => ({rotate, offset, scale, hide})})
-          S.box(w, h, d, {color, side, back, radius}) \xB7 S.card(w, h, {depth, radius, color, back}) \xB7 S.disc(r, d, {...})
-          S.shape(loops | "M\u2026 path data", depth, {scale, color, side}) \xB7 S.sphere(r, {color}) (smooth) or {colorAt(lat, lon)}
-  Place: S.add(mesh, {position, rotate: [x\xB0, y\xB0, z\xB0], scale, parent: {position, rotate, parent}, opacity, flat, decal, twoSided})
-          \u2014 parent moves text with the card it is printed on; decal draws it over that card's face.
-  Also: S.line(points3d, {stroke, width}) \xB7 S.at(point3d, (x, y, scale) => markup) flat labels at 3D points \xB7 S.project(p) \u2192 {x, y, z, s}
-        S.measure(str, {face, size}) \xB7 S.clip(poly, normal, point)
-  Finish with: return S.render();   3D text uses the brand's display face (an item lists others in "faces3d").
-
-Maps (Natural Earth, 177 countries). Call one and the library comes with your program:
-  worldFind("India" | "UK" | "USA" | 356) \u2192 {name, id, c: [lon, lat], rings}
-  const m = worldMap($, { x, y, w, h, center: [lon, lat], zoom });  m.path(country | name) \u2192 path data \xB7 m.project(lon, lat) \u2192 [x, y]
-        m.countries \xB7 m.outline (the map's edge) \xB7 m.clipId() (clip to it) \xB7 m.ring(points)
-  worldGlobe(S, { r, spin, tilt, colorOf: (country) => colour }) countries on a 3D globe \xB7 worldOnSphere(lon, lat, r, spin, tilt) \u2192 a 3D point`;
-var AUTHORING_GUIDE = `Writing Volito graphics
-
-A graphic is a program: plain JavaScript that defines function frame(t, $) and returns the SVG markup of
-one frame (no <svg> root). It is a pure function of t \u2014 any frame can be drawn alone, in any order \u2014 so it
-renders the same in MONARC PRO, in a browser and from this CLI.
-
-Props and moments
-  An item's props arrive as $.data (const p = $.data; p.name, p.role \u2026). Never hard-code text a creator
-  would change: make it a prop with a default and a maxLength the design can hold.
-  Named moments come from $.beat(name, fallback). Pack items read "in" (when the entrance starts) and
-  "out" (when the exit starts) so a creator can move them: --beat in=0.4 --beat out=-0.6.
-  When words are given (a transcript), land each element 0.04\u20130.12 s before the word that says it:
-  $.words.length ? $.atOr(firstWord, fallback) : fallback. Without words, use the beats.
-
-Parts
-  Draw each element through the motion kit (const M = motion($, t)) as a named part, with the item's own
-  motion as defaults: M.part("plate", { at, in: "wipe", box }, markup), M.text("name", { ...font, at, in: "rise" }, text).
-  List the parts in item.json ("parts": { "plate": "the card" }) so creators know what they can move.
-  Backgrounds (scrims, panels) pass vary: false so a mood leaves them still.
-
-Shape of a good item
-  - Enter in the first ~0.8 s, hold, leave in the last ~0.4 s (or hold to the end when out \u2265 duration).
-  - Lay out from $.W, $.H and scale every size by $.k (= min(W, H) / 1080): one design fits 16:9, 9:16, 1:1, 4:5.
-  - Keep text inside the title-safe area: ~5% of the width at the sides on 16:9; on 9:16 leave ~13% at the
-    top and ~22% at the bottom for platform UI (captions, buttons).
-  - Size text to fit: measure it ($.measure) and shrink the size until it fits the box it owns; wrap long
-    text with maxW. The check reports any line that runs off the frame.
-  - Colour comes from the brand: $.c.bg / $.c.fg for ground and text, $.c.accent for the one thing that
-    matters, $.c.accent2 for markers, $.c.surface for cards. Faces from $.font("display" | "text" | "mono").
-    $.case(str) applies the brand's case. Never invent colours \u2014 a creator's DESIGN.md re-skins the item.
-  - overlay items draw nothing behind themselves (footage shows through); put a $.scrim under text that sits
-    on footage. full items draw their own ground with $.panel(t, { box: { x: 0, y: 0, w: $.W, h: $.H } }).
-  - Escape any text you put in raw markup with $.esc(); $.text, $.chip and friends escape for you.
-
-An item on disk
-  my-item/item.json   { "id": "my-item", "name": "\u2026", "description": "\u2026", "category": "title",
-                        "placement": "overlay" | "full", "duration": { "default": 5, "min": 2, "max": 20 },
-                        "aspects": ["16:9", "9:16", "1:1", "4:5"],
-                        "props": { "title": { "type": "text", "default": "Hello", "maxLength": 28 } },
-                        "beats": { "in": 0.15, "out": -0.45 } }
-  my-item/frame.js    function frame(t, $) { const p = $.data; \u2026 return svg; }
-  Prop types: text, longtext (line breaks kept), number (min, max, step), boolean, choice (options),
-  color (#hex, "" = the brand's), list (rows of text, or of {field: "text" | "number"}; maxItems),
-  image (a path or URL the caller loads; draw it with $.image(propName, x, y, w, h)), icon (an icon name).
-
-A pack
-  my-pack/pack.json   { "format": 1, "id": "my-pack", "name": "\u2026", "version": "1.0.0", "description": "\u2026",
-                        "author": "\u2026", "license": "\u2026", "style": "ember", "shared": "shared.js",
-                        "items": ["my-item", \u2026] }
-  my-pack/shared.js   helpers prepended to every item's code (function declarations only).
-  Load extra packs with --packs <dir> or VOLITO_PACKS=<dir>.
-
-The loop
-  volito new my-item          a template to start from
-  volito check ./my-item      errors and warnings at every aspect
-  volito sheet ./my-item      frames across time in one PNG \u2014 look at it
-  volito render ./my-item --format mov
-  Agents: motion_check, then motion_preview, fix what you see, then motion_render.`;
-
 export {
   MG_SPRITE_NAMES,
   MG_ICON_NAMES,
@@ -6063,6 +6691,9 @@ export {
   BUILTIN_STYLES2 as BUILTIN_STYLES,
   composeDesignMd2 as composeDesignMd,
   EDITOR_STYLES,
+  TrueTypeFace,
+  glyphTable,
+  setGlyphSource,
   MOVES,
   IDLES,
   HITS,
@@ -6082,6 +6713,8 @@ export {
   MotionError,
   manifestProblems,
   makeItem,
+  LIBRARY_NAMES,
+  registerLibrary,
   resolveProps,
   resolveStyle,
   canvasFor,
@@ -6089,37 +6722,32 @@ export {
   buildProgram,
   customItem,
   describeItem,
-  fontsDir,
-  packsDir,
-  packageVersion,
-  loadPack,
-  builtinPacks,
-  packsIn,
-  library,
-  findItem,
-  searchItems,
-  probeFfmpeg,
-  FfmpegMissing,
   ProgramError,
+  soundHookAvailable,
   ProgramRunner,
+  SOUND_KINDS,
+  SOUND_NOTES,
+  noteHz,
+  parseKey,
+  normalizeSoundSpec,
+  bedOf,
+  cuesFromMarks,
+  renderSound,
+  wavEncode,
+  describeCues,
   VIDEO_FORMATS,
   FORMAT_NOTES,
   openSession,
   frameDocument,
+  framePixels,
   renderStill,
   sheetTimes,
   renderSheet,
+  designSound,
+  renderSoundFile,
   formatFromPath,
   defaultOutput,
   renderVideo,
   checkItem,
-  describeReport,
-  normalizeWords,
-  readWords,
-  loadImage,
-  loadMedia,
-  readStyleArg,
-  MOTION_GUIDE,
-  LIBRARY_GUIDE,
-  AUTHORING_GUIDE
+  describeReport
 };