@cueframe/kernel 0.2.2 → 0.2.3

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

@@ -0,0 +1,119 @@
+/**
+ * The pure shape rules a scene-shot clip must satisfy inside a persisted composition.
+ *
+ * These are properties of the persisted contract — the scene spec plus the timeline clip that
+ * carries it — so they live next to the contract itself rather than in an authoring package. Both
+ * the authoring surface (`@cueframe/authoring/scene`, which re-exports every symbol here and adds
+ * the `scene.add` / `scene.update` request validation on top) and the render path
+ * (`@cueframe/core`'s `assembleRenderInput`, which refuses a malformed scene clip before it
+ * projects or seals anything) run exactly this implementation. There is no second copy.
+ *
+ * Nothing here reaches a host: the caller supplies the frame rate, a source resolver over its
+ * component store, and optionally the media kinds it knows. The validator imports are types only,
+ * so this module adds no runtime edge from `scene` to `validators`.
+ */
+import type { Composition, Gap, TimelineClip, Track } from '../validators/composition.js';
+import { type SceneShotSpecV2 } from './schema.js';
+export type SceneClipIssueCode = 'validation_error' | 'invalid_composition';
+/** One rejection: a path into the clip (or request) and an actionable detail. */
+export interface SceneClipRuleIssue {
+    path: string;
+    detail: string;
+    code: SceneClipIssueCode;
+}
+/** The part of a registered component source these rules read: its immutable manifest. */
+export interface SceneSourceDeclaration {
+    componentId: string;
+    manifest: {
+        version?: number;
+        assets: Record<string, {
+            kind: string;
+            required: boolean;
+            mimeTypes?: string[];
+        }>;
+        graphics: {
+            api: string;
+            required?: boolean;
+            accelerationPreference?: string;
+        };
+        alphaPolicy: string;
+        sceneShot?: {
+            version: number;
+        };
+    };
+}
+export type SceneSourceResolver = (componentId: string, sourceVersionId: string) => SceneSourceDeclaration | null | undefined;
+export declare function isSceneShotSource(declaration: SceneSourceDeclaration | null | undefined): declaration is SceneSourceDeclaration;
+/** `props.componentRef` as the component runtime pins it, or null. */
+export declare function readSceneSourceRef(props: Record<string, unknown>): {
+    sourceVersionId: string;
+} | null;
+export type SceneShotClip = TimelineClip & {
+    source: Extract<TimelineClip['source'], {
+        kind: 'component';
+    }>;
+};
+export declare function isTimelineClip(content: TimelineClip | Gap): content is TimelineClip;
+/**
+ * A clip is a scene shot when its pinned `props.componentRef` resolves to a source whose manifest
+ * declares `sceneShot: { version: 2 }` with `graphics.api: 'webgl'` — an admitted source
+ * declaration, never a caller label or a loose props shape.
+ */
+export declare function isSceneShotClip(content: TimelineClip | Gap, resolveSource: SceneSourceResolver): content is SceneShotClip;
+export interface SceneClipRuleContext {
+    /** Composition frame rate; clip timing must sit on its frame lattice. */
+    fps: number;
+    resolveSource: SceneSourceResolver;
+    /** When supplied, bound media must exist here and be `image`. */
+    mediaKindById?: Record<string, string>;
+}
+/** True when `seconds` is not a whole number of frames at `fps`. */
+export declare function offFrameLattice(seconds: number, fps: number): boolean;
+/** Transition kinds v1 accepts on a scene clip; fade validity is checked by the timeline stage. */
+export declare const SCENE_TRANSITION_KINDS: readonly ["cut", "fade"];
+/**
+ * A scene clip's boundary duration, on the lattice and long enough to be a boundary.
+ *
+ * Projection turns `transitionIn.duration` into frames with `Math.max(1, Math.round(d * fps))`.
+ * The floor and the rounding are both silent, and the render lane reads a fade of one frame as a
+ * cut, so without this an authored 0.01 s fade at 30 fps would quantize to zero frames, be lifted
+ * to one, and disappear into a cut with nothing said — exactly the silent no-op
+ * §"Failure reporting" forbids. Refusing here is what makes the lane's own zero-frame refusal
+ * reachable from an authored composition rather than from unit tests alone.
+ */
+export declare function sceneTransitionDurationIssues(transition: {
+    type: string;
+    duration: number;
+}, fps: number): SceneClipRuleIssue[];
+/**
+ * Parses a scene spec, reporting its zod issues under `path` rather than throwing, so a caller can
+ * merge them with the other clip rules and report the first one.
+ */
+export declare function sceneSpecIssues(value: unknown, path: string): {
+    spec: SceneShotSpecV2;
+    issues: SceneClipRuleIssue[];
+};
+/**
+ * The outer-clip rules every scene clip must satisfy, whether it arrives through
+ * `scene.add`/`scene.update` or through a generic clip op: front depth, full-frame placement,
+ * no outer effects or transform animation, one boundary owner, cut/fade only, frame-lattice
+ * timing, and bindings that match the referenced slots.
+ */
+export declare function sceneClipShapeIssues(clip: TimelineClip, ctx: Pick<SceneClipRuleContext, 'fps' | 'mediaKindById'>, options?: {
+    checkMedia?: boolean;
+}): SceneClipRuleIssue[];
+export declare function sceneClipOverlapIssue(clip: TimelineClip, track: Track): SceneClipRuleIssue | null;
+export declare function sceneDedicatedTrackIssue(track: Track, resolveSource: SceneSourceResolver, path: string): SceneClipRuleIssue | null;
+export interface SceneClipIssue {
+    clipId: string;
+    path: string;
+    message: string;
+}
+/**
+ * Every rule above, applied to the persisted composition: a generic `clip.update`,
+ * `moveClipToTrack` or `clip.add` cannot leave a scene clip off the front plane, off the
+ * frame lattice, with outer transforms/effects, competing boundary owners, stale bindings,
+ * or sharing its dedicated track with a generic clip. Tracks without scene shots are not
+ * restricted.
+ */
+export declare function collectSceneClipIssues(composition: Composition, ctx: SceneClipRuleContext): SceneClipIssue[];

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

@@ -0,0 +1,61 @@
+/**
+ * Pure evaluation of authored min-separation constraints.
+ *
+ * W4 preparation supplies one conservative local oriented bound for each named authored object
+ * at every content frame. A compound preset is deliberately one body here: internal builder parts
+ * never compete with each other. This module derives no builder geometry and owns no sampling
+ * schedule; it only evaluates the complete frame set supplied by preparation.
+ */
+import type { SceneConstraintV2, SceneTransformV2, SceneVec3 } from './schema.js';
+export interface SceneLocalBoundsV2 {
+    /** Centre in the authored object's local coordinates. */
+    center: SceneVec3;
+    /** Non-negative half-extents. One or two zero axes represent planar or linear geometry. */
+    halfExtents: SceneVec3;
+}
+export interface SceneConstraintBodyV2 {
+    bounds: SceneLocalBoundsV2;
+    /**
+     * Outermost parent first and the named object's own transform last.
+     * Opacity is carried for evidence but never filters constraint participation.
+     */
+    transforms: readonly SceneTransformV2[];
+    opacity: number;
+}
+export interface SceneConstraintFrameV2 {
+    /** Requested content frame, after the shot's existing hold policy. */
+    frame: number;
+    resolveBody: (authoredId: string) => SceneConstraintBodyV2 | null | undefined;
+}
+export interface SceneOrientedBoundsV2 {
+    center: SceneVec3;
+    axes: readonly [SceneVec3, SceneVec3, SceneVec3];
+    halfExtents: SceneVec3;
+}
+export interface SceneSeparationPairResultV2 {
+    constraintIndex: number;
+    frame: number;
+    objects: readonly [string, string];
+    /** Best separating-axis gap in reference pixels. This is not Euclidean mesh distance. */
+    separatingAxisGap: number;
+    requiredGap: number;
+}
+export interface SceneSeparationResultV2 {
+    pairs: SceneSeparationPairResultV2[];
+}
+export type SceneConstraintRefusalCode = 'scene_constraint_frames_missing' | 'scene_constraint_bounds_missing' | 'scene_constraint_bounds_invalid' | 'scene_min_separation_violated';
+export declare class SceneConstraintRefusal extends Error {
+    readonly code: SceneConstraintRefusalCode;
+    readonly path: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+    constructor(code: SceneConstraintRefusalCode, path: string, message: string, detail: Readonly<Record<string, unknown>>);
+}
+/** Columns of Three's authored Euler order Rx · Ry · Rz, with angles already in radians. */
+export declare function sceneRotationAxesV2(rotation: SceneVec3): readonly [SceneVec3, SceneVec3, SceneVec3];
+export declare function sceneOrientedBoundsV2(body: SceneConstraintBodyV2, path?: string): SceneOrientedBoundsV2;
+/**
+ * Best gap over the 15 separating axes: three face axes from each box and nine edge cross axes.
+ * Positive is separated, zero is touching and negative is penetration.
+ */
+export declare function sceneSeparatingAxisGapV2(a: SceneOrientedBoundsV2, b: SceneOrientedBoundsV2): number;
+export declare function evaluateSceneSeparationV2(constraints: readonly SceneConstraintV2[], frames: readonly SceneConstraintFrameV2[]): SceneSeparationResultV2;

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

@@ -0,0 +1,21 @@
+import type { SceneLaptopV2, SceneVec3 } from './schema.js';
+export interface SceneDeviceDimensionsV1 {
+    w: number;
+    h: number;
+    t: number;
+    d: number;
+    screenInset: number;
+    radius: number;
+}
+export interface SceneLaptopLayoutV1 {
+    baseY: number;
+    hingeFromBaseY: number;
+    hingeZ: number;
+    hingeY: number;
+    lidCentreY: number;
+    bottomY: number;
+}
+export declare function sceneDeviceDimensionsV1(kind: 'laptop' | 'phone', width: number): SceneDeviceDimensionsV1;
+export declare function sceneLaptopLayoutV1(dim: SceneDeviceDimensionsV1): SceneLaptopLayoutV1;
+export declare const SCENE_DEVICE_SCREEN_OFFSET_V1 = 0.6;
+export declare function sceneLaptopScreenQuadV1(node: Pick<SceneLaptopV2, 'width' | 'openAngle'>): readonly [SceneVec3, SceneVec3, SceneVec3, SceneVec3];

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

@@ -0,0 +1,11 @@
+import { SceneShotSpecV2 } from './schema.js';
+export interface SceneShotExampleV2 {
+    id: string;
+    title: string;
+    summary: string;
+    slots: string[];
+    spec: SceneShotSpecV2;
+}
+export declare const SCENE_SHOT_EXAMPLES: readonly SceneShotExampleV2[];
+export declare const sceneShotExample: (id: string) => SceneShotExampleV2 | null;
+export declare function assertSceneShotExamplesValid(): void;

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

@@ -0,0 +1,11 @@
+export * from './schema.js';
+export * from './animation.js';
+export * from './clipRules.js';
+export * from './constraints.js';
+export * from './examples.js';
+export * from './budget.js';
+export * from './device.js';
+export * from './photographicRig.js';
+export * from './videoSchedule.js';
+export * from './resolution.js';
+export * from './preparedRender.js';

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

@@ -0,0 +1,242 @@
+import type { SceneBuilderAllocationDescriptorV1 } from "./preparedRender.js";
+export declare const PHOTOGRAPHIC_STUDIO_RIG_ID: "photographic-studio-v1";
+export declare const PHOTOGRAPHIC_STUDIO_HDRI_PATH = "environments/brown_photostudio_02.hdr";
+export declare const PHOTOGRAPHIC_STUDIO_HDRI_SHA256 = "469abc5e6035b6c450bae8adbb448f8d1fa7c51d9e384e501516c28352c91b58";
+export declare const PHOTOGRAPHIC_STUDIO_HDRI_BYTES = 1648130;
+export declare const PHOTOGRAPHIC_STUDIO_PMREM_VERSION = "three-0.183.2-fromEquirectangular-cubeuv256-v1";
+export declare const PHOTOGRAPHIC_STUDIO_LIGHTING_VERSION = 1;
+export declare const PHOTOGRAPHIC_STUDIO_EDGE_INTENSITY = 26;
+export declare const PHOTOGRAPHIC_STUDIO_EDGE_LIGHTS: readonly (readonly [number, number, number])[];
+export declare const PHOTOGRAPHIC_STUDIO_GPU_BYTES: Readonly<{
+    sourceRgba16f: number;
+    pmremTargetRgba16f: number;
+    pmremTransientRgba16f: number;
+    preparationPeak: number;
+    retained: number;
+}>;
+export declare const PHOTOGRAPHIC_STUDIO_RIG_FACTS: Readonly<{
+    rigId: "photographic-studio-v1";
+    hdri: Readonly<{
+        path: "environments/brown_photostudio_02.hdr";
+        sha256: "469abc5e6035b6c450bae8adbb448f8d1fa7c51d9e384e501516c28352c91b58";
+        bytes: 1648130;
+    }>;
+    pmremVersion: "three-0.183.2-fromEquirectangular-cubeuv256-v1";
+    lightingVersion: 1;
+    studioPreset: "soft";
+    hemisphere: Readonly<{
+        skyColor: "#ffffff";
+        groundColor: "#202024";
+        intensity: 0.7;
+    }>;
+    studioLights: readonly (Readonly<{
+        role: "key";
+        position: readonly [700, 1100, 1300];
+        intensity: 1.6;
+        castShadow: false;
+    }> | Readonly<{
+        role: "fill";
+        position: readonly [-1100, 400, 900];
+        intensity: 0.9;
+        castShadow: false;
+    }> | Readonly<{
+        role: "rim";
+        position: readonly [0, 1300, -1900];
+        intensity: 1;
+        castShadow: false;
+    }>)[];
+    edgeLights: readonly Readonly<{
+        position: readonly [number, number, number];
+        intensity: 26;
+        castShadow: false;
+    }>[];
+    environmentIntensity: 1;
+    floor: "none";
+    shadows: "none";
+    gpuBytes: Readonly<{
+        sourceRgba16f: number;
+        pmremTargetRgba16f: number;
+        pmremTransientRgba16f: number;
+        preparationPeak: number;
+        retained: number;
+    }>;
+}>;
+export declare function photographicStudioPreparationFactsV1(worldScale: number): {
+    identity: {
+        rigId: "photographic-studio-v1";
+        hdriSha256: "469abc5e6035b6c450bae8adbb448f8d1fa7c51d9e384e501516c28352c91b58";
+        pmremVersion: "three-0.183.2-fromEquirectangular-cubeuv256-v1";
+        lightingVersion: 1;
+        worldScale: number;
+        hemisphere: Readonly<{
+            skyColor: "#ffffff";
+            groundColor: "#202024";
+            intensity: 0.7;
+        }>;
+        lightLayout: readonly (Readonly<{
+            role: "key";
+            position: readonly [700, 1100, 1300];
+            intensity: 1.6;
+            castShadow: false;
+        }> | Readonly<{
+            role: "fill";
+            position: readonly [-1100, 400, 900];
+            intensity: 0.9;
+            castShadow: false;
+        }> | Readonly<{
+            role: "rim";
+            position: readonly [0, 1300, -1900];
+            intensity: 1;
+            castShadow: false;
+        }>)[];
+        edgeLightLayout: readonly Readonly<{
+            position: readonly [number, number, number];
+            intensity: 26;
+            castShadow: false;
+        }>[];
+        environmentIntensity: 1;
+        floor: "none";
+        shadows: "none";
+        retainedGpuBytes: number;
+        preparationPeakGpuBytes: number;
+    };
+    allocations: readonly [{
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "encoded-hdri";
+        readonly domain: "cpu";
+        readonly resource: "encoded-image";
+        readonly format: "rgbe";
+        readonly bytes: 1648130;
+        readonly lifetime: "preparation";
+    }, {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "encoded-hdri-working-copy";
+        readonly domain: "cpu";
+        readonly resource: "encoded-image";
+        readonly format: "rgbe";
+        readonly bytes: 1648130;
+        readonly lifetime: "preparation";
+    }, {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "decoded-hdri";
+        readonly domain: "cpu";
+        readonly resource: "decoded-image";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "preparation";
+    }, {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "rgbe-source";
+        readonly domain: "gl";
+        readonly resource: "pmrem-source";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "preparation";
+    }, {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "pmrem-transient";
+        readonly domain: "gl";
+        readonly resource: "pmrem-target";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "preparation";
+    }, {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "pmrem-environment";
+        readonly domain: "gl";
+        readonly resource: "pmrem-target";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "context";
+    }];
+};
+export declare function sceneFocusPreparationAllocationsV1(width: number, height: number, samples?: 4): readonly SceneBuilderAllocationDescriptorV1[];
+export declare function photographicSceneRigFactsV1(worldScale: number, width: number, height: number): {
+    identity: {
+        rigId: "photographic-studio-v1";
+        hdriSha256: "469abc5e6035b6c450bae8adbb448f8d1fa7c51d9e384e501516c28352c91b58";
+        pmremVersion: "three-0.183.2-fromEquirectangular-cubeuv256-v1";
+        lightingVersion: 1;
+        worldScale: number;
+        hemisphere: Readonly<{
+            skyColor: "#ffffff";
+            groundColor: "#202024";
+            intensity: 0.7;
+        }>;
+        lightLayout: readonly (Readonly<{
+            role: "key";
+            position: readonly [700, 1100, 1300];
+            intensity: 1.6;
+            castShadow: false;
+        }> | Readonly<{
+            role: "fill";
+            position: readonly [-1100, 400, 900];
+            intensity: 0.9;
+            castShadow: false;
+        }> | Readonly<{
+            role: "rim";
+            position: readonly [0, 1300, -1900];
+            intensity: 1;
+            castShadow: false;
+        }>)[];
+        edgeLightLayout: readonly Readonly<{
+            position: readonly [number, number, number];
+            intensity: 26;
+            castShadow: false;
+        }>[];
+        environmentIntensity: 1;
+        floor: "none";
+        shadows: "none";
+        retainedGpuBytes: number;
+        preparationPeakGpuBytes: number;
+    };
+    allocations: (SceneBuilderAllocationDescriptorV1 | {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "encoded-hdri";
+        readonly domain: "cpu";
+        readonly resource: "encoded-image";
+        readonly format: "rgbe";
+        readonly bytes: 1648130;
+        readonly lifetime: "preparation";
+    } | {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "encoded-hdri-working-copy";
+        readonly domain: "cpu";
+        readonly resource: "encoded-image";
+        readonly format: "rgbe";
+        readonly bytes: 1648130;
+        readonly lifetime: "preparation";
+    } | {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "decoded-hdri";
+        readonly domain: "cpu";
+        readonly resource: "decoded-image";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "preparation";
+    } | {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "rgbe-source";
+        readonly domain: "gl";
+        readonly resource: "pmrem-source";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "preparation";
+    } | {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "pmrem-transient";
+        readonly domain: "gl";
+        readonly resource: "pmrem-target";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "preparation";
+    } | {
+        readonly owner: "rig:photographic-studio-v1";
+        readonly name: "pmrem-environment";
+        readonly domain: "gl";
+        readonly resource: "pmrem-target";
+        readonly format: "rgba16f";
+        readonly bytes: number;
+        readonly lifetime: "context";
+    })[];
+};