@jbrowse/render-core 4.3.0 → 5.0.0-beta.10

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/waiting-on-a-number/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/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,124 +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;
+    /**
+     * 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.
+     */
+    fetchCanceled: 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.
+     * A load this display depends on beyond its primary fetch has not landed for
+     * 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.
      */
-    isLoadingOrCanceled: boolean;
+    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.
- *
- * 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 declare function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, 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,97 +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, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
-    return (!fetchInert &&
-        !viewportEmpty &&
-        (isLoadingOrCanceled ||
-            (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/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/gpuContextLostError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Flagged rather than matched by message or `instanceof`, so the error UI can
+ * offer the remedy specific to a loss (switch the page to Canvas2D) without
+ * offering it for render errors whose remedy differs (an over-allocation says to
+ * zoom in).
+ *
+ * A lost WebGPU device carries the same flag deliberately: the two causes
+ * differ, but the remedy on offer — take the page off the GPU — is the same one.
+ *
+ * React-free, and split out of `useRenderingBackend` for that reason: the HAL
+ * raises the surface error below and must not import a hook to do it.
+ * `useRenderingBackend` re-exports these, so every existing import site keeps
+ * working.
+ */
+export declare function createGpuContextLostError(message?: string): Error & {
+    gpuContextLost: true;
+};
+export declare function createGpuDeviceLostError(): Error & {
+    gpuContextLost: true;
+};
+/**
+ * A canvas whose swap-chain image the driver refuses. Distinct from a device
+ * loss, because the device is fine and still renders offscreen, and distinct
+ * from an over-limit allocation, because zooming in does not fix it. Canvas2D
+ * does, which is why this carries the flag that puts that button on the banner.
+ */
+export declare function createGpuSurfaceLostError(detail: string): Error & {
+    gpuContextLost: true;
+};
+export declare function isGpuContextLostError(error: unknown): error is object & Record<"gpuContextLost", unknown>;

package/esm/gpuContextLostError.js

@@ -0,0 +1,40 @@
+const CONTEXT_LOST_MESSAGE = 'WebGL context lost. The browser reclaimed the GPU context for this display, ' +
+    'usually because too many GPU-rendered views are open at once.';
+const DEVICE_LOST_MESSAGE = 'WebGPU device lost. The GPU device backing this display went away and kept ' +
+    'going away after several attempts to rebuild on a fresh one.';
+const SURFACE_LOST_MESSAGE = 'WebGPU could not give this display a drawable surface. The GPU driver ' +
+    'rejected the canvas image, so every frame this display submits is discarded.';
+/**
+ * Flagged rather than matched by message or `instanceof`, so the error UI can
+ * offer the remedy specific to a loss (switch the page to Canvas2D) without
+ * offering it for render errors whose remedy differs (an over-allocation says to
+ * zoom in).
+ *
+ * A lost WebGPU device carries the same flag deliberately: the two causes
+ * differ, but the remedy on offer — take the page off the GPU — is the same one.
+ *
+ * React-free, and split out of `useRenderingBackend` for that reason: the HAL
+ * raises the surface error below and must not import a hook to do it.
+ * `useRenderingBackend` re-exports these, so every existing import site keeps
+ * working.
+ */
+export function createGpuContextLostError(message = CONTEXT_LOST_MESSAGE) {
+    return Object.assign(new Error(message), {
+        gpuContextLost: true,
+    });
+}
+export function createGpuDeviceLostError() {
+    return createGpuContextLostError(DEVICE_LOST_MESSAGE);
+}
+/**
+ * A canvas whose swap-chain image the driver refuses. Distinct from a device
+ * loss, because the device is fine and still renders offscreen, and distinct
+ * from an over-limit allocation, because zooming in does not fix it. Canvas2D
+ * does, which is why this carries the flag that puts that button on the banner.
+ */
+export function createGpuSurfaceLostError(detail) {
+    return createGpuContextLostError(`${SURFACE_LOST_MESSAGE} (${detail})`);
+}
+export function isGpuContextLostError(error) {
+    return (typeof error === 'object' && error !== null && 'gpuContextLost' in error);
+}