@cueframe/kernel 0.2.45 → 0.2.47

package/dist/composition-ops.js

@@ -1,908 +1,47 @@
 import {
-  playableSpans
-} from "./chunk-AMFFWX3C.js";
+  CaptionMaterializationError,
+  CompositionOp,
+  GRID_DEFAULT_MAX_MARKERS,
+  GRID_HARD_MAX_MARKERS,
+  GridError,
+  applyCaptionOpToStore,
+  applyOp,
+  applyOpToStore,
+  captionSourceMediaIds,
+  collectAlphaLayerClips,
+  collectRawComponentClips,
+  collectUnbakedComponentClips,
+  createRecordingStore,
+  invertOp,
+  materializeCaptionsFromComposition,
+  materializeCompositionCaptions,
+  materializeGridMarkers,
+  mediaFamily,
+  replaceRegion,
+  resolveClipKind,
+  wrapWithOpRecorder
+} from "./chunk-KCXADPOC.js";
+import "./chunk-FEG264CF.js";
 import "./chunk-QH3YI3ND.js";
-import "./chunk-CYILSHK5.js";
-import "./chunk-QISFYLBB.js";
+import "./chunk-JPMVNMF3.js";
+import "./chunk-IMIUHG2E.js";
 import "./chunk-VZ7TYX6Z.js";
-import "./chunk-DENF4TPI.js";
-import {
-  createHeadlessStore,
-  findClipById,
-  findMarkerById,
-  findTrackContainingClipId
-} from "./chunk-POTCIQTA.js";
+import "./chunk-T56BK7NS.js";
+import "./chunk-VEQTURKN.js";
 import "./chunk-AG7HKF2U.js";
-import {
-  CaptionSegment,
-  CaptionStyle,
-  Composition,
-  Format,
-  Marker,
-  PerClipEffect,
-  TimelineClip,
-  Track,
-  Transition
-} from "./chunk-ID5QY7V6.js";
+import "./chunk-ID5QY7V6.js";
 import "./chunk-WPZKOVYF.js";
-import {
-  ReframeSegment
-} from "./chunk-B7J5UUUV.js";
+import "./chunk-B7J5UUUV.js";
 import "./chunk-KYRDKK2D.js";
 import "./chunk-WREYUH2E.js";
-import "./chunk-ULQJWGUV.js";
+import "./chunk-E63UEO5C.js";
 import "./chunk-7PA7FGLD.js";
-import {
-  SCENE_SLOT_MEDIA_FORMATS,
-  SceneShotSpecV2
-} from "./chunk-CL5Y6V6K.js";
+import "./chunk-CL5Y6V6K.js";
 import "./chunk-2L7PYYJK.js";
-import {
-  introducedCaptionFaceIssues
-} from "./chunk-AVTEPAWI.js";
+import "./chunk-AVTEPAWI.js";
 import "./chunk-2ESYSVXG.js";
-
-// ../composition-ops/src/index.ts
-import { z } from "zod";
-
-// ../composition-ops/src/opRecorder.ts
-var genTrackId = (kind) => `track-${kind}-${crypto.randomUUID().slice(0, 8)}`;
-function wrapWithOpRecorder(base, opts) {
-  const { record, getComposition } = opts;
-  const captionTarget = {
-    getState: () => ({ composition: getComposition() }),
-    setCaptionStyle: (style) => base.setCaptionStyle(style),
-    setCaptions: (segments, style) => base.setCaptions(segments, style)
-  };
-  const wrapped = {
-    addClip: (clip, options) => {
-      const before = getComposition();
-      const c = clip.kind ? clip : { ...clip, kind: "video" };
-      if (options?.newTrack) {
-        const newTrackId = options.newTrackId ?? genTrackId("video");
-        record({ type: "clip.add", clip: c, newTrack: true, newTrackId }, before);
-        base.addClip(c, { newTrack: true, newTrackId });
-      } else {
-        record({ type: "clip.add", clip: c }, before);
-        base.addClip(c);
-      }
-    },
-    removeClip: (id) => {
-      record({ type: "clip.remove", clipId: id }, getComposition());
-      base.removeClip(id);
-    },
-    updateClip: (id, updates) => {
-      record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
-      base.updateClip(id, updates);
-    },
-    removeClipsByMediaId: (mediaId) => {
-      record({ type: "removeClipsByMediaId", mediaId }, getComposition());
-      base.removeClipsByMediaId(mediaId);
-    },
-    setClipProperties: (id, props) => {
-      const { playbackRate, ...patch } = props;
-      if (playbackRate !== void 0) {
-        if (opts.onUnjournalable) {
-          const result = base.setClipProperties(id, props);
-          opts.onUnjournalable("setClipProperties.playbackRate");
-          return result;
-        }
-        throw new Error(
-          "opRecorder.setClipProperties: playbackRate is not serializable as a clip.update op (source.playbackRate triggers a cross-field ripple). Use the server-authoritative ripple path."
-        );
-      }
-      record({ type: "clip.update", clipId: id, patch }, getComposition());
-      return base.setClipProperties(id, props);
-    },
-    addOverlay: (clip) => {
-      const before = getComposition();
-      const track = before.tracks.find((t) => t.kind === "overlay");
-      let trackId = track?.id;
-      if (!trackId) {
-        trackId = genTrackId("overlay");
-        record({ type: "addTrack", kind: "overlay", id: trackId }, before);
-        base.addTrack("overlay", void 0, trackId);
-      }
-      record({ type: "clip.add", clip, trackId }, getComposition());
-      base.addOverlay(clip);
-    },
-    removeOverlay: (id) => {
-      record({ type: "clip.remove", clipId: id }, getComposition());
-      base.removeOverlay(id);
-    },
-    updateOverlay: (id, updates) => {
-      record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
-      base.updateOverlay(id, updates);
-    },
-    loadOverlays: (clips) => {
-      record({ type: "loadOverlays", clips }, getComposition());
-      base.loadOverlays(clips);
-    },
-    addAudioClip: (clip) => {
-      const before = getComposition();
-      const track = before.tracks.find((t) => t.kind === "audio");
-      let trackId = track?.id;
-      if (!trackId) {
-        trackId = genTrackId("audio");
-        record({ type: "addTrack", kind: "audio", id: trackId }, before);
-        base.addTrack("audio", void 0, trackId);
-      }
-      record({ type: "clip.add", clip, trackId }, getComposition());
-      base.addAudioClip(clip);
-    },
-    removeAudioClip: (id) => {
-      record({ type: "clip.remove", clipId: id }, getComposition());
-      base.removeAudioClip(id);
-    },
-    updateAudioClip: (id, updates) => {
-      record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
-      base.updateAudioClip(id, updates);
-    },
-    addMarker: (marker) => {
-      record({ type: "addMarker", marker }, getComposition());
-      base.addMarker(marker);
-    },
-    removeMarker: (id) => {
-      record({ type: "removeMarker", markerId: id }, getComposition());
-      base.removeMarker(id);
-    },
-    updateMarker: (id, updates) => {
-      record({ type: "updateMarker", markerId: id, updates }, getComposition());
-      base.updateMarker(id, updates);
-    },
-    setCropIntents: (clipId, segments) => {
-      record({ type: "setCropIntents", clipId, segments }, getComposition());
-      base.setCropIntents(clipId, segments);
-    },
-    setEffects: (clipId, effects) => {
-      record({ type: "setEffects", clipId, effects }, getComposition());
-      base.setEffects(clipId, effects);
-    },
-    // The two caption writes go through the same function `applyOpToStore` uses, so the op this
-    // journals is exactly the op a replay applies. Calling the store's setter directly left this
-    // lane — Studio's composition store and the in-app agent capability are built on it — able to
-    // write a face the op gate refuses and to journal an op `applyOp` would refuse on replay.
-    // The op is applied FIRST: a refusal must leave nothing in the journal.
-    setCaptionStyle: (style) => {
-      const before = getComposition();
-      const op = { type: "setCaptionStyle", style };
-      applyCaptionOpToStore(captionTarget, op);
-      record(op, before);
-    },
-    setCaptions: (segments, style) => {
-      const before = getComposition();
-      const op = {
-        type: "setCaptions",
-        segments,
-        ...style !== void 0 ? { style } : {}
-      };
-      applyCaptionOpToStore(captionTarget, op);
-      record(op, before);
-    },
-    setFormat: (format) => {
-      record({ type: "setFormat", format }, getComposition());
-      base.setFormat(format);
-    },
-    addTrack: (kind, name, id) => {
-      const useId = id ?? genTrackId(kind);
-      record({ type: "addTrack", kind, ...name !== void 0 ? { name } : {}, id: useId }, getComposition());
-      base.addTrack(kind, name, useId);
-    },
-    removeTrack: (trackId) => {
-      record({ type: "removeTrack", trackId }, getComposition());
-      base.removeTrack(trackId);
-    },
-    updateTrack: (trackId, updates) => {
-      record({ type: "updateTrack", trackId, updates }, getComposition());
-      base.updateTrack(trackId, updates);
-    },
-    reorderTracks: (fromIndex, toIndex) => {
-      record({ type: "reorderTracks", fromIndex, toIndex }, getComposition());
-      base.reorderTracks(fromIndex, toIndex);
-    },
-    moveClipToTrack: (clipId, targetTrackId, newStartTime) => {
-      record(
-        {
-          type: "moveClipToTrack",
-          clipId,
-          targetTrackId,
-          ...newStartTime !== void 0 ? { newStartTime } : {}
-        },
-        getComposition()
-      );
-      base.moveClipToTrack(clipId, targetTrackId, newStartTime);
-    },
-    duplicateClip: (id) => {
-      record({ type: "duplicateClip", clipId: id }, getComposition());
-      return base.duplicateClip(id);
-    },
-    cutAndRipple: (start, end) => {
-      record({ type: "cutAndRipple", start, end }, getComposition());
-      base.cutAndRipple(start, end);
-    },
-    ripple: (time, amount) => {
-      record({ type: "ripple", time, amount }, getComposition());
-      base.ripple(time, amount);
-    },
-    addExcludedRange: (clipId, sourceStart, sourceEnd, reason) => {
-      record(
-        {
-          type: "addExcludedRange",
-          clipId,
-          sourceStart,
-          sourceEnd,
-          ...reason !== void 0 ? { reason } : {}
-        },
-        getComposition()
-      );
-      base.addExcludedRange(clipId, sourceStart, sourceEnd, reason);
-    },
-    removeExcludedRange: (clipId, rangeIdx) => {
-      record({ type: "removeExcludedRange", clipId, rangeIdx }, getComposition());
-      base.removeExcludedRange(clipId, rangeIdx);
-    }
-  };
-  return { ...base, ...wrapped };
-}
-
-// ../composition-ops/src/recordingStore.ts
-function createRecordingStore(initial) {
-  const base = createHeadlessStore(initial);
-  const ops = [];
-  const wrapped = wrapWithOpRecorder(base, {
-    record: (op, _before) => ops.push(op),
-    getComposition: () => base.getState().composition
-  });
-  return {
-    ...wrapped,
-    getOps: () => [...ops]
-  };
-}
-
-// ../composition-ops/src/materializeGrid.ts
-var GridError = class extends Error {
-  constructor(code, message, opIndex) {
-    super(message);
-    this.code = code;
-    this.opIndex = opIndex;
-    this.name = "GridError";
-  }
-  code;
-  opIndex;
-};
-var GRID_DEFAULT_MAX_MARKERS = 500;
-var GRID_HARD_MAX_MARKERS = 2e3;
-function materializeGridMarkers(placement, gridPointsMs, opts) {
-  const { grid, clipId } = opts;
-  const cap = opts.maxMarkers ?? GRID_DEFAULT_MAX_MARKERS;
-  const rate = placement.playbackRate ?? 1;
-  const trimStart = placement.trim?.start ?? 0;
-  const trimEnd = placement.trim?.end ?? trimStart + placement.duration * rate;
-  const spans = playableSpans(trimStart, trimEnd, placement.excludedRanges);
-  const markers = [];
-  let n = 0;
-  for (const ms of gridPointsMs) {
-    const sourceSec = ms / 1e3;
-    let playedBefore = 0;
-    let visible = false;
-    for (const span of spans) {
-      if (sourceSec < span.start) break;
-      if (sourceSec < span.end) {
-        playedBefore += sourceSec - span.start;
-        visible = true;
-        break;
-      }
-      playedBefore += span.end - span.start;
-    }
-    if (!visible) continue;
-    markers.push({
-      id: `grid-${grid}-${clipId}-${n}`,
-      startTime: placement.startTime + playedBefore / rate,
-      kind: grid,
-      name: `${grid}-${n}`,
-      metadata: { sourceClipId: clipId }
-    });
-    n++;
-  }
-  if (markers.length > cap) {
-    throw new GridError(
-      "grid_cap_exceeded",
-      `materializeGrid: ${markers.length} '${grid}' markers fall inside clip '${clipId}' \u2014 over the cap of ${cap}. Raise maxMarkers (\u2264 ${GRID_HARD_MAX_MARKERS}) or narrow the clip's visible window (trim / excludedRanges) so fewer grid points land.`
-    );
-  }
-  return markers;
-}
-
-// ../composition-ops/src/replaceRegion.ts
-var EPS = 1e-3;
-function replaceRegion(input) {
-  const { cutSchedule, programAudioSourceId, durationByMediaId } = input;
-  if (cutSchedule.length === 0) {
-    throw new Error("replaceRegion: empty cut schedule");
-  }
-  const sorted = [...cutSchedule].sort((a, b) => a.startSec - b.startSec);
-  for (let i = 0; i < sorted.length; i++) {
-    const s = sorted[i];
-    if (s.endSec <= s.startSec) throw new Error(`replaceRegion: cut span '${s.candidateId}' has non-positive duration [${s.startSec},${s.endSec}]`);
-    const dur = durationByMediaId[s.mediaId];
-    if (dur !== void 0 && (s.sourceInSec < -EPS || s.sourceOutSec > dur + EPS)) {
-      throw new Error(`replaceRegion: cut span '${s.candidateId}' source [${s.sourceInSec},${s.sourceOutSec}] out of media [0,${dur}]`);
-    }
-    if (i > 0) {
-      const prev = sorted[i - 1];
-      if (Math.abs(s.startSec - prev.endSec) > EPS) {
-        throw new Error(`replaceRegion: cut schedule is not contiguous \u2014 gap/overlap between ${prev.endSec} and ${s.startSec}`);
-      }
-    }
-  }
-  const regionStart = sorted[0].startSec;
-  const regionEnd = sorted[sorted.length - 1].endSec;
-  const audioPinned = programAudioSourceId !== void 0;
-  const mediaClip = (id, startTime, duration, mediaId, trimStart, trimEnd, extra = {}) => ({
-    id,
-    startTime,
-    duration,
-    source: { kind: "media", mediaId, trim: { start: trimStart, end: trimEnd }, ...extra }
-  });
-  const videoTrack = {
-    id: `switch-cut-${stableSuffix(sorted)}`,
-    kind: "video",
-    name: input.trackName ?? "Switch Cut",
-    contents: sorted.map(
-      (s, i) => mediaClip(`cut-${i}-${s.candidateId}`, s.startSec, s.endSec - s.startSec, s.mediaId, s.sourceInSec, s.sourceOutSec, audioPinned ? { muted: true } : {})
-    )
-  };
-  const tracks = [...input.composition.tracks, videoTrack];
-  if (audioPinned) {
-    const dur = durationByMediaId[programAudioSourceId];
-    const audioOut = regionEnd - regionStart;
-    if (dur !== void 0 && audioOut > dur + EPS) {
-      throw new Error(`replaceRegion: program audio source '${programAudioSourceId}' (${dur}s) shorter than the region (${audioOut}s)`);
-    }
-    tracks.push({
-      id: `switch-audio-${programAudioSourceId}`,
-      kind: "audio",
-      name: "Program Audio",
-      contents: [
-        mediaClip(`program-audio-${programAudioSourceId}`, regionStart, regionEnd - regionStart, programAudioSourceId, 0, regionEnd - regionStart, { sync: "independent" })
-      ]
-    });
-  }
-  const next = { ...input.composition, tracks };
-  return Composition.parse(next);
-}
-function stableSuffix(spans) {
-  return spans.map((s) => `${s.candidateId}@${s.startSec.toFixed(2)}`).join("_").slice(0, 48).replace(/[^a-zA-Z0-9_@.-]/g, "");
-}
-
-// ../composition-ops/src/alphaLayers.ts
-function collectAlphaLayerClips(composition) {
-  const tracks = composition?.tracks;
-  if (!Array.isArray(tracks)) return [];
-  const out = [];
-  for (const track of tracks) {
-    const contents = track?.contents;
-    if (!Array.isArray(contents)) continue;
-    for (const c of contents) {
-      const src = c?.source;
-      if (!src || typeof src !== "object") continue;
-      if (src.kind !== "alpha-layer") continue;
-      const componentId = src.componentId;
-      const clipId = c.id;
-      const startTime = c.startTime;
-      const duration = c.duration;
-      if (typeof componentId !== "string" || componentId.length === 0) continue;
-      if (typeof clipId !== "string" || clipId.length === 0) continue;
-      if (typeof startTime !== "number" || typeof duration !== "number" || duration <= 0) continue;
-      const rawProps = src.props;
-      const props = rawProps && typeof rawProps === "object" && !Array.isArray(rawProps) ? rawProps : {};
-      const rawAssets = src.assets;
-      const assets = rawAssets && typeof rawAssets === "object" && !Array.isArray(rawAssets) ? Object.fromEntries(
-        Object.entries(rawAssets).filter(
-          (entry) => typeof entry[1] === "string" && entry[1].length > 0
-        )
-      ) : {};
-      out.push({ clipId, componentId, props, assets, startTime, duration });
-    }
-  }
-  return out;
-}
-function collectRawComponentClips(composition) {
-  const tracks = composition?.tracks;
-  if (!Array.isArray(tracks)) return [];
-  const out = [];
-  for (const track of tracks) {
-    const contents = track?.contents;
-    if (!Array.isArray(contents)) continue;
-    for (const c of contents) {
-      const src = c?.source;
-      if (!src || typeof src !== "object") continue;
-      if (src.kind !== "component") continue;
-      const id = c.id;
-      out.push(typeof id === "string" && id.length > 0 ? id : "(unnamed clip)");
-    }
-  }
-  return out;
-}
-function collectUnbakedComponentClips(composition) {
-  const tracks = composition?.tracks;
-  if (!Array.isArray(tracks)) return [];
-  const out = [];
-  for (const track of tracks) {
-    const contents = track?.contents;
-    if (!Array.isArray(contents)) continue;
-    for (const c of contents) {
-      const src = c?.source;
-      if (!src || typeof src !== "object") continue;
-      if (src.kind !== "overlay") continue;
-      if (src.primitiveId !== "custom") continue;
-      const params = src.params;
-      const componentId = params && typeof params === "object" ? params.componentId : void 0;
-      const clipId = c.id;
-      if (typeof componentId !== "string" || componentId.length === 0) continue;
-      if (typeof clipId !== "string" || clipId.length === 0) continue;
-      out.push({ clipId, componentId });
-    }
-  }
-  return out;
-}
-
-// ../composition-ops/src/index.ts
-var SceneAssetBindings = z.record(z.string().min(1), z.string().min(1));
-function mediaFamily(mimeType) {
-  const top = mimeType.split("/")[0]?.trim().toLowerCase();
-  if (top === "video") return "video";
-  if (top === "audio") return "audio";
-  if (top === "image") return "image";
-  throw new Error(
-    `mediaFamily: cannot derive a timeline family from mimeType ${JSON.stringify(mimeType)} \u2014 expected a video/*, audio/* or image/* type.`
-  );
-}
-function deriveFromSource(sourceKind) {
-  switch (sourceKind) {
-    case "overlay":
-      return "overlay";
-    case "effect":
-      return "effect";
-    case "component":
-      return "overlay";
-    case "alpha-layer":
-      return "overlay";
-    case "card":
-      return "overlay";
-    case "media":
-      return void 0;
-    // ambiguous — caller must disambiguate
-    case "composition":
-      return "video";
-    default: {
-      const _exhaustive = sourceKind;
-      throw new Error(`deriveFromSource: unknown source kind ${String(_exhaustive)}`);
-    }
-  }
-}
-function resolveClipKind(clip, track) {
-  const resolved = clip.kind ?? deriveFromSource(clip.source.kind) ?? track?.kind;
-  if (!resolved) {
-    throw new Error(
-      `resolveClipKind: clip with a 'media' source has no 'kind' and no track context \u2014 cannot determine its family (video | audio | image). Set clip.kind or target a track.`
-    );
-  }
-  return resolved;
-}
-var CompositionOp = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("clip.add"), clip: TimelineClip, trackId: z.string().optional(), newTrack: z.boolean().optional(), newTrackId: z.string().optional() }).strict().describe(
-    "Add a clip to the timeline. The clip self-routes to a track by FAMILY (`clip.kind`, else derived from `source.kind`, else the target track) \u2014 a `media` clip MUST carry `kind` (video|audio|image) or a `trackId`, else it is rejected as ambiguous. `trackId` targets an existing SAME-family track; `newTrack:true` (with optional pinned `newTrackId`) creates a fresh track of that family."
-  ),
-  z.object({ type: z.literal("clip.remove"), clipId: z.string() }).strict().describe(
-    "Remove a clip by id (located across every track)."
-  ),
-  z.object({ type: z.literal("clip.update"), clipId: z.string(), patch: TimelineClip.partial() }).strict().describe(
-    "Patch an existing clip by id (cross-family). The patch is a partial TimelineClip. NOTE: `source` is REPLACED wholesale \u2014 the patch merges at the top level only, so a partial `source` WIPES the source fields you omit. Patch the whole source object when changing it. (To change reframe/excluded ranges, prefer setCropIntents / addExcludedRange, not a source patch.)"
-  ),
-  z.object({ type: z.literal("removeClipsByMediaId"), mediaId: z.string() }).strict().describe(
-    "Remove EVERY clip sourced from a given mediaId (e.g. after deleting that media)."
-  ),
-  z.object({ type: z.literal("loadOverlays"), clips: z.array(TimelineClip) }).strict().describe(
-    "Replace the overlay channel wholesale with the given clips (bulk set, not a merge)."
-  ),
-  z.object({ type: z.literal("addMarker"), marker: Marker }).strict().describe(
-    "Add a timeline marker (a named time point/range; carry extensions in `metadata`)."
-  ),
-  z.object({ type: z.literal("removeMarker"), markerId: z.string() }).strict().describe(
-    "Remove a marker by id."
-  ),
-  z.object({ type: z.literal("updateMarker"), markerId: z.string(), updates: Marker.partial() }).strict().describe(
-    "Patch a marker's fields by id (partial merge)."
-  ),
-  z.object({ type: z.literal("setCropIntents"), clipId: z.string(), segments: z.array(ReframeSegment).nullable() }).strict().describe(
-    "Set (or CLEAR, with `segments: null`) the camera/reframe channel on a MEDIA clip \u2014 the time-aligned source\u2192output viewport (focus, zoom, ease, bias). This is the PREFERRED way to author reframing; do NOT reframe via a whole-source `clip.update` patch. Segments tile the clip's duration."
-  ),
-  z.object({ type: z.literal("setEffects"), clipId: z.string(), effects: z.array(PerClipEffect) }).strict().describe(
-    "Set (or CLEAR, with `effects: []`) a clip's EFFECT channel \u2014 the registered effect primitives stacked onto that clip, each `{ primitiveId, params? }`. WHOLESALE: the array REPLACES the clip's current effects, so send the full stack (read the clip first to add one). This is the ONLY way to change effects on an existing clip \u2014 do NOT reach for a `clip.update` patch, whose top-level merge is the source-clobbering footgun documented above."
-  ),
-  z.object({ type: z.literal("setCaptionStyle"), style: CaptionStyle.partial() }).strict().describe(
-    "Merge style overrides (font/color/position/emphasis) onto the composition's caption layer. Partial \u2014 omitted fields keep their current value; creates the caption container if absent."
-  ),
-  z.object({ type: z.literal("setCaptionDepth"), zPlane: z.enum(["front", "behind-subject"]) }).strict().describe(
-    "Set the caption compositing plane. Use `behind-subject` to place captions behind the segmented foreground subject; use `front` for conventional captions above all video layers."
-  ),
-  z.object({ type: z.literal("setCaptions"), segments: z.array(CaptionSegment), style: CaptionStyle.partial().optional() }).strict().describe(
-    "Replace the caption SEGMENTS wholesale \u2014 author the word-timed caption layer directly (each segment = one sentence/page of `words` with timeline-ms `startMs`/`endMs`, optional `emphasis`). This is how a client with its OWN word timings (e.g. a generated VO take) gets word-synced captions without a source transcript; the compose lane's transcript slice writes the same layer. `style`, when given, merges with setCaptionStyle semantics; an omitted style keeps the existing one. Renderer paginates within a segment and never pools words across two \u2014 keep segments sentence-bounded."
-  ),
-  z.object({ type: z.literal("applyMotionPreset"), clipId: z.string(), preset: z.string(), params: z.object({ enterMs: z.number().optional(), exitMs: z.number().optional(), staggerMs: z.number().optional() }).strict().optional() }).strict().describe(
-    "Shell a STATIC `card` clip with a frame-driven MOTION preset \u2014 the public card-shelling op (the layout renders VERBATIM; only the container animates in/out). The server wraps the card in the chosen `preset` (fade-up / slide-in-left / slide-in-right / scale-pop / stagger-reveal), transpiles it, mints it as a LIVE component, and swaps the clip source to that component (the bakeless live lane \u2014 no box). `params` tunes timing (`enterMs`/`exitMs`, `staggerMs` for stagger-reveal). The target must be a static card (components already carry motion; library overlays already move); re-run overwrites idempotently ONLY while the target is still a card (an uncompilable shell); once shelled, the clip is a COMPONENT \u2014 to change its motion, remove and re-add the card, then re-shell. Honored under `dry_run` (validates preset + target without transpiling or persisting). ORDERING: the preset resolves its target against the PERSISTED composition \u2014 a card added in the SAME batch is not yet visible to it. Persist the clip.add batch first, then shell in a following call."
-  ),
-  // Scene shots (spec §"Authoring, persistence, and discovery"). Route-materialized: the host
-  // registers the generated wrapper source through its component store and rewrites these to
-  // addTrack / clip.add / clip.update carrying `props.componentRef`; the agent edits a scene
-  // spec, never wrapper TSX or a hash. Exactly one of `trackId` (a dedicated overlay track) or
-  // `newTrack` (mint one) is required on `scene.add`.
-  z.object({
-    type: z.literal("scene.add"),
-    clipId: z.string().min(1),
-    trackId: z.string().min(1).optional(),
-    newTrack: z.boolean().optional(),
-    newTrackId: z.string().min(1).optional(),
-    startTime: z.number().nonnegative(),
-    duration: z.number().positive(),
-    transitionIn: Transition.optional(),
-    scene: SceneShotSpecV2,
-    assets: SceneAssetBindings
-  }).strict().describe(
-    // Lives here, not in the published api/openapi.json. It used to exist ONLY
-    // in that document, which made the contract hand-maintained and put it out
-    // of reach of a scripted sync from this SSOT.
-    `Author a scene shot and place it on a dedicated overlay track. The host validates the scene, generates and registers an immutable wrapper component source, and emits the ordinary track/clip operations carrying \`props.componentRef\` \u2014 you edit a scene SPEC, never wrapper TSX or a source hash. Registration and the composition update are ONE undoable edit; a failure publishes nothing and leaves no clip pointing at an unresolved source. Pass EXACTLY ONE of \`trackId\` (an existing dedicated scene track) or \`newTrack: true\` (mint one). That track holds scene-shot clips and gaps only \u2014 no generic component/primitive/media clips in v1 \u2014 and existing generic overlay tracks are unaffected. Scene clips use front zPlane and full-frame placement: outer per-clip \`region\`, \`position\`, \`scale\`, \`rotation\`, \`fit\`, \`effects\`, \`animate\`, \`params.transition\`, \`params.sequenceGroup\` and internal fadeIn/fadeOut are REFUSED with a path, because the shot's own layer transforms are the single transform owner. TEXT: \`space: "screen"\` text is composed above the world result, stays fixed in the frame and stays sharp through focus; \`space: "world"\` text is rasterized into the 3D scene, moves with the camera and is occluded by geometry. Screenshots and world text are UNLIT and colour-managed so product UI colours are not tinted by the studio lighting, while device bodies are lit and cast shadows; an unlit surface still occludes. SCOPE GAP (pre-existing, neither closed nor changed by scene shots): global wrap effects \u2014 composition-level grades and camera effects \u2014 do not reach front-overlay clips, so they do not affect a scene shot. Author the look INSIDE the shot (\`post.grain\`, \`post.vignette\`, \`post.focus\`, \`backdrop\`, \`environment\`) instead. DISCOVERY: there is no built-in scene primitive to look up in list_catalog; the wrapper this operation registers appears afterwards as an ordinary INSTALLED component under the existing catalog rules. ASSETS: \`assets\` binds each slot name a layer references to a media id in the same project, and the slot's declared KIND decides what it admits \u2014 an image slot takes ${SCENE_SLOT_MEDIA_FORMATS.image}, a video slot ${SCENE_SLOT_MEDIA_FORMATS.video}. Binding the wrong kind is refused with the slot's path.`
-  ),
-  z.object({
-    type: z.literal("scene.update"),
-    clipId: z.string().min(1),
-    startTime: z.number().nonnegative().optional(),
-    duration: z.number().positive().optional(),
-    transitionIn: Transition.optional(),
-    scene: SceneShotSpecV2.optional(),
-    assets: SceneAssetBindings.optional()
-  }).strict().describe(`Revise a scene shot in place by clip id. Send a replacement \`scene\` and/or \`assets\`; timing changes use the ordinary clip timing fields (\`startTime\`, \`duration\`, \`transitionIn\`). Omitted fields keep their persisted values and the MERGED result is re-validated as a whole, so a partial edit cannot leave the shot invalid. Changing only values or asset IDs updates props and bindings and REUSES the pinned source; changing the referenced SLOT SET regenerates the wrapper manifest and registers a new immutable source version atomically. Undo restores the source reference, spec, bindings and timing together. Topology, asset bindings, text content, font properties, device kind and colours are STATIC within a shot's animation \u2014 change them here (a revised spec) rather than trying to animate them. This is not a source trim or slip: a shortened or extended clip resamples the SAME normalized animation over its new duration, and trim/slip requests on generated animation are rejected rather than reinterpreted as media trims. In one batch, \`scene.update\` may target a shot added by an earlier \`scene.add\`. ASSETS: \`assets\` binds each slot name a layer references to a media id in the same project, and the slot's declared KIND decides what it admits \u2014 an image slot takes ${SCENE_SLOT_MEDIA_FORMATS.image}, a video slot ${SCENE_SLOT_MEDIA_FORMATS.video}. Binding the wrong kind is refused with the slot's path.`),
-  z.object({ type: z.literal("materializeGrid"), clipId: z.string(), grid: z.enum(["beat", "word", "shot"]), maxMarkers: z.number().int().positive().max(2e3).optional() }).strict().describe(
-    'Materialize a clip\'s SOURCE-media temporal GRID as timeline markers \u2014 the rhythm authority you cut to. `grid:"beat"` reads a MUSIC bed\'s beat map (get_media_context.beatGrid), `grid:"word"` the VO word onsets (wordGrid); each grid point is projected from media time to TIMELINE time through the clip\'s placement (startTime, trim, playbackRate, excludedRanges) and written as a `kind:"beat"|"word"` marker (`metadata.sourceClipId` set). Points outside the clip\'s visible window are skipped. Re-running REPLACES the prior markers from the same clip+grid (idempotent). Land cuts and transition MIDPOINTS on the markers (a 0.5s transition starts 0.25s before its marker). `maxMarkers` (default 500, ceiling 2000) \u2014 exceeding it fails loud with the count. `grid:"shot"` is not yet exposed (shot_grid_unavailable). The target must be a media clip; absent evidence fails loud (grid_unavailable) naming how to get it (declare audioRole:"music" at ingest / transcribe).'
-  ),
-  z.object({
-    type: z.literal("captions.fromTranscript"),
-    mediaId: z.string().min(1),
-    window: z.object({ startSec: z.number().min(0), endSec: z.number().positive() }).strict().optional()
-  }).strict().describe(
-    "Attach caption CONTENT from the media's cached transcript \u2014 no pasting words. ROUTE-MATERIALIZED like applyMotionPreset/materializeGrid: the server slices the word-timed transcript to `window` (source seconds; absent = the whole media), rebases times, sentence-splits into segments, and applies it as `setCaptions`. 422 media_no_transcript when the media has no transcript or no words in the window. For your OWN word timings use setCaptions directly."
-  ),
-  z.object({ type: z.literal("setFormat"), format: Format.pick({ aspectRatio: true, fps: true, resolution: true }) }).strict().describe(
-    "Set the output format \u2014 `aspectRatio` (16:9|9:16|1:1|4:5) plus optional `fps` and `resolution`. Merges: an omitted field keeps the current value."
-  ),
-  z.object({ type: z.literal("addTrack"), kind: Track.shape.kind, name: z.string().optional(), id: z.string().optional() }).strict().describe(
-    "Add an EMPTY track of a given family (video|audio|image|overlay|effect). Optional pinned `id`. The new track is appended, so it starts at the BACK: index 0 is the top layer and higher indices are further back (see `reorderTracks`). Track order only ranks clips on the same plane \u2014 every overlay draws above the video lane unless its `zPlane` is `behind-subject`, whatever its track index."
-  ),
-  z.object({ type: z.literal("removeTrack"), trackId: z.string() }).strict().describe(
-    "Remove a track AND all its clips by id."
-  ),
-  z.object({ type: z.literal("updateTrack"), trackId: z.string(), updates: Track.pick({ name: true, enabled: true, volume: true }).partial() }).strict().describe(
-    "Patch a track's `name` / `enabled` by id."
-  ),
-  z.object({ type: z.literal("reorderTracks"), fromIndex: z.number(), toIndex: z.number() }).strict().describe(
-    'Move a track from one index to another. ORDER: index 0 is the TOP layer, not the bottom \u2014 moving a backdrop to index 0 puts it in FRONT of everything and hides the composition. Higher index = further back. PRECEDENCE: track order decides compositing only among clips on the same plane. Overlays are composited in a lane ABOVE the video lane whatever their track index; the one exception is `zPlane:"behind-subject"`, which moves the overlay inside its host clip, behind the segmented foreground. So if reordering tracks does not change what you see, the plane split already decided it.'
-  ),
-  z.object({ type: z.literal("moveClipToTrack"), clipId: z.string(), targetTrackId: z.string(), newStartTime: z.number().optional() }).strict().describe(
-    "Move a clip to another SAME-family track, optionally at a new `newStartTime`."
-  ),
-  z.object({ type: z.literal("duplicateClip"), clipId: z.string(), newClipId: z.string().optional() }).strict().describe(
-    "Duplicate a clip by id. Pin `newClipId` to make the copy's id deterministic (required for a clean undo/inverse)."
-  ),
-  z.object({ type: z.literal("cutAndRipple"), start: z.number(), end: z.number() }).strict().describe(
-    "Server-authoritative: delete the [start,end] time window (seconds) and ripple every downstream clip/marker/caption earlier to close the gap."
-  ),
-  z.object({ type: z.literal("ripple"), time: z.number(), amount: z.number() }).strict().describe(
-    "Server-authoritative: shift everything at/after `time` (seconds) by `amount` seconds (+ opens a gap, \u2212 closes one)."
-  ),
-  z.object({ type: z.literal("addExcludedRange"), clipId: z.string(), sourceStart: z.number(), sourceEnd: z.number(), reason: z.string().optional() }).strict().describe(
-    "Server-authoritative: exclude a [sourceStart,sourceEnd] span (seconds) of a clip's SOURCE (an internal trim) and ripple downstream \u2014 the preferred way to drop a sub-range vs a source patch."
-  ),
-  z.object({ type: z.literal("removeExcludedRange"), clipId: z.string(), rangeIdx: z.number() }).strict().describe(
-    "Server-authoritative: remove a clip's previously-added excluded range by index (re-includes that span, ripples downstream)."
-  )
-]).describe(
-  "One scoped composition operation. Discriminated by `type` \u2014 `clip.add` / `clip.remove` / `clip.update` patch clips across any family; the rest cover markers, reframe, effects, captions, format, tracks, and the server-authoritative ripple recomputes. Every variant is `.strict()`: an unknown field is refused, not ignored."
-);
-function mergedCaptionStyle(composition, patch) {
-  const existing = composition.captions?.style ?? {};
-  if (!patch) return existing;
-  const defined = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== void 0));
-  return { ...existing, ...defined };
-}
-function assertCaptionFacesDrawable(opType, composition, patch) {
-  const existing = composition.captions?.style ?? {};
-  const issues = introducedCaptionFaceIssues(existing, mergedCaptionStyle(composition, patch));
-  if (issues.length === 0) return;
-  throw new Error(
-    `${opType}: this edit introduces a caption face with no bytes behind it \u2014 ` + issues.map((issue) => `style.${issue.field}: ${issue.message}`).join(" ")
-  );
-}
-function applyCaptionOpToStore(store, op) {
-  const composition = store.getState().composition;
-  assertCaptionFacesDrawable(op.type, composition, op.style);
-  if (op.type === "setCaptionStyle") {
-    store.setCaptionStyle(op.style);
-    return;
-  }
-  store.setCaptions(op.segments, op.style);
-}
-function applyOp(composition, op) {
-  const store = createHeadlessStore(composition);
-  applyOpToStore(store, op);
-  return store.getState().composition;
-}
-function applyOpToStore(store, op) {
-  const composition = store.getState().composition;
-  switch (op.type) {
-    case "clip.add": {
-      if (findClipById(composition, op.clip.id)) {
-        throw new Error(`clip.add: clip '${op.clip.id}' already exists`);
-      }
-      if (op.newTrackId !== void 0 && composition.tracks.some((track) => track.id === op.newTrackId)) {
-        throw new Error(`clip.add: track '${op.newTrackId}' already exists`);
-      }
-      if (op.trackId !== void 0) {
-        const track = composition.tracks.find((t) => t.id === op.trackId);
-        if (!track) throw new Error(`clip.add: track '${op.trackId}' not found`);
-        const kind = resolveClipKind(op.clip, track);
-        if (kind !== track.kind) {
-          throw new Error(
-            `clip.add: clip family '${kind}' does not match target track '${op.trackId}' (kind '${track.kind}')`
-          );
-        }
-        store.addClipToTrack(op.clip, { trackId: op.trackId });
-      } else {
-        const kind = resolveClipKind(op.clip);
-        store.addClipToTrack(
-          op.clip,
-          op.newTrack ? { kind, newTrack: true, newTrackId: op.newTrackId } : { kind }
-        );
-      }
-      break;
-    }
-    case "clip.remove":
-      store.removeClip(op.clipId);
-      break;
-    case "clip.update":
-      store.updateClip(op.clipId, op.patch);
-      break;
-    case "removeClipsByMediaId":
-      store.removeClipsByMediaId(op.mediaId);
-      break;
-    case "loadOverlays":
-      store.loadOverlays(op.clips);
-      break;
-    case "addMarker":
-      store.addMarker(op.marker);
-      break;
-    case "removeMarker":
-      store.removeMarker(op.markerId);
-      break;
-    case "updateMarker":
-      store.updateMarker(op.markerId, op.updates);
-      break;
-    case "setCropIntents":
-      store.setCropIntents(op.clipId, op.segments);
-      break;
-    case "setEffects": {
-      if (!findClipById(composition, op.clipId)) {
-        throw new Error(`setEffects: clip '${op.clipId}' not found`);
-      }
-      store.setEffects(op.clipId, op.effects);
-      break;
-    }
-    case "setCaptionStyle":
-      applyCaptionOpToStore(store, op);
-      break;
-    case "setCaptionDepth":
-      store.setCaptionDepth(op.zPlane);
-      break;
-    case "setCaptions":
-      applyCaptionOpToStore(store, op);
-      break;
-    case "applyMotionPreset":
-      throw new Error(
-        `applyOp: 'applyMotionPreset' is route-materialized \u2014 it needs a director transpile of the generated motion shell and is rewritten to a clip.update at /composition/apply before reaching the pure engine.`
-      );
-    case "materializeGrid":
-      throw new Error(
-        `applyOp: 'materializeGrid' is route-materialized \u2014 it reads the clip's source-media grid (beat/word/shot) via a media reader and is rewritten to removeMarker+addMarker ops at /composition/apply before reaching the pure engine.`
-      );
-    case "captions.fromTranscript":
-      throw new Error(
-        `applyOp: 'captions.fromTranscript' is route-materialized \u2014 it is resolved to setCaptions at /composition/apply before reaching the pure engine.`
-      );
-    case "scene.add":
-    case "scene.update":
-      throw new Error(
-        `applyOp: '${op.type}' is route-materialized \u2014 the host validates the scene, registers the generated scene-shot wrapper source through its component store and rewrites the request to ordinary addTrack / clip.add / clip.update ops carrying \`props.componentRef\` before reaching the pure engine.`
-      );
-    case "setFormat":
-      store.setFormat(op.format);
-      break;
-    case "addTrack":
-      store.addTrack(op.kind, op.name, op.id);
-      break;
-    case "removeTrack":
-      store.removeTrack(op.trackId);
-      break;
-    case "updateTrack":
-      store.updateTrack(op.trackId, op.updates);
-      break;
-    case "reorderTracks":
-      store.reorderTracks(op.fromIndex, op.toIndex);
-      break;
-    case "moveClipToTrack":
-      store.moveClipToTrack(op.clipId, op.targetTrackId, op.newStartTime);
-      break;
-    case "duplicateClip": {
-      const minted = store.duplicateClip(op.clipId);
-      if (op.newClipId !== void 0 && minted !== void 0 && minted !== op.newClipId) {
-        store.updateClip(minted, { id: op.newClipId });
-      }
-      break;
-    }
-    case "cutAndRipple":
-      store.cutAndRipple(op.start, op.end);
-      break;
-    case "ripple":
-      store.ripple(op.time, op.amount);
-      break;
-    case "addExcludedRange":
-      store.addExcludedRange(op.clipId, op.sourceStart, op.sourceEnd, op.reason);
-      break;
-    case "removeExcludedRange":
-      store.removeExcludedRange(op.clipId, op.rangeIdx);
-      break;
-    default: {
-      const _exhaustive = op;
-      throw new Error(`applyOp: unknown op ${_exhaustive.type}`);
-    }
-  }
-}
-function invertOp(before, op) {
-  switch (op.type) {
-    case "clip.add":
-      return { type: "clip.remove", clipId: op.clip.id };
-    case "clip.remove": {
-      const found = findClipById(before, op.clipId);
-      if (!found) {
-        throw new Error(`invertOp(clip.remove): clip '${op.clipId}' not in the pre-image`);
-      }
-      const track = before.tracks[found.trackIndex];
-      return { type: "clip.add", clip: found.clip, trackId: track.id };
-    }
-    case "clip.update": {
-      const found = findClipById(before, op.clipId);
-      if (!found) {
-        throw new Error(`invertOp(clip.update): clip '${op.clipId}' not in the pre-image`);
-      }
-      const prior = found.clip;
-      const inversePatch = {};
-      for (const key of Object.keys(op.patch)) inversePatch[key] = prior[key];
-      return { type: "clip.update", clipId: op.clipId, patch: inversePatch };
-    }
-    case "addMarker":
-      return { type: "removeMarker", markerId: op.marker.id };
-    case "removeMarker": {
-      const found = findMarkerById(before, op.markerId);
-      if (!found) {
-        throw new Error(`invertOp(removeMarker): marker '${op.markerId}' not in the pre-image`);
-      }
-      return { type: "addMarker", marker: found.marker };
-    }
-    case "updateMarker": {
-      const found = findMarkerById(before, op.markerId);
-      if (!found) {
-        throw new Error(`invertOp(updateMarker): marker '${op.markerId}' not in the pre-image`);
-      }
-      const prior = found.marker;
-      const inverseUpdates = {};
-      for (const key of Object.keys(op.updates)) {
-        inverseUpdates[key] = prior[key];
-      }
-      return { type: "updateMarker", markerId: op.markerId, updates: inverseUpdates };
-    }
-    case "setCropIntents": {
-      const found = findClipById(before, op.clipId);
-      if (!found) {
-        throw new Error(`invertOp(setCropIntents): clip '${op.clipId}' not in the pre-image`);
-      }
-      const src = found.clip.source;
-      const priorSegments = src.kind === "media" && src.reframe ? src.reframe.segments : null;
-      return { type: "setCropIntents", clipId: op.clipId, segments: priorSegments };
-    }
-    case "setEffects": {
-      const found = findClipById(before, op.clipId);
-      if (!found) {
-        throw new Error(`invertOp(setEffects): clip '${op.clipId}' not in the pre-image`);
-      }
-      return { type: "setEffects", clipId: op.clipId, effects: found.clip.effects ?? [] };
-    }
-    case "setFormat": {
-      const f = before.format;
-      return {
-        type: "setFormat",
-        format: {
-          aspectRatio: f.aspectRatio,
-          ...f.fps !== void 0 ? { fps: f.fps } : {},
-          ...f.resolution !== void 0 ? { resolution: f.resolution } : {}
-        }
-      };
-    }
-    case "setCaptionDepth":
-      return { type: "setCaptionDepth", zPlane: before.captions?.zPlane ?? "front" };
-    case "addTrack":
-      if (op.id === void 0) {
-        throw new Error("invertOp(addTrack): no pinned `id` \u2014 cannot target the minted track");
-      }
-      return { type: "removeTrack", trackId: op.id };
-    case "updateTrack": {
-      const track = before.tracks.find((t) => t.id === op.trackId);
-      if (!track) {
-        throw new Error(`invertOp(updateTrack): track '${op.trackId}' not in the pre-image`);
-      }
-      const inverseUpdates = {};
-      if ("name" in op.updates) inverseUpdates.name = track.name;
-      if ("enabled" in op.updates) inverseUpdates.enabled = track.enabled;
-      return { type: "updateTrack", trackId: op.trackId, updates: inverseUpdates };
-    }
-    case "reorderTracks": {
-      const len = before.tracks.length;
-      const restingIndex = Math.max(0, Math.min(op.toIndex, len - 1));
-      return { type: "reorderTracks", fromIndex: restingIndex, toIndex: op.fromIndex };
-    }
-    case "moveClipToTrack": {
-      const found = findTrackContainingClipId(before, op.clipId);
-      if (!found) {
-        throw new Error(`invertOp(moveClipToTrack): clip '${op.clipId}' not in the pre-image`);
-      }
-      const priorClip = found.track.contents[found.clipIndex];
-      return {
-        type: "moveClipToTrack",
-        clipId: op.clipId,
-        targetTrackId: found.track.id,
-        newStartTime: priorClip.startTime
-      };
-    }
-    case "duplicateClip":
-      if (op.newClipId === void 0) {
-        throw new Error(
-          "invertOp(duplicateClip): no `newClipId` \u2014 the copy id is store-minted and non-deterministic. Pin `newClipId` on the op for a deterministic inverse."
-        );
-      }
-      return { type: "clip.remove", clipId: op.newClipId };
-    case "cutAndRipple":
-    case "ripple":
-    case "addExcludedRange":
-    case "removeExcludedRange":
-    case "removeTrack":
-    case "removeClipsByMediaId":
-    case "loadOverlays":
-    case "setCaptionStyle":
-    case "setCaptions":
-    case "applyMotionPreset":
-    case "materializeGrid":
-    case "captions.fromTranscript":
-    case "scene.add":
-    case "scene.update":
-      throw new Error(
-        `invertOp: '${op.type}' has no per-op inverse in scope (server-authoritative cross-field recompute or whole-channel/positional restore) \u2014 fail loud, no fake inverse.`
-      );
-    default: {
-      const _exhaustive = op;
-      throw new Error(`invertOp: unknown op ${_exhaustive.type}`);
-    }
-  }
-}
 export {
+  CaptionMaterializationError,
   CompositionOp,
   GRID_DEFAULT_MAX_MARKERS,
   GRID_HARD_MAX_MARKERS,
@@ -910,11 +49,14 @@ export {
   applyCaptionOpToStore,
   applyOp,
   applyOpToStore,
+  captionSourceMediaIds,
   collectAlphaLayerClips,
   collectRawComponentClips,
   collectUnbakedComponentClips,
   createRecordingStore,
   invertOp,
+  materializeCaptionsFromComposition,
+  materializeCompositionCaptions,
   materializeGridMarkers,
   mediaFamily,
   replaceRegion,