reframe-video 0.1.3 → 0.3.0

package/assets/sfx/LICENSE.md

@@ -5,11 +5,12 @@ Verified against each asset page's license field on 2026-06-11.
 | files | source | author | license |
 |---|---|---|---|
 | keypress-001/004/007/010/014.wav | [Keyboard Soundpack #1](https://opengameart.org/content/keyboard-soundpack-1-typing-and-single-keystrokes) (Cherry KC 1000 recordings) | unicaegames | CC0 |
-| click_002/003/004.ogg, confirmation_001.ogg | [Interface Sounds](https://opengameart.org/content/interface-sounds) | Kenney (kenney.nl) | CC0 |
+| click_001/002/003/004.ogg, confirmation_001/002/003/004.ogg, maximize_001/002/005/009.ogg, open_001.ogg, pluck_001/002.ogg, select_001/002/003.ogg, bong_001.ogg, glass_001.ogg | [Interface Sounds](https://kenney.nl/assets/interface-sounds) | Kenney (kenney.nl) | CC0 |
 | tick.wav (tick_001), pop.wav (drop_002), shimmer.wav (glass_002 + echo tail) | [Interface Sounds](https://opengameart.org/content/interface-sounds) | Kenney (kenney.nl) | CC0 |
 | whoosh.wav (wind body), rise.wav (reversed slice) | [Air whoosh](https://opengameart.org/content/air-whoosh) | qubodup | CC0 |
 | whoosh.wav (transient layer: swish-9) | [Swishes Sound Pack](https://opengameart.org/content/swishes-sound-pack) | artisticdude | CC0 |
 | thud.wav (trimmed) | [Muffled Distant Explosion](https://opengameart.org/content/muffled-distant-explosion) | NenadSimic | CC0 |
+| footstep_001/002/003.ogg (footstep00/03/06) | [RPG Audio](https://kenney.nl/assets/rpg-audio) | Kenney (kenney.nl) | CC0 |
 | bgm-song21.mp3 | [Mysterious Ambience (song21)](https://opengameart.org/content/mysterious-ambience-song21) | cynicmusic (pixelsphere.org) | multi-licensed; used under its CC0 option |
 
 CC0 requires no attribution; this file records provenance anyway.

package/dist/bin.js

@@ -42,7 +42,7 @@ function segCountOf(points, closed) {
   if (n < 2) return 0;
   return closed ? n : n - 1;
 }
-function pathPoint(points, closed, u) {
+function pathPoint(points, closed, u, curviness = 1) {
   const n = points.length;
   if (n === 0) return [0, 0];
   if (n === 1) return [points[0][0], points[0][1]];
@@ -51,19 +51,41 @@ function pathPoint(points, closed, u) {
   const [p0, p1, p2, p3] = controls(points, closed, i);
   const t2 = t * t;
   const t3 = t2 * t;
-  const f = (a, b, c, d) => 0.5 * (2 * b + (-a + c) * t + (2 * a - 5 * b + 4 * c - d) * t2 + (-a + 3 * b - 3 * c + d) * t3);
-  return [f(p0[0], p1[0], p2[0], p3[0]), f(p0[1], p1[1], p2[1], p3[1])];
-}
-function pathTangentAngle(points, closed, u) {
+  if (curviness === 1) {
+    const f = (a, b, c, d) => 0.5 * (2 * b + (-a + c) * t + (2 * a - 5 * b + 4 * c - d) * t2 + (-a + 3 * b - 3 * c + d) * t3);
+    return [f(p0[0], p1[0], p2[0], p3[0]), f(p0[1], p1[1], p2[1], p3[1])];
+  }
+  const h00 = 2 * t3 - 3 * t2 + 1;
+  const h10 = t3 - 2 * t2 + t;
+  const h01 = -2 * t3 + 3 * t2;
+  const h11 = t3 - t2;
+  const k = curviness * 0.5;
+  const H = (a, b, c, d) => h00 * b + h10 * k * (c - a) + h01 * c + h11 * k * (d - b);
+  return [H(p0[0], p1[0], p2[0], p3[0]), H(p0[1], p1[1], p2[1], p3[1])];
+}
+function pathTangentAngle(points, closed, u, curviness = 1) {
   const n = points.length;
   if (n < 2) return 0;
   const segs = segCountOf(points, closed);
   const { i, t } = locate(segs, u);
   const [p0, p1, p2, p3] = controls(points, closed, i);
   const t2 = t * t;
-  const d = (a, b, c, e) => 0.5 * (-a + c + 2 * (2 * a - 5 * b + 4 * c - e) * t + 3 * (-a + 3 * b - 3 * c + e) * t2);
-  const dx = d(p0[0], p1[0], p2[0], p3[0]);
-  const dy = d(p0[1], p1[1], p2[1], p3[1]);
+  let dx;
+  let dy;
+  if (curviness === 1) {
+    const d = (a, b, c, e) => 0.5 * (-a + c + 2 * (2 * a - 5 * b + 4 * c - e) * t + 3 * (-a + 3 * b - 3 * c + e) * t2);
+    dx = d(p0[0], p1[0], p2[0], p3[0]);
+    dy = d(p0[1], p1[1], p2[1], p3[1]);
+  } else {
+    const g00 = 6 * t2 - 6 * t;
+    const g10 = 3 * t2 - 4 * t + 1;
+    const g01 = -6 * t2 + 6 * t;
+    const g11 = 3 * t2 - 2 * t;
+    const k = curviness * 0.5;
+    const D = (a, b, c, e) => g00 * b + g10 * k * (c - a) + g01 * c + g11 * k * (e - b);
+    dx = D(p0[0], p1[0], p2[0], p3[0]);
+    dy = D(p0[1], p1[1], p2[1], p3[1]);
+  }
   if (dx === 0 && dy === 0) return 0;
   return Math.atan2(dy, dx) * 180 / Math.PI;
 }
@@ -144,8 +166,8 @@ function compileScene(ir) {
   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;
+    if (prop === "opacity" || prop === "scale" || prop === "progress" || prop === "scaleX" || prop === "scaleY") return 1;
+    if (prop === "rotation" || prop === "skewX" || prop === "skewY") return 0;
     throw new Error(`cannot animate "${prop}" of "${target}": no base value to start from`);
   };
   const labelTimes = /* @__PURE__ */ new Map();
@@ -248,16 +270,17 @@ function compileScene(ir) {
         const duration = tl.duration ?? DEFAULT_MOTIONPATH_DURATION;
         const points = tl.points;
         const closed = tl.closed ?? false;
+        const curviness = tl.curviness ?? 1;
         const autoRotate = tl.autoRotate ?? false;
         const rotateOffset = tl.rotateOffset ?? 0;
         let list = motionPaths.get(tl.target);
         if (!list) motionPaths.set(tl.target, list = []);
-        list.push({ t0: start, t1: start + duration, points, closed, autoRotate, rotateOffset, ...tl.ease !== void 0 && { ease: tl.ease } });
+        list.push({ t0: start, t1: start + duration, points, closed, curviness, autoRotate, rotateOffset, ...tl.ease !== void 0 && { ease: tl.ease } });
         if (points.length > 0) {
-          const [ex, ey] = pathPoint(points, closed, 1);
+          const [ex, ey] = pathPoint(points, closed, 1, curviness);
           current.set(key(tl.target, "x"), ex);
           current.set(key(tl.target, "y"), ey);
-          if (autoRotate) current.set(key(tl.target, "rotation"), pathTangentAngle(points, closed, 1) + rotateOffset);
+          if (autoRotate) current.set(key(tl.target, "rotation"), pathTangentAngle(points, closed, 1, curviness) + rotateOffset);
         }
         return start + duration;
       }
@@ -322,7 +345,18 @@ function validateScene(ir) {
         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);
+      if (node.type === "group") {
+        const clip = node.props.clip;
+        if (clip) {
+          if (clip.kind !== "rect" && clip.kind !== "ellipse") {
+            problems.push(`group "${node.id}" clip: unknown kind "${clip.kind}" \u2014 use "rect" or "ellipse"`);
+          }
+          if (!(clip.width > 0) || !(clip.height > 0)) {
+            problems.push(`group "${node.id}" clip: width and height must be > 0`);
+          }
+        }
+        collect(node.children);
+      }
     }
   };
   collect(ir.nodes);
@@ -405,6 +439,9 @@ function validateScene(ir) {
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path2}: motionPath "${tl.target}" duration must be > 0`);
         }
+        if (tl.curviness !== void 0 && tl.curviness < 0) {
+          problems.push(`${path2}: motionPath "${tl.target}" curviness must be >= 0`);
+        }
         break;
       }
       case "wait":
@@ -423,6 +460,13 @@ function validateScene(ir) {
         if (tl.scale !== void 0 && tl.scale <= 0) {
           problems.push(`${path2}: beat "${tl.name}" scale must be > 0`);
         }
+        for (const id of tl.nodes ?? []) {
+          if (!nodeById.has(id)) {
+            problems.push(
+              `${path2}: beat "${tl.name}" owns unknown node "${id}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          }
+        }
         tl.children.forEach((c, i) => checkTimeline(c, `${path2}.beat(${tl.name})[${i}]`));
         break;
     }
@@ -463,11 +507,40 @@ function validateScene(ir) {
   }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
-var COMMON_PROPS, PROPS_BY_TYPE, SceneValidationError;
+function validateComposition(comp) {
+  const problems = [];
+  if (comp.scenes.length === 0) problems.push("composition has no scenes");
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, entry] of comp.scenes.entries()) {
+    const where = `scenes[${i}]`;
+    try {
+      validateScene(entry.scene);
+    } catch (err) {
+      if (err instanceof SceneValidationError) {
+        for (const p of err.problems) problems.push(`${where} (scene "${entry.scene.id}"): ${p}`);
+      } else throw err;
+    }
+    if (seen.has(entry.scene.id)) {
+      problems.push(`${where}: duplicate scene id "${entry.scene.id}" \u2014 scene ids must be unique in a composition`);
+    }
+    seen.add(entry.scene.id);
+    if (entry.transition !== void 0 && !TRANSITIONS.includes(entry.transition)) {
+      problems.push(`${where}: unknown transition "${entry.transition}" \u2014 valid: ${TRANSITIONS.join(", ")}`);
+    }
+    if (typeof entry.at === "string" && Number.isNaN(Number(entry.at))) {
+      problems.push(`${where}: "at" string "${entry.at}" is not a number (use "-0.5"/"+0.5" or a number)`);
+    }
+    if (typeof entry.at === "number" && entry.at < 0) {
+      problems.push(`${where}: absolute "at" must be >= 0`);
+    }
+  }
+  if (problems.length > 0) throw new SceneValidationError(problems);
+}
+var COMMON_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
 var init_validate = __esm({
   "../core/src/validate.ts"() {
     "use strict";
-    COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "anchor"];
+    COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
     PROPS_BY_TYPE = {
       rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -486,6 +559,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
       }
       problems;
     };
+    TRANSITIONS = ["cut", "crossfade"];
   }
 });
 
@@ -543,10 +617,27 @@ var init_dsl = __esm({
   }
 });
 
+// ../core/src/composeComposition.ts
+var init_composeComposition = __esm({
+  "../core/src/composeComposition.ts"() {
+    "use strict";
+    init_compile();
+    init_ir();
+  }
+});
+
 // ../core/src/compose.ts
 function composeScene(base, ...overlays) {
   const ir = structuredClone(base);
   const report = { applied: [], orphans: [], warnings: [] };
+  const baseNodeIds = /* @__PURE__ */ new Set();
+  const collectBase = (nodes) => {
+    for (const node of nodes) {
+      baseNodeIds.add(node.id);
+      if (node.type === "group") collectBase(node.children);
+    }
+  };
+  collectBase(base.nodes);
   overlays.forEach((overlay, index) => {
     const layer = overlay.name ?? `overlay-${index}`;
     if (overlay.target !== void 0 && overlay.target !== ir.id) {
@@ -554,12 +645,12 @@ function composeScene(base, ...overlays) {
         `${layer}: authored against scene "${overlay.target}" but composing onto "${ir.id}"`
       );
     }
-    applyOverlay(ir, overlay, layer, report);
+    applyOverlay(ir, overlay, layer, report, baseNodeIds);
   });
   validateScene(ir);
   return { ir, report };
 }
-function applyOverlay(ir, overlay, layer, report) {
+function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
   const nodeById = /* @__PURE__ */ new Map();
   const collect = (nodes) => {
     for (const node of nodes) {
@@ -674,7 +765,7 @@ function applyOverlay(ir, overlay, layer, report) {
       to: ["duration", "ease", "stagger"],
       tween: ["duration", "ease"],
       wait: ["duration"],
-      motionPath: ["points", "duration", "ease"],
+      motionPath: ["points", "duration", "ease", "curviness", "autoRotate"],
       beat: ["at", "gap", "scale", "duration", "order"]
     };
     let timingPatched = false;
@@ -712,6 +803,49 @@ function applyOverlay(ir, overlay, layer, report) {
     nodeById.set(node.id, node);
     applied(`addNodes.${node.id}`, "add-node");
   }
+  for (const id of overlay.removeNodes ?? []) {
+    if (baseNodeIds.has(id)) {
+      orphan(
+        `removeNodes.${id}`,
+        `"${id}" is a base scene node \u2014 the scene owns it; hide it with opacity: 0 instead of removing`
+      );
+      continue;
+    }
+    const index = ir.nodes.findIndex((n) => n.id === id);
+    if (index < 0) {
+      orphan(
+        `removeNodes.${id}`,
+        `unknown overlay-added node "${id}" \u2014 nothing to remove`
+      );
+      continue;
+    }
+    ir.nodes.splice(index, 1);
+    nodeById.delete(id);
+    applied(`removeNodes.${id}`, "remove-node");
+  }
+  if (overlay.addTimeline && overlay.addTimeline.length > 0) {
+    const collectTargets = (tl, out) => {
+      if (tl.kind === "tween" || tl.kind === "motionPath") out.add(tl.target);
+      if ("children" in tl) tl.children.forEach((c) => collectTargets(c, out));
+    };
+    const valid = [];
+    overlay.addTimeline.forEach((frag, i) => {
+      const targets = /* @__PURE__ */ new Set();
+      collectTargets(frag, targets);
+      const missing = [...targets].filter((id) => !nodeById.has(id));
+      if (missing.length > 0) {
+        orphan(`addTimeline[${i}]`, `targets unknown node(s) ${missing.join(", ")} \u2014 known ids: ${knownIds()}`);
+        return;
+      }
+      valid.push(structuredClone(frag));
+      applied(`addTimeline[${i}]`, "add-timeline");
+    });
+    if (valid.length > 0) {
+      ir.timeline = ir.timeline ? { kind: "par", children: [ir.timeline, ...valid] } : valid.length === 1 ? valid[0] : { kind: "par", children: valid };
+      delete ir.duration;
+      ir.duration = compileScene(ir).duration;
+    }
+  }
 }
 var SCENE_PATCHABLE;
 var init_compose = __esm({
@@ -902,6 +1036,48 @@ var init_presets = __esm({
   }
 });
 
+// ../core/src/devicePreset.ts
+var init_devicePreset = __esm({
+  "../core/src/devicePreset.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
+// ../core/src/rig.ts
+var init_rig = __esm({
+  "../core/src/rig.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
+// ../core/src/characterPreset.ts
+var init_characterPreset = __esm({
+  "../core/src/characterPreset.ts"() {
+    "use strict";
+    init_dsl();
+    init_rig();
+  }
+});
+
+// ../core/src/figure.ts
+var init_figure = __esm({
+  "../core/src/figure.ts"() {
+    "use strict";
+    init_dsl();
+    init_rig();
+  }
+});
+
+// ../core/src/motionOps.ts
+var init_motionOps = __esm({
+  "../core/src/motionOps.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
 // ../core/src/audio.ts
 function resolveAudioPlan(compiled) {
   const audio = compiled.ir.audio;
@@ -938,6 +1114,15 @@ function resolveAudioPlan(compiled) {
     });
   }
   cues.sort((a, b) => a.t - b.t);
+  return {
+    duration,
+    bgm: resolveBgm(audio.bgm),
+    cues,
+    duckWindows: mergeDuckWindows(cues, duration),
+    warnings
+  };
+}
+function mergeDuckWindows(cues, duration) {
   const duckWindows = [];
   for (const cue of cues) {
     const window2 = { t0: cue.t, t1: Math.min(duration, cue.t + cue.duration) };
@@ -945,23 +1130,22 @@ function resolveAudioPlan(compiled) {
     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 };
+  return duckWindows;
+}
+function resolveBgm(b) {
+  if (!b) return null;
+  const duck = b.duck === false ? null : {
+    depth: b.duck?.depth ?? 0.5,
+    attack: b.duck?.attack ?? 0.05,
+    release: b.duck?.release ?? 0.25
+  };
+  return {
+    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
+  };
 }
 var SFX_DURATION, FILE_CUE_DURATION;
 var init_audio = __esm({
@@ -1098,10 +1282,16 @@ var init_src = __esm({
     init_ir();
     init_dsl();
     init_validate();
+    init_composeComposition();
     init_compose();
     init_compile();
     init_path();
     init_presets();
+    init_devicePreset();
+    init_rig();
+    init_characterPreset();
+    init_figure();
+    init_motionOps();
     init_audio();
     init_evaluate();
     init_interpolate();
@@ -1200,7 +1390,7 @@ function buildLogoSting(d) {
   const inks = d.paths.map(
     (p, i) => path({ id: `ink-${i}`, d: p.d, originX: vcx, originY: vcy, x: 0, y: 0, stroke: p.fill, strokeWidth: sw, progress: 0 })
   );
-  const rig = {
+  const rig2 = {
     group: "logo",
     center: [CX, CY],
     baseScale: fit,
@@ -1220,7 +1410,7 @@ function buildLogoSting(d) {
     ],
     timeline: seq(
       motionPreset(d.motion ?? "reveal-orbit", {
-        target: rig,
+        target: rig2,
         ...d.energy !== void 0 && { energy: d.energy },
         ...d.speed !== void 0 && { speed: d.speed },
         ...d.intensity !== void 0 && { intensity: d.intensity },
@@ -2042,18 +2232,16 @@ var init_batch = __esm({
 // ../render-cli/src/loadScene.ts
 var loadScene_exports = {};
 __export(loadScene_exports, {
+  isComposition: () => isComposition,
+  loadModule: () => loadModule,
   loadScene: () => loadScene
 });
 import { build as build2 } from "esbuild";
 import { readFile as readFile5 } from "node:fs/promises";
 import { dirname as dirname6, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
-async function loadScene(path2) {
-  if (path2.endsWith(".json")) {
-    const ir = JSON.parse(await readFile5(path2, "utf8"));
-    validateScene(ir);
-    return ir;
-  }
+async function loadDefault(path2) {
+  if (path2.endsWith(".json")) return JSON.parse(await readFile5(path2, "utf8"));
   let code;
   try {
     const out = await build2({
@@ -2070,15 +2258,33 @@ async function loadScene(path2) {
     });
     code = out.outputFiles[0].text;
   } catch (err) {
-    throw new Error(
-      `failed to bundle ${path2}:
-${err instanceof Error ? err.message : String(err)}`
-    );
+    throw new Error(`failed to bundle ${path2}:
+${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(`${path2} must default-export a scene`);
+  if (mod.default === void 0) throw new Error(`${path2} must default-export a scene or composition`);
   return mod.default;
 }
+function isComposition(def) {
+  return typeof def === "object" && def !== null && Array.isArray(def.scenes);
+}
+async function loadScene(path2) {
+  const def = await loadDefault(path2);
+  if (isComposition(def)) {
+    throw new Error(`${path2} is a composition \u2014 render it directly, not as a single scene`);
+  }
+  validateScene(def);
+  return def;
+}
+async function loadModule(path2) {
+  const def = await loadDefault(path2);
+  if (isComposition(def)) {
+    validateComposition(def);
+    return { kind: "composition", ir: def };
+  }
+  validateScene(def);
+  return { kind: "scene", ir: def };
+}
 var HERE, CORE_ENTRY;
 var init_loadScene = __esm({
   "../render-cli/src/loadScene.ts"() {
@@ -2101,6 +2307,7 @@ var HERE2 = dirname7(fileURLToPath5(import.meta.url));
 var ROOT2 = PACKAGED ? resolve4(HERE2, "..") : resolve4(HERE2, "..", "..", "..");
 var USER_CWD = process.env.INIT_CWD ?? process.cwd();
 var RENDER_CLI = PACKAGED ? join6(ROOT2, "dist", "cli.js") : join6(ROOT2, "packages", "render-cli", "src", "cli.ts");
+var LABELS = PACKAGED ? join6(ROOT2, "dist", "labels.js") : join6(ROOT2, "packages", "render-cli", "src", "labels.ts");
 var ANALYZE = PACKAGED ? join6(ROOT2, "dist", "analyze.js") : join6(ROOT2, "benchmark", "harness", "motion", "analyze.ts");
 var TRACE = PACKAGED ? join6(ROOT2, "dist", "trace-cli.js") : join6(ROOT2, "benchmark", "harness", "motion", "trace-cli.ts");
 var CMD = PACKAGED ? "reframe" : "pnpm reframe";
@@ -2114,6 +2321,7 @@ usage:
                                  rise-settle, slide-bank, reveal-orbit, spin-forge)
   ${CMD} preview                 open the scrub/edit UI (lists scenes in your directory)
   ${CMD} new <scene-name>        scaffold <scene-name>.ts in your directory
+  ${CMD} labels <scene.ts|.json>  print the event clock (label \u2192 exact seconds; for sound design / timing)
   ${CMD} motion <mp4|framesDir>  motion-profile a rendered clip
   ${CMD} trace <ref.mp4> [--apply scene.ts]  extract a video's motion structure \u2192 MotionSketch / timeline
   ${CMD} guide [--regen]         print the scene-authoring guide (for you or your AI)
@@ -2244,6 +2452,17 @@ ${USAGE}`);
         await (PACKAGED ? run(process.execPath, [RENDER_CLI, mode, inputPath, ...outArgs]) : run("npx", ["tsx", RENDER_CLI, mode, inputPath, ...outArgs]))
       );
     }
+    case "labels": {
+      const input = rest[0];
+      if (!input || input.startsWith("-")) fail(`labels needs a scene file
+
+${USAGE}`);
+      const inputPath = userPath(input);
+      if (!existsSync4(inputPath)) fail(`no such file: ${inputPath}`);
+      process.exit(
+        await (PACKAGED ? run(process.execPath, [LABELS, inputPath]) : run("npx", ["tsx", LABELS, inputPath]))
+      );
+    }
     case "logo": {
       const positional = [];
       const flags = {};
@@ -2332,6 +2551,9 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       process.exit(failed > 0 ? 1 : 0);
     }
     case "preview": {
+      console.log(
+        "preview: drag waypoints/nodes; double-click a path to add a waypoint or a handle to remove it;\n         \u270E reshapes an ease curve; 'vary \xD74' proposes motion variants.\ndeep-link a scene + time:  http://localhost:5173/?scene=<scene-name>&t=<seconds>"
+      );
       if (PACKAGED) {
         const { createRequire } = await import("node:module");
         const vitePkg = createRequire(import.meta.url).resolve("vite/package.json");