reframe-video 0.1.2 → 0.2.0

package/dist/labels.js

@@ -0,0 +1,606 @@
+#!/usr/bin/env tsx
+
+// ../core/src/ir.ts
+var DEFAULT_TO_DURATION = 0.5;
+var DEFAULT_TWEEN_DURATION = 0.5;
+var DEFAULT_MOTIONPATH_DURATION = 1;
+
+// ../core/src/path.ts
+function locate(segCount, u) {
+  if (segCount <= 0) return { i: 0, t: 0 };
+  const clamped = Math.max(0, Math.min(1, u));
+  const scaled = clamped * segCount;
+  let i = Math.floor(scaled);
+  if (i >= segCount) i = segCount - 1;
+  return { i, t: scaled - i };
+}
+function controls(points, closed, i) {
+  const n = points.length;
+  const at = (k) => {
+    if (closed) return points[(k % n + n) % n];
+    return points[Math.max(0, Math.min(n - 1, k))];
+  };
+  return [at(i - 1), at(i), at(i + 1), at(i + 2)];
+}
+function segCountOf(points, closed) {
+  const n = points.length;
+  if (n < 2) return 0;
+  return closed ? n : n - 1;
+}
+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]];
+  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 t3 = t2 * t;
+  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;
+  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;
+}
+
+// ../core/src/compile.ts
+var key = (target, prop) => `${target}.${prop}`;
+function scaleTimeline(tl, k) {
+  switch (tl.kind) {
+    case "seq":
+    case "par":
+      return { ...tl, children: tl.children.map((c) => scaleTimeline(c, k)) };
+    case "stagger":
+      return { ...tl, interval: tl.interval * k, children: tl.children.map((c) => scaleTimeline(c, k)) };
+    case "wait":
+      return { ...tl, duration: tl.duration * k };
+    case "tween":
+      return { ...tl, duration: (tl.duration ?? DEFAULT_TWEEN_DURATION) * k };
+    case "motionPath":
+      return { ...tl, duration: (tl.duration ?? DEFAULT_MOTIONPATH_DURATION) * k };
+    case "to":
+      return {
+        ...tl,
+        duration: (tl.duration ?? DEFAULT_TO_DURATION) * k,
+        ...tl.stagger !== void 0 && { stagger: tl.stagger * k }
+      };
+    case "beat":
+      return {
+        ...tl,
+        children: tl.children.map((c) => scaleTimeline(c, k)),
+        ...tl.gap !== void 0 && { gap: tl.gap * k }
+      };
+  }
+}
+function orderBeats(children) {
+  return children.map((c, i) => ({ c, i, key: c.kind === "beat" && c.order !== void 0 ? c.order : i })).sort((a, b) => a.key - b.key || a.i - b.i).map((x) => x.c);
+}
+function compileScene(ir) {
+  const nodeById = /* @__PURE__ */ new Map();
+  const nodeOrder = [];
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      nodeById.set(node.id, node);
+      nodeOrder.push(node.id);
+      if (node.type === "group") collect(node.children);
+    }
+  };
+  collect(ir.nodes);
+  const initialValues = /* @__PURE__ */ new Map();
+  for (const [id, node] of nodeById) {
+    for (const [prop, value] of Object.entries(node.props)) {
+      if (typeof value === "number" || typeof value === "string") {
+        initialValues.set(key(id, prop), value);
+      }
+    }
+  }
+  if (ir.initial !== void 0) {
+    const override = ir.states?.[ir.initial] ?? {};
+    for (const [id, props] of Object.entries(override)) {
+      for (const [prop, value] of Object.entries(props)) {
+        initialValues.set(key(id, prop), value);
+      }
+    }
+  }
+  const segments = /* @__PURE__ */ new Map();
+  const motionPaths = /* @__PURE__ */ new Map();
+  const current = new Map(initialValues);
+  const pushSegment = (seg) => {
+    const k = key(seg.target, seg.prop);
+    let list = segments.get(k);
+    if (!list) segments.set(k, list = []);
+    list.push(seg);
+    current.set(k, seg.to);
+  };
+  const currentValue = (target, prop) => {
+    const v = current.get(key(target, prop));
+    if (v !== void 0) return v;
+    if (prop === "opacity" || prop === "scale" || prop === "progress" || 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();
+  const beatTimes = /* @__PURE__ */ new Map();
+  const durationOf = (tl, start) => {
+    switch (tl.kind) {
+      case "seq": {
+        let t = start;
+        for (const child of orderBeats(tl.children)) t = durationOf(child, t);
+        return t;
+      }
+      case "par": {
+        let end = start;
+        for (const child of tl.children) end = Math.max(end, durationOf(child, start));
+        return end;
+      }
+      case "stagger": {
+        let end = start;
+        tl.children.forEach((child, i) => {
+          end = Math.max(end, durationOf(child, start + i * tl.interval));
+        });
+        return end;
+      }
+      case "wait":
+        return start + tl.duration;
+      case "tween":
+        return start + (tl.duration ?? DEFAULT_TWEEN_DURATION);
+      case "motionPath":
+        return start + (tl.duration ?? DEFAULT_MOTIONPATH_DURATION);
+      case "to": {
+        const override = ir.states?.[tl.state] ?? {};
+        const duration = tl.duration ?? DEFAULT_TO_DURATION;
+        const si = tl.stagger ?? 0;
+        const targets = nodeOrder.filter(
+          (id) => id in override && (tl.filter === void 0 || tl.filter.includes(id))
+        );
+        return start + duration + Math.max(0, targets.length - 1) * si;
+      }
+      case "beat": {
+        const grouping = { kind: tl.parallel ? "par" : "seq", children: tl.children };
+        const natural = durationOf(grouping, 0);
+        const k = tl.scale ?? (tl.duration !== void 0 ? tl.duration / Math.max(1e-9, natural) : 1);
+        const beatStart = tl.at ?? start + (tl.gap ?? 0);
+        return beatStart + k * natural;
+      }
+    }
+  };
+  const walk = (tl, start) => {
+    const end = walkInner(tl, start);
+    if ("label" in tl && tl.label !== void 0) labelTimes.set(tl.label, { t0: start, t1: end });
+    return end;
+  };
+  const walkInner = (tl, start) => {
+    switch (tl.kind) {
+      case "seq": {
+        let t = start;
+        for (const child of orderBeats(tl.children)) t = walk(child, t);
+        return t;
+      }
+      case "beat": {
+        const grouping = { kind: tl.parallel ? "par" : "seq", children: tl.children };
+        const k = tl.scale ?? (tl.duration !== void 0 ? tl.duration / Math.max(1e-9, durationOf(grouping, 0)) : 1);
+        const inner = k === 1 ? grouping : scaleTimeline(grouping, k);
+        const beatStart = tl.at ?? start + (tl.gap ?? 0);
+        const end = walk(inner, beatStart);
+        beatTimes.set(tl.name, { t0: beatStart, t1: end });
+        labelTimes.set(tl.name, { t0: beatStart, t1: end });
+        return end;
+      }
+      case "par": {
+        let end = start;
+        for (const child of tl.children) end = Math.max(end, walk(child, start));
+        return end;
+      }
+      case "stagger": {
+        let end = start;
+        tl.children.forEach((child, i) => {
+          end = Math.max(end, walk(child, start + i * tl.interval));
+        });
+        return end;
+      }
+      case "wait":
+        return start + tl.duration;
+      case "tween": {
+        const duration = tl.duration ?? DEFAULT_TWEEN_DURATION;
+        for (const [prop, toValue] of Object.entries(tl.props)) {
+          pushSegment({
+            target: tl.target,
+            prop,
+            t0: start,
+            t1: start + duration,
+            from: currentValue(tl.target, prop),
+            to: toValue,
+            ...tl.ease !== void 0 && { ease: tl.ease }
+          });
+        }
+        return start + duration;
+      }
+      case "motionPath": {
+        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, curviness, autoRotate, rotateOffset, ...tl.ease !== void 0 && { ease: tl.ease } });
+        if (points.length > 0) {
+          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, curviness) + rotateOffset);
+        }
+        return start + duration;
+      }
+      case "to": {
+        const override = ir.states?.[tl.state] ?? {};
+        const duration = tl.duration ?? DEFAULT_TO_DURATION;
+        const staggerInterval = tl.stagger ?? 0;
+        const targets = nodeOrder.filter(
+          (id) => id in override && (tl.filter === void 0 || tl.filter.includes(id))
+        );
+        targets.forEach((id, i) => {
+          const t0 = start + i * staggerInterval;
+          for (const [prop, toValue] of Object.entries(override[id])) {
+            pushSegment({
+              target: id,
+              prop,
+              t0,
+              t1: t0 + duration,
+              from: currentValue(id, prop),
+              to: toValue,
+              ...tl.ease !== void 0 && { ease: tl.ease }
+            });
+          }
+        });
+        const last = Math.max(0, targets.length - 1);
+        return start + duration + last * staggerInterval;
+      }
+    }
+  };
+  const inferredEnd = ir.timeline ? walk(ir.timeline, 0) : 0;
+  for (const list of segments.values()) list.sort((a, b) => a.t0 - b.t0);
+  for (const list of motionPaths.values()) list.sort((a, b) => a.t0 - b.t0);
+  return {
+    ir,
+    duration: ir.duration ?? inferredEnd,
+    segments,
+    motionPaths,
+    initialValues,
+    nodeById,
+    nodeOrder,
+    labelTimes,
+    beatTimes
+  };
+}
+
+// ../core/src/validate.ts
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
+var PROPS_BY_TYPE = {
+  rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
+  ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
+  line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
+  image: [...COMMON_PROPS, "src", "width", "height"],
+  path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
+  group: COMMON_PROPS
+};
+var SceneValidationError = class extends Error {
+  constructor(problems) {
+    super(`Scene validation failed:
+${problems.map((p) => `  - ${p}`).join("\n")}`);
+    this.problems = problems;
+    this.name = "SceneValidationError";
+  }
+  problems;
+};
+function validateScene(ir) {
+  const problems = [];
+  const nodeById = /* @__PURE__ */ new Map();
+  const collect = (nodes) => {
+    for (const node of nodes) {
+      if (nodeById.has(node.id)) {
+        problems.push(`duplicate node id "${node.id}" \u2014 every node id must be unique`);
+      }
+      nodeById.set(node.id, node);
+      if (node.type === "group") {
+        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);
+  const checkProps = (where, nodeId, props) => {
+    const node = nodeById.get(nodeId);
+    if (!node) {
+      problems.push(
+        `${where} targets unknown node "${nodeId}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+      );
+      return;
+    }
+    const allowed = PROPS_BY_TYPE[node.type];
+    for (const key2 of Object.keys(props)) {
+      if (!allowed.includes(key2)) {
+        problems.push(
+          `${where}: "${key2}" is not a prop of ${node.type} "${nodeId}" \u2014 valid props: ${allowed.join(", ")}`
+        );
+      }
+    }
+  };
+  const states = ir.states ?? {};
+  for (const [stateName, overrides] of Object.entries(states)) {
+    for (const [nodeId, props] of Object.entries(overrides)) {
+      checkProps(`state "${stateName}"`, nodeId, props);
+    }
+  }
+  if (ir.initial !== void 0 && !(ir.initial in states)) {
+    problems.push(
+      `initial state "${ir.initial}" is not defined \u2014 defined states: ${Object.keys(states).join(", ") || "(none)"}`
+    );
+  }
+  const labels = /* @__PURE__ */ new Set();
+  const checkTimeline = (tl, path3) => {
+    if ("label" in tl && tl.label !== void 0) {
+      if (labels.has(tl.label)) {
+        problems.push(
+          `${path3}: duplicate timeline label "${tl.label}" \u2014 labels are overlay addresses and must be unique`
+        );
+      }
+      labels.add(tl.label);
+    }
+    switch (tl.kind) {
+      case "seq":
+      case "par":
+        tl.children.forEach((c, i) => checkTimeline(c, `${path3}.${tl.kind}[${i}]`));
+        break;
+      case "stagger":
+        if (tl.interval < 0) problems.push(`${path3}: stagger interval must be >= 0`);
+        tl.children.forEach((c, i) => checkTimeline(c, `${path3}.stagger[${i}]`));
+        break;
+      case "to":
+        if (!(tl.state in states)) {
+          problems.push(
+            `${path3}: 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(`${path3}: to("${tl.state}") duration must be > 0`);
+        }
+        for (const id of tl.filter ?? []) {
+          if (!nodeById.has(id)) problems.push(`${path3}: filter contains unknown node "${id}"`);
+        }
+        break;
+      case "tween":
+        checkProps(path3, tl.target, tl.props);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path3}: tween duration must be > 0`);
+        }
+        break;
+      case "motionPath": {
+        const node = nodeById.get(tl.target);
+        if (!node) {
+          problems.push(
+            `${path3}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+          );
+        } else if (node.type === "line") {
+          problems.push(`${path3}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+        }
+        if (tl.points.length < 1) problems.push(`${path3}: motionPath "${tl.target}" needs at least 1 point`);
+        if (tl.duration !== void 0 && tl.duration <= 0) {
+          problems.push(`${path3}: motionPath "${tl.target}" duration must be > 0`);
+        }
+        if (tl.curviness !== void 0 && tl.curviness < 0) {
+          problems.push(`${path3}: motionPath "${tl.target}" curviness must be >= 0`);
+        }
+        break;
+      }
+      case "wait":
+        if (tl.duration < 0) problems.push(`${path3}: wait duration must be >= 0`);
+        break;
+      case "beat":
+        if (labels.has(tl.name)) {
+          problems.push(
+            `${path3}: 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(`${path3}: beat "${tl.name}" duration must be > 0`);
+        }
+        if (tl.scale !== void 0 && tl.scale <= 0) {
+          problems.push(`${path3}: beat "${tl.name}" scale must be > 0`);
+        }
+        for (const id of tl.nodes ?? []) {
+          if (!nodeById.has(id)) {
+            problems.push(
+              `${path3}: beat "${tl.name}" owns unknown node "${id}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+            );
+          }
+        }
+        tl.children.forEach((c, i) => checkTimeline(c, `${path3}.beat(${tl.name})[${i}]`));
+        break;
+    }
+  };
+  if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const [i, b] of (ir.behaviors ?? []).entries()) {
+    checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
+  }
+  if (ir.duration !== void 0 && ir.duration <= 0) {
+    problems.push("scene duration must be > 0");
+  }
+  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
+  for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
+    if (typeof cue.at === "string" && !labels.has(cue.at)) {
+      problems.push(
+        `audio.cues[${i}]: unknown timeline label "${cue.at}" \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+    if (typeof cue.at === "number" && cue.at < 0) {
+      problems.push(`audio.cues[${i}]: "at" must be >= 0`);
+    }
+    if (cue.sfx === void 0 === (cue.file === void 0)) {
+      problems.push(`audio.cues[${i}]: exactly one of "sfx" or "file" is required`);
+    }
+    if (cue.sfx !== void 0 && !SFX_NAMES.includes(cue.sfx)) {
+      problems.push(`audio.cues[${i}]: unknown sfx "${cue.sfx}" \u2014 valid: ${SFX_NAMES.join(", ")}`);
+    }
+    if (cue.gain !== void 0 && cue.gain < 0) {
+      problems.push(`audio.cues[${i}]: gain must be >= 0`);
+    }
+  }
+  const duck = ir.audio?.bgm?.duck;
+  if (typeof duck === "object" && duck !== null && duck.depth !== void 0 && (duck.depth < 0 || duck.depth > 1)) {
+    problems.push("audio.bgm.duck.depth must be in [0, 1]");
+  }
+  if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
+    problems.push('audio.bgm: use either "file" or "synth", not both');
+  }
+  if (problems.length > 0) throw new SceneValidationError(problems);
+}
+
+// ../core/src/presets.ts
+var SET = 1 / 120;
+
+// ../core/src/interpolate.ts
+var BACK_C1 = 1.70158;
+var BACK_C2 = BACK_C1 * 1.525;
+var BACK_C3 = BACK_C1 + 1;
+var ELASTIC_C4 = 2 * Math.PI / 3;
+var ELASTIC_C5 = 2 * Math.PI / 4.5;
+function easeOutBounce(u) {
+  const n1 = 7.5625;
+  const d1 = 2.75;
+  if (u < 1 / d1) return n1 * u * u;
+  if (u < 2 / d1) return n1 * (u -= 1.5 / d1) * u + 0.75;
+  if (u < 2.5 / d1) return n1 * (u -= 2.25 / d1) * u + 0.9375;
+  return n1 * (u -= 2.625 / d1) * u + 0.984375;
+}
+var EASE_TABLE = {
+  linear: (u) => u,
+  easeInQuad: (u) => u * u,
+  easeOutQuad: (u) => 1 - (1 - u) * (1 - u),
+  easeInOutQuad: (u) => u < 0.5 ? 2 * u * u : 1 - (-2 * u + 2) ** 2 / 2,
+  easeInCubic: (u) => u ** 3,
+  easeOutCubic: (u) => 1 - (1 - u) ** 3,
+  easeInOutCubic: (u) => u < 0.5 ? 4 * u ** 3 : 1 - (-2 * u + 2) ** 3 / 2,
+  easeInQuart: (u) => u ** 4,
+  easeOutQuart: (u) => 1 - (1 - u) ** 4,
+  easeInOutQuart: (u) => u < 0.5 ? 8 * u ** 4 : 1 - (-2 * u + 2) ** 4 / 2,
+  easeInExpo: (u) => u === 0 ? 0 : 2 ** (10 * u - 10),
+  easeOutExpo: (u) => u === 1 ? 1 : 1 - 2 ** (-10 * u),
+  easeInOutExpo: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? 2 ** (20 * u - 10) / 2 : (2 - 2 ** (-20 * u + 10)) / 2,
+  // --- expressive eases (GSAP's signature feel) — standard Penner equations ---
+  // back: overshoots past the target then settles (pop / snap)
+  easeInBack: (u) => BACK_C3 * u ** 3 - BACK_C1 * u * u,
+  easeOutBack: (u) => 1 + BACK_C3 * (u - 1) ** 3 + BACK_C1 * (u - 1) ** 2,
+  easeInOutBack: (u) => u < 0.5 ? (2 * u) ** 2 * ((BACK_C2 + 1) * 2 * u - BACK_C2) / 2 : ((2 * u - 2) ** 2 * ((BACK_C2 + 1) * (2 * u - 2) + BACK_C2) + 2) / 2,
+  // elastic: rings around the target before settling (playful spring)
+  easeInElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : -(2 ** (10 * u - 10)) * Math.sin((u * 10 - 10.75) * ELASTIC_C4),
+  easeOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : 2 ** (-10 * u) * Math.sin((u * 10 - 0.75) * ELASTIC_C4) + 1,
+  easeInOutElastic: (u) => u === 0 ? 0 : u === 1 ? 1 : u < 0.5 ? -(2 ** (20 * u - 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5)) / 2 : 2 ** (-20 * u + 10) * Math.sin((20 * u - 11.125) * ELASTIC_C5) / 2 + 1,
+  // bounce: drops and bounces to rest (lands without overshoot)
+  easeInBounce: (u) => 1 - easeOutBounce(1 - u),
+  easeOutBounce,
+  easeInOutBounce: (u) => u < 0.5 ? (1 - easeOutBounce(1 - 2 * u)) / 2 : (1 + easeOutBounce(2 * u - 1)) / 2
+};
+var EASE_NAMES = Object.keys(EASE_TABLE);
+
+// ../render-cli/src/loadScene.ts
+import { build } from "esbuild";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var HERE = dirname(fileURLToPath(import.meta.url));
+var CORE_ENTRY = true ? resolve(HERE, "index.js") : resolve(HERE, "..", "..", "core", "src", "index.ts");
+async function loadDefault(path3) {
+  if (path3.endsWith(".json")) return JSON.parse(await readFile(path3, "utf8"));
+  let code;
+  try {
+    const out = await build({
+      entryPoints: [path3],
+      bundle: true,
+      format: "esm",
+      platform: "neutral",
+      write: false,
+      logLevel: "silent",
+      sourcemap: "inline",
+      // both specifiers accepted: the guide's canonical "@reframe/core" and
+      // the published package name
+      alias: { "@reframe/core": CORE_ENTRY, "reframe-video": CORE_ENTRY }
+    });
+    code = out.outputFiles[0].text;
+  } catch (err) {
+    throw new Error(`failed to bundle ${path3}:
+${err instanceof Error ? err.message : String(err)}`);
+  }
+  const mod = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
+  if (mod.default === void 0) throw new Error(`${path3} 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(path3) {
+  const def = await loadDefault(path3);
+  if (isComposition(def)) {
+    throw new Error(`${path3} is a composition \u2014 render it directly, not as a single scene`);
+  }
+  validateScene(def);
+  return def;
+}
+
+// ../render-cli/src/labels.ts
+var path2 = process.argv[2];
+if (!path2) {
+  console.error("usage: reframe labels <scene.ts|.json>");
+  process.exit(1);
+}
+var scene = await loadScene(path2);
+var compiled = compileScene(scene);
+var rows = [...compiled.labelTimes.entries()].sort((a, b) => a[1].t0 - b[1].t0 || a[0].localeCompare(b[0]));
+console.log(`# ${scene.id} \u2014 ${rows.length} labels \xB7 ${compiled.duration.toFixed(2)}s @ ${scene.fps ?? 30}fps`);
+console.log(`# ${"start".padStart(7)}  ${"end".padStart(7)}  label`);
+for (const [name, { t0, t1 }] of rows) {
+  console.log(`${`${t0.toFixed(2)}s`.padStart(8)}  ${`${t1.toFixed(2)}s`.padStart(8)}  ${name}`);
+}

package/dist/renderer-canvas.js

@@ -13,6 +13,21 @@ function renderFrame(ctx, compiled, t, images) {
 function drawDisplayList(ctx, ops, images) {
   for (const op of ops) {
     ctx.save();
+    if (op.clips) {
+      for (const clip of op.clips) {
+        ctx.setTransform(...clip.transform);
+        ctx.beginPath();
+        const { shape } = clip;
+        if (shape.kind === "ellipse") {
+          ctx.ellipse(shape.x + shape.width / 2, shape.y + shape.height / 2, Math.abs(shape.width / 2), Math.abs(shape.height / 2), 0, 0, Math.PI * 2);
+        } else if (shape.radius && shape.radius > 0) {
+          ctx.roundRect(shape.x, shape.y, shape.width, shape.height, shape.radius);
+        } else {
+          ctx.rect(shape.x, shape.y, shape.width, shape.height);
+        }
+        ctx.clip();
+      }
+    }
     ctx.setTransform(...op.transform);
     ctx.globalAlpha = Math.max(0, Math.min(1, op.opacity));
     switch (op.type) {

package/dist/trace-cli.js

@@ -6,7 +6,7 @@ import { resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // ../core/src/validate.ts
-var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "anchor"];
+var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor"];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
@@ -243,10 +243,10 @@ function analyzePair(prev, next, opts) {
 import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
 import { join } from "node:path";
-async function resolveSource(path) {
-  const s = await stat(path);
-  if (s.isDirectory()) return { kind: "png", input: join(path, "%05d.png") };
-  return { kind: "mp4", input: path };
+async function resolveSource(path2) {
+  const s = await stat(path2);
+  if (s.isDirectory()) return { kind: "png", input: join(path2, "%05d.png") };
+  return { kind: "mp4", input: path2 };
 }
 async function* frameStream(source, opts) {
   const frameBytes = opts.width * opts.height;
@@ -588,10 +588,10 @@ function extractMotionSketch(profile) {
   const hi = Math.max(HI_FLOOR, backgroundLevel(diff) + NOISE_MARGIN);
   const lo = hi * HI_LO_RATIO;
   const groups = groupRuns(findRuns(diff, nCells, hi, lo), spec.cols);
-  const events = groups.map((group) => {
-    const cells = [...new Set(group.map((r) => r.cell))];
-    const p0 = Math.min(...group.map((r) => r.p0));
-    const p1 = Math.max(...group.map((r) => r.p1));
+  const events = groups.map((group2) => {
+    const cells = [...new Set(group2.map((r) => r.cell))];
+    const p0 = Math.min(...group2.map((r) => r.p0));
+    const p1 = Math.max(...group2.map((r) => r.p1));
     const cols = cells.map((c) => c % spec.cols);
     const rows = cells.map((c) => Math.floor(c / spec.cols));
     const minC = Math.min(...cols);

package/dist/types/audio.d.ts

@@ -7,6 +7,7 @@
  * AI regenerate the scene, and the sound design follows.
  */
 import type { CompiledScene } from "./compile.js";
+import type { CompiledComposition } from "./composeComposition.js";
 import type { SfxName } from "./ir.js";
 /** Nominal cue lengths (s) for duck-window math; file cues use a default. */
 export declare const SFX_DURATION: Record<SfxName, number>;
@@ -51,3 +52,11 @@ export interface AudioPlan {
     warnings: string[];
 }
 export declare function resolveAudioPlan(compiled: CompiledScene): AudioPlan | null;
+/**
+ * Composition-level AudioPlan: each scene's cues offset by that scene's start,
+ * plus composition-level absolute-time cues, under a composition bed (e.g.
+ * kokoro narration) that spans all scenes. Per-scene bgm is ignored (warned) —
+ * the bed lives at the composition level. Same determinism boundary as
+ * resolveAudioPlan (plan + WAV bytes, not AAC-in-mp4).
+ */
+export declare function resolveCompositionAudioPlan(comp: CompiledComposition): AudioPlan | null;