@threenative/core 0.3.3 → 0.3.4

package/dist/world.d.ts

@@ -1,7 +1,7 @@
-import { Object3D, Mesh, LOD, Vector3, Group, BufferGeometry } from 'three';
-import { I as IComputeDriven, a as IGPUReadbackSample } from './gpu-readback-CMklJs6r.js';
-import { I as IRendererLike } from './renderer-Cy4qeBOA.js';
-import { I as IAssetLoader } from './assets-CYKk2WTu.js';
+import { Object3D, Mesh, LOD, Vector3, Material, Group, Camera, BufferGeometry } from 'three';
+import { I as IComputeDriven, a as IGPUReadbackSample } from './gpu-readback-CqJEfWNQ.js';
+import { I as IRendererLike } from './renderer-CfsS2hxi.js';
+import { I as IAssetLoader } from './assets-CqvE429w.js';
 import 'three/webgpu';
 
 interface IWorldErosionOptions {
@@ -25,9 +25,27 @@ interface IWorldTileColliderInput {
     readonly tileX: number;
     readonly tileZ: number;
 }
+/**
+ * One frame's allowance for admission work — the millisecond budget every path that puts streamed
+ * content on screen draws on, spent in bounded units rather than in one lump.
+ *
+ * `admit` is the whole contract: run one unit and charge the frame for it, or report that there was
+ * no room and run nothing. A caller that is refused leaves the work for a later frame instead of
+ * dropping it, so the budget decides *when* content is admitted, never *whether*.
+ *
+ * Nothing here decides what anything looks like; it decides only how much of it a frame may pay for.
+ */
+interface IAdmissionBudget {
+    /**
+     * Run one unit of admission work, charging the frame's budget for it. `false` means the budget
+     * was spent and `work` was never called, so the caller must stop and resume on a later frame.
+     */
+    admit(work: () => void): boolean;
+}
 interface IWorldTile {
     readonly bytes: number;
-    readonly collider: IWorldTileCollider;
+    /** `undefined` for a resident tile outside `colliderRadius`, or when no factory was given. */
+    readonly collider: IWorldTileCollider | undefined;
     readonly field: Heightfield;
     readonly key: string;
     readonly lod: LOD;
@@ -53,6 +71,14 @@ interface IWorldTilesOptions {
     readonly assets?: Pick<IAssetLoader, "release">;
     /** A game-owned, already-loaded logical model key, or a key resolver per tile. */
     readonly assetKey?: string | ((tileX: number, tileZ: number) => string);
+    /**
+     * Chebyshev radius, in tiles from the followed one, that gets a `createCollider` body. Defaults
+     * to `streamRadius`, so every resident tile collides. A smaller radius keeps a wide render ring
+     * cheap to simulate: a tile crossing the radius has its collider created or disposed as it goes.
+     */
+    readonly colliderRadius?: number;
+    /** Terrain tiles and seam bridges receive the scene's shadows. Default false. */
+    readonly receiveShadow?: boolean;
     /** Creates the physics body from the field's explicit collider-order copy. */
     readonly createCollider?: (input: IWorldTileColliderInput) => IWorldTileCollider;
     /** TSL pass options are game supplied and are forwarded to each resident field. */
@@ -72,6 +98,20 @@ interface IWorldTilesOptions {
     readonly lodFactors?: readonly number[];
     /** Distances in world units at which the next LOD becomes active. */
     readonly lodDistances?: readonly number[];
+    /**
+     * Re-derive the terrain every frame and assert it: a finiteness scan of every rendered vertex,
+     * a seam measurement per resident pair and an LOD pop sample per blending tile. Off by default
+     * because it is a measurement and it cost ~270 ms over a six-second walk on a 289-tile ring.
+     * `TN_TERRAIN_VALIDATE=1` or `?tnTerrainValidate=1` turns it on for a run; this overrides that.
+     */
+    readonly validate?: boolean;
+    /**
+     * Merge settled same-LOD terrain tiles into super-tiles: one mesh per K×K block, rebuilt from the
+     * resident tiles through the admission budget. It changes how many draws the main pass submits,
+     * never how the ground looks — a merged vertex lands on the world position its tile's vertex did.
+     * Off by default; `mergeTiles: true`, `?tnTerrainMerge=1` or `TN_TERRAIN_MERGE=1` turns it on.
+     */
+    readonly mergeTiles?: boolean;
     /** Explicit game-owned measurement region used by the topology evaluator. */
     readonly topologyObservation?: IWorldTilesTopologyObservation;
 }
@@ -86,7 +126,8 @@ interface IWorldTilesOptions {
  * @alias stream terrain across chunks
  * @constraint sampleHeight and surface are required game choices; no landform or surface preset is installed
  * @constraint residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
- * @override tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets
+ * @constraint seam gap, LOD pop and the rendered-vertex finiteness scan are measurements that are off by default; TN_TERRAIN_VALIDATE=1, ?tnTerrainValidate=1 or validate: true runs them, and maxSeamGap, maxVisualSeamGap and maxLodPop report undefined while they are off
+ * @override tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets
  * @example const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
  */
 declare class TerrainTiles extends Object3D implements IComputeDriven {
@@ -107,19 +148,63 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
     get residentColliderKeys(): readonly string[];
     get lodLevelCount(): number;
     get lodTransitions(): number;
-    /** Maximum per-render-frame displacement of the visible LOD surface during transitions. */
-    get maxLodPop(): number;
+    /**
+     * What the main pass submits for terrain levels right now: `tiles` surfaces, held as `blocks`
+     * merged super-tiles plus one mesh each for the tiles that are not merged (a lone block member or
+     * a tile mid LOD morph). `draws` is `blocks` plus those individual meshes, so with the merge off
+     * it is exactly the number of visible level meshes — the census the merge exists to cut. `rebuilds`
+     * counts the block geometries built over this residency owner's life.
+     */
+    get terrainTiles(): {
+        readonly blocks: number;
+        readonly draws: number;
+        readonly rebuilds: number;
+        readonly tiles: number;
+    };
+    /**
+     * Resident tiles mid LOD morph right now, so `process` is still owed. A blend is
+     * `LOD_TRANSITION_FRAMES` frames long and only `process` advances it, so a caller that skips
+     * `process` while its follow point is standing still would freeze every blend on frame one.
+     */
+    get blendingTiles(): number;
+    /**
+     * Maximum per-render-frame displacement of the visible LOD surface during transitions.
+     *
+     * `undefined` when validation is off: the pop is sampled by measuring the rendered surface twice
+     * a frame, and reporting the empty value `0` instead of a measurement would be a lie a caller
+     * could assert on.
+     */
+    get maxLodPop(): number | undefined;
     /** Maximum number of rendered frames during which an LOD transition remained observable. */
     get maxLodTransitionFrames(): number;
-    /** Maximum visible edge gap observed across follow/process calls for this residency owner. */
-    get maxSeamGap(): number;
-    /** Maximum remaining visible gap after skirt or bridge coverage observed across follow/process calls. */
-    get maxVisualSeamGap(): number;
+    /**
+     * Maximum visible edge gap observed across follow/process calls for this residency owner, or
+     * `undefined` when validation is off — see `maxLodPop`.
+     */
+    get maxSeamGap(): number | undefined;
+    /**
+     * Maximum remaining visible gap after skirt or bridge coverage observed across follow/process
+     * calls, or `undefined` when validation is off — see `maxLodPop`.
+     */
+    get maxVisualSeamGap(): number | undefined;
     /** Number of mixed-LOD edge reconciliations observed during this residency lifetime. */
     get stitchedEdgeCount(): number;
+    /**
+     * A tile or a collider the last `follow` wanted and its budget refused, so the next one is owed
+     * work even for an unmoved follow point. `0` once a pass wanted nothing it did not get.
+     */
+    get deferredAdmissions(): number;
     get warmupNodes(): readonly unknown[];
     getTile(key: string): IWorldTile | undefined;
-    follow(position: IWorldTilesFollowPosition | Pick<Vector3, "x" | "z">): void;
+    /**
+     * Move residency to the followed point: admit, evict and re-level every tile.
+     *
+     * `budget` caps what one call may admit. A tile the budget refuses is not resident this pass and
+     * costs nothing to try again, because `follow` recomputes the wanted set on every call — which is
+     * what makes this safe to defer: the tile was not drawn before either, so a refused admission
+     * leaves a gap rather than a hole. Omitted, a call admits everything it wants, as it always did.
+     */
+    follow(position: IWorldTilesFollowPosition | Pick<Vector3, "x" | "z">, budget?: IAdmissionBudget): void;
     heightAt(x: number, z: number): number;
     normalAt(x: number, z: number, target?: Vector3): Vector3;
     sample(channel: string, x: number, z: number): number;
@@ -130,6 +215,37 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
     dispose(): void;
 }
 
+/**
+ * The oracle for terrain geometry that is otherwise trusted every frame.
+ *
+ * `TerrainTiles` re-derives what it already knows — every rendered vertex checked for finiteness,
+ * every resident seam re-measured, every LOD blend's visible displacement sampled — and that is a
+ * measurement, not a mechanism: on a 289-tile ring a six-second walk paid ~270 ms in three loops
+ * that only throw when something is already broken. So it is off by default and the shipped frame
+ * trusts the cheap change detector instead, which compares buffer versions and the residency and
+ * LOD state the class writes itself.
+ *
+ * `TN_TERRAIN_VALIDATE=1`, `?tnTerrainValidate=1`, or `validate: true` on the constructor puts the
+ * loops back and every assertion with them. It is a validation mode, not a proof: it proves the
+ * frames it ran on.
+ */
+/** Marker printed when terrain validation is on, so a log says which mode produced it. */
+declare const TERRAIN_VALIDATE_MARKER = "TN_TERRAIN_VALIDATE";
+/** The launch flag. */
+declare const TERRAIN_VALIDATE_FLAG = "TN_TERRAIN_VALIDATE";
+/**
+ * Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.
+ *
+ * @situation turn terrain's per-frame seam, LOD pop and vertex checks on for one run
+ * @situation assert the terrain geometry a game streams before it ships
+ * @constraint off by default: it is the work it checks, every frame
+ * @example // Reads its own the way `renderListValidationRequested` does: a native launch sets the
+ * // environment variable, a browser asks with the query string, a test or harness sets the
+ * // global. `0` and `false` are off, so a saved URL that enabled it still says "off".
+ * const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
+ */
+declare function terrainValidationRequested(): boolean;
+
 type WorldGenerationPath = "gpu" | "cpu-fallback" | "unsupported";
 interface IWorldComputeLimits {
     readonly maxComputeInvocationsPerWorkgroup: number;
@@ -171,6 +287,776 @@ interface IWorldCapabilitiesOptions {
  */
 declare function getWorldCapabilities(options?: IWorldCapabilitiesOptions): IWorldCapabilities;
 
+/**
+ * The `world.json` package contract: a versioned manifest that names a raw heightmap, stable
+ * asset ids, placement runs and the square cells that stream them.
+ *
+ * Every value is authored by the world exporter and read by the runtime, so the game never
+ * hard-codes a cell layout or an asset path. Validation never throws on malformed JSON-shaped
+ * input: it collects named errors so an exporter can report every problem in one pass.
+ */
+type WorldPackageErrorCode = "WORLD_VERSION_MISMATCH" | "WORLD_UNKNOWN_ASSET" | "WORLD_RUN_OUT_OF_RANGE" | "WORLD_CELL_OUTSIDE_EXTENT" | "WORLD_MALFORMED";
+interface IWorldPackageError {
+    readonly code: WorldPackageErrorCode;
+    readonly message: string;
+    /** JSON-shaped path to the offending field, e.g. `cells[2].runs[0].offset`. */
+    readonly path: string;
+}
+interface IWorldExtent {
+    readonly minX: number;
+    readonly minZ: number;
+    readonly sizeX: number;
+    readonly sizeZ: number;
+}
+interface IWorldTerrain {
+    /** Package-relative path to the raw little-endian uint16 heightmap. */
+    readonly heightmap: string;
+    /** Vertex counts; `columns = sizeX / spacing + 1`, likewise `rows`. */
+    readonly columns: number;
+    readonly rows: number;
+    /** Metres between adjacent heightmap vertices on both axes. */
+    readonly spacing: number;
+    readonly heightMin: number;
+    readonly heightMax: number;
+    /** Optional opaque layer-mask paths, passed through to the game's surface untouched. */
+    readonly layers?: Readonly<Record<string, string>>;
+}
+interface IWorldAssetLod {
+    readonly glb: string;
+    readonly distance: number;
+}
+interface IWorldAssetBounds {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+}
+interface IWorldAsset {
+    readonly glb: string;
+    readonly lods?: readonly IWorldAssetLod[];
+    readonly bounds: IWorldAssetBounds;
+    readonly maxDistance?: number;
+}
+interface IWorldRun {
+    readonly asset: string;
+    /** Record offset into `placements`; one record is eight float32 values. */
+    readonly offset: number;
+    readonly count: number;
+}
+interface IWorldCell {
+    readonly x: number;
+    readonly z: number;
+    readonly runs: readonly IWorldRun[];
+    readonly chunks?: readonly string[];
+}
+interface IWorldPackage {
+    readonly version: 1;
+    readonly extent: IWorldExtent;
+    readonly cellSize: number;
+    readonly terrain: IWorldTerrain;
+    readonly assets: Readonly<Record<string, IWorldAsset>>;
+    readonly placements: string;
+    readonly cells: readonly IWorldCell[];
+}
+interface IWorldPackageValidationOptions {
+    /** Byte length of the placement buffer the runs index into. */
+    readonly placementsByteLength: number;
+    /** When known, the heightmap length must be `columns * rows * 2`. */
+    readonly heightmapByteLength?: number;
+}
+/**
+ * Validate a `world.json` manifest against the v1 contract.
+ *
+ * Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is
+ * collected, so an exporter sees the complete list at once.
+ *
+ * @situation check a Blender-exported world package before the runtime attaches anything
+ * @situation report why a world package cannot be streamed
+ * @constraint validation only checks structure and ranges; it never fetches the heightmap or GLBs
+ * @example const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
+ */
+declare function validateWorldPackage(manifest: unknown, options: IWorldPackageValidationOptions): {
+    ok: boolean;
+    errors: IWorldPackageError[];
+};
+/**
+ * Borrow the run's placement records as a live view over the placement buffer.
+ *
+ * @situation feed one cell's instance transforms into a batch without copying
+ * @constraint the returned view aliases the caller's buffer; writing to it mutates the source
+ * @example const records = cellPlacements(buffer, { asset: "tree", offset: 0, count: 120 });
+ */
+declare function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array;
+
+/**
+ * Build a game-usable `sampleHeight` from a raw v1 heightmap.
+ *
+ * The returned function interpolates bilinearly in world units and clamps to the map edges, so it
+ * plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is
+ * `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
+ *
+ * @situation turn an exported raw heightmap into terrain collision and rendering
+ * @situation query ground height from a Blender-authored world package
+ * @constraint the sampler reads the game's data; the framework never selects a terrain shape
+ * @example const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
+ */
+declare function heightSamplerFromHeightmap(terrain: IWorldTerrain, extent: IWorldExtent, data: Uint16Array): (x: number, z: number) => number;
+/**
+ * Fetch a raw little-endian uint16 heightmap and expose it as samples.
+ *
+ * @situation load a world package's heightmap once before building terrain
+ * @constraint a non-OK response throws; bytes are byte-swapped only on a big-endian host
+ * @example const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
+ */
+declare function loadWorldHeightmap(url: string): Promise<Uint16Array>;
+
+type Channel = "r" | "g" | "b" | "a";
+/** One texture set: albedo (and optionally a normal map) tiled in metres, tinted in linear. */
+interface ITerrainSplatLayer {
+    readonly id: string;
+    readonly tile: number;
+    readonly tint: readonly [number, number, number];
+    readonly normal?: boolean;
+    readonly saturation?: number;
+    /** Box-projected, for cliffs a top-down projection smears. */
+    readonly triplanar?: boolean;
+}
+/** A layer blended over what is below it by one mask channel, remapped from `lo..hi`. */
+interface ITerrainSplatMaskedLayer extends ITerrainSplatLayer {
+    readonly mask: string;
+    /** The component of a `rgb` mask; ignored by a single-component mask. */
+    readonly channel: "r" | "g" | "b";
+    readonly lo: number;
+    readonly hi: number;
+}
+/**
+ * The package's terrain table (`terrain.layers.table`). Written by the export recipe
+ * `export_terrain_layers.py` from the game's own table; every value is the game's.
+ */
+interface ITerrainSplatTable {
+    readonly base: ITerrainSplatLayer;
+    /** Noise (0..1 at `scale` per metre) that pushes every mask edge by +-`push`. */
+    readonly breakup: {
+        readonly scale: number;
+        readonly push: number;
+    };
+    /** Large-scale brightness variation against visible tiling, mapped to `min..max`. */
+    readonly macro: {
+        readonly scale: number;
+        readonly min: number;
+        readonly max: number;
+    };
+    readonly layers: readonly ITerrainSplatMaskedLayer[];
+    /**
+     * `terrain.layers.splat`: `planes` RGBA8 planes of `size`², rows bottom-up, covering the
+     * package extent. `masks` names each mask's plane and component (`rgb` = pick by the layer's
+     * `channel`).
+     */
+    readonly splat: {
+        readonly size: number;
+        readonly planes: number;
+        readonly masks: Readonly<Record<string, readonly [number, Channel | "rgb"]>>;
+    };
+    /** Package-relative folder of `<id>_diff.jpg` and `<id>_nrm.jpg`. */
+    readonly textures: string;
+}
+interface ILoadTerrainSplatOptions {
+    readonly assets: IAssetLoader;
+    /** The world package's `world.json`, as `WorldCells.load` takes it. */
+    readonly url: string;
+}
+/**
+ * The splat terrain surface a world package describes, for `WorldCells.load({ surface })`.
+ *
+ * Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the
+ * heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness
+ * variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up
+ * authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries
+ * a normal map. Nothing here is a look choice: textures, tiles, tints, thresholds and noise scales
+ * all come from the package's table, which the game authors once and its DCC shares.
+ *
+ * @situation terrain textured by splat masks exported from Blender with the world package
+ * @situation the game's terrain should match the DCC's terrain material without a second copy
+ * @constraint the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `export_terrain_layers.py` recipe
+ * @constraint WebGPU allows 16 sampled textures per stage: planes + diffuse maps + normal maps must fit
+ * @override every value comes from the package's table; the returned material is the game's to adjust
+ * @example
+ * const surface = await loadTerrainSplat({ assets: ctx.assets, url: "world/world.json" });
+ * const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
+ */
+declare function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material>;
+
+/** The point a streamed world follows; an `Object3D` satisfies this shape. */
+interface IWorldCellsFollow {
+    readonly position: {
+        readonly x: number;
+        readonly z: number;
+    };
+}
+/** Hard caps on what stays resident. A cap that is reached reports pressure, it never throws. */
+interface IWorldCellsBudget {
+    readonly residentCells: number;
+    readonly instances: number;
+    /** Placement-record bytes (`32` per instance) the resident cells are allowed to weigh. */
+    readonly bytes: number;
+}
+/** Terrain options forwarded to the composed `TerrainTiles`; `tileSize` defaults to `cellSize`. */
+interface IWorldCellsTerrainOptions {
+    readonly tileSize?: number;
+    readonly tileResolution?: number;
+    readonly lodFactors?: readonly number[];
+    readonly lodDistances?: readonly number[];
+    readonly skirtDepth?: number;
+    /**
+     * Tiles kept resident around the follow tile, independent of the cell `ring`: terrain can reach
+     * to the horizon while props stay near. Defaults to `ring`, so raising only this widens the
+     * ground without widening the props, and the far tiles take the coarser `lodDistances` levels.
+     */
+    readonly streamRadius?: number;
+    /**
+     * Tiles that get a `createCollider` body, by Chebyshev radius from the follow tile. Defaults to
+     * `ring`. A tile entering or leaving it creates or disposes its collider, so a wide terrain
+     * radius does not have to mean a physics body for every tile in it.
+     */
+    readonly colliderRadius?: number;
+}
+interface IWorldCellsLoadOptions {
+    /**
+     * Logical path of `world.json` (`world/world.json`); every other path in the package resolves
+     * against it. A leading `/` is accepted and stripped, so an uncompiled `public/world` keeps
+     * working.
+     */
+    readonly url: string;
+    /**
+     * Loader the package's paths resolve through — its manifest, or the authored names when there is
+     * none. Defaults to a fresh `createAssetLoader()`; inside a game, pass `ctx.assets` so the
+     * package's compiled output and compressed textures reach the renderer the game booted with.
+     *
+     * The world releases the source models it asks this loader for only when it created the loader
+     * itself: each asset's requested level paths are released through `release("model", path)` once
+     * the last asset naming a path is gone, so a streamed package does not pin an internally owned
+     * cache. An explicitly supplied loader is the caller's — the world never releases its cache, so a
+     * second game or world holding the same model keeps it alive; the caller ends that lifetime with
+     * its own `release`. The loader is never cleared, and a path this world never asked for is never
+     * touched either way.
+     */
+    readonly assets?: IAssetLoader;
+    /** Game-owned terrain surface, handed straight to `TerrainTiles`. */
+    readonly surface: IWorldTilesOptions["surface"];
+    /** Passed straight to `TerrainTiles` for per-tile colliders. */
+    readonly createCollider?: IWorldTilesOptions["createCollider"];
+    /** Read once per update; an `Object3D` works. */
+    readonly follow: IWorldCellsFollow;
+    /** Chebyshev radius in cells to keep resident; a cell leaves only beyond `ring + 1`. */
+    readonly ring: number;
+    readonly budgets: IWorldCellsBudget;
+    readonly terrain?: IWorldCellsTerrainOptions;
+    /**
+     * How a scattered part whose own material is `transparent` is drawn. `"cutout"` (the default)
+     * gives the part a clone of that material with `transparent: false` and an `alphaTest`, so the
+     * instanced draw needs no per-instance sorting and the depth buffer rejects what is behind it;
+     * `"blend"` draws the material as authored. One clone per asset part, never per cell.
+     */
+    readonly transparentScatter?: "cutout" | "blend";
+    /**
+     * Shadows for the streamed world, all off by default. `cast` makes scattered batches cast into
+     * the scene's shadow map, but only their `castLevels` finest distance levels (default 1: the
+     * near shape), since a far LOD's shadow is sub-texel in any open-world shadow window and every
+     * caster is redrawn per shadow level. `receive` lets scatter and terrain receive shadows.
+     */
+    readonly shadows?: {
+        readonly cast?: boolean;
+        readonly castLevels?: number;
+        readonly receive?: boolean;
+        /**
+         * @deprecated Accepted and ignored. Clusters replace it: what a shadow level submits is bounded
+         * by the clusters its own window covers, not by a hand-tuned radius. It still validates, so a
+         * game that set it keeps compiling and keeps loading.
+         */
+        readonly castDistance?: number;
+        /**
+         * Called at most once a second after streamed records changed, so the shadow levels that read
+         * them redraw. `VirtualShadowNode.invalidateAll` is the whole of it, and a call with no region
+         * is exactly that. Not called per frame, and not called at all when nothing changed.
+         *
+         * When it is called about records, it is called with the union of the bounds of the records
+         * that changed — the placement position widened by the asset's own bounds, unioned over the
+         * records of this update and nothing else, so a hook that forwards it to
+         * `VirtualShadowNode.invalidateRegion` redraws the levels whose window covers them and leaves
+         * the rest of the cascade holding its maps. A call with no region is still a blanket one: the
+         * prewarm passes it while a caster's first draw is owed, and there is no region for that.
+         */
+        readonly invalidate?: (region?: IShadowRegion) => void;
+        /**
+         * An asset whose authored bounds are shorter than this casts into the finest shadow level only,
+         * default 1.5 m. Ground cover below it — ferns, grass, bushes — casts a shadow that is sub-texel
+         * noise at every range a wide level covers, and costs one draw per key per level there. Raise it
+         * to draw everything at every range, lower it to cull more. Measured on the authored bounds, so
+         * a package that scales a fern up four times is judged on the un-scaled fern.
+         */
+        readonly smallCasterMetres?: number;
+    };
+    /**
+     * Triangles a hand-placed chunk's merged material group may reach before one of its
+     * `InstancedMesh` is left instanced. Defaults to 43,690, the same 4 MiB
+     * budget the merged buffers are split on counted in the worst case, a de-indexed triangle: a merged
+     * group is a single draw, so expanding into it wins until the merged geometry is too big for the
+     * frame, and above it the instanced draw is the cheaper of the two. A group that crosses the budget
+     * is split into several meshes in traversal order rather than grown, and an instanced shape over
+     * 2,048 triangles is never expanded. Everything else in a chunk merges regardless — one mesh per
+     * material, in the main pass and in every shadow pass that redraws it.
+     */
+    readonly chunkMergeMaxTriangles?: number;
+    /**
+     * `(url) => Promise<Object3D>`, overriding `assets.model`; a raw `GLTFLoader` or a game's own
+     * loader works. The url is the authored one, so a compiled package wants `assets` instead.
+     */
+    readonly loadModel?: (url: string) => Promise<Object3D>;
+    /**
+     * Model loads in flight at once, assets and chunks together. Defaults to `loadAll`'s
+     * `concurrency`, six.
+     */
+    readonly concurrency?: number;
+    /**
+     * Cell-asset batches refiltered per `update`, nearest cell first. Defaults to 16. A cell that did
+     * not get its turn keeps drawing the batches it has until a later update replaces them.
+     */
+    readonly rebuildsPerUpdate?: number;
+    /**
+     * Seconds of motion to stream ahead of, default 1.5: the ring centres on where the follow point
+     * will be (`position + velocity * prefetchSeconds`), so a fast camera finds cells already loaded
+     * instead of outrunning them. The lead is capped at three quarters of the ring, so the cell the
+     * follow point is in always stays resident. `0` streams around the follow point itself.
+     */
+    readonly prefetchSeconds?: number;
+    /**
+     * New batch meshes created per update, default 2. On WebGPU each new InstancedMesh builds its
+     * own shader the first frame it draws (~10-20 ms of main thread), so a burst of first-seen assets
+     * is spread over frames instead of stacked into one; recycled meshes are not counted.
+     */
+    readonly freshMeshesPerUpdate?: number;
+    /**
+     * Side of the world-grid square one shared batch's records are clustered into, in world units.
+     * Defaults to the package's own `cellSize`, which is the square the placements are already cut
+     * on. Each `(key, cluster)` is its own caster InstancedMesh with its own bounds on the shadow
+     * caster layer, so a virtual-shadow level submits only the clusters its window covers. The main
+     * pass keeps one mesh per `asset:level:part` whatever this is, so it costs main-pass draws
+     * nothing. A larger square means fewer caster meshes and more of the world in every level render.
+     */
+    readonly clusterSize?: number;
+    /**
+     * Milliseconds one `update` may spend admitting streamed content — cell batches, terrain tiles,
+     * colliders and `maxDistance`/`lods` refilters together. Defaults to 2, and `Infinity` opts out
+     * of the ceiling entirely.
+     *
+     * The ceiling is a budget, not a promise: one unit of work always finishes, so a frame spends at
+     * most this plus its last unit. Work that does not fit waits for the next `update` rather than
+     * being dropped, and `stats().admission` reports what is waiting. A frame that admits nothing
+     * costs nothing here.
+     */
+    readonly admissionBudgetMs?: number;
+    /**
+     * Milliseconds source for the admission budget, `performance.now` by default. Injectable so a
+     * test can prove the ceiling instead of hoping a machine is slow enough to show it.
+     */
+    readonly admissionNow?: () => number;
+    /**
+     * The screen-space projection the extra levels of a baked AutoLOD chain are switched at, for an
+     * asset whose `world.json` entry names no `lods` of its own.
+     *
+     * A chain measures its levels' geometric error in world units and the model runtime turns that
+     * into pixels per frame; a batched draw cannot, so the same test is solved for distance once,
+     * here, and every placement beyond it draws the next level. `fovY` is the vertical field of view
+     * in degrees and `viewportHeight` the drawing-buffer height in raster pixels — a CSS height is the
+     * wrong number, exactly as it is for the model runtime.
+     *
+     * Defaults are 60° over 1080 raster rows: a desktop view, and what the switch distance is a
+     * function of. A world whose camera this class cannot see should pass its own, or a world with a
+     * narrow field of view (a telephoto gun sight) or a tall window will switch earlier than its
+     * pixels ask for. An asset with authored `lods` ignores all three numbers entirely: the package is
+     * the authority on its own shape.
+     *
+     * `maxPixelError` is the error budget, in pixels, every synthesized level is selected against, and
+     * it defaults to 4 rather than to the budget the asset's chain was registered with. The
+     * registered budget is calibrated for a `ModelLod`, which picks a level for *one* mesh from where
+     * that mesh is on screen; an instanced draw cannot, because every placement in the draw is at its
+     * own distance and the draw is one call with one geometry. The batched answer has to be solved
+     * once, for the whole key, which moves every switch distance outward by the ratio of the budgets —
+     * and a 1 px budget is calibrated for a hero object filling the screen. At 1 px a tree's switches
+     * land at 400–600 m on a 1080-row view, which on a 2 km map with a 640 m ring is past most of the
+     * resident world: the levels are all there and none of them is ever selected, which is the same
+     * full triangle bill the chain was added to remove. Four pixels puts the first switch inside the
+     * ring, where it can actually do something.
+     */
+    readonly autoLod?: {
+        readonly fovY?: number;
+        readonly viewportHeight?: number;
+        readonly maxPixelError?: number;
+    };
+    /**
+     * The GPU-driven main pass: one compute dispatch culls and LOD-selects every resident placement
+     * into a shared matrix buffer, and each main key draws its own region of it through an indirect
+     * record. The CPU keeps only the coarse per-cell visibility, so a walking camera costs no repack
+     * and no `maxDistance`/`lods` refilter.
+     *
+     * `true` by default where the backend can run it: it needs compute, storage buffers and
+     * `drawIndexedIndirect`, and a backend without them falls back to exactly this class's CPU path —
+     * a lost saving, never a wrong picture. `gpuScene: false`, `TN_GPU_SCENE=0` or `?tnGpuScene=0`
+     * turns it off, and `stats().gpuScene` and the `TN_WORLD_GPU_SCENE` line say which path a run
+     * took.
+     */
+    readonly gpuScene?: boolean;
+    /**
+     * Hold every dispatch's indirect args against the pure `cullAndSelect` reference and print the keys
+     * that disagree. `false` by default, and `TN_GPU_SCENE_VALIDATE=1` or `?tnGpuSceneValidate=1` turns
+     * it on.
+     *
+     * A readback is a queue submission and a mapped buffer, so this is a mode for answering "which key
+     * draws fewer instances than the CPU path" and never a walk to be measured with.
+     */
+    readonly gpuSceneValidate?: boolean;
+    /**
+     * Sample what the GPU actually selects in the main pass — a readback of the indirect args every
+     * 30 dispatches — and report it as `stats().gpuScene` and on the `TN_WORLD_GPU_SCENE`
+     * line. Off unless asked: the engine asks when the frame budget is on, and a validation turns it on
+     * by itself, so `TN_FRAME_BUDGET`'s `mainGpuTriangles` is the GPU-selected count and not the mesh
+     * capacity `tri=` reports. Set it explicitly when driving the world without a frame budget.
+     */
+    readonly gpuSceneTally?: boolean;
+    /**
+     * Record every GPU-dressed main batch mesh into one `BundleGroup` and replay the bundle instead of
+     * re-walking three's per-object path for each draw. Off by default: measured on machinefall's
+     * map-walk, bundles gave no CPU p50/p95 gain (the main thread is mostly idle and the frame is
+     * GPU/present bound), and `?tnBundles=0` stays the off path while `bundles: true` or
+     * `?tnBundles=1`/`TN_BUNDLES=1` turns it on. `stats().bundle` and the `TN_WORLD_BUNDLE` line say
+     * which way a run took.
+     *
+     * The render list inside a bundle is fixed when it is recorded, so a bundled mesh is never hidden:
+     * the dispatch draws zero instances for a key the camera cannot see, and an indirect draw of zero
+     * instances costs the GPU nothing. Toggling `visible` would force a re-record instead, and the
+     * shadow node's texel gate skips a bundled mesh for the same reason.
+     */
+    readonly bundles?: boolean;
+    /**
+     * Raise the LOD distance bias when the main pass is over its share of the frame's GPU budget, and
+     * decay it back toward 1 when it is comfortably under, default true.
+     *
+     * The main pass is triangle-bound: a flyover's near and mid tree levels are millions of triangles
+     * and the GPU time tracks that count. When `renderer.gpuMainMs()` — the smoothed main-pass GPU
+     * time — exceeds `mainGpuShare` of a 60 fps frame, every LOD switch is crossed earlier by
+     * multiplying the camera distance both selection paths compare by one shared multiplier, coarsening
+     * the same placements the GPU is already struggling to draw. It rises in bounded steps, never in a
+     * jump, so no level pops. `false` pins the bias at 1 for the whole run, which is byte-identical to
+     * the selection before this feature existed: `?tnAdaptiveLod=0`, `TN_ADAPTIVE_LOD=0` or
+     * `__tnAdaptiveLod = 0` also turns it off.
+     */
+    readonly adaptiveLod?: boolean;
+    /**
+     * The fraction of a frame's GPU time the main pass may take before the adaptive LOD bias rises,
+     * `(0, 1]`, default 0.5.
+     *
+     * The budget is `mainGpuShare x min(deltaTime, 1/60 s)`: the frame cap keeps the budget honest the
+     * same way the shadow refresh gate does, because the frame that draws an expensive main pass is
+     * itself long and reading its own inflated delta would let the cost it judges pass its own test.
+     * `?tnMainGpuShare=0.1`, `TN_MAIN_GPU_SHARE=0.1` or `__tnMainGpuShare = 0.1` forces adaptation on a
+     * GPU that would otherwise never exceed the share.
+     */
+    readonly mainGpuShare?: number;
+    /**
+     * Bake a whole-asset octahedral impostor for every alpha-cutout foliage asset and append it as the
+     * asset's terminal, two-triangle LOD, default false.
+     *
+     * Opt-in until the impostor casts a forest's shadow: it replaces the coarsest level the wide
+     * shadow levels draw, and its two-triangle card leaves the road and forest floor almost unshaded
+     * (PR #375 visual regression), so a default world keeps its source levels as shadow casters.
+     *
+     * The bake runs inside the render cadence — one of its sixteen views per `process` — so it costs a
+     * slice of a frame rather than a hitch, and it starts only after the asset's own model has been
+     * adopted. A seamless switch needs the impostor's atlas to cover the same cutout the source draws,
+     * so an asset whose levels carry no alpha-cutout part is never baked. `false` drops only the atlas
+     * terminal: every level the authored package and its baked chain give is kept, and the authored
+     * middle-level cutout coverage a level would otherwise be missing its foliage at is still applied.
+     */
+    readonly impostors?: boolean;
+}
+/**
+ * What the GPU actually selected in the main pass, from the scene's last landed tally.
+ *
+ * `triangles` is the GPU-selected count (`instanceCount x indexCount / 3` summed over the indirect
+ * records), never the mesh-capacity upper bound `renderer.info.render.triangles` reports, and it
+ * covers the main pass only: shadow passes are not tallied. `ageFrames` is how many dispatches have
+ * passed since those bytes were issued, so a caller never mistakes a stale sample for this frame's.
+ */
+interface IWorldCellsGpuTally {
+    readonly instances: number;
+    readonly triangles: number;
+    readonly ageFrames: number;
+}
+interface IWorldCellsStats {
+    readonly residentCells: number;
+    readonly residentKeys: readonly string[];
+    /** Placement instances the resident cells hold, before any `maxDistance` filter. */
+    readonly instances: number;
+    readonly loadsInFlight: number;
+    /** Model loads waiting for a free lane; served nearest-cell first, in admission order. */
+    readonly loadsQueued: number;
+    /**
+     * Shared batches still to be minted, plus the ones minted and not yet drawn; `0` once
+     * `prewarmed` has resolved.
+     */
+    readonly pendingPrewarm: number;
+    /** Shared batches minted by the prewarm so far, cumulative. */
+    readonly prewarmMinted: number;
+    readonly evictions: number;
+    /** Cumulative `maxDistance`/`lods` refilters performed, across every update. */
+    readonly rebuilds: number;
+    /**
+     * Cumulative refilter *passes* run, whether or not they queued a rebuild. The pass walks every
+     * resident cell, derives both distance brackets and sorts what it found, so this is what says
+     * whether a follow point standing inside the 2 m step paid for it; `rebuilds` only says whether it
+     * was worth anything. See `LEVEL_REFILTER_STEP_METRES`.
+     */
+    readonly refilters: number;
+    /**
+     * Cumulative stale cell-assets the refilter passes found, across every update. The pass walks every
+     * resident cell and gates it as a whole before it looks at one batch, so a follow point that has
+     * crossed nothing leaves this still — which is what says the walk cost brackets and comparisons and
+     * not allocations.
+     */
+    readonly refilterEntries: number;
+    /**
+     * Cumulative refilters whose rebuild held the same records and were settled without a write,
+     * clear or compaction. A rising share of `rebuilds` is a follow point crossing a cell's distance
+     * bracket rather than any placement crossing a gate.
+     */
+    readonly unchanged: number;
+    readonly failures: number;
+    /**
+     * What the main-pass cull cost, cumulative, and the evidence that a settled camera costs nothing.
+     *
+     * `frustums` is one a frame that had a perspective camera — it used to be one per main mesh, ~230
+     * of them on a 2 km walk. `windows` is how many of those meshes had to re-derive their window at
+     * all, and `repacks` how many copied records: both are 0 on a frame where the visible squares did
+     * not change and no record joined or left, which is what the two integer comparisons in
+     * `SharedBatch.cullFrom` buy.
+     */
+    readonly mainCull: {
+        readonly frustums: number;
+        readonly windows: number;
+        readonly repacks: number;
+        readonly visibleEpoch: number;
+    };
+    /**
+     * What the GPU-driven main pass is doing, and why it is not: `on` is the answer, `reason` is the
+     * one line `TN_WORLD_GPU_SCENE` printed, and `dispatches` is what the walk actually paid for its
+     * per-instance work. `mainCull.repacks` and `refilters` stay at `0` while it is on — that is the
+     * CPU work it replaced, counted by the same counters that report it when it is off. `dressed` over
+     * `meshes` is the marker line's own pair, and it is the one that says the scene has meshes to draw
+     * with: an `on` with `0` dressed is a ring the CPU path is still drawing.
+     */
+    readonly gpuScene: {
+        readonly on: boolean;
+        readonly reason: string;
+        readonly dispatches: number;
+        /** Resident source records: one per placement, shared by every part of the level it reached. */
+        readonly instances: number;
+        readonly keys: number;
+        readonly dressed: number;
+        readonly meshes: number;
+        /**
+         * Instances and triangles the GPU actually selected in the main pass, and the age of that
+         * sample in dispatches. Absent until the first tally lands, never zero: the scene's own
+         * `instances` above is what it holds, and `gpuInstances` is what the GPU drew.
+         */
+        readonly gpuInstances?: number;
+        readonly gpuTriangles?: number;
+        readonly gpuTallyAgeFrames?: number;
+    };
+    /**
+     * What the main pass's draw bundles are doing: `children` is how many GPU-dressed meshes are
+     * parented under the one `BundleGroup`, and `records` is how many times that group has been
+     * re-recorded since the world loaded.
+     *
+     * A record is a structural change and nothing else — a key minted or retired, a geometry or
+     * material swapped, or a GPU-scene buffer regrow that re-dresses its meshes. Streaming, culling and
+     * LOD do not move it, which is the whole claim: a 200-frame walk holds `records` at the number of
+     * keys that came and went, and a settled camera holds it still.
+     */
+    readonly bundle: {
+        readonly on: boolean;
+        readonly children: number;
+        readonly records: number;
+    };
+    /**
+     * The runtime impostor path: how many assets appended a terminal level, how many bakes are still
+     * queued or in flight, the triangles all terminal levels submit together — the number the whole
+     * feature exists to reduce — and the cache size: the logical colour atlas bytes held (each atlas's
+     * RGBA8 colour and normal mip chains), not every physical GPU buffer a render target may own, and
+     * the budget those bytes are enforced against.
+     */
+    readonly impostor: {
+        readonly assets: number;
+        readonly pending: number;
+        readonly atlasBytes: number;
+        readonly budgetBytes: number;
+        readonly terminalTriangles: number;
+        /**
+         * The whole-map far aggregates: one `InstancedMesh` per atlas cache key, the ORIGINAL placements
+         * they hold (`instances`), how many of those the near ring has taken back (`nearOwned`), the
+         * physical instance bytes, and how many times an aggregate's buffer has been written. Missing
+         * measurements stay absent; a settled camera holds `uploads` still.
+         */
+        readonly far: {
+            readonly aggregates: number;
+            readonly instances: number;
+            readonly live: number;
+            readonly nearOwned: number;
+            readonly bytes: number;
+            readonly uploads: number;
+        };
+    };
+    /** Cumulative rejected requests: cells skipped, instances or bytes refused, terrain retries. */
+    readonly pressure: {
+        readonly cells: number;
+        readonly instances: number;
+        readonly bytes: number;
+    };
+    /**
+     * What the last `update` spent on admitting streamed content, and what it left behind.
+     *
+     * A rising `backlog` is the honest signal that admission is not keeping up with the follow point;
+     * it is the one number that says a player is outrunning the world.
+     */
+    readonly admission: {
+        /** Milliseconds the last `update` spent admitting; at most the budget plus its last unit. */
+        readonly spentMs: number;
+        /** Cell-asset builds the last `update` had no budget for, still queued for a later one. */
+        readonly deferred: number;
+        /** Units of work those builds still owe — placement slices left plus meshes left to publish. */
+        readonly backlog: number;
+    };
+}
+/**
+ * A plain `{ min, max }` region, the shape a shadow level's invalidation reads and the shape a game
+ * can be handed without importing three. Plain numbers, so the object a caller records its bounds
+ * in is the object that crosses the boundary.
+ */
+interface IShadowRegion {
+    min: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/**
+ * Stream a Blender-authored world package by cell and keep it resident around a followed point.
+ *
+ * The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per
+ * resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through
+ * `loadAll` + `addInSlices`. Ring residency, per-asset `maxDistance` filtering, the per-asset `lods`
+ * levels, hard budgets and generation-tokened cancellation all live here; every geometry, material
+ * and surface still comes from the package's GLBs and the game.
+ *
+ * An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch`
+ * each, and a scattered part whose own material is transparent draws as an alpha cutout unless the
+ * game asks for blending, because an `InstancedMesh` cannot sort its instances.
+ *
+ * An asset whose package entry names no `lods` is drawn at the levels its own model carries a baked
+ * AutoLOD chain for: the levels an instanced draw cannot reach by itself, switched at the distance
+ * their error projects over the `autoLod` viewport. Authored `lods` win; a chain is only a fallback.
+ *
+ * @situation stream a large Blender-authored world by cell instead of one huge GLB
+ * @situation keep scattered props and hand-placed chunks resident around a moving player
+ * @situation honour per-asset draw distances and hard streaming budgets without a mid-frame throw
+ * @constraint surface is the game's; this class creates no material, colour or geometry
+ * @constraint budgets are hard caps that report pressure instead of over-committing
+ * @constraint model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell
+ * @constraint refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first
+ * @constraint admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has
+ * @constraint SkinnedMesh parts are skipped; an instanced copy would draw one rest pose
+ * @constraint a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with authored `lods` never consults it
+ * @override ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
+ * @constraint `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number
+ * @constraint every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers
+ * @constraint two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct
+ * @constraint the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds
+ * @constraint a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left
+ * @constraint `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
+ * @example
+ * const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
+ * scene.add(world);
+ * world.update();
+ */
+declare class WorldCells extends Group implements IComputeDriven {
+    #private;
+    readonly processCadence: "render";
+    private constructor();
+    static load(options: IWorldCellsLoadOptions): Promise<WorldCells>;
+    get released(): boolean;
+    get warmupNodes(): readonly unknown[];
+    /**
+     * Resolves once every minted batch has been drawn at least once, main and shadow context.
+     *
+     * The loading gate a game with a loading screen waits on, so the shader builds the prewarm exists
+     * to move happen behind it instead of in the first seconds of play. It counts updates the world
+     * was in a scene for, because a batch added while the world is not in a scene is projected by
+     * nothing and builds nothing. `dispose` settles it too: a world torn down mid-load must not leave
+     * a game awaiting it forever.
+     */
+    get prewarmed(): Promise<void>;
+    /**
+     * Per-frame residency step; call it wherever `TerrainTiles.process` is called.
+     *
+     * Reads the follow target, keeps the in-ring cells, evicts cells beyond the hysteresis ring, and
+     * spends one admission budget on everything the ring newly wants: cell-asset batches, terrain
+     * tiles, colliders and the `maxDistance`/`lods` refilters the follow point has moved far enough to
+     * have changed. Whatever does not fit waits for the next call — nothing is dropped, and
+     * `stats().admission` is the honest report of what is waiting. A terrain budget throw is caught
+     * and counted, and so is a teardown that throws while releasing what left; `failures` carries
+     * both. Every other error, the game's included, escapes.
+     *
+     * The residency pass itself is skipped while the follow point has moved less than half a metre
+     * since the last one and nothing is pending (a load, a cell build, a deferred terrain admission, a
+     * prewarm mint or a shadow level not yet told), because the pass would re-derive the set the
+     * world already holds. The drain, the prewarm, the invalidation and the main cull below it run
+     * every time.
+     *
+     * `camera` is the frame's render camera, which the engine's render-cadence dispatch hands over
+     * because it is the one this world draws with. A game that drives this world itself can pass it,
+     * and a game that does not keeps every resident record drawn.
+     */
+    update(renderer?: IRendererLike, camera?: Camera): void;
+    /**
+     * The render-cadence dispatch. The engine hands the frame's render camera over, and this world's
+     * main windows follow it; see {@link #cullMainPass} for why the decision is not the meshes' own.
+     */
+    process(renderer?: IRendererLike, camera?: Camera): void;
+    attachRenderer(renderer: IRendererLike): void;
+    /** Current per-asset reference count; an asset absent from the map is `0`. */
+    assetRefCounts(): Readonly<Record<string, number>>;
+    /**
+     * Turn on the GPU-selected tally for the rest of the world's life.
+     *
+     * The engine calls this when the frame budget is on, and a `gpuSceneValidate` turns it on without
+     * it. Set `gpuSceneTally: true` at load instead when a world is driven outside a frame budget.
+     */
+    enableGpuSceneTally(): void;
+    /**
+     * The GPU's own main-pass selection from the last landed tally, or `undefined` before one lands.
+     *
+     * `triangles` is the GPU-selected count, which `renderer.info.render.triangles` cannot give for an
+     * indirect draw: three counts the mesh capacity there, an upper bound over what the kernel could
+     * select. This is what the kernel selected. Main pass only, and `ageFrames` is its staleness.
+     */
+    gpuSceneTally(): IWorldCellsGpuTally | undefined;
+    stats(): IWorldCellsStats;
+    detach(): void;
+    dispose(): void;
+}
+
 interface IHeightfieldOrigin {
     readonly x: number;
     readonly z: number;
@@ -251,4 +1137,4 @@ declare class Heightfield extends Group implements IComputeDriven {
     toGeometry(): BufferGeometry;
 }
 
-export { Heightfield, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type IWorldCapabilities, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, TerrainTiles, getWorldCapabilities };
+export { Heightfield, type IAdmissionBudget, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type ILoadTerrainSplatOptions, type IShadowRegion, type ITerrainSplatLayer, type ITerrainSplatMaskedLayer, type ITerrainSplatTable, type IWorldAsset, type IWorldAssetBounds, type IWorldAssetLod, type IWorldCapabilities, type IWorldCell, type IWorldCellsBudget, type IWorldCellsFollow, type IWorldCellsLoadOptions, type IWorldCellsStats, type IWorldCellsTerrainOptions, type IWorldExtent, type IWorldPackage, type IWorldPackageError, type IWorldPackageValidationOptions, type IWorldRun, type IWorldTerrain, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, TERRAIN_VALIDATE_FLAG, TERRAIN_VALIDATE_MARKER, TerrainTiles, WorldCells, type WorldPackageErrorCode, cellPlacements, getWorldCapabilities, heightSamplerFromHeightmap, loadTerrainSplat, loadWorldHeightmap, terrainValidationRequested, validateWorldPackage };