@cueframe/kernel 0.1.0 → 0.1.1

package/dist/_members/composition/projection/behind-readiness.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CAN THIS OVERLAY ACTUALLY GO BEHIND THE SUBJECT — answered in the editor,
+ * before a render is paid for.
+ *
+ * The render already decides this, in the director's `resolveBehindPlacement`:
+ * a behind-subject overlay whose clip has no matte, no geometry sidecar, or too
+ * little subject presence is DEGRADED — `zPlane` flipped back to `front` and the
+ * authored `anchor` deleted — and the reason is recorded in a `degraded[]` array
+ * that both of its callers discard. So the user flips the toggle, pays for a
+ * render, and finds out from the output.
+ *
+ * This module answers the same question from data the editor already has on the
+ * media row, so the toggle can tell the truth at the moment it is flipped.
+ *
+ * ── IT IS ONLY WORTH ANYTHING IF IT AGREES WITH THE SERVER ──────────────────
+ * Every rule below mirrors a specific server rule, named at its call site. Two
+ * helpers are currently duplicated from the private `@cueframe/shared/
+ * variant-keys` (`hashMatteIntent`, `clipOverlapsBehindWindow`); they live here
+ * because this package is the shared one, and the private copies become
+ * re-exports of these when the fact-record work lands. Until then the agreement
+ * is held by `__tests__/behind-readiness.test.ts`, whose key fixture is a hash
+ * taken from PRODUCTION rather than invented.
+ *
+ * ── WHAT IT CANNOT ANSWER ───────────────────────────────────────────────────
+ * The server has a FOURTH degrade path — the occlusion budget — which needs the
+ * `.geometry.json` sidecar from R2, and the client has no presigned URL for it.
+ * So `subject-present` means "the preconditions hold", NOT "this is guaranteed
+ * to render behind", and UI copy must not promise more.
+ */
+/** A matte intent: the clip's SOURCE window plus what is being cut out.
+ *  Mirrors `MatteIntentLike` in the private variant-keys. */
+export interface MatteIntentLike {
+    startSec: number;
+    endSec: number;
+    subjectClass: "person" | "product";
+}
+/** The fields this module reads off a `mediaItems.mattes[hash]` entry — the
+ *  same two `resolveBehindPlacement` reads out of its `matteGeometry` map. */
+export interface MatteEntryLike {
+    geometryR2Key?: string;
+    presenceFraction?: number;
+}
+/** The clip an overlay will be placed against, and the source window whose
+ *  matte answers for it. */
+export interface BehindTarget {
+    mediaId: string;
+    window: {
+        startSec: number;
+        endSec: number;
+    };
+}
+/**
+ * Why a behind-subject overlay will or will not survive the render. The three
+ * failing states correspond 1:1 to the server's degrade reasons: `no-clip` and
+ * `no-subject` both degrade as `"no-subject"` there, `no-matte` as
+ * `"no-geometry"`.
+ */
+export type BehindReadiness = {
+    state: "no-clip";
+} | {
+    state: "no-matte";
+    target: BehindTarget;
+} | {
+    state: "no-subject";
+    target: BehindTarget;
+    presenceFraction: number;
+} | {
+    state: "subject-present";
+    target: BehindTarget;
+};
+/**
+ * Content-address a matte intent, byte-identically to the server's
+ * `hashMatteIntent`. Milliseconds-rounded so float jitter cannot miss a cached
+ * matte; 12 hex chars. Async because `crypto.subtle` is — available in the
+ * webview and in Node alike.
+ *
+ * The bake VERSION is deliberately not hashed (it segments the R2 key instead),
+ * so this key is stable across model bumps.
+ */
+export declare function matteIntentKey(intent: MatteIntentLike): Promise<string>;
+/**
+ * The clip a behind-subject overlay anchors against: **the first media clip on
+ * a VIDEO track, in track→content order, whose timeline range overlaps the
+ * overlay**. This is `resolveBehindPlacement`'s rule, and it is deliberately
+ * NOT `computeMatteWindowsByMediaId`'s — that one also scans audio and image
+ * tracks, because it answers a different question (which mattes to bake).
+ * Mirroring the wrong one of the two would put the editor and the render into
+ * exactly the disagreement this module exists to remove.
+ *
+ * The returned `window` is the clip's SOURCE trim, defaulted the way
+ * `renders.ts` defaults it: `trim.start ?? 0`, `trim.end ?? start + duration`.
+ * That is the window the matte is keyed by.
+ *
+ * Returns null when the overlay is unknown, or floats over no video clip —
+ * which the server degrades as `"no-subject"`.
+ */
+export declare function primaryClipForOverlay(composition: unknown, overlayId: string): BehindTarget | null;
+export interface BehindReadinessInput {
+    /** The wire-shape composition currently open in the editor. */
+    composition: unknown;
+    /** The overlay being inspected. It need NOT already be behind-subject — the
+     *  editor asks this to decide what to show BEFORE the toggle is flipped. */
+    overlayId: string;
+    /** `mediaItems.mattes`, per media id, exactly as it arrives from Convex. */
+    mattesByMediaId: Record<string, Record<string, MatteEntryLike> | undefined>;
+}
+/**
+ * Will this overlay actually render behind the subject? Mirrors the first three
+ * of `resolveBehindPlacement`'s four gates, in the same order:
+ *
+ *   1. no primary clip                  → server: degrade("no-subject")
+ *   2. no matte / no geometry sidecar   → server: degrade("no-geometry")
+ *   3. presence below the floor         → server: degrade("no-subject")
+ *
+ * The fourth (occlusion budget) is not knowable client-side — see the header.
+ */
+export declare function behindReadinessForOverlay(input: BehindReadinessInput): Promise<BehindReadiness>;
+/**
+ * The same verdict from an ALREADY-RESOLVED target — the half that actually
+ * costs something (a SHA-256) split from the half that is a pure walk.
+ *
+ * The editor calls this one. `primaryClipForOverlay` is sync, so a component
+ * can memoize the target on the composition and then depend only on the
+ * window's two numbers plus the media's matte record — instead of re-hashing on
+ * every keystroke that produces a new composition reference.
+ */
+export declare function behindReadinessForTarget(target: BehindTarget | null, mattes: Record<string, MatteEntryLike> | undefined): Promise<BehindReadiness>;

package/dist/_members/composition/projection/index.d.ts

@@ -3,5 +3,7 @@ export * from "./cardTokens.js";
 export * from "./composition-floor.js";
 export * from "./safe-zones.js";
 export * from "./behind-placement.js";
+export * from "./behind-readiness.js";
+export * from "./reframe-readiness.js";
 export * from "./occlusion-budget.js";
 export * from "./cropProjection.js";

package/dist/_members/composition/projection/reframe-readiness.d.ts

@@ -0,0 +1,156 @@
+/**
+ * WHICH CLIPS WANT A CROP, AND DO WE HAVE WHAT IT TAKES — answered in the
+ * editor, from data the media row already carries.
+ *
+ * The sibling of `behind-readiness.ts`, one rung down the fidelity ladder. That
+ * module asks whether a SILHOUETTE exists so an overlay can go behind a person;
+ * this one asks whether a BOX TRACK exists so a clip can follow one. Same shape,
+ * same discipline, ~40× apart in what the answer costs.
+ *
+ * ── WHY IT EXISTS ───────────────────────────────────────────────────────────
+ * A follow-the-speaker reframe is authored in the editor and only takes effect
+ * at render, because the crop trajectory is derived from a SUBJECT TRACK the
+ * editor never asked for. So the editor showed an uncropped source while the
+ * render produced a moving crop — the "editor shows something the render will
+ * not honour" defect, in its second location. Deriving the trajectory locally
+ * fixes that, and the derive needs to find the right track first. That lookup
+ * is what this module is.
+ *
+ * ── IT IS ONLY WORTH ANYTHING IF IT AGREES WITH THE SERVER ──────────────────
+ * `reframeTargets` mirrors `collectTrajectoryDeriveJobs` (private
+ * `renders.ts`) — the walk the SHIP render uses to decide which clips derive a
+ * trajectory and at which window. `sourceWindowKey` mirrors `hashSourceWindow`
+ * (private `@cueframe/shared/variant-keys`) byte for byte; the golden fixtures
+ * in `__tests__/reframe-readiness.test.ts` are hashes taken from PRODUCTION
+ * rather than invented, for the same reason `behind-readiness`'s are.
+ *
+ * ── WHAT IT DELIBERATELY DOES NOT CHECK ─────────────────────────────────────
+ * The DETECTOR VERSION. The server skips a track whose `detectorVersion` is not
+ * the current `DETECTOR_VERSION`, and the app cannot ask that without a third,
+ * unguarded mirror of a string whose TS↔Python sync is already CI-guarded on
+ * both existing copies. So the editor derives off whatever track sits at the
+ * window. A version bump means the render re-detects and the framing shifts
+ * slightly — same subject, same authored intent, and far closer to the truth
+ * than showing an uncropped source. A decision, not an omission.
+ */
+/** A source window. Subject tracks key on this — the window, plus the producer
+ *  when it is not the default face detector. Mirrors `SourceWindowLike`. */
+export interface SourceWindowLike {
+    startSec: number;
+    endSec: number;
+    /**
+     * Which producer detected the track: 'face' (YuNet/SCRFD, the default) or
+     * 'person' (YOLO11x + BoT-SORT). Folded into the hash ONLY when it is not
+     * 'face', so existing face-track keys never churn and a person track for the
+     * same window gets a DISTINCT key instead of overwriting the face one.
+     */
+    detector?: "face" | "person";
+}
+/** The fields this module reads off a `mediaItems.subjectTracks[hash]` entry. */
+export interface SubjectTrackEntryLike {
+    /** R2 object key — the STABLE identity every server-side reader matches on. */
+    trackR2Key?: string;
+    /**
+     * Presigned URL for that key, added ALONGSIDE it by `resolveR2Urls`. The row
+     * carries only a SUMMARY of the track (the face roster, a count); the
+     * per-frame boxes `deriveTrajectory` needs are the R2 object, so this is the
+     * one field that makes a client-side derive possible at all.
+     */
+    trackUrl?: string;
+    detectorVersion?: string;
+    window?: {
+        startSec: number;
+        endSec: number;
+    };
+    /** The inline face roster — who is in this window, for a per-person picker. */
+    faces?: Array<{
+        faceId: string;
+        bbox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        speakingShare?: number;
+    }>;
+}
+/**
+ * Content-address a source window, byte-identically to the server's
+ * `hashSourceWindow`. Milliseconds-rounded so float jitter cannot miss a cached
+ * track; 12 hex chars. Async because `crypto.subtle` is — available in the
+ * webview and in Node alike.
+ *
+ * The detector is omitted from the canonical form when it is 'face', which is
+ * NOT a shortcut: it is what keeps every already-cached face-track key valid.
+ */
+export declare function sourceWindowKey(window: SourceWindowLike): Promise<string>;
+/** A clip that has authored a reframe, and the window whose track answers for
+ *  it. `segments` travels along because `deriveTrajectory` takes it verbatim. */
+export interface ReframeTarget {
+    clipId: string;
+    mediaId: string;
+    window: {
+        startSec: number;
+        endSec: number;
+    };
+    /** The authored `source.reframe.segments`, untouched — the derive owns their
+     *  shape, and re-typing it here would be a fourth place to keep in sync. */
+    segments: unknown[];
+}
+/**
+ * Does this reframe track a real subject? A geometric one (a screen-recording
+ * point-zoom, an honest center crop) needs nothing detected and must NEVER be
+ * handed a detection bill — nor be told it is waiting for one.
+ */
+export declare function reframeNeedsDetection(segments: unknown[]): boolean;
+/**
+ * Every clip in the composition that has authored a reframe, with the source
+ * window its track is keyed by.
+ *
+ * MIRRORS `collectTrajectoryDeriveJobs`, including the two rules that are easy
+ * to get subtly wrong:
+ *   · only VIDEO and IMAGE tracks (an audio clip is `kind:"media"` too, and a
+ *     viewport crop is meaningless for sound)
+ *   · the window is the SOURCE TRIM, defaulted exactly as `renders.ts` defaults
+ *     it — `trim.start ?? 0`, `trim.end ?? start + clip.duration`
+ *
+ * Walked defensively with no zod, the `collectBehindWindows` convention, so it
+ * is safe in every bundle.
+ */
+export declare function reframeTargets(composition: unknown): ReframeTarget[];
+/**
+ * What the editor can say about one reframed clip.
+ *
+ * `geometric` is a distinct state and not a convenience: a point-zoom on a
+ * screen recording is fully derivable with no detection, so calling it
+ * "waiting for a track" would be a lie that also implies a charge.
+ */
+export type ReframeReadiness = 
+/** No detection needed — derives off a faceless stub, today, for free. */
+{
+    state: "geometric";
+}
+/** The track exists and can be fetched. */
+ | {
+    state: "track-ready";
+    entry: SubjectTrackEntryLike;
+    trackUrl: string;
+}
+/** A track is registered but carries no presigned URL, so the client cannot
+ *  derive. The RENDER still can — it reads the key directly. */
+ | {
+    state: "track-unfetchable";
+    entry: SubjectTrackEntryLike;
+}
+/** Nothing detected at this window yet. This is the state that buys one. */
+ | {
+    state: "no-track";
+};
+/**
+ * Can the editor derive this clip's crop trajectory right now?
+ *
+ * `subjectTracks` is `mediaItems.subjectTracks` for the target's media, exactly
+ * as it arrives from Convex — undefined for an item with no cloud perception,
+ * which is the honest shape for a local-only import.
+ */
+export declare function reframeReadinessForTarget(target: ReframeTarget, subjectTracks: Record<string, SubjectTrackEntryLike> | undefined): Promise<ReframeReadiness>;

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

@@ -3303,9 +3303,12 @@ export type CaptionStyle = z.infer<typeof CaptionStyle>;
 /** 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. */
+ *  segments (see `splitIntoSentences`) cut captions at sentence ends.
+ *
+ *  Depth is NOT per-segment: it is one choice for the whole caption layer
+ *  (`CompositionCaptions.zPlane`), because it decides whether the source needs
+ *  a matte at all. (This comment said captions were FRONT-ONLY until
+ *  2026-08-28 — see `CaptionDepth` for why that rule existed and why it went.) */
 export declare const CaptionSegment: z.ZodObject<{
     words: z.ZodArray<z.ZodObject<{
         text: z.ZodString;
@@ -3344,28 +3347,6 @@ 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. */
@@ -3510,6 +3491,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 +3506,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 +3554,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 +3724,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 +3736,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 +3781,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,6 +3816,12 @@ export declare const CompositionCaptions: z.ZodDiscriminatedUnion<"source", [z.Z
         maxWidthPercent?: number | undefined;
     } | undefined;
 }>]>;
+/** Do these captions render UNDER the speaker's silhouette? The one predicate
+ *  every gate asks, so the trigger, the renderer and the editor cannot drift
+ *  the way the overlay gates did before `isBehindSubjectDepthSource`. */
+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. */
@@ -4337,6 +4330,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 +4345,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 +4393,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 +4563,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 +4575,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 +4620,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -4884,6 +4883,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 +4928,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -5019,6 +5020,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 +5065,7 @@ export declare const Composition: z.ZodObject<{
             }[];
         }[];
         source: "authored";
+        zPlane?: "front" | "behind-subject" | undefined;
         style?: {
             position?: "top" | "center" | "bottom" | undefined;
             fontFamily?: string | undefined;
@@ -5660,6 +5663,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 +5678,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 +5726,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 +5896,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 +5908,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 +5953,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6207,6 +6216,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 +6261,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6342,6 +6353,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 +6398,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6625,6 +6638,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 +6683,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -6771,6 +6786,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 +6831,7 @@ export declare const CompositionVersion: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;