@cueframe/kernel 0.1.3 → 0.2.0

package/dist/{chunk-NQSMEUJ6.js → chunk-6XI57FZZ.js}

@@ -20,11 +20,11 @@ import {
   scoreAndRank,
   segmentShots,
   stabilizeSelectionHysteresis
-} from "./chunk-ZPRBGW4Y.js";
+} from "./chunk-LNBVTDFR.js";
 import {
   flattenCompoundClips,
   hasCompoundClips
-} from "./chunk-23HFEKV7.js";
+} from "./chunk-QISFYLBB.js";
 import {
   compositionHasVo,
   roleDefaultGainDb
@@ -36,7 +36,7 @@ import {
 import {
   CueframeError,
   encodeError
-} from "./chunk-AW57IWNW.js";
+} from "./chunk-4FOOBSEE.js";
 
 // ../execution/core/src/render/emphasis.ts
 function buildEmphasisSet(emphasisWords) {
@@ -177,99 +177,276 @@ function resolveBookendTimeline(brandKit, bodyFrames, fps) {
   };
 }
 
-// ../execution/core/src/render/compositionRender.ts
-function projectClipEffects(clip, renderClipId) {
-  const effects = clip.effects;
-  if (!effects || effects.length === 0) return [];
-  return effects.map((e, idx) => ({
-    id: `${renderClipId}::effect:${idx}`,
-    primitiveId: e.primitiveId,
-    params: e.params ?? {},
-    target: { kind: "clip", clipId: renderClipId }
-  }));
-}
-function compositionFormatDimensions(format) {
-  const fps = format.fps ?? 30;
-  const resolution = format.resolution ?? "fhd";
-  const dims = {
-    "9:16": {
-      hd: { width: 720, height: 1280 },
-      fhd: { width: 1080, height: 1920 },
-      "4k": { width: 2160, height: 3840 }
-    },
-    "1:1": {
-      hd: { width: 720, height: 720 },
-      fhd: { width: 1080, height: 1080 },
-      "4k": { width: 2160, height: 2160 }
-    },
-    "4:5": {
-      hd: { width: 720, height: 900 },
-      fhd: { width: 1080, height: 1350 },
-      "4k": { width: 2160, height: 2700 }
-    },
-    "16:9": {
-      hd: { width: 1280, height: 720 },
-      fhd: { width: 1920, height: 1080 },
-      "4k": { width: 3840, height: 2160 }
-    }
-  };
-  return { ...dims[format.aspectRatio][resolution], fps };
+// ../execution/core/src/render/compositionValidation.ts
+function renderInputError(code, message, locator) {
+  return new CueframeError(code, message, void 0, locator);
 }
 function validateComposition(raw) {
   if (!raw || typeof raw !== "object") {
-    throw new Error("composition: expected object, got " + typeof raw);
+    throw renderInputError("invalid_composition", "composition: expected object, got " + typeof raw, {
+      compositionPath: "composition"
+    });
   }
   const obj = raw;
   if (obj.v !== 1) {
-    throw new Error("composition.v: expected literal 1");
+    throw renderInputError("invalid_composition", "composition.v: expected literal 1", {
+      compositionPath: "composition.v"
+    });
   }
   const fmt = obj.format;
   if (!fmt || typeof fmt.aspectRatio !== "string") {
-    throw new Error("composition.format.aspectRatio: required string");
+    throw renderInputError("invalid_composition", "composition.format.aspectRatio: required string", {
+      compositionPath: "composition.format.aspectRatio"
+    });
   }
   if (!Array.isArray(obj.tracks)) {
-    throw new Error("composition.tracks: expected array");
+    throw renderInputError("invalid_composition", "composition.tracks: expected array", {
+      compositionPath: "composition.tracks"
+    });
   }
   for (let i = 0; i < obj.tracks.length; i++) {
     const t = obj.tracks[i];
     if (!t || typeof t !== "object") {
-      throw new Error(`composition.tracks[${i}]: expected object`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}]: expected object`, {
+        compositionPath: `composition.tracks[${i}]`
+      });
     }
     if (typeof t.id !== "string") {
-      throw new Error(`composition.tracks[${i}].id: expected string`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}].id: expected string`, {
+        compositionPath: `composition.tracks[${i}].id`
+      });
     }
     if (!["video", "audio", "image", "overlay", "effect"].includes(t.kind)) {
-      throw new Error(`composition.tracks[${i}].kind: invalid value`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}].kind: invalid value`, {
+        compositionPath: `composition.tracks[${i}].kind`,
+        ...typeof t.id === "string" ? { trackId: t.id } : {}
+      });
     }
     if (!Array.isArray(t.contents)) {
-      throw new Error(`composition.tracks[${i}].contents: expected array`);
+      throw renderInputError("invalid_composition", `composition.tracks[${i}].contents: expected array`, {
+        compositionPath: `composition.tracks[${i}].contents`,
+        trackId: t.id
+      });
     }
   }
   if (obj.markers !== void 0 && !Array.isArray(obj.markers)) {
-    throw new Error("composition.markers: expected array when present");
+    throw renderInputError("invalid_composition", "composition.markers: expected array when present", {
+      compositionPath: "composition.markers"
+    });
   }
   if (obj.captions !== void 0) {
     const c = obj.captions;
     if (!c || typeof c !== "object") {
-      throw new Error("composition.captions: expected object when present");
+      throw renderInputError("invalid_composition", "composition.captions: expected object when present", {
+        compositionPath: "composition.captions"
+      });
     }
     if (!Array.isArray(c.segments)) {
-      throw new Error("composition.captions.segments: expected array");
+      throw renderInputError("invalid_composition", "composition.captions.segments: expected array", {
+        compositionPath: "composition.captions.segments"
+      });
     }
     if (c.style !== void 0 && (typeof c.style !== "object" || c.style === null)) {
-      throw new Error("composition.captions.style: expected object when present");
+      throw renderInputError("invalid_composition", "composition.captions.style: expected object when present", {
+        compositionPath: "composition.captions.style"
+      });
     }
     if (c.style !== void 0) {
-      const fs = c.style.fontSize;
-      if (fs !== void 0 && (typeof fs !== "number" || fs < 1 || fs > 15)) {
-        throw new Error(
-          `composition.captions.style.fontSize: PERCENT of composition height (1-15, default 5) \u2014 got ${String(fs)}. px values are not accepted; a px-intent value renders giant band-overflowing captions. Re-author the style with a percent value.`
+      const fontSize = c.style.fontSize;
+      if (fontSize !== void 0 && (typeof fontSize !== "number" || fontSize < 1 || fontSize > 15)) {
+        throw renderInputError(
+          "invalid_composition",
+          `composition.captions.style.fontSize: PERCENT of composition height (1-15, default 5) \u2014 got ${String(fontSize)}. px values are not accepted; a px-intent value renders giant band-overflowing captions. Re-author the style with a percent value.`,
+          { compositionPath: "composition.captions.style.fontSize" }
         );
       }
     }
   }
   return obj;
 }
+
+// ../execution/core/src/render/compositionAudioAndDepth.ts
+function buildCaptionSpeechSpans(composition, fps) {
+  const words = (composition.captions?.segments ?? []).flatMap((seg) => seg.words).filter((w) => w.endMs > w.startMs).sort((a, b) => a.startMs - b.startMs);
+  if (words.length === 0) return [];
+  const MERGE_GAP_MS = 300;
+  const MIN_SPAN_MS = 200;
+  const spans = [];
+  let cur = { startMs: words[0].startMs, endMs: words[0].endMs };
+  for (let i = 1; i < words.length; i++) {
+    const w = words[i];
+    if (w.startMs - cur.endMs < MERGE_GAP_MS) {
+      if (w.endMs > cur.endMs) cur.endMs = w.endMs;
+    } else {
+      spans.push(cur);
+      cur = { startMs: w.startMs, endMs: w.endMs };
+    }
+  }
+  spans.push(cur);
+  return spans.filter((s) => s.endMs - s.startMs >= MIN_SPAN_MS).map((s) => ({
+    startFrame: Math.round(s.startMs / 1e3 * fps),
+    endFrame: Math.round(s.endMs / 1e3 * fps)
+  }));
+}
+function applyRoleDefaultGains(audioTracks, composition) {
+  let voPresent;
+  for (const track of composition.tracks) {
+    if (track.kind !== "audio" || track.enabled === false) continue;
+    for (const c of track.contents) {
+      if (!("source" in c)) continue;
+      const src = c.source;
+      if (src.kind !== "media") continue;
+      const role = src.audioRole;
+      if (!role) continue;
+      if (src.volumeDb !== void 0 || src.volume !== void 0) continue;
+      if (voPresent === void 0) voPresent = compositionHasVo(composition);
+      const gain = Math.pow(10, roleDefaultGainDb(role, voPresent) / 20);
+      for (const t of audioTracks) {
+        if (t.id === c.id || t.id.startsWith(`${c.id}#`)) t.volume = gain;
+      }
+    }
+  }
+}
+function applyDuckEnvelopes(audioTracks, composition, fps) {
+  const captionSpansFrames = buildCaptionSpeechSpans(composition, fps);
+  for (const track of composition.tracks) {
+    if (track.kind !== "audio" || track.enabled === false) continue;
+    for (const c of track.contents) {
+      if (!("source" in c)) continue;
+      const src = c.source;
+      if (src.kind !== "media") continue;
+      const duck = src.duck;
+      const role = src.audioRole;
+      if (!duck || role !== "music" && role !== "vo") continue;
+      const absWindows = duck.windows && duck.windows.length > 0 ? duck.windows.map((w) => ({
+        startFrame: Math.round(w.startMs / 1e3 * fps),
+        endFrame: Math.round(w.endMs / 1e3 * fps)
+      })) : captionSpansFrames;
+      if (absWindows.length === 0) continue;
+      const duckVolume = Math.pow(10, duck.duckDb / 20);
+      const attackFrames = Math.max(0, Math.round(duck.attackMs / 1e3 * fps));
+      const releaseFrames = Math.max(0, Math.round(duck.releaseMs / 1e3 * fps));
+      for (const t of audioTracks) {
+        if (t.id !== c.id && !t.id.startsWith(`${c.id}#`)) continue;
+        const rel = [];
+        for (const w of absWindows) {
+          const s = Math.max(0, w.startFrame - t.startFrame);
+          const e = Math.min(t.durationInFrames, w.endFrame - t.startFrame);
+          if (e > s) rel.push({ startFrame: s, endFrame: e });
+        }
+        if (rel.length === 0) continue;
+        t.duckWindows = rel;
+        t.duckVolume = duckVolume;
+        t.duckAttackFrames = attackFrames;
+        t.duckReleaseFrames = releaseFrames;
+      }
+    }
+  }
+}
+function bindBehindSubjectHosts(overlays, clips) {
+  const packedClips = clips.filter((clip) => clip.packedUrl !== void 0);
+  for (const overlay of overlays) {
+    if (overlay.zPlane !== "behind-subject") continue;
+    const overlayEnd = overlay.startFrame + overlay.durationInFrames;
+    const covering = packedClips.filter((clip) => {
+      const clipEnd = clip.timelineStartFrames + clip.durationInFrames;
+      return clip.timelineStartFrames <= overlay.startFrame && clipEnd >= overlayEnd;
+    });
+    if (covering.length === 1) {
+      overlay.hostClipId = covering[0].id;
+      continue;
+    }
+    const overlapping = packedClips.filter((clip) => {
+      const clipEnd = clip.timelineStartFrames + clip.durationInFrames;
+      return clip.timelineStartFrames < overlayEnd && clipEnd > overlay.startFrame;
+    });
+    const candidates = covering.length > 1 ? covering : overlapping;
+    const code = candidates.length > 1 ? "behind_subject_host_ambiguous" : "behind_subject_host_missing";
+    throw renderInputError(
+      code,
+      candidates.length > 1 ? `Behind-subject overlay '${overlay.id}' is covered by multiple packed clips (${candidates.map((clip) => clip.id).join(", ")}); host selection must be unambiguous.` : `Behind-subject overlay '${overlay.id}' is not fully covered by one packed clip; bake an exact matte for its host interval.`,
+      {
+        trackId: overlay.trackId,
+        clipId: overlay.id,
+        compositionPath: `composition.tracks[${overlay.trackId}]`,
+        candidateClipIds: candidates.map((clip) => clip.id)
+      }
+    );
+  }
+}
+function assertBehindSubjectCaptionCoverage(captionSegments, clips, fps) {
+  const packed = clips.filter((clip) => clip.packedUrl !== void 0);
+  for (const segment of captionSegments ?? []) {
+    for (const word of segment) {
+      const startFrame = Math.round(word.startMs / 1e3 * fps);
+      const endFrame = Math.max(startFrame + 1, Math.round(word.endMs / 1e3 * fps));
+      const covering = packed.filter((clip) => {
+        const clipEnd = clip.timelineStartFrames + clip.durationInFrames;
+        return clip.timelineStartFrames <= startFrame && clipEnd >= endFrame;
+      });
+      if (covering.length === 1) continue;
+      const overlapping = packed.filter((clip) => {
+        const clipEnd = clip.timelineStartFrames + clip.durationInFrames;
+        return clip.timelineStartFrames < endFrame && clipEnd > startFrame;
+      });
+      const candidates = covering.length > 1 ? covering : overlapping;
+      const code = candidates.length > 1 ? "behind_subject_caption_host_ambiguous" : "behind_subject_caption_host_missing";
+      throw renderInputError(
+        code,
+        candidates.length > 1 ? `Behind-subject caption word '${word.text}' is covered by multiple packed clips (${candidates.map((clip) => clip.id).join(", ")}).` : `Behind-subject caption word '${word.text}' is not fully covered by one packed clip; an exact matte is required for its entire interval.`,
+        { candidateClipIds: candidates.map((clip) => clip.id), startFrame, endFrame }
+      );
+    }
+  }
+}
+
+// ../execution/core/src/render/compositionRender.ts
+function projectClipEffects(clip, renderClipId, identity) {
+  const effects = clip.effects;
+  if (!effects || effects.length === 0) return [];
+  return effects.map((e, idx) => ({
+    ...identity,
+    id: `${renderClipId}::effect:${idx}`,
+    primitiveId: e.primitiveId,
+    params: e.params ?? {},
+    target: { kind: "clip", clipId: renderClipId }
+  }));
+}
+function visualIdentity(track, trackIndex, trackCount, contentIndex) {
+  return {
+    trackId: track.id,
+    trackIndex,
+    layerIndex: trackCount - trackIndex,
+    contentIndex
+  };
+}
+function compositionFormatDimensions(format) {
+  const fps = format.fps ?? 30;
+  const resolution = format.resolution ?? "fhd";
+  const dims = {
+    "9:16": {
+      hd: { width: 720, height: 1280 },
+      fhd: { width: 1080, height: 1920 },
+      "4k": { width: 2160, height: 3840 }
+    },
+    "1:1": {
+      hd: { width: 720, height: 720 },
+      fhd: { width: 1080, height: 1080 },
+      "4k": { width: 2160, height: 2160 }
+    },
+    "4:5": {
+      hd: { width: 720, height: 900 },
+      fhd: { width: 1080, height: 1350 },
+      "4k": { width: 2160, height: 2700 }
+    },
+    "16:9": {
+      hd: { width: 1280, height: 720 },
+      fhd: { width: 1920, height: 1080 },
+      "4k": { width: 3840, height: 2160 }
+    }
+  };
+  return { ...dims[format.aspectRatio][resolution], fps };
+}
 function frames(seconds, fps) {
   return Math.max(0, Math.round(seconds * fps));
 }
@@ -299,11 +476,13 @@ function overlayTransitionFields(c, fps) {
 function rendersNoFrames(c) {
   return !(c.duration > 0);
 }
-function resolveSrcUrl(mediaId, srcUrls) {
+function resolveSrcUrl(mediaId, srcUrls, locator) {
   const url = srcUrls[mediaId];
   if (!url) {
-    throw new Error(
-      `Composition references mediaId '${mediaId}' but no presigned URL was supplied. Pre-sign every unique mediaId before calling compositionToRenderInput.`
+    throw renderInputError(
+      "source_media_not_found",
+      `Composition references mediaId '${mediaId}' but no presigned URL was supplied. Pre-sign every unique mediaId before calling compositionToRenderInput.`,
+      { ...locator, mediaId }
     );
   }
   return url;
@@ -321,7 +500,7 @@ function playableSpans(trimStart, trimEnd, excluded) {
   if (cursor < trimEnd) out.push({ start: cursor, end: trimEnd });
   return out;
 }
-function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, trajectories) {
+function projectMediaTrack(track, trackIndex, trackCount, fps, srcUrls, trajectoryUrls, coViewUrls, trajectories) {
   const clips = [];
   const audio = [];
   const effects = [];
@@ -329,15 +508,38 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
     if (c.source.kind !== "media") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on a ${track.kind} track (expected 'media')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on a ${track.kind} track (expected 'media')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     if (rendersNoFrames(c)) continue;
-    const src = resolveSrcUrl(c.source.mediaId, srcUrls);
-    if (coViewUrls?.[c.source.mediaId] !== void 0 && c.region !== void 0 && !(c.region.x === 0 && c.region.y === 0 && c.region.w === 1 && c.region.h === 1)) {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}] (clip ${c.id}): a co-view clip (captions-behind-subject) cannot also carry a sub-frame region \u2014 the co-view render path does not honor region. Use one or the other.`
+    const src = resolveSrcUrl(c.source.mediaId, srcUrls, {
+      trackId: track.id,
+      clipId: c.id,
+      compositionPath: `composition.tracks[${track.id}].contents[${i}].source.mediaId`
+    });
+    const packedUrl = coViewUrls?.[c.id];
+    const packedEnvelopeFields = packedUrl === void 0 ? [] : [
+      c.region !== void 0 && !(c.region.x === 0 && c.region.y === 0 && c.region.w === 1 && c.region.h === 1) ? "region" : null,
+      c.fit !== void 0 && c.fit !== "cover" ? "fit" : null,
+      c.opacity !== void 0 && c.opacity !== 1 ? "opacity" : null,
+      c.scale !== void 0 && c.scale !== 1 ? "scale" : null,
+      c.rotation !== void 0 && c.rotation !== 0 ? "rotation" : null,
+      c.animate !== void 0 ? "animate" : null,
+      c.transitionIn !== void 0 && c.transitionIn.type !== "none" && c.transitionIn.type !== "cut" ? "transitionIn" : null
+    ].filter((field) => field !== null);
+    if (packedEnvelopeFields.length > 0) {
+      throw renderInputError(
+        "packed_visual_envelope_unsupported",
+        `composition.tracks[${track.id}].contents[${i}] (clip ${c.id}): the packed co-view render path cannot yet preserve ${packedEnvelopeFields.join(", ")}. Remove those fields or render without behind-subject depth; ignoring them would produce false evidence.`,
+        {
+          trackId: track.id,
+          clipId: c.id,
+          compositionPath: `composition.tracks[${track.id}].contents[${i}]`,
+          fields: packedEnvelopeFields
+        }
       );
     }
     if (track.kind === "audio") {
@@ -389,7 +591,9 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
       const subId = spans.length === 1 ? c.id : `${c.id}#${s}`;
       if (firstEmittedSubId === void 0) firstEmittedSubId = subId;
       clips.push({
+        ...visualIdentity(track, trackIndex, trackCount, i),
         id: subId,
+        ...spans.length > 1 ? { parentId: c.id } : {},
         src,
         sourceInFrames,
         sourceOutFrames: sourceInFrames + subDurationFrames,
@@ -412,44 +616,38 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
         } : {},
         ...trajectoryUrls?.[c.id] !== void 0 ? { cropTrajectoryUrl: trajectoryUrls[c.id] } : {},
         ...trajectories?.[c.id] !== void 0 ? { cropTrajectory: trajectories[c.id] } : {},
-        ...coViewUrls?.[c.source.mediaId] !== void 0 ? { packedUrl: coViewUrls[c.source.mediaId] } : {}
+        ...packedUrl !== void 0 ? { packedUrl } : {}
       });
     }
     if (firstEmittedSubId !== void 0) {
-      effects.push(...projectClipEffects(c, firstEmittedSubId));
+      effects.push(...projectClipEffects(
+        c,
+        firstEmittedSubId,
+        visualIdentity(track, trackIndex, trackCount, i)
+      ));
     }
   }
-  for (let i = 1; i < clips.length; i++) {
-    const prev = clips[i - 1];
-    const cur = clips[i];
-    if (prev.src !== cur.src) continue;
-    if ((prev.playbackRate ?? 1) !== (cur.playbackRate ?? 1)) continue;
-    if (JSON.stringify(prev.region) !== JSON.stringify(cur.region)) continue;
-    if ((prev.fit ?? "cover") !== (cur.fit ?? "cover")) continue;
-    if (prev.cropTrajectoryUrl !== cur.cropTrajectoryUrl) continue;
-    if (prev.cropTrajectory !== cur.cropTrajectory) continue;
-    if ((prev.trimStartFrames ?? 0) !== (cur.trimStartFrames ?? 0)) continue;
-    const prevEnd = prev.timelineStartFrames + prev.durationInFrames;
-    if (Math.abs(prevEnd - cur.timelineStartFrames) > 1) continue;
-    const parent = prev.parentId ?? prev.id;
-    cur.parentId = parent;
-    if (prev.parentId === void 0) prev.parentId = parent;
-  }
   return { clips, audio, effects };
 }
-function projectImageTrack(track, fps, srcUrls) {
+function projectImageTrack(track, trackIndex, trackCount, fps, srcUrls) {
   const clips = [];
   const effects = [];
   for (let i = 0; i < track.contents.length; i++) {
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
     if (c.source.kind !== "media") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an image track (expected 'media')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an image track (expected 'media')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     if (rendersNoFrames(c)) continue;
-    const src = resolveSrcUrl(c.source.mediaId, srcUrls);
+    const src = resolveSrcUrl(c.source.mediaId, srcUrls, {
+      trackId: track.id,
+      clipId: c.id,
+      compositionPath: `composition.tracks[${track.id}].contents[${i}].source.mediaId`
+    });
     const { startFrame: timelineStartFrames, durationInFrames } = timelineSpanFrames(
       c.startTime,
       c.startTime + c.duration,
@@ -457,6 +655,7 @@ function projectImageTrack(track, fps, srcUrls) {
     );
     if (durationInFrames === 0) continue;
     clips.push({
+      ...visualIdentity(track, trackIndex, trackCount, i),
       id: c.id,
       src,
       sourceInFrames: 0,
@@ -473,7 +672,11 @@ function projectImageTrack(track, fps, srcUrls) {
       ...c.region !== void 0 ? { region: c.region } : {},
       ...c.fit !== void 0 ? { fit: c.fit } : {}
     });
-    effects.push(...projectClipEffects(c, c.id));
+    effects.push(...projectClipEffects(
+      c,
+      c.id,
+      visualIdentity(track, trackIndex, trackCount, i)
+    ));
   }
   return { clips, effects };
 }
@@ -487,11 +690,18 @@ function clipTransformChannel(c) {
     ...c.animate !== void 0 ? { animate: c.animate } : {}
   };
 }
-function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {}) {
+function projectOverlayTrack(track, trackIndex, trackCount, fps, alphaUrls = {}) {
   const overlays = [];
   for (let i = 0; i < track.contents.length; i++) {
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
+    if (c.effects && c.effects.length > 0) {
+      throw renderInputError(
+        "clip_effect_scope_unsupported",
+        `Overlay clip '${c.id}' has clip effects that cannot yet preserve the overlay alpha/region envelope. Move the effect to an effect track or remove it.`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].effects` }
+      );
+    }
     if (c.source.kind === "alpha-layer") {
       const { startFrame: startFrame2, durationInFrames: durationInFrames2 } = timelineSpanFrames(
         c.startTime,
@@ -501,11 +711,19 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       if (durationInFrames2 === 0) continue;
       const src = alphaUrls[c.id];
       if (!src) {
-        throw new Error(
-          `composition.tracks[${track.id}].contents[${i}]: alpha-layer clip ${c.id} has no baked alpha (alphaUrls[${c.id}] missing) \u2014 bake before render`
+        throw renderInputError(
+          "variant_not_baked",
+          `composition.tracks[${track.id}].contents[${i}]: alpha-layer clip ${c.id} has no baked alpha (alphaUrls[${c.id}] missing) \u2014 bake before render`,
+          {
+            trackId: track.id,
+            clipId: c.id,
+            componentId: c.source.componentId,
+            compositionPath: `composition.tracks[${track.id}].contents[${i}].source`
+          }
         );
       }
       overlays.push({
+        ...visualIdentity(track, trackIndex, trackCount, i),
         id: c.id,
         template: "alpha-layer",
         startFrame: startFrame2,
@@ -527,6 +745,7 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       );
       if (durationInFrames2 === 0) continue;
       overlays.push({
+        ...visualIdentity(track, trackIndex, trackCount, i),
         id: c.id,
         template: "card",
         startFrame: startFrame2,
@@ -544,8 +763,10 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       continue;
     }
     if (c.source.kind !== "overlay") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an overlay track (expected 'overlay', 'alpha-layer', or 'card')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an overlay track (expected 'overlay', 'alpha-layer', or 'card')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     const { startFrame, durationInFrames } = timelineSpanFrames(
@@ -556,19 +777,14 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
     if (durationInFrames === 0) continue;
     let overlayParams = c.source.params ?? {};
     if (c.source.primitiveId === "custom") {
-      const fresh = jsSourceByClipId[c.id];
-      const sc = typeof fresh === "string" && fresh.length > 0 ? fresh : overlayParams.sourceCode;
-      if (typeof sc !== "string" || sc.length === 0) {
-        throw new Error(
-          `composition.tracks[${track.id}].contents[${i}].source: custom overlay has no sourceCode (no fresh jsSource for clip '${c.id}' and no inline params.sourceCode) \u2014 mirror code 'custom_missing_sourcecode'`
-        );
-      }
-      const { componentId: _cid, sourceCode: _sc, ...props } = overlayParams;
-      void _cid;
-      void _sc;
-      overlayParams = { sourceCode: sc, ...props };
+      throw renderInputError(
+        "invalid_composition",
+        `composition.tracks[${track.id}].contents[${i}].source: custom overlays must be baked to a verified alpha-layer before rendering`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
+      );
     }
     overlays.push({
+      ...visualIdentity(track, trackIndex, trackCount, i),
       id: c.id,
       template: c.source.primitiveId,
       startFrame,
@@ -585,14 +801,16 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
   }
   return overlays;
 }
-function projectEffectTrack(track, fps) {
+function projectEffectTrack(track, trackIndex, trackCount, fps) {
   const effects = [];
   for (let i = 0; i < track.contents.length; i++) {
     const c = track.contents[i];
     if (!("source" in c) || !c.source) continue;
     if (c.source.kind !== "effect") {
-      throw new Error(
-        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an effect track (expected 'effect')`
+      throw renderInputError(
+        "clip_source_track_mismatch",
+        `composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an effect track (expected 'effect')`,
+        { trackId: track.id, clipId: c.id, compositionPath: `composition.tracks[${track.id}].contents[${i}].source` }
       );
     }
     const { startFrame, durationInFrames } = timelineSpanFrames(
@@ -602,6 +820,7 @@ function projectEffectTrack(track, fps) {
     );
     if (durationInFrames === 0) continue;
     effects.push({
+      ...visualIdentity(track, trackIndex, trackCount, i),
       id: c.id,
       primitiveId: c.source.primitiveId,
       params: c.source.params ?? {},
@@ -612,83 +831,6 @@ function projectEffectTrack(track, fps) {
   }
   return effects;
 }
-function buildCaptionSpeechSpans(composition, fps) {
-  const words = (composition.captions?.segments ?? []).flatMap((seg) => seg.words).filter((w) => w.endMs > w.startMs).sort((a, b) => a.startMs - b.startMs);
-  if (words.length === 0) return [];
-  const MERGE_GAP_MS = 300;
-  const MIN_SPAN_MS = 200;
-  const spans = [];
-  let cur = { startMs: words[0].startMs, endMs: words[0].endMs };
-  for (let i = 1; i < words.length; i++) {
-    const w = words[i];
-    if (w.startMs - cur.endMs < MERGE_GAP_MS) {
-      if (w.endMs > cur.endMs) cur.endMs = w.endMs;
-    } else {
-      spans.push(cur);
-      cur = { startMs: w.startMs, endMs: w.endMs };
-    }
-  }
-  spans.push(cur);
-  return spans.filter((s) => s.endMs - s.startMs >= MIN_SPAN_MS).map((s) => ({
-    startFrame: Math.round(s.startMs / 1e3 * fps),
-    endFrame: Math.round(s.endMs / 1e3 * fps)
-  }));
-}
-function applyRoleDefaultGains(audioTracks, composition) {
-  let voPresent;
-  for (const track of composition.tracks) {
-    if (track.kind !== "audio" || track.enabled === false) continue;
-    for (const c of track.contents) {
-      if (!("source" in c)) continue;
-      const src = c.source;
-      if (src.kind !== "media") continue;
-      const role = src.audioRole;
-      if (!role) continue;
-      if (src.volumeDb !== void 0 || src.volume !== void 0) continue;
-      if (voPresent === void 0) voPresent = compositionHasVo(composition);
-      const gain = Math.pow(10, roleDefaultGainDb(role, voPresent) / 20);
-      for (const t of audioTracks) {
-        if (t.id === c.id || t.id.startsWith(`${c.id}#`)) t.volume = gain;
-      }
-    }
-  }
-}
-function applyDuckEnvelopes(audioTracks, composition, fps) {
-  const captionSpansFrames = buildCaptionSpeechSpans(composition, fps);
-  for (const track of composition.tracks) {
-    if (track.kind !== "audio" || track.enabled === false) continue;
-    for (const c of track.contents) {
-      if (!("source" in c)) continue;
-      const src = c.source;
-      if (src.kind !== "media") continue;
-      const duck = src.duck;
-      const role = src.audioRole;
-      if (!duck || role !== "music" && role !== "vo") continue;
-      const absWindows = duck.windows && duck.windows.length > 0 ? duck.windows.map((w) => ({
-        startFrame: Math.round(w.startMs / 1e3 * fps),
-        endFrame: Math.round(w.endMs / 1e3 * fps)
-      })) : captionSpansFrames;
-      if (absWindows.length === 0) continue;
-      const duckVolume = Math.pow(10, duck.duckDb / 20);
-      const attackFrames = Math.max(0, Math.round(duck.attackMs / 1e3 * fps));
-      const releaseFrames = Math.max(0, Math.round(duck.releaseMs / 1e3 * fps));
-      for (const t of audioTracks) {
-        if (t.id !== c.id && !t.id.startsWith(`${c.id}#`)) continue;
-        const rel = [];
-        for (const w of absWindows) {
-          const s = Math.max(0, w.startFrame - t.startFrame);
-          const e = Math.min(t.durationInFrames, w.endFrame - t.startFrame);
-          if (e > s) rel.push({ startFrame: s, endFrame: e });
-        }
-        if (rel.length === 0) continue;
-        t.duckWindows = rel;
-        t.duckVolume = duckVolume;
-        t.duckAttackFrames = attackFrames;
-        t.duckReleaseFrames = releaseFrames;
-      }
-    }
-  }
-}
 function referencedMediaIds(composition) {
   const ids = /* @__PURE__ */ new Set();
   for (const track of composition.tracks) {
@@ -701,24 +843,7 @@ function referencedMediaIds(composition) {
   }
   return [...ids];
 }
-function componentRefsByClipId(composition) {
-  const refs = {};
-  for (const track of composition.tracks) {
-    if (track.kind !== "overlay") continue;
-    for (const c of track.contents) {
-      if (!("source" in c) || !c.source) continue;
-      const src = c.source;
-      if (src.kind !== "overlay" || src.primitiveId !== "custom") continue;
-      const params = src.params ?? {};
-      if (typeof params.sourceCode === "string" && params.sourceCode.length > 0) continue;
-      if (typeof params.componentId === "string" && params.componentId.length > 0) {
-        refs[c.id] = params.componentId;
-      }
-    }
-  }
-  return refs;
-}
-function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUrls, alphaUrls, jsSourceByClipId, subCompositions, trajectories) {
+function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUrls, alphaUrls, subCompositions, trajectories) {
   const flattened = hasCompoundClips(composition) ? flattenCompoundClips(composition, (id) => subCompositions?.[id]) : composition;
   composition = flattened;
   const { width, height, fps } = compositionFormatDimensions(composition.format);
@@ -726,23 +851,46 @@ function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUr
   const overlays = [];
   const audioTracks = [];
   const effects = [];
-  for (const track of composition.tracks) {
+  const trackCount = composition.tracks.length;
+  for (const [trackIndex, track] of composition.tracks.entries()) {
     if (track.enabled === false) continue;
     if (track.kind === "video" || track.kind === "audio") {
-      const { clips: c, audio, effects: clipEffects } = projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, trajectories);
+      const { clips: c, audio, effects: clipEffects } = projectMediaTrack(
+        track,
+        trackIndex,
+        trackCount,
+        fps,
+        srcUrls,
+        trajectoryUrls,
+        coViewUrls,
+        trajectories
+      );
       clips.push(...c);
       audioTracks.push(...audio);
       effects.push(...clipEffects);
     } else if (track.kind === "image") {
-      const { clips: c, effects: clipEffects } = projectImageTrack(track, fps, srcUrls);
+      const { clips: c, effects: clipEffects } = projectImageTrack(
+        track,
+        trackIndex,
+        trackCount,
+        fps,
+        srcUrls
+      );
       clips.push(...c);
       effects.push(...clipEffects);
     } else if (track.kind === "overlay") {
-      overlays.push(...projectOverlayTrack(track, fps, alphaUrls ?? {}, jsSourceByClipId ?? {}));
+      overlays.push(...projectOverlayTrack(
+        track,
+        trackIndex,
+        trackCount,
+        fps,
+        alphaUrls ?? {}
+      ));
     } else if (track.kind === "effect") {
-      effects.push(...projectEffectTrack(track, fps));
+      effects.push(...projectEffectTrack(track, trackIndex, trackCount, fps));
     }
   }
+  bindBehindSubjectHosts(overlays, clips);
   if (audioTracks.length > 0) {
     applyRoleDefaultGains(audioTracks, composition);
   }
@@ -773,6 +921,9 @@ function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUr
   }
   const bodyDurationInFrames = maxBackgroundEndFrames > 0 ? Math.min(maxEndFrames, maxBackgroundEndFrames) : maxEndFrames;
   const captionSegments = composition.captions?.segments.map((seg) => seg.words).filter((words) => words.length > 0);
+  if (composition.captions?.zPlane === "behind-subject") {
+    assertBehindSubjectCaptionCoverage(captionSegments, clips, fps);
+  }
   const brandKit = composition.brandKit;
   const { totalFrames: durationInFrames } = resolveBookendTimeline(
     brandKit,
@@ -838,8 +989,7 @@ function assembleRenderInput(composition, resolved) {
     resolved.srcUrls,
     resolved.trajectoryUrls ?? {},
     resolved.coViewUrls ?? {},
-    resolved.alphaUrls ?? {},
-    resolved.jsSourceByClipId ?? {}
+    resolved.alphaUrls ?? {}
   );
   if (renderInput.brandKit && resolved.fontAssets && resolved.fontAssets.length > 0) {
     renderInput.brandKit.fontAssets = resolved.fontAssets;
@@ -1824,11 +1974,11 @@ export {
   VIDEO_BOOKEND_DEFAULT_MS,
   bookendFrames,
   resolveBookendTimeline,
-  compositionFormatDimensions,
   validateComposition,
+  assertBehindSubjectCaptionCoverage,
+  compositionFormatDimensions,
   playableSpans,
   referencedMediaIds,
-  componentRefsByClipId,
   compositionToRenderInput,
   assembleRenderInput,
   DEFAULT_FPS,