@cueframe/kernel 0.2.2 → 0.2.4

package/dist/_members/composition/scene/schema.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Canonical authored SceneShotSpecV2 contract.
+ *
+ * This module contains persisted authoring data only. Renderer-prepared values such as baked
+ * image metadata, resolved colours, shadow bounds, builder facts and allocation ledgers belong
+ * to later preparation/runtime contracts.
+ */
+import { z } from 'zod';
+export declare const SCENE_SHOT_SPEC_VERSION: 2;
+export declare const SCENE_MAX_LAYERS = 32;
+export declare const SCENE_MAX_GROUP_DEPTH = 4;
+export declare const SCENE_MAX_KEYFRAMES_PER_CHANNEL = 256;
+export declare const SCENE_MAX_KEYFRAMES_PER_SHOT = 2048;
+export declare const SCENE_MAX_SURFACES = 32;
+export declare const SCENE_FOV_MIN: number;
+export declare const SCENE_FOV_MAX: number;
+export declare const SCENE_LAYER_ID_PATTERN: RegExp;
+export declare const SCENE_ASSET_SLOT_PATTERN: RegExp;
+export declare const SCENE_BRAND_COLOR_TOKENS: readonly ["background", "surface", "text", "textMuted", "accent", "accentStrong", "accentSoft", "success", "warning", "danger"];
+export type SceneBrandColorToken = (typeof SCENE_BRAND_COLOR_TOKENS)[number];
+export declare const SCENE_BRAND_FONT_TOKENS: readonly ["heading", "body", "caption"];
+export type SceneBrandFontToken = (typeof SCENE_BRAND_FONT_TOKENS)[number];
+export type SceneBrandColorRefValue = `$brand:colors.${SceneBrandColorToken}`;
+export type SceneBrandFontRefValue = `$brand:fonts.${SceneBrandFontToken}`;
+export type SceneColor = string;
+export type SceneFontFamily = string;
+export type SceneVec3 = [number, number, number];
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const SceneHexColor: z.ZodString;
+export declare const SceneBrandColorRef: z.ZodEnum<{
+    "$brand:colors.accent": "$brand:colors.accent";
+    "$brand:colors.surface": "$brand:colors.surface";
+    "$brand:colors.success": "$brand:colors.success";
+    "$brand:colors.text": "$brand:colors.text";
+    "$brand:colors.background": "$brand:colors.background";
+    "$brand:colors.textMuted": "$brand:colors.textMuted";
+    "$brand:colors.warning": "$brand:colors.warning";
+    "$brand:colors.accentStrong": "$brand:colors.accentStrong";
+    "$brand:colors.accentSoft": "$brand:colors.accentSoft";
+    "$brand:colors.danger": "$brand:colors.danger";
+}>;
+export declare const SceneColor: z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+    "$brand:colors.accent": "$brand:colors.accent";
+    "$brand:colors.surface": "$brand:colors.surface";
+    "$brand:colors.success": "$brand:colors.success";
+    "$brand:colors.text": "$brand:colors.text";
+    "$brand:colors.background": "$brand:colors.background";
+    "$brand:colors.textMuted": "$brand:colors.textMuted";
+    "$brand:colors.warning": "$brand:colors.warning";
+    "$brand:colors.accentStrong": "$brand:colors.accentStrong";
+    "$brand:colors.accentSoft": "$brand:colors.accentSoft";
+    "$brand:colors.danger": "$brand:colors.danger";
+}>]>;
+export declare const SceneBrandFontRef: z.ZodEnum<{
+    "$brand:fonts.caption": "$brand:fonts.caption";
+    "$brand:fonts.body": "$brand:fonts.body";
+    "$brand:fonts.heading": "$brand:fonts.heading";
+}>;
+export declare const SCENE_FONT_FAMILY_PATTERN: RegExp;
+export declare const SceneAdmittedFontFamily: z.ZodString;
+export declare const SceneFontFamily: z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+    "$brand:fonts.caption": "$brand:fonts.caption";
+    "$brand:fonts.body": "$brand:fonts.body";
+    "$brand:fonts.heading": "$brand:fonts.heading";
+}>]>;
+export declare const SceneLayerId: z.ZodString;
+export declare const SceneAssetSlot: z.ZodString;
+export interface SceneReferenceSizeV2 {
+    width: number;
+    height: number;
+}
+export declare const SceneReferenceSizeV2: z.ZodType<SceneReferenceSizeV2>;
+export interface SceneCameraV2 {
+    position: SceneVec3;
+    rotation: SceneVec3;
+    fov: number;
+}
+/** Authored camera fields. Omitted members are materialized from the shot reference height. */
+export interface SceneCameraInputV2 {
+    position?: SceneVec3;
+    rotation?: SceneVec3;
+    fov?: number;
+}
+export declare const SceneCameraInputV2: z.ZodType<SceneCameraInputV2>;
+/** Fully materialized camera shape consumed by evaluation and preparation. */
+export declare const SceneCameraV2: z.ZodType<SceneCameraV2>;
+export interface SceneTransformV2 {
+    position: SceneVec3;
+    rotation: SceneVec3;
+    scale: number;
+}
+export declare const SceneTransformV2: z.ZodType<SceneTransformV2>;
+export interface SceneGradientStopV2 {
+    at: number;
+    color: SceneColor;
+}
+export type SceneBackdropV2 = {
+    kind: 'transparent';
+} | {
+    kind: 'solid';
+    color: SceneColor;
+} | {
+    kind: 'linear';
+    angle: number;
+    stops: SceneGradientStopV2[];
+} | {
+    kind: 'radial';
+    at: [number, number];
+    stops: SceneGradientStopV2[];
+};
+export declare const SceneBackdropV2: z.ZodType<SceneBackdropV2>;
+export interface SceneImageSurfaceV2 {
+    source: 'image';
+    assetSlot: string;
+}
+export interface SceneColorSurfaceV2 {
+    source: 'color';
+    color: SceneColor;
+}
+export interface SceneComponentSurfaceV2 {
+    source: 'component';
+    component: {
+        version: 1;
+        componentId: string;
+        sourceVersionId: string;
+    };
+    captureFrame: number;
+    layout: {
+        width: number;
+        height: number;
+    };
+    /** Omission lets preparation choose effective scale 2 or auto-raise to 3. */
+    bakeScale?: 2 | 3;
+    params?: Record<string, JsonValue>;
+}
+export interface SceneVideoSurfaceV2 {
+    source: 'video';
+    mediaId: string;
+    startFrame: number;
+    endFrame?: number;
+}
+export type SceneSurfaceBindingV2 = SceneImageSurfaceV2 | SceneColorSurfaceV2 | SceneComponentSurfaceV2 | SceneVideoSurfaceV2;
+export declare const SceneSurfaceBindingV2: z.ZodType<SceneSurfaceBindingV2>;
+export interface SceneMaterialOverrideV2 {
+    role: string;
+    type: 'physical' | 'unlit';
+    color?: SceneColor;
+    roughness?: number;
+    metalness?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    anisotropy?: number;
+    anisotropyRotation?: number;
+    ior?: number;
+    reflectivity?: number;
+}
+export declare const SceneMaterialOverrideV2: z.ZodType<SceneMaterialOverrideV2>;
+export interface SceneTextRunV2 {
+    text: string;
+    color?: SceneColor;
+    emphasis?: boolean;
+}
+export interface SceneTextLineV2 {
+    runs: SceneTextRunV2[];
+}
+interface SceneObjectBaseV2 {
+    id: string;
+    transform: SceneTransformV2;
+    opacity: number;
+}
+interface SceneMaterialObjectV2 extends SceneObjectBaseV2 {
+    materials?: SceneMaterialOverrideV2[];
+    surfaces?: Record<string, SceneSurfaceBindingV2>;
+}
+interface SceneTextBodyV2 {
+    id: string;
+    opacity: number;
+    lines: SceneTextLineV2[];
+    fontFamily: SceneFontFamily;
+    fontWeight: number;
+    fontStyle: 'normal' | 'italic';
+    fontSize: number;
+    lineHeight: number;
+    letterSpacing: number;
+    align: 'left' | 'center' | 'right';
+    maxWidth?: number;
+    color: SceneColor;
+}
+export interface SceneGroupV2 extends SceneObjectBaseV2 {
+    kind: 'group';
+    children: SceneObjectV2[];
+}
+export interface SceneLaptopV2 extends SceneMaterialObjectV2 {
+    kind: 'laptop';
+    width: number;
+    openAngle: number;
+}
+export interface ScenePhoneV2 extends SceneMaterialObjectV2 {
+    kind: 'phone';
+    width: number;
+}
+export interface SceneSlabV2 extends SceneMaterialObjectV2 {
+    kind: 'slab';
+    width: number;
+    height: number;
+    thickness: number;
+    cornerRadius: number;
+    edgeRadius: number;
+    finish: 'satin' | 'brushed';
+}
+export interface ScenePageV2 extends SceneObjectBaseV2 {
+    kind: 'page';
+    width: number;
+    height: number;
+    fit: 'contain' | 'cover';
+    transparency: 'straight' | 'premultiplied' | 'opaque';
+    depthWrite: boolean;
+    backface: 'hidden' | 'visible';
+    materials?: SceneMaterialOverrideV2[];
+    surfaces: Record<string, SceneSurfaceBindingV2>;
+}
+export interface SceneWorldTextV2 extends SceneTextBodyV2 {
+    kind: 'text';
+    space: 'world';
+    transform: SceneTransformV2;
+}
+export interface SceneScreenTextV2 extends SceneTextBodyV2 {
+    kind: 'text';
+    space: 'screen';
+    x: number;
+    y: number;
+    rotation: number;
+    scale: number;
+}
+export type SceneObjectV2 = SceneGroupV2 | SceneLaptopV2 | ScenePhoneV2 | SceneSlabV2 | ScenePageV2 | SceneWorldTextV2 | SceneScreenTextV2;
+export declare const SceneObjectV2: z.ZodType<SceneObjectV2>;
+export type SceneEasingV2 = {
+    kind: 'linear';
+} | {
+    kind: 'hold';
+} | {
+    kind: 'bezier';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+export interface SceneKeyframeV2 {
+    at: number;
+    value: number;
+    easing?: SceneEasingV2;
+}
+export type SceneChannelTargetV2 = {
+    kind: 'camera';
+} | {
+    kind: 'layer';
+    layerId: string;
+} | {
+    kind: 'environment';
+} | {
+    kind: 'focus';
+};
+export interface SceneChannelV2 {
+    target: SceneChannelTargetV2;
+    property: string;
+    keyframes: SceneKeyframeV2[];
+}
+export declare const SceneEasingV2: z.ZodType<SceneEasingV2>;
+export declare const SceneKeyframeV2: z.ZodType<SceneKeyframeV2>;
+export declare const SceneChannelTargetV2: z.ZodType<SceneChannelTargetV2>;
+export declare const SceneChannelV2: z.ZodType<SceneChannelV2>;
+export declare const SCENE_CAMERA_PROPERTIES: readonly ["positionX", "positionY", "positionZ", "rotationX", "rotationY", "rotationZ", "fov"];
+export declare const SCENE_WORLD_OBJECT_PROPERTIES: readonly ["positionX", "positionY", "positionZ", "rotationX", "rotationY", "rotationZ", "scale", "opacity"];
+export declare const SCENE_LAPTOP_PROPERTIES: readonly ["positionX", "positionY", "positionZ", "rotationX", "rotationY", "rotationZ", "scale", "opacity", "openAngle"];
+export declare const SCENE_SCREEN_TEXT_PROPERTIES: readonly ["x", "y", "rotation", "scale", "opacity"];
+export declare const SCENE_ENVIRONMENT_PROPERTIES: readonly ["intensity"];
+export declare const SCENE_FOCUS_PROPERTIES: readonly ["distance", "range", "maxBlur"];
+export declare const SCENE_CHANNEL_PROPERTIES: readonly ("x" | "y" | "opacity" | "scale" | "rotation" | "intensity" | "fov" | "range" | "maxBlur" | "openAngle" | "distance" | "positionX" | "positionY" | "positionZ" | "rotationX" | "rotationY" | "rotationZ")[];
+export interface SceneFocusV2 {
+    distance: number;
+    range: number;
+    maxBlur: number;
+}
+export interface ScenePostV2 {
+    grain: number;
+    vignette: number;
+    focus: SceneFocusV2 | null;
+}
+export declare const SceneFocusV2: z.ZodType<SceneFocusV2>;
+export declare const ScenePostV2: z.ZodType<ScenePostV2>;
+export interface SceneGeneratedStudioRigV2 {
+    kind?: 'studio';
+    lightingProfile: 'studio' | 'studio-edge';
+    preset: 'soft' | 'key' | 'rim';
+    intensity: number;
+    floorY: number;
+    shadowOpacity: number;
+}
+export interface ScenePhotographicStudioRigV1 {
+    kind: 'photographic-studio-v1';
+}
+export type SceneRigV2 = SceneGeneratedStudioRigV2 | ScenePhotographicStudioRigV1;
+export declare const SceneRigV2: z.ZodType<SceneRigV2>;
+export interface SceneConstraintV2 {
+    kind: 'minSeparation';
+    objects: string[];
+    gap: number;
+}
+export declare const SceneConstraintV2: z.ZodType<SceneConstraintV2>;
+export interface SceneShotSpecV2 {
+    version: 2;
+    referenceSize: SceneReferenceSizeV2;
+    camera: SceneCameraV2;
+    environment: SceneRigV2;
+    backdrop: SceneBackdropV2;
+    layers: SceneObjectV2[];
+    animation: SceneChannelV2[];
+    post: ScenePostV2;
+    constraints: SceneConstraintV2[];
+}
+export declare const SCENE_PRESET_SLOTS: Readonly<{
+    readonly laptop: readonly ["screen"];
+    readonly phone: readonly ["screen"];
+    readonly slab: readonly ["front"];
+    readonly page: readonly ["content"];
+}>;
+export declare const SCENE_PRESET_MATERIAL_ROLES: Readonly<{
+    readonly laptop: readonly ["base", "lid", "keyboard", "trackpad", "bezel", "screen", "glass"];
+    readonly phone: readonly ["shell", "screen", "glass"];
+    readonly slab: readonly ["body", "face"];
+    readonly page: readonly ["base"];
+}>;
+export type SceneRefusalCode = 'scene_spec_version_unsupported' | 'scene_lighting_profile_unsupported' | 'scene_rig_unsupported' | 'scene_photographic_rig_field_unsupported' | 'scene_object_light_field_unsupported';
+/**
+ * The one public admission schema. Its first stage provides named, exact-path refusals and its
+ * second stage parses/materializes the schema that is also published as JSON Schema.
+ */
+export declare const SceneShotSpecV2: z.ZodType<SceneShotSpecV2>;
+/** Parse untrusted authored data through the same public schema all consumers embed. */
+export declare function parseSceneShotSpecV2(value: unknown): SceneShotSpecV2;
+/** Distinct outer image asset slots in first-use order, recursively through groups. */
+export declare function sceneShotImageSlots(spec: Pick<SceneShotSpecV2, 'layers'>): string[];
+/** Distinct video media ids in first-use order, recursively through groups. */
+export declare function sceneShotVideoSlots(spec: Pick<SceneShotSpecV2, 'layers'>): string[];
+export declare function sceneShotSurfaceCount(spec: Pick<SceneShotSpecV2, 'layers'>): number;
+/** Agent-facing schema generated from the same Zod contract used by runtime parsing. */
+export declare const sceneShotJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodType<SceneShotSpecV2, unknown, z.core.$ZodTypeInternals<SceneShotSpecV2, unknown>>>;
+export declare function sceneShotJsonSchemaText(): string;
+export {};

package/dist/_members/composition/scene/videoSchedule.d.ts

@@ -0,0 +1,43 @@
+export interface SceneVideoRateV1 {
+    num: number;
+    den: number;
+}
+export interface SceneVerifiedPresentationIndexV1 {
+    /** Integer presentation timestamps in decode/display order. */
+    pts: readonly number[];
+    timeBase: SceneVideoRateV1;
+}
+export interface SceneSealedVideoScheduleV1 {
+    sourceRate: SceneVideoRateV1;
+    shotRate: SceneVideoRateV1;
+    contentDuration: number;
+    startFrame: number;
+    endFrame: number;
+    sourceFrameCount: number;
+    addressing: 'midpoint';
+}
+export type SceneVideoAdmissionCode = 'video_presentation_index_missing' | 'video_variable_frame_rate' | 'video_trim_not_integer' | 'video_trim_out_of_range' | 'video_rate_invalid';
+export declare class SceneVideoAdmissionRefusal extends Error {
+    readonly code: SceneVideoAdmissionCode;
+    readonly corrective = "Render or transcode this asset to CFR with the existing media tools, then prepare the scene again.";
+    constructor(code: SceneVideoAdmissionCode, message: string);
+}
+export declare function canonicalSceneVideoRateV1(value: SceneVideoRateV1, field?: string): SceneVideoRateV1;
+export declare function verifySceneVideoPresentationIndexV1(index: SceneVerifiedPresentationIndexV1): {
+    sourceRate: SceneVideoRateV1;
+    sourceFrameCount: number;
+};
+export declare function prepareSceneVideoScheduleV1(input: {
+    presentationIndex: SceneVerifiedPresentationIndexV1;
+    shotRate: SceneVideoRateV1;
+    contentDuration: number;
+    startFrame: number;
+    endFrame?: number;
+}): SceneSealedVideoScheduleV1;
+export declare function sceneVideoSourceIndexV1(frame: number, schedule: SceneSealedVideoScheduleV1): number;
+/** The installed decoder receives frame 2s+1 at playbackRate Fo/(2Fs), selecting (s+1/2)/Fs. */
+export declare function sceneVideoMidpointAddressV1(frame: number, schedule: SceneSealedVideoScheduleV1): {
+    sourceIndex: number;
+    mediaFrame: number;
+    playbackRate: number;
+};

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

@@ -256,6 +256,7 @@ export declare const BrandKit: z.ZodObject<{
         entranceStaggerMs: z.ZodOptional<z.ZodNumber>;
         exitMs: z.ZodOptional<z.ZodNumber>;
         fontFamily: z.ZodOptional<z.ZodString>;
+        fontWeight: z.ZodOptional<z.ZodNumber>;
         emphasisFontFamily: z.ZodOptional<z.ZodString>;
         emphasisScale: z.ZodOptional<z.ZodNumber>;
         emphasisFontWeight: z.ZodOptional<z.ZodNumber>;

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

@@ -568,6 +568,7 @@ export declare const RenderSnapshot: z.ZodObject<{
             entranceStaggerMs: z.ZodOptional<z.ZodNumber>;
             exitMs: z.ZodOptional<z.ZodNumber>;
             fontFamily: z.ZodOptional<z.ZodString>;
+            fontWeight: z.ZodOptional<z.ZodNumber>;
             emphasisFontFamily: z.ZodOptional<z.ZodString>;
             emphasisScale: z.ZodOptional<z.ZodNumber>;
             emphasisFontWeight: z.ZodOptional<z.ZodNumber>;
@@ -1399,6 +1400,7 @@ export declare const RenderJob: z.ZodObject<{
                 entranceStaggerMs: z.ZodOptional<z.ZodNumber>;
                 exitMs: z.ZodOptional<z.ZodNumber>;
                 fontFamily: z.ZodOptional<z.ZodString>;
+                fontWeight: z.ZodOptional<z.ZodNumber>;
                 emphasisFontFamily: z.ZodOptional<z.ZodString>;
                 emphasisScale: z.ZodOptional<z.ZodNumber>;
                 emphasisFontWeight: z.ZodOptional<z.ZodNumber>;

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

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { Composition } from '../composition/validators/index.js';
 import type { TimelineClip as TimelineClipT, Track as TrackT } from '../composition/validators/index.js';
 import { type HeadlessStore } from '../composition/ops/index.js';
+import { SceneShotSpecV2 } from '../composition/scene/index.js';
 export type ClipKind = TrackT['kind'];
 export type MediaFamily = Extract<ClipKind, 'video' | 'audio' | 'image'>;
 export declare function mediaFamily(mimeType: string): MediaFamily;
@@ -786,6 +787,31 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<[z.ZodObject<{
         exitMs: z.ZodOptional<z.ZodNumber>;
         staggerMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"scene.add">;
+    clipId: z.ZodString;
+    trackId: z.ZodOptional<z.ZodString>;
+    newTrack: z.ZodOptional<z.ZodBoolean>;
+    newTrackId: z.ZodOptional<z.ZodString>;
+    startTime: z.ZodNumber;
+    duration: z.ZodNumber;
+    transitionIn: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        duration: z.ZodNumber;
+    }, z.core.$strip>>;
+    scene: z.ZodType<SceneShotSpecV2, unknown, z.core.$ZodTypeInternals<SceneShotSpecV2, unknown>>;
+    assets: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"scene.update">;
+    clipId: z.ZodString;
+    startTime: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    transitionIn: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        duration: z.ZodNumber;
+    }, z.core.$strip>>;
+    scene: z.ZodOptional<z.ZodType<SceneShotSpecV2, unknown, z.core.$ZodTypeInternals<SceneShotSpecV2, unknown>>>;
+    assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"materializeGrid">;
     clipId: z.ZodString;
@@ -873,6 +899,25 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<[z.ZodObject<{
     rangeIdx: z.ZodNumber;
 }, z.core.$strict>], "type">;
 export type CompositionOp = z.infer<typeof CompositionOp>;
+/**
+ * What the caption ops need of a store: the composition they are judged against, and the two
+ * writes they make.
+ *
+ * `applyOpToStore` and the op recorder both go through `applyCaptionOpToStore` below, so the op a
+ * journal records is by construction the op a replay applies. The recorder used to call the
+ * store's setter directly, which meant Studio's composition store and the in-app agent could
+ * write a caption style this gate refuses AND journal an op `applyOp` would then refuse on
+ * replay — a recording that cannot be replayed is worse than an ungated write.
+ */
+export type CaptionOpTarget = {
+    getState(): {
+        composition: Composition;
+    };
+} & Pick<HeadlessStore, 'setCaptionStyle' | 'setCaptions'>;
+export type CaptionOp = Extract<CompositionOp, {
+    type: 'setCaptionStyle' | 'setCaptions';
+}>;
+export declare function applyCaptionOpToStore(store: CaptionOpTarget, op: CaptionOp): void;
 export declare function applyOp(composition: Composition, op: CompositionOp): Composition;
 export declare function applyOpToStore(store: HeadlessStore, op: CompositionOp): void;
 export declare function invertOp(before: Composition, op: CompositionOp): CompositionOp;

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

@@ -1,5 +1,5 @@
 import type { Composition, TimelineClip, Marker, Track, Format, ReframeSegment, CaptionSegment, CaptionStyle, PerClipEffect } from '../composition/validators/index.js';
-import type { CompositionOp } from './index.js';
+import { type CompositionOp } from './index.js';
 export interface RecordableOps {
     addClip(clip: TimelineClip, options?: {
         newTrack?: boolean;

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

@@ -1,26 +1,58 @@
-import type { Composition, Format } from "../../composition/validators/index.js";
+import type { Composition, Format, TimelineClip as WireClip } from "../../composition/validators/index.js";
 import type { RenderInput } from "./types.js";
 import type { TrajectoryData } from "../../composition/reframe/trajectory.js";
+import { type PreparedRenderInputLeaseV1, type SceneShotPreparationDependenciesV1 } from "./sceneShotPreparation.js";
 export { validateComposition } from "./compositionValidation.js";
 export { assertBehindSubjectCaptionCoverage } from "./compositionAudioAndDepth.js";
+/** Re-exported from `trackProjection`, where the frame-lattice helpers it belongs with now live. */
+export { playableSpans } from "./trackProjection.js";
 export declare function compositionFormatDimensions(format: Format): {
     width: number;
     height: number;
     fps: number;
 };
-export declare function playableSpans(trimStart: number, trimEnd: number, excluded: Array<{
-    start: number;
-    end: number;
-}> | undefined): Array<{
-    start: number;
-    end: number;
-}>;
 export declare function referencedMediaIds(composition: Composition): string[];
-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 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>, options?: {
+    /**
+     * Which clips the caller's pinned source manifests declare as scene shots. Only a caller that
+     * holds `componentSources` can answer this, so a projection without them treats no clip as a
+     * scene shot — which is also what happens downstream: no pinned rows means no scene marker and
+     * no scene lane.
+     */
+    isSceneClip?: (clip: WireClip) => boolean;
+}): RenderInput;
+/**
+ * Projection plus the host's resolved bindings. When the host pins `componentSources`, every
+ * component overlay whose pinned source declares the scene-shot capability is prepared here:
+ * the composition-level scene rules run first over the whole `Composition`, then brand references
+ * are resolved from the render input's own brand snapshot, faces sealed, slots bound, and the
+ * typed scene marker set (see `sceneShotPreparation.ts`).
+ *
+ * Exactly two kinds of caller reach this function: Studio's export lane
+ * (`apps/studio/src/export/buildRenderInput.ts`, both builders) and any cloud host that projects a
+ * `Composition`. For them this is where the composition-level scene rules run, so a scene clip
+ * that acquired outer effects, an off-lattice time, a transition kind v1 refuses, a stale binding
+ * or a generic neighbour on its dedicated track is refused before projection, at the composition
+ * path the author edits.
+ *
+ * The other lanes do not come through here, and none of them is a hole. Studio's local evidence
+ * capture (`apps/studio/src/render/localEvidenceCapture.ts`) and its interactive preview
+ * (`apps/studio/src/render/sceneShotPreviewSeal.ts`) each hold a projection they built with
+ * `buildPreviewInput` and seal it by calling `prepareSceneShotOverlays` on it directly; they reach
+ * the composition-level rules through Studio's own host adapter, which runs the same shared
+ * `assertSceneClipShapes` over the whole composition before it pins any source
+ * (`apps/studio/src/render/projectComponentSources.ts`). The render harness has no composition to
+ * check at all: it is handed a finished `RenderInput` JSON, so it re-checks only what a render
+ * input alone can express (the seal, and the marker agreement on the page).
+ */
 export declare function assembleRenderInput(composition: Composition, resolved: {
     srcUrls: Record<string, string>;
     trajectoryUrls?: Record<string, string>;
     coViewUrls?: Record<string, string>;
     alphaUrls?: Record<string, string>;
+    trajectories?: Record<string, TrajectoryData>;
     fontAssets?: NonNullable<RenderInput["brandKit"]>["fontAssets"];
+    componentSources?: RenderInput["componentSources"];
 }): RenderInput;
+/** Projects a composition and realizes every V2 scene marker before returning renderable input. */
+export declare function assemblePreparedRenderInput(composition: Composition, resolved: Parameters<typeof assembleRenderInput>[1], dependencies: SceneShotPreparationDependenciesV1): Promise<PreparedRenderInputLeaseV1>;

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

@@ -1,10 +1,17 @@
-export type { RenderInput, ProjectedVisualIdentity, CompositionClip, CompositionOverlay, CompositionAudioTrack, CompositionEffect, CaptionWord, CaptionStyle, OverlayTemplate, OverlayParams } from './types.js';
+export type { RenderInput, ProjectedVisualIdentity, CompositionClip, CompositionOverlay, CompositionAudioTrack, CompositionEffect, CaptionWord, CaptionStyle, OverlayTemplate, OverlayParams, SceneShotOverlayMarkerV1, SceneShotSealedFontFace, SceneShotSlotBindingV1 } from './types.js';
+export { SCENE_SHOT_IMAGE_MIME_TYPES, SCENE_SHOT_PARAM, SCENE_SHOT_PREPARATION_STAGE, assertSceneClipShapes, prepareSceneShotRenderInput, readSceneShotManifest, resolvePinnedSceneFactsV1, sceneSourceResolverForPinnedRows, } from './sceneShotPreparation.js';
+export type { PreparedRenderInputLeaseV1, ResolvedScenePreparationFactsV1, SceneShotPreparationDependenciesV1, SceneShotPreparationLocator, } from './sceneShotPreparation.js';
 export type { ResolvedBrandKit } from '../../composition/projection/index.js';
+export { SCENE_CAPTURE_IDENTITY_FIELDS, SceneCaptureIdentityRefusal, canonicalSceneComponentCaptureIdentityV1, canonicalSceneJsonV1, completeSceneComponentCaptureIdentityV1, parseSceneComponentCaptureIdentityV1, parseSceneComponentCaptureIntentV1, } from './sceneCaptureIdentity.js';
+export type { SceneComponentCaptureIdentityV1 } from './sceneCaptureIdentity.js';
+export type { SceneBuilderAllocationDescriptorV1, SceneBuilderDescriptorRegistryV1, SceneBuilderDescriptorV1, SceneBuilderPartDescriptorV1, SceneBuilderSlotDescriptorV1, SceneCanonicalJson, SceneCaptureSessionAttestationV1, SceneComponentCaptureDependencyV1, SceneComponentCaptureIntentV1, SceneComponentCaptureResultV1, SceneComponentCaptureSessionV1, SceneExactRateV1, SceneVerifiedPngV1, } from './types.js';
+export * from './sceneShotPlan.js';
+export * from './slabDescriptor.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, assembleRenderInput, validateComposition, compositionFormatDimensions, playableSpans, assertBehindSubjectCaptionCoverage, } from './compositionRender.js';
+export { compositionToRenderInput, referencedMediaIds, assembleRenderInput, assemblePreparedRenderInput, 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/sceneCaptureIdentity.d.ts

@@ -0,0 +1,14 @@
+import type { SceneCaptureSessionAttestationV1, SceneComponentCaptureIntentV1 } from './types.js';
+/** Backward-compatible core name for the composition-owned portable field order. */
+export declare const SCENE_CAPTURE_IDENTITY_FIELDS: readonly ["componentId", "sourceVersionId", "params", "assetBindings", "layoutWidth", "layoutHeight", "bakeScale", "captureFrame", "durationInFrames", "fps", "seed", "brandFacts", "fontFacts", "mediaFacts", "rasterWidth", "rasterHeight", "runtimeIdentity", "dependencyIdentity", "browserProduct", "browserVersion", "browserExecutableSha256", "headless", "rasterAffectingFlags", "os", "arch", "deviceScaleFactor", "colorProfile", "requestedGlBackend", "actualGlBackend", "actualRenderer", "gpuIdentity"];
+export type SceneCaptureIdentityField = typeof SCENE_CAPTURE_IDENTITY_FIELDS[number];
+export type SceneComponentCaptureIdentityV1 = Omit<SceneComponentCaptureIntentV1, 'expectedDeviceScaleFactor'> & Omit<SceneCaptureSessionAttestationV1, 'loadedRuntimeIdentity' | 'loadedDependencyIdentity' | 'observedRasterAffectingFlags'>;
+export declare class SceneCaptureIdentityRefusal extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function canonicalSceneJsonV1(value: unknown, path?: string): string;
+export declare function parseSceneComponentCaptureIntentV1(value: unknown): SceneComponentCaptureIntentV1;
+export declare function parseSceneComponentCaptureIdentityV1(value: unknown): SceneComponentCaptureIdentityV1;
+export declare function completeSceneComponentCaptureIdentityV1(intent: SceneComponentCaptureIntentV1, attestation: SceneCaptureSessionAttestationV1): SceneComponentCaptureIdentityV1;
+export declare function canonicalSceneComponentCaptureIdentityV1(value: unknown): string;