@driftengine/core 3.61.0

package/dist/render/gpuCapability.d.ts

@@ -0,0 +1,111 @@
+/** Whether this renderer string names a part known to struggle with the good profile. */
+export declare function isWeakGpuFamily(rendererName: string): boolean;
+/**
+ * What a WebGPU adapter calls the part, in the shape the table above matches.
+ *
+ * **Here rather than inline in `selectBackend`, because two callers need the identical string.**
+ * The backend selection builds it to hand the renderer a part number for the clamp, and
+ * `describeGpu` builds it to answer a consumer choosing a profile *before* a renderer exists. Two
+ * spellings of this join is the 2026-08-13 rule's first clause exactly: one decision, two
+ * implementations, and the drift shows up as a clamp that fires in one path and not the other.
+ *
+ * Every field is optional and browsers withhold them to differing degrees, so they are joined
+ * rather than formatted: a string with a vendor and nothing else is still something the table can
+ * recognise. An empty result falls back to the literal `WebGPU`, so nothing that prints it gets a
+ * blank — which is also why `isWeakGpuFamily('WebGPU')` is false and must stay false.
+ */
+export declare function adapterRendererName(info: GPUAdapterInfo | undefined): string;
+/**
+ * What a WebGL2 context calls the part.
+ *
+ * `WEBGL_debug_renderer_info` is an extension and a browser may withhold it, so the empty string
+ * is an ordinary answer and not a failure — `isWeakGpuFamily('')` is false, which is the same
+ * "unknown is not weak" rule the table above is built on.
+ */
+export declare function webgl2RendererName(gl: WebGL2RenderingContext): string;
+/** What part this machine has, as far as the browser will say. See `describeGpu`. */
+export interface GpuIdentity {
+    /**
+     * The part's own string, or `''` where the browser declined to name it.
+     *
+     * The same string `RendererApi.rendererName` carries once a renderer exists, from the same two
+     * derivations — this is that answer, moved earlier.
+     */
+    readonly rendererName: string;
+    /** `isWeakGpuFamily(rendererName)`, so a caller does not have to remember to ask. */
+    readonly weak: boolean;
+    /**
+     * Which API answered, and **never a prediction of the backend `createRenderer` will build on.**
+     *
+     * Naming the part and choosing a backend are different questions with different costs: this
+     * asks an adapter for its name, and the selection asks for a *device*, compiles what it was
+     * given and reads back a pixel. A machine can name a WebGPU adapter and still end up on WebGL2.
+     * The field is here so a bug report can say where the string came from, not so a caller can
+     * branch on it.
+     */
+    readonly source: 'webgpu' | 'webgl2' | 'none';
+}
+/** The seams a test needs. A caller in a browser passes none of them. */
+export interface DescribeGpuOptions {
+    /** Whether to ask WebGPU first. Defaults to true, matching `createRenderer`. */
+    readonly preferWebGpu?: boolean;
+    /** Defaults to `navigator.gpu`. */
+    readonly gpu?: GPU | null;
+    /**
+     * Where the WebGL2 fallback reads its string from. Defaults to a **detached** canvas.
+     *
+     * **Detached, and that is the whole reason this is not read off the caller's canvas.** A second
+     * `getContext('webgl2')` on one canvas returns the *existing* context and silently ignores the
+     * attributes, so whoever calls first decides `alpha`, `antialias` and `powerPreference` for
+     * everybody — and `Renderer` chooses `antialias` from the very profile a caller is here to
+     * decide. Reading the name off the real canvas would settle a rendering attribute as a side
+     * effect of asking a question. `webgl2/renderer.ts` records the same trap from the other side,
+     * where a consumer doing this by hand was the bug.
+     */
+    readonly createCanvas?: () => HTMLCanvasElement | null;
+}
+/**
+ * Ask what part this machine has, **before** building a renderer.
+ *
+ * **The gap this closes:** `isWeakGpuFamily` is exported for a consumer to classify the part it is
+ * running on, and until now the only string to hand it arrived on a renderer that had already been
+ * constructed — by which time the profile has been consumed and, as `applyResolutionScale` puts
+ * it, everything except the pixel density is memory allocated at construction. So the one function
+ * the engine offers for this decision took an argument the engine would not give you in time.
+ * Reported from outside 2026-08-28, by a consumer that had fallen back to `(pointer: coarse)`
+ * instead: a good proxy, right about a phone and wrong about a weak desktop, which is exactly the
+ * case `isWeakGpuFamily` exists for.
+ *
+ * **WebGL2 is asked first, and that order is a measurement rather than a preference.** The first
+ * version of this asked WebGPU first, and on this machine it answered `amd rdna-4` where the built
+ * WebGL2 renderer answered `ANGLE (AMD, Vulkan 1.4.354 (AMD Radeon RX 9070 XT (RADV GFX1201)
+ * (0x00007550)), radv)` — the same part, two spellings, and only one of them carries a model
+ * number. That is not cosmetic: `GPUAdapterInfo` reports an *architecture bucket* to limit
+ * fingerprinting, so `adreno-7xx` is one string for both the 710 measured at 112 ms a frame and
+ * the 740 in a flagship, and the table above deliberately refuses to clamp it. The unmasked
+ * WebGL2 string says `Adreno (TM) 710` and the table does clamp that. Asking the API that names
+ * the part first therefore gives a **more accurate verdict on the devices this table exists for**,
+ * and it costs an adapter request less on every machine that answers.
+ *
+ * **So this can be more precise than the renderer's own `rendererName`, and a caller comparing
+ * the two should expect that** rather than read it as a fault: a WebGPU renderer on that phone
+ * knows only `adreno-7xx` and its internal clamp cannot fire, while a consumer that called this
+ * has the part number and can choose a profile the clamp could not reach.
+ *
+ * **What it costs** is one detached WebGL2 context, created and immediately handed back, and — only
+ * where that declines to name the part — one adapter request. An adapter request, not a device
+ * request, which is the cheap half of what `selectBackend` does. Only a consumer that asks pays it.
+ *
+ * **Why this rather than a callback inside `createRenderer`.** Handing the profile in as a function
+ * of the part was the alternative and was not taken: the WebGL2 name cannot be read off the real
+ * canvas before the profile is chosen anyway, since that canvas's `antialias` comes *from* the
+ * profile; and a fallback from WebGPU to WebGL2 mid-creation would have to call that function a
+ * second time with a different identity, which is a re-entrancy trap inside the one function every
+ * consumer calls. This keeps the decision in the consumer's hands and the signature unchanged.
+ *
+ * **Nothing here throws.** A machine that will name itself through neither API is an ordinary
+ * outcome and answers `source: 'none'` with an empty name — which `isWeakGpuFamily` reads as *not
+ * weak*, the same "unknown is not weak" rule the table is built on. A caller gets the good profile
+ * and `ResolutionGovernor` corrects it from measurement, which is the design.
+ */
+export declare function describeGpu(options?: DescribeGpuOptions): Promise<GpuIdentity>;

package/dist/render/gpuCapability.js

@@ -0,0 +1,194 @@
+/**
+ * A hint, from the renderer string, about whether this part can hold the good profile.
+ *
+ * **It is a hint and never the authority.** A device database is a thing to maintain and
+ * it is wrong about every GPU nobody has tested, so the unknown case is deliberately *not*
+ * weak: guessing weak on the unknown would ship a soft picture to every device released
+ * after this line was written. `ResolutionGovernor` is what corrects a wrong guess, in both
+ * directions, from measurement rather than from a table.
+ *
+ * The families listed are the ones this project has evidence for, and each is a
+ * measurement rather than a reputation:
+ *
+ * - **Adreno 5xx/6xx and 70x/71x** — `NFD6QQ`, an Adreno 619 at 156.66 ms a frame that
+ *   then lost its context outright, and `JBL3XG`, an Adreno 710 at 112 ms. Both were
+ *   opened at the desktop profile because the default quality is a constant.
+ * - **Intel HD/UHD** — a UHD 630 that was unplayable fullscreen and *"perfetto"* in a
+ *   small window, which is the signature of a part using system RAM as VRAM.
+ * - **Mali-G3x/G5x and PowerVR** — the same class as those Adrenos by every public number.
+ *   No report from either yet; listed because the cost of being wrong is a picture one
+ *   step softer than it needed to be, and the cost of omitting them is another `NFD6QQ`.
+ *
+ * Adreno 72x-8xx and the Immortalis Malis are excluded on purpose. `JBL3XG`'s 710 is the
+ * one 7xx data point and it belongs to the mid-range; the flagships hold the budget. If a
+ * second 7xx report lands, move that whole family here rather than special-casing a number.
+ */
+/**
+ * **WebGPU does not hand out part numbers, and that changes what this table can match.**
+ *
+ * `UNMASKED_RENDERER_WEBGL` gives a string like `ANGLE (Qualcomm, Adreno (TM) 619, OpenGL ES
+ * 3.2)`. `GPUAdapterInfo` deliberately does not: it reports a vendor and an *architecture
+ * bucket*, to reduce fingerprinting entropy. Measured on this machine, an RX 9070 XT reports
+ * `vendor: "amd", architecture: "rdna-4"` and nothing else — no model, no description.
+ *
+ * So the patterns below have to recognise both shapes, and the bucketed one costs precision:
+ * `adreno-7xx` cannot distinguish the 710 that was measured at 112 ms a frame from the 740 in
+ * a current flagship. **It is therefore deliberately absent**, on the same reasoning that keeps
+ * the unknown part unclamped — guessing weak is a soft picture for somebody who did not need
+ * one, and `ResolutionGovernor` corrects a wrong guess from measurement in either direction.
+ *
+ * The bucket spellings are inferred from the specification's vocabulary rather than read off a
+ * device this project owns, so a phone that ought to clamp and does not is a bug in these two
+ * lines rather than in the mechanism. `Renderer.rendererName` is reported in the game's boot
+ * log for exactly that reason: the string a real device gives settles it in one message.
+ */
+const WEAK_ARCHITECTURES = [/adreno-[56]xx/, /mali-g[35]x/];
+const WEAK_FAMILIES = [
+    ...WEAK_ARCHITECTURES,
+    // Adreno 5xx and 6xx entirely, plus the 700 and 710 mid-range.
+    /adreno\s*(?:\(tm\))?\s*[56]\d\d/,
+    /adreno\s*(?:\(tm\))?\s*7[01]\d/,
+    // `Intel(R) HD Graphics 520`, `Intel(R) UHD Graphics 630`, and the same without the (R).
+    /intel(?:\(r\))?\s+u?hd\s+graphics/,
+    // Mali-G31 through G57. The Immortalis and G6xx/G7xx parts are not here.
+    /mali-g[35]\d/,
+    /powervr/,
+];
+/** Whether this renderer string names a part known to struggle with the good profile. */
+export function isWeakGpuFamily(rendererName) {
+    const name = rendererName.toLowerCase();
+    return WEAK_FAMILIES.some((pattern) => pattern.test(name));
+}
+/**
+ * What a WebGPU adapter calls the part, in the shape the table above matches.
+ *
+ * **Here rather than inline in `selectBackend`, because two callers need the identical string.**
+ * The backend selection builds it to hand the renderer a part number for the clamp, and
+ * `describeGpu` builds it to answer a consumer choosing a profile *before* a renderer exists. Two
+ * spellings of this join is the 2026-08-13 rule's first clause exactly: one decision, two
+ * implementations, and the drift shows up as a clamp that fires in one path and not the other.
+ *
+ * Every field is optional and browsers withhold them to differing degrees, so they are joined
+ * rather than formatted: a string with a vendor and nothing else is still something the table can
+ * recognise. An empty result falls back to the literal `WebGPU`, so nothing that prints it gets a
+ * blank — which is also why `isWeakGpuFamily('WebGPU')` is false and must stay false.
+ */
+export function adapterRendererName(info) {
+    return ([info?.description, info?.vendor, info?.architecture, info?.device]
+        .filter((part) => typeof part === 'string' && part.length > 0)
+        .join(' ')
+        .trim() || 'WebGPU');
+}
+/**
+ * What a WebGL2 context calls the part.
+ *
+ * `WEBGL_debug_renderer_info` is an extension and a browser may withhold it, so the empty string
+ * is an ordinary answer and not a failure — `isWeakGpuFamily('')` is false, which is the same
+ * "unknown is not weak" rule the table above is built on.
+ */
+export function webgl2RendererName(gl) {
+    const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
+    if (debugInfo === null)
+        return '';
+    return String(gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) ?? '');
+}
+const UNKNOWN = { rendererName: '', weak: false, source: 'none' };
+/**
+ * Ask what part this machine has, **before** building a renderer.
+ *
+ * **The gap this closes:** `isWeakGpuFamily` is exported for a consumer to classify the part it is
+ * running on, and until now the only string to hand it arrived on a renderer that had already been
+ * constructed — by which time the profile has been consumed and, as `applyResolutionScale` puts
+ * it, everything except the pixel density is memory allocated at construction. So the one function
+ * the engine offers for this decision took an argument the engine would not give you in time.
+ * Reported from outside 2026-08-28, by a consumer that had fallen back to `(pointer: coarse)`
+ * instead: a good proxy, right about a phone and wrong about a weak desktop, which is exactly the
+ * case `isWeakGpuFamily` exists for.
+ *
+ * **WebGL2 is asked first, and that order is a measurement rather than a preference.** The first
+ * version of this asked WebGPU first, and on this machine it answered `amd rdna-4` where the built
+ * WebGL2 renderer answered `ANGLE (AMD, Vulkan 1.4.354 (AMD Radeon RX 9070 XT (RADV GFX1201)
+ * (0x00007550)), radv)` — the same part, two spellings, and only one of them carries a model
+ * number. That is not cosmetic: `GPUAdapterInfo` reports an *architecture bucket* to limit
+ * fingerprinting, so `adreno-7xx` is one string for both the 710 measured at 112 ms a frame and
+ * the 740 in a flagship, and the table above deliberately refuses to clamp it. The unmasked
+ * WebGL2 string says `Adreno (TM) 710` and the table does clamp that. Asking the API that names
+ * the part first therefore gives a **more accurate verdict on the devices this table exists for**,
+ * and it costs an adapter request less on every machine that answers.
+ *
+ * **So this can be more precise than the renderer's own `rendererName`, and a caller comparing
+ * the two should expect that** rather than read it as a fault: a WebGPU renderer on that phone
+ * knows only `adreno-7xx` and its internal clamp cannot fire, while a consumer that called this
+ * has the part number and can choose a profile the clamp could not reach.
+ *
+ * **What it costs** is one detached WebGL2 context, created and immediately handed back, and — only
+ * where that declines to name the part — one adapter request. An adapter request, not a device
+ * request, which is the cheap half of what `selectBackend` does. Only a consumer that asks pays it.
+ *
+ * **Why this rather than a callback inside `createRenderer`.** Handing the profile in as a function
+ * of the part was the alternative and was not taken: the WebGL2 name cannot be read off the real
+ * canvas before the profile is chosen anyway, since that canvas's `antialias` comes *from* the
+ * profile; and a fallback from WebGPU to WebGL2 mid-creation would have to call that function a
+ * second time with a different identity, which is a re-entrancy trap inside the one function every
+ * consumer calls. This keeps the decision in the consumer's hands and the signature unchanged.
+ *
+ * **Nothing here throws.** A machine that will name itself through neither API is an ordinary
+ * outcome and answers `source: 'none'` with an empty name — which `isWeakGpuFamily` reads as *not
+ * weak*, the same "unknown is not weak" rule the table is built on. A caller gets the good profile
+ * and `ResolutionGovernor` corrects it from measurement, which is the design.
+ */
+export async function describeGpu(options = {}) {
+    const named = (rendererName, source) => ({
+        rendererName,
+        weak: isWeakGpuFamily(rendererName),
+        source,
+    });
+    /* WebGL2 first: it is the API that gives a model number. See the header for the measurement. */
+    const canvas = options.createCanvas === undefined
+        ? (globalThis.document?.createElement('canvas') ?? null)
+        : options.createCanvas();
+    if (canvas !== null) {
+        let gl = null;
+        try {
+            gl = canvas.getContext('webgl2');
+        }
+        catch {
+            gl = null;
+        }
+        if (gl !== null) {
+            const name = webgl2RendererName(gl);
+            /*
+             * Handed back promptly rather than left to the collector. A detached canvas holding a live
+             * context is a GPU allocation nothing will use again, and a boot that leaks one on every
+             * consumer is the kind of cost this function has no business adding.
+             */
+            gl.getExtension('WEBGL_lose_context')?.loseContext();
+            if (name !== '')
+                return named(name, 'webgl2');
+        }
+    }
+    /*
+     * Only where WebGL2 declined to name the part — a browser withholding
+     * `WEBGL_debug_renderer_info`, or one with no WebGL2 at all. The bucketed adapter string is
+     * less precise and is better than nothing.
+     */
+    if (options.preferWebGpu ?? true) {
+        const gpu = options.gpu === undefined ? globalThis.navigator?.gpu : options.gpu;
+        if (gpu != null) {
+            try {
+                const adapter = await gpu.requestAdapter();
+                /*
+                 * A browser that offers no adapter has told us nothing about the part, so this answers
+                 * unknown rather than `WebGPU` — the literal the join defaults to would be a name nobody
+                 * can act on standing where the absence of one is the honest answer.
+                 */
+                if (adapter !== null)
+                    return named(adapterRendererName(adapter.info), 'webgpu');
+            }
+            catch {
+                /* An adapter request that throws is a machine without usable WebGPU. */
+            }
+        }
+    }
+    return UNKNOWN;
+}

package/dist/render/gpuTimer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * How long the GPU actually spent, in three parts.
+ *
+ * Wall clock cannot answer this. It is vsync-capped long before a GPU is saturated, so
+ * every configuration from Low to 4K High reads the same on a clock while the GPU times
+ * behind them span 13.5x. That gap is the difference between a machine with headroom and
+ * one running the game at 3 fps.
+ *
+ * **The frame is partitioned, not nested.** `TIME_ELAPSED_EXT` cannot nest, so there is
+ * no whole-frame query wrapped around two inner ones — three sequential brackets sum to
+ * the frame instead, and `rest` earns its slot by being the number that says *this one
+ * is not shadows*.
+ *
+ * Sampled one frame in eight. Seven samples a second is ample for a distribution, and it
+ * removes any argument about query overhead on drivers nobody here owns.
+ */
+import type { FrameTimer } from './backend/timer.ts';
+export declare const GPU_SLOTS: readonly ['shadows', 'reflection', 'rest'];
+export type GpuSlot = (typeof GPU_SLOTS)[number];
+/** Milliseconds per bracket. */
+export interface GpuSample {
+    readonly shadows: number;
+    readonly reflection: number;
+    readonly rest: number;
+}
+export declare class GpuTimer implements FrameTimer {
+    private readonly gl;
+    /** False where the extension is missing or disabled, which is a normal state. */
+    readonly available: boolean;
+    /** Samples the driver said were untrustworthy. Reported, never silently dropped. */
+    disjointDrops: number;
+    /**
+     * The last sample `poll` resolved, held so `lastFrameMs` can answer without re-reading.
+     *
+     * Null until one resolves, and null is the honest answer for a device with no extension:
+     * unmeasured is not zero.
+     */
+    private lastSample;
+    private readonly ext;
+    private readonly sampleEvery;
+    /** Completed triples waiting to be read, oldest first. */
+    private readonly inFlight;
+    private current;
+    private open;
+    private frame;
+    private measuring;
+    /** Whether `beginFrame` said yes for the frame being drawn. */
+    get sampling(): boolean;
+    constructor(gl: WebGL2RenderingContext, sampleEvery?: number);
+    /**
+     * Whether this frame is measured. Call once per frame, before any `begin`.
+     *
+     * `begin` and `end` do nothing on an unmeasured frame, so the skipped frames really
+     * are free rather than merely cheap.
+     */
+    beginFrame(): boolean;
+    /**
+     * Close the frame and queue it for reading.
+     *
+     * Explicit rather than counting to three, because the shadow pass runs **several
+     * times a frame** — static, the depth peel, then dynamic — and the reflection pass
+     * may not run at all when water is off. A frame is over when the caller says so,
+     * and `poll` sums the brackets per slot, so three shadow passes are one shadow
+     * number rather than three partial ones.
+     */
+    endFrame(): void;
+    /**
+     * Open a bracket. Never two at once — `TIME_ELAPSED_EXT` cannot nest, and the
+     * partition is what guarantees `end` runs before the next `begin`.
+     */
+    begin(slot: GpuSlot): void;
+    end(): void;
+    /**
+     * The oldest finished sample, or null. Never blocks and never waits for a result:
+     * a diagnostic that stalls the pipeline to measure it is measuring itself.
+     */
+    poll(): GpuSample | null;
+    /**
+     * The whole of the last resolved frame, in milliseconds, or null where nothing measured.
+     *
+     * The three brackets are summed because they partition the frame rather than overlapping:
+     * `shadows` and `reflection` are the passes drawn before the scene, `rest` is everything
+     * after. A caller wanting the breakdown reads `poll`, which is what the frame meter does.
+     */
+    lastFrameMs(): number | null;
+    dispose(): void;
+}

package/dist/render/gpuTimer.js

@@ -0,0 +1,145 @@
+export const GPU_SLOTS = ['shadows', 'reflection', 'rest'];
+/** In flight at once. Past this a frame is skipped rather than allocating. */
+const POOL_DEPTH = 4;
+const NS_PER_MS = 1e6;
+export class GpuTimer {
+    gl;
+    /** False where the extension is missing or disabled, which is a normal state. */
+    available;
+    /** Samples the driver said were untrustworthy. Reported, never silently dropped. */
+    disjointDrops = 0;
+    /**
+     * The last sample `poll` resolved, held so `lastFrameMs` can answer without re-reading.
+     *
+     * Null until one resolves, and null is the honest answer for a device with no extension:
+     * unmeasured is not zero.
+     */
+    lastSample = null;
+    ext;
+    sampleEvery;
+    /** Completed triples waiting to be read, oldest first. */
+    inFlight = [];
+    current = null;
+    open = false;
+    frame = 0;
+    measuring = false;
+    /** Whether `beginFrame` said yes for the frame being drawn. */
+    get sampling() {
+        return this.measuring;
+    }
+    constructor(gl, sampleEvery = 8) {
+        this.gl = gl;
+        this.ext = gl.getExtension('EXT_disjoint_timer_query_webgl2');
+        this.available = this.ext !== null;
+        this.sampleEvery = Math.max(1, Math.floor(sampleEvery));
+    }
+    /**
+     * Whether this frame is measured. Call once per frame, before any `begin`.
+     *
+     * `begin` and `end` do nothing on an unmeasured frame, so the skipped frames really
+     * are free rather than merely cheap.
+     */
+    beginFrame() {
+        if (this.ext === null)
+            return false;
+        const measured = this.frame % this.sampleEvery === 0;
+        this.frame++;
+        this.measuring = measured && this.inFlight.length < POOL_DEPTH;
+        if (this.measuring)
+            this.current = { queries: [], slots: [] };
+        return this.measuring;
+    }
+    /**
+     * Close the frame and queue it for reading.
+     *
+     * Explicit rather than counting to three, because the shadow pass runs **several
+     * times a frame** — static, the depth peel, then dynamic — and the reflection pass
+     * may not run at all when water is off. A frame is over when the caller says so,
+     * and `poll` sums the brackets per slot, so three shadow passes are one shadow
+     * number rather than three partial ones.
+     */
+    endFrame() {
+        if (!this.measuring || this.current === null)
+            return;
+        if (this.current.queries.length > 0)
+            this.inFlight.push(this.current);
+        this.current = null;
+        this.measuring = false;
+    }
+    /**
+     * Open a bracket. Never two at once — `TIME_ELAPSED_EXT` cannot nest, and the
+     * partition is what guarantees `end` runs before the next `begin`.
+     */
+    begin(slot) {
+        if (!this.measuring || this.ext === null || this.open)
+            return;
+        const query = this.gl.createQuery();
+        if (query === null)
+            return;
+        this.gl.beginQuery(this.ext.TIME_ELAPSED_EXT, query);
+        this.current?.queries.push(query);
+        this.current?.slots.push(slot);
+        this.open = true;
+    }
+    end() {
+        if (!this.measuring || this.ext === null || !this.open)
+            return;
+        this.gl.endQuery(this.ext.TIME_ELAPSED_EXT);
+        this.open = false;
+    }
+    /**
+     * The oldest finished sample, or null. Never blocks and never waits for a result:
+     * a diagnostic that stalls the pipeline to measure it is measuring itself.
+     */
+    poll() {
+        if (this.ext === null)
+            return null;
+        const oldest = this.inFlight[0];
+        if (oldest === undefined)
+            return null;
+        for (const query of oldest.queries) {
+            const ready = this.gl.getQueryParameter(query, this.gl.QUERY_RESULT_AVAILABLE);
+            if (!ready)
+                return null;
+        }
+        this.inFlight.shift();
+        const disjoint = this.gl.getParameter(this.ext.GPU_DISJOINT_EXT);
+        if (disjoint) {
+            this.disjointDrops++;
+            for (const query of oldest.queries)
+                this.gl.deleteQuery(query);
+            return null;
+        }
+        // Summed per slot, not assigned: the shadow pass runs once per layer, so a frame
+        // holds several `shadows` brackets and the answer is their total.
+        const parts = { shadows: 0, reflection: 0, rest: 0 };
+        for (let i = 0; i < oldest.queries.length; i++) {
+            const query = oldest.queries[i];
+            const slot = oldest.slots[i];
+            parts[slot] += this.gl.getQueryParameter(query, this.gl.QUERY_RESULT) / NS_PER_MS;
+            this.gl.deleteQuery(query);
+        }
+        this.lastSample = parts;
+        return parts;
+    }
+    /**
+     * The whole of the last resolved frame, in milliseconds, or null where nothing measured.
+     *
+     * The three brackets are summed because they partition the frame rather than overlapping:
+     * `shadows` and `reflection` are the passes drawn before the scene, `rest` is everything
+     * after. A caller wanting the breakdown reads `poll`, which is what the frame meter does.
+     */
+    lastFrameMs() {
+        if (this.lastSample === null)
+            return null;
+        return this.lastSample.shadows + this.lastSample.reflection + this.lastSample.rest;
+    }
+    dispose() {
+        for (const pending of this.inFlight) {
+            for (const query of pending.queries)
+                this.gl.deleteQuery(query);
+        }
+        this.inFlight.length = 0;
+        this.current = null;
+    }
+}

package/dist/render/halfFloat.d.ts

@@ -0,0 +1,4 @@
+/** IEEE 754 binary16 conversion, shared by everything that has to hand a device half floats. */
+export declare function halfBits(value: number): number;
+/** A whole array of floats as binary16, which is what a `r16float` or `rgba16float` upload wants. */
+export declare function toHalfFloats(values: Float32Array): Uint16Array;

package/dist/render/halfFloat.js

@@ -0,0 +1,38 @@
+/** IEEE 754 binary16 conversion, shared by everything that has to hand a device half floats. */
+/** IEEE 754 binary16, via a float32 view, which is the only exact way to read the bits. */
+const conversion = new ArrayBuffer(4);
+const asFloat = new Float32Array(conversion);
+const asUint = new Uint32Array(conversion);
+export function halfBits(value) {
+    asFloat[0] = value;
+    const bits = asUint[0] ?? 0;
+    const sign = (bits >>> 16) & 0x8000;
+    let exponent = (bits >>> 23) & 0xff;
+    let mantissa = bits & 0x7fffff;
+    /* Infinity and NaN carry straight across; a NaN must stay a NaN rather than becoming infinity. */
+    if (exponent === 0xff)
+        return sign | 0x7c00 | (mantissa === 0 ? 0 : 0x200);
+    /* Rebias 127 to 15. Above half's range saturates to infinity rather than wrapping to zero. */
+    exponent = exponent - 127 + 15;
+    if (exponent >= 0x1f)
+        return sign | 0x7c00;
+    if (exponent <= 0) {
+        /*
+         * Subnormal. An environment's darkest texels live here, and flushing them to zero is what
+         * makes a night sky's gradient band — so they are shifted rather than discarded.
+         */
+        if (exponent < -10)
+            return sign;
+        mantissa |= 0x800000;
+        const shift = 14 - exponent;
+        return sign | (mantissa >>> shift);
+    }
+    return sign | (exponent << 10) | (mantissa >>> 13);
+}
+/** A whole array of floats as binary16, which is what a `r16float` or `rgba16float` upload wants. */
+export function toHalfFloats(values) {
+    const out = new Uint16Array(values.length);
+    for (let i = 0; i < values.length; i++)
+        out[i] = halfBits(values[i] ?? 0);
+    return out;
+}

package/dist/render/handleRegistry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A slot table addressed by generational handles.
+ *
+ * **The handle arithmetic, and nothing about what a handle names.** It came out of `pass.ts`
+ * when a second registry wanted exactly this: two copies of a generation rule are two chances to
+ * get the invalidation wrong, and the failure mode is a handle answering to whoever took its slot
+ * next — a use-after-free that reads as a leak.
+ *
+ * The definition type is a parameter rather than a union of the two kinds it holds. A union would
+ * oblige every caller to narrow a value it already knows the type of, and would make adding a
+ * third kind an edit to this file rather than to the caller that wanted it.
+ */
+export interface HandleRegistry<T> {
+    definitions: (T | undefined)[];
+    /** Bumped whenever a slot is released, which is what invalidates the handles that named it. */
+    generations: number[];
+    /** Slots released and not yet reused, so registration does not grow the array forever. */
+    free: number[];
+}
+export declare function createHandleRegistry<T>(): HandleRegistry<T>;
+/**
+ * Take a slot and return the handle that names it.
+ *
+ * Handles start at 1: zero is a generation-0 slot-0 handle and would be indistinguishable from
+ * the number a caller gets from an uninitialised field, so generations start at 1 instead.
+ */
+export declare function registerIn<T>(registry: HandleRegistry<T>, definition: T): number;
+/** The definition a handle names, or `undefined` if it names one that has been released. */
+export declare function definitionAt<T>(registry: HandleRegistry<T>, handle: number): T | undefined;
+/**
+ * Release a slot.
+ *
+ * Guarded on the handle still being live, so calling it twice frees the slot once — a slot
+ * pushed onto `free` twice is a slot handed to two different definitions.
+ */
+export declare function unregisterIn<T>(registry: HandleRegistry<T>, handle: number): T | undefined;
+/**
+ * Release every slot still held, handing each definition to the caller on the way out.
+ *
+ * **Teardown's half of `unregisterIn`, and it was missing.** Both renderers hold registries like
+ * this one and neither emptied one when it was disposed, so a definition kept whatever `init`
+ * built — a pipeline, a bind group, its buffers — for as long as the process lived. A private
+ * field going out of scope is not a GPU object being destroyed. Written here rather than once per
+ * backend for the reason this module exists at all: two copies of a lifetime rule are two chances
+ * to get it wrong, and the one that is wrong is the one nobody reads.
+ *
+ * `release` is the caller's, because the device object a definition must be handed is the only
+ * part of this that is per-backend — and on one of them there is a condition on handing it over
+ * at all.
+ *
+ * Each slot is released *before* its definition is told, so a `release` that reaches back into
+ * this registry finds a slot already gone rather than one it can free twice.
+ */
+export declare function drainRegistry<T>(registry: HandleRegistry<T>, release: (definition: T) => void): void;