@jbrowse/render-core 4.3.0

package/esm/canvasContext.js

@@ -0,0 +1,74 @@
+const KIND_LABELS = {
+    webgpu: 'WebGPU',
+    webgl2: 'WebGL2',
+    '2d': 'Canvas 2D',
+};
+const acquired = new WeakMap();
+const configuredBy = new WeakMap();
+/**
+ * Record `owner` as the holder of `canvas`'s current WebGPU configuration.
+ *
+ * `getContext('webgpu')` hands back the **same** `GPUCanvasContext` object every
+ * time, so a configuration is per-element state that two HALs can end up
+ * sharing: a re-init on a reused element (a display whose `model` prop swaps
+ * under it, an init that overlaps a cancelled one) builds a second HAL on the
+ * same context, and `unconfigure()` from whichever loses the race takes the
+ * winner's swap chain with it. Firefox then throws `InvalidStateError:
+ * GPUCanvasContext.getCurrentTexture: Canvas not configured` on every frame the
+ * live HAL draws, forever — the browser fires no context-lost event for it, so
+ * none of the loss recovery in `useRenderingBackend` ever runs.
+ *
+ * Last configure wins, which is the live one: a cancelled init is disposed, and
+ * disposal is the only thing that unconfigures.
+ */
+export function noteCanvasConfigured(canvas, owner) {
+    configuredBy.set(canvas, owner);
+}
+/** Whether `owner`'s configuration is still the one on `canvas`. */
+export function canvasConfiguredBy(canvas, owner) {
+    return configuredBy.get(canvas) === owner;
+}
+/**
+ * Record that `canvas` is now permanently committed to `kind`. Call on every
+ * **successful** `getContext`, in every HAL and every Canvas2D backend — a kind
+ * that isn't recorded is one the diagnosis below can't name, and it will fall
+ * back to the vaguer message.
+ */
+export function noteCanvasContext(canvas, kind) {
+    acquired.set(canvas, kind);
+}
+/** The kind this canvas is committed to, if we were the ones who took it. */
+export function acquiredCanvasContext(canvas) {
+    return acquired.get(canvas);
+}
+/**
+ * `getContext('2d')` + null-check + bookkeeping, as one call. Every Canvas2D
+ * backend hand-wrote that ritual with the same bare message, which is four
+ * copies of a diagnosis to keep in step — and three of them belong to the two
+ * consumers whose canvas *never* unmounts (dotplot, the synteny level), i.e.
+ * exactly where a reused element is reachable.
+ */
+export function acquireCanvas2D(canvas) {
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw canvasContextError(canvas, '2d');
+    }
+    noteCanvasContext(canvas, '2d');
+    return ctx;
+}
+/**
+ * The error to throw when `getContext(requested)` returned null.
+ *
+ * Keeps each caller's historical message as the first clause (`Canvas 2D context
+ * not available`, and tests match on it) and appends the *reason*, which is the
+ * part that was missing: either "this element is already committed to X" — the
+ * recoverable case, with the remedy named — or an honest statement of the two
+ * possibilities when we don't know.
+ */
+export function canvasContextError(canvas, requested) {
+    const prior = acquiredCanvasContext(canvas);
+    const head = `${KIND_LABELS[requested]} context not available`;
+    return new Error(prior !== undefined && prior !== requested
+        ? `${head}: this <canvas> element is already committed to a ${KIND_LABELS[prior]} context, and a canvas's context kind is permanent. This is a re-init on a reused element — it needs a fresh one. Mount the canvas with RenderCanvas (@jbrowse/render-core/RenderCanvas), which keys it on useRenderingBackend's canvasKey.`
+        : `${head}: getContext('${requested}') returned null. Either this browser/machine does not support it, or the element is already committed to a different context kind (a canvas's kind is permanent once acquired).`);
+}

package/esm/colorRampLut.d.ts

@@ -0,0 +1,17 @@
+import type { GpuHal } from './hal/index.ts';
+/**
+ * Entries in a colour-ramp LUT, and so the width of the texture every ramp
+ * consumer binds. Off the shader that samples it: `rampColor` divides by this
+ * to land entry i on its own texel center, so a table built to a different
+ * number is a half-shade of drift at every entry.
+ */
+export declare const COLOR_RAMP_LUT_ENTRIES = 256;
+/**
+ * Upload a 256-entry RGBA colour-ramp LUT as each named pass's 256×1 texture —
+ * the runtime half of the shared ramp mechanism whose shader half is
+ * `shaders/colorRampLut.slang`. HiC, LD (whose two shader variants are the
+ * reason this takes a pass list) and wiggle density all put their ramps behind
+ * their samplers through this one call; each keeps its own scale and its own
+ * LUT contents.
+ */
+export declare function uploadColorRampLut(hal: GpuHal, ramp: Uint8Array, passIds: readonly string[]): void;

package/esm/colorRampLut.js

@@ -0,0 +1,25 @@
+import { RAMP_LUT_ENTRIES } from './shaders/colorRampLut.generated.js';
+/**
+ * Entries in a colour-ramp LUT, and so the width of the texture every ramp
+ * consumer binds. Off the shader that samples it: `rampColor` divides by this
+ * to land entry i on its own texel center, so a table built to a different
+ * number is a half-shade of drift at every entry.
+ */
+export const COLOR_RAMP_LUT_ENTRIES = RAMP_LUT_ENTRIES;
+/**
+ * Upload a 256-entry RGBA colour-ramp LUT as each named pass's 256×1 texture —
+ * the runtime half of the shared ramp mechanism whose shader half is
+ * `shaders/colorRampLut.slang`. HiC, LD (whose two shader variants are the
+ * reason this takes a pass list) and wiggle density all put their ramps behind
+ * their samplers through this one call; each keeps its own scale and its own
+ * LUT contents.
+ */
+export function uploadColorRampLut(hal, ramp, passIds) {
+    if (ramp.length !== COLOR_RAMP_LUT_ENTRIES * 4) {
+        throw new Error(`uploadColorRampLut: expected a ${COLOR_RAMP_LUT_ENTRIES}-entry RGBA LUT ` +
+            `(${COLOR_RAMP_LUT_ENTRIES * 4} bytes), got ${ramp.length} bytes`);
+    }
+    for (const passId of passIds) {
+        hal.uploadTexture(passId, ramp, COLOR_RAMP_LUT_ENTRIES, 1);
+    }
+}

package/esm/coverageBand.d.ts

@@ -0,0 +1,107 @@
+import type { CoverageBandBuffers } from './coverageBandBuffers.ts';
+import type { InstancePass } from './instancePass.ts';
+export { coverageBandBuffers } from './coverageBandBuffers.ts';
+export type { CoverageBandBuffers } from './coverageBandBuffers.ts';
+export declare const COVERAGE_BAND_UNIFORMS_SIZE_BYTES = 112;
+/**
+ * The fifth buffer, base modifications stacked in the same bars. Separate
+ * because only one producer emits it — a MAF alignment carries no modification
+ * calls — and a display that has no mod data must not have to ship an empty
+ * buffer to satisfy the shape.
+ */
+export interface CoverageBandModBuffer {
+    modCovPackedBuffer: ArrayBuffer;
+}
+/**
+ * One draw layer of the coverage band, and the id of the GPU pass that draws it.
+ *
+ * The band is the same five marks wherever it appears — a display either has a
+ * layer's data or does not, and no display reorders them.
+ */
+export type CoverageLayerId = 'coverage' | 'snpCov' | 'modCov' | 'interbase' | 'indicator';
+/**
+ * The band's z-order, back to front: the depth bars, the SNP slices stacked
+ * inside them, the modification slices stacked on those, the interbase histogram
+ * hanging from the band top, and its indicator triangles above that.
+ *
+ * The order is load-bearing rather than cosmetic — the interbase bars hang down
+ * over the lower half the depth bars grow up into, so the two overlap at any
+ * real depth — and it is one fact, so it is stated once here and every backend
+ * of every display iterates it. It was stated per backend per display, which is
+ * how "MAF drew its band in a different order on the fallback" was a screenshot
+ * to catch rather than a compile error.
+ *
+ * What stays per display is the GATING, which genuinely differs: MAF has no
+ * `showInterbaseIndicators` setting and no modification data at all.
+ */
+export declare const COVERAGE_BAND_LAYER_ORDER: readonly CoverageLayerId[];
+/**
+ * Whatever a display attaches to each band layer — a GPU pass, a Canvas2D
+ * painter, a gate — resolved into paint order.
+ *
+ * The argument is exhaustive over `CoverageLayerId`, so a layer added to the
+ * order above is a compile error in every display until it is wired. `undefined`
+ * is how a display says it has no such layer (MAF carries no modification
+ * calls); it is dropped rather than drawn empty, which keeps a display that has
+ * no data for a layer from having to ship an empty buffer to satisfy the shape.
+ */
+export declare function orderCoverageBandLayers<T>(byId: Record<CoverageLayerId, T | undefined>): (T & ({} | null))[];
+export declare const COVERAGE_BAR_PASS: InstancePass<Pick<CoverageBandBuffers, 'coveragePackedBuffer'>>;
+export declare const COVERAGE_SNP_PASS: InstancePass<Pick<CoverageBandBuffers, 'snpPackedBuffer'>>;
+export declare const COVERAGE_MOD_PASS: InstancePass<CoverageBandModBuffer>;
+export declare const COVERAGE_INTERBASE_PASS: InstancePass<Pick<CoverageBandBuffers, 'interbasePackedBuffer'>>;
+export declare const COVERAGE_INDICATOR_PASS: InstancePass<Pick<CoverageBandBuffers, 'indicatorPackedBuffer'>>;
+/** Palette slots the band paints by name, each a packed ABGR u32. */
+export interface CoverageBandColors {
+    coverage: number;
+    baseA: number;
+    baseC: number;
+    baseG: number;
+    baseT: number;
+    baseN: number;
+    insertionIndicator: number;
+    softclipIndicator: number;
+    hardclipIndicator: number;
+}
+/**
+ * Everything the band's UBO holds that a caller actually decides. `hpZero` is
+ * absent because it is not one: it is a fixed sentinel the HP math needs — see
+ * `writeCoverageBandUniforms`.
+ */
+export interface CoverageBandUniformValues {
+    /** HP-split viewport start + visible span; keep `bpLen` POSITIVE and flip via `reversed`. */
+    bpHi: number;
+    bpLo: number;
+    bpLen: number;
+    /** The span clip [-1,1] covers horizontally — a block's scissored width, not the canvas. */
+    canvasW: number;
+    canvasH: number;
+    reversed: boolean;
+    /** Band box in CSS px: its height, the scalebar-label inset, and its top edge on the canvas. */
+    covHeight: number;
+    covYOffset: number;
+    covTop: number;
+    /** The region's own peak depth, which is what the buffers' `relDepth` is a fraction of. */
+    regionMaxDepth: number;
+    /** The display's autoscaled depth domain. `undefined` max = not resolved yet. */
+    domainMin: number;
+    domainMax: number | undefined;
+    /** 0 = linear, 1 = log2, 2 = symlog, matching wiggle-core's SCALE_TYPE_*. */
+    scaleType: number;
+    symlogConstant: number;
+    binSize: number;
+    /** `interbaseBarHeightPx` — the one rule the draw, the hit test and this share. */
+    interbaseHeight: number;
+    snpMinFrequency: number;
+    colors: CoverageBandColors;
+}
+/**
+ * Fill the coverage band's uniform buffer. Total-write (the generated packer),
+ * so a field left out is a compile error rather than last frame's value.
+ *
+ * `hpZero` is derived here rather than at each call site because getting it
+ * wrong is a silently wrong band, not a broken one: it MUST be 0, since the HP
+ * math materializes +inf as `1/hpZero` to stop the compiler folding the hi/lo
+ * split it exists to preserve.
+ */
+export declare function writeCoverageBandUniforms(buf: ArrayBuffer, v: CoverageBandUniformValues): void;

package/esm/coverageBand.js

@@ -0,0 +1,109 @@
+import * as coverageBarShader from './shaders/coverageBar.generated.js';
+import * as coverageIndicatorShader from './shaders/coverageIndicator.generated.js';
+import * as coverageInterbaseShader from './shaders/coverageInterbase.generated.js';
+import * as coverageModShader from './shaders/coverageMod.generated.js';
+import * as coverageSnpShader from './shaders/coverageSnp.generated.js';
+import { slangPass } from './slangPass.js';
+export { coverageBandBuffers } from './coverageBandBuffers.js';
+export const COVERAGE_BAND_UNIFORMS_SIZE_BYTES = coverageBarShader.UNIFORMS_SIZE_BYTES;
+/**
+ * The band's z-order, back to front: the depth bars, the SNP slices stacked
+ * inside them, the modification slices stacked on those, the interbase histogram
+ * hanging from the band top, and its indicator triangles above that.
+ *
+ * The order is load-bearing rather than cosmetic — the interbase bars hang down
+ * over the lower half the depth bars grow up into, so the two overlap at any
+ * real depth — and it is one fact, so it is stated once here and every backend
+ * of every display iterates it. It was stated per backend per display, which is
+ * how "MAF drew its band in a different order on the fallback" was a screenshot
+ * to catch rather than a compile error.
+ *
+ * What stays per display is the GATING, which genuinely differs: MAF has no
+ * `showInterbaseIndicators` setting and no modification data at all.
+ */
+export const COVERAGE_BAND_LAYER_ORDER = [
+    'coverage',
+    'snpCov',
+    'modCov',
+    'interbase',
+    'indicator',
+];
+/**
+ * Whatever a display attaches to each band layer — a GPU pass, a Canvas2D
+ * painter, a gate — resolved into paint order.
+ *
+ * The argument is exhaustive over `CoverageLayerId`, so a layer added to the
+ * order above is a compile error in every display until it is wired. `undefined`
+ * is how a display says it has no such layer (MAF carries no modification
+ * calls); it is dropped rather than drawn empty, which keeps a display that has
+ * no data for a layer from having to ship an empty buffer to satisfy the shape.
+ */
+export function orderCoverageBandLayers(byId) {
+    return COVERAGE_BAND_LAYER_ORDER.map(id => byId[id]).filter(layer => layer !== undefined);
+}
+// Each pass's instances are packed by the WORKER (or, for MAF, by the RPC that
+// stands in for one) in the shader's own layout, so every "packer" here is the
+// field the producer filled, uploaded verbatim. The layouts are generated from
+// these shaders into @jbrowse/alignments-core, which is what the producers pack
+// through.
+export const COVERAGE_BAR_PASS = {
+    ...slangPass({ id: 'coverage', mod: coverageBarShader }),
+    pack: data => data.coveragePackedBuffer,
+};
+export const COVERAGE_SNP_PASS = {
+    ...slangPass({ id: 'snpCov', mod: coverageSnpShader }),
+    pack: data => data.snpPackedBuffer,
+};
+export const COVERAGE_MOD_PASS = {
+    ...slangPass({ id: 'modCov', mod: coverageModShader }),
+    pack: data => data.modCovPackedBuffer,
+};
+export const COVERAGE_INTERBASE_PASS = {
+    ...slangPass({ id: 'interbase', mod: coverageInterbaseShader }),
+    pack: data => data.interbasePackedBuffer,
+};
+export const COVERAGE_INDICATOR_PASS = {
+    ...slangPass({ id: 'indicator', mod: coverageIndicatorShader }),
+    pack: data => data.indicatorPackedBuffer,
+};
+/**
+ * Fill the coverage band's uniform buffer. Total-write (the generated packer),
+ * so a field left out is a compile error rather than last frame's value.
+ *
+ * `hpZero` is derived here rather than at each call site because getting it
+ * wrong is a silently wrong band, not a broken one: it MUST be 0, since the HP
+ * math materializes +inf as `1/hpZero` to stop the compiler folding the hi/lo
+ * split it exists to preserve.
+ */
+export function writeCoverageBandUniforms(buf, v) {
+    const { domainMax, colors } = v;
+    coverageBarShader.writeUniforms(buf, {
+        bpHi: v.bpHi,
+        bpLo: v.bpLo,
+        bpLen: v.bpLen,
+        hpZero: 0,
+        canvasW: v.canvasW,
+        canvasH: v.canvasH,
+        covHeight: v.covHeight,
+        covYOffset: v.covYOffset,
+        covTop: v.covTop,
+        regionMaxDepth: v.regionMaxDepth,
+        depthDomainMax: domainMax ?? 0,
+        depthDomainMin: v.domainMin,
+        coverageSymlogConstant: v.symlogConstant,
+        binSize: v.binSize,
+        interbaseHeight: v.interbaseHeight,
+        snpMinFreq: v.snpMinFrequency,
+        reversed: v.reversed ? 1 : 0,
+        coverageScaleType: v.scaleType,
+        colorCoverage: colors.coverage,
+        colorBaseA: colors.baseA,
+        colorBaseC: colors.baseC,
+        colorBaseG: colors.baseG,
+        colorBaseT: colors.baseT,
+        colorBaseN: colors.baseN,
+        colorInsertionIndicator: colors.insertionIndicator,
+        colorSoftclipIndicator: colors.softclipIndicator,
+        colorHardclipIndicator: colors.hardclipIndicator,
+    });
+}

package/esm/coverageBandBuffers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The four coverage-band buffers a producer packs per region, in the layouts
+ * `coverageBand.slang`'s passes read. Every field is filled by
+ * `@jbrowse/alignments-core` — `packCoverageBinsForGpu`, `computeSNPCoverage`
+ * and `computeInterbaseCoverage` (which emits the last two) — so a display gets
+ * these by running that pipeline, not by shaping them itself.
+ *
+ * Structural rather than nominal, and named after the layout rather than after
+ * either display: the alignments worker's `CoverageUploadData` and the MAF
+ * worker's `MafCoverageRegion` both satisfy it, which is what lets the passes
+ * in `coverageBand.ts` carry their own packers instead of each plugin
+ * restating four field reads.
+ *
+ * Its own module, apart from the GPU passes in `coverageBand.ts`: a state
+ * model reaching for just this shape has no reason to statically pull in
+ * every coverage shader — GPU pass descriptors are a display's *renderer*
+ * concern, which is lazy-loaded, and a state model is not.
+ */
+export interface CoverageBandBuffers {
+    coveragePackedBuffer: ArrayBuffer;
+    snpPackedBuffer: ArrayBuffer;
+    interbasePackedBuffer: ArrayBuffer;
+    indicatorPackedBuffer: ArrayBuffer;
+}
+/**
+ * Just the band's four buffers out of a wider per-region payload — the field set
+ * stated once, so a display carrying them into its own upload payload cannot
+ * spell three of them.
+ */
+export declare function coverageBandBuffers(src: CoverageBandBuffers): CoverageBandBuffers;

package/esm/coverageBandBuffers.js

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

package/esm/createRenderingBackend.d.ts

@@ -0,0 +1,52 @@
+import type { GpuHal, PipelineDescriptor, SampleCount } from './hal/types.ts';
+/**
+ * Options for `createRenderingBackend`. The two factories are an options object
+ * (not positional args) on purpose: both are single-arg `(x) => new Backend(x)`
+ * lambdas, so positionally they're trivially swappable by mistake — naming them
+ * makes the GPU vs Canvas2D path unambiguous at every call site.
+ */
+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.
+     *
+     * **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.
+     */
+    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>;
+/**
+ * Factory for a **Canvas2D-only** display — one that ships no GPU shader path.
+ *
+ * Every display must already provide a Canvas2D draw function (SVG export needs
+ * it), so for a display whose data volume never demands the GPU (gene-scale
+ * annotations, low-density score tracks, text/sequence), the GPU renderer +
+ * shader are pure overhead. Such a display skips `createRenderingBackend`'s HAL
+ * ladder entirely and returns its Canvas2D backend directly through this
+ * helper. The backend then plugs into the exact same `RenderLifecycleMixin` /
+ * `DisplayChrome` machinery as a GPU display — the lifecycle is backend-
+ * agnostic, so nothing downstream knows or cares there's no HAL.
+ *
+ * Reference: `plugins/sequence`'s `SequenceRenderer`. Promote to the dual-path
+ * `createRenderingBackend` only once a profile shows Canvas2D can't keep 60fps
+ * at the display's real feature counts (≳100K features/frame — see
+ * RFC-001 §3a).
+ */
+export declare function createCanvas2DBackend<TRenderingBackend>(canvas: HTMLCanvasElement, createCanvas2DRenderingBackend: (canvas: HTMLCanvasElement) => TRenderingBackend): Promise<TRenderingBackend>;

package/esm/createRenderingBackend.js

@@ -0,0 +1,58 @@
+import { assertUniquePassIds, createGpuHal } from './hal/index.js';
+export async function createRenderingBackend(canvas, { passes, uniformByteSize, sampleCount = 4, 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
+    // must not be the one who cannot see it.
+    assertUniquePassIds(passes);
+    // Each rung's reason is collected rather than dropped in the console: if
+    // Canvas2D — the rung that cannot itself be fallen back from — also fails,
+    // "Canvas 2D context not available" on its own says nothing about *why* the
+    // two rungs above it declined, and those are usually the interesting part (a
+    // committed context from a previous init, a driver that lost the device). The
+    // error UI's stack-trace dialog walks `AggregateError.errors`, so bundling
+    // them is what puts them in front of whoever reports the bug.
+    const ladderFailures = [];
+    const hal = await createGpuHal(canvas, {
+        passes,
+        uniformByteSize,
+        sampleCount,
+        failures: ladderFailures,
+    });
+    if (hal) {
+        return createGpuBackend(hal);
+    }
+    try {
+        return createCanvas2DBackend(canvas);
+    }
+    catch (e) {
+        if (ladderFailures.length === 0) {
+            throw e;
+        }
+        // `e` is the last entry of the errors array, which says more than `cause`
+        // would: it places the Canvas2D failure in order behind the WebGPU and
+        // WebGL ones.
+        // oxlint-disable-next-line eslint/preserve-caught-error
+        throw new AggregateError([...ladderFailures, e], `No rendering backend could be created for this canvas: ${e}`);
+    }
+}
+/**
+ * Factory for a **Canvas2D-only** display — one that ships no GPU shader path.
+ *
+ * Every display must already provide a Canvas2D draw function (SVG export needs
+ * it), so for a display whose data volume never demands the GPU (gene-scale
+ * annotations, low-density score tracks, text/sequence), the GPU renderer +
+ * shader are pure overhead. Such a display skips `createRenderingBackend`'s HAL
+ * ladder entirely and returns its Canvas2D backend directly through this
+ * helper. The backend then plugs into the exact same `RenderLifecycleMixin` /
+ * `DisplayChrome` machinery as a GPU display — the lifecycle is backend-
+ * agnostic, so nothing downstream knows or cares there's no HAL.
+ *
+ * Reference: `plugins/sequence`'s `SequenceRenderer`. Promote to the dual-path
+ * `createRenderingBackend` only once a profile shows Canvas2D can't keep 60fps
+ * at the display's real feature counts (≳100K features/frame — see
+ * RFC-001 §3a).
+ */
+export function createCanvas2DBackend(canvas, createCanvas2DRenderingBackend) {
+    return Promise.resolve(createCanvas2DRenderingBackend(canvas));
+}

package/esm/displayPhase.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ *
+ * `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.
+ */
+export type DisplayPhase = 'renderError' | DisplayStatusPhase;
+/**
+ * The phases a display without a rendering backend can be in — every phase
+ * except the one that reports a backend failure. Its own type because
+ * `renderError` is the only phase whose UI needs something no model can supply
+ * (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.
+ */
+export type DisplayStatusPhase = 'tooLarge' | 'error' | 'loading' | 'ready';
+export interface DisplayStatusPhaseInputs {
+    regionTooLarge: boolean;
+    error: unknown;
+}
+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.
+ *
+ * `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.
+ */
+export declare function computeDisplayPhase({ renderError, regionTooLarge, error }: DisplayPhaseInputs, loading: () => boolean): 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.
+ */
+export interface DisplayLoadingInputs {
+    /**
+     * 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.
+     */
+    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.
+     */
+    viewportEmpty: 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.
+     */
+    isLoadingOrCanceled: 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.
+     */
+    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.
+ *
+ * `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.
+ *
+ * `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.
+ */
+export declare function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, rendersCanvas, canvasDrawn, }: DisplayLoadingInputs, viewportCurrent: () => boolean, hostMounted?: () => boolean): boolean;
+/**
+ * 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.
+ */
+export declare function computeDisplayStatusPhase({ regionTooLarge, error }: DisplayStatusPhaseInputs, loading: () => boolean): DisplayStatusPhase;