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

package/esm/RenderLifecycleMixin.d.ts

@@ -95,11 +95,11 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * never called and `canvasDrawn` can never flip).
      *
      * Lives here, beside `canvasDrawn`, because every consumer of "has this
-     * display painted" needs the pair — and until 2026-08 each family
-     * declared its own copy (per-region hard-coded `true`, global carried the
-     * hook for LD), so a display could express the state only to whichever
-     * family it happened to compose. See `painted` below for the reader that
-     * was missed.
+     * display painted" needs the pair. Both LGV fetch foundations fill it
+     * with `!fetchInert`, so a display there states its placeholder once,
+     * through that hook; the raw default reaches only a display composing
+     * this mixin outside them. See `painted` below for the reader that was
+     * missed while the two were separate overrides.
      */
     readonly rendersCanvas: boolean;
     /**
@@ -119,6 +119,23 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * and the two families compose the two mixins in opposite orders.
      */
     readonly paintInert: boolean;
+    /**
+     * #getter
+     * Overridable hook (default false): what is on the canvas was painted
+     * from data a later change has made wrong, so `painted` below should
+     * answer *pending* until the repaint lands even though `canvasDrawn` is
+     * still true. The per-region fetch foundation fills it with
+     * `staleSettingsDrawn` — held data drawn under settings that have since
+     * moved — which is the state `clearAllRpcData` used to express by
+     * resetting `canvasDrawn` on every settings change, blanking the display
+     * to do it. A capture waiting on `data-display-drawn` then waits for the
+     * refetch rather than snapshotting the previous setting's pixels.
+     *
+     * A hook and not a reset of the flag, because the flag is re-marked by
+     * any redraw — a pan between the settings change and the refetch would
+     * report the stale canvas drawn — and a derivation cannot be raced.
+     */
+    readonly paintSuperseded: boolean;
 } & {
     /**
      * #getter
@@ -140,7 +157,9 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      *
      * `paintInert` is the third term and the same argument once more, for the
      * state where a display *would* paint a canvas and never gets to — a fetch
-     * that failed before first paint. See that hook.
+     * that failed before first paint. `paintSuperseded` is the fourth, and
+     * the one that subtracts: a canvas painted from data a settings change
+     * has made wrong is drawn and not finished. See both hooks.
      */
     readonly painted: boolean;
 } & {

package/esm/RenderLifecycleMixin.js

@@ -104,11 +104,11 @@ export function RenderLifecycleMixin() {
          * never called and `canvasDrawn` can never flip).
          *
          * Lives here, beside `canvasDrawn`, because every consumer of "has this
-         * display painted" needs the pair — and until 2026-08 each family
-         * declared its own copy (per-region hard-coded `true`, global carried the
-         * hook for LD), so a display could express the state only to whichever
-         * family it happened to compose. See `painted` below for the reader that
-         * was missed.
+         * display painted" needs the pair. Both LGV fetch foundations fill it
+         * with `!fetchInert`, so a display there states its placeholder once,
+         * through that hook; the raw default reaches only a display composing
+         * this mixin outside them. See `painted` below for the reader that was
+         * missed while the two were separate overrides.
          */
         get rendersCanvas() {
             return true;
@@ -132,6 +132,25 @@ export function RenderLifecycleMixin() {
         get paintInert() {
             return false;
         },
+        /**
+         * #getter
+         * Overridable hook (default false): what is on the canvas was painted
+         * from data a later change has made wrong, so `painted` below should
+         * answer *pending* until the repaint lands even though `canvasDrawn` is
+         * still true. The per-region fetch foundation fills it with
+         * `staleSettingsDrawn` — held data drawn under settings that have since
+         * moved — which is the state `clearAllRpcData` used to express by
+         * resetting `canvasDrawn` on every settings change, blanking the display
+         * to do it. A capture waiting on `data-display-drawn` then waits for the
+         * refetch rather than snapshotting the previous setting's pixels.
+         *
+         * A hook and not a reset of the flag, because the flag is re-marked by
+         * any redraw — a pan between the settings change and the refetch would
+         * report the stale canvas drawn — and a derivation cannot be raced.
+         */
+        get paintSuperseded() {
+            return false;
+        },
     }))
         .views(self => ({
         /**
@@ -154,10 +173,14 @@ export function RenderLifecycleMixin() {
          *
          * `paintInert` is the third term and the same argument once more, for the
          * state where a display *would* paint a canvas and never gets to — a fetch
-         * that failed before first paint. See that hook.
+         * that failed before first paint. `paintSuperseded` is the fourth, and
+         * the one that subtracts: a canvas painted from data a settings change
+         * has made wrong is drawn and not finished. See both hooks.
          */
         get painted() {
-            return self.canvasDrawn || !self.rendersCanvas || self.paintInert;
+            return ((self.canvasDrawn && !self.paintSuperseded) ||
+                !self.rendersCanvas ||
+                self.paintInert);
         },
     }))
         .actions(self => ({

package/esm/canvas2dUtils.d.ts

@@ -203,6 +203,31 @@ export declare function strokeRectInside(ctx: {
  * Scalar in, scalar out: runs per feature per frame, so it must not allocate.
  */
 export declare function spanLeft(x1: number, x2: number, width: number): number;
+/**
+ * The `fillRect` x and width a genomic span paints as, given a bare
+ * `makeBpMapper`: `spanLeft`'s pivot and the min-width floor that goes with it,
+ * as one value a painter and its hit box can both read.
+ *
+ * `minWidth` defaults to 0, which makes this plain screen ordering — the
+ * leftmost projected edge and the unsigned distance. Pass a floor and the span
+ * grows away from `startBp`, which is the reversed-block rule `spanLeft` owns:
+ * anchoring the leftmost edge instead slides a sub-pixel mark by up to the floor
+ * on a flipped region and never on a forward one.
+ *
+ * Reach for this over `spanLeft` wherever the *numbers* are wanted rather than a
+ * fill — a hover box, an SVG rect, a cull test, an overlay div — which is where
+ * the pivot and the floor were being restated separately. The multi-row painter
+ * and the hover box it has to line up with each spelled out both.
+ * `fillBpSpan` is the same span when a `fillRect` is the only consumer.
+ *
+ * Not for a per-instance paint loop: this allocates a result per call, so the
+ * span mark's painter and wiggle's two bar loops take `spanLeft` and the two
+ * numbers inline, and stay the last hand-written copies of this arithmetic.
+ */
+export declare function spanRect(toX: (bp: number) => number, startBp: number, endBp: number, minWidth?: number): {
+    left: number;
+    width: number;
+};
 export declare function makeRampFillStyleLut(ramp: Uint8Array): (t: number) => string;
 export declare function bpToScreenPx(absBp: number, regionStart: number, regionEnd: number, screenStartPx: number, screenEndPx: number, reversed?: boolean): number;
 export declare function makeBpMapper(bounds: BpRegionBounds): (bp: number) => number;

package/esm/canvas2dUtils.js

@@ -334,6 +334,33 @@ export function strokeRectInside(ctx, x, y, w, h, lineWidth = 1) {
 export function spanLeft(x1, x2, width) {
     return x2 < x1 ? x1 - width : x1;
 }
+/**
+ * The `fillRect` x and width a genomic span paints as, given a bare
+ * `makeBpMapper`: `spanLeft`'s pivot and the min-width floor that goes with it,
+ * as one value a painter and its hit box can both read.
+ *
+ * `minWidth` defaults to 0, which makes this plain screen ordering — the
+ * leftmost projected edge and the unsigned distance. Pass a floor and the span
+ * grows away from `startBp`, which is the reversed-block rule `spanLeft` owns:
+ * anchoring the leftmost edge instead slides a sub-pixel mark by up to the floor
+ * on a flipped region and never on a forward one.
+ *
+ * Reach for this over `spanLeft` wherever the *numbers* are wanted rather than a
+ * fill — a hover box, an SVG rect, a cull test, an overlay div — which is where
+ * the pivot and the floor were being restated separately. The multi-row painter
+ * and the hover box it has to line up with each spelled out both.
+ * `fillBpSpan` is the same span when a `fillRect` is the only consumer.
+ *
+ * Not for a per-instance paint loop: this allocates a result per call, so the
+ * span mark's painter and wiggle's two bar loops take `spanLeft` and the two
+ * numbers inline, and stay the last hand-written copies of this arithmetic.
+ */
+export function spanRect(toX, startBp, endBp, minWidth = 0) {
+    const x1 = toX(startBp);
+    const x2 = toX(endBp);
+    const width = Math.max(minWidth, Math.abs(x2 - x1));
+    return { left: spanLeft(x1, x2, width), width };
+}
 // Quantize a 0..1 ramp position to a 256-entry index. Shared so the direct
 // lookup and the fillStyle LUT below can't quantize differently — a half-step
 // of drift between them shows up as a one-shade mismatch between a cell's fill

package/esm/colorRampLut.d.ts

@@ -9,9 +9,9 @@ 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.
+ * `shaders/colorRampLut.slang`. Called by `createMarkBackend` alone now, for
+ * every mark declaring a `texture`: hic, LD's two shader variants and wiggle
+ * density all put their ramps behind their samplers through it, each keeping
+ * its own scale and its own LUT contents.
  */
 export declare function uploadColorRampLut(hal: GpuHal, ramp: Uint8Array, passIds: readonly string[]): void;

package/esm/colorRampLut.js

@@ -9,10 +9,10 @@ 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.
+ * `shaders/colorRampLut.slang`. Called by `createMarkBackend` alone now, for
+ * every mark declaring a `texture`: hic, LD's two shader variants and wiggle
+ * density all put their ramps behind their samplers through it, each keeping
+ * its own scale and its own LUT contents.
  */
 export function uploadColorRampLut(hal, ramp, passIds) {
     if (ramp.length !== COLOR_RAMP_LUT_ENTRIES * 4) {

package/esm/computePipeline.d.ts

@@ -0,0 +1,13 @@
+import type { ShaderBinding } from './hal/index.ts';
+export interface ComputePipelineState {
+    device: GPUDevice;
+    pipeline: GPUComputePipeline;
+    bindGroupLayout: GPUBindGroupLayout;
+    bindings: readonly ShaderBinding[];
+}
+/**
+ * One compute pipeline per kernel, built on first use against the current
+ * device and rebuilt after a device loss. Concurrent first callers share the
+ * one async build.
+ */
+export declare function makeComputePipelineCache(code: string, entryPoint: string, bindings: readonly ShaderBinding[]): (device: GPUDevice) => Promise<ComputePipelineState>;

package/esm/computePipeline.js

@@ -0,0 +1,55 @@
+/// <reference types="@webgpu/types" />
+import { onDeviceLost } from './gpuDevice.js';
+// Built from the kernel's own reflected binding table rather than restated by
+// the caller, so a mismatch shows up as a validation failure at pipeline
+// creation rather than as a wrong buffer under a right-looking index.
+function makeBindGroupLayout(device, bindings) {
+    return device.createBindGroupLayout({
+        entries: bindings.map(b => {
+            if (b.kind === 'texture' || b.kind === 'sampler') {
+                throw new Error(`compute kernel: binding ${b.index} ('${b.name}') is a ${b.kind}, ` +
+                    `which a buffer-only dispatch does not bind`);
+            }
+            return {
+                binding: b.index,
+                visibility: GPUShaderStage.COMPUTE,
+                buffer: { type: b.kind },
+            };
+        }),
+    });
+}
+/**
+ * One compute pipeline per kernel, built on first use against the current
+ * device and rebuilt after a device loss. Concurrent first callers share the
+ * one async build.
+ */
+export function makeComputePipelineCache(code, entryPoint, bindings) {
+    let state = null;
+    let statePromise = null;
+    onDeviceLost(() => {
+        state = null;
+        statePromise = null;
+    });
+    return async function ensurePipeline(device) {
+        if (state?.device === device) {
+            return state;
+        }
+        if (statePromise) {
+            return statePromise;
+        }
+        statePromise = (async () => {
+            const module = device.createShaderModule({ code });
+            const bindGroupLayout = makeBindGroupLayout(device, bindings);
+            const pipeline = await device.createComputePipelineAsync({
+                layout: device.createPipelineLayout({
+                    bindGroupLayouts: [bindGroupLayout],
+                }),
+                compute: { module, entryPoint },
+            });
+            state = { device, pipeline, bindGroupLayout, bindings };
+            statePromise = null;
+            return state;
+        })();
+        return statePromise;
+    };
+}

package/esm/contractReports.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A contract family — the `<family>` in the `[jbrowse <family> contract]`
+ * prefix every contract check in the tree reports under.
+ * `config/jest/console.js` matches `\w+`, so a new one reaches the test gate
+ * without touching it.
+ */
+export type ContractFamily = 'display' | 'session' | 'figure';
+export interface ContractReport {
+    family: ContractFamily;
+    message: string;
+    /** what armed the channel, so a host can say why it is showing this */
+    armedBy: string;
+}
+/**
+ * Whether the checks should run at all.
+ *
+ * Read it where a check costs something to run — the `MutationObserver` a live
+ * figure installs, the per-frame payload walk in `installUpload`. A check whose
+ * cost is a `WeakSet` lookup should run unconditionally and report through
+ * {@link reportContractViolation} instead, so that arming the channel late
+ * still surfaces what it found.
+ */
+export declare function contractReportsOn(): boolean;
+/**
+ * Turn the channel on in a production build, saying what turned it on.
+ *
+ * The reason is not decoration: a notification that appears in an app the
+ * reader did not build has to answer "why am I seeing this" in its own text, or
+ * it reads as the app being broken rather than as a plugin being under
+ * development. First caller wins, so the earliest evidence is the one quoted.
+ */
+export declare function enableContractReports(reason: string): void;
+/**
+ * Where a host puts contract violations that reach a user — a session
+ * notification in the apps. Installing one drains whatever was found before the
+ * host existed, and the disposer only clears the sink it installed, so a
+ * session torn down after its replacement was built does not take the live
+ * one's sink with it.
+ */
+export declare function setContractReportSink(fn: (report: ContractReport) => void): () => void;
+/**
+ * Report a violation of an ordering contract no type can state.
+ *
+ * In tree this is the `console.error` it has always been, and the jest gate is
+ * what listens. Out of tree it is the only thing that reaches a plugin author
+ * at all: their display runs in a production build of somebody's app, which
+ * strips nothing here, and a violation surfaces the moment anything arms the
+ * channel — a `localStorage` flag, a plugin loaded from localhost, or a site
+ * whose config asks for it.
+ *
+ * `agent-docs/reference/ARCHITECTURAL_LIMITS.md` §"Ordering is the contract" is
+ * the register of what reports here.
+ */
+export declare function reportContractViolation(family: ContractFamily, message: string): void;

package/esm/contractReports.js

@@ -0,0 +1,112 @@
+const DEVELOPER_MODE_KEY = 'jbrowseDeveloperMode';
+// The flag a plugin author can set on any deployed JBrowse without owning it or
+// asking anyone, which is the population this whole channel is for.
+function storageFlag() {
+    try {
+        return typeof localStorage === 'undefined' ||
+            localStorage.getItem(DEVELOPER_MODE_KEY) === null
+            ? undefined
+            : `localStorage.${DEVELOPER_MODE_KEY} is set`;
+    }
+    catch {
+        // storage can be denied outright, and a diagnostic is not the thing to take
+        // the app down with
+        return undefined;
+    }
+}
+// Module scope for the same reason `numberGrouping` is: a check is called from
+// a mixin factory, an MST action and a React effect that cannot share a
+// closure, and each realm resolves this once at startup rather than through an
+// observable a worker could not see.
+let armedBy = process.env.NODE_ENV === 'production'
+    ? storageFlag()
+    : 'this is a development build';
+let sink;
+const unlogged = [];
+const undelivered = [];
+const PENDING_LIMIT = 20;
+function remember(queue, found) {
+    if (queue.length < PENDING_LIMIT) {
+        queue.push(found);
+    }
+}
+/**
+ * Whether the checks should run at all.
+ *
+ * Read it where a check costs something to run — the `MutationObserver` a live
+ * figure installs, the per-frame payload walk in `installUpload`. A check whose
+ * cost is a `WeakSet` lookup should run unconditionally and report through
+ * {@link reportContractViolation} instead, so that arming the channel late
+ * still surfaces what it found.
+ */
+export function contractReportsOn() {
+    return armedBy !== undefined;
+}
+/**
+ * Turn the channel on in a production build, saying what turned it on.
+ *
+ * The reason is not decoration: a notification that appears in an app the
+ * reader did not build has to answer "why am I seeing this" in its own text, or
+ * it reads as the app being broken rather than as a plugin being under
+ * development. First caller wins, so the earliest evidence is the one quoted.
+ */
+export function enableContractReports(reason) {
+    armedBy ??= reason;
+    for (const found of unlogged.splice(0)) {
+        emit(found, armedBy);
+    }
+}
+/**
+ * Where a host puts contract violations that reach a user — a session
+ * notification in the apps. Installing one drains whatever was found before the
+ * host existed, and the disposer only clears the sink it installed, so a
+ * session torn down after its replacement was built does not take the live
+ * one's sink with it.
+ */
+export function setContractReportSink(fn) {
+    sink = fn;
+    if (armedBy !== undefined) {
+        for (const found of undelivered.splice(0)) {
+            fn({ ...found, armedBy });
+        }
+    }
+    return () => {
+        if (sink === fn) {
+            sink = undefined;
+        }
+    };
+}
+function emit(found, armed) {
+    // `console.error`, never a throw: an error escaping `afterAttach` is read by
+    // the session loader as an invalid track and the display is silently dropped,
+    // which would hide the very violation being reported. The prefix is what
+    // `config/jest/console.js` buffers and `contractGate.js` fails a test on.
+    console.error(`[jbrowse ${found.family} contract] ${found.message}`);
+    if (sink === undefined) {
+        remember(undelivered, found);
+    }
+    else {
+        sink({ ...found, armedBy: armed });
+    }
+}
+/**
+ * Report a violation of an ordering contract no type can state.
+ *
+ * In tree this is the `console.error` it has always been, and the jest gate is
+ * what listens. Out of tree it is the only thing that reaches a plugin author
+ * at all: their display runs in a production build of somebody's app, which
+ * strips nothing here, and a violation surfaces the moment anything arms the
+ * channel — a `localStorage` flag, a plugin loaded from localhost, or a site
+ * whose config asks for it.
+ *
+ * `agent-docs/reference/ARCHITECTURAL_LIMITS.md` §"Ordering is the contract" is
+ * the register of what reports here.
+ */
+export function reportContractViolation(family, message) {
+    if (armedBy === undefined) {
+        remember(unlogged, { family, message });
+    }
+    else {
+        emit({ family, message }, armedBy);
+    }
+}

package/esm/coverageBand.d.ts

@@ -1,6 +1,5 @@
 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;
 /**

package/esm/coverageBand.js

@@ -4,7 +4,6 @@ import * as coverageInterbaseShader from './shaders/coverageInterbase.generated.
 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

package/esm/coverageBandBuffers.d.ts

@@ -22,9 +22,3 @@ export interface CoverageBandBuffers {
     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

@@ -1,13 +1 @@
-/**
- * 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,
-    };
-}
+export {};

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/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

@@ -83,6 +83,15 @@ export interface DisplayLoadingInputs {
      * click.
      */
     isLoadingOrCanceled: boolean;
+    /**
+     * A load this display depends on beyond its primary fetch has not landed for
+     * the first time, so the frame the primary fetch calls current is still
+     * missing something (multi-way synteny's lane genes and links). A loading
+     * term rather than a `dataSuperseded` fold: that flag holds the export
+     * through every later refetch too, and a scrim over lanes that are already
+     * drawn is the thing a display saying this wants to avoid.
+     */
+    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
@@ -142,7 +151,7 @@ export interface DisplayLoadingInputs {
  * 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;
+export declare function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, awaitingDependentData, 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

package/esm/displayPhase.js

@@ -70,10 +70,11 @@ export function computeDisplayPhase({ renderError, regionTooLarge, error }, load
  * IntersectionObserver's first callback, which is exactly when a display must
  * not flash `ready`. Only the paint it will never do is excused.
  */
-export function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
+export function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
     return (!fetchInert &&
         !viewportEmpty &&
         (isLoadingOrCanceled ||
+            awaitingDependentData ||
             (rendersCanvas && hostMounted() && !canvasDrawn) ||
             !viewportCurrent()));
 }

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>;