@cueframe/kernel 0.1.0 → 0.1.2

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

@@ -61,57 +61,12 @@ export declare const MediaClipSource: z.ZodObject<{
     muted: z.ZodOptional<z.ZodBoolean>;
     playbackRate: z.ZodOptional<z.ZodNumber>;
     sync: z.ZodOptional<z.ZodEnum<["video", "independent"]>>;
-    /**
-     * Ken-Burns motion preset for `kind: "image"` tracks. The renderer's
-     * `<StillFrame>` reads this to drive a per-frame transform over the
-     * clip's duration. Default is `"in"` (gentle zoom-in) — chosen because
-     * still photos with zero motion read as "broken video" against
-     * surrounding b-roll. Set to `"none"` to opt out. Ignored on non-image
-     * tracks.
-     */
     kenBurns: z.ZodOptional<z.ZodEnum<["in", "out", "pan-l", "pan-r", "none"]>>;
-    /**
-     * Audio mix override for `kind: "audio"` tracks (SFX / music beds).
-     * `volumeDb` is decibels relative to source (negative = quieter); the
-     * renderer converts to linear gain via `10^(dB/20)`. Default at render
-     * time is -12 dB for stock SFX beds — quiet enough to sit under VO
-     * without ducking. `fadeInMs` / `fadeOutMs` interpolate linearly from
-     * silence to `volumeDb` (and back) at the clip's edges; default 200 ms
-     * each. All three are ignored on non-audio tracks.
-     */
     volumeDb: z.ZodOptional<z.ZodNumber>;
     fadeInMs: z.ZodOptional<z.ZodNumber>;
     fadeOutMs: z.ZodOptional<z.ZodNumber>;
-    /**
-     * Loop the underlying media until the clip's `duration` runs out, instead
-     * of letting the media play to its natural end and freezing on the last
-     * frame (video / gif) or going silent (audio). Used by gif enrichment
-     * clips that may be shorter than the moment they cover, and by sfx
-     * ambient beds. Ignored on `kind: "image"` tracks (stills don't have a
-     * source timeline to loop).
-     */
     loop: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * What this audio-track clip IS, for mix policy + eval. Absent on video/image
-     * clips (the track-family enum on TimelineClip stays untouched — nothing
-     * downstream switches on family; `audioRole` lives on the SOURCE like
-     * `volumeDb`). SFX vs music vs VO is otherwise indistinguishable to the
-     * duck/master/eval logic. (`sfxCompile` stamps `sfx`/`music`; VO is future.)
-     * `ambience` is a bed that HOLDS under VO — it loops, sits at the BOTTOM of the
-     * mix, and is NEVER duck-stamped (founder ruling: ambience does not duck under
-     * speech; no beat map, no anchor semantics).
-     */
     audioRole: z.ZodOptional<z.ZodEnum<["sfx", "music", "vo", "ambience"]>>;
-    /**
-     * Speech-aware ducking (music / vo roles only). Deterministic: the render
-     * derives the duck envelope from the composition's OWN timeline-aligned
-     * caption words — no audio analysis, no ffmpeg sidechain. `duckDb` is the
-     * gain applied during speech (e.g. -12); `attackMs`/`releaseMs` ramp the
-     * envelope in/out (defaults 150 / 400). `windows` are explicit speech spans
-     * (timeline ms) — REQUIRED when the composition has no captions; when
-     * captions exist the projection derives windows from `captions.segments`
-     * words and `windows` MUST be absent (one SSOT, no drift).
-     */
     duck: z.ZodOptional<z.ZodObject<{
         duckDb: z.ZodNumber;
         attackMs: z.ZodNumber;
@@ -143,14 +98,6 @@ export declare const MediaClipSource: z.ZodObject<{
             endMs: number;
         }[] | undefined;
     }>>;
-    /**
-     * SFX event anchor — provenance + re-resolution handle for a hit bound to a
-     * graphic/transition entrance. NOT consumed at render (`startTime` stays the
-     * single placement truth; see the sfxCompile drift note). `clipId` is the
-     * overlay/video clip whose entrance this hits; `offsetMs` is vs that clip's
-     * `startTime` (usually 0). Exists so re-resolution + eval can re-derive the
-     * binding after an amendment. Absent on non-SFX audio clips.
-     */
     anchor: z.ZodOptional<z.ZodObject<{
         clipId: z.ZodString;
         offsetMs: z.ZodNumber;
@@ -161,20 +108,6 @@ export declare const MediaClipSource: z.ZodObject<{
         clipId: string;
         offsetMs: number;
     }>>;
-    /**
-     * The camera channel — the canonical `reframe` model. `segments` tile the
-     * clip's duration and animate a source→output viewport: each carries WHO
-     * the camera tracks (`focus`), HOW TIGHT (`zoom`, <1 punches in), an optional
-     * fine framing nudge (`bias`), and optional zoom-ramp easing (`ease`). The
-     * derive math (deriveTrajectory) honors these directly — no closed-enum
-     * framing names, no hardcoded scale constants.
-     *
-     * When omitted, the renderer plays the raw source (no crop). When present,
-     * the variant cache keys by `hashReframe(reframe.segments)`.
-     *
-     * Replaces the deleted subject-centric `cropIntents` (2026-06-14 cutover —
-     * one viewport primitive for all clip kinds).
-     */
     reframe: z.ZodOptional<z.ZodObject<{
         segments: z.ZodArray<z.ZodEffects<z.ZodObject<{
             startSec: z.ZodNumber;
@@ -462,7 +395,7 @@ export declare const MediaClipSource: 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;
@@ -530,7 +463,7 @@ export declare const MediaClipSource: 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;
@@ -559,11 +492,6 @@ export declare const ComponentClipSource: z.ZodObject<{
     kind: z.ZodLiteral<"component">;
     componentId: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    /** Depth plane, mirroring OverlayClipSource — without this field the cloud
-     *  motion-preset sink's zPlane carry was silently STRIPPED at parse (Opus
-     *  review F1), planting a lane asymmetry that would fire the day cards are
-     *  allowed behind-subject. NOTE: the save-time component→custom desugar must
-     *  also carry it when behind-cards land. */
     zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
 }, "strip", z.ZodTypeAny, {
     kind: "component";
@@ -580,14 +508,7 @@ export declare const OverlayClipSource: z.ZodObject<{
     kind: z.ZodLiteral<"overlay">;
     primitiveId: z.ZodString;
     params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    /** Launch-grade depth (spec 2026-06-11): which z-plane this overlay renders on.
-     *  'behind-subject' = under the subject cut-out (the matte occludes it).
-     *  Extensible enum, NOT a boolean — later planes ('behind-background') are additive.
-     *  Default front. Depth fields (zPlane/anchor/parallax) mirror the TS shape in
-     *  `@cueframe/core/render/types#CompositionOverlay`. */
     zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
-    /** Durable anchor in SCENE space (source-normalized [0,1]); projected through the
-     *  clip's crop trajectory at render (world-lock). System-computed default; agent may set. */
     anchor: z.ZodOptional<z.ZodObject<{
         space: z.ZodLiteral<"scene">;
         x: z.ZodNumber;
@@ -601,7 +522,6 @@ export declare const OverlayClipSource: z.ZodObject<{
         y: number;
         space: "scene";
     }>>;
-    /** Differential vs camera motion: 0 = locked to scene; small ± = depth parallax. */
     parallax: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     kind: "overlay";
@@ -639,17 +559,6 @@ export declare const EffectClipSource: z.ZodObject<{
     primitiveId: string;
     params?: Record<string, unknown> | undefined;
 }>;
-/**
- * An owned `.cueframe` component composited as a BAKED ALPHA video (Task 2.6b).
- * Per-tenant component code is NEVER run in the shared cloud renderer — it is
- * baked locally/isolated to an alpha video and composited as trusted pixels. This
- * variant carries only the AUTHORED truth (the component file + its props + the
- * composite z-plane). The DERIVED baked-alpha R2 key is a render artifact and
- * lives in the `renderAssets` envelope (render-assets SSOT), NOT here — the
- * composition round-trips `Composition.parse` as pure authored intent, and the
- * alpha is re-baked on edit. zPlane mirrors OverlayClipSource (compose over/under
- * the subject matte). Lands on overlay tracks.
- */
 export declare const AlphaLayerClipSource: z.ZodObject<{
     kind: z.ZodLiteral<"alpha-layer">;
     componentId: z.ZodString;
@@ -666,34 +575,10 @@ export declare const AlphaLayerClipSource: z.ZodObject<{
     props: Record<string, unknown>;
     zPlane?: "front" | "behind-subject" | undefined;
 }>;
-/**
- * A graphic authored as a standalone HTML/CSS fragment, carried VERBATIM into the
- * render (dangerouslySetInnerHTML) — the storyboard-first medium. Remotion IS
- * Chromium (probe #1: AE@fuzz-3% = 0 px), so the cheap headless still and the
- * final Remotion wrap draw the IDENTICAL markup — the port is a WRAPPER, not a
- * translation. This variant carries the AUTHORED truth only: the markup + an
- * optional brand-token map. The graphic's output-space keep-out box is the clip's
- * `region` (on TimelineClip), NOT here. Lands on overlay tracks; zPlane mirrors
- * OverlayClipSource (front default; behind-subject world-lock is a follow-up).
- */
 export declare const CardClipSource: z.ZodObject<{
     kind: z.ZodLiteral<"card">;
-    /** Standard HTML/CSS, verbatim. A `<style>` block may be inlined. No <script>
-     *  (innerHTML never executes it) — decoration only. Required + non-empty. */
     html: z.ZodString;
-    /** Brand-token bindings: each value is a literal OR a whole-string `$brand:<path>`
-     *  ref. Resolved deep at render (resolveBrandRefsDeep — the SAME resolver the
-     *  graphics compiler + alpha bake use) into `--cf-<key>` CSS custom properties on
-     *  the wrapper box; the authored CSS references them as `var(--cf-<key>)`. Keeps
-     *  the payload standard CSS while staying brand-resolvable, with no inline-string
-     *  substitution. */
     tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    /** Depth plane. FRONT ONLY for now — behind-subject cards are not wired into
-     *  the matte pipeline (the depth predicates in depth.ts / variant-keys /
-     *  resolve-behind-placement exclude card), so admitting "behind-subject" here
-     *  would render the card unoccluded with no matte and no error. The wire
-     *  refuses it LOUDLY instead; widen to the OverlayClipSource enum when the
-     *  behind wiring lands (review finding 2026-07-10). */
     zPlane: z.ZodOptional<z.ZodLiteral<"front">>;
 }, "strip", z.ZodTypeAny, {
     kind: "card";
@@ -706,24 +591,6 @@ export declare const CardClipSource: z.ZodObject<{
     zPlane?: "front" | undefined;
     tokens?: Record<string, string> | undefined;
 }>;
-/**
- * COMPOUND CLIP — a clip whose source is another composition.
- *
- * The content union was `TimelineClip | Gap` with a CLOSED source union, so a
- * sequence could never contain a sequence: a reusable segment (an intro, a
- * lower-third package, last week's cut) had to be flattened by hand into every
- * composition that wanted it, and edits to the original reached none of them.
- *
- * This is deliberately strategic surface, not an NLE luxury: it is the same
- * shape `derive_composition` / `fromComposition` traffic in — a composition
- * addressable AS a clip is how "every format from one edit" becomes a
- * timeline object rather than a workflow.
- *
- * `compositionId` is a REFERENCE — the document does not embed the child, so
- * the child's edits flow through. Resolution (id → Composition) happens at
- * projection time via a caller-supplied map; the wire stays self-contained.
- * `trim` selects a window of the child's own timeline, like a media trim.
- */
 export declare const CompositionClipSource: z.ZodObject<{
     kind: z.ZodLiteral<"composition">;
     compositionId: z.ZodString;
@@ -783,57 +650,12 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     muted: z.ZodOptional<z.ZodBoolean>;
     playbackRate: z.ZodOptional<z.ZodNumber>;
     sync: z.ZodOptional<z.ZodEnum<["video", "independent"]>>;
-    /**
-     * Ken-Burns motion preset for `kind: "image"` tracks. The renderer's
-     * `<StillFrame>` reads this to drive a per-frame transform over the
-     * clip's duration. Default is `"in"` (gentle zoom-in) — chosen because
-     * still photos with zero motion read as "broken video" against
-     * surrounding b-roll. Set to `"none"` to opt out. Ignored on non-image
-     * tracks.
-     */
     kenBurns: z.ZodOptional<z.ZodEnum<["in", "out", "pan-l", "pan-r", "none"]>>;
-    /**
-     * Audio mix override for `kind: "audio"` tracks (SFX / music beds).
-     * `volumeDb` is decibels relative to source (negative = quieter); the
-     * renderer converts to linear gain via `10^(dB/20)`. Default at render
-     * time is -12 dB for stock SFX beds — quiet enough to sit under VO
-     * without ducking. `fadeInMs` / `fadeOutMs` interpolate linearly from
-     * silence to `volumeDb` (and back) at the clip's edges; default 200 ms
-     * each. All three are ignored on non-audio tracks.
-     */
     volumeDb: z.ZodOptional<z.ZodNumber>;
     fadeInMs: z.ZodOptional<z.ZodNumber>;
     fadeOutMs: z.ZodOptional<z.ZodNumber>;
-    /**
-     * Loop the underlying media until the clip's `duration` runs out, instead
-     * of letting the media play to its natural end and freezing on the last
-     * frame (video / gif) or going silent (audio). Used by gif enrichment
-     * clips that may be shorter than the moment they cover, and by sfx
-     * ambient beds. Ignored on `kind: "image"` tracks (stills don't have a
-     * source timeline to loop).
-     */
     loop: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * What this audio-track clip IS, for mix policy + eval. Absent on video/image
-     * clips (the track-family enum on TimelineClip stays untouched — nothing
-     * downstream switches on family; `audioRole` lives on the SOURCE like
-     * `volumeDb`). SFX vs music vs VO is otherwise indistinguishable to the
-     * duck/master/eval logic. (`sfxCompile` stamps `sfx`/`music`; VO is future.)
-     * `ambience` is a bed that HOLDS under VO — it loops, sits at the BOTTOM of the
-     * mix, and is NEVER duck-stamped (founder ruling: ambience does not duck under
-     * speech; no beat map, no anchor semantics).
-     */
     audioRole: z.ZodOptional<z.ZodEnum<["sfx", "music", "vo", "ambience"]>>;
-    /**
-     * Speech-aware ducking (music / vo roles only). Deterministic: the render
-     * derives the duck envelope from the composition's OWN timeline-aligned
-     * caption words — no audio analysis, no ffmpeg sidechain. `duckDb` is the
-     * gain applied during speech (e.g. -12); `attackMs`/`releaseMs` ramp the
-     * envelope in/out (defaults 150 / 400). `windows` are explicit speech spans
-     * (timeline ms) — REQUIRED when the composition has no captions; when
-     * captions exist the projection derives windows from `captions.segments`
-     * words and `windows` MUST be absent (one SSOT, no drift).
-     */
     duck: z.ZodOptional<z.ZodObject<{
         duckDb: z.ZodNumber;
         attackMs: z.ZodNumber;
@@ -865,14 +687,6 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
             endMs: number;
         }[] | undefined;
     }>>;
-    /**
-     * SFX event anchor — provenance + re-resolution handle for a hit bound to a
-     * graphic/transition entrance. NOT consumed at render (`startTime` stays the
-     * single placement truth; see the sfxCompile drift note). `clipId` is the
-     * overlay/video clip whose entrance this hits; `offsetMs` is vs that clip's
-     * `startTime` (usually 0). Exists so re-resolution + eval can re-derive the
-     * binding after an amendment. Absent on non-SFX audio clips.
-     */
     anchor: z.ZodOptional<z.ZodObject<{
         clipId: z.ZodString;
         offsetMs: z.ZodNumber;
@@ -883,20 +697,6 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         clipId: string;
         offsetMs: number;
     }>>;
-    /**
-     * The camera channel — the canonical `reframe` model. `segments` tile the
-     * clip's duration and animate a source→output viewport: each carries WHO
-     * the camera tracks (`focus`), HOW TIGHT (`zoom`, <1 punches in), an optional
-     * fine framing nudge (`bias`), and optional zoom-ramp easing (`ease`). The
-     * derive math (deriveTrajectory) honors these directly — no closed-enum
-     * framing names, no hardcoded scale constants.
-     *
-     * When omitted, the renderer plays the raw source (no crop). When present,
-     * the variant cache keys by `hashReframe(reframe.segments)`.
-     *
-     * Replaces the deleted subject-centric `cropIntents` (2026-06-14 cutover —
-     * one viewport primitive for all clip kinds).
-     */
     reframe: z.ZodOptional<z.ZodObject<{
         segments: z.ZodArray<z.ZodEffects<z.ZodObject<{
             startSec: z.ZodNumber;
@@ -1184,7 +984,7 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [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;
@@ -1252,7 +1052,7 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [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;
@@ -1280,11 +1080,6 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     kind: z.ZodLiteral<"component">;
     componentId: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    /** Depth plane, mirroring OverlayClipSource — without this field the cloud
-     *  motion-preset sink's zPlane carry was silently STRIPPED at parse (Opus
-     *  review F1), planting a lane asymmetry that would fire the day cards are
-     *  allowed behind-subject. NOTE: the save-time component→custom desugar must
-     *  also carry it when behind-cards land. */
     zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
 }, "strip", z.ZodTypeAny, {
     kind: "component";
@@ -1300,14 +1095,7 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     kind: z.ZodLiteral<"overlay">;
     primitiveId: z.ZodString;
     params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    /** Launch-grade depth (spec 2026-06-11): which z-plane this overlay renders on.
-     *  'behind-subject' = under the subject cut-out (the matte occludes it).
-     *  Extensible enum, NOT a boolean — later planes ('behind-background') are additive.
-     *  Default front. Depth fields (zPlane/anchor/parallax) mirror the TS shape in
-     *  `@cueframe/core/render/types#CompositionOverlay`. */
     zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
-    /** Durable anchor in SCENE space (source-normalized [0,1]); projected through the
-     *  clip's crop trajectory at render (world-lock). System-computed default; agent may set. */
     anchor: z.ZodOptional<z.ZodObject<{
         space: z.ZodLiteral<"scene">;
         x: z.ZodNumber;
@@ -1321,7 +1109,6 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         y: number;
         space: "scene";
     }>>;
-    /** Differential vs camera motion: 0 = locked to scene; small ± = depth parallax. */
     parallax: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     kind: "overlay";
@@ -1374,22 +1161,8 @@ export declare const ClipSource: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     zPlane?: "front" | "behind-subject" | undefined;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"card">;
-    /** Standard HTML/CSS, verbatim. A `<style>` block may be inlined. No <script>
-     *  (innerHTML never executes it) — decoration only. Required + non-empty. */
     html: z.ZodString;
-    /** Brand-token bindings: each value is a literal OR a whole-string `$brand:<path>`
-     *  ref. Resolved deep at render (resolveBrandRefsDeep — the SAME resolver the
-     *  graphics compiler + alpha bake use) into `--cf-<key>` CSS custom properties on
-     *  the wrapper box; the authored CSS references them as `var(--cf-<key>)`. Keeps
-     *  the payload standard CSS while staying brand-resolvable, with no inline-string
-     *  substitution. */
     tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    /** Depth plane. FRONT ONLY for now — behind-subject cards are not wired into
-     *  the matte pipeline (the depth predicates in depth.ts / variant-keys /
-     *  resolve-behind-placement exclude card), so admitting "behind-subject" here
-     *  would render the card unoccluded with no matte and no error. The wire
-     *  refuses it LOUDLY instead; widen to the OverlayClipSource enum when the
-     *  behind wiring lands (review finding 2026-07-10). */
     zPlane: z.ZodOptional<z.ZodLiteral<"front">>;
 }, "strip", z.ZodTypeAny, {
     kind: "card";
@@ -1442,10 +1215,6 @@ export declare const Transition: z.ZodObject<{
     duration: number;
 }>;
 export type Transition = z.infer<typeof Transition>;
-/** Phase 5 layer model: the single placement primitive — the output-space rect
- *  (fractions of the output frame, 0..1) a layer occupies. Mirrors the
- *  composition-floor `Rect` placement vocabulary already used for captions/overlays.
- *  Default (omitted) = full frame {x:0,y:0,w:1,h:1}. */
 export declare const Region: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
@@ -1463,14 +1232,8 @@ export declare const Region: z.ZodObject<{
     h: number;
 }>;
 export type Region = z.infer<typeof Region>;
-/** How a layer's source fills its `region`: `cover` (fill + crop, the renderer
- *  default) or `contain` (letterbox — routed through a designed band, not flat
- *  black bars). Omitted = `cover`. */
 export declare const ClipFit: z.ZodEnum<["cover", "contain"]>;
 export type ClipFit = z.infer<typeof ClipFit>;
-/** One entry of a clip's EFFECT channel — a registered effect primitive plus its
- *  params. Exported because the `setEffects` op reuses this exact wire shape (the
- *  op vocabulary never re-describes a validator shape with its own z.object). */
 export declare const PerClipEffect: z.ZodObject<{
     primitiveId: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -1482,32 +1245,6 @@ export declare const PerClipEffect: z.ZodObject<{
     params?: Record<string, unknown> | undefined;
 }>;
 export type PerClipEffect = z.infer<typeof PerClipEffect>;
-/**
- * KEYFRAMES — a value that changes over a clip's life.
- *
- * The composition had NO time-varying model. `TimelineClip` carried scalar
- * `opacity` / `scale` / `rotation` / `position`, and the only trace of an
- * intent to animate them was two error codes with no producer
- * (`invariants/errors.ts`: `varying_keyframe_time_out_of_range`,
- * `varying_keyframe_duplicate_time`). Two brain docs read
- * `registry.ts varyingParams` as the model; it is a list of param NAMES a
- * primitive accepts, not a value over time. So "we sell motion" was true of the
- * renderer and false of the document.
- *
- * TIME IS CLIP-RELATIVE, and that is the load-bearing decision. Absolute
- * timeline seconds would desync every keyframe on the clip the moment a ripple
- * moved it — silently, because nothing about the clip itself would look wrong.
- * Clip-relative time survives moves, ripples and lane changes untouched; only a
- * TRIM has to think about it.
- *
- * VALUES ARE SCALAR in v1. A vector channel like `position` decomposes into
- * `position.x` / `position.y` without needing a second shape, so nothing is
- * lost and the interpolator stays one function.
- *
- * `cubicBezier` ships from day one even though the UI will only offer named
- * easings at first — so the curve editor is additive later rather than a
- * migration of everything authored before it.
- */
 export declare const KeyframeEasing: z.ZodUnion<[z.ZodEnum<["linear", "ease", "easeIn", "easeOut", "easeInOut"]>, z.ZodObject<{
     cubicBezier: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
 }, "strict", z.ZodTypeAny, {
@@ -1517,10 +1254,8 @@ export declare const KeyframeEasing: z.ZodUnion<[z.ZodEnum<["linear", "ease", "e
 }>]>;
 export type KeyframeEasing = z.infer<typeof KeyframeEasing>;
 export declare const Keyframe: z.ZodObject<{
-    /** Seconds from the clip's own start — NOT timeline time. See above. */
     time: z.ZodNumber;
     value: z.ZodNumber;
-    /** How to reach this keyframe from the previous one. Default `linear`. */
     easing: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["linear", "ease", "easeIn", "easeOut", "easeInOut"]>, z.ZodObject<{
         cubicBezier: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
     }, "strict", z.ZodTypeAny, {
@@ -1542,12 +1277,9 @@ export declare const Keyframe: z.ZodObject<{
     } | undefined;
 }>;
 export type Keyframe = z.infer<typeof Keyframe>;
-/** A channel needs two points to vary; one point is just a scalar with extra steps. */
 export declare const KeyframeChannel: z.ZodArray<z.ZodObject<{
-    /** Seconds from the clip's own start — NOT timeline time. See above. */
     time: z.ZodNumber;
     value: z.ZodNumber;
-    /** How to reach this keyframe from the previous one. Default `linear`. */
     easing: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["linear", "ease", "easeIn", "easeOut", "easeInOut"]>, z.ZodObject<{
         cubicBezier: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
     }, "strict", z.ZodTypeAny, {
@@ -1569,7 +1301,6 @@ export declare const KeyframeChannel: z.ZodArray<z.ZodObject<{
     } | undefined;
 }>, "many">;
 export type KeyframeChannel = z.infer<typeof KeyframeChannel>;
-/** Param paths that may be animated. Closed, so a typo fails loud. */
 export declare const ANIMATABLE_PARAMS: readonly ["opacity", "scale", "rotation", "position.x", "position.y", "volume"];
 export type AnimatableParam = (typeof ANIMATABLE_PARAMS)[number];
 export declare const TimelineClip: z.ZodObject<{
@@ -1606,57 +1337,12 @@ export declare const TimelineClip: z.ZodObject<{
         muted: z.ZodOptional<z.ZodBoolean>;
         playbackRate: z.ZodOptional<z.ZodNumber>;
         sync: z.ZodOptional<z.ZodEnum<["video", "independent"]>>;
-        /**
-         * Ken-Burns motion preset for `kind: "image"` tracks. The renderer's
-         * `<StillFrame>` reads this to drive a per-frame transform over the
-         * clip's duration. Default is `"in"` (gentle zoom-in) — chosen because
-         * still photos with zero motion read as "broken video" against
-         * surrounding b-roll. Set to `"none"` to opt out. Ignored on non-image
-         * tracks.
-         */
         kenBurns: z.ZodOptional<z.ZodEnum<["in", "out", "pan-l", "pan-r", "none"]>>;
-        /**
-         * Audio mix override for `kind: "audio"` tracks (SFX / music beds).
-         * `volumeDb` is decibels relative to source (negative = quieter); the
-         * renderer converts to linear gain via `10^(dB/20)`. Default at render
-         * time is -12 dB for stock SFX beds — quiet enough to sit under VO
-         * without ducking. `fadeInMs` / `fadeOutMs` interpolate linearly from
-         * silence to `volumeDb` (and back) at the clip's edges; default 200 ms
-         * each. All three are ignored on non-audio tracks.
-         */
         volumeDb: z.ZodOptional<z.ZodNumber>;
         fadeInMs: z.ZodOptional<z.ZodNumber>;
         fadeOutMs: z.ZodOptional<z.ZodNumber>;
-        /**
-         * Loop the underlying media until the clip's `duration` runs out, instead
-         * of letting the media play to its natural end and freezing on the last
-         * frame (video / gif) or going silent (audio). Used by gif enrichment
-         * clips that may be shorter than the moment they cover, and by sfx
-         * ambient beds. Ignored on `kind: "image"` tracks (stills don't have a
-         * source timeline to loop).
-         */
         loop: z.ZodOptional<z.ZodBoolean>;
-        /**
-         * What this audio-track clip IS, for mix policy + eval. Absent on video/image
-         * clips (the track-family enum on TimelineClip stays untouched — nothing
-         * downstream switches on family; `audioRole` lives on the SOURCE like
-         * `volumeDb`). SFX vs music vs VO is otherwise indistinguishable to the
-         * duck/master/eval logic. (`sfxCompile` stamps `sfx`/`music`; VO is future.)
-         * `ambience` is a bed that HOLDS under VO — it loops, sits at the BOTTOM of the
-         * mix, and is NEVER duck-stamped (founder ruling: ambience does not duck under
-         * speech; no beat map, no anchor semantics).
-         */
         audioRole: z.ZodOptional<z.ZodEnum<["sfx", "music", "vo", "ambience"]>>;
-        /**
-         * Speech-aware ducking (music / vo roles only). Deterministic: the render
-         * derives the duck envelope from the composition's OWN timeline-aligned
-         * caption words — no audio analysis, no ffmpeg sidechain. `duckDb` is the
-         * gain applied during speech (e.g. -12); `attackMs`/`releaseMs` ramp the
-         * envelope in/out (defaults 150 / 400). `windows` are explicit speech spans
-         * (timeline ms) — REQUIRED when the composition has no captions; when
-         * captions exist the projection derives windows from `captions.segments`
-         * words and `windows` MUST be absent (one SSOT, no drift).
-         */
         duck: z.ZodOptional<z.ZodObject<{
             duckDb: z.ZodNumber;
             attackMs: z.ZodNumber;
@@ -1688,14 +1374,6 @@ export declare const TimelineClip: z.ZodObject<{
                 endMs: number;
             }[] | undefined;
         }>>;
-        /**
-         * SFX event anchor — provenance + re-resolution handle for a hit bound to a
-         * graphic/transition entrance. NOT consumed at render (`startTime` stays the
-         * single placement truth; see the sfxCompile drift note). `clipId` is the
-         * overlay/video clip whose entrance this hits; `offsetMs` is vs that clip's
-         * `startTime` (usually 0). Exists so re-resolution + eval can re-derive the
-         * binding after an amendment. Absent on non-SFX audio clips.
-         */
         anchor: z.ZodOptional<z.ZodObject<{
             clipId: z.ZodString;
             offsetMs: z.ZodNumber;
@@ -1706,20 +1384,6 @@ export declare const TimelineClip: z.ZodObject<{
             clipId: string;
             offsetMs: number;
         }>>;
-        /**
-         * The camera channel — the canonical `reframe` model. `segments` tile the
-         * clip's duration and animate a source→output viewport: each carries WHO
-         * the camera tracks (`focus`), HOW TIGHT (`zoom`, <1 punches in), an optional
-         * fine framing nudge (`bias`), and optional zoom-ramp easing (`ease`). The
-         * derive math (deriveTrajectory) honors these directly — no closed-enum
-         * framing names, no hardcoded scale constants.
-         *
-         * When omitted, the renderer plays the raw source (no crop). When present,
-         * the variant cache keys by `hashReframe(reframe.segments)`.
-         *
-         * Replaces the deleted subject-centric `cropIntents` (2026-06-14 cutover —
-         * one viewport primitive for all clip kinds).
-         */
         reframe: z.ZodOptional<z.ZodObject<{
             segments: z.ZodArray<z.ZodEffects<z.ZodObject<{
                 startSec: z.ZodNumber;
@@ -2007,7 +1671,7 @@ export declare const TimelineClip: 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;
@@ -2075,7 +1739,7 @@ export declare const TimelineClip: 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;
@@ -2103,11 +1767,6 @@ export declare const TimelineClip: z.ZodObject<{
         kind: z.ZodLiteral<"component">;
         componentId: z.ZodString;
         props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        /** Depth plane, mirroring OverlayClipSource — without this field the cloud
-         *  motion-preset sink's zPlane carry was silently STRIPPED at parse (Opus
-         *  review F1), planting a lane asymmetry that would fire the day cards are
-         *  allowed behind-subject. NOTE: the save-time component→custom desugar must
-         *  also carry it when behind-cards land. */
         zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
     }, "strip", z.ZodTypeAny, {
         kind: "component";
@@ -2123,14 +1782,7 @@ export declare const TimelineClip: z.ZodObject<{
         kind: z.ZodLiteral<"overlay">;
         primitiveId: z.ZodString;
         params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        /** Launch-grade depth (spec 2026-06-11): which z-plane this overlay renders on.
-         *  'behind-subject' = under the subject cut-out (the matte occludes it).
-         *  Extensible enum, NOT a boolean — later planes ('behind-background') are additive.
-         *  Default front. Depth fields (zPlane/anchor/parallax) mirror the TS shape in
-         *  `@cueframe/core/render/types#CompositionOverlay`. */
         zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
-        /** Durable anchor in SCENE space (source-normalized [0,1]); projected through the
-         *  clip's crop trajectory at render (world-lock). System-computed default; agent may set. */
         anchor: z.ZodOptional<z.ZodObject<{
             space: z.ZodLiteral<"scene">;
             x: z.ZodNumber;
@@ -2144,7 +1796,6 @@ export declare const TimelineClip: z.ZodObject<{
             y: number;
             space: "scene";
         }>>;
-        /** Differential vs camera motion: 0 = locked to scene; small ± = depth parallax. */
         parallax: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         kind: "overlay";
@@ -2197,22 +1848,8 @@ export declare const TimelineClip: z.ZodObject<{
         zPlane?: "front" | "behind-subject" | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"card">;
-        /** Standard HTML/CSS, verbatim. A `<style>` block may be inlined. No <script>
-         *  (innerHTML never executes it) — decoration only. Required + non-empty. */
         html: z.ZodString;
-        /** Brand-token bindings: each value is a literal OR a whole-string `$brand:<path>`
-         *  ref. Resolved deep at render (resolveBrandRefsDeep — the SAME resolver the
-         *  graphics compiler + alpha bake use) into `--cf-<key>` CSS custom properties on
-         *  the wrapper box; the authored CSS references them as `var(--cf-<key>)`. Keeps
-         *  the payload standard CSS while staying brand-resolvable, with no inline-string
-         *  substitution. */
         tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-        /** Depth plane. FRONT ONLY for now — behind-subject cards are not wired into
-         *  the matte pipeline (the depth predicates in depth.ts / variant-keys /
-         *  resolve-behind-placement exclude card), so admitting "behind-subject" here
-         *  would render the card unoccluded with no matte and no error. The wire
-         *  refuses it LOUDLY instead; widen to the OverlayClipSource enum when the
-         *  behind wiring lands (review finding 2026-07-10). */
         zPlane: z.ZodOptional<z.ZodLiteral<"front">>;
     }, "strip", z.ZodTypeAny, {
         kind: "card";
@@ -2252,13 +1889,6 @@ export declare const TimelineClip: z.ZodObject<{
             end: number;
         } | undefined;
     }>]>;
-    /** The clip's track FAMILY — mirrors `Track.kind`, distinct from `source.kind`
-     *  (content). OPTIONAL: most clips' family derives unambiguously from the
-     *  source (overlay/effect/component/alpha-layer → overlay/effect), so existing
-     *  authored clips need no migration. It is load-bearing ONLY for `media`
-     *  sources, which are ambiguous (a media clip can be video | audio | image) —
-     *  there `kind` is the clip's self-describing family and `clip.add` requires it
-     *  (or a target track) to route. See `resolveClipKind` (@cueframe/composition-ops). */
     kind: z.ZodOptional<z.ZodEnum<["video", "audio", "image", "overlay", "effect"]>>;
     opacity: z.ZodOptional<z.ZodNumber>;
     scale: z.ZodOptional<z.ZodNumber>;
@@ -2273,8 +1903,6 @@ export declare const TimelineClip: z.ZodObject<{
         x: number;
         y: number;
     }>>;
-    /** Phase 5: output-space placement rect (default = full frame). The single
-     *  placement primitive; position/scale/rotation are the animation channel. */
     region: z.ZodOptional<z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
@@ -2291,7 +1919,6 @@ export declare const TimelineClip: z.ZodObject<{
         w: number;
         h: number;
     }>>;
-    /** Phase 5: how the source fills `region` (default `cover`). */
     fit: z.ZodOptional<z.ZodEnum<["cover", "contain"]>>;
     effects: z.ZodOptional<z.ZodArray<z.ZodObject<{
         primitiveId: z.ZodString;
@@ -2313,31 +1940,10 @@ export declare const TimelineClip: z.ZodObject<{
         type: string;
         duration: number;
     }>>;
-    /**
-     * A/V LINK GROUP. Clips sharing an id move, trim and delete together.
-     *
-     * Not polish — a correctness property. Without it, selecting a video clip
-     * does not select its audio, so every ripple, move and trim silently desyncs
-     * sound from picture and the user finds out at playback. Every editor this
-     * repo has been measured against carries the same field; ours had none
-     * (`grep linkGroup` returned nothing across `apps/studio/src` and
-     * `packages/composition/src` on 2026-08-23).
-     *
-     * Membership is the ONLY thing stored. What a link implies — expand the
-     * selection, carry the group through a move — is behaviour, and lives in
-     * `../timeline/link.ts` so both lanes get it from one implementation.
-     */
     linkGroupId: z.ZodOptional<z.ZodString>;
-    /**
-     * Time-varying parameter channels, keyed by param path. A param present here
-     * OVERRIDES its scalar sibling for the clip's whole duration — the scalar
-     * stays as the value a still frame or a non-animating renderer reads.
-     */
     animate: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
-        /** Seconds from the clip's own start — NOT timeline time. See above. */
         time: z.ZodNumber;
         value: z.ZodNumber;
-        /** How to reach this keyframe from the previous one. Default `linear`. */
         easing: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["linear", "ease", "easeIn", "easeOut", "easeInOut"]>, z.ZodObject<{
             cubicBezier: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
         }, "strict", z.ZodTypeAny, {
@@ -2418,7 +2024,7 @@ export declare const TimelineClip: 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;
@@ -2559,7 +2165,7 @@ export declare const TimelineClip: 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;
@@ -2716,7 +2322,7 @@ export declare const TrackContent: z.ZodEffects<z.ZodUnknown, {
                 } | 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;
@@ -2820,14 +2426,6 @@ export declare const Track: z.ZodObject<{
     kind: z.ZodEnum<["video", "audio", "image", "overlay", "effect"]>;
     name: z.ZodOptional<z.ZodString>;
     enabled: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * TRACK-LEVEL GAIN, linear, multiplied into every clip on the track.
-     *
-     * The mixer had per-clip volume and nothing above it, so "turn the music
-     * down" meant editing every music clip and re-editing each new one. Absent =
-     * unity; the projection only multiplies when it is present, so an untouched
-     * composition renders byte-identically to before this field existed.
-     */
     volume: z.ZodOptional<z.ZodNumber>;
     contents: z.ZodArray<z.ZodEffects<z.ZodUnknown, {
         id: string;
@@ -2877,7 +2475,7 @@ export declare const Track: 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;
@@ -3026,7 +2624,7 @@ export declare const Track: 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;
@@ -3124,16 +2722,16 @@ export declare const Track: 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;
 }>;
 export type Track = z.infer<typeof Track>;
 export declare const Marker: z.ZodObject<{
@@ -3159,13 +2757,6 @@ export declare const Marker: z.ZodObject<{
     metadata?: Record<string, unknown> | undefined;
 }>;
 export type Marker = z.infer<typeof Marker>;
-/**
- * Word-level caption timing. Mirrors the TS shape in
- * `@cueframe/core/render/types#CaptionWord` — kept here as a zod schema
- * so it validates at the wire boundary. Times are millisecond-based to
- * match `@remotion/captions`. `emphasis: true` opts a word into the
- * Captions primitive's emphasis styling (separate font/scale/color).
- */
 export declare const CaptionWord: z.ZodObject<{
     text: z.ZodString;
     startMs: z.ZodNumber;
@@ -3186,11 +2777,6 @@ export declare const CaptionWord: z.ZodObject<{
     annotate?: "circle" | "underline" | undefined;
 }>;
 export type CaptionWord = z.infer<typeof CaptionWord>;
-/**
- * Caption styling — mirrors `@cueframe/core/render/types#CaptionStyle`.
- * All fields optional on the wire so the renderer falls back to the
- * primitive's defaults / brand kit's `captionStyle` per-field.
- */
 export declare const CaptionStyle: z.ZodObject<{
     fontFamily: z.ZodOptional<z.ZodString>;
     fontSize: z.ZodOptional<z.ZodNumber>;
@@ -3289,23 +2875,6 @@ export declare const CaptionStyle: z.ZodObject<{
     maxWidthPercent?: number | undefined;
 }>;
 export type CaptionStyle = z.infer<typeof CaptionStyle>;
-/**
- * Top-level captions layer on a Composition. Spans the whole timeline
- * with consistent style — sibling of `tracks` / `markers`, not an
- * overlay primitive.
- *
- * `words` are timeline-aligned milliseconds (NOT source-relative). The
- * agent / API path slices the source's transcript to the clip window
- * and re-bases timestamps to t=0 on insert. `style` is optional; the
- * renderer falls back to brand kit's `captionStyle` then primitive
- * defaults.
- */
-/** One caption SEGMENT (a phrase / sentence) — the content unit the agent
- *  authors AND a hard caption-page boundary at render: the renderer paginates
- *  within a segment and never pools words across two, so sentence-bounded
- *  segments (see `splitIntoSentences`) cut captions at sentence ends. Captions
- *  are FRONT-ONLY; depth ("behind subject") lives on overlays
- *  (`OverlayClipSource.zPlane`), never on captions. */
 export declare const CaptionSegment: z.ZodObject<{
     words: z.ZodArray<z.ZodObject<{
         text: z.ZodString;
@@ -3344,31 +2913,8 @@ export declare const CaptionSegment: z.ZodObject<{
     }[];
 }>;
 export type CaptionSegment = z.infer<typeof CaptionSegment>;
-/**
- * PROVENANCE IS REQUIRED. `segments` is a materialized projection, and until
- * 2026-08-14 it carried no record of where it came from — which is the whole
- * bug. `useCaptionMaterialization` said so itself: "once segments exist there is
- * no reliable way to distinguish 'materialized from this doc' from
- * 'API-authored', and guessing risks destroying" the authored ones. So nothing
- * dared re-derive, and captions silently outlived the edits that invalidated
- * them — a real project carried words timed 1940–4400ms inside a 2.4s
- * composition, with the render reading those stale times.
- *
- * `derived` — a projection of a clip's transcript. Anything that changes that
- * clip (trim, cut, an excluded range, playback rate) MUST re-derive it, and may,
- * because `from` says exactly what to recompute from.
- *
- * `authored` — a human or agent wrote these words. Never rewritten
- * automatically; the segmentation is a deliberate choice.
- *
- * Segments stay MATERIALIZED rather than resolved at read time on purpose:
- * `compositionToRenderInput(composition, srcUrls)` takes no transcripts, and a
- * renderer that had to fetch them would stop being self-contained and
- * deterministic — which the render cache key depends on.
- */
 export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
     source: z.ZodLiteral<"derived">;
-    /** The clip these words are a projection OF. Re-derive from this. */
     from: z.ZodObject<{
         clipId: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -3510,6 +3056,7 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
         annotationColor?: string | undefined;
         maxWidthPercent?: number | undefined;
     }>>;
+    zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
 }, "strip", z.ZodTypeAny, {
     segments: {
         words: {
@@ -3524,6 +3071,7 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
     from: {
         clipId: string;
     };
+    zPlane?: "front" | "behind-subject" | undefined;
     style?: {
         position?: "top" | "center" | "bottom" | undefined;
         fontFamily?: string | undefined;
@@ -3571,6 +3119,7 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
     from: {
         clipId: string;
     };
+    zPlane?: "front" | "behind-subject" | undefined;
     style?: {
         position?: "top" | "center" | "bottom" | undefined;
         fontFamily?: string | undefined;
@@ -3740,6 +3289,7 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
         annotationColor?: string | undefined;
         maxWidthPercent?: number | undefined;
     }>>;
+    zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
 }, "strip", z.ZodTypeAny, {
     segments: {
         words: {
@@ -3751,6 +3301,7 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
         }[];
     }[];
     source: "authored";
+    zPlane?: "front" | "behind-subject" | undefined;
     style?: {
         position?: "top" | "center" | "bottom" | undefined;
         fontFamily?: string | undefined;
@@ -3795,6 +3346,7 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
         }[];
     }[];
     source: "authored";
+    zPlane?: "front" | "behind-subject" | undefined;
     style?: {
         position?: "top" | "center" | "bottom" | undefined;
         fontFamily?: string | undefined;
@@ -3829,9 +3381,10 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
         maxWidthPercent?: number | undefined;
     } | undefined;
 }>]>;
+export declare function captionsAreBehindSubject(captions: {
+    zPlane?: unknown;
+} | null | undefined): boolean;
 export type CompositionCaptions = z.infer<typeof CompositionCaptions>;
-/** All caption words across the layer's segments, in order — the flattened view
- *  consumers that don't care about behind use. */
 export declare function captionWords(c: CompositionCaptions): CaptionWord[];
 export declare const Composition: z.ZodObject<{
     v: z.ZodLiteral<1>;
@@ -3856,14 +3409,6 @@ export declare const Composition: z.ZodObject<{
         kind: z.ZodEnum<["video", "audio", "image", "overlay", "effect"]>;
         name: z.ZodOptional<z.ZodString>;
         enabled: z.ZodOptional<z.ZodBoolean>;
-        /**
-         * TRACK-LEVEL GAIN, linear, multiplied into every clip on the track.
-         *
-         * The mixer had per-clip volume and nothing above it, so "turn the music
-         * down" meant editing every music clip and re-editing each new one. Absent =
-         * unity; the projection only multiplies when it is present, so an untouched
-         * composition renders byte-identically to before this field existed.
-         */
         volume: z.ZodOptional<z.ZodNumber>;
         contents: z.ZodArray<z.ZodEffects<z.ZodUnknown, {
             id: string;
@@ -3913,7 +3458,7 @@ export declare const Composition: 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;
@@ -4062,7 +3607,7 @@ export declare const Composition: 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;
@@ -4160,16 +3705,16 @@ export declare const Composition: 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;
@@ -4195,7 +3740,6 @@ export declare const Composition: z.ZodObject<{
     }>, "many">>;
     captions: z.ZodOptional<z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
         source: z.ZodLiteral<"derived">;
-        /** The clip these words are a projection OF. Re-derive from this. */
         from: z.ZodObject<{
             clipId: z.ZodString;
         }, "strip", z.ZodTypeAny, {
@@ -4337,6 +3881,7 @@ export declare const Composition: z.ZodObject<{
             annotationColor?: string | undefined;
             maxWidthPercent?: number | undefined;
         }>>;
+        zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
     }, "strip", z.ZodTypeAny, {
         segments: {
             words: {
@@ -4351,6 +3896,7 @@ export declare const Composition: z.ZodObject<{
         from: {
             clipId: string;
         };
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4398,6 +3944,7 @@ export declare const Composition: z.ZodObject<{
         from: {
             clipId: string;
         };
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4567,6 +4114,7 @@ export declare const Composition: z.ZodObject<{
             annotationColor?: string | undefined;
             maxWidthPercent?: number | undefined;
         }>>;
+        zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
     }, "strip", z.ZodTypeAny, {
         segments: {
             words: {
@@ -4578,6 +4126,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4622,6 +4171,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4760,7 +4310,7 @@ export declare const Composition: 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;
@@ -4858,9 +4408,9 @@ export declare const Composition: z.ZodObject<{
             duration: number;
             startTime: number;
         })[];
+        enabled?: boolean | undefined;
         volume?: number | undefined;
         name?: string | undefined;
-        enabled?: boolean | undefined;
     }[];
     markers?: {
         id: string;
@@ -4884,6 +4434,7 @@ export declare const Composition: z.ZodObject<{
         from: {
             clipId: string;
         };
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4928,6 +4479,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4993,9 +4545,9 @@ export declare const Composition: 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;
@@ -5019,6 +4571,7 @@ export declare const Composition: z.ZodObject<{
         from: {
             clipId: string;
         };
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -5063,6 +4616,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -5118,31 +4672,6 @@ export declare const Composition: z.ZodObject<{
     } | undefined;
 }>;
 export type Composition = z.infer<typeof Composition>;
-/**
- * Composition with render-time URL resolution attached.
- *
- * `mediaSources` maps `TimelineClip.source.mediaId` → presigned R2 URL.
- * It's resolved on the way to render (from the corresponding `mediaItems`
- * row's R2 key) and travels with the composition through the render
- * pipeline. The canonical persisted composition (`projects.composition`
- * row) NEVER carries `mediaSources` — presigned URLs expire (~24h R2
- * TTL); only the stable `mediaId` references survive at rest, and the
- * URL map is freshly resolved each render.
- *
- * This type exists to replace the spread of
- * `(composition as { mediaSources?: Record<string, string> })` casts
- * across renderers, compose workflows, and projection code. The shape
- * the cast described was always the render-time view of a Composition;
- * naming it makes the in-transit/at-rest distinction explicit at the
- * type system level.
- *
- * Optional because some in-transit paths (the build step that emits a
- * composition before mediaSources is populated) carry the structural
- * shape without yet having resolved every reference. Call sites that
- * genuinely require resolution defend with `?? {}` today; a stricter
- * `RenderableCompositionResolved` variant can be added when a consumer
- * needs the compile-time guarantee.
- */
 export type RenderableComposition = Composition & {
     mediaSources?: Record<string, string>;
 };
@@ -5179,14 +4708,6 @@ export declare const CompositionVersion: z.ZodObject<{
             kind: z.ZodEnum<["video", "audio", "image", "overlay", "effect"]>;
             name: z.ZodOptional<z.ZodString>;
             enabled: z.ZodOptional<z.ZodBoolean>;
-            /**
-             * TRACK-LEVEL GAIN, linear, multiplied into every clip on the track.
-             *
-             * The mixer had per-clip volume and nothing above it, so "turn the music
-             * down" meant editing every music clip and re-editing each new one. Absent =
-             * unity; the projection only multiplies when it is present, so an untouched
-             * composition renders byte-identically to before this field existed.
-             */
             volume: z.ZodOptional<z.ZodNumber>;
             contents: z.ZodArray<z.ZodEffects<z.ZodUnknown, {
                 id: string;
@@ -5236,7 +4757,7 @@ export declare const CompositionVersion: 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;
@@ -5385,7 +4906,7 @@ export declare const CompositionVersion: 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;
@@ -5483,16 +5004,16 @@ export declare const CompositionVersion: 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;
@@ -5518,7 +5039,6 @@ export declare const CompositionVersion: z.ZodObject<{
         }>, "many">>;
         captions: z.ZodOptional<z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
             source: z.ZodLiteral<"derived">;
-            /** The clip these words are a projection OF. Re-derive from this. */
             from: z.ZodObject<{
                 clipId: z.ZodString;
             }, "strip", z.ZodTypeAny, {
@@ -5660,6 +5180,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 annotationColor?: string | undefined;
                 maxWidthPercent?: number | undefined;
             }>>;
+            zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
         }, "strip", z.ZodTypeAny, {
             segments: {
                 words: {
@@ -5674,6 +5195,7 @@ export declare const CompositionVersion: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -5721,6 +5243,7 @@ export declare const CompositionVersion: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -5890,6 +5413,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 annotationColor?: string | undefined;
                 maxWidthPercent?: number | undefined;
             }>>;
+            zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
         }, "strip", z.ZodTypeAny, {
             segments: {
                 words: {
@@ -5901,6 +5425,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -5945,6 +5470,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6083,7 +5609,7 @@ export declare const CompositionVersion: 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;
@@ -6181,9 +5707,9 @@ export declare const CompositionVersion: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -6207,6 +5733,7 @@ export declare const CompositionVersion: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6251,6 +5778,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6316,9 +5844,9 @@ export declare const CompositionVersion: 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;
@@ -6342,6 +5870,7 @@ export declare const CompositionVersion: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6386,6 +5915,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6501,7 +6031,7 @@ export declare const CompositionVersion: 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;
@@ -6599,9 +6129,9 @@ export declare const CompositionVersion: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -6625,6 +6155,7 @@ export declare const CompositionVersion: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6669,6 +6200,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6745,9 +6277,9 @@ export declare const CompositionVersion: 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;
@@ -6771,6 +6303,7 @@ export declare const CompositionVersion: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6815,6 +6348,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;