@jbrowse/render-core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/gpuDevice.d.ts

@@ -1,10 +1,12 @@
+import type { RendererName } from './graphicsCapabilities.ts';
 interface GpuDeviceCell {
     device: GPUDevice | null;
     /** Serializes concurrent calls during async init and after recovery. */
     devicePromise: Promise<GPUDevice | null> | null;
     /**
      * Proof that this machine's WebGPU works, set the first time a device is
-     * acquired. It is what makes a failed acquisition readable, because the two
+     * acquired. The flag tells the two causes of a failed acquisition apart,
+     * because the two
      * causes are indistinguishable at the call site and want opposite handling:
      *
      *  - Before it, failure means "no WebGPU here" — the ordinary path on most
@@ -15,9 +17,9 @@ interface GpuDeviceCell {
      *    `requestAdapter` still declines. So this is not a rare race — it is the
      *    expected timing of the one path that re-acquires.
      *
-     * Caching the second kind is what `createGpuHal` then reads as "no WebGPU on
-     * this machine" (its own words), silently pinning the whole page to WebGL2
-     * until a reload. So past this flag a failure is retried and never cached.
+     * `createGpuHal` reads a cached failure of the second kind as "no WebGPU on
+     * this machine" (its own words) and pins the whole page to WebGL2 until a
+     * reload. So past this flag a failure is retried and never cached.
      */
     hadDevice: boolean;
     deviceLostListeners: Set<() => void>;
@@ -30,19 +32,34 @@ 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;
+    /**
+     * The page's first `requestAdapter`, which device acquisition and the
+     * capability probe share: on a machine without WebGPU each ask takes a few
+     * hundred milliseconds to decline. Optional for the same reason as
+     * `builtRenderer`.
+     */
+    firstAdapter?: Promise<GPUAdapter | null>;
 }
 declare global {
     var __jbrowseRenderCoreGpuDeviceV1: GpuDeviceCell | undefined;
 }
 export declare function onDeviceLost(listener: () => void): () => void;
+/** The page's first adapter request; see `GpuDeviceCell.firstAdapter` */
+export declare function requestFirstAdapter(): Promise<GPUAdapter | null>;
 /**
  * The renderers `?renderer=` can pin the page to. `canvas` is a spelling of
  * `canvas2d` kept because it is in the wild.
  *
- * A pin means *only* that rung — `createGpuHal` does not fall past it. That is
- * the whole point of the flag: it exists to compare backends, and a comparison
- * whose subject silently substitutes itself is worse than no comparison. The
- * failure is visible instead, as a `renderError` carrying the pin that could
+ * A pin means *only* that rung — `createGpuHal` does not fall past it. The flag
+ * is for comparing backends, and a comparison that renders with a different
+ * backend than the one pinned is worse than no comparison. The failure shows
+ * instead, as a `renderError` carrying the pin that could
  * not be honored, with the banner's "disable GPU" as the way out.
  */
 export declare const GPU_OVERRIDES: readonly ['webgpu', 'webgl', 'canvas2d', 'canvas'];
@@ -56,11 +73,13 @@ export type GpuOverride = (typeof GPU_OVERRIDES)[number];
  * `--renderer` flag), so validating here is validating once at the only place
  * an unchecked value enters. An unrecognized one clears the pin and says so:
  * before this, `?renderer=WebGL` or a typo was indistinguishable from passing
- * nothing at all, which is the one outcome a person debugging a renderer must
- * not silently get.
+ * nothing at all, and a person debugging a renderer got the default ladder
+ * with no sign the pin was ignored.
  */
 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

@@ -11,22 +11,23 @@
  * button on the context-loss banner, which `packages/render-core/CLAUDE.md`
  * names as the only sanctioned fallback path once a backend is built.
  *
- * A statically-bundled plugin is the case this exists for. ADR-030 makes the
- * GPU surface static-import-only, so a third-party display carries its own copy
- * of this module by design; with module locals its `gpuOverride` would start
+ * A plugin that bundled render-core is the case this exists for. Every plugin
+ * built before ADR-128 did, so a third-party display can carry its own copy of
+ * this module; with module locals its `gpuOverride` would start
  * null and stay null, and the user who pins `?renderer=canvas2d` or clicks
  * "disable GPU" after a crash would watch the plugin ignore both and take
- * WebGPU anyway. Sharing the cell fixes that without putting anything in the
- * frozen `ReExports` ABI — which is the trade ADR-030 declined, and rightly.
+ * WebGPU anyway. Sharing the cell fixes that for every copy, served or bundled.
  *
  * **The shape is a cross-version contract.** Copies at different render-core
  * versions meet here, and whichever loads first wins the initialization, so a
  * 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,
@@ -90,8 +91,15 @@ function logGpuCapabilities(adapter, device) {
     console.warn(`[GPU] WebGPU device ready — vendor="${vendor}" architecture="${architecture}" description="${description}" ` +
         `maxTextureDimension2D=${maxTextureDimension2D} maxBufferSize=${maxBufferSize} maxStorageBufferBindingSize=${maxStorageBufferBindingSize}`);
 }
+/** The page's first adapter request; see `GpuDeviceCell.firstAdapter` */
+export function requestFirstAdapter() {
+    cell.firstAdapter ??= navigator.gpu.requestAdapter();
+    return cell.firstAdapter;
+}
 async function acquire() {
-    const adapter = await navigator.gpu.requestAdapter();
+    const adapter = await (cell.hadDevice
+        ? navigator.gpu.requestAdapter()
+        : requestFirstAdapter());
     if (!adapter) {
         console.warn('[GPU] No compatible GPU adapter available. This may indicate WebGPU is disabled, unsupported hardware, or a system limitation. Falling back to WebGL2.');
         return null;
@@ -152,8 +160,11 @@ async function createDevice() {
         // Surface any WebGPU validation / out-of-memory / internal errors that
         // would otherwise be silently swallowed. Without this, a bad draw/pipeline
         // results in a blank canvas with no console output.
+        // The constructor name, because the message alone does not say whether a
+        // failure is validation, out-of-memory or internal — and that is what
+        // decides which `pushErrorScope` filter could have caught it.
         d.addEventListener('uncapturederror', (event) => {
-            console.error('[GPU] UNCAPTURED ERROR:', event.error.message);
+            console.error(`[GPU] UNCAPTURED ${event.error.constructor.name}:`, event.error.message);
         });
         void d.lost.then(info => {
             // Identity check: if the shared device has already been replaced (test
@@ -183,10 +194,10 @@ async function createDevice() {
  * The renderers `?renderer=` can pin the page to. `canvas` is a spelling of
  * `canvas2d` kept because it is in the wild.
  *
- * A pin means *only* that rung — `createGpuHal` does not fall past it. That is
- * the whole point of the flag: it exists to compare backends, and a comparison
- * whose subject silently substitutes itself is worse than no comparison. The
- * failure is visible instead, as a `renderError` carrying the pin that could
+ * A pin means *only* that rung — `createGpuHal` does not fall past it. The flag
+ * is for comparing backends, and a comparison that renders with a different
+ * backend than the one pinned is worse than no comparison. The failure shows
+ * instead, as a `renderError` carrying the pin that could
  * not be honored, with the banner's "disable GPU" as the way out.
  */
 export const GPU_OVERRIDES = ['webgpu', 'webgl', 'canvas2d', 'canvas'];
@@ -202,8 +213,8 @@ function isGpuOverride(value) {
  * `--renderer` flag), so validating here is validating once at the only place
  * an unchecked value enters. An unrecognized one clears the pin and says so:
  * before this, `?renderer=WebGL` or a typo was indistinguishable from passing
- * nothing at all, which is the one outcome a person debugging a renderer must
- * not silently get.
+ * nothing at all, and a person debugging a renderer got the default ladder
+ * with no sign the pin was ignored.
  */
 export function setGpuOverride(value) {
     if (value !== null && !isGpuOverride(value)) {
@@ -216,6 +227,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
@@ -247,7 +264,9 @@ export function resetGpuDeviceForTests() {
     cell.device = null;
     cell.devicePromise = null;
     cell.hadDevice = false;
+    cell.firstAdapter = undefined;
     cell.deviceLostListeners.clear();
+    cell.builtRenderer = undefined;
 }
 export function getGpuDevice() {
     const override = getGpuOverride();

package/esm/graphicsCapabilities.d.ts

@@ -1,8 +1,8 @@
 export interface GraphicsCapabilities {
     webgpu: boolean;
     /**
-     * `undefined` when the WebGL2 probe was skipped, which is what
-     * `getGraphicsCapabilities` does whenever WebGPU answered first — see there.
+     * `undefined` when the WebGL2 probe was skipped. `getGraphicsCapabilities`
+     * skips it whenever WebGPU answered first — see there.
      */
     webgl2?: boolean;
     gpuVendor?: string;
@@ -29,8 +29,8 @@ export interface GraphicsCapabilities {
  * 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
+ * Deliberately *not* the {@link GpuOverride} vocabulary, the values a user
+ * types into `?renderer=`, which therefore carry 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.
@@ -65,22 +65,30 @@ 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.
+ * Take the renderer ladder's device and capability steps now, before a display
+ * asks. On a real GPU the adapter and device requests took half a second, and a
+ * first display that starts them on mount paints that much after its data.
+ */
+export declare function prewarmGraphics(): void;
+/**
+ * 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, because a pinned renderer
+ * that falls back to another rung 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, getGpuDevice, getGpuOverride, isGpuRenderingDisabled, requestFirstAdapter, } 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
@@ -28,7 +28,7 @@ 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();
+        const adapter = await requestFirstAdapter();
         return adapter
             ? {
                 webgpu: true,
@@ -50,11 +50,11 @@ async function probeWebgpu() {
  * 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
+ * loss to the console, where a user sees it. 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
+ * re-acquires it), so the eviction cascade in GPU_PORTABILITY.md cannot
  * start here.
  *
  * The driver string comes off the same context, so it is free where it matters:
@@ -111,22 +111,40 @@ 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.
+ * Take the renderer ladder's device and capability steps now, before a display
+ * asks. On a real GPU the adapter and device requests took half a second, and a
+ * first display that starts them on mount paints that much after its data.
+ */
+export function prewarmGraphics() {
+    if (isGpuRenderingDisabled()) {
+        return;
+    }
+    const override = getGpuOverride();
+    void getGpuDevice().then(device => {
+        if (!device && override === null) {
+            void getGraphicsCapabilities();
+        }
+    });
+}
+/**
+ * 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, because a pinned renderer
+ * that falls back to another rung 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 +163,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,11 +1,10 @@
 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.
+     * WebGPU sizes its multisampled target by it; WebGL2 asks the browser for an
+     * antialiased drawing buffer only above one sample, so a display whose passes
+     * all measure their own coverage pays for no samples on either rung.
      */
     sampleCount: SampleCount;
     /**
@@ -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>;

package/esm/hal/createHal.js

@@ -1,4 +1,4 @@
-import { getGpuOverride, isGpuRenderingDisabled } from '../gpuDevice.js';
+import { getGpuOverride, isGpuRenderingDisabled, setBuiltRenderer, } from '../gpuDevice.js';
 import { getGraphicsCapabilities } from '../graphicsCapabilities.js';
 import { WebGL2Hal } from './webgl2Hal.js';
 import { WebGPUHal } from './webgpuHal.js';
@@ -17,14 +17,24 @@ function warnSoftwareRasterizerOnce(glRenderer) {
 // 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 }) {
+//
+// Records the rung it returned on the page-wide cell, which is how
+// `effectiveRenderer` gets to report what drew rather than what the adapter
+// probe predicted — the two part when `WebGPUHal.create` throws and the ladder
+// lands on WebGL2.
+export async function createGpuHal(canvas, options) {
+    const hal = await climbLadder(canvas, options);
+    setBuiltRenderer(hal === null ? 'Canvas2D' : hal instanceof WebGPUHal ? 'WebGPU' : 'WebGL2');
+    return hal;
+}
+async function climbLadder(canvas, { passes, sampleCount, failures }) {
     if (isGpuRenderingDisabled()) {
         return null;
     }
     const override = getGpuOverride();
     if (override !== 'webgl') {
         try {
-            const webgpu = await WebGPUHal.create(canvas, passes, uniformByteSize, sampleCount);
+            const webgpu = await WebGPUHal.create(canvas, passes, sampleCount);
             if (webgpu) {
                 return webgpu;
             }
@@ -54,7 +64,7 @@ export async function createGpuHal(canvas, { passes, uniformByteSize, sampleCoun
     // 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
+    // once produces a task over 500 ms. GPU_PORTABILITY.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.
     //
@@ -81,7 +91,7 @@ export async function createGpuHal(canvas, { passes, uniformByteSize, sampleCoun
         }
     }
     try {
-        return new WebGL2Hal(canvas, passes, uniformByteSize);
+        return await WebGL2Hal.create(canvas, passes, sampleCount);
     }
     catch (e) {
         console.warn('[GPU] WebGL2 unavailable, falling back to Canvas2D:', e);

package/esm/hal/deviceGpuCache.d.ts

@@ -1,36 +1,31 @@
-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;
+import type { PipelineDescriptor, SampleCount, ShaderBinding } from './types.ts';
+/** A pass's one bind-group layout, and the pipeline layout holding it as group 0. */
+export interface PassLayout {
+    bindGroupLayout: GPUBindGroupLayout;
+    pipelineLayout: 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.
+ * A render pass's bind-group layout, read off its shader's reflected table:
+ * each binding visible to exactly the stages that read it, so the layout
+ * cannot disagree with the shader about which stage reads what. The uniform
+ * block takes a dynamic offset into the HAL's ring.
  */
-export declare function getDeviceLayouts(device: GPUDevice): DeviceLayouts;
+export declare function bindGroupLayoutEntries(bindings: readonly ShaderBinding[]): GPUBindGroupLayoutEntry[];
 /**
- * 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}).
+ * What a pipeline is compiled from and cached under: `WebGPUHal` builds from
+ * nothing else. `uniformByteSize` stays out, since the layouts declare no
+ * `minBindingSize`, and so does the page-wide canvas format.
  */
+export interface PipelineRecipe {
+    wgslSource: string;
+    bindGroupLayout: GPUBindGroupLayoutEntry[];
+    vertexBuffer: GPUVertexBufferLayout;
+    blend: GPUBlendState | undefined;
+    topology: GPUPrimitiveTopology;
+    /** Baked in: a pipeline built at 4 draws nothing into a target at 1. */
+    sampleCount: SampleCount;
+}
+export declare function pipelineRecipe(desc: PipelineDescriptor, wgslSource: string, sampleCount: SampleCount): PipelineRecipe;
+export declare function getPassLayout(device: GPUDevice, entries: GPUBindGroupLayoutEntry[]): PassLayout;
+export declare function getOrBuildPipeline(device: GPUDevice, recipe: PipelineRecipe, build: (recipe: PipelineRecipe) => Promise<GPURenderPipeline>): Promise<GPURenderPipeline>;
 export declare function resetDeviceGpuCacheForTests(device: GPUDevice): void;