@cueframe/kernel 0.1.1 → 0.1.2

package/dist/_members/composition/validators/graphicKinds.d.ts

@@ -1,32 +1,4 @@
-/**
- * ClipSource kinds that constitute an AUTHORED GRAPHIC — pure data, ZERO
- * imports, in its own module so the Temporal WORKFLOW bundle can value-import
- * it: `validators/composition.ts` imports `zid` (convex-helpers) for the
- * mediaId brand, so ANY value import of it — or of the validators barrel —
- * drags convex-helpers into the workflow isolate and breaks the bundle
- * (bundle.test.ts). Type imports stay on the barrel (erased at compile).
- *
- * ONE SSOT consumed by the compose no-discard gate
- * (the API layer), the director's
- * renderable-graphics lock (compileCssLayout.ts), the brief-exclusions gate
- * (briefContract.ts), and the track-family invariants. A new graphic kind
- * added to the ClipSource union MUST be added here too, or it silently misses
- * those gates (review finding 2026-07-10).
- */
 import type { GraphicRole } from "../graphics-plan/schemas.js";
 export declare const AUTHORED_GRAPHIC_KINDS: readonly ["overlay", "component", "card", "alpha-layer"];
 export type AuthoredGraphicKind = (typeof AUTHORED_GRAPHIC_KINDS)[number];
-/**
- * The canonical authored KIND for each planner graphic ROLE — the clip kind the
- * deterministic graphics compiler (graphics-plan/compile.ts) emits and the LLM
- * designer authors by default. EVERY role currently compiles to an `overlay`
- * clip: title-card/stat/lower-third/pull-quote are overlay primitives, `hero`'s
- * behind-subject look is a zPlane ON an overlay (not a distinct kind), and
- * `logo-tag` is a watermark overlay.
- *
- * The bridge the brief-EXCLUSIONS filter (briefContract.dropExcludedPlanGraphics)
- * needs: plan graphics carry a ROLE, exclusions name a KIND. `Record<GraphicRole,
- * …>` makes a NEW role a COMPILE error here — the same add-or-silently-miss
- * discipline the kinds SSOT above enforces.
- */
 export declare const GRAPHIC_ROLE_CANONICAL_KIND: Record<GraphicRole, AuthoredGraphicKind>;

package/dist/_members/composition/validators/render.d.ts

@@ -127,7 +127,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -276,7 +276,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -374,16 +374,16 @@ export declare const RenderSnapshot: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }, {
             id: string;
             kind: "overlay" | "video" | "effect" | "audio" | "image";
             contents: unknown[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }>, "many">;
         markers: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -979,7 +979,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -1077,9 +1077,9 @@ export declare const RenderSnapshot: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -1214,9 +1214,9 @@ export declare const RenderSnapshot: z.ZodObject<{
             id: string;
             kind: "overlay" | "video" | "effect" | "audio" | "image";
             contents: unknown[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -2662,7 +2662,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -2760,9 +2760,9 @@ export declare const RenderSnapshot: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -3133,9 +3133,9 @@ export declare const RenderSnapshot: z.ZodObject<{
             id: string;
             kind: "overlay" | "video" | "effect" | "audio" | "image";
             contents: unknown[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -3775,7 +3775,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -3924,7 +3924,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -4022,16 +4022,16 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }, {
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }>, "many">;
             markers: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
@@ -4627,7 +4627,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -4725,9 +4725,9 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -4862,9 +4862,9 @@ export declare const RenderJob: z.ZodObject<{
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -6310,7 +6310,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -6408,9 +6408,9 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -6781,9 +6781,9 @@ export declare const RenderJob: z.ZodObject<{
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -7344,7 +7344,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -7442,9 +7442,9 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -7879,9 +7879,9 @@ export declare const RenderJob: z.ZodObject<{
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;

package/dist/_members/composition-ops/alphaLayers.d.ts

@@ -1,70 +1,14 @@
-/**
- * Alpha-layer clip walk — the SINGLE shared, V8-safe home for finding a wire
- * composition's alpha-layer clips (overlay-track clips whose
- * `source.kind === 'alpha-layer'`).
- *
- * This is PURE and crypto-free on purpose: both the director (Node worker, which
- * bakes the alpha) and Convex (V8 isolate, which materializes the authored
- * tsxSource into the stage body) walk the SAME composition for the SAME clips —
- * so the walk is the SSOT and lives here, importable from both. The director's
- * content-hash (`alphaLayerHash`, uses `node:crypto`) stays director-side; it is
- * NOT shareable with the V8 isolate and is orthogonal to the walk.
- */
 export interface AlphaLayerClipRef {
     clipId: string;
     componentId: string;
     props: Record<string, unknown>;
-    /** timeline seconds (used to derive the bake's durationInFrames) */
     startTime: number;
     duration: number;
 }
-/**
- * Walk a wire composition for alpha-layer clips (overlay-track clips whose
- * `source.kind === 'alpha-layer'`). Pure + tolerant of unknown shape (skips
- * malformed entries rather than throwing — the validator already gated saves).
- */
 export declare function collectAlphaLayerClips(composition: unknown): AlphaLayerClipRef[];
-/**
- * Walk a wire composition for RAW `component` clip sources — sources that have
- * NOT been desugared and therefore cannot be projected by the renderer.
- *
- * `component` is a first-class `ClipSource` in the validator, but it is an
- * AUTHORING shape, never a render one: the cloud's save/writer chokepoint
- * (`the server's composition projection`) lowers every one of them to an
- * `alpha-layer` or a `custom` overlay before it is persisted, reading the
- * component's `executionMode` from the `installedComponents` table. Anything
- * that reaches `projectOverlayTrack` still wearing `kind:'component'` throws
- * `kind=component is invalid on an overlay track`.
- *
- * That throw is why this exists. On the desktop lane there is no such
- * chokepoint (and no registry to lower against), so an agent-authored component
- * clip committed straight to the store, the preview projected it during render,
- * and the throw escaped a `useMemo` into the app-root ErrorBoundary — the entire
- * editor replaced by "Something went wrong", with the broken composition saved,
- * so every subsequent open died the same way. Observed 2026-08-18.
- *
- * Two callers, which is the point of putting it here rather than in either of
- * them: the desktop plane REFUSES an apply that would create one, and the
- * preview GATE holds the player with a readable reason if a project already
- * contains one. The first stops the state being reachable; the second is how
- * anyone who already reached it gets their project open again.
- *
- * Pure + tolerant of unknown shape, like its siblings above.
- */
 export declare function collectRawComponentClips(composition: unknown): string[];
 export interface LiveComponentClipRef {
     clipId: string;
     componentId: string;
 }
-/**
- * Walk a wire composition for LIVE component-backed `custom` overlays — the
- * bakeless-lane peer of `collectAlphaLayerClips`. A live component desugars (at
- * the save writer) to `{ kind:'overlay', primitiveId:'custom', params:{
- * componentId, ...props } }` — a componentId REFERENCE with no frozen source.
- * The renderJob-create path (renders.ts) walks these to materialize each
- * component's FRESH transpiled jsSource per render (keyed by clipId). Pure +
- * tolerant of unknown shape. Desktop-INLINE customs (which carry their own
- * `params.sourceCode` and no `componentId`) are NOT returned — they need no
- * materialization.
- */
 export declare function collectLiveComponentClips(composition: unknown): LiveComponentClipRef[];

package/dist/_members/composition-ops/index.d.ts

@@ -1,79 +1,11 @@
-/**
- * @cueframe/composition-ops — the composition OPERATION model (single home).
- *
- * One package owns "what an op is": the serializable `CompositionOp` discriminated
- * union, `applyOp(composition, op)` (pure — applies an op to a wire Composition),
- * and `invertOp` (the inverse, for the op-log / multiplayer undo).
- *
- * Layering (deliberate, not fragmentation):
- *  - This package = the op vocabulary + pure apply/inverse. OSS; the agent and the
- *    editor both emit + optimistically-apply ops through it.
- *  - apply logic is REUSED from `@cueframe/core` (the headless store), not forked.
- *  - The server-authoritative persistence (transactional scoped row writes + the
- *    op-log) is ONE generic Convex mutation in `the server's op applier`
- *    — a thin consumer of this package. Convex functions must live in the Convex app;
- *    that is the only piece outside this package, and it does not grow per-op.
- */
 import { z } from 'zod';
 import { Composition } from '../composition/validators/index.js';
 import type { TimelineClip as TimelineClipT, Track as TrackT } from '../composition/validators/index.js';
 import { type HeadlessStore } from '../composition/ops/index.js';
-/** A clip's track FAMILY (mirrors `Track.kind`). */
 export type ClipKind = TrackT['kind'];
-/** The three families a MEDIA item can belong to. */
 export type MediaFamily = Extract<ClipKind, 'video' | 'audio' | 'image'>;
-/**
- * The timeline family of a media item, derived from its `mimeType`.
- *
- * `mimeType` is the ONLY trustworthy statement of what a media item is: it is
- * `v.string()` (required) on the schema and byte-detected at ingest — populated
- * on 305/305 prod rows. `mediaItems.kind` is a duplicate of the same fact that
- * nobody maintains (null on every video uploaded in 2026-08) and that is
- * overloaded with provenance values (`source`, `stock`, `gif`, `asset`) which
- * are not families at all. Measured 2026-08-17: where `kind` was set it agreed
- * with the mimeType prefix in 232/232 rows. So there is one fact here, and this
- * is where it is read.
- *
- * THROWS on anything it cannot name. A media item whose type we can't determine
- * must not be silently treated as video — that is precisely how an image reached
- * the video frame-extractor and hung the render for 30s on `delayRender`.
- */
 export declare function mediaFamily(mimeType: string): MediaFamily;
-/**
- * Resolve a clip's track family — the single determinate rule:
- *   `clip.kind  ??  deriveFromSource(source.kind)  ??  track?.kind  ??  throw`.
- *
- * The `track?.kind` step is a PLACEMENT reading, not a family oracle: "this clip
- * is going on that track, so treat it as that family." It is correct here
- * because this function is PURE — it has no database, and a media clip's real
- * family lives on the media item (`mediaFamily(mimeType)`), which only a
- * DB-aware caller can read. The editor's recording store legitimately adds media
- * clips with no `kind` and a target track.
- *
- * What must NOT happen is a *server* guard treating this placement reading as
- * an assertion and then rejecting the caller for it — that was the old
- * `image_media_on_video_track`. The server stamps the true family from
- * `mediaFamily(mediaItem.mimeType)` at the Convex ingress before folding ops, so
- * by the time this runs server-side, `clip.kind` is already authoritative and
- * the track step is never reached.
- *
- * FAILS LOUD for a media source with neither `clip.kind` nor a track — there is
- * no safe default (no-fallbacks rule). Pure: no state, no side effects.
- */
 export declare function resolveClipKind(clip: Pick<TimelineClipT, 'kind' | 'source'>, track?: Pick<TrackT, 'kind'>): ClipKind;
-/**
- * The serializable composition operation. One discriminated union; every writer
- * (agent, editor) emits these; the server validates with this schema at the
- * boundary. Local-only ops (selectClip/selectOverlay/clearOverlaySelection) are
- * deliberately ABSENT — selection is UI state, never persisted.
- *
- * Cross-field/ripple ops (`cutAndRipple`, `ripple`, `add/removeExcludedRange`)
- * are server-AUTHORITATIVE: the server mutation recomputes downstream timeline
- * state within one transaction (they do not free-merge). They are still
- * expressed here so all writers share one vocabulary. (A `playbackRate` change
- * is also cross-field — it lives at `source.playbackRate` and ripples downstream
- * clips — which is exactly why it is NOT a `clip.update` patch field.)
- */
 export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"clip.add">;
     clip: z.ZodObject<{
@@ -444,7 +376,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -512,7 +444,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -797,7 +729,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -938,7 +870,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1085,7 +1017,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1232,7 +1164,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1709,7 +1641,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1777,7 +1709,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2063,7 +1995,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2204,7 +2136,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2349,7 +2281,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2494,7 +2426,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2966,7 +2898,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3034,7 +2966,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3319,7 +3251,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3460,7 +3392,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3604,7 +3536,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3748,7 +3680,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -4386,6 +4318,15 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
         annotationColor?: string | undefined;
         maxWidthPercent?: number | undefined;
     };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"setCaptionDepth">;
+    zPlane: z.ZodEnum<["front", "behind-subject"]>;
+}, "strict", z.ZodTypeAny, {
+    type: "setCaptionDepth";
+    zPlane: "front" | "behind-subject";
+}, {
+    type: "setCaptionDepth";
+    zPlane: "front" | "behind-subject";
 }>, z.ZodObject<{
     type: z.ZodLiteral<"setCaptions">;
     segments: z.ZodArray<z.ZodObject<{
@@ -4868,70 +4809,8 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
     rangeIdx: number;
 }>]>;
 export type CompositionOp = z.infer<typeof CompositionOp>;
-/**
- * Apply an op to a wire Composition, returning the new Composition (pure).
- * Reuses `@cueframe/core`'s tested op logic via a headless store — no fork.
- */
 export declare function applyOp(composition: Composition, op: CompositionOp): Composition;
-/**
- * Dispatch ONE op onto a LIVE store — the op→method switch, extracted from
- * `applyOp` so there is exactly one of it.
- *
- * `applyOp` is pure: it mints a throwaway headless store, folds, and hands back
- * a new Composition. That serves every caller that OWNS the composition value
- * (the Convex mutation, the local-harness store, the ensemble author). It does
- * NOT serve a caller whose composition lives inside somebody else's store —
- * desktop's zustand `CompositionState`, which has no whole-composition setter
- * and whose op-recorder/undo trail only sees writes that go through its
- * methods. Handing that caller a fresh Composition value would be a dead end;
- * the only way in is the methods, which is precisely what this switch calls.
- *
- * So: `HeadlessStore` here is a STRUCTURAL contract (`CompositionOps` + a
- * `getState`), not a concrete class — `@cueframe/authoring`'s `CompositionStore`
- * and the desktop store satisfy it, and `LocalExecutor` (apps/studio/src/llm) folds
- * a validated batch through it op-by-op. Writing a second switch for that lane
- * is what "one vocabulary" exists to prevent: it would drift silently the first
- * time an op is added here and forgotten there.
- *
- * NOT transactional on its own — it applies ONE op and a throw leaves the store
- * wherever it got to. A caller wanting the server's all-or-nothing contract
- * validates the whole batch on a scratch fold (`ops.reduce(applyOp, current)`)
- * FIRST, and only then commits through this.
- */
 export declare function applyOpToStore(store: HeadlessStore, op: CompositionOp): void;
-/**
- * The inverse op (for the op-log → selective multiplayer undo / diff / audit).
- *
- * `invertOp(before, op)` returns the op that, applied to `applyOp(before, op)`,
- * restores `before`. It needs the PRE-image to capture the value the forward op
- * overwrote (the patched fields, the replaced reframe segments, the removed
- * clip, …).
- *
- * Coverage (value-restoring): clip.add↔clip.remove, clip.update (prior fields),
- * markers (add/remove/update), setCropIntents (prior segments), setEffects (prior
- * effect stack), setFormat (prior values), addTrack↔removeTrack, updateTrack
- * (prior name/enabled), reorderTracks (reversed), moveClipToTrack (move back),
- * duplicateClip (clip.remove of the PINNED newClipId).
- *
- * DEFERRED — these THROW (fail loud; a wrong inverse silently corrupts undo, so
- * we never fake one):
- *  - cutAndRipple / ripple / addExcludedRange / removeExcludedRange — server-
- *    authoritative cross-field timeline recomputes (clips split/merge, durations
- *    and downstream startTimes recompute, markers + caption words ripple). No
- *    clean single-op inverse; restoring them is a snapshot-restore concern.
- *  - removeTrack — removes a track AND its clips at a position; there is no
- *    op to re-insert a populated track at an index (addTrack appends an EMPTY
- *    track), so the pre-image can't be restored as one op.
- *  - removeClipsByMediaId / loadOverlays — whole-channel replace/clear (multiple
- *    clips across tracks, with positions and scene-marker side effects); no
- *    single restoring op.
- *  - setCaptionStyle — MERGES (and creates the captions container when absent)
- *    with no clear/drop op, so a forward call that adds a style key (or the
- *    container) can't be exactly reverted.
- *  - duplicateClip WITHOUT `newClipId` — the copy's id is store-minted
- *    (non-deterministic), so there is no clip id to remove. Pin `newClipId` for a
- *    deterministic inverse.
- */
 export declare function invertOp(before: Composition, op: CompositionOp): CompositionOp;
 export { createRecordingStore, type RecordingStore } from './recordingStore.js';
 export { wrapWithOpRecorder, type RecordableOps, type OpRecorderOpts } from './opRecorder.js';