@jbrowse/render-core 5.0.0-beta.7 → 5.0.0-beta.9

package/esm/displayPhase.d.ts

@@ -1,16 +1,20 @@
 /**
  * The mutually-exclusive visual state of a GPU display. Computing it in one
- * place means the precedence — renderError > tooLarge > error > loading > ready
- * — lives in a single function instead of being re-encoded by subtraction
- * (`&& !regionTooLarge && !error && !renderError`) in every display model AND
- * mirrored a second time by `DisplayChrome`'s JSX order. `DisplayChrome`
- * switches on it; the loading scrim's visibility is just
- * `displayPhase === 'loading'`, computed once in the chrome.
+ * place means the precedence — renderError > tooLarge > error > canceled >
+ * loading > ready — lives in a single function instead of being re-encoded by
+ * subtraction (`&& !regionTooLarge && !error && !renderError`) in every display
+ * model AND mirrored a second time by `DisplayChrome`'s JSX order.
  *
  * `renderError` and `tooLarge` replace the whole display subtree (their own
  * root element, so the transition unmounts the canvas → `canvasRef(null)` →
- * `backend.dispose()`). `error` and `loading` are overlays rendered *over* the
- * still-mounted canvas, so they share the `ready` branch's root.
+ * `backend.dispose()`). `error`, `canceled` and `loading` are overlays rendered
+ * *over* the still-mounted canvas, so they share the `ready` branch's root.
+ *
+ * `loading` is the one phase that means work is outstanding: every reader
+ * asking "is it finished" (`AppReadyMarker`, `jb.waitReady`, the capture waits)
+ * treats every other phase as finished. `canceled` is the user's standing stop,
+ * durable until Retry (or, on the LGV families, a viewport change); the chrome
+ * draws it as the loading overlay in its canceled state, which carries Retry.
  */
 export type DisplayPhase = 'renderError' | DisplayStatusPhase;
 /**
@@ -20,10 +24,14 @@ export type DisplayPhase = 'renderError' | DisplayStatusPhase;
  * (the backend hook's `retry()`), which is exactly the line between the shared
  * status chrome and the GPU chrome wrapped around it: `DisplayStatusChrome`
  * takes this, `DisplayChrome` takes the wider union and peels off `renderError`
- * before delegating. A main-thread SVG display (arc) computes this one and is
- * then *unable* to claim a phase whose banner has no retry to offer.
+ * before delegating.
+ */
+export type DisplayStatusPhase = 'tooLarge' | 'error' | DisplayActivityPhase;
+/**
+ * What is left once no failure terminal holds, as `computeActivityPhase`
+ * answers it for every fetching family.
  */
-export type DisplayStatusPhase = 'tooLarge' | 'error' | 'loading' | 'ready';
+export type DisplayActivityPhase = 'canceled' | 'loading' | 'ready';
 export interface DisplayStatusPhaseInputs {
     regionTooLarge: boolean;
     error: unknown;
@@ -32,133 +40,95 @@ export interface DisplayPhaseInputs extends DisplayStatusPhaseInputs {
     renderError: unknown;
 }
 /**
- * `loading` is the only display-specific axis: MultiRegion passes
- * "!isReady || stale viewport", Global passes "fetch in flight", sequence
- * layers a zoom gate on top. The terminal precedence above it is identical for
- * every display, so it lives here — pass the display's loading condition and
- * get the resolved phase back.
+ * The terminal precedence shared by every display, over the display's own
+ * activity phase.
  *
- * `loading` is a **thunk**, evaluated only after the three terminal states are
- * ruled out. This is load-bearing for MobX, not a micro-optimization: the
- * loading condition typically reads the containing view (`visibleRegions`,
- * `loadedRegions`, …), a large reactive dependency set. Evaluating it eagerly
- * would make every reader of `displayPhase` subscribe to all of it even while a
- * banner is up — and `DisplayChrome`'s observer, re-firing on that churn during
- * a terminal state, then fails to commit the banner subtree to the DOM (the
- * React-reconciliation hazard documented in DisplayChrome.tsx). Short-circuiting
- * keeps the tracked set to just the terminal flags when one is active, matching
- * the old direct-read early-returns.
+ * `activity` is a **thunk**, evaluated only after the three failure terminals
+ * are ruled out. Load-bearing for MobX: the activity condition typically reads
+ * the containing view (`visibleRegions`, `loadedRegions`, …), and evaluating it
+ * eagerly would subscribe every reader of `displayPhase` to that churn even
+ * while a banner is up — and `DisplayChrome`'s observer, re-firing during a
+ * terminal state, then fails to commit the banner subtree (see
+ * DisplayChrome.tsx).
  */
-export declare function computeDisplayPhase({ renderError, regionTooLarge, error }: DisplayPhaseInputs, loading: () => boolean): DisplayPhase;
+export declare function computeDisplayPhase({ renderError, regionTooLarge, error }: DisplayPhaseInputs, activity: () => DisplayActivityPhase): DisplayPhase;
 /**
- * The five terms the `loading` condition is built from, minus the one that is a
- * thunk. All cheap flags on the display itself, so they are read eagerly the
- * same way `computeDisplayPhase` reads its terminals.
+ * The terms the activity phase is built from, minus the thunks. All cheap flags
+ * on the display itself, so they are read eagerly the same way
+ * `computeDisplayPhase` reads its terminals.
  */
-export interface DisplayLoadingInputs {
+export interface DisplayActivityInputs {
+    /**
+     * The containing track is minimized. Every fetch gate skips a minimized
+     * track and its canvas is unmounted, so nothing the terms below wait on can
+     * arrive. Suppresses them all, like `fetchInert`, which a subclass overrides
+     * outright and so cannot carry it.
+     */
+    isMinimized: boolean;
     /**
      * The display is deliberately showing a static message instead of data
-     * (sequence past base resolution, LD with the triangle off), so no scrim at
-     * all. Suppresses every term below — which is why `rendersCanvas: false` is
-     * not a substitute: that one drops the pre-first-paint term alone, leaving the
-     * fetch terms free to scrim over the placeholder, and `isLoadingOrCanceled`
-     * includes a cancel that is deliberately durable.
+     * (sequence past base resolution, LD with the triangle off). Suppresses every
+     * term below, a standing cancel included — which is why `rendersCanvas: false`
+     * is not a substitute: that one drops the pre-first-paint term alone.
      */
     fetchInert: boolean;
     /**
-     * The view holds no content block, so there is nothing to fetch and nothing
-     * to paint: `showAllRegions` over a region set whose every member falls under
-     * `minimumBlockWidth`, which is a scaffold-level assembly and little else (see
-     * `viewportEmpty`). Suppresses every term below for the same reason
-     * `fetchInert` does, and it is the pre-first-paint one that makes it
-     * necessary: no fetch is issued, so `canvasDrawn` is never set and the scrim
-     * would sit there for as long as the viewport stays off content.
+     * The view holds no content block (`showAllRegions` over a region set whose
+     * every member falls under `minimumBlockWidth`; see `viewportEmpty`), so no
+     * fetch is issued and `canvasDrawn` is never set. Suppresses every term below.
      */
     viewportEmpty: boolean;
+    /** a fetch is in flight */
+    isLoading: boolean;
     /**
-     * A fetch is in flight, or the user canceled one. **Never a bare
-     * `isLoading`**: cancel drops the stop token synchronously, so without the
-     * second term the phase falls to `ready` and the overlay carrying the Retry
-     * button unmounts, leaving the display stopped and empty with nothing to
-     * click.
+     * The user canceled a fetch and has not retried. Outranks every loading term,
+     * since what those wait on is the fetch the user stopped. Kept apart from
+     * `isLoading` because a cancel is finished, not pending: folded into the
+     * loading term, a canceled display read `loading` until Retry and parked every
+     * readiness gate on it.
      */
-    isLoadingOrCanceled: boolean;
+    fetchCanceled: boolean;
     /**
      * A load this display depends on beyond its primary fetch has not landed for
-     * the first time, so the frame the primary fetch calls current is still
-     * missing something (multi-way synteny's lane genes and links). A loading
-     * term rather than a `dataSuperseded` fold: that flag holds the export
-     * through every later refetch too, and a scrim over lanes that are already
-     * drawn is the thing a display saying this wants to avoid.
+     * the first time (multi-way synteny's lane genes and links). A loading term
+     * rather than a `dataSuperseded` fold: that flag holds the export through
+     * every later refetch too, and a scrim over lanes already drawn is the thing
+     * a display saying this wants to avoid.
      */
     awaitingDependentData: boolean;
     /**
      * Whether this display paints a canvas in its current configuration. Gates
-     * the pre-first-paint term alone, because a display that is showing a
-     * deliberate non-canvas placeholder (LD with the triangle off) never flips
-     * `canvasDrawn` and would sit under the scrim forever.
+     * the pre-first-paint term alone, because a display showing a deliberate
+     * non-canvas placeholder (LD with the triangle off) never flips `canvasDrawn`.
      */
     rendersCanvas: boolean;
     /** first paint has happened */
     canvasDrawn: boolean;
 }
 /**
- * The `loading` term itself — the one axis `computeDisplayPhase` leaves to its
- * caller — expressed once for both LGV display families.
+ * The activity phase, expressed once for every fetching display family, so a
+ * term added here reaches every display. The two LGV families hand-wrote it
+ * until they had drifted on the cancel term and on which suppression hook each
+ * carried.
  *
- * It was two hand-written expressions, and they had already drifted apart in
- * three ways that were equivalent only by accident: the per-region family spelled
- * the cancel term out by hand (`!isReady || … || fetchCanceled`, over a bare
- * `isLoading`) rather than reading `isLoadingOrCanceled`, and each family carried
- * exactly one of the two suppression hooks — `fetchInert` on per-region,
- * `rendersCanvas` on global — so a display in the other family could express its
- * case only by overriding `displayPhase`, which is the thing both hooks exist to
- * prevent. Single-sourcing the expression is the same argument the precedence
- * above already won, one level down: a term added here reaches every display,
- * instead of reaching whichever family the author happened to be reading.
- *
- * The four inputs all now live on a mixin every foundation composes —
- * `fetchInert` / `isLoadingOrCanceled` on `FetchMixin`, `rendersCanvas` /
- * `canvasDrawn` on `RenderLifecycleMixin` — so `foundationDisplayPhase` passes
- * the model straight through and the only thing a family supplies is
- * `viewportCurrent`: per-region its staleness predicate, global `() => true` (it
- * keeps the last frame up through a refetch rather than scrimming). Two hooks
- * used to be hard-coded per family instead, which is how the second drift
- * happened after the first was fixed — LD needed `fetchInert` and the
- * global family did not have it.
- *
- * `viewportCurrent` is a **thunk** for the same MobX reason `computeDisplayPhase`'s
- * `loading` is: it reads the containing view (`visibleRegions`, `loadedRegions`),
- * while the flag inputs above are on the display itself. Short-circuiting keeps a
- * suppressed or already-loading display from subscribing to viewport churn.
+ * `viewportCurrent` is a **thunk** for the MobX reason `computeDisplayPhase`'s
+ * `activity` is: it reads the containing view, while the flags above are on the
+ * display. Per-region passes its staleness predicate, global `() => true` (it
+ * keeps the last frame up through a refetch rather than scrimming).
  *
  * `hostMounted` is a thunk for the same reason, and gates the **pre-first-paint
- * term only**. A container that mounts a view's body lazily — `ViewContainer`
- * does, to stay under the WebGL2 context ceiling — leaves an off-screen view
- * with no canvas, so `markCanvasDrawn` is never called and `!canvasDrawn` stays
- * true with nothing able to resolve it. That parked `[data-app-phase="ready"]`
- * for the whole app on a view the user could not see, and every capture and e2e
- * gate waiting on it burned its full timeout.
- *
- * It is a required flag on every view and on the duck-typed host contracts, not
- * an optional one defaulted here: a stand-in that forgot it would silently
- * excuse the first paint and let a readiness gate fire over a view that had not
- * started.
- *
- * The fetch terms deliberately stay live while unmounted: an off-screen display
- * still fetches, so reporting it idle would let a readiness gate fire over work
- * genuinely in flight — and during cold load `visible` is false until the
- * IntersectionObserver's first callback, which is exactly when a display must
- * not flash `ready`. Only the paint it will never do is excused.
+ * term only**. `ViewContainer` mounts an off-screen view's body lazily, so its
+ * display has no canvas and `!canvasDrawn` could never resolve — which parked
+ * `[data-app-phase="ready"]` for the whole app. It is required on every view and
+ * host contract rather than defaulted there, so a stand-in has to state it and
+ * cannot excuse the first paint by omission. The fetch terms stay live while unmounted: an
+ * off-screen display still fetches, and during cold load `visible` is false
+ * until the IntersectionObserver's first callback.
  */
-export declare function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }: DisplayLoadingInputs, viewportCurrent: () => boolean, hostMounted?: () => boolean): boolean;
+export declare function computeActivityPhase({ isMinimized, fetchInert, viewportEmpty, isLoading, fetchCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }: DisplayActivityInputs, viewportCurrent: () => boolean, hostMounted?: () => boolean): DisplayActivityPhase;
 /**
  * The same ranking minus `renderError`, for a display with no rendering backend
- * to fail (arc's main-thread SVG). `computeDisplayPhase` delegates here rather
- * than restating the tail, so there is still exactly one place the order lives —
- * and the narrower return type is what lets `DisplayStatusChrome` accept a
- * backend-less display without either a cast or a dead branch.
- *
- * `loading` is a thunk here for the same reason as above.
+ * to fail (arc's main-thread SVG). `computeDisplayPhase` delegates here, so the
+ * order lives in one place.
  */
-export declare function computeDisplayStatusPhase({ regionTooLarge, error }: DisplayStatusPhaseInputs, loading: () => boolean): DisplayStatusPhase;
+export declare function computeDisplayStatusPhase({ regionTooLarge, error }: DisplayStatusPhaseInputs, activity: () => DisplayActivityPhase): DisplayStatusPhase;

package/esm/displayPhase.js

@@ -1,98 +1,57 @@
 /**
- * `loading` is the only display-specific axis: MultiRegion passes
- * "!isReady || stale viewport", Global passes "fetch in flight", sequence
- * layers a zoom gate on top. The terminal precedence above it is identical for
- * every display, so it lives here — pass the display's loading condition and
- * get the resolved phase back.
- *
- * `loading` is a **thunk**, evaluated only after the three terminal states are
- * ruled out. This is load-bearing for MobX, not a micro-optimization: the
- * loading condition typically reads the containing view (`visibleRegions`,
- * `loadedRegions`, …), a large reactive dependency set. Evaluating it eagerly
- * would make every reader of `displayPhase` subscribe to all of it even while a
- * banner is up — and `DisplayChrome`'s observer, re-firing on that churn during
- * a terminal state, then fails to commit the banner subtree to the DOM (the
- * React-reconciliation hazard documented in DisplayChrome.tsx). Short-circuiting
- * keeps the tracked set to just the terminal flags when one is active, matching
- * the old direct-read early-returns.
+ * The terminal precedence shared by every display, over the display's own
+ * activity phase.
+ *
+ * `activity` is a **thunk**, evaluated only after the three failure terminals
+ * are ruled out. Load-bearing for MobX: the activity condition typically reads
+ * the containing view (`visibleRegions`, `loadedRegions`, …), and evaluating it
+ * eagerly would subscribe every reader of `displayPhase` to that churn even
+ * while a banner is up — and `DisplayChrome`'s observer, re-firing during a
+ * terminal state, then fails to commit the banner subtree (see
+ * DisplayChrome.tsx).
  */
-export function computeDisplayPhase({ renderError, regionTooLarge, error }, loading) {
+export function computeDisplayPhase({ renderError, regionTooLarge, error }, activity) {
     return renderError
         ? 'renderError'
-        : computeDisplayStatusPhase({ regionTooLarge, error }, loading);
+        : computeDisplayStatusPhase({ regionTooLarge, error }, activity);
 }
 /**
- * The `loading` term itself — the one axis `computeDisplayPhase` leaves to its
- * caller — expressed once for both LGV display families.
- *
- * It was two hand-written expressions, and they had already drifted apart in
- * three ways that were equivalent only by accident: the per-region family spelled
- * the cancel term out by hand (`!isReady || … || fetchCanceled`, over a bare
- * `isLoading`) rather than reading `isLoadingOrCanceled`, and each family carried
- * exactly one of the two suppression hooks — `fetchInert` on per-region,
- * `rendersCanvas` on global — so a display in the other family could express its
- * case only by overriding `displayPhase`, which is the thing both hooks exist to
- * prevent. Single-sourcing the expression is the same argument the precedence
- * above already won, one level down: a term added here reaches every display,
- * instead of reaching whichever family the author happened to be reading.
- *
- * The four inputs all now live on a mixin every foundation composes —
- * `fetchInert` / `isLoadingOrCanceled` on `FetchMixin`, `rendersCanvas` /
- * `canvasDrawn` on `RenderLifecycleMixin` — so `foundationDisplayPhase` passes
- * the model straight through and the only thing a family supplies is
- * `viewportCurrent`: per-region its staleness predicate, global `() => true` (it
- * keeps the last frame up through a refetch rather than scrimming). Two hooks
- * used to be hard-coded per family instead, which is how the second drift
- * happened after the first was fixed — LD needed `fetchInert` and the
- * global family did not have it.
+ * The activity phase, expressed once for every fetching display family, so a
+ * term added here reaches every display. The two LGV families hand-wrote it
+ * until they had drifted on the cancel term and on which suppression hook each
+ * carried.
  *
- * `viewportCurrent` is a **thunk** for the same MobX reason `computeDisplayPhase`'s
- * `loading` is: it reads the containing view (`visibleRegions`, `loadedRegions`),
- * while the flag inputs above are on the display itself. Short-circuiting keeps a
- * suppressed or already-loading display from subscribing to viewport churn.
+ * `viewportCurrent` is a **thunk** for the MobX reason `computeDisplayPhase`'s
+ * `activity` is: it reads the containing view, while the flags above are on the
+ * display. Per-region passes its staleness predicate, global `() => true` (it
+ * keeps the last frame up through a refetch rather than scrimming).
  *
  * `hostMounted` is a thunk for the same reason, and gates the **pre-first-paint
- * term only**. A container that mounts a view's body lazily — `ViewContainer`
- * does, to stay under the WebGL2 context ceiling — leaves an off-screen view
- * with no canvas, so `markCanvasDrawn` is never called and `!canvasDrawn` stays
- * true with nothing able to resolve it. That parked `[data-app-phase="ready"]`
- * for the whole app on a view the user could not see, and every capture and e2e
- * gate waiting on it burned its full timeout.
- *
- * It is a required flag on every view and on the duck-typed host contracts, not
- * an optional one defaulted here: a stand-in that forgot it would silently
- * excuse the first paint and let a readiness gate fire over a view that had not
- * started.
- *
- * The fetch terms deliberately stay live while unmounted: an off-screen display
- * still fetches, so reporting it idle would let a readiness gate fire over work
- * genuinely in flight — and during cold load `visible` is false until the
- * IntersectionObserver's first callback, which is exactly when a display must
- * not flash `ready`. Only the paint it will never do is excused.
+ * term only**. `ViewContainer` mounts an off-screen view's body lazily, so its
+ * display has no canvas and `!canvasDrawn` could never resolve — which parked
+ * `[data-app-phase="ready"]` for the whole app. It is required on every view and
+ * host contract rather than defaulted there, so a stand-in has to state it and
+ * cannot excuse the first paint by omission. The fetch terms stay live while unmounted: an
+ * off-screen display still fetches, and during cold load `visible` is false
+ * until the IntersectionObserver's first callback.
  */
-export function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
-    return (!fetchInert &&
-        !viewportEmpty &&
-        (isLoadingOrCanceled ||
-            awaitingDependentData ||
-            (rendersCanvas && hostMounted() && !canvasDrawn) ||
-            !viewportCurrent()));
+export function computeActivityPhase({ isMinimized, fetchInert, viewportEmpty, isLoading, fetchCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
+    return isMinimized || fetchInert || viewportEmpty
+        ? 'ready'
+        : fetchCanceled
+            ? 'canceled'
+            : isLoading ||
+                awaitingDependentData ||
+                (rendersCanvas && hostMounted() && !canvasDrawn) ||
+                !viewportCurrent()
+                ? 'loading'
+                : 'ready';
 }
 /**
  * The same ranking minus `renderError`, for a display with no rendering backend
- * to fail (arc's main-thread SVG). `computeDisplayPhase` delegates here rather
- * than restating the tail, so there is still exactly one place the order lives —
- * and the narrower return type is what lets `DisplayStatusChrome` accept a
- * backend-less display without either a cast or a dead branch.
- *
- * `loading` is a thunk here for the same reason as above.
+ * to fail (arc's main-thread SVG). `computeDisplayPhase` delegates here, so the
+ * order lives in one place.
  */
-export function computeDisplayStatusPhase({ regionTooLarge, error }, loading) {
-    return regionTooLarge
-        ? 'tooLarge'
-        : error
-            ? 'error'
-            : loading()
-                ? 'loading'
-                : 'ready';
+export function computeDisplayStatusPhase({ regionTooLarge, error }, activity) {
+    return regionTooLarge ? 'tooLarge' : error ? 'error' : activity();
 }

package/esm/gpuDevice.d.ts

@@ -5,7 +5,8 @@ interface GpuDeviceCell {
     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
@@ -16,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>;
@@ -46,10 +47,10 @@ export declare function onDeviceLost(listener: () => void): () => void;
  * 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'];
@@ -63,8 +64,8 @@ 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;

package/esm/gpuDevice.js

@@ -11,13 +11,12 @@
  * 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
@@ -188,10 +187,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'];
@@ -207,8 +206,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)) {

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.
@@ -77,9 +77,8 @@ export declare function getGraphicsCapabilities(): Promise<GraphicsCapabilities>
  * 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
+ * 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)

package/esm/graphicsCapabilities.js

@@ -50,7 +50,7 @@ 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
@@ -123,9 +123,8 @@ export function getGraphicsCapabilities() {
  * 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
+ * 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)

package/esm/hal/createHal.js

@@ -91,7 +91,7 @@ async function climbLadder(canvas, { passes, sampleCount, failures }) {
         }
     }
     try {
-        return new WebGL2Hal(canvas, passes);
+        return await WebGL2Hal.create(canvas, passes);
     }
     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;