@driftengine/core 3.63.0 → 4.0.0

package/dist/render/gpudriven/shadowCamera.d.ts

@@ -0,0 +1,87 @@
+/** Where the second pipeline's light stands, and the two corrections its map needs. */
+/**
+ * A bounding sphere over every cluster, from the world bounds the cull buffer already holds.
+ *
+ * **It reads the transformed bounds rather than transforming them itself**, which it did until
+ * 2026-09-17 and which was one of two places in this pipeline that multiplied a cluster by its
+ * mesh's matrix. `clusterWorld.ts` is the other and is now the only one: two copies of that
+ * arithmetic can disagree about the scale a sphere takes, and a light's box that disagrees with the
+ * cull's bounds clips casters out of a map that the cull believes are in it — which is a surface
+ * lit with something standing in front of it.
+ *
+ * `stride` is how many floats a cluster occupies; `CLUSTER_CULL_FLOATS` for the cull buffer, where
+ * the centre and radius are the first four of eight.
+ *
+ * `out` is the centre and the radius, four floats.
+ */
+export declare function sceneShadowBounds(
+/** Centre and radius, four floats at every `stride`, in world space. */
+bounds: Float32Array, stride: number, count: number, out: Float32Array): Float32Array;
+export declare function fitDirectionalShadow(centre: ArrayLike<number>, radius: number, lightDir: readonly [number, number, number], out: Float32Array): number;
+/**
+ * **The map for a frame: the whole scene while it fits inside `follow` metres, and a sphere of that
+ * radius around the eye once it does not.**
+ *
+ * The scene fit is right for what this pipeline was first given — rigs a few metres across, a box
+ * that never moves and so never shimmers — and wrong for a world, which is what the voxel
+ * sandbox's port made this pipeline draw: at radius 14 its sphere is hundreds of metres across and
+ * a 2048 map over it has texels a quarter of a metre wide. So past a radius the caller names, the
+ * map follows the eye, as the forward path's does in `lightMatrix.ts`. **At or under it nothing
+ * changes, to the bit**, and with no radius at all nothing ever does — which is what keeps the three
+ * rigs the control rather than a second fit's first customer.
+ *
+ * **Why the scene's size rather than whether the eye is inside it**: a fit that switched as the eye
+ * crossed a boundary would jump the whole map between two scales mid-walk, where a scene grows past
+ * the radius once and stays there.
+ *
+ * `sphere` is the scene's centre and radius, four floats, as `sceneShadowBounds` writes them.
+ * Returns the metres the depth range spans, which the lookup multiplies a stored difference by.
+ */
+export declare function fitShadow(sphere: ArrayLike<number>, eye: ArrayLike<number>, follow: number | undefined, lightDir: readonly [number, number, number], mapSize: number, out: Float32Array): number;
+/**
+ * **Two corrections, and the difference is one negated row.**
+ *
+ * The lookup wants the light-space position with `x` and `y` still in -1..1 — it remaps those
+ * itself — and `z` already in the 0..1 WebGPU clips to. That is `SHADOW_LOOKUP_CORRECTION`, and it
+ * is `SHADOW_CLIP_CORRECTION` in `webgpu/renderer.ts` under another name, for the same reason: a
+ * map is sampled rather than presented.
+ *
+ * The raster wants the same depth and the **opposite rows**, and this is the part that is easy to
+ * get backwards. A generated vertex stage ends with `gl_Position.y = -gl_Position.y`, which naga
+ * writes and nothing here does — so the forward path's shadow pass is handed the unflipped matrix
+ * and emits a flipped picture, while a hand-written stage handed the same matrix emits an unflipped
+ * one and stores every row at the mirror of where the lookup goes looking. Flipping it here is what
+ * puts the two pipelines' maps in the same orientation, so one lookup can read either.
+ *
+ * **And the flip reverses the winding with it**, which is why the pipeline that uses this declares
+ * `frontFace: 'cw'` — the same pair `depthPass.ts` carries, arrived at from the other side.
+ *
+ * Neither reverses depth. `depthConvention.ts` leaves shadow maps conventional, so the row is
+ * `0.5z + 0.5` where the frame's is `0.5 - 0.5z`, and the pass that renders one clears to
+ * `SHADOW_DEPTH_CLEAR` and compares with `less`.
+ */
+export declare const SHADOW_LOOKUP_CORRECTION: Float32Array<ArrayBuffer>;
+export declare const SHADOW_RASTER_CORRECTION: Float32Array<ArrayBuffer>;
+/**
+ * How far toward the light the light's cone test stands its eye, in metres.
+ *
+ * **A directional light has no eye, and the cone test wants one.** Stood this far toward the sun,
+ * every direction from the eye to a cluster in the map is the sun's own to within the cluster's
+ * distance from the camera over this — three hundred-thousandths of a radian across a city three
+ * kilometres wide — so the perspective test answers the directional one the map's raster applies
+ * when it culls the faces turned from the light. A triangle it could cull wrongly is that close to
+ * edge-on to the sun, and covers a thousandth of a texel of any map. In `float32` the eye is good
+ * to eight metres of the hundred million, which moves the direction by less again.
+ */
+export declare const LIGHT_CONE_DISTANCE = 100000000;
+/** The eye the light's cone test reads: `eye` moved `LIGHT_CONE_DISTANCE` toward the light. */
+export declare function lightConeEye(eye: ArrayLike<number>, lightDir: ArrayLike<number>, out: [number, number, number]): [number, number, number];
+/**
+ * The raster's matrix with its depth turned over, `1 - z`, and nothing else moved: what the light's
+ * cull projects a cluster through, because the light's pyramid is stored turned over
+ * (`shadowPyramidBase`) so the camera's cull and reduction can read it. Applied after
+ * `SHADOW_RASTER_CORRECTION`, so the rows are the raster's, which are the map's and the pyramid's.
+ */
+export declare const SHADOW_CULL_CORRECTION: Float32Array<ArrayBuffer>;
+/** `out = correction · light`, column-major. */
+export declare function correctShadowMatrix(correction: Float32Array, light: Float32Array, out: Float32Array): Float32Array;

package/dist/render/gpudriven/shadowCamera.js

@@ -0,0 +1,345 @@
+/** Where the second pipeline's light stands, and the two corrections its map needs. */
+/**
+ * **The light's projection, fitted to the scene's bounding sphere rather than the camera.**
+ *
+ * The forward path fits a cascade to the *view* frustum, which is what a large world wants: the map
+ * follows the camera and spends its texels where the viewer is. It also costs that path a snapping
+ * rule, because a box that moves continuously makes every shadow edge crawl as the camera turns.
+ *
+ * This one fitted the whole scene, and still does while the scene is no larger than the radius a
+ * caller names: its rigs are a few metres across, so a sphere around the lot is a box that never
+ * moves and therefore never shimmers. **What that gave up was stated rather than discovered** — a
+ * world too big for one map gets a soft, coarse shadow everywhere — and a world arrived: the voxel
+ * sandbox's port. So past that radius `fitShadow` follows the eye instead, snapped as the forward
+ * path's cascade is. One sphere rather than a cascade of them: `docs/CAPABILITIES.md` records what
+ * that costs at a distance.
+ *
+ * **A sphere rather than an eight-corner box**, because a box's extent in light space depends on
+ * the sun's direction and a sphere's does not — so the fit is the same size at every hour, and a
+ * shadow that grows softer as the sun moves is the sun moving rather than the fit breathing.
+ */
+import { SHADOW_DEPTH_FADE } from './shadow.js';
+/** Where the basis stops taking `y` as its reference. Any sun steeper than this is overhead. */
+const OVERHEAD = 0.99;
+/**
+ * A bounding sphere over every cluster, from the world bounds the cull buffer already holds.
+ *
+ * **It reads the transformed bounds rather than transforming them itself**, which it did until
+ * 2026-09-17 and which was one of two places in this pipeline that multiplied a cluster by its
+ * mesh's matrix. `clusterWorld.ts` is the other and is now the only one: two copies of that
+ * arithmetic can disagree about the scale a sphere takes, and a light's box that disagrees with the
+ * cull's bounds clips casters out of a map that the cull believes are in it — which is a surface
+ * lit with something standing in front of it.
+ *
+ * `stride` is how many floats a cluster occupies; `CLUSTER_CULL_FLOATS` for the cull buffer, where
+ * the centre and radius are the first four of eight.
+ *
+ * `out` is the centre and the radius, four floats.
+ */
+export function sceneShadowBounds(
+/** Centre and radius, four floats at every `stride`, in world space. */
+bounds, stride, count, out) {
+    let lowX = Infinity;
+    let lowY = Infinity;
+    let lowZ = Infinity;
+    let highX = -Infinity;
+    let highY = -Infinity;
+    let highZ = -Infinity;
+    for (let c = 0; c < count; c += 1) {
+        const at = c * stride;
+        const cx = bounds[at];
+        const cy = bounds[at + 1];
+        const cz = bounds[at + 2];
+        const radius = bounds[at + 3];
+        /*
+         * **A record of no radius is a slot nobody holds, not a cluster at the origin.** A streaming
+         * scene's buffers are sized by capacity, so the records past what is live are zeros — and
+         * counting them stretches this box all the way back to the origin over empty space, which puts
+         * the light's whole depth range across a volume that is mostly nothing. A static scene has no
+         * such records and is unaffected: a baked cluster always has a positive radius.
+         */
+        if (!(radius > 0))
+            continue;
+        lowX = Math.min(lowX, cx - radius);
+        lowY = Math.min(lowY, cy - radius);
+        lowZ = Math.min(lowZ, cz - radius);
+        highX = Math.max(highX, cx + radius);
+        highY = Math.max(highY, cy + radius);
+        highZ = Math.max(highZ, cz + radius);
+    }
+    if (!Number.isFinite(lowX)) {
+        /*
+         * **A scene with no clusters is a unit sphere, not a point.** A radius of zero divides by zero
+         * in the fit below and every entry of the matrix comes back NaN — which reaches the device as
+         * a draw that covers nothing and a lookup that is never inside the map, so the frame is simply
+         * unshadowed and nothing says why.
+         */
+        out[0] = 0;
+        out[1] = 0;
+        out[2] = 0;
+        out[3] = 1;
+        return out;
+    }
+    out[0] = (lowX + highX) * 0.5;
+    out[1] = (lowY + highY) * 0.5;
+    out[2] = (lowZ + highZ) * 0.5;
+    out[3] = Math.max(Math.hypot(highX - lowX, highY - lowY, highZ - lowZ) * 0.5, 
+    /* Never zero, for the reason above: one flat quad is a legal scene. */
+    1e-3);
+    return out;
+}
+/**
+ * The light's view-projection, in the OpenGL convention the rest of this engine builds matrices in:
+ * `x` and `y` in -1..1 and `z` in -1..1 as well. Returns the metres its depth range spans.
+ *
+ * **Written out rather than composed from a look-at and an orthographic**, because the product is
+ * four lines and the two halves are not independently useful. The whole of it is: project onto the
+ * light's basis, divide by the radius, and negate the depth axis so that *nearer the light* is
+ * smaller — which is the direction a depth test with `less` wants and is the opposite of the
+ * frame's reversed depth. `depthConvention.ts` carries why shadows are not reversed.
+ *
+ * `lightDir` points **toward** the light, as `Environment.directionalDir` does.
+ */
+/** The light's right, up and toward-the-light axes, nine numbers. See `lightBasis`. */
+const BASIS = new Float64Array(9);
+/**
+ * The light's three axes, which depend on its direction and on nothing else.
+ *
+ * **One basis for both fits, and the following fit needs it to be exactly this.** Snapping a map
+ * to whole texels only holds its edges still if the texel grid it snaps to is fixed, and the grid
+ * is this basis: `lightMatrix.ts` says the same about the forward path's, where anchoring the light
+ * at the focus instead would move light space under the snap and cancel it.
+ */
+function lightBasis(lightDir, out) {
+    const length = Math.hypot(lightDir[0], lightDir[1], lightDir[2]) || 1;
+    const ax = lightDir[0] / length;
+    const ay = lightDir[1] / length;
+    const az = lightDir[2] / length;
+    /*
+     * **The reference direction moves when the sun is overhead, and a sun overhead is the common
+     * case.** `cross(up, axis)` collapses as the two line up, so a light within a degree of straight
+     * down produces a basis of denormals and a map that is mostly one texel. Noon is not an edge
+     * case in a day cycle.
+     */
+    const upX = Math.abs(ay) > OVERHEAD ? 0 : 0;
+    const upY = Math.abs(ay) > OVERHEAD ? 0 : 1;
+    const upZ = Math.abs(ay) > OVERHEAD ? 1 : 0;
+    let rx = upY * az - upZ * ay;
+    let ry = upZ * ax - upX * az;
+    let rz = upX * ay - upY * ax;
+    const rLength = Math.hypot(rx, ry, rz) || 1;
+    rx /= rLength;
+    ry /= rLength;
+    rz /= rLength;
+    /* The third axis is the cross of the other two, so the basis is orthonormal by construction. */
+    out[0] = rx;
+    out[1] = ry;
+    out[2] = rz;
+    out[3] = ay * rz - az * ry;
+    out[4] = az * rx - ax * rz;
+    out[5] = ax * ry - ay * rx;
+    out[6] = ax;
+    out[7] = ay;
+    out[8] = az;
+}
+export function fitDirectionalShadow(centre, radius, lightDir, out) {
+    lightBasis(lightDir, BASIS);
+    const rx = BASIS[0];
+    const ry = BASIS[1];
+    const rz = BASIS[2];
+    const ux = BASIS[3];
+    const uy = BASIS[4];
+    const uz = BASIS[5];
+    const ax = BASIS[6];
+    const ay = BASIS[7];
+    const az = BASIS[8];
+    const scale = 1 / Math.max(radius, 1e-6);
+    const put = (column, x, y, z) => {
+        out[column * 4] = x;
+        out[column * 4 + 1] = y;
+        out[column * 4 + 2] = z;
+        out[column * 4 + 3] = 0;
+    };
+    /* Rows are the basis and columns are the axes: row 0 is the light's right, row 2 its depth. */
+    put(0, rx * scale, ux * scale, -ax * scale);
+    put(1, ry * scale, uy * scale, -ay * scale);
+    put(2, rz * scale, uz * scale, -az * scale);
+    const dot = (x, y, z) => x * centre[0] + y * centre[1] + z * centre[2];
+    out[12] = -dot(rx, ry, rz) * scale;
+    out[13] = -dot(ux, uy, uz) * scale;
+    /* Positive, because the depth row is already negated: the centre of the scene lands at zero. */
+    out[14] = dot(ax, ay, az) * scale;
+    out[15] = 1;
+    /* The box is a diameter deep, which is what turns a stored depth difference into metres. */
+    return 2 * Math.max(radius, 1e-6);
+}
+/**
+ * **The map for a frame: the whole scene while it fits inside `follow` metres, and a sphere of that
+ * radius around the eye once it does not.**
+ *
+ * The scene fit is right for what this pipeline was first given — rigs a few metres across, a box
+ * that never moves and so never shimmers — and wrong for a world, which is what the voxel
+ * sandbox's port made this pipeline draw: at radius 14 its sphere is hundreds of metres across and
+ * a 2048 map over it has texels a quarter of a metre wide. So past a radius the caller names, the
+ * map follows the eye, as the forward path's does in `lightMatrix.ts`. **At or under it nothing
+ * changes, to the bit**, and with no radius at all nothing ever does — which is what keeps the three
+ * rigs the control rather than a second fit's first customer.
+ *
+ * **Why the scene's size rather than whether the eye is inside it**: a fit that switched as the eye
+ * crossed a boundary would jump the whole map between two scales mid-walk, where a scene grows past
+ * the radius once and stays there.
+ *
+ * `sphere` is the scene's centre and radius, four floats, as `sceneShadowBounds` writes them.
+ * Returns the metres the depth range spans, which the lookup multiplies a stored difference by.
+ */
+export function fitShadow(sphere, eye, follow, lightDir, mapSize, out) {
+    const radius = sphere[3];
+    /* No radius is an infinite one: a scene is never larger, so the fit never follows. */
+    if (!(radius > (follow ?? Infinity))) {
+        return fitDirectionalShadow(sphere, radius, lightDir, out);
+    }
+    return fitFollowingShadow(eye, follow, sphere, lightDir, mapSize, out);
+}
+/**
+ * A sphere of `radius` around `focus`, **snapped to whole texels of a fixed light space**, and deep
+ * enough toward the light to hold every caster the scene has there.
+ *
+ * **Snapped, or every edge crawls.** The basis is the light's alone, so the grid is fixed; the
+ * focus's three light-space coordinates are rounded to it, and the map moves in whole texels or not
+ * at all. A world point then falls in the same texel until the map steps, rather than at a new
+ * sub-texel offset every frame.
+ *
+ * **Deep enough toward the sun for every caster.** A receiver is inside the sphere, and anything
+ * that shadows one lies between it and the light — so the range reaches toward the light as far as
+ * the scene's own far side, which is where the last possible caster is. `lightMatrix.ts` reaches
+ * three radii; a dusk sun over a city casts a tower's shadow further than that, and the scene's
+ * sphere is known exactly here. **The reach is rounded up to whole radii**, so it changes only when
+ * the eye has walked a radius along the light rather than rescaling every stored depth each frame.
+ *
+ * **And symmetric about the eye, which is not for casters but for the lookup.** The lookup gives
+ * up on the last stretch of stored depth, `SHADOW_DEPTH_FADE`, because in the scene fit that is the
+ * scene's far rim. The first version of this reached only a radius away from the sun, which put
+ * every receiver in that stretch — the ground below the eye came out less shadowed the further
+ * below it was, and the sphere's far side not at all. Symmetric, a receiver at most a radius from
+ * the eye is stored within `radius / reach` of the middle, and the least reach is the whole number
+ * of radii that keeps that short of the fade.
+ */
+function fitFollowingShadow(focus, radius, sphere, lightDir, mapSize, out) {
+    lightBasis(lightDir, BASIS);
+    const rx = BASIS[0];
+    const ry = BASIS[1];
+    const rz = BASIS[2];
+    const ux = BASIS[3];
+    const uy = BASIS[4];
+    const uz = BASIS[5];
+    const ax = BASIS[6];
+    const ay = BASIS[7];
+    const az = BASIS[8];
+    const fx = focus[0];
+    const fy = focus[1];
+    const fz = focus[2];
+    const texel = (2 * radius) / Math.max(1, mapSize);
+    const across = Math.round((rx * fx + ry * fy + rz * fz) / texel) * texel;
+    const up = Math.round((ux * fx + uy * fy + uz * fz) / texel) * texel;
+    const along = Math.round((ax * fx + ay * fy + az * fz) / texel) * texel;
+    const farSide = ax * sphere[0] +
+        ay * sphere[1] +
+        az * sphere[2] +
+        sphere[3];
+    /*
+     * A receiver a radius from the eye is stored at 0.5 + radius / (2 reach); keeping that below the
+     * fade's start needs reach >= radius / (2 (start - 0.5)), which is 1.25 radii and so two.
+     */
+    const least = Math.ceil(1 / (2 * (SHADOW_DEPTH_FADE[0] - 0.5)));
+    const reach = radius * Math.max(least, Math.ceil((farSide - along) / radius));
+    const scale = 1 / radius;
+    const depth = 1 / reach;
+    const put = (column, x, y, z) => {
+        out[column * 4] = x;
+        out[column * 4 + 1] = y;
+        out[column * 4 + 2] = z;
+        out[column * 4 + 3] = 0;
+    };
+    put(0, rx * scale, ux * scale, -ax * depth);
+    put(1, ry * scale, uy * scale, -ay * depth);
+    put(2, rz * scale, uz * scale, -az * depth);
+    out[12] = -across * scale;
+    out[13] = -up * scale;
+    /* Nearer the light is smaller, as in the scene fit: the sunward end lands at -1. */
+    out[14] = along * depth;
+    out[15] = 1;
+    return 2 * reach;
+}
+/**
+ * **Two corrections, and the difference is one negated row.**
+ *
+ * The lookup wants the light-space position with `x` and `y` still in -1..1 — it remaps those
+ * itself — and `z` already in the 0..1 WebGPU clips to. That is `SHADOW_LOOKUP_CORRECTION`, and it
+ * is `SHADOW_CLIP_CORRECTION` in `webgpu/renderer.ts` under another name, for the same reason: a
+ * map is sampled rather than presented.
+ *
+ * The raster wants the same depth and the **opposite rows**, and this is the part that is easy to
+ * get backwards. A generated vertex stage ends with `gl_Position.y = -gl_Position.y`, which naga
+ * writes and nothing here does — so the forward path's shadow pass is handed the unflipped matrix
+ * and emits a flipped picture, while a hand-written stage handed the same matrix emits an unflipped
+ * one and stores every row at the mirror of where the lookup goes looking. Flipping it here is what
+ * puts the two pipelines' maps in the same orientation, so one lookup can read either.
+ *
+ * **And the flip reverses the winding with it**, which is why the pipeline that uses this declares
+ * `frontFace: 'cw'` — the same pair `depthPass.ts` carries, arrived at from the other side.
+ *
+ * Neither reverses depth. `depthConvention.ts` leaves shadow maps conventional, so the row is
+ * `0.5z + 0.5` where the frame's is `0.5 - 0.5z`, and the pass that renders one clears to
+ * `SHADOW_DEPTH_CLEAR` and compares with `less`.
+ */
+export const SHADOW_LOOKUP_CORRECTION = new Float32Array([
+    1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0.5, 1,
+]);
+export const SHADOW_RASTER_CORRECTION = new Float32Array([
+    1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0.5, 1,
+]);
+/**
+ * How far toward the light the light's cone test stands its eye, in metres.
+ *
+ * **A directional light has no eye, and the cone test wants one.** Stood this far toward the sun,
+ * every direction from the eye to a cluster in the map is the sun's own to within the cluster's
+ * distance from the camera over this — three hundred-thousandths of a radian across a city three
+ * kilometres wide — so the perspective test answers the directional one the map's raster applies
+ * when it culls the faces turned from the light. A triangle it could cull wrongly is that close to
+ * edge-on to the sun, and covers a thousandth of a texel of any map. In `float32` the eye is good
+ * to eight metres of the hundred million, which moves the direction by less again.
+ */
+export const LIGHT_CONE_DISTANCE = 1e8;
+/** The eye the light's cone test reads: `eye` moved `LIGHT_CONE_DISTANCE` toward the light. */
+export function lightConeEye(eye, lightDir, out) {
+    const x = lightDir[0];
+    const y = lightDir[1];
+    const z = lightDir[2];
+    const scale = LIGHT_CONE_DISTANCE / (Math.hypot(x, y, z) || 1);
+    out[0] = eye[0] + x * scale;
+    out[1] = eye[1] + y * scale;
+    out[2] = eye[2] + z * scale;
+    return out;
+}
+/**
+ * The raster's matrix with its depth turned over, `1 - z`, and nothing else moved: what the light's
+ * cull projects a cluster through, because the light's pyramid is stored turned over
+ * (`shadowPyramidBase`) so the camera's cull and reduction can read it. Applied after
+ * `SHADOW_RASTER_CORRECTION`, so the rows are the raster's, which are the map's and the pyramid's.
+ */
+export const SHADOW_CULL_CORRECTION = new Float32Array([
+    1, 0, 0, 0, 0, 1, 0, 0, 0, 0, -1, 0, 0, 0, 1, 1,
+]);
+/** `out = correction · light`, column-major. */
+export function correctShadowMatrix(correction, light, out) {
+    for (let column = 0; column < 4; column += 1) {
+        for (let row = 0; row < 4; row += 1) {
+            let sum = 0;
+            for (let k = 0; k < 4; k += 1) {
+                sum += correction[k * 4 + row] * light[column * 4 + k];
+            }
+            out[column * 4 + row] = sum;
+        }
+    }
+    return out;
+}

package/dist/render/gpudriven/streamScene.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The frame's geometry, which arrives and leaves while the frame loop runs.
+ *
+ * **`GpuDrivenPass` uploaded its scene in a method called `buildStatic`**, and its constructor said
+ * why: this pipeline's geometry does not move. A voxel world streams chunks as a player walks and
+ * remeshes one on every block they break, so it has to.
+ *
+ * **Four `RangeAlloc`s over what the pass binds**: six arrays the scene keeps — the cluster and
+ * mesh records a frame's culling reads — and two it never keeps. The vertices and the indices go
+ * through a `GeometrySink` straight into the device's buffers when a mesh is placed, because
+ * holding them as well doubled what a world costs, and at the voxel sandbox's radius 32 the copy
+ * was an ArrayBuffer Chrome will not allocate. A mesh claims a run of each, writes its rows, and
+ * hands the runs back when it leaves.
+ *
+ * **One path, not two.** The static case is a scene filled once and never emptied — `streamingScene`
+ * is that, and it is what every caller of `buildGpuDrivenScene` plus `new GpuDrivenPass` becomes.
+ * Two paths would mean the three rigs in `DRAFT_SCENES` exercise the path no published scene uses,
+ * which is how a control stops being a control; `streamScene.test.ts` asserts this class packs a
+ * static scene byte for byte where `buildGpuDrivenScene` packed it.
+ *
+ * **`add` allocates only when a mesh larger than any before it arrives**, because it is called
+ * from a frame loop when a player walks: the scratch it interleaves into grows to the largest mesh
+ * and is reused. A scene filled before its pass mounts is the exception, and it is the static
+ * case: it holds each mesh until the pass attaches, and nothing after. `heldBytes` says which.
+ */
+import type { GpuDrivenMesh } from './sceneUpload.ts';
+/** How many units of each axis a scene may hold. Declared once; a claim past it is refused. */
+export interface StreamCapacity {
+    readonly vertices: number;
+    readonly indices: number;
+    readonly clusters: number;
+    readonly meshes: number;
+}
+/** What `add` hands back, and what `remove` needs to give the room back. */
+export interface StreamHandle {
+    readonly mesh: number;
+    readonly vertexBase: number;
+    readonly vertexCount: number;
+    readonly indexBase: number;
+    readonly indexCount: number;
+    readonly clusterBase: number;
+    readonly clusterCount: number;
+}
+/** One buffer's changed run, in units of that buffer's record. */
+export interface DirtySpan {
+    readonly from: number;
+    readonly to: number;
+}
+export interface StreamUpload {
+    readonly clusters: readonly DirtySpan[];
+    readonly meshes: readonly DirtySpan[];
+}
+/**
+ * Where a scene's vertices and indices go, since it keeps no copy of them.
+ *
+ * **Handed a scratch array, and a sink must copy it before returning.** `rows` and `values` may be
+ * longer than `count` records: the scene interleaves every mesh into the same two arrays and
+ * reuses them on the next add, which is what keeps `add` from allocating in a frame loop.
+ * `queue.writeBuffer` copies when it is called, so `GpuDrivenPass` hands them straight on.
+ */
+export interface GeometrySink {
+    /** `count` vertices of twelve floats each, from the start of `rows`, placed at `firstVertex`. */
+    writeVertices(firstVertex: number, rows: Float32Array, count: number): void;
+    /** `count` indices from the start of `values`, already rebased onto the scene, at `firstIndex`. */
+    writeIndices(firstIndex: number, values: Uint32Array, count: number): void;
+}
+export declare class StreamingScene {
+    readonly capacity: StreamCapacity;
+    /** Eight floats a cluster: world centre, radius, cone axis, cutoff. */
+    readonly cull: Float32Array;
+    /** Six floats a cluster: world centre, radius, own error, parent error. */
+    readonly lod: Float32Array;
+    /** Four words a cluster: index offset, index count, cluster id, mesh index. */
+    readonly meta: Uint32Array;
+    readonly materialOf: Uint32Array;
+    readonly transforms: Float32Array;
+    readonly instanceSpheres: Float32Array;
+    private readonly vertexAlloc;
+    private readonly indexAlloc;
+    private readonly clusterAlloc;
+    private readonly meshAlloc;
+    private readonly dirtyClusters;
+    private readonly dirtyMeshes;
+    /**
+     * Scratch `worldClustersInto` needs, sized once.
+     *
+     * It wants `bounds` as four floats a cluster — centre and radius together — and `cones` as four,
+     * where a `ClusterSource` keeps `boundsCentre` / `boundsRadius` and `coneAxis` / `coneCutoff` as
+     * separate arrays. Packing them is a copy a frame loop must not allocate for.
+     */
+    private readonly boundScratch;
+    private readonly coneScratch;
+    private readonly errorScratch;
+    private readonly meshScratch;
+    private live;
+    /**
+     * **Where the geometry is.** Held a mesh at a time until a pass attaches (`staging`), written
+     * straight to that pass's buffers (`attached`), or nowhere once the pass has gone (`spent`).
+     */
+    private state;
+    private sink;
+    private readonly staged;
+    private rowScratch;
+    private indexScratch;
+    private waiting;
+    private waitingCount;
+    constructor(capacity: StreamCapacity);
+    /** How many clusters currently draw. A removed cluster's slot is still allocated until released. */
+    get liveClusters(): number;
+    /** Room left on each axis, which `scripts/stream-fragmentation.mjs` and its tests read. */
+    get freeVertices(): number;
+    /** The worst each axis ever reached, which is the occupancy a fragmentation run reports. */
+    get highWater(): StreamCapacity;
+    /**
+     * The geometry this scene holds on the CPU, in bytes: what is staged for a pass that has not
+     * attached, and the two scratch arrays an attached scene interleaves through. **Nothing past
+     * that** — which is the whole of what `GeometrySink` is for, as a number a test and a readout can
+     * read.
+     */
+    get heldBytes(): number;
+    /**
+     * Give the scene the one place its geometry goes, and send it everything staged so far.
+     *
+     * **Once, and a second time is refused by name.** The scene keeps no copy of what it has sent,
+     * so a second pass would bind two empty buffers and draw nothing — silently, which is the one
+     * answer this cannot give. The dirty journal already made a scene one pass's: two passes would
+     * each take its spans and each miss the other's.
+     */
+    attach(sink: GeometrySink): void;
+    /**
+     * The pass has gone. Adds and removes still keep the records, and the geometry goes nowhere.
+     *
+     * **Called by `GpuDrivenPass.dispose` before it destroys its buffers**, because a write to a
+     * destroyed buffer is a device error; and nothing waits after it, because nothing reads.
+     */
+    detach(): void;
+    /**
+     * Place a mesh, or refuse.
+     *
+     * **Every claim before any write, and a rollback if the last one fails.** A partial add is a mesh
+     * whose clusters point at vertices another mesh owns, which draws somebody else's geometry rather
+     * than failing — the shape of mistake `packClusters` documents one level up.
+     *
+     * **`null` rather than an exception**, because a streaming consumer calls this from a frame loop
+     * when the player walks: an exception there is a crashed demo where a refusal is a chunk that
+     * arrives a frame later.
+     */
+    add(mesh: GpuDrivenMesh, transform: ArrayLike<number>, material: number): StreamHandle | null;
+    /** Take a mesh out. Its ranges go back and its clusters stop drawing. */
+    remove(handle: StreamHandle): void;
+    /** What changed since the last call, then cleared. An unchanged frame uploads nothing. */
+    takeDirty(): StreamUpload;
+    /**
+     * Where a mesh is interleaved: a fresh array while it has to be held until a pass attaches, and
+     * the one scratch otherwise, grown only when a mesh larger than any before it arrives.
+     */
+    private rowsFor;
+    private valuesFor;
+    /** Hand a placed mesh's geometry on, or hold it for the pass that has not attached yet. */
+    private place;
+    /**
+     * Keep a removed mesh's vertex and index ranges from the allocator until the next `takeDirty`.
+     *
+     * **Because the geometry is written when a mesh is added, not when the frame is recorded.** The
+     * pass records its frame at `beginFrame` and submits it at `endFrame`, and a queue write lands
+     * before the frame it was made during runs. A mesh added in that window into a range freed that
+     * frame would be drawn through the removed mesh's clusters, which the device holds until the
+     * next upload. `takeDirty` is that upload's first step, so from then on nothing reads the range.
+     * The cluster and mesh slots do not wait: their records travel together through the journal.
+     */
+    private hold;
+    private releaseWaiting;
+    /**
+     * A bounding sphere over every live cluster: centre in floats 0 to 2, radius in float 3.
+     *
+     * **`sceneShadowBounds` itself rather than a second spelling of it**, and that is not tidiness —
+     * the first version of this method wrote a *box* into the same four floats the pass reads a
+     * sphere out of, so the shadow camera was fitted to a sphere centred on the box's minimum corner
+     * with `maxX` as its radius. Two GPU-driven rigs lost their shadows and the maintainer saw it on
+     * the page before the capture diff was read.
+     *
+     * The function's own header already says why there is one copy of this arithmetic: a light's box
+     * that disagrees with the cull's bounds clips casters out of a map the cull believes are in it.
+     * A second copy here was the same mistake one level up.
+     */
+    sceneBounds(out: Float32Array): void;
+}
+/**
+ * A scene filled once from a list of meshes, which is the static case.
+ *
+ * With no capacity given it sizes itself to exactly what the meshes need, so a static scene
+ * allocates nothing spare and packs where `buildGpuDrivenScene` packed.
+ */
+export declare function streamingScene(meshes: readonly GpuDrivenMesh[], transforms: Float32Array, capacity?: StreamCapacity): StreamingScene;