@threenative/core 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -1,23 +1,222 @@
 import * as three from 'three';
-import { AnimationMixer, Object3D, AnimationClip, Camera, Vector3, Group, Matrix4, Mesh, BufferGeometry, Material, InstancedMesh, ColorRepresentation, Box3, Scene, DirectionalLight, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
-export { I as IAssetLoader, a as IAssetLoaderOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-kyoF7JlJ.js';
-export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions } from './audio-BFiGneTL.js';
-export { C as CanvasLayer } from './canvas-layer-BLVijiUJ.js';
-import { a as IGamePluginRuntime, b as IGamePluginHooks } from './game-XGrTzapq.js';
-export { A as AfterPhysicsCallback, C as ContextMenuPolicy, c as ICtx, I as IGame, d as IGameObservationContribution, e as IGameObservationSampleRequest, f as IGamePlatformSource, g as IInputAction, h as IInputGamepad, i as IPointerDragHandle, j as IPointerEvent3D, k as IPointerEvents3D, l as IPointerEvents3DOptions, m as IPointerEvents3DPicker, n as IPointerState, o as IRandom, p as IRawInputPointer, q as IRawInputPointerEdge, r as IRawInputState, s as IRaycastOptions, t as IScenePickerOptions, u as IThreeNativeAudioConfig, v as IThreeNativeAudioLoop, w as IThreeNativeAudioOverride, x as IThreeNativeAudioSpectrum, y as IThreeNativeBootSplash, z as IThreeNativeConfig, B as IThreeNativeIconVariants, D as IThreeNativeTexturesConfig, E as ITweenOptions, F as IWarmUpCacheOptions, G as IWarmUpObservation, H as IWarmUpOptions, J as IWarmUpProgress, K as IWarmUpRenderer, L as IWarmUpReport, M as InputBindings, N as InputPlatformSource, P as PointerEvent3DListener, O as PointerEvent3DType, Q as PointerEvents3D, S as Scene, R as SceneFrame, T as ScenePicker, U as ScheduleHandle, V as Scheduler, W as ThreeNativeBackgroundMode, X as ThreeNativeOrientation, Y as ThreeNativeUiRenderer, Z as WarmUpCacheStatus, _ as WarmUpObservationStatus, $ as afterPhysics, a0 as createRandom, a1 as defineGame, a2 as warmUpScene } from './game-XGrTzapq.js';
+import { Object3D, AnimationClip, AnimationMixer, Camera, Vector3, Group, Matrix4, Mesh, BufferGeometry, InstancedMesh, Material, ColorRepresentation, Box3, Scene, DirectionalLight, HemisphereLight, Color, FogExp2, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
+export { I as IAssetLoader, a as IAssetLoaderOptions, b as ITextureOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-CqvE429w.js';
+export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-7i3Xl0l3.js';
+export { C as CanvasLayer } from './canvas-layer-DDmC_VVF.js';
+import { a as IGamePluginRuntime, b as IGamePluginHooks } from './game-CljaDv4D.js';
+export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as InputMap, a3 as InputPlatformSource, a4 as PointerEvent3DListener, a5 as PointerEvent3DType, a6 as PointerEvents3D, a7 as Scene, a8 as SceneFrame, a9 as ScenePicker, aa as ScheduleHandle, ab as Scheduler, ac as ThreeNativeBackgroundMode, ad as ThreeNativeLodMinTrianglesScope, ae as ThreeNativeLodPreset, af as ThreeNativeOrientation, ag as ThreeNativeUiRenderer, ah as WarmUpCacheStatus, ai as WarmUpObservationStatus, aj as afterPhysics, ak as captureMouse, al as createRandom, am as defineGame, an as warmUpScene } from './game-CljaDv4D.js';
 import * as three_webgpu from 'three/webgpu';
 import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode } from 'three/webgpu';
-import { I as IRendererLike } from './renderer-C6hqZpoG.js';
-export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, F as FRAME_BUDGET_MARKER, a as FRAME_BUDGET_PHASES, b as FRAME_HITCH_MARKER, c as FrameBudget, d as FrameBudgetPhase, e as IFrameBudgetOptions, f as IFrameBudgetSummary, g as IFrameBudgetWindow, h as IFramePhaseSample, i as IPipelineCensus, j as IPipelineCensusCounts, k as IPipelineCensusEvent, l as IPipelineCensusOptions, m as IPipelineProvenance, n as IPipelineShaderObservation, o as IRenderChainApplied, p as IRenderChainBudgetWindow, q as IRenderChainDroppedStage, r as IRenderChainOptions, s as IRenderChainRenderer, t as IRenderChainRequest, u as IRenderChainStage, v as IRenderChainStageContext, w as IRenderChainVelocityMeasurement, x as IRenderChainVelocityReport, y as IRenderChainVelocityRequest, z as IRenderChainVelocityResult, A as IVelocityRenderPass, P as PIPELINE_CENSUS_CAPABILITY, B as PIPELINE_CENSUS_VERSION, C as PipelineCensus, E as PipelineCensusMode, G as PipelineCensusStatus, R as RENDER_CHAIN_MARKER, H as RENDER_CHAIN_STAGE_ORDER, J as RENDER_CHAIN_TIERS, K as RenderChain, L as RenderChainSource, M as RenderChainStageId, N as RenderChainStageName, O as RenderChainTier, Q as RenderChainTierRequest, S as RenderChainVelocitySource, V as VELOCITY_OUTPUT_NAME, T as VELOCITY_PREVIOUS_BONE_MATRICES, U as VELOCITY_PREVIOUS_INSTANCE_MATRICES, W as VELOCITY_PREVIOUS_WORLD_MATRIX, X as VelocityTracker, Y as createPipelineCensus, Z as ensureVelocityOutput, _ as prewarm, $ as readRenderChainObservation, a0 as readRenderChainReport, a1 as readVelocityPreviousBoneMatrices, a2 as readVelocityPreviousMatrices, a3 as readVelocityPreviousWorldMatrix, a4 as velocityTexture, a5 as withVelocityContext } from './renderer-C6hqZpoG.js';
-import { I as IComputeDriven$1, a as IGPUReadbackSample } from './gpu-readback-D2iRvoe9.js';
-export { C as ComputeDrivenRegistry, G as GPUReadback, b as IGPUReadbackOptions } from './gpu-readback-D2iRvoe9.js';
+import { I as IRendererLike, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-CfsS2hxi.js';
+export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, b as DEFAULT_TARGET_FPS, c as FRAME_BUDGET_MARKER, d as FRAME_BUDGET_PHASES, e as FRAME_HITCH_MARKER, f as FrameBudget, g as FrameBudgetPhase, h as FrameCounters, i as ICounterDevice, j as IFrameBudgetOptions, k as IFrameBudgetPassSummary, l as IFrameBudgetSummary, m as IFrameCounters, n as IFramePhaseSample, o as IPipelineCensus, p as IPipelineCensusCounts, q as IPipelineCensusEvent, r as IPipelineCensusOptions, s as IPipelineProvenance, t as IPipelineShaderObservation, u as IPlatformInfo, v as IRenderChainApplied, w as IRenderChainBudgetWindow, x as IRenderChainDroppedStage, y as IRenderChainOptions, z as IRenderChainRenderer, A as IRenderChainRequest, B as IRenderChainStage, C as IRenderChainStageContext, E as IRenderChainVelocityMeasurement, G as IRenderChainVelocityReport, H as IRenderChainVelocityRequest, J as IRenderChainVelocityResult, K as IRenderPassSample, L as ITargetFps, M as IVelocityRenderPass, N as MAX_TARGET_FPS, P as PIPELINE_CENSUS_CAPABILITY, O as PIPELINE_CENSUS_VERSION, Q as PipelineCensus, R as PipelineCensusMode, S as PipelineCensusStatus, T as PlatformFormFactor, U as PlatformOS, V as PlatformRuntime, W as RENDER_CHAIN_MARKER, X as RENDER_CHAIN_STAGE_ORDER, Y as RENDER_CHAIN_TIERS, Z as RenderChain, _ as RenderChainSource, $ as RenderChainStageId, a0 as RenderChainStageName, a1 as RenderChainTier, a2 as RenderChainTierRequest, a3 as RenderChainVelocitySource, a4 as TargetFpsSource, a5 as VELOCITY_OUTPUT_NAME, a6 as VELOCITY_PREVIOUS_BONE_MATRICES, a7 as VELOCITY_PREVIOUS_INSTANCE_MATRICES, a8 as VELOCITY_PREVIOUS_WORLD_MATRIX, a9 as VelocityTracker, aa as counterDeviceOf, ab as createPipelineCensus, ac as ensureVelocityOutput, ad as getPlatform, ae as isMobile, af as isNative, ag as isTouchscreenAvailable, ah as isWeb, ai as prewarm, aj as readRenderChainObservation, ak as readRenderChainReport, al as readVelocityPreviousBoneMatrices, am as readVelocityPreviousMatrices, an as readVelocityPreviousWorldMatrix, ao as resolveTargetFps, ap as snapRefreshRate, aq as velocityTexture, ar as withVelocityContext } from './renderer-CfsS2hxi.js';
+import { I as IComputeDriven$1, a as IGPUReadbackSample } from './gpu-readback-CqJEfWNQ.js';
+export { C as ComputeDrivenRegistry, G as GPUReadback, b as IGPUReadbackOptions } from './gpu-readback-CqJEfWNQ.js';
+import { SkyMesh } from 'three/addons/objects/SkyMesh.js';
 import { Node as Node$1 } from 'three/src/nodes/Nodes.js';
 import 'zustand/vanilla';
 
+/**
+ * Nested cost spans across the render phase, default-off.
+ *
+ * The frame budget names six phases and one of them — `render` — is 16.1 ms of a 20.2 ms frame
+ * while every engine-owned thing inside it sums to under 1.5 ms. A phase that big with nothing
+ * inside it is not a measurement, it is a question, and four ranked optimisation options were
+ * priced against four different answers to it. This is the instrument that answers it: a span tree
+ * whose leaves are the parts of the render phase, with the leftover computed rather than assumed.
+ *
+ * Three properties make it trustworthy enough to price work against:
+ *
+ *  - **The residual is arithmetic, not a category.** Every non-leaf reports its own duration minus
+ *    the durations of the spans it contains, so an unmeasured part shows up as a number instead of
+ *    being quietly filed under "other". A child that outlives its parent reports a negative
+ *    residual rather than being clamped to zero, because a negative residual means the nesting is
+ *    wrong and a clamped one means nothing at all.
+ *  - **It is default-off and costs one guarded return when off.** `TN_FRAME_SPANS=1` installs it;
+ *    unset, every call site is `if (recorder === undefined) return;` with no clock read.
+ *  - **Nothing here decides anything.** It measures the path that exists. It does not select a
+ *    renderer, a traversal strategy or a pass order, and no number it produces is evidence for
+ *    owning the renderer.
+ *
+ * The ids are integers on the hot path — a span call must not allocate a string to be cheap enough
+ * to put around a per-draw call — and the names exist only in the report.
+ */
+/** Marker printed once per report window when spans are installed. */
+declare const SPANS_MARKER = "TN_FRAME_SPANS";
+/**
+ * The launch flag that installs the spans. Off by default: this is a diagnostic that adds work to
+ * the frame it measures, so a game must ask for it.
+ */
+declare const SPANS_FLAG = "TN_FRAME_SPANS";
+/**
+ * Every span, in the order the report prints them. Integers, because `beginSpan` runs per draw.
+ *
+ * `pass` and its nested kinds are one id per render call three makes, not one per camera: three
+ * renders the main camera first and the shadow and reflection cameras from inside that call, so
+ * the nesting is the renderer's own and a flat list of passes would have to invent a relationship
+ * the measurement already has.
+ */
+declare const SPANS: {
+    /** Compute-driven render work dispatched by the engine before the world render. */
+    readonly compute: 0;
+    /** The engine's own `beforeRender` seam, where a game prepares the scene it is about to draw. */
+    readonly beforeRender: 1;
+    /** The scene-graph matrix walk. */
+    readonly sceneUpdate: 2;
+    /** The projection's reconcile, when one is installed. */
+    readonly reconcile: 3;
+    /** Virtual-geometry clustered mesh update. */
+    readonly clustered: 4;
+    /** Automatic discrete LOD selection. */
+    readonly lod: 5;
+    /** The projected-size cull, apply and restore together. */
+    readonly cull: 6;
+    /** The main camera's render call. */
+    readonly mainPass: 7;
+    /** A nested render call three names as a shadow map. */
+    readonly shadowPass: 8;
+    /** A nested render call three names as a reflector. */
+    readonly reflectionPass: 9;
+    /** Any other nested render call. */
+    readonly nestedPass: 10;
+    /** Render-list construction inside a render call. */
+    readonly projectObject: 11;
+    /** Render-list sort inside a render call. */
+    readonly sort: 12;
+    /** Per-draw submission inside a render call, accumulated across the draws of one pass. */
+    readonly draw: 13;
+};
+type SpanId = (typeof SPANS)[keyof typeof SPANS];
+/** Names, indexed by id. The only place a span name is a string. */
+declare const SPAN_NAMES: readonly string[];
+declare const SPAN_COUNT: number;
+/** One span's cost across a reported window. */
+interface ISpanSummary {
+    /** Frames in the window that entered this span at least once. */
+    readonly frames: number;
+    /** Entries per frame, mean over the frames that entered it. */
+    readonly perFrame: number;
+    readonly mean: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly max: number;
+    /**
+     * This span's own time minus the time of the spans inside it, at p50.
+     *
+     * Negative when a child outlived its parent, which means the nesting is wrong. Never clamped: a
+     * clamped residual reads as a complete attribution, and this is the number that says whether the
+     * attribution is complete.
+     */
+    readonly residualP50: number;
+}
+/**
+ * One reported window of the span tree.
+ *
+ * `residual` is the render phase's own cost with every top-level span subtracted — the number this
+ * instrument exists to shrink. `coverage` is its complement as a fraction of the phase, and a
+ * reader that sees 0.68 is being told that a third of the phase is still unmeasured.
+ */
+interface ISpanWindow {
+    readonly window: number;
+    readonly frames: number;
+    /** The render phase as the frame budget charged it, at p50. */
+    readonly renderMs: number;
+    readonly residualMs: number;
+    readonly coverage: number;
+    /** Frames whose span nesting exceeded `MAX_DEPTH`, whose residual is therefore incomplete. */
+    readonly overflowed: number;
+    readonly spans: Readonly<Record<string, ISpanSummary>>;
+}
+/**
+ * Accumulates a nested span tree, one frame at a time, and reports it windowed.
+ *
+ * The owner brackets a frame with `beginFrame` and `endFrame`; the render phase's own duration is
+ * handed in at the close rather than measured here, so the root residual is arithmetic against the
+ * number the frame budget already reports and cannot drift from it.
+ *
+ * Nesting is strict: `end(id)` must name the span `begin(id)` opened. A mismatch throws, because a
+ * tree whose parentage is wrong produces a residual that is confidently wrong, and that is worse
+ * than a loud failure in a mode a game opted into.
+ */
+declare class SpanRecorder {
+    #private;
+    readonly capacity: number;
+    constructor(capacity?: number);
+    /** Opens a span. Returns false when the tree is already at `MAX_DEPTH` and the span is dropped. */
+    begin(id: SpanId, now: number): boolean;
+    /** Closes the span `begin` opened. Throws when it names a different span. */
+    end(id: SpanId, now: number): void;
+    /**
+     * Adds `ms` to a span that is entered many times per frame — a per-draw call, or a call site that
+     * cannot be bracketed. Counts as one entry and attributes to the enclosing span exactly as a
+     * bracketed one would.
+     */
+    add(id: SpanId, ms: number): void;
+    /** How many spans are currently open. Zero outside a frame's own work. */
+    get depth(): number;
+    /**
+     * Throws a half-open frame away without recording it.
+     *
+     * A frame that failed mid-render has a span stack that cannot be closed honestly, and recording
+     * it would put a fabricated zero in the window. The loop abandons it instead, so the window only
+     * ever reports frames whose spans all closed.
+     */
+    abandonFrame(): void;
+    /** Records the frame's totals against the render phase the frame budget charged. */
+    endFrame(renderPhaseMs: number): void;
+    /** The window just closed, or `undefined` when no frame was recorded in it. */
+    window(): ISpanWindow | undefined;
+}
+/** Installs or removes the recorder every `beginSpan`/`endSpan` routes to. */
+declare function setSpanRecorder(next: SpanRecorder | undefined): void;
+declare function spanRecorder(): SpanRecorder | undefined;
+/** The one clock the spans and the frame budget share, so their numbers are comparable. */
+declare function spanNow(): number;
+/**
+ * Opens a span. One guarded return when spans are off — no clock read, no allocation, no branch on
+ * anything but the recorder's own presence.
+ */
+declare function beginSpan(id: SpanId): void;
+declare function endSpan(id: SpanId): void;
+/** Adds an already-measured duration to a span entered many times per frame. */
+declare function addSpan(id: SpanId, ms: number): void;
+/**
+ * Whether `TN_FRAME_SPANS` asks for spans on this launch.
+ *
+ * Three ways in, because the three launches have three different seams and none of them is
+ * `import.meta.env` (Vite replaces that at build time, and a measurement flag must be settable
+ * without rebuilding the game): a native host forwards `TN_FRAME_SPANS` through `process.env`, a
+ * browser page carries `?tnFrameSpans=1` in its URL, and any harness can set
+ * `globalThis.__tnFrameSpans` before the game boots.
+ */
+declare function spansRequested(): boolean;
+/** The window as the marker line prints it. */
+declare function formatSpansWindow(window: ISpanWindow): string;
+
+/** A stride measured at unit world scale, so uniformly scaled clones can share it. */
+interface ISharedStride {
+    /** Metres of ground per clip-second at rate 1, per unit of uniform world scale. */
+    readonly groundSpeed: number;
+    readonly inPlace: boolean;
+}
+declare class RigPreparation {
+    #private;
+    /** The cached binding count for an equivalent preparation, or `undefined` on a miss. */
+    boundCount(source: Object3D, clip: AnimationClip): number | undefined;
+    rememberBound(source: Object3D, clip: AnimationClip, bound: number): void;
+    /** The cached unit-scale stride for an equivalent, fully covered clip, or `undefined`. */
+    stride(source: Object3D, clip: AnimationClip): ISharedStride | undefined;
+    rememberStride(source: Object3D, clip: AnimationClip, stride: ISharedStride): void;
+}
+
 interface IAnimationPlayerOptions {
     readonly clips: readonly AnimationClip[];
     readonly root: Object3D;
     readonly requiredClips?: readonly string[] | Readonly<Record<string, string>>;
+    /**
+     * Shared preparation for clones of one source rig. Set by `SkeletalMesh3D`; a standalone
+     * player leaves it undefined and keeps the per-instance binding audit and stride sample.
+     */
+    readonly preparation?: RigPreparation;
     /**
      * Match a travelling clip's playback rate to the ground the body actually covers.
      *
@@ -192,6 +391,37 @@ declare class CameraShake {
     update(dt: number): ICameraShakeOffset;
 }
 
+/**
+ * Why a launch stopped, said where the player can read it.
+ *
+ * A launch has exactly two ways to go wrong quietly, and both were measured on a real game:
+ * progress stops moving (a decode that never returns, an asset that never settles) and the GPU
+ * device is lost (another process had taken 94% of VRAM). In both the loop keeps iterating, the
+ * loading layer keeps painting, and the only account of what happened is a line on stdout — which
+ * a player does not have, and which a bug report therefore never carries.
+ *
+ * So the failure is reported as text, once, through `onLaunchFailure` — and core stops there. Core
+ * cannot draw it: on the native host `document` is a Three.js compatibility stub whose
+ * `appendChild` is a no-op, so an overlay written here would be invisible on exactly the target
+ * that needs it. The page owns the presentation (and the copy-to-clipboard button players are
+ * asked for when they report a launch that hung); this owns the noticing and the wording.
+ */
+/** What failed. `stalled` is "no progress for a while"; `device-lost` is the GPU going away. */
+type LaunchFailureKind = "stalled" | "device-lost";
+interface ILaunchFailure {
+    readonly kind: LaunchFailureKind;
+    /** One human sentence, already naming the numbers — this is what the Copy button copies. */
+    readonly message: string;
+}
+/**
+ * Called for every launch failure the engine notices, with the message to show the player.
+ *
+ * @situation show the player why the game stopped loading instead of leaving the loading screen up
+ * @situation report a stalled launch or a lost GPU device in the game's own UI
+ * @example const off = onLaunchFailure((failure) => shell.loading({ failure: failure.message }));
+ */
+declare function onLaunchFailure(listener: (failure: ILaunchFailure) => void): () => void;
+
 type AtmosphereRgb = readonly [number, number, number];
 type AtmosphereVector = AtmosphereRgb | Readonly<{
     x: number;
@@ -528,6 +758,15 @@ interface IInstancedBatchBuildOptions {
     readonly parent?: Object3D;
     /** Passed straight to the built mesh. Default `false`, as in Three.js. */
     readonly receiveShadow?: boolean;
+    /**
+     * An existing mesh to refill instead of creating one: used when it draws this batch's geometry
+     * and material and holds at least this many instances. Reusing matters on WebGPU, where three
+     * keys an instanced mesh's compiled node program by the mesh itself — every new InstancedMesh
+     * rebuilds its shader, and a streamed world creating hundreds a cell stalls on it.
+     */
+    readonly into?: InstancedMesh;
+    /** Instance slots to allocate when a new mesh is created, so later refills fit. Default: count. */
+    readonly capacity?: number;
 }
 /**
  * Collapses many copies of one shape into a single draw, without knowing the count up front.
@@ -548,8 +787,22 @@ declare class InstancedBatch {
     constructor(options: IInstancedBatchOptions);
     /** How many instances have been placed so far. */
     get count(): number;
+    /**
+     * Writes every placed matrix into `target` (a mesh's `instanceMatrix.array`), starting at instance
+     * `offset`, and returns how many were written. For a caller that packs several batches into one
+     * shared instance buffer instead of building a mesh per batch.
+     */
+    writeMatrices(target: Float32Array, offset: number): number;
     /** The built mesh, or `undefined` before {@link build} — never a guess. */
     get mesh(): InstancedMesh | undefined;
+    /**
+     * True when this batch holds element-for-element the matrices of `other`.
+     *
+     * A refilter rebuilds a cell's batch from the same run in the same order, so "did the answer
+     * change" is exactly this question, and comparing is what lets the swap skip a rebuild that came
+     * back identical instead of writing, clearing and compacting records the buffer already holds.
+     */
+    equals(other: InstancedBatch | undefined): boolean;
     /**
      * Records one instance from a matrix the game composed itself, and returns its instance index.
      *
@@ -593,9 +846,47 @@ interface IMergePart {
 interface IMergePartsOptions {
     /** Named in the error when the merge is refused. Say what was being built. */
     readonly label: string;
+    /**
+     * Channels to keep from each part besides `position`. Absent or empty keeps today's
+     * position-only merge, whose normals are recomputed from the merged result.
+     *
+     * `"normal"` keeps each part's authored normals, transformed by the part's placement matrix
+     * (the inverse-transpose normal matrix) and **never** recomputed. `"uv"` keeps each part's
+     * texture coordinates verbatim — the placement matrix moves position and normal, so UV values
+     * are retained unchanged. A part that does not carry a listed channel refuses the merge.
+     */
+    readonly preserve?: readonly ("uv" | "normal")[];
+}
+interface IMergeByMaterialOptions {
+    /** Named in the error when a group's merge is refused. Say what was being built. */
+    readonly label: string;
+    /**
+     * Leaves one mesh out of its material's group and out of the result — a piece that moves at run
+     * time, or one a capture script addresses by name.
+     */
+    readonly skip?: (mesh: Mesh) => boolean;
+    /**
+     * An `InstancedMesh` is baked into its material's group as one part per instance matrix while that
+     * group stays at or below this many triangles. Above it — or absent, which is the old behaviour —
+     * it comes back in the result untouched, because one instanced draw is already cheaper than the
+     * triangles it expands into.
+     */
+    readonly expandInstancedUnderTriangles?: number;
+    /**
+     * Vertices one merged group may hold before the rest of its material's parts start a second mesh.
+     *
+     * One merged group is one upload on the frame that first draws it, and that upload is the frame's
+     * whole cost: measured in a browser, a streamed world created 826 GPU buffers totalling 228.8 MB
+     * out of `createAttribute`, 33 of them over 1 MB, and the first draw of the largest chunk meshes
+     * took up to 230 ms. Splitting a material group in traversal order — which keeps the pieces
+     * adjacent to the pieces they were placed beside — bounds each of those uploads instead of
+     * trading one draw for a single enormous buffer. See `CHUNK_MERGE_MAX_VERTICES`.
+     */
+    readonly maxGroupVertices?: number;
 }
 /**
- * Merge game-authored pieces into one buffer, keeping each piece's own colour.
+ * Merge game-authored pieces into one buffer, keeping each piece's own colour and, when asked,
+ * its uv and authored normals.
  *
  * 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
@@ -603,9 +894,72 @@ interface IMergePartsOptions {
  * 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.
+ * are entirely the game's, one per part, and changing them changes nothing here. By default the
+ * merged normals are recomputed from the merged buffer; `preserve` keeps the authored normals and
+ * texture coordinates instead so an imported model's shading survives the bake.
+ *
+ * A group whose parts are all indexed merges indexed — the sum of their vertex counts, not three
+ * times their triangles — and only a mixed group falls back to the de-indexed soup. One crossing
+ * 65,535 vertices gets a 32-bit index, because a 16-bit one cannot name the vertex.
  */
 declare function mergeParts(parts: Iterable<IMergePart>, options: IMergePartsOptions): BufferGeometry;
+/**
+ * Bake a hierarchy's static meshes into one mesh per material, transforms and all.
+ *
+ * A building or a ship is dozens of boxes and cylinders that never move relative to each other, and
+ * every one of them is a draw call. Grouping by material and merging each group is the ordinary
+ * fix, and the ordinary fix is thirty lines an agent rewrites in every game, each time slightly
+ * differently: walk the tree, group by material, bake `matrixWorld` into the vertices, hand the
+ * group to `mergeParts`, build a mesh on the game's own material. The parts here are the same
+ * `IMergePart` list, so a game that already merges by hand gets the same refusals — a group that
+ * cannot merge throws naming `label:material`, not silently vanishing.
+ *
+ * Nothing here decides how anything looks: the material is the game's own instance, the geometry is
+ * exactly what was authored, and the group split follows the materials the game already made.
+ *
+ * `normal` survives when every mesh in a group carries it and is recomputed otherwise. `uv` survives
+ * when any mesh carries it, so a group where only some do is the refusal `mergeParts` raises, never
+ * a texture silently left unmapped. Skinned meshes are left alone — their vertices are posed per
+ * frame — and an instanced one is left alone unless `expandInstancedUnderTriangles` names a cap its
+ * group fits under and its own shape is small enough to be worth repeating, which bakes every
+ * instance matrix into the merge.
+ *
+ * `maxGroupVertices` bounds a single group, and a material whose parts cross it is merged into
+ * several meshes in traversal order — more draws, none of them carrying a buffer big enough to stall
+ * the frame that first submits it.
+ */
+declare function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[];
+
+/**
+ * A debug switch a game reads the same way on every platform it ships to.
+ *
+ * Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
+ * turn this on for one run without changing the code, and how does a capture script reach the object
+ * it wants to look at. The answers here are one function each, and neither decides how anything
+ * looks.
+ */
+/**
+ * A debug switch read from the URL, or from the environment on a native launch.
+ *
+ * @situation read a debug toggle from the URL or an environment variable
+ *
+ * A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
+ * launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
+ * a command line. `0` and `false` are off, so a saved URL that used to enable a switch still says
+ * "off" rather than quietly turning it back on.
+ */
+declare function debugFlag(name: string): boolean;
+/**
+ * Publish one game object for a capture script or the console, in development builds only.
+ *
+ * @situation expose a game object to a capture script or the console in dev builds
+ *
+ * Playtest reads `__THREENATIVE__` in a dev build and is silent in a production one, so a game that
+ * publishes its player, its camera or a scene handle under `.debug` is reachable from the same
+ * place a production build is not. Other keys on the shared object are left alone; the dev surfaces
+ * the engine installs beside them keep working.
+ */
+declare function exposeDebug(name: string, value: unknown): void;
 
 /**
  * A mesh that draws only the clusters this camera can resolve.
@@ -686,8 +1040,9 @@ declare class ClusteredMesh extends Mesh {
  * 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.
+ * game that has to remember to call something has not been given it. The first call censuses the
+ * root once and subscribes to its graph events; later calls walk only the clustered meshes and
+ * batch roots themselves, so a scene holding neither costs a map lookup.
  *
  * @returns triangles the clustered meshes and batches will submit.
  */
@@ -772,6 +1127,428 @@ declare class ClusteredBatch {
     update(camera: Camera, viewportHeight: number): number;
 }
 
+/**
+ * Pixels a one-world-unit error at `depth` covers, for this camera and viewport.
+ *
+ * Perspective divides the projected scale by the depth; orthographic has no depth term and uses the
+ * frustum height instead. A non-positive depth or an unprojectable camera throws rather than
+ * returning a plausible-looking wrong scale.
+ */
+declare function lodPixelScale(camera: Camera, viewportHeight: number, depth: number): number;
+/** The LOD0 geometry of a mesh under a discrete chain, or the mesh's own geometry otherwise. */
+declare function baseGeometryOf(mesh: Mesh): BufferGeometry;
+/**
+ * Takes every discrete-LOD mesh under `root` through this frame's selection.
+ *
+ * The engine calls this itself, once a frame, after matrices are synced and before the render.
+ * Multi-view callers that need the finest level across passes use {@link selectLodLevel} directly;
+ * this entry point selects for the one camera it is handed — which is the main view, and is at
+ * least as fine as a shadow pass of lower resolution needs.
+ *
+ * @returns triangles the managed meshes will submit this frame.
+ */
+declare function updateModelLods(root: {
+    traverse(callback: (object: object) => void): void;
+}, camera: Camera, viewportHeight: number): number;
+
+/**
+ * What the gate did on the last frame, in the shape a frame-budget window reports.
+ *
+ * `enabled: false` means the game declined the gate, and the counts are still measured — turning
+ * the convention off must not turn its measurement off. Every exemption is named separately so an
+ * override is visible rather than silent.
+ */
+interface IRenderCameraCullReport {
+    readonly schemaVersion: 1;
+    readonly enabled: boolean;
+    /**
+     * False when the camera has no perspective distance term (orthographic) or no viewport to
+     * project into; the gate then leaves the whole scene drawn rather than guessing.
+     */
+    readonly cameraResolved: boolean;
+    readonly thresholdPixels: number;
+    /** Renderables walked this frame. */
+    readonly considered: number;
+    /** Renderables hidden by this gate this frame. */
+    readonly culled: number;
+    readonly exemptCameraAttached: number;
+    readonly exemptMarked: number;
+    readonly exemptShadowCasters: number;
+    readonly exemptWithoutBounds: number;
+    /**
+     * Objects whose position buffer is rewritten every frame, so the gate cannot trust a bound it
+     * cannot afford to rescan. Kept drawn, like `frustumCulled = false`.
+     */
+    readonly exemptDynamicBounds: number;
+    /** Objects that already set `frustumCulled = false`, and so never had trustworthy bounds. */
+    readonly exemptFrustumCulled: number;
+}
+/**
+ * Keep an object drawn regardless of how small the render camera resolves it.
+ *
+ * The named per-object override for the projected-size gate, which is on by default. Mark the
+ * player's own cockpit, a nameplate, a quest marker, or anything a game never wants to pop out.
+ * `alwaysRender(object, false)` removes the marker. The count of marked objects is reported beside
+ * the cull, so an override is stated rather than hidden.
+ *
+ * @situation keep a small object drawn when the engine would skip it as too far to resolve
+ * @situation stop my cockpit, marker or player model popping out at distance
+ * @situation a tiny object disappeared at range and I need it always visible
+ * @constraint the marker is per object and survives scene rebuilds only as long as the object does
+ * @constraint disabling the gate (`renderer.minimumProjectedPixels: false`) keeps its measurement on
+ * @example alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
+ */
+declare function alwaysRender(object: Object3D, enabled?: boolean): void;
+
+/**
+ * The per-frame world-matrix walk, with a hidden subtree left where it stands.
+ *
+ * `three`'s `Object3D.updateMatrixWorld` recurses into every child of every node whatever its
+ * `visible` flag, multiplying a world matrix for each. That is the correct default for a library
+ * that cannot know what a game is doing, and it is the wrong one for a renderer that is about to
+ * skip exactly those subtrees: a full-detail body while its merged stand-in draws, a hidden LOD
+ * level, a parked or hangared model each pay the walk and none of them can draw.
+ *
+ * Native flight in `sandbox/midway-open-pacific` profiled `updateMatrixWorld` plus
+ * `multiplyMatrices` at **29 % of all JavaScript ticks**, and the same scene's hand-rolled
+ * visible-only pass walked **779 nodes per frame instead of 9,903**, 3.1 ms down to 0.3 ms. That
+ * pass was the game's; this is the engine's, so the next game does not write it again.
+ *
+ * The pass mirrors three exactly for a visible node: `matrixAutoUpdate` -> `updateMatrix()`, then
+ * the `matrixWorldNeedsUpdate || force` recompute honouring `matrixWorldAutoUpdate` and a null
+ * parent, then force the children. A node with `visible === false` still composes its **own**
+ * matrix — that is what makes the next part cheap — and is not recursed into; when it was forced
+ * (or carried a dirty flag) it is remembered, so the first frame it is visible again its whole
+ * subtree is recomputed with `force = true`.
+ *
+ * Two things are never dropped by the pruning, because both are read while nothing above them is
+ * visible:
+ *
+ * - a class that overrides `updateMatrixWorld` runs its own. `SkinnedMesh` refreshes
+ *   `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base walk
+ *   left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
+ *   vanishing from the frame. Their subtrees are small, so walking them whole costs nothing;
+ * - a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its
+ *   skeleton's matrices wherever the armature happens to sit. Whether bones sit below a node is
+ *   decided once and remembered — a rig is built whole and does not grow.
+ *
+ * A game that reads a **hidden** object's `matrixWorld` directly must not rely on this pass
+ * having reached it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` (which update the
+ * chain they need) or call `object.updateWorldMatrix(true, false)` first. The convention's named
+ * override is `renderer.matrixWorld: "all"`, which visits every node exactly as three's own walk
+ * does; `"visible"` is the default.
+ */
+/** How much of the scene graph the engine walks for world matrices each frame. */
+type MatrixWorldMode = "visible" | "all";
+/** What the pass did on the last frame, for the frame telemetry a window reports. */
+interface IMatrixWorldReport {
+    readonly schemaVersion: 1;
+    readonly mode: MatrixWorldMode;
+    /**
+     * Nodes the engine walked this frame, summed over every application (authored scene and a
+     * projection mirror when one is in use). One number both ways, so `"all"` can be read as the
+     * cost of the walk the convention just removed.
+     */
+    readonly visited: number;
+}
+interface IMatrixWorldOptions {
+    /** `"visible"` (default) skips a hidden subtree; `"all"` reproduces three's own walk. */
+    readonly mode?: MatrixWorldMode;
+}
+/**
+ * One game's world-matrix walk, holding the state the pruning needs between frames.
+ *
+ * The stale set and the bone cache live on the instance rather than in module scope: two games,
+ * two playtest scenarios or two roots in one process must not share "this subtree was skipped
+ * while hidden", or one game's hidden node would be force-refreshed by the other's frame.
+ */
+declare class MatrixWorldPass {
+    #private;
+    constructor(options?: IMatrixWorldOptions);
+    get mode(): MatrixWorldMode;
+    /** What the current frame has walked so far, across every {@link apply} call. */
+    get report(): IMatrixWorldReport;
+    /** Starts a frame's count. The pass's state (stale set, bone cache) is untouched. */
+    beginFrame(): void;
+    /**
+     * Walks `root`, mirroring three for every node the mode visits.
+     *
+     * Returns the nodes this call visited, so a caller can report one application's cost without
+     * also reporting the frame's total.
+     */
+    apply(root: Object3D, force?: boolean): number;
+    /** Forgets what was skipped. A whole-scene swap has no hidden ancestors left to refresh. */
+    dispose(): void;
+}
+
+/**
+ * Where the spans attach to three's own render path.
+ *
+ * Kept apart from the recorder because they are two different kinds of risk. The recorder is
+ * arithmetic over a stack and is proven by unit tests; this file reaches into another library's
+ * private methods, and every line of it is a bet about how three 0.185 is shaped. Reading them
+ * separately is how the bet stays visible.
+ *
+ * Every wrapper is an own property on the instance, so it is the object the frame actually uses
+ * and uninstalling restores the prototype's method. Three's private methods are read defensively:
+ * a renderer whose internals have moved loses that span rather than throwing, and the span simply
+ * does not appear in the report — an absent measurement, never a fabricated zero.
+ */
+
+/** The slice of the raw three renderer the probes wrap. Structural, so a test can stand in a fake. */
+interface ISpanProbeTarget {
+    render(scene: unknown, camera: unknown): unknown;
+    _projectObject?(...args: unknown[]): void;
+    _renderObjectDirect?(...args: unknown[]): void;
+}
+/**
+ * Wraps the renderer's own render path so each part of a frame lands in its own span.
+ *
+ * Every wrapper is an own property on the instance, so it is the object the frame actually uses and
+ * uninstalling restores the prototype's method. Three's private methods are read defensively: a
+ * renderer whose internals have moved loses that span rather than throwing, and the span simply
+ * does not appear in the report — an absent measurement, never a fabricated zero.
+ *
+ * The recursion guards matter: `_projectObject` calls itself once per child, so only the outermost
+ * call opens a span, and `render` is deliberately not guarded because a nested render *is* the
+ * shadow and reflection passes.
+ */
+declare function installSpanProbes(target: ISpanProbeTarget, root: Object3D): () => void;
+
+/**
+ * The engine telling the agent that built the scene what a human would otherwise find by playing.
+ *
+ * A scene reached 1,815 triangles per draw with its GPU ten times under budget and nobody knew,
+ * because the census and the phase split are measured every frame and nothing reads them. The
+ * frame already carries the shape: how many objects the cull considered, how many draws each pass
+ * submitted, how many casters are exempt, and what share of the frame the GPU actually used. This
+ * turns those numbers into a verdict, once per reported window.
+ *
+ * **The rule is derived, never a constant an author is told to revisit.** It fires when
+ *
+ *  - the GPU used less than a third of the frame — the device is not the constraint, and
+ *  - the JS render phase alone is longer than the display's own period — so the scene cannot make
+ *    the display's rate even if everything else in the frame were free.
+ *
+ * Both numbers come from the frame meter. The display's period comes from the host's own
+ * presentation cap where there is one, and otherwise from the frame rate the game itself declared;
+ * no third source is invented, and a launch that can name neither gets no verdict rather than a
+ * guessed one.
+ *
+ * It is silent on an honestly GPU-bound scene with the same draw count, which is the property that
+ * makes it worth reading: a warning that fires on every heavy scene is a warning nobody reads.
+ */
+
+/** Marker printed at most once per reported window. */
+declare const SCENE_WARNING_MARKER = "TN_SCENE_WARNING";
+/**
+ * What the frame already knows about the scene's shape.
+ *
+ * Every field is a count the engine measures anyway — the projection's cull census and the render
+ * pass budget — so the warning adds a reading, never a measurement.
+ */
+interface ISceneShape {
+    /** Objects the projected-size cull looked at this window. */
+    readonly objectsConsidered: number;
+    /** Objects it hid. */
+    readonly culled: number;
+    /** Objects exempt from the gate because they cast shadows. */
+    readonly shadowExemptCasters: number;
+    /** Draws submitted per pass kind, from the render pass budget. */
+    readonly draws: Readonly<Partial<Record<FramePassKind, number>>>;
+    /** Triangles per draw across every pass; the number a merge or an atlas moves. */
+    readonly trianglesPerDraw: number;
+}
+/** The verdict, and the shape behind it. */
+interface ISceneWarning {
+    readonly window: number;
+    /** The GPU's share of the frame, as a fraction. */
+    readonly gpuShare: number;
+    /** The JS render phase's mean, in milliseconds. */
+    readonly renderMs: number;
+    /** The period the display works at, in milliseconds, and where that number came from. */
+    readonly displayPeriodMs: number;
+    readonly displaySource: "host-cap" | "declared-target";
+    /** The largest thing the CPU describes every frame, and its share of the terms compared. */
+    readonly dominantTerm: string;
+    readonly dominantShare: number;
+    readonly shape: ISceneShape;
+}
+/**
+ * The display's own period, in milliseconds, or `undefined` when nothing can say.
+ *
+ * The host's presentation cap first, because on a native launch that is literally the rate frames
+ * reach the display at. A browser has no refresh-rate API, so the rate the game declared is the
+ * only honest second source — and it is the same number the resolution scaler already judges
+ * against, not a new one.
+ */
+declare function displayPeriodMs(declaredTargetFps: number | undefined): {
+    ms: number;
+    source: ISceneWarning["displaySource"];
+} | undefined;
+/**
+ * The verdict for one reported window, or `undefined` when the frame does not earn one.
+ *
+ * Fails closed in both directions: a window whose GPU was never measured gets no verdict, because
+ * "the GPU is idle" is a claim and an absent reading is not evidence for it; and a window with no
+ * shape to report gets none either, because a warning that cannot say what to change is noise.
+ */
+declare function sceneWarning(window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined): ISceneWarning | undefined;
+/**
+ * The scene's shape for one window, from the counts the frame already reported.
+ *
+ * `undefined` when the window carries no pass split: without draws there is nothing to name, and
+ * a verdict built on an absent census would be a sentence about a scene nobody measured.
+ */
+declare function describeSceneShape(window: IFrameBudgetWindow, cull: IRenderCameraCullReport | undefined): ISceneShape | undefined;
+/** The one-line summary a reader sees without opening a log viewer. */
+declare function describeSceneWarning(warning: ISceneWarning): string;
+/** The marker line. */
+declare function formatSceneWarning(warning: ISceneWarning): string;
+
+/**
+ * Authored static subtrees: stop recomposing transforms that nobody moves.
+ *
+ * The matrix walk is 2.22 ms of the reference game's 16.1 ms render phase, and almost none of what
+ * it recomputes changed since the previous frame — island geometry, deck fittings, static props and
+ * terrain are composed from the same position, quaternion and scale every frame, then multiplied
+ * into the same world matrix, for as long as the game runs.
+ *
+ * **What this deletes, exactly, so the claim can be checked.** Three's `updateMatrixWorld` does
+ * three things per object: `updateMatrix()` composes the local matrix when `matrixAutoUpdate`,
+ * the world matrix is multiplied out when `matrixWorldNeedsUpdate || force`, and the walk recurses
+ * into every child — the recursion is unconditional in three 0.185, so a frozen subtree still gets
+ * visited. Freezing removes the two composes and keeps the visit. That is the honest bound: this
+ * deletes arithmetic, not traversal, and the traversal is a separate lever with a separate PRD.
+ *
+ * **Staticness is authored, never guessed.** A heuristic that decides an object has "not moved in
+ * 60 frames" is a correctness bug with no reproduction, so nothing here watches gameplay. What the
+ * engine does do is check the promise where it is cheap to check it: the root's own local transform
+ * is compared against what was frozen, once per frame, and a root the author moved thaws and
+ * refreezes itself. That is O(static roots), not O(objects), and it turns the most common way to
+ * get this wrong into a non-event. Writes deeper inside a frozen subtree are the author's to
+ * announce with `invalidateStatic`, and `TN_RENDERLIST_VALIDATE=1` is what proves they did.
+ */
+
+/** Marker printed with the static census on each reported window. */
+declare const STATIC_TRANSFORM_MARKER = "TN_STATIC_TRANSFORMS";
+/**
+ * Marks a subtree static: its transforms are composed once here and never again until something
+ * changes them.
+ *
+ * Idempotent, and it answers the version the subtree is now at, so a caller can assert on the
+ * contract rather than on the flag. Marking a root twice re-arms it, which is the same thing
+ * `invalidateStatic` does and the reason a generator can emit the call unconditionally.
+ */
+declare function markStatic(root: Object3D): number;
+/**
+ * Thaws a subtree: every object composes again from the next walk.
+ *
+ * The flags are restored to three's defaults rather than to whatever they were before, because a
+ * game that had already turned `matrixAutoUpdate` off for its own reasons and then marked the
+ * subtree static is asking for the same behaviour either way.
+ */
+declare function unmarkStatic(root: Object3D): void;
+/**
+ * Announces that something inside a frozen subtree moved. The subtree recomposes once and refreezes
+ * at its new transform.
+ *
+ * Takes the object that moved, or the root; either way the root that owns it is what re-arms, since
+ * a world matrix deeper in the subtree is a product of everything above it.
+ */
+declare function invalidateStatic(object: Object3D): number | undefined;
+/** Whether this object is a frozen root. */
+declare function isStatic(root: Object3D): boolean;
+/** One window's census of what is frozen and what had to thaw. */
+interface IStaticTransformCensus {
+    /** Subtrees currently frozen. */
+    readonly roots: number;
+    /** Objects inside them, which is the count that stopped recomposing. */
+    readonly objects: number;
+    /** Roots the per-frame check found moved, and re-armed, since the previous census. */
+    readonly rearmed: number;
+}
+/**
+ * Re-arms any frozen root whose authored transform has changed since it was frozen.
+ *
+ * Called once per render phase, before the walk. It reads 26 numbers per frozen root and writes
+ * nothing when nothing moved, so a scene that stays still pays a comparison per subtree and no
+ * allocation at all. It cannot see a write deeper inside the subtree — that is `invalidateStatic`'s
+ * job and `TN_RENDERLIST_VALIDATE=1`'s proof — and it does not pretend to.
+ */
+declare function refreshStaticTransforms(): void;
+/** The census, and the re-arm counter it resets. */
+declare function staticTransformCensus(): IStaticTransformCensus;
+/** Drops every registration. A game that tore down its scene must not keep its roots alive. */
+declare function resetStaticTransforms(): void;
+
+/**
+ * The parity oracle for anything that stops recomputing a transform.
+ *
+ * A cache that is right on the scene you tested and wrong on the one you did not is worse than no
+ * cache, because it ships as a visual bug nobody can reproduce. This is the instrument that makes
+ * the difference falsifiable: with `TN_RENDERLIST_VALIDATE=1`, every frame recomputes every world
+ * matrix from the authored transforms, the long way, and compares it elementwise against the one
+ * the frame is about to draw with. The first disagreement throws, naming the object and the
+ * element, because a validation mode that logs and continues is a validation mode nobody reads.
+ *
+ * It is a validation mode, not a proof: it proves the frames it ran on. Run it on the scenes you
+ * care about, in CI, for as many frames as you can afford.
+ *
+ * Off by default and expensive by construction — it does the work it is checking, twice.
+ */
+
+/** Marker printed when the validator is installed, so a log says which mode produced it. */
+declare const RENDERLIST_VALIDATE_MARKER = "TN_RENDERLIST_VALIDATE";
+/** The launch flag. */
+declare const RENDERLIST_VALIDATE_FLAG = "TN_RENDERLIST_VALIDATE";
+/** Whether `TN_RENDERLIST_VALIDATE` asks for validation on this launch. */
+declare function renderListValidationRequested(): boolean;
+/** What one frame's check found. */
+interface IValidationReport {
+    /** Objects whose world matrix was recomputed and compared. */
+    readonly checked: number;
+    /** Objects skipped because they own their own world matrix; reported, never counted as checked. */
+    readonly gameOwned: number;
+    /** Frames validated so far. */
+    readonly frames: number;
+}
+/**
+ * Recomputes every world matrix under `root` and throws on the first that disagrees.
+ *
+ * The recomputation is deliberately independent of the flags a freeze sets: it composes the local
+ * matrix from `position`/`quaternion`/`scale` when the object composes its own, uses the authored
+ * `matrix` when it does not, and multiplies by the parent's *recomputed* world matrix rather than
+ * the cached one — so an error at the top of a subtree cannot be hidden by a matching error
+ * underneath it.
+ */
+declare function validateWorldMatrices(root: Object3D): {
+    checked: number;
+    gameOwned: number;
+};
+/**
+ * The per-frame validator, installed when the flag asks for it.
+ *
+ * Holds a frame counter so the marker can say how much was proven, which is the difference between
+ * "validation passed" and "validation passed on 1,800 frames of the reference game".
+ */
+declare class RenderListValidator {
+    #private;
+    /**
+     * Validates one frame. Throws on the first divergence.
+     *
+     * `roots` is the thing being drawn plus every frozen subtree. Those are not the same object
+     * when the engine's projection is collapsing the scene: the draw root is then the mirror, and
+     * validating only it reported three objects checked and zero divergences on a scene with two
+     * hundred frozen meshes, one of which really was stale. A freeze is authored on the authored
+     * scene, so the authored roots are checked whether or not they are what reaches the GPU.
+     */
+    frame(...roots: readonly Object3D[]): void;
+    report(): IValidationReport;
+}
+/** The marker line for one reported window. */
+declare function formatValidationReport(report: IValidationReport): string;
+
 /** 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. */
@@ -952,6 +1729,8 @@ interface IClipWindow {
     readonly level: number;
     readonly extent: number;
     readonly pageWorldSize: number;
+    /** Pages a window trails its followed centre by before it moves and re-renders. */
+    readonly refreshPages: number;
     readonly minX: number;
     readonly minY: number;
     readonly maxX: number;
@@ -963,8 +1742,18 @@ interface IDirectionalClipmapOptions {
     /** 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;
+    /**
+     * Fraction of an extent inside which a point selects that level, `(0, 1]`, default 0.9. One value
+     * for every level, or one per level finest first, the last entry standing in for the rest.
+     */
+    readonly selectionGuard?: number | readonly number[];
+    /**
+     * Fraction of an extent a level's window may trail its followed centre by before it re-renders,
+     * `[0, 1)`, default 0.125. Rounded to a whole number of the level's texels, so `0` keeps the
+     * old one-texel step. Larger steps re-render a level less often as the camera walks. One value
+     * for every level, or one per level finest first, the last entry standing in for the rest.
+     */
+    readonly refreshStep?: number | readonly number[];
 }
 /**
  * Camera-centred clip windows in a light-space basis, snapped to whole pages.
@@ -977,14 +1766,21 @@ declare class DirectionalClipmap {
     #private;
     readonly clipExtents: readonly number[];
     readonly pagesPerAxis: number;
-    readonly selectionGuard: number;
+    /**
+     * Per level, finest first; the last entry stands in for every level past it. Mutable through
+     * {@link setRefreshStep} so a level whose own render is expensive can be stepped further, which
+     * is fewer grid positions for its window rather than a different grid.
+     */
+    refreshStep: number[];
+    /** Per level, finest first; the last entry stands in for every level past it. */
+    readonly selectionGuard: readonly number[];
     readonly levelCount: number;
     basisU: IVector3Like;
     basisV: IVector3Like;
     basisW: IVector3Like;
     centerWorld: IVector3Like;
     centerLight: ILightSpacePoint;
-    constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, }: IDirectionalClipmapOptions);
+    constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, refreshStep, }: IDirectionalClipmapOptions);
     /** Re-orient the basis; returns true when it changed enough that cached pages are stale. */
     setDirection(direction: IVector3Like): boolean;
     project(worldPoint: IVector3Like): ILightSpacePoint;
@@ -993,6 +1789,8 @@ declare class DirectionalClipmap {
         v: number;
         w?: number;
     }): IVector3Like;
+    /** Re-step one level's window: the trail its followed centre may move before it re-renders. */
+    setRefreshStep(level: number, step: number): void;
     updateCenter(worldPoint: IVector3Like): readonly IClipWindow[];
     getWindow(level: number): IClipWindow;
     pageWorldSize(level: number): number;
@@ -1065,12 +1863,130 @@ interface IVirtualShadowOptions {
     /**
      * 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.
+     * `selectionGuard` minus `refreshStep`, since a window trails its centre by that much. One value
+     * for every level, or one per level finest first, the last entry standing in for the rest.
+     */
+    readonly selectionGuard?: number | readonly number[];
+    /**
+     * Fraction of a level's extent its window may trail the followed centre by before it re-renders,
+     * `[0, selectionGuard)`, default 0.125 — `refreshStep: 0` keeps the old one-texel step. The step
+     * is rounded to a whole number of that level's texels, so a walking camera re-renders a level
+     * ~`1/refreshStep` times less often while the shadow texels stay on one fixed world grid. Costs
+     * that much of `selectionGuard`, which it is already reduced by, so a window never reaches past
+     * the trailing edge of a map rendered before the centre moved. One value for every level, or one
+     * per level finest first, the last entry standing in for the rest — the fine level is the one a
+     * walking camera re-renders most, so it is the one that wants the larger step.
+     */
+    readonly refreshStep?: number | readonly number[];
+    /**
+     * Let a level buy itself a wider `refreshStep` out of what its own last render cost, default true.
+     *
+     * A level render is a whole scene draw, so the engine cannot know what one is worth until it has
+     * paid for it: the node measures the draw it just took and smooths that reading, and a level whose
+     * smoothed cost is a large share of the frame period is re-rendered less often. This is automatic
+     * because the value it reacts to is a measurement, not a setting — a game sets nothing, and a
+     * cheap level is never widened and behaves exactly as before. The widened trail is capped by the
+     * window's own margin, so the camera stays inside the region that level serves and everything that
+     * level serves stays inside the map; a level with no such margin is never widened at all.
+     *
+     * `false` puts every level back on the `refreshStep` it was given, which is also what a harness
+     * that wants to count today's renders uses.
+     */
+    readonly adaptiveRefresh?: boolean;
+    /**
+     * Fraction of the display period a level's smoothed render cost may take before its refresh trail
+     * widens, `(0, 1]`, default 0.4.
+     *
+     * The period is the frame's own `deltaTime`, capped at the 60 fps frame (16.7 ms). The cap is what
+     * keeps the budget honest: the frame that renders an expensive level is itself long because of that
+     * render, so reading the share against its own inflated delta would count the cost twice and let
+     * the very level that needs adapting pass its own test. At 60 Hz the cap is the frame itself; on a
+     * 120 Hz panel the same render is twice the share it is at 60; below 60 the cap holds the budget
+     * at the 60 fps frame rather than growing with the stall. Below the share nothing changes at all,
+     * and above it the trail widens in proportion to the overshoot,
+     * because that is the ratio between what the level costs and what a frame can afford to spend on
+     * it — a level four times over the share refreshs about four times less often, until the cap
+     * below it runs out.
+     */
+    readonly expensiveRefreshShare?: number;
+    /**
+     * Raise a level's texel size gate while its own render is too expensive for the frame, default
+     * true.
+     *
+     * The same measurement adaptive refresh reads — the smoothed cost of the level's own last render,
+     * against the share of the frame it may take — drives a second, independent adaptation: a level
+     * whose render is over budget sizes its gate up in steps of 1.5 until it is affordable again, up
+     * to 8 times the configured gate, and halves it back toward 1 once the render is comfortably under
+     * half the budget. The gate only ever judges a caster by its size (see `minCasterTexels`), so this
+     * drops the tiniest props first and never a building, and a level that is cheap is never touched:
+     * it stays at scale 1 and submits exactly what it did before.
+     *
+     * `false` pins every level at scale 1, which is also what a harness that wants today's draw
+     * counts uses.
+     */
+    readonly adaptiveCasterGate?: boolean;
+    /**
+     * How long a level waits after its own last render before an invalidation may re-render it, in
+     * seconds. One value for every level, or one per level finest first, the last entry standing in
+     * for the rest. Default `0.25 * extent / finestExtent` — 0.25 s, 1 s and 3.33 s for extents
+     * 24 / 96 / 320 — and `0` renders on the very next frame, which is what the node did before.
+     *
+     * A streamed world invalidates its shadows on every residency update, and a cell admitted at the
+     * ring edge lands in the coarsest window: the level that redraws for it is the one paying for the
+     * whole ring's wide casters, ten times a second where movement alone asks for two. A level
+     * waiting out its delay keeps the map and window it has, which is already right for every static
+     * caster in it, so only a newly streamed caster is missing — the trade is that a far tree's
+     * shadow can appear up to the delay late (3.33 s at extent 320, invisible on a level whose texel
+     * is wider than the tree). A window that moved is never delayed: that is a different reason, and
+     * it is not this option's.
+     */
+    readonly invalidationDelay?: number | readonly number[];
+    /**
+     * How far behind the window centre each level camera sits, in world units. Default 200. An
+     * explicit `lightDistance` *and* `depthRange` switch the level's light-space depth off the derived
+     * span below and back onto this pair, so a game that knows its own world sizes can still say so.
      */
-    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. */
+    /**
+     * Depth range each level camera covers past its centre, in world units. Default 400. Read only
+     * together with `lightDistance`; on its own the span is still derived.
+     */
     readonly depthRange?: number;
+    /**
+     * Texels of a level a caster must cover before it draws into that level, default 1.5. A level's
+     * texel is `2 * extent / mapSize`, so the finest levels keep everything and the coarse ones keep
+     * only what they can resolve: a fern is a whole number of texels in a 48 m window and a fraction
+     * of one in a 640 m window, so it stops being drawn there and the shadow it casts is the ground
+     * cover's own, not its silhouette's. Set 0 to draw every caster into every level.
+     */
+    readonly minCasterTexels?: number;
+    /**
+     * Draw every level past the finest one with less geometry than the main pass would, default true.
+     *
+     * Two defaults, both Unreal's and both applied in one place — the traverse a level render already
+     * makes over the casters in its window, where each of the two is a change to the object three
+     * draws from and is put back the moment that render is over:
+     *
+     * 1. **Shadow LOD bias.** A mesh whose geometry carries a registered AutoLOD chain
+     *    (`lodChainOf`) is submitted with the chain's *coarsest* geometry. A level 2 window cannot
+     *    resolve a tree's needles, so drawing LOD0 there is a texel of needles per texel of shadow;
+     *    the coarse level's own texel is metres wide. Level 0 draws what the main pass draws.
+     * 2. **Alpha-caster range.** An alpha-tested (`alphaTest > 0`) or transparent mesh casts into the
+     *    finest level only. Its cutout is its own texture: a coarse level either drops it — the
+     *    level's texel is wider than the card, so the fence is sub-texel — or keeps resolving a
+     *    texture it cannot afford. This is a per-primitive shadow cull distance, and the trade is
+     *    honest and one-sided: a fence's or a foliage card's shadow ends where the finest level's
+     *    window ends, and a wide level shows bare ground where it stood. Opaque casters — a merged
+     *    chunk's position-only proxy, a tree's silhouette — are drawn on every level as before.
+     *
+     * Neither is left changed: a hidden caster's `castShadow` and a coarse mesh's `geometry` are put
+     * back before the next level, before the mover maps and before the main pass, which see the world
+     * exactly as the game authored it. Mover maps keep full detail — a 256² map over the level's own
+     * window, drawing only the tracked casters.
+     * `false` puts every level back on stock full-detail draws, which is what the node did before
+     * either default existed.
+     */
+    readonly shadowLodBias?: boolean;
     /** Print the `TN_VIRTUAL_SHADOW` line every `markerEvery` frames; `false` silences it. Default 300. */
     readonly marker?: boolean | number;
 }
@@ -1090,8 +2006,76 @@ interface IVirtualShadowStats {
     readonly cached: number;
     /** Levels rendered this frame, for any reason. */
     readonly rendered: number;
+    /**
+     * Levels that wanted a render this frame and did not get one, because the node renders at most
+     * one level per frame. They keep the map they already have and come due again next frame.
+     */
+    readonly deferred: number;
+    /**
+     * Levels holding a redraw for an invalidation that is still inside its own `invalidationDelay`,
+     * so this frame is not the frame they render on. They keep the map they have, which is right for
+     * every static caster in it: only a caster streamed in since is missing, and the cumulative
+     * `coalesced` below is what is being waited out.
+     */
+    readonly held: number;
     /** Fraction of levels served from cache over the node's lifetime. */
     readonly reuseRatio: number;
+    /**
+     * Level renders over the node's lifetime, for any reason. `byMove` and `byInvalidation` are the two
+     * the node has — a window that moved, and an invalidation that asked and waited out its delay — and
+     * they add up to this exactly, because a render the single per-frame budget defers is counted
+     * against the reason that queued it and not again when it is finally taken.
+     */
+    readonly rendersTotal: number;
+    /** Of those, the renders taken because a level's window moved. */
+    readonly byMove: number;
+    /** Of those, the renders taken because an invalidation asked and its level's delay had passed. */
+    readonly byInvalidation: number;
+    /**
+     * Invalidation asks that cost no render of their own, over the node's lifetime: absorbed by a
+     * render the level was taking anyway for its window, or merged into an ask already waiting out
+     * that level's delay. The two of these are the shape of the win — with the default delays a walk
+     * asks once a second and renders about that often, and every ask in between is counted here.
+     */
+    readonly coalesced: number;
+    /**
+     * The same four counters per level, finest first: which window moved, which invalidation asked
+     * for a redraw, which level took the frame's single render, and which wanted one and did not get
+     * it. One entry per level per frame, so a harness reading this — or the `TN_VIRTUAL_SHADOW`
+     * marker line, which carries it — can see which level a walk keeps re-rendering instead of only
+     * how many.
+     */
+    readonly perLevel: readonly IVirtualShadowLevelStat[];
+}
+/** One level's row of {@link IVirtualShadowStats}: 1 or 0 per counter, per frame. */
+interface IVirtualShadowLevelStat {
+    /** The level's clip extent, in world units. */
+    readonly extent: number;
+    readonly deferred: number;
+    readonly invalidated: number;
+    readonly moved: number;
+    readonly rendered: number;
+    /** Caster meshes this level's chosen camera layers submit this frame. Zero if it did not render. */
+    readonly draws: number;
+    /** The same bill split by kind; the five parts sum to {@link draws}. */
+    readonly drawsBy: IVirtualShadowDraws;
+    /** The adaptive caster gate's scale on this level, 1 when it is not shedding casters. */
+    readonly gateScale: number;
+    /** Casters the gate hid on the render this level took this frame; zero if it did not render. */
+    readonly gateHidden: number;
+}
+/** One level's caster draws, by the kind of mesh that submitted them. */
+interface IVirtualShadowDraws {
+    /** Caster batch meshes on the cluster layer, when the cluster half is the level's choice. */
+    readonly cluster: number;
+    /** Key-wide caster meshes on the wide layer, when the wide half is the level's choice. */
+    readonly wide: number;
+    /** Small casters, submitted by the finest level and by any level rendering a prewarm. */
+    readonly small: number;
+    /** Merged per-chunk shadow proxies (`<name>-shadow`), drawn with the cluster half. */
+    readonly chunkProxy: number;
+    /** Everything else casting from layer 0 — terrain, props — which every level draws. */
+    readonly layer0: number;
 }
 declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
 /**
@@ -1099,6 +2083,21 @@ declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
  * Keep it free of other uses; the main camera never needs it (tracked objects keep layer 0).
  */
 declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
+/**
+ * The object layer a shadow-only caster is put on, so each level's own shadow camera renders it and
+ * the main camera never sees it. The level cameras have it enabled already; an object that exists
+ * only as a shadow caster calls `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)`.
+ */
+declare const VIRTUAL_SHADOW_CASTER_LAYER = 28;
+/**
+ * The wide counterpart of {@link VIRTUAL_SHADOW_CASTER_LAYER}: one caster mesh per
+ * `asset:level:part` holding every resident cell's records, for the levels whose window covers the
+ * whole resident ring. A level renders exactly one of the two caster layers — whichever submits
+ * fewer draws, counted off the meshes themselves, because a cluster per square is a draw per square
+ * for the same pixels once the window holds the ring. `WorldCells` writes both halves of every key,
+ * so whichever a level picks is there; the main camera renders neither.
+ */
+declare const VIRTUAL_SHADOW_WIDE_CASTER_LAYER = 27;
 /**
  * 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
@@ -1113,7 +2112,9 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
  * 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.
+ * so the look is the same code path a plain shadow uses. At most one level renders per frame,
+ * finest first — a level render is a whole scene draw, and a level passed over keeps the map and
+ * window it has, so a fragment only ever samples a map that level drew.
  *
  * 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
@@ -1136,8 +2137,18 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
 declare class VirtualShadowNode extends ShadowBaseNode {
     #private;
     static get type(): string;
-    readonly options: Required<Omit<IVirtualShadowOptions, "marker">> & {
+    readonly options: Required<Omit<IVirtualShadowOptions, "marker" | "refreshStep" | "selectionGuard" | "invalidationDelay">> & {
         readonly markerEvery: number;
+        /** Per level, finest first; the last entry stands in for every level past it. */
+        readonly refreshStep: readonly number[];
+        /** The per-level `selectionGuard` each level's own window is drawn with. */
+        readonly selectionGuard: readonly number[];
+        /**
+         * Per level, finest first: the seconds a dirty level waits after its own last render before an
+         * invalidation may re-render it. Already scaled by that level's extent, so the fine levels
+         * answer a streamed caster promptly and the coarse ones let a burst merge into one render.
+         */
+        readonly invalidationDelay: readonly number[];
     };
     readonly clipmap: DirectionalClipmap;
     /**
@@ -1163,6 +2174,18 @@ declare class VirtualShadowNode extends ShadowBaseNode {
     untrackCaster(objectOrId: Object3D | string): boolean;
     /** Force every level to re-render on the next frame — a tree fell, a door opened. */
     invalidateAll(): void;
+    /**
+     * Force only the levels whose current window covers `bounds`, on the next frame. A streamed world
+     * that hands its shadow casters over has a moving near set, and a blanket `invalidateAll()` on
+     * every refresh redrew all three levels for a change that lands in one corner of one of them. A
+     * level whose window does not cover the region draws the same thing either way, so skipping it is
+     * the same frame with fewer draws in it.
+     *
+     * `bounds` is `{ min: {x,y,z}, max: {x,y,z} }`, a plain object so a game can hand one over without
+     * importing three. Regions are consumed by the next `updateBefore`; one that arrives before the
+     * levels exist is dropped, because their first frame renders all of them anyway.
+     */
+    invalidateRegion(bounds: IBoundsLike): void;
     setup(builder: NodeBuilder): Node | null | undefined;
     updateBefore(frame: NodeFrame): undefined;
     dispose(): void;
@@ -1178,6 +2201,87 @@ declare class VirtualShadowNode extends ShadowBaseNode {
  */
 declare function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined;
 
+/** Every value is the game's: this rig wires them and chooses none. */
+interface IDaylightOptions {
+    /** The eye the sky, the sun's shadow windows and the haze centre on; usually the camera. */
+    readonly follow: Object3D;
+    /** Unit vector from the ground towards the sun. */
+    readonly sunDirection: Vector3;
+    readonly sunColor: Color;
+    /** Irradiance in three's physical units; the same number a Blender sun strength carries. */
+    readonly sunIntensity: number;
+    /** Half-widths of the shadow windows in world units, finest first, strictly increasing. */
+    readonly shadowExtents: readonly number[];
+    /**
+     * How far a window may trail the camera before it re-renders, as a fraction of its own extent:
+     * one value for every level, or one per level finest first, the last entry standing in for the
+     * rest. One for all of them spends the hysteresis the fine level can least afford on the coarse
+     * one, which is the level a walking camera re-renders least. Default 0.125.
+     */
+    readonly refreshStep?: number | readonly number[];
+    /** Preetham sky parameters, as three's `SkyMesh` takes them. */
+    readonly sky: {
+        readonly turbidity: number;
+        readonly rayleigh: number;
+        readonly mieCoefficient: number;
+        readonly mieDirectionalG: number;
+    };
+    /** Sky fill from above and bounce from below, as a hemisphere light. */
+    readonly fill: {
+        readonly sky: Color;
+        readonly ground: Color;
+        readonly intensity: number;
+    };
+    /** Exponential-squared haze in the sky's horizon colour, so distance fades into the sky. */
+    readonly haze: {
+        readonly color: Color;
+        readonly density: number;
+    };
+    /** Linear exposure multiplier for the AgX tone curve (2^EV). */
+    readonly exposure: number;
+    /**
+     * Edge of the sky box in world units. It must sit inside the camera's far plane with its corners
+     * included (a box, so half-diagonal ≈ 0.87 × this).
+     */
+    readonly skySize: number;
+}
+/**
+ * An outdoor daylight rig: a physical sky that stays on the eye, one sun whose open-world shadow
+ * windows follow the eye (`VirtualShadowNode`), a hemisphere fill, sky-coloured distance haze and
+ * the AgX tone curve at the game's exposure. It is plumbing, not a look: every colour, angle,
+ * intensity and density is a required option, and the rig adds nothing a game did not ask for.
+ *
+ * Add it with `ctx.add(daylight)`: `attachRenderer` sets tone mapping, exposure and the shadow map
+ * once, and `process` (render cadence) keeps the sky box, the sun and its target on the eye every
+ * frame, so a 2 km map never walks out of its own sky or shadow.
+ *
+ * @situation daytime sky, sun and shadows for a large outdoor map
+ * @situation distant terrain should fade into the sky instead of a coloured wall
+ * @situation match a Blender look-dev scene's sun, sky and exposure in the game
+ * @constraint every value is required; there is no default sun, sky, haze or exposure
+ * @constraint `skySize` must keep the sky box's corners inside the camera's far plane
+ * @constraint shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
+ * @override sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
+ * @example
+ * const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });
+ * ctx.add(daylight);
+ */
+declare class Daylight extends Group implements IComputeDriven$1 {
+    #private;
+    readonly warmupNodes: readonly unknown[];
+    readonly processCadence: "render";
+    readonly sky: SkyMesh;
+    readonly sun: DirectionalLight;
+    readonly fill: HemisphereLight;
+    constructor(options: IDaylightOptions);
+    get released(): boolean;
+    /** The haze this rig owns; `attachRenderer` puts it on the scene the rig was added to. */
+    get haze(): FogExp2;
+    attachRenderer(renderer: IRendererLike): void;
+    process(): void;
+    detach(): void;
+}
+
 /**
  * Two load-time mechanisms every streaming game writes by hand, and gets wrong in the same places.
  *
@@ -1531,6 +2635,100 @@ declare class FluidField2D extends Group {
     detach(): void;
 }
 
+/**
+ * A disturbance that propagates. `WaveField` in this same package evaluates a fixed analytic
+ * swell: it is the sea a game always has, and nothing a game does changes it. This is the other
+ * half — a square patch of surface that is flat until something hits it, carries the rings
+ * outward at a real celerity, and forgets them again.
+ *
+ * The solve is the 2-D wave equation on a regular grid, plus an advected foam density. It owns no
+ * Three.js object, no material and no colour: it reports height, foam and horizontal flow, and the
+ * game decides what those look like. Add its height to an analytic swell; do not replace one.
+ *
+ * There is deliberately no obstacle or hull mask. A mask is only correct for a body that does not
+ * move, and a game whose hulls move is better served drawing the displacement those hulls make
+ * than re-rasterising a mask every time one of them advances a metre.
+ */
+interface IRippleFieldFlow {
+    x: number;
+    z: number;
+}
+interface IRippleFieldOptions {
+    /** Cells per side. Cost is quadratic in this; 128 over a 400 m patch is ~3 m per cell. */
+    readonly resolution: number;
+    /** Width of the patch in metres. */
+    readonly size: number;
+    /** Wave celerity in metres per second. Sets both ring speed and the stable step. */
+    readonly speed?: number;
+    /** Bulk damping. Higher forgets a disturbance sooner. */
+    readonly damping?: number;
+    /** Seconds for undisturbed foam to halve. */
+    readonly foamHalfLife?: number;
+    /** Steady surface drift in metres per second, added to the solved flow. */
+    readonly current?: IRippleFieldFlow;
+    /**
+     * Integration step in seconds. Defaults to 1/60 s, or the CFL limit for this cell size and
+     * celerity where that is smaller.
+     */
+    readonly step?: number;
+    /** Substeps one `advance` will run before it drops the rest of the frame's time. */
+    readonly maxSteps?: number;
+}
+declare class RippleField {
+    #private;
+    readonly resolution: number;
+    readonly size: number;
+    readonly dx: number;
+    readonly speed: number;
+    readonly damping: number;
+    readonly step: number;
+    readonly maxSteps: number;
+    foamHalfLife: number;
+    current: IRippleFieldFlow;
+    /** Surface height per cell, row-major from the patch's -x/-z corner. Read-only to the game. */
+    height: Float32Array;
+    /** Foam density per cell in 0..1. */
+    foam: Float32Array;
+    /** Horizontal flow per cell, metres per second, excluding `current`. */
+    readonly flowX: Float32Array;
+    readonly flowZ: Float32Array;
+    /** Patch centre in world metres, always snapped to a whole cell. */
+    centerX: number;
+    centerZ: number;
+    /** Simulated seconds elapsed. */
+    time: number;
+    /** Bumped whenever a cell changes, so a texture upload can skip an unchanged frame. */
+    version: number;
+    constructor(options: IRippleFieldOptions);
+    /** True while the point is inside the patch, `margin` metres in from its rim. */
+    contains(x: number, z: number, margin?: number): boolean;
+    /**
+     * Move the patch so it covers the action. The grid shifts by whole cells and the newly exposed
+     * band arrives flat, which is what the sponge rim had already damped it to.
+     */
+    recenter(x: number, z: number): void;
+    /**
+     * Push the surface at a point: a Gaussian of the given radius, with the kernel corrected so the
+     * disturbance injects no net volume. Without that correction every splash slowly raises the sea.
+     * Returns false when the point is outside the patch.
+     */
+    impulse(x: number, z: number, radius: number, amplitude: number, foam?: number): boolean;
+    /** Lay down entrained air without claiming a pressure impulse happened. */
+    depositFoam(x: number, z: number, radius: number, amount: number): boolean;
+    /** Run whole fixed steps to consume `dt`, and report how many ran. */
+    advance(dt: number): number;
+    /** Disturbance height in metres at a world point, zero outside the patch. */
+    heightAt(x: number, z: number): number;
+    /** Foam density in 0..1 at a world point. */
+    foamAt(x: number, z: number): number;
+    /** Surface flow in metres per second at a world point, including `current`. */
+    flowAt(x: number, z: number, out?: IRippleFieldFlow): IRippleFieldFlow;
+    /** Total disturbance energy. Zero on an undisturbed patch; useful as a test oracle. */
+    energy(): number;
+    /** Flatten the patch and forget every disturbance. Position, options and time survive. */
+    reset(): void;
+}
+
 type WaveDirection = readonly [number, number] | {
     readonly x: number;
     readonly z?: number;
@@ -1597,7 +2795,21 @@ declare class WaveField {
     constructor(options: IWaveFieldOptions);
     /** Update the default graph clock. Explicit sample times remain available for fixed-step code. */
     setTime(value: number): void;
+    /**
+     * Surface height and normal at a point. Allocates the result and its vector; a caller that wants
+     * only the number should call `heightAt`, which is the same evaluation without either.
+     */
     sample(x: number, z: number, time: number): IWaveFieldSample;
+    /**
+     * Surface height at a point, as a number.
+     *
+     * The scalar half of `sample`, and the same arithmetic in the same order, so the two agree
+     * exactly. What it skips is everything only a normal needs: the domain warp's jacobian, the
+     * cosine and slope of every wave, the normalisation, the result object and the `Vector3`. A
+     * floating hull, a splash query or a whitewater height test asks this question thousands of times
+     * a frame and throws the normal away every time.
+     */
+    heightAt(x: number, z: number, time: number): number;
     /** Surface height at a point, as a graph. The scalar half of what `sample` returns. */
     heightNode(options?: IWaveFieldGraphOptions): Node<"float">;
     /**
@@ -1617,17 +2829,53 @@ declare class WaveField {
     displacementNode(timeNode?: three_webgpu.UniformNode<"float", number>): Node<"vec3">;
 }
 
-/** How the mirrored pass is sized. Both numbers are cost, not appearance. */
+/** What the mirrored pass costs: how big it is, how many of them, and how much of the world. */
 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.
+     * How many *pixels* the second pass costs. Half is the usual answer. This is not on its own the
+     * number that decides whether a surface is affordable, and a game that reads it that way will
+     * measure no improvement and conclude its water is free: a scene with many objects is bound by
+     * the draw calls the mirrored pass submits, not by its pixels, and those do not shrink with the
+     * target. Measured on `sandbox/midway-open-pacific` at 1920x1080 on an nvidia/turing adapter with
+     * 1,965 draws in the frame, halving this again — 0.5 to 0.25 — moved GPU p95 from 17.80 ms to
+     * 17.58 ms. Removing the pass entirely moved it to 7.67 ms. `layers` is the number that mattered.
      */
     readonly resolutionScale: number;
     /** Whether this surface may appear in other reflectors' passes. Off is one pass; on is n². */
     readonly bounces?: boolean;
+    /**
+     * Which layers the mirrored pass draws, as a three `Layers` mask. Omit to draw everything the
+     * scene camera draws, which is the default and what a reflection means when nothing says
+     * otherwise.
+     *
+     * This is how much *world* the second pass costs, and on a crowded scene it is the whole bill.
+     * The mirrored pass is a second draw of everything, so a frame with sixty-eight aircraft in it
+     * pays for sixty-eight aircraft twice — once where the player can see them and once in the water,
+     * where they are a few pixels and half of them are behind the camera anyway. Put the big
+     * silhouettes a player actually reads in the water on their own layer and name it here.
+     *
+     * The mask decides what appears in the mirror, so the game owns it: this only carries the number
+     * through to the pass, and a game that omits it gets the whole world reflected as before.
+     */
+    readonly layers?: number;
+    /**
+     * How often the mirrored pass redraws, in presented frames.
+     *
+     * The reflection is a second render of the world and on a crowded sea it is the largest single
+     * item in the frame. It is also low-frequency: a swell, a hull and a wake read the same whether
+     * the mirror was taken this frame or two frames ago, and at speed the eye cannot hold a reflected
+     * silhouette still enough to notice it lag. `2` redraws every second frame and samples the
+     * previous frame's target in between, halving the pass's cost; a higher number halves it again.
+     *
+     * Omit it — or pass `1` — and the pass redraws every frame, which is the shipping behaviour and
+     * the default. The trade is temporal: while the camera moves, the reflection is up to
+     * `refreshInterval - 1` frames behind the scene it mirrors. Fast camera motion can make a
+     * reflected edge shimmer, and a moving object's reflection trails it. A still camera sees none of
+     * that, so name it only where the measured pass dominates the frame.
+     */
+    readonly refreshInterval?: number;
 }
 interface IWaterSurfaceOptions {
     /** World-space height of the surface, in metres. The mirror plane, and where thickness is 0. */
@@ -1681,6 +2929,19 @@ declare class WaterSurface3D {
      */
     readonly target: Object3D | undefined;
     constructor(options: IWaterSurfaceOptions);
+    /**
+     * The camera the mirrored pass draws this surface with, for one scene camera.
+     *
+     * The pass mints one of these per scene camera, lazily, and reflects the camera through the
+     * mirror plane each frame. It is exposed because `layers` is not the only thing a game may need
+     * to say about the second draw — a near/far pair is the other — and because a reflection you
+     * cannot inspect is a reflection you cannot cost. Undefined when this surface has no reflection.
+     */
+    reflectionCameraFor(camera: Camera): Camera | undefined;
+    /** What the mirrored pass draws, as the mask the game supplied. Undefined means everything. */
+    readonly reflectionLayers: number | undefined;
+    /** How often the mirrored pass redraws, in presented frames. `1` is every frame, the default. */
+    readonly reflectionRefreshInterval: number;
     /** 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. */
@@ -1872,6 +3133,213 @@ declare class GroundSnap {
     audit(): number | null;
 }
 
+/**
+ * Force-integrated fixed-wing flight dynamics for a game-owned aircraft.
+ *
+ * The model integrates lift, drag, thrust and aerodynamic moments in SI units, `+Y` up, with the
+ * nose down local `-Z`. Attitude is a quaternion, so there are no Euler clamps and no commanded
+ * velocity vectors: the game writes controls, the model writes forces, and the aircraft keeps its
+ * own momentum. Every number that decides how the aircraft looks or performs — mass, wing area,
+ * engine power, inertia, control authority, wind, damage multipliers and payload — arrives from
+ * the game. This module owns only the mechanism that turns those inputs into motion.
+ */
+interface IFlightVector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface IFlightQuaternion {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+interface IFlightAxes {
+    readonly r: IFlightVector3;
+    readonly u: IFlightVector3;
+    readonly f: IFlightVector3;
+}
+/** Per-aircraft constants. The game supplies these; the model ships no airframe of its own. */
+interface IAircraftAirframe {
+    /** Empty mass, kg. */
+    readonly dryMass: number;
+    /** Mass of a full fuel load, kg. */
+    readonly fuelMass: number;
+    /** Reference wing area, m². */
+    readonly wingArea: number;
+    /** Wingspan, m. */
+    readonly span: number;
+    /** Mean aerodynamic chord, m. */
+    readonly chord: number;
+    /** Shaft power at full throttle, W. */
+    readonly power: number;
+    /** Propeller efficiency, 0–1. */
+    readonly propEfficiency: number;
+    /** Maximum static thrust, N. */
+    readonly staticThrust: number;
+    /** Pitch moment of inertia, kg·m². */
+    readonly pitchInertia: number;
+    /** Roll moment of inertia, kg·m². */
+    readonly rollInertia: number;
+    /** Yaw moment of inertia, kg·m². */
+    readonly yawInertia: number;
+}
+/** Multipliers a game applies for damage, load or upgrades. 1 / 0 is the undamaged case. */
+interface IFlightModifiers {
+    readonly power: number;
+    readonly lift: number;
+    readonly drag: number;
+    readonly roll: number;
+    readonly controls: number;
+}
+declare const NEUTRAL_FLIGHT_MODIFIERS: IFlightModifiers;
+/** One fixed step of pilot input. Every field is a dimensionless command in `[-1, 1]`. */
+interface IFlightControls {
+    readonly turn?: number;
+    readonly pitch?: number;
+    readonly rudder?: number;
+    readonly wheelBrake?: boolean;
+    /** When true, stability assist is bypassed and the game commands the attitude directly. */
+    readonly autopilot?: boolean;
+}
+/** The moving deck an aircraft launches from. */
+interface IFlightDeck {
+    readonly x: number;
+    readonly y?: number;
+    readonly z: number;
+    readonly heading: number;
+    readonly speed: number;
+    readonly length: number;
+    readonly width: number;
+}
+interface IFlightState {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    attitude?: IFlightQuaternion;
+    heading: number;
+    pitch: number;
+    roll: number;
+    rollRate: number;
+    pitchRate: number;
+    yawRate: number;
+    speed: number;
+    ias: number;
+    groundSpeed: number;
+    throttle: number;
+    rpm: number;
+    fuel: number;
+    hp: number;
+    engineCut: boolean;
+    gear: boolean;
+    brakes: boolean;
+    gearPos: number;
+    brakePos: number;
+    flapPos: number;
+    flaps: number;
+    aileron: number;
+    elevator: number;
+    rudder: number;
+    controlAileron: number;
+    assist: boolean;
+    trim: number;
+    gforce: number;
+    aoa: number;
+    beta: number;
+    stall: number;
+    /** Mass of everything under the wings, kg. The game writes it as stores are released. */
+    payloadMass: number;
+    /** Extra flat-plate drag coefficient from external stores. */
+    payloadDrag: number;
+    flightTime: number;
+    lift: number;
+    drag: number;
+    thrust: number;
+    mass: number;
+    deckSpeed?: number;
+    deckLateral?: number;
+    deckOffset?: number;
+    chocks?: boolean;
+}
+interface IFlightEnvironment {
+    readonly airframe: IAircraftAirframe;
+    readonly wind?: IFlightVector3;
+    readonly modifiers?: IFlightModifiers;
+    readonly gravity?: number;
+    /** Height of the carrier deck surface above the water, m. */
+    readonly deckHeight?: number;
+}
+interface IFlightForces {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly normalLoad: number;
+    readonly lift: number;
+    readonly drag: number;
+    readonly thrust: number;
+    readonly alpha: number;
+    readonly beta: number;
+    readonly airspeed: number;
+    readonly density: number;
+    readonly mass: number;
+    readonly qs: number;
+    readonly axes: IFlightAxes;
+    readonly cl: number;
+    readonly cd: number;
+    readonly stall: number;
+    readonly critical: number;
+}
+/** ISA air density at altitude `y` metres, kg/m³. */
+declare function airDensity(y: number): number;
+/** Current mass of the aircraft from its empty mass, fuel load and game-written payload. */
+declare function aircraftMass(state: IFlightState, airframe: IAircraftAirframe): number;
+/** Lift and drag coefficients for an angle of attack and the deployed high-lift devices. */
+declare function aerodynamicCoefficients(alpha: number, flaps?: number, gear?: number, brakes?: number): {
+    cl: number;
+    cd: number;
+    stall: number;
+    critical: number;
+};
+/** Write a heading/pitch/roll pose into the body quaternion. Nose down local `-Z`. */
+declare function setAttitude(state: IFlightState, heading?: number, pitch?: number, roll?: number): IFlightQuaternion;
+/** Right, up and forward unit vectors of the body frame. */
+declare function attitudeAxes(state: IFlightState): IFlightAxes;
+/** Height of the gear contact point below the body origin at the current pitch. */
+declare function gearClearance(state: IFlightState): number;
+interface IFlightModelOptions<TState extends IFlightState = IFlightState> extends IFlightEnvironment {
+    /** The game's own aircraft object, extended with whatever else the game needs on it. */
+    readonly state: TState;
+}
+/**
+ * One aircraft's dynamics: a thin owner of a game-authored state object plus its environment.
+ *
+ * The step record copies the options' own fields once, at construction — so `airframe`, `wind`,
+ * `gravity` and `deckHeight` are read from the objects those fields reference, which stay live,
+ * but replacing a field on the options object afterwards is not observed. Change a model's airframe
+ * or deck by building it again, as a game that binds aircraft to carriers already does.
+ *
+ * @example
+ * const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
+ * model.setAttitude(0, 0.2, 0);
+ * model.step(1 / 60, { turn: -1, pitch: 0.4 });
+ */
+declare class FlightModel<TState extends IFlightState = IFlightState> {
+    #private;
+    readonly state: TState;
+    readonly environment: IFlightEnvironment;
+    constructor(options: IFlightModelOptions<TState>);
+    setAttitude(heading?: number, pitch?: number, roll?: number): void;
+    reset(): void;
+    axes(): IFlightAxes;
+    gearClearance(): number;
+    forces(modifiers?: IFlightModifiers): IFlightForces;
+    step(dt: number, controls: IFlightControls, modifiers?: IFlightModifiers): void;
+    stepDeck(deck: IFlightDeck, dt: number, controls: IFlightControls, modifiers?: IFlightModifiers): "liftoff" | "overrun" | null;
+}
+
 type ThreePoseVector = readonly [number, number, number];
 type ThreePoseQuaternion = readonly [number, number, number, number];
 interface IThreePoseBounds {
@@ -1917,21 +3385,6 @@ declare function measureThreePose(object: Object3D, options?: IMeasureThreePoseO
  */
 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[];
@@ -2189,6 +3642,6 @@ declare function boneLengthDeviations(root: Object3D, bind: IBoneLengthSnapshot,
  * 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.2";
+declare const version = "0.3.4";
 
-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 };
+export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, Daylight, FlightModel, FluidField2D, FramePassKind, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, 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 IDaylightOptions, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, IFrameBudgetWindow, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergeByMaterialOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type IRippleFieldFlow, type IRippleFieldOptions, type ISceneShape, type ISceneWarning, type ISkeletalMesh3DOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISpanProbeTarget, type ISpanSummary, type ISpanWindow, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, type IStaticTransformCensus, type IStrideReport, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IValidationReport, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LUT_RESOLUTIONS, type LaunchFailureKind, type MatrixWorldMode, MatrixWorldPass, NEUTRAL_FLIGHT_MODIFIERS, type NormaliseAxis, PROBE_VOLUME_MARKER, PathFollow3D, ProbeVolume, type ProbeVolumeDensity, RENDERLIST_VALIDATE_FLAG, RENDERLIST_VALIDATE_MARKER, type Recording, RenderListValidator, type ReplayPointer, RippleField, SCENE_WARNING_MARKER, SPANS, SPANS_FLAG, SPANS_MARKER, SPAN_COUNT, SPAN_NAMES, STATIC_TRANSFORM_MARKER, SkeletalMesh3D, SoftBody3D, type SpanId, SpanRecorder, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, VIRTUAL_SHADOW_CASTER_LAYER, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VIRTUAL_SHADOW_WIDE_CASTER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addInSlices, addSpan, aerodynamicCoefficients, airDensity, aircraftMass, alwaysRender, attachToBone, attitudeAxes, baseGeometryOf, beginSpan, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, debugFlag, describeSceneShape, describeSceneWarning, directionFromSolarPosition, directionalTransmittance, displayPeriodMs, endSpan, exposeDebug, formatSceneWarning, formatSpansWindow, formatValidationReport, gearClearance, installSpanProbes, invalidateStatic, isStatic, loadAll, lodPixelScale, markStatic, measureThreePose, mergeByMaterial, mergeParts, normaliseToMetres, onLaunchFailure, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, readVirtualShadowMarker, refreshStaticTransforms, renderListValidationRequested, replay, resetStaticTransforms, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, sceneWarning, setAttitude, setSpanRecorder, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, spanNow, spanRecorder, spansRequested, staticTransformCensus, unmarkStatic, updateAtmosphereParameters, updateClusteredMeshes, updateModelLods, validateWorldMatrices, version, zenithTransmittance };