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

package/esm/encodeMemo.js

@@ -0,0 +1,48 @@
+import { computed } from 'mobx';
+/**
+ * A per-key encode memo over a display's cell map: `encode` runs for a key
+ * when its data reference moves, every key re-encodes when `inputs` yields a
+ * new identity, and a departed key is dropped. `inputs` runs through a
+ * `computed`, so a getter that allocates a fresh object per read re-encodes
+ * only when what it read changed.
+ *
+ * The returned map is a new instance whenever an entry moved and the same one
+ * otherwise, so an MST view holding it invalidates its observers exactly when
+ * a cell did. `installUpload` runs its `encode` path on this; a display that
+ * needs the encoded map itself — for a hit test, an SVG export — holds one in
+ * a `.views` closure and hands the installer identity cells.
+ */
+export function createEncodeMemo(cells, inputs, encode) {
+    const encoded = new Map();
+    const encodedFrom = new Map();
+    const props = inputs && computed(inputs);
+    let lastProps;
+    let snapshot = encoded;
+    return () => {
+        const current = cells();
+        const p = props ? props.get() : undefined;
+        if (p !== lastProps) {
+            lastProps = p;
+            encodedFrom.clear();
+        }
+        let changed = false;
+        for (const [key, data] of current) {
+            if (encodedFrom.get(key) !== data) {
+                encoded.set(key, encode(data, p, key));
+                encodedFrom.set(key, data);
+                changed = true;
+            }
+        }
+        for (const key of encoded.keys()) {
+            if (!current.has(key)) {
+                encoded.delete(key);
+                encodedFrom.delete(key);
+                changed = true;
+            }
+        }
+        if (changed) {
+            snapshot = new Map(encoded);
+        }
+        return snapshot;
+    };
+}

package/esm/gpuDevice.d.ts

@@ -1,3 +1,4 @@
+import type { RendererName } from './graphicsCapabilities.ts';
 interface GpuDeviceCell {
     device: GPUDevice | null;
     /** Serializes concurrent calls during async init and after recovery. */
@@ -30,6 +31,12 @@ interface GpuDeviceCell {
      * @see setGpuOverride
      */
     gpuOverride: string | null;
+    /**
+     * The rung the last `createGpuHal` returned, so `effectiveRenderer` reports
+     * what drew rather than what the probe predicted. Optional because a cell an
+     * older copy built has none, and "nothing built yet" is a real state there.
+     */
+    builtRenderer?: RendererName;
 }
 declare global {
     var __jbrowseRenderCoreGpuDeviceV1: GpuDeviceCell | undefined;
@@ -61,6 +68,8 @@ export type GpuOverride = (typeof GPU_OVERRIDES)[number];
  */
 export declare function setGpuOverride(value: string | null): void;
 export declare function getGpuOverride(): string | null;
+export declare function setBuiltRenderer(name: RendererName): void;
+export declare function getBuiltRenderer(): RendererName | undefined;
 /**
  * Whether the GPU is off for the whole page — either pinned by `?renderer=` at
  * startup or switched off from a display's GPU-error banner after an

package/esm/gpuDevice.js

@@ -24,9 +24,11 @@
  * field added later would read `undefined` on a cell built by an older copy.
  * Changing this interface therefore means bumping the `V1` in the global's
  * name, which costs the sharing between the two versions — the point of the
- * suffix is that losing it is a decision rather than a silent misread. Reset in
- * place (see `resetGpuDeviceForTests`); never reassign the cell itself, or
- * copies holding the old object diverge from the new one.
+ * suffix is that losing it is a decision rather than a silent misread. The one
+ * exception is an optional field whose `undefined` is an honest state, as
+ * `builtRenderer`'s is. Reset in place (see `resetGpuDeviceForTests`); never
+ * reassign the cell itself, or copies holding the old object diverge from the
+ * new one.
  */
 const cell = (globalThis.__jbrowseRenderCoreGpuDeviceV1 ??= {
     device: null,
@@ -216,6 +218,12 @@ export function setGpuOverride(value) {
 export function getGpuOverride() {
     return cell.gpuOverride;
 }
+export function setBuiltRenderer(name) {
+    cell.builtRenderer = name;
+}
+export function getBuiltRenderer() {
+    return cell.builtRenderer;
+}
 /**
  * Whether the GPU is off for the whole page — either pinned by `?renderer=` at
  * startup or switched off from a display's GPU-error banner after an
@@ -248,6 +256,7 @@ export function resetGpuDeviceForTests() {
     cell.devicePromise = null;
     cell.hadDevice = false;
     cell.deviceLostListeners.clear();
+    cell.builtRenderer = undefined;
 }
 export function getGpuDevice() {
     const override = getGpuOverride();

package/esm/graphicsCapabilities.d.ts

@@ -65,22 +65,25 @@ export declare function isSoftwareRenderer(glRenderer: string): boolean;
  */
 export declare function getGraphicsCapabilities(): Promise<GraphicsCapabilities>;
 /**
- * Which rung will actually draw — the ladder in `createGpuHal`, read as an
- * answer rather than run. This is the question every consumer asks (the About
- * widget's "Graphics:" line, the stack-trace dialog's environment block, the
- * analytics field), and answering it needs both halves: what the machine can do
- * *and* the page-wide pin from `?renderer=` or the GPU-error banner's "disable
- * GPU" button.
+ * Which rung draws. Once `createGpuHal` has built one on this page, the rung it
+ * returned is the answer — the adapter probe says WebGPU where
+ * `WebGPUHal.create` then throws and the ladder lands on WebGL2. Before any
+ * backend exists it is the ladder read as an answer rather than run, from what
+ * the machine can do *and* the page-wide pin from `?renderer=` or the
+ * GPU-error banner's "disable GPU" button. This is the question every consumer
+ * asks: the About widget's "Graphics:" line, the stack-trace dialog's
+ * environment block, the analytics field.
  *
- * The pin is checked first and wins outright, because **a pin never falls
- * through to the next rung** — `createGpuHal` throws instead, on the reasoning
- * that a pinned renderer which silently substitutes another makes any
- * comparison against it wrong. So the pinned rung *is* the answer, and a pin
- * that cannot be honored surfaces as a `renderError` rather than as a different
- * string here. That is what makes this exact rather than a guess: the one case
- * it cannot resolve from capabilities alone (`?renderer=webgl` on a WebGPU
- * machine, where the WebGL2 probe was skipped) is also the case where the pin
- * decides on its own.
+ * The Canvas2D pin is checked ahead of the record because the banner's
+ * "disable GPU" sets it before the displays rebuild on the new rung. The other
+ * pins win outright in the prediction, because **a pin never falls through to
+ * the next rung** — `createGpuHal` throws instead, on the reasoning that a
+ * pinned renderer which silently substitutes another makes any comparison
+ * against it wrong. So the pinned rung *is* the answer, and a pin that cannot
+ * be honored surfaces as a `renderError` rather than as a different string
+ * here. The one case the prediction cannot resolve from capabilities alone
+ * (`?renderer=webgl` on a WebGPU machine, where the WebGL2 probe was skipped)
+ * is also the case where the pin decides on its own.
  *
  * **`softwareWebgl` skips the WebGL2 rung here because it skips it there**, and
  * only where the ladder skips it — unpinned. Leaving it out is not a rounding

package/esm/graphicsCapabilities.js

@@ -1,4 +1,4 @@
-import { getGpuOverride, isGpuRenderingDisabled } from './gpuDevice.js';
+import { getBuiltRenderer, getGpuOverride, isGpuRenderingDisabled, } from './gpuDevice.js';
 // Substrings of UNMASKED_RENDERER_WEBGL that mean "no GPU is involved". Kept
 // conservative and specific — a wrong `true` here would describe a real GPU as
 // software, and the reports built from it are what a later ladder decision would
@@ -111,22 +111,25 @@ export function getGraphicsCapabilities() {
     return capabilities;
 }
 /**
- * Which rung will actually draw — the ladder in `createGpuHal`, read as an
- * answer rather than run. This is the question every consumer asks (the About
- * widget's "Graphics:" line, the stack-trace dialog's environment block, the
- * analytics field), and answering it needs both halves: what the machine can do
- * *and* the page-wide pin from `?renderer=` or the GPU-error banner's "disable
- * GPU" button.
+ * Which rung draws. Once `createGpuHal` has built one on this page, the rung it
+ * returned is the answer — the adapter probe says WebGPU where
+ * `WebGPUHal.create` then throws and the ladder lands on WebGL2. Before any
+ * backend exists it is the ladder read as an answer rather than run, from what
+ * the machine can do *and* the page-wide pin from `?renderer=` or the
+ * GPU-error banner's "disable GPU" button. This is the question every consumer
+ * asks: the About widget's "Graphics:" line, the stack-trace dialog's
+ * environment block, the analytics field.
  *
- * The pin is checked first and wins outright, because **a pin never falls
- * through to the next rung** — `createGpuHal` throws instead, on the reasoning
- * that a pinned renderer which silently substitutes another makes any
- * comparison against it wrong. So the pinned rung *is* the answer, and a pin
- * that cannot be honored surfaces as a `renderError` rather than as a different
- * string here. That is what makes this exact rather than a guess: the one case
- * it cannot resolve from capabilities alone (`?renderer=webgl` on a WebGPU
- * machine, where the WebGL2 probe was skipped) is also the case where the pin
- * decides on its own.
+ * The Canvas2D pin is checked ahead of the record because the banner's
+ * "disable GPU" sets it before the displays rebuild on the new rung. The other
+ * pins win outright in the prediction, because **a pin never falls through to
+ * the next rung** — `createGpuHal` throws instead, on the reasoning that a
+ * pinned renderer which silently substitutes another makes any comparison
+ * against it wrong. So the pinned rung *is* the answer, and a pin that cannot
+ * be honored surfaces as a `renderError` rather than as a different string
+ * here. The one case the prediction cannot resolve from capabilities alone
+ * (`?renderer=webgl` on a WebGPU machine, where the WebGL2 probe was skipped)
+ * is also the case where the pin decides on its own.
  *
  * **`softwareWebgl` skips the WebGL2 rung here because it skips it there**, and
  * only where the ladder skips it — unpinned. Leaving it out is not a rounding
@@ -145,6 +148,10 @@ export function effectiveRenderer(c) {
     if (isGpuRenderingDisabled()) {
         return 'Canvas2D';
     }
+    const built = getBuiltRenderer();
+    if (built) {
+        return built;
+    }
     const override = getGpuOverride();
     if (override === 'webgl') {
         return 'WebGL2';

package/esm/hal/createHal.d.ts

@@ -1,7 +1,6 @@
 import type { GpuHal, PipelineDescriptor, SampleCount } from './types.ts';
 export interface GpuHalOptions {
     passes: PipelineDescriptor[];
-    uniformByteSize: number;
     /**
      * Reaches the WebGPU rung only. The WebGL2 rung draws to the default
      * framebuffer with `antialias: true`, so its multisampling is the browser's
@@ -19,4 +18,4 @@ export interface GpuHalOptions {
      */
     failures?: unknown[];
 }
-export declare function createGpuHal(canvas: HTMLCanvasElement, { passes, uniformByteSize, sampleCount, failures }: GpuHalOptions): Promise<GpuHal | null>;
+export declare function createGpuHal(canvas: HTMLCanvasElement, options: GpuHalOptions): Promise<GpuHal | null>;

package/esm/hal/createHal.js

@@ -1,4 +1,4 @@
-import { getGpuOverride, isGpuRenderingDisabled } from '../gpuDevice.js';
+import { getGpuOverride, isGpuRenderingDisabled, setBuiltRenderer, } from '../gpuDevice.js';
 import { getGraphicsCapabilities } from '../graphicsCapabilities.js';
 import { WebGL2Hal } from './webgl2Hal.js';
 import { WebGPUHal } from './webgpuHal.js';
@@ -17,14 +17,24 @@ function warnSoftwareRasterizerOnce(glRenderer) {
 // Ladder: WebGPU → WebGL2 → Canvas2D (null). The `?renderer=` URL param pins it
 // to a single rung for debugging — `webgpu`, `webgl`, or `canvas2d`/`canvas` —
 // and a pin never falls through to the next rung. See GPU_OVERRIDES.
-export async function createGpuHal(canvas, { passes, uniformByteSize, sampleCount, failures }) {
+//
+// Records the rung it returned on the page-wide cell, which is how
+// `effectiveRenderer` gets to report what drew rather than what the adapter
+// probe predicted — the two part when `WebGPUHal.create` throws and the ladder
+// lands on WebGL2.
+export async function createGpuHal(canvas, options) {
+    const hal = await climbLadder(canvas, options);
+    setBuiltRenderer(hal === null ? 'Canvas2D' : hal instanceof WebGPUHal ? 'WebGPU' : 'WebGL2');
+    return hal;
+}
+async function climbLadder(canvas, { passes, sampleCount, failures }) {
     if (isGpuRenderingDisabled()) {
         return null;
     }
     const override = getGpuOverride();
     if (override !== 'webgl') {
         try {
-            const webgpu = await WebGPUHal.create(canvas, passes, uniformByteSize, sampleCount);
+            const webgpu = await WebGPUHal.create(canvas, passes, sampleCount);
             if (webgpu) {
                 return webgpu;
             }
@@ -81,7 +91,7 @@ export async function createGpuHal(canvas, { passes, uniformByteSize, sampleCoun
         }
     }
     try {
-        return new WebGL2Hal(canvas, passes, uniformByteSize);
+        return new WebGL2Hal(canvas, passes);
     }
     catch (e) {
         console.warn('[GPU] WebGL2 unavailable, falling back to Canvas2D:', e);

package/esm/hal/deviceGpuCache.js

@@ -21,8 +21,8 @@
  * is the one pipeline input the descriptor cannot express, so it is the inner
  * key; see the `pipelines` field.
  *
- * The one field of a pipeline that is not on the descriptor is the uniform
- * size, and it cannot make two HALs disagree here:
+ * The descriptor's `uniformByteSize` never reaches the pipeline, so it cannot
+ * make two HALs disagree here:
  * `createUniformOnlyBindGroupLayout` declares no `minBindingSize`, so the
  * layout — and thus the pipeline built against it — is the same whatever a
  * display's `uniformByteSize` is. The size reaches the GPU through the bind

package/esm/hal/gpuHalBase.d.ts

@@ -31,6 +31,7 @@ export declare abstract class GpuHalBase<Buf extends {
     protected descriptors: Map<string, PipelineDescriptor>;
     protected regions: RegionRegistry<Buf>;
     protected oom: OomReporter;
+    readonly uniformByteSize: number;
     protected disposed: boolean;
     constructor(descriptors: PipelineDescriptor[], halName: string);
     protected abstract limits(): HalLimits;
@@ -49,7 +50,6 @@ export declare abstract class GpuHalBase<Buf extends {
     getBufferCount(regionKey: number, passId: string): number;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    pruneRegions(active: Iterable<number>): void;
     uploadTexture(passId: string, data: Uint8Array, width: number, height: number): void;
     dispose(): void;
 }

package/esm/hal/gpuHalBase.js

@@ -19,11 +19,13 @@ export class GpuHalBase {
     descriptors;
     regions;
     oom;
+    uniformByteSize;
     // Guards dispose() against double invocation (pagehide + React cleanup can
     // both fire).
     disposed = false;
     constructor(descriptors, halName) {
         this.descriptors = new Map(descriptors.map(d => [d.id, d]));
+        this.uniformByteSize = Math.max(0, ...descriptors.map(d => d.uniformByteSize));
         this.oom = new OomReporter(halName);
         this.regions = new RegionRegistry(buf => {
             this.destroyBuffer(buf);
@@ -55,9 +57,6 @@ export class GpuHalBase {
     deleteRegion(regionKey) {
         this.regions.deleteRegion(regionKey);
     }
-    pruneRegions(active) {
-        this.regions.prune(active);
-    }
     uploadTexture(passId, data, width, height) {
         // Read the binding off the descriptor, so a pass with no texture is
         // answered without touching the backend's pipeline state at all.

package/esm/hal/mockHal.d.ts

@@ -102,7 +102,6 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
     uploadBuffer(regionKey: number, passId: string, data: ArrayBuffer | ArrayBufferView, count: number): void;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    pruneRegions(active: Iterable<number>): void;
     private noteReplaced;
     private noteRegionReplaced;
     writeUniforms(data: ArrayBuffer): void;

package/esm/hal/mockHal.js

@@ -119,16 +119,6 @@ export class MockHal extends GpuHalBase {
         this.noteRegionReplaced(regionKey);
         super.deleteRegion(regionKey);
     }
-    pruneRegions(active) {
-        const activeSet = new Set(active);
-        this.record('pruneRegions', [...activeSet]);
-        for (const regionKey of this.drawnThisFrame.keys()) {
-            if (!activeSet.has(regionKey)) {
-                this.noteRegionReplaced(regionKey);
-            }
-        }
-        super.pruneRegions(activeSet);
-    }
     noteReplaced(regionKey, passId) {
         if (this.frameOpen && this.drawnThisFrame.get(regionKey)?.has(passId)) {
             this.replacedWhileDrawnLog.push(`${regionKey}:${passId}`);

package/esm/hal/regionRegistry.d.ts

@@ -7,5 +7,4 @@ export declare class RegionRegistry<Buf> {
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
     deleteAll(): void;
-    prune(active: Iterable<number>): void;
 }

package/esm/hal/regionRegistry.js

@@ -1,9 +1,6 @@
-// Per-(region, pass) buffer registry shared by WebGL2Hal and WebGPUHal.
-// Owns the nested map and the destroy semantics so the two HALs only have to
-// supply a leaf-buffer type and its destroy hook. Both HALs used to ship
-// near-identical deleteBuffer/deleteRegion/deleteAll/prune/getOrCreate
-// implementations; centralizing avoids drift when one side's lifecycle is
-// tweaked and the other isn't. Contract pinned by regionRegistry.test.ts.
+// Per-(region, pass) buffer registry shared by WebGL2Hal and WebGPUHal: the
+// nested map plus destroy semantics, so each HAL supplies only its leaf-buffer
+// type and destroy hook.
 export class RegionRegistry {
     destroy;
     regions = new Map();
@@ -54,13 +51,4 @@ export class RegionRegistry {
         }
         this.regions.clear();
     }
-    // Delete every region whose key is NOT in `active`.
-    prune(active) {
-        const activeSet = new Set(active);
-        for (const regionKey of this.regions.keys()) {
-            if (!activeSet.has(regionKey)) {
-                this.deleteRegion(regionKey);
-            }
-        }
-    }
 }

package/esm/hal/types.d.ts

@@ -80,15 +80,20 @@ export interface PipelineDescriptor {
     glslVertex: string;
     glslFragment: string;
     instanceStride: number;
+    /** Bytes of the uniform block the shader binds; the HAL's slot is the largest over its passes. */
+    uniformByteSize: number;
     verticesPerInstance: number;
     blend: boolean;
     blendState?: BlendState;
     vertexAttributes: readonly VertexAttributeLayout[];
     topology?: 'triangle-list' | 'triangle-strip' | 'line-list';
+    coverage?: 'analytic';
     textures?: readonly [TextureBinding, ...TextureBinding[]];
     bindings?: readonly ShaderBinding[];
 }
 export interface GpuHal {
+    /** The uniform slot size, the largest block any registered pass binds. */
+    readonly uniformByteSize: number;
     /**
      * Size the canvas, and report the scale its backing store actually got.
      * Callers derive every device-px rect from THAT rather than from `getDpr()`:
@@ -101,7 +106,6 @@ export interface GpuHal {
     getBufferCount(regionKey: number, passId: string): number;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    pruneRegions(active: Iterable<number>): void;
     uploadTexture(passId: string, data: Uint8Array, width: number, height: number): void;
     writeUniforms(data: ArrayBuffer): void;
     beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;

package/esm/hal/webgl2Hal.d.ts

@@ -17,7 +17,7 @@ export declare class WebGL2Hal extends GpuHalBase<RegionPassBuffer> implements G
     private contextLostListener;
     private contextRestoredListener;
     private checkGlError;
-    constructor(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[], uniformByteSize: number);
+    constructor(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[]);
     protected limits(): {
         maxBufferBytes: number;
         maxTextureDimensionPx: number;

package/esm/hal/webgl2Hal.js

@@ -156,7 +156,7 @@ export class WebGL2Hal extends GpuHalBase {
             console.error(`[WebGL2Hal] GL error at "${label}": ${glErrorName(this.gl, err)}`);
         }
     }
-    constructor(canvas, descriptors, uniformByteSize) {
+    constructor(canvas, descriptors) {
         super(descriptors, 'WebGL2Hal');
         this.canvas = canvas;
         this.debug = debugEnabled();
@@ -202,7 +202,7 @@ export class WebGL2Hal extends GpuHalBase {
         this.maxTextureDim = Number(gl.getParameter(gl.MAX_TEXTURE_SIZE));
         this.ubo = gl.createBuffer();
         gl.bindBuffer(gl.UNIFORM_BUFFER, this.ubo);
-        gl.bufferData(gl.UNIFORM_BUFFER, uniformByteSize, gl.DYNAMIC_DRAW);
+        gl.bufferData(gl.UNIFORM_BUFFER, this.uniformByteSize, gl.DYNAMIC_DRAW);
         this.passes = new Map();
         // Programs are built on first use (see `getPass`), not here: a renderer
         // declares every pass it could ever draw — alignments alone declares 21,

package/esm/hal/webgpuHal.d.ts

@@ -66,7 +66,7 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
      * configured context behind with nothing to release it.
      */
     private configureContext;
-    static create(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[], uniformByteSize: number, sampleCount: SampleCount): Promise<WebGPUHal | null>;
+    static create(canvas: HTMLCanvasElement, descriptors: PipelineDescriptor[], sampleCount: SampleCount): Promise<WebGPUHal | null>;
     resize(width: number, height: number): import("./types.ts").CanvasScale;
     private recreateMsaaTexture;
     /**
@@ -92,7 +92,7 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
      * {@link pendingDestroy} for why the frame decides when.
      *
      * Every buffer release routes here through the `RegionRegistry` destroy hook,
-     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion`, `pruneRegions` and
+     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion` and
      * `dispose` are all covered without any of them knowing a frame is open.
      */
     private destroyWhenIdle;

package/esm/hal/webgpuHal.js

@@ -15,11 +15,13 @@ class ShaderCompileError extends Error {
 // aligned slot in the uniform ring buffer.
 //
 // The ring is allocated eagerly at this many slots, as a GPU buffer AND a CPU
-// staging array, whether a renderer writes 4 slots or 1900 — so the cost is
-// per display and is the aligned uniform size that decides it, not the slot
-// count. A display whose uniform fits the 256-byte minimum alignment pays
-// 512 KB each side; alignments' 864-byte uniform aligns to 1024, so 2 MiB each
-// side. Trivial once, per-track at ten open alignments tracks.
+// staging array, whether a renderer writes 4 slots or 1900 — so the cost is per
+// display, and both terms are in it. A display whose uniform fits the 256-byte
+// minimum alignment pays 512 KB each side; alignments' 640-byte uniform aligns
+// to 768, so 1.5 MiB each side, per track. A frame is measured using 2-4 of
+// those slots, which is what makes the count above the oversized term rather
+// than any struct:
+// agent-docs/ideas/size-the-uniform-ring-to-its-measured-occupancy.md.
 //
 // Exhausting it does not throw: the write is dropped and its draws render
 // against the previous batch's uniforms, which is wrong data rather than stale
@@ -196,7 +198,7 @@ export class WebGPUHal extends GpuHalBase {
     // than once per frame, and a reconfigure that failed is not attempted again.
     warnedSwapChainLoss = false;
     swapChainUnrecoverable = false;
-    constructor(device, canvas, context, descriptors, uniformByteSize, sampleCount, pipelines, layouts) {
+    constructor(device, canvas, context, descriptors, sampleCount, pipelines, layouts) {
         super(descriptors, 'WebGPUHal');
         this.device = device;
         this.canvas = canvas;
@@ -206,7 +208,8 @@ export class WebGPUHal extends GpuHalBase {
         this.sampleCount = sampleCount;
         // Align uniform slots to device requirements for dynamic offsets
         const alignment = device.limits.minUniformBufferOffsetAlignment;
-        this.alignedUniformSize = Math.ceil(uniformByteSize / alignment) * alignment;
+        this.alignedUniformSize =
+            Math.ceil(this.uniformByteSize / alignment) * alignment;
         const ringSize = MAX_UNIFORM_SLOTS * this.alignedUniformSize;
         this.uniformRingBuffer = device.createBuffer({
             size: ringSize,
@@ -245,7 +248,7 @@ export class WebGPUHal extends GpuHalBase {
         });
         noteCanvasConfigured(this.canvas, this);
     }
-    static async create(canvas, descriptors, uniformByteSize, sampleCount) {
+    static async create(canvas, descriptors, sampleCount) {
         const device = await getGpuDevice();
         if (!device) {
             return null;
@@ -266,7 +269,7 @@ export class WebGPUHal extends GpuHalBase {
             throw canvasContextError(canvas, 'webgpu');
         }
         noteCanvasContext(canvas, 'webgpu');
-        return new WebGPUHal(device, canvas, context, descriptors, uniformByteSize, sampleCount, pipelines, layouts);
+        return new WebGPUHal(device, canvas, context, descriptors, sampleCount, pipelines, layouts);
     }
     resize(width, height) {
         const { changed, scale } = syncCanvasSize(this.canvas, width, height);
@@ -352,7 +355,7 @@ export class WebGPUHal extends GpuHalBase {
      * {@link pendingDestroy} for why the frame decides when.
      *
      * Every buffer release routes here through the `RegionRegistry` destroy hook,
-     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion`, `pruneRegions` and
+     * so `uploadBuffer`, `deleteBuffer`, `deleteRegion` and
      * `dispose` are all covered without any of them knowing a frame is open.
      */
     destroyWhenIdle(resource) {

package/esm/installUpload.d.ts

@@ -74,7 +74,10 @@ export declare function oneCell<K, T>(key: K, value: T | undefined | null): Read
  *
  * **Calling again only swaps the backend.** Displays wire this from
  * `startRenderingBackend`, which fires again on every context-loss recovery;
- * the diff and the encode cache live in the setup thunk and survive it.
+ * the diff and the encode memo live in the setup thunk and survive it.
+ *
+ * `encode` runs through `createEncodeMemo`. A display that needs the encoded
+ * map itself holds that memo in a `.views` closure and hands identity cells.
  *
  * @see installUpload.test.ts for the upload, encode and release counts.
  * @see ADR-078 for why this is one autorun and a diff.

package/esm/installUpload.js

@@ -1,5 +1,6 @@
 import { getType } from '@jbrowse/mobx-state-tree';
-import { computed } from 'mobx';
+import { contractReportsOn, reportContractViolation, } from './contractReports.js';
+import { createEncodeMemo } from './encodeMemo.js';
 import { createMapUploadSync } from './mapUploadSync.js';
 import { isCheckedAtTheStore } from './regionDataMap.js';
 /**
@@ -29,7 +30,7 @@ function checkPayloads(self, cells) {
             }
             if (!named.has(key)) {
                 named.add(key);
-                console.error(`[jbrowse display contract] ${getType(self).name}: cell ${String(key)} ` +
+                reportContractViolation('display', `${getType(self).name}: cell ${String(key)} ` +
                     `handed to installUpload is \`${String(value)}\`. A fetch answers ` +
                     'a payload or nothing; leave the key out until it has one.');
             }
@@ -46,49 +47,17 @@ export function installUpload(self, backend, { cells, inputs, encode, render })
                 b.release(key);
             },
         });
-        if (!encode) {
-            const own = cells;
-            return {
-                upload: b => {
-                    const current = own();
-                    if (process.env.NODE_ENV !== 'production') {
-                        checkPayloads(self, current);
-                    }
-                    return sync(b, current);
-                },
-                render: b => render(b, own()),
-            };
-        }
-        const encoded = new Map();
-        const encodedFrom = new Map();
-        const props = inputs && computed(inputs);
-        let lastProps;
+        const own = encode
+            ? createEncodeMemo(cells, inputs, encode)
+            : cells;
         return {
             upload: b => {
-                const current = cells();
-                if (process.env.NODE_ENV !== 'production') {
-                    checkPayloads(self, current);
-                }
-                const p = props ? props.get() : undefined;
-                if (p !== lastProps) {
-                    lastProps = p;
-                    encodedFrom.clear();
-                }
-                for (const [key, data] of current) {
-                    if (encodedFrom.get(key) !== data) {
-                        encoded.set(key, encode(data, p, key));
-                        encodedFrom.set(key, data);
-                    }
-                }
-                for (const key of encoded.keys()) {
-                    if (!current.has(key)) {
-                        encoded.delete(key);
-                        encodedFrom.delete(key);
-                    }
+                if (contractReportsOn()) {
+                    checkPayloads(self, cells());
                 }
-                return sync(b, encoded);
+                return sync(b, own());
             },
-            render: b => render(b, encoded),
+            render: b => render(b, own()),
         };
     });
 }