@cueframe/kernel 0.2.1 → 0.2.3

package/dist/_members/animate/scene/v2/slabGeometry.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The slab body's geometry, at the FROZEN tessellation.
+ *
+ * **NOTE FOR W3.** `SLAB_TESSELLATION_VERSION`, `SLAB_TESSELLATION` and `SLAB_TRIANGLES` are
+ * policy constants and belong in `@cueframe/composition/scene` beside the other budget numbers
+ * (Decision 5 puts "pure accounting and policy constants" there, and the plan's ownership map
+ * gives that file to W3). They live here because W2 needs the geometry before that module exists,
+ * and because the number has to be asserted against the geometry that three actually builds
+ * rather than against a copy of itself. When W3 lands they move unchanged in value.
+ */
+import { ExtrudeGeometry, type BufferGeometry } from 'three';
+/**
+ * `tessellationVersion: 1` — frozen inside I0 (report §4.1a) and consumed here, never chosen.
+ *
+ * Versioned and fixed: Decision 5 puts adaptive tessellation and author-controlled segment counts
+ * outside first delivery, so there is no field anywhere in the contract that reaches these two
+ * numbers. A future profile is a NEW version with its own measured triangle count, not an edit to
+ * this one — the count below is a budget input, and a silent change to it would move the admission
+ * arithmetic of every shot that already validated.
+ */
+export declare const SLAB_TESSELLATION_VERSION = 1;
+/**
+ * 24 curve segments around each face corner, 6 across the edge bevel.
+ *
+ * **Why 24/6 and not the spike's 32/8.** `SCENE_MAX_LAYERS` is 32 and Decision 5's triangle cap is
+ * 250 000. At 32/8 a slab is 9 358 triangles, so 32 slabs is 299 456 — two policy constants that
+ * refuse each other. At 24/6 the worst case at the layer cap is 32 × 5 486 = 175 552, **74 448
+ * triangles inside the cap**, so no combination of 32 layers can exceed the triangle budget at all.
+ *
+ * **The visual cost was measured, not assumed** (I0 `review-fixes.json`, `f5f17Finishes.sweep`):
+ * under the first-delivery rig, 32/8 reads satin 1.14× body @ 0 px and brushed 1.24× @ 8 px, and
+ * 24/6 reads 1.07× @ 0 px and 1.17× @ 11 px. Both are far below any usable rim criterion, so
+ * nothing that is or could be a finish gate depends on the difference: 24/6 costs ~6 % of a
+ * highlight that is not a gate and buys back 41 % of the triangles.
+ */
+export declare const SLAB_TESSELLATION: {
+    readonly curveSegments: 24;
+    readonly bevelSegments: 6;
+};
+/**
+ * The BODY's own triangle count at `SLAB_TESSELLATION` — the extruded solid alone.
+ *
+ * This is the number `slabTriangleCount(slabBodyGeometry(...))` returns, and it is also the slab's
+ * SHADOW-PASS count: the content face casts nothing (report §4.1's `shadowPassTriangles` column).
+ */
+export declare const SLAB_BODY_TRIANGLES = 5484;
+/** The content face: one `PlaneGeometry` quad, mounted only when the `front` slot is bound. */
+export declare const SLAB_CONTENT_FACE_TRIANGLES = 2;
+/**
+ * The INSTANTIATED triangle count of one slab PRESET at `SLAB_TESSELLATION` — **5 486**, asserted
+ * and never re-derived (report §4.1a, plan W2 item 7 and exit clause 5).
+ *
+ * **It is the preset total, body plus content face**, exactly as I0 counted it: `ledger.json`'s
+ * slab row reads `body 5 484` + `content face 2` = `instantiatedTriangles 5 486`, which is the
+ * same shape as its 32/8 figure of `9 356 + 2 = 9 358`. That distinction is worth stating because
+ * the first version of this file asserted 5 486 against the BODY and went red at 5 484 — the body
+ * reproduces I0 exactly and the constant was being compared to the wrong part.
+ *
+ * A measured constant, not a formula. `slabTriangleCount` counts what three actually built and
+ * `slabGeometry.test.ts` asserts the two agree, so a three upgrade that changes how
+ * `ExtrudeGeometry` closes its caps turns into a red test rather than into a budget that silently
+ * disagrees with the geometry it accounts for. A formula here would agree with itself forever.
+ *
+ * The budget charges the preset total for every slab, bound face or not: admission runs before the
+ * surfaces are resolved, and a bound that depended on whether an author later bound a slot would
+ * not be a bound.
+ */
+export declare const SLAB_TRIANGLES: number;
+/** Decision 5's per-resident-shot cap, restated so the headroom claim is checkable in one place. */
+export declare const SCENE_MAX_TRIANGLES = 250000;
+/** The layer cap the triangle cap is proved compatible with (report §5.8a: it is DERIVED from it). */
+export declare const SCENE_MAX_LAYERS = 32;
+/** Report §5.5's slab defaults, in reference px. */
+export declare const SLAB_DEFAULTS: {
+    thickness: number;
+    cornerRadius: number;
+    edgeRadius: number;
+    finish: "satin";
+    /** The flat dark base the two finishes are painted over; the specular is the whole performance. */
+    baseColor: string;
+};
+/**
+ * The slab body: an extruded rounded rectangle with an independent quarter-round bevel.
+ *
+ * **NEVER `RoundedBoxGeometry`.** It clamps its radius to half the THINNEST axis, which collapses a
+ * 32 px face radius on a 32 px-thick slab to 16 px — the face corners silently stop being the
+ * radius the author wrote (report §5.5). Edge rounding and face-corner rounding are separate fields
+ * with separate bounds for exactly this reason, and this constructor is what keeps them separate.
+ *
+ * **The bevel is a true quarter-circle, not a chamfer.** Three walks the bevel as
+ * `z = bevelThickness · cos(t·π/2)`, `bs = bevelSize · sin(t·π/2)`, so passing the same number for
+ * both makes the shoulder an arc of that radius. A chamfer has ONE normal and gives one flat band;
+ * an arc sweeps its normal through 90° between the face and the edge, so some line along the
+ * shoulder reflects the brightest light in the room at every yaw the slab ever takes. That sweep is
+ * the mechanism the `studio-edge` rim gate measures.
+ *
+ * **The outer box stays exactly `w × h × t` centred on the origin.** The shape is inset by the
+ * effective edge radius, the extrusion runs from `−e` to `depth + e`, and the result is translated
+ * back by `depth / 2` — so the front face is at `z = +t/2`, which is what the content-face offset
+ * and any collision half-extent are entitled to assume.
+ */
+export declare function slabBodyGeometry(width: number, height: number, thickness: number, cornerRadius: number, edgeRadius: number): ExtrudeGeometry;
+/**
+ * The instantiated triangle count of a built geometry: the index buffer over three.
+ *
+ * Counts what was BUILT. `SLAB_TRIANGLES` is what the budget was admitted against, and the two are
+ * compared rather than one being computed from the other.
+ */
+export declare function slabTriangleCount(geometry: BufferGeometry): number;
+/** Σ over a shot's slabs, for the admission rule that totals the flattened tree (report §4.1a). */
+export declare function slabTrianglesFor(slabCount: number): number;
+/**
+ * Add a `uv1` attribute holding PER-FACE NORMALISED UVs, leaving `uv` alone.
+ *
+ * **Why both, and why `uv` is the one left in world units.** `ExtrudeGeometry` does not generate
+ * normalised UVs: its default `WorldUVGenerator.generateTopUV` returns the vertex's own local x and
+ * y AS the uv, unscaled (three 0.183.2, `ExtrudeGeometry.js`), and `generateSideWallUV` does the
+ * same with x/y/z. So on this geometry the uv coordinate IS the world pixel — u runs ±(w/2 − e)
+ * across the face and v runs ±(h/2 − e) down it. That is not a defect to correct here: the two
+ * generated finishes are AUTHORED in that space. Their tile sizes are world pixels and their
+ * `repeat` is `1 / tilePx` (see `finishes.ts`), which is what makes a grain the same physical size
+ * on a 520 px slab and a 1040 px one instead of stretching with the geometry. Normalising `uv`
+ * would rescale both maps by the slab's own dimensions and the frozen finish facts — absolute peak
+ * luma at a pinned pose — would stop reproducing.
+ *
+ * So the normalised UVs go in `uv1`, where a slot binding can use them (three's `Texture.channel`
+ * selects the attribute) without touching the space the finishes live in. `uv1` is `(0,0)` at the
+ * face's top-left corner and `(1,1)` at its bottom-right, which is §5.6's `uvOrigin: 'top-left'`
+ * for the `front` slot. Every side and bevel vertex uses the chart selected by its dominant face
+ * normal, so no face collapses to a line and every chart remains normalised independently.
+ *
+ * Costs no triangles and no draw call; it is 8 bytes per vertex of declared geometry.
+ */
+export declare function withNormalisedFaceUv(geometry: BufferGeometry, width: number, height: number): BufferGeometry;

package/dist/_members/animate/scene/v2/slots.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Report §5.6's SLOT TABLE, and the surface path's call into amendment A2's resolution check.
+ *
+ * **A slot is declared by the BUILDER, not by the author.** Friendly names resolve to these rows
+ * and to nothing else; an unknown slot name is refused with the preset's legal list, and a
+ * duplicate binding is impossible by construction because `surfaces` is a record. **Curved geometry
+ * does not automatically acquire a planar screen** — a slot exists only where its preset declares
+ * one, which is why the laptop has `screen`, the slab has `front`, the page has `content`, and
+ * nothing has anything else.
+ *
+ * **NOTE FOR W3.** The table is wire contract and moves with the schema. **NOTE FOR W4.**
+ * `assertSceneSurfaceResolution` is a runtime GUARD standing in for preparation's sealed selection;
+ * see `projectedResolution.ts` for exactly what W4 must take over.
+ */
+import { type SceneBakeScale, type SceneSlotRect } from './projectedResolution.js';
+import type { SceneObjectV2, SceneShotSpecV2, SceneSurfaceBindingV2 } from '../../../composition/scene/index.js';
+import type { SceneWorldTransform } from '../coordinates.js';
+/** One row of §5.6's frozen slot table. */
+export interface SceneSlotDescriptor {
+    slot: string;
+    attachment: {
+        part: string;
+        materialRole: string;
+    };
+    /** Reference px, DERIVED from the preset's own params. */
+    dimensions: SceneSlotRect;
+    uvOrigin: 'top-left' | 'bottom-left';
+    fit: 'contain' | 'cover' | 'stretch';
+    alpha: 'opaque' | 'straight' | 'premultiplied';
+    depth: 'write' | 'test-only';
+    required: boolean;
+    /** The bake scales this slot admits. Every preset in first delivery admits both. */
+    bakeScales: readonly SceneBakeScale[];
+}
+/**
+ * The slots one object declares, with dimensions derived from its own params.
+ *
+ * The laptop's `width·0.86 × width·0.54` comes from `laptopLayout`'s proportions; the slab's
+ * `width × height` is its whole front face; the page's is its declared box, which `fit` then fits
+ * the admitted content inside.
+ */
+export declare function sceneSlotsFor(node: SceneObjectV2): SceneSlotDescriptor[];
+/** A bound surface with everything the check needs: its slot rect and its ancestor chain. */
+interface BoundSurface {
+    layerId: string;
+    slot: string;
+    binding: SceneSurfaceBindingV2;
+    dimensions: SceneSlotRect;
+    /** Outermost first, the object's own transform last. */
+    chain: SceneWorldTransform[];
+}
+/** Every bound surface in a shot, with its slot rectangle and transform chain. */
+export declare function sceneBoundSurfaces(spec: SceneShotSpecV2): BoundSurface[];
+/**
+ * **Amendment A2 in the surface path.** Run the projected-resolution check over every bound surface
+ * that declares a capture `layout`, and let its refusal out.
+ *
+ * **What this is and is not.** It is a GUARD: the runtime holds ONE evaluated frame (W1's contract
+ * — the caller evaluates the animation), so the enumeration here is that frame alone, and it can
+ * only catch a shot that is already over the line at the frame being drawn. Preparation's version
+ * runs over the sealed schedule's complete `f = 0 … D−1` enumeration and SEALS the answer, which is
+ * the only version that can refuse a shot before a pixel is spent. W4 owns that; until then this
+ * stops a resampled UI from reaching the frame silently, which is what A2 forbids.
+ *
+ * Surfaces with no declared `layout` are skipped, and that is correct rather than lenient: an image
+ * binding has no bake scale and no declared raster, so the metric has no numerator. The check
+ * applies to CAPTURES, which are the things a bake scale is chosen for.
+ */
+export declare function assertSceneSurfaceResolution(spec: SceneShotSpecV2, output: {
+    width: number;
+    height: number;
+}): void;
+export {};

package/dist/_members/animate/scene/v2/videoBinding.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import { CanvasTexture } from 'three';
+import type { Object3D, Texture } from 'three';
+import { type SceneSealedVideoScheduleV1 } from '../../../composition/scene/index.js';
+import type { PreparedSceneSurfaceVisualV1 } from './preparedSurface.js';
+export declare function sceneHasVideoTextureV1(scene: Object3D, texture: Texture): boolean;
+export interface SceneVideoTextureBindingV1 {
+    readonly kind: 'video-texture';
+    readonly texture: CanvasTexture;
+    readonly visual: PreparedSceneSurfaceVisualV1;
+    readonly sourceIndex: number;
+    readonly revision: number;
+    readonly request: string;
+    /** Internal draw receipt shared with the Three commit bridge. */
+    readonly drawReceipt: {
+        request: string | null;
+        revision: number | null;
+    };
+    readonly readinessHandle: number;
+    readonly releaseReadiness: () => void;
+}
+export interface SceneVideoBindingPropsV1 {
+    src: string;
+    schedule: SceneSealedVideoScheduleV1;
+    contentFrame: number;
+    width: number;
+    height: number;
+    resourceOwner?: string;
+    children(binding: SceneVideoTextureBindingV1 | null): React.ReactNode;
+}
+/**
+ * Owns the decoder-to-texture copy. The callback image is copied before @remotion/media closes it;
+ * flushSync makes the matching Three commit and draw finish before Video releases its own handle.
+ */
+export declare function SceneVideoBindingV1({ src, schedule, contentFrame, width, height, resourceOwner, children }: SceneVideoBindingPropsV1): React.JSX.Element;
+/** Must mount inside the shared Three canvas before a video texture is used by a material. */
+export declare function SceneVideoTextureCommitV1({ binding }: {
+    binding: SceneVideoTextureBindingV1;
+}): null;

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

@@ -0,0 +1,19 @@
+import { type DeviceKind } from '../three/DeviceMesh.js';
+import type { ShadowBounds } from '../three/StudioRig.js';
+export type WorldPoint = [number, number, number];
+export declare function pointsBounds(points: readonly WorldPoint[]): ShadowBounds;
+export declare function unionBounds(a: ShadowBounds, b: ShadowBounds): ShadowBounds;
+/**
+ * The corners of the shells DeviceMesh casts with, in the device's own frame (Three axes, the
+ * same units as `width`): the phone's slab; the laptop's base and its lid swung to `openAngle`
+ * about the hinge.
+ *
+ * The placements come from `laptopLayout` and `lidRotationX` themselves — the base's centre, the
+ * hinge, the lid's centre and the swing are read, not restated, so moving the layout moves these
+ * bounds with it. What is still derived here is the EXTENT of each shell, which the layout does
+ * not describe: the base is `w × t × d` about `baseY`, the lid is `w × h × t` reaching from the
+ * hinge, and the phone is `w × h × t` about its group. Those follow `deviceDimensions` directly,
+ * and a change to the SHELL GEOMETRY in DeviceMesh — not to its layout — still has to be made
+ * here too. The screen and glass planes cast nothing and are omitted.
+ */
+export declare function deviceShellCorners(kind: DeviceKind, width: number, openAngle: number): WorldPoint[];

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

@@ -0,0 +1,87 @@
+import { type SceneWorldTextV2 } from '../../composition/scene/index.js';
+import { type TextBlockLayout } from './textLayout.js';
+/**
+ * The largest world-text raster this renderer will allocate on either axis.
+ *
+ * Every world-text plane draws one texel per output pixel, so a wide block at 4K is a wide
+ * texture. WebGL2 itself guarantees only 2048, so the size a renderer may assume is not a
+ * property of WebGL — it is whatever the host admission floor is, and here that floor is
+ * `STUDIO_SHADOW_MAP_BUDGET`: `webGlRefusal` in `@cueframe/component-runtime`'s `webglProbe.ts`
+ * turns away every browser reporting a smaller `MAX_TEXTURE_SIZE` before a frame is captured.
+ *
+ * Derived from that constant rather than written again as its own literal, so the claim "this
+ * renderer never asks for a texture larger than the host was admitted to provide" is structural,
+ * not a coincidence two files have to keep agreeing on by hand. Written as its own 4096 it held
+ * only while the two numbers happened to match: moving the budget would have left this one
+ * behind, either refusing blocks every admitted host could draw or asking for a texture no host
+ * ever promised.
+ *
+ * An oversized block is refused with a path (`worldTextRasterSize` below), never resized to fit.
+ */
+export declare const WORLD_TEXT_MAX_TEXTURE = 4096;
+/** The 2D drawing surface the rasterizer needs; a node test supplies a recording double. */
+export interface TextRasterContext {
+    canvas: {
+        width: number;
+        height: number;
+    };
+    font: string;
+    fillStyle: string;
+    textAlign: string;
+    textBaseline: string;
+    letterSpacing?: string;
+    clearRect(x: number, y: number, width: number, height: number): void;
+    fillText(text: string, x: number, y: number): void;
+    measureText(text: string): {
+        width: number;
+        fontBoundingBoxAscent?: number;
+        fontBoundingBoxDescent?: number;
+        actualBoundingBoxAscent?: number;
+        actualBoundingBoxDescent?: number;
+    };
+}
+/**
+ * The cache identity of one world-text raster: the resolved text, every typography field that
+ * changes a glyph's shape or place, and the reference scale.
+ *
+ * The identity is the content itself rather than a digest of it, so two different blocks cannot
+ * collide onto one texture — a hash's failure mode here is drawing the wrong words. It is
+ * deterministic and stable across instances and frames: content and typography are static within
+ * a shot, so a shot never rebuilds its own raster, and two shots that say the same thing at the
+ * same scale share one immutable texture.
+ */
+export type WorldTextRasterInput = SceneWorldTextV2 & {
+    width: number;
+};
+export declare function worldTextCacheKey(layer: WorldTextRasterInput, scale: number, index: number): string;
+/** The raster's pixel size: the laid-out block, one texel per output pixel, refused if oversized. */
+export declare function worldTextRasterSize(layout: TextBlockLayout, layerId: string, index: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Draw one world-text layer's typed lines and runs onto a transparent 2D surface.
+ *
+ * The same lines, runs, colours and typography the DOM path uses, laid out by the same module:
+ * line boxes from `textBlockLayout`, the baseline from `lineBaselineY`, the alignment origin from
+ * `lineOriginX` over the measured run widths. Runs are drawn left to right at the alphabetic
+ * baseline, each in its own colour, so two-colour type comes out of the raster exactly as it
+ * comes out of the DOM. Text is drawn, never parsed: no markup path exists here either.
+ *
+ * The surface is cleared first and never filled, so everything outside a glyph stays transparent
+ * — the plane must composite onto the world, not sit on a card.
+ *
+ * Known bound: run boundaries are where the two text paths could still differ. Here each run is
+ * measured on its own and the advances are concatenated, so a run boundary is always a shaping
+ * boundary; the DOM path hands the browser one line of adjacent spans and lets it shape the line.
+ * Browsers do not kern or ligate across inline-element boundaries in practice, so the two agree on
+ * everything authored so far — but that is an observed behaviour, not a guarantee either path
+ * makes, and a face with cross-boundary shaping would move a coloured run by a fraction of a pixel
+ * on one path and not the other. What *is* guaranteed is everything above the run: the block box,
+ * the line boxes, the baselines and the alignment origin all come from `textLayout`, which both
+ * paths call. Closing the bound would mean shaping the whole line once and colouring glyph ranges,
+ * which needs a shaper this renderer does not have.
+ */
+export declare function drawWorldText(ctx: TextRasterContext, layer: WorldTextRasterInput, layout: TextBlockLayout, index: number): void;
+/** The block layout of a world-text layer at an output scale; the plane is exactly this box. */
+export declare function worldTextLayout(layer: WorldTextRasterInput, scale: number): TextBlockLayout;

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

@@ -0,0 +1,32 @@
+import type { WorldTextRasterInput } from './worldTextRaster.js';
+import { type Texture } from 'three';
+import type { TextBlockLayout } from './textLayout.js';
+import { type SceneActualResourceRegistrarV1 } from './v2/runtimeAllocations.js';
+export interface WorldTextRasterRequest {
+    layer: WorldTextRasterInput;
+    layout: TextBlockLayout;
+    size: {
+        width: number;
+        height: number;
+    };
+    /** The layer's index in `spec.layers`, for error paths. */
+    index: number;
+    /** The renderer's maximum anisotropy; the plane is often seen at an angle. */
+    anisotropy: number;
+}
+/**
+ * Draw a world-text layer into a detached 2D canvas and wrap it as an sRGB texture.
+ *
+ * The canvas never enters the document: it is created, drawn once and handed to the GPU. The
+ * result is immutable — content and typography are static within a shot — which is what lets one
+ * raster be shared by content identity across layers and shots.
+ *
+ * Filtering: trilinear with the host's maximum anisotropy, because a world plane is routinely seen
+ * at an angle and at less than one texel per pixel. The alpha stays straight (not premultiplied):
+ * that is the pairing Three's `NormalBlending` expects, which multiplies colour by coverage at
+ * blend time. The cost is the usual one for a mipmapped straight-alpha texture — a heavily
+ * minified glyph edge averages toward the transparent black the canvas cleared to — and the fix,
+ * if a fixture ever shows it, is to turn mipmaps off here and rely on the anisotropic magnification
+ * path alone.
+ */
+export declare function createWorldTextTexture(request: WorldTextRasterRequest, registerActual?: SceneActualResourceRegistrarV1): Texture;

package/dist/_members/animate/stage/PerspectiveStage.d.ts

@@ -0,0 +1,73 @@
+import React from 'react';
+import { type StageCamera } from './camera.js';
+import { type FocusSpec } from './dof.js';
+export interface StageContextValue {
+    camera: StageCamera;
+    width: number;
+    height: number;
+    focus?: FocusSpec;
+}
+export declare function useStage(): StageContextValue;
+export interface PerspectiveStageProps {
+    camera?: Partial<StageCamera>;
+    /** Stage size in px. Defaults to the video frame. */
+    width?: number;
+    height?: number;
+    focus?: FocusSpec;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/**
+ * A CSS-3D stage: `perspective` derived from the camera fov, and a world group carrying the
+ * inverse camera pose so children placed with <StageLayer> orbit, dolly, and tilt together.
+ * Pairs 1:1 with ThreeCanvas's `stageCamera` — a layer at z=0 and a mesh at z=0 share pixels.
+ */
+export declare const PerspectiveStage: React.FC<PerspectiveStageProps>;
+export interface StageLayerShadow {
+    opacity?: number;
+    blur?: number;
+    offsetY?: number;
+}
+export interface StageLayerProps {
+    x?: number;
+    y?: number;
+    z?: number;
+    rotX?: number;
+    rotY?: number;
+    rotZ?: number;
+    /**
+     * Uniform scale applied after the rotations. A layer at depth `z` projects at `P / (P - z)`,
+     * so `(P - z) / P` cancels that and keeps the layer the size it would be at z=0.
+     */
+    scale?: number;
+    /** Box size in px. Defaults to the stage size (a full-frame plane). */
+    width?: number;
+    height?: number;
+    /** Drop shadow from the layer's own silhouette. */
+    shadow?: StageLayerShadow;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/**
+ * A planar layer in the stage, centred on (x, y) relative to the frame centre and pushed to z.
+ * The layer re-provides the stage context sized to its own box, so a nested layer is centred on
+ * its parent layer's box; direct children of the stage are centred on the frame.
+ * Depth of field and shadows use CSS filters, which flatten this layer's own 3D children —
+ * nest further StageLayers only in layers without blur or shadow.
+ */
+export declare const StageLayer: React.FC<StageLayerProps>;
+export interface ContactShadowProps {
+    /**
+     * Floor height in px, CSS y-down, measured from the centre of the *enclosing stage box*.
+     * That box is the composition frame at the top level, but a `StageLayer` re-provides the
+     * stage with its own width/height, so inside a layer `y` is measured from that layer's
+     * centre — nesting rebases the origin on purpose. Positive is below the centre.
+     */
+    y: number;
+    width: number;
+    depth: number;
+    opacity?: number;
+    z?: number;
+}
+/** A soft elliptical shadow lying on the floor plane under a grounded object. */
+export declare const ContactShadow: React.FC<ContactShadowProps>;

package/dist/_members/animate/stage/camera.d.ts

@@ -0,0 +1,143 @@
+import { Matrix4 } from 'three';
+import { sceneCameraPlanesV2 } from '../../composition/scene/index.js';
+/**
+ * One camera model for two renderers. Coordinates are CSS: x right, y down, z toward the
+ * viewer, origin at the frame center, units in pixels of the z=0 plane. `z` is an offset
+ * from the default eye distance (positive = further away). Rotations orbit the origin.
+ */
+export interface StageCamera {
+    x: number;
+    y: number;
+    z: number;
+    rotX: number;
+    rotY: number;
+    rotZ: number;
+    fov: number;
+}
+export declare const DEFAULT_CAMERA: StageCamera;
+/** CSS `perspective` (eye distance) that makes a vertical `fov` see exactly `height` px at z=0. */
+export declare function perspectiveFor(fov: number, height: number): number;
+/** One ordered CSS transform op. Degrees for rotations, pixels for the translation. */
+export type CameraOp = {
+    kind: 'translate3d';
+    x: number;
+    y: number;
+    z: number;
+} | {
+    kind: 'rotateX';
+    deg: number;
+} | {
+    kind: 'rotateY';
+    deg: number;
+} | {
+    kind: 'rotateZ';
+    deg: number;
+};
+/**
+ * The single source of truth for the world pose: the inverse camera pose as an ordered op
+ * list, translate first (rightmost applies first), then rotate. `worldTransform` serializes
+ * this list and `worldMatrix` composes it; neither may restate the order on its own, so the
+ * DOM stage and the Three rig cannot drift apart.
+ */
+export declare function cameraOps(c: StageCamera): CameraOp[];
+/** Inverse camera pose for the world group, serialized from `cameraOps`. */
+export declare function worldTransform(c: StageCamera): string;
+export interface CameraKeyframe {
+    frame: number;
+    camera: Partial<StageCamera>;
+    /** Easing for the segment that ends at this keyframe. Linear when omitted. */
+    easing?: (t: number) => number;
+}
+export declare function resolveCamera(keyframes: CameraKeyframe[], frame: number, base?: StageCamera): StageCamera;
+/**
+ * The ordered op list as a matrix in CSS coordinates.
+ *
+ * Exported for the CSS-side ORACLE only (`scene/__oracle__/cssProjection.ts`). `worldMatrix` and
+ * `projectCss` used to live here; slice W1 moved them into the gate, because the shipped bridge is
+ * `scene/coordinates.ts`'s `F`-conjugation and a second projection in runtime reach is exactly how
+ * two conventions drift apart. `w1-css-oracle-isolation.test.mjs` walks the scene lane's transitive
+ * import graph and asserts no SCENE runtime path imports the oracle.
+ */
+export declare function cameraOpsMatrix(c: StageCamera): Matrix4;
+export interface ThreeCameraPose {
+    position: [number, number, number];
+    quaternion: [number, number, number, number];
+    fov: number;
+    aspect: number;
+    near: number;
+    far: number;
+}
+/**
+ * The same camera as a Three PerspectiveCamera pose (y-up). Camera pose C = M⁻¹ with the eye
+ * at (0,0,P); conjugating by diag(1,-1,1) converts CSS y-down to Three y-up.
+ */
+export declare function cameraToThree(c: StageCamera, width: number, height: number): ThreeCameraPose;
+/** Decision 1's default vertical FOV, in RADIANS. Degrees appear only at three's own `fov` API. */
+export declare const SCENE_DEFAULT_FOV: number;
+/**
+ * Sec.5.3's inclusive fov bounds, in radians (18deg..80deg).
+ *
+ * DECLARED HERE, ENFORCED BY W3. Nothing in W1 reads them: the renderer takes an already-valid
+ * shot, and the refusal outside these bounds is a schema refusal at `camera.fov`, which the
+ * ownership map gives to W3 along with every other refusal code. They are stated next to the
+ * camera they bound rather than invented twice, and they move with the refusal when W3 lands.
+ */
+export declare const SCENE_FOV_MIN: number;
+export declare const SCENE_FOV_MAX: number;
+/**
+ * The eye distance that makes the Z = 0 plane exactly 1:1 with reference pixels:
+ * `referenceHeight / (2 * tan(fov / 2))`. Verified by `i0ProjectionParity.test.ts`'s self-check,
+ * which projects the world origin to (960, 540) and world y = referenceHeight/2 to y = 0, exactly.
+ */
+export declare function sceneEyeDistance(referenceHeight: number, fov: number): number;
+/**
+ * An authored scene camera. `position` is ABSOLUTE (not V1's offset from the eye distance),
+ * `rotation` is radians in Euler XYZ, `fov` is radians.
+ *
+ * NOTE FOR W3: report Sec.5.3's `SceneCameraV2`. Declared here until W3 owns the wire schema.
+ */
+export interface SceneCameraV2 {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    fov: number;
+}
+/** The default camera of Sec.5.3 for one reference height. */
+export declare function defaultSceneCamera(referenceHeight: number, fov?: number): SceneCameraV2;
+/** A fiber `PerspectiveCamera`'s complete state, in output pixels. `fov` stays in RADIANS. */
+export interface SceneCameraPose {
+    position: [number, number, number];
+    quaternion: [number, number, number, number];
+    fov: number;
+    aspect: number;
+    near: number;
+    far: number;
+}
+/**
+ * The depth planes, from the REFERENCE eye distance rather than from the authored camera z.
+ *
+ * Deliberate, and it is what makes the V1 and V2 lanes comparable: V1's planes are `P/100` and
+ * `P*40` for `P = perspectiveFor(fov, outputHeight)`, a function of fov and output height alone.
+ * Deriving them from the authored camera position instead would make the two contracts disagree
+ * about depth precision on a shot whose camera has dollied, which is not a coordinate question.
+ * `referenceHeight * scale` IS the output height, so this is V1's number exactly.
+ */
+export declare const sceneCameraPlanes: typeof sceneCameraPlanesV2;
+/** An authored (Three-native) scene camera as a fiber camera pose, in output pixels. */
+export declare function sceneCameraPose(camera: SceneCameraV2, referenceHeight: number, scale: number, frame: {
+    width: number;
+    height: number;
+}): SceneCameraPose;
+/**
+ * The V1 scene camera (Y-down, degrees, `z` an OFFSET from the eye distance, rotations orbiting the
+ * origin) as the same pose, in closed form.
+ *
+ * `pose_css = Rz(rotZ)*Ry(rotY)*Rx(rotX)*T(x, y, z+P)`, and conjugating by `F` distributes over the
+ * product: `Rz(-rotZ)*Ry(rotY)*Rx(-rotX)*T(x, -y, z+P)`. The rotation is therefore an Euler in
+ * **ZYX** order, which is exactly why the V1 camera cannot be re-expressed as a V2 camera's XYZ
+ * angles and why this returns a pose rather than a `SceneCameraV2`. `x`, `y` and `z` arrive already
+ * scaled to output pixels.
+ */
+export declare function sceneCameraPoseFromV1(camera: StageCamera, referenceHeight: number, scale: number, frame: {
+    width: number;
+    height: number;
+}): SceneCameraPose;

package/dist/_members/animate/stage/dof.d.ts

@@ -0,0 +1,9 @@
+export interface FocusSpec {
+    /** World z of the focus plane (px). */
+    z: number;
+    /** Distance from the plane at which blur reaches maxBlur (px). */
+    range: number;
+    maxBlur: number;
+}
+/** Layer depth of field: blur radius for a planar layer at `layerZ`. */
+export declare function dofBlur(layerZ: number, focus?: FocusSpec): number;

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

@@ -0,0 +1,6 @@
+export { DEFAULT_CAMERA, perspectiveFor, worldTransform, resolveCamera, cameraToThree, type StageCamera, type CameraKeyframe, type ThreeCameraPose } from './camera.js';
+export { cameraOps, cameraOpsMatrix, type CameraOp } from './camera.js';
+export { SCENE_DEFAULT_FOV, SCENE_FOV_MIN, SCENE_FOV_MAX, sceneEyeDistance, defaultSceneCamera, sceneCameraPlanes, sceneCameraPose, sceneCameraPoseFromV1, type SceneCameraV2, type SceneCameraPose, } from './camera.js';
+export { CAMERA_PRESETS, dollyIn, dollyOut, drift, tiltReveal, orbit, type CameraMove, type PresetOptions } from './presets.js';
+export { dofBlur, type FocusSpec } from './dof.js';
+export { PerspectiveStage, StageLayer, ContactShadow, useStage, type StageContextValue, type PerspectiveStageProps, type StageLayerProps, type StageLayerShadow, type ContactShadowProps } from './PerspectiveStage.js';

package/dist/_members/animate/stage/presets.d.ts

@@ -0,0 +1,17 @@
+import type { CameraKeyframe } from './camera.js';
+export type CameraMove = 'static' | 'dolly-in' | 'dolly-out' | 'drift' | 'tilt-reveal' | 'orbit';
+export interface PresetOptions {
+    fov?: number;
+    /** Move magnitude: px for dolly/drift, degrees for tilt/orbit. */
+    amount?: number;
+    easing?: (t: number) => number;
+}
+type Preset = (durationInFrames: number, opts?: PresetOptions) => CameraKeyframe[];
+export declare const dollyIn: Preset;
+export declare const dollyOut: Preset;
+/** A slow lateral glide with a few degrees of orbit — nothing sits perfectly still. */
+export declare const drift: Preset;
+export declare const tiltReveal: Preset;
+export declare const orbit: Preset;
+export declare const CAMERA_PRESETS: Record<CameraMove, Preset>;
+export {};