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

package/esm/marks/markPaint.js

@@ -0,0 +1,18 @@
+import { forEachClippedBlock } from '../canvas2dUtils.js';
+/**
+ * Paint one frame's blocks with a mark list — the Canvas2D half of a
+ * declaration, and the SVG export path, since `MarkContext2D` is satisfied by
+ * both a real 2D context and the SVG one.
+ *
+ * Its own module, away from the backend that calls it: an SVG export runs with
+ * no backend attached at all (and must, or a headless export would depend on a
+ * GPU device having been probed), so the path that draws must not pull the HAL
+ * in behind it.
+ */
+export function paintMarkBlocks(ctx, marks, regions, blocks, state) {
+    forEachClippedBlock(ctx, blocks, state.canvasWidth, state.canvasHeight, block => regions.get(block.displayedRegionIndex), (region, block) => {
+        for (const mark of marks) {
+            mark.paintBlock(ctx, region, block, state);
+        }
+    });
+}

package/esm/marks/pointMark.d.ts

@@ -0,0 +1,24 @@
+import type { MarkShape } from './types.ts';
+/**
+ * The `point` shape's channels: a glyph per instance at `x`, on the `y` scale,
+ * widening to a bar where `x2 - x` is wider than the glyph.
+ *
+ * `x2` is a channel rather than an option because the widening is per instance:
+ * one array holds SNPs (`x2 === x + 1`) and structural variants together, and
+ * the shader, the painter and the hit test all take the same branch off it.
+ */
+export interface PointChannels {
+    x: Uint32Array;
+    x2: Uint32Array;
+    y: Float32Array;
+    color: Uint32Array;
+    glyph: Uint8Array;
+    count: number;
+}
+export interface PointParams {
+    /** `[min, max]` of the linear scale `y` is read through. */
+    domain: [number, number];
+    /** Glyph diameter in CSS px. */
+    diameterPx: number;
+}
+export declare const pointMark: MarkShape<PointChannels, PointParams>;

package/esm/marks/pointMark.js

@@ -0,0 +1,98 @@
+import { bpRangeXTuple } from '../blockClipUtils.js';
+import { getDpr, makeBpMapper } from '../canvas2dUtils.js';
+import * as shader from '../shaders/pointMark.generated.js';
+import { valueToYPx } from '../shaders/pointMark.js.generated.js';
+import { slangPass } from '../slangPass.js';
+import { abgrToCssRgba } from './colorFill.js';
+import { appendGlyph } from './glyphPaint.js';
+export const pointMark = {
+    id: 'point',
+    pass: {
+        ...slangPass({ id: 'point', 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,
+            domainMin: params.domain[0],
+            domainMax: params.domain[1],
+            zero: 0,
+            // viewportWidth and radiusPx stay in CSS units to match canvasHeight:
+            // mixing a DPR-scaled radius with a CSS-scaled height draws vertically
+            // stretched ellipses on hi-DPI.
+            viewportWidth: clip.scissorW,
+            radiusPx: params.diameterPx / 2,
+            devicePixelRatio: getDpr(),
+        });
+    },
+    paintBlock(ctx, channels, block, frame, params) {
+        const { x, x2, y, color, glyph, count } = channels;
+        if (count === 0) {
+            return;
+        }
+        const { diameterPx, domain } = params;
+        const r = diameterPx / 2;
+        const canvasHeight = frame.canvasHeight;
+        const domainMin = domain[0];
+        const domainMax = domain[1];
+        // The per-block closure, not the six-argument `bpToScreenPx`: that spelling
+        // re-derives the region span and the block width at every call, and this
+        // loop makes two calls per instance. Measured at 1.67x on 100K points.
+        const bpToPx = makeBpMapper(block);
+        // Batched by colour: a run of one colour is one fillStyle write and one
+        // fill() over a shared path, which is most of a painting.
+        let current = color[0];
+        ctx.fillStyle = abgrToCssRgba(current);
+        ctx.beginPath();
+        for (let i = 0; i < count; i++) {
+            const abgr = color[i];
+            if (abgr !== current) {
+                ctx.fill();
+                current = abgr;
+                ctx.fillStyle = abgrToCssRgba(abgr);
+                ctx.beginPath();
+            }
+            const xStart = bpToPx(x[i]);
+            const xEnd = bpToPx(x2[i]);
+            const yPx = valueToYPx(y[i], domainMin, domainMax, canvasHeight);
+            const widthPx = Math.abs(xEnd - xStart);
+            if (widthPx > diameterPx) {
+                ctx.rect(Math.min(xStart, xEnd), yPx - r, widthPx, diameterPx);
+            }
+            else {
+                appendGlyph(ctx, glyph[i], xStart, yPx, diameterPx);
+            }
+        }
+        ctx.fill();
+    },
+    hitNearest(channels, block, frame, params, xPx, yPx, candidates, maxDistSq) {
+        const { x, x2, y } = channels;
+        const bpToPx = makeBpMapper(block);
+        const { diameterPx, domain } = params;
+        const domainMin = domain[0];
+        const domainMax = domain[1];
+        const canvasHeight = frame.canvasHeight;
+        let best;
+        let bestDistSq = maxDistSq;
+        for (const i of candidates) {
+            const xStart = bpToPx(x[i]);
+            const xEnd = bpToPx(x2[i]);
+            // The bar branch, in the same words the shader and the painter take it:
+            // a mark with extent is grabbed at the nearest point along its span, a
+            // glyph at its centre.
+            const lo = Math.min(xStart, xEnd);
+            const hi = Math.max(xStart, xEnd);
+            const ptX = hi - lo > diameterPx ? Math.max(lo, Math.min(xPx, hi)) : xStart;
+            const ptY = valueToYPx(y[i], domainMin, domainMax, canvasHeight);
+            const dx = xPx - ptX;
+            const dy = yPx - ptY;
+            const distSq = dx * dx + dy * dy;
+            if (distSq < bestDistSq) {
+                bestDistSq = distSq;
+                best = { index: i, x: ptX, y: ptY, distSq };
+            }
+        }
+        return best;
+    },
+};

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,71 @@
+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';
+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);
+        let best;
+        let bestDistSq = maxDistSq;
+        for (const i of candidates) {
+            const xa = bpToPx(x[i]);
+            const xb = bpToPx(x2[i]);
+            const width = Math.max(minWidthPx, Math.abs(xb - xa));
+            const left = spanLeft(xa, xb, width);
+            const top = offset + rowHeight * row[i] - scrollTop;
+            // the rect `paintBlock` fills, less `seamPx`, which is painter-only
+            // overdraw; distance 0 inside it, else to its nearest edge
+            const nx = Math.min(Math.max(xPx, left), left + width);
+            const ny = Math.min(Math.max(yPx, top), top + h);
+            const dx = xPx - nx;
+            const dy = yPx - ny;
+            const distSq = dx * dx + dy * dy;
+            if (distSq < bestDistSq) {
+                bestDistSq = distSq;
+                best = { index: i, x: nx, y: ny, distSq };
+            }
+        }
+        return best;
+    },
+};

package/esm/marks/types.d.ts

@@ -0,0 +1,206 @@
+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. 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.
+ *
+ * `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,125 @@
+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.
+ *
+ * `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 c = channels(region);
+                return c === undefined || bandExcludes(band?.(state), yPx)
+                    ? undefined
+                    : shape.hitNearest(c, block, state, params(state, region, block), xPx, yPx, candidates, maxDistSq);
+            }
+            : 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;
 }