@cueframe/kernel 0.2.1 → 0.2.3

package/dist/_members/animate/three/DeviceMesh.d.ts

@@ -0,0 +1,256 @@
+import { ExtrudeGeometry, Shape } from 'three';
+import type { BufferGeometry, Camera, Material, Scene, Texture, WebGLRenderer } from 'three';
+import { type SceneDeviceDimensionsV1, type SceneLaptopLayoutV1 } from '../../composition/scene/index.js';
+import type { SceneMaterialOverrideV2 } from '../../composition/scene/index.js';
+import { type SceneActualResourceRegistrarV1 } from '../scene/v2/runtimeAllocations.js';
+export type DeviceKind = 'laptop' | 'phone';
+export interface DeviceDimensions extends SceneDeviceDimensionsV1 {
+    /** lid/phone width, lid/phone height, shell thickness, base depth (laptop), screen inset, corner radius — px */
+    w: number;
+    h: number;
+    t: number;
+    d: number;
+    screenInset: number;
+    radius: number;
+}
+export declare function deviceDimensions(kind: DeviceKind, width: number): DeviceDimensions;
+/**
+ * Where a laptop's parts sit inside its own group, in Three axes and the same units as `width`.
+ *
+ * The one statement of this layout. It was hand-copied into three places — the mesh itself, the
+ * scene's shadow bounds and the device-showcase primitive — and a change to any one of them
+ * silently moved the shadow or the floor of the others. All three now read this, the primitive
+ * through the package barrel, so there is nothing left to keep in step by hand.
+ */
+export interface LaptopLayout extends SceneLaptopLayoutV1 {
+    /** The base's centre inside the device group. */
+    baseY: number;
+    /** The hinge above the base's centre: the base's top face. */
+    hingeFromBaseY: number;
+    /** The hinge behind the base's centre: the base's back edge. */
+    hingeZ: number;
+    /** The hinge inside the device group. */
+    hingeY: number;
+    /** The lid's centre above the hinge, before the lid swings. */
+    lidCentreY: number;
+    /** The base's underside — what rests on the floor. */
+    bottomY: number;
+}
+export declare function laptopLayout(dim: DeviceDimensions): LaptopLayout;
+/**
+ * The screen's glass overlay: how much of its own reflection it lays over the screenshot.
+ *
+ * The plane is a sheen, and it is authored as a tenth — but a tenth of what, in which space? That
+ * depends on the pipeline the mesh is drawn through, and there are two of them, so there are two
+ * numbers and every caller says which one it is blending in.
+ *
+ * `DEVICE_GLASS_OPACITY_ENCODED` is the authored tenth itself, and it is what a mesh drawn
+ * straight onto the canvas wants: WebGL blends on the canvas's stored sRGB bytes, clamped to
+ * white, so `0.10` there is a tenth of an encoded white and lifts a black screen pixel to sRGB 25.
+ * `device-showcase` is that pipeline.
+ *
+ * `DEVICE_GLASS_OPACITY_LINEAR` is the same tenth for a pipeline that blends in linear light. A
+ * scene shot composes its world in the focus pass's half-float target — the only space a
+ * depth-aware blur can average colour in — where `0.10` would be a tenth of the reflection's
+ * *radiance*, unclamped. Measured through the lane, that reflection is 1.09 on a lid tilted ten
+ * degrees back (it catches the room's ceiling) and 0.027 on an upright one, so a tenth of it laid
+ * sRGB 94 over a screenshot's black and cost the gated card its colours. The tenth is therefore
+ * carried across rather than re-tuned: a tenth of an encoded white is `srgbToLinear(0.10) =
+ * 0.0100` of a linear one. `DeviceMesh.test.ts` pins both — the encoded one to the authored
+ * decimal, the linear one to three's own transfer function.
+ *
+ * The two are not interchangeable, so `DeviceMesh` takes the number as a prop and every caller
+ * names the constant it means. The prop defaults to the encoded one because that is what a mesh
+ * drawn with no render target bound blends in, which is every caller but the scene shot — and the
+ * scene shot is the one pipeline that has to say otherwise, which it does, in `SceneWorld`. That
+ * is the defect this pair replaces: one shared constant, moved into linear light for the scene
+ * lane, silently taking nine tenths of the sheen off `device-showcase`, whose own gate cannot see
+ * a reflection that faint.
+ *
+ * The albedo is three's default white, in both, and that is a correction of its own. The round
+ * that moved this shot into linear light also set the albedo to black, on the reasoning that glass
+ * has no diffuse albedo and a `meshPhysicalMaterial` at white shades a full diffuse lobe worth 2.66
+ * of linear radiance — "0.10 of that is 0.27 of linear white over the screenshot, sRGB 141 on a
+ * black pixel". That measurement was taken in a pipeline that had lost its tone curve and was still
+ * blending the tenth as if it were a linear coverage. With the curve applied by the material and
+ * the tenth carried across, the same white albedo lays `srgbToLinear(0.10) x ACES(2.66) = 0.0092`
+ * of linear white on a black screen pixel — sRGB **24**, against the 25 the shot was authored with.
+ * The albedo was never the problem; it was compensating for the two things that were, and with them
+ * fixed it over-corrected: black albedo *and* the linear carry together took the sheen down by
+ * three orders of magnitude, to at most one code, which is no sheen at all. Measured consequence:
+ * the screenshot was reaching the frame raw-saturated, and 4:2:0 chroma subsampling costs twice as
+ * much on it (the acceptance evidence's concurrency row, 99.9th-percentile luma 13 against a bound
+ * of 12; 7.5 with the sheen restored). The physical argument stands on its own terms — a real sheet
+ * of glass has no diffuse lobe — but this plane is an authored veil, not a simulation, and the
+ * authored veil is a tenth of a white one.
+ */
+export declare const DEVICE_GLASS_OPACITY_ENCODED = 0.1;
+/** The tenth above for a pipeline that blends in linear light; see `DEVICE_GLASS_OPACITY_ENCODED`. */
+export declare const DEVICE_GLASS_OPACITY_LINEAR: number;
+/**
+ * Every lit material this mesh draws, enumerated once, each one tone-mapping itself.
+ *
+ * The enumeration is the point. Three applies `renderer.toneMapping` only to a material drawn
+ * with no render target bound (see `toneMapping.ts`), and a scene shot draws its whole world into
+ * one — so anything in here that did not carry `SELF_TONE_MAPPED` would quietly lose the ACES
+ * roll-off in a scene shot and clip instead, while keeping it in `device-showcase`. Listing them
+ * as data rather than spreading the props across the tree below is what lets a test walk the whole
+ * set and check the compiled fragment of each.
+ *
+ * The unlit materials are deliberately not here and must not be added: the screenshot plane and
+ * its black stand-in below, and `UnlitPlane`'s page and world-text planes, are colour-managed
+ * surfaces the contract promises to leave exactly as authored. They carry `toneMapped: false` with
+ * no injection, so no curve touches them under either pipeline.
+ *
+ * `color` is left off the two shells because it is the caller's `finish`, and off the glass's
+ * `opacity` because that is the per-pipeline tenth above.
+ */
+export declare const DEVICE_LIT_MATERIALS: {
+    /** The phone's shell: `meshPhysicalMaterial`, the caller's finish. */
+    readonly phoneShell: {
+        readonly metalness: 0.85;
+        readonly roughness: 0.32;
+        readonly clearcoat: 0.5;
+        readonly clearcoatRoughness: 0.2;
+        readonly toneMapped: false;
+        readonly onBeforeCompile: typeof import("./toneMapping.js").toneMapInTheMaterial;
+    };
+    /** The laptop's base and its lid, which take the same finish and the same material. */
+    readonly laptopShell: {
+        readonly metalness: 0.85;
+        readonly roughness: 0.35;
+        readonly clearcoat: 0.4;
+        readonly toneMapped: false;
+        readonly onBeforeCompile: typeof import("./toneMapping.js").toneMapInTheMaterial;
+    };
+    /** The keyboard well on the laptop's base: `meshStandardMaterial`. */
+    readonly keyboard: {
+        readonly color: "#111114";
+        readonly roughness: 0.9;
+        readonly metalness: 0.1;
+        readonly toneMapped: false;
+        readonly onBeforeCompile: typeof import("./toneMapping.js").toneMapInTheMaterial;
+    };
+    /** The trackpad in front of it: `meshStandardMaterial`. */
+    readonly trackpad: {
+        readonly color: "#1a1a1f";
+        readonly roughness: 0.6;
+        readonly metalness: 0.3;
+        readonly toneMapped: false;
+        readonly onBeforeCompile: typeof import("./toneMapping.js").toneMapInTheMaterial;
+    };
+    /** The dark bezel behind the lid's screen: `meshStandardMaterial`. */
+    readonly bezel: {
+        readonly color: "#050507";
+        readonly roughness: 0.5;
+        readonly toneMapped: false;
+        readonly onBeforeCompile: typeof import("./toneMapping.js").toneMapInTheMaterial;
+    };
+    /**
+     * The screen's glass sheen: `meshPhysicalMaterial`, default albedo, per-pipeline opacity.
+     *
+     * `envMapIntensity` is the one number in this table that does not reach a frame on its own —
+     * it needs `takeSceneEnvironment` on the mesh that draws it. See that function.
+     */
+    readonly glass: {
+        readonly transparent: true;
+        readonly roughness: 0.06;
+        readonly metalness: 0;
+        readonly envMapIntensity: 1.2;
+        readonly toneMapped: false;
+        readonly onBeforeCompile: typeof import("./toneMapping.js").toneMapInTheMaterial;
+    };
+};
+/**
+ * Hand a lit material the environment of the scene being drawn, so its own `envMapIntensity` is
+ * the one that reaches the frame.
+ *
+ * Three uploads a material's `envMapIntensity` only for a material that carries its OWN `envMap`:
+ * `WebGLMaterials.refreshMaterialUniforms` guards every assignment of it with
+ * `if ( material.envMap )`. A material lit by `scene.environment` alone takes the other branch
+ * entirely — `WebGLRenderer.setProgram` writes `scene.environmentIntensity` over that uniform for
+ * any standard/lambert/phong material whose `envMap` is null (three 0.183.2,
+ * `WebGLRenderer.js:2602`). `StudioRig` sets `scene.environment` and nothing in either lane gives
+ * a material an `envMap`, so the glass's authored 1.2 was a number nothing read from the day the
+ * rig was written: the sheen was drawn at the scene's intensity of 1, and a reviewer signing off
+ * the rendered frame could not have seen the difference. This is what makes the knob real.
+ *
+ * Assigning the scene's own environment costs nothing else. `WebGLPrograms` resolves a material's
+ * environment as `material.envMap || scene.environment`, so the resolved texture, the shader
+ * defines and the cached program are the ones already in use and nothing recompiles; the material
+ * simply stops taking the scene's intensity and starts taking its own. `envMapRotation` swaps from
+ * the scene's to the material's, and both are the identity here.
+ *
+ * It goes through three's own per-draw hook rather than through a layout effect because the
+ * environment is created in `StudioRig`'s layout effect, and this mesh mounts on its own schedule —
+ * a device layer mounts only once its screenshot has committed, which is a later commit than the
+ * rig's. `onBeforeRender` is handed the scene being drawn and runs immediately before that draw's
+ * `setProgram` (`WebGLRenderer.renderObject`), so the material tracks whatever the scene's
+ * environment is at the moment it is drawn — mount order cannot get this wrong, and a rig mounted
+ * with `environment={false}`, or unmounted, takes the material back to null with it.
+ */
+export declare function takeSceneEnvironment(_renderer: WebGLRenderer, scene: Scene, _camera: Camera, _geometry: BufferGeometry, material: Material): void;
+/** Lid rotation about the hinge: 90° open is vertical; 0° lies on the base (rotated toward +z). */
+export declare function lidRotationX(openAngle: number): number;
+/** A rounded rectangle centred on the origin, ready to extrude. Pure: no DOM, no renderer. */
+export declare function roundedRectShape(w: number, h: number, radius: number): Shape;
+/**
+ * The phone shell, deliberately NOT a RoundedBoxGeometry like the laptop.
+ *
+ * RoundedBoxGeometry clamps its radius to half the *thinnest* axis, so on an 11px
+ * slab the phone's 49px corner radius collapses to ~5px and the body reads as a
+ * hard-cornered brick. Extruding a rounded rect rounds x and y at the radius asked
+ * for and leaves the edge bevel independent of it. The laptop keeps
+ * RoundedBoxGeometry: its requested radius clamps to ~6px, which is imperceptible
+ * at lid scale, and a box is the right silhouette for a lid and a base. Do not
+ * unify the two back together.
+ *
+ * ExtrudeGeometry expands the body outward by `bevelSize` and runs z from
+ * -bevelThickness to depth+bevelThickness, so the core shape is inset by the bevel
+ * and the result translated back by depth/2. The outer box is then exactly
+ * w × h × t centred on the origin — the same contract as the RoundedBoxGeometry it
+ * replaces, so the screen and glass planes at z = t/2 + ε still sit just in front
+ * of the face.
+ */
+export declare function phoneShellGeometry(w: number, h: number, t: number, radius: number): ExtrudeGeometry;
+/**
+ * How far in front of the shell's front face each of the three stacked planes sits, in the same
+ * units as `width`. Small and fixed: enough to beat depth-fighting at any device scale, not enough
+ * to read as a gap.
+ *
+ * Exported because the screen's is not only this mesh's business. `mixedShot.test.ts` measures
+ * where the laptop's screen surface actually lands in camera space, to check that the fixture
+ * holds its focus on the screen rather than on the device layer's origin, and it has to place the
+ * plane exactly where this mesh places it. It used to restate `0.6` as a hand-copied literal; a
+ * change here would have moved the screen and left the measurement describing where it used to be.
+ */
+export declare const DEVICE_PLANE_OFFSETS: {
+    /** The lid's dark bezel, behind the screenshot. */
+    readonly bezel: 0.3;
+    /** The screenshot itself. */
+    readonly screen: 0.6;
+    /** The glass sheen over it. */
+    readonly glass: 1.2;
+};
+export interface DeviceMeshProps {
+    kind: DeviceKind;
+    screen: Texture | null;
+    /** A sealed color surface. Mutually exclusive with `screen`. */
+    screenColor?: string;
+    materialOverrides?: Readonly<Record<string, SceneMaterialOverrideV2 | undefined>>;
+    finish?: string;
+    /**
+     * The screen glass's opacity, in the space the caller's pipeline blends in. Defaults to the
+     * canvas pipeline's number; a caller compositing in linear light passes the other one. See
+     * `DEVICE_GLASS_OPACITY_ENCODED` and `DEVICE_GLASS_OPACITY_LINEAR`.
+     */
+    glassOpacity?: number;
+    openAngle?: number;
+    width?: number;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    /** Stable prepared object owner for runtime allocation receipts. */
+    resourceOwner?: string;
+}
+export declare function ownDeviceGeometryV1(geometry: BufferGeometry, owner: string, name: string, registerActual?: SceneActualResourceRegistrarV1): () => void;
+export declare function DeviceMesh({ kind, screen, screenColor, materialOverrides, finish, glassOpacity, openAngle, width, position, rotation, resourceOwner }: DeviceMeshProps): import("react").JSX.Element;

package/dist/_members/animate/three/SceneCameraRig.d.ts

@@ -0,0 +1,12 @@
+import type { SceneCameraPose } from '../stage/camera.js';
+/**
+ * Applies a Three-native scene camera pose to the fiber camera each frame, before Remotion advances
+ * the renderer.
+ *
+ * The pose arrives complete and already in output pixels; nothing is converted here except `fov`,
+ * which is radians everywhere in the contract and degrees only at three's own API — this is that
+ * boundary, and it is the only place in the scene lane where a degree exists.
+ */
+export declare function SceneCameraRig({ pose }: {
+    pose: SceneCameraPose;
+}): null;

package/dist/_members/animate/three/StageCameraRig.d.ts

@@ -0,0 +1,7 @@
+import { type StageCamera } from '../stage/camera.js';
+/** Applies the shared StageCamera to the fiber camera each frame, before Remotion advances the renderer. */
+export declare function StageCameraRig({ camera, width, height }: {
+    camera: StageCamera;
+    width: number;
+    height: number;
+}): null;

package/dist/_members/animate/three/StudioRig.d.ts

@@ -0,0 +1,228 @@
+import { Vector3 } from 'three';
+import { STUDIO_SHADOW_MAP_BUDGET } from '../../composition/scene/index.js';
+export type StudioPreset = 'soft' | 'key' | 'rim';
+export type StudioLightRole = 'key' | 'fill' | 'rim';
+/**
+ * The shot's lighting profile (spec Decision 2, amendment A4, ruled 2026-09-10).
+ *
+ * Two values and no third. `studio` is the default and IS this rig unchanged; `studio-edge` is
+ * this rig plus the two fixed lights below. The profile belongs to the SHOT, never to an object:
+ * see `STUDIO_EDGE_LIGHTS` for why that distinction is the load-bearing half of the ruling.
+ */
+export type SceneLightingProfile = 'studio' | 'studio-edge';
+/** The default, stated once so no caller has to remember it. */
+export declare const DEFAULT_LIGHTING_PROFILE: SceneLightingProfile;
+/** The only two legal values, in the order refusals name them. */
+export declare const LIGHTING_PROFILES: readonly SceneLightingProfile[];
+export interface StudioRigProps {
+    /**
+     * A4: `studio` (default) is this rig unchanged; `studio-edge` adds exactly the two fixed,
+     * non-shadow-casting directional lights in `STUDIO_EDGE_LIGHTS`. Not animatable — a light
+     * count that changes mid-shot is not a rig — and sealed into the plan's `rigIdentity`.
+     */
+    lightingProfile?: SceneLightingProfile;
+    preset?: StudioPreset;
+    intensity?: number;
+    /** Floor height in px (Three y-up; negative is below the frame centre). Given in world units by the caller; not scaled by `worldScale`. */
+    floorY?: number;
+    shadowOpacity?: number;
+    environment?: boolean;
+    /**
+     * Multiplies the rig's own fixed layout — light positions, the shadow frustum and the floor
+     * extent — so a scene authored in reference pixels keeps its light and shadow coverage at any
+     * output size. 1 (the default) is the tuned 1080p layout below, unchanged.
+     */
+    worldScale?: number;
+    /**
+     * The world the shadow must cover, in world units (Three axes): the union of the reference
+     * frame and every caster's bounds. The caster's frustum grows past its tuned coverage to hold
+     * it (see `studioShadowFrustum`); absent, the frustum is the tuned `worldScale` coverage alone.
+     */
+    shadowBounds?: ShadowBounds;
+}
+/** An axis-aligned box in world units, Three axes (y up). */
+export interface ShadowBounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    minZ: number;
+    maxZ: number;
+}
+export interface StudioLight {
+    role: StudioLightRole;
+    position: [number, number, number];
+    castShadow: boolean;
+}
+/**
+ * Where the three lights sit, and which one casts.
+ *
+ * Exported as data because the two properties that matter here are not otherwise checkable
+ * without a GPU: that the shadow lands where the camera can see it, and that the preset the
+ * catalog calls "hard key" is actually hardest on the faces an audience looks at.
+ *
+ * The KEY is in front (+z). Everything this rig lights is framed head-on, so the camera-facing
+ * faces are the whole performance: a key behind the subject leaves them on fill alone and the
+ * `key` preset comes out flatter than `soft`, which inverts the table below.
+ *
+ * The RIM is above and behind, and it is the shadow caster — the only light whose shadow the
+ * camera can see. Subjects here sit on the shadow floor, so a front light throws its shadow
+ * backwards where the subject's own body hides it; `device-showcase` used to render a laptop
+ * with no ground contact anywhere in frame, the exact flat-placeholder tell the lit scenes exist
+ * to remove. From behind, the shadow falls toward the camera and lands as a band on the floor
+ * just in front of the subject.
+ *
+ * The rim's [0, 1300, -1900] is 34 degrees above the horizon and on axis in x, and all three
+ * numbers are load-bearing for that band: a lateral offset shears it to one side until the floor
+ * beside the subject is inside it, a steeper light shortens the throw until it hides under the
+ * subject, and a shallower one stretches it across the whole floor.
+ */
+export declare const STUDIO_LIGHTS: readonly StudioLight[];
+/**
+ * The `studio-edge` profile's two lights: POSITION, COUNT and INTENSITY, as constants.
+ *
+ * They are constants and not fields, and that is the ruling rather than an implementation choice.
+ * A4 gives the shot one boolean-shaped decision — which of two profiles — and nothing else: no
+ * `slabEdgeLighting`, no per-object light, no authored position and no authored intensity anywhere
+ * in the object contract. **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`. `scene_object_light_field_unsupported` is what refuses the alternative.
+ *
+ * `[±2000, 350, −700]` reference units, scaled by `worldScale` like every other rig position, is
+ * the pair the I0 intensity sweep was measured on (report §7/A4). They are the only way to get a
+ * SIDE silhouette rim at all: the rig's own rim light is on-axis in x, so `N·L` is exactly 0 for a
+ * ±x-facing bevel normal, and scaling it 1×–8× moves the side silhouette by nothing at any
+ * multiplier. The rim is a geometry fact about where the light is, not about how bright it is.
+ *
+ * **They cast no shadow, and that is what makes the neighbouring-device gate structural.** The
+ * rig's rim light stays the sole caster, so the shadow-catching floor — transparent where
+ * unshadowed — is untouched and the contact band cannot move. It also means the profile allocates
+ * **no shadow map and no render target**: the §4.2 ledger is identical under both profiles.
+ */
+export declare const STUDIO_EDGE_LIGHTS: readonly [number, number, number][];
+/**
+ * The `studio-edge` intensity, frozen at 20 by I0's eight-point sweep (report §7/A4): 0 → 1.07×
+ * body and no run; 2 → 2.82× / 4 px; 6 → 3.60× / 7 px; 12 → 3.84× / 7 px; **20 → 3.94× / 7 px**;
+ * 26 → 3.98× / 7 px; 40 → 4.02× / 10 px; 60 → 4.05× / 10 px. 20 is where the run reaches its
+ * plateau; past it the rim widens without getting brighter in the way the gate measures.
+ */
+export declare const STUDIO_EDGE_INTENSITY = 20;
+/** How many extra lights a profile mounts. Two under `studio-edge`, none under `studio`. */
+export declare function studioEdgeLightCount(profile: SceneLightingProfile): number;
+export interface StudioShadowFrustum {
+    /** Half-width of the caster's orthographic frustum, world units. */
+    extent: number;
+    near: number;
+    far: number;
+    /** Shadow map edge in texels; scales with `extent` up to `STUDIO_SHADOW_MAP_BUDGET`. */
+    mapSize: number;
+}
+/** The caster's frustum at `worldScale` 1: tuned against a 1920x1080 render (see StudioRig). */
+export declare const STUDIO_SHADOW_FRUSTUM: StudioShadowFrustum;
+/**
+ * The largest shadow map the rig will allocate. The tuned frame uses 2048; a frustum that has to
+ * grow past the tuned coverage keeps its texel density (and so the band's softness) by doubling
+ * the map, until this cap, after which the map is spread thinner.
+ *
+ * Defined in `@cueframe/composition/scene` rather than here because it is not only this rig's
+ * number: `@cueframe/component-runtime`'s `webGlRefusal` compares it against the host's reported
+ * `MAX_TEXTURE_SIZE` and refuses the browser — typed `component_graphics_unavailable`, naming the
+ * reported limit and this budget — before a scene shot is captured on a host that cannot afford
+ * it. Both lanes reach that check: the local component lane through
+ * `assertComponentBrowserHardware`, and the composition lane through the tracked
+ * `scene-shot-contract.bundle.mjs`. So an under-budget host refuses at admission; the map is
+ * never halved here to fit, and 4096 is never requested from a host that cannot give it.
+ *
+ * Measured on the desktop backend the packaged app actually renders through by
+ * `apps/studio/scripts/probe-gpu-limits.mjs` — Chrome for Testing with `gl: 'angle'` chosen by
+ * `resolveComponentChromiumConfig`, `ANGLE (Apple, ANGLE Metal Renderer: Apple M5)`:
+ * `MAX_TEXTURE_SIZE`, `MAX_RENDERBUFFER_SIZE` and `MAX_VIEWPORT_DIMS` are all 16384, four times
+ * this cap in each dimension. Allocating this exact shape (RGBA8 colour texture plus a
+ * DEPTH_COMPONENT24 renderbuffer) at 1024, 2048, 4096 and 8192 and keeping all four live at once
+ * — about 680 MB — completed every framebuffer with `gl.getError() === 0` and no context loss.
+ * `apps/studio/scripts/packaged-render-smoke.mjs` renders the mixed-shot fixture through the
+ * assembled `Resources` tree on that same backend. 4096 stands.
+ *
+ * WHAT THIS BUDGET DOES NOT COVER, stated because the uniform world pass made it bigger: every
+ * scene shot now composes through two full-frame half-float colour targets (`focusResources.ts`),
+ * focus or no focus. `MAX_TEXTURE_SIZE` bounds a DIMENSION, not a memory footprint, and WebGL
+ * exposes no query for the latter — so admission can refuse a host whose textures are too small
+ * and a host with no renderable half-float colour, and it cannot refuse a host that has both and
+ * not enough memory. At 3840x2160 the pass costs 66.4 MB per RGBA16F plane: 66.4 (world resolve)
+ * + 33.2 (DEPTH_COMPONENT24) + 66.4 (gathered) = 166 MB single-sampled, and a further
+ * 99.5 MB per canvas MSAA sample on the world target, so 564 MB at the 4x this canvas reports.
+ * At 1920x1080 the same figures are 41.5 MB and 141 MB. The shadow map at this budget adds 67 MB.
+ * The measurement above kept about 680 MB of framebuffers live on the packaged backend without a
+ * context loss, which is the headroom that number is evidence for. A host that runs out anyway
+ * fails as an incomplete framebuffer rather than as a typed refusal; closing that needs a
+ * completeness gate exercised against a real GPU, and it is recorded as owed rather than added
+ * unexercised (final fix wave, item 18).
+ */
+export { STUDIO_SHADOW_MAP_BUDGET };
+/**
+ * How far past the bounds the frustum reaches, as a factor: room for the PCF taps at the map's
+ * edge and for the band's own soft falloff beyond the caster's silhouette.
+ */
+export declare const STUDIO_SHADOW_REACH_PAD = 1.25;
+/** Floor plane edge at `worldScale` 1. */
+export declare const STUDIO_FLOOR_EXTENT = 12000;
+/**
+ * The caster's view basis at `worldScale`, built the way Three's `Matrix4.lookAt` builds a
+ * directional light's shadow camera looking from the rim at the origin with y up: `right` and
+ * `up` span the orthographic frustum's plane, `forward` is depth away from the light.
+ */
+export declare function studioCasterBasis(worldScale: number): {
+    eye: Vector3;
+    right: Vector3;
+    up: Vector3;
+    forward: Vector3;
+};
+/**
+ * The shadow frustum for a world scaled by `worldScale`, grown to cover `bounds` when given.
+ *
+ * Without bounds this is the tuned coverage scaled: `STUDIO_SHADOW_FRUSTUM` times `worldScale`
+ * with the 2048 map. With bounds, each corner of the box is projected into the caster's view; the
+ * half-extent becomes the larger of the tuned coverage and the corners' reach times
+ * `STUDIO_SHADOW_REACH_PAD`, near/far widen the same way when a corner lies outside the tuned
+ * depth range, and the map doubles with the extent so texel density holds until the budget. A
+ * receiver under a caster shares the caster's view coordinates (the shadow travels along the
+ * light), so covering the casters covers where their shadows land sideways.
+ *
+ * Given `floorY`, the depth range also folds in where each corner's ray meets the floor, which is
+ * further from the light than the corner itself: without it a caster near the tuned far plane
+ * would have its band cut off at the exact distance where it becomes visible. Pure: no renderer,
+ * no scene.
+ */
+export declare function studioShadowFrustum(worldScale: number, bounds?: ShadowBounds, floorY?: number): StudioShadowFrustum;
+/** A rig light's position for a world scaled by `worldScale`. */
+export declare function studioLightPosition(light: StudioLight, worldScale: number): [number, number, number];
+/**
+ * Per-preset intensities, tuned against the arrangement above: `key` is the hard-key look, `soft`
+ * the default wrap, `rim` the backlit one. `cameraFacingLight` is what orders them.
+ */
+export declare const STUDIO_PRESETS: Record<StudioPreset, Record<'hemi' | StudioLightRole, number>>;
+/**
+ * Direct-light term a camera-facing surface (normal +z) receives at `preset`: the Lambert sum
+ * over the rig's directional lights. Pure — no renderer, no scene.
+ *
+ * This is the number that decides whether a preset reads hard or flat on the faces an audience
+ * actually sees, so it is what the preset table is ordered by.
+ */
+export declare function cameraFacingLight(preset: StudioPreset, intensity?: number): number;
+/**
+ * Three-point studio lighting with a room environment for reflections and a shadow-catching floor.
+ *
+ * At `worldScale` 1 with no `shadowBounds` the shadow camera and `floorY` are the tuned
+ * 1080p-class layout: the caster's orthographic frustum at +/-1600 world units on a 2048 map and
+ * `floorY` at -420, both chosen against a 1920x1080 render. A legacy caller rendering 3840 wide
+ * without a `worldScale` sees the visible floor run past +/-1600, so the contact band is clipped
+ * with a hard vertical edge roughly 320 px inside each side of the frame; that caller's fix is
+ * `worldScale`. Callers that author in reference pixels (SceneShot) pass their reference scale as
+ * `worldScale` and the world's bounds as `shadowBounds`, so the frustum scales with the frame and
+ * grows past the tuned coverage when a caster is placed beyond it — see `studioShadowFrustum` for
+ * how the map follows.
+ *
+ * Do not change the `worldScale` 1 numbers without re-verifying the gated `stage-device-render`
+ * and `scene-shot-render` tests: their luma assertions are measured against these exact values.
+ */
+export declare function StudioRig({ lightingProfile, preset, intensity, floorY, shadowOpacity, environment, worldScale, shadowBounds }: StudioRigProps): import("react").JSX.Element;

package/dist/_members/animate/three/ThreeCanvas.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { type SceneCameraPose, type StageCamera } from '../stage/camera.js';
 interface ThreeCanvasProps {
     children: React.ReactNode;
     width?: number;
@@ -7,6 +8,27 @@ interface ThreeCanvasProps {
     near?: number;
     far?: number;
     cameraPosition?: [number, number, number];
+    /**
+     * Orthographic camera with its frustum pinned 1:1 to `width`×`height` pixels
+     * (left=-w/2, right=w/2, top=h/2, bottom=-h/2). Pair with flexBoxToThree so
+     * objects land exactly on layout boxes. Perspective when false (default).
+     */
+    orthographic?: boolean;
+    /**
+     * Drive the fiber camera from the shared stage camera so meshes and DOM layers
+     * see the same view. Always perspective — it wins over `orthographic`, `fov`,
+     * `near`, `far` and `cameraPosition`.
+     */
+    stageCamera?: StageCamera;
+    /**
+     * Drive the fiber camera from a Three-native scene camera pose (Decision 1 / report §5.3): the
+     * scene lane's camera, already in output pixels, `fov` in radians. Wins over everything, and is
+     * mutually exclusive with `stageCamera` — a canvas driven by both would have two conventions.
+     */
+    sceneCamera?: SceneCameraPose;
+    shadows?: boolean;
+    dpr?: number;
+    gl?: Record<string, unknown>;
     style?: React.CSSProperties;
 }
 export declare const ThreeCanvas: React.FC<ThreeCanvasProps>;

package/dist/_members/animate/three/defaultScreen.d.ts

@@ -0,0 +1,23 @@
+import { CanvasTexture } from 'three';
+export interface ScreenLayout {
+    sidebar: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    cards: Array<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+    chart: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+/** Pure layout for the placeholder dashboard; the curve is a fixed smooth polynomial, no randomness. */
+export declare function defaultScreenLayout(w: number, h: number): ScreenLayout;
+/** Browser-only: draws the placeholder into a canvas texture. */
+export declare function makeDefaultScreenTexture(accent: string, w?: number, h?: number): CanvasTexture;

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

@@ -1,2 +1,8 @@
 export { ThreeCanvas } from './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 './drei.js';
+export { StageCameraRig } from './StageCameraRig.js';
+export { SceneCameraRig } from './SceneCameraRig.js';
+export { useImageTexture } from './useImageTexture.js';
+export { StudioRig, STUDIO_SHADOW_FRUSTUM, STUDIO_SHADOW_MAP_BUDGET, STUDIO_SHADOW_REACH_PAD, STUDIO_FLOOR_EXTENT, studioShadowFrustum, studioLightPosition, STUDIO_EDGE_LIGHTS, STUDIO_EDGE_INTENSITY, studioEdgeLightCount, DEFAULT_LIGHTING_PROFILE, LIGHTING_PROFILES, type StudioRigProps, type StudioShadowFrustum, type ShadowBounds, type SceneLightingProfile, } from './StudioRig.js';
+export { DeviceMesh, deviceDimensions, laptopLayout, lidRotationX, DEVICE_GLASS_OPACITY_ENCODED, DEVICE_GLASS_OPACITY_LINEAR, DEVICE_LIT_MATERIALS, DEVICE_PLANE_OFFSETS, type DeviceKind, type DeviceMeshProps, type DeviceDimensions, type LaptopLayout, } from './DeviceMesh.js';
+export { SELF_TONE_MAPPED, UNLIT_COLOUR_MANAGED, toneMapInTheMaterial, toneMappingPreamble } from './toneMapping.js';
+export { makeDefaultScreenTexture, defaultScreenLayout, type ScreenLayout } from './defaultScreen.js';

package/dist/_members/animate/three/textureLifecycle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The disposal policy behind `useImageTexture`, kept pure so it can be checked without a
+ * renderer: a texture is disposed only after the commit that stops using it, never at the moment
+ * its replacement finishes loading, because until React has committed the replacement into the
+ * material the old one is still what the frame draws.
+ */
+/** Anything the policy may dispose; structural so tests need no Three. */
+export interface Disposable {
+    dispose(): void;
+}
+/** What one texture owner holds between commits. */
+export interface HeldTexture<T extends Disposable = Disposable> {
+    /** The texture the last commit drew with. */
+    drawn: T | null;
+}
+export declare const NO_TEXTURE: HeldTexture<never>;
+/**
+ * React committed `next` as the drawn texture (or `null`, when the source went away). The one it
+ * replaces has had its last committed use, so it goes now; committing the same texture again is
+ * a no-op.
+ */
+export declare function commitImageTexture<T extends Disposable>(held: HeldTexture<T>, next: T | null): HeldTexture<T>;
+/** The owner unmounted: whatever it last drew with has no user left. */
+export declare function releaseImageTexture<T extends Disposable>(held: HeldTexture<T>): HeldTexture<never>;
+/**
+ * A load finished for an owner that has since unmounted or moved to another source: the texture
+ * never reaches React and nothing else is touched.
+ */
+export declare function discardStaleTexture<T extends Disposable>(texture: T): void;