@cueframe/kernel 0.1.4 → 0.2.0

package/dist/_members/core/render/compositionAudioAndDepth.d.ts

@@ -0,0 +1,6 @@
+import type { Composition } from "../../composition/validators/index.js";
+import type { CompositionAudioTrack, CompositionClip, CompositionOverlay, RenderInput } from "./types.js";
+export declare function applyRoleDefaultGains(audioTracks: CompositionAudioTrack[], composition: Composition): void;
+export declare function applyDuckEnvelopes(audioTracks: CompositionAudioTrack[], composition: Composition, fps: number): void;
+export declare function bindBehindSubjectHosts(overlays: CompositionOverlay[], clips: readonly CompositionClip[]): void;
+export declare function assertBehindSubjectCaptionCoverage(captionSegments: RenderInput['captionSegments'], clips: readonly CompositionClip[], fps: number): void;

package/dist/_members/core/render/compositionRender.d.ts

@@ -1,12 +1,13 @@
 import type { Composition, Format } from "../../composition/validators/index.js";
 import type { RenderInput } from "./types.js";
 import type { TrajectoryData } from "../../composition/reframe/trajectory.js";
+export { validateComposition } from "./compositionValidation.js";
+export { assertBehindSubjectCaptionCoverage } from "./compositionAudioAndDepth.js";
 export declare function compositionFormatDimensions(format: Format): {
     width: number;
     height: number;
     fps: number;
 };
-export declare function validateComposition(raw: unknown): Composition;
 export declare function playableSpans(trimStart: number, trimEnd: number, excluded: Array<{
     start: number;
     end: number;
@@ -15,13 +16,11 @@ export declare function playableSpans(trimStart: number, trimEnd: number, exclud
     end: number;
 }>;
 export declare function referencedMediaIds(composition: Composition): string[];
-export declare function componentRefsByClipId(composition: Composition): Record<string, string>;
-export declare function compositionToRenderInput(composition: Composition, srcUrls: Record<string, string>, trajectoryUrls?: Record<string, string>, coViewUrls?: Record<string, string>, alphaUrls?: Record<string, string>, jsSourceByClipId?: Record<string, string>, subCompositions?: Record<string, Composition>, trajectories?: Record<string, TrajectoryData>): RenderInput;
+export declare function compositionToRenderInput(composition: Composition, srcUrls: Record<string, string>, trajectoryUrls?: Record<string, string>, coViewUrls?: Record<string, string>, alphaUrls?: Record<string, string>, subCompositions?: Record<string, Composition>, trajectories?: Record<string, TrajectoryData>): RenderInput;
 export declare function assembleRenderInput(composition: Composition, resolved: {
     srcUrls: Record<string, string>;
     trajectoryUrls?: Record<string, string>;
     coViewUrls?: Record<string, string>;
     alphaUrls?: Record<string, string>;
-    jsSourceByClipId?: Record<string, string>;
     fontAssets?: NonNullable<RenderInput["brandKit"]>["fontAssets"];
 }): RenderInput;

package/dist/_members/core/render/compositionValidation.d.ts

@@ -0,0 +1,4 @@
+import type { Composition } from "../../composition/validators/index.js";
+import { CueframeError, type ErrorCode } from "../../errors/index.js";
+export declare function renderInputError(code: ErrorCode, message: string, locator: Record<string, unknown>): CueframeError;
+export declare function validateComposition(raw: unknown): Composition;

package/dist/_members/core/render/index.d.ts

@@ -1,10 +1,10 @@
-export type { RenderInput, CompositionClip, CompositionOverlay, CompositionAudioTrack, CompositionEffect, CaptionWord, CaptionStyle, OverlayTemplate, OverlayParams } from './types.js';
+export type { RenderInput, ProjectedVisualIdentity, CompositionClip, CompositionOverlay, CompositionAudioTrack, CompositionEffect, CaptionWord, CaptionStyle, OverlayTemplate, OverlayParams } from './types.js';
 export type { ResolvedBrandKit } from '../../composition/projection/index.js';
 export type { EmphasisWord } from './emphasis.js';
 export type { DocNode, TranscriptUtterance } from './captions.js';
 export { buildEmphasisSet, isEmphasized } from './emphasis.js';
 export { extractCaptionWordsFromDoc, sliceTranscriptWords, splitIntoSentences } from './captions.js';
-export { compositionToRenderInput, referencedMediaIds, componentRefsByClipId, assembleRenderInput, validateComposition, compositionFormatDimensions, playableSpans, } from './compositionRender.js';
+export { compositionToRenderInput, referencedMediaIds, assembleRenderInput, validateComposition, compositionFormatDimensions, playableSpans, assertBehindSubjectCaptionCoverage, } from './compositionRender.js';
 export { bookendFrames, resolveBookendTimeline, CARD_BOOKEND_DEFAULT_MS, VIDEO_BOOKEND_DEFAULT_MS, } from './bookends.js';
 export type { BookendTimeline } from './bookends.js';
 export { DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, ensureEven, qualityToCrf, resolutionToOutputSize, } from './exportSettings.js';

package/dist/_members/core/render/types.d.ts

@@ -1,9 +1,19 @@
-import type { Scene, GlobalEffects, EffectTarget } from '../../composition/ops/index.js';
+import type { EffectTarget } from '../../composition/ops/index.js';
 import type { ResolvedBrandKit } from '../../composition/projection/index.js';
 import type { Reframe } from '../../composition/reframe/index.js';
 import type { TrajectoryData } from '../../composition/reframe/trajectory.js';
 import type { CaptionWord as WireCaptionWord, CaptionStyle as WireCaptionStyle } from '../../composition/validators/index.js';
 export type OverlayTemplate = 'custom' | 'gif' | 'image' | 'lottie' | (string & {});
+/**
+ * Stable visual ordering projected from Composition.tracks.
+ * Track index 0 is the highest timeline lane; larger layerIndex paints later.
+ */
+export interface ProjectedVisualIdentity {
+    trackId: string;
+    trackIndex: number;
+    layerIndex: number;
+    contentIndex: number;
+}
 export interface OverlayParams {
     text: string;
     subtext?: string;
@@ -12,8 +22,6 @@ export interface OverlayParams {
     textColor?: string;
     fontFamily?: string;
     backgroundColor?: string;
-    sourceCode?: string;
-    jsxSource?: string;
     transition?: 'fade' | 'slide' | 'wipe' | 'none';
     sequenceGroup?: string;
     src?: string;
@@ -29,7 +37,7 @@ export interface OverlayParams {
     html?: string;
     cssTokens?: Record<string, string>;
 }
-export interface CompositionClip {
+export interface CompositionClip extends ProjectedVisualIdentity {
     id: string;
     src: string;
     previewSrc?: string;
@@ -68,7 +76,7 @@ export interface CompositionClip {
     packedUrl?: string;
     coViewDebug?: boolean;
 }
-export interface CompositionOverlay {
+export interface CompositionOverlay extends ProjectedVisualIdentity {
     id: string;
     template: OverlayTemplate;
     templateId?: string;
@@ -76,6 +84,8 @@ export interface CompositionOverlay {
     durationInFrames: number;
     params: OverlayParams;
     zPlane?: 'front' | 'behind-subject';
+    /** Canonical packed clip that owns a behind-subject overlay. */
+    hostClipId?: string;
     anchor?: {
         space: 'scene';
         x: number;
@@ -102,7 +112,7 @@ export interface CompositionOverlay {
 }
 export type CaptionWord = WireCaptionWord;
 export type CaptionStyle = WireCaptionStyle & Required<Pick<WireCaptionStyle, 'fontFamily' | 'fontSize' | 'fontWeight' | 'color' | 'highlightColor' | 'backgroundColor' | 'position' | 'textTransform'>>;
-export interface CompositionEffect {
+export interface CompositionEffect extends ProjectedVisualIdentity {
     id: string;
     primitiveId: string;
     params: Record<string, unknown>;
@@ -146,7 +156,5 @@ export interface RenderInput {
     outputHeight?: number;
     crf?: number;
     watermark?: boolean;
-    scenes?: Scene[];
-    sceneGlobal?: GlobalEffects;
     brandKit?: ResolvedBrandKit;
 }

package/dist/_members/director/ai-sdk/messages.d.ts

@@ -5,119 +5,50 @@ import { GenerationArtifact } from "../domain/generation.js";
 export declare const CueFrameMessageMetadata: z.ZodOptional<z.ZodObject<{
     createdAt: z.ZodNumber;
     runId: z.ZodOptional<z.ZodString>;
-    backend: z.ZodOptional<z.ZodEnum<["cli", "ts-agent", "convex-agent", "direct"]>>;
+    backend: z.ZodOptional<z.ZodEnum<{
+        cli: "cli";
+        "ts-agent": "ts-agent";
+        "convex-agent": "convex-agent";
+        direct: "direct";
+    }>>;
     context: z.ZodOptional<z.ZodObject<{
         location: z.ZodString;
         project: z.ZodDefault<z.ZodNullable<z.ZodObject<{
             id: z.ZodString;
-            home: z.ZodEnum<["local", "cloud"]>;
-        }, "strip", z.ZodTypeAny, {
-            id: string;
-            home: "local" | "cloud";
-        }, {
-            id: string;
-            home: "local" | "cloud";
-        }>>>;
-        selectedMediaIds: z.ZodDefault<z.ZodArray<z.ZodBranded<z.ZodString, "Id<media>">, "many">>;
+            home: z.ZodEnum<{
+                local: "local";
+                cloud: "cloud";
+            }>;
+        }, z.core.$strip>>>;
+        selectedMediaIds: z.ZodDefault<z.ZodArray<z.core.$ZodBranded<z.ZodString, "Id<media>", "out">>>;
         fastMode: z.ZodDefault<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
-        location: string;
-        project: {
-            id: string;
-            home: "local" | "cloud";
-        } | null;
-        selectedMediaIds: (string & z.BRAND<"Id<media>">)[];
-        fastMode: boolean;
-    }, {
-        location: string;
-        project?: {
-            id: string;
-            home: "local" | "cloud";
-        } | null | undefined;
-        selectedMediaIds?: string[] | undefined;
-        fastMode?: boolean | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    createdAt: number;
-    context?: {
-        location: string;
-        project: {
-            id: string;
-            home: "local" | "cloud";
-        } | null;
-        selectedMediaIds: (string & z.BRAND<"Id<media>">)[];
-        fastMode: boolean;
-    } | undefined;
-    runId?: string | undefined;
-    backend?: "cli" | "ts-agent" | "convex-agent" | "direct" | undefined;
-}, {
-    createdAt: number;
-    context?: {
-        location: string;
-        project?: {
-            id: string;
-            home: "local" | "cloud";
-        } | null | undefined;
-        selectedMediaIds?: string[] | undefined;
-        fastMode?: boolean | undefined;
-    } | undefined;
-    runId?: string | undefined;
-    backend?: "cli" | "ts-agent" | "convex-agent" | "direct" | undefined;
-}>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
 export type CueFrameMessageMetadata = z.infer<typeof CueFrameMessageMetadata>;
 export declare const CueFramePhase: z.ZodObject<{
     phase: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    phase: string;
-    detail?: string | undefined;
-}, {
-    phase: string;
-    detail?: string | undefined;
-}>;
+}, z.core.$strip>;
 export declare const CueFrameIteration: z.ZodObject<{
     iteration: z.ZodNumber;
     maxIterations: z.ZodNumber;
     agent: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    agent: string;
-    iteration: number;
-    maxIterations: number;
-}, {
-    agent: string;
-    iteration: number;
-    maxIterations: number;
-}>;
+}, z.core.$strip>;
 export declare const CueFrameSuggestions: z.ZodObject<{
-    items: z.ZodArray<z.ZodString, "many">;
-}, "strip", z.ZodTypeAny, {
-    items: string[];
-}, {
-    items: string[];
-}>;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export declare const CueFramePlan: z.ZodObject<{
     plan: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    plan: string;
-}, {
-    plan: string;
-}>;
+}, z.core.$strip>;
 export declare const CueFrameRunOutcome: z.ZodObject<{
-    outcome: z.ZodEnum<["aborted", "error"]>;
+    outcome: z.ZodEnum<{
+        error: "error";
+        aborted: "aborted";
+    }>;
     reason: z.ZodOptional<z.ZodString>;
     wrote: z.ZodBoolean;
     phase: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    outcome: "aborted" | "error";
-    wrote: boolean;
-    phase?: string | undefined;
-    reason?: string | undefined;
-}, {
-    outcome: "aborted" | "error";
-    wrote: boolean;
-    phase?: string | undefined;
-    reason?: string | undefined;
-}>;
+}, z.core.$strip>;
 export type CueFrameUIData = {
     phase: z.infer<typeof CueFramePhase>;
     iteration: z.infer<typeof CueFrameIteration>;
@@ -132,69 +63,56 @@ export declare const cueFrameDataPartSchemas: {
     phase: z.ZodObject<{
         phase: z.ZodString;
         detail: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        phase: string;
-        detail?: string | undefined;
-    }, {
-        phase: string;
-        detail?: string | undefined;
-    }>;
+    }, z.core.$strip>;
     iteration: z.ZodObject<{
         iteration: z.ZodNumber;
         maxIterations: z.ZodNumber;
         agent: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        agent: string;
-        iteration: number;
-        maxIterations: number;
-    }, {
-        agent: string;
-        iteration: number;
-        maxIterations: number;
-    }>;
+    }, z.core.$strip>;
     suggestions: z.ZodObject<{
-        items: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        items: string[];
-    }, {
-        items: string[];
-    }>;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
     plan: z.ZodObject<{
         plan: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        plan: string;
-    }, {
-        plan: string;
-    }>;
+    }, z.core.$strip>;
     run: z.ZodObject<{
-        outcome: z.ZodEnum<["aborted", "error"]>;
+        outcome: z.ZodEnum<{
+            error: "error";
+            aborted: "aborted";
+        }>;
         reason: z.ZodOptional<z.ZodString>;
         wrote: z.ZodBoolean;
         phase: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        outcome: "aborted" | "error";
-        wrote: boolean;
-        phase?: string | undefined;
-        reason?: string | undefined;
-    }, {
-        outcome: "aborted" | "error";
-        wrote: boolean;
-        phase?: string | undefined;
-        reason?: string | undefined;
-    }>;
+    }, z.core.$strip>;
     generation: z.ZodObject<{
         artifactVersion: z.ZodLiteral<1>;
-        clientRequestId: z.ZodBranded<z.ZodString, "Id<generationRequest>">;
-        generationId: z.ZodBranded<z.ZodString, "Id<generation>">;
-        mediaId: z.ZodBranded<z.ZodString, "Id<media>">;
-        generationGroupId: z.ZodBranded<z.ZodString, "Id<generationGroup>">;
+        clientRequestId: z.core.$ZodBranded<z.ZodString, "Id<generationRequest>", "out">;
+        generationId: z.core.$ZodBranded<z.ZodString, "Id<generation>", "out">;
+        mediaId: z.core.$ZodBranded<z.ZodString, "Id<media>", "out">;
+        generationGroupId: z.core.$ZodBranded<z.ZodString, "Id<generationGroup>", "out">;
         version: z.ZodNumber;
-        kind: z.ZodEnum<["image", "video", "audio"]>;
+        kind: z.ZodEnum<{
+            video: "video";
+            audio: "audio";
+            image: "image";
+        }>;
         requestSummary: z.ZodString;
-        status: z.ZodEnum<["draft", "submitting", "queued", "generating", "provider_complete", "materialising", "processing", "ready", "cancelling", "cancelled", "failed"]>;
+        status: z.ZodEnum<{
+            generating: "generating";
+            processing: "processing";
+            cancelled: "cancelled";
+            ready: "ready";
+            failed: "failed";
+            draft: "draft";
+            submitting: "submitting";
+            queued: "queued";
+            provider_complete: "provider_complete";
+            materialising: "materialising";
+            cancelling: "cancelling";
+        }>;
         progress: z.ZodOptional<z.ZodNumber>;
         placementReady: z.ZodDefault<z.ZodBoolean>;
-        parentMediaId: z.ZodOptional<z.ZodBranded<z.ZodString, "Id<media>">>;
+        parentMediaId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "Id<media>", "out">>;
         estimateUsd: z.ZodOptional<z.ZodNumber>;
         failure: z.ZodOptional<z.ZodObject<{
             code: z.ZodString;
@@ -202,91 +120,23 @@ export declare const cueFrameDataPartSchemas: {
             recovery: z.ZodOptional<z.ZodString>;
             retryable: z.ZodBoolean;
             correlationId: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            code: string;
-            title: string;
-            retryable: boolean;
-            recovery?: string | undefined;
-            correlationId?: string | undefined;
-        }, {
-            code: string;
-            title: string;
-            retryable: boolean;
-            recovery?: string | undefined;
-            correlationId?: string | undefined;
-        }>>;
+        }, z.core.$strip>>;
         createdAt: z.ZodNumber;
         updatedAt: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        status: "generating" | "processing" | "cancelled" | "ready" | "failed" | "draft" | "submitting" | "queued" | "provider_complete" | "materialising" | "cancelling";
-        kind: "video" | "audio" | "image";
-        mediaId: string & z.BRAND<"Id<media>">;
-        createdAt: number;
-        updatedAt: number;
-        clientRequestId: string & z.BRAND<"Id<generationRequest>">;
-        generationGroupId: string & z.BRAND<"Id<generationGroup>">;
-        generationId: string & z.BRAND<"Id<generation>">;
-        version: number;
-        artifactVersion: 1;
-        requestSummary: string;
-        placementReady: boolean;
-        parentMediaId?: (string & z.BRAND<"Id<media>">) | undefined;
-        estimateUsd?: number | undefined;
-        progress?: number | undefined;
-        failure?: {
-            code: string;
-            title: string;
-            retryable: boolean;
-            recovery?: string | undefined;
-            correlationId?: string | undefined;
-        } | undefined;
-    }, {
-        status: "generating" | "processing" | "cancelled" | "ready" | "failed" | "draft" | "submitting" | "queued" | "provider_complete" | "materialising" | "cancelling";
-        kind: "video" | "audio" | "image";
-        mediaId: string;
-        createdAt: number;
-        updatedAt: number;
-        clientRequestId: string;
-        generationGroupId: string;
-        generationId: string;
-        version: number;
-        artifactVersion: 1;
-        requestSummary: string;
-        parentMediaId?: string | undefined;
-        estimateUsd?: number | undefined;
-        progress?: number | undefined;
-        placementReady?: boolean | undefined;
-        failure?: {
-            code: string;
-            title: string;
-            retryable: boolean;
-            recovery?: string | undefined;
-            correlationId?: string | undefined;
-        } | undefined;
-    }>;
+    }, z.core.$strip>;
     error: z.ZodObject<{
         code: z.ZodString;
         title: z.ZodString;
         recovery: z.ZodOptional<z.ZodString>;
         retryable: z.ZodBoolean;
-        source: z.ZodOptional<z.ZodEnum<["provider", "generation", "materialisation", "agent", "transport"]>>;
+        source: z.ZodOptional<z.ZodEnum<{
+            provider: "provider";
+            generation: "generation";
+            materialisation: "materialisation";
+            agent: "agent";
+            transport: "transport";
+        }>>;
         correlationId: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        code: string;
-        title: string;
-        retryable: boolean;
-        recovery?: string | undefined;
-        source?: "provider" | "generation" | "materialisation" | "agent" | "transport" | undefined;
-        correlationId?: string | undefined;
-        details?: string | undefined;
-    }, {
-        code: string;
-        title: string;
-        retryable: boolean;
-        recovery?: string | undefined;
-        source?: "provider" | "generation" | "materialisation" | "agent" | "transport" | undefined;
-        correlationId?: string | undefined;
-        details?: string | undefined;
-    }>;
+    }, z.core.$strip>;
 };