@driftengine/core 3.63.0 → 4.0.0

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();

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

@@ -0,0 +1,41 @@
+/**
+ * What counts as a material change: the rule both backends count their `materials` line by.
+ *
+ * **A material is the shading state a draw reads that is not its own placement**, and the WebGPU
+ * backend keeps it in a ring of per-frame slots: a draw copies the open material into a new slot
+ * when something has changed it since the last draw, and otherwise shares the slot before it. So
+ * the slots a frame takes are its material changes, and that is what the backend's ceiling
+ * rations. WebGL2 sets the same state as loose uniforms and has nothing to run out of — but a
+ * consumer developing there is building the frame the other backend will ration, so it counts the
+ * same changes by the same rule, and draws them all.
+ *
+ * **What changes it**: a material setter; the start of a frame or of a mesh pass, which reopens
+ * the pass's own material; a probe bake, which sets its own and puts the pass's back; and a draw
+ * carrying options of its own (`ownsMaterial`), whose state is written for it and restored after
+ * it, so that it and the draw after it each open one.
+ *
+ * What it gives up: a setter called with the value already set still counts, because it takes a
+ * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
+ */
+/** What of a draw's own options its material carries. */
+export interface DrawMaterialOptions {
+    readonly opacity: number;
+    readonly lit: boolean;
+    readonly fog: boolean;
+    readonly toneMapped: boolean;
+    /** Whether the draw refracts this time, which a backend decides by whether it has a snapshot. */
+    readonly refracting: boolean;
+}
+/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
+export declare function ownsMaterial(options: DrawMaterialOptions): boolean;
+/** Whether the next draw shares the open material or opens a new one. */
+export declare class MaterialChanges {
+    /**
+     * The slot the open material occupies on a backend that keeps slots, or -1 when the next draw
+     * opens one. A backend without slots writes 0 when it opens one.
+     */
+    slot: number;
+    get open(): boolean;
+    /** Something the material holds changed, or a pass reopened it: the next draw opens a new one. */
+    dirty(): void;
+}

package/dist/render/backend/materialChanges.js

@@ -0,0 +1,38 @@
+/**
+ * What counts as a material change: the rule both backends count their `materials` line by.
+ *
+ * **A material is the shading state a draw reads that is not its own placement**, and the WebGPU
+ * backend keeps it in a ring of per-frame slots: a draw copies the open material into a new slot
+ * when something has changed it since the last draw, and otherwise shares the slot before it. So
+ * the slots a frame takes are its material changes, and that is what the backend's ceiling
+ * rations. WebGL2 sets the same state as loose uniforms and has nothing to run out of — but a
+ * consumer developing there is building the frame the other backend will ration, so it counts the
+ * same changes by the same rule, and draws them all.
+ *
+ * **What changes it**: a material setter; the start of a frame or of a mesh pass, which reopens
+ * the pass's own material; a probe bake, which sets its own and puts the pass's back; and a draw
+ * carrying options of its own (`ownsMaterial`), whose state is written for it and restored after
+ * it, so that it and the draw after it each open one.
+ *
+ * What it gives up: a setter called with the value already set still counts, because it takes a
+ * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
+ */
+/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
+export function ownsMaterial(options) {
+    return (options.opacity < 1 || !options.lit || !options.fog || !options.toneMapped || options.refracting);
+}
+/** Whether the next draw shares the open material or opens a new one. */
+export class MaterialChanges {
+    /**
+     * The slot the open material occupies on a backend that keeps slots, or -1 when the next draw
+     * opens one. A backend without slots writes 0 when it opens one.
+     */
+    slot = -1;
+    get open() {
+        return this.slot >= 0;
+    }
+    /** Something the material holds changed, or a pass reopened it: the next draw opens a new one. */
+    dirty() {
+        this.slot = -1;
+    }
+}

package/dist/render/backend/select.js

@@ -160,11 +160,19 @@ async function acquireWebGpu(gpu, wantsGpuTiming, shaders, stage) {
          * the default still refuses the model, and `WebGPURenderer.createMesh` says so in one line
          * rather than letting the driver say it a hundred times.
          */
+        /*
+         * **And the storage binding ceiling, for the same reason one level down.** A buffer that can be
+         * created is not a buffer that can be bound: `maxStorageBufferBindingSize` defaults to 128 MiB
+         * against this machine's 4 GiB, and the GPU-driven pipeline binds its whole vertex buffer as
+         * one storage binding. The voxel sandbox's port at a radius of ten asked for 262,807,200 bytes
+         * and came back as a hundred device warnings and a world with no terrain.
+         */
         const required = {};
         for (const limit of [
             'maxSampledTexturesPerShaderStage',
             'maxSamplersPerShaderStage',
             'maxBufferSize',
+            'maxStorageBufferBindingSize',
         ]) {
             const ceiling = adapter.limits[limit];
             if (typeof ceiling === 'number' && ceiling > 0)