@driftengine/core 3.63.0 → 4.1.0

package/dist/index.js

@@ -3,7 +3,7 @@
 export { startLoop } from './core/loop.js';
 export { StepBudget } from './core/stepBudget.js';
 export { hashToUnit, mulberry32, pickBySeed, savableMulberry32 } from './core/rng.js';
-export { exactAcos, exactCos, exactExp, exactSin } from './math/exact.js';
+export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './math/exact.js';
 export { TickTrace } from './core/tickTrace.js';
 export { BrowserStore, MemoryStore, defaultStore } from './core/storage.js';
 /* The same seam over a backend that answers later, with the queue, the retry and the status. */
@@ -60,7 +60,7 @@ export { MAX_DEPTH_LAYER, Renderer, WebGL2Renderer } from './render/backend/webg
 export { PickableSet } from './render/pickable.js';
 /* How big a piece of geometry is, which everything that culls or picks a detail level starts from. */
 export { boundsOfBox, boundsOfPositions, createBounds } from './math/bounds.js';
-export { createFrustum, frustumFromViewProjection, sphereInFrustum } from './math/frustum.js';
+export { boxInFrustum, createFrustum, frustumFromViewProjection, sphereInFrustum, } from './math/frustum.js';
 export { boundsVisible } from './render/visibility.js';
 export { apparentSize, lodForBounds } from './render/lod.js';
 /* A transform hierarchy. Additive: nothing in the renderer knows a node exists. */
@@ -79,6 +79,11 @@ export { createVisitResult, visitVisible } from './scene/visit.js';
  */
 export { generateMipChain, mipLevelCount, } from './render/backend/webgpu/surfaceTexturePass.js';
 export { createPassAttachment } from './render/passTarget.js';
+/*
+ * What a pass drawing the world does with `PrepareContext.jitter`, so a reconstructed frame's
+ * resolve finds its geometry where the renderer's own verbs put theirs.
+ */
+export { jitterClip } from './render/recon/jitter.js';
 export { OcclusionBuffer } from './render/occlusion.js';
 /*
  * `Renderer` above stays exported and is not deprecated. `createRenderer` is the way to get
@@ -87,6 +92,80 @@ export { OcclusionBuffer } from './render/occlusion.js';
  * take one.
  */
 export { createRenderer } from './render/backend/createRenderer.js';
+/*
+ * The second pipeline, as the two things a consumer assembles: the scene packing and the pass
+ * that draws it.
+ *
+ * **Exported here and reached by nobody who does not ask for it.** `pipeline: 'gpu-driven'` on
+ * `createRenderer` is the permission — it fails at boot where the backend cannot run this — and
+ * `GpuDrivenPass` is the implementation, registered the way `@driftengine/splats` registers one.
+ * A consumer who names neither pays nothing: `core-only` is measured with these exported and does
+ * not move, because nothing in the forward path reaches them.
+ *
+ * It draws vertex colour, one directional term, a hemispheric ambient and an emissive add — not
+ * the standard material. `DRAFT_SCENES`, never `SCENES`, until it draws the six published ones.
+ */
+export { GPU_DRIVEN_LISTS, GpuDrivenPass, MATERIAL_FLOATS, } from './render/backend/webgpu/gpuDrivenPass.js';
+/*
+ * **One environment, one haze, on both pipelines.** `GpuDrivenView.fog` is the medium the forward
+ * path binds, and a consumer drawing both in one frame fills it from `atmosphereFog` rather than
+ * working the numbers out again — the voxel sandbox's port is the first.
+ */
+export { atmosphereFog, createFogTarget } from './render/fog.js';
+export { buildGpuDrivenScene } from './render/gpudriven/sceneUpload.js';
+/*
+ * **The scene a `GpuDrivenPass` takes**, which is a streaming one since 2026-09-18 — a static
+ * scene is one filled once, so there is a single path rather than two. `buildGpuDrivenScene` stays
+ * exported because it is the packer `streamScene.test.ts` holds the streaming layout to.
+ */
+export { StreamingScene, streamingScene } from './render/gpudriven/streamScene.js';
+export { packDecodeTables, programFromEncoded } from './render/gpudriven/decodeTables.js';
+/*
+ * **A network graph on a device**: the one neural runtime's device half. `@driftengine/texture`
+ * holds the references and validates a graph; this runs the validated graph, whose shapes it takes
+ * as given, on a device opened from whichever `GPU` the caller has — a browser's or the native
+ * host's Dawn. Exported because the device may not leave `render/`, so a package that runs a
+ * network does so through here or not at all.
+ */
+export { openInferenceDevice } from './render/inference/device.js';
+export { createGraphRunner } from './render/inference/runner.js';
+/* The buffer-reuse rule, exported because `@driftengine/texture`'s evaluator plans by this one
+   rather than by a second copy of it — see `reuse.ts` for why it is on this side of the arrow. */
+export { planReuse } from './render/inference/reuse.js';
+/* The tile lists a device draws a splat cloud from, beside the shader that walks them. */
+export { countSplatTiles, fillSplatTiles, splatPixelBox, splatTileGrid, splatTileOffsets, SPLAT_BIN_FLOATS, SPLAT_TILE, } from './render/inference/splatTiles.js';
+/**
+ * **Indirect light, as three levels that fall back to each other and never off the end.**
+ *
+ * `ROADMAP.md` refused screen-space global illumination because its error is unbounded — a ray
+ * that leaves the frame has no answer, and every technique that ships one anyway invents one from
+ * whatever happened to be on screen. This does not reverse that refusal: the screen is an
+ * accelerator with a world-space distance field behind it, whose error is bounded by its own
+ * resolution, and a probe volume behind *that*, which is never wrong and only ever coarse.
+ *
+ * **CPU-side, and reached by nobody who does not ask.** There is no WGSL, no pass and no renderer
+ * option yet, so no scene renders differently for these existing — this wave's first constraint,
+ * measured rather than asserted: the eight published scenes are 0 of 921,600 pixels against the
+ * build before them, and `core-only` is byte-identical with these exported and without them.
+ * Exported anyway, for the reason `bake/cluster.ts` was not: a capability with no route out of its
+ * package is one the first consumer finds by failing a boundary test.
+ */
+export { GI_SOURCE_FIELD, GI_SOURCE_PROBES, GI_SOURCE_SCREEN, newIndirectResult, traceIndirect, } from './render/gi/chain.js';
+export { GLOBAL_FIELD_BLEND, composeGlobalField, createGlobalField, sampleGlobalField, } from './render/gi/globalField.js';
+export { GI_SCREEN_MARCH, SCREEN_TRACE_BIAS_M, screenRayOrigin, traceScreen, } from './render/gi/traceScreen.js';
+export { FIELD_MARCH, coneRadiusAt, newFieldHit, traceField } from './render/gi/traceField.js';
+export { PROBE_VISIBILITY_SHARPNESS, bakeProbeVisibility, createProbeVisibility, probeUpdateSchedule, probeVisibilityWeight, sampleProbeVolume, visibleProbes, } from './render/gi/probeVolume.js';
+export { DENOISE_MIN_ALPHA, filterStepFor, newTemporalPixel, spatialDenoise, temporalDenoise, } from './render/gi/denoise.js';
+export { reflectDirection, reflectionCone, traceReflection } from './render/gi/reflection.js';
+/*
+ * The pass that draws the renderer's field on a device. WebGPU only, and it says so at
+ * registration rather than at the first frame: a distance field is composed by compute and WebGL2
+ * has none. It no longer composes one of its own — `addDistanceField` is how a scene declares
+ * what its indirect light may be traced against, and this marches what the renderer made of them.
+ */
+export { GiFieldPass } from './render/backend/webgpu/giFieldPass.js';
+export { DistanceFieldScene, MAX_DISTANCE_FIELDS } from './render/gi/fieldScene.js';
+export { placeCascade } from './render/gi/globalField.js';
 /*
  * The acceptance probe, exported because a consumer may want to ask the question itself — an
  * editor deciding whether to offer a backend, a shell deciding what to tell the player — and
@@ -225,6 +304,13 @@ export { DebugLines } from './render/debugLines.js';
  * over and what a drag does, and fills line buffers the caller draws with `drawLines`.
  * Nothing here touches a context.
  */
+/*
+ * Ray intersection, exported because a consumer building a tool needs the same arithmetic the
+ * gizmo does. `editor/src/viewport/gizmo.ts` reaching into `src/math/intersect.ts` by path would
+ * be the editor using a private hook, which `ARCHITECTURE.md` treats as a hole in the engine
+ * rather than as the editor's problem — so the hole is closed here.
+ */
+export { rayClosestOnLine, rayPlane, raySphere } from './math/intersect.js';
 export { GIZMO_GROUP_ACTIVE, GIZMO_GROUP_COLORS, GIZMO_GROUP_COUNT, GIZMO_GROUP_NEUTRAL, GIZMO_GROUP_X, GIZMO_GROUP_Y, GIZMO_GROUP_Z, GIZMO_NONE, GIZMO_ROTATE_X, GIZMO_ROTATE_Y, GIZMO_ROTATE_Z, GIZMO_SCALE_UNIFORM, GIZMO_SCALE_X, GIZMO_SCALE_Y, GIZMO_SCALE_Z, GIZMO_TRANSLATE_X, GIZMO_TRANSLATE_XY, GIZMO_TRANSLATE_Y, GIZMO_TRANSLATE_YZ, GIZMO_TRANSLATE_Z, GIZMO_TRANSLATE_ZX, Gizmo, gizmoScaleFor, } from './render/gizmo.js';
 export { RainField } from './render/rainField.js';
 export { coveredAbove } from './physics/heightSurface.js';
@@ -286,6 +372,21 @@ export { bakeOverlay, drawPixelText, pixelTextCells, pixelTextSize } from './ui/
 export { FpsMeter } from './dev/fpsMeter.js';
 export { CONTACT_LIMIT, createContactReports, describeContacts } from './dev/contactProbe.js';
 export { GPU_SLOTS, GpuTimer } from './render/gpuTimer.js';
+/*
+ * Per-pass timings, which are a readout rather than a frame graph.
+ *
+ * **`render/frame/index.ts` says nothing under it may be reached from outside `render/` yet, and
+ * this module is the exception with a reason.** The rest of that directory is the graph's
+ * construction — declarations, lifetimes, aliasing, scheduling — whose public shape the design
+ * leaves to a later phase, and exporting it now would fix a shape nobody has had to live with.
+ * A timing readout is not that: it is seven functions over three arrays, its own header argues why
+ * it is not a widening of `GpuTimer`, and anything that profiles a frame needs it.
+ *
+ * The editor is what made this concrete. `AGENTS.md`'s rule is that a consumer needing a private
+ * import has found a hole in the engine, and the hole is fixed here rather than worked around
+ * there — which is the whole reason the editor was built outside `packages/`.
+ */
+export { createPassTimings, passLabel, passMs, recordPassLabel, recordPassSample, resetPassTimings, } from './render/frame/passTimings.js';
 export { classifyRightGesture } from './input/rightGesture.js';
 export { createWindState, sampleWind } from './render/wind.js';
 export { advanceWindField, createWindField } from './render/windField.js';
@@ -329,3 +430,12 @@ export { parseSdfFont } from './render/sdfFont.js';
 export { DEFAULT_SDF_TEXT_STYLE, SdfTextLayout } from './render/sdfTextLayout.js';
 export { WindStreakRenderer } from './render/windStreakRenderer.js';
 export { buildTree } from './geometry/treeBuilder.js';
+/*
+ * Large worlds: the cell grid that streams and freezes, and the origin that rendering rebases
+ * against while the simulation never does. See `world/rebase.ts` for why that asymmetry is the
+ * rule the whole design hangs on.
+ */
+export { cellBounds, cellCoord, cellCoordInRange, cellCoordsOf, cellIdFor, cellIdFrom, cellsInFrustum, cellsInRadius, createCellGrid, } from './world/cell.js';
+export { renderOrigin, toRenderSpace, toWorldSpace } from './world/rebase.js';
+export { cameraPositionFrom, cellPredictor, createCellStream, pumpCellStream, setCellStreamOrigin, } from './world/cellStream.js';
+export { createFrozenCells, freezeCell, frozenEntities, frozenFingerprintContribution, isCellFrozen, thawCell, } from './world/freeze.js';

package/dist/input/input.js

@@ -317,7 +317,12 @@ export class InputSource {
     constructor(target, preventDefaultCodes = [], options = {}) {
         this.target = target;
         this.preventDefaultCodes = new Set(preventDefaultCodes);
-        this.isCoarse = window.matchMedia('(pointer: coarse)').matches;
+        /* Guarded, and `ui/fullscreen.ts` guards the identical query with the identical test. This
+           line is in a constructor, so unguarded it did not degrade a hint — it threw, and an embedder
+           without `matchMedia` could not construct input at all. False is what a runtime with no
+           pointer media query honestly is. */
+        this.isCoarse =
+            typeof window.matchMedia === 'function' && window.matchMedia('(pointer: coarse)').matches;
         this.deadzone = options.deadzone ?? DEFAULT_DEADZONE;
         this.autoPoll = options.autoPoll ?? true;
         for (const name of ['keyboard', 'mouse', 'touch', 'gamepad']) {

package/dist/math/exact.d.ts

@@ -18,9 +18,10 @@
  *
  * ## What is here, and what is deliberately not
  *
- * `exactSin`, `exactCos`, `exactExp`, `exactAcos`. Four, because four is what the engine and its
- * first consumer actually reach for: the terrain binding's slope angle needs `acos`, a lockstep
- * fixture rotating anything needs `sin` and `cos`, and exponential decay needs `exp`.
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos` and `exactLog`. Five, because five is what the
+ * engine and its first consumer actually reach for: the terrain binding's slope angle needs `acos`,
+ * a lockstep fixture rotating anything needs `sin` and `cos`, exponential decay needs `exp`, and a
+ * detector's box prior is a logit of the patch grid, which needs `log`.
  *
  * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
  * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
@@ -55,6 +56,15 @@ export declare function exactCos(x: number): number;
  * representation and there is nothing a fitted polynomial would buy.
  */
 export declare function exactExp(x: number): number;
+/**
+ * `Math.log`, reproducibly: fdlibm's algorithm, which is also V8's.
+ *
+ * Take the power of two out as `k` and leave a significand in [√2/2, √2), so that `f = m - 1` is
+ * small either side of zero; then log(1 + f) = f - f²/2 + s·(f²/2 + R(s²)) with s = f/(2 + f), and
+ * `k·ln 2` added back in two parts so the large part loses nothing. The exponent is read and the
+ * significand rescaled through the double's own words — integer operations, not transcendentals.
+ */
+export declare function exactLog(x: number): number;
 /**
  * `Math.acos`, reproducibly. Outside [-1, 1] this answers NaN, as `Math.acos` does.
  *

package/dist/math/exact.js

@@ -18,9 +18,10 @@
  *
  * ## What is here, and what is deliberately not
  *
- * `exactSin`, `exactCos`, `exactExp`, `exactAcos`. Four, because four is what the engine and its
- * first consumer actually reach for: the terrain binding's slope angle needs `acos`, a lockstep
- * fixture rotating anything needs `sin` and `cos`, and exponential decay needs `exp`.
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos` and `exactLog`. Five, because five is what the
+ * engine and its first consumer actually reach for: the terrain binding's slope angle needs `acos`,
+ * a lockstep fixture rotating anything needs `sin` and `cos`, exponential decay needs `exp`, and a
+ * detector's box prior is a logit of the patch grid, which needs `log`.
  *
  * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
  * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
@@ -226,6 +227,70 @@ export function exactExp(x) {
     sum = 1 + r * sum;
     return sum * pow2(k);
 }
+/* fdlibm's `log` polynomial in s², for log(1 + f) around f = 0 by way of s = f / (2 + f). */
+const LG1 = 6.66666666666673513e-1;
+const LG2 = 3.999999999940941908e-1;
+const LG3 = 2.857142874366239149e-1;
+const LG4 = 2.222219843214978396e-1;
+const LG5 = 1.818357216161805012e-1;
+const LG6 = 1.531383769920937332e-1;
+const LG7 = 1.479819860511658591e-1;
+const TWO54 = 1.8014398509481984e16;
+const SMALLEST_NORMAL = 2.2250738585072014e-308;
+/* A double's two words, for reading and setting an exponent; one view, reused. */
+const words = new DataView(new ArrayBuffer(8));
+/**
+ * `Math.log`, reproducibly: fdlibm's algorithm, which is also V8's.
+ *
+ * Take the power of two out as `k` and leave a significand in [√2/2, √2), so that `f = m - 1` is
+ * small either side of zero; then log(1 + f) = f - f²/2 + s·(f²/2 + R(s²)) with s = f/(2 + f), and
+ * `k·ln 2` added back in two parts so the large part loses nothing. The exponent is read and the
+ * significand rescaled through the double's own words — integer operations, not transcendentals.
+ */
+export function exactLog(x) {
+    if (Number.isNaN(x) || x < 0)
+        return Number.NaN;
+    if (x === 0)
+        return Number.NEGATIVE_INFINITY;
+    if (x === Number.POSITIVE_INFINITY)
+        return x;
+    let k = 0;
+    let value = x;
+    if (value < SMALLEST_NORMAL) {
+        k = -54;
+        value *= TWO54;
+    }
+    words.setFloat64(0, value);
+    let hx = words.getUint32(0);
+    k += (hx >>> 20) - 1023;
+    hx &= 0x000fffff;
+    /* Keep the significand at or above √2/2: past √2, halve it and count one more power of two. */
+    const i = (hx + 0x95f64) & 0x100000;
+    words.setUint32(0, hx | (i ^ 0x3ff00000));
+    k += i >>> 20;
+    const f = words.getFloat64(0) - 1;
+    if ((0x000fffff & (2 + hx)) < 3) {
+        /* |f| < 2^-20: two terms of the series are the whole answer. */
+        if (f === 0)
+            return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
+        const r = f * f * (0.5 - 0.33333333333333333 * f);
+        return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
+    }
+    const s = f / (2 + f);
+    const z = s * s;
+    const w = z * z;
+    const t1 = w * (LG2 + w * (LG4 + w * LG6));
+    const t2 = z * (LG1 + w * (LG3 + w * (LG5 + w * LG7)));
+    const r = t2 + t1;
+    /* Far enough from one that f²/2 is worth carrying apart from f. */
+    if (((hx - 0x6147a) | (0x6b851 - hx)) > 0) {
+        const half = 0.5 * f * f;
+        return k === 0
+            ? f - (half - s * (half + r))
+            : k * LN2_HI - (half - (s * (half + r) + k * LN2_LO) - f);
+    }
+    return k === 0 ? f - s * (f - r) : k * LN2_HI - (s * (f - r) - k * LN2_LO - f);
+}
 /** fdlibm's `asin` rational on `z = x²`, valid where `z` is small. */
 function asinRational(z) {
     const numerator = z * (P0 + z * (P1 + z * (P2 + z * (P3 + z * (P4 + z * P5)))));

package/dist/math/frustum.d.ts

@@ -10,6 +10,11 @@ import type { ReadonlyMat4 } from 'gl-matrix';
  * the frustum when `n · p + d >= 0` for all six.
  */
 export type Frustum = Float32Array;
+/**
+ * Planes in either precision. **Double precision is for a world past 2^24 units**, where a plane's
+ * offset is a number a single float cannot hold to the metre; `cellsInFrustum` asks for it.
+ */
+export type FrustumPlanes = Float32Array | Float64Array;
 export declare function createFrustum(): Frustum;
 /**
  * Pull the six planes out of a view-projection matrix.
@@ -28,7 +33,7 @@ export declare function createFrustum(): Frustum;
  *
  * gl-matrix stores column-major, so `m[column * 4 + row]`.
  */
-export declare function frustumFromViewProjection(m: ReadonlyMat4, out: Frustum): Frustum;
+export declare function frustumFromViewProjection<T extends FrustumPlanes>(m: ReadonlyMat4 | Float64Array, out: T): T;
 /**
  * Whether a world-space sphere is anywhere inside the frustum.
  *
@@ -41,4 +46,14 @@ export declare function frustumFromViewProjection(m: ReadonlyMat4, out: Frustum)
  * all six planes, near an edge. That costs a draw that turns out to be invisible and never costs
  * a draw that was visible, which is the only asymmetry a cull may have.
  */
-export declare function sphereInFrustum(frustum: Frustum, x: number, y: number, z: number, radius: number): boolean;
+export declare function sphereInFrustum(frustum: FrustumPlanes, x: number, y: number, z: number, radius: number): boolean;
+/**
+ * Whether an axis-aligned box is anywhere inside the frustum, by the same question the sphere test
+ * asks: outside only when wholly beyond one plane.
+ *
+ * **The corner that decides it is chosen per plane** — the one furthest along that plane's normal.
+ * A fixed corner answers correctly for the planes whose normals happen to point its way and culls a
+ * box straddling any of the others. Conservative at the edges, as the sphere test is: a box near a
+ * corner of the frustum can be outside it and still kept.
+ */
+export declare function boxInFrustum(frustum: FrustumPlanes, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): boolean;

package/dist/math/frustum.js

@@ -88,3 +88,27 @@ export function sphereInFrustum(frustum, x, y, z, radius) {
     }
     return true;
 }
+/**
+ * Whether an axis-aligned box is anywhere inside the frustum, by the same question the sphere test
+ * asks: outside only when wholly beyond one plane.
+ *
+ * **The corner that decides it is chosen per plane** — the one furthest along that plane's normal.
+ * A fixed corner answers correctly for the planes whose normals happen to point its way and culls a
+ * box straddling any of the others. Conservative at the edges, as the sphere test is: a box near a
+ * corner of the frustum can be outside it and still kept.
+ */
+export function boxInFrustum(frustum, minX, minY, minZ, maxX, maxY, maxZ) {
+    for (let plane = 0; plane < PLANE_COUNT; plane += 1) {
+        const at = plane * 4;
+        const nx = frustum[at] ?? 0;
+        const ny = frustum[at + 1] ?? 0;
+        const nz = frustum[at + 2] ?? 0;
+        const reach = nx * (nx >= 0 ? maxX : minX) +
+            ny * (ny >= 0 ? maxY : minY) +
+            nz * (nz >= 0 ? maxZ : minZ) +
+            (frustum[at + 3] ?? 0);
+        if (reach < 0)
+            return false;
+    }
+    return true;
+}

package/dist/render/backend/api.d.ts

@@ -464,7 +464,20 @@ export type RendererApi = Omit<{
      */
     updateMesh(mesh: MeshHandle, positions: Float32Array, normals?: Float32Array): void;
     /** Draw a handle this renderer made. Passing one from the other backend is a caller error. */
-    drawMesh(mesh: MeshHandle, model: ReadonlyMat4, depthLayer?: number, tint?: Vec3 | null): void;
+    drawMesh(mesh: MeshHandle, model: ReadonlyMat4, depthLayer?: number, tint?: Vec3 | null, 
+    /**
+     * Where this mesh's surface was last frame, for a reconstruction's motion target.
+     *
+     * **Only a reconstruction reads it**, and only on WebGPU: it is what turns a moving object's
+     * stale history from a smear into a reprojection. A draw that says nothing gets the camera's
+     * motion, derived from the depth, which is exactly right for anything that did not move and
+     * wrong in proportion to how far a mover moved. Null and omitted mean the same thing.
+     *
+     * It is the *model* matrix this mesh was drawn with last frame, not a velocity: the pass
+     * transforms each vertex twice and lets the perspective divide do the rest, so a rotation and a
+     * scale are as correct as a translation.
+     */
+    previousModel?: ReadonlyMat4 | null): void;
     /** Release the geometry behind a handle. */
     disposeMesh(mesh: MeshHandle): void;
     /**
@@ -494,3 +507,23 @@ export type RendererApi = Omit<{
 };
 /** Which backend is actually drawing. Reported, never inferred. */
 export type RenderBackend = 'webgl2' | 'webgpu';
+/**
+ * Whether this backend can be driven from buffers the GPU itself wrote.
+ *
+ * **A fact about the backend, not a method on this surface, and that is the finding rather than
+ * the shortcut.** Indirect execution needs a render or compute pass encoder, and both are already
+ * in the hands of the code that would use them: `PassContext` hands a contributed pass the
+ * `GPURenderPassEncoder`, and `ComputeDefinition.dispatch` hands a definition the
+ * `GPUComputePassEncoder` while saying in as many words that the workgroup count is the
+ * definition's and does not cross this surface. A `drawIndexedIndirect` here would be a second
+ * way to reach an encoder a caller already holds.
+ *
+ * So what is missing is not a verb. It is an answer to *may I*, which a GPU-driven pipeline has
+ * to ask before it builds an argument buffer nothing can consume.
+ *
+ * **WebGL2 is a refusal rather than an omission.** It has no compute stage to write an argument
+ * buffer and no indirect draw to read one. Emulating it means reading the buffer back to the
+ * processor and issuing the draws from there, which is slower than the ordinary path it would be
+ * pretending to replace — so this reports false and the GPU-driven pipeline is WebGPU-only.
+ */
+export declare function indirectSupport(backend: 'webgl2' | 'webgpu'): boolean;

package/dist/render/backend/api.js

@@ -1 +1,22 @@
-export {};
+/**
+ * Whether this backend can be driven from buffers the GPU itself wrote.
+ *
+ * **A fact about the backend, not a method on this surface, and that is the finding rather than
+ * the shortcut.** Indirect execution needs a render or compute pass encoder, and both are already
+ * in the hands of the code that would use them: `PassContext` hands a contributed pass the
+ * `GPURenderPassEncoder`, and `ComputeDefinition.dispatch` hands a definition the
+ * `GPUComputePassEncoder` while saying in as many words that the workgroup count is the
+ * definition's and does not cross this surface. A `drawIndexedIndirect` here would be a second
+ * way to reach an encoder a caller already holds.
+ *
+ * So what is missing is not a verb. It is an answer to *may I*, which a GPU-driven pipeline has
+ * to ask before it builds an argument buffer nothing can consume.
+ *
+ * **WebGL2 is a refusal rather than an omission.** It has no compute stage to write an argument
+ * buffer and no indirect draw to read one. Emulating it means reading the buffer back to the
+ * processor and issuing the draws from there, which is slower than the ordinary path it would be
+ * pretending to replace — so this reports false and the GPU-driven pipeline is WebGPU-only.
+ */
+export function indirectSupport(backend) {
+    return backend === 'webgpu';
+}

package/dist/render/backend/budget.d.ts

@@ -1,12 +1,13 @@
 /**
  * What a frame asked of a backend, against what that backend allows.
  *
- * **This exists because a ceiling firing was unobservable.** The WebGPU backend holds ten per-frame
- * ceilings — draws, material changes, overlays, water bodies, light volumes, plumes, three kinds of
- * effect batch and the scatter shadow round — and past any of them it skips the work and writes one
- * `console.warn` for the lifetime of the renderer. WebGL2 holds none of them and draws everything.
- * So a scene over a ceiling renders differently on the two backends, silently, and a consumer
- * developing against WebGL2 has no way to see it coming.
+ * **This exists because a ceiling firing was unobservable.** The WebGPU backend holds fourteen
+ * per-frame ceilings — draws, material changes, two kinds of shadow draw, water bodies, light
+ * volumes, four kinds of effect batch and four kinds of overlay — and past any of them it skips the
+ * work and writes one `console.warn` for the lifetime of the renderer. WebGL2 holds none of them and
+ * draws everything. So a scene over a ceiling renders differently on the two backends, silently,
+ * and a consumer developing against WebGL2 had no way to see it coming — which is why WebGL2 counts
+ * the same fifteen lines by the same rules, and reports the number the other backend rations.
  *
  * **The cost of that was measured from outside.** A consumer spent weeks on ground that
  * vanished and reappeared as the camera moved; its own report still lists, as the decisive

package/dist/render/backend/budget.js

@@ -1,12 +1,13 @@
 /**
  * What a frame asked of a backend, against what that backend allows.
  *
- * **This exists because a ceiling firing was unobservable.** The WebGPU backend holds ten per-frame
- * ceilings — draws, material changes, overlays, water bodies, light volumes, plumes, three kinds of
- * effect batch and the scatter shadow round — and past any of them it skips the work and writes one
- * `console.warn` for the lifetime of the renderer. WebGL2 holds none of them and draws everything.
- * So a scene over a ceiling renders differently on the two backends, silently, and a consumer
- * developing against WebGL2 has no way to see it coming.
+ * **This exists because a ceiling firing was unobservable.** The WebGPU backend holds fourteen
+ * per-frame ceilings — draws, material changes, two kinds of shadow draw, water bodies, light
+ * volumes, four kinds of effect batch and four kinds of overlay — and past any of them it skips the
+ * work and writes one `console.warn` for the lifetime of the renderer. WebGL2 holds none of them and
+ * draws everything. So a scene over a ceiling renders differently on the two backends, silently,
+ * and a consumer developing against WebGL2 had no way to see it coming — which is why WebGL2 counts
+ * the same fifteen lines by the same rules, and reports the number the other backend rations.
  *
  * **The cost of that was measured from outside.** A consumer spent weeks on ground that
  * vanished and reappeared as the camera moved; its own report still lists, as the decisive

package/dist/render/backend/createRenderer.d.ts

@@ -1,6 +1,38 @@
 import { type RenderQualityOptions } from '../renderQuality.ts';
 import type { RenderBackend, RendererApi } from './api.ts';
 import { type SplashOptions } from '../../ui/splash.ts';
+/**
+ * Which of the two pipelines is drawing.
+ *
+ * A union rather than a boolean because a third is foreseeable and a boolean named for one of them
+ * is what makes the third awkward — `ROADMAP.md`'s own note about `hdrScene` starting life as
+ * `bool hdr`.
+ */
+export type RenderPipeline = 'forward' | 'gpu-driven';
+/**
+ * What a caller who says nothing gets.
+ *
+ * **A named constant rather than a literal in the `??`**, because the literal is unreachable from
+ * a test here: nothing in this environment resolves a renderer, so flipping it changed no answer
+ * and no test noticed. The constant is where the decision lives and it is asserted directly.
+ *
+ * Forward, and it stays forward until the second pipeline has drawn the six published scenes.
+ */
+export declare const DEFAULT_PIPELINE: RenderPipeline;
+/**
+ * Why a requested pipeline cannot run on the backend that is about to draw, or null where it can.
+ *
+ * **Its own function because it is the only part of the decision a test in this environment can
+ * reach.** Nothing here can resolve a renderer — there is no GL context and no adapter — so every
+ * test of `createRenderer` ends in a rejection, and a check that lives only inside the factory is
+ * a check nothing exercises. `built` is this function's one caller and every return from the
+ * factory passes through it.
+ *
+ * **The backend is the one that will draw, not the one that was asked for.** Three paths into
+ * `built` arrive having fallen back from WebGPU, and a check written against the request passes on
+ * all three.
+ */
+export declare function pipelineRefusal(pipeline: RenderPipeline, backend: RenderBackend, reason: string): string | null;
 /** Everything about selection a caller may want to decide instead of inherit. */
 export interface CreateRendererOptions {
     /**
@@ -19,6 +51,23 @@ export interface CreateRendererOptions {
      * shows that, and the fallback is silent when it happens.
      */
     readonly preferWebGpu?: boolean;
+    /**
+     * Which pipeline to draw with. **Defaults to `'forward'`.**
+     *
+     * `'gpu-driven'` selects the cluster pipeline: instances and clusters culled on the device
+     * against a depth pyramid built this frame, a visibility buffer, and one shading dispatch per
+     * material. It needs indirect draws and dispatches, which WebGL2 does not have.
+     *
+     * **Asking for it where it cannot run throws.** Not a warning and not a fallback: a silent
+     * fallback means a consumer ships believing they have a pipeline they do not, and the difference
+     * only shows as a frame time on somebody else's machine. The throw carries the reason in words,
+     * from `gpuDrivenRefusal`.
+     *
+     * **This includes a WebGPU request that fell back**, which is the case a check written against
+     * the *asked-for* backend would miss: every fallback path here is a path where the pipeline
+     * became unavailable after the choice was made.
+     */
+    readonly pipeline?: RenderPipeline;
     /**
      * The query string to read `?backend=` from. Defaults to the document's own.
      *
@@ -116,6 +165,14 @@ export interface CreatedRenderer {
      * renderer knows.
      */
     readonly reversedDepth: boolean;
+    /**
+     * Which pipeline is drawing: the forward path, or the one driven from buffers the GPU wrote.
+     *
+     * Reported for the same reason `backend` is — a consumer who asked for one and got the other
+     * has to be able to find out. They cannot, here: asking for `gpu-driven` on a backend that
+     * cannot run it throws rather than answering `forward`. See `CreateRendererOptions.pipeline`.
+     */
+    readonly pipeline: RenderPipeline;
 }
 /**
  * Build a renderer on the best backend this browser will actually give us.

package/dist/render/backend/createRenderer.js

@@ -3,6 +3,35 @@ import { resolveRenderQuality } from '../renderQuality.js';
 import { BACKEND_TIMEOUT_MS, forcedBackend, selectBackend } from './select.js';
 import { TIMED_OUT, withDeadline } from './deadline.js';
 import { mountSplash } from '../../ui/splash.js';
+import { gpuDrivenRefusal, gpuDrivenSupported } from '../gpudriven/pipeline.js';
+/**
+ * What a caller who says nothing gets.
+ *
+ * **A named constant rather than a literal in the `??`**, because the literal is unreachable from
+ * a test here: nothing in this environment resolves a renderer, so flipping it changed no answer
+ * and no test noticed. The constant is where the decision lives and it is asserted directly.
+ *
+ * Forward, and it stays forward until the second pipeline has drawn the six published scenes.
+ */
+export const DEFAULT_PIPELINE = 'forward';
+/**
+ * Why a requested pipeline cannot run on the backend that is about to draw, or null where it can.
+ *
+ * **Its own function because it is the only part of the decision a test in this environment can
+ * reach.** Nothing here can resolve a renderer — there is no GL context and no adapter — so every
+ * test of `createRenderer` ends in a rejection, and a check that lives only inside the factory is
+ * a check nothing exercises. `built` is this function's one caller and every return from the
+ * factory passes through it.
+ *
+ * **The backend is the one that will draw, not the one that was asked for.** Three paths into
+ * `built` arrive having fallen back from WebGPU, and a check written against the request passes on
+ * all three.
+ */
+export function pipelineRefusal(pipeline, backend, reason) {
+    if (pipeline !== 'gpu-driven' || gpuDrivenSupported(backend))
+        return null;
+    return `[driftengine] ${gpuDrivenRefusal(backend)} (${reason})`;
+}
 /**
  * Hand the badge the one fact it is waiting for: a frame reached the screen.
  *
@@ -60,7 +89,22 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
      * the two failure paths — a fallback still paints, and a badge that outlived a fallback would
      * sit on the screen until the cap for a game that was running perfectly well underneath it.
      */
+    const pipeline = options.pipeline ?? DEFAULT_PIPELINE;
     const built = (result) => {
+        /*
+         * **Checked here rather than at the top, because every return passes through here.** The
+         * question is not which backend was *asked for* — it is which one is about to draw, and three
+         * of the paths into this function arrive having fallen back. A check against the request would
+         * pass on all three and hand back a forward renderer with `pipeline: 'gpu-driven'` on it.
+         *
+         * The splash goes down first. A page that throws out of `createRenderer` with a badge mounted
+         * leaves it on screen over nothing, for as long as the tab is open.
+         */
+        const refused = pipelineRefusal(pipeline, result.backend, result.reason);
+        if (refused !== null) {
+            splash?.present();
+            throw new Error(refused);
+        }
         if (splash !== null)
             presentOnFirstFrame(result.renderer, splash);
         /*
@@ -80,6 +124,7 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
             ...result,
             rendererName: result.renderer.rendererName,
             reversedDepth: result.renderer.reversedDepth,
+            pipeline,
         };
     };
     /*
@@ -93,7 +138,11 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
      * the promise the deadline was racing.
      */
     const budgetMs = options.backendTimeoutMs ?? BACKEND_TIMEOUT_MS;
-    const startedAt = Date.now();
+    /* Monotonic, and it has to be: `budgetMs - spent` below subtracts two readings. The wall clock
+       steps — daylight saving, an NTP correction, a laptop resuming with a stale clock — and a
+       forward step makes `spent` exceed the budget, so the engine falls back to WebGL2 reporting
+       "WebGPU stalled" about a device that was fine. */
+    const startedAt = performance.now();
     const choice = await selectBackend(search, options.preferWebGpu ?? true, quality.gpuTiming ?? false, options.probeShaders ?? [], budgetMs);
     if (choice.backend === 'webgpu' && choice.device !== null) {
         /*
@@ -131,7 +180,7 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
                 stage = 'constructing the renderer';
                 return { surface, WebGPURenderer };
             })();
-            const spent = Date.now() - startedAt;
+            const spent = performance.now() - startedAt;
             const settled = await withDeadline(construction, budgetMs - spent);
             if (settled === TIMED_OUT) {
                 device.destroy();