@cueframe/kernel 0.1.1 → 0.1.3

package/dist/compose/renderer.js

@@ -1,39 +1,39 @@
 import {
   resolvePrimitive
-} from "../chunk-AP6ZIVAV.js";
+} from "../chunk-HBVAZXYO.js";
 import "../chunk-H5LMJKZU.js";
-import "../chunk-GULDS3VE.js";
-import "../chunk-7DHP4ESU.js";
 import "../chunk-MFHXCHRI.js";
 import "../chunk-JQMPHKLU.js";
 import "../chunk-MHOQTPOB.js";
-import "../chunk-OLFOPQCA.js";
-import "../chunk-DLF4WVSE.js";
-import "../chunk-U4V4FZGE.js";
-import "../chunk-AWT3P5ZN.js";
-import "../chunk-GA23TRNR.js";
-import "../chunk-PMY24FUD.js";
+import "../chunk-GULDS3VE.js";
+import "../chunk-YLDMAZZE.js";
+import "../chunk-BKHGL4MB.js";
 import {
   Grain,
   Vignette
-} from "../chunk-ABL557OT.js";
-import "../chunk-P727GZVO.js";
+} from "../chunk-GMD33ZD7.js";
+import "../chunk-SAMQUUO5.js";
+import "../chunk-RP4SXXLJ.js";
+import "../chunk-DYZE7JZA.js";
+import "../chunk-ZSZABOE5.js";
+import "../chunk-UQSOS726.js";
+import "../chunk-DLF4WVSE.js";
+import "../chunk-U4V4FZGE.js";
 import "../chunk-BDMTUEEZ.js";
 import "../chunk-EMGFZ3PR.js";
-import "../chunk-ZFEXATWN.js";
-import "../chunk-YX2GSJK7.js";
-import "../chunk-AYVJXDLB.js";
-import "../chunk-SW336CJP.js";
+import "../chunk-AWT3P5ZN.js";
 import "../chunk-QGAWDLYX.js";
-import "../chunk-ZSZABOE5.js";
+import "../chunk-G5BFI32U.js";
+import "../chunk-XHGZ2E77.js";
+import "../chunk-ZFEXATWN.js";
 import "../chunk-CX2IIQ4R.js";
-import "../chunk-7FO3ZJ43.js";
+import "../chunk-DCVJWGIA.js";
 import "../chunk-7PA7FGLD.js";
 import "../chunk-JF4JJAFP.js";
 import {
   CueframeError,
   encodeError
-} from "../chunk-OCFDUCF4.js";
+} from "../chunk-AW57IWNW.js";
 import "../chunk-2ESYSVXG.js";
 
 // ../execution/compose/src/CompositionRenderer.tsx

package/dist/compose.js

@@ -1,7 +1,7 @@
 import {
   resolveTokens,
   sceneToRenderInput
-} from "./chunk-MBCXCJOE.js";
+} from "./chunk-TXSFYUZH.js";
 import {
   allCatalogs,
   getPrimitiveSubtext,
@@ -13,46 +13,46 @@ import {
   resetPrimitiveOverrides,
   resolvePrimitive,
   resolveTransitionPresentation
-} from "./chunk-AP6ZIVAV.js";
+} from "./chunk-HBVAZXYO.js";
 import "./chunk-H5LMJKZU.js";
-import "./chunk-GULDS3VE.js";
-import "./chunk-7DHP4ESU.js";
 import "./chunk-MFHXCHRI.js";
 import "./chunk-JQMPHKLU.js";
 import "./chunk-MHOQTPOB.js";
-import "./chunk-OLFOPQCA.js";
+import "./chunk-GULDS3VE.js";
+import "./chunk-YLDMAZZE.js";
+import "./chunk-BKHGL4MB.js";
+import "./chunk-GMD33ZD7.js";
+import "./chunk-SAMQUUO5.js";
+import "./chunk-RP4SXXLJ.js";
+import "./chunk-DYZE7JZA.js";
+import "./chunk-ZSZABOE5.js";
+import "./chunk-UQSOS726.js";
 import "./chunk-DLF4WVSE.js";
 import "./chunk-U4V4FZGE.js";
-import "./chunk-AWT3P5ZN.js";
-import "./chunk-GA23TRNR.js";
-import "./chunk-PMY24FUD.js";
-import "./chunk-ABL557OT.js";
-import "./chunk-P727GZVO.js";
 import "./chunk-BDMTUEEZ.js";
 import "./chunk-EMGFZ3PR.js";
-import "./chunk-ZFEXATWN.js";
-import "./chunk-YX2GSJK7.js";
-import "./chunk-AYVJXDLB.js";
-import "./chunk-SW336CJP.js";
+import "./chunk-AWT3P5ZN.js";
 import "./chunk-QGAWDLYX.js";
-import "./chunk-ZSZABOE5.js";
+import "./chunk-G5BFI32U.js";
+import "./chunk-XHGZ2E77.js";
+import "./chunk-ZFEXATWN.js";
 import "./chunk-CX2IIQ4R.js";
 import {
   getPrimitiveSubtextParam,
   getPrimitiveTextParam,
   listPrimitivesByCategory
-} from "./chunk-7FO3ZJ43.js";
-import "./chunk-DK2ODBNT.js";
+} from "./chunk-DCVJWGIA.js";
+import "./chunk-NQSMEUJ6.js";
 import "./chunk-QH3YI3ND.js";
-import "./chunk-HY3RIEZW.js";
-import "./chunk-TWQOKKAF.js";
-import "./chunk-JMURQODM.js";
+import "./chunk-ZPRBGW4Y.js";
+import "./chunk-23HFEKV7.js";
+import "./chunk-VZ7TYX6Z.js";
 import "./chunk-7PA7FGLD.js";
 import "./chunk-KYRDKK2D.js";
 import "./chunk-JF4JJAFP.js";
 import "./chunk-DENF4TPI.js";
 import "./chunk-WREYUH2E.js";
-import "./chunk-OCFDUCF4.js";
+import "./chunk-AW57IWNW.js";
 import "./chunk-2ESYSVXG.js";
 export {
   allCatalogs,

package/dist/composition/audio.js

@@ -25,7 +25,7 @@ import {
   sfxByFamily,
   sfxPackR2Key,
   sfxTransients
-} from "../chunk-JMURQODM.js";
+} from "../chunk-VZ7TYX6Z.js";
 import {
   SFX_PACK_ENTRIES,
   SFX_PACK_VERSION

package/dist/composition/brand-kit.js

@@ -17,11 +17,6 @@ var DEFAULT_BRAND_KIT = {
     { hex: "#262626", label: "Muted", usage: "Borders, subtle backgrounds" },
     { hex: "#a3a3a3", label: "Muted Text", usage: "Secondary text, captions" }
   ],
-  // Vendored families only (`VENDORED_FONT_FAMILIES`): the picker lists exactly
-  // those, and the render sandbox has no font egress, so a default outside the
-  // list is a value the user cannot re-select and a face that rasterizes as
-  // the generic fallback. The previous defaults ('DM Serif Display', 'Geist')
-  // were both.
   headingFont: { fontFamily: "Instrument Serif", fontWeight: 400 },
   bodyFont: { fontFamily: "Inter", fontWeight: 400 },
   syncCaptions: false,

package/dist/composition/graphics-plan.js

@@ -1,7 +1,7 @@
 import {
   placeInLegalArea,
   resolveBrandRefsDeep
-} from "../chunk-FYZVH3MC.js";
+} from "../chunk-YQ7FFW3G.js";
 import "../chunk-DSMLHYJ4.js";
 import "../chunk-JF4JJAFP.js";
 import {
@@ -26,9 +26,9 @@ import {
   PlanRect,
   StyleRole,
   ZPlane
-} from "../chunk-PODIYN2K.js";
-import "../chunk-W35ZMOXB.js";
-import "../chunk-EA6MYCYW.js";
+} from "../chunk-WZH57M53.js";
+import "../chunk-WPZKOVYF.js";
+import "../chunk-2B5VJZHL.js";
 import "../chunk-WREYUH2E.js";
 import "../chunk-2ESYSVXG.js";
 

package/dist/composition/ops.js

@@ -20,12 +20,12 @@ import {
   selectMediaClipAt,
   selectSceneMarkers,
   selectTracksByKind
-} from "../chunk-ZWMV6DD2.js";
+} from "../chunk-ICSZF37W.js";
 import "../chunk-KYRDKK2D.js";
-import "../chunk-TOJEXFXL.js";
-import "../chunk-PODIYN2K.js";
-import "../chunk-W35ZMOXB.js";
-import "../chunk-EA6MYCYW.js";
+import "../chunk-TFGKUWHY.js";
+import "../chunk-WZH57M53.js";
+import "../chunk-WPZKOVYF.js";
+import "../chunk-2B5VJZHL.js";
 import "../chunk-WREYUH2E.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/composition/primitive-catalog.js

@@ -26,7 +26,7 @@ import {
   validateCatalogFilters,
   validateParamsAgainstSchema,
   validatePrimitiveParams
-} from "../chunk-7FO3ZJ43.js";
+} from "../chunk-DCVJWGIA.js";
 import "../chunk-7PA7FGLD.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/composition/projection.js

@@ -7,8 +7,11 @@ import {
   MIN_PRESENCE_FOR_BEHIND,
   behindReadinessForOverlay,
   behindReadinessForTarget,
+  behindWindowsOf,
   buildSilhouetteKeepOutOutput,
   buildSubjectsOutput,
+  captionBehindWindowsOf,
+  clipOverlapsBehind,
   computeCropTransform,
   deriveBehindAnchor,
   detectDroppedBrandTokens,
@@ -17,6 +20,7 @@ import {
   evaluateOcclusionBudget,
   faceKeepOutForWindow,
   matteIntentKey,
+  matteWindowsByMediaId,
   outputToTrajectoryFrame,
   primaryClipForOverlay,
   reframeNeedsDetection,
@@ -26,7 +30,7 @@ import {
   silhouetteKeepOutForWindow,
   sourceRectToOutput,
   sourceWindowKey
-} from "../chunk-JJ6XD7NG.js";
+} from "../chunk-GIA2SVVB.js";
 import {
   BRAND_TOKEN_REFS,
   BRAND_TOKEN_ROOT_KEYS,
@@ -62,12 +66,12 @@ import {
   resolveLayoutIntent,
   resolveOverlayRegion,
   unionFaceKeepOutSeries
-} from "../chunk-FYZVH3MC.js";
+} from "../chunk-YQ7FFW3G.js";
 import {
   apcaLc
 } from "../chunk-DSMLHYJ4.js";
 import "../chunk-JF4JJAFP.js";
-import "../chunk-OCFDUCF4.js";
+import "../chunk-AW57IWNW.js";
 import "../chunk-2ESYSVXG.js";
 export {
   BEHIND_BAND,
@@ -92,10 +96,13 @@ export {
   apcaLc,
   behindReadinessForOverlay,
   behindReadinessForTarget,
+  behindWindowsOf,
   boundingBox,
   buildSilhouetteKeepOutOutput,
   buildSubjectsOutput,
+  captionBehindWindowsOf,
   captionsBehindEligible,
+  clipOverlapsBehind,
   coViewReframe,
   colorMix,
   componentBrandPalette,
@@ -111,6 +118,7 @@ export {
   faceKeepOutForWindow,
   lookupSafeZones,
   matteIntentKey,
+  matteWindowsByMediaId,
   normalizePlatform,
   outputToTrajectoryFrame,
   placeInLegalArea,

package/dist/composition/reframe/kenBurns.js

@@ -33,13 +33,9 @@ function kenBurnsToReframe(mode, durationSec) {
   const seg = {
     startSec: 0,
     endSec,
-    // `point` focus: detection-free, centers on the authored location. The pan
-    // sweep is expressed as a center ramp the derive bakes from ease (from→to).
     focus: { mode: "point", x: toX, y: 0.5 },
     zoom: KEN_BURNS_PAN_ZOOM,
     ease: { in: endSec, out: 0 },
-    // `bias.x` carries the pan ORIGIN offset (fromX − toX) so the derive can ramp
-    // the center from origin→authored-point across the ease edge. Source-normalized.
     bias: { x: fromX - toX, y: 0 },
     intent: `ken-burns-${mode}`
   };

package/dist/composition/reframe.js

@@ -4,8 +4,9 @@ import {
   ReframeSegment,
   ReframeSegmentFields,
   coverVisibleFraction,
-  detectAspectCropLoss
-} from "../chunk-EA6MYCYW.js";
+  detectAspectCropLoss,
+  findAspectCropLosses
+} from "../chunk-2B5VJZHL.js";
 import {
   MAX_SOURCE_MAGNIFICATION,
   NO_GAIN_ZOOM,
@@ -32,6 +33,7 @@ export {
   coverVisibleFraction,
   detectAspectCropLoss,
   faceOverSpan,
+  findAspectCropLosses,
   fitWindow,
   punchInWarrant,
   shotScaleZoom,

package/dist/composition/timeline.js

@@ -26,7 +26,7 @@ import {
   trackKindForSource,
   trimForSubRange,
   valueAt
-} from "../chunk-TWQOKKAF.js";
+} from "../chunk-23HFEKV7.js";
 import {
   expandClipIdsToLinkGroups,
   expandToLinkGroup,

package/dist/composition/validators/graphic-kinds.js

@@ -1,7 +1,7 @@
 import {
   AUTHORED_GRAPHIC_KINDS,
   GRAPHIC_ROLE_CANONICAL_KIND
-} from "../../chunk-W35ZMOXB.js";
+} from "../../chunk-WPZKOVYF.js";
 import "../../chunk-2ESYSVXG.js";
 export {
   AUTHORED_GRAPHIC_KINDS,

package/dist/composition/validators.js

@@ -48,7 +48,7 @@ import {
   WebhookDeliveryStatus,
   WebhookDestination,
   YoutubeDestination
-} from "../chunk-TOJEXFXL.js";
+} from "../chunk-TFGKUWHY.js";
 import {
   ANIMATABLE_PARAMS,
   AlphaLayerClipSource,
@@ -81,16 +81,16 @@ import {
   Transition,
   captionWords,
   captionsAreBehindSubject
-} from "../chunk-PODIYN2K.js";
+} from "../chunk-WZH57M53.js";
 import {
   AUTHORED_GRAPHIC_KINDS
-} from "../chunk-W35ZMOXB.js";
+} from "../chunk-WPZKOVYF.js";
 import {
   Focus,
   Reframe,
   ReframeSegment,
   ReframeSegmentFields
-} from "../chunk-EA6MYCYW.js";
+} from "../chunk-2B5VJZHL.js";
 import "../chunk-WREYUH2E.js";
 import "../chunk-2ESYSVXG.js";
 export {

package/dist/composition-ops.js

@@ -3,17 +3,17 @@ import {
   findClipById,
   findMarkerById,
   findTrackContainingClipId
-} from "./chunk-ZWMV6DD2.js";
+} from "./chunk-ICSZF37W.js";
 import {
   playableSpans
-} from "./chunk-DK2ODBNT.js";
+} from "./chunk-NQSMEUJ6.js";
 import "./chunk-QH3YI3ND.js";
-import "./chunk-HY3RIEZW.js";
-import "./chunk-TWQOKKAF.js";
-import "./chunk-JMURQODM.js";
+import "./chunk-ZPRBGW4Y.js";
+import "./chunk-23HFEKV7.js";
+import "./chunk-VZ7TYX6Z.js";
 import "./chunk-7PA7FGLD.js";
 import "./chunk-KYRDKK2D.js";
-import "./chunk-TOJEXFXL.js";
+import "./chunk-TFGKUWHY.js";
 import {
   CaptionSegment,
   CaptionStyle,
@@ -23,14 +23,14 @@ import {
   PerClipEffect,
   TimelineClip,
   Track
-} from "./chunk-PODIYN2K.js";
-import "./chunk-W35ZMOXB.js";
+} from "./chunk-WZH57M53.js";
+import "./chunk-WPZKOVYF.js";
 import {
   ReframeSegment
-} from "./chunk-EA6MYCYW.js";
+} from "./chunk-2B5VJZHL.js";
 import "./chunk-DENF4TPI.js";
 import "./chunk-WREYUH2E.js";
-import "./chunk-OCFDUCF4.js";
+import "./chunk-AW57IWNW.js";
 import "./chunk-2ESYSVXG.js";
 
 // ../composition-ops/src/index.ts
@@ -41,15 +41,6 @@ var genTrackId = (kind) => `track-${kind}-${crypto.randomUUID().slice(0, 8)}`;
 function wrapWithOpRecorder(base, opts) {
   const { record, getComposition } = opts;
   const wrapped = {
-    // ── clips ──
-    // clip.add is family-self-routing; a bare `media` source is ambiguous, so
-    // the editor's video-lane addClip stamps kind:'video' (replay byte-faithful:
-    // the SAME object goes to the base store and the op). Every mapping derives
-    // from ARGS + BEFORE-state only, so ops record BEFORE the base mutation —
-    // `before` is exact and a throwing base never leaves a phantom op behind
-    // (record throws first on invalid input; base throws are surfaced to the
-    // caller with the op already journaled, which the flush's server apply
-    // would then reject loudly — never silently).
     addClip: (clip, options) => {
       const before = getComposition();
       const c = clip.kind ? clip : { ...clip, kind: "video" };
@@ -89,7 +80,6 @@ function wrapWithOpRecorder(base, opts) {
       record({ type: "clip.update", clipId: id, patch }, getComposition());
       return base.setClipProperties(id, props);
     },
-    // ── overlays (pre-emit the overlay track on first add: pinned id, targeted clip.add) ──
     addOverlay: (clip) => {
       const before = getComposition();
       const track = before.tracks.find((t) => t.kind === "overlay");
@@ -114,7 +104,6 @@ function wrapWithOpRecorder(base, opts) {
       record({ type: "loadOverlays", clips }, getComposition());
       base.loadOverlays(clips);
     },
-    // ── audio (same pre-emit rule) ──
     addAudioClip: (clip) => {
       const before = getComposition();
       const track = before.tracks.find((t) => t.kind === "audio");
@@ -135,7 +124,6 @@ function wrapWithOpRecorder(base, opts) {
       record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
       base.updateAudioClip(id, updates);
     },
-    // ── markers ──
     addMarker: (marker) => {
       record({ type: "addMarker", marker }, getComposition());
       base.addMarker(marker);
@@ -148,12 +136,10 @@ function wrapWithOpRecorder(base, opts) {
       record({ type: "updateMarker", markerId: id, updates }, getComposition());
       base.updateMarker(id, updates);
     },
-    // ── crop / effects / captions / format ──
     setCropIntents: (clipId, segments) => {
       record({ type: "setCropIntents", clipId, segments }, getComposition());
       base.setCropIntents(clipId, segments);
     },
-    // Wholesale array — `[]` records the clear, same as any other set.
     setEffects: (clipId, effects) => {
       record({ type: "setEffects", clipId, effects }, getComposition());
       base.setEffects(clipId, effects);
@@ -170,7 +156,6 @@ function wrapWithOpRecorder(base, opts) {
       record({ type: "setFormat", format }, getComposition());
       base.setFormat(format);
     },
-    // ── tracks (always pin the id) ──
     addTrack: (kind, name, id) => {
       const useId = id ?? genTrackId(kind);
       record({ type: "addTrack", kind, ...name !== void 0 ? { name } : {}, id: useId }, getComposition());
@@ -204,7 +189,6 @@ function wrapWithOpRecorder(base, opts) {
       record({ type: "duplicateClip", clipId: id }, getComposition());
       return base.duplicateClip(id);
     },
-    // ── server-authoritative (cross-field timeline recompute) ──
     cutAndRipple: (start, end) => {
       record({ type: "cutAndRipple", start, end }, getComposition());
       base.cutAndRipple(start, end);
@@ -473,126 +457,33 @@ function resolveClipKind(clip, track) {
   return resolved;
 }
 var CompositionOp = z.discriminatedUnion("type", [
-  // ── clips ──
-  // `newTrackId` pins the id of the track created when `newTrack` is set, so a
-  // recorded op replays to the identical track (byte-faithful op-log).
-  // `.strict()` on every variant: an unknown op-level key (e.g. an LLM agent's
-  // typo) fails loud instead of being silently stripped. Scope is op-level only —
-  // nested validators (TimelineClip, Marker, …) keep their own passthrough.
-  // `clip.add` is family-self-routing: the clip's family (resolveClipKind —
-  // clip.kind, else derived from source, else the target track) picks the track.
-  // `trackId` targets an EXISTING same-family track; `newTrack`/`newTrackId`
-  // create a fresh track of the family (the id is pinned for byte-faithful
-  // op-replay — same role it played on the old `addClip`). A `media` clip with
-  // neither `clip.kind` nor `trackId` is rejected at apply time (ambiguous).
   z.object({ type: z.literal("clip.add"), clip: TimelineClip, trackId: z.string().optional(), newTrack: z.boolean().optional(), newTrackId: z.string().optional() }).strict(),
-  // `clip.remove` is cross-family: the store locates the clip by id across every
-  // track (one locator replaces the three family-specific removers).
   z.object({ type: z.literal("clip.remove"), clipId: z.string() }).strict(),
-  // `clip.update` is cross-family: the store locates the clip by id across every
-  // track and merges `patch` (one op replaces the three family-specific updaters
-  // updateClip/updateOverlay/updateAudioClip AND setClipProperties). The patch is
-  // `TimelineClip.partial()` — opacity/scale/rotation/region/fit are top-level
-  // TimelineClip fields, so they fold straight into the patch. This KILLS the
-  // historic region/fit silent-drop: the parallel `props` channel (a hand-kept
-  // ClipProps mirror that drifted from the validator) is gone — the patch IS the
-  // validator, so it can never miss a field. `playbackRate` is deliberately NOT
-  // here: it lives at `source.playbackRate`, not as a top-level field, and a rate
-  // change is a cross-field ripple recompute (server-authoritative), not a free
-  // merge — it does not belong in clip.update.
-  //
-  // SOURCE PATCH SEMANTICS (T2 note): the merge is SHALLOW (top-level only). A
-  // `patch.source` REPLACES the WHOLE `source` object — it does NOT deep-merge.
-  // So a partial source (e.g. `{ source: { kind: 'media', mediaId } }` to retarget
-  // media) WIPES every other source field (trim, reframe, volume, excludedRanges,
-  // …). To change ONE source channel, send the COMPLETE source object with that
-  // channel updated (read it from the current clip first). Use `setCropIntents` /
-  // `addExcludedRange` for the reframe/excluded channels instead of a source patch.
   z.object({ type: z.literal("clip.update"), clipId: z.string(), patch: TimelineClip.partial() }).strict(),
   z.object({ type: z.literal("removeClipsByMediaId"), mediaId: z.string() }).strict(),
-  // ── overlays (load stays; add/remove/update fold into clip.add/clip.remove/clip.update) ──
   z.object({ type: z.literal("loadOverlays"), clips: z.array(TimelineClip) }).strict(),
-  // ── markers ──
   z.object({ type: z.literal("addMarker"), marker: Marker }).strict(),
   z.object({ type: z.literal("removeMarker"), markerId: z.string() }).strict(),
   z.object({ type: z.literal("updateMarker"), markerId: z.string(), updates: Marker.partial() }).strict(),
-  // ── crop (reframe) ── op `type` kept as 'setCropIntents' so recorded op
-  // streams replay unchanged; the segment payload is now ReframeSegment[].
   z.object({ type: z.literal("setCropIntents"), clipId: z.string(), segments: z.array(ReframeSegment).nullable() }).strict(),
-  // ── effects ── the per-clip EFFECT channel (`TimelineClip.effects`). The field
-  // was always in the validator and `clip.add` always accepted it, but nothing
-  // could CHANGE it on an existing clip: the only route was a whole-clip
-  // `clip.update`, which this vocabulary steers callers away from (a partial
-  // `source` in that patch clobbers the source). WHOLESALE set; `effects: []`
-  // clears the channel — the same set/clear shape `setCropIntents` has. The item
-  // schema is the validator's own `PerClipEffect`, reused (never re-described).
   z.object({ type: z.literal("setEffects"), clipId: z.string(), effects: z.array(PerClipEffect) }).strict(),
-  // ── captions ── style-only overrides (font, color, position, emphasis). Reuse
-  // CaptionStyle.partial() so the op vocabulary never hand-drifts from the validator;
-  // setCaptionStyle merges (omitted fields don't clobber) onto composition.captions.style.
   z.object({ type: z.literal("setCaptionStyle"), style: CaptionStyle.partial() }).strict(),
-  // setCaptions replaces the caption SEGMENTS wholesale (word timings are one
-  // coherent document — the only writer used to be the transcript-slice lanes,
-  // which locked the caption layer away from clients with their own VO
-  // timings); `style` merges when given, keeps the existing style when omitted.
+  z.object({ type: z.literal("setCaptionDepth"), zPlane: z.enum(["front", "behind-subject"]) }).strict(),
   z.object({ type: z.literal("setCaptions"), segments: z.array(CaptionSegment), style: CaptionStyle.partial().optional() }).strict(),
-  // ── motion ── applyMotionPreset is the PUBLIC card-shelling op: wrap a static
-  // `card` clip's approved markup in a frame-driven motion shell (layout verbatim),
-  // mint it as a live component, and swap the clip source to that component (the
-  // director's `apply_motion_preset` capability, minus the box — the live lane).
-  // It is ROUTE-MATERIALIZED: generating the shell needs a director esbuild
-  // transpile, which the pure engine / applyOp mutation can't run, so the op route
-  // (`/composition/apply`) validates + orchestrates it and rewrites it to a
-  // `clip.update` BEFORE the mutation. `applyOp` therefore never applies it (it
-  // throws — reaching the pure engine means the route path was bypassed), and its
-  // recorded/invertible form is the substituted `clip.update` (whose inverse
-  // restores the prior card source). `preset` is `z.string()` here (validated
-  // against MOTION_PRESETS at the route, which owns @cueframe/authoring — this
-  // package stays authoring-free); the OpenAPI mirror enumerates the presets.
   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(),
-  // ── grids ── materializeGrid reads a clip's SOURCE-media temporal grid
-  // (beat map / word onsets / shot boundaries), maps each grid point from media
-  // time to TIMELINE time through the clip's placement, and writes `kind:<grid>`
-  // markers (replacing any prior materialization from the same clipId+grid).
-  // Like applyMotionPreset it is ROUTE-MATERIALIZED: the pure engine / applyOp
-  // MUTATION has no media reader, so the op route (`/composition/apply` +
-  // `/composition/ops`) resolves the grid evidence and rewrites the op to a
-  // batch of removeMarker+addMarker ops BEFORE the mutation. `applyOp` therefore
-  // never applies it (it throws — reaching the pure engine means the route path
-  // was bypassed), and its recorded/invertible form is the substituted marker
-  // ops (whose own inverses restore the prior markers). `maxMarkers` (≤ 2000)
-  // raises the default 500 cap; exceeding it fails loud with the count.
   z.object({ type: z.literal("materializeGrid"), clipId: z.string(), grid: z.enum(["beat", "word", "shot"]), maxMarkers: z.number().int().positive().max(2e3).optional() }).strict(),
-  // `captions.fromTranscript` is a REF op: attach caption content from the
-  // media's cached transcript (optionally a source-time window), sentence-split
-  // server-side. ROUTE-MATERIALIZED like applyMotionPreset/materializeGrid: the
-  // API route resolves it to `setCaptions` BEFORE the pure applier — the agent
-  // never pastes transcript text. applyOp throws on an unresolved instance (a
-  // pure applier cannot do I/O; silent no-op is the bug class this lane kills).
   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(),
-  // ── format ──
   z.object({ type: z.literal("setFormat"), format: Format.pick({ aspectRatio: true, fps: true, resolution: true }) }).strict(),
-  // ── tracks ──
   z.object({ type: z.literal("addTrack"), kind: Track.shape.kind, name: z.string().optional(), id: z.string().optional() }).strict(),
   z.object({ type: z.literal("removeTrack"), trackId: z.string() }).strict(),
-  // `volume` joined the pickable set with the track fader (2026-08-24). Review
-  // finding: the fader's store verb accepted it while THIS payload schema did
-  // not — so a fader move recorded into the op journal, or replayed over the
-  // REST-op path, failed validation. The store verb and the op vocabulary must
-  // widen together or the op-log lies about what the editor can do.
   z.object({ type: z.literal("updateTrack"), trackId: z.string(), updates: Track.pick({ name: true, enabled: true, volume: true }).partial() }).strict(),
   z.object({ type: z.literal("reorderTracks"), fromIndex: z.number(), toIndex: z.number() }).strict(),
   z.object({ type: z.literal("moveClipToTrack"), clipId: z.string(), targetTrackId: z.string(), newStartTime: z.number().optional() }).strict(),
-  // `newClipId` PINS the id of the copy duplicateClip mints (the store otherwise
-  // mints a uuid-suffixed id internally). Pinning makes the op deterministic so
-  // `invertOp` can return a `clip.remove` of that exact id (a non-pinned
-  // duplicateClip has no determinate inverse — invertOp throws for it).
   z.object({ type: z.literal("duplicateClip"), clipId: z.string(), newClipId: z.string().optional() }).strict(),
-  // ── server-authoritative (cross-field timeline recompute) ──
   z.object({ type: z.literal("cutAndRipple"), start: z.number(), end: z.number() }).strict(),
   z.object({ type: z.literal("ripple"), time: z.number(), amount: z.number() }).strict(),
   z.object({ type: z.literal("addExcludedRange"), clipId: z.string(), sourceStart: z.number(), sourceEnd: z.number(), reason: z.string().optional() }).strict(),
@@ -629,10 +520,6 @@ function applyOpToStore(store, op) {
     case "clip.remove":
       store.removeClip(op.clipId);
       break;
-    // `store.updateClip` is cross-family (locates the clip by id across every
-    // track, like `removeClip`), so it serves all three former family updaters
-    // AND setClipProperties' visual props (region/fit/opacity/scale/rotation +
-    // timing) — a plain partial merge of top-level TimelineClip fields.
     case "clip.update":
       store.updateClip(op.clipId, op.patch);
       break;
@@ -664,6 +551,9 @@ function applyOpToStore(store, op) {
     case "setCaptionStyle":
       store.setCaptionStyle(op.style);
       break;
+    case "setCaptionDepth":
+      store.setCaptionDepth(op.zPlane);
+      break;
     case "setCaptions":
       store.setCaptions(op.segments, op.style);
       break;
@@ -792,6 +682,8 @@ function invertOp(before, op) {
         }
       };
     }
+    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");
@@ -832,8 +724,6 @@ function invertOp(before, op) {
         );
       }
       return { type: "clip.remove", clipId: op.newClipId };
-    // ── DEFERRED (fail loud — see the doc-comment above for why none has a
-    //    clean per-op inverse in scope). ──
     case "cutAndRipple":
     case "ripple":
     case "addExcludedRange":
@@ -843,17 +733,8 @@ function invertOp(before, op) {
     case "loadOverlays":
     case "setCaptionStyle":
     case "setCaptions":
-    // applyMotionPreset is route-materialized into a clip.update before it is
-    // recorded, so invertOp is never asked to invert it in practice; if it is
-    // (a bypassed route path), fail loud — the real inverse lives on the
-    // substituted clip.update (which restores the prior card source).
     case "applyMotionPreset":
-    // materializeGrid is route-materialized into removeMarker+addMarker ops
-    // before it is recorded, so invertOp never inverts it in practice; the real
-    // inverses live on those substituted marker ops. Fail loud if reached.
     case "materializeGrid":
-    // captions.fromTranscript is route-materialized into setCaptions before it
-    // is recorded, so invertOp never inverts it in practice; fail loud if reached.
     case "captions.fromTranscript":
       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.`