@jbrowse/render-core 4.3.0

package/esm/perRegionRenderingBackend.d.ts

@@ -0,0 +1,114 @@
+import { Canvas2DRenderingBackendBase, GpuRenderingBackendBase } from './renderingBackendBase.ts';
+import type { BlockClipResult } from './blockClipUtils.ts';
+import type { InstancePass } from './instancePass.ts';
+import type { RenderBlock } from './renderBlock.ts';
+import type { FrameDimensions, RenderingBackend } from './renderingBackendBase.ts';
+export type { FrameDimensions } from './renderingBackendBase.ts';
+/**
+ * Shared contract for per-region streamed GPU backends.
+ *
+ * The model owns the data (`rpcDataMap` / `laidOutDataMap`); the backend
+ * uploads what's needed to the GPU (`upload`, one region per key) and draws
+ * against a data map passed back through `renderBlocks` each frame.
+ *
+ * `UploadData` is what the upload-side autorun pushes per region;
+ * `RenderData` is what the render-side reads. They default to the same
+ * type — MAF is the lone case where they diverge (upload payload also
+ * carries a pre-encoded GPU buffer that the render side doesn't need).
+ *
+ * Renderers are stateless: they keep no per-region cache. Canvas2D backends
+ * stub `upload` / `release` as no-ops since they read everything from the
+ * `regions` map at render time. GPU backends use `upload` to push bytes into
+ * HAL buffers, and `release` to drop a departed region's buffers.
+ */
+export interface PerRegionRenderingBackend<UploadData, RenderState, Block = RenderBlock, RenderData = UploadData> extends RenderingBackend {
+    upload(displayedRegionIndex: number, data: UploadData): void;
+    release(displayedRegionIndex: number): void;
+    /**
+     * Paint one frame and report whether real content reached the canvas. The
+     * render callback forwards this straight to `RenderLifecycleMixin`, which
+     * flips `canvasDrawn` (the loading scrim, `data-display-drawn`, every browser
+     * test's wait) only on `true` — so a tick that drew nothing must answer
+     * `false` rather than let a display assert doneness over an empty canvas.
+     *
+     * The two bases answer at different precision on purpose. GPU knows exactly
+     * ("a `drawRegion` ran", after the region-absent and offscreen-clip guards);
+     * Canvas2D delegates clipping to the plugin's `drawXxxBlocks` and so answers
+     * "some block had region data", which is the same for every case a display
+     * can distinguish and avoids re-running `clipBlockForCanvas` purely for a
+     * predicate.
+     */
+    renderBlocks(blocks: Block[], regions: ReadonlyMap<number, RenderData>, state: RenderState): boolean;
+}
+/**
+ * Canvas2D-side base for `PerRegionRenderingBackend` implementations. Inherits
+ * the `canvas` + 2D context (and no-op `dispose`) from
+ * `Canvas2DRenderingBackendBase`; stubs the upload/prune hooks the backend shape
+ * requires but Canvas2D doesn't need (everything comes through `draw` from the
+ * model's data map).
+ *
+ * `renderBlocks` is concrete: it runs `prepareCanvas` (DPR-aware backing-store
+ * sizing — symmetric to the GPU base owning `resize`/scissor) and then calls
+ * the abstract `draw`. Subclasses implement only `draw`, which delegates to the
+ * plugin's pure `drawXxxBlocks` function (also shared with SVG export). Keeping
+ * `prepareCanvas` in the base means a renderer can't forget it and render
+ * blurry on hi-DPI.
+ */
+export declare abstract class Canvas2DPerRegionRenderingBackend<UploadData, RenderState extends FrameDimensions, Block extends RenderBlock = RenderBlock, RenderData = UploadData> extends Canvas2DRenderingBackendBase implements PerRegionRenderingBackend<UploadData, RenderState, Block, RenderData> {
+    upload(): void;
+    release(): void;
+    renderBlocks(blocks: Block[], regions: ReadonlyMap<number, RenderData>, state: RenderState): boolean;
+    /**
+     * Paint the visible blocks into `this.ctx` (already DPR-prepared). Delegates
+     * to the plugin's pure `drawXxxBlocks(ctx, regions, blocks, state)` function.
+     */
+    protected abstract draw(blocks: Block[], regions: ReadonlyMap<number, RenderData>, state: RenderState): void;
+}
+/**
+ * GPU-side base for `PerRegionRenderingBackend` implementations. Inherits the
+ * `hal` reference, the pre-allocated uniform scratch `ArrayBuffer`, and the
+ * HAL-delegating `dispose` from `GpuRenderingBackendBase`; adds the shared
+ * `release` (delegates to HAL).
+ *
+ * `renderBlocks` is a concrete frame scaffold shared by every per-region GPU
+ * renderer: resize the backing store, `beginFrame`/`endFrame`, and per block
+ * compute the scissor clip + set scissor/viewport. The scaffold's invariants
+ * (paired begin/end, cleared scissor/viewport, the skip-absent-region and
+ * skip-offscreen guards) are owned here so a subclass can't forget them.
+ * Subclasses implement only `drawRegion`, which writes uniforms and issues
+ * draw passes for one already-clipped block.
+ */
+export declare abstract class GpuPerRegionRenderingBackend<UploadData, RenderState extends FrameDimensions, Block extends RenderBlock = RenderBlock, RenderData = UploadData> extends GpuRenderingBackendBase implements PerRegionRenderingBackend<UploadData, RenderState, Block, RenderData> {
+    release(displayedRegionIndex: number): void;
+    /**
+     * The passes this backend fills from one region's payload, each carrying its
+     * own packer. Usually the same array handed to `createRenderingBackend` —
+     * minus any pass that draws off another's buffer (wiggle's line passes,
+     * canvas's chevron), which is registered but never uploaded to.
+     */
+    protected abstract regionPasses: InstancePass<UploadData>[];
+    /**
+     * Pack and upload every pass for one region.
+     *
+     * Concrete for the same reason `renderBlocks` below is: the invariants are
+     * the base's to keep. Each subclass used to write this, and each wrote the
+     * empty case differently — `if (count === 0) deleteRegion() else upload()`
+     * five times, an unconditional leading `deleteRegion()` once. Both spellings
+     * exist because a pass whose data went empty must not keep drawing its last
+     * buffer, and `uploadPass` gets that from the HAL: an empty pack deletes that
+     * pass's buffer, so a multi-pass backend clears exactly the passes that went
+     * empty instead of dropping the whole region and rebuilding it.
+     *
+     * Override only for a payload no packer can take — none does today.
+     */
+    upload(displayedRegionIndex: number, data: UploadData): void;
+    renderBlocks(blocks: Block[], regions: ReadonlyMap<number, RenderData>, state: RenderState): boolean;
+    /**
+     * Write uniforms and issue draw passes for one block whose scissor/viewport
+     * are already set to its clipped span. `clip` carries the HP-split bp range
+     * and pixel dimensions; `region` is the model's per-region data (used by
+     * renderers that read per-region uniforms like an outline color, ignored by
+     * those whose draw state is fully in the uploaded buffer).
+     */
+    protected abstract drawRegion(block: Block, clip: BlockClipResult, region: RenderData, state: RenderState): void;
+}

package/esm/perRegionRenderingBackend.js

@@ -0,0 +1,93 @@
+import { clipBlock } from './blockClipUtils.js';
+import { prepareCanvas } from './canvas2dUtils.js';
+import { uploadPass } from './instancePass.js';
+import { Canvas2DRenderingBackendBase, GpuRenderingBackendBase, } from './renderingBackendBase.js';
+/**
+ * Canvas2D-side base for `PerRegionRenderingBackend` implementations. Inherits
+ * the `canvas` + 2D context (and no-op `dispose`) from
+ * `Canvas2DRenderingBackendBase`; stubs the upload/prune hooks the backend shape
+ * requires but Canvas2D doesn't need (everything comes through `draw` from the
+ * model's data map).
+ *
+ * `renderBlocks` is concrete: it runs `prepareCanvas` (DPR-aware backing-store
+ * sizing — symmetric to the GPU base owning `resize`/scissor) and then calls
+ * the abstract `draw`. Subclasses implement only `draw`, which delegates to the
+ * plugin's pure `drawXxxBlocks` function (also shared with SVG export). Keeping
+ * `prepareCanvas` in the base means a renderer can't forget it and render
+ * blurry on hi-DPI.
+ */
+export class Canvas2DPerRegionRenderingBackend extends Canvas2DRenderingBackendBase {
+    upload() { }
+    release() { }
+    renderBlocks(blocks, regions, state) {
+        prepareCanvas(this.canvas, this.ctx, state.canvasWidth, state.canvasHeight);
+        this.draw(blocks, regions, state);
+        return blocks.some(block => regions.has(block.displayedRegionIndex));
+    }
+}
+/**
+ * GPU-side base for `PerRegionRenderingBackend` implementations. Inherits the
+ * `hal` reference, the pre-allocated uniform scratch `ArrayBuffer`, and the
+ * HAL-delegating `dispose` from `GpuRenderingBackendBase`; adds the shared
+ * `release` (delegates to HAL).
+ *
+ * `renderBlocks` is a concrete frame scaffold shared by every per-region GPU
+ * renderer: resize the backing store, `beginFrame`/`endFrame`, and per block
+ * compute the scissor clip + set scissor/viewport. The scaffold's invariants
+ * (paired begin/end, cleared scissor/viewport, the skip-absent-region and
+ * skip-offscreen guards) are owned here so a subclass can't forget them.
+ * Subclasses implement only `drawRegion`, which writes uniforms and issues
+ * draw passes for one already-clipped block.
+ */
+export class GpuPerRegionRenderingBackend extends GpuRenderingBackendBase {
+    release(displayedRegionIndex) {
+        this.hal.deleteRegion(displayedRegionIndex);
+    }
+    /**
+     * Pack and upload every pass for one region.
+     *
+     * Concrete for the same reason `renderBlocks` below is: the invariants are
+     * the base's to keep. Each subclass used to write this, and each wrote the
+     * empty case differently — `if (count === 0) deleteRegion() else upload()`
+     * five times, an unconditional leading `deleteRegion()` once. Both spellings
+     * exist because a pass whose data went empty must not keep drawing its last
+     * buffer, and `uploadPass` gets that from the HAL: an empty pack deletes that
+     * pass's buffer, so a multi-pass backend clears exactly the passes that went
+     * empty instead of dropping the whole region and rebuilding it.
+     *
+     * Override only for a payload no packer can take — none does today.
+     */
+    upload(displayedRegionIndex, data) {
+        for (const pass of this.regionPasses) {
+            uploadPass(this.hal, displayedRegionIndex, pass, data);
+        }
+    }
+    renderBlocks(blocks, regions, state) {
+        const { canvasWidth, canvasHeight } = state;
+        let painted = false;
+        // The scale the canvas ACTUALLY got, which is `getDpr()` until the backing
+        // store clamps and below it after. Read from the resize rather than the
+        // window, so a track dragged past the clamp draws at reduced resolution
+        // instead of asking for a viewport its target cannot hold.
+        const scale = this.hal.resize(canvasWidth, canvasHeight);
+        // Always pair beginFrame/endFrame so the canvas clears to transparent even
+        // when every block is skipped (e.g. all regions pruned by a density gate).
+        this.hal.beginFrame(0, 0, 0, 0);
+        for (const block of blocks) {
+            const region = regions.get(block.displayedRegionIndex);
+            if (region !== undefined) {
+                const clip = clipBlock(block, canvasWidth, canvasHeight, scale);
+                if (clip) {
+                    this.hal.setScissor(clip.pxX, 0, clip.pxW, clip.pxH);
+                    this.hal.setViewport(clip.pxX, 0, clip.pxW, clip.pxH);
+                    this.drawRegion(block, clip, region, state);
+                    painted = true;
+                }
+            }
+        }
+        this.hal.clearScissor();
+        this.hal.clearViewport();
+        this.hal.endFrame();
+        return painted;
+    }
+}

package/esm/recoveryBudget.d.ts

@@ -0,0 +1,40 @@
+export declare const MAX_RECOVERIES = 2;
+export declare const RECOVERY_WINDOW_MS = 60000;
+export type RecoveryVerdict = 'recover' | 'give-up';
+/**
+ * The recovery budget a display spends re-initializing its rendering backend
+ * after a lost WebGL context or a lost WebGPU device.
+ *
+ * The budget is **windowed, not lifetime**. A context that resolves and then
+ * immediately re-loses has to keep climbing toward the cap — that is the flap
+ * the cap exists for, and it happens within seconds. But two unrelated losses
+ * an hour apart are not a flap, and a lifetime counter cannot tell them apart:
+ * it spends the second loss's budget on the first one's and leaves a
+ * long-running session permanently unable to auto-recover. Counting over a
+ * window separates the two without needing to know which kind of loss it saw.
+ *
+ * `now` is passed in rather than read, so the caller owns the clock and this
+ * stays testable without fake timers.
+ */
+export declare class RecoveryBudget {
+    private count;
+    private lastAt;
+    private readonly max;
+    private readonly windowMs;
+    constructor(max?: number, windowMs?: number);
+    /**
+     * Record a loss and say whether to recover from it. Call this **only when
+     * about to act** on the answer — it is a mutation, and calling it
+     * speculatively (this hook's recovery effect runs on every render) would
+     * refresh the window forever and the count would never lapse.
+     */
+    record(now: number): RecoveryVerdict;
+    /** Which attempt the loss just recorded is — drives the backoff exponent. */
+    get attempt(): number;
+    /**
+     * Back to a clean slate, for the two events that mean the trouble is over: a
+     * genuine `webglcontextrestored` and a manual Retry. A successful re-init is
+     * deliberately NOT one of them — every flap contains one.
+     */
+    reset(): void;
+}

package/esm/recoveryBudget.js

@@ -0,0 +1,56 @@
+// How many recoveries a display may attempt before it stops and leaves the
+// manual Retry button, and the window those attempts are counted over.
+export const MAX_RECOVERIES = 2;
+export const RECOVERY_WINDOW_MS = 60_000;
+/**
+ * The recovery budget a display spends re-initializing its rendering backend
+ * after a lost WebGL context or a lost WebGPU device.
+ *
+ * The budget is **windowed, not lifetime**. A context that resolves and then
+ * immediately re-loses has to keep climbing toward the cap — that is the flap
+ * the cap exists for, and it happens within seconds. But two unrelated losses
+ * an hour apart are not a flap, and a lifetime counter cannot tell them apart:
+ * it spends the second loss's budget on the first one's and leaves a
+ * long-running session permanently unable to auto-recover. Counting over a
+ * window separates the two without needing to know which kind of loss it saw.
+ *
+ * `now` is passed in rather than read, so the caller owns the clock and this
+ * stays testable without fake timers.
+ */
+export class RecoveryBudget {
+    count = 0;
+    // "No loss yet" — any first `record` yields 1 down either branch, so nothing
+    // turns on the value, but -Infinity says it in a way a 0 read off the same
+    // clock as `now` does not.
+    lastAt = -Infinity;
+    max;
+    windowMs;
+    constructor(max = MAX_RECOVERIES, windowMs = RECOVERY_WINDOW_MS) {
+        this.max = max;
+        this.windowMs = windowMs;
+    }
+    /**
+     * Record a loss and say whether to recover from it. Call this **only when
+     * about to act** on the answer — it is a mutation, and calling it
+     * speculatively (this hook's recovery effect runs on every render) would
+     * refresh the window forever and the count would never lapse.
+     */
+    record(now) {
+        this.count = now - this.lastAt > this.windowMs ? 1 : this.count + 1;
+        this.lastAt = now;
+        return this.count > this.max ? 'give-up' : 'recover';
+    }
+    /** Which attempt the loss just recorded is — drives the backoff exponent. */
+    get attempt() {
+        return this.count;
+    }
+    /**
+     * Back to a clean slate, for the two events that mean the trouble is over: a
+     * genuine `webglcontextrestored` and a manual Retry. A successful re-init is
+     * deliberately NOT one of them — every flap contains one.
+     */
+    reset() {
+        this.count = 0;
+        this.lastAt = -Infinity;
+    }
+}

package/esm/regionDataMap.d.ts

@@ -0,0 +1,60 @@
+import type { ObservableMap } from 'mobx';
+export declare function isCheckedAtTheStore(map: ReadonlyMap<unknown, unknown>): boolean;
+/**
+ * The volatile a display keys its per-region payloads by
+ * (`displayedRegionIndex` → result). Every one of them in tree is built with
+ * this, so "how is per-region data represented" has one answer — see
+ * ADR-060.
+ *
+ * **Shallow, and that follows from an invariant the codebase already states**:
+ * per-region values are freshly constructed and never mutated (agent-docs
+ * CLAUDE.md; backends diff by reference identity). Nothing inside an entry can
+ * therefore change, so the deep enhancer's field-level atoms can never fire —
+ * they are unreachable reactivity, not a safety margin. What they do cost is
+ * paid on every insert and every read:
+ *
+ * - **Insert.** `deepEnhancer` recursively rebuilds each payload as an
+ *   observable object graph — the stored value is not the object the worker
+ *   produced. A multi-wiggle region is one atom per field per source, so a
+ *   thousand-sample track pays ~18k on every pan; MAF pays the whole set again
+ *   for every cached region on every row reorder, since `placeFetchedRows`
+ *   re-places them all.
+ * - **Read.** Each field access goes through `getObservablePropValue_`. Hot
+ *   loops that hoist their typed arrays are fine, but the ones that don't were
+ *   paying it per iteration.
+ *
+ * Typed arrays and class instances (Flatbush) pass through the deep enhancer
+ * untouched, so the arrays were never the cost — the objects holding them were.
+ *
+ * Coarser tracking is the only behavioral difference, and it is unobservable
+ * here: an entry is only ever replaced whole, so the keys atom and the entry's
+ * own atom fire on exactly the same `.set`/`.delete`/`.clear`.
+ *
+ * Not for maps of primitives (`groupMaxHeightOverrides`,
+ * `detectedModifications`), where the enhancer is a no-op, nor for UI state
+ * whose values are mutated in place.
+ *
+ * **Dev-only, every entry is checked on the way in.** A fetch RPC answers a
+ * payload or a `regionTooLarge` refusal, and every reader of this map is
+ * written for the payload — so a value that is not one is a fetch that did not
+ * happen, stored as though it had. There is no type to catch it: `onResult`
+ * receives whatever the RPC resolved, typed as the payload it was supposed to
+ * be, and the mock in the display harness resolved `undefined` for every
+ * un-stubbed method for as long as the harness existed. Six reactions across
+ * four packages then threw `Cannot read properties of undefined` on every run,
+ * inside autoruns MobX catches and logs — invisible until the reaction gate
+ * went in.
+ *
+ * Checked HERE because this is the one constructor all of them share, so the
+ * store is one place while the readers are hundreds, and because a payload
+ * caught at the `set` names the region and the display instead of surfacing as
+ * a TypeError in whichever getter happened to read it first.
+ *
+ * **`T extends object` is the same statement as the check, in the one place a
+ * type can make it.** The runtime predicate is "a non-null object", and
+ * `object` is that predicate spelled as a constraint — so a map cannot be
+ * *declared* as holding something the check would then report, which is the
+ * only way the two could come apart. It costs nothing: every payload in tree is
+ * an interface, an array, an intersection or a class.
+ */
+export declare function regionDataMap<T extends object>(name: string): ObservableMap<number, T>;

package/esm/regionDataMap.js

@@ -0,0 +1,98 @@
+import { observable } from 'mobx';
+// Maps built here check themselves at the `set`, so the upload seam skips them
+// and a bad entry is reported once, with the field named.
+//
+// Module state, and duplication-safe in the only way that matters here: two
+// live copies of this package would each hold their own set, so a map built by
+// one and installed through the other is checked twice rather than missed.
+const checkedAtTheStore = new WeakSet();
+export function isCheckedAtTheStore(map) {
+    return checkedAtTheStore.has(map);
+}
+/**
+ * The volatile a display keys its per-region payloads by
+ * (`displayedRegionIndex` → result). Every one of them in tree is built with
+ * this, so "how is per-region data represented" has one answer — see
+ * ADR-060.
+ *
+ * **Shallow, and that follows from an invariant the codebase already states**:
+ * per-region values are freshly constructed and never mutated (agent-docs
+ * CLAUDE.md; backends diff by reference identity). Nothing inside an entry can
+ * therefore change, so the deep enhancer's field-level atoms can never fire —
+ * they are unreachable reactivity, not a safety margin. What they do cost is
+ * paid on every insert and every read:
+ *
+ * - **Insert.** `deepEnhancer` recursively rebuilds each payload as an
+ *   observable object graph — the stored value is not the object the worker
+ *   produced. A multi-wiggle region is one atom per field per source, so a
+ *   thousand-sample track pays ~18k on every pan; MAF pays the whole set again
+ *   for every cached region on every row reorder, since `placeFetchedRows`
+ *   re-places them all.
+ * - **Read.** Each field access goes through `getObservablePropValue_`. Hot
+ *   loops that hoist their typed arrays are fine, but the ones that don't were
+ *   paying it per iteration.
+ *
+ * Typed arrays and class instances (Flatbush) pass through the deep enhancer
+ * untouched, so the arrays were never the cost — the objects holding them were.
+ *
+ * Coarser tracking is the only behavioral difference, and it is unobservable
+ * here: an entry is only ever replaced whole, so the keys atom and the entry's
+ * own atom fire on exactly the same `.set`/`.delete`/`.clear`.
+ *
+ * Not for maps of primitives (`groupMaxHeightOverrides`,
+ * `detectedModifications`), where the enhancer is a no-op, nor for UI state
+ * whose values are mutated in place.
+ *
+ * **Dev-only, every entry is checked on the way in.** A fetch RPC answers a
+ * payload or a `regionTooLarge` refusal, and every reader of this map is
+ * written for the payload — so a value that is not one is a fetch that did not
+ * happen, stored as though it had. There is no type to catch it: `onResult`
+ * receives whatever the RPC resolved, typed as the payload it was supposed to
+ * be, and the mock in the display harness resolved `undefined` for every
+ * un-stubbed method for as long as the harness existed. Six reactions across
+ * four packages then threw `Cannot read properties of undefined` on every run,
+ * inside autoruns MobX catches and logs — invisible until the reaction gate
+ * went in.
+ *
+ * Checked HERE because this is the one constructor all of them share, so the
+ * store is one place while the readers are hundreds, and because a payload
+ * caught at the `set` names the region and the display instead of surfacing as
+ * a TypeError in whichever getter happened to read it first.
+ *
+ * **`T extends object` is the same statement as the check, in the one place a
+ * type can make it.** The runtime predicate is "a non-null object", and
+ * `object` is that predicate spelled as a constraint — so a map cannot be
+ * *declared* as holding something the check would then report, which is the
+ * only way the two could come apart. It costs nothing: every payload in tree is
+ * an interface, an array, an intersection or a class.
+ */
+export function regionDataMap(
+// the field this map is stored on, so a violation names the map rather than
+// the thirteen that share this constructor. No default — an omitted name is
+// the anonymous message this parameter exists to remove, and it would be
+// reached by forgetting rather than by deciding.
+name) {
+    const map = observable.map(undefined, { deep: false, name });
+    if (process.env.NODE_ENV !== 'production') {
+        checkedAtTheStore.add(map);
+        const set = map.set.bind(map);
+        map.set = (key, value) => {
+            // as `unknown`, because the claim that this is a `T` is the thing in
+            // doubt — checking it against its own declared type narrows to `never`
+            // and checks nothing
+            const stored = value;
+            if (typeof stored !== 'object' || stored === null) {
+                // `console.error`, never `throw`: the store runs inside the fetch's own
+                // result handler, where a throw is caught and reported as a failed
+                // region — which would hide the violation being reported.
+                console.error(`[jbrowse display contract] ${name}: region ${key} stored ` +
+                    `\`${stored === null ? 'null' : typeof stored}\`, not a ` +
+                    'payload. A fetch RPC answers a payload or a regionTooLarge ' +
+                    'refusal; storing anything else leaves every reader of this map ' +
+                    'reading through it.');
+            }
+            return set(key, value);
+        };
+    }
+    return map;
+}

package/esm/renderBlock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A region's genomic span paired with its on-screen pixel span. The base
+ * geometry every backend works in: GPU clip math (`clipBlock`), Canvas2D clip
+ * (`clipBlockForCanvas`), the bp→px mapper (`makeBpMapper`), and canvas
+ * SVG/label/peptide positioning all consume this shape.
+ */
+export interface BpRegionBounds {
+    start: number;
+    end: number;
+    screenStartPx: number;
+    screenEndPx: number;
+    reversed?: boolean;
+}
+/**
+ * A `BpRegionBounds` tagged with the `displayedRegionIndex` that joins it to
+ * `rpcDataMap` / HAL buffers. `reversed` is resolved (always present) once a
+ * block reaches the render path.
+ */
+export interface RenderBlock extends BpRegionBounds {
+    displayedRegionIndex: number;
+    reversed: boolean;
+}
+export declare function buildRenderBlocks(regions: (BpRegionBounds & {
+    displayedRegionIndex: number;
+})[]): RenderBlock[];

package/esm/renderBlock.js

@@ -0,0 +1,10 @@
+export function buildRenderBlocks(regions) {
+    return regions.map(r => ({
+        displayedRegionIndex: r.displayedRegionIndex,
+        start: r.start,
+        end: r.end,
+        screenStartPx: r.screenStartPx,
+        screenEndPx: r.screenEndPx,
+        reversed: r.reversed ?? false,
+    }));
+}

package/esm/renderingBackendBase.d.ts

@@ -0,0 +1,71 @@
+import type { GpuHal } from './hal/types.ts';
+/**
+ * Minimum render-state shape a frame scaffold needs: the CSS-pixel canvas
+ * dimensions used to size the backing store, and — on the per-region side —
+ * to clip each block.
+ *
+ * Here rather than beside either family because both bound their render state
+ * by it: `GpuPerRegionRenderingBackend.renderBlocks` and
+ * `GpuGlobalRenderingBackend.render` open with the same `hal.resize`, and the
+ * two Canvas2D bases with the same `prepareCanvas`.
+ */
+export interface FrameDimensions {
+    canvasWidth: number;
+    canvasHeight: number;
+}
+/**
+ * What every rendering backend has, whatever its upload shape — the three
+ * shape contracts (`PerRegionRenderingBackend`, `GlobalRenderingBackend`,
+ * `KeyedRenderingBackend`) all extend this, and `useRenderingBackend` is
+ * bounded by it.
+ *
+ * `setErrorHandler` is here rather than optional at the hook because it was
+ * optional at the hook, and the three backends that then went without it —
+ * alignments, dotplot and multi-LGV synteny, which allocate the largest vertex
+ * buffers in the app — were the three whose over-limit allocations reached
+ * nobody: the HAL reported "too much data to render on this GPU, zoom in", the
+ * reporter's handler was null, and the view painted blank with a console line.
+ * The displays had their error banners built and wired the whole time.
+ *
+ * Extending `GpuRenderingBackendBase` or `Canvas2DRenderingBackendBase` below
+ * satisfies it, which is the intended way to get it.
+ */
+export interface RenderingBackend {
+    /**
+     * Route a HAL over-limit allocation to the display's `renderError`. Wired by
+     * `useRenderingBackend` once the backend is live; a no-op on Canvas2D, which
+     * allocates no GPU resources.
+     */
+    setErrorHandler(handler: (error: Error) => void): void;
+    dispose(): void;
+}
+/**
+ * Shared GPU-side state for every GPU rendering backend — both per-region
+ * (`GpuPerRegionRenderingBackend`) and monolithic (`GpuGlobalRenderingBackend`).
+ * Owns the `hal` reference and a pre-allocated uniform scratch `ArrayBuffer`
+ * reused across frames to avoid per-frame GC churn. `dispose()` delegates to
+ * the HAL. Subclasses add only their upload/render shape.
+ */
+export declare abstract class GpuRenderingBackendBase {
+    protected hal: GpuHal;
+    protected uniformData: ArrayBuffer;
+    constructor(hal: GpuHal, uniformByteSize: number);
+    setErrorHandler(handler: (error: Error) => void): void;
+    dispose(): void;
+}
+/**
+ * Shared Canvas2D-side state for every Canvas2D rendering backend — both
+ * per-region (`Canvas2DPerRegionRenderingBackend`) and monolithic
+ * (`Canvas2DGlobalRenderingBackend`). Owns the `canvas` and its 2D context
+ * (constructor throws if unavailable). `dispose()` is a no-op since Canvas2D
+ * holds no GPU resources. Subclasses add only their render shape and stub the
+ * upload/prune hooks their interface requires (everything flows through the
+ * model's data map at render time).
+ */
+export declare abstract class Canvas2DRenderingBackendBase {
+    protected canvas: HTMLCanvasElement;
+    protected ctx: CanvasRenderingContext2D;
+    constructor(canvas: HTMLCanvasElement);
+    setErrorHandler(_handler: (error: Error) => void): void;
+    dispose(): void;
+}

package/esm/renderingBackendBase.js

@@ -0,0 +1,50 @@
+import { acquireCanvas2D } from './canvasContext.js';
+/**
+ * Shared GPU-side state for every GPU rendering backend — both per-region
+ * (`GpuPerRegionRenderingBackend`) and monolithic (`GpuGlobalRenderingBackend`).
+ * Owns the `hal` reference and a pre-allocated uniform scratch `ArrayBuffer`
+ * reused across frames to avoid per-frame GC churn. `dispose()` delegates to
+ * the HAL. Subclasses add only their upload/render shape.
+ */
+export class GpuRenderingBackendBase {
+    hal;
+    uniformData;
+    constructor(hal, uniformByteSize) {
+        this.hal = hal;
+        this.uniformData = new ArrayBuffer(uniformByteSize);
+    }
+    // Forward OOM / over-limit allocation failures from the HAL to the display's
+    // renderError. Wired by useRenderingBackend once the backend is live.
+    setErrorHandler(handler) {
+        this.hal.setErrorHandler(handler);
+    }
+    dispose() {
+        this.hal.dispose();
+    }
+}
+/**
+ * Shared Canvas2D-side state for every Canvas2D rendering backend — both
+ * per-region (`Canvas2DPerRegionRenderingBackend`) and monolithic
+ * (`Canvas2DGlobalRenderingBackend`). Owns the `canvas` and its 2D context
+ * (constructor throws if unavailable). `dispose()` is a no-op since Canvas2D
+ * holds no GPU resources. Subclasses add only their render shape and stub the
+ * upload/prune hooks their interface requires (everything flows through the
+ * model's data map at render time).
+ */
+export class Canvas2DRenderingBackendBase {
+    canvas;
+    ctx;
+    constructor(canvas) {
+        // Canvas2D is the ladder's last rung, so this is where a re-init on a reused
+        // element lands — and a bare "not available" sends the reader looking for a
+        // missing browser feature instead of the committed context actually in the
+        // way. `acquireCanvas2D` names which (canvasContext.ts).
+        this.ctx = acquireCanvas2D(canvas);
+        this.canvas = canvas;
+    }
+    // Canvas2D allocates no GPU resources, so there is no OOM channel to forward.
+    // Present for symmetry with the GPU base so useRenderingBackend can wire both
+    // uniformly.
+    setErrorHandler(_handler) { }
+    dispose() { }
+}

package/esm/shaders/antialias.js.generated.d.ts

@@ -0,0 +1,4 @@
+export declare function aaPx(dpr: number): number;
+export declare function aaHalfPx(dpr: number): number;
+export declare function aaRamp(signedInk: number, widthPx: number): number;
+export declare function edgeCoverage(signedInkCssPx: number, dpr: number): number;

package/esm/shaders/antialias.js.generated.js

@@ -0,0 +1,25 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from antialias.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+// Scalar twins of antialias.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+function _clamp(x, lo, hi) {
+    return _min(_max(x, lo), hi);
+}
+function _max(a, b) {
+    return b > a || Number.isNaN(a) ? b : a;
+}
+function _min(a, b) {
+    return b < a || Number.isNaN(a) ? b : a;
+}
+export function aaPx(dpr) {
+    return (1.0 / _max(dpr, 1.0));
+}
+export function aaHalfPx(dpr) {
+    return (0.5 * aaPx(dpr));
+}
+export function aaRamp(signedInk, widthPx) {
+    return _clamp(((signedInk / widthPx) + 0.5), 0.0, 1.0);
+}
+export function edgeCoverage(signedInkCssPx, dpr) {
+    return aaRamp(signedInkCssPx, aaPx(dpr));
+}

package/esm/shaders/capsule.generated.d.ts

@@ -0,0 +1 @@
+export declare const CAPSULE_MIN_LEN_PX = 0.0001;