@jbrowse/render-core 5.0.0-beta.2 → 5.0.0-beta.4

package/esm/marks/spanMark.d.ts

@@ -0,0 +1,45 @@
+import type { MarkShape } from './types.ts';
+/**
+ * The `span` shape's channels: a coloured rectangle from `x` to `x2` on the
+ * band belonging to `row`.
+ */
+export interface SpanChannels {
+    x: Uint32Array;
+    x2: Uint32Array;
+    row: Uint32Array;
+    color: Uint32Array;
+    count: number;
+}
+export interface SpanParams {
+    /** CSS px per row. */
+    rowHeight: number;
+    /** Fraction of the row the rect fills, leaving inter-row gaps. */
+    rowProportion: number;
+    /**
+     * Narrowest a span is painted, in CSS px. Zero is a no-op and is what a
+     * caller whose marks TILE writes — widening a sub-pixel cell inside a run
+     * paints ink the data does not contain. A caller whose marks are sparse
+     * intervals floors, because at chromosome zoom the alternative is a smudge.
+     */
+    minWidthPx: number;
+    /**
+     * CSS px of overlap added to each span's right edge by the **painter only**.
+     *
+     * The GPU pass needs none: abutting quads share an exact clip-space edge and
+     * the rasterizer fills it once. Canvas2D antialiases each `fillRect`
+     * independently, so two runs meeting on a fractional pixel each take partial
+     * coverage of it and a hairline of background shows through. Which callers
+     * want it splits on the same axis `minWidthPx` does — MAF's cells tile, so it
+     * pads; the multi-row painter's features are sparse intervals with background
+     * between them by right, so it writes 0.
+     *
+     * Padding the drawn width and not the anchor is what keeps it growing
+     * rightward on both orientations, so a reversed block's spans stay exact
+     * mirrors of a forward block's. Wiggle's `WIGGLE_FUDGE_FACTOR` is the same
+     * rule spelled per display; the shader must not grow a matching pad.
+     */
+    seamPx: number;
+    /** Rows-area scroll offset in CSS px; 0 for a canvas sized to its content. */
+    scrollTop: number;
+}
+export declare const spanMark: MarkShape<SpanChannels, SpanParams>;

package/esm/marks/spanMark.js

@@ -0,0 +1,59 @@
+import { bpRangeXTuple } from '../blockClipUtils.js';
+import { makeBpMapper, spanLeft } from '../canvas2dUtils.js';
+import { drawnRowHeightPx, rowBandOffsetPx, } from '../shaders/rowRect.js.generated.js';
+import * as shader from '../shaders/spanMark.generated.js';
+import { slangPass } from '../slangPass.js';
+import { makeAbgrFill } from './colorFill.js';
+import { inkOnRect, nearestInk } from './markHit.js';
+export const spanMark = {
+    id: 'span',
+    pass: {
+        ...slangPass({ id: 'span', mod: shader }),
+        pack: c => shader.packInstances(c, c.count),
+    },
+    writeUniforms(scratch, clip, block, frame, params) {
+        shader.writeUniforms(scratch, {
+            bpRangeX: bpRangeXTuple(clip, block.reversed),
+            canvasHeight: frame.canvasHeight,
+            // CSS px, not physical: `extendToMinWidthX` divides `minCellPx` by this
+            // to reach clip space, so a CSS width is what makes the floor a CSS-pixel
+            // one and matches the painter's `Math.max` below.
+            minCellDenomPx: clip.scissorW,
+            minCellPx: params.minWidthPx,
+            zero: 0,
+            rowHeight: params.rowHeight,
+            rowProportion: params.rowProportion,
+            scrollTop: params.scrollTop,
+        });
+    },
+    paintBlock(ctx, channels, block, _frame, params) {
+        const { x, x2, row, color, count } = channels;
+        const { rowHeight, rowProportion, minWidthPx, seamPx, scrollTop } = params;
+        const h = drawnRowHeightPx(rowHeight, rowProportion);
+        const offset = rowBandOffsetPx(rowHeight, rowProportion);
+        const bpToPx = makeBpMapper(block);
+        const setFill = makeAbgrFill(ctx);
+        for (let i = 0; i < count; i++) {
+            const xa = bpToPx(x[i]);
+            const xb = bpToPx(x2[i]);
+            const width = Math.max(minWidthPx, Math.abs(xb - xa));
+            setFill(color[i]);
+            ctx.fillRect(spanLeft(xa, xb, width), offset + rowHeight * row[i] - scrollTop, width + seamPx, h);
+        }
+    },
+    hitNearest(channels, block, _frame, params, xPx, yPx, candidates, maxDistSq) {
+        const { x, x2, row } = channels;
+        const { rowHeight, rowProportion, minWidthPx, scrollTop } = params;
+        const h = drawnRowHeightPx(rowHeight, rowProportion);
+        const offset = rowBandOffsetPx(rowHeight, rowProportion);
+        const bpToPx = makeBpMapper(block);
+        return nearestInk(candidates, maxDistSq, i => {
+            const xa = bpToPx(x[i]);
+            const xb = bpToPx(x2[i]);
+            const width = Math.max(minWidthPx, Math.abs(xb - xa));
+            // the rect `paintBlock` fills, less `seamPx`, which is painter-only
+            // overdraw
+            return inkOnRect(xPx, yPx, spanLeft(xa, xb, width), offset + rowHeight * row[i] - scrollTop, width, h);
+        });
+    },
+};

package/esm/marks/types.d.ts

@@ -0,0 +1,216 @@
+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, structural for the same reason
+ * `ClipContext2D` is: render-core must not depend on `@jbrowse/core`, where the
+ * real `Ctx2D = CanvasRenderingContext2D | SvgCanvas` union lives. Both members
+ * satisfy it, so a display passes its `Ctx2D` straight in — which is also what
+ * makes one painter the on-screen fallback and the SVG export path.
+ */
+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): 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;
+}
+export type MarkFrame = FrameDimensions;
+/** 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;
+}
+/**
+ * A shape: one hand-written `.slang`, one packer, one Canvas2D painter and one
+ * hit test, all reading the same channel arrays.
+ *
+ * `TChannels` is the shape's own vocabulary — parallel typed arrays plus a
+ * count. `TParams` is everything else the drawing needs, which reaches the GPU
+ * as uniforms and the painter as arguments; the two must be the same values or
+ * the backends diverge, which is what having one object per shape prevents.
+ *
+ * There is no `MarkShape` constructor. A shape is written out once and
+ * admitted by a consumer rather than by completeness — the ADR-040 bar. It
+ * lives here when two displays share it (`span`) or its geometry is generic
+ * (`point`); a display whose shader's generated twins feed its own hit test
+ * keeps the shape beside them (variants' `cellMark`) and still declares it
+ * through `defineMark`.
+ */
+export interface MarkShape<TChannels, TParams> {
+    readonly id: string;
+    readonly pass: InstancePass<TChannels>;
+    writeUniforms(scratch: ArrayBuffer, clip: BlockClipResult, block: RenderBlock, frame: MarkFrame, params: TParams): void;
+    paintBlock(ctx: MarkContext2D, channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams): void;
+    /**
+     * The shape's draw predicate over (block, frame, params) — not over its
+     * instances, which it is never handed. Both backends skip the block when it
+     * says no, and so does `hitNearest`: a block with no ink on it has nothing
+     * to be near. Optional: a shape whose every block can carry ink leaves it
+     * off.
+     *
+     * Placement is one use: the canvas continuation marker exists only where a
+     * block meets a canvas edge, and an interior block would otherwise shade a
+     * whole pileup's worth of vertices to draw nothing. Settings are the other,
+     * and the general one: the coverage band's layers read `hasDomain` off
+     * `params` so an unresolved autoscale draws no depth-scaled layer rather
+     * than bars of arbitrary height, and `showInterbase` off it so the histogram
+     * and its triangles turn off together.
+     */
+    paintsBlock?(block: RenderBlock, frame: MarkFrame, params: TParams): boolean;
+    /**
+     * The nearest drawn ink to `(xPx, yPx)` among `candidates`, or undefined if
+     * nothing beats `maxDistSq`.
+     *
+     * The candidate set is the caller's, not the shape's: a display with a
+     * worker-built index (GWAS's Flatbush over (bp, value)) hands in what the
+     * index answered, and one without hands in every instance. What the shape
+     * owns is where its ink actually is — the half that drifts from the painter.
+     *
+     * Distance 0 means the point is on the ink `paintBlock` fills, edges
+     * included, and a caller wanting containment alone passes a bound that
+     * admits nothing else (`Number.MIN_VALUE`). Only a strictly nearer candidate
+     * replaces the best, so on a tie the first candidate wins — a caller that
+     * iterates back to front gets the last-painted mark, which is the one on
+     * top. `drawAgainstHit.ts` is the sweep that holds a shape to this.
+     *
+     * Optional, because a shape earns it from a consumer like any other member.
+     * MAF answers a hit from row/column arithmetic over the alignment rather than
+     * from `span`'s channels, so it reads none.
+     */
+    hitNearest?(channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams, xPx: number, yPx: number, candidates: Iterable<number>, maxDistSq: number): MarkHit | undefined;
+}
+/**
+ * Which uniform struct is standing in the HAL's current slot, so the next mark
+ * of the SAME block can draw off it instead of packing and staging the same
+ * bytes again. Compared by reference and never called or read for its values:
+ * one writer plus one `params` lens is one struct, because `writeUniforms` sees
+ * nothing but the block, the clip, the frame and what that lens returned.
+ *
+ * A display declaring several marks over one writer and one lens is the common
+ * shape, not an edge case — the coverage band is five, the feature glyphs are
+ * five — and every mark after the first was restating the previous one's write.
+ *
+ * **The caller owns one of these per block and hands the same one to every mark
+ * of that block.** A stale one drawn against the next block's clip is silently
+ * the wrong geometry, so it is a fresh object per block rather than a field
+ * that has to be remembered to reset. A caller that writes uniforms of its own
+ * between marks (alignments' per-section pileup write) starts a new one after
+ * it, or hands none at all.
+ */
+export interface StagedUniforms {
+    writer: unknown;
+    params: unknown;
+}
+/**
+ * A shape bound to one display's region payload and render state — what
+ * `defineMark` returns and what a display actually holds.
+ *
+ * The shape's own generics are erased here on purpose: a display draws a list
+ * of marks over heterogeneous shapes, and only the binding knows how to reach
+ * either one's channels.
+ */
+export interface Mark<TRegion, TState extends MarkFrame> {
+    readonly pass: InstancePass<TRegion>;
+    /**
+     * The pass id whose instance buffer this mark draws from, for a mark that
+     * is registered but never uploaded to: the canvas chevrons ride the line
+     * buffer and the continuation markers ride rect's. `defineMark` refuses the
+     * pairing unless the two passes declare one instance struct.
+     */
+    readonly bufferOf?: string;
+    /**
+     * The 256-entry RGBA colour ramp this mark's pass samples this frame, or
+     * undefined when it samples none. `createMarkBackend` uploads it per pass and
+     * only when the bytes' identity moves, and binds an inert table for the
+     * undefined case — a shader owns its sampler unconditionally, and a textured
+     * pass with no texture never draws on the WebGPU HAL.
+     */
+    readonly texture?: (state: TState, region: TRegion) => Uint8Array | undefined;
+    drawRegion(hal: GpuHal, scratch: ArrayBuffer, block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState, regionKey: number, staged?: StagedUniforms): 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;
+}
+/**
+ * `{ shape, channels }` over typed arrays — the declaration a display writes in
+ * place of a `GpuXxxRenderer` class, a `Canvas2DXxxRenderer` class, a factory
+ * and a pass list.
+ *
+ * `channels` and `params` are projections, not copies: `channels` names which
+ * of the region's arrays feed the shape's lanes, and `params` names which of
+ * the render state's values reach the uniforms — and which of the region's,
+ * for a value the payload carries rather than the frame (the variant matrix's
+ * column count). Both run once per block per frame, never per instance.
+ *
+ * **`channels` answers `undefined` for a region this mark has nothing in.**
+ * That is how one mark list serves a display whose cells are a union — synteny
+ * draws ribbon cells, outline cells and glyph-lane cells off one list, and a
+ * region key holds exactly one of the three. The mark then packs an empty
+ * buffer (which every HAL reads as the release), draws nothing and paints
+ * nothing, so the kind test is stated once per mark instead of once per
+ * backend.
+ *
+ * **`params` is handed the block**, because the key a display's per-track
+ * state is filed under is the block's `displayedRegionIndex` and nothing else
+ * in the lens's reach says which track this is. Every method the lens feeds
+ * already receives the block; the lens receiving it is what lets it stay a
+ * pick rather than pushing the lookup into the shape.
+ *
+ * `bufferOf` names the mark whose uploaded buffer this one draws from, so the
+ * declaration says what the HAL's `drawPass(id, region, bufferPassId)` says:
+ * the chevron mark's channels are the line mark's, packed once under the line
+ * pass.
+ *
+ * `texture` is the colour ramp the mark's pass samples, for a shape that
+ * resolves a per-instance scalar through a LUT (wiggle density, and the same
+ * 256-entry table HiC and LD bind). It is state, not a channel: the backend
+ * uploads it once per pass and re-uploads only when the bytes' identity moves,
+ * so a ramp change costs one texture and no instance byte.
+ *
+ * **Per pass per FRAME, though the lens is handed a region too.** LD reads its
+ * ramp off the payload's own metric — a pre-computed file with no D' column
+ * downgrades the request, and the metric that arrived is the authoritative one
+ * — which is exact because LD holds one region. A display with several regions
+ * wanting different ramps for one pass would re-upload the texture per region
+ * per frame; correct, since each recorded draw keeps the table bound when it
+ * was encoded, but a texture per region per frame is not what this is for.
+ *
+ * `band` is the strip of the canvas the mark is clipped to, for a display that
+ * stacks bands on one canvas (MAF's coverage strip over its rows viewport).
+ * The GPU scissors to it and Canvas2D clips to it, a zero-height band draws
+ * nothing, and the shape still places Y against the whole canvas — the band is
+ * a clip, never an offset, which is what lets one `scrollTop` serve both
+ * backends. A mark without one paints wherever its shape puts ink.
+ */
+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;
+    texture?: (state: TState, region: TRegion) => Uint8Array | undefined;
+}): Mark<TRegion, TState>;

package/esm/marks/types.js

@@ -0,0 +1,146 @@
+import { devicePxBand, withClip } from '../canvas2dUtils.js';
+/**
+ * `{ shape, channels }` over typed arrays — the declaration a display writes in
+ * place of a `GpuXxxRenderer` class, a `Canvas2DXxxRenderer` class, a factory
+ * and a pass list.
+ *
+ * `channels` and `params` are projections, not copies: `channels` names which
+ * of the region's arrays feed the shape's lanes, and `params` names which of
+ * the render state's values reach the uniforms — and which of the region's,
+ * for a value the payload carries rather than the frame (the variant matrix's
+ * column count). Both run once per block per frame, never per instance.
+ *
+ * **`channels` answers `undefined` for a region this mark has nothing in.**
+ * That is how one mark list serves a display whose cells are a union — synteny
+ * draws ribbon cells, outline cells and glyph-lane cells off one list, and a
+ * region key holds exactly one of the three. The mark then packs an empty
+ * buffer (which every HAL reads as the release), draws nothing and paints
+ * nothing, so the kind test is stated once per mark instead of once per
+ * backend.
+ *
+ * **`params` is handed the block**, because the key a display's per-track
+ * state is filed under is the block's `displayedRegionIndex` and nothing else
+ * in the lens's reach says which track this is. Every method the lens feeds
+ * already receives the block; the lens receiving it is what lets it stay a
+ * pick rather than pushing the lookup into the shape.
+ *
+ * `bufferOf` names the mark whose uploaded buffer this one draws from, so the
+ * declaration says what the HAL's `drawPass(id, region, bufferPassId)` says:
+ * the chevron mark's channels are the line mark's, packed once under the line
+ * pass.
+ *
+ * `texture` is the colour ramp the mark's pass samples, for a shape that
+ * resolves a per-instance scalar through a LUT (wiggle density, and the same
+ * 256-entry table HiC and LD bind). It is state, not a channel: the backend
+ * uploads it once per pass and re-uploads only when the bytes' identity moves,
+ * so a ramp change costs one texture and no instance byte.
+ *
+ * **Per pass per FRAME, though the lens is handed a region too.** LD reads its
+ * ramp off the payload's own metric — a pre-computed file with no D' column
+ * downgrades the request, and the metric that arrived is the authoritative one
+ * — which is exact because LD holds one region. A display with several regions
+ * wanting different ramps for one pass would re-upload the texture per region
+ * per frame; correct, since each recorded draw keeps the table bound when it
+ * was encoded, but a texture per region per frame is not what this is for.
+ *
+ * `band` is the strip of the canvas the mark is clipped to, for a display that
+ * stacks bands on one canvas (MAF's coverage strip over its rows viewport).
+ * The GPU scissors to it and Canvas2D clips to it, a zero-height band draws
+ * nothing, and the shape still places Y against the whole canvas — the band is
+ * a clip, never an offset, which is what lets one `scrollTop` serve both
+ * backends. A mark without one paints wherever its shape puts ink.
+ */
+export function defineMark(spec) {
+    const { shape, channels, params, band, texture } = spec;
+    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;
+    return {
+        pass: {
+            ...shape.pass,
+            pack: region => {
+                const c = channels(region);
+                return c === undefined ? NOTHING : shape.pass.pack(c);
+            },
+        },
+        bufferOf,
+        texture,
+        drawRegion(hal, scratch, block, clip, region, state, regionKey, staged) {
+            const strip = band?.(state);
+            const scissor = strip
+                ? devicePxBand(strip.top, strip.height, clip.scaleY, clip.pxH)
+                : undefined;
+            if (scissor?.height !== 0 && channels(region) !== undefined) {
+                const p = params(state, region, block);
+                if (!shape.paintsBlock || shape.paintsBlock(block, state, p)) {
+                    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);
+                    if (scissor) {
+                        hal.setScissor(clip.pxX, 0, clip.pxW, clip.pxH);
+                    }
+                }
+            }
+        },
+        paintBlock(ctx, region, block, state) {
+            const strip = band?.(state);
+            const c = channels(region);
+            if ((!strip || strip.height > 0) && c !== undefined) {
+                const p = params(state, region, block);
+                if (!shape.paintsBlock || shape.paintsBlock(block, state, p)) {
+                    const paint = () => {
+                        shape.paintBlock(ctx, c, block, state, p);
+                    };
+                    if (strip) {
+                        withClip(ctx, 0, strip.top, state.canvasWidth, strip.height, paint);
+                    }
+                    else {
+                        paint();
+                    }
+                }
+            }
+        },
+        hitNearest: shape.hitNearest
+            ? (region, block, state, xPx, yPx, candidates, maxDistSq) => {
+                const strip = band?.(state);
+                const c = channels(region);
+                let hit;
+                // The three gates `paintBlock` takes, in its order — the band on its
+                // HEIGHT, as there, so a band both backends decline answers nothing
+                // either. The cursor being inside the strip is a fourth, and the ink
+                // being inside it the fifth: a band is a CLIP, so ink outside one was
+                // never drawn and cannot be the nearest thing to anything.
+                if ((!strip || strip.height > 0) &&
+                    c !== undefined &&
+                    !bandExcludes(strip, yPx)) {
+                    const p = params(state, region, block);
+                    if (!shape.paintsBlock || shape.paintsBlock(block, state, p)) {
+                        hit = shape.hitNearest(c, block, state, p, xPx, yPx, candidates, maxDistSq);
+                    }
+                }
+                return hit && !bandExcludes(strip, hit.y) ? hit : undefined;
+            }
+            : undefined,
+    };
+}
+// What a mark with nothing in this region packs. An empty pack IS the release
+// — every HAL deletes the pass's prior buffer before it looks at the count.
+const NOTHING = new ArrayBuffer(0);
+function bandExcludes(strip, yPx) {
+    return (strip !== undefined && (yPx < strip.top || yPx > strip.top + strip.height));
+}

package/esm/perRegionRenderingBackend.d.ts

@@ -4,6 +4,8 @@ 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 +14,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 +59,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.
@@ -111,4 +121,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) {
@@ -90,4 +109,8 @@ export class GpuPerRegionRenderingBackend extends GpuRenderingBackendBase {
         this.hal.endFrame();
         return painted;
     }
+    /** @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.

package/esm/regionDataMap.js

@@ -27,8 +27,8 @@ export function isCheckedAtTheStore(map) {
  *   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.

package/esm/renderBlock.d.ts

@@ -23,3 +23,17 @@ export interface RenderBlock extends BpRegionBounds {
 export declare function buildRenderBlocks(regions: (BpRegionBounds & {
     displayedRegionIndex: number;
 })[]): RenderBlock[];
+/**
+ * One display key's whole canvas as a single block.
+ *
+ * For a display whose x axis is not the block's bp span: a dotplot segment, a
+ * synteny ribbon, a Hi-C or LD diamond each read their screen x off the
+ * payload's own coordinates through a transform the shader and the painter both
+ * apply — a `panPx` fold from the fetch-time base for the first two, the
+ * diagonal `viewScale`/`viewOffsetX` for the last two. So the block carries
+ * nothing but its key and the identity bp span that keeps `clipBlock`
+ * well-formed.
+ */
+export declare function canvasWideBlock(displayedRegionIndex: number, canvasWidth: number): RenderBlock;
+/** {@link canvasWideBlock} per key, in the keys' own order. */
+export declare function canvasWideBlocks(keys: Iterable<number>, canvasWidth: number): RenderBlock[];

package/esm/renderBlock.js

@@ -8,3 +8,28 @@ export function buildRenderBlocks(regions) {
         reversed: r.reversed ?? false,
     }));
 }
+/**
+ * One display key's whole canvas as a single block.
+ *
+ * For a display whose x axis is not the block's bp span: a dotplot segment, a
+ * synteny ribbon, a Hi-C or LD diamond each read their screen x off the
+ * payload's own coordinates through a transform the shader and the painter both
+ * apply — a `panPx` fold from the fetch-time base for the first two, the
+ * diagonal `viewScale`/`viewOffsetX` for the last two. So the block carries
+ * nothing but its key and the identity bp span that keeps `clipBlock`
+ * well-formed.
+ */
+export function canvasWideBlock(displayedRegionIndex, canvasWidth) {
+    return {
+        displayedRegionIndex,
+        start: 0,
+        end: canvasWidth,
+        screenStartPx: 0,
+        screenEndPx: canvasWidth,
+        reversed: false,
+    };
+}
+/** {@link canvasWideBlock} per key, in the keys' own order. */
+export function canvasWideBlocks(keys, canvasWidth) {
+    return [...keys].map(key => canvasWideBlock(key, canvasWidth));
+}