@cueframe/kernel 0.2.1 → 0.2.3

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

@@ -0,0 +1,142 @@
+import { evaluateSceneSeparationV2, selectSceneBakeScale, type SceneObjectV2, type SceneChannelV2, type SceneShotSpecV2, type SceneSurfaceBindingV2, type SealedSceneShotPlanV1, type ScenePreparedFontFaceV1 } from '../../composition/scene/index.js';
+import type { SceneBuilderDescriptorRegistryV1, SceneBuilderDescriptorV1, SceneComponentCaptureIntentV1, SceneComponentCaptureDependencyV1, SceneCanonicalJson, SceneBuilderAllocationDescriptorV1, SceneExactRateV1 } from './types.js';
+import { type SceneVerifiedVideoFactsV1 } from '../../composition/scene/index.js';
+export type ScenePlanRefusalCode = 'scene_builder_descriptor_unavailable' | 'scene_builder_descriptor_invalid' | 'scene_component_facts_missing' | 'scene_component_capture_invalid' | 'scene_image_facts_missing' | 'scene_video_facts_missing' | 'scene_budget_exceeded' | 'scene_evaluated_value_invalid' | 'scene_plan_output_mismatch' | 'scene_reference_aspect_mismatch' | 'scene_brand_unresolved' | 'scene_material_role_unsupported' | 'scene_material_type_mismatch' | 'scene_font_unavailable';
+export declare class ScenePlanRefusal extends Error {
+    readonly code: ScenePlanRefusalCode;
+    readonly path: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+    constructor(code: ScenePlanRefusalCode, path: string, message: string, detail?: Readonly<Record<string, unknown>>);
+}
+export interface ScenePlanOutputV1 {
+    width: number;
+    height: number;
+    fps: SceneExactRateV1;
+    durationInFrames: number;
+}
+export interface SceneComponentPreparationFactsV1 {
+    durationInFrames: number;
+    runtimeIdentity: string;
+    dependencyIdentity: string;
+    seed: string;
+    params: SceneComponentCaptureIntentV1['params'];
+    assetBindings: SceneComponentCaptureIntentV1['assetBindings'];
+    brandFacts: SceneComponentCaptureIntentV1['brandFacts'];
+    fontFacts: SceneComponentCaptureIntentV1['fontFacts'];
+    mediaFacts: SceneComponentCaptureIntentV1['mediaFacts'];
+    requestedGlBackend: string;
+    rasterAffectingFlags: SceneComponentCaptureIntentV1['rasterAffectingFlags'];
+}
+export interface PreparedSceneSurfaceV1 {
+    path: string;
+    authoredObjectId: string;
+    slot: string;
+    binding: SceneSurfaceBindingV2;
+    descriptor: SceneBuilderDescriptorV1['surfaceSlots'][number];
+    captureIntent?: SceneComponentCaptureIntentV1;
+    bakeScale?: 2 | 3;
+    bakeScaleReason?: 'declared' | 'default-sufficient' | 'raised-by-resolution-check';
+    resolutionCheck?: ReturnType<typeof selectSceneBakeScale>;
+}
+export interface PreparedSceneObjectV1 {
+    authoredId: string;
+    parentId: string | null;
+    kind: SceneObjectV2['kind'];
+    builder: SceneBuilderDescriptorV1 | null;
+    parts: readonly {
+        id: string;
+        partId: string;
+        materialRole: string;
+        triangles: number;
+        mounted: boolean;
+    }[];
+}
+export interface PreparedSceneShotPreflightV1 {
+    version: 1;
+    scene: SceneShotSpecV2;
+    output: ScenePlanOutputV1;
+    cameraIdentity: {
+        position: readonly [number, number, number];
+        fov: number;
+        near: number;
+        far: number;
+    };
+    /** Serializable authored motion retained for frame evaluation; the final-frame hold is D-1. */
+    motion: {
+        channels: SceneChannelV2[];
+        contentDurationInFrames: number;
+        finalContentFrame: number;
+        cameraClipPlanes: readonly {
+            near: number;
+            far: number;
+        }[];
+    };
+    objects: PreparedSceneObjectV1[];
+    surfaces: PreparedSceneSurfaceV1[];
+    separation: ReturnType<typeof evaluateSceneSeparationV2>;
+    rigIdentity: SceneCanonicalJson;
+    rigAllocations: readonly SceneBuilderAllocationDescriptorV1[];
+    fonts: readonly ScenePreparedFontFaceV1[];
+}
+export interface SceneRigPreparationFactsV1 {
+    identity: SceneCanonicalJson;
+    allocations: readonly SceneBuilderAllocationDescriptorV1[];
+}
+export interface SceneShotWorldBoundsV1 {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    minZ: number;
+    maxZ: number;
+}
+export interface PrepareSceneShotPreflightArgsV1 {
+    authoredScene: unknown;
+    output: ScenePlanOutputV1;
+    descriptors: SceneBuilderDescriptorRegistryV1;
+    resolveComponentFacts?: (binding: Extract<SceneSurfaceBindingV2, {
+        source: 'component';
+    }>, path: string) => SceneComponentPreparationFactsV1 | null;
+    resolveCameraClipPlanes: (scene: SceneShotSpecV2, frame: number, durationInFrames: number) => {
+        near: number;
+        far: number;
+    };
+    resolveRigFacts: (scene: SceneShotSpecV2, worldBounds: SceneShotWorldBoundsV1) => SceneRigPreparationFactsV1 | null;
+    fonts?: readonly ScenePreparedFontFaceV1[];
+}
+export declare function prepareSceneShotPreflightV1(args: PrepareSceneShotPreflightArgsV1): PreparedSceneShotPreflightV1;
+export declare function assertScenePlanOutputV1(plan: Pick<PreparedSceneShotPreflightV1, 'output'>, requested: ScenePlanOutputV1): void;
+export interface SceneVerifiedImageV1 {
+    handle: string;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
+    byteLength: number;
+    width: number;
+    height: number;
+    decodedSha256: string;
+}
+export type { ScenePlanAllocationLedgerV1, SceneSealedSurfaceV1 as SealedSceneSurfaceV1, SealedSceneShotPlanV1 } from '../../composition/scene/index.js';
+export interface SceneVerifiedImageLeaseV1 {
+    image: SceneVerifiedImageV1;
+    release(): Promise<void>;
+}
+export interface SceneVerifiedVideoLeaseV1 {
+    video: SceneVerifiedVideoFactsV1;
+    release(): Promise<void>;
+}
+export interface RealizeSceneShotPlanDepsV1 {
+    capture: SceneComponentCaptureDependencyV1;
+    resolveImage: (binding: Extract<SceneSurfaceBindingV2, {
+        source: 'image';
+    }>, path: string) => Promise<SceneVerifiedImageLeaseV1 | null>;
+    resolveVideo?: (binding: Extract<SceneSurfaceBindingV2, {
+        source: 'video';
+    }>, path: string, signal?: AbortSignal) => Promise<SceneVerifiedVideoLeaseV1 | null>;
+    sha256(value: string): Promise<string>;
+    signal?: AbortSignal;
+}
+export interface SealedSceneShotPlanLeaseV1 {
+    plan: SealedSceneShotPlanV1;
+    /** Idempotently releases image handles and session leases after the consuming render ends. */
+    cleanup(): Promise<void>;
+}
+export declare function realizeSceneShotPlanV1(preflight: PreparedSceneShotPreflightV1, deps: RealizeSceneShotPlanDepsV1): Promise<SealedSceneShotPlanLeaseV1>;

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

@@ -0,0 +1,57 @@
+import { type SceneShotSpecV2, type SceneSourceResolver, type ScenePreparedFontFaceV1 } from '../../composition/scene/index.js';
+import type { Composition } from '../../composition/validators/index.js';
+import { type PrepareSceneShotPreflightArgsV1, type RealizeSceneShotPlanDepsV1, type SceneComponentPreparationFactsV1 } from './sceneShotPlan.js';
+import type { CompositionOverlay, RenderInput } from './types.js';
+export declare const SCENE_SHOT_PREPARATION_STAGE: "preparation";
+export declare const SCENE_SHOT_PARAM: "scene";
+export declare const SCENE_SHOT_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+export declare const SCENE_SHOT_VIDEO_MIME_TYPES: readonly ["video/mp4", "video/webm"];
+export interface SceneShotPreparationLocator {
+    stage: typeof SCENE_SHOT_PREPARATION_STAGE;
+    clipId: string;
+    componentId?: string;
+    path: string;
+}
+export declare function readSceneShotManifest(manifest: unknown, context: {
+    clipId: string;
+    componentId?: string;
+}): {
+    version: 2;
+    api: 'webgl';
+    assets: Record<string, unknown>;
+} | null;
+export declare function sceneSourceResolverForPinnedRows(rows: NonNullable<RenderInput['componentSources']>): SceneSourceResolver;
+export declare function assertSceneClipShapes(composition: Composition, context: {
+    fps: number;
+    resolveSource: SceneSourceResolver;
+}): void;
+export interface ResolvedScenePreparationFactsV1 {
+    scene: SceneShotSpecV2;
+    componentFactsByPath: Readonly<Record<string, SceneComponentPreparationFactsV1>>;
+    fonts: readonly ScenePreparedFontFaceV1[];
+}
+/** Resolves only schema-declared brand sites and seals exact outer text faces from host bytes. */
+export declare function resolvePinnedSceneFactsV1(authored: SceneShotSpecV2, context: {
+    input: RenderInput;
+    overlay: CompositionOverlay;
+}, componentFactsByPath?: Readonly<Record<string, SceneComponentPreparationFactsV1>>): ResolvedScenePreparationFactsV1;
+export interface SceneShotPreparationDependenciesV1 {
+    descriptors: PrepareSceneShotPreflightArgsV1['descriptors'];
+    resolveComponentFacts?(scene: SceneShotSpecV2, context: {
+        input: RenderInput;
+        overlay: CompositionOverlay;
+    }): Promise<Readonly<Record<string, SceneComponentPreparationFactsV1>>>;
+    componentFactsByPath?: Readonly<Record<string, SceneComponentPreparationFactsV1>>;
+    resolveRigFacts: PrepareSceneShotPreflightArgsV1['resolveRigFacts'];
+    resolveCameraClipPlanes: PrepareSceneShotPreflightArgsV1['resolveCameraClipPlanes'];
+    realization: RealizeSceneShotPlanDepsV1;
+    realizationForOverlay?(context: {
+        input: RenderInput;
+        overlay: CompositionOverlay;
+    }): RealizeSceneShotPlanDepsV1;
+}
+export interface PreparedRenderInputLeaseV1 {
+    input: RenderInput;
+    cleanup(): Promise<void>;
+}
+export declare function prepareSceneShotRenderInput(input: RenderInput, dependencies: SceneShotPreparationDependenciesV1): Promise<PreparedRenderInputLeaseV1>;

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

@@ -0,0 +1,21 @@
+import { type SceneObjectV2, type SceneSlabV2 } from '../../composition/scene/index.js';
+import type { SceneBuilderAllocationDescriptorV1, SceneBuilderDescriptorRegistryV1, SceneBuilderDescriptorV1 } from './types.js';
+/** The production builder mounts the unlit content face this many reference pixels past +t/2. */
+export declare const SCENE_SLAB_CONTENT_OFFSET_V1 = 0.6;
+export declare function sceneSlabBuilderDescriptorV1(slab: SceneSlabV2, allocations: readonly SceneBuilderAllocationDescriptorV1[], measuredBodyTriangles: number): SceneBuilderDescriptorV1;
+/** W4 supports the already-built slab. Every other preset remains an explicit W5 descriptor gap. */
+export declare function createSceneSlabDescriptorRegistryV1(factsFor: (slab: SceneSlabV2) => {
+    allocations: readonly SceneBuilderAllocationDescriptorV1[];
+    measuredBodyTriangles: number;
+}): SceneBuilderDescriptorRegistryV1;
+/** Registry seam whose production supplier constructs and measures every supported preset. */
+export declare function createSceneBuilderDescriptorRegistryV1(resolveDescriptor: (object: SceneObjectV2, context?: {
+    referenceSize: {
+        width: number;
+        height: number;
+    };
+    output: {
+        width: number;
+        height: number;
+    };
+}) => SceneBuilderDescriptorV1 | null): SceneBuilderDescriptorRegistryV1;

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

@@ -0,0 +1,33 @@
+/**
+ * Per-track projection: turning one `Track` of the wire composition into the render input's
+ * clips, overlays, audio tracks and effects.
+ *
+ * Split out of `compositionRender.ts`, which now holds only the whole-composition assembly that
+ * calls these — the format table, the merged caption-face guard, `compositionToRenderInput` and
+ * `assembleRenderInput`. The projectors are a closed set with their own shared vocabulary (the
+ * frame lattice, the visual identity, the src-url resolution, the overlay transition fields), and
+ * that vocabulary is private to them: nothing outside this file needs `timelineSpanFrames` or
+ * `overlayTransitionFields`, and every one of them wants all of it. This is a move, not a rewrite:
+ * the projections, the refusals and their paths are unchanged.
+ */
+import type { Track, TimelineClip as WireClip } from "../../composition/validators/index.js";
+import type { CompositionAudioTrack, CompositionClip, CompositionEffect, CompositionOverlay } from "./types.js";
+import type { TrajectoryData } from "../../composition/reframe/trajectory.js";
+export declare function playableSpans(trimStart: number, trimEnd: number, excluded: Array<{
+    start: number;
+    end: number;
+}> | undefined): Array<{
+    start: number;
+    end: number;
+}>;
+export declare function projectMediaTrack(track: Track, trackIndex: number, trackCount: number, fps: number, srcUrls: Record<string, string>, trajectoryUrls?: Record<string, string>, coViewUrls?: Record<string, string>, trajectories?: Record<string, TrajectoryData>): {
+    clips: CompositionClip[];
+    audio: CompositionAudioTrack[];
+    effects: CompositionEffect[];
+};
+export declare function projectImageTrack(track: Track, trackIndex: number, trackCount: number, fps: number, srcUrls: Record<string, string>): {
+    clips: CompositionClip[];
+    effects: CompositionEffect[];
+};
+export declare function projectOverlayTrack(track: Track, trackIndex: number, trackCount: number, fps: number, alphaUrls?: Record<string, string>, isSceneClip?: (clip: WireClip) => boolean): CompositionOverlay[];
+export declare function projectEffectTrack(track: Track, trackIndex: number, trackCount: number, fps: number): CompositionEffect[];

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

@@ -1,6 +1,8 @@
 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 { SceneBuilderDescriptorV1, SceneExactRateV1, SceneObjectV2, ScenePreparedJson, SealedSceneShotPlanV1 } from '../../composition/scene/index.js';
+export type { SceneBuilderAllocationDescriptorV1, SceneBuilderDescriptorV1, SceneBuilderPartDescriptorV1, SceneBuilderSlotDescriptorV1, SceneExactRateV1, } from '../../composition/scene/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 & {});
@@ -76,6 +78,39 @@ export interface CompositionClip extends ProjectedVisualIdentity {
     packedUrl?: string;
     coViewDebug?: boolean;
 }
+/** One text face a scene shot uses, sealed at preparation: family, weight and style are exact. */
+export interface SceneShotSealedFontFace {
+    family: string;
+    weight: number;
+    style: 'normal' | 'italic';
+    /** The sealed font asset of a custom (brand) face; vendored faces carry none. */
+    url?: string;
+    /** Scene paths of the text layers that use the face (`layers.N`). */
+    paths: string[];
+}
+/** The admitted image bound to one scene slot, by content facts only; the handle stays on `componentSources`. */
+export interface SceneShotSlotBindingV1 {
+    mimeType: string;
+    width: number;
+    height: number;
+    /** Scene paths that reference the slot (`layers.N.screen`, `layers.N.image`). */
+    paths: string[];
+}
+/**
+ * The internal scene marker preparation sets on a projected component overlay whose pinned source
+ * declares `sceneShot: { version: 2 }`. It carries the resolved runtime scene (brand references
+ * already resolved), the sealed faces, the slot bindings, the source identity and the seed. Root
+ * consumes it only when it agrees with the pinned source manifest; the browser never re-resolves.
+ */
+export interface SceneShotOverlayMarkerV1 {
+    version: 1;
+    authoredSceneVersion: 2;
+    componentId: string;
+    sourceVersionId: string;
+    sealSha256: string;
+    contentDurationInFrames: number;
+    plan: SealedSceneShotPlanV1;
+}
 export interface CompositionOverlay extends ProjectedVisualIdentity {
     id: string;
     template: OverlayTemplate;
@@ -83,6 +118,13 @@ export interface CompositionOverlay extends ProjectedVisualIdentity {
     startFrame: number;
     durationInFrames: number;
     params: OverlayParams;
+    componentId?: string;
+    sourceVersionId?: string;
+    /** Host-owned deterministic seed, kept outside component params and prepared scene seals. */
+    renderSeed?: string;
+    componentAssets?: Record<string, unknown>;
+    /** Set by scene preparation for scene-shot sources; absent on every other overlay. */
+    sceneShot?: SceneShotOverlayMarkerV1;
     zPlane?: 'front' | 'behind-subject';
     /** Canonical packed clip that owns a behind-subject overlay. */
     hostClipId?: string;
@@ -150,6 +192,8 @@ export interface RenderInput {
     width: number;
     height: number;
     fps: number;
+    /** Authoritative exact rate transport; required for non-integer scene-shot outputs. */
+    fpsRational?: SceneExactRateV1;
     durationInFrames: number;
     platform?: string;
     outputWidth?: number;
@@ -157,4 +201,102 @@ export interface RenderInput {
     crf?: number;
     watermark?: boolean;
     brandKit?: ResolvedBrandKit;
+    componentSources?: Record<string, {
+        sourceVersionId: string;
+        source: {
+            version: 2;
+            componentId: string;
+            tsxSource: string;
+            manifest: unknown;
+        };
+        assets: Record<string, {
+            handle: string;
+            kind: 'image' | 'video' | 'audio' | 'data';
+            mimeType: string;
+            width?: number;
+            height?: number;
+            durationSec?: number;
+            frameRate?: number;
+        }>;
+    }>;
+}
+export type SceneCanonicalJson = ScenePreparedJson;
+/** Facts known before a browser is admitted. Actual host facts are deliberately absent. */
+export interface SceneComponentCaptureIntentV1 {
+    componentId: string;
+    sourceVersionId: string;
+    params: SceneCanonicalJson;
+    assetBindings: SceneCanonicalJson;
+    layoutWidth: number;
+    layoutHeight: number;
+    bakeScale: 2 | 3;
+    captureFrame: number;
+    durationInFrames: number;
+    fps: SceneExactRateV1;
+    seed: string;
+    brandFacts: SceneCanonicalJson;
+    fontFacts: SceneCanonicalJson;
+    mediaFacts: SceneCanonicalJson;
+    rasterWidth: number;
+    rasterHeight: number;
+    /** Expected actual page DPR for this capture; verified against the session observation. */
+    expectedDeviceScaleFactor: 2 | 3;
+    runtimeIdentity: string;
+    dependencyIdentity: string;
+    requestedGlBackend: string;
+    rasterAffectingFlags: SceneCanonicalJson;
+}
+/** Observations from the exact admitted browser session that performs the capture. */
+export interface SceneCaptureSessionAttestationV1 {
+    /** Loaded receipts checked against the declarative intent before identity completion. */
+    loadedRuntimeIdentity: string;
+    loadedDependencyIdentity: string;
+    observedRasterAffectingFlags: SceneCanonicalJson;
+    browserProduct: string;
+    browserVersion: string;
+    browserExecutableSha256: string;
+    headless: boolean;
+    os: string;
+    arch: string;
+    deviceScaleFactor: number;
+    colorProfile: string;
+    actualGlBackend: string;
+    actualRenderer: string;
+    /** Null means the admitted session could not resolve an effective GPU identity. */
+    gpuIdentity: string | null;
+}
+export interface SceneVerifiedPngV1 {
+    handle: string;
+    mimeType: 'image/png';
+    byteLength: number;
+    width: number;
+    height: number;
+    decodedSha256: string;
+}
+export interface SceneComponentCaptureResultV1 {
+    attestation: SceneCaptureSessionAttestationV1;
+    png: SceneVerifiedPngV1;
+    cacheScope: 'session';
+}
+export interface SceneComponentCaptureSessionV1 {
+    capture(intent: SceneComponentCaptureIntentV1, signal?: AbortSignal): Promise<SceneComponentCaptureResultV1>;
+    close(): Promise<void>;
+}
+export interface SceneComponentCaptureDependencyV1 {
+    /** Resolve verified/pinned declarative execution facts before launch; contains no host observations. */
+    resolveExecutionFacts(source: Pick<SceneComponentCaptureIntentV1, 'componentId' | 'sourceVersionId'>, signal?: AbortSignal): Promise<Pick<SceneComponentCaptureIntentV1, 'runtimeIdentity' | 'dependencyIdentity' | 'requestedGlBackend' | 'rasterAffectingFlags'>>;
+    openSession(intent: SceneComponentCaptureIntentV1, signal?: AbortSignal): Promise<SceneComponentCaptureSessionV1>;
+}
+export interface SceneBuilderDescriptorRegistryV1 {
+    /** The resolver must return the same kind and facts derived from this fully parsed object state. */
+    resolve(object: SceneObjectV2, context?: {
+        referenceSize: {
+            width: number;
+            height: number;
+        };
+        output: {
+            width: number;
+            height: number;
+        };
+    }): SceneBuilderDescriptorV1 | null;
 }

package/dist/_members/errors/registry.d.ts

@@ -457,6 +457,12 @@ export declare const ERROR_CODES: {
         readonly retryable: false;
         readonly httpStatus: 409;
     };
+    readonly component_scene_invalid: {
+        readonly stage: "validate";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 422;
+    };
     readonly motion_preset_unknown: {
         readonly stage: "validate";
         readonly category: "authoring";

package/dist/_members/mcp/adapter.d.ts

@@ -35,6 +35,11 @@ export type AdapterProgressEvent = {
 };
 export type OnProgressCallback = (event: AdapterProgressEvent) => void;
 export interface CuratedToolSetOpts {
+    /** Preserve local wire errors (including concurrency receipts) in desktop clients. */
+    errorFormat?: (response: {
+        status: number;
+        text: string;
+    }) => string;
     allowedNames: readonly string[];
     /**
      * Execution-surface variants for a curated tool. The public MCP surface uses

package/dist/_members/mcp/generated/sceneContract.d.ts

@@ -0,0 +1,155 @@
+/**
+ * AUTO-GENERATED — do not edit by hand.
+ *
+ * Sources: packages/composition/src/scene/generated/schema.json (the canonical SceneShotSpecV2
+ * JSON schema, itself generated from packages/composition/src/scene/schema.ts), the agent-facing
+ * description vendored with it at api/openapi.json#/components/schemas/SceneShotSpecV2, and
+ * SCENE_SHOT_EXAMPLES from packages/composition/src/scene/examples.ts.
+ * Generator: packages/mcp/scripts/generate-scene-contract.ts
+ * Re-run: `pnpm generate:api-consumers` from the repo root.
+ *
+ * `@cueframe/mcp` cannot depend on `@cueframe/composition`, so the scene contract is copied here
+ * rather than imported — by a generator, gated by `pnpm check:api-consumer-drift`, so the copy
+ * cannot drift silently. The schema below is the canonical document byte-for-byte, plus the
+ * `description` annotation the public contract carries for it; nothing is weakened or restated.
+ */
+/** The canonical SceneShotSpecV2 JSON schema, served verbatim at `cueframe://scene-shot`. */
+export declare const SCENE_SHOT_SCHEMA: Readonly<Record<string, unknown>>;
+/** Agent-facing prose kept outside the canonical schema document. */
+export declare const SCENE_SHOT_SCHEMA_DESCRIPTION = "A version-2 scene shot: a self-contained 3D world-object shot that scene.add / scene.update materializes into an ordinary component clip. The shot owns its layers, camera, lighting, backdrop and normalized local animation; the composition owns start, duration, ordering, cuts and transitions. Coordinates are REFERENCE PIXELS: origin at frame centre, +X right, +Y down, +Z toward the viewer. referenceSize must have the SAME aspect ratio as the composition format; mismatch fails instead of cropping. At equal aspect ratio the shot scales uniformly by outputWidth/referenceWidth. A segment's easing belongs to the keyframe it ARRIVES at; the first keyframe has no easing. Authoring limits: 32 layers, 4 devices, 16 distinct image slots, 256 keyframes per channel, 2048 keyframes per shot. Version 2 supports nested groups, procedural slab/page/phone/laptop objects, screen- and world-space text, admitted image/component/video surfaces, fixed photographic and generated studio environments, transparent/solid/linear/radial backdrops, constraints, focus, grain and vignette. Raw HTML, custom shader props, imported GLB models, arbitrary external HDR environments, skeletal animation and physics are refused with an exact field path.";
+/** What each shot in the published example demonstrates, per clip. */
+export declare const SCENE_SHOT_EXAMPLE_SHOTS: readonly [{
+    readonly clipId: "shot-world-objects";
+    readonly exampleId: "world-objects";
+    readonly title: "World objects";
+    readonly summary: "Nested satin card and fitted page.";
+    readonly slots: readonly ["page"];
+}];
+/**
+ * A complete `apply_composition` body: one slab-heavy nested world-object shot on a dedicated
+ * scene track, followed by a revision that changes its admitted page asset and duration. The
+ * `scene` payload is the canonical example verbatim.
+ */
+export declare const SCENE_SHOT_WORLD_OBJECT_BODY: {
+    readonly ops: readonly [{
+        readonly type: "scene.add";
+        readonly clipId: "shot-world-objects";
+        readonly newTrack: true;
+        readonly startTime: 0;
+        readonly duration: 6;
+        readonly scene: {
+            readonly version: 2;
+            readonly referenceSize: {
+                readonly width: 1920;
+                readonly height: 1080;
+            };
+            readonly environment: {
+                readonly kind: "photographic-studio-v1";
+            };
+            readonly backdrop: {
+                readonly kind: "solid";
+                readonly color: "$brand:colors.background";
+            };
+            readonly layers: readonly [{
+                readonly kind: "group";
+                readonly id: "cards";
+                readonly transform: {
+                    readonly position: readonly [0, 0, 0];
+                    readonly rotation: readonly [0, 0, 0];
+                    readonly scale: 1;
+                };
+                readonly opacity: 1;
+                readonly children: readonly [{
+                    readonly kind: "slab";
+                    readonly id: "hero";
+                    readonly transform: {
+                        readonly position: readonly [0, 0, 0];
+                        readonly rotation: readonly [0, 0, 0];
+                        readonly scale: 1;
+                    };
+                    readonly opacity: 1;
+                    readonly width: 720;
+                    readonly height: 900;
+                    readonly thickness: 32;
+                    readonly cornerRadius: 32;
+                    readonly edgeRadius: 15;
+                    readonly finish: "satin";
+                    readonly surfaces: {
+                        readonly front: {
+                            readonly source: "component";
+                            readonly component: {
+                                readonly version: 1;
+                                readonly componentId: "hero-card";
+                                readonly sourceVersionId: "0000000000000000000000000000000000000000000000000000000000000000";
+                            };
+                            readonly captureFrame: 12;
+                            readonly layout: {
+                                readonly width: 720;
+                                readonly height: 900;
+                            };
+                        };
+                    };
+                }, {
+                    readonly kind: "page";
+                    readonly id: "page";
+                    readonly transform: {
+                        readonly position: readonly [760, 0, -20];
+                        readonly rotation: readonly [0, 0, 0];
+                        readonly scale: 1;
+                    };
+                    readonly opacity: 1;
+                    readonly width: 640;
+                    readonly height: 800;
+                    readonly fit: "contain";
+                    readonly transparency: "straight";
+                    readonly depthWrite: true;
+                    readonly backface: "hidden";
+                    readonly surfaces: {
+                        readonly content: {
+                            readonly source: "image";
+                            readonly assetSlot: "page";
+                        };
+                    };
+                }];
+            }];
+            readonly animation: readonly [{
+                readonly target: {
+                    readonly kind: "layer";
+                    readonly layerId: "cards";
+                };
+                readonly property: "rotationY";
+                readonly keyframes: readonly [{
+                    readonly at: 0;
+                    readonly value: 0;
+                }, {
+                    readonly at: 1;
+                    readonly value: 18.84955592153876;
+                    readonly easing: {
+                        readonly kind: "linear";
+                    };
+                }];
+            }];
+            readonly post: {
+                readonly grain: 0;
+                readonly vignette: 0;
+                readonly focus: null;
+            };
+            readonly constraints: readonly [];
+            readonly camera: {
+                readonly position: readonly [0, 0, 1483.6378065054962];
+                readonly rotation: readonly [0, 0, 0];
+                readonly fov: 0.6981317007977318;
+            };
+        };
+        readonly assets: {
+            readonly page: "<landingPageScreenshotMediaId>";
+        };
+    }, {
+        readonly type: "scene.update";
+        readonly clipId: "shot-world-objects";
+        readonly duration: 7;
+        readonly assets: {
+            readonly page: "<updatedLandingPageScreenshotMediaId>";
+        };
+    }];
+};

package/dist/_members/mcp/sceneShot.d.ts

@@ -0,0 +1,38 @@
+export declare const SCENE_SHOT_RESOURCE_URI = "cueframe://scene-shot";
+export declare const SCENE_SHOT_RESOURCE_DESCRIPTION: string;
+/** The V2 capability envelope, stated as the two lists an agent has to act on. */
+export declare const SCENE_SHOT_LIMITS: {
+    readonly supported: readonly ["nested groups and procedural slab, page, phone and laptop world objects", "admitted PNG/JPEG/WebP images, captured components and frame-addressed video surfaces", "procedural phone and laptop devices, with a laptop open angle in [0,180] degrees", "typed text in screen space or world space, with per-run colours for two-colour type", "one camera and either generated studio lighting or the fixed photographic studio environment", "a transparent, solid, linear-gradient or radial-gradient backdrop", "world-space focus, grain and vignette", "JSON numeric animation channels over camera, layer transform/opacity, laptop openAngle, environment intensity and focus"];
+    readonly notSupportedInV2: readonly ["raw HTML in a shot — a page is an ADMITTED SCREENSHOT; live HTML is never rasterized or injected", "custom shader props — no shader source enters through the scene spec", "imported models (GLB and friends) — devices are procedural only", "arbitrary external HDR environments — use the admitted fixed photographic rig or generated studio", "skeletal animation and physics", "animating topology, asset bindings, text content, font properties, device kind or colours — those are static within a shot; author a revised spec instead", "source trim/slip of generated animation — a resized clip resamples the same normalized channels"];
+    readonly authoringLimits: {
+        readonly layers: 32;
+        readonly devices: 4;
+        readonly distinctImageSlots: 16;
+        readonly keyframesPerChannel: 256;
+        readonly keyframesPerShot: 2048;
+        readonly note: "Oversized resources are refused with a path and a corrective message; nothing is silently resized to fit a budget.";
+    };
+};
+/** The behaviours agents most often get wrong, each phrased as the rule that fails the request. */
+export declare const SCENE_SHOT_RULES: {
+    readonly imageFormats: string;
+    readonly referenceAspect: string;
+    readonly screenVersusWorldText: string;
+    readonly lightingAndColour: string;
+    readonly timelineOwnership: string;
+    readonly animationEasing: string;
+    readonly focusIsPerPixelDepth: string;
+    readonly globalEffectScopeGap: string;
+    readonly catalogDiscovery: string;
+    readonly brandTokens: string;
+    readonly failures: string;
+};
+/**
+ * Every `$brand:` token the scene schema admits, grouped by family, read straight out of the
+ * SERVED schema's enums — i.e. out of the canonical `scene/schema.json` this resource carries.
+ * Never hand-listed: the composition contract's exported token constants are the source, and they
+ * reach here through schema.ts → schema.json → the generated copy in `./generated/sceneContract`.
+ */
+export declare function sceneBrandTokens(schema: unknown): Record<string, string[]>;
+/** The full discovery document served at `cueframe://scene-shot`. */
+export declare function sceneShotContract(): Record<string, unknown>;