@jbrowse/render-core 5.0.0-beta.2 → 5.0.0-beta.3

package/esm/RenderLifecycleMixin.d.ts

@@ -119,6 +119,23 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * and the two families compose the two mixins in opposite orders.
      */
     readonly paintInert: boolean;
+    /**
+     * #getter
+     * Overridable hook (default false): what is on the canvas was painted
+     * from data a later change has made wrong, so `painted` below should
+     * answer *pending* until the repaint lands even though `canvasDrawn` is
+     * still true. The per-region fetch foundation fills it with
+     * `staleSettingsDrawn` — held data drawn under settings that have since
+     * moved — which is the state `clearAllRpcData` used to express by
+     * resetting `canvasDrawn` on every settings change, blanking the display
+     * to do it. A capture waiting on `data-display-drawn` then waits for the
+     * refetch rather than snapshotting the previous setting's pixels.
+     *
+     * A hook and not a reset of the flag, because the flag is re-marked by
+     * any redraw — a pan between the settings change and the refetch would
+     * report the stale canvas drawn — and a derivation cannot be raced.
+     */
+    readonly paintSuperseded: boolean;
 } & {
     /**
      * #getter
@@ -140,7 +157,9 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      *
      * `paintInert` is the third term and the same argument once more, for the
      * state where a display *would* paint a canvas and never gets to — a fetch
-     * that failed before first paint. See that hook.
+     * that failed before first paint. `paintSuperseded` is the fourth, and
+     * the one that subtracts: a canvas painted from data a settings change
+     * has made wrong is drawn and not finished. See both hooks.
      */
     readonly painted: boolean;
 } & {

package/esm/RenderLifecycleMixin.js

@@ -132,6 +132,25 @@ export function RenderLifecycleMixin() {
         get paintInert() {
             return false;
         },
+        /**
+         * #getter
+         * Overridable hook (default false): what is on the canvas was painted
+         * from data a later change has made wrong, so `painted` below should
+         * answer *pending* until the repaint lands even though `canvasDrawn` is
+         * still true. The per-region fetch foundation fills it with
+         * `staleSettingsDrawn` — held data drawn under settings that have since
+         * moved — which is the state `clearAllRpcData` used to express by
+         * resetting `canvasDrawn` on every settings change, blanking the display
+         * to do it. A capture waiting on `data-display-drawn` then waits for the
+         * refetch rather than snapshotting the previous setting's pixels.
+         *
+         * A hook and not a reset of the flag, because the flag is re-marked by
+         * any redraw — a pan between the settings change and the refetch would
+         * report the stale canvas drawn — and a derivation cannot be raced.
+         */
+        get paintSuperseded() {
+            return false;
+        },
     }))
         .views(self => ({
         /**
@@ -154,10 +173,14 @@ export function RenderLifecycleMixin() {
          *
          * `paintInert` is the third term and the same argument once more, for the
          * state where a display *would* paint a canvas and never gets to — a fetch
-         * that failed before first paint. See that hook.
+         * that failed before first paint. `paintSuperseded` is the fourth, and
+         * the one that subtracts: a canvas painted from data a settings change
+         * has made wrong is drawn and not finished. See both hooks.
          */
         get painted() {
-            return self.canvasDrawn || !self.rendersCanvas || self.paintInert;
+            return ((self.canvasDrawn && !self.paintSuperseded) ||
+                !self.rendersCanvas ||
+                self.paintInert);
         },
     }))
         .actions(self => ({

package/esm/canvas2dUtils.d.ts

@@ -203,6 +203,31 @@ export declare function strokeRectInside(ctx: {
  * Scalar in, scalar out: runs per feature per frame, so it must not allocate.
  */
 export declare function spanLeft(x1: number, x2: number, width: number): number;
+/**
+ * The `fillRect` x and width a genomic span paints as, given a bare
+ * `makeBpMapper`: `spanLeft`'s pivot and the min-width floor that goes with it,
+ * as one value a painter and its hit box can both read.
+ *
+ * `minWidth` defaults to 0, which makes this plain screen ordering — the
+ * leftmost projected edge and the unsigned distance. Pass a floor and the span
+ * grows away from `startBp`, which is the reversed-block rule `spanLeft` owns:
+ * anchoring the leftmost edge instead slides a sub-pixel mark by up to the floor
+ * on a flipped region and never on a forward one.
+ *
+ * Reach for this over `spanLeft` wherever the *numbers* are wanted rather than a
+ * fill — a hover box, an SVG rect, a cull test, an overlay div — which is where
+ * the pivot and the floor were being restated separately. The multi-row painter
+ * and the hover box it has to line up with each spelled out both.
+ * `fillBpSpan` is the same span when a `fillRect` is the only consumer.
+ *
+ * Not for a per-instance paint loop: this allocates a result per call, so the
+ * span mark's painter and wiggle's two bar loops take `spanLeft` and the two
+ * numbers inline, and stay the last hand-written copies of this arithmetic.
+ */
+export declare function spanRect(toX: (bp: number) => number, startBp: number, endBp: number, minWidth?: number): {
+    left: number;
+    width: number;
+};
 export declare function makeRampFillStyleLut(ramp: Uint8Array): (t: number) => string;
 export declare function bpToScreenPx(absBp: number, regionStart: number, regionEnd: number, screenStartPx: number, screenEndPx: number, reversed?: boolean): number;
 export declare function makeBpMapper(bounds: BpRegionBounds): (bp: number) => number;

package/esm/canvas2dUtils.js

@@ -334,6 +334,33 @@ export function strokeRectInside(ctx, x, y, w, h, lineWidth = 1) {
 export function spanLeft(x1, x2, width) {
     return x2 < x1 ? x1 - width : x1;
 }
+/**
+ * The `fillRect` x and width a genomic span paints as, given a bare
+ * `makeBpMapper`: `spanLeft`'s pivot and the min-width floor that goes with it,
+ * as one value a painter and its hit box can both read.
+ *
+ * `minWidth` defaults to 0, which makes this plain screen ordering — the
+ * leftmost projected edge and the unsigned distance. Pass a floor and the span
+ * grows away from `startBp`, which is the reversed-block rule `spanLeft` owns:
+ * anchoring the leftmost edge instead slides a sub-pixel mark by up to the floor
+ * on a flipped region and never on a forward one.
+ *
+ * Reach for this over `spanLeft` wherever the *numbers* are wanted rather than a
+ * fill — a hover box, an SVG rect, a cull test, an overlay div — which is where
+ * the pivot and the floor were being restated separately. The multi-row painter
+ * and the hover box it has to line up with each spelled out both.
+ * `fillBpSpan` is the same span when a `fillRect` is the only consumer.
+ *
+ * Not for a per-instance paint loop: this allocates a result per call, so the
+ * span mark's painter and wiggle's two bar loops take `spanLeft` and the two
+ * numbers inline, and stay the last hand-written copies of this arithmetic.
+ */
+export function spanRect(toX, startBp, endBp, minWidth = 0) {
+    const x1 = toX(startBp);
+    const x2 = toX(endBp);
+    const width = Math.max(minWidth, Math.abs(x2 - x1));
+    return { left: spanLeft(x1, x2, width), width };
+}
 // Quantize a 0..1 ramp position to a 256-entry index. Shared so the direct
 // lookup and the fillStyle LUT below can't quantize differently — a half-step
 // of drift between them shows up as a one-shade mismatch between a cell's fill

package/esm/colorRampLut.d.ts

@@ -9,9 +9,9 @@ export declare const COLOR_RAMP_LUT_ENTRIES = 256;
 /**
  * Upload a 256-entry RGBA colour-ramp LUT as each named pass's 256×1 texture —
  * the runtime half of the shared ramp mechanism whose shader half is
- * `shaders/colorRampLut.slang`. HiC, LD (whose two shader variants are the
- * reason this takes a pass list) and wiggle density all put their ramps behind
- * their samplers through this one call; each keeps its own scale and its own
- * LUT contents.
+ * `shaders/colorRampLut.slang`. Called by `createMarkBackend` alone now, for
+ * every mark declaring a `texture`: hic, LD's two shader variants and wiggle
+ * density all put their ramps behind their samplers through it, each keeping
+ * its own scale and its own LUT contents.
  */
 export declare function uploadColorRampLut(hal: GpuHal, ramp: Uint8Array, passIds: readonly string[]): void;

package/esm/colorRampLut.js

@@ -9,10 +9,10 @@ export const COLOR_RAMP_LUT_ENTRIES = RAMP_LUT_ENTRIES;
 /**
  * Upload a 256-entry RGBA colour-ramp LUT as each named pass's 256×1 texture —
  * the runtime half of the shared ramp mechanism whose shader half is
- * `shaders/colorRampLut.slang`. HiC, LD (whose two shader variants are the
- * reason this takes a pass list) and wiggle density all put their ramps behind
- * their samplers through this one call; each keeps its own scale and its own
- * LUT contents.
+ * `shaders/colorRampLut.slang`. Called by `createMarkBackend` alone now, for
+ * every mark declaring a `texture`: hic, LD's two shader variants and wiggle
+ * density all put their ramps behind their samplers through it, each keeping
+ * its own scale and its own LUT contents.
  */
 export function uploadColorRampLut(hal, ramp, passIds) {
     if (ramp.length !== COLOR_RAMP_LUT_ENTRIES * 4) {

package/esm/computePipeline.d.ts

@@ -0,0 +1,13 @@
+import type { ShaderBinding } from './hal/index.ts';
+export interface ComputePipelineState {
+    device: GPUDevice;
+    pipeline: GPUComputePipeline;
+    bindGroupLayout: GPUBindGroupLayout;
+    bindings: readonly ShaderBinding[];
+}
+/**
+ * One compute pipeline per kernel, built on first use against the current
+ * device and rebuilt after a device loss. Concurrent first callers share the
+ * one async build.
+ */
+export declare function makeComputePipelineCache(code: string, entryPoint: string, bindings: readonly ShaderBinding[]): (device: GPUDevice) => Promise<ComputePipelineState>;

package/esm/computePipeline.js

@@ -0,0 +1,55 @@
+/// <reference types="@webgpu/types" />
+import { onDeviceLost } from './gpuDevice.js';
+// Built from the kernel's own reflected binding table rather than restated by
+// the caller, so a mismatch shows up as a validation failure at pipeline
+// creation rather than as a wrong buffer under a right-looking index.
+function makeBindGroupLayout(device, bindings) {
+    return device.createBindGroupLayout({
+        entries: bindings.map(b => {
+            if (b.kind === 'texture' || b.kind === 'sampler') {
+                throw new Error(`compute kernel: binding ${b.index} ('${b.name}') is a ${b.kind}, ` +
+                    `which a buffer-only dispatch does not bind`);
+            }
+            return {
+                binding: b.index,
+                visibility: GPUShaderStage.COMPUTE,
+                buffer: { type: b.kind },
+            };
+        }),
+    });
+}
+/**
+ * One compute pipeline per kernel, built on first use against the current
+ * device and rebuilt after a device loss. Concurrent first callers share the
+ * one async build.
+ */
+export function makeComputePipelineCache(code, entryPoint, bindings) {
+    let state = null;
+    let statePromise = null;
+    onDeviceLost(() => {
+        state = null;
+        statePromise = null;
+    });
+    return async function ensurePipeline(device) {
+        if (state?.device === device) {
+            return state;
+        }
+        if (statePromise) {
+            return statePromise;
+        }
+        statePromise = (async () => {
+            const module = device.createShaderModule({ code });
+            const bindGroupLayout = makeBindGroupLayout(device, bindings);
+            const pipeline = await device.createComputePipelineAsync({
+                layout: device.createPipelineLayout({
+                    bindGroupLayouts: [bindGroupLayout],
+                }),
+                compute: { module, entryPoint },
+            });
+            state = { device, pipeline, bindGroupLayout, bindings };
+            statePromise = null;
+            return state;
+        })();
+        return statePromise;
+    };
+}

package/esm/coverageBand.d.ts

@@ -1,6 +1,5 @@
 import type { CoverageBandBuffers } from './coverageBandBuffers.ts';
 import type { InstancePass } from './instancePass.ts';
-export { coverageBandBuffers } from './coverageBandBuffers.ts';
 export type { CoverageBandBuffers } from './coverageBandBuffers.ts';
 export declare const COVERAGE_BAND_UNIFORMS_SIZE_BYTES = 112;
 /**

package/esm/coverageBand.js

@@ -4,7 +4,6 @@ import * as coverageInterbaseShader from './shaders/coverageInterbase.generated.
 import * as coverageModShader from './shaders/coverageMod.generated.js';
 import * as coverageSnpShader from './shaders/coverageSnp.generated.js';
 import { slangPass } from './slangPass.js';
-export { coverageBandBuffers } from './coverageBandBuffers.js';
 export const COVERAGE_BAND_UNIFORMS_SIZE_BYTES = coverageBarShader.UNIFORMS_SIZE_BYTES;
 /**
  * The band's z-order, back to front: the depth bars, the SNP slices stacked

package/esm/coverageBandBuffers.d.ts

@@ -22,9 +22,3 @@ export interface CoverageBandBuffers {
     interbasePackedBuffer: ArrayBuffer;
     indicatorPackedBuffer: ArrayBuffer;
 }
-/**
- * Just the band's four buffers out of a wider per-region payload — the field set
- * stated once, so a display carrying them into its own upload payload cannot
- * spell three of them.
- */
-export declare function coverageBandBuffers(src: CoverageBandBuffers): CoverageBandBuffers;

package/esm/coverageBandBuffers.js

@@ -1,13 +1 @@
-/**
- * Just the band's four buffers out of a wider per-region payload — the field set
- * stated once, so a display carrying them into its own upload payload cannot
- * spell three of them.
- */
-export function coverageBandBuffers(src) {
-    return {
-        coveragePackedBuffer: src.coveragePackedBuffer,
-        snpPackedBuffer: src.snpPackedBuffer,
-        interbasePackedBuffer: src.interbasePackedBuffer,
-        indicatorPackedBuffer: src.indicatorPackedBuffer,
-    };
-}
+export {};

package/esm/createRenderingBackend.d.ts

@@ -7,31 +7,27 @@ import type { GpuHal, PipelineDescriptor, SampleCount } from './hal/types.ts';
  */
 export interface RenderingBackendOptions<TRenderingBackend> {
     passes: PipelineDescriptor[];
-    uniformByteSize: number;
     /**
-     * Samples per pixel this display's WebGPU target is allocated at — 4 unless
-     * stated, which is what every display asked for while this was a build-time
-     * constant.
+     * Samples per pixel this display's WebGPU target is allocated at. Omitted, it
+     * is derived from `passes`: 1 when every registered pass declares
+     * `//! coverage: analytic`, else 4. Registered, not drawn — an inactive pass
+     * that leans on MSAA holds its display at 4. Passing it overrides the
+     * derivation in either direction.
      *
-     * **It is a property of the display, not of the build**, because what it buys
-     * differs per display and what it costs does not. The cost is one colour
-     * attachment the size of the canvas, so an empty 600px track pays what a full
-     * one does and eight ordinary tracks on a retina panel hold 109.7 MiB nothing
-     * counts (ARCHITECTURAL_LIMITS.md §"The MSAA target is the largest
-     * per-display allocation"). What it buys is nothing at all for a display
-     * whose fragments compute their own coverage, and the one fix there is for
-     * conflation at the shared edges of tiled cells, which is Hi-C and LD.
-     *
-     * Setting it to 1 allocates **no** target rather than a smaller one. Which
-     * displays should is a look-at-the-pixels decision taken one display at a
-     * time; `ideas/arc-antialiasing-without-msaa.md` is the survey and the
-     * captures.
+     * The cost is one colour attachment the size of the canvas — an empty 600px
+     * track pays what a full one does, and eight ordinary tracks on a retina
+     * panel hold 109.7 MiB nothing counts (ARCHITECTURAL_LIMITS.md §"The MSAA
+     * target is the largest per-display allocation"); 1 allocates none. Whether a
+     * display's pixels survive the flip is a look-at-the-pixels decision taken
+     * one display at a time; `ideas/arc-antialiasing-without-msaa.md` is the
+     * survey and the captures.
      */
     sampleCount?: SampleCount;
     createGpuBackend: (hal: GpuHal) => TRenderingBackend;
     createCanvas2DBackend: (canvas: HTMLCanvasElement) => TRenderingBackend;
 }
-export declare function createRenderingBackend<TRenderingBackend>(canvas: HTMLCanvasElement, { passes, uniformByteSize, sampleCount, createGpuBackend, createCanvas2DBackend, }: RenderingBackendOptions<TRenderingBackend>): Promise<TRenderingBackend>;
+export declare function deriveSampleCount(passes: readonly PipelineDescriptor[]): SampleCount;
+export declare function createRenderingBackend<TRenderingBackend>(canvas: HTMLCanvasElement, { passes, sampleCount, createGpuBackend, createCanvas2DBackend, }: RenderingBackendOptions<TRenderingBackend>): Promise<TRenderingBackend>;
 /**
  * Factory for a **Canvas2D-only** display — one that ships no GPU shader path.
  *

package/esm/createRenderingBackend.js

@@ -1,5 +1,8 @@
 import { assertUniquePassIds, createGpuHal } from './hal/index.js';
-export async function createRenderingBackend(canvas, { passes, uniformByteSize, sampleCount = 4, createGpuBackend, createCanvas2DBackend, }) {
+export function deriveSampleCount(passes) {
+    return passes.every(p => p.coverage === 'analytic') ? 1 : 4;
+}
+export async function createRenderingBackend(canvas, { passes, sampleCount = deriveSampleCount(passes), createGpuBackend, createCanvas2DBackend, }) {
     // Before the ladder, so a duplicate id is reported on every machine rather
     // than only the ones that reach a GPU rung — the bug it prevents is silent
     // and GPU-only, which is precisely why a developer on the Canvas2D fallback
@@ -15,7 +18,6 @@ export async function createRenderingBackend(canvas, { passes, uniformByteSize,
     const ladderFailures = [];
     const hal = await createGpuHal(canvas, {
         passes,
-        uniformByteSize,
         sampleCount,
         failures: ladderFailures,
     });

package/esm/encodeMemo.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A per-key encode memo over a display's cell map: `encode` runs for a key
+ * when its data reference moves, every key re-encodes when `inputs` yields a
+ * new identity, and a departed key is dropped. `inputs` runs through a
+ * `computed`, so a getter that allocates a fresh object per read re-encodes
+ * only when what it read changed.
+ *
+ * The returned map is a new instance whenever an entry moved and the same one
+ * otherwise, so an MST view holding it invalidates its observers exactly when
+ * a cell did. `installUpload` runs its `encode` path on this; a display that
+ * needs the encoded map itself — for a hit test, an SVG export — holds one in
+ * a `.views` closure and hands the installer identity cells.
+ */
+export declare function createEncodeMemo<K, Data, Props, Encoded>(cells: () => ReadonlyMap<K, Data>, inputs: (() => Props) | undefined, encode: (data: Data, props: Props, key: K) => Encoded): () => ReadonlyMap<K, Encoded>;

package/esm/encodeMemo.js

@@ -0,0 +1,48 @@
+import { computed } from 'mobx';
+/**
+ * A per-key encode memo over a display's cell map: `encode` runs for a key
+ * when its data reference moves, every key re-encodes when `inputs` yields a
+ * new identity, and a departed key is dropped. `inputs` runs through a
+ * `computed`, so a getter that allocates a fresh object per read re-encodes
+ * only when what it read changed.
+ *
+ * The returned map is a new instance whenever an entry moved and the same one
+ * otherwise, so an MST view holding it invalidates its observers exactly when
+ * a cell did. `installUpload` runs its `encode` path on this; a display that
+ * needs the encoded map itself — for a hit test, an SVG export — holds one in
+ * a `.views` closure and hands the installer identity cells.
+ */
+export function createEncodeMemo(cells, inputs, encode) {
+    const encoded = new Map();
+    const encodedFrom = new Map();
+    const props = inputs && computed(inputs);
+    let lastProps;
+    let snapshot = encoded;
+    return () => {
+        const current = cells();
+        const p = props ? props.get() : undefined;
+        if (p !== lastProps) {
+            lastProps = p;
+            encodedFrom.clear();
+        }
+        let changed = false;
+        for (const [key, data] of current) {
+            if (encodedFrom.get(key) !== data) {
+                encoded.set(key, encode(data, p, key));
+                encodedFrom.set(key, data);
+                changed = true;
+            }
+        }
+        for (const key of encoded.keys()) {
+            if (!current.has(key)) {
+                encoded.delete(key);
+                encodedFrom.delete(key);
+                changed = true;
+            }
+        }
+        if (changed) {
+            snapshot = new Map(encoded);
+        }
+        return snapshot;
+    };
+}

package/esm/gpuDevice.d.ts

@@ -1,3 +1,4 @@
+import type { RendererName } from './graphicsCapabilities.ts';
 interface GpuDeviceCell {
     device: GPUDevice | null;
     /** Serializes concurrent calls during async init and after recovery. */
@@ -30,6 +31,12 @@ interface GpuDeviceCell {
      * @see setGpuOverride
      */
     gpuOverride: string | null;
+    /**
+     * The rung the last `createGpuHal` returned, so `effectiveRenderer` reports
+     * what drew rather than what the probe predicted. Optional because a cell an
+     * older copy built has none, and "nothing built yet" is a real state there.
+     */
+    builtRenderer?: RendererName;
 }
 declare global {
     var __jbrowseRenderCoreGpuDeviceV1: GpuDeviceCell | undefined;
@@ -61,6 +68,8 @@ export type GpuOverride = (typeof GPU_OVERRIDES)[number];
  */
 export declare function setGpuOverride(value: string | null): void;
 export declare function getGpuOverride(): string | null;
+export declare function setBuiltRenderer(name: RendererName): void;
+export declare function getBuiltRenderer(): RendererName | undefined;
 /**
  * Whether the GPU is off for the whole page — either pinned by `?renderer=` at
  * startup or switched off from a display's GPU-error banner after an

package/esm/gpuDevice.js

@@ -24,9 +24,11 @@
  * field added later would read `undefined` on a cell built by an older copy.
  * Changing this interface therefore means bumping the `V1` in the global's
  * name, which costs the sharing between the two versions — the point of the
- * suffix is that losing it is a decision rather than a silent misread. Reset in
- * place (see `resetGpuDeviceForTests`); never reassign the cell itself, or
- * copies holding the old object diverge from the new one.
+ * suffix is that losing it is a decision rather than a silent misread. The one
+ * exception is an optional field whose `undefined` is an honest state, as
+ * `builtRenderer`'s is. Reset in place (see `resetGpuDeviceForTests`); never
+ * reassign the cell itself, or copies holding the old object diverge from the
+ * new one.
  */
 const cell = (globalThis.__jbrowseRenderCoreGpuDeviceV1 ??= {
     device: null,
@@ -216,6 +218,12 @@ export function setGpuOverride(value) {
 export function getGpuOverride() {
     return cell.gpuOverride;
 }
+export function setBuiltRenderer(name) {
+    cell.builtRenderer = name;
+}
+export function getBuiltRenderer() {
+    return cell.builtRenderer;
+}
 /**
  * Whether the GPU is off for the whole page — either pinned by `?renderer=` at
  * startup or switched off from a display's GPU-error banner after an
@@ -248,6 +256,7 @@ export function resetGpuDeviceForTests() {
     cell.devicePromise = null;
     cell.hadDevice = false;
     cell.deviceLostListeners.clear();
+    cell.builtRenderer = undefined;
 }
 export function getGpuDevice() {
     const override = getGpuOverride();

package/esm/graphicsCapabilities.d.ts

@@ -65,22 +65,25 @@ export declare function isSoftwareRenderer(glRenderer: string): boolean;
  */
 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.
+ * Which rung draws. Once `createGpuHal` has built one on this page, the rung it
+ * returned is the answer — the adapter probe says WebGPU where
+ * `WebGPUHal.create` then throws and the ladder lands on WebGL2. Before any
+ * backend exists it is the ladder read as an answer rather than run, from what
+ * the machine can do *and* the page-wide pin from `?renderer=` or the
+ * GPU-error banner's "disable GPU" button. This is the question every consumer
+ * asks: the About widget's "Graphics:" line, the stack-trace dialog's
+ * environment block, the analytics field.
  *
- * 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.
+ * The Canvas2D pin is checked ahead of the record because the banner's
+ * "disable GPU" sets it before the displays rebuild on the new rung. The other
+ * pins win outright in the prediction, 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. The one case the prediction 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

package/esm/graphicsCapabilities.js

@@ -1,4 +1,4 @@
-import { getGpuOverride, isGpuRenderingDisabled } from './gpuDevice.js';
+import { getBuiltRenderer, 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
@@ -111,22 +111,25 @@ export function getGraphicsCapabilities() {
     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.
+ * Which rung draws. Once `createGpuHal` has built one on this page, the rung it
+ * returned is the answer — the adapter probe says WebGPU where
+ * `WebGPUHal.create` then throws and the ladder lands on WebGL2. Before any
+ * backend exists it is the ladder read as an answer rather than run, from what
+ * the machine can do *and* the page-wide pin from `?renderer=` or the
+ * GPU-error banner's "disable GPU" button. This is the question every consumer
+ * asks: the About widget's "Graphics:" line, the stack-trace dialog's
+ * environment block, the analytics field.
  *
- * 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.
+ * The Canvas2D pin is checked ahead of the record because the banner's
+ * "disable GPU" sets it before the displays rebuild on the new rung. The other
+ * pins win outright in the prediction, 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. The one case the prediction 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
@@ -145,6 +148,10 @@ export function effectiveRenderer(c) {
     if (isGpuRenderingDisabled()) {
         return 'Canvas2D';
     }
+    const built = getBuiltRenderer();
+    if (built) {
+        return built;
+    }
     const override = getGpuOverride();
     if (override === 'webgl') {
         return 'WebGL2';

package/esm/hal/createHal.d.ts

@@ -1,7 +1,6 @@
 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
@@ -19,4 +18,4 @@ export interface GpuHalOptions {
      */
     failures?: unknown[];
 }
-export declare function createGpuHal(canvas: HTMLCanvasElement, { passes, uniformByteSize, sampleCount, failures }: GpuHalOptions): Promise<GpuHal | null>;
+export declare function createGpuHal(canvas: HTMLCanvasElement, options: GpuHalOptions): Promise<GpuHal | null>;