@threenative/core 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -1,70 +1,1452 @@
-import { AnimationMixer, AnimationClip, Object3D, Sprite, Vector3, CatmullRomCurve3 } from 'three';
-export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions } from './audio-CEAw0w5y.js';
-import { a as IRendererLike, b as IGamePluginRuntime, c as IGamePluginHooks } from './game-DRt1Qhq3.js';
-export { C as CanvasLayer, d as ICtx, I as IGame, e as IGameObservationContribution, f as IGameObservationSampleRequest, g as IGamePlatformSource, h as IRandom, i as IRawInputPointer, j as IRaycastOptions, k as IScenePickerOptions, S as Scene, l as SceneFrame, m as ScenePicker, n as ScheduleHandle, o as Scheduler, p as createRandom, q as defineGame } from './game-DRt1Qhq3.js';
-import { StorageBufferNode, SpriteNodeMaterial, ComputeNode } from 'three/webgpu';
-import { IReplayRecording } from '@threenative/playtest';
+import * as three from 'three';
+import { AnimationMixer, Object3D, AnimationClip, Camera, Vector3, Group, Matrix4, Mesh, BufferGeometry, Material, InstancedMesh, ColorRepresentation, Box3, Scene, DirectionalLight, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
+export { I as IAssetLoader, a as IAssetLoaderOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-kyoF7JlJ.js';
+export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions } from './audio-BFiGneTL.js';
+export { C as CanvasLayer } from './canvas-layer-BLVijiUJ.js';
+import { a as IGamePluginRuntime, b as IGamePluginHooks } from './game-XGrTzapq.js';
+export { A as AfterPhysicsCallback, C as ContextMenuPolicy, c as ICtx, I as IGame, d as IGameObservationContribution, e as IGameObservationSampleRequest, f as IGamePlatformSource, g as IInputAction, h as IInputGamepad, i as IPointerDragHandle, j as IPointerEvent3D, k as IPointerEvents3D, l as IPointerEvents3DOptions, m as IPointerEvents3DPicker, n as IPointerState, o as IRandom, p as IRawInputPointer, q as IRawInputPointerEdge, r as IRawInputState, s as IRaycastOptions, t as IScenePickerOptions, u as IThreeNativeAudioConfig, v as IThreeNativeAudioLoop, w as IThreeNativeAudioOverride, x as IThreeNativeAudioSpectrum, y as IThreeNativeBootSplash, z as IThreeNativeConfig, B as IThreeNativeIconVariants, D as IThreeNativeTexturesConfig, E as ITweenOptions, F as IWarmUpCacheOptions, G as IWarmUpObservation, H as IWarmUpOptions, J as IWarmUpProgress, K as IWarmUpRenderer, L as IWarmUpReport, M as InputBindings, N as InputPlatformSource, P as PointerEvent3DListener, O as PointerEvent3DType, Q as PointerEvents3D, S as Scene, R as SceneFrame, T as ScenePicker, U as ScheduleHandle, V as Scheduler, W as ThreeNativeBackgroundMode, X as ThreeNativeOrientation, Y as ThreeNativeUiRenderer, Z as WarmUpCacheStatus, _ as WarmUpObservationStatus, $ as afterPhysics, a0 as createRandom, a1 as defineGame, a2 as warmUpScene } from './game-XGrTzapq.js';
+import * as three_webgpu from 'three/webgpu';
+import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode } from 'three/webgpu';
+import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, F as FRAME_BUDGET_MARKER, a as FRAME_BUDGET_PHASES, b as FRAME_HITCH_MARKER, c as FrameBudget, d as FrameBudgetPhase, e as IFrameBudgetOptions, f as IFrameBudgetSummary, g as IFrameBudgetWindow, h as IFramePhaseSample, i as IPipelineCensus, j as IPipelineCensusCounts, k as IPipelineCensusEvent, l as IPipelineCensusOptions, m as IPipelineProvenance, n as IPipelineShaderObservation, o as IRenderChainApplied, p as IRenderChainBudgetWindow, q as IRenderChainDroppedStage, r as IRenderChainOptions, s as IRenderChainRenderer, t as IRenderChainRequest, u as IRenderChainStage, v as IRenderChainStageContext, w as IRenderChainVelocityMeasurement, x as IRenderChainVelocityReport, y as IRenderChainVelocityRequest, z as IRenderChainVelocityResult, A as IVelocityRenderPass, P as PIPELINE_CENSUS_CAPABILITY, B as PIPELINE_CENSUS_VERSION, C as PipelineCensus, E as PipelineCensusMode, G as PipelineCensusStatus, R as RENDER_CHAIN_MARKER, H as RENDER_CHAIN_STAGE_ORDER, J as RENDER_CHAIN_TIERS, K as RenderChain, L as RenderChainSource, M as RenderChainStageId, N as RenderChainStageName, O as RenderChainTier, Q as RenderChainTierRequest, S as RenderChainVelocitySource, V as VELOCITY_OUTPUT_NAME, T as VELOCITY_PREVIOUS_BONE_MATRICES, U as VELOCITY_PREVIOUS_INSTANCE_MATRICES, W as VELOCITY_PREVIOUS_WORLD_MATRIX, X as VelocityTracker, Y as createPipelineCensus, Z as ensureVelocityOutput, _ as prewarm, $ as readRenderChainObservation, a0 as readRenderChainReport, a1 as readVelocityPreviousBoneMatrices, a2 as readVelocityPreviousMatrices, a3 as readVelocityPreviousWorldMatrix, a4 as velocityTexture, a5 as withVelocityContext } from './renderer-C6hqZpoG.js';
+import { I as IComputeDriven$1, a as IGPUReadbackSample } from './gpu-readback-D2iRvoe9.js';
+export { C as ComputeDrivenRegistry, G as GPUReadback, b as IGPUReadbackOptions } from './gpu-readback-D2iRvoe9.js';
+import { Node as Node$1 } from 'three/src/nodes/Nodes.js';
 import 'zustand/vanilla';
 
 interface IAnimationPlayerOptions {
     readonly clips: readonly AnimationClip[];
     readonly root: Object3D;
+    readonly requiredClips?: readonly string[] | Readonly<Record<string, string>>;
+    /**
+     * Match a travelling clip's playback rate to the ground the body actually covers.
+     *
+     * On by default, because a model whose feet do not agree with its motion is the single most
+     * common thing wrong with a character in a game built here, and every game solves it the same
+     * way. Set `false` to keep the authored rate; the measurement below stays live either way and
+     * says that it was overridden. The convention re-times locomotion only: a `"once"` clip — a
+     * death, a flinch — always plays at its authored rate.
+     */
+    readonly strideSync?: boolean;
+    /**
+     * The object whose travel counts as ground covered. Defaults to `root`.
+     *
+     * Name the body a game moves when the rig is a child of it, which is the usual shape: the clip
+     * writes the model's own root track, so measuring the same object the mixer writes would read
+     * the clip's motion back as if it were the body's.
+     */
+    readonly strideRoot?: Object3D;
+}
+/**
+ * What the feet are doing against what the body is doing.
+ *
+ * Reported whether or not the convention is applied: turning a convention off must not turn its
+ * measurement off, or a game that opted out has no way to know what it cost.
+ */
+interface IStrideReport {
+    /** Metres of ground the current clip carries per clip-second, at rate 1. Zero if it travels none. */
+    readonly clipGroundSpeed: number;
+    /** Metres per second the root has actually covered, smoothed over the last update. */
+    readonly groundSpeed: number;
+    /** The playback rate those two imply, clamped to `limits`. */
+    readonly rate: number;
+    /** True when that rate is being applied to the action. */
+    readonly synced: boolean;
+    /** True when a rate was measured and deliberately not applied. */
+    readonly overridden: boolean;
+    /**
+     * True when the clip carries no root motion and its stride was read off the feet instead.
+     *
+     * `synced: false, overridden: false` is what an idle reports, so without this a game whose walk
+     * cycle is silently going unmatched cannot tell itself apart from one with nothing to match. An
+     * in-place clip that also yields no foot plant reports `inPlace: true` with a zero
+     * `clipGroundSpeed`, which names the asset as the thing to fix.
+     */
+    readonly inPlace: boolean;
 }
 interface IAnimationPlayOptions {
     readonly fade?: number;
+    /**
+     * `"loop"` (default) repeats; `"once"` plays through and holds the last frame. A `"once"` clip
+     * also keeps its authored rate — stride sync re-times locomotion, not events.
+     */
+    readonly mode?: "loop" | "once";
 }
 declare class AnimationPlayer {
     #private;
     readonly mixer: AnimationMixer;
+    readonly root: Object3D;
     constructor(options: IAnimationPlayerOptions);
     get current(): string | undefined;
     get advancedFrames(): number;
+    /** True when a `"once"` clip has reached its end and is holding. */
+    get finished(): boolean;
+    /**
+     * What the feet are doing against what the body is doing, as of the last `update`.
+     *
+     * Live whether or not the convention is applied. A game that set `strideSync: false` reads
+     * `overridden: true` here next to the rate it declined, which is the only way an override can
+     * be honest about what it turned off.
+     */
+    get stride(): IStrideReport;
+    /** The clip behind a name, for a game that wants the action or the raw `AnimationClip`. */
+    clip(name: string): AnimationClip;
     play(name: string, options?: IAnimationPlayOptions): void;
     update(dt: number): void;
     stop(): void;
     dispose(): void;
 }
 
-type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
-interface IThreeNativeConfig {
-    readonly app?: {
-        readonly id?: string;
-        readonly name?: string;
-        readonly version?: string;
-        readonly build?: number;
-        readonly icon?: string;
-    };
-    readonly display?: {
-        readonly orientation?: ThreeNativeOrientation;
-        readonly fullscreen?: boolean;
-        readonly keepScreenOn?: boolean;
+type NormaliseAxis = "height" | "longest";
+interface INormaliseToMetresOptions {
+    readonly metres: number;
+    readonly axis: NormaliseAxis;
+    /** Crown bone to use for a skinned height measurement. Defaults to a named/highest bone. */
+    readonly top?: Object3D | string;
+}
+/**
+ * Scale an asset to a real-world size and return the factor applied.
+ *
+ * Height for a skinned asset comes from its crown bone, not its bind-pose Box3. Longest-axis
+ * normalization remains a geometry measurement because it is used for rigid props and weapons.
+ */
+declare function normaliseToMetres(object: Object3D, options: INormaliseToMetresOptions): number;
+
+interface ISkeletalMesh3DOptions {
+    readonly source: Object3D;
+    readonly clips?: readonly AnimationClip[];
+    readonly requiredClips?: readonly string[] | Readonly<Record<string, string>>;
+    readonly size?: INormaliseToMetresOptions;
+    readonly strideRoot?: Object3D;
+    readonly strideSync?: boolean;
+}
+declare class SkeletalMesh3D extends AnimationPlayer {
+    constructor(options: ISkeletalMesh3DOptions);
+}
+
+type BillboardLockAxis = "x" | "y" | "z";
+interface IBillboard3DOptions {
+    /** Camera whose view direction or position the object follows. */
+    readonly camera: Camera;
+    /** Restrict the facing rotation to one world axis, for example `"y"` for a tree. */
+    readonly lockAxis?: BillboardLockAxis;
+}
+/**
+ * Orient one game-owned object toward a camera without owning its geometry or surface.
+ *
+ * The object is updated only when its owner calls {@link update}; there is no scene-wide registry
+ * or per-frame traversal. Perspective cameras face from the object's world position toward the
+ * camera, while orthographic cameras use their parallel view direction. The final world rotation
+ * is converted back into the object's local space, so a rotated parent remains correct.
+ */
+declare class Billboard3D {
+    #private;
+    readonly object: Object3D;
+    readonly camera: Camera;
+    readonly lockAxis: BillboardLockAxis | undefined;
+    constructor(object: Object3D, options: IBillboard3DOptions);
+    /** Apply the current camera pose to the object and return this helper for fluent setup. */
+    update(camera?: Camera): this;
+}
+
+type CameraShakeCurve = (phase: number) => number;
+interface ICameraShakeOptions {
+    /** Position amplitude in world metres, supplied by the game. */
+    readonly amplitude: Vector3;
+    /** Rotation amplitude in radians around x/y/z, supplied by the game. */
+    readonly rotationAmplitude: Vector3;
+    /** Curve cycles per second, supplied by the game. */
+    readonly frequency: number;
+    /** Exponential envelope decay per second, supplied by the game. */
+    readonly decay: number;
+    /** Game-authored waveform sampled at `elapsed * frequency * 2π`. */
+    readonly curve: CameraShakeCurve;
+}
+interface ICameraShakeOffset {
+    readonly position: Vector3;
+    readonly rotation: Vector3;
+}
+/**
+ * Produce a transient camera offset without owning or mutating a camera.
+ *
+ * The caller supplies the amplitudes, frequency, decay and waveform. {@link update} evaluates the
+ * waveform against the caller's fixed-step delta and returns a reusable position/rotation offset;
+ * a template can compose it after its own camera rig and damping.
+ */
+declare class CameraShake {
+    #private;
+    readonly amplitude: Vector3;
+    readonly rotationAmplitude: Vector3;
+    readonly frequency: number;
+    readonly decay: number;
+    readonly curve: CameraShakeCurve;
+    readonly offset: ICameraShakeOffset;
+    constructor(options: ICameraShakeOptions);
+    get active(): boolean;
+    get elapsed(): number;
+    /** Start or restart the authored shake waveform. */
+    trigger(): this;
+    /** Stop the effect and clear the offset. */
+    stop(): this;
+    /** Evaluate the current offset and advance by one caller-supplied fixed-step delta. */
+    update(dt: number): ICameraShakeOffset;
+}
+
+type AtmosphereRgb = readonly [number, number, number];
+type AtmosphereVector = AtmosphereRgb | Readonly<{
+    x: number;
+    y: number;
+    z: number;
+}> | Vector3;
+/** Physical inputs for the atmosphere model. Coefficients use 1/km and radii use km. */
+interface IAtmosphereParameters {
+    readonly rayleigh: AtmosphereVector;
+    readonly mie: AtmosphereVector;
+    readonly ozone: AtmosphereVector;
+    readonly planetRadius: number;
+    readonly atmosphereRadius: number;
+}
+interface IResolvedAtmosphereParameters {
+    readonly rayleigh: Vector3;
+    readonly mie: Vector3;
+    readonly ozone: Vector3;
+    readonly planetRadius: number;
+    readonly atmosphereRadius: number;
+}
+type IAtmosphereParameterPatch = Partial<IAtmosphereParameters>;
+interface ISolarPositionInput {
+    readonly date?: Date | string;
+    readonly dayOfYear?: number;
+    readonly timeOfDay?: number;
+    readonly latitude: number;
+    readonly longitude: number;
+    /** UTC offset in hours. Use zero when `date` is already UTC. */
+    readonly utcOffset?: number;
+}
+interface ISolarPosition {
+    elevation: number;
+    azimuth: number;
+}
+/** Validate and clone game-owned coefficients. There is intentionally no Earth fallback.
+ * @situation validate atmosphere coefficients before a game creates its sky
+ * @constraint provide all three coefficient vectors and both radii; omitted fields are errors
+ * @example const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
+ */
+declare function resolveAtmosphereParameters(options: IAtmosphereParameters): IResolvedAtmosphereParameters;
+/** Apply a partial game-owned atmosphere change while preserving validation.
+ * @situation change scattering coefficients and rebake an atmosphere
+ * @constraint patches cannot introduce omitted, negative, or non-finite physical values
+ * @example atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });
+ */
+declare function updateAtmosphereParameters(current: IResolvedAtmosphereParameters, patch: IAtmosphereParameterPatch): IResolvedAtmosphereParameters;
+/**
+ * Return the direct vertical transmittance of the supplied atmosphere.
+ *
+ * The coefficient fixture follows the Hillaire/Bruneton Earth model: an exponential Rayleigh
+ * column, an exponential aerosol column, and the triangular ozone column. This CPU value is a
+ * small validation oracle for the same coefficients that the GPU LUT kernels consume.
+ * @situation check a supplied atmosphere's direct vertical transmittance
+ * @constraint use the returned value as a validation oracle; the rendered path samples the LUT
+ * @example const zenith = zenithTransmittance({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
+ */
+declare function zenithTransmittance(parameters: IAtmosphereParameters | IResolvedAtmosphereParameters): AtmosphereRgb;
+/** Approximate direct transmittance for a ray leaving the ground in a supplied direction.
+ * @situation colour a game-owned sun from atmosphere extinction
+ * @constraint pass a non-zero direction; coefficients and radii come from the game
+ * @example const transmittance = directionalTransmittance(parameters, sunDirection);
+ */
+declare function directionalTransmittance(parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, direction: Vector3): Vector3;
+/** Calculate solar elevation and azimuth from time, latitude, and longitude.
+ * @situation move a sun across a real day at a game's latitude and longitude
+ * @situation run a day and night cycle over the game's sky
+ * @constraint dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed
+ * @constraint pass a mutable { azimuth, elevation } target to reuse the result object in a steady frame loop
+ * @example const sun = solarPosition({ date, latitude: 49.28, longitude: -123.12, utcOffset: -8 });
+ */
+declare function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;
+declare function solarPosition(date: Date | string, latitude: number, longitude: number, target?: ISolarPosition): ISolarPosition;
+/** Convert solar elevation and azimuth degrees into a normalized Three.js direction.
+ * @situation aim a template's sun from solarPosition output
+ * @constraint elevation and azimuth must be finite degrees
+ * @example const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
+ */
+declare function directionFromSolarPosition(elevation: number, azimuth: number): Vector3;
+
+interface IAtmosphereLutResolution {
+    readonly width: number;
+    readonly height: number;
+}
+interface IAtmosphereLutResolutions {
+    readonly transmittance: IAtmosphereLutResolution;
+    readonly multiScattering: IAtmosphereLutResolution;
+    readonly skyView: IAtmosphereLutResolution;
+}
+/** The reference dimensions; games may provide smaller dimensions when their startup budget says so. */
+declare const ATMOSPHERE_LUT_RESOLUTIONS: IAtmosphereLutResolutions;
+declare const LUT_RESOLUTIONS: IAtmosphereLutResolutions;
+interface IParameterUniforms {
+    readonly atmosphereRadius: UniformNode<"float", number>;
+    readonly mie: UniformNode<"vec3", three.Vector3>;
+    readonly ozone: UniformNode<"vec3", three.Vector3>;
+    readonly planetRadius: UniformNode<"float", number>;
+    readonly rayleigh: UniformNode<"vec3", three.Vector3>;
+}
+/** Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
+ * @situation choose atmosphere LUT dimensions for a measured startup budget
+ * @constraint every width and height must be a positive integer; the dimensions are not a named fidelity tier
+ * @example const resolutions = resolveAtmosphereLutResolutions({ skyView: { width: 128, height: 72 } });
+ */
+declare function resolveAtmosphereLutResolutions(resolutions: Partial<IAtmosphereLutResolutions> | undefined): IAtmosphereLutResolutions;
+/** Own the transmittance, multi-scattering, and sky-view compute lookup textures.
+ * @situation bake the three atmosphere LUTs once before a game shows its world
+ * @constraint supply all physical parameters; this class creates no scene appearance
+ * @example const luts = new AtmosphereLuts({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
+ */
+declare class AtmosphereLuts {
+    #private;
+    readonly resolutions: IAtmosphereLutResolutions;
+    readonly transmittance: StorageTexture;
+    readonly multiScattering: StorageTexture;
+    readonly skyView: StorageTexture;
+    readonly warmupNodes: readonly ComputeNode[];
+    readonly uniforms: IParameterUniforms;
+    constructor(parameters: IAtmosphereParametersLike, resolutions?: Partial<IAtmosphereLutResolutions>);
+    get hash(): string;
+    update(parameters: IAtmosphereParametersLike): void;
+    sampleTransmittance(uv: Node<"vec2">): TextureNode;
+    sampleSkyView(uv: Node<"vec2">): TextureNode;
+    dispose(): void;
+}
+type IAtmosphereParametersLike = IResolvedAtmosphereParameters | IAtmosphereParameters;
+
+/** The structural contract consumed by the compute registry from PRD-242. */
+interface IComputeDriven {
+    readonly warmupNodes: readonly unknown[];
+    attachRenderer(renderer: IRendererLike): void;
+    readonly processCadence?: "fixed" | "render";
+    process(renderer: IRendererLike): void;
+    detach(): void;
+    readonly released: boolean;
+}
+interface IAtmosphereOptions extends IAtmosphereParameters {
+    readonly resolutions?: Partial<IAtmosphereLutResolutions>;
+}
+interface IAtmosphereScenePass {
+    getTextureNode(name?: string): Node<"vec4">;
+}
+type AtmosphereDirection = Vector3 | readonly [number, number, number] | Node<"vec3">;
+/**
+ * Own the compute lifetime and expose only parameter-driven atmosphere nodes.
+ *
+ * The class deliberately creates no mesh, material, or scene light. A template chooses all of
+ * those, and the same object remains useful when a game supplies a completely different look.
+ * @situation render a sunrise that changes as time and place change
+ * @situation add distance haze from the depth of a scene pass
+ * @alias bright sky saturated green platforms
+ * @constraint supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback
+ * @constraint the game creates the sky object, surface, and sun from the returned nodes
+ * @example const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
+ * ctx.add(atmosphere);
+ */
+declare class Atmosphere extends Group implements IComputeDriven {
+    #private;
+    readonly luts: AtmosphereLuts;
+    constructor(options: IAtmosphereOptions);
+    get parameters(): IResolvedAtmosphereParameters;
+    get warmupNodes(): readonly ComputeNode[];
+    get released(): boolean;
+    get hash(): string;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    detach(): void;
+    setAtmosphere(patch: IAtmosphereParameterPatch): this;
+    setCoefficients(patch: IAtmosphereParameterPatch): this;
+    setSunDirection(elevation: number, azimuth: number): this;
+    setSunDirection(direction: Vector3): this;
+    setSunDirection(position: Pick<ISolarPosition, "elevation" | "azimuth">): this;
+    getSunDirection(target?: Vector3): Vector3;
+    /** Return the game-owned sky radiance lookup as a TSL vec3 or a CPU validation sample. */
+    radiance(direction: AtmosphereDirection): Node<"vec3"> | Vector3;
+    /** Return direct solar transmittance as a TSL vec3 or a CPU validation sample. */
+    sunTransmittance(direction: AtmosphereDirection): Node<"vec3"> | Vector3;
+    /**
+     * Composite scene colour against game-supplied in-scattered radiance using scene-pass depth.
+     *
+     * The optional radiance node lets the game apply its own exposure or artistic tint. Leaving it
+     * out uses the raw unit-illumination LUT value and does not introduce a framework look.
+     */
+    aerialPerspective(scenePass: IAtmosphereScenePass, depth: Node<"float"> | number, inScatteredRadiance?: Node<"vec3"> | Vector3): Node<"vec4">;
+}
+
+/** Calculate solar elevation and azimuth for one UTC date.
+ * @situation calculate a sun direction from a timestamp and a game location
+ * @constraint dates are interpreted as UTC; use solarPosition for an explicit local offset
+ * @example const sun = solarPositionAt(new Date(), 49.28, -123.12);
+ */
+declare function solarPositionAt(date: Date | string, latitude: number, longitude: number): ISolarPosition;
+
+interface IClothTopologyOptions {
+    /** Original geometry vertex indices that never move. Duplicate positions pin together. */
+    readonly pinned: readonly number[];
+}
+
+/** Packed collision input supplied by an optional dependency such as `@threenative/physics`. */
+interface ISoftBodyCollision {
+    readonly capacity: number;
+    writeBoxes(target: Float32Array, worldToLocal: Matrix4): number;
+}
+interface ISoftBody3DOptions extends IClothTopologyOptions {
+    /** Spring acceleration per metre of stretch. Required; the game owns the cloth response. */
+    readonly stiffness: number;
+    /** Exponential velocity decay per second. Required; zero disables damping. */
+    readonly damping: number;
+    /** Local-space acceleration in metres per second squared. */
+    readonly gravity: readonly [number, number, number];
+    /** Local-space wind acceleration in metres per second squared. */
+    readonly wind: readonly [number, number, number];
+    /** Existing physics bodies translated by the physics package; omitted when cloth has no world collision. */
+    readonly collision?: ISoftBodyCollision;
+    /** Framework fixed-step duration. Defaults to the engine convention of 1/60 second. */
+    readonly timeStep?: number;
+    /** Throttled GPU position readback for gameplay/proof; zero disables it. */
+    readonly readbackEveryFrames?: number;
+}
+/**
+ * Simulate an ordinary game-authored triangle mesh as cloth on the existing fixed-step GPU lane.
+ *
+ * The mesh supplies every visible choice. This class welds exporter duplicates, owns spring and
+ * position buffers, and replaces only the cloned material's position node. It adds no material,
+ * colour, texture, wind, stiffness, damping, or pinning default.
+ *
+ * @situation make a flag, cape, or curtain move as cloth
+ * @situation simulate a deforming surface while keeping one edge pinned
+ * @situation simulate cloth sails blowing in the wind
+ * @situation make cloth sails billow in wind on a ship
+ * @constraint the mesh must use one Three.js node material and contain complete triangles
+ * @constraint pinned, stiffness, damping, gravity, and wind are required game-owned inputs
+ * @constraint Pixel 8 steady upper bound for the shipped 45-vertex pennant with readback every two frames: whole-starter update p95 4.66 ms, render p95 3.56 ms, and GPU timer 0.05 ms across three 300-frame final-rung windows at 552x248 with 4x MSAA; these whole-scene numbers are not isolated solver cost
+ * @override timeStep follows the engine 1/60-second convention unless the game overrides it
+ * @override readbackEveryFrames enables an explicitly stale CPU position sample; zero disables it
+ * @example const flag = new SoftBody3D(flagMesh, { pinned: topEdge, stiffness: 35, damping: 1.8, gravity: [0, -9.81, 0], wind: [1.5, 0, 0.4] });
+ */
+declare class SoftBody3D extends Mesh<BufferGeometry, NodeMaterial> implements IComputeDriven$1 {
+    #private;
+    readonly processCadence: "fixed";
+    readonly warmupNodes: readonly ComputeNode[];
+    readonly stiffness: number;
+    readonly damping: number;
+    readonly timeStep: number;
+    readonly gravity: Vector3;
+    readonly wind: Vector3;
+    readonly uniqueVertexCount: number;
+    readonly springCount: number;
+    constructor(mesh: Mesh, options: ISoftBody3DOptions);
+    get released(): boolean;
+    get steps(): number;
+    /** Latest asynchronous GPU positions and their age, when readback was requested. */
+    get sample(): IGPUReadbackSample | undefined;
+    debug(): Record<string, unknown>;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    detach(): void;
+}
+
+/** Selects the meshes that become part of a GPU trace set. */
+interface IGPUSceneBVHOptions {
+    readonly include?: (object: Mesh) => boolean;
+}
+/**
+ * A material range expressed in packed index elements, after the BVH leaf reorder.
+ *
+ * `start` and `count` address the uploaded index buffer, not the source geometry, so a single
+ * source material can appear as more than one range once the SAH sort interleaves its triangles.
+ */
+interface IGPUSceneBVHMaterialGroup {
+    readonly count: number;
+    readonly materialIndex: number;
+    readonly start: number;
+}
+/** The upstream TSL ray query, exposed without renaming or wrapping it. */
+type GPUSceneBVHTraceFunction = (...args: readonly unknown[]) => unknown;
+declare const bvhIntersectFirstHit: GPUSceneBVHTraceFunction;
+declare const rayStruct: StructTypeNode;
+/**
+ * Snapshot selected scene meshes into world-space storage buffers for an upstream TSL BVH query.
+ *
+ * This class owns packing, residency, and release. It deliberately does not own the ray query or
+ * a rendered effect: a game imports the exact upstream `bvhIntersectFirstHit` and `rayStruct`
+ * exports through the core entry point and uses these four named nodes in its own `src/render/`
+ * kernel. The snapshot is static until `rebuild()`.
+ */
+declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
+    #private;
+    readonly indices: StorageBufferNode<"uvec3">;
+    readonly nodes: StorageBufferNode<"struct">;
+    readonly normals: StorageBufferNode<"vec3">;
+    readonly positions: StorageBufferNode<"vec3">;
+    readonly warmupNodes: readonly unknown[];
+    constructor(scene: Object3D, options?: IGPUSceneBVHOptions);
+    get buildMs(): number;
+    get materialGroups(): readonly IGPUSceneBVHMaterialGroup[];
+    get objectCount(): number;
+    get released(): boolean;
+    get triangleCount(): number;
+    get vertexCount(): number;
+    attachRenderer(renderer: IRendererLike): void;
+    process(_renderer: IRendererLike): void;
+    /** Repack the selected scene objects and replace the GPU buffers behind the stable node handles. */
+    rebuild(): void;
+    /** Dispose every storage attribute owned by this snapshot. Safe to call more than once. */
+    detach(): void;
+}
+
+/** One instance's transform, in the units the geometry was authored in. */
+interface IInstancedPlacement {
+    /** World position of the instance's origin, as `[x, y, z]`. */
+    readonly position: readonly [number, number, number];
+    /** Euler rotation in radians, as `[x, y, z]`. Default none. */
+    readonly rotation?: readonly [number, number, number];
+    /** Per-axis scale as `[x, y, z]`, or one number for all three. Default 1. */
+    readonly scale?: readonly [number, number, number] | number;
+}
+interface IInstancedBatchOptions {
+    /** The shape every instance draws, supplied by the game. */
+    readonly geometry: BufferGeometry;
+    /**
+     * The surface every instance draws with, supplied by the game and used by reference — recolour
+     * it and the whole batch recolours. Required: collapsing the draws is the engine's job, what
+     * the props look like never is.
+     */
+    readonly material: Material;
+}
+interface IInstancedBatchBuildOptions {
+    /** Passed straight to the built mesh. Default `false`, as in Three.js. */
+    readonly castShadow?: boolean;
+    /** Name on the built mesh, so a capture or a scene dump can tell one batch from another. */
+    readonly name?: string;
+    /** Added to this object when the batch builds. Omit to take the mesh and place it yourself. */
+    readonly parent?: Object3D;
+    /** Passed straight to the built mesh. Default `false`, as in Three.js. */
+    readonly receiveShadow?: boolean;
+}
+/**
+ * Collapses many copies of one shape into a single draw, without knowing the count up front.
+ *
+ * `new InstancedMesh(geometry, material, count)` needs `count` before anything has been placed, so
+ * a procedural builder either walks its own layout twice, over-allocates and fixes `.count`
+ * afterwards, or gathers transforms into an array first. This is that array, with the
+ * `Object3D`-scratch-and-`updateMatrix` dance and the post-fill bookkeeping — `instanceMatrix`
+ * invalidation and a bounding sphere the culler can use — done once instead of at every site.
+ *
+ * It decides nothing about how the result looks: the shape, the surface and every transform are
+ * the game's, and the built mesh is handed back so the game can keep animating instances by index.
+ */
+declare class InstancedBatch {
+    #private;
+    readonly geometry: BufferGeometry;
+    readonly material: Material;
+    constructor(options: IInstancedBatchOptions);
+    /** How many instances have been placed so far. */
+    get count(): number;
+    /** The built mesh, or `undefined` before {@link build} — never a guess. */
+    get mesh(): InstancedMesh | undefined;
+    /**
+     * Records one instance from a matrix the game composed itself, and returns its instance index.
+     *
+     * The matrix is copied, so the caller may reuse a single scratch `Matrix4` across every call.
+     */
+    add(matrix: Matrix4): number;
+    /** Records one instance from position, scale and Euler rotation, and returns its instance index. */
+    place(placement: IInstancedPlacement): number;
+    /**
+     * Records one instance stretched between two points, and returns its instance index.
+     *
+     * Chains, tie rods, railing bars, struts and cables are all "from A to B" rather than "at P with
+     * rotation R". Deriving the orientation here is what keeps every caller from hand-computing an
+     * Euler angle that goes wrong the moment one endpoint moves.
+     */
+    span(from: readonly [number, number, number], to: readonly [number, number, number], radius: number): number;
+    /**
+     * Turns everything placed so far into one `InstancedMesh`, and returns it.
+     *
+     * Returns `undefined` when nothing was placed. That is deliberate: `new InstancedMesh(g, m, 0)`
+     * satisfies every type check and draws nothing, so a builder whose layout produced no instances
+     * would look identical to one that worked. `undefined` puts that case in the caller's types.
+     */
+    build(options?: IInstancedBatchBuildOptions): InstancedMesh | undefined;
+}
+
+/**
+ * One piece on its way into a merged buffer.
+ *
+ * A `Mesh` is already one of these — pass the meshes straight in and their own transforms are
+ * used. Every value here is the game's: the shape, where it sits, and what colour it is.
+ */
+interface IMergePart {
+    /** The piece's own colour, written flat across its vertices. Omit it on every part for none. */
+    readonly color?: ColorRepresentation;
+    /** The shape. It is cloned before anything is done to it, so the game's copy is untouched. */
+    readonly geometry: BufferGeometry;
+    /** Where the piece sits. A `Mesh` brings its own; identity when there is none. */
+    readonly matrix?: Matrix4;
+}
+interface IMergePartsOptions {
+    /** Named in the error when the merge is refused. Say what was being built. */
+    readonly label: string;
+}
+/**
+ * Merge game-authored pieces into one buffer, keeping each piece's own colour.
+ *
+ * Two things go wrong every time an agent bakes a building, a ship or a character out of
+ * primitives, and neither is about how any of it looks. `mergeGeometries` returns `null` on
+ * mismatched inputs instead of throwing, and the usual mismatch — one non-indexed extrusion among
+ * a hundred indexed primitives — is invisible until the whole scene is missing; and a merged
+ * buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat
+ * `color` attribute written before the merge. Writing that attribute is mechanical. The colours
+ * are entirely the game's, one per part, and changing them changes nothing here.
+ */
+declare function mergeParts(parts: Iterable<IMergePart>, options: IMergePartsOptions): BufferGeometry;
+
+/**
+ * A mesh that draws only the clusters this camera can resolve.
+ *
+ * The asset pipeline bakes a cluster DAG into the `.glb` (`TN_virtual_geometry`); the loader returns
+ * one of these when it finds one, and an ordinary `Mesh` when it does not. Nothing about how the
+ * mesh looks lives here: `geometry`, `material` and every appearance parameter are the game's, and
+ * swapping the surface at any time swaps what draws.
+ *
+ * The rule, and it asks a cluster nothing about its neighbours: **draw a cluster when its own error
+ * projects to fewer screen pixels than the threshold, and its parent group's does not.** Each side
+ * is projected through the sphere of the group it belongs to, which is what keeps the cut watertight
+ * as the camera moves — a group's sphere encloses every child's, so the parent's projected error can
+ * never fall below a child's.
+ */
+/** The baked payload, exactly as `TN_virtual_geometry` stores it. */
+interface IClusterTable {
+    /** Per cluster, `[centreX, centreY, centreZ, radius]`. Culling reads it; PRD-283 will. */
+    readonly bounds: Float32Array;
+    /** Per cluster, `[axisX, axisY, axisZ, cutoff]`. */
+    readonly cones: Float32Array;
+    /** Per cluster, `[ownError, parentError]`, in the mesh's own units. */
+    readonly errors: Float32Array;
+    /** Cluster-ordered triangles for every level, indexing the geometry's vertex buffer. */
+    readonly indices: Uint32Array;
+    /** Per cluster, the sphere `parentError` is projected through. */
+    readonly parentSpheres: Float32Array;
+    /** Per cluster, `[start, count]` into {@link IClusterTable.indices}. */
+    readonly ranges: Uint32Array;
+    /** Per cluster, the sphere its own error is projected through. */
+    readonly sourceSpheres: Float32Array;
+}
+interface IClusteredMeshOptions {
+    /**
+     * Screen-space error a cluster may show, in pixels, before its children are drawn instead.
+     *
+     * One pixel is the honest default: the point of the technique is that what the camera cannot
+     * resolve is never submitted. Raising it trades fidelity for triangles, and the number is the
+     * game's to choose.
+     */
+    readonly errorPixels?: number;
+    /**
+     * How far the camera must move, in the mesh's own units, before the cut is taken again.
+     *
+     * Popping is a defect, not a tuning parameter: a camera standing still and breathing must not
+     * flip a cluster back and forth. Below this the previous cut is kept, which is always a cut some
+     * camera would have chosen and therefore always watertight. Default is a thousandth of the mesh's
+     * radius.
+     */
+    readonly recutDistance?: number;
+}
+declare class ClusteredMesh extends Mesh {
+    #private;
+    /** The baked payload. Read-only at run time; the bake is the only thing that writes it. */
+    readonly table: IClusterTable;
+    /** Screen-space error budget in pixels. Writable — it is the game's call. */
+    errorPixels: number;
+    /** Camera movement, in the mesh's own units, below which the previous cut is kept. */
+    recutDistance: number;
+    constructor(geometry: BufferGeometry, surface: Material | Material[], table: IClusterTable, options?: IClusteredMeshOptions);
+    /** Clusters in the current cut. */
+    get drawnClusters(): number;
+    /** Triangles the current cut submits. */
+    get drawnTriangles(): number;
+    /**
+     * Chooses this frame's cut and compacts it into one index range.
+     *
+     * Called by the game before it renders, not from `onBeforeRender`: an empty cut has to skip the
+     * draw rather than submit a zero-count one, and by the time three calls `onBeforeRender` the draw
+     * is already on the list. A mesh this leaves invisible is made visible again by the next call,
+     * which is why the call belongs in the frame loop rather than in the renderer.
+     *
+     * @returns triangles the mesh will draw.
+     */
+    update(camera: Camera, viewportHeight: number): number;
+}
+/**
+ * Takes every clustered mesh and every clustered batch under `root` through this frame's cut.
+ *
+ * The engine calls this itself, once a frame, before the render — virtual geometry ships on and a
+ * game that has to remember to call something has not been given it. A scene holding neither costs
+ * one traversal that finds nothing.
+ *
+ * @returns triangles the clustered meshes and batches will submit.
+ */
+declare function updateClusteredMeshes(root: {
+    traverse(callback: (object: object) => void): void;
+}, camera: Camera, viewportHeight: number): number;
+
+/**
+ * Many copies of one clustered body, each drawn at the detail its own distance earns.
+ *
+ * `InstancedBatch` collapses repeated props into one draw; this does the same for a body that
+ * carries a cluster DAG, and adds the part `InstancedBatch` cannot do — a copy twelve metres away
+ * and a copy two hundred metres away do not draw the same triangles.
+ *
+ * **Why instances are bucketed rather than cut one by one.** One indexed draw has one index range,
+ * and multi-draw indirect is not portably available on this stack, so *n* different cuts would mean
+ * *n* draws and *n* index buffers — on four hundred boulders that is a gigabyte of index data to
+ * save vertex work. Instead the copies are grouped by distance, one cut is taken per occupied
+ * group, and each group draws as one instanced draw. Every group's cut is a real cut of the DAG and
+ * therefore watertight; the group is cut at the distance of its *nearest* member, so no copy is ever
+ * drawn coarser than its own distance allows — only finer, by at most the width of one group.
+ *
+ * Geometry, surface and every transform are the game's, exactly as with `InstancedBatch`.
+ */
+/** One copy's transform, in the units the geometry was authored in. */
+interface IClusteredPlacement {
+    readonly position: readonly [number, number, number];
+    readonly rotation?: readonly [number, number, number];
+    readonly scale?: readonly [number, number, number] | number;
+}
+interface IClusteredBatchOptions {
+    /**
+     * How far the camera must move, as a fraction of its distance to the nearest copy, before the
+     * cut is taken again. Default 1%.
+     *
+     * The engine cuts every batch every frame, so this is the difference between a walk that costs a
+     * few hundred cluster tests and one that costs half a million. A camera that has not moved
+     * meaningfully keeps the previous cut, which is always a cut some camera would have chosen and
+     * therefore always watertight.
+     */
+    readonly recutFraction?: number;
+    /**
+     * Ratio between one distance group and the next, above 1.
+     *
+     * Narrower groups follow each copy's own distance more closely and cost one more draw each.
+     * 1.25 is the default: about a dozen groups across a scene that spans a few hundred metres.
+     */
+    readonly distanceRatio?: number;
+    /** Screen-space error budget in pixels, as {@link ClusteredMesh}. Default 1. */
+    readonly errorPixels?: number;
+    /** The shape every copy draws, carrying the baked cluster table. */
+    readonly geometry: BufferGeometry;
+    /** The surface every copy draws with, supplied by the game and used by reference. */
+    readonly material: Material;
+    /** The bake, exactly as `TN_virtual_geometry` stores it. */
+    readonly table: IClusterTable;
+}
+interface IClusteredBatchBuildOptions {
+    readonly castShadow?: boolean;
+    readonly name?: string;
+    readonly parent: Object3D;
+    readonly receiveShadow?: boolean;
+}
+declare class ClusteredBatch {
+    #private;
+    constructor(options: IClusteredBatchOptions);
+    /** How many copies are placed. */
+    get count(): number;
+    /** Draws this batch will submit — one per occupied distance group. */
+    get drawCalls(): number;
+    /** Triangles the current cut submits, over every copy. */
+    get drawnTriangles(): number;
+    /** Adds one copy. Returns its index, so the game can move it later. */
+    place(placement: IClusteredPlacement): number;
+    /** Attaches the batch to the scene. Nothing draws until {@link ClusteredBatch.update} runs. */
+    build(options: IClusteredBatchBuildOptions): Object3D;
+    /**
+     * Chooses this frame's cut for every distance group.
+     *
+     * @returns triangles the batch will submit.
+     */
+    update(camera: Camera, viewportHeight: number): number;
+}
+
+/** The atlas has one copied edge texel on either side of each packed SH sub-volume. */
+declare const ATLAS_PADDING = 1;
+/** The machine-readable marker emitted whenever the probe state changes. */
+declare const PROBE_VOLUME_MARKER = "TN_PROBE_VOLUME";
+type IVector3Like$1 = {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+};
+type IProbePosition = Vector3 | Node<"vec3">;
+/** One RGB L2 spherical-harmonic coefficient, in the upstream probe ordering. */
+interface IProbeVolumeCoefficient {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+/** Probe density in probes per world unit, either isotropic or per-axis. */
+type ProbeVolumeDensity = number | readonly [number, number, number] | IVector3Like$1;
+interface IProbeVolumeOptions {
+    /** World-space bounds; the volume does not move with the object after construction. */
+    readonly bounds: Box3 | {
+        readonly min: IVector3Like$1;
+        readonly max: IVector3Like$1;
     };
-    readonly window?: {
-        readonly title?: string;
-        readonly width?: number;
-        readonly height?: number;
-        readonly resizable?: boolean;
+    /** Probe spacing expressed as probes per world unit. */
+    readonly density: ProbeVolumeDensity;
+    /** Optional device limit supplied by a host that knows it before construction. */
+    readonly maxTextureDimension3D?: number;
+    /** Alias for integrations that expose the WebGPU limit under a device-oriented name. */
+    readonly deviceTextureLimit?: number;
+    /** Maximum wall-clock work per render phase, in milliseconds. */
+    readonly bakeBudgetMs?: number;
+    /** Additional guard that keeps a clock-less host from processing an unbounded queue. */
+    readonly maxWorkItemsPerFrame?: number;
+    /** Resolution of each captured cube face. The static-lighting default is intentionally small. */
+    readonly cubemapSize?: number;
+    readonly near?: number;
+    readonly far?: number;
+    /** Additional indirect passes after the direct-light pass. */
+    readonly bounces?: number;
+    /** Injectable clock for deterministic scheduling tests. */
+    readonly now?: () => number;
+    readonly report?: (line: string) => void;
+}
+interface IProbeVolumeBakeProgress {
+    readonly completed: number;
+    readonly total: number;
+    readonly fraction: number;
+    readonly probesCompleted: number;
+    readonly probesTotal: number;
+    readonly pass: number;
+    readonly passes: number;
+}
+interface IProbeVolumeObservation {
+    readonly marker: typeof PROBE_VOLUME_MARKER;
+    readonly status: "unbaked" | "baking" | "ready";
+    readonly stale: boolean;
+    readonly unbaked: boolean;
+    /** `null` means no completed bake has established an age yet. */
+    readonly stalenessFrames: number | null;
+    readonly probeCount: number;
+    readonly atlasBytes: number;
+    readonly atlas: {
+        readonly width: number;
+        readonly height: number;
+        readonly depth: number;
     };
+    readonly bakeProgress: IProbeVolumeBakeProgress;
+    /** Wall-clock time spent by the most recent incremental render-phase slice. */
+    readonly bakeCostMs: number;
+    readonly bakeBudgetMs: number;
+    /** True while pass zero samples a black texture instead of a previous bake. */
+    readonly samplingIsolated: boolean;
+}
+/** Read a complete marker-shaped observation without accepting malformed data. */
+declare function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined;
+/**
+ * A WebGPU irradiance probe volume.
+ *
+ * The volume owns placement, GPU bake scheduling and a single padded atlas. It owns no light,
+ * material or colour: every coefficient comes from the scene rendered by its cube cameras. Add it
+ * through `ctx.add()` so `process()` runs in the render phase measured by `FrameBudget`.
+ *
+ * Bakes are static-lighting-first and explicit. Call `requestBake(scene)` after lights and static
+ * geometry are authored; a completed bake is reused until the game requests another one.
+ */
+declare class ProbeVolume extends Object3D implements IComputeDriven$1 {
+    #private;
+    readonly isProbeVolume = true;
+    readonly processCadence: "render";
+    readonly warmupNodes: readonly unknown[];
+    readonly boundingBox: Box3;
+    readonly resolution: Vector3;
+    constructor(options: IProbeVolumeOptions);
+    get texture(): Data3DTexture;
+    get atlasDepth(): number;
+    get atlasBytes(): number;
+    get probeCount(): number;
+    get released(): boolean;
+    get atlasData(): Float32Array;
+    get observation(): IProbeVolumeObservation;
+    /** Attach the active renderer; only WebGPU has the 3D render-target contract this class needs. */
+    attachRenderer(renderer: IRendererLike): void;
+    /** Start or coalesce an incremental static bake for a scene. */
+    requestBake(scene: Scene, options?: {
+        readonly bounces?: number;
+    }): Promise<void>;
+    /** Alias that reads naturally at call sites that want an awaitable bake request. */
+    bake(scene: Scene, options?: {
+        readonly bounces?: number;
+    }): Promise<void>;
+    bake(renderer: IRendererLike, scene: Scene, options?: {
+        readonly bounces?: number;
+    }): Promise<void>;
     /**
-     * What the generated loading screen reads.
+     * Return the L2 irradiance node for a world position and world normal.
      *
-     * These are declarations, not a renderer: `src/render/loading.ts` is your source and it is the
-     * only thing that draws them, so a look this cannot express is a file you edit rather than an
-     * option we add. Deleting that file still opts out of the screen entirely.
+     * `sample()` with no arguments is the material-friendly form and reads `positionWorld` and
+     * `normalWorld`. Passing numeric vectors is reserved for diagnostics and deterministic tests;
+     * it evaluates the same SH coefficients held by the atlas packer.
      */
-    readonly loading?: {
-        /** Image drawn centred above the bar, project-relative like `public/logo.png`. */
-        readonly image?: string;
-        readonly backdropColor?: string;
-        readonly trackColor?: string;
-        readonly progressColor?: string;
-        /** False draws the backdrop and image with no bar. */
-        readonly showProgressBar?: boolean;
+    sample(): Node<"vec3">;
+    sample(position: Vector3, normal: Vector3): Vector3;
+    sample(position: IProbePosition, normal?: Vector3 | Node<"vec3">): Vector3 | Node<"vec3">;
+    sampleIrradiance(position: Vector3, normal: Vector3): Vector3;
+    /** The GPU graph used by `sample`; exposed so generated materials can compose it explicitly. */
+    sampleNode(position?: Node<"vec3">, normal?: Node<"vec3">): Node<"vec3">;
+    /** Internal data seam used by unit/conformance fixtures to seed a known SH atlas without a GPU. */
+    setProbeCoefficients(ix: number, iy: number, iz: number, coefficients: readonly IProbeVolumeCoefficient[]): void;
+    /** One bounded render-phase slice. The game loop calls this through IComputeDriven. */
+    process(renderer: IRendererLike): void;
+    detach(): void;
+    get paddedSlices(): number;
+    get maximumDimension(): number;
+    get totalWork(): number;
+    probePosition(ix: number, iy: number, iz: number, target?: Vector3): Vector3;
+}
+
+/**
+ * Renderer-independent bookkeeping for virtual shadow pages.
+ *
+ * Four pieces, none of which know a GPU exists: stable virtual page addresses and a bounded
+ * physical page pool with LRU eviction (`PhysicalPagePool`), camera-centred clip windows snapped
+ * to whole pages in a light-space basis (`DirectionalClipmap`), the pages a frame needs from
+ * receiver points and visible caster bounds (`ReceiverDemandPass`), and the pages a moving caster
+ * dirties (`ShadowInvalidationTracker`). `VirtualShadowNode` in `virtual-shadow.ts` is the only
+ * consumer; everything here is pure so its rules are provable in a node-environment spec.
+ *
+ * Fail closed: malformed input throws at the boundary instead of producing a page that samples
+ * nothing.
+ */
+/** A plain `{x, y, z}` triple; three's `Vector3` satisfies it without a copy. */
+interface IVector3Like {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** An axis-aligned world-space box as two corners. */
+interface IBoundsLike {
+    readonly min: IVector3Like;
+    readonly max: IVector3Like;
+}
+/** A point in the light-space basis: `u` and `v` across the light, `w` toward it. */
+interface ILightSpacePoint {
+    readonly u: number;
+    readonly v: number;
+    readonly w: number;
+}
+/** The address of one virtual page: a clip level and integer page coordinates. */
+interface IVirtualPageAddress {
+    readonly level: number;
+    readonly x: number;
+    readonly y: number;
+    readonly key: string;
+}
+/** One clip level's window of `pagesPerAxis²` virtual pages around the centre. */
+interface IClipWindow {
+    readonly level: number;
+    readonly extent: number;
+    readonly pageWorldSize: number;
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+}
+interface IDirectionalClipmapOptions {
+    /** Unit-free direction *toward* the source; normalised here. */
+    readonly direction: IVector3Like;
+    /** Half-width of each level's window in world units, finest first. */
+    readonly clipExtents: readonly number[];
+    readonly pagesPerAxis: number;
+    /** Fraction of an extent inside which a point selects that level; `(0, 1]`. */
+    readonly selectionGuard?: number;
+}
+/**
+ * Camera-centred clip windows in a light-space basis, snapped to whole pages.
+ *
+ * The basis is right-handed (`U × V = W`). A page camera placed along `+W` with `up = V` then
+ * renders screen X = `V × W` = `+U`, which is the axis the sampler reads the atlas along. The
+ * prototype this was ported from built `V = U × W` and every page came out mirrored.
+ */
+declare class DirectionalClipmap {
+    #private;
+    readonly clipExtents: readonly number[];
+    readonly pagesPerAxis: number;
+    readonly selectionGuard: number;
+    readonly levelCount: number;
+    basisU: IVector3Like;
+    basisV: IVector3Like;
+    basisW: IVector3Like;
+    centerWorld: IVector3Like;
+    centerLight: ILightSpacePoint;
+    constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, }: IDirectionalClipmapOptions);
+    /** Re-orient the basis; returns true when it changed enough that cached pages are stale. */
+    setDirection(direction: IVector3Like): boolean;
+    project(worldPoint: IVector3Like): ILightSpacePoint;
+    unproject({ u, v, w }: {
+        u: number;
+        v: number;
+        w?: number;
+    }): IVector3Like;
+    updateCenter(worldPoint: IVector3Like): readonly IClipWindow[];
+    getWindow(level: number): IClipWindow;
+    pageWorldSize(level: number): number;
+    containsPage(level: number, x: number, y: number): boolean;
+    worldToPage(worldPoint: IVector3Like, level: number): IVirtualPageAddress;
+    /** The finest level whose guarded extent contains the point, else the coarsest. */
+    selectLevel(worldPoint: IVector3Like): number;
+    /** Light-space extent and world centre (at `w = 0`) of one page. */
+    pageBounds(level: number, x: number, y: number): {
+        level: number;
+        x: number;
+        y: number;
+        minU: number;
+        minV: number;
+        maxU: number;
+        maxV: number;
+        centerU: number;
+        centerV: number;
+        pageWorldSize: number;
+        centerWorld: IVector3Like;
     };
-    readonly nativeEntry?: string;
-    readonly renderer?: {
-        readonly preferWebGPU?: boolean;
+    boundsToPageRange(bounds: IBoundsLike, level: number): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    boundsToPageKeys(bounds: IBoundsLike, level: number): string[];
+    windowPages(level: number): IVirtualPageAddress[];
+}
+/**
+ * Remembers each tracked caster's last bounds and dirties every page the old and new bounds
+ * cover on every level when they change. Unchanged bounds dirty nothing.
+ */
+declare class ShadowInvalidationTracker {
+    #private;
+    readonly clipmap: DirectionalClipmap;
+    constructor(clipmap: DirectionalClipmap);
+    get trackedCount(): number;
+    /** Record a caster's current bounds; returns true when pages were dirtied. */
+    update(id: number | string, bounds: IBoundsLike): boolean;
+    has(id: number | string): boolean;
+    remove(id: number | string): boolean;
+    /** Dirty the current coverage of every tracked caster; returns the pending key count. */
+    invalidateAll(): number;
+    /** Drop trackers whose id is not in `liveIds`, dirtying the pages they covered. */
+    prune(liveIds: ReadonlySet<number | string>): number;
+    consumeInvalidatedKeys(): Set<string>;
+    clear(): void;
+}
+
+/**
+ * Options for {@link VirtualShadowNode}. Every value is a mechanism parameter; the light's own
+ * `shadow` keeps bias, normalBias, intensity, map type and filter, exactly as with a stock shadow.
+ */
+interface IVirtualShadowOptions {
+    /**
+     * Half-width of each clip level's window in world units, finest first and strictly
+     * increasing. Default `[16, 48, 144]`: three windows, each three times wider than the last.
+     */
+    readonly clipExtents?: readonly number[];
+    /** Texels per level edge. Default: the light's `shadow.mapSize.width`. */
+    readonly mapSize?: number;
+    /**
+     * Texels per edge of each level's mover map — the map tracked casters draw into every frame.
+     * Default: half of `mapSize`, never below 256. Movers are few and close, so half the texels
+     * over the same window reads as the same shadow at a quarter of the fill.
+     */
+    readonly moverMapSize?: number;
+    /**
+     * Fraction of a level's extent inside which a fragment still selects that level, `(0, 1]`,
+     * default 0.9 — the outer ring falls through to the next level so the edge is never sampled.
+     */
+    readonly selectionGuard?: number;
+    /** How far behind the window centre each level camera sits, in world units. Default 200. */
+    readonly lightDistance?: number;
+    /** Depth range each level camera covers past its centre, in world units. Default 400. */
+    readonly depthRange?: number;
+    /** Print the `TN_VIRTUAL_SHADOW` line every `markerEvery` frames; `false` silences it. Default 300. */
+    readonly marker?: boolean | number;
+}
+/** Per-frame counters, readable any time through {@link VirtualShadowNode.stats}. */
+interface IVirtualShadowStats {
+    readonly frame: number;
+    readonly levels: number;
+    /** Levels whose window moved this frame and were re-rendered. */
+    readonly moved: number;
+    /** Levels re-rendered because `invalidateAll()` or explicit tracker invalidation asked for it. */
+    readonly invalidated: number;
+    /** Tracked casters, as of this frame. */
+    readonly movers: number;
+    /** Mover maps rendered this frame: one per level when at least one caster is tracked. */
+    readonly moverRenders: number;
+    /** Levels served from their cached map this frame. */
+    readonly cached: number;
+    /** Levels rendered this frame, for any reason. */
+    readonly rendered: number;
+    /** Fraction of levels served from cache over the node's lifetime. */
+    readonly reuseRatio: number;
+}
+declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
+/**
+ * The object layer tracked casters are enabled on, so each level's mover camera sees only them.
+ * Keep it free of other uses; the main camera never needs it (tracked objects keep layer 0).
+ */
+declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
+/**
+ * One directional shadow for a whole open world: camera-centred clip levels, each snapped to its
+ * own texel grid and re-rendered only when its window moves. Movers never touch that cache: a
+ * tracked caster draws into a second, per-level mover map every frame, and a fragment takes the
+ * darker of the two — so a walking stag costs one small render of itself, not a render of the wood.
+ *
+ * Plugs into three's own slot, so every material in the scene receives it with no other change:
+ * `light.shadow.shadowNode = new VirtualShadowNode(light, { clipExtents: [16, 48, 144] })`.
+ *
+ * What it owns is mechanism: level windows, texel snapping, per-level caching, invalidation,
+ * level selection and the statistics. The light's `shadow` keeps bias, normal bias, intensity,
+ * map type and filter, and those source settings are mirrored into each stock level node before
+ * rendering. Per-level map sizes, cameras, `autoUpdate` and `needsUpdate` are owned by this node.
+ * Each level is rendered by the stock {@link ShadowNode} through the renderer's shadow-map type,
+ * so the look is the same code path a plain shadow uses.
+ *
+ * Ported from the virtual-shadow-map prototype's clipmap and invalidation; the sparse page atlas
+ * is deliberately not the first cut — a page needs the scene rendered once per page, and on a
+ * forest of hundreds of instanced meshes three level renders are cheaper than twenty-four page
+ * renders. The page pool and demand pass in `virtual-shadow-pages.ts` stay ready for it.
+ *
+ * @situation crisp shadows close to the player across a large outdoor level
+ * @situation shadow map too coarse over a big terrain
+ * @situation one directional light shadow for a whole open world
+ * @situation shadows shimmer when the camera moves
+ * @constraint the light must be a DirectionalLight with `castShadow` and a target in the scene
+ * @constraint clipExtents are half-widths in world units, finest first, strictly increasing
+ * @constraint call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves
+ * @override bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
+ * @example
+ * const sun = new DirectionalLight(0xffffff, 3);
+ * sun.castShadow = true;
+ * sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });
+ */
+declare class VirtualShadowNode extends ShadowBaseNode {
+    #private;
+    static get type(): string;
+    readonly options: Required<Omit<IVirtualShadowOptions, "marker">> & {
+        readonly markerEvery: number;
     };
+    readonly clipmap: DirectionalClipmap;
+    /**
+     * Compatibility handle for explicit page invalidation. Automatic caster motion uses mover maps;
+     * callers that already update this tracker still invalidate the affected cached levels.
+     */
+    readonly tracker: ShadowInvalidationTracker;
+    constructor(light: DirectionalLight, options?: IVirtualShadowOptions);
+    /** The per-frame counters, as of the last `updateBefore`. */
+    get stats(): IVirtualShadowStats;
+    /** The stock shadow nodes behind each level, for diagnostics. */
+    get levelNodes(): readonly Node[];
+    /** The stock shadow nodes behind each level's mover map, for diagnostics. */
+    get moverNodes(): readonly Node[];
+    /** The placeholder lights, one per level; exposed for tests and debug views. */
+    get levelLights(): readonly Object3D[];
+    /**
+     * Make an object a mover: it leaves the cached level maps and draws into every level's mover
+     * map each frame, so its shadow follows it without a level render. Static geometry never
+     * needs this — a level re-renders whenever its window moves anyway.
+     */
+    trackCaster(object: Object3D): string;
+    untrackCaster(objectOrId: Object3D | string): boolean;
+    /** Force every level to re-render on the next frame — a tree fell, a door opened. */
+    invalidateAll(): void;
+    setup(builder: NodeBuilder): Node | null | undefined;
+    updateBefore(frame: NodeFrame): undefined;
+    dispose(): void;
+}
+/**
+ * Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.
+ *
+ * @situation inspect virtual shadow cache and mover counters from a renderer log
+ * @constraint non-marker lines and markers with incomplete or non-numeric stats return `undefined`
+ * @example
+ * const stats = readVirtualShadowMarker(line);
+ * if (stats !== undefined) console.log(stats.reuseRatio);
+ */
+declare function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined;
+
+/**
+ * Two load-time mechanisms every streaming game writes by hand, and gets wrong in the same places.
+ *
+ * A game that shows a loading curtain and builds its world behind it has two loops that decide how
+ * long the curtain stays up, and neither is about how anything looks: the loop that **fetches** the
+ * models and the loop that **attaches** the finished objects to the scene. Written naively, the
+ * first is serial and the second is one-object-per-frame, and both are slow for reasons that have
+ * nothing to do with the game.
+ *
+ * Measured in a real game (a 190 m valley, ~70 GLBs, ~400 attached objects), on the same build and
+ * the same content:
+ *
+ * | Attach loop  | Detail tier |
+ * | ------------ | ----------- |
+ * | 1 per frame  | 16.5 s      |
+ * | 6 per frame  | 11.26 s     |
+ * | 24 per frame | 9.39 s      |
+ * | 256 per frame| **6.89 s**  |
+ * | all at once  | 7.18 s      |
+ *
+ * and the fetch loop: 52 models one at a time took **38.4 s**; six at a time took **8.8 s**.
+ *
+ * Neither of these decides how anything looks. `addInSlices` never creates an object and never
+ * chooses where it goes — it is handed a list and the game's own `add`. `loadAll` never chooses
+ * what to load — it is handed a list and the game's own `load`. Geometry, material, colour,
+ * texture, curve and timing stay with the game in both, and a game can change its appearance
+ * completely without editing either.
+ *
+ * What they are not is code a game can get right portably by itself, which is why they live here.
+ * Yielding correctly is a platform seam: awaiting `requestAnimationFrame` deadlocks a host whose
+ * frames are pumped by the code doing the waiting, racing it against a timer reorders the frame
+ * sequence a harness observes, and a hard-coded `setTimeout(16)` is neither a frame on the native
+ * runtime nor a frame on a machine that cannot hold 60. See `yieldToHost` in `warmup.ts` for the
+ * two wrong versions that came before the one both of these use.
+ */
+/** How far a sliced attachment has got, reported once per slice. */
+interface IAddInSlicesProgress {
+    /** Objects attached so far. Never greater than `total`. */
+    readonly added: number;
+    /** Objects the run was given. Known before the first slice. */
+    readonly total: number;
+}
+interface IAddInSlicesOptions {
+    /**
+     * Objects attached between presented frames. Default 256.
+     *
+     * The default is large because the reason it used to be small has been taken over by something
+     * better. One per frame was right when nothing else compiled the world: the renderer built a few
+     * newly visible pipelines per presented frame instead of all of them inside one multi-second
+     * frame. It is not right once the framework warms the held scene (`warmUpScene`) — the compile is
+     * then paid either way and the slice only chooses where, so a small slice buys nothing and costs
+     * one present per object.
+     *
+     * 256 is where the measured curve flattens without giving up the yields entirely: over a few
+     * hundred objects it still presents a handful of frames, so a browser watchdog cannot see a hung
+     * page, and it costs nothing against attaching everything in one go.
+     */
+    readonly sliceSize?: number;
+    /** Called once per slice, and once more for a partial final slice. */
+    readonly onProgress?: (progress: IAddInSlicesProgress) => void;
+    /**
+     * How the run hands the loop back to the host between slices. Defaults to yielding one
+     * macrotask, which is one native-runtime loop iteration and therefore one presented frame.
+     */
+    readonly yieldFrame?: () => Promise<void>;
+    /**
+     * Asked before every object; a false answer stops the run.
+     *
+     * This is how a scene that can be torn down mid-attach stays correct. A generation invalidated
+     * by a restart, a scene change, or an HMR reload must stop attaching into a graph that is no
+     * longer current, and it must do so **without throwing** — a throw here is indistinguishable
+     * from a real attachment failure at the catch site, and games end up reporting a teardown as an
+     * asset error. The stop is reported instead, as `stopped` on the report.
+     */
+    readonly while?: () => boolean;
+    /** Silences the `TN_ADD_SLICES` marker. Never silences the report. Default true (on). */
+    readonly marker?: boolean;
+}
+/** What a sliced attachment did, so a caller can report it rather than assume it. */
+interface IAddInSlicesReport {
+    /** Objects actually handed to `add`. */
+    readonly added: number;
+    /** Objects the run was given. */
+    readonly total: number;
+    /** Slices the work was cut into, and therefore the frames the loop got to present, plus one. */
+    readonly slices: number;
+    /** Wall-clock milliseconds the run took, attaching and yielding together. */
+    readonly elapsedMs: number;
+    /** The slice size actually used — the default, or the one the game chose. */
+    readonly sliceSize: number;
+    /** Whether that slice size came from the game rather than from the default. */
+    readonly sliceSizeOverridden: boolean;
+    /** True when `while` ended the run early. `added` is then less than `total`. */
+    readonly stopped: boolean;
+}
+/** How far a bounded-concurrency load has got, reported once per settled item. */
+interface ILoadAllProgress {
+    /** Loads that have resolved. */
+    readonly settled: number;
+    /** Loads the run was given. Known before the first one starts. */
+    readonly total: number;
+}
+interface ILoadAllOptions {
+    /**
+     * Loads in flight at once. Default 6.
+     *
+     * Bounded rather than unbounded, because a full-width fan-out coalesces its completion callbacks
+     * into 100-200 ms tasks and freezes the loading screen it is filling — which reads as the hang
+     * the concurrency was added to remove. Six is also the per-host connection limit a browser
+     * applies to HTTP/1.1, so a larger number frequently buys queueing rather than parallelism.
+     */
+    readonly concurrency?: number;
+    /** Called after each load settles. */
+    readonly onProgress?: (progress: ILoadAllProgress) => void;
+    /**
+     * How the run hands the loop back to the host after each settled load. Defaults to yielding one
+     * macrotask, which is what keeps a progress bar moving while the lanes are busy.
+     */
+    readonly yieldFrame?: () => Promise<void>;
+    /** Silences the `TN_LOAD_ALL` marker. Never silences `onProgress`. Default true (on). */
+    readonly marker?: boolean;
+}
+/**
+ * Attach a built list of objects to the scene in slices, presenting a frame between each.
+ *
+ * The objects are already built and already the game's; this decides only *when* each one joins
+ * the graph. Order is the list's order, and there is no option to change it — an attach loop that
+ * reordered its input would change which object a positional lookup finds.
+ *
+ * @situation add hundreds of built objects to the scene without one multi-second frame
+ * @situation stream a detail tier in behind a loading curtain without the page looking hung
+ * @example
+ * const report = await addInSlices(detailObjects, (object) => ctx.add(object), {
+ *   onProgress: ({ added, total }) => setProgress(added / total),
+ *   while: () => generation.live,
+ * });
+ */
+declare function addInSlices<T>(objects: Iterable<T>, add: (object: T, index: number) => void, options?: IAddInSlicesOptions): Promise<IAddInSlicesReport>;
+/**
+ * Load a list with bounded concurrency, and hand the results back **in the input's order**.
+ *
+ * The ordering is the whole point and has no override. `Promise.all` already keeps order but runs
+ * everything at once; a hand-rolled worker pool bounds the lanes but pushes results as they land,
+ * so the array comes back in completion order — whatever the network happened to return. A game
+ * that picks from that list positionally then places a different model in the same spot on every
+ * load, and its world is never the same twice. That defect shipped in a real game and is why this
+ * writes each result to its item's own index and never appends.
+ *
+ * Fails closed like `Promise.all`: the first rejection rejects the call, and no lane starts a load
+ * it had not already begun.
+ *
+ * @situation load many models or textures in parallel instead of one at a time
+ * @situation keep a loading screen moving while a list of assets downloads
+ * @example
+ * const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`), {
+ *   onProgress: ({ settled, total }) => setProgress(settled / total),
+ * });
+ */
+declare function loadAll<TIn, TOut>(items: readonly TIn[], load: (item: TIn, index: number) => Promise<TOut>, options?: ILoadAllOptions): Promise<TOut[]>;
+
+/** One band of the spectrum, drawn on its own patch. */
+interface ISpectralOceanCascade {
+    /** The world-space edge length, in metres, this cascade's grid tiles across. */
+    readonly patchSize: number;
+}
+interface ISpectralOceanOptions {
+    /** Grid resolution per cascade. A power of two; the transform has no other shape. */
+    readonly resolution: number;
+    /**
+     * The cascades, largest patch first.
+     *
+     * Each one carries only the wavelengths the next-smaller patch cannot resolve, so the bands do
+     * not overlap and a wave is never counted twice. One cascade is a toy: the join between bands is
+     * where a spectral ocean visibly fails, so there is nothing to look at until there are two.
+     */
+    readonly cascades: readonly ISpectralOceanCascade[];
+    readonly windSpeed: number;
+    /** Wind heading in radians. */
+    readonly windDirection: number;
+    readonly gravity: number;
+    /** Overall spectrum scale. A wave height decision, so the game owns the number. */
+    readonly amplitude: number;
+    /**
+     * How sharply waves align with the wind, as the exponent on the directional spread.
+     *
+     * A spectrum-tuning number with no defensible default, so there is none.
+     */
+    readonly directionality: number;
+    /** Horizontal displacement scale. Zero is a pure heightfield; higher values sharpen crests. */
+    readonly choppiness: number;
+    /** Waves shorter than this are cut off, in metres. */
+    readonly smallWaveCutoff: number;
+    readonly seed: number;
+    /**
+     * Which clock advances the simulation. Defaults to the game's fixed step.
+     *
+     * Fixed, because this sea is something the game reads: `sampleHeight` reports its age in frames,
+     * and a field advanced by the display makes that age mean a different amount of time on every
+     * machine. A game whose ocean is only ever looked at can pass `"render"` and pay for exactly the
+     * frames it draws.
+     */
+    readonly cadence?: "fixed" | "render";
+    /**
+     * The grid the CPU height query is sampled on, per side. Zero disables the query entirely.
+     *
+     * This is not the simulation resolution. It is the size of the only thing copied back off the
+     * GPU, so it is the whole cost of being able to float something: `readbackResolution` squared
+     * floats, every `readbackEveryFrames` frames.
+     */
+    readonly readbackResolution: number;
+    /** Frames between height copies. Ignored when `readbackResolution` is zero. */
+    readonly readbackEveryFrames: number;
+}
+/** A height read from the CPU copy, with the age of the frame that produced it. */
+interface ISpectralOceanHeight {
+    readonly height: number;
+    /**
+     * Frames between the GPU state this height came from and now.
+     *
+     * A spectral ocean cannot offer an exact CPU height — there is no closed form, only texels the
+     * GPU made — so this number is the contract. A caller that ignores it floats a hull on water
+     * that is not the water being drawn, and nothing in the frame says so.
+     */
+    readonly staleFrames: number;
+}
+/**
+ * A spectral ocean: cascaded wave spectra, inverse-transformed on the GPU every frame.
+ *
+ * It draws nothing. The game builds its own mesh and its own material and reads
+ * `cascadeDisplacement(index)`; every colour, every foam threshold, every sky this water reflects
+ * is the game's, and none of it can be changed from here.
+ *
+ * What it offers that an analytic wave function cannot is the look. What it cannot offer is an
+ * exact CPU height: there is no closed form, only the texels the GPU produced, so `sampleHeight`
+ * is a throttled copy that is always some frames behind and always says how many. A game that
+ * needs the height to be exact wants an analytic field instead — that is a different contract, and
+ * the reason this class has a different name rather than a flag.
+ */
+declare class SpectralOcean extends Object3D implements IComputeDriven$1 {
+    #private;
+    readonly resolution: number;
+    readonly cascades: readonly ISpectralOceanCascade[];
+    readonly processCadence: "fixed" | "render";
+    readonly warmupNodes: readonly ComputeNode[];
+    /** Floats copied off the GPU per readback, so a report can state the cost rather than imply it. */
+    readonly readbackFloats: number;
+    constructor(options: ISpectralOceanOptions);
+    get released(): boolean;
+    /** Simulation steps dispatched. A report that cannot count its own dispatches proves nothing. */
+    get steps(): number;
+    /** How old the CPU height copy is, or `undefined` when the height query is switched off. */
+    get staleFrames(): number | undefined;
+    /** The `(displaceX, height, displaceZ, fold)` buffer the game's material reads. */
+    cascadeDisplacement(index: number): StorageBufferNode<"vec4">;
+    /** The world-space tile size of one cascade, which the game's material needs to place it. */
+    cascadePatchSize(index: number): number;
+    /** Seconds of wave time. The game advances it, so a paused game has a paused sea. */
+    advance(seconds: number): void;
+    /**
+     * The surface height at a world position, and how many frames behind it is.
+     *
+     * `undefined` until the first copy lands, and `undefined` forever when the height query was
+     * switched off — never zero, because a hull floating at zero is indistinguishable from a hull
+     * floating at sea level and that is exactly the mistake this must not allow.
+     */
+    sampleHeight(x: number, z: number): ISpectralOceanHeight | undefined;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    detach(): void;
 }
 
 interface IGPUParticles3DBuffers {
@@ -77,10 +1459,12 @@ interface IGPUParticles3DOptions {
     readonly start: (buffers: IGPUParticles3DBuffers) => ComputeNode;
     readonly process: (buffers: IGPUParticles3DBuffers) => ComputeNode;
 }
-declare class GPUParticles3D extends Sprite {
+declare class GPUParticles3D extends Sprite implements IComputeDriven$1 {
     #private;
     readonly amount: number;
     readonly buffers: IGPUParticles3DBuffers;
+    readonly processCadence: "render";
+    readonly warmupNodes: readonly ComputeNode[];
     emitting: boolean;
     constructor(options: IGPUParticles3DOptions);
     get released(): boolean;
@@ -90,22 +1474,348 @@ declare class GPUParticles3D extends Sprite {
     detach(): void;
 }
 
+interface IFluidFieldVector2 {
+    readonly x: number;
+    readonly y: number;
+}
+interface IFluidFieldOptions {
+    readonly resolution: number;
+    readonly viscosity?: number;
+    readonly pressureIterations?: number;
+    readonly maxSplats?: number;
+    readonly timeStep?: number;
+    readonly vorticity?: number;
+    readonly splatRadius?: number;
+}
+interface IFluidFieldSampler {
+    sample(uv: Node$1<"vec2">): StorageTextureNode;
+}
+/**
+ * Run a deterministic GPU fluid field whose data stays available to the game's render graph.
+ *
+ * The class is deliberately a scene object with the compute-driven lifecycle contract: adding it
+ * to a game scene attaches the renderer, warm-up sees every pass, fixed steps dispatch the passes,
+ * and removing it releases every GPU allocation. `dye` and `velocity` are read-only numeric
+ * samplers; the game decides what those values become when drawn.
+ * @situation simulate smoke, fire, fog, wind, or fluid response on a grid
+ * @situation inject a touch, pointer, or gameplay impulse into a fluid field
+ * @situation sample fluid dye or velocity in a game-owned render node
+ * @constraint add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
+ * @constraint `dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code
+ * @override pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
+ * @example const field = new FluidField2D({ resolution: 256, viscosity: 0, pressureIterations: 20 });
+ * ctx.add(field);
+ * field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
+ */
+declare class FluidField2D extends Group {
+    #private;
+    readonly resolution: number;
+    readonly viscosity: number;
+    readonly pressureIterations: number;
+    readonly maxSplats: number;
+    readonly timeStep: number;
+    readonly vorticity: number;
+    readonly splatRadius: number;
+    readonly processCadence: "fixed";
+    readonly warmupNodes: readonly ComputeNode[];
+    readonly velocity: IFluidFieldSampler;
+    readonly dye: IFluidFieldSampler;
+    constructor(options: IFluidFieldOptions);
+    get released(): boolean;
+    get queuedSplats(): number;
+    get steps(): number;
+    get splatsApplied(): number;
+    attachRenderer(renderer: IRendererLike): void;
+    splat(uv: IFluidFieldVector2, velocity: IFluidFieldVector2, amount: number): void;
+    process(renderer?: IRendererLike | undefined): void;
+    detach(): void;
+}
+
+type WaveDirection = readonly [number, number] | {
+    readonly x: number;
+    readonly z?: number;
+    readonly y?: number;
+};
+interface IWaveFieldWave {
+    readonly amplitude?: number;
+    readonly direction: WaveDirection;
+    readonly wavelength: number;
+    readonly speed: number;
+    readonly phase?: number;
+    readonly steepness?: number;
+    /**
+     * Mark this wave as detail: the graph fades it out with the `fade` node passed to
+     * `heightNode` / `normalNode`, and leaves it at full amplitude everywhere else.
+     *
+     * A wave shorter than the distance one screen pixel covers cannot be resolved, and what it
+     * produces instead is a crawling moire that reads as a repeating pattern. Fading it is the fix.
+     * `sample` on the CPU has no camera and therefore no fade, so CPU and GPU height differ by at
+     * most the summed amplitude of the detail waves — keep them small, or float things on the
+     * non-detail waves alone.
+     */
+    readonly detail?: boolean;
+}
+interface IWaveFieldDomainWarp {
+    readonly direction?: WaveDirection;
+    readonly waveVector?: WaveDirection;
+    readonly displacement?: WaveDirection;
+    readonly amplitude?: number;
+    readonly wavelength?: number;
+    readonly speed: number;
+    readonly phase?: number;
+}
+interface IWaveFieldOptions {
+    readonly waves: readonly IWaveFieldWave[];
+    readonly domainWarp?: readonly IWaveFieldDomainWarp[];
+}
+/** Where, when, and how finely to evaluate the field in a graph. */
+interface IWaveFieldGraphOptions {
+    /**
+     * The horizontal point to evaluate at, in whatever space the caller wants the answer in.
+     * Defaults to this vertex's local x and z.
+     */
+    readonly point?: Node<"vec2">;
+    /** The clock. Defaults to the field's own `time` uniform. */
+    readonly time?: Node<"float">;
+    /** A 0..1 multiplier on every wave marked `detail`. Omitted, detail waves stay at full size. */
+    readonly fade?: Node<"float">;
+}
+interface IWaveFieldSample {
+    readonly height: number;
+    readonly normal: Vector3;
+}
+/**
+ * An analytic wave field with one packed parameter source for CPU sampling and TSL displacement.
+ * It owns no geometry or appearance; a game chooses how the returned displacement is drawn.
+ */
+declare class WaveField {
+    #private;
+    readonly waves: readonly IWaveFieldWave[];
+    readonly domainWarp: readonly IWaveFieldDomainWarp[];
+    readonly parameters: Readonly<Float32Array>;
+    readonly time: three_webgpu.UniformNode<"float", number>;
+    constructor(options: IWaveFieldOptions);
+    /** Update the default graph clock. Explicit sample times remain available for fixed-step code. */
+    setTime(value: number): void;
+    sample(x: number, z: number, time: number): IWaveFieldSample;
+    /** Surface height at a point, as a graph. The scalar half of what `sample` returns. */
+    heightNode(options?: IWaveFieldGraphOptions): Node<"float">;
+    /**
+     * The analytic surface normal at a point, as a graph — the same value `sample` returns, and the
+     * reason a water material needs no hand-written ripple pattern.
+     *
+     * Differencing the height, or stamping a normal map over the surface, is what puts visible
+     * repeats in water: both quantise a field that has none. This differentiates the wave sum
+     * itself, so the normal repeats only where the waves do, which for wavelengths with no common
+     * multiple is nowhere.
+     *
+     * Evaluate it per fragment — pass `point` in world XZ — and the ripples survive at any distance
+     * from the camera, at the cost of the wave sum running per pixel rather than per vertex.
+     */
+    normalNode(options?: IWaveFieldGraphOptions): Node<"vec3">;
+    /** Return a TSL node that displaces local vertices using the same packed values as `sample`. */
+    displacementNode(timeNode?: three_webgpu.UniformNode<"float", number>): Node<"vec3">;
+}
+
+/** How the mirrored pass is sized. Both numbers are cost, not appearance. */
+interface IWaterReflectionOptions {
+    /**
+     * The mirrored pass's render target, as a fraction of the drawing buffer.
+     *
+     * A reflection is a second draw of the whole world, so this is the one number that decides
+     * whether a water surface is affordable. Half is the usual answer.
+     */
+    readonly resolutionScale: number;
+    /** Whether this surface may appear in other reflectors' passes. Off is one pass; on is n². */
+    readonly bounces?: boolean;
+}
+interface IWaterSurfaceOptions {
+    /** World-space height of the surface, in metres. The mirror plane, and where thickness is 0. */
+    readonly level: number;
+    /**
+     * Thickness readings saturate here, in metres.
+     *
+     * A required number because it is the range of the instrument, not a taste: sky behind the
+     * surface has no depth at all, and something has to be reported for it.
+     */
+    readonly maxThickness: number;
+    /** Omit for a surface that reflects nothing; `reflectionAt` then throws rather than lying. */
+    readonly reflection?: IWaterReflectionOptions;
+}
+/**
+ * What a horizontal water surface can see: the world mirrored in it, the world beneath it, and
+ * how much water stands between the two.
+ *
+ * This is the render plumbing a water material needs and cannot write portably — a mirrored
+ * camera and its render target, the frame's own colour read back as the light coming up through
+ * the surface, and the scene's depth turned into **metres of water under this pixel**. It decides
+ * nothing about how any of that looks: no colour, no absorption tint, no fresnel weighting, no
+ * glint. Those are the game's, composed from the nodes below in its own `src/render/` material.
+ *
+ * The depth reading is the part worth having. `linearDepth` answers in a normalised 0..1 that
+ * changes meaning with every camera near/far pair, so a material that subtracts two of them gets
+ * a number in no unit at all, and its shoreline moves when the camera's far plane does.
+ * `thicknessAt` returns metres, and metres survive the camera changing.
+ *
+ * ```js
+ * const surface = new WaterSurface3D({ level: 0, maxThickness: 4, reflection: { resolutionScale: 0.5 } });
+ * const offset = normal.xz.mul(0.02);
+ * material.colorNode = mix(
+ *   surface.refractionAt(offset).mul(siltTint),      // the game's colours,
+ *   surface.reflectionAt(offset),                    // composed by the game,
+ *   fresnel,                                         // with the game's own fresnel.
+ * );
+ * material.opacityNode = surface.thicknessAt().div(surface.maxThickness);
+ * ```
+ */
+declare class WaterSurface3D {
+    #private;
+    readonly maxThickness: number;
+    /**
+     * The object whose plane is mirrored, kept outside the scene graph on purpose.
+     *
+     * A water level is a fact about the world, not about the mesh that happens to draw it: parent
+     * the mirror to the surface mesh, as three's own examples do, and a non-uniform scale anywhere
+     * up that mesh's ancestry skews the plane the reflection is taken about. This one is placed
+     * from `level` and nothing else, so it stays level.
+     */
+    readonly target: Object3D | undefined;
+    constructor(options: IWaterSurfaceOptions);
+    /** The world-space height of the surface, in metres. */
+    get level(): number;
+    /** Move the surface — a tide, a sluice, a flooding room. The mirror plane follows. */
+    setLevel(value: number): void;
+    get released(): boolean;
+    /**
+     * The world mirrored in the surface, at an optional screen-space offset.
+     *
+     * The offset is where a game spends its surface normal: a still mirror takes none, and ripples
+     * are the normal's horizontal part scaled by however far the game wants the reflection to slide.
+     */
+    reflectionAt(offset?: Node<"vec2">): Node<"vec3">;
+    /**
+     * The frame beneath the surface — everything already drawn this frame, read at an offset.
+     *
+     * An offset that lands on something **in front of** the water is refused and the fragment falls
+     * back to a straight read. Without that, a rock standing in the shallows smears across the
+     * water in front of it: the classic refraction bleed, and the reason a hand-rolled offset looks
+     * wrong the first time every game writes one.
+     */
+    refractionAt(offset?: Node<"vec2">): Node<"vec3">;
+    /**
+     * Metres of water between this fragment and whatever is drawn behind it, clamped to
+     * `maxThickness`. Zero exactly where the bed meets the surface, which is the shoreline.
+     *
+     * Sky behind the surface has no depth and reads as `maxThickness`, not as zero: an unbounded
+     * horizon is deep water, not dry land.
+     */
+    thicknessAt(offset?: Node<"vec2">): Node<"float">;
+    /** Drop the mirrored pass and its render target. */
+    dispose(): void;
+}
+
+/**
+ * A soft round sprite, built as pixel data rather than by painting a canvas.
+ *
+ * Canvas-drawn images sample black under `WebGPURenderer` — a documented trap that cost a shipped
+ * game real debugging time — so sprite images are written straight into pixel data. A radial alpha
+ * falloff is also the whole difference between a puff and a rectangle: a flat quad reads as a grey
+ * box, the same quad with this alpha reads as smoke.
+ *
+ * @param size edge length in pixels
+ * @param hardness 0 fades from the very centre, 1 keeps a solid core out to the rim
+ */
+declare function softCircleDataTexture(size?: number, hardness?: number): DataTexture;
+
+interface ITracerPool3DOptions {
+    /** Slots in the pool. Shots over the count recycle the oldest streak. Default 12. */
+    readonly count?: number;
+    /**
+     * The streak's shape, supplied by the game. The default is a neutral unit-length cylinder
+     * along +Y with its base at the origin — the pool stretches it along y, so any geometry laid
+     * out the same way works. Override it to change the streak's cross-section or silhouette.
+     */
+    readonly geometry?: BufferGeometry;
+    /**
+     * The streak's surface, supplied by the game and cloned per slot so each can fade
+     * independently. Required: pooling, travel and fading are the engine's; what the streak
+     * looks like never is. Set `opacity` to the peak brightness and pass a transparent,
+     * additive surface for the usual bright-fade look.
+     */
+    readonly material: Material;
+    /** Longest streak in metres; shorter shots get a shorter streak. Default 3.2. */
+    readonly segmentLength?: number;
+    /** Travel speed in metres per second. Default 360. */
+    readonly speed?: number;
+    /** Seconds a streak lives before fading out fully. Default 0.11. */
+    readonly lifetime?: number;
+}
+/**
+ * Per-shot overrides a game passes to {@link TracerPool3D.spawn} — shot-to-shot variation
+ * keeps two rounds from reading as one drawn line. The values are the game's (usually from
+ * its seeded random so replays stay identical); the pool only applies them.
+ */
+interface ITracerSpawnOptions {
+    /** Longest streak for this shot, in metres. Defaults to the pool's `segmentLength`. */
+    readonly segmentLength?: number;
+    /** Seconds this streak lives before fading out fully. Defaults to the pool's `lifetime`. */
+    readonly lifetime?: number;
+    /** Multiplier on this streak's cross-section (x/z scale). Default 1. */
+    readonly widthScale?: number;
+}
+/**
+ * Pooled travelling bullet streaks for hitscan shots.
+ *
+ * A hitscan round leaves nothing to see, so a shot is only a sound and a number — you cannot tell
+ * where it went or who is firing. The pool draws a short bright segment that travels from the
+ * muzzle toward the point reached and fades out. Segments are stretched cylinders rather than
+ * `Line`s, because line width is not portable across backends and a one-pixel line is invisible at
+ * thirty metres.
+ *
+ * Every member starts visible at zero opacity, so the whole pool doubles as a pipeline prewarm
+ * surface (`prewarm(tracers)`); nothing is created while firing. Call {@link update} once per
+ * frame and {@link dispose} with the owning scene.
+ */
+declare class TracerPool3D {
+    #private;
+    constructor(parent: Object3D, options: ITracerPool3DOptions);
+    /**
+     * Stop submitting the slots that are not carrying a shot.
+     *
+     * The pool is resident from construction at zero opacity so its pipeline compiles during
+     * loading; the cost is a draw per dead streak every frame forever, and on a phone the draw call
+     * is the expensive part, not the triangles. Once compiled the pipeline is cached, so `spawn`
+     * re-showing a slot is free. Call this a second or two into the scene, after `prewarm` — not on
+     * the first frame, or the compile this exists to force will not have happened yet.
+     */
+    settle(): void;
+    /**
+     * Draw one round travelling from `from` along `direction` for `distance` metres.
+     * `options` carries the game's per-shot variation; omit it for the pool defaults.
+     */
+    spawn(from: Vector3, direction: Vector3, distance: number, options?: ITracerSpawnOptions): void;
+    /** Advance every live streak; call once per frame with the frame's delta seconds. */
+    update(dt: number): void;
+    /** Remove every mesh from the parent and release pooled surfaces. Game-owned geometry survives. */
+    dispose(): void;
+}
+
 interface IPathFollow3DOptions {
     readonly loop?: boolean;
     readonly points: readonly Vector3[];
     readonly speed?: number;
 }
 interface IPathFollow3DSample {
-    readonly point: Vector3;
-    readonly progress: number;
-    readonly tangent: Vector3;
+    point: Vector3;
+    progress: number;
+    tangent: Vector3;
 }
 interface IPathFollow3DProjection {
-    readonly distanceFromStart: number;
-    readonly lateralDistance: number;
-    readonly tangent: Vector3;
-    readonly point: Vector3;
-    readonly segment: number;
+    distanceFromStart: number;
+    lateralDistance: number;
+    tangent: Vector3;
+    point: Vector3;
+    segment: number;
 }
 /** A portable, distance-based follower for an authored Three.js route. */
 declare class PathFollow3D {
@@ -118,24 +1828,367 @@ declare class PathFollow3D {
     get progress(): number;
     get speed(): number;
     set speed(value: number);
-    advance(dt: number): IPathFollow3DSample;
+    advance(dt: number, target?: IPathFollow3DSample): IPathFollow3DSample;
     progressTo(distance: number): this;
-    sample(distance?: number): IPathFollow3DSample;
-    pointAt(distance: number): IPathFollow3DSample;
-    project(position: Vector3): IPathFollow3DProjection;
+    sample(distance?: number, target?: IPathFollow3DSample): IPathFollow3DSample;
+    pointAt(distance: number, target?: IPathFollow3DSample): IPathFollow3DSample;
+    project(position: Vector3, target?: IPathFollow3DProjection): IPathFollow3DProjection;
+}
+
+interface IGroundSnapOptions {
+    /** Whether to apply the correction. Measurement and `clearance` continue when this is false. */
+    readonly enabled?: boolean;
+    /** Maximum correction speed in metres per second. Unset follows the authored pose exactly. */
+    readonly maxRate?: number;
+    /** Visual meshes to measure. Defaults to every mesh below `model`. */
+    readonly meshes?: readonly Object3D[];
 }
+/**
+ * Keeps the lowest posed point of a rendered model on a surface.
+ *
+ * This is render grounding, not collider snap-to-ground. It uses a cached skin envelope so a
+ * frame loop never runs the precise per-vertex bounds path. `enabled` is deliberately a range:
+ * turning correction off still leaves `clearance` and `audit()` truthful.
+ */
+declare class GroundSnap {
+    readonly model: Object3D;
+    readonly meshes: readonly Object3D[] | undefined;
+    enabled: boolean;
+    maxRate: number | undefined;
+    clearance: number | null;
+    private readonly parentInverse;
+    private readonly parentOrigin;
+    private readonly parentTarget;
+    constructor(model: Object3D, options?: IGroundSnapOptions);
+    /** Move `group` so its lowest posed point meets `surfaceY`, then report the real clearance. */
+    apply(group: Object3D, surfaceY: number, dt: number): void;
+    private applyWorldCorrection;
+    /**
+     * Compare the cheap envelope's lower bound with a precise vertex measurement.
+     *
+     * This is intentionally opt-in: calling it in `apply()` would restore the frame-time defect
+     * this class exists to remove. A negative result means the envelope is below the precise skin.
+     */
+    audit(): number | null;
+}
+
+type ThreePoseVector = readonly [number, number, number];
+type ThreePoseQuaternion = readonly [number, number, number, number];
+interface IThreePoseBounds {
+    readonly min: ThreePoseVector;
+    readonly max: ThreePoseVector;
+    readonly size: ThreePoseVector;
+}
+/** JSON-safe world-space measurements for one Three.js object and its visual bounds. */
+interface IThreePoseMeasurement {
+    readonly name: string;
+    readonly type: string;
+    readonly position: ThreePoseVector;
+    readonly quaternion: ThreePoseQuaternion;
+    readonly scale: ThreePoseVector;
+    readonly axes: {
+        readonly x: ThreePoseVector;
+        readonly y: ThreePoseVector;
+        readonly z: ThreePoseVector;
+    };
+    readonly bounds: IThreePoseBounds | null;
+}
+interface IMeasureThreePoseOptions {
+    /**
+     * Objects whose geometry forms the reported bounds. Defaults to `object`.
+     * This path is precise; it walks every vertex. Do not call it in a frame loop — see
+     * `posedBounds`.
+     */
+    readonly bounds?: readonly Object3D[] | false;
+}
+/**
+ * Measure an Object3D in world space for attachment and animation diagnostics.
+ *
+ * Passing explicit `bounds` lets a probe measure a body without an attached weapon or
+ * invisible hitbox. The result is JSON-safe so it can cross the browser playtest bridge.
+ */
+declare function measureThreePose(object: Object3D, options?: IMeasureThreePoseOptions): IThreePoseMeasurement;
+/**
+ * Cheap world-space bounds for a posed model.
+ *
+ * The first call pays the precise vertex walk to build a conservative skin envelope. Later calls
+ * read one world-matrix translation per contributing bone and allocate nothing. The returned
+ * object is cached for the root and updated in place; copy it if it must outlive the next call.
+ */
+declare function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds;
+
+type PlatformRuntime = "web" | "native";
+type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
+type PlatformFormFactor = "mobile" | "desktop" | "unknown";
+interface IPlatformInfo {
+    readonly runtime: PlatformRuntime;
+    readonly os: PlatformOS;
+    readonly formFactor: PlatformFormFactor;
+    readonly maxTouchPoints: number;
+}
+declare function getPlatform(): Readonly<IPlatformInfo>;
+declare function isWeb(): boolean;
+declare function isNative(): boolean;
+declare function isMobile(): boolean;
+declare function isTouchscreenAvailable(): boolean;
+
+type ReplayPointer = readonly [number, number, number, number, number];
+interface IReplayRecordingSample {
+    readonly keys: readonly string[];
+    readonly pointer?: ReplayPointer;
+    readonly tick: number;
+}
+interface IReplayRecording {
+    readonly input: readonly IReplayRecordingSample[];
+    readonly randomState: number;
+    readonly runtime: {
+        agent: string;
+        core: string;
+        portable?: boolean;
+        rapier: string | null;
+        step: number;
+    };
+    readonly seed: number;
+    readonly ticks: number;
+    readonly version: 1;
+}
+declare function parseReplayRecording(value: unknown): IReplayRecording;
 
 type Recording = IReplayRecording;
+interface IReplayOptions {
+    /** Allow a recording to be replayed by a different host with the same simulation contract. */
+    readonly portable?: boolean;
+}
 type ReplayPublic = {
     readonly recording: Recording | undefined;
     readonly runId: symbol;
 };
-declare function replay<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(): IGamePluginHooks<TState, TPhysics> & ReplayPublic;
+declare function replay<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(options?: IReplayOptions): IGamePluginHooks<TState, TPhysics> & ReplayPublic;
 declare function createReplayDriver(recording: Recording, target: EventTarget, pointerTarget?: EventTarget): ((runtime: IGamePluginRuntime) => number) & {
     prepare: (runtime: IGamePluginRuntime) => void;
     runId: symbol;
 };
 
-declare const version = "0.1.0";
+type SpritePlaybackMode = "loop" | "pingPong" | "once";
+interface ISpriteFrame3D {
+    /** Pixels from the left edge of the atlas. */
+    readonly x: number;
+    /** Pixels from the top edge when `origin` is `"top-left"`. */
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** Seconds this frame is held; every frame must provide its own authored timing. */
+    readonly duration: number;
+}
+interface ISpriteAnimator3DOptions {
+    /** The game-owned atlas texture. Its filters, wrapping and surface remain untouched. */
+    readonly texture: Texture;
+    /** Pixel-space atlas rectangles with per-frame durations. */
+    readonly frames: readonly ISpriteFrame3D[];
+    readonly mode?: SpritePlaybackMode;
+    /** Atlas coordinate origin; top-left is conventional for exported sprite sheets. */
+    readonly origin?: "top-left" | "bottom-left";
+    /** Start advancing immediately unless the game explicitly opts out. */
+    readonly autoPlay?: boolean;
+}
+/**
+ * Advance a game-owned atlas texture on the fixed step supplied by its owner.
+ *
+ * This helper changes only `texture.offset` and `texture.repeat`. The game still chooses the
+ * texture, filters, wrapping, surface, geometry and every frame's duration. Call {@link update}
+ * from the scene's fixed-step update; no wall clock or global animation loop is consulted.
+ */
+declare class SpriteAnimator3D {
+    #private;
+    readonly texture: Texture;
+    readonly frames: readonly ISpriteFrame3D[];
+    readonly mode: SpritePlaybackMode;
+    readonly origin: "top-left" | "bottom-left";
+    constructor(options: ISpriteAnimator3DOptions);
+    get frameIndex(): number;
+    get elapsed(): number;
+    get finished(): boolean;
+    get playing(): boolean;
+    /** Advance by one caller-supplied fixed-step delta. */
+    update(dt: number): this;
+    /** Pause fixed-step advancement while leaving the selected frame visible. */
+    pause(): this;
+    /** Resume, restarting a completed one-shot from frame zero. */
+    play(): this;
+    /** Stop and reset to the first authored frame. */
+    stop(): this;
+    /** Select a frame without advancing time. */
+    setFrame(index: number): this;
+}
+
+/** Names of every bone in traversal order. Empty for an unskinned model. */
+declare function skeletonBones(root: Object3D): readonly string[];
+/** Parent a child to a named bone while preserving the child's authored world scale. */
+declare function attachToBone(root: Object3D, boneName: string, child: Object3D): Object3D;
+/** How far a bone sits from the object it is supposed to be touching. */
+interface IBoneContactReport {
+    readonly bone: string;
+    readonly target: string;
+    /** Metres from the bone to the nearest point of the target's world bounds. Zero when inside. */
+    readonly distance: number;
+    readonly inside: boolean;
+    readonly bonePosition: ThreePoseVector;
+    readonly targetPoint: ThreePoseVector;
+}
+/**
+ * Measure whether a named bone reaches a game object, in metres.
+ *
+ * This turns "his hands are on the keyboard" and "he is sitting on the chair" into numbers a
+ * scenario can assert. It walks the target's vertices through `measureThreePose`, so call it on
+ * a check or a debug sample rather than every frame.
+ */
+declare function boneContact(root: Object3D, boneName: string, target: Object3D): IBoneContactReport;
+
+/** One track of a clip, and whether it resolves to a real property on a root. */
+interface IClipTrackBinding {
+    readonly track: string;
+    /** The node the track names, or `null` when nothing under the root carries that name. */
+    readonly node: string | null;
+    readonly bound: boolean;
+    /** Three.js's own reason the track binds nothing. `null` when it binds. */
+    readonly reason: string | null;
+}
+interface IClipBindingReport {
+    readonly clip: string;
+    readonly tracks: number;
+    readonly bound: number;
+    /** Every track that drives nothing, in clip order. */
+    readonly unbound: readonly IClipTrackBinding[];
+}
+interface IClipCoverageReport {
+    readonly clip: string;
+    readonly bones: number;
+    readonly driven: readonly string[];
+    /** Bones no bound track touches. They hold whatever the previous clip left them in. */
+    readonly undriven: readonly string[];
+}
+interface IClipPoseSubject {
+    readonly root: Object3D;
+    readonly clip: AnimationClip;
+}
+interface IClipPoseErrorOptions {
+    /** Measured bone name to reference bone name. Defaults to the names the two rigs share. */
+    readonly bones?: Readonly<Record<string, string>>;
+    /** Poses compared across the clip. Defaults to 8. */
+    readonly samples?: number;
+}
+interface IBonePoseError {
+    readonly bone: string;
+    readonly reference: string;
+    readonly meanDegrees: number;
+    readonly maxDegrees: number;
+    readonly maxAtSeconds: number;
+}
+interface IClipPoseErrorReport {
+    readonly clip: string;
+    readonly referenceClip: string;
+    readonly samples: number;
+    readonly meanDegrees: number;
+    readonly maxDegrees: number;
+    /** Every compared bone, worst mean first. */
+    readonly bones: readonly IBonePoseError[];
+}
+/**
+ * Report which of a clip's tracks resolve to a real property on `root`.
+ *
+ * A retarget that writes the wrong glTF target path produces tracks named `<bone>.undefined`:
+ * they load without error, bind nothing, and the character plays its bind pose.
+ */
+declare function clipTrackBindings(root: Object3D, clip: AnimationClip): IClipBindingReport;
+/**
+ * Report which bones of `root` a clip does not drive.
+ *
+ * An undriven bone keeps whatever the previous clip left it in, so a rig whose clips cover 22 of
+ * 65 bones carries the last walk cycle's hand shape into every pose that follows.
+ */
+declare function clipBoneCoverage(root: Object3D, clip: AnimationClip): IClipCoverageReport;
+/**
+ * Score how far a clip's pose is from the same pose on a reference rig, in degrees.
+ *
+ * Each bone is compared as its world rotation *relative to its own rig's bind pose*, as a whole
+ * quaternion. The delta makes the two rigs' bind conventions cancel, so rigs whose arms sit 90
+ * degrees apart at rest still score zero when the retarget is right; the whole quaternion makes
+ * twist count, which a bone-direction check cannot see — a forearm rolled about its own axis
+ * points exactly where it should while the skin between elbow and wrist tears into a smear.
+ *
+ * Both rigs are driven and then restored to the transforms they arrived with.
+ */
+declare function clipPoseError(subject: IClipPoseSubject, reference: IClipPoseSubject, options?: IClipPoseErrorOptions): IClipPoseErrorReport;
+
+/**
+ * One rig's parent→child bone distances, captured at one moment.
+ *
+ * A rigid skeleton preserves every parent→child distance under any pose — that is what makes
+ * bone length the one number that names a broken pose without a screenshot (PRD-324).
+ */
+interface IBoneLengthSnapshot {
+    readonly bones: number;
+    /** Bone name → world distance to its parent bone, in metres. Bones without a bone parent are absent. */
+    readonly lengths: Readonly<Record<string, number>>;
+}
+/** One bone whose parent→child distance changed between the snapshot and now. */
+interface IBoneLengthDeviation {
+    readonly bone: string;
+    /** The distance at the snapshot, in metres. */
+    readonly bindLength: number;
+    /** The distance now, in metres. */
+    readonly posedLength: number;
+    /** `posedLength / bindLength`; `Infinity` when the bind distance was zero. */
+    readonly ratio: number;
+    /** `|posedLength − bindLength|`, in metres. */
+    readonly delta: number;
+}
+interface IBoneLengthDeviationReport {
+    readonly bones: number;
+    /** Bones actually compared: named in both the snapshot and now. */
+    readonly compared: number;
+    /** The largest relative change across compared bones. Zero for a rigid pose. */
+    readonly maxDeviation: number;
+    /** The worst deviating bone, or `null` when the pose is rigid. */
+    readonly worst: IBoneLengthDeviation | null;
+    /** Every bone past `tolerance`, worst first. */
+    readonly deviations: readonly IBoneLengthDeviation[];
+    /** True when no bone moved past `tolerance` relative to its bind distance. */
+    readonly rigid: boolean;
+}
+interface IBoneLengthDeviationsOptions {
+    /**
+     * Allowed relative change per bone before it is named. Default `0.01` — one per cent of its
+     * own bind length, which float noise sits far below and a pose defect sits far above.
+     */
+    readonly tolerance?: number;
+}
+/**
+ * Measure every parent→child bone distance, in world space, as the rig stands right now.
+ *
+ * World distances, so a uniform ancestor scale is part of the number: capture the baseline and
+ * the comparison under the same ancestor transform (in the usual shape, both after the rig's
+ * normalisation) and the scale cancels in the comparison.
+ */
+declare function boneLengths(root: Object3D): IBoneLengthSnapshot;
+/**
+ * Compare a rig's parent→child bone distances now against a captured snapshot.
+ *
+ * A rigid skeleton preserves every parent→child distance under any pose, so any named bone is
+ * a defect with an address: something moved a bone away from its parent — a position or scale
+ * track in the wrong space, a bind mismatch, a clipped hierarchy — and no screenshot needs to
+ * be squinted at to say which one (PRD-324).
+ */
+declare function boneLengthDeviations(root: Object3D, bind: IBoneLengthSnapshot, options?: IBoneLengthDeviationsOptions): IBoneLengthDeviationReport;
+
+/**
+ * The version this library reports.
+ *
+ * It read `0.1.0` while the package published `0.2.0`, and `__tests__/build.spec.ts` asserted the
+ * stale literal, so the test held the bug in place rather than catching it. A literal is
+ * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
+ * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
+ */
+declare const version = "0.3.1";
 
-export { AnimationPlayer, GPUParticles3D, IGamePluginHooks, IGamePluginRuntime, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IThreeNativeConfig, PathFollow3D, type Recording, type ThreeNativeOrientation, createReplayDriver, replay, version };
+export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, FluidField2D, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type ICameraShakeOffset, type ICameraShakeOptions, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILoadAllOptions, type ILoadAllProgress, type IMeasureThreePoseOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IPlatformInfo, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type ISkeletalMesh3DOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, type IStrideReport, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LUT_RESOLUTIONS, type NormaliseAxis, PROBE_VOLUME_MARKER, PathFollow3D, type PlatformFormFactor, type PlatformOS, type PlatformRuntime, ProbeVolume, type ProbeVolumeDensity, type Recording, type ReplayPointer, SkeletalMesh3D, SoftBody3D, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addInSlices, attachToBone, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, directionFromSolarPosition, directionalTransmittance, getPlatform, isMobile, isNative, isTouchscreenAvailable, isWeb, loadAll, measureThreePose, mergeParts, normaliseToMetres, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, readVirtualShadowMarker, replay, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, updateAtmosphereParameters, updateClusteredMeshes, version, zenithTransmittance };