reframe-video 0.6.33 → 0.6.39

package/dist/browserEntry.js

@@ -219,11 +219,68 @@
           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);
+          const at = typeof tl.at === "number" ? tl.at : void 0;
+          const beatStart = at ?? start + (tl.gap ?? 0);
           return beatStart + k * natural;
         }
       }
     };
+    let labelClock;
+    const anyAnchor = (tl) => tl.kind === "beat" && typeof tl.at === "string" || "children" in tl && tl.children.some(anyAnchor);
+    if (ir.timeline && anyAnchor(ir.timeline)) {
+      const clock = /* @__PURE__ */ new Map();
+      const clockWalk = (tl, start) => {
+        let end = start;
+        switch (tl.kind) {
+          case "seq": {
+            let t = start;
+            for (const c of orderBeats(tl.children)) t = clockWalk(c, t);
+            end = t;
+            break;
+          }
+          case "par": {
+            for (const c of tl.children) end = Math.max(end, clockWalk(c, start));
+            break;
+          }
+          case "stagger": {
+            tl.children.forEach((c, i) => {
+              end = Math.max(end, clockWalk(c, start + i * tl.interval));
+            });
+            break;
+          }
+          case "wait":
+            end = start + tl.duration;
+            break;
+          case "tween":
+            end = start + (tl.duration ?? DEFAULT_TWEEN_DURATION);
+            break;
+          case "motionPath":
+            end = start + (tl.duration ?? DEFAULT_MOTIONPATH_DURATION);
+            break;
+          case "to": {
+            const override = ir.states?.[tl.state] ?? {};
+            const si = tl.stagger ?? 0;
+            const targets = nodeOrder.filter((id) => id in override && (tl.filter === void 0 || tl.filter.includes(id)));
+            end = start + (tl.duration ?? DEFAULT_TO_DURATION) + Math.max(0, targets.length - 1) * si;
+            break;
+          }
+          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 at = typeof tl.at === "number" ? tl.at : void 0;
+            const beatStart = at ?? start + (tl.gap ?? 0);
+            end = clockWalk(inner, beatStart);
+            clock.set(tl.name, { t0: beatStart, t1: end });
+            break;
+          }
+        }
+        if ("label" in tl && tl.label !== void 0) clock.set(tl.label, { t0: start, t1: end });
+        return end;
+      };
+      clockWalk(ir.timeline, 0);
+      labelClock = clock;
+    }
     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 });
@@ -240,7 +297,8 @@
           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 anchored = typeof tl.at === "string" ? labelClock?.get(tl.at)?.t0 : tl.at;
+          const beatStart = anchored !== void 0 ? anchored + (typeof tl.at === "string" ? tl.gap ?? 0 : 0) : 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 });
@@ -885,7 +943,8 @@
           const height = num(id, "height", node.props.height);
           const [ax, ay] = ANCHOR_FACTORS[node.props.anchor ?? "top-left"];
           const fps = compiled2.ir.fps ?? 30;
-          const start = node.props.start ?? 0;
+          const startRaw = node.props.start;
+          const start = typeof startRaw === "string" ? compiled2.labelTimes.get(startRaw)?.t0 ?? 0 : startRaw ?? 0;
           const rate = node.props.rate ?? 1;
           const clipStart = node.props.clipStart ?? 0;
           const srcT = clipStart + Math.max(0, t - start) * rate;

package/dist/cli.js

@@ -245,11 +245,68 @@ function compileScene(ir) {
         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);
+        const at = typeof tl.at === "number" ? tl.at : void 0;
+        const beatStart = at ?? start + (tl.gap ?? 0);
         return beatStart + k * natural;
       }
     }
   };
+  let labelClock;
+  const anyAnchor = (tl) => tl.kind === "beat" && typeof tl.at === "string" || "children" in tl && tl.children.some(anyAnchor);
+  if (ir.timeline && anyAnchor(ir.timeline)) {
+    const clock = /* @__PURE__ */ new Map();
+    const clockWalk = (tl, start) => {
+      let end = start;
+      switch (tl.kind) {
+        case "seq": {
+          let t = start;
+          for (const c of orderBeats(tl.children)) t = clockWalk(c, t);
+          end = t;
+          break;
+        }
+        case "par": {
+          for (const c of tl.children) end = Math.max(end, clockWalk(c, start));
+          break;
+        }
+        case "stagger": {
+          tl.children.forEach((c, i) => {
+            end = Math.max(end, clockWalk(c, start + i * tl.interval));
+          });
+          break;
+        }
+        case "wait":
+          end = start + tl.duration;
+          break;
+        case "tween":
+          end = start + (tl.duration ?? DEFAULT_TWEEN_DURATION);
+          break;
+        case "motionPath":
+          end = start + (tl.duration ?? DEFAULT_MOTIONPATH_DURATION);
+          break;
+        case "to": {
+          const override = ir.states?.[tl.state] ?? {};
+          const si = tl.stagger ?? 0;
+          const targets = nodeOrder.filter((id) => id in override && (tl.filter === void 0 || tl.filter.includes(id)));
+          end = start + (tl.duration ?? DEFAULT_TO_DURATION) + Math.max(0, targets.length - 1) * si;
+          break;
+        }
+        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 at = typeof tl.at === "number" ? tl.at : void 0;
+          const beatStart = at ?? start + (tl.gap ?? 0);
+          end = clockWalk(inner, beatStart);
+          clock.set(tl.name, { t0: beatStart, t1: end });
+          break;
+        }
+      }
+      if ("label" in tl && tl.label !== void 0) clock.set(tl.label, { t0: start, t1: end });
+      return end;
+    };
+    clockWalk(ir.timeline, 0);
+    labelClock = clock;
+  }
   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 });
@@ -266,7 +323,8 @@ function compileScene(ir) {
         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 anchored = typeof tl.at === "string" ? labelClock?.get(tl.at)?.t0 : tl.at;
+        const beatStart = anchored !== void 0 ? anchored + (typeof tl.at === "string" ? tl.gap ?? 0 : 0) : 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 });
@@ -586,6 +644,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const startAnchors = [];
   const checkPaint = (where, value) => {
     if (typeof value !== "object" || value === null) return;
     const g = value;
@@ -618,6 +677,7 @@ function validateScene(ir) {
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
+      if (node.type === "video" && typeof node.props.start === "string") startAnchors.push({ id: node.id, at: node.props.start });
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -678,6 +738,7 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
+  const beatAnchors = [];
   const checkEase = (path2, ease) => {
     if (ease === void 0) return;
     if (typeof ease === "string") {
@@ -769,6 +830,7 @@ function validateScene(ir) {
           );
         }
         labels.add(tl.name);
+        if (typeof tl.at === "string") beatAnchors.push({ name: tl.name, at: tl.at, path: path2 });
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
@@ -787,6 +849,22 @@ function validateScene(ir) {
     }
   };
   if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const a of beatAnchors) {
+    if (a.at === a.name) {
+      problems.push(`${a.path}: beat "${a.name}" at: "${a.at}" cannot anchor to itself`);
+    } else if (!labels.has(a.at)) {
+      problems.push(
+        `${a.path}: beat "${a.name}" at: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
+  for (const a of startAnchors) {
+    if (!labels.has(a.at)) {
+      problems.push(
+        `video "${a.id}" start: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
   for (const [i, b] of (ir.behaviors ?? []).entries()) {
     checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
   }
@@ -913,6 +991,13 @@ function compileComposition(comp) {
 
 // ../core/src/compose.ts
 var SCENE_PATCHABLE = ["background", "duration", "fps"];
+var TIMELINE_PATCHABLE = {
+  to: ["duration", "ease", "stagger"],
+  tween: ["duration", "ease"],
+  wait: ["duration"],
+  motionPath: ["points", "duration", "ease", "curviness", "autoRotate"],
+  beat: ["at", "gap", "scale", "duration", "order"]
+};
 function composeScene(base, ...overlays) {
   const ir = structuredClone(base);
   const report = { applied: [], orphans: [], warnings: [] };
@@ -1047,13 +1132,6 @@ function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
       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"],
-      motionPath: ["points", "duration", "ease", "curviness", "autoRotate"],
-      beat: ["at", "gap", "scale", "duration", "order"]
-    };
     let timingPatched = false;
     for (const [label, patch] of Object.entries(overlay.timeline)) {
       const step = byLabel.get(label);
@@ -1064,7 +1142,7 @@ function applyOverlay(ir, overlay, layer, report, baseNodeIds) {
         );
         continue;
       }
-      const allowed = PATCHABLE[step.kind] ?? [];
+      const allowed = TIMELINE_PATCHABLE[step.kind] ?? [];
       for (const [key2, value] of Object.entries(patch)) {
         if (value === void 0) continue;
         if (!allowed.includes(key2)) {
@@ -1174,7 +1252,35 @@ function hash01(n, seed) {
 }
 
 // ../core/src/evaluate.ts
+var IDENTITY = [1, 0, 0, 1, 0, 0];
+function multiply(m, n) {
+  return [
+    m[0] * n[0] + m[2] * n[1],
+    m[1] * n[0] + m[3] * n[1],
+    m[0] * n[2] + m[2] * n[3],
+    m[1] * n[2] + m[3] * n[3],
+    m[0] * n[4] + m[2] * n[5] + m[4],
+    m[1] * n[4] + m[3] * n[5] + m[5]
+  ];
+}
 var DEG = Math.PI / 180;
+function localMatrix(x, y, rotationDeg, scale, scaleX = 1, scaleY = 1, skewXDeg = 0, skewYDeg = 0) {
+  const r = rotationDeg * Math.PI / 180;
+  if (scaleX === 1 && scaleY === 1 && skewXDeg === 0 && skewYDeg === 0) {
+    const cos = Math.cos(r) * scale;
+    const sin = Math.sin(r) * scale;
+    return [cos, sin, -sin, cos, x, y];
+  }
+  const c = Math.cos(r);
+  const s = Math.sin(r);
+  const tx = Math.tan(skewXDeg * Math.PI / 180);
+  const ty = Math.tan(skewYDeg * Math.PI / 180);
+  const R = [c, s, -s, c, 0, 0];
+  const K = [1, ty, tx, 1, 0, 0];
+  const S = [scale * scaleX, 0, 0, scale * scaleY, 0, 0];
+  const m = multiply(R, multiply(K, S));
+  return [m[0], m[1], m[2], m[3], x, y];
+}
 function behaviorEnvelope(b, t) {
   const from = b.from ?? Number.NEGATIVE_INFINITY;
   const until = b.until ?? Number.POSITIVE_INFINITY;
@@ -1230,6 +1336,38 @@ function sampleProp(compiled, t, target, prop, fallback) {
   }
   return value;
 }
+function nodeParentMatrix(compiled, id, t) {
+  const num2 = (target, prop, fallback) => {
+    const v = sampleProp(compiled, t, target, prop, fallback);
+    return typeof v === "number" ? v : fallback;
+  };
+  let result = null;
+  const walk = (node, parent) => {
+    if (node.id === id) {
+      result = parent;
+      return true;
+    }
+    if (node.type === "group") {
+      const m = multiply(
+        parent,
+        localMatrix(
+          num2(node.id, "x", node.props.x),
+          num2(node.id, "y", node.props.y),
+          num2(node.id, "rotation", node.props.rotation ?? 0),
+          num2(node.id, "scale", node.props.scale ?? 1),
+          num2(node.id, "scaleX", node.props.scaleX ?? 1),
+          num2(node.id, "scaleY", node.props.scaleY ?? 1),
+          num2(node.id, "skewX", node.props.skewX ?? 0),
+          num2(node.id, "skewY", node.props.skewY ?? 0)
+        )
+      );
+      for (const child of node.children) if (walk(child, m)) return true;
+    }
+    return false;
+  };
+  for (const node of compiled.ir.nodes) if (walk(node, IDENTITY)) break;
+  return result;
+}
 
 // ../core/src/autoFoley.ts
 var V_MIN = 360;
@@ -1275,6 +1413,10 @@ function autoFoley(compiled, opts = {}) {
       os.push(num(compiled, t, id, "opacity", node.props.opacity ?? 1));
     }
     const speed = (i2) => i2 <= 0 ? 0 : Math.hypot(xs[i2] - xs[i2 - 1], ys[i2] - ys[i2 - 1]) * fps;
+    const worldX = (frame) => {
+      const m = nodeParentMatrix(compiled, id, frame / fps);
+      return m ? m[0] * xs[frame] + m[2] * ys[frame] + m[4] : xs[frame];
+    };
     let i = 1;
     while (i <= N) {
       if (speed(i) <= vMin) {
@@ -1297,19 +1439,20 @@ function autoFoley(compiled, opts = {}) {
       if (peakV > vMin && durS >= MIN_DUR && visible) {
         if (wantWhoosh) {
           const quickFlick = durS < 0.25;
-          cands.push({ t: peak / fps, sfx: quickFlick ? "swish" : "whoosh", gain: master * loud(peakV), pan: panOf(xs[peak]), rank: peakV });
+          cands.push({ t: peak / fps, sfx: quickFlick ? "swish" : "whoosh", gain: master * loud(peakV), pan: panOf(worldX(peak)), rank: peakV });
         }
         const stopped = b >= N || speed(b + 1) < vStop && speed(Math.min(N, b + 2)) < vStop;
-        const landsOnScreen = xs[b] >= 0 && xs[b] <= W && os[b] > 0.1;
+        const wxb = worldX(b);
+        const landsOnScreen = wxb >= 0 && wxb <= W && os[b] > 0.1;
         if (wantImpact && peakV > vDecel && stopped && landsOnScreen && b < N) {
-          cands.push({ t: (b + 1) / fps, sfx: size > 220 ? "thud" : "knock", gain: master * loud(peakV), pan: panOf(xs[b]), rank: peakV * 1.1 });
+          cands.push({ t: (b + 1) / fps, sfx: size > 220 ? "thud" : "knock", gain: master * loud(peakV), pan: panOf(worldX(b)), rank: peakV * 1.1 });
         }
       }
     }
     if (wantPop && ss[0] < 0.25) {
       for (let k = 1; k <= N; k++) {
         if (ss[k - 1] < 0.5 && ss[k] >= 0.5 && os[k] > 0.05) {
-          cands.push({ t: k / fps, sfx: "pop", gain: master * 0.7, pan: panOf(xs[k]), rank: 600 });
+          cands.push({ t: k / fps, sfx: "pop", gain: master * 0.7, pan: panOf(worldX(k)), rank: 600 });
           break;
         }
       }
@@ -1378,13 +1521,14 @@ var SFX_DURATION = {
   camera: 0.18
 };
 var FILE_CUE_DURATION = 0.4;
-function collectClipAudio(ir, duration, warnings) {
+function collectClipAudio(ir, duration, labelTimes, warnings) {
   const out = [];
   const walk = (nodes) => {
     for (const node of nodes) {
       if (node.type === "video") {
         const gain = node.props.volume ?? 1;
-        const start = node.props.start ?? 0;
+        const startRaw = node.props.start;
+        const start = typeof startRaw === "string" ? labelTimes.get(startRaw)?.t0 ?? 0 : startRaw ?? 0;
         if (gain <= 0) continue;
         if (start >= duration) {
           warnings.push(`video "${node.id}": start ${start.toFixed(2)}s past the scene end \u2014 audio dropped`);
@@ -1402,7 +1546,7 @@ function resolveAudioPlan(compiled) {
   const audio = compiled.ir.audio;
   const warnings = [];
   const duration = compiled.duration;
-  const clipAudio = collectClipAudio(compiled.ir, duration, warnings);
+  const clipAudio = collectClipAudio(compiled.ir, duration, compiled.labelTimes, warnings);
   const autoCues = audio?.autoFoley ? autoFoley(compiled, audio.autoFoley === true ? {} : audio.autoFoley) : [];
   const manualCues = [...audio?.cues ?? [], ...autoCues];
   if (!audio || !audio.bgm && manualCues.length === 0) {
@@ -2599,7 +2743,7 @@ ${stderr.slice(-2e3)}`))
   });
 }
 function neededSeconds(node, duration) {
-  const start = node.props.start ?? 0;
+  const start = typeof node.props.start === "string" ? 0 : node.props.start ?? 0;
   const rate = node.props.rate ?? 1;
   const clipStart = node.props.clipStart ?? 0;
   return clipStart + Math.max(0, duration - start) * Math.max(0, rate) + 1 / 30;

package/dist/compile-api.js

@@ -142,6 +142,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const startAnchors = [];
   const checkPaint = (where, value) => {
     if (typeof value !== "object" || value === null) return;
     const g = value;
@@ -174,6 +175,7 @@ function validateScene(ir) {
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
+      if (node.type === "video" && typeof node.props.start === "string") startAnchors.push({ id: node.id, at: node.props.start });
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -234,6 +236,7 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
+  const beatAnchors = [];
   const checkEase = (path2, ease) => {
     if (ease === void 0) return;
     if (typeof ease === "string") {
@@ -325,6 +328,7 @@ function validateScene(ir) {
           );
         }
         labels.add(tl.name);
+        if (typeof tl.at === "string") beatAnchors.push({ name: tl.name, at: tl.at, path: path2 });
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
@@ -343,6 +347,22 @@ function validateScene(ir) {
     }
   };
   if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const a of beatAnchors) {
+    if (a.at === a.name) {
+      problems.push(`${a.path}: beat "${a.name}" at: "${a.at}" cannot anchor to itself`);
+    } else if (!labels.has(a.at)) {
+      problems.push(
+        `${a.path}: beat "${a.name}" at: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
+  for (const a of startAnchors) {
+    if (!labels.has(a.at)) {
+      problems.push(
+        `video "${a.id}" start: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
   for (const [i, b] of (ir.behaviors ?? []).entries()) {
     checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
   }

package/dist/compile.js

@@ -147,6 +147,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const startAnchors = [];
   const checkPaint = (where, value) => {
     if (typeof value !== "object" || value === null) return;
     const g = value;
@@ -179,6 +180,7 @@ function validateScene(ir) {
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
+      if (node.type === "video" && typeof node.props.start === "string") startAnchors.push({ id: node.id, at: node.props.start });
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -239,6 +241,7 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
+  const beatAnchors = [];
   const checkEase = (path2, ease) => {
     if (ease === void 0) return;
     if (typeof ease === "string") {
@@ -330,6 +333,7 @@ function validateScene(ir) {
           );
         }
         labels.add(tl.name);
+        if (typeof tl.at === "string") beatAnchors.push({ name: tl.name, at: tl.at, path: path2 });
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
@@ -348,6 +352,22 @@ function validateScene(ir) {
     }
   };
   if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const a of beatAnchors) {
+    if (a.at === a.name) {
+      problems.push(`${a.path}: beat "${a.name}" at: "${a.at}" cannot anchor to itself`);
+    } else if (!labels.has(a.at)) {
+      problems.push(
+        `${a.path}: beat "${a.name}" at: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
+  for (const a of startAnchors) {
+    if (!labels.has(a.at)) {
+      problems.push(
+        `video "${a.id}" start: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
   for (const [i, b] of (ir.behaviors ?? []).entries()) {
     checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
   }

package/dist/diff.js

@@ -251,11 +251,68 @@ function compileScene(ir) {
         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);
+        const at = typeof tl.at === "number" ? tl.at : void 0;
+        const beatStart = at ?? start + (tl.gap ?? 0);
         return beatStart + k * natural;
       }
     }
   };
+  let labelClock;
+  const anyAnchor = (tl) => tl.kind === "beat" && typeof tl.at === "string" || "children" in tl && tl.children.some(anyAnchor);
+  if (ir.timeline && anyAnchor(ir.timeline)) {
+    const clock = /* @__PURE__ */ new Map();
+    const clockWalk = (tl, start) => {
+      let end = start;
+      switch (tl.kind) {
+        case "seq": {
+          let t = start;
+          for (const c of orderBeats(tl.children)) t = clockWalk(c, t);
+          end = t;
+          break;
+        }
+        case "par": {
+          for (const c of tl.children) end = Math.max(end, clockWalk(c, start));
+          break;
+        }
+        case "stagger": {
+          tl.children.forEach((c, i) => {
+            end = Math.max(end, clockWalk(c, start + i * tl.interval));
+          });
+          break;
+        }
+        case "wait":
+          end = start + tl.duration;
+          break;
+        case "tween":
+          end = start + (tl.duration ?? DEFAULT_TWEEN_DURATION);
+          break;
+        case "motionPath":
+          end = start + (tl.duration ?? DEFAULT_MOTIONPATH_DURATION);
+          break;
+        case "to": {
+          const override = ir.states?.[tl.state] ?? {};
+          const si = tl.stagger ?? 0;
+          const targets = nodeOrder.filter((id) => id in override && (tl.filter === void 0 || tl.filter.includes(id)));
+          end = start + (tl.duration ?? DEFAULT_TO_DURATION) + Math.max(0, targets.length - 1) * si;
+          break;
+        }
+        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 at = typeof tl.at === "number" ? tl.at : void 0;
+          const beatStart = at ?? start + (tl.gap ?? 0);
+          end = clockWalk(inner, beatStart);
+          clock.set(tl.name, { t0: beatStart, t1: end });
+          break;
+        }
+      }
+      if ("label" in tl && tl.label !== void 0) clock.set(tl.label, { t0: start, t1: end });
+      return end;
+    };
+    clockWalk(ir.timeline, 0);
+    labelClock = clock;
+  }
   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 });
@@ -272,7 +329,8 @@ function compileScene(ir) {
         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 anchored = typeof tl.at === "string" ? labelClock?.get(tl.at)?.t0 : tl.at;
+        const beatStart = anchored !== void 0 ? anchored + (typeof tl.at === "string" ? tl.gap ?? 0 : 0) : 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 });
@@ -473,6 +531,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 function validateScene(ir) {
   const problems = [];
   const nodeById = /* @__PURE__ */ new Map();
+  const startAnchors = [];
   const checkPaint = (where, value) => {
     if (typeof value !== "object" || value === null) return;
     const g = value;
@@ -505,6 +564,7 @@ function validateScene(ir) {
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
       if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
+      if (node.type === "video" && typeof node.props.start === "string") startAnchors.push({ id: node.id, at: node.props.start });
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -565,6 +625,7 @@ function validateScene(ir) {
     );
   }
   const labels = /* @__PURE__ */ new Set();
+  const beatAnchors = [];
   const checkEase = (path2, ease) => {
     if (ease === void 0) return;
     if (typeof ease === "string") {
@@ -656,6 +717,7 @@ function validateScene(ir) {
           );
         }
         labels.add(tl.name);
+        if (typeof tl.at === "string") beatAnchors.push({ name: tl.name, at: tl.at, path: path2 });
         if (tl.duration !== void 0 && tl.duration <= 0) {
           problems.push(`${path2}: beat "${tl.name}" duration must be > 0`);
         }
@@ -674,6 +736,22 @@ function validateScene(ir) {
     }
   };
   if (ir.timeline) checkTimeline(ir.timeline, "timeline");
+  for (const a of beatAnchors) {
+    if (a.at === a.name) {
+      problems.push(`${a.path}: beat "${a.name}" at: "${a.at}" cannot anchor to itself`);
+    } else if (!labels.has(a.at)) {
+      problems.push(
+        `${a.path}: beat "${a.name}" at: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
+  for (const a of startAnchors) {
+    if (!labels.has(a.at)) {
+      problems.push(
+        `video "${a.id}" start: "${a.at}" \u2014 unknown timeline label \u2014 known labels: ${[...labels].join(", ") || "(none)"}`
+      );
+    }
+  }
   for (const [i, b] of (ir.behaviors ?? []).entries()) {
     checkProps(`behaviors[${i}]`, b.target, { [b.prop]: 0 });
   }
@@ -980,7 +1058,7 @@ ${stderr.slice(-2e3)}`))
   });
 }
 function neededSeconds(node, duration) {
-  const start = node.props.start ?? 0;
+  const start = typeof node.props.start === "string" ? 0 : node.props.start ?? 0;
   const rate = node.props.rate ?? 1;
   const clipStart = node.props.clipStart ?? 0;
   return clipStart + Math.max(0, duration - start) * Math.max(0, rate) + 1 / 30;