@cueframe/kernel 0.2.2 → 0.2.3

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

@@ -0,0 +1,59 @@
+import React from 'react';
+import { type ShadowBounds } from '../../three/StudioRig.js';
+import type { SceneShotRender } from '../render.js';
+import type { SceneBackdropV2, SceneObjectV2, SceneShotSpecV2, SealedSceneShotPlanV1 } from '../../../composition/scene/index.js';
+import type { PreparedSceneSurfaceVisualV1 } from './preparedSurface.js';
+import { type SceneVideoTextureBindingV1 } from './videoBinding.js';
+/** The backdrop as CSS on the shot root. Transparent paints nothing, so the frame keeps its alpha. */
+export declare function backdropStyleV2(backdrop: SceneBackdropV2): React.CSSProperties;
+export declare function drawSceneFrameV2({ advance, invalidate, isRendering, playing, now }: {
+    advance: (timestamp: number) => void;
+    invalidate: () => void;
+    isRendering: boolean;
+    playing: boolean;
+    now: number;
+}): void;
+/** Every image slot the tree binds, with its handle resolved BEFORE any canvas mounts. */
+export declare function resolveSceneAssetsV2(layers: readonly SceneObjectV2[], assets: Record<string, unknown>): Map<string, string>;
+export interface SceneShotV2Props {
+    /** One EVALUATED frame of a new-contract shot. The caller evaluates the animation; see the contract. */
+    spec: SceneShotSpecV2;
+    assets: Record<string, unknown>;
+    render: SceneShotRender;
+    /** THE NEGATIVE CONTROL of the material-lifecycle gate, and nothing else may set it. */
+    mountSurfacesEarly?: boolean;
+    /** Complete preparation evidence authorizing omission of the authored one-frame guard. */
+    preparedPlan?: SealedSceneShotPlanV1;
+    sealedBodyTriangles?: Readonly<Record<string, number>>;
+    sealedSurfaceColors?: Readonly<Record<string, string>>;
+    preparedSurfaceVisuals?: Readonly<Record<string, PreparedSceneSurfaceVisualV1>>;
+    videoTextureBindings?: readonly SceneVideoTextureBindingV1[];
+    sealedSurfaceHandles?: Readonly<Record<string, string>>;
+    sealedShadowBounds?: ShadowBounds;
+    sealedCameraPlanes?: {
+        near: number;
+        far: number;
+    };
+}
+/**
+ * The new-contract scene-shot renderer.
+ *
+ * A pure function of (evaluated spec, output size). Reference pixels scale uniformly by output
+ * width over reference width; a mismatched aspect throws `scene_aspect_mismatch`, because output
+ * resizing changes projection and viewport and never authored geometry (Decision 1).
+ *
+ * **The three-layer finishing split, which is contract and not implementation detail.** The shot is
+ * three stacked layers over one box: the CSS backdrop, the world (one fiber canvas, one camera, one
+ * depth buffer), and the screen text as DOM. The two DOM layers go through the alpha-preserving SVG
+ * filter; the world is finished inside the focus pass's output stage, from the same numbers. **No
+ * element that contains the WebGL canvas carries a CSS `filter`** — a filtered layer holding one is
+ * what let Chromium rasterize a whole shot once at 756x413 and repeat that raster across six frames
+ * of a 390-frame render (defect D4). `w1-mixed-shot` asserts that on the served markup.
+ *
+ * What differs from V1 is only what Decision 1 changes: the camera is Three-native and absolute,
+ * angles are radians, the floor is Y-up reference units, and every object's transform is authored
+ * in Three's axes. The lighting, the rig, the device geometry, the readiness path, the focus pass
+ * and the finishing are the same code the retained baselines were measured against — which is the
+ * point, because it makes the comparison a comparison of conventions and not of two renderers.
+ */
+export declare function SceneShotV2({ spec, assets, render, mountSurfacesEarly, preparedPlan, sealedBodyTriangles, sealedSurfaceColors, preparedSurfaceVisuals, videoTextureBindings, sealedSurfaceHandles, sealedShadowBounds, sealedCameraPlanes }: SceneShotV2Props): React.JSX.Element;

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

@@ -0,0 +1,170 @@
+import React from 'react';
+import { type SceneWorldTransform } from '../coordinates.js';
+import type { PreparedSceneSurfaceVisualV1 } from './preparedSurface.js';
+import { type SceneLaptopV2, type ScenePageV2, type ScenePhoneV2, type SceneSlabV2, type SceneWorldTextV2 } from '../../../composition/scene/index.js';
+export declare const sceneDeviceResourceOwnerV1: (node: Pick<SceneLaptopV2 | ScenePhoneV2, "kind" | "id">) => string;
+/** The slab front slot is a centred contain fit inside the authored face. */
+export declare const slabContentFit: (width: number, height: number, image: {
+    width: number;
+    height: number;
+}) => import("../planeFit.js").PlaneFitResult;
+/**
+ * One new-contract object's group: the authored (Three-native) pose, and the object's opacity
+ * multiplied through every material under it.
+ *
+ * The same shape as V1's `PosedLayer` and for the same reason — the layout effect must run after
+ * the group and its content are attached and before the readiness effect draws the frame, and
+ * React runs layout effects bottom-up — but it takes an AUTHORED transform rather than a V1 one,
+ * so nothing converts anything here.
+ */
+export declare function PosedObject({ transform, scale, opacity, children }: {
+    transform: SceneWorldTransform;
+    scale: number;
+    opacity: number;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * THE LAPTOP BUILDER (plan W1 item 3).
+ *
+ * A group with an animatable hinge and the screen attached to the lid. The hinge is `DeviceMesh`'s
+ * own — the lid group pivots at the back edge of the base and carries the bezel, the screenshot
+ * plane and the glass with it — so the geometry and the materials are the ones the retained
+ * baselines were measured against, and `openAngle` drives them per frame.
+ *
+ * `openAngle` is RADIANS on the wire (report §5.5). `DeviceMesh`'s own parameter is degrees, so the
+ * conversion happens here, at the builder boundary, exactly as `fov` converts at three's API. There
+ * is one such conversion in the whole scene lane per quantity, and this is the hinge's.
+ *
+ * **THE MATERIAL-LIFECYCLE RULE (report §5.6.1), which is the reason this component can return
+ * `null`.** Three does not rebuild a shader program when `map` is assigned to an already-created
+ * material without `needsUpdate`, so a mesh mounted with `map: null` stays untextured for the
+ * WHOLE render even after the texture commits — and the render succeeds. So: a builder whose slot
+ * binding is present returns `null` until `useSceneImageTexture` has committed, and the readiness
+ * handle that hook took during render keeps the frame open meanwhile. Never
+ * `<mesh><material map={maybeNull} /></mesh>`. `w1-material-lifecycle` is the gate, and its
+ * negative control — the same fixture built with `mountEarly` — must fail it.
+ */
+export declare function LaptopObject({ node, src, screenColor, preparedSurface, scale, surfaceResourceOwner, glassOpacity, mountEarly }: {
+    node: SceneLaptopV2;
+    /** The admitted handle for the object's screen slot, resolved before the canvas mounted. */
+    src: string;
+    screenColor?: string;
+    preparedSurface?: PreparedSceneSurfaceVisualV1;
+    surfaceResourceOwner?: string;
+    scale: number;
+    /**
+     * The screen glass's opacity, in the space the caller's pipeline blends in.
+     *
+     * Defaults to the LINEAR tenth, because a scene shot composes its world in the focus pass's
+     * half-float target. A caller drawing straight onto the canvas — which is what the V1/V2
+     * comparison does on BOTH of its arms, so that the comparison is of conventions and not of
+     * pipelines — passes the encoded one. `DeviceMesh` documents the pair; this prop exists so the
+     * builder never decides the pipeline on its caller's behalf.
+     */
+    glassOpacity?: number;
+    /**
+     * THE NEGATIVE CONTROL, and nothing else may set it.
+     *
+     * `true` mounts the mesh before the texture commits, which is the defect §5.6.1 names: the
+     * material is created with `map: null`, three caches a program for it, and the later assignment
+     * never reaches the GPU. It exists so the material-lifecycle gate has a red arm — a green gate
+     * with no red control proves nothing here, because the defect produces a *successful* render.
+     */
+    mountEarly?: boolean;
+}): React.JSX.Element | null;
+/** Canonical phone builder using the same owned shell/screen/glass hierarchy as DeviceMesh. */
+export declare function PhoneObject({ node, src, screenColor, preparedSurface, scale, surfaceResourceOwner, glassOpacity, mountEarly }: {
+    node: ScenePhoneV2;
+    src: string;
+    screenColor?: string;
+    preparedSurface?: PreparedSceneSurfaceVisualV1;
+    surfaceResourceOwner?: string;
+    scale: number;
+    glassOpacity?: number;
+    mountEarly?: boolean;
+}): React.JSX.Element | null;
+/**
+ * The distance the content face sits in front of the slab's own front plane, in REFERENCE px.
+ *
+ * The body's front face is at `z = +thickness/2` exactly (`slabBodyGeometry` documents why), so a
+ * coplanar content quad would z-fight across the whole face — a shimmer that moves with the camera
+ * and that no still frame reveals. 0.6 reference px is under a tenth of the 15 px edge radius, so
+ * the face does not float off the shoulder at any yaw the shot takes, and it is comfortably more
+ * than the depth buffer's resolution at these near/far planes.
+ */
+export declare const SLAB_CONTENT_OFFSET = 0.6;
+/**
+ * THE SLAB BUILDER (plan W2 item 2).
+ *
+ * Two meshes and one group:
+ *
+ *   - the BODY: the extruded rounded solid at the frozen 24/6 tessellation, with one of the two
+ *     generated finishes. It is LIT, it casts and receives shadow, and it draws through
+ *     `takeSceneEnvironment` so the scene's environment is the material's own — the third of the
+ *     three three.js rules in `finishes.ts`.
+ *   - the FRONT FACE: the `front` slot's admitted content, on an UNLIT, colour-managed quad.
+ *
+ * **The face is unlit, and that is a contract clause rather than a look.** A4 gates content
+ * surfaces as BYTE-IDENTICAL with the lighting profile on and off, and that gate is only passable
+ * because a content face takes no light by construction: `UNLIT_COLOUR_MANAGED` carries
+ * `toneMapped: false` and a basic material. Mapping the capture onto the lit body instead would
+ * make the gate fail — one moved interior pixel means a content surface IS taking light, which is
+ * a finding and not a tolerance.
+ *
+ * **The material-lifecycle rule (report §5.6.1), same as the laptop and for the same reason.** A
+ * builder whose slot binding is present returns `null` until `useSceneImageTexture` has committed.
+ * Three does not rebuild a shader program when `map` is assigned to an already-created material
+ * without `needsUpdate`, so a mesh mounted with `map: null` stays untextured for the WHOLE render
+ * and the render SUCCEEDS. `mountEarly` is the negative control, and nothing but the
+ * material-lifecycle gate sets it.
+ *
+ * **A bare slab is a first-class case, not a missing binding.** `surfaces` absent means the body
+ * with no face, which is what the finish gates measure: a content inset covering three quarters of
+ * the face would make any luma profile a measurement of the capture rather than of the material.
+ */
+export declare function SlabObject({ node, src, frontColor, preparedSurface, scale, surfaceResourceOwner, mountEarly, expectedBodyTriangles }: {
+    node: SceneSlabV2;
+    /** The admitted handle for the `front` slot, or `undefined` for a bare slab. */
+    src: string | undefined;
+    frontColor?: string;
+    preparedSurface?: PreparedSceneSurfaceVisualV1;
+    surfaceResourceOwner?: string;
+    scale: number;
+    /** THE NEGATIVE CONTROL; see `LaptopObject`. Nothing but the material-lifecycle gate sets it. */
+    mountEarly?: boolean;
+    expectedBodyTriangles?: number;
+}): React.JSX.Element | null;
+/** Own the slab's independently replaceable GPU resources for exactly one mounted builder. */
+export declare function useOwnedSlabResources(width: number, height: number, thickness: number, cornerRadius: number, edgeRadius: number, finishName: SceneSlabV2['finish'], baseColor: string, materialOverride?: import('../../../composition/scene/index.js').SceneMaterialOverrideV2, owner?: string): {
+    geometry: import("three").ExtrudeGeometry;
+    finish: import("./finishes.js").SlabFinishMaterial;
+};
+/**
+ * A page: the bound image on an unlit, colour-managed world plane, occluding and occluded like any
+ * world surface. Same material-lifecycle rule as the laptop, for the same reason.
+ */
+export declare function PageObject({ node, src, contentColor, preparedSurface, scale, surfaceResourceOwner, mountEarly }: {
+    node: ScenePageV2;
+    src: string;
+    contentColor?: string;
+    preparedSurface?: PreparedSceneSurfaceVisualV1;
+    surfaceResourceOwner?: string;
+    scale: number;
+    /** THE NEGATIVE CONTROL; see `LaptopObject`. Nothing but the material-lifecycle gate sets it. */
+    mountEarly?: boolean;
+}): React.JSX.Element | null;
+/**
+ * World text: the typed lines and runs rasterized from the same layout and the same font the DOM
+ * path uses, on an unlit plane placed by the object's world transform.
+ *
+ * The raster itself is V1's — `useWorldTextTexture`, `worldTextLayout`, the shared raster cache and
+ * its font readiness — because the typography is not what this contract changes and a second
+ * rasterizer would be a second set of baselines. The V2 node carries exactly the typographic fields
+ * that path reads; what it does not carry is a V1 `transform`, which that path never reads.
+ */
+export declare function WorldTextObject({ node, index, scale, referenceWidth }: {
+    node: SceneWorldTextV2;
+    index: number;
+    scale: number;
+    referenceWidth: number;
+}): React.JSX.Element | null;

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

@@ -0,0 +1,152 @@
+/**
+ * The two GENERATED slab finishes — satin and brushed — and the material each one builds.
+ *
+ * **Nothing here is sampled from a photograph, and that is the point.** The spike put five
+ * photogrammetric CC0 scans on this slab and every one read as a FOUND object: weathered casting,
+ * oxidised gilt, a good powder coat that still carried the scan's own speckle. That is what a scan
+ * IS — one real, aged square metre of metal with its history in it. New hardware has no history and
+ * you cannot subtract one from the other. So every texel below is computed from a seeded PRNG,
+ * which buys three properties this lane needs:
+ *
+ *   - **no dirt**, because dirt was never generated: the only variation is the band-limited noise
+ *     these functions put there deliberately;
+ *   - **small**: generated one-channel-ish data, not four 2048 JPEGs, so the material costs
+ *     single-digit MiB against Decision 5's 256 MiB per-shot surface budget;
+ *   - **deterministic**: `mulberry32` from a fixed integer seed gives the same texels on every host
+ *     and every run. There is no `Math.random()` in this file, which is what lets gate 3's `sha256`
+ *     equality and gate 4's byte identity mean anything at all.
+ *
+ * Everything is TILEABLE by construction — the value-noise lattices index modulo their own size —
+ * so a map wraps seamlessly and the slab never shows a repeat edge.
+ *
+ * **The three three.js rules this file exists to obey.** Each is a measured defect from the spike,
+ * not a style preference, and each looks like "the material didn't load" when it is broken:
+ *
+ *   1. **Extrusion UVs are unnormalised**, so the uv coordinate IS the world pixel. `repeat` is
+ *      therefore `1 / (tile size in world px)`. A `repeat` of 1 would tile a map ~1040 times across
+ *      this slab and grind it into grey noise. See `slabGeometry.ts`.
+ *   2. **Three MULTIPLIES the scalar by the map**: `roughness · roughnessMap.g`,
+ *      `metalness · metalnessMap.b`, `color · map`. A scalar and its map are therefore declared
+ *      TOGETHER, in one place, by `slabFinishMaterial` — leaving a `metalness: 0` in place beside a
+ *      metalness map silently multiplies it to zero and gives back a dielectric.
+ *   3. **`envMapIntensity` only reaches a frame through `takeSceneEnvironment`.** Three uploads it
+ *      only for a material carrying its OWN `envMap`; a material lit by `scene.environment` takes
+ *      the other branch and has `scene.environmentIntensity` written over that uniform. The slab
+ *      body therefore draws through that hook. Note that this makes the knob REAL, not authorable:
+ *      report §5.7 keeps `envMapIntensity` out of the contract entirely, because environment
+ *      strength is `environment.intensity` and nothing else.
+ */
+import { DataTexture, MeshPhysicalMaterial } from 'three';
+import type { SceneMaterialOverrideV2 } from '../../../composition/scene/index.js';
+import { type SceneActualResourceRegistrarV1 } from './runtimeAllocations.js';
+/** The two finishes report §5.5 names. `satin` is the default. */
+export type SceneSlabFinish = 'satin' | 'brushed';
+export declare const SLAB_FINISHES: readonly SceneSlabFinish[];
+/**
+ * The satin micro-roughness map.
+ *
+ * **The encoding, which is rule 2 in its sharpest form.** Three computes roughness as
+ * `material.roughness · roughnessMap.g`, and an 8-bit map can only carry [0, 1] — so a map meaning
+ * "1.0 plus or minus `amp`" cannot be stored directly. Instead the map holds
+ * `(1 + amp·n) / (1 + amp)`, which lands in `[(1−amp)/(1+amp), 1]`, and the caller sets
+ * `material.roughness = base · (1 + amp)`. The product is then exactly `base · (1 + amp·n)`.
+ * `satinRoughnessScalar` returns that scalar so the two halves cannot drift apart, and
+ * `slabFinishMaterial` is the only place either is written.
+ *
+ * The noise is deliberately LOW frequency: a slow undulation reads as an unevenly cured satin coat,
+ * where a high-frequency version of the same modulation reads as sensor grain — the exact "grungy"
+ * note the generated finishes exist to remove.
+ */
+export declare function satinRoughnessMap(size: number, tilePx: number, amp: number, seed: number): DataTexture;
+/** The scalar half of the satin encoding above. Never written anywhere else. */
+export declare const satinRoughnessScalar: (base: number, amp: number) => number;
+/**
+ * A barely-there ISOTROPIC anodised grain, used by satin and as brushed's CLEARCOAT normal.
+ *
+ * The spike's first cut used a 128-cell lattice at strength 6 and it was wrong in the way the
+ * generated finishes exist to fix: a 128 lattice over a 512 px map tiled every 512 world px puts a
+ * feature every 4 world px, which at a ~1:1 projection is a 4 px stipple — visible orange peel,
+ * i.e. texture, i.e. grunge. 256/512 cells put it at 1–2 world px, below what the eye resolves as a
+ * pattern, and strength 1.2 rather than 6 makes it a sheen modulation instead of a relief.
+ */
+export declare const anodisedGrainNormal: (size: number, tilePx: number, seed: number) => DataTexture;
+/**
+ * Fine parallel brushing along the slab's LONG axis.
+ *
+ * The lattices are 512 wide and 6 tall: across the slab the height changes every ~2 texels, down it
+ * every ~170, so the gradient is almost entirely in x and the surface normal tilts side to side
+ * only. That is what stretches a point highlight into a line running down the slab — and because
+ * `uv`'s v axis is the slab's local y, the streaks run along the long axis, which is where the
+ * direction has to be for a brushed panel to read as machined rather than scratched.
+ *
+ * **Strength is 2.5, down from a first cut at 10, and the difference was a rim.** At 10 the lines
+ * read as tooling marks, and they DESTROYED the silhouette: the shoulder is an arc whose normal
+ * sweeps 90° in x, and a normal map perturbing x every ~2 units puts seven full cycles across it,
+ * scrambling exactly the axis the lit edge depends on. Measured, the band went to 0 px at 0.21×
+ * body — the edge read DARKER than the face. At 2.5 the direction still reads and the shoulder
+ * survives, which is what the `studio-edge` brushed gate then measures at 250.00 @ 2 px.
+ */
+export declare const brushedNormal: (size: number, tilePx: number, seed: number) => DataTexture;
+/**
+ * Every number either finish is built from, in ONE table.
+ *
+ * Satin is the original three-card acceptance material. Brushed retains W2's separately measured
+ * profile. The seeds are named constants rather than literals so byte-identity gates have one
+ * place to look.
+ */
+export declare const SLAB_FINISH_SPEC: {
+    /** The W2 brushed defaults; satin overrides the original recipe's material fields below. */
+    readonly common: {
+        readonly clearcoat: 0.6;
+        readonly clearcoatRoughness: 0.22;
+        /** Rule 2: declared here beside every map, so no map is silently multiplied by a stale scalar. */
+        readonly metalness: 0;
+        readonly mapSize: 2048;
+    };
+    readonly satin: {
+        /** The *base* roughness. The scalar three receives is `satinRoughnessScalar(base, amp)`. */
+        readonly roughnessBase: 0.32;
+        readonly roughnessAmp: 0.03;
+        readonly roughnessTilePx: 1024;
+        readonly roughnessSeed: 6221057;
+        readonly roughnessMapSize: 512;
+        readonly normalTilePx: 512;
+        readonly normalSeed: 6221058;
+        readonly normalMapSize: 512;
+        readonly normalScale: 0.12;
+        readonly metalness: 0.22;
+        readonly clearcoat: 1;
+        readonly clearcoatRoughness: 0.12;
+        readonly envMapIntensity: 0.14;
+    };
+    readonly brushed: {
+        readonly roughness: 0.28;
+        readonly normalTilePx: 3;
+        readonly normalSeed: 7;
+        /** Three's tangent/local-x is the slab's short axis, so rotate the BRDF onto long local-y. */
+        readonly anisotropy: 0.65;
+        readonly anisotropyRotation: number;
+        readonly clearcoatNormalTilePx: 9;
+        readonly clearcoatNormalSeed: 13;
+    };
+};
+/** The maps one finish owns, kept together so disposal cannot miss one. */
+export interface SlabFinishMaterial {
+    material: MeshPhysicalMaterial;
+    dispose(): void;
+}
+/**
+ * Build the material for one finish, with every scalar declared beside the map it multiplies.
+ *
+ * `baseColor` is the slab's flat base; there is no colour map, so it is not multiplied by anything
+ * and reaches the frame as written.
+ */
+export declare function slabFinishMaterial(finish: SceneSlabFinish, baseColor: string, override?: SceneMaterialOverrideV2, owner?: string, registerActual?: SceneActualResourceRegistrarV1): SlabFinishMaterial;
+/**
+ * The declared GL bytes one finish's generated maps allocate, for Decision 5's ledger.
+ *
+ * `Σ_l max(1, floor(W/2^l)) · max(1, floor(H/2^l)) · bytesPerTexel` across the full mip chain, at
+ * the actual declared storage format (RGBA8, 4 B/texel). Declared BEFORE allocation, which is what
+ * Decision 5 asks builders for; the runtime instrumentation checks the allocation against it.
+ */
+export declare function slabFinishDeclaredBytes(finish: SceneSlabFinish): number;

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

@@ -0,0 +1,119 @@
+/**
+ * A4's two refusals, and the rig identity the profile is sealed into.
+ *
+ * **NOTE FOR W3.** Refusal CODES and their paths are wire contract and belong in
+ * `@cueframe/composition/scene`'s schema module when W3 lands (plan ownership map). They are here
+ * because W2 has to enforce them before that schema exists, and because enforcement without a
+ * refusal is a default, which is the class of quiet wrongness this contract exists to remove. The
+ * two codes, their paths and their message shapes move unchanged.
+ *
+ * **NOTE FOR W4.** `sceneRigIdentityV2` is what preparation seals into the plan's `rigIdentity`
+ * (report §5.9). It is pure so that W4 can call it, and so that a reviewer can check that
+ * `lightingProfile` is genuinely part of the identity a capture and a ledger key on.
+ */
+import { STUDIO_EDGE_INTENSITY, STUDIO_EDGE_LIGHTS, STUDIO_SHADOW_MAP_BUDGET, type SceneLightingProfile, type ShadowBounds, type StudioPreset } from '../../three/StudioRig.js';
+import { PHOTOGRAPHIC_STUDIO_RIG_FACTS, PHOTOGRAPHIC_STUDIO_RIG_ID } from './PhotographicStudioRig.js';
+import type { SceneGeneratedStudioRigV2, ScenePhotographicStudioRigV1 } from '../../../composition/scene/index.js';
+export type SceneLightingRefusalCode = 'scene_lighting_profile_unsupported' | 'scene_rig_unsupported' | 'scene_photographic_rig_field_unsupported' | 'scene_object_light_field_unsupported';
+export type SceneRigKindV2 = 'studio' | typeof PHOTOGRAPHIC_STUDIO_RIG_ID;
+/** Admit the absent legacy kind or the one fixed photographic rig; nothing accepts a custom HDRI. */
+export declare function admitSceneRigKind(value: unknown, path?: string): SceneRigKindV2;
+/** Admit the complete rig object. The photographic arm has exactly one key and no knobs. */
+export declare function admitSceneRigV2(rig: unknown, path?: string): SceneRigKindV2;
+/** A typed refusal with the path the author's document is refused AT. */
+export declare class SceneLightingRefusal extends Error {
+    readonly code: SceneLightingRefusalCode;
+    readonly path: string;
+    readonly detail: Record<string, unknown>;
+    constructor(code: SceneLightingRefusalCode, message: string, path: string, detail: Record<string, unknown>);
+}
+/**
+ * Admit a shot's `lightingProfile`, or refuse it by name.
+ *
+ * Any value that is not one of the two is `scene_lighting_profile_unsupported` at
+ * `environment.lightingProfile`, naming the value AND the two legal profiles — a refusal that does
+ * not say what IS legal makes an author guess, and the legal set here is two strings long.
+ *
+ * `undefined` is the default, `'studio'`. `null` is not: an explicitly null profile is an author
+ * saying something, and what they said is not a profile.
+ */
+export declare function admitLightingProfile(value: unknown, path?: string): SceneLightingProfile;
+/**
+ * Every field name an object might try to carry a light with — refused at the object's own path.
+ *
+ * **This list is the load-bearing half of A4.** The ruling is that adding or removing slabs never
+ * changes the light count: it is two under `studio-edge` whether the shot holds one slab, twelve or
+ * none, and zero extra under `studio`. That is only true if no object can contribute a light, so
+ * there is no `slabEdgeLighting`, no per-object light, no position and no intensity anywhere in
+ * `SceneObjectV2` — and an author writing one gets a refusal rather than a field that is ignored.
+ *
+ * `slabEdgeLighting` and `slabEdgeBoost` are named explicitly because the I0 PROTOTYPE carried
+ * them: arm (a) scaled the rig's own rim light per slab, and a document written against that
+ * prototype would otherwise be silently accepted with its lighting dropped on the floor.
+ */
+export declare const SCENE_OBJECT_LIGHT_FIELDS: readonly string[];
+/**
+ * Refuse any light-shaped field on an object, at `layers.N.<field>`.
+ *
+ * Returns the object unchanged when it carries none, so a caller can use it as a gate in an
+ * expression. `index` is used for the path when the node has no id yet.
+ */
+export declare function assertNoObjectLightField(node: object, layerPath: string): void;
+/** Report §5.9's `rigIdentity`: what a capture and a ledger key on. */
+export interface SceneGeneratedStudioRigIdentityV2 {
+    lightingProfile: SceneLightingProfile;
+    preset: StudioPreset;
+    intensity: number;
+    floorY: number;
+    shadowOpacity: number;
+    shadowMapEdge: number;
+    environmentVersion: number;
+}
+export interface ScenePhotographicStudioRigIdentityV1 {
+    rigId: typeof PHOTOGRAPHIC_STUDIO_RIG_ID;
+    hdriSha256: string;
+    pmremVersion: string;
+    lightingVersion: number;
+    worldScale: number;
+    lightLayout: typeof PHOTOGRAPHIC_STUDIO_RIG_FACTS.studioLights;
+    edgeLightLayout: typeof PHOTOGRAPHIC_STUDIO_RIG_FACTS.edgeLights;
+    environmentIntensity: 1;
+    floor: 'none';
+    shadows: 'none';
+    retainedGpuBytes: number;
+    preparationPeakGpuBytes: number;
+}
+export type SceneRigIdentityV2 = SceneGeneratedStudioRigIdentityV2 | ScenePhotographicStudioRigIdentityV1;
+/**
+ * The generated `RoomEnvironment`'s version.
+ *
+ * Bumped when the environment three generates changes — a different room, a different PMREM
+ * roughness, a three upgrade that moves either. It is in the identity because the environment is
+ * what lights every reflective surface in the shot, so a changed one is a changed picture, and a
+ * capture reused across it would be a stale one.
+ */
+export declare const SCENE_ENVIRONMENT_VERSION = 1;
+/**
+ * Seal the rig into an identity — including `lightingProfile`, which is the clause A4 adds.
+ *
+ * **Not animatable.** A profile is a property of the shot: a light count that changes mid-shot is
+ * not a rig, and an identity that a shot changes halfway through is not an identity. `intensity`
+ * IS animatable (report §5.7), so what is sealed here is its value at frame 0, which is what the
+ * sealed plan's `rigIdentity` carries and what W4 must keep doing.
+ */
+export declare function sceneRigIdentityV2(rig: ScenePhotographicStudioRigV1, worldScale: number, shadowBounds?: ShadowBounds): ScenePhotographicStudioRigIdentityV1;
+export declare function sceneRigIdentityV2(rig: SceneGeneratedStudioRigV2, worldScale: number, shadowBounds?: ShadowBounds): SceneGeneratedStudioRigIdentityV2;
+/**
+ * What the profile allocates: **nothing**, and this function says so as an assertion rather than
+ * leaving it to be inferred.
+ *
+ * The two `studio-edge` lights cast no shadow, so they allocate no shadow map and no render target.
+ * Report §4.2's ledger is identical under both profiles and W7's totals do not move. "Two more
+ * lights" reads like a cost, and here it is not one; the gate that proves it is the byte-equality
+ * of every retained region assertion between the two profiles.
+ */
+export declare function lightingProfileDeclaredBytes(_profile: SceneLightingProfile): number;
+/** A shot's total light count under a profile: the rig's three, plus the profile's. */
+export declare function sceneLightCount(profile: SceneLightingProfile, objectCount: number): number;
+export { STUDIO_EDGE_LIGHTS, STUDIO_EDGE_INTENSITY, STUDIO_SHADOW_MAP_BUDGET };
+export type { SceneLightingProfile };

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

@@ -0,0 +1,4 @@
+import { type WebGLRenderer } from 'three';
+import { type SceneActualResourceRegistrarV1 } from './runtimeAllocations.js';
+/** Observe PMREM's internal targets at the renderer binding that precedes their first allocation. */
+export declare function withObservedPmremTargetsV1<T>(renderer: WebGLRenderer, owner: string, build: () => T, registerActual?: SceneActualResourceRegistrarV1): T;

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

@@ -0,0 +1,32 @@
+import { type SceneBuilderAllocationDescriptorV1, type SceneBuilderDescriptorV1, type SceneObjectV2, type SceneSlabV2 } from '../../../composition/scene/index.js';
+import { type ShadowBounds } from '../../three/StudioRig.js';
+import type { SceneGeneratedStudioRigV2 } from '../../../composition/scene/index.js';
+export { photographicStudioPreparationFactsV1, sceneFocusPreparationAllocationsV1, } from '../../../composition/scene/index.js';
+/** Facts measured from the same Three geometry constructor used by SlabObject. */
+export declare function sceneSlabPreparationFactsV1(slab: SceneSlabV2): {
+    bodyTriangles: number;
+    allocations: readonly SceneBuilderAllocationDescriptorV1[];
+};
+/** The persistent float grain table allocated by FocusResources when post processing is active. */
+export declare function sceneGrainPreparationAllocationV1(): SceneBuilderAllocationDescriptorV1;
+export declare function sceneGrainPreparationCpuAllocationV1(): SceneBuilderAllocationDescriptorV1;
+export declare function generatedStudioPreparationFactsV1(rig: SceneGeneratedStudioRigV2, worldScale: number, bounds: ShadowBounds, width: number, height: number): {
+    identity: import("./lighting.js").SceneGeneratedStudioRigIdentityV2;
+    allocations: SceneBuilderAllocationDescriptorV1[];
+};
+/** Complete descriptor facts measured from the same constructors mounted by the production builders. */
+export declare function scenePresetBuilderDescriptorV1(object: Exclude<SceneObjectV2, {
+    kind: 'group';
+} | {
+    kind: 'text';
+    space: 'screen';
+}>, context?: {
+    referenceSize: {
+        width: number;
+        height: number;
+    };
+    output: {
+        width: number;
+        height: number;
+    };
+}): SceneBuilderDescriptorV1;

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

@@ -0,0 +1,17 @@
+import type { Texture } from 'three';
+/**
+ * A surface whose bytes have already reached the shared Three consumer.
+ * The producer owns and disposes textures; builders only retain the reference while mounted.
+ */
+export type PreparedSceneSurfaceVisualV1 = {
+    kind: 'texture';
+    texture: Texture;
+    readiness: 'committed';
+} | {
+    kind: 'color';
+    color: string;
+};
+export declare function preparedSurfaceDeviceProps(surface: PreparedSceneSurfaceVisualV1 | undefined): {
+    screen: Texture | null;
+    screenColor?: string;
+};

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

@@ -0,0 +1,2 @@
+/** Canonical portable resolution logic lives with the authored scene contract. */
+export * from '../../../composition/scene/index.js';

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

@@ -0,0 +1,5 @@
+import type { WebGLRenderer } from 'three';
+type Subscriber = (target: Parameters<WebGLRenderer['setRenderTarget']>[0]) => void;
+/** One wrapper per renderer; subscriptions detach safely in any order. */
+export declare function subscribeSceneRenderTargetsV1(renderer: WebGLRenderer, subscriber: Subscriber): () => void;
+export {};

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

@@ -0,0 +1,55 @@
+import type { SealedSceneShotPlanV1 } from '../../../composition/scene/index.js';
+import { type ReactNode } from 'react';
+export interface SceneRuntimeAllocationSnapshotV1 {
+    createdPlans: number;
+    disposedPlans: number;
+    livePlans: number;
+    liveContextGlBytes: number;
+    liveCpuBytes: number;
+    peakGlBytesIncludingPreparation: number;
+    peakDeclaredLiveBytes: number;
+    actualCreatedResources: number;
+    actualDisposedResources: number;
+    actualLiveGlBytes: number;
+    actualLiveCpuBytes: number;
+    actualPeakLiveBytes: number;
+    actualLiveRows: readonly SceneActualResourceReceiptV1[];
+}
+export interface SceneActualResourceRowV1 {
+    owner: string;
+    name: string;
+    domain: 'gl' | 'cpu';
+    bytes: number;
+    width?: number;
+    height?: number;
+    samples?: number;
+    byteLength?: number;
+    /** Measured internal target whose installed Three name is not a wire allocation name. */
+    evidenceOnly?: boolean;
+}
+export interface SceneActualResourceReceiptV1 extends SceneActualResourceRowV1 {
+    resourceId: number;
+}
+export type SceneActualResourceRegistrarV1 = (object: object, rows: readonly SceneActualResourceRowV1[]) => () => void;
+export declare function sceneActualResourceRegistrarForMountV1(mountId: number): SceneActualResourceRegistrarV1;
+/** Returns a registrar bound to a pure token; receipts begin only after its boundary commits. */
+export declare function useSceneActualResourceRegistrarV1(): SceneActualResourceRegistrarV1;
+/** Plan replacement remounts one committed owner; render and discarded trees emit no receipts. */
+export declare function SceneRuntimeAllocationBoundaryV1({ plan, children }: {
+    plan: SealedSceneShotPlanV1;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<{
+    plan: SealedSceneShotPlanV1;
+    children?: ReactNode;
+}>;
+export declare function sceneRuntimeAllocationSnapshotV1(): Readonly<SceneRuntimeAllocationSnapshotV1>;
+/** Reset is test/host-cycle instrumentation only; mounted resources must be gone first. */
+export declare function resetSceneRuntimeAllocationCountersV1(): void;
+/** Register measured storage beside a real owned object; release after its actual dispose succeeds. */
+export declare function registerActualSceneResourcesV1(object: object, rows: readonly SceneActualResourceRowV1[], mountId?: number): () => void;
+/** Called by the actual prepared scene mount and released by its layout-effect cleanup. */
+export declare function reserveSceneRuntimeAllocationV1(plan: SealedSceneShotPlanV1): {
+    mountId: number;
+    release: () => void;
+};
+export declare function acquireSceneRuntimeAllocationV1(plan: SealedSceneShotPlanV1): () => void;

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

@@ -0,0 +1,23 @@
+import type { ShadowBounds } from '../../three/StudioRig.js';
+import type { SceneObjectV2 } from '../../../composition/scene/index.js';
+/**
+ * The shot's shadow allocation, in REFERENCE units, from the shot's own sweep.
+ *
+ * Shot-level by construction: the caller hands every evaluated frame it wants covered — in
+ * practice the extremes of its animation, which is what it knows and what W4's preparation will
+ * seal — and the union of them is one allocation that cannot change size mid-render. A frustum
+ * recomputed from the frame being drawn would resize the shadow map as the shot ran, and the
+ * contact band would move with it.
+ *
+ * Pages and world text contribute coverage although they do not cast: only device shells set
+ * `castShadow`, and an unlit plane has no shadow to place. Including them can only grow the
+ * frustum — never shrink it — so the receiving floor under a page stays inside the caster's view.
+ *
+ * The frame term is the authored frame at z = 0, down to the floor when the floor lies below it,
+ * exactly as V1's `shotShadowBounds` computes it. It assumes the camera looks at the frame plane
+ * head-on; a camera pushed far off axis is covered only through the objects it can see.
+ */
+export declare function sceneShadowBoundsV2(samples: readonly (readonly SceneObjectV2[])[], referenceSize: {
+    width: number;
+    height: number;
+}, floorY: number): ShadowBounds;