@cueframe/kernel 0.2.1 → 0.2.3

package/dist/_members/animate/index.d.ts

@@ -17,7 +17,13 @@ export { Arrow, makeArrowPath } from './mobjects/Arrow.js';
 export { BrandBox } from './mobjects/BrandBox.js';
 export { Graph } from './mobjects/Graph.js';
 export { DiGraph } from './mobjects/DiGraph.js';
-export { ThreeCanvas } from './three/ThreeCanvas.js';
-export { Box, Sphere, Cylinder, Cone, Torus, TorusKnot, Plane, Circle, Ring, Dodecahedron, Icosahedron, Octahedron, Tetrahedron, Capsule, Extrude, Lathe, Tube, Text, Text3D, Center, Float, Environment, ContactShadows, AccumulativeShadows, RandomizedLight, Lightformer, Stage, Sky, Stars, Sparkles, Cloud, Line, QuadraticBezierLine, CubicBezierLine, CatmullRomLine, MeshDistortMaterial, MeshWobbleMaterial, MeshReflectorMaterial, MeshTransmissionMaterial, Edges, Outlines, GradientTexture, RoundedBox, Billboard, Html, PivotControls, Grid, Backdrop, } from './three/drei.js';
+export { ThreeCanvas, StageCameraRig, useImageTexture, StudioRig, DeviceMesh, deviceDimensions, laptopLayout, lidRotationX, DEVICE_GLASS_OPACITY_ENCODED, DEVICE_GLASS_OPACITY_LINEAR, DEVICE_LIT_MATERIALS, DEVICE_PLANE_OFFSETS, SELF_TONE_MAPPED, UNLIT_COLOUR_MANAGED, makeDefaultScreenTexture, defaultScreenLayout, STUDIO_EDGE_LIGHTS, STUDIO_EDGE_INTENSITY, studioEdgeLightCount, DEFAULT_LIGHTING_PROFILE, LIGHTING_PROFILES, studioShadowFrustum, type StudioRigProps, type DeviceKind, type DeviceMeshProps, type DeviceDimensions, type LaptopLayout, type ScreenLayout, type SceneLightingProfile, } from './three/index.js';
+export { solveFlex, flexReady, isFlexReady, leafIds, flexBoxToThree, fitBox, FlexLayout, useFlexReady, buildTree, unionTracks, weightsAt, type FlexCell, type FlexBox, type FlexSize, type FlexDir, type Fit, type FitMode, type FitResult, type FlexTrack, type FlexTrackSpec, type FlexLayoutProps, } from './layout/index.js';
+export * from './stage/index.js';
+export { MediaTileScene, mediaTileFramesReady, ImageTileScene, MEDIA_TILE_SCENE_LIMITS, assertMediaTileScene, mediaTileCropUvs, mediaTileFogDistances, type MediaTile, type MediaTileAsset, type MediaTileCamera, type MediaTileFog, type MediaTileSceneProps, type MediaTileStream, } from './media/MediaTileScene.js';
+export { SceneShotError, referenceScale, conjugateF, sceneWorldMatrix, sceneCssMatrix, sceneLayerPose, scaleSceneTransform, type SceneShotRender, type SceneShotErrorCode, type SceneFrameSize, type ThreeLayerPose, type SceneVec3, type SceneWorldTransform, } from './scene/index.js';
+export { SceneShotV2, backdropStyleV2, resolveSceneAssetsV2, sceneShadowBoundsV2, PreparedSceneShotV1, PreparedSceneShotError, SceneVideoBindingV1, SceneVideoTextureCommitV1, acquireSceneRuntimeAllocationV1, registerActualSceneResourcesV1, resetSceneRuntimeAllocationCountersV1, sceneRuntimeAllocationSnapshotV1, LaptopObject, PageObject, SlabObject, WorldTextObject, PosedObject, SLAB_CONTENT_OFFSET, type SceneShotV2Props, type PreparedSceneShotV1Props, type SceneShotSpecV2, type SceneObjectV2, type SceneGroupV2, type SceneVideoBindingPropsV1, type SceneVideoTextureBindingV1, type SceneActualResourceRowV1, type SceneActualResourceReceiptV1, type SceneRuntimeAllocationSnapshotV1, type SceneLaptopV2, type SceneSlabV2, type ScenePageV2, type SceneWorldTextV2, type SceneScreenTextV2, type SceneBackdropV2, type ScenePostV2, type SceneRigV2, type SceneGeneratedStudioRigV2, type ScenePhotographicStudioRigV1, type SceneSurfaceBindingV2, } from './scene/index.js';
+export { SLAB_TESSELLATION, SLAB_TESSELLATION_VERSION, SLAB_TRIANGLES, SLAB_DEFAULTS, SCENE_MAX_TRIANGLES, SCENE_MAX_LAYERS, slabBodyGeometry, slabTriangleCount, slabTrianglesFor, withNormalisedFaceUv, SLAB_FINISHES, SLAB_FINISH_SPEC, slabFinishMaterial, slabFinishDeclaredBytes, satinRoughnessMap, satinRoughnessScalar, brushedNormal, anodisedGrainNormal, PhotographicStudioRig, PhotographicStudioEnvironmentError, verifyPhotographicStudioHdr, PHOTOGRAPHIC_STUDIO_RIG_ID, PHOTOGRAPHIC_STUDIO_HDRI_PATH, PHOTOGRAPHIC_STUDIO_HDRI_SHA256, PHOTOGRAPHIC_STUDIO_HDRI_BYTES, PHOTOGRAPHIC_STUDIO_PMREM_VERSION, PHOTOGRAPHIC_STUDIO_LIGHTING_VERSION, PHOTOGRAPHIC_STUDIO_EDGE_LIGHTS, PHOTOGRAPHIC_STUDIO_EDGE_INTENSITY, PHOTOGRAPHIC_STUDIO_GPU_BYTES, PHOTOGRAPHIC_STUDIO_RIG_FACTS, admitLightingProfile, admitSceneRigKind, admitSceneRigV2, assertNoObjectLightField, sceneRigIdentityV2, sceneLightCount, lightingProfileDeclaredBytes, SceneLightingRefusal, SCENE_OBJECT_LIGHT_FIELDS, SCENE_ENVIRONMENT_VERSION, sceneSlotsFor, sceneBoundSurfaces, assertSceneSurfaceResolution, RESOLUTION_BOUND, ALLOWED_BAKE_SCALES, DEFAULT_BAKE_SCALE, SceneResolutionRefusal, checkSurfaceResolution, selectSceneBakeScale, projectedSlotEdges, projectToOutputPixels, type SceneSlabFinish, type SceneLightingRefusalCode, type SceneRigIdentityV2, type SceneRigKindV2, type SceneGeneratedStudioRigIdentityV2, type ScenePhotographicStudioRigIdentityV1, type SceneBakeScale, type SceneResolutionResult, type SceneBakeScaleSelection, type SceneEvaluatedPose, type SceneSlotRect, type SceneResolutionRefusalCode, type SceneSlotDescriptor, sceneSlabPreparationFactsV1, scenePresetBuilderDescriptorV1, generatedStudioPreparationFactsV1, photographicStudioPreparationFactsV1, sceneGrainPreparationAllocationV1, sceneGrainPreparationCpuAllocationV1, sceneFocusPreparationAllocationsV1, preparedSurfaceDeviceProps, type PreparedSceneSurfaceVisualV1, } from './scene/index.js';
+export { driftWallRecipe, infiniteSpiralRecipe, depthJourneyRecipe, infiniteCanvasRecipe, gridToHeroRecipe, type MediaTileRecipeResult, } from './media/recipes.js';
 export declare const sandboxScope: Record<string, unknown>;
 export declare const sandboxScopeNames: string[];

package/dist/_members/animate/layout/FlexLayout.d.ts

@@ -0,0 +1,69 @@
+import React from 'react';
+import { type FlexCell } from './solveFlex.js';
+import { type Fit } from './fit.js';
+/**
+ * Weighted flexbox layout that reflows. Lives here (not in primitives) so authored
+ * components can import it — `@cueframe/animate` is on the component import allowlist.
+ * The `flex-layout` catalog primitive is a thin wrapper over this.
+ */
+/** Sizing for one track: weight (grow) plus optional declared size along the main axis. */
+export interface FlexTrackSpec {
+    weight: number;
+    /** px along the main axis. With `weight: 0` the track is content-sized and pushes its neighbours. */
+    basis?: number;
+    min?: number;
+    max?: number;
+    shrink?: number;
+    /** Nest cells across the other axis. One level deep. */
+    split?: Array<number | Omit<FlexTrackSpec, 'split'>>;
+}
+/** A bare number is a weight. */
+export type FlexTrack = number | FlexTrackSpec;
+export interface FlexLayoutProps {
+    direction?: 'row' | 'column';
+    gap?: number;
+    padding?: number;
+    /** Main-axis tracks. Children fill the leaves depth-first. */
+    tracks?: FlexTrack[];
+    /**
+     * End state. Weights ease from tracks → tracksEnd across the clip. Shapes may differ:
+     * a cell present on only one side enters from / exits to zero.
+     */
+    tracksEnd?: FlexTrack[];
+    /** Per-leaf fit rule, in leaf order. Default stretch. */
+    fits?: Fit[];
+    /**
+     * Reflow progress 0..1. Default: eased over the clip from the current frame. Pass it
+     * explicitly to keep other layers (e.g. a 3D scene solved with solveFlex) on the same beat.
+     */
+    progress?: number;
+    /** Draw the rig — thin outlines on every cell. A design element, not debug UI. */
+    outline?: boolean;
+    outlineColor?: string;
+    /**
+     * Solve frame in px. Defaults to the video size. Inside a `params.region` container pass
+     * the region's pixel size so nested splits and aspect fits solve against the region.
+     */
+    width?: number;
+    height?: number;
+    children?: React.ReactNode;
+}
+type Dir = 'row' | 'column';
+/**
+ * Canonical shape covering both states. Where one side nests and the other does not,
+ * the flat side's weight is carried by the first nested cell and the rest read as 0 —
+ * so those cells enter from (or exit to) nothing.
+ */
+export declare function unionTracks(a: FlexTrack[], b?: FlexTrack[]): FlexTrackSpec[];
+/** Interpolated weight per cell id at progress p in [0,1]. Ids: `t{i}` and `t{i}.{j}`. */
+export declare function weightsAt(tracks: FlexTrack[], tracksEnd: FlexTrack[] | undefined, p: number): Record<string, number>;
+/** tracks → FlexCell tree over the union shape. ids are stable so weights animate by id. */
+export declare function buildTree(tracks: FlexTrack[], direction: Dir, gap: number, padding: number, tracksEnd?: FlexTrack[]): FlexCell;
+/**
+ * True once the layout engine is loaded. Holds the frame (delayRender) until then, so no
+ * frame is captured before the first solve. Use it in any component that calls solveFlex
+ * itself alongside <FlexLayout> — e.g. to place 3D objects on the same boxes.
+ */
+export declare function useFlexReady(): boolean;
+export declare const FlexLayout: React.FC<FlexLayoutProps>;
+export {};

package/dist/_members/animate/layout/fit.d.ts

@@ -0,0 +1,44 @@
+import type { FlexBox } from './solveFlex.js';
+/**
+ * Fit rules — how a cell's content sits inside the box the solver gave it.
+ * Pure geometry, no measurement: content aspect or authored size is declared,
+ * so the same inputs give the same inner box everywhere.
+ *
+ *  stretch   content fills the cell (default)
+ *  contain   largest box of `aspect` inside the cell
+ *  cover     smallest box of `aspect` covering the cell (cell clips the overflow)
+ *  position  content keeps its natural size, anchored in the cell — what type does
+ *  scale     content authored at `size` px, uniformly scaled to fit the cell
+ *  matte     content fills the cell, but is clipped to the `contain` box — the art
+ *            is never resized, the matte does the work
+ */
+export type FitMode = 'stretch' | 'contain' | 'cover' | 'position' | 'scale' | 'matte';
+export interface Fit {
+    mode: FitMode;
+    /** content aspect ratio (w / h) — used by contain, cover, matte. Defaults to the cell's own aspect. */
+    aspect?: number;
+    /** authored pixel size — required by `scale`. */
+    size?: {
+        w: number;
+        h: number;
+    };
+    /** where the content sits inside the cell, 0..1 on each axis. Default centre. */
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+export interface FitResult {
+    /** the box the content occupies, in the same coordinates as the cell */
+    box: FlexBox;
+    /** uniform scale to apply to a `size`-authored child (`scale` mode), else 1 */
+    scale: number;
+    /** `matte` only: inset from the cell edges to the visible window; else null */
+    clip: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    } | null;
+}
+export declare function fitBox(cell: FlexBox, fit?: Fit): FitResult;

package/dist/_members/animate/layout/index.d.ts

@@ -0,0 +1,3 @@
+export { solveFlex, flexReady, isFlexReady, leafIds, flexBoxToThree, type FlexCell, type FlexBox, type FlexSize, type FlexDir, } from './solveFlex.js';
+export { fitBox, type Fit, type FitMode, type FitResult } from './fit.js';
+export { FlexLayout, useFlexReady, buildTree, unionTracks, weightsAt, type FlexTrack, type FlexTrackSpec, type FlexLayoutProps, } from './FlexLayout.js';

package/dist/_members/animate/layout/solveFlex.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Flexbox layout solve for compositions. Pure: the same (tree, size, weights)
+ * always yields the same boxes. Consumers position DOM, Three.js (see
+ * flexBoxToThree) and SVG from the same numbers, so nothing drifts.
+ *
+ * yoga's default entry uses top-level await, which Remotion's esbuild target
+ * (chrome85) rejects — so the engine is loaded once here via a module-scope
+ * promise and every solve after that is synchronous.
+ */
+export type FlexDir = 'row' | 'column';
+export interface FlexCell {
+    id: string;
+    /** flex-grow weight along the parent's main axis. Default 1. 0 collapses the cell. */
+    grow?: number;
+    /**
+     * flex-basis in px along the parent's main axis. Default 0 so weights alone decide
+     * the split. With `grow: 0` this makes a content-sized cell: it takes exactly
+     * `basis` and its neighbours share the rest — the size of one cell moves the others.
+     */
+    basis?: number;
+    /**
+     * min / max size in px along the parent's main axis. `min` is a floor, not a fixed
+     * size: yoga (unlike CSS) lets a floored cell keep its weighted share of the remaining
+     * growth, so it can land above `min`. For an exact size use `grow: 0` + `basis`.
+     */
+    min?: number;
+    max?: number;
+    /** flex-shrink. Default 1 for weighted cells, 0 for content-sized cells (grow 0). */
+    shrink?: number;
+    /** main axis for this cell's children. Default 'row'. */
+    dir?: FlexDir;
+    /** px between children. */
+    gap?: number;
+    /** px inside this cell, around its children. */
+    padding?: number;
+    children?: FlexCell[];
+}
+export interface FlexBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface FlexSize {
+    w: number;
+    h: number;
+}
+/** Resolves once the engine is loaded. Await this (delayRender) before the first solve. */
+export declare const flexReady: Promise<void>;
+export declare function isFlexReady(): boolean;
+/** Depth-first ids of leaf cells — the slots children get assigned to. */
+export declare function leafIds(cell: FlexCell): string[];
+/**
+ * Solve `root` into `size`. `weights[id]` overrides a cell's `grow` — this is
+ * what gets animated; re-solve every frame rather than interpolating boxes, so
+ * every intermediate frame is a valid layout.
+ *
+ * A cell whose weight, basis and min are all 0 is removed from layout entirely
+ * (display: none), so it takes no gap either — that is how cells enter and exit.
+ */
+export declare function solveFlex(root: FlexCell, size: FlexSize, weights?: Record<string, number>): Record<string, FlexBox>;
+/**
+ * Centre of a box in Three.js world units for an orthographic camera whose
+ * frustum is pinned 1:1 to `size` pixels (left=-w/2, right=w/2, top=h/2, bottom=-h/2).
+ * Layout is y-down; Three is y-up.
+ */
+export declare function flexBoxToThree(box: FlexBox, size: FlexSize): {
+    x: number;
+    y: number;
+};

package/dist/_members/animate/media/MediaTileScene.d.ts

@@ -0,0 +1,65 @@
+import React from 'react';
+export declare const MEDIA_TILE_SCENE_LIMITS: Readonly<{
+    streams: 8;
+    tiles: 512;
+    textureBytes: number;
+}>;
+export interface MediaTileAsset {
+    handle: string;
+    kind: 'image' | 'video';
+    width?: number;
+    height?: number;
+    durationSec?: number;
+    frameRate?: number;
+}
+export interface MediaTileStream {
+    asset: MediaTileAsset;
+    trimBeforeFrames?: number;
+    trimAfterFrames?: number;
+    playbackRate?: number;
+    loop?: boolean;
+}
+export interface MediaTile {
+    stream: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Positive values move away from the camera. */
+    z?: number;
+    rotation?: number;
+    opacity?: number;
+    /** Normalized source crop using a top-left origin. */
+    crop?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface MediaTileCamera {
+    x?: number;
+    y?: number;
+    z?: number;
+    zoom?: number;
+    perspective?: number;
+}
+export interface MediaTileFog {
+    color: string;
+    near: number;
+    far: number;
+}
+export interface MediaTileSceneProps {
+    streams: Record<string, MediaTileStream>;
+    tiles: readonly MediaTile[];
+    camera?: MediaTileCamera;
+    fog?: MediaTileFog;
+    background?: string;
+    style?: React.CSSProperties;
+}
+export declare function mediaTileFramesReady(sourceFrames: readonly (number | null | undefined)[], frame: number, playing: boolean): boolean;
+export declare function assertMediaTileScene(streams: Record<string, MediaTileStream>, tiles: readonly MediaTile[]): string[];
+export declare function mediaTileCropUvs(crop: MediaTile['crop']): number[];
+export declare function mediaTileFogDistances(fog: MediaTileFog, camera: MediaTileCamera | undefined, perspective: number): [color: string, near: number, far: number];
+export declare function MediaTileScene({ streams, tiles, camera, fog, background, style }: MediaTileSceneProps): React.JSX.Element;
+export declare const ImageTileScene: typeof MediaTileScene;

package/dist/_members/animate/media/recipes.d.ts

@@ -0,0 +1,61 @@
+import type { MediaTile, MediaTileCamera, MediaTileFog } from './MediaTileScene.js';
+export interface MediaTileRecipeResult {
+    tiles: MediaTile[];
+    camera?: MediaTileCamera;
+    fog?: MediaTileFog;
+}
+export declare function driftWallRecipe(input: {
+    streamIds: readonly string[];
+    columns: number;
+    rows: number;
+    tileWidth: number;
+    tileHeight: number;
+    gap: number;
+    progress: number;
+    driftX?: number;
+    driftY?: number;
+}): MediaTileRecipeResult;
+export declare function infiniteSpiralRecipe(input: {
+    streamIds: readonly string[];
+    count: number;
+    tileWidth: number;
+    tileHeight: number;
+    radiusStep: number;
+    turns: number;
+    progress: number;
+}): MediaTileRecipeResult;
+export declare function depthJourneyRecipe(input: {
+    streamIds: readonly string[];
+    count: number;
+    tileWidth: number;
+    tileHeight: number;
+    depth: number;
+    progress: number;
+}): MediaTileRecipeResult;
+/**
+ * A frame-driven adaptation of Edoardo Lunardi's MIT-licensed Infinite Canvas
+ * chunk layout. The original camera is interactive; this recipe maps a
+ * deliberate, non-orbiting camera translation onto composition progress.
+ */
+export declare function infiniteCanvasRecipe(input: {
+    streamIds: readonly string[];
+    viewportHeight: number;
+    progress: number;
+    aspectRatio?: number;
+    forwardTravel?: number;
+    driftX?: number;
+    driftY?: number;
+    fovDegrees?: number;
+}): MediaTileRecipeResult;
+export declare function gridToHeroRecipe(input: {
+    streamIds: readonly string[];
+    columns: number;
+    rows: number;
+    heroIndex: number;
+    tileWidth: number;
+    tileHeight: number;
+    gap: number;
+    progress: number;
+    heroWidth: number;
+    heroHeight: number;
+}): MediaTileRecipeResult;

package/dist/_members/animate/scene/FocusPass.d.ts

@@ -0,0 +1,76 @@
+import type { SceneFocusV2 } from '../../composition/scene/index.js';
+import type { SceneFinishingUniforms } from './finishingPass.js';
+import { FocusResources, type FocusRenderer } from './focusResources.js';
+import type { SceneFrameSize } from './scaling.js';
+/**
+ * Any priority above zero takes rendering away from the fiber loop, which then calls this pass
+ * instead of drawing the scene itself. One is enough: this shot has no other subscriber.
+ */
+export declare const FOCUS_PASS_PRIORITY = 1;
+/**
+ * The near and far planes the depth reconstruction needs, from a camera that is entitled to them.
+ *
+ * `viewDistanceFromDepth` inverts the *perspective* depth mapping. Under an orthographic camera the
+ * same buffer holds a linear depth and the same arithmetic returns a distance nothing in the scene
+ * is at — every pixel would then be blurred by the wrong radius, with no symptom but a picture that
+ * looks subtly wrong. So the camera is narrowed rather than cast, and a shot that somehow reaches
+ * the pass with another projection is refused. `stageCamera` builds a perspective camera, which is
+ * why this is a guard against a future change rather than a case anyone can author today.
+ */
+export declare function focusCameraPlanes(camera: unknown): {
+    near: number;
+    far: number;
+};
+/**
+ * Refuse a pass whose resources were built for a different renderer.
+ *
+ * The resources hold one GL context's targets, textures and framebuffers, and the multisample
+ * count read from that context's canvas; drawing them with another renderer would draw through
+ * objects it has never uploaded. Fiber builds one renderer per canvas and never swaps it — the
+ * store's `gl` is created with the canvas and is not replaced by a prop change — so the resources
+ * may be constructed once and kept, which is what `useState` does with them. This is the assertion
+ * that says so, checked on every render rather than assumed, because the symptom of being wrong is
+ * a blank or stale frame with no error anywhere.
+ */
+export declare function assertPassRenderer(resources: FocusResources, gl: FocusRenderer): void;
+export interface FocusPassProps {
+    /**
+     * The evaluated focus for this frame, or `null` when the shot authors none. The pass is mounted
+     * either way: `null` is a maximum blur of zero, which is an identity gather (`FOCUS_OFF`).
+     */
+    focus: SceneFocusV2 | null;
+    /**
+     * This frame's grain and vignette, for the world half of the shot's finishing.
+     *
+     * The DOM half is the SVG filter on the backdrop and the screen text; the world's is here,
+     * because a `filter` over a layer that holds a WebGL canvas is what let Chromium hand back one
+     * raster of a shot tiled across the frame (D4). Both halves are given the same numbers.
+     */
+    finishing: SceneFinishingUniforms;
+    scale: number;
+    frame: SceneFrameSize;
+}
+/**
+ * The shot's world, drawn on every advance of the manual frame loop, with the shot's depth-aware
+ * focus applied to it.
+ *
+ * Mounted by every scene shot, not only the ones that declare focus. One pipeline is the whole
+ * point: the world is rasterized into this pass's half-float target and composited to the frame
+ * through this pass's output stage whatever the shot says, so turning `post.focus` on can change
+ * the blur radius and nothing else. Drawing the world straight onto the canvas when no focus is
+ * authored made focus-on and focus-off two different colour pipelines — the canvas blends clamped
+ * 8-bit sRGB with the renderer's tone curve applied, a render target blends unclamped linear — and
+ * a shot with `maxBlur: 0` came out a different picture from the same shot with no focus at all.
+ *
+ * Remotion's canvas renders by calling fiber's `advance` — once per frame while rendering, and once
+ * more whenever a load commits (`advanceRendererOnce`). Every advance runs the frame subscribers
+ * and then, only if none of them claimed a render priority, draws the scene. Claiming a priority
+ * here puts this pass in that place: the world is drawn into the pass's own target and the gather
+ * writes the frame, on exactly the advances that would otherwise have drawn the scene directly. No
+ * timer, no animation loop, and nothing to keep in step — a frame cannot be captured half-composed
+ * because the capture happens after the advance that drew it.
+ *
+ * The resources are this instance's; the size follows the frame, and unmounting disposes the
+ * targets, the depth texture, both materials and the quad geometry.
+ */
+export declare function FocusPass({ focus, finishing, scale, frame }: FocusPassProps): null;

package/dist/_members/animate/scene/UnlitPlane.d.ts

@@ -0,0 +1,45 @@
+import type { Texture } from 'three';
+import type { PlaneFitResult } from './planeFit.js';
+/**
+ * Fragments below this alpha are discarded rather than drawn.
+ *
+ * A transparent unlit plane must both composite its own alpha and occlude what is behind it — the
+ * contract calls an unlit surface a geometric participant. Writing depth for every fragment would
+ * let a world-text plane's empty margin punch a hole in the device behind it; writing none would
+ * stop it occluding at all. Discarding the fully transparent fragments gives both: nothing is
+ * written where the texture is empty, and every visible texel — including an antialiased glyph
+ * rim — writes colour and depth.
+ */
+export declare const UNLIT_PLANE_ALPHA_TEST = 0.01;
+export interface UnlitPlaneProps {
+    texture: Texture;
+    fit: PlaneFitResult;
+    color?: string;
+    transparent?: boolean;
+    depthWrite?: boolean;
+    backface?: 'hidden' | 'visible';
+    resourceOwner: string;
+    resourceName: string;
+}
+/**
+ * A screenshot or a rasterized text run on a world plane: unlit, colour-managed, occluding.
+ *
+ * Unlit and `UNLIT_COLOUR_MANAGED` so the product UI's colours survive the studio lighting exactly
+ * as authored, which is what the contract promises for screenshots and world text. The constant is
+ * spread rather than restated so the tone-mapping test can walk every material in this package by
+ * the name it carries. `transparent`
+ * is authored true — `applyLayerOpacity` keeps it that way at full opacity — because Three
+ * disables blending outright for an opaque material, which would write the texture's own edge
+ * alpha straight into the frame instead of compositing it.
+ *
+ * The UV window is applied in a layout effect of this leaf component, so it lands before the
+ * parent layer's readiness effect draws and releases the frame (layout effects run bottom-up). It
+ * is a uniform change, not a program parameter, so it needs no `needsUpdate`. The write is skipped
+ * when the texture already carries the window asked for: a page decodes its own texture and may be
+ * cropped, but a world-text raster is shared by content identity and is only ever given the
+ * identity window, so this plane never writes to a texture another instance is drawing with.
+ *
+ * One consequence of the alpha test worth knowing: it applies after the layer opacity multiplies
+ * the texture's alpha, so a plane fading out disappears at the threshold rather than at zero.
+ */
+export declare function UnlitPlane({ texture, fit, color, transparent, depthWrite, backface, resourceOwner, resourceName }: UnlitPlaneProps): import("react").JSX.Element;

package/dist/_members/animate/scene/__oracle__/cssProjection.d.ts

@@ -0,0 +1,24 @@
+import { Matrix4 } from 'three';
+import { perspectiveFor, type StageCamera } from '../../stage/camera.js';
+/**
+ * THE CSS-SIDE ORACLE. Test code only.
+ *
+ * `perspectiveFor`, `worldMatrix` and `projectCss` are the old CSS-first projection. Slice W1 of
+ * `2026-09-10-world-objects-plan.md` replaces the runtime with `scene/coordinates.ts`'s single
+ * `F`-conjugation bridge and keeps this arithmetic as *the other calculation the gate compares
+ * against* — Decision 1 asks for two independent projections, not for one shipped twice.
+ *
+ * No SCENE runtime path may import this file.
+ * `render-harness/scripts/__tests__/w1-css-oracle-isolation.test.mjs` walks the transitive
+ * first-party import graph from the scene renderer's own entry points and fails if one does; that
+ * test, not a convention, is what keeps the two conventions from drifting back together.
+ *
+ * The op list itself is NOT restated here: `cameraOpsMatrix` composes `stage/camera.ts`'s own
+ * ordered list, so the DOM stage (`PerspectiveStage`, which still authors in this convention and
+ * is not W1's to move) and this oracle cannot disagree about what the V1 camera means.
+ */
+/** The V1 camera's world matrix in CSS coordinates: x right, y DOWN, z toward the viewer. */
+export declare function worldMatrix(c: StageCamera): Matrix4;
+/** Where a CSS point lands on screen under the stage's perspective. */
+export declare function projectCss(c: StageCamera, width: number, height: number, p: [number, number, number]): [number, number];
+export { perspectiveFor };

package/dist/_members/animate/scene/assets.d.ts

@@ -0,0 +1,21 @@
+import type { SceneImageSlotKind } from './useSceneImageTexture.js';
+/** Everything needed to name one layer's image binding in an error the author can act on. */
+export interface SceneImageSlotRef {
+    slot: string;
+    /** The layer's index in `spec.layers`, for the validator-style error path. */
+    layerIndex?: number;
+    /** Exact validator-style object path when the layer may be nested. */
+    layerPath?: string;
+    layerId: string;
+    /** The field that carries the slot name: a device's `screen`, a page's `image`, a slab's `front`. */
+    field: 'screen' | 'image' | 'front';
+    what: SceneImageSlotKind;
+}
+/**
+ * The admitted runtime handle for an image slot. The outer `assets` map is the component runtime's
+ * `Record<slot, ComponentAssetBindingV2>`; the scene itself only names slots. A slot that is
+ * missing, not an image, or carries no handle fails here, before any canvas is mounted. The error
+ * path uses the layer's array index and the field the slot was written in, as the validator's
+ * paths do; the message names the layer id.
+ */
+export declare function sceneImageHandle(assets: Record<string, unknown>, ref: SceneImageSlotRef): string;

package/dist/_members/animate/scene/backdrop.d.ts

@@ -0,0 +1,7 @@
+import type { SceneColor } from '../../composition/scene/index.js';
+/**
+ * A scene colour as CSS. Brand references are resolved by the render-preparation stage into the
+ * runtime spec this renderer receives; one that survives to here is a preparation bug, and
+ * inventing a colour for it would hide that bug in the output.
+ */
+export declare function resolveSceneColor(color: SceneColor, path: string): string;

package/dist/_members/animate/scene/coordinates.d.ts

@@ -0,0 +1,58 @@
+import { Matrix4 } from 'three';
+/**
+ * Decision 1's coordinate bridge, in production.
+ *
+ * Authored world transforms are Three's own: X right, **Y up**, the camera looking down its local
+ * −Z, **radians**, Euler order **XYZ** (the composed matrix is `T · Rx · Ry · Rz · S`), and a
+ * strictly positive uniform scale. One world unit is one reference-layout pixel.
+ *
+ * There is exactly one conversion to the CSS boundary and it is the conjugation `F · M · F` with
+ * `F = diag(1, −1, 1, 1)`, applied to the COMPLETE matrices — object world matrix, camera world
+ * matrix and the landmark's own local `y`. Flipping the translation alone is invalid and is the
+ * negative control of `i0ProjectionParity.test.ts`; it misses by ≥16 output pixels.
+ *
+ * `perspectiveFor`, `worldMatrix` and `projectCss` — the old CSS-first projection — survive only as
+ * the gate's CSS-side oracle (`scene/__oracle__/cssProjection.ts`). No SCENE runtime path imports
+ * them: `render-harness/scripts/__tests__/w1-css-oracle-isolation.test.mjs` walks the scene lane's
+ * transitive first-party import graph and asserts it. (`perspectiveFor` remains runtime for
+ * `stage/PerspectiveStage.tsx`, the DOM stage, which is not the scene bridge and which Decision 2's
+ * deletion prohibition forbids weakening in this slice.)
+ */
+export type SceneVec3 = [number, number, number];
+/**
+ * A world transform in the authored (Three-native) convention.
+ *
+ * NOTE FOR W3: this is report §5.4's `SceneTransformV2`. It is declared here rather than in
+ * `@cueframe/composition/scene` because W3 owns the wire schema; when W3 lands, this type moves
+ * there unchanged and this module imports it.
+ */
+export interface SceneWorldTransform {
+    /** Reference pixels, Y up. */
+    position: SceneVec3;
+    /** RADIANS, Euler order XYZ. */
+    rotation: SceneVec3;
+    /** Uniform, strictly positive. */
+    scale: number;
+}
+/** Euler order for every authored rotation. Stated once so nothing restates it. */
+export declare const SCENE_EULER_ORDER: "XYZ";
+/** `F = diag(1, −1, 1, 1)`: the whole of the CSS boundary conversion. */
+export declare const F: Matrix4;
+/**
+ * The bridge: `F · M · F`. Applied to a complete matrix — a world matrix, a camera matrix — never
+ * to a translation alone.
+ */
+export declare function conjugateF(m: Matrix4): Matrix4;
+/** `T · Rx · Ry · Rz · S` in Three's axes, from an authored transform. */
+export declare function sceneWorldMatrix(t: SceneWorldTransform): Matrix4;
+/** The same transform at the CSS boundary, conjugated by `F`. Used by the landmark gate's CSS side. */
+export declare function sceneCssMatrix(t: SceneWorldTransform): Matrix4;
+export interface ThreeLayerPose {
+    position: SceneVec3;
+    quaternion: [number, number, number, number];
+    scale: number;
+}
+/** An authored transform as the pose of an R3F `<group>`. */
+export declare function sceneLayerPose(t: SceneWorldTransform): ThreeLayerPose;
+/** A transform in output pixels: position scales, rotation and the uniform scale are ratios. */
+export declare function scaleSceneTransform(t: SceneWorldTransform, scale: number): SceneWorldTransform;

package/dist/_members/animate/scene/deviceOpacity.d.ts

@@ -0,0 +1,18 @@
+import type { Object3D } from 'three';
+/**
+ * Apply a layer opacity to every material under `root`, multiplying each material's own authored
+ * opacity (the glass is 0.1 by design) rather than overwriting it. The base is remembered on the
+ * material the first time it is seen, so repeated frames never compound. Materials here are
+ * created per DeviceMesh instance, so this never touches another layer's material.
+ *
+ * `transparent` is a program parameter in Three (the `OPAQUE` define), re-derived only when the
+ * material's version changes, so a flip after the first draw must also set `needsUpdate`. A
+ * same-state re-apply must not: each `needsUpdate` recompiles the program.
+ *
+ * A material the layer authored as transparent stays transparent at full opacity: the unlit page
+ * and world-text planes carry their own alpha, and Three disables blending outright for an opaque
+ * material (`material.blending === NormalBlending && transparent === false` → `NoBlending`), so
+ * flipping one of those to opaque would write its unpremultiplied edge texels straight into the
+ * frame. The authored flag is remembered alongside the authored opacity, once, on first sight.
+ */
+export declare function applyLayerOpacity(root: Object3D, opacity: number): void;

package/dist/_members/animate/scene/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed failures raised by the scene-shot renderer. The code is the first token of the message so
+ * hosts that only see an `Error` (Remotion's error boundary, the render lane's sanitized envelope)
+ * can still classify it; later stages map these onto the shared error registry.
+ */
+export type SceneShotErrorCode = 'scene_aspect_mismatch' | 'scene_asset_unbound' | 'scene_asset_load_failed' | 'scene_brand_unresolved' | 'scene_font_unavailable' | 'scene_resource_exhausted'
+/** The host's renderer lacks a capability the shot requires; distinct from running out of one. */
+ | 'scene_render_target_unsupported' | 'scene_internal';
+export declare class SceneShotError extends Error {
+    readonly code: SceneShotErrorCode;
+    /** Dotted path into the scene spec the failure is about, when there is one. */
+    readonly path: string | null;
+    constructor(code: SceneShotErrorCode, detail: string, path?: string | null);
+}