reframe-video 0.1.2 → 0.2.0

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])];
+  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) {
+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);
@@ -355,11 +389,11 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
-  const checkTimeline = (tl, path) => {
+  const checkTimeline = (tl, path2) => {
     if ("label" in tl && tl.label !== void 0) {
       if (labels.has(tl.label)) {
         problems.push(
-          `${path}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
+          `${path2}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
         );
       }
       labels.add(tl.label);
@@ -367,63 +401,73 @@ function validateScene(ir) {
     switch (tl.kind) {
       case "seq":
       case "par":
-        tl.children.forEach((c, i) => checkTimeline(c, `${path}.${tl.kind}[${i}]`));
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.${tl.kind}[${i}]`));
         break;
       case "stagger":
-        if (tl.interval < 0) problems.push(`${path}: stagger interval must be >= 0`);
-        tl.children.forEach((c, i) => checkTimeline(c, `${path}.stagger[${i}]`));
+        if (tl.interval < 0) problems.push(`${path2}: stagger interval must be >= 0`);
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.stagger[${i}]`));
         break;
       case "to":
         if (!(tl.state in states)) {
           problems.push(
-            `${path}: to("${tl.state}") references an undefined state \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+            `${path2}: to("${tl.state}") references an undefined state \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
           );
         }
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: to("${tl.state}") duration must be > 0`);
+          problems.push(`${path2}: to("${tl.state}") duration must be > 0`);
         }
         for (const id of tl.filter ?? []) {
-          if (!nodeById.has(id)) problems.push(`${path}: filter contains unknown node "${id}"`);
+          if (!nodeById.has(id)) problems.push(`${path2}: filter contains unknown node "${id}"`);
         }
         break;
       case "tween":
-        checkProps(path, tl.target, tl.props);
+        checkProps(path2, tl.target, tl.props);
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: tween duration must be > 0`);
+          problems.push(`${path2}: tween duration must be > 0`);
         }
         break;
       case "motionPath": {
         const node = nodeById.get(tl.target);
         if (!node) {
           problems.push(
-            `${path}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
           );
         } else if (node.type === "line") {
-          problems.push(`${path}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+          problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
         }
-        if (tl.points.length < 1) problems.push(`${path}: motionPath "${tl.target}" needs at least 1 point`);
+        if (tl.points.length < 1) problems.push(`${path2}: motionPath "${tl.target}" needs at least 1 point`);
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: motionPath "${tl.target}" duration must be > 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":
-        if (tl.duration < 0) problems.push(`${path}: wait duration must be >= 0`);
+        if (tl.duration < 0) problems.push(`${path2}: wait duration must be >= 0`);
         break;
       case "beat":
         if (labels.has(tl.name)) {
           problems.push(
-            `${path}: duplicate timeline label "${tl.name}" (beat name) \u2014 labels are overlay addresses and must be unique`
+            `${path2}: duplicate timeline label "${tl.name}" (beat name) \u2014 labels are overlay addresses and must be unique`
           );
         }
         labels.add(tl.name);
         if (tl.duration !== void 0 && tl.duration <= 0) {
-          problems.push(`${path}: beat "${tl.name}" duration must be > 0`);
+          problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
         if (tl.scale !== void 0 && tl.scale <= 0) {
-          problems.push(`${path}: beat "${tl.name}" scale must be > 0`);
+          problems.push(`${path2}: beat "${tl.name}" scale must be > 0`);
         }
-        tl.children.forEach((c, i) => checkTimeline(c, `${path}.beat(${tl.name})[${i}]`));
+        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,10 +559,56 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
       }
       problems;
     };
+    TRANSITIONS = ["cut", "crossfade"];
   }
 });
 
 // ../core/src/dsl.ts
+function scene(input) {
+  const ir = { version: 1, ...input };
+  validateScene(ir);
+  if (ir.duration === void 0 && ir.timeline) {
+    ir.duration = compileScene(ir).duration;
+  }
+  return ir;
+}
+function rect(props) {
+  const { id, ...rest } = props;
+  return { type: "rect", id, props: rest };
+}
+function text(props) {
+  const { id, ...rest } = props;
+  return { type: "text", id, props: rest };
+}
+function path(props) {
+  const { id, ...rest } = props;
+  return { type: "path", id, props: rest };
+}
+function group(props, children) {
+  const { id, ...rest } = props;
+  return { type: "group", id, props: rest, children };
+}
+function seq(...children) {
+  return { kind: "seq", children };
+}
+function par(...children) {
+  return { kind: "par", children };
+}
+function stagger(interval, ...children) {
+  return { kind: "stagger", interval, children };
+}
+function beat(name, opts, children) {
+  return { kind: "beat", name, children, ...opts };
+}
+function tween(target, props, opts = {}) {
+  return { kind: "tween", target, props, ...opts };
+}
+function wait(duration, label) {
+  return { kind: "wait", duration, ...label !== void 0 && { label } };
+}
+function motionPath(target, points, opts = {}) {
+  return { kind: "motionPath", target, points, ...opts };
+}
 var init_dsl = __esm({
   "../core/src/dsl.ts"() {
     "use strict";
@@ -498,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) {
@@ -509,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) {
@@ -629,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;
@@ -667,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({
@@ -679,12 +858,197 @@ var init_compose = __esm({
 });
 
 // ../core/src/presets.ts
-var SET;
+function makeRng(seed) {
+  let a = seed >>> 0 || 2654435769;
+  return () => {
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function ctx(o) {
+  const rand = makeRng((o.seed ?? 0) + 1);
+  return {
+    e: clamp01(o.energy ?? 0.5),
+    sp: Math.max(0.25, o.speed ?? 1),
+    it: clamp01(o.intensity ?? 0.5),
+    from: o.from,
+    rand,
+    jit: (amp) => (rand() - 0.5) * 2 * amp,
+    g: o.target.group,
+    cx: o.target.center[0],
+    cy: o.target.center[1],
+    s: o.target.baseScale,
+    fills: o.target.fills,
+    inks: o.target.inks
+  };
+}
+function settleEase(e) {
+  return e < 0.34 ? "easeOutCubic" : e < 0.67 ? "easeOutBack" : "easeOutElastic";
+}
+function fromVec(from, dist) {
+  switch (from) {
+    case "left":
+      return [-dist, 0];
+    case "right":
+      return [dist, 0];
+    case "top":
+      return [0, -dist];
+    default:
+      return [0, dist];
+  }
+}
+function fadeFills(c, base = 0.4, gap = 0.06) {
+  return stagger(
+    gap / c.sp,
+    ...c.fills.map(
+      (id, i) => tween(id, { opacity: 1 }, { duration: dur(base, c.sp), ease: "easeOutQuad", ...i === 0 && { label: "reveal" } })
+    )
+  );
+}
+function drawInks(c) {
+  return stagger(
+    0.15 / c.sp,
+    ...c.inks.map(
+      (id, i) => tween(id, { progress: 1 }, { duration: dur(1.3 + c.jit(0.2), c.sp), ease: "easeInOutQuad", ...i === 0 && { label: "draw" } })
+    )
+  );
+}
+function motionPreset(name, opts) {
+  const c = ctx(opts);
+  switch (name) {
+    case "draw-bloom":
+      return beat("draw-bloom", {}, [
+        drawInks(c),
+        fadeFills(c, 0.45),
+        tween(c.g, { scale: c.s * (1.02 + 0.05 * c.e) }, { duration: dur(2.4, c.sp), ease: "easeInOutQuad", label: "settle" })
+      ]);
+    case "punch-in": {
+      const peak = c.s * (1 + 0.06 + 0.24 * c.e + c.jit(0.02));
+      return beat("punch-in", {}, [
+        par(
+          fadeFills(c, 0.25),
+          seq(
+            tween(c.g, { scale: peak }, { duration: dur(0.45 + c.jit(0.05), c.sp), ease: "easeOutCubic", label: "punch" }),
+            tween(c.g, { scale: c.s }, { duration: dur(0.5, c.sp), ease: settleEase(c.e) })
+          )
+        )
+      ]);
+    }
+    case "rise-settle": {
+      const es = 0.65 + c.rand() * 0.7;
+      const dist = (220 + 260 * c.it) * es;
+      const [dx, dy] = fromVec(c.from ?? "bottom", dist);
+      const jx = c.jit(110);
+      return beat("rise-settle", {}, [
+        par(
+          motionPath(
+            c.g,
+            [
+              [c.cx + dx + jx, c.cy + dy],
+              [c.cx + dx * 0.4 - jx * 0.6, c.cy + dy * 0.4],
+              [c.cx, c.cy]
+            ],
+            { duration: dur(1.1, c.sp), ease: settleEase(c.e), label: "rise" }
+          ),
+          fadeFills(c, 0.4)
+        )
+      ]);
+    }
+    case "slide-bank": {
+      const es = 0.65 + c.rand() * 0.7;
+      const dist = (420 + 240 * c.it) * es;
+      const [dx, dy] = fromVec(c.from ?? "left", dist);
+      const arc = c.jit(140);
+      const midx = c.jit(120);
+      const move = dur(1.2, c.sp);
+      return beat("slide-bank", {}, [
+        par(
+          motionPath(
+            c.g,
+            [
+              [c.cx + dx, c.cy + dy],
+              [c.cx + dx * 0.4 + midx, c.cy + dy * 0.4 - 70 - arc],
+              [c.cx, c.cy]
+            ],
+            { duration: move, ease: settleEase(c.e), autoRotate: true, label: "slide" }
+          ),
+          // level the bank out once it lands (authored after the path → wins for rotation)
+          seq(wait(move), tween(c.g, { rotation: 0 }, { duration: dur(0.5, c.sp), ease: "easeOutCubic" })),
+          fadeFills(c, 0.4)
+        )
+      ]);
+    }
+    case "reveal-orbit": {
+      const es = 0.65 + c.rand() * 0.7;
+      const orbit = (180 + 160 * c.it) * es;
+      const jx = c.jit(0.4);
+      const jy = c.jit(0.4);
+      return beat("reveal-orbit", {}, [
+        drawInks(c),
+        fadeFills(c, 0.45),
+        par(
+          motionPath(
+            c.g,
+            [
+              [c.cx, c.cy],
+              [c.cx - orbit * (1 + jx), c.cy - orbit * 0.8],
+              [c.cx + orbit * (1 + jy), c.cy - orbit],
+              [c.cx, c.cy]
+            ],
+            { duration: dur(1.7, c.sp), ease: "easeInOutCubic", label: "orbit" }
+          ),
+          seq(
+            tween(c.g, { scale: c.s * (1.12 + 0.1 * c.e) }, { duration: dur(0.85, c.sp), ease: "easeOutBack" }),
+            tween(c.g, { scale: c.s }, { duration: dur(0.85, c.sp), ease: "easeInOutQuad" })
+          )
+        )
+      ]);
+    }
+    case "spin-forge": {
+      const turns = 1 + Math.round(c.it);
+      const dir = c.rand() < 0.5 ? -1 : 1;
+      const startRot = dir * 360 * turns;
+      const peak = c.s * (1 + 0.05 + 0.2 * c.e);
+      return beat("spin-forge", {}, [
+        par(
+          seq(
+            tween(c.g, { scale: c.s * 0.2, rotation: startRot }, { duration: SET }),
+            // establish (invisible)
+            tween(c.g, { scale: peak, rotation: 0 }, { duration: dur(0.9, c.sp), ease: "easeOutBack", label: "spin" }),
+            tween(c.g, { scale: c.s }, { duration: dur(0.3, c.sp), ease: "easeInOutQuad" })
+          ),
+          seq(wait(SET), fadeFills(c, 0.3))
+        )
+      ]);
+    }
+  }
+}
+var clamp01, SET, dur;
 var init_presets = __esm({
   "../core/src/presets.ts"() {
     "use strict";
     init_dsl();
+    clamp01 = (x) => Math.max(0, Math.min(1, x));
     SET = 1 / 120;
+    dur = (base, sp) => base / sp;
+  }
+});
+
+// ../core/src/devicePreset.ts
+var init_devicePreset = __esm({
+  "../core/src/devicePreset.ts"() {
+    "use strict";
+    init_dsl();
+  }
+});
+
+// ../core/src/motionOps.ts
+var init_motionOps = __esm({
+  "../core/src/motionOps.ts"() {
+    "use strict";
+    init_dsl();
   }
 });
 
@@ -724,6 +1088,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) };
@@ -731,23 +1104,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({
@@ -884,10 +1256,13 @@ var init_src = __esm({
     init_ir();
     init_dsl();
     init_validate();
+    init_composeComposition();
     init_compose();
     init_compile();
     init_path();
     init_presets();
+    init_devicePreset();
+    init_motionOps();
     init_audio();
     init_evaluate();
     init_interpolate();
@@ -897,6 +1272,152 @@ var init_src = __esm({
   }
 });
 
+// ../render-cli/src/logoSting.ts
+var logoSting_exports = {};
+__export(logoSting_exports, {
+  LOGO_PRESETS: () => LOGO_PRESETS,
+  buildLogoSting: () => buildLogoSting,
+  resolveLogo: () => resolveLogo
+});
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+async function loadSvg(arg) {
+  if (existsSync(arg)) {
+    return { svg: await readFile(arg, "utf8"), name: arg.split("/").pop().replace(/\.svg$/i, "") };
+  }
+  const slug = arg.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const r = await fetch(`https://cdn.simpleicons.org/${slug}`);
+  if (!r.ok) throw new Error(`no local file "${arg}", and simple-icons has no "${slug}" (${r.status})`);
+  return { svg: await r.text(), name: arg };
+}
+function tooDark(hex) {
+  const h = hex.replace("#", "");
+  const n = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
+  const r = parseInt(n.slice(0, 2), 16);
+  const g = parseInt(n.slice(2, 4), 16);
+  const b = parseInt(n.slice(4, 6), 16);
+  return 0.299 * r + 0.587 * g + 0.114 * b < 40;
+}
+function parseSvg(svg) {
+  let viewBox = { minX: 0, minY: 0, w: 100, h: 100 };
+  const vb = svg.match(/viewBox\s*=\s*"([\d.\-\s]+)"/i);
+  if (vb) {
+    const [a, b, c, d] = vb[1].trim().split(/\s+/).map(Number);
+    viewBox = { minX: a, minY: b, w: c, h: d };
+  } else {
+    const w = svg.match(/\bwidth\s*=\s*"([\d.]+)/i);
+    const h = svg.match(/\bheight\s*=\s*"([\d.]+)/i);
+    if (w && h) viewBox = { minX: 0, minY: 0, w: +w[1], h: +h[1] };
+  }
+  const rootFill = svg.match(/<svg[^>]*\bfill\s*=\s*"(#[0-9a-fA-F]{3,8})"/)?.[1];
+  const fallback = rootFill && !tooDark(rootFill) ? rootFill : "#E6EDF3";
+  const paths = [];
+  const re = /<path\b[^>]*>/g;
+  let m;
+  while (m = re.exec(svg)) {
+    const tag = m[0];
+    const d = tag.match(/\bd\s*=\s*"([^"]+)"/)?.[1];
+    if (!d) continue;
+    let fill = tag.match(/\bfill\s*=\s*"(#[0-9a-fA-F]{3,8})"/)?.[1] ?? fallback;
+    if (tooDark(fill)) fill = fallback;
+    paths.push({ d, fill });
+  }
+  return { paths, viewBox };
+}
+async function resolveLogo(arg, displayName, opts) {
+  if (opts.motion && !LOGO_PRESETS.includes(opts.motion)) {
+    throw new Error(`unknown --motion "${opts.motion}". options: ${LOGO_PRESETS.join(", ")}`);
+  }
+  const { svg, name } = await loadSvg(arg);
+  const { paths, viewBox } = parseSvg(svg);
+  if (paths.length === 0) throw new Error("no <path> elements found \u2014 logo stings need a path-based SVG");
+  const from = FROMS.includes(opts.from) ? opts.from : void 0;
+  const data = {
+    name: displayName ?? titleCase(name),
+    paths,
+    viewBox,
+    ...opts.motion && { motion: opts.motion },
+    ...opts.energy !== void 0 && { energy: opts.energy },
+    ...opts.speed !== void 0 && { speed: opts.speed },
+    ...opts.intensity !== void 0 && { intensity: opts.intensity },
+    ...from && { from },
+    ...opts.seed !== void 0 && { seed: opts.seed }
+  };
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "logo";
+  return { data, slug };
+}
+function buildLogoSting(d) {
+  const W = 1080;
+  const H = 1080;
+  const CX = 540;
+  const CY = 500;
+  const vcx = d.viewBox.minX + d.viewBox.w / 2;
+  const vcy = d.viewBox.minY + d.viewBox.h / 2;
+  const fit = LOGO_PX / Math.max(d.viewBox.w, d.viewBox.h);
+  const sw = 2.2 / fit;
+  const fills = d.paths.map(
+    (p, i) => path({ id: `fill-${i}`, d: p.d, originX: vcx, originY: vcy, x: 0, y: 0, fill: p.fill, opacity: 0 })
+  );
+  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 = {
+    group: "logo",
+    center: [CX, CY],
+    baseScale: fit,
+    fills: fills.map((n) => n.id),
+    inks: inks.map((n) => n.id)
+  };
+  return scene({
+    id: "logo-sting",
+    size: { width: W, height: H },
+    fps: 30,
+    background: BG,
+    nodes: [
+      rect({ id: "bg", x: 0, y: 0, width: W, height: H, fill: BG }),
+      group({ id: "logo", x: CX, y: CY, scale: fit }, [...fills, ...inks]),
+      text({ id: "word", x: CX, y: 905, anchor: "center", content: d.name, fontFamily: "Inter", fontSize: 56, fontWeight: 800, fill: FG, opacity: 0 }),
+      text({ id: "made", x: CX, y: 968, anchor: "center", content: "made with reframe", fontFamily: "Inter", fontSize: 20, fill: MUTED, opacity: 0 })
+    ],
+    timeline: seq(
+      motionPreset(d.motion ?? "reveal-orbit", {
+        target: rig,
+        ...d.energy !== void 0 && { energy: d.energy },
+        ...d.speed !== void 0 && { speed: d.speed },
+        ...d.intensity !== void 0 && { intensity: d.intensity },
+        ...d.from !== void 0 && { from: d.from },
+        ...d.seed !== void 0 && { seed: d.seed }
+      }),
+      par(
+        tween("word", { opacity: 1 }, { duration: 0.5, ease: "easeOutQuad", label: "word" }),
+        seq(wait(0.2), tween("made", { opacity: 1 }, { duration: 0.5, ease: "easeOutQuad" }))
+      ),
+      wait(0.8, "hold")
+    )
+  });
+}
+var LOGO_PRESETS, titleCase, FROMS, BG, FG, MUTED, LOGO_PX;
+var init_logoSting = __esm({
+  "../render-cli/src/logoSting.ts"() {
+    "use strict";
+    init_src();
+    LOGO_PRESETS = [
+      "draw-bloom",
+      "punch-in",
+      "rise-settle",
+      "slide-bank",
+      "reveal-orbit",
+      "spin-forge"
+    ];
+    titleCase = (s) => s.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+    FROMS = ["left", "right", "top", "bottom"];
+    BG = "#0D1117";
+    FG = "#E6EDF3";
+    MUTED = "#8B949E";
+    LOGO_PX = 520;
+  }
+});
+
 // ../render-cli/src/audio/wav.ts
 function encodeWavMono16(samples, sampleRate = SAMPLE_RATE) {
   const dataBytes = samples.length * 2;
@@ -941,52 +1462,52 @@ function buffer(duration) {
   return { out: new Float32Array(n), n };
 }
 function whoosh(seed) {
-  const dur = 0.35;
-  const { out, n } = buffer(dur);
+  const dur2 = 0.35;
+  const { out, n } = buffer(dur2);
   let lp = 0;
   let lp2 = 0;
   for (let i = 0; i < n; i++) {
     const t = i / SAMPLE_RATE;
-    const u = t / dur;
+    const u = t / dur2;
     const center = 1200 * Math.pow(300 / 1200, u);
     const alpha = Math.min(1, TAU * center / SAMPLE_RATE);
     lp += alpha * (noise(i, seed) - lp);
     lp2 += alpha * 0.5 * (lp - lp2);
-    const env = u < 0.3 ? u / 0.3 : expDecay(t - 0.3 * dur, dur * 0.7, 4);
+    const env = u < 0.3 ? u / 0.3 : expDecay(t - 0.3 * dur2, dur2 * 0.7, 4);
     out[i] = (lp - lp2) * env * 2.2;
   }
   return out;
 }
 function pop(seed) {
-  const dur = 0.12;
-  const { out, n } = buffer(dur);
+  const dur2 = 0.12;
+  const { out, n } = buffer(dur2);
   let phase = 0;
   for (let i = 0; i < n; i++) {
     const t = i / SAMPLE_RATE;
     const freq = 600 * Math.pow(150 / 600, t / 0.08);
     phase += TAU * freq / SAMPLE_RATE;
     const transient = t < 2e-3 ? noise(i, seed) * 0.5 : 0;
-    out[i] = (Math.sin(phase) + transient) * expDecay(t, dur, 6) * 0.8;
+    out[i] = (Math.sin(phase) + transient) * expDecay(t, dur2, 6) * 0.8;
   }
   return out;
 }
 function tick(seed) {
-  const dur = 0.03;
-  const { out, n } = buffer(dur);
+  const dur2 = 0.03;
+  const { out, n } = buffer(dur2);
   for (let i = 0; i < n; i++) {
     const t = i / SAMPLE_RATE;
     const sine = t < 4e-3 ? Math.sin(TAU * 4e3 * t) : 0;
-    out[i] = (sine * 0.6 + noise(i, seed) * 0.35) * expDecay(t, dur, 8);
+    out[i] = (sine * 0.6 + noise(i, seed) * 0.35) * expDecay(t, dur2, 8);
   }
   return out;
 }
 function rise(seed) {
-  const dur = 0.5;
-  const { out, n } = buffer(dur);
+  const dur2 = 0.5;
+  const { out, n } = buffer(dur2);
   let phase = 0;
   for (let i = 0; i < n; i++) {
     const t = i / SAMPLE_RATE;
-    const u = t / dur;
+    const u = t / dur2;
     const freq = 220 * Math.pow(880 / 220, u);
     phase += TAU * freq / SAMPLE_RATE;
     const env = Math.sin(Math.PI * Math.min(1, u * 1.05)) ** 1.5;
@@ -995,8 +1516,8 @@ function rise(seed) {
   return out;
 }
 function shimmer(seed) {
-  const dur = 0.9;
-  const { out, n } = buffer(dur);
+  const dur2 = 0.9;
+  const { out, n } = buffer(dur2);
   const partials = Array.from({ length: 5 }, (_, p) => ({
     freq: 2e3 + hash01(p, seed + 7) * 2e3,
     am: 0.5 + hash01(p, seed + 8) * 1.5,
@@ -1004,7 +1525,7 @@ function shimmer(seed) {
   }));
   for (let i = 0; i < n; i++) {
     const t = i / SAMPLE_RATE;
-    const u = t / dur;
+    const u = t / dur2;
     const env = Math.sin(Math.PI * u) ** 1.2;
     let s = 0;
     for (const part of partials) {
@@ -1015,8 +1536,8 @@ function shimmer(seed) {
   return out;
 }
 function thud(seed) {
-  const dur = 0.25;
-  const { out, n } = buffer(dur);
+  const dur2 = 0.25;
+  const { out, n } = buffer(dur2);
   let phase = 0;
   let lp = 0;
   for (let i = 0; i < n; i++) {
@@ -1025,7 +1546,7 @@ function thud(seed) {
     phase += TAU * freq / SAMPLE_RATE;
     lp += 0.02 * (noise(i, seed) - lp);
     const attack = t < 0.01 ? lp * 3 : 0;
-    out[i] = (Math.sin(phase) * 0.9 + attack) * expDecay(t, dur, 5);
+    out[i] = (Math.sin(phase) * 0.9 + attack) * expDecay(t, dur2, 5);
   }
   return out;
 }
@@ -1060,7 +1581,7 @@ var init_synth = __esm({
     init_wav();
     noise = (n, seed) => hash01(n, seed) * 2 - 1;
     TAU = Math.PI * 2;
-    expDecay = (t, dur, k = 5) => Math.exp(-k * t / dur);
+    expDecay = (t, dur2, k = 5) => Math.exp(-k * t / dur2);
     RECIPES = {
       whoosh,
       pop,
@@ -1074,26 +1595,26 @@ var init_synth = __esm({
 
 // ../render-cli/src/audio/sfx.ts
 import { mkdir, rename, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync as existsSync2 } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-function fnv1a(text) {
+function fnv1a(text2) {
   let h = 2166136261;
-  for (let i = 0; i < text.length; i++) {
-    h ^= text.charCodeAt(i);
+  for (let i = 0; i < text2.length; i++) {
+    h ^= text2.charCodeAt(i);
     h = Math.imul(h, 16777619);
   }
   return (h >>> 0).toString(16);
 }
 async function writeCached(key2, make) {
-  const path = join(CACHE, `${key2}.wav`);
-  if (existsSync(path)) return path;
+  const path2 = join(CACHE, `${key2}.wav`);
+  if (existsSync2(path2)) return path2;
   await mkdir(CACHE, { recursive: true });
-  const temp = `${path}.${process.pid}.${fnv1a(String(performance.now()))}.tmp`;
+  const temp = `${path2}.${process.pid}.${fnv1a(String(performance.now()))}.tmp`;
   await writeFile(temp, encodeWavMono16(make()));
-  await rename(temp, path);
-  return path;
+  await rename(temp, path2);
+  return path2;
 }
 async function resolveCueFile(cue, sceneDir) {
   if (cue.source.kind === "file") {
@@ -1103,14 +1624,14 @@ async function resolveCueFile(cue, sceneDir) {
       resolve(sceneDir, p),
       join(VENDORED, p)
     ]) {
-      if (candidate && existsSync(candidate)) return candidate;
+      if (candidate && existsSync2(candidate)) return candidate;
     }
     throw new Error(
       `audio cue file "${p}" not found (tried absolute, scene-relative, assets/sfx/)`
     );
   }
   const vendored = join(VENDORED, `${cue.source.name}.wav`);
-  if (existsSync(vendored)) return vendored;
+  if (existsSync2(vendored)) return vendored;
   const { name, params } = cue.source;
   return writeCached(`${name}-${fnv1a(JSON.stringify(params))}`, () => synthSfx(name, params));
 }
@@ -1118,7 +1639,7 @@ async function resolveBgmFile(source, duration, sceneDir) {
   if (source.kind === "file") {
     const p = source.path;
     for (const candidate of [isAbsolute(p) ? p : null, resolve(sceneDir, p), join(VENDORED, p)]) {
-      if (candidate && existsSync(candidate)) return candidate;
+      if (candidate && existsSync2(candidate)) return candidate;
     }
     throw new Error(`bgm file "${p}" not found`);
   }
@@ -1288,14 +1809,14 @@ var init_encode = __esm({
 });
 
 // ../render-cli/src/fonts.ts
-import { readFile } from "node:fs/promises";
+import { readFile as readFile2 } from "node:fs/promises";
 import { dirname as dirname3, join as join3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 async function fontFaceCss() {
   if (cssCache) return cssCache;
   const rules = await Promise.all(
     WEIGHTS.map(async (weight) => {
-      const data = await readFile(join3(FONTS_DIR, `inter-${weight}.woff2`));
+      const data = await readFile2(join3(FONTS_DIR, `inter-${weight}.woff2`));
       return `@font-face {
   font-family: "Inter";
   font-style: normal;
@@ -1318,8 +1839,8 @@ var init_fonts = __esm({
 });
 
 // ../render-cli/src/images.ts
-import { readFile as readFile2 } from "node:fs/promises";
-import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile3 } from "node:fs/promises";
+import { existsSync as existsSync3 } from "node:fs";
 import { extname, isAbsolute as isAbsolute2, resolve as resolve2 } from "node:path";
 async function buildImageAssets(ir, sceneDir) {
   const assets = {};
@@ -1333,11 +1854,11 @@ async function buildImageAssets(ir, sceneDir) {
     const candidates = [isAbsolute2(src) ? src : null, resolve2(sceneDir, src)].filter(
       (c) => c !== null
     );
-    const found = candidates.find((c) => existsSync2(c));
+    const found = candidates.find((c) => existsSync3(c));
     if (!found) {
       throw new Error(`image "${src}" not found (tried: ${candidates.join(", ")})`);
     }
-    const data = await readFile2(found);
+    const data = await readFile3(found);
     assets[src] = `data:${mime};base64,${data.toString("base64")}`;
   }
   return assets;
@@ -1461,8 +1982,8 @@ async function withPage(size, fn) {
 async function browserBundle() {
   if (bundleCache) return bundleCache;
   if (true) {
-    const { readFile: readFile5 } = await import("node:fs/promises");
-    bundleCache = await readFile5(
+    const { readFile: readFile6 } = await import("node:fs/promises");
+    bundleCache = await readFile6(
       join4(dirname4(fileURLToPath3(import.meta.url)), "browserEntry.js"),
       "utf8"
     );
@@ -1524,7 +2045,7 @@ __export(batch_exports, {
   parseCsv: () => parseCsv,
   runBatch: () => runBatch
 });
-import { mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile3, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdir as mkdir3, mkdtemp as mkdtemp2, readFile as readFile4, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join5, dirname as dirname5 } from "node:path";
 function overlayFromFlat(row, name) {
@@ -1563,8 +2084,8 @@ function overlayFromFlat(row, name) {
   }
   return doc;
 }
-function parseCsv(text) {
-  const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+function parseCsv(text2) {
+  const lines = text2.split(/\r?\n/).filter((l) => l.trim().length > 0);
   if (lines.length < 2) return [];
   const split = (line) => {
     const out = [];
@@ -1599,14 +2120,14 @@ function parseCsv(text) {
     return row;
   });
 }
-async function loadRows(path) {
-  const text = await readFile3(path, "utf8");
-  if (path.endsWith(".csv")) return parseCsv(text);
-  const parsed = JSON.parse(text);
-  if (!Array.isArray(parsed)) throw new Error(`${path}: expected a JSON array of row objects`);
+async function loadRows(path2) {
+  const text2 = await readFile4(path2, "utf8");
+  if (path2.endsWith(".csv")) return parseCsv(text2);
+  const parsed = JSON.parse(text2);
+  if (!Array.isArray(parsed)) throw new Error(`${path2}: expected a JSON array of row objects`);
   return parsed;
 }
-async function runBatch(scene, rows, opts) {
+async function runBatch(scene2, rows, opts) {
   await mkdir3(opts.outDir, { recursive: true });
   const results = new Array(rows.length);
   let next = 0;
@@ -1619,7 +2140,7 @@ async function runBatch(scene, rows, opts) {
       let result;
       try {
         const rowOverlay = overlayFromFlat(row, name);
-        const { ir, report } = composeScene(scene, ...opts.baseOverlays, rowOverlay);
+        const { ir, report } = composeScene(scene2, ...opts.baseOverlays, rowOverlay);
         const framesDir = await mkdtemp2(join5(tmpdir3(), `reframe-batch-${index}-`));
         const output = join5(opts.outDir, `${name}.mp4`);
         const plan = opts.noAudio ? null : resolveAudioPlan(compileScene(ir));
@@ -1682,22 +2203,20 @@ 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 readFile4 } from "node:fs/promises";
+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(path) {
-  if (path.endsWith(".json")) {
-    const ir = JSON.parse(await readFile4(path, "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({
-      entryPoints: [path],
+      entryPoints: [path2],
       bundle: true,
       format: "esm",
       platform: "neutral",
@@ -1710,15 +2229,33 @@ async function loadScene(path) {
     });
     code = out.outputFiles[0].text;
   } catch (err) {
-    throw new Error(
-      `failed to bundle ${path}:
-${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(`${path} 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"() {
@@ -1731,7 +2268,7 @@ var init_loadScene = __esm({
 
 // ../render-cli/src/reframe.ts
 import { spawn as spawn3, spawnSync } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 import { mkdir as mkdir4, writeFile as writeFile5 } from "node:fs/promises";
 import { basename, isAbsolute as isAbsolute3, join as join6, resolve as resolve4 } from "node:path";
 import { dirname as dirname7 } from "node:path";
@@ -1741,6 +2278,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";
@@ -1749,8 +2287,12 @@ var USAGE = `reframe \u2014 declarative motion graphics
 usage:
   ${CMD} render <scene.ts|.json|.html> [--overlay edits.json]... [-o out.mp4] [--fps N] [--duration S] [--no-audio]
   ${CMD} batch <scene.ts> <data.json|csv> [-o outDir] [--overlay base.json]... [--concurrency N] [--fps N]
+  ${CMD} logo <logo.svg|brand-slug> ["Name"] [--motion <preset>] [--energy 0..1] [--seed N] [-o out.mp4]
+                                 animate a logo into a sting (presets: draw-bloom, punch-in,
+                                 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)
@@ -1775,9 +2317,9 @@ function run(cmd, args, opts = {}) {
     });
     let sawBrowserError = false;
     proc.stderr.on("data", (d) => {
-      const text = d.toString();
-      if (/Executable doesn't exist|browserType\.launch/.test(text)) sawBrowserError = true;
-      process.stderr.write(text);
+      const text2 = d.toString();
+      if (/Executable doesn't exist|browserType\.launch/.test(text2)) sawBrowserError = true;
+      process.stderr.write(text2);
     });
     proc.on("close", (code) => {
       if (code !== 0 && sawBrowserError) {
@@ -1858,7 +2400,7 @@ async function main() {
 
 ${USAGE}`);
       const inputPath = userPath(input);
-      if (!existsSync3(inputPath)) fail(`no such file: ${inputPath}`);
+      if (!existsSync4(inputPath)) fail(`no such file: ${inputPath}`);
       const mode = /\.(ts|json)$/.test(input) ? "ir" : /\.html$/.test(input) ? "html" : null;
       if (!mode) {
         fail(`cannot infer render mode from "${input}" \u2014 expected .ts/.json (reframe scene) or .html (GSAP page)`);
@@ -1881,12 +2423,60 @@ ${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 = {};
+      for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a.startsWith("--")) flags[a.slice(2)] = rest[++i] ?? "";
+        else if (a === "-o") flags.o = rest[++i] ?? "";
+        else positional.push(a);
+      }
+      const arg = positional[0];
+      if (!arg) {
+        fail(`usage: ${CMD} logo <logo.svg | brand-slug> ["Display Name"] [--motion <preset>] [--energy 0..1] [--speed n] [--intensity 0..1] [--from left|right|top|bottom] [--seed n] [-o out.mp4]`);
+      }
+      preflightFfmpeg();
+      const { tmpdir: tmpdir4 } = await import("node:os");
+      const { resolveLogo: resolveLogo2, buildLogoSting: buildLogoSting2 } = await Promise.resolve().then(() => (init_logoSting(), logoSting_exports));
+      const num = (k) => flags[k] !== void 0 ? Number(flags[k]) : void 0;
+      console.log(`loading logo: ${arg} \u2026`);
+      const { data, slug } = await resolveLogo2(arg, positional[1], {
+        motion: flags.motion,
+        energy: num("energy"),
+        speed: num("speed"),
+        intensity: num("intensity"),
+        from: flags.from,
+        seed: num("seed")
+      });
+      const sceneIR = buildLogoSting2(data);
+      const tmp = join6(tmpdir4(), `reframe-logo-${slug}-${process.pid}.json`);
+      await writeFile5(tmp, JSON.stringify(sceneIR));
+      const outBase = PACKAGED ? join6(USER_CWD, "out") : join6(ROOT2, "out");
+      const out = flags.o ? userPath(flags.o) : join6(outBase, `logo-${slug}.mp4`);
+      await mkdir4(dirname7(out), { recursive: true });
+      console.log(`rendering ${data.name} (${data.paths.length} path${data.paths.length > 1 ? "s" : ""}, motion: ${data.motion ?? "reveal-orbit"}) \u2192 ${out}`);
+      process.exit(
+        await (PACKAGED ? run(process.execPath, [RENDER_CLI, "ir", tmp, "-o", out, "--no-audio"]) : run("npx", ["tsx", RENDER_CLI, "ir", tmp, "-o", out, "--no-audio"]))
+      );
+    }
     case "batch": {
       const [sceneArg, dataArg, ...flags] = rest;
       if (!sceneArg || !dataArg) fail(`usage: ${CMD} batch <scene.ts> <data.json|csv> [...]`);
       const scenePath = userPath(sceneArg);
       const dataPath = userPath(dataArg);
-      for (const p of [scenePath, dataPath]) if (!existsSync3(p)) fail(`no such file: ${p}`);
+      for (const p of [scenePath, dataPath]) if (!existsSync4(p)) fail(`no such file: ${p}`);
       preflightFfmpeg();
       let outDir = PACKAGED ? join6(USER_CWD, "out", "batch") : join6(ROOT2, "out", "batch");
       let concurrency = 3;
@@ -1901,15 +2491,15 @@ ${USAGE}`);
       }
       const { loadRows: loadRows2, runBatch: runBatch2 } = await Promise.resolve().then(() => (init_batch(), batch_exports));
       const { loadScene: loadScene2 } = await Promise.resolve().then(() => (init_loadScene(), loadScene_exports));
-      const { readFile: readFile5 } = await import("node:fs/promises");
-      const scene = await loadScene2(scenePath);
+      const { readFile: readFile6 } = await import("node:fs/promises");
+      const scene2 = await loadScene2(scenePath);
       const baseOverlays = await Promise.all(
-        baseOverlayPaths.map(async (p) => JSON.parse(await readFile5(p, "utf8")))
+        baseOverlayPaths.map(async (p) => JSON.parse(await readFile6(p, "utf8")))
       );
       const rows = await loadRows2(dataPath);
       if (rows.length === 0) fail(`${dataPath}: no data rows`);
       console.log(`batch: ${rows.length} rows \xD7 ${concurrency} workers \u2192 ${outDir}`);
-      const results = await runBatch2(scene, rows, {
+      const results = await runBatch2(scene2, rows, {
         outDir,
         baseOverlays,
         concurrency,
@@ -1932,6 +2522,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");
@@ -1958,7 +2551,7 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
       const targetDir = inRepo ? join6(ROOT2, "examples", "scenes") : USER_CWD;
       const target = join6(targetDir, `${name}.ts`);
       const shown = inRepo ? `examples/scenes/${name}.ts` : `${name}.ts`;
-      if (existsSync3(target)) fail(`${shown} already exists`);
+      if (existsSync4(target)) fail(`${shown} already exists`);
       const id = name.split("-")[0] ?? name;
       await writeFile5(target, SCENE_TEMPLATE(name, id));
       console.log(`created ${shown}
@@ -1988,8 +2581,8 @@ ${results.length - failed} rendered (${orphaned} with orphans), ${failed} failed
     }
     case "guide": {
       const file = rest.includes("--regen") ? PACKAGED ? join6(ROOT2, "guides", "regen-contract.md") : join6(ROOT2, "docs", "regen-contract.md") : PACKAGED ? join6(ROOT2, "guides", "edsl-guide.md") : join6(ROOT2, "benchmark", "guides", "edsl-guide.md");
-      const { readFile: readFile5 } = await import("node:fs/promises");
-      process.stdout.write(await readFile5(file, "utf8"));
+      const { readFile: readFile6 } = await import("node:fs/promises");
+      process.stdout.write(await readFile6(file, "utf8"));
       return;
     }
     case "demo":