@driftengine/core 3.61.0

package/src/render/gpuCapability.ts

@@ -0,0 +1,244 @@
+/**
+ * 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: readonly RegExp[] = [/adreno-[56]xx/, /mali-g[35]x/];
+
+const WEAK_FAMILIES: readonly RegExp[] = [
+  ...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: string): boolean {
+  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: GPUAdapterInfo | undefined): string {
+  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: WebGL2RenderingContext): string {
+  const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
+  if (debugInfo === null) return '';
+  return String((gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) as unknown) ?? '');
+}
+
+/** 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;
+}
+
+const UNKNOWN: GpuIdentity = { 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: DescribeGpuOptions = {}): Promise<GpuIdentity> {
+  const named = (rendererName: string, source: 'webgpu' | 'webgl2'): GpuIdentity => ({
+    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: WebGL2RenderingContext | null = 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/src/render/gpuTimer.ts

@@ -0,0 +1,182 @@
+/**
+ * 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 const GPU_SLOTS = ['shadows', 'reflection', 'rest'] as const;
+
+export type GpuSlot = (typeof GPU_SLOTS)[number];
+
+/** Milliseconds per bracket. */
+export interface GpuSample {
+  readonly shadows: number;
+  readonly reflection: number;
+  readonly rest: number;
+}
+
+interface TimerExtension {
+  readonly TIME_ELAPSED_EXT: number;
+  readonly GPU_DISJOINT_EXT: number;
+}
+
+/** 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 implements FrameTimer {
+  /** 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 = 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.
+   */
+  private lastSample: GpuSample | null = null;
+
+  private readonly ext: TimerExtension | null;
+  private readonly sampleEvery: number;
+  /** Completed triples waiting to be read, oldest first. */
+  private readonly inFlight: { queries: WebGLQuery[]; slots: GpuSlot[] }[] = [];
+  private current: { queries: WebGLQuery[]; slots: GpuSlot[] } | null = null;
+  private open = false;
+  private frame = 0;
+  private measuring = false;
+  /** Whether `beginFrame` said yes for the frame being drawn. */
+  get sampling(): boolean {
+    return this.measuring;
+  }
+
+  constructor(
+    private readonly gl: WebGL2RenderingContext,
+    sampleEvery = 8,
+  ) {
+    this.ext = gl.getExtension('EXT_disjoint_timer_query_webgl2') as TimerExtension | null;
+    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(): boolean {
+    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(): void {
+    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: GpuSlot): void {
+    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(): void {
+    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(): GpuSample | null {
+    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) as boolean;
+      if (!ready) return null;
+    }
+    this.inFlight.shift();
+
+    const disjoint = this.gl.getParameter(this.ext.GPU_DISJOINT_EXT) as boolean;
+    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: Record<GpuSlot, number> = { shadows: 0, reflection: 0, rest: 0 };
+    for (let i = 0; i < oldest.queries.length; i++) {
+      const query = oldest.queries[i] as WebGLQuery;
+      const slot = oldest.slots[i] as GpuSlot;
+      parts[slot] += (this.gl.getQueryParameter(query, this.gl.QUERY_RESULT) as number) / 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(): number | null {
+    if (this.lastSample === null) return null;
+    return this.lastSample.shadows + this.lastSample.reflection + this.lastSample.rest;
+  }
+
+  dispose(): void {
+    for (const pending of this.inFlight) {
+      for (const query of pending.queries) this.gl.deleteQuery(query);
+    }
+    this.inFlight.length = 0;
+    this.current = null;
+  }
+}

package/src/render/halfFloat.ts

@@ -0,0 +1,39 @@
+/** 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: number): number {
+  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: Float32Array): Uint16Array {
+  const out = new Uint16Array(values.length);
+  for (let i = 0; i < values.length; i++) out[i] = halfBits(values[i] ?? 0);
+  return out;
+}

package/src/render/handleRegistry.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+
+/** How many bits of a handle are the slot. 4,096 registered definitions is far past generous. */
+const SLOT_BITS = 12;
+const SLOT_MASK = (1 << SLOT_BITS) - 1;
+
+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 function createHandleRegistry<T>(): HandleRegistry<T> {
+  return { definitions: [], generations: [], free: [] };
+}
+
+/**
+ * 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 function registerIn<T>(registry: HandleRegistry<T>, definition: T): number {
+  const slot = registry.free.pop() ?? registry.definitions.length;
+  registry.definitions[slot] = definition;
+  registry.generations[slot] ??= 1;
+  return ((registry.generations[slot] ?? 1) << SLOT_BITS) | slot;
+}
+
+/** The definition a handle names, or `undefined` if it names one that has been released. */
+export function definitionAt<T>(registry: HandleRegistry<T>, handle: number): T | undefined {
+  if (handle <= 0) return undefined;
+  const slot = handle & SLOT_MASK;
+  if (registry.generations[slot] !== handle >>> SLOT_BITS) return undefined;
+  return registry.definitions[slot];
+}
+
+/**
+ * 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 function unregisterIn<T>(registry: HandleRegistry<T>, handle: number): T | undefined {
+  const definition = definitionAt(registry, handle);
+  if (definition === undefined) return undefined;
+  const slot = handle & SLOT_MASK;
+  registry.definitions[slot] = undefined;
+  registry.generations[slot] = (registry.generations[slot] ?? 1) + 1;
+  registry.free.push(slot);
+  return definition;
+}
+
+/**
+ * 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 function drainRegistry<T>(
+  registry: HandleRegistry<T>,
+  release: (definition: T) => void,
+): void {
+  for (let slot = 0; slot < registry.definitions.length; slot += 1) {
+    if (registry.definitions[slot] === undefined) continue;
+    /* Rebuilt rather than remembered: the generation bump that invalidates the handles naming
+       this slot is `unregisterIn`'s to make, and making it twice is how a slot is freed twice. */
+    const handle = ((registry.generations[slot] ?? 1) << SLOT_BITS) | slot;
+    const definition = unregisterIn(registry, handle);
+    if (definition !== undefined) release(definition);
+  }
+}