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

package/esm/marks/types.d.ts

@@ -0,0 +1,261 @@
+import type { BlockClipResult } from '../blockClipUtils.ts';
+import type { ClipContext2D } from '../canvas2dUtils.ts';
+import type { GpuHal } from '../hal/index.ts';
+import type { InstancePass } from '../instancePass.ts';
+import type { RenderBlock } from '../renderBlock.ts';
+import type { FrameDimensions } from '../renderingBackendBase.ts';
+/**
+ * The 2D-context subset a shape's painter needs, which both a canvas and
+ * `@jbrowse/core`'s `SvgCanvas` satisfy: one painter is the fallback and the
+ * SVG export.
+ */
+export interface MarkContext2D extends ClipContext2D {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+    lineCap?: CanvasLineCap;
+    lineJoin?: CanvasLineJoin;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    translate(x: number, y: number): void;
+    scale(x: number, y: number): void;
+    rotate(angle: number): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number): void;
+    setLineDash(segments: number[]): void;
+    closePath(): void;
+    fill(): void;
+    stroke(): void;
+    drawImage?(image: CanvasImageSource, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+}
+/**
+ * A canvas a mark's pass samples in place of a colour ramp. Hand a fresh object
+ * per repaint: the backend uploads on identity.
+ */
+export interface MarkImage {
+    image: HTMLCanvasElement | OffscreenCanvas;
+    width: number;
+    height: number;
+}
+/**
+ * RGBA8 texels with their dimensions: a table a pass samples, such as a row
+ * table. Hand a fresh object per change: the backend uploads on identity.
+ */
+export interface MarkTexels {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+}
+/** What a mark's pass binds: a 256-entry RGBA ramp, a canvas, or texels. */
+export type MarkTexture = Uint8Array | MarkImage | MarkTexels;
+/**
+ * A pass's textures by the sampler that reads each: `colorRamp`, `rowTable`,
+ * a ring's `strip`. A sampler left out, or answered undefined, keeps what it
+ * holds.
+ */
+export type MarkTextures = Readonly<Record<string, MarkTexture | undefined>>;
+export type MarkFrame = FrameDimensions;
+export type MarkValueScaleType = 'linear' | 'log' | 'symlog';
+/**
+ * The colour scale a ramp channel's raw `colorValue`s resolve through each
+ * frame, with the 256-entry RGBA LUT the pass's sampler binds: straight, its
+ * middle stop at the middle, and `mid`, where a diverging ramp puts that stop,
+ * read through a uniform.
+ */
+export interface MarkRamp {
+    domain: [number, number];
+    scale: 'linear' | 'log';
+    lut: Uint8Array;
+    /** The value the ramp's middle stop sits at; the domain's middle when absent. */
+    mid?: number;
+}
+/**
+ * A threshold a value channel's raw `colorValue`s resolve through each frame:
+ * the ascending cut points, at most `MAX_COLOR_CUTS` of them, and one packed
+ * ABGR per interval between them, `cuts.length + 1` in all. The cuts and
+ * colours ride uniforms, so an edit moves them and uploads no instance bytes.
+ */
+export interface MarkThreshold {
+    cuts: readonly number[];
+    colors: Uint32Array;
+}
+/** The scale a quantitative colour channel resolves through: a ramp or a threshold. */
+export type MarkColorScale = MarkRamp | MarkThreshold;
+/** A horizontal strip of the canvas, in CSS px down from its top edge. */
+export interface MarkBand {
+    top: number;
+    height: number;
+}
+/** Where a shape's ink sits nearest a cursor, and how far that is. */
+export interface MarkHit {
+    index: number;
+    x: number;
+    y: number;
+    distSq: number;
+}
+/** An axis-aligned box of the canvas, in CSS px. */
+export interface InkRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    /**
+     * The ink as a stroked path, for a shape whose box is mostly empty space (a
+     * link's curve): a highlight strokes it, clipped to the box.
+     */
+    stroke?: InkStroke;
+}
+/**
+ * An SVG path `d` in canvas px, the width the shape strokes it at, and where
+ * the canvas origin sits in the frame the box is in, which `shiftInk` moves
+ * with the box.
+ */
+export interface InkStroke {
+    d: string;
+    widthPx: number;
+    originX: number;
+    originY: number;
+}
+/**
+ * A shape: one `.slang` pass, a uniform writer and a Canvas2D painter over the
+ * same channel arrays, and the geometry its hit test reads. `TParams` reaches
+ * the GPU as uniforms and the painter as arguments, so both backends draw the
+ * same values.
+ */
+export interface MarkShape<TChannels, TParams> {
+    readonly id: string;
+    readonly pass: InstancePass<TChannels>;
+    /**
+     * Draws over the whole canvas from every loaded region's payload, after the
+     * blocks and unclipped to any block's column, each region's instances placed
+     * through a canvas-wide block of its own: a link, whose curve crosses regions
+     * holding neither foot.
+     */
+    readonly spansView?: boolean;
+    writeUniforms(scratch: ArrayBuffer, clip: BlockClipResult, block: RenderBlock, frame: MarkFrame, params: TParams): void;
+    paintBlock(ctx: MarkContext2D, channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams): void;
+    /**
+     * Whether the block carries any ink under these params. Both backends and the
+     * hit test skip a block it declines.
+     */
+    paintsBlock?(block: RenderBlock, frame: MarkFrame, params: TParams): boolean;
+    /**
+     * Slots the GPU addresses per instance this frame, where the pass's
+     * registered count is a worst case over canvas widths. The canvas chevron
+     * pass shades a slot per chevron a line could put on screen, which is the
+     * canvas width over the chevron pitch — a tenth of its registered budget at a
+     * laptop width, and every surplus slot is a vertex invocation that runs the
+     * whole placement before culling itself.
+     */
+    verticesPerInstance?(frame: MarkFrame, params: TParams): number;
+    /**
+     * The textures the pass samples that the params the painter and the hit
+     * test read decide (`span`'s row table), so the two backends cannot be
+     * handed different tables. A display's own `textures` lens wins for a
+     * sampler it answers.
+     */
+    textures?(params: TParams): MarkTextures;
+    /**
+     * The rect `paintBlock` fills for instance `i`, undefined where it paints
+     * nothing. `defineMark` derives `hitNearest` from it where none is declared,
+     * and a highlight guide draws it. Painter-only overdraw, `span`'s seam, is
+     * not ink.
+     */
+    ink?(channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams, i: number): InkRect | undefined;
+    /**
+     * The nearest drawn ink to `(xPx, yPx)` among `candidates`, or undefined if
+     * nothing beats `maxDistSq`. Distance 0 is on the ink, edges included. Only a
+     * strictly nearer candidate replaces the best, so candidates handed back to
+     * front answer a tie with the mark on top.
+     */
+    hitNearest?(channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams, xPx: number, yPx: number, candidates: Iterable<number>, maxDistSq: number): MarkHit | undefined;
+    /**
+     * The values an instance can hold and still put ink within `radiusPx` of
+     * canvas y `yPx`, which a display's index over (bp, value) is searched with.
+     * A shape with no value axis leaves it off.
+     */
+    valueWindow?(yPx: number, radiusPx: number, frame: MarkFrame, params: TParams): [number, number];
+}
+/**
+ * The uniform writer and `params` lens whose struct is in the HAL's slot, so a
+ * later mark of the same block over both draws without writing it again. Hand
+ * every mark of a block one fresh object: a stale one draws against the
+ * previous block's clip.
+ */
+export interface StagedUniforms {
+    writer: unknown;
+    params: unknown;
+}
+/**
+ * Puts a texture behind one of a pass's samplers once per identity: a repeat
+ * of the bound one costs nothing, and undefined leaves what is bound or binds
+ * an inert table where nothing is, since a textured pass missing a texture
+ * draws nothing on either GPU HAL.
+ */
+export interface TextureBinder {
+    bind(passId: string, sampler: string, texture: MarkTexture | undefined): void;
+}
+/** What `hal.drawPass` takes for one mark of a frame plan. */
+export interface PlannedPass {
+    readonly id: string;
+    readonly bufferOf: string | undefined;
+}
+/**
+ * A shape bound to a display's region payload and render state, its generics
+ * erased so one list holds several shapes.
+ */
+export interface Mark<TRegion, TState extends MarkFrame> {
+    readonly pass: InstancePass<TRegion>;
+    /** The shape's {@link MarkShape.spansView}. */
+    readonly spansView?: boolean;
+    /** The pass whose uploaded instance buffer this mark draws from. */
+    readonly bufferOf?: string;
+    /** What the pass's samplers read this frame; undefined binds an inert table. */
+    readonly textures?: (state: TState, region: TRegion) => MarkTextures | undefined;
+    /**
+     * Whether the mark draws at all under `state`. `planMarks` asks once per
+     * frame and every other consumer per block, before any lens.
+     */
+    readonly enabled?: (state: TState) => boolean;
+    /** The pass a frame plan draws; undefined with a `band` or `paintsBlock`. */
+    readonly planned?: PlannedPass;
+    drawRegion(hal: GpuHal, scratch: ArrayBuffer, block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState, regionKey: number, staged?: StagedUniforms, textures?: TextureBinder): void;
+    paintBlock(ctx: MarkContext2D, region: TRegion, block: RenderBlock, state: TState): void;
+    hitNearest?(region: TRegion, block: RenderBlock, state: TState, xPx: number, yPx: number, candidates: Iterable<number>, maxDistSq: number): MarkHit | undefined;
+    /** The box instance `i` painted under the mark's gates, clipped to a band. */
+    ink?(region: TRegion, block: RenderBlock, state: TState, i: number): InkRect | undefined;
+    /** The shape's `valueWindow` under the mark's gates, if they open. */
+    valueWindow?(region: TRegion, block: RenderBlock, state: TState, yPx: number, radiusPx: number): [number, number] | undefined;
+}
+/**
+ * The shape under another pass id. A pass id keys the instance buffer and
+ * texture, so two marks of one shape in one display need two ids; pipelines
+ * are keyed by content, so the clone compiles nothing.
+ */
+export declare function withPassId<C, P>(shape: MarkShape<C, P>, id: string): MarkShape<C, P>;
+/**
+ * Binds a shape to a display's payload and render state through two picks run
+ * once per block per frame: `channels` names the region's arrays for the
+ * shape's lanes, and answers undefined for a region the mark has nothing in,
+ * which then packs, draws and paints nothing; `params` names what reaches the
+ * uniforms.
+ *
+ * `bufferOf` draws off another mark's uploaded buffer of the same instance
+ * struct. `textures` binds per pass per frame, each sampler re-uploading when
+ * its texture's identity moves, so ramps that differ by region re-upload per
+ * region. `band` clips the
+ * mark to a strip without offsetting it. `enabled` turns the mark off for a
+ * whole frame, for every consumer.
+ */
+export declare function defineMark<TRegion, TState extends MarkFrame, TChannels, TParams>(spec: {
+    shape: MarkShape<TChannels, TParams>;
+    channels: (region: TRegion) => TChannels | undefined;
+    params: (state: TState, region: TRegion, block: RenderBlock) => TParams;
+    bufferOf?: Mark<TRegion, TState>;
+    band?: (state: TState) => MarkBand;
+    textures?: (state: TState, region: TRegion) => MarkTextures | undefined;
+    enabled?: (state: TState) => boolean;
+}): Mark<TRegion, TState>;

package/esm/marks/types.js

@@ -0,0 +1,175 @@
+import { devicePxBand, withClip } from '../canvas2dUtils.js';
+import { shapeHitNearest } from './markHit.js';
+/**
+ * The shape under another pass id. A pass id keys the instance buffer and
+ * texture, so two marks of one shape in one display need two ids; pipelines
+ * are keyed by content, so the clone compiles nothing.
+ */
+export function withPassId(shape, id) {
+    return { ...shape, id, pass: { ...shape.pass, id } };
+}
+/**
+ * Binds a shape to a display's payload and render state through two picks run
+ * once per block per frame: `channels` names the region's arrays for the
+ * shape's lanes, and answers undefined for a region the mark has nothing in,
+ * which then packs, draws and paints nothing; `params` names what reaches the
+ * uniforms.
+ *
+ * `bufferOf` draws off another mark's uploaded buffer of the same instance
+ * struct. `textures` binds per pass per frame, each sampler re-uploading when
+ * its texture's identity moves, so ramps that differ by region re-upload per
+ * region. `band` clips the
+ * mark to a strip without offsetting it. `enabled` turns the mark off for a
+ * whole frame, for every consumer.
+ */
+export function defineMark(spec) {
+    const { shape, channels, params, band, textures: ownTextures, enabled } = spec;
+    const hitNearest = shapeHitNearest(shape);
+    const shapeInk = shape.ink?.bind(shape);
+    const shapeValueWindow = shape.valueWindow?.bind(shape);
+    const shapeTextures = shape.textures?.bind(shape);
+    const samplers = shape.pass.textures?.map(t => t.name) ?? [];
+    const lender = spec.bufferOf?.pass;
+    if (lender &&
+        (lender.instanceStride !== shape.pass.instanceStride ||
+            JSON.stringify(lender.vertexAttributes) !==
+                JSON.stringify(shape.pass.vertexAttributes))) {
+        throw new Error(`mark ${shape.id} draws off ${lender.id}'s buffer but declares a different instance struct`);
+    }
+    const bufferOf = lender?.id;
+    const planned = band || shape.paintsBlock ? undefined : { id: shape.pass.id, bufferOf };
+    // `channels` gates `params`: a union payload's params lens may only read its
+    // own kind of region.
+    function resolve(region, block, state) {
+        if (enabled && !enabled(state)) {
+            return undefined;
+        }
+        const strip = band?.(state);
+        if (strip && !bandIsOpen(strip)) {
+            return undefined;
+        }
+        const c = channels(region);
+        if (c === undefined) {
+            return undefined;
+        }
+        const p = params(state, region, block);
+        if (shape.paintsBlock && !shape.paintsBlock(block, state, p)) {
+            return undefined;
+        }
+        return { channels: c, params: p, strip };
+    }
+    return {
+        pass: {
+            ...shape.pass,
+            pack: region => {
+                const c = channels(region);
+                return c === undefined ? NOTHING : shape.pass.pack(c);
+            },
+        },
+        bufferOf,
+        spansView: shape.spansView,
+        textures: ownTextures,
+        enabled,
+        planned,
+        // `resolve`'s gates inline: its picks leaving as a record or through
+        // closure state measured 0.80-0.86x of these locals on
+        // markUniformDedupe.bench.ts.
+        drawRegion(hal, scratch, block, clip, region, state, regionKey, staged, textures) {
+            if (enabled && !enabled(state)) {
+                return;
+            }
+            const strip = band?.(state);
+            if (strip && !bandIsOpen(strip)) {
+                return;
+            }
+            if (channels(region) === undefined) {
+                return;
+            }
+            const p = params(state, region, block);
+            if (shape.paintsBlock && !shape.paintsBlock(block, state, p)) {
+                return;
+            }
+            if (textures && samplers.length > 0) {
+                const own = ownTextures?.(state, region);
+                const fromParams = shapeTextures?.(p);
+                for (const sampler of samplers) {
+                    textures.bind(shape.pass.id, sampler, own?.[sampler] ?? fromParams?.[sampler]);
+                }
+            }
+            const scissor = strip && devicePxBand(strip.top, strip.height, clip.scaleY, clip.pxH);
+            if (scissor?.height === 0) {
+                return;
+            }
+            if (scissor) {
+                hal.setScissor(clip.pxX, scissor.top, clip.pxW, scissor.height);
+            }
+            if (staged?.writer !== shape.writeUniforms || staged.params !== params) {
+                shape.writeUniforms(scratch, clip, block, state, p);
+                hal.writeUniforms(scratch);
+                if (staged) {
+                    staged.writer = shape.writeUniforms;
+                    staged.params = params;
+                }
+            }
+            hal.drawPass(shape.pass.id, regionKey, bufferOf, shape.verticesPerInstance?.(state, p));
+            if (scissor) {
+                hal.setScissor(clip.pxX, 0, clip.pxW, clip.pxH);
+            }
+        },
+        paintBlock(ctx, region, block, state) {
+            const open = resolve(region, block, state);
+            if (!open) {
+                return;
+            }
+            const { strip } = open;
+            if (strip) {
+                withClip(ctx, 0, strip.top, state.canvasWidth, strip.height, () => {
+                    shape.paintBlock(ctx, open.channels, block, state, open.params);
+                });
+            }
+            else {
+                shape.paintBlock(ctx, open.channels, block, state, open.params);
+            }
+        },
+        hitNearest: hitNearest
+            ? (region, block, state, xPx, yPx, candidates, maxDistSq) => {
+                const open = resolve(region, block, state);
+                if (!open || bandExcludes(open.strip, yPx)) {
+                    return undefined;
+                }
+                const hit = hitNearest(open.channels, block, state, open.params, xPx, yPx, candidates, maxDistSq);
+                // Rejecting a nearest hit the band clipped away, rather than asking
+                // again, can mask a farther candidate inside the strip.
+                return hit && !bandExcludes(open.strip, hit.y) ? hit : undefined;
+            }
+            : undefined,
+        ink: shapeInk
+            ? (region, block, state, i) => {
+                const open = resolve(region, block, state);
+                if (!open) {
+                    return undefined;
+                }
+                const r = shapeInk(open.channels, block, state, open.params, i);
+                return r && open.strip ? clipToBand(r, open.strip) : r;
+            }
+            : undefined,
+        valueWindow: shapeValueWindow
+            ? (region, block, state, yPx, radiusPx) => {
+                const open = resolve(region, block, state);
+                return open && shapeValueWindow(yPx, radiusPx, state, open.params);
+            }
+            : undefined,
+    };
+}
+function bandIsOpen(strip) {
+    return strip.height > 0 && Number.isFinite(strip.top + strip.height);
+}
+function clipToBand(r, strip) {
+    const top = Math.max(r.top, strip.top);
+    const bottom = Math.min(r.top + r.height, strip.top + strip.height);
+    return bottom > top ? { ...r, top, height: bottom - top } : undefined;
+}
+const NOTHING = new ArrayBuffer(0);
+function bandExcludes(strip, yPx) {
+    return (strip !== undefined && (yPx < strip.top || yPx > strip.top + strip.height));
+}

package/esm/marks/valueScale.d.ts

@@ -0,0 +1,23 @@
+import type { MarkValueScaleType } from './types.ts';
+/** The y scale a valued shape places its instances through. */
+export interface MarkValueScale {
+    /** `[min, max]` the values are read through. */
+    domain: [number, number];
+    /** How that domain is read; linear when absent. */
+    scaleType?: MarkValueScaleType;
+    /**
+     * symlog's linear-region width, already resolved from `domain` the way the
+     * axis resolves it (`resolveSymlogConstant`); d3's 1 when absent.
+     */
+    symlogConstant?: number;
+    /** Whether the domain's minimum sits at the band's top rather than its bottom. */
+    reverse?: boolean;
+}
+/**
+ * The two uniforms `valueScale.slang` reads a scale by, which the painter, the
+ * ink box and the hit test read too.
+ */
+export declare function valueScaleUniforms({ scaleType, symlogConstant, }: MarkValueScale): {
+    valueScaleType: import("../scoreScale.ts").ScaleTypeCode;
+    valueSymlogConstant: number;
+};

package/esm/marks/valueScale.js

@@ -0,0 +1,11 @@
+import { scaleTypeCode } from '../scoreScale.js';
+/**
+ * The two uniforms `valueScale.slang` reads a scale by, which the painter, the
+ * ink box and the hit test read too.
+ */
+export function valueScaleUniforms({ scaleType, symlogConstant = 1, }) {
+    return {
+        valueScaleType: scaleTypeCode(scaleType),
+        valueSymlogConstant: symlogConstant,
+    };
+}

package/esm/namedReactions.d.ts

@@ -12,10 +12,9 @@ export declare function recordNamedReaction(self: object, name: string, disposer
  *
  * The two halves belong together: `reactionDependencies` can only see a
  * reaction that was recorded, so an installer that calls `autorun` and
- * `addDisposer` directly silently opts its dependency set out of the tests that
- * are supposed to pin it — and nothing fails, which is the same shape of
- * quiet-hole the mechanism exists to close. Every installer goes through here
- * so there is no second spelling to forget.
+ * `addDisposer` directly leaves its dependency set out of the tests that are
+ * supposed to pin it, and those tests still pass. Every installer goes through
+ * here so there is no second spelling to forget.
  */
 export declare function namedAutorun(self: IAnyStateTreeNode, body: () => void, options: IAutorunOptions & {
     name: string;

package/esm/namedReactions.js

@@ -23,10 +23,9 @@ export function recordNamedReaction(self, name, disposer) {
  *
  * The two halves belong together: `reactionDependencies` can only see a
  * reaction that was recorded, so an installer that calls `autorun` and
- * `addDisposer` directly silently opts its dependency set out of the tests that
- * are supposed to pin it — and nothing fails, which is the same shape of
- * quiet-hole the mechanism exists to close. Every installer goes through here
- * so there is no second spelling to forget.
+ * `addDisposer` directly leaves its dependency set out of the tests that are
+ * supposed to pin it, and those tests still pass. Every installer goes through
+ * here so there is no second spelling to forget.
  */
 export function namedAutorun(self, body, options) {
     const disposer = autorun(body, options);

package/esm/perRegionRenderingBackend.d.ts

@@ -1,9 +1,12 @@
 import { Canvas2DRenderingBackendBase, GpuRenderingBackendBase } from './renderingBackendBase.ts';
 import type { BlockClipResult } from './blockClipUtils.ts';
+import type { CanvasScale } from './canvas2dUtils.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';
+/** Straight RGBA, each channel 0-1 — what `beginFrame` takes. */
+export type ClearColor = readonly [number, number, number, number];
 /**
  * Shared contract for per-region streamed GPU backends.
  *
@@ -12,9 +15,8 @@ export type { FrameDimensions } from './renderingBackendBase.ts';
  * 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).
+ * `RenderData` is what the render-side reads. They default to the same type,
+ * and every per-region display keeps the default today.
  *
  * Renderers are stateless: they keep no per-region cache. Canvas2D backends
  * stub `upload` / `release` as no-ops since they read everything from the
@@ -58,6 +60,15 @@ export declare abstract class Canvas2DPerRegionRenderingBackend<UploadData, Rend
     upload(): void;
     release(): void;
     renderBlocks(blocks: Block[], regions: ReadonlyMap<number, RenderData>, state: RenderState): boolean;
+    /**
+     * What the frame is painted onto before the blocks are drawn — the Canvas2D
+     * half of the GPU base's `beginFrame` clear. Undefined, the default, leaves
+     * `prepareCanvas`'s `clearRect` as the whole of it, which is transparent.
+     * Synteny is the one display that overrides: its indel wedges pre-blend
+     * against a KNOWN ground and only agree with the base ribbon beside them over
+     * a destination that really is that colour.
+     */
+    protected clearColor(_state: RenderState): ClearColor | undefined;
     /**
      * Paint the visible blocks into `this.ctx` (already DPR-prepared). Delegates
      * to the plugin's pure `drawXxxBlocks(ctx, regions, blocks, state)` function.
@@ -103,6 +114,11 @@ export declare abstract class GpuPerRegionRenderingBackend<UploadData, RenderSta
      */
     upload(displayedRegionIndex: number, data: UploadData): void;
     renderBlocks(blocks: Block[], regions: ReadonlyMap<number, RenderData>, state: RenderState): boolean;
+    /**
+     * Draw what spans the whole canvas after the blocks, with the scissor and
+     * viewport cleared, and answer whether anything drew.
+     */
+    protected drawOverBlocks(_regions: ReadonlyMap<number, RenderData>, _state: RenderState, _scale: CanvasScale): 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
@@ -111,4 +127,6 @@ export declare abstract class GpuPerRegionRenderingBackend<UploadData, RenderSta
      * those whose draw state is fully in the uploaded buffer).
      */
     protected abstract drawRegion(block: Block, clip: BlockClipResult, region: RenderData, state: RenderState): void;
+    /** @see Canvas2DPerRegionRenderingBackend.clearColor */
+    protected clearColor(_state: RenderState): ClearColor;
 }

package/esm/perRegionRenderingBackend.js

@@ -2,6 +2,7 @@ import { clipBlock } from './blockClipUtils.js';
 import { prepareCanvas } from './canvas2dUtils.js';
 import { uploadPass } from './instancePass.js';
 import { Canvas2DRenderingBackendBase, GpuRenderingBackendBase, } from './renderingBackendBase.js';
+const TRANSPARENT = [0, 0, 0, 0];
 /**
  * Canvas2D-side base for `PerRegionRenderingBackend` implementations. Inherits
  * the `canvas` + 2D context (and no-op `dispose`) from
@@ -21,9 +22,26 @@ export class Canvas2DPerRegionRenderingBackend extends Canvas2DRenderingBackendB
     release() { }
     renderBlocks(blocks, regions, state) {
         prepareCanvas(this.canvas, this.ctx, state.canvasWidth, state.canvasHeight);
+        const clear = this.clearColor(state);
+        if (clear) {
+            const [r, g, b, a] = clear;
+            this.ctx.fillStyle = `rgba(${Math.round(r * 255)},${Math.round(g * 255)},${Math.round(b * 255)},${a})`;
+            this.ctx.fillRect(0, 0, state.canvasWidth, state.canvasHeight);
+        }
         this.draw(blocks, regions, state);
         return blocks.some(block => regions.has(block.displayedRegionIndex));
     }
+    /**
+     * What the frame is painted onto before the blocks are drawn — the Canvas2D
+     * half of the GPU base's `beginFrame` clear. Undefined, the default, leaves
+     * `prepareCanvas`'s `clearRect` as the whole of it, which is transparent.
+     * Synteny is the one display that overrides: its indel wedges pre-blend
+     * against a KNOWN ground and only agree with the base ribbon beside them over
+     * a destination that really is that colour.
+     */
+    clearColor(_state) {
+        return undefined;
+    }
 }
 /**
  * GPU-side base for `PerRegionRenderingBackend` implementations. Inherits the
@@ -70,9 +88,10 @@ export class GpuPerRegionRenderingBackend extends GpuRenderingBackendBase {
         // 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);
+        // Always pair beginFrame/endFrame so the canvas clears even when every
+        // block is skipped (e.g. all regions pruned by a density gate).
+        const [clearR, clearG, clearB, clearA] = this.clearColor(state);
+        this.hal.beginFrame(clearR, clearG, clearB, clearA);
         for (const block of blocks) {
             const region = regions.get(block.displayedRegionIndex);
             if (region !== undefined) {
@@ -87,7 +106,22 @@ export class GpuPerRegionRenderingBackend extends GpuRenderingBackendBase {
         }
         this.hal.clearScissor();
         this.hal.clearViewport();
+        if (this.drawOverBlocks(regions, state, scale)) {
+            painted = true;
+            this.hal.clearViewport();
+        }
         this.hal.endFrame();
         return painted;
     }
+    /**
+     * Draw what spans the whole canvas after the blocks, with the scissor and
+     * viewport cleared, and answer whether anything drew.
+     */
+    drawOverBlocks(_regions, _state, _scale) {
+        return false;
+    }
+    /** @see Canvas2DPerRegionRenderingBackend.clearColor */
+    clearColor(_state) {
+        return TRANSPARENT;
+    }
 }

package/esm/regionDataMap.d.ts

@@ -17,8 +17,8 @@ export declare function isCheckedAtTheStore(map: ReadonlyMap<unknown, unknown>):
  *   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.
+ *   for every cached region on every row reorder, since a reorder 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.