@threenative/core 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -1,18 +1,23 @@
 import * as three from 'three';
-import { AnimationMixer, AnimationClip, Object3D, Camera, Vector3, Group, Matrix4, Mesh, BufferGeometry, Material, InstancedMesh, Box3, Scene, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
-import { a as IGamePluginRuntime, b as IGamePluginHooks } from './game-CYIaKhgl.js';
-export { C as ContextMenuPolicy, c as IAssetLoader, d as IAssetLoaderOptions, e as ICtx, I as IGame, f as IGameObservationContribution, g as IGameObservationSampleRequest, h as IGamePlatformSource, i as IInputAction, j as IInputGamepad, k as IPointerDragHandle, l as IPointerEvent3D, m as IPointerEvents3D, n as IPointerEvents3DOptions, o as IPointerEvents3DPicker, p as IPointerState, q as IRandom, r as IRawInputPointer, s as IRawInputPointerEdge, t as IRawInputState, u as IRaycastOptions, v as IScenePickerOptions, w as IThreeNativeBootSplash, x as IThreeNativeConfig, y as IThreeNativeIconVariants, z as IThreeNativeTexturesConfig, A as ITweenOptions, B as IWarmUpOptions, D as IWarmUpProgress, E as IWarmUpRenderer, F as IWarmUpReport, G as InputBindings, H as InputPlatformSource, P as PointerEvent3DListener, J as PointerEvent3DType, K as PointerEvents3D, S as Scene, L as SceneFrame, M as ScenePicker, N as ScheduleHandle, O as Scheduler, T as ThreeNativeBackgroundMode, Q as ThreeNativeOrientation, R as ThreeNativeUiRenderer, U as createAssetLoader, V as createRandom, W as defineGame, X as warmUpScene } from './game-CYIaKhgl.js';
-export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions } from './audio-Dp2mXpD3.js';
-import { I as IRendererLike } from './canvas-layer-CtrZHgIh.js';
-export { C as CanvasLayer, 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 IRenderChainApplied, j as IRenderChainBudgetWindow, k as IRenderChainDroppedStage, l as IRenderChainOptions, m as IRenderChainRenderer, n as IRenderChainRequest, o as IRenderChainStage, p as IRenderChainStageContext, q as IRenderChainVelocityMeasurement, r as IRenderChainVelocityReport, s as IRenderChainVelocityRequest, t as IRenderChainVelocityResult, u as IVelocityRenderPass, R as RENDER_CHAIN_MARKER, v as RENDER_CHAIN_STAGE_ORDER, w as RENDER_CHAIN_TIERS, x as RenderChain, y as RenderChainSource, z as RenderChainStageName, A as RenderChainTier, B as RenderChainTierRequest, D as RenderChainVelocitySource, V as VELOCITY_OUTPUT_NAME, E as VELOCITY_PREVIOUS_BONE_MATRICES, G as VELOCITY_PREVIOUS_INSTANCE_MATRICES, H as VELOCITY_PREVIOUS_WORLD_MATRIX, J as VelocityTracker, K as ensureVelocityOutput, L as prewarm, M as readRenderChainObservation, N as readRenderChainReport, O as readVelocityPreviousBoneMatrices, P as readVelocityPreviousMatrices, Q as readVelocityPreviousWorldMatrix, S as velocityTexture, T as withVelocityContext } from './canvas-layer-CtrZHgIh.js';
+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, SpriteNodeMaterial, StorageTextureNode } 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.
      *
@@ -49,6 +54,15 @@ interface IStrideReport {
     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;
@@ -61,6 +75,7 @@ interface IAnimationPlayOptions {
 declare class AnimationPlayer {
     #private;
     readonly mixer: AnimationMixer;
+    readonly root: Object3D;
     constructor(options: IAnimationPlayerOptions);
     get current(): string | undefined;
     get advancedFrames(): number;
@@ -82,6 +97,33 @@ declare class AnimationPlayer {
     dispose(): void;
 }
 
+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. */
@@ -216,6 +258,7 @@ declare function zenithTransmittance(parameters: IAtmosphereParameters | IResolv
 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 });
@@ -277,7 +320,7 @@ declare class AtmosphereLuts {
 type IAtmosphereParametersLike = IResolvedAtmosphereParameters | IAtmosphereParameters;
 
 /** The structural contract consumed by the compute registry from PRD-242. */
-interface IComputeDriven$1 {
+interface IComputeDriven {
     readonly warmupNodes: readonly unknown[];
     attachRenderer(renderer: IRendererLike): void;
     readonly processCadence?: "fixed" | "render";
@@ -299,12 +342,13 @@ type AtmosphereDirection = Vector3 | readonly [number, number, number] | Node<"v
  * 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$1 {
+declare class Atmosphere extends Group implements IComputeDriven {
     #private;
     readonly luts: AtmosphereLuts;
     constructor(options: IAtmosphereOptions);
@@ -341,114 +385,6 @@ declare class Atmosphere extends Group implements IComputeDriven$1 {
  */
 declare function solarPositionAt(date: Date | string, latitude: number, longitude: number): ISolarPosition;
 
-/**
- * The lifecycle contract for a game-owned GPU simulation.
- *
- * A compute-driven object owns its kernels, buffers, and appearance. The framework only attaches
- * the active renderer, warms the kernels before the world is shown, dispatches process calls at
- * the object's declared cadence, and releases the object when its scene ends.
- */
-interface IComputeDriven {
-    /** Kernels to compile before the world is shown. Read once, at attach. */
-    readonly warmupNodes: readonly unknown[];
-    attachRenderer(renderer: IRendererLike): void;
-    /**
-     * The loop phase that dispatches `process`. Defaults to fixed-step; render cadence preserves the
-     * existing behavior of consumers whose simulation is intentionally tied to presentation.
-     */
-    readonly processCadence?: "fixed" | "render";
-    /** Dispatched once per fixed step, in scene-add order unless render cadence is declared. */
-    process(renderer: IRendererLike): void;
-    detach(): void;
-    readonly released: boolean;
-}
-/** The ordered registry used by the game loop for all compute-driven scene objects. */
-declare class ComputeDrivenRegistry {
-    #private;
-    get size(): number;
-    /** Attach and remember one object. Re-adding the same object is idempotent. */
-    add(object: Object3D & IComputeDriven, renderer: IRendererLike): void;
-    /** Release one object without disturbing the order of the remaining objects. */
-    remove(driven: IComputeDriven): void;
-    /** Kernels in the same order as their objects were added to the scene. */
-    get warmupNodes(): readonly unknown[];
-    /** Dispatch fixed-step objects once; detached scene children are released before dispatch. */
-    process(renderer: IRendererLike): void;
-    /** Dispatch render-cadence objects once; detached scene children are released before dispatch. */
-    processRender(renderer: IRendererLike): void;
-    /** Release every registered object, continuing after a failure so no resource is stranded. */
-    clear(): void;
-}
-
-interface IGPUReadbackOptions {
-    /** The GPU storage attribute to copy — a TSL storage node's `.value`. */
-    readonly attribute: unknown;
-    /**
-     * Frames between readback requests. `1` asks every frame; larger values throttle.
-     *
-     * A copy off the GPU costs a queue submission and a mapped buffer, so a game reading a field it
-     * only consults for physics asks for it every few frames and pays the staleness instead.
-     */
-    readonly everyFrames: number;
-}
-/** A landed copy of GPU memory, with the age of the frame that produced it. */
-interface IGPUReadbackSample {
-    readonly data: Float32Array;
-    /**
-     * Frames between the frame whose GPU state these bytes hold and the frame reading them.
-     *
-     * This is the number a caller must not be allowed to ignore. A buoyancy solver that treats a
-     * 4-frame-old surface as this frame's surface floats a hull through the water it is drawn on,
-     * and nothing in the frame says so.
-     */
-    readonly staleFrames: number;
-}
-/**
- * A throttled, fire-and-forget copy of a GPU buffer into CPU memory.
- *
- * Every sample it hands back carries its own age. That is the whole point: the copy is
- * asynchronous, so the bytes are always some frames behind the GPU, and a class that hid that
- * would let a caller mistake stale data for live data with no way to find out.
- *
- * `request()` never awaits and never blocks the frame. One copy is in flight at a time; requests
- * made while one is pending are dropped rather than queued, because a backlog of copies of a field
- * that has already moved on is latency with no information in it.
- */
-declare class GPUReadback {
-    #private;
-    readonly everyFrames: number;
-    constructor(options: IGPUReadbackOptions);
-    get released(): boolean;
-    /** True while a copy is in flight. A game that wants to pace its own work can read it. */
-    get pending(): boolean;
-    /** The newest landed bytes, or `undefined` before the first copy lands. */
-    get data(): Float32Array | undefined;
-    /**
-     * How many frames old the landed bytes are.
-     *
-     * Before anything has landed this is the number of frames since construction, which grows
-     * without bound on purpose: "no data yet" and "data from frame zero" must not read the same.
-     */
-    get staleFrames(): number;
-    /** The newest bytes with their age attached, or `undefined` before the first copy lands. */
-    get sample(): IGPUReadbackSample | undefined;
-    /** Requests, landings and failures, for a report that has to say why a sample is old. */
-    get stats(): {
-        readonly requests: number;
-        readonly lands: number;
-        readonly failures: number;
-    };
-    /**
-     * Advances the frame clock and starts a copy when the throttle allows one.
-     *
-     * Safe to call every frame. It returns before the GPU has answered — awaiting it is the one
-     * thing that would turn this class into the stall it exists to avoid.
-     */
-    request(renderer: IRendererLike): void;
-    /** Drops the attribute reference and the landed bytes. Further requests throw. */
-    dispose(): void;
-}
-
 interface IClothTopologyOptions {
     /** Original geometry vertex indices that never move. Duplicate positions pin together. */
     readonly pinned: readonly number[];
@@ -493,7 +429,7 @@ interface ISoftBody3DOptions extends IClothTopologyOptions {
  * @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 {
+declare class SoftBody3D extends Mesh<BufferGeometry, NodeMaterial> implements IComputeDriven$1 {
     #private;
     readonly processCadence: "fixed";
     readonly warmupNodes: readonly ComputeNode[];
@@ -542,7 +478,7 @@ declare const rayStruct: StructTypeNode;
  * 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 {
+declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
     #private;
     readonly indices: StorageBufferNode<"uvec3">;
     readonly nodes: StorageBufferNode<"struct">;
@@ -640,6 +576,37 @@ declare class InstancedBatch {
     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.
  *
@@ -809,7 +776,7 @@ declare class ClusteredBatch {
 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 = {
+type IVector3Like$1 = {
     readonly x: number;
     readonly y: number;
     readonly z: number;
@@ -822,12 +789,12 @@ interface IProbeVolumeCoefficient {
     readonly b: number;
 }
 /** Probe density in probes per world unit, either isotropic or per-axis. */
-type ProbeVolumeDensity = number | readonly [number, number, number] | IVector3Like;
+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;
-        readonly max: IVector3Like;
+        readonly min: IVector3Like$1;
+        readonly max: IVector3Like$1;
     };
     /** Probe spacing expressed as probes per world unit. */
     readonly density: ProbeVolumeDensity;
@@ -891,7 +858,7 @@ declare function readProbeVolumeObservation(value: unknown): IProbeVolumeObserva
  * 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 {
+declare class ProbeVolume extends Object3D implements IComputeDriven$1 {
     #private;
     readonly isProbeVolume = true;
     readonly processCadence: "render";
@@ -943,6 +910,434 @@ declare class ProbeVolume extends Object3D implements IComputeDriven {
     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;
+    };
+    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. */
@@ -1021,7 +1416,7 @@ interface ISpectralOceanHeight {
  * 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 {
+declare class SpectralOcean extends Object3D implements IComputeDriven$1 {
     #private;
     readonly resolution: number;
     readonly cascades: readonly ISpectralOceanCascade[];
@@ -1064,7 +1459,7 @@ interface IGPUParticles3DOptions {
     readonly start: (buffers: IGPUParticles3DBuffers) => ComputeNode;
     readonly process: (buffers: IGPUParticles3DBuffers) => ComputeNode;
 }
-declare class GPUParticles3D extends Sprite implements IComputeDriven {
+declare class GPUParticles3D extends Sprite implements IComputeDriven$1 {
     #private;
     readonly amount: number;
     readonly buffers: IGPUParticles3DBuffers;
@@ -1148,6 +1543,17 @@ interface IWaveFieldWave {
     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;
@@ -1162,6 +1568,18 @@ 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;
@@ -1180,8 +1598,120 @@ declare class WaveField {
     /** 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>): three_webgpu.Node<"vec3">;
+    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;
 }
 
 /**
@@ -1491,25 +2021,165 @@ declare class SpriteAnimator3D {
     setFrame(index: number): this;
 }
 
-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;
+/** 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;
 }
 /**
- * Scale an asset to a real-world size and return the factor applied.
+ * Measure whether a named bone reaches a game object, in metres.
  *
- * 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.
+ * 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 normaliseToMetres(object: Object3D, options: INormaliseToMetresOptions): number;
+declare function boneContact(root: Object3D, boneName: string, target: Object3D): IBoneContactReport;
 
-/** 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;
+/** 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.
@@ -1519,6 +2189,6 @@ declare function attachToBone(root: Object3D, boneName: string, child: Object3D)
  * 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.0";
+declare const version = "0.3.1";
 
-export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, ComputeDrivenRegistry, FluidField2D, GPUParticles3D, GPUReadback, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type ICameraShakeOffset, type ICameraShakeOptions, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, type IComputeDriven, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, type IGPUReadbackOptions, type IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type IMeasureThreePoseOptions, 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 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 IWaveFieldDomainWarp, 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, SoftBody3D, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, type WaveDirection, WaveField, attachToBone, bvhIntersectFirstHit, createReplayDriver, directionFromSolarPosition, directionalTransmittance, getPlatform, isMobile, isNative, isTouchscreenAvailable, isWeb, measureThreePose, normaliseToMetres, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, replay, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, updateAtmosphereParameters, updateClusteredMeshes, version, zenithTransmittance };
+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 };