@jbrowse/render-core 4.3.0

package/esm/graphicsCapabilities.d.ts

@@ -0,0 +1,98 @@
+export interface GraphicsCapabilities {
+    webgpu: boolean;
+    /**
+     * `undefined` when the WebGL2 probe was skipped, which is what
+     * `getGraphicsCapabilities` does whenever WebGPU answered first — see there.
+     */
+    webgl2?: boolean;
+    gpuVendor?: string;
+    gpuArchitecture?: string;
+    /**
+     * `UNMASKED_RENDERER_WEBGL` from the WebGL2 probe — the real driver string
+     * ("SwiftShader Device", "Mesa Intel(R) UHD Graphics 630"), not the masked
+     * one, which is a fixed placeholder. Present only when the probe ran (no
+     * WebGPU) and the browser exposes `WEBGL_debug_renderer_info`; Firefox with
+     * `privacy.resistFingerprinting` does not. It identifies hardware far more
+     * precisely than `gpuVendor`/`gpuArchitecture` do, so like them it stays
+     * local — the stack-trace dialog the user chooses to copy — and never goes to
+     * analytics. `softwareWebgl` is the coarse bit that does.
+     */
+    glRenderer?: string;
+    /**
+     * Whether that driver string names a software rasterizer. `undefined` means
+     * unknown (no probe, or no extension), which is deliberately not `false`: the
+     * distinction is the whole value of the field.
+     */
+    softwareWebgl?: boolean;
+}
+/**
+ * The rungs of the rendering ladder, as the names a person reads — the About
+ * widget's "Graphics:" line, the stack-trace dialog, the analytics field.
+ *
+ * Deliberately *not* the {@link GpuOverride} vocabulary, which is what a user
+ * types into `?renderer=` and therefore carries lowercase spellings and the
+ * `webgl`/`canvas` aliases. One is an input to parse, the other an answer to
+ * display, and collapsing them would mean either showing "canvas2d" in the UI
+ * or accepting "Canvas2D" in a URL.
+ */
+export type RendererName = 'WebGPU' | 'WebGL2' | 'Canvas2D';
+/**
+ * Whether a `UNMASKED_RENDERER_WEBGL` string names a software rasterizer, where
+ * WebGL costs ~25x Canvas2D on the main thread for the same session (measured;
+ * on real hardware the ordering reverses at ~2x). Exported for its test — the
+ * marker list is the part that can be wrong.
+ */
+export declare function isSoftwareRenderer(glRenderer: string): boolean;
+/**
+ * What this machine can do, memoized for the page: capabilities cannot change
+ * within a session, and every call that probed again was another WebGL2 context
+ * (each reopening of the About widget or the stack-trace dialog made one).
+ *
+ * **The WebGL2 probe is skipped when WebGPU is available**, leaving `webgl2`
+ * undefined, because it is the rung below and nothing reads it:
+ * {@link effectiveRenderer} returns WebGPU regardless. So a WebGPU machine
+ * creates no WebGL2 context at all.
+ *
+ * Nothing needs the skipped rung resolved, and a "probe everything" variant was
+ * deleted for it: {@link effectiveRenderer} already encodes the whole capability
+ * vector, since `Canvas2D` means neither rung exists and `WebGL2` means WebGPU
+ * is missing. The only bit a full probe adds is whether a WebGPU machine *also*
+ * has WebGL2 — which no shipping browser answers no to, and which nothing would
+ * do anything with. Report the effective renderer instead of a list.
+ *
+ * This is capabilities alone. What will actually draw is
+ * {@link effectiveRenderer}, which is this plus the page-wide pin.
+ */
+export declare function getGraphicsCapabilities(): Promise<GraphicsCapabilities>;
+/**
+ * Which rung will actually draw — the ladder in `createGpuHal`, read as an
+ * answer rather than run. This is the question every consumer asks (the About
+ * widget's "Graphics:" line, the stack-trace dialog's environment block, the
+ * analytics field), and answering it needs both halves: what the machine can do
+ * *and* the page-wide pin from `?renderer=` or the GPU-error banner's "disable
+ * GPU" button.
+ *
+ * The pin is checked first and wins outright, because **a pin never falls
+ * through to the next rung** — `createGpuHal` throws instead, on the reasoning
+ * that a pinned renderer which silently substitutes another makes any
+ * comparison against it wrong. So the pinned rung *is* the answer, and a pin
+ * that cannot be honored surfaces as a `renderError` rather than as a different
+ * string here. That is what makes this exact rather than a guess: the one case
+ * it cannot resolve from capabilities alone (`?renderer=webgl` on a WebGPU
+ * machine, where the WebGL2 probe was skipped) is also the case where the pin
+ * decides on its own.
+ *
+ * **`softwareWebgl` skips the WebGL2 rung here because it skips it there**, and
+ * only where the ladder skips it — unpinned. Leaving it out is not a rounding
+ * error on a rare machine: the VM, the locked-down laptop and the remote desktop
+ * are exactly the population the rung-skip exists for, so the one group that
+ * newly falls back was the one group still reported as WebGL2, in the About box,
+ * in the stack traces users paste into bug reports, and in the analytics field
+ * whose stated purpose is counting that fallback.
+ *
+ * Keeping this beside `gpuDevice` is the point of the module living in
+ * render-core: it was previously in `@jbrowse/core`, which cannot see the
+ * override, so every consumer reported the capability answer and a user who had
+ * clicked "Use Canvas2D" was still reported as WebGL2.
+ */
+export declare function effectiveRenderer(c: GraphicsCapabilities): RendererName;

package/esm/graphicsCapabilities.js

@@ -0,0 +1,165 @@
+import { getGpuOverride, isGpuRenderingDisabled } from './gpuDevice.js';
+// Substrings of UNMASKED_RENDERER_WEBGL that mean "no GPU is involved". Kept
+// conservative and specific — a wrong `true` here would describe a real GPU as
+// software, and the reports built from it are what a later ladder decision would
+// rest on. Chrome's SwiftShader arrives as an ANGLE string ("ANGLE (Google,
+// Vulkan 1.3.0 (SwiftShader Device ...))"), which is why these are substring
+// tests rather than equality.
+const SOFTWARE_RENDERER_MARKERS = [
+    'swiftshader',
+    'llvmpipe',
+    'lavapipe',
+    'softpipe',
+    'software rasterizer',
+    'software renderer',
+    'microsoft basic render driver',
+];
+/**
+ * Whether a `UNMASKED_RENDERER_WEBGL` string names a software rasterizer, where
+ * WebGL costs ~25x Canvas2D on the main thread for the same session (measured;
+ * on real hardware the ordering reverses at ~2x). Exported for its test — the
+ * marker list is the part that can be wrong.
+ */
+export function isSoftwareRenderer(glRenderer) {
+    const lower = glRenderer.toLowerCase();
+    return SOFTWARE_RENDERER_MARKERS.some(marker => lower.includes(marker));
+}
+async function probeWebgpu() {
+    try {
+        // navigator.gpu is typed non-nullable but is undefined without WebGPU
+        // support, so the try/catch guards that access as well as adapter failures
+        const adapter = await navigator.gpu.requestAdapter();
+        return adapter
+            ? {
+                webgpu: true,
+                // coarse, non-fingerprinting fields (e.g. "nvidia"/"apple") the
+                // browser exposes on purpose — surfaced only in the local stack-trace
+                // dialog
+                gpuVendor: adapter.info.vendor,
+                gpuArchitecture: adapter.info.architecture,
+            }
+            : { webgpu: false };
+    }
+    catch {
+        return { webgpu: false };
+    }
+}
+/**
+ * Whether a WebGL2 context can be created, which costs one. The context is not
+ * released with `WEBGL_lose_context.loseContext()`, deliberately: on Firefox
+ * that call is effectively driver-wide (ADR-005 removed it from
+ * `WebGL2Hal.dispose()` for the same reason), so probing while tracks were on
+ * screen knocked out their live sibling contexts — and both browsers log the
+ * loss to the console, which is what a user sees. The canvas is unreachable the
+ * moment this returns and the browser reclaims the context on GC, the same
+ * release the HAL relies on. A page that then reaches the 16-context ceiling
+ * evicts this one first (it is the oldest, and nothing draws to it or
+ * re-acquires it), so the eviction cascade in GPU_CONTEXT_BUDGET.md cannot
+ * start here.
+ *
+ * The driver string comes off the same context, so it is free where it matters:
+ * this only runs when WebGPU is absent, which is the population that renders on
+ * WebGL2 and so the only one whose rasterizer changes anything.
+ */
+function probeWebgl2() {
+    const canvas = document.createElement('canvas');
+    // 1x1 rather than the default 300x150: nothing is ever drawn, so the drawing
+    // buffer is pure waste until GC takes it
+    canvas.width = 1;
+    canvas.height = 1;
+    const gl = canvas.getContext('webgl2');
+    if (!gl) {
+        return { webgl2: false };
+    }
+    // UNMASKED_RENDERER_WEBGL, not RENDERER — the masked one is a fixed
+    // placeholder string ("WebKit WebGL") that names nothing
+    const ext = gl.getExtension('WEBGL_debug_renderer_info');
+    const glRenderer = ext
+        ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)
+        : null;
+    return glRenderer
+        ? {
+            webgl2: true,
+            glRenderer,
+            softwareWebgl: isSoftwareRenderer(glRenderer),
+        }
+        : { webgl2: true };
+}
+let capabilities;
+/**
+ * What this machine can do, memoized for the page: capabilities cannot change
+ * within a session, and every call that probed again was another WebGL2 context
+ * (each reopening of the About widget or the stack-trace dialog made one).
+ *
+ * **The WebGL2 probe is skipped when WebGPU is available**, leaving `webgl2`
+ * undefined, because it is the rung below and nothing reads it:
+ * {@link effectiveRenderer} returns WebGPU regardless. So a WebGPU machine
+ * creates no WebGL2 context at all.
+ *
+ * Nothing needs the skipped rung resolved, and a "probe everything" variant was
+ * deleted for it: {@link effectiveRenderer} already encodes the whole capability
+ * vector, since `Canvas2D` means neither rung exists and `WebGL2` means WebGPU
+ * is missing. The only bit a full probe adds is whether a WebGPU machine *also*
+ * has WebGL2 — which no shipping browser answers no to, and which nothing would
+ * do anything with. Report the effective renderer instead of a list.
+ *
+ * This is capabilities alone. What will actually draw is
+ * {@link effectiveRenderer}, which is this plus the page-wide pin.
+ */
+export function getGraphicsCapabilities() {
+    capabilities ??= probeWebgpu().then(gpu => gpu.webgpu ? gpu : { ...gpu, ...probeWebgl2() });
+    return capabilities;
+}
+/**
+ * Which rung will actually draw — the ladder in `createGpuHal`, read as an
+ * answer rather than run. This is the question every consumer asks (the About
+ * widget's "Graphics:" line, the stack-trace dialog's environment block, the
+ * analytics field), and answering it needs both halves: what the machine can do
+ * *and* the page-wide pin from `?renderer=` or the GPU-error banner's "disable
+ * GPU" button.
+ *
+ * The pin is checked first and wins outright, because **a pin never falls
+ * through to the next rung** — `createGpuHal` throws instead, on the reasoning
+ * that a pinned renderer which silently substitutes another makes any
+ * comparison against it wrong. So the pinned rung *is* the answer, and a pin
+ * that cannot be honored surfaces as a `renderError` rather than as a different
+ * string here. That is what makes this exact rather than a guess: the one case
+ * it cannot resolve from capabilities alone (`?renderer=webgl` on a WebGPU
+ * machine, where the WebGL2 probe was skipped) is also the case where the pin
+ * decides on its own.
+ *
+ * **`softwareWebgl` skips the WebGL2 rung here because it skips it there**, and
+ * only where the ladder skips it — unpinned. Leaving it out is not a rounding
+ * error on a rare machine: the VM, the locked-down laptop and the remote desktop
+ * are exactly the population the rung-skip exists for, so the one group that
+ * newly falls back was the one group still reported as WebGL2, in the About box,
+ * in the stack traces users paste into bug reports, and in the analytics field
+ * whose stated purpose is counting that fallback.
+ *
+ * Keeping this beside `gpuDevice` is the point of the module living in
+ * render-core: it was previously in `@jbrowse/core`, which cannot see the
+ * override, so every consumer reported the capability answer and a user who had
+ * clicked "Use Canvas2D" was still reported as WebGL2.
+ */
+export function effectiveRenderer(c) {
+    if (isGpuRenderingDisabled()) {
+        return 'Canvas2D';
+    }
+    const override = getGpuOverride();
+    if (override === 'webgl') {
+        return 'WebGL2';
+    }
+    if (override === 'webgpu') {
+        return 'WebGPU';
+    }
+    if (c.webgpu) {
+        return 'WebGPU';
+    }
+    // `softwareWebgl` is `undefined` where the browser withholds
+    // WEBGL_debug_renderer_info, and an unknown rasterizer keeps the rung — the
+    // same reading `createGpuHal` gives it.
+    if (c.webgl2 && !c.softwareWebgl) {
+        return 'WebGL2';
+    }
+    return 'Canvas2D';
+}

package/esm/hal/createHal.d.ts

@@ -0,0 +1,22 @@
+import type { GpuHal, PipelineDescriptor, SampleCount } from './types.ts';
+export interface GpuHalOptions {
+    passes: PipelineDescriptor[];
+    uniformByteSize: number;
+    /**
+     * Reaches the WebGPU rung only. The WebGL2 rung draws to the default
+     * framebuffer with `antialias: true`, so its multisampling is the browser's
+     * own and there is nothing here to thread into it.
+     */
+    sampleCount: SampleCount;
+    /**
+     * Out-parameter collecting why each rung declined, in ladder order. Falling
+     * through a rung is normal (no WebGPU on this machine) and stays a
+     * `console.warn` — but when the *last* rung fails too, the reasons the earlier
+     * ones gave are the diagnosis, and they used to exist only in a console the
+     * user reporting the bug never opens. `createRenderingBackend` attaches this
+     * to the error it throws, and the error UI's stack-trace dialog already walks
+     * `AggregateError.errors` (core's `formatErrorStack`), so they arrive with it.
+     */
+    failures?: unknown[];
+}
+export declare function createGpuHal(canvas: HTMLCanvasElement, { passes, uniformByteSize, sampleCount, failures }: GpuHalOptions): Promise<GpuHal | null>;

package/esm/hal/createHal.js

@@ -0,0 +1,91 @@
+import { getGpuOverride, isGpuRenderingDisabled } from '../gpuDevice.js';
+import { getGraphicsCapabilities } from '../graphicsCapabilities.js';
+import { WebGL2Hal } from './webgl2Hal.js';
+import { WebGPUHal } from './webgpuHal.js';
+// Per copy of this module rather than on the globalThis cell, deliberately: a
+// second bundled copy warning a second time is a duplicate console line, which
+// is the "a memo per copy is fine" case ADR-030's amendment carves out. Nothing
+// reads it.
+let warnedSoftwareRasterizer = false;
+function warnSoftwareRasterizerOnce(glRenderer) {
+    if (warnedSoftwareRasterizer) {
+        return;
+    }
+    warnedSoftwareRasterizer = true;
+    console.warn(`[GPU] WebGL2 here is software-rendered (${glRenderer ?? 'unknown driver'}), where it costs several times Canvas2D on the main thread — rendering with Canvas2D instead. Pass ?renderer=webgl to use WebGL2 anyway.`);
+}
+// Ladder: WebGPU → WebGL2 → Canvas2D (null). The `?renderer=` URL param pins it
+// to a single rung for debugging — `webgpu`, `webgl`, or `canvas2d`/`canvas` —
+// and a pin never falls through to the next rung. See GPU_OVERRIDES.
+export async function createGpuHal(canvas, { passes, uniformByteSize, sampleCount, failures }) {
+    if (isGpuRenderingDisabled()) {
+        return null;
+    }
+    const override = getGpuOverride();
+    if (override !== 'webgl') {
+        try {
+            const webgpu = await WebGPUHal.create(canvas, passes, uniformByteSize, sampleCount);
+            if (webgpu) {
+                return webgpu;
+            }
+            // `create` returns null only for "no WebGPU device on this machine",
+            // which is the ordinary path on most hardware and not worth recording as
+            // a failure; every other way it can decline now throws.
+        }
+        catch (e) {
+            console.warn('[GPU] WebGPU init failed, falling back to WebGL2:', e);
+            failures?.push(e);
+        }
+        // A pin is not a preference. `?renderer=webgpu` used to be indistinguishable
+        // from passing nothing — WebGPU is the first rung either way — so on a
+        // machine where it declined, the page rendered on WebGL2 and said nothing,
+        // and anyone using the flag to compare the two backends measured WebGL2
+        // twice. Fail where it can be seen instead. The other pins already behave
+        // this way: `webgl` skips this rung, `canvas2d` returns null above.
+        if (override === 'webgpu') {
+            const message = 'WebGPU was pinned with ?renderer=webgpu but no WebGPU backend could be created. Not falling back to WebGL2 — a pinned renderer that silently substitutes another makes any comparison against it wrong. Drop the parameter for the default WebGPU → WebGL2 → Canvas2D ladder.';
+            throw failures?.length
+                ? new AggregateError(failures, message)
+                : new Error(message);
+        }
+    }
+    // The one machine where the WebGL2 rung is the wrong answer even though it
+    // works: a software rasterizer. Measured on one ordinary view — 1 view, 3
+    // volvox tracks, and *no scroll churn at all* — headless Chrome (SwiftShader),
+    // three runs each: WebGL2 blocks the main thread for 1.3-5.5 s in a single
+    // task and 2.1-8.8 s in total, while Canvas2D never exceeds 339 ms and never
+    // once produces a task over 500 ms. GPU_CONTEXT_BUDGET.md has the churn case
+    // at ~25x; this is the floor, and it is the load-time pipeline build rather
+    // than the per-pass rebuild the churn number measures.
+    //
+    // Stepping over the rung rather than pinning the page is the difference that
+    // matters: `gpuOverride` means "a human asked for this", and spending it on a
+    // decision the app made would leave nothing able to tell the two apart —
+    // including the About widget and the bug report the user is about to send.
+    //
+    // Only when nothing was pinned. `?renderer=webgl` means that rung, and the
+    // browser-test runner sets it for every GPU arm (`appendGpuParam`), so the
+    // cross-backend gate keeps comparing canvas2d against a real WebGL2 render
+    // rather than against a second Canvas2D one — it runs under SwiftShader, so
+    // without that pin this check would quietly make it compare a backend with
+    // itself and pass.
+    //
+    // `softwareWebgl` is `undefined` wherever the browser withholds
+    // WEBGL_debug_renderer_info (Firefox under privacy.resistFingerprinting), and
+    // that must not read as `true`: an unknown rasterizer keeps the WebGL2 rung.
+    if (override === null) {
+        const { softwareWebgl, glRenderer } = await getGraphicsCapabilities();
+        if (softwareWebgl) {
+            warnSoftwareRasterizerOnce(glRenderer);
+            return null;
+        }
+    }
+    try {
+        return new WebGL2Hal(canvas, passes, uniformByteSize);
+    }
+    catch (e) {
+        console.warn('[GPU] WebGL2 unavailable, falling back to Canvas2D:', e);
+        failures?.push(e);
+        return null;
+    }
+}

package/esm/hal/deviceGpuCache.d.ts

@@ -0,0 +1,36 @@
+import type { PipelineDescriptor, SampleCount } from './types.ts';
+/**
+ * The two pipeline layouts every pass is built against. Both are created
+ * eagerly now — the textured pair used to be lazy so that a display drawing no
+ * textured pass paid nothing, which was worth two objects per *display* and is
+ * not worth the null-bundling for two objects per *device*.
+ */
+export interface DeviceLayouts {
+    uniformOnlyBindGroupLayout: GPUBindGroupLayout;
+    uniformOnlyPipelineLayout: GPUPipelineLayout;
+    texturedBindGroupLayout: GPUBindGroupLayout;
+    texturedPipelineLayout: GPUPipelineLayout;
+}
+/**
+ * The bind group and pipeline layouts for `device`, built once per device.
+ *
+ * A device that is lost drops out of the map with itself — `gpuDevice.ts`
+ * releases its reference in the `.lost` handler and the next acquisition is a
+ * new object, so the layouts and pipelines built against the dead one are
+ * unreachable and there is no cache to invalidate by hand.
+ */
+export declare function getDeviceLayouts(device: GPUDevice): DeviceLayouts;
+/**
+ * The pipeline for `desc` at `sampleCount` on `device`, building it through
+ * `build` on the first ask and handing every later one the same promise.
+ *
+ * `build` receives the sample count rather than closing over one, so the key
+ * and the pipeline stored under it cannot disagree.
+ */
+export declare function getOrBuildPipeline(device: GPUDevice, desc: PipelineDescriptor, sampleCount: SampleCount, build: (layouts: DeviceLayouts, sampleCount: SampleCount) => Promise<GPURenderPipeline>): Promise<GPURenderPipeline>;
+/**
+ * Drop every device's entry. Tests only — nothing in the app invalidates this
+ * cache, because losing the device is what invalidates it (see
+ * {@link getDeviceLayouts}).
+ */
+export declare function resetDeviceGpuCacheForTests(device: GPUDevice): void;

package/esm/hal/deviceGpuCache.js

@@ -0,0 +1,120 @@
+/// <reference types="@webgpu/types" />
+/**
+ * The GPU objects that belong to the **device** rather than to one `WebGPUHal`,
+ * memoized so the second display of a track type builds none of them.
+ *
+ * WebGL2 has no equivalent and wants none: a program is owned by the context
+ * that linked it, and each display owns a context, so nothing there is
+ * shareable. WebGPU inverts that — `gpuDevice.ts` hands every display one
+ * device, and a `GPURenderPipeline` is a device object — and until this module
+ * the HAL kept building per-display copies anyway. Ten alignments tracks
+ * compiled 230 pipelines for 23 distinct programs.
+ *
+ * **The key is the descriptor object, and that is what makes it correct.** A
+ * plugin's pass list is a module-level const (`ALIGNMENTS_PASSES`) and
+ * `slangPass` reads `wgslSource` off a generated module const, so every display
+ * of a type hands the HAL the *same* `PipelineDescriptor` objects by reference.
+ * Identity therefore means "same shader, same layout, same blend, same
+ * topology" without comparing any of them, and two passes that merely share a
+ * `.slang` shape module (MAF and multi-row both draw `rowRect`) get separate
+ * entries because `slangPass` built them separate objects. The **sample count**
+ * is the one pipeline input the descriptor cannot express, so it is the inner
+ * key; see the `pipelines` field.
+ *
+ * The one field of a pipeline that is not on the descriptor is the uniform
+ * size, and it cannot make two HALs disagree here:
+ * `createUniformOnlyBindGroupLayout` declares no `minBindingSize`, so the
+ * layout — and thus the pipeline built against it — is the same whatever a
+ * display's `uniformByteSize` is. The size reaches the GPU through the bind
+ * group's `size` and the dynamic offset, both of which stay per-HAL.
+ *
+ * Per copy of this module rather than on the `globalThis` cell, for the reason
+ * `createHal.ts` gives for `warnedSoftwareRasterizer`: a second bundled copy
+ * builds a second set, which costs a duplicate and never a wrong answer.
+ * Layouts compare structurally in WebGPU, so a bind group from one copy is
+ * valid against a pipeline from the other.
+ */
+const perDevice = new WeakMap();
+function createLayouts(device) {
+    const uniformEntry = {
+        binding: 1,
+        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true },
+    };
+    const uniformOnlyBindGroupLayout = device.createBindGroupLayout({
+        entries: [uniformEntry],
+    });
+    const texturedBindGroupLayout = device.createBindGroupLayout({
+        entries: [
+            uniformEntry,
+            {
+                binding: 2,
+                visibility: GPUShaderStage.FRAGMENT,
+                texture: { sampleType: 'float' },
+            },
+            {
+                binding: 3,
+                visibility: GPUShaderStage.FRAGMENT,
+                sampler: { type: 'filtering' },
+            },
+        ],
+    });
+    return {
+        uniformOnlyBindGroupLayout,
+        uniformOnlyPipelineLayout: device.createPipelineLayout({
+            bindGroupLayouts: [uniformOnlyBindGroupLayout],
+        }),
+        texturedBindGroupLayout,
+        texturedPipelineLayout: device.createPipelineLayout({
+            bindGroupLayouts: [texturedBindGroupLayout],
+        }),
+    };
+}
+function cacheFor(device) {
+    let entry = perDevice.get(device);
+    if (!entry) {
+        entry = { layouts: createLayouts(device), pipelines: new WeakMap() };
+        perDevice.set(device, entry);
+    }
+    return entry;
+}
+/**
+ * The bind group and pipeline layouts for `device`, built once per device.
+ *
+ * A device that is lost drops out of the map with itself — `gpuDevice.ts`
+ * releases its reference in the `.lost` handler and the next acquisition is a
+ * new object, so the layouts and pipelines built against the dead one are
+ * unreachable and there is no cache to invalidate by hand.
+ */
+export function getDeviceLayouts(device) {
+    return cacheFor(device).layouts;
+}
+/**
+ * The pipeline for `desc` at `sampleCount` on `device`, building it through
+ * `build` on the first ask and handing every later one the same promise.
+ *
+ * `build` receives the sample count rather than closing over one, so the key
+ * and the pipeline stored under it cannot disagree.
+ */
+export function getOrBuildPipeline(device, desc, sampleCount, build) {
+    const { layouts, pipelines } = cacheFor(device);
+    let bySampleCount = pipelines.get(desc);
+    if (!bySampleCount) {
+        bySampleCount = new Map();
+        pipelines.set(desc, bySampleCount);
+    }
+    let pipeline = bySampleCount.get(sampleCount);
+    if (!pipeline) {
+        pipeline = build(layouts, sampleCount);
+        bySampleCount.set(sampleCount, pipeline);
+    }
+    return pipeline;
+}
+/**
+ * Drop every device's entry. Tests only — nothing in the app invalidates this
+ * cache, because losing the device is what invalidates it (see
+ * {@link getDeviceLayouts}).
+ */
+export function resetDeviceGpuCacheForTests(device) {
+    perDevice.delete(device);
+}

package/esm/hal/gpuHalBase.d.ts

@@ -0,0 +1,55 @@
+import { OomReporter } from './oomReporter.ts';
+import { RegionRegistry } from './regionRegistry.ts';
+import type { PipelineDescriptor, TextureBinding } from './types.ts';
+/**
+ * The device ceilings the shared upload shells refuse past. WebGPU asks the
+ * device, WebGL2 has no such parameter for buffers and carries its own constant
+ * (see `MAX_VERTEX_BUFFER_BYTES`), and `MockHal` has none at all.
+ */
+export interface HalLimits {
+    maxBufferBytes: number;
+    maxTextureDimensionPx: number;
+}
+/**
+ * The half of a HAL that is not per-backend: the descriptor map, the
+ * `(region, pass)` buffer registry and the upload/delete semantics over it, the
+ * over-limit refusals and their wording, and the once-only `dispose` guard.
+ *
+ * `packages/render-core/CLAUDE.md` states HAL parity as a rule ("a behavior
+ * change to one HAL lands in the other and in `MockHal`"); this class is the
+ * structural half of it. What stays in the leaves is what genuinely differs —
+ * the frame bracket, uniform ring vs UBO, scissor Y-flip, MSAA, lazy vs eager
+ * pipeline build, and WebGPU's deferred destroy, which the `destroyBuffer` hook
+ * keeps WebGPU's alone.
+ *
+ * A backend's `Buf` carries its own leaf handle plus the instance `count` every
+ * caller reads through `getBufferCount`.
+ */
+export declare abstract class GpuHalBase<Buf extends {
+    count: number;
+}> {
+    protected descriptors: Map<string, PipelineDescriptor>;
+    protected regions: RegionRegistry<Buf>;
+    protected oom: OomReporter;
+    protected disposed: boolean;
+    constructor(descriptors: PipelineDescriptor[], halName: string);
+    protected abstract limits(): HalLimits;
+    protected abstract createBuffer(data: ArrayBuffer | ArrayBufferView, count: number): Buf;
+    protected abstract destroyBuffer(buf: Buf): void;
+    /**
+     * Replace the texture bound to `passId`, releasing whatever was there. Only
+     * reached for a pass that declares a binding, and only within
+     * `maxTextureDimensionPx`.
+     */
+    protected abstract createTexture(passId: string, binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    /** Release this HAL's own GPU objects. Runs exactly once, from `dispose`. */
+    protected abstract releaseResources(): void;
+    setErrorHandler(handler: (error: Error) => void): void;
+    uploadBuffer(regionKey: number, passId: string, data: ArrayBuffer | ArrayBufferView, count: number): void;
+    getBufferCount(regionKey: number, passId: string): number;
+    deleteBuffer(regionKey: number, passId: string): void;
+    deleteRegion(regionKey: number): void;
+    pruneRegions(active: Iterable<number>): void;
+    uploadTexture(passId: string, data: Uint8Array, width: number, height: number): void;
+    dispose(): void;
+}

package/esm/hal/gpuHalBase.js

@@ -0,0 +1,81 @@
+import { OomReporter } from './oomReporter.js';
+import { RegionRegistry } from './regionRegistry.js';
+/**
+ * The half of a HAL that is not per-backend: the descriptor map, the
+ * `(region, pass)` buffer registry and the upload/delete semantics over it, the
+ * over-limit refusals and their wording, and the once-only `dispose` guard.
+ *
+ * `packages/render-core/CLAUDE.md` states HAL parity as a rule ("a behavior
+ * change to one HAL lands in the other and in `MockHal`"); this class is the
+ * structural half of it. What stays in the leaves is what genuinely differs —
+ * the frame bracket, uniform ring vs UBO, scissor Y-flip, MSAA, lazy vs eager
+ * pipeline build, and WebGPU's deferred destroy, which the `destroyBuffer` hook
+ * keeps WebGPU's alone.
+ *
+ * A backend's `Buf` carries its own leaf handle plus the instance `count` every
+ * caller reads through `getBufferCount`.
+ */
+export class GpuHalBase {
+    descriptors;
+    regions;
+    oom;
+    // Guards dispose() against double invocation (pagehide + React cleanup can
+    // both fire).
+    disposed = false;
+    constructor(descriptors, halName) {
+        this.descriptors = new Map(descriptors.map(d => [d.id, d]));
+        this.oom = new OomReporter(halName);
+        this.regions = new RegionRegistry(buf => {
+            this.destroyBuffer(buf);
+        });
+    }
+    setErrorHandler(handler) {
+        this.oom.setHandler(handler);
+    }
+    uploadBuffer(regionKey, passId, data, count) {
+        // The prior buffer goes before the count is looked at, which is what makes
+        // an empty upload the release rather than a no-op.
+        this.regions.deleteBuffer(regionKey, passId);
+        if (count > 0) {
+            const { maxBufferBytes } = this.limits();
+            if (data.byteLength > maxBufferBytes) {
+                this.oom.report(`This region has too much data to render on this GPU — zoom in. (vertex buffer ${data.byteLength} bytes exceeds the ${maxBufferBytes}-byte limit)`);
+            }
+            else {
+                this.regions.set(regionKey, passId, this.createBuffer(data, count));
+            }
+        }
+    }
+    getBufferCount(regionKey, passId) {
+        return this.regions.get(regionKey, passId)?.count ?? 0;
+    }
+    deleteBuffer(regionKey, passId) {
+        this.regions.deleteBuffer(regionKey, passId);
+    }
+    deleteRegion(regionKey) {
+        this.regions.deleteRegion(regionKey);
+    }
+    pruneRegions(active) {
+        this.regions.prune(active);
+    }
+    uploadTexture(passId, data, width, height) {
+        // Read the binding off the descriptor, so a pass with no texture is
+        // answered without touching the backend's pipeline state at all.
+        const binding = this.descriptors.get(passId)?.textures?.[0];
+        if (binding) {
+            const { maxTextureDimensionPx } = this.limits();
+            if (width > maxTextureDimensionPx || height > maxTextureDimensionPx) {
+                this.oom.report(`This region is too large to render on this GPU — zoom in. (texture ${width}×${height} exceeds max texture size ${maxTextureDimensionPx})`);
+            }
+            else {
+                this.createTexture(passId, binding, data, width, height);
+            }
+        }
+    }
+    dispose() {
+        if (!this.disposed) {
+            this.disposed = true;
+            this.releaseResources();
+        }
+    }
+}