@vosjs/studio-core 0.10.0 → 0.11.1

package/dist/index.js

@@ -424,12 +424,358 @@ function projectFromArtifact(artifact, videoUrl, opts = {}) {
   return { doc, videoUrl };
 }
 
+// src/lower/motion.ts
+import { sortKeyframes } from "@vosjs/timeline";
+
+// src/anim.ts
+var CARD_ENTER_KINDS = [
+  "none",
+  "fade",
+  "rise",
+  "tilt-in",
+  "pull-out"
+];
+var CARD_EXIT_KINDS = ["none", "fade", "recede"];
+var TEXT_ENTER_KINDS = [
+  "none",
+  "fade",
+  "rise",
+  "pop",
+  "blur",
+  "typewriter"
+];
+var TEXT_EXIT_KINDS = ["none", "fade", "rise"];
+var MEDIA_ENTER_KINDS = ["none", "fade", "rise"];
+var MEDIA_EXIT_KINDS = ["none", "fade", "rise"];
+var IDLE_KINDS = ["spin", "float"];
+var UNIT_KINDS = /* @__PURE__ */ new Set(["pop", "blur", "typewriter"]);
+function animStep(step) {
+  if (step == null) return null;
+  if (typeof step === "string") return { kind: step };
+  return step;
+}
+function enterOf(anim) {
+  return animStep(anim?.enter);
+}
+function exitOf(anim) {
+  return animStep(anim?.exit);
+}
+function isUnitStep(step) {
+  if (!step) return false;
+  if (UNIT_KINDS.has(step.kind)) return true;
+  if (step.kind !== "fade" && step.kind !== "rise") return false;
+  return step.unit !== void 0 || step.stagger !== void 0 || step.seconds !== void 0 || step.direction !== void 0;
+}
+function overlayFxSpec(clip) {
+  const step = enterOf(clip.anim);
+  if (!isUnitStep(step) || !step || step.kind === "none") return null;
+  const kind = step.kind;
+  const fx = kind === "fade" || kind === "rise" || kind === "pop" || kind === "blur" || kind === "typewriter" ? kind : "rise";
+  return {
+    fx,
+    ...step.unit !== void 0 ? { unit: step.unit } : {},
+    ...step.direction !== void 0 ? { direction: step.direction } : {},
+    ...step.stagger !== void 0 ? { stagger: step.stagger } : {},
+    ...step.seconds !== void 0 ? { duration: step.seconds } : {}
+  };
+}
+var BLOCK_KINDS = /* @__PURE__ */ new Set(["none", "fade", "rise"]);
+function enterKey(clip) {
+  const step = enterOf(clip.anim);
+  if (!step) return "rise";
+  return BLOCK_KINDS.has(step.kind) ? step.kind : "rise";
+}
+function exitKey(clip) {
+  const step = exitOf(clip.anim);
+  if (!step) return "fade";
+  return BLOCK_KINDS.has(step.kind) ? step.kind : "fade";
+}
+function idleKey(clip) {
+  const idle = clip.anim?.idle;
+  return idle === "spin" || idle === "float" ? idle : null;
+}
+function lastLayerEnd(doc) {
+  let end = 0;
+  for (const o of doc.overlays ?? []) end = Math.max(end, o.start + o.duration);
+  for (const o of doc.objects ?? [])
+    if (o.span) end = Math.max(end, o.span.start + o.span.duration);
+  return Number.isFinite(end) && end > 0 ? end : 0;
+}
+
+// src/lower/motion.ts
+import { splitBySpeed, totalDuration } from "@vosjs/timeline";
+function docRestTime(doc) {
+  if (doc.endCard) return null;
+  const last = doc.segments.at(-1);
+  const hold = last?.hold;
+  if (typeof hold !== "number" || !(hold > 0)) return null;
+  const segs = doc.segments.length ? doc.segments : [{ in: 0, out: doc.source.meta.durationMs / 1e3 }];
+  const total = totalDuration(
+    withHolds(segs, splitBySpeed(segs, doc.speed ?? []))
+  );
+  const rest = total - hold;
+  if (!(rest >= 0)) return null;
+  return Math.round(rest * 1e3) / 1e3;
+}
+var ENTRANCE_SECONDS = 1.2;
+var END_CARD_SECONDS = 2.5;
+var END_CARD_RECEDE = 0.7;
+var CARD_FADE_SECONDS = 0.35;
+var TILT_IN_POSE = [-9, 14];
+var PULL_OUT_LEVEL = 1.32;
+var END_CARD_FROM = "endcard";
+var HOLD_SOURCE_SPAN = 2e-3;
+function cardEnter(frame) {
+  return enterOf(frame.anim);
+}
+function cardExit(frame) {
+  return exitOf(frame.anim);
+}
+function entranceSeconds(e) {
+  if (!e || e.kind === "none") return 0;
+  return Math.max(0.2, Math.min(3, e.seconds ?? ENTRANCE_SECONDS));
+}
+function exitSeconds(e) {
+  if (!e || e.kind === "none") return 0;
+  const house = e.kind === "fade" ? CARD_FADE_SECONDS : END_CARD_RECEDE;
+  return Math.max(0.1, Math.min(3, e.seconds ?? house));
+}
+function withHolds(docSegments, rated) {
+  const out = [];
+  const pending = docSegments.filter((s) => typeof s.hold === "number" && s.hold > 0).map((s) => ({ out: s.out, hold: s.hold, used: false }));
+  for (let i = 0; i < rated.length; i++) {
+    const piece = rated[i];
+    out.push(piece);
+    const next = rated[i + 1];
+    for (const p of pending) {
+      if (p.used) continue;
+      const endsHere = Math.abs(piece.out - p.out) < 1e-9;
+      const nextContinues = next && Math.abs(next.in - p.out) < 1e-9 && next.out > p.out;
+      if (endsHere && !nextContinues) {
+        out.push({
+          in: p.out - HOLD_SOURCE_SPAN,
+          out: p.out,
+          rate: HOLD_SOURCE_SPAN / p.hold
+        });
+        p.used = true;
+      }
+    }
+  }
+  return out;
+}
+function entranceTiltKeyframes(e) {
+  const s = entranceSeconds(e);
+  if (!s || e?.kind !== "tilt-in") return [];
+  return [
+    { t: 0, value: [...TILT_IN_POSE], ease: "none" },
+    { t: s, value: [0, 0], ease: "power3.out" }
+  ];
+}
+function entranceZoomKeyframes(e) {
+  const s = entranceSeconds(e);
+  if (!s) return [];
+  if (e?.kind === "pull-out")
+    return [
+      { t: 0, value: [PULL_OUT_LEVEL, 0.5, 0.42], ease: "none" },
+      { t: s, value: [1, 0.5, 0.5], ease: "power3.out" }
+    ];
+  return [
+    { t: 0, value: [1, 0.5, 0.5], ease: "none" },
+    { t: s, value: [1, 0.5, 0.5], ease: "none" }
+  ];
+}
+function prependEntrance(track, head) {
+  if (!head.length) return track;
+  const end = head[head.length - 1].t;
+  const rest = (track?.keyframes ?? []).filter((k) => k.t > end + 0.1);
+  return { keyframes: sortKeyframes([...head, ...rest]) };
+}
+function exitPose(e) {
+  return e?.kind === "fade" ? [1, 0, 0] : [0.9, -0.02, 0.22];
+}
+function cardPoseTrack(enter, exit, footageEnd, outputEnd2 = footageEnd) {
+  const keyframes = [];
+  const s = entranceSeconds(enter);
+  if (s) {
+    const from = enter?.kind === "rise" ? [0.96, 0.08, 0.7] : enter?.kind === "pull-out" || enter?.kind === "fade" ? enter.kind === "fade" ? [1, 0, 0] : [1, 0, 1] : [0.94, 0.05, 0.7];
+    keyframes.push({ t: 0, value: from, ease: "none" });
+    keyframes.push({ t: s, value: [1, 0, 1], ease: "power3.out" });
+  }
+  const x = exitSeconds(exit);
+  if (x > 0 && footageEnd > 0) {
+    const room = outputEnd2 - footageEnd;
+    const t0 = Math.max(s, room > 1e-6 ? footageEnd : footageEnd - x);
+    const t1 = room > 1e-6 ? t0 + Math.min(x, Math.max(0.1, room)) : t0 + x;
+    keyframes.push({ t: t0, value: [1, 0, 1], ease: "none" });
+    keyframes.push({ t: t1, value: exitPose(exit), ease: "power2.out" });
+  }
+  if (!keyframes.length) return void 0;
+  return { keyframes: sortKeyframes(keyframes) };
+}
+function endCardClips(card, doc, endStart) {
+  const seconds = Math.max(1, Math.min(8, card.seconds ?? END_CARD_SECONDS));
+  const anim = { enter: "rise", exit: "none" };
+  const clips = [];
+  const text = (id, body, preset, y, delay) => ({
+    id,
+    kind: "text",
+    text: body,
+    preset,
+    start: endStart + delay,
+    duration: Math.max(0.3, seconds - delay),
+    transform: { x: 0.5, y, scale: 1, rotation: 0 },
+    anim,
+    from: END_CARD_FROM,
+    align: "center",
+    ...card.ink ? { color: card.ink } : {},
+    shadow: 0
+  });
+  if (card.headline?.trim())
+    clips.push(text("endcard-title", card.headline.trim(), "title", 0.44, 0.35));
+  if (card.sub?.trim())
+    clips.push(text("endcard-sub", card.sub.trim(), "caption", 0.57, 0.5));
+  const mark = card.mark;
+  const wide = !!mark && mark.aspect > 2.2;
+  if (mark && mark.key) {
+    const size = resolveExportSize(doc);
+    const designW = 1080 * size.width / Math.max(1, size.height);
+    const hPx = wide ? 44 : 30;
+    const clip = {
+      id: "endcard-markimg",
+      kind: "image",
+      key: mark.key,
+      width: Math.min(0.9, hPx * Math.max(0.2, mark.aspect) / designW),
+      radius: 0,
+      shadow: "none",
+      start: endStart + 0.65,
+      duration: Math.max(0.3, seconds - 0.65),
+      transform: { x: 0.5, y: wide ? 0.88 : 0.835, scale: 1, rotation: 0 },
+      anim,
+      from: END_CARD_FROM
+    };
+    clips.push(clip);
+  }
+  if (card.wordmark?.trim() && !wide)
+    clips.push(
+      text(
+        "endcard-mark",
+        card.wordmark.trim(),
+        "label",
+        mark && mark.key ? 0.895 : 0.88,
+        0.65
+      )
+    );
+  return clips;
+}
+function expandEndCard(doc, outputDuration) {
+  const card = doc.endCard;
+  if (!card || !doc.segments.length) return { doc, endStart: null, seconds: 0 };
+  const seconds = Math.max(1, Math.min(8, card.seconds ?? END_CARD_SECONDS));
+  const segments = doc.segments.map(
+    (s, i) => i === doc.segments.length - 1 ? { ...s, hold: (s.hold ?? 0) + seconds } : s
+  );
+  const endStart = outputDuration;
+  const overlays = [
+    ...doc.overlays ?? [],
+    ...endCardClips(card, doc, endStart)
+  ];
+  return { doc: { ...doc, segments, overlays }, endStart, seconds };
+}
+var hasLegacyClipMotion = (o) => o.enter !== void 0 || o.exit !== void 0 || o.kind === "text" && o.fx !== void 0;
+function migrateClipAnim(o) {
+  const anim = { ...o.anim ?? {} };
+  if (o.kind === "text" && o.fx) {
+    const fx = o.fx;
+    anim.enter = {
+      kind: fx.fx,
+      unit: fx.unit ?? "block",
+      ...fx.direction !== void 0 ? { direction: fx.direction } : {},
+      ...fx.stagger !== void 0 ? { stagger: fx.stagger } : {},
+      ...fx.duration !== void 0 ? { seconds: fx.duration } : {}
+    };
+  } else if (o.enter !== void 0 && anim.enter === void 0) {
+    anim.enter = o.enter;
+  }
+  if (o.exit !== void 0 && anim.exit === void 0) anim.exit = o.exit;
+  return anim;
+}
+function migrateMotion(doc) {
+  const frame = doc.frame ?? {};
+  const segments = Array.isArray(doc.segments) ? doc.segments : [];
+  const overlays = Array.isArray(doc.overlays) ? doc.overlays : [];
+  const objects = Array.isArray(doc.objects) ? doc.objects : [];
+  const legacy = frame.entrance !== void 0 || doc.endCard !== void 0 || overlays.some(hasLegacyClipMotion) || objects.some((o) => o.animation !== void 0);
+  if (!legacy) return doc;
+  const out = { ...doc };
+  const nextFrame = { ...frame };
+  if (frame.entrance !== void 0) {
+    const e = frame.entrance;
+    if (e && e.kind !== "none") {
+      nextFrame.anim = {
+        ...frame.anim ?? {},
+        enter: e.seconds !== void 0 ? { kind: e.kind, seconds: e.seconds } : e.kind
+      };
+    }
+    delete nextFrame.entrance;
+  }
+  let nextOverlays = overlays.map((o) => {
+    if (!hasLegacyClipMotion(o)) return o;
+    const next = { ...o, anim: migrateClipAnim(o) };
+    delete next.enter;
+    delete next.exit;
+    if (next.kind === "text") delete next.fx;
+    return next;
+  });
+  if (doc.endCard !== void 0) {
+    const card = doc.endCard;
+    if (card && segments.length) {
+      const seconds = Math.max(1, Math.min(8, card.seconds ?? END_CARD_SECONDS));
+      const rated = withHolds(segments, splitBySpeed(segments, doc.speed ?? []));
+      const endStart = totalDuration(rated);
+      nextOverlays = [...nextOverlays, ...endCardClips(card, doc, endStart)];
+      nextFrame.anim = {
+        ...nextFrame.anim ?? {},
+        exit: {
+          kind: "recede",
+          seconds: Math.min(END_CARD_RECEDE, seconds * 0.4)
+        }
+      };
+    }
+    delete out.endCard;
+  }
+  const nextObjects = objects.map((o) => {
+    if (o.animation === void 0) return o;
+    const next = {
+      ...o,
+      anim: {
+        ...o.anim ?? {},
+        ...o.anim?.idle === void 0 ? { idle: o.animation ?? null } : {}
+      }
+    };
+    delete next.animation;
+    return next;
+  });
+  if (doc.frame !== void 0 || nextFrame.anim !== void 0)
+    out.frame = nextFrame;
+  if (doc.overlays !== void 0 || nextOverlays.length)
+    out.overlays = nextOverlays;
+  if (doc.objects !== void 0) out.objects = nextObjects;
+  return out;
+}
+function outputEnd(doc, footageEnd) {
+  return Math.max(footageEnd, lastLayerEnd(doc));
+}
+
 // src/docVersion.ts
-var DOC_SCHEMA_VERSION = 2;
+var DOC_SCHEMA_VERSION = 3;
 function migrateHostedDoc(raw) {
   const version = typeof raw.docSchemaVersion === "number" ? raw.docSchemaVersion : 0;
   if (version >= DOC_SCHEMA_VERSION) return raw;
-  return { ...raw, docSchemaVersion: DOC_SCHEMA_VERSION };
+  let doc = raw;
+  if (version < 3 && doc.source && typeof doc.source === "object") {
+    doc = migrateMotion(doc);
+  }
+  return { ...doc, docSchemaVersion: DOC_SCHEMA_VERSION };
 }
 
 // src/doc/studioDoc.ts
@@ -1452,7 +1798,7 @@ function overlaySegments(text, unit) {
 }
 var FX_DIR = { forward: 0, reverse: 1, center: 2 };
 function resolveOverlayFx(clip, clipDuration) {
-  const spec = clip.fx;
+  const spec = overlayFxSpec(clip) ?? clip.fx ?? null;
   if (!spec) return null;
   const unit = spec.unit ?? "block";
   const units = overlaySegments(clip.text, unit);
@@ -2772,164 +3118,6 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
 
 }`;
 
-// src/lower/motion.ts
-import { sortKeyframes } from "@vosjs/timeline";
-import { splitBySpeed, totalDuration } from "@vosjs/timeline";
-function docRestTime(doc) {
-  if (doc.endCard) return null;
-  const last = doc.segments.at(-1);
-  const hold = last?.hold;
-  if (typeof hold !== "number" || !(hold > 0)) return null;
-  const segs = doc.segments.length ? doc.segments : [{ in: 0, out: doc.source.meta.durationMs / 1e3 }];
-  const total = totalDuration(
-    withHolds(segs, splitBySpeed(segs, doc.speed ?? []))
-  );
-  const rest = total - hold;
-  if (!(rest >= 0)) return null;
-  return Math.round(rest * 1e3) / 1e3;
-}
-var ENTRANCE_SECONDS = 1.2;
-var END_CARD_SECONDS = 2.5;
-var END_CARD_RECEDE = 0.7;
-var TILT_IN_POSE = [-9, 14];
-var PULL_OUT_LEVEL = 1.32;
-var HOLD_SOURCE_SPAN = 2e-3;
-function entranceSeconds(e) {
-  if (!e || e.kind === "none") return 0;
-  return Math.max(0.2, Math.min(3, e.seconds ?? ENTRANCE_SECONDS));
-}
-function withHolds(docSegments, rated) {
-  const out = [];
-  const pending = docSegments.filter((s) => typeof s.hold === "number" && s.hold > 0).map((s) => ({ out: s.out, hold: s.hold, used: false }));
-  for (let i = 0; i < rated.length; i++) {
-    const piece = rated[i];
-    out.push(piece);
-    const next = rated[i + 1];
-    for (const p of pending) {
-      if (p.used) continue;
-      const endsHere = Math.abs(piece.out - p.out) < 1e-9;
-      const nextContinues = next && Math.abs(next.in - p.out) < 1e-9 && next.out > p.out;
-      if (endsHere && !nextContinues) {
-        out.push({
-          in: p.out - HOLD_SOURCE_SPAN,
-          out: p.out,
-          rate: HOLD_SOURCE_SPAN / p.hold
-        });
-        p.used = true;
-      }
-    }
-  }
-  return out;
-}
-function entranceTiltKeyframes(e) {
-  const s = entranceSeconds(e);
-  if (!s || e?.kind !== "tilt-in") return [];
-  return [
-    { t: 0, value: [...TILT_IN_POSE], ease: "none" },
-    { t: s, value: [0, 0], ease: "power3.out" }
-  ];
-}
-function entranceZoomKeyframes(e) {
-  const s = entranceSeconds(e);
-  if (!s) return [];
-  if (e?.kind === "pull-out")
-    return [
-      { t: 0, value: [PULL_OUT_LEVEL, 0.5, 0.42], ease: "none" },
-      { t: s, value: [1, 0.5, 0.5], ease: "power3.out" }
-    ];
-  return [
-    { t: 0, value: [1, 0.5, 0.5], ease: "none" },
-    { t: s, value: [1, 0.5, 0.5], ease: "none" }
-  ];
-}
-function prependEntrance(track, head) {
-  if (!head.length) return track;
-  const end = head[head.length - 1].t;
-  const rest = (track?.keyframes ?? []).filter((k) => k.t > end + 0.1);
-  return { keyframes: sortKeyframes([...head, ...rest]) };
-}
-function cardPoseTrack(e, endStart, endSeconds) {
-  const keyframes = [];
-  const s = entranceSeconds(e);
-  if (s) {
-    const from = e?.kind === "rise" ? [0.96, 0.08, 0.7] : e?.kind === "pull-out" ? [1, 0, 1] : [0.94, 0.05, 0.7];
-    keyframes.push({ t: 0, value: from, ease: "none" });
-    keyframes.push({ t: s, value: [1, 0, 1], ease: "power3.out" });
-  }
-  if (endStart !== null && endSeconds > 0) {
-    const t0 = Math.max(endStart, s);
-    keyframes.push({ t: t0, value: [1, 0, 1], ease: "none" });
-    keyframes.push({
-      t: t0 + Math.min(END_CARD_RECEDE, endSeconds * 0.4),
-      value: [0.9, -0.02, 0.22],
-      ease: "power2.out"
-    });
-  }
-  if (!keyframes.length) return void 0;
-  return { keyframes: sortKeyframes(keyframes) };
-}
-function expandEndCard(doc, outputDuration) {
-  const card = doc.endCard;
-  if (!card || !doc.segments.length) return { doc, endStart: null, seconds: 0 };
-  const seconds = Math.max(1, Math.min(8, card.seconds ?? END_CARD_SECONDS));
-  const segments = doc.segments.map(
-    (s, i) => i === doc.segments.length - 1 ? { ...s, hold: (s.hold ?? 0) + seconds } : s
-  );
-  const endStart = outputDuration;
-  const clips = [];
-  const text = (id, body, preset, y, delay) => ({
-    id,
-    kind: "text",
-    text: body,
-    preset,
-    start: endStart + delay,
-    duration: Math.max(0.3, seconds - delay),
-    transform: { x: 0.5, y, scale: 1, rotation: 0 },
-    enter: "rise",
-    exit: "none",
-    align: "center",
-    ...card.ink ? { color: card.ink } : {},
-    shadow: 0
-  });
-  if (card.headline?.trim())
-    clips.push(text("endcard-title", card.headline.trim(), "title", 0.44, 0.35));
-  if (card.sub?.trim())
-    clips.push(text("endcard-sub", card.sub.trim(), "caption", 0.57, 0.5));
-  const mark = card.mark;
-  const wide = !!mark && mark.aspect > 2.2;
-  if (mark && mark.key) {
-    const size = resolveExportSize(doc);
-    const designW = 1080 * size.width / Math.max(1, size.height);
-    const hPx = wide ? 44 : 30;
-    const clip = {
-      id: "endcard-markimg",
-      kind: "image",
-      key: mark.key,
-      width: Math.min(0.9, hPx * Math.max(0.2, mark.aspect) / designW),
-      radius: 0,
-      shadow: "none",
-      start: endStart + 0.65,
-      duration: Math.max(0.3, seconds - 0.65),
-      transform: { x: 0.5, y: wide ? 0.88 : 0.835, scale: 1, rotation: 0 },
-      enter: "rise",
-      exit: "none"
-    };
-    clips.push(clip);
-  }
-  if (card.wordmark?.trim() && !wide)
-    clips.push(
-      text(
-        "endcard-mark",
-        card.wordmark.trim(),
-        "label",
-        mark && mark.key ? 0.895 : 0.88,
-        0.65
-      )
-    );
-  const overlays = [...doc.overlays ?? [], ...clips];
-  return { doc: { ...doc, segments, overlays }, endStart, seconds };
-}
-
 // src/lower/extractClicks.ts
 import { segmentRate, sourceToTimeline } from "@vosjs/timeline";
 var CLICK_FX_PRE = 0.06;
@@ -3772,6 +3960,15 @@ var ON_FRAME = `(ctx, content, dt) => {
   // range); the paused/seek path needs nothing \u2014 mapTime already lands srcT.
   var srcRate = TL.rateAt ? TL.rateAt(d.segments || [], t) : 1
   var playRate = Math.min(16, Math.max(0.0625, srcRate))
+  // Where the FOOTAGE ends in output seconds. The output may outlast it
+  // (clips placed after the footage), and a hold is a freeze piece whose
+  // rate is tiny: in both the element must stay PAUSED on its frame. An
+  // ended element's play() rewinds it to zero and the drift guard then
+  // seeks it back, which reads as frames jumping back and forth; a hold
+  // crawling at the clamped 1/16 speed toward that same end was the same
+  // bug in slow motion.
+  var footEnd = TL.totalDuration ? TL.totalDuration(d.segments || []) : Infinity
+  var frozen = srcRate < 0.01 || t >= footEnd - 1e-3
   // Drive a <video> to the on-screen SOURCE moment: play natively while playing (drift
   // correction covers cut-boundary jumps), else step to the exact frame (registering a
   // decode promise so the deterministic export awaits it). Shared by the screen video
@@ -3779,7 +3976,7 @@ var ON_FRAME = `(ctx, content, dt) => {
   ${FRAME_STEP_SRC}
   function syncVid(vid) {
     try {
-      if (playing) {
+      if (playing && !frozen) {
         if (vid.playbackRate !== playRate) {
           vid.playbackRate = playRate
           // Resampled (tape-style) speed, matching the export's offline mix.
@@ -4622,7 +4819,7 @@ function studioLayerData(layers, duration) {
         ry: round5(o.transform3d.ry),
         rz: round5(o.transform3d.rz),
         scale: round5(o.transform3d.scale || OBJECT_DEFAULT_SCALE),
-        anim: o.animation ?? null,
+        anim: idleKey(o),
         // Pose keyframes: clip-local [x,y,z,rx,ry,rz,scale] track,
         // sampled at t − span.start. Omitted when absent — parity.
         ...(() => {
@@ -4654,8 +4851,8 @@ function studioLayerData(layers, duration) {
           y: round5(o.transform.y),
           scale: round5(o.transform.scale || 1),
           rot: round5(o.transform.rotation || 0),
-          enter: o.enter ?? "rise",
-          exit: o.exit ?? "fade",
+          enter: enterKey(o),
+          exit: exitKey(o),
           // Pose keyframes: a CLIP-LOCAL [x, y, scale, rot, opacity]
           // track, sampled in ON_FRAME at t − start. Omitted when the clip
           // has no motion — data byte parity.
@@ -4743,11 +4940,10 @@ function studioLayerData(layers, duration) {
   };
 }
 function lowerToComposition(input) {
-  const before = durationSec(input, ratedSegments(input));
-  const expanded = expandEndCard(input, before);
-  const doc = expanded.doc;
+  const doc = migrateMotion(input);
   const rated = ratedSegments(doc);
-  const duration = durationSec(doc, rated);
+  const footageEnd = durationSec(doc, rated);
+  const duration = outputEnd(doc, footageEnd);
   const fx = doc.cursor.clickFx;
   const smoothed = smoothCursor(doc.source.cursor, {
     factor: doc.cursor.smoothing,
@@ -4821,7 +5017,7 @@ function lowerToComposition(input) {
     // A pull-out entrance writes the track's head.
     zoomTrack: prependEntrance(
       zoomTrackFromDoc(zoomSpans, rated, zoomStyle),
-      entranceZoomKeyframes(doc.frame.entrance)
+      entranceZoomKeyframes(cardEnter(doc.frame))
     ),
     // Tilt spans: OUTPUT-time [rx, ry] degree track. The rest pose is
     // FLAT — there is no static card tilt any more — and the motion constants
@@ -4830,18 +5026,19 @@ function lowerToComposition(input) {
     // spans and no tilt-in entrance — byte parity. The entrance is a
     // producer of this track, never a second pose.
     ...(() => {
-      const head = entranceTiltKeyframes(doc.frame.entrance);
+      const head = entranceTiltKeyframes(cardEnter(doc.frame));
       const spans = doc.tilt && doc.tilt.length ? tiltTrackFromDoc(doc.tilt, rated, zoomStyle.tilt) : void 0;
       const track = prependEntrance(spans, head);
       return track ? { tiltTrack: track } : {};
     })(),
-    // The card's pose through the entrance and the end card: [scale, dy,
-    // opacity] in output seconds. Absent when neither exists.
+    // The card's pose through its enter and its exit: [scale, dy, opacity]
+    // in output seconds. Absent when the card carries neither.
     ...(() => {
       const track = cardPoseTrack(
-        doc.frame.entrance,
-        expanded.endStart,
-        expanded.seconds
+        cardEnter(doc.frame),
+        cardExit(doc.frame),
+        footageEnd,
+        duration
       );
       return track ? { cardPoseTrack: track } : {};
     })()
@@ -5292,11 +5489,15 @@ function zoomCoversRect(span, rect, layout, tol = 0.02) {
   return rect.x >= w.x0 - tol && rect.x + rect.w <= w.x1 + tol && rect.y >= w.y0 - tol && rect.y + rect.h <= w.y1 + tol;
 }
 
+// src/digest/style.ts
+import { totalDuration as totalDuration4 } from "@vosjs/timeline";
+
 // src/audioBeds.ts
 import { totalDuration as totalDuration3 } from "@vosjs/timeline";
 var round32 = (v) => Math.round(v * 1e3) / 1e3;
 function docOutputDuration(doc) {
-  return totalDuration3(ratedSegments(doc));
+  const footage = totalDuration3(ratedSegments(doc));
+  return isRecordingDoc(doc) ? outputEnd(migrateMotion(doc), footage) : footage;
 }
 function musicBedClip(input) {
   const track = round32(input.trackDuration);
@@ -5418,7 +5619,7 @@ var LAYOUT_FRAME_FIELDS = [
   "focus",
   "focusFollow",
   "parallax",
-  "entrance"
+  "anim"
 ];
 var STAGE_CLIP_PREFIX = "stage-";
 var REST_TILT_ID = "rest";
@@ -5504,6 +5705,99 @@ function copyLayout(from, to, opts = {}) {
   if (typeof hold === "number" && hold > 0 && last) last.hold = hold;
   return { doc, notes };
 }
+var shiftBy = (at, templateEnd, takeEnd) => at === "start" ? 0 : at === "end" ? takeEnd - templateEnd : at;
+function clipsFrom(doc, from) {
+  return {
+    overlays: (doc.overlays ?? []).filter((o) => o.from === from),
+    objects: (doc.objects ?? []).filter((o) => o.from === from),
+    audio: (doc.audio ?? []).filter((a) => a.from === from)
+  };
+}
+function dropTemplate(doc, from) {
+  const has = clipsFrom(doc, from);
+  if (!has.overlays.length && !has.objects.length && !has.audio.length)
+    return doc;
+  const out = { ...doc };
+  if (doc.overlays) out.overlays = doc.overlays.filter((o) => o.from !== from);
+  if (doc.objects) out.objects = doc.objects.filter((o) => o.from !== from);
+  out.audio = doc.audio.filter((a) => a.from !== from);
+  return out;
+}
+function applyTemplate(template, take, opts) {
+  const from = opts.from ?? "template";
+  const notes = [];
+  const base = dropTemplate(take, from);
+  const doc = structuredClone(base);
+  const templateEnd = totalDuration4(ratedSegments(template));
+  const takeEnd = totalDuration4(ratedSegments(take));
+  const shift = shiftBy(opts.at, templateEnd, takeEnd);
+  const own = new Map((take.overlays ?? []).map((o) => [o.id, o]));
+  const overlays = (doc.overlays ?? []).filter(
+    (o) => !(template.overlays ?? []).some((t) => t.id === o.id)
+  );
+  const skipped = [];
+  for (const clip of template.overlays ?? []) {
+    const next = structuredClone(clip);
+    next.start = Math.max(0, round33(clip.start + shift));
+    next.from = from;
+    const mine = own.get(clip.id);
+    if (next.kind === "text") {
+      const word = opts.words?.[clip.id];
+      if (word !== void 0) next.text = word;
+      else if (mine?.kind === "text") next.text = mine.text;
+    } else if (opts.keys?.[clip.id]) {
+      next.key = opts.keys[clip.id];
+    } else if (mine && mine.kind !== "text") {
+      next.key = mine.key;
+    } else if (!/^(https?:|\/\/)/.test(next.key)) {
+      skipped.push(clip.id);
+      continue;
+    }
+    overlays.push(next);
+  }
+  if (skipped.length)
+    notes.push(
+      `${skipped.join(", ")}: the template's media key is its own; pass keys[id] or the take's clip`
+    );
+  if (overlays.length || doc.overlays) doc.overlays = overlays;
+  const objects = (doc.objects ?? []).filter(
+    (o) => !(template.objects ?? []).some((t) => t.id === o.id)
+  );
+  for (const clip of template.objects ?? []) {
+    const next = structuredClone(clip);
+    if (next.span)
+      next.span.start = Math.max(0, round33(next.span.start + shift));
+    next.from = from;
+    objects.push(next);
+  }
+  if (objects.length || doc.objects) doc.objects = objects;
+  const audio = doc.audio.filter(
+    (a) => !template.audio.some((t) => t.id === a.id)
+  );
+  for (const clip of template.audio) {
+    const next = structuredClone(clip);
+    next.start = Math.max(0, round33(clip.start + shift));
+    next.from = from;
+    audio.push(next);
+  }
+  doc.audio = audio;
+  if (template.frame.anim) {
+    doc.frame = {
+      ...doc.frame,
+      anim: { ...doc.frame.anim ?? {}, ...template.frame.anim }
+    };
+  }
+  if (opts.look) {
+    const laid = copyLayout(template, doc, { keys: opts.keys });
+    laid.doc.overlays = (laid.doc.overlays ?? []).map(
+      (o) => isStageClip(o) ? { ...o, from } : o
+    );
+    notes.push(...laid.notes);
+    return { doc: laid.doc, notes };
+  }
+  return { doc, notes };
+}
+var round33 = (v) => Math.round(v * 1e3) / 1e3;
 
 // src/digest/geometry.ts
 var CROP_MIN_FRAC = 0.25;
@@ -5580,7 +5874,6 @@ function cropBox(m, geo, meta) {
 }
 
 // src/digest/build.ts
-import { totalDuration as totalDuration4 } from "@vosjs/timeline";
 var DIGEST_VERSION = 1;
 function buildDigest(input) {
   const { doc, meta } = { doc: input.doc, meta: input.doc.source.meta };
@@ -5648,7 +5941,7 @@ function buildDigest(input) {
   };
 }
 function outputDurationOf(doc) {
-  return totalDuration4(ratedSegments(doc));
+  return docOutputDuration(doc);
 }
 function round8(v) {
   return Math.round(v * 1e3) / 1e3;
@@ -7541,6 +7834,9 @@ export {
   CAM_SPAN_MIN,
   CAPTURE_COVERAGE_MIN,
   CARD_EDGE_OVERDRAW,
+  CARD_ENTER_KINDS,
+  CARD_EXIT_KINDS,
+  CARD_FADE_SECONDS,
   CARD_FOV,
   CARD_Z,
   CHANNEL_SPECS_HASH,
@@ -7579,6 +7875,8 @@ export {
   DIGEST_VERSION,
   DOC_SCHEMA_VERSION,
   DRAG_FIT_LEVEL,
+  END_CARD_FROM,
+  END_CARD_RECEDE,
   END_CARD_SECONDS,
   ENTRANCE_SECONDS,
   EXPORT_RESOLUTION_OPTIONS,
@@ -7589,8 +7887,11 @@ export {
   FRAME_BORDER_DEFAULT,
   FRAME_BORDER_WIDTH_DEFAULT,
   HOUSE_GRADIENT,
+  IDLE_KINDS,
   LAYOUT_FRAME_FIELDS,
   LOOK_KINDS,
+  MEDIA_ENTER_KINDS,
+  MEDIA_EXIT_KINDS,
   MINIMAL_BAR_THEMES,
   MOTION_DELTA,
   MOTION_EASE,
@@ -7621,6 +7922,8 @@ export {
   TEXT3D_DEPTH_DEFAULT,
   TEXT3D_DEPTH_MAX,
   TEXT3D_DEPTH_MIN,
+  TEXT_ENTER_KINDS,
+  TEXT_EXIT_KINDS,
   TEXT_PRESETS,
   TILT_AUTO_DEAD_ZONE,
   TILT_AUTO_MIN,
@@ -7651,7 +7954,9 @@ export {
   ZOOM_STYLE_OPTIONS,
   anchorKindOf,
   anchorSourceDuration,
+  animStep,
   applyLook,
+  applyTemplate,
   aspectRatioValue,
   audioLane,
   backdropMedia,
@@ -7663,6 +7968,8 @@ export {
   camRectFromPose,
   camRestPose,
   camTrackFromDoc,
+  cardEnter,
+  cardExit,
   cardInset,
   cardPointToScreen,
   cardPoseTrack,
@@ -7674,6 +7981,7 @@ export {
   clampZoomLevel,
   clipEnvelope,
   clipLength,
+  clipsFrom,
   computeCardLayout,
   computeMicRms,
   computePeaks,
@@ -7689,11 +7997,18 @@ export {
   docRestTime,
   docToCropSpace,
   docToFullSpace,
+  dropTemplate,
   duckCurve,
   effectiveSegments,
+  endCardClips,
+  enterKey,
+  enterOf,
   entranceSeconds,
   envelopeAt,
   envelopeValueAt,
+  exitKey,
+  exitOf,
+  exitSeconds,
   expandEndCard,
   expectedFrameSize,
   exportSizeFor,
@@ -7704,6 +8019,7 @@ export {
   hexToRgbTriplet,
   houseLook,
   idleGaps,
+  idleKey,
   isLookKind,
   isMusicBed,
   isPlayback,
@@ -7711,6 +8027,8 @@ export {
   isRecordingDoc,
   isRejected,
   isStageClip,
+  isUnitStep,
+  lastLayerEnd,
   layoutOf,
   levelForFocusFraction,
   lookFromBrand,
@@ -7720,6 +8038,7 @@ export {
   lowerToComposition,
   micLane,
   migrateHostedDoc,
+  migrateMotion,
   momentsFromDoc,
   motionTrack,
   musicBedClip,
@@ -7728,11 +8047,13 @@ export {
   objectMotionPoseAt,
   objectsLane,
   outputDurationOf,
+  outputEnd,
   outputRangeToSource,
   overlapFraction,
   overlayFaceFor,
   overlayFontFaces,
   overlayFontString,
+  overlayFxSpec,
   overlayHit,
   overlayLines,
   overlayMotionBase,