@threenative/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,85 +1,1524 @@
-export { A as AudioBus, b as AudioBusOptions, c as AudioPlayOptions } from './audio-3vkjtiuo.js';
-import { R as RendererLike, a as GamePluginRuntime, b as GamePluginHooks } from './game-DRPs3M7r.js';
-export { A as AssetLoader, c as AssetLoaderOptions, C as CameraConfig, d as Ctx, D as Debuggable, E as EntitySnapshot, G as Game, e as GameConfig, f as GamePlatformSource, g as GamePlugin, h as GamePluginFunction, i as GameStore, I as InputAction, j as InputBindings, k as InputMap, O as OrthogonalCameraConfig, P as PerspectiveCameraConfig, l as PluginCleanup, m as Random, n as RawInputState, o as Registry, p as RendererKind, q as RendererOptions, S as Scene, r as SceneConstructor, s as SceneEnterResult, t as SceneFrame, u as ScheduleHandle, v as Scheduler, w as StatePatch, V as Viewport, x as ViewportOptions, y as ViewportResizeHandler, z as ViewportSize, B as autoFields, F as createAssetLoader, H as createGameStore, J as createRandom, K as createRenderer, L as defineGame, M as input } from './game-DRPs3M7r.js';
-import { AnimationMixer, AnimationClip, Object3D, Sprite } from 'three';
-import { StorageBufferNode, SpriteNodeMaterial, ComputeNode } from 'three/webgpu';
-import { IReplayRecording } from '@threenative/playtest';
+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 * as three_webgpu from 'three/webgpu';
+import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, SpriteNodeMaterial, StorageTextureNode } from 'three/webgpu';
+import { Node as Node$1 } from 'three/src/nodes/Nodes.js';
 import 'zustand/vanilla';
 
-interface AnimationPlayerOptions {
+interface IAnimationPlayerOptions {
     readonly clips: readonly AnimationClip[];
     readonly root: Object3D;
+    /**
+     * 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;
 }
-interface AnimationPlayOptions {
+/**
+ * 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;
+}
+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;
-    constructor(options: AnimationPlayerOptions);
+    constructor(options: IAnimationPlayerOptions);
     get current(): string | undefined;
     get advancedFrames(): number;
-    play(name: string, options?: AnimationPlayOptions): void;
+    /** 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;
 }
 
-interface FixedStepLoopOptions {
-    readonly step?: number;
-    readonly maxSteps?: number;
-    readonly onUpdate: (dt: number) => void;
-    readonly onRender?: () => void;
-    readonly requestFrame?: (callback: (time: number) => void) => number;
-    readonly cancelFrame?: (handle: number) => void;
+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;
 }
-declare class FixedStepLoop {
+/**
+ * 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 step: number;
-    readonly maxSteps: number;
-    constructor(options: FixedStepLoopOptions);
-    get running(): boolean;
-    get fps(): number;
-    start(now?: number): void;
-    stop(): void;
-    stepFrame(now: number): number;
-    advance(ticks: number): number;
+    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
+ * @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$1 {
+    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
+ * @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 {
+    #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;
+
+/**
+ * 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[];
+}
+
+/** 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 {
+    #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 {
+    #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;
+}
+
+/**
+ * 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 = {
+    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;
+interface IProbeVolumeOptions {
+    /** World-space bounds; the volume does not move with the object after construction. */
+    readonly bounds: Box3 | {
+        readonly min: IVector3Like;
+        readonly max: IVector3Like;
+    };
+    /** 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 {
+    #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>;
+    /**
+     * Return the L2 irradiance node for a world position and world normal.
+     *
+     * `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.
+     */
+    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;
+}
+
+/** 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 {
+    #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 GPUParticles3DBuffers {
+interface IGPUParticles3DBuffers {
     readonly positions: StorageBufferNode<"vec3">;
     readonly velocities: StorageBufferNode<"vec3">;
 }
-interface GPUParticles3DOptions {
+interface IGPUParticles3DOptions {
     readonly amount: number;
     readonly material: SpriteNodeMaterial;
-    readonly start: (buffers: GPUParticles3DBuffers) => ComputeNode;
-    readonly process: (buffers: GPUParticles3DBuffers) => ComputeNode;
+    readonly start: (buffers: IGPUParticles3DBuffers) => ComputeNode;
+    readonly process: (buffers: IGPUParticles3DBuffers) => ComputeNode;
 }
-declare class GPUParticles3D extends Sprite {
+declare class GPUParticles3D extends Sprite implements IComputeDriven {
     #private;
     readonly amount: number;
-    readonly buffers: GPUParticles3DBuffers;
+    readonly buffers: IGPUParticles3DBuffers;
+    readonly processCadence: "render";
+    readonly warmupNodes: readonly ComputeNode[];
     emitting: boolean;
-    constructor(options: GPUParticles3DOptions);
+    constructor(options: IGPUParticles3DOptions);
     get released(): boolean;
-    attachRenderer(renderer: RendererLike): void;
-    process(renderer?: RendererLike | undefined): void;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
     restart(): void;
     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;
+}
+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[];
+}
+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;
+    /** 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">;
+}
+
+/**
+ * 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 {
+    point: Vector3;
+    progress: number;
+    tangent: Vector3;
+}
+interface IPathFollow3DProjection {
+    distanceFromStart: number;
+    lateralDistance: number;
+    tangent: Vector3;
+    point: Vector3;
+    segment: number;
+}
+/** A portable, distance-based follower for an authored Three.js route. */
+declare class PathFollow3D {
+    #private;
+    readonly curve: CatmullRomCurve3;
+    readonly loop: boolean;
+    readonly totalLength: number;
+    constructor(options: IPathFollow3DOptions);
+    get completed(): boolean;
+    get progress(): number;
+    get speed(): number;
+    set speed(value: number);
+    advance(dt: number, target?: IPathFollow3DSample): IPathFollow3DSample;
+    progressTo(distance: number): this;
+    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>(): GamePluginHooks<TState, TPhysics> & ReplayPublic;
-declare function createReplayDriver(recording: Recording, target: EventTarget, pointerTarget?: EventTarget): ((runtime: GamePluginRuntime) => number) & {
-    prepare: (runtime: GamePluginRuntime) => void;
+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;
+}
+
+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;
+
+/** 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;
+
+/**
+ * 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.0";
 
-export { type AnimationPlayOptions, AnimationPlayer, type AnimationPlayerOptions, FixedStepLoop, type FixedStepLoopOptions, GPUParticles3D, type GPUParticles3DBuffers, type GPUParticles3DOptions, GamePluginHooks, GamePluginRuntime, type Recording, RendererLike, createReplayDriver, replay, version };
+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 };