@cueframe/kernel 0.1.0 → 0.1.2

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

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

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

@@ -127,7 +127,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -276,7 +276,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -374,16 +374,16 @@ export declare const RenderSnapshot: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }, {
             id: string;
             kind: "overlay" | "video" | "effect" | "audio" | "image";
             contents: unknown[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }>, "many">;
         markers: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -550,6 +550,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 annotationColor?: string | undefined;
                 maxWidthPercent?: number | undefined;
             }>>;
+            zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
         }, "strip", z.ZodTypeAny, {
             segments: {
                 words: {
@@ -564,6 +565,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -611,6 +613,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -780,6 +783,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 annotationColor?: string | undefined;
                 maxWidthPercent?: number | undefined;
             }>>;
+            zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
         }, "strip", z.ZodTypeAny, {
             segments: {
                 words: {
@@ -791,6 +795,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -835,6 +840,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -973,7 +979,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -1071,9 +1077,9 @@ export declare const RenderSnapshot: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -1097,6 +1103,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -1141,6 +1148,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -1206,9 +1214,9 @@ export declare const RenderSnapshot: z.ZodObject<{
             id: string;
             kind: "overlay" | "video" | "effect" | "audio" | "image";
             contents: unknown[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -1232,6 +1240,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -1276,6 +1285,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -2652,7 +2662,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                             } | undefined;
                         }[];
                     } | undefined;
-                    kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                    kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                     excludedRanges?: {
                         start: number;
                         end: number;
@@ -2750,9 +2760,9 @@ export declare const RenderSnapshot: z.ZodObject<{
                 duration: number;
                 startTime: number;
             })[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -2776,6 +2786,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -2820,6 +2831,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -3121,9 +3133,9 @@ export declare const RenderSnapshot: z.ZodObject<{
             id: string;
             kind: "overlay" | "video" | "effect" | "audio" | "image";
             contents: unknown[];
+            enabled?: boolean | undefined;
             volume?: number | undefined;
             name?: string | undefined;
-            enabled?: boolean | undefined;
         }[];
         markers?: {
             id: string;
@@ -3147,6 +3159,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             from: {
                 clipId: string;
             };
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -3191,6 +3204,7 @@ export declare const RenderSnapshot: z.ZodObject<{
                 }[];
             }[];
             source: "authored";
+            zPlane?: "front" | "behind-subject" | undefined;
             style?: {
                 position?: "top" | "center" | "bottom" | undefined;
                 fontFamily?: string | undefined;
@@ -3761,7 +3775,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -3910,7 +3924,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -4008,16 +4022,16 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }, {
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }>, "many">;
             markers: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
@@ -4184,6 +4198,7 @@ export declare const RenderJob: z.ZodObject<{
                     annotationColor?: string | undefined;
                     maxWidthPercent?: number | undefined;
                 }>>;
+                zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
             }, "strip", z.ZodTypeAny, {
                 segments: {
                     words: {
@@ -4198,6 +4213,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4245,6 +4261,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4414,6 +4431,7 @@ export declare const RenderJob: z.ZodObject<{
                     annotationColor?: string | undefined;
                     maxWidthPercent?: number | undefined;
                 }>>;
+                zPlane: z.ZodOptional<z.ZodEnum<["front", "behind-subject"]>>;
             }, "strip", z.ZodTypeAny, {
                 segments: {
                     words: {
@@ -4425,6 +4443,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4469,6 +4488,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4607,7 +4627,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -4705,9 +4725,9 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -4731,6 +4751,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4775,6 +4796,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4840,9 +4862,9 @@ export declare const RenderJob: z.ZodObject<{
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -4866,6 +4888,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -4910,6 +4933,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -6286,7 +6310,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -6384,9 +6408,9 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -6410,6 +6434,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -6454,6 +6479,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -6755,9 +6781,9 @@ export declare const RenderJob: z.ZodObject<{
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -6781,6 +6807,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -6825,6 +6852,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -7316,7 +7344,7 @@ export declare const RenderJob: z.ZodObject<{
                                 } | undefined;
                             }[];
                         } | undefined;
-                        kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+                        kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
                         excludedRanges?: {
                             start: number;
                             end: number;
@@ -7414,9 +7442,9 @@ export declare const RenderJob: z.ZodObject<{
                     duration: number;
                     startTime: number;
                 })[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -7440,6 +7468,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -7484,6 +7513,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -7849,9 +7879,9 @@ export declare const RenderJob: z.ZodObject<{
                 id: string;
                 kind: "overlay" | "video" | "effect" | "audio" | "image";
                 contents: unknown[];
+                enabled?: boolean | undefined;
                 volume?: number | undefined;
                 name?: string | undefined;
-                enabled?: boolean | undefined;
             }[];
             markers?: {
                 id: string;
@@ -7875,6 +7905,7 @@ export declare const RenderJob: z.ZodObject<{
                 from: {
                     clipId: string;
                 };
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;
@@ -7919,6 +7950,7 @@ export declare const RenderJob: z.ZodObject<{
                     }[];
                 }[];
                 source: "authored";
+                zPlane?: "front" | "behind-subject" | undefined;
                 style?: {
                     position?: "top" | "center" | "bottom" | undefined;
                     fontFamily?: string | undefined;

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

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