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

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

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/renderingBackendBase.d.ts

@@ -1,22 +1,19 @@
 import type { GpuHal } from './hal/types.ts';
 /**
  * Minimum render-state shape a frame scaffold needs: the CSS-pixel canvas
- * dimensions used to size the backing store, and — on the per-region side —
- * to clip each block.
+ * dimensions used to size the backing store, and to clip each block.
  *
  * Here rather than beside either family because both bound their render state
- * by it: `GpuPerRegionRenderingBackend.renderBlocks` and
- * `GpuGlobalRenderingBackend.render` open with the same `hal.resize`, and the
- * two Canvas2D bases with the same `prepareCanvas`.
+ * by it: `GpuPerRegionRenderingBackend.renderBlocks` opens with `hal.resize`,
+ * and its Canvas2D twin with `prepareCanvas`.
  */
 export interface FrameDimensions {
     canvasWidth: number;
     canvasHeight: number;
 }
 /**
- * What every rendering backend has, whatever its upload shape — the three
- * shape contracts (`PerRegionRenderingBackend`, `GlobalRenderingBackend`,
- * `KeyedRenderingBackend`) all extend this, and `useRenderingBackend` is
+ * What every rendering backend has, whatever its upload shape —
+ * `PerRegionRenderingBackend` extends this, and `useRenderingBackend` is
  * bounded by it.
  *
  * `setErrorHandler` is here rather than optional at the hook because it was
@@ -40,8 +37,8 @@ export interface RenderingBackend {
     dispose(): void;
 }
 /**
- * Shared GPU-side state for every GPU rendering backend — both per-region
- * (`GpuPerRegionRenderingBackend`) and monolithic (`GpuGlobalRenderingBackend`).
+ * Shared GPU-side state for every GPU rendering backend
+ * (`GpuPerRegionRenderingBackend`, and the shared-canvas backends over it).
  * Owns the `hal` reference and a pre-allocated uniform scratch `ArrayBuffer`
  * reused across frames to avoid per-frame GC churn. `dispose()` delegates to
  * the HAL. Subclasses add only their upload/render shape.
@@ -49,14 +46,14 @@ export interface RenderingBackend {
 export declare abstract class GpuRenderingBackendBase {
     protected hal: GpuHal;
     protected uniformData: ArrayBuffer;
-    constructor(hal: GpuHal, uniformByteSize: number);
+    constructor(hal: GpuHal);
     setErrorHandler(handler: (error: Error) => void): void;
     dispose(): void;
 }
 /**
- * Shared Canvas2D-side state for every Canvas2D rendering backend — both
- * per-region (`Canvas2DPerRegionRenderingBackend`) and monolithic
- * (`Canvas2DGlobalRenderingBackend`). Owns the `canvas` and its 2D context
+ * Shared Canvas2D-side state for every Canvas2D rendering backend
+ * (`Canvas2DPerRegionRenderingBackend`, and the shared-canvas backends over
+ * it). Owns the `canvas` and its 2D context
  * (constructor throws if unavailable). `dispose()` is a no-op since Canvas2D
  * holds no GPU resources. Subclasses add only their render shape and stub the
  * upload/prune hooks their interface requires (everything flows through the

package/esm/renderingBackendBase.js

@@ -1,7 +1,7 @@
 import { acquireCanvas2D } from './canvasContext.js';
 /**
- * Shared GPU-side state for every GPU rendering backend — both per-region
- * (`GpuPerRegionRenderingBackend`) and monolithic (`GpuGlobalRenderingBackend`).
+ * Shared GPU-side state for every GPU rendering backend
+ * (`GpuPerRegionRenderingBackend`, and the shared-canvas backends over it).
  * Owns the `hal` reference and a pre-allocated uniform scratch `ArrayBuffer`
  * reused across frames to avoid per-frame GC churn. `dispose()` delegates to
  * the HAL. Subclasses add only their upload/render shape.
@@ -9,9 +9,9 @@ import { acquireCanvas2D } from './canvasContext.js';
 export class GpuRenderingBackendBase {
     hal;
     uniformData;
-    constructor(hal, uniformByteSize) {
+    constructor(hal) {
         this.hal = hal;
-        this.uniformData = new ArrayBuffer(uniformByteSize);
+        this.uniformData = new ArrayBuffer(hal.uniformByteSize);
     }
     // Forward OOM / over-limit allocation failures from the HAL to the display's
     // renderError. Wired by useRenderingBackend once the backend is live.
@@ -23,9 +23,9 @@ export class GpuRenderingBackendBase {
     }
 }
 /**
- * Shared Canvas2D-side state for every Canvas2D rendering backend — both
- * per-region (`Canvas2DPerRegionRenderingBackend`) and monolithic
- * (`Canvas2DGlobalRenderingBackend`). Owns the `canvas` and its 2D context
+ * Shared Canvas2D-side state for every Canvas2D rendering backend
+ * (`Canvas2DPerRegionRenderingBackend`, and the shared-canvas backends over
+ * it). Owns the `canvas` and its 2D context
  * (constructor throws if unavailable). `dispose()` is a no-op since Canvas2D
  * holds no GPU resources. Subclasses add only their render shape and stub the
  * upload/prune hooks their interface requires (everything flows through the

package/esm/shaders/capsule.js.generated.d.ts

@@ -0,0 +1 @@
+export declare function capsuleDistPx(alongPx: number, acrossPx: number, halfLenPx: number): number;

package/esm/shaders/capsule.js.generated.js

@@ -0,0 +1,11 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from capsule.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+// Scalar twins of capsule.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+function _max(a, b) {
+    return b > a || Number.isNaN(a) ? b : a;
+}
+export function capsuleDistPx(alongPx, acrossPx, halfLenPx) {
+    let _t0 = _max((Math.abs(alongPx) - halfLenPx), 0.0);
+    return Math.sqrt(((_t0 * _t0) + (acrossPx * acrossPx)));
+}