reframe-video 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,10 +1,89 @@
 // ../core/src/ir.ts
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
+var DEFAULT_MOTIONPATH_DURATION = 1;
 var DEFAULT_FPS = 30;
 
+// ../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) {
+  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;
+  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) {
+  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]);
+  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 = [];
@@ -33,6 +112,7 @@ function compileScene(ir) {
     }
   }
   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);
@@ -49,6 +129,50 @@ function compileScene(ir) {
     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 });
@@ -58,9 +182,19 @@ function compileScene(ir) {
     switch (tl.kind) {
       case "seq": {
         let t = start;
-        for (const child of tl.children) t = walk(child, t);
+        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));
@@ -90,6 +224,23 @@ function compileScene(ir) {
         }
         return start + duration;
       }
+      case "motionPath": {
+        const duration = tl.duration ?? DEFAULT_MOTIONPATH_DURATION;
+        const points = tl.points;
+        const closed = tl.closed ?? false;
+        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 } });
+        if (points.length > 0) {
+          const [ex, ey] = pathPoint(points, closed, 1);
+          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);
+        }
+        return start + duration;
+      }
       case "to": {
         const override = ir.states?.[tl.state] ?? {};
         const duration = tl.duration ?? DEFAULT_TO_DURATION;
@@ -118,14 +269,17 @@ function compileScene(ir) {
   };
   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
+    labelTimes,
+    beatTimes
   };
 }
 
@@ -137,6 +291,7 @@ var PROPS_BY_TYPE = {
   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 {
@@ -190,11 +345,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);
@@ -202,33 +357,63 @@ 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(
+            `${path2}: motionPath targets unknown node "${tl.target}" \u2014 known ids: ${[...nodeById.keys()].join(", ")}`
+          );
+        } else if (node.type === "line") {
+          problems.push(`${path2}: motionPath cannot target a line (no x/y) \u2014 "${tl.target}"`);
+        }
+        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(`${path2}: motionPath "${tl.target}" duration 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(
+            `${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(`${path2}: beat "${tl.name}" duration must be > 0`);
+        }
+        if (tl.scale !== void 0 && tl.scale <= 0) {
+          problems.push(`${path2}: beat "${tl.name}" scale must be > 0`);
+        }
+        tl.children.forEach((c, i) => checkTimeline(c, `${path2}.beat(${tl.name})[${i}]`));
         break;
     }
   };
@@ -298,6 +483,10 @@ function image(props) {
   const { id, ...rest } = props;
   return { type: "image", 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 };
@@ -311,6 +500,9 @@ function par(...children) {
 function stagger(interval, ...children) {
   return { kind: "stagger", interval, children };
 }
+function beat(name, opts, children) {
+  return { kind: "beat", name, children, ...opts };
+}
 function to(state, opts = {}) {
   return { kind: "to", state, ...opts };
 }
@@ -320,6 +512,9 @@ function 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 };
+}
 function oscillate(target, prop, params, window = {}) {
   return { target, prop, ...window, behavior: { kind: "named", name: "oscillate", params } };
 }
@@ -451,13 +646,16 @@ function applyOverlay(ir, overlay, layer, report) {
     const byLabel = /* @__PURE__ */ new Map();
     const walkTimeline = (tl) => {
       if ("label" in tl && tl.label !== void 0) byLabel.set(tl.label, tl);
+      if (tl.kind === "beat") byLabel.set(tl.name, tl);
       if ("children" in tl) tl.children.forEach(walkTimeline);
     };
     if (ir.timeline) walkTimeline(ir.timeline);
     const PATCHABLE = {
       to: ["duration", "ease", "stagger"],
       tween: ["duration", "ease"],
-      wait: ["duration"]
+      wait: ["duration"],
+      motionPath: ["points", "duration", "ease"],
+      beat: ["at", "gap", "scale", "duration", "order"]
     };
     let timingPatched = false;
     for (const [label, patch] of Object.entries(overlay.timeline)) {
@@ -481,7 +679,7 @@ function applyOverlay(ir, overlay, layer, report) {
         }
         step[key2] = value;
         applied(`timeline.${label}.${key2}`, "set");
-        if (key2 === "duration" || key2 === "stagger") timingPatched = true;
+        if (["duration", "stagger", "at", "gap", "scale", "order"].includes(key2)) timingPatched = true;
       }
     }
     if (timingPatched && overlay.scene?.duration === void 0) {
@@ -506,6 +704,186 @@ function formatComposeReport(report) {
   return lines.join("\n");
 }
 
+// ../core/src/presets.ts
+var PRESET_NAMES = [
+  "draw-bloom",
+  "punch-in",
+  "rise-settle",
+  "slide-bank",
+  "reveal-orbit",
+  "spin-forge"
+];
+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;
+  };
+}
+var clamp01 = (x) => Math.max(0, Math.min(1, x));
+var SET = 1 / 120;
+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
+  };
+}
+var dur = (base, sp) => base / sp;
+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))
+        )
+      ]);
+    }
+  }
+}
+
 // ../core/src/audio.ts
 var SFX_DURATION = {
   whoosh: 0.35,
@@ -607,6 +985,19 @@ function hash01(n, seed) {
 }
 
 // ../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,
@@ -620,7 +1011,20 @@ var EASE_TABLE = {
   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
+  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);
 function resolveEase(ease) {
@@ -735,6 +1139,7 @@ function evaluate(compiled, t) {
   const ops = [];
   const valueAt = (target, prop, fallback) => {
     let value = compiled.initialValues.get(`${target}.${prop}`) ?? fallback;
+    let segStart = Number.NEGATIVE_INFINITY;
     const segs = compiled.segments.get(`${target}.${prop}`);
     if (segs) {
       let active;
@@ -743,6 +1148,7 @@ function evaluate(compiled, t) {
         else break;
       }
       if (active) {
+        segStart = active.t0;
         if (t >= active.t1) {
           value = active.to;
         } else {
@@ -751,6 +1157,23 @@ function evaluate(compiled, t) {
         }
       }
     }
+    if (prop === "x" || prop === "y" || prop === "rotation") {
+      const drivers = compiled.motionPaths.get(target);
+      if (drivers) {
+        let active;
+        for (const d of drivers) {
+          if (d.t0 <= t) active = d;
+          else break;
+        }
+        if (active && active.t0 >= segStart && (prop !== "rotation" || active.autoRotate) && active.points.length > 0) {
+          const span = active.t1 - active.t0;
+          const u = span <= 0 ? 1 : resolveEase(active.ease)(Math.max(0, Math.min(1, (t - active.t0) / span)));
+          if (prop === "x") value = pathPoint(active.points, active.closed, u)[0];
+          else if (prop === "y") value = pathPoint(active.points, active.closed, u)[1];
+          else value = pathTangentAngle(active.points, active.closed, u) + active.rotateOffset;
+        }
+      }
+    }
     for (const b of compiled.ir.behaviors ?? []) {
       if (b.target === target && b.prop === prop && typeof value === "number") {
         const envelope = behaviorEnvelope(b, t);
@@ -848,6 +1271,23 @@ function evaluate(compiled, t) {
         });
         return;
       }
+      case "path": {
+        const ox = num(id, "originX", node.props.originX ?? 0);
+        const oy = num(id, "originY", node.props.originY ?? 0);
+        const fill = opt(id, "fill", node.props.fill);
+        const stroke = opt(id, "stroke", node.props.stroke);
+        ops.push({
+          type: "path",
+          id,
+          transform: ox === 0 && oy === 0 ? matrix : multiply(matrix, [1, 0, 0, 1, -ox, -oy]),
+          opacity,
+          d: str(id, "d", node.props.d),
+          progress: Math.max(0, Math.min(1, num(id, "progress", node.props.progress ?? 1))),
+          ...fill !== void 0 && { fill },
+          ...stroke !== void 0 && { stroke, strokeWidth: num(id, "strokeWidth", node.props.strokeWidth ?? 1) }
+        });
+        return;
+      }
       case "text": {
         const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
         const raw = valueAt(id, "content", node.props.content);
@@ -908,14 +1348,62 @@ function collectImageSrcs(ir) {
   walkTimeline(ir.timeline);
   return [...srcs];
 }
+
+// ../core/src/motion.ts
+var EASE_BY_CLASS = {
+  accelerating: "easeInCubic",
+  decelerating: "easeOutCubic",
+  linear: "linear"
+};
+function easeFor(easing) {
+  return EASE_BY_CLASS[easing.class] ?? "easeOutCubic";
+}
+function sketchToTimeline(sketch, nodeIds) {
+  if (nodeIds.length === 0) return seq();
+  const events = [...sketch.events].sort((a, b) => a.t0 - b.t0);
+  const steps = [];
+  events.forEach((ev, i) => {
+    const node = nodeIds[i % nodeIds.length];
+    const dur2 = Math.max(0.05, ev.t1 - ev.t0);
+    const ease = easeFor(ev.easing);
+    let motion;
+    switch (ev.kind) {
+      case "enter":
+        motion = tween(node, { opacity: 1 }, { duration: dur2, ease });
+        break;
+      case "exit":
+        motion = tween(node, { opacity: 0 }, { duration: dur2, ease });
+        break;
+      case "emphasis": {
+        const peak = 1 + Math.max(0.08, Math.min(0.5, ev.magnitude));
+        motion = seq(
+          tween(node, { scale: peak }, { duration: dur2 / 2, ease: "easeOutCubic" }),
+          tween(node, { scale: 1 }, { duration: dur2 / 2, ease: "easeInOutQuad" })
+        );
+        break;
+      }
+      case "scale":
+        motion = tween(node, { scale: 1 + Math.max(-0.5, Math.min(0.5, ev.magnitude)) }, { duration: dur2, ease });
+        break;
+      case "move":
+        motion = tween(node, { opacity: 1 }, { duration: dur2, ease });
+        break;
+    }
+    steps.push(ev.t0 > 0 ? seq(wait(ev.t0), motion) : motion);
+  });
+  return par(...steps);
+}
 export {
   DEFAULT_FPS,
+  DEFAULT_MOTIONPATH_DURATION,
   DEFAULT_TO_DURATION,
   DEFAULT_TWEEN_DURATION,
   EASE_NAMES,
+  PRESET_NAMES,
   PROPS_BY_TYPE,
   SFX_DURATION,
   SceneValidationError,
+  beat,
   collectImageSrcs,
   compileScene,
   composeScene,
@@ -927,14 +1415,20 @@ export {
   isColor,
   lerpValue,
   line,
+  motionPath,
+  motionPreset,
   oscillate,
   par,
+  path,
+  pathPoint,
+  pathTangentAngle,
   rect,
   resolveAudioPlan,
   resolveEase,
   sampleBehavior,
   scene,
   seq,
+  sketchToTimeline,
   stagger,
   text,
   to,