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

package/esm/instanceCache.d.ts

@@ -14,9 +14,8 @@ export interface InstanceCacheOpts<TData> {
     colorOffsetWords: number;
 }
 /**
- * A per-key cache of packed instance bytes with a geometry/color split: a
- * recolor patches the one color lane in place instead of re-packing every
- * other one.
+ * A cache of packed instance bytes with a geometry/color split: a recolor
+ * patches the one color lane in place instead of re-packing every other one.
  *
  * The split is worth having because the two inputs move on completely
  * different schedules — geometry on an RPC refetch, colors on a `colorBy`
@@ -32,12 +31,16 @@ export interface InstanceCacheOpts<TData> {
  * problem. `installUpload` exists for the same reason one
  * layer up — an upload memo is not a hand-rolled `let`.
  *
+ * **The geometry token is the key**, so nothing has to evict: a payload whose
+ * coordinates were replaced takes its bytes with it, and a cache shared by
+ * several displays cannot hand one display another's buffer — two displays
+ * never hold one coordinate array. That is also what lets a mark's `pack`
+ * hold one of these, a mark list being module-level and shared.
+ *
  * The GPU re-upload still happens on a recolor (no HAL does partial buffer
  * updates); what is skipped is the dominant CPU interleave.
  */
 export declare function createInstanceCache<TData>(opts: InstanceCacheOpts<TData>): {
-    /** Packed bytes for `key`, re-packing or re-coloring only as needed. */
-    get(key: number, data: TData): ArrayBuffer;
-    delete(key: number): void;
-    clear(): void;
+    /** Packed bytes for `data`, re-packing or re-coloring only as needed. */
+    get(data: TData): ArrayBuffer;
 };

package/esm/instanceCache.js

@@ -1,7 +1,6 @@
 /**
- * A per-key cache of packed instance bytes with a geometry/color split: a
- * recolor patches the one color lane in place instead of re-packing every
- * other one.
+ * A cache of packed instance bytes with a geometry/color split: a recolor
+ * patches the one color lane in place instead of re-packing every other one.
  *
  * The split is worth having because the two inputs move on completely
  * different schedules — geometry on an RPC refetch, colors on a `colorBy`
@@ -17,19 +16,25 @@
  * problem. `installUpload` exists for the same reason one
  * layer up — an upload memo is not a hand-rolled `let`.
  *
+ * **The geometry token is the key**, so nothing has to evict: a payload whose
+ * coordinates were replaced takes its bytes with it, and a cache shared by
+ * several displays cannot hand one display another's buffer — two displays
+ * never hold one coordinate array. That is also what lets a mark's `pack`
+ * hold one of these, a mark list being module-level and shared.
+ *
  * The GPU re-upload still happens on a recolor (no HAL does partial buffer
  * updates); what is skipped is the dominant CPU interleave.
  */
 export function createInstanceCache(opts) {
     const { geomToken, colors, interleave, strideWords, colorOffsetWords } = opts;
-    const cache = new Map();
+    const cache = new WeakMap();
     return {
-        /** Packed bytes for `key`, re-packing or re-coloring only as needed. */
-        get(key, data) {
+        /** Packed bytes for `data`, re-packing or re-coloring only as needed. */
+        get(data) {
             const geom = geomToken(data);
             const cols = colors(data);
-            const hit = cache.get(key);
-            if (hit?.geom === geom) {
+            const hit = cache.get(geom);
+            if (hit) {
                 if (hit.colors !== cols) {
                     const u32 = new Uint32Array(hit.buf);
                     for (let i = 0, n = cols.length; i < n; i++) {
@@ -40,14 +45,8 @@ export function createInstanceCache(opts) {
                 return hit.buf;
             }
             const buf = interleave(data);
-            cache.set(key, { geom, colors: cols, buf });
+            cache.set(geom, { colors: cols, buf });
             return buf;
         },
-        delete(key) {
-            cache.delete(key);
-        },
-        clear() {
-            cache.clear();
-        },
     };
 }

package/esm/mapUploadSync.d.ts

@@ -1,14 +1,6 @@
 export interface MapUploadTarget<K, T, B> {
     upload: (backend: B, key: K, data: T) => void;
-    /**
-     * How a key that left the map is released. `remove` deletes it by itself;
-     * `prune` is handed the keys still present and releases everything else.
-     * `installUpload` takes the first, which is the only correct shape on a
-     * canvas several displays share and does the same job on a display's own
-     * map.
-     */
     remove?: (backend: B, key: K) => void;
-    prune?: (backend: B, active: ReadonlySet<K>) => void;
 }
 /**
  * The one reference diff every keyed GPU upload in the tree runs on. Uploads

package/esm/mapUploadSync.js

@@ -39,7 +39,6 @@ export function createMapUploadSync(target) {
                 changed = true;
             }
         }
-        target.prune?.(backend, new Set(entries.keys()));
         return changed;
     };
 }

package/esm/marks/colorFill.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Packed ABGR → `rgba(...)`, and the run-tracking fill a painter wraps it in.
+ *
+ * `@jbrowse/core/util/colorBits` re-exports `abgrToCssRgba` from here: core
+ * depends on render-core, never the reverse. The direction that genuinely
+ * needs core is resolving a CSS colour to a packed number, which is why a
+ * shape takes packed colours and the display resolves them.
+ */
+export declare function abgrToCssRgba(c: number): string;
+/**
+ * A fill-style setter that only touches `ctx.fillStyle` when the colour
+ * changes. Most of a painting is runs of one colour, and both the string
+ * allocation and the context write cost more than the comparison.
+ */
+export declare function makeAbgrFill(ctx: {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+}): (abgr: number) => void;

package/esm/marks/colorFill.js

@@ -0,0 +1,26 @@
+/**
+ * Packed ABGR → `rgba(...)`, and the run-tracking fill a painter wraps it in.
+ *
+ * `@jbrowse/core/util/colorBits` re-exports `abgrToCssRgba` from here: core
+ * depends on render-core, never the reverse. The direction that genuinely
+ * needs core is resolving a CSS colour to a packed number, which is why a
+ * shape takes packed colours and the display resolves them.
+ */
+export function abgrToCssRgba(c) {
+    const a = ((c >>> 24) & 255) / 255;
+    return `rgba(${c & 255},${(c >>> 8) & 255},${(c >>> 16) & 255},${a})`;
+}
+/**
+ * A fill-style setter that only touches `ctx.fillStyle` when the colour
+ * changes. Most of a painting is runs of one colour, and both the string
+ * allocation and the context write cost more than the comparison.
+ */
+export function makeAbgrFill(ctx) {
+    let last;
+    return (abgr) => {
+        if (abgr !== last) {
+            last = abgr;
+            ctx.fillStyle = abgrToCssRgba(abgr);
+        }
+    };
+}

package/esm/marks/drawAgainstHit.d.ts

@@ -0,0 +1,47 @@
+import type { RenderBlock } from '../renderBlock.ts';
+import type { MarkContext2D, MarkFrame, MarkShape } from './types.ts';
+export interface RecordedRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fillStyle: string;
+}
+/**
+ * A `MarkContext2D` that records every rect a painter fills, in paint order —
+ * `fillRect` and path `rect` alike, so a shape that batches by colour records
+ * the same list as one that fills per instance. A path traced with
+ * `moveTo`/`lineTo` and filled records its bounding box, which is what a
+ * shape whose hit test answers a polygon's box (the variant inversion
+ * triangle) is held to.
+ *
+ * A **stroked** path records one rect per `moveTo`/`lineTo` edge, each the
+ * edge's bounding box widened by half the current `lineWidth` — the extent a
+ * round cap reaches on all four sides. Per edge rather than per `stroke()`,
+ * because a painter that batches a colour run into one path (dotplot's) would
+ * otherwise record the run's hull as a single instance. `fillStyle` on such a
+ * record is the `strokeStyle` it went down in; the field is the colour of the
+ * ink either way.
+ */
+export declare function recordingContext(): {
+    ctx: MarkContext2D;
+    calls: RecordedRect[];
+};
+/**
+ * The draw-against-hit gate for a shape whose instances paint as rects: paint
+ * the block, then walk it in `step` px and hold `hitNearest` to what the
+ * painter recorded. A hit at distance 0 has to sit on the rect of the index it
+ * names, and a point on a rect has to answer that rect — the last-painted one
+ * where rects overlap, since the sweep hands candidates in back to front.
+ *
+ * Returns the violations rather than asserting, so a test reads as
+ * `expect(sweep(...)).toEqual([])`. `maxDistSq` is the caller's, because a
+ * shape whose hit target is wider than its ink (`point`) needs a bound that
+ * admits the whole rect.
+ */
+export declare function sweepDrawAgainstHit<C extends {
+    count: number;
+}, P>(shape: MarkShape<C, P>, channels: C, block: RenderBlock, frame: MarkFrame, params: P, { maxDistSq, step }: {
+    maxDistSq: number;
+    step?: number;
+}): string[];

package/esm/marks/drawAgainstHit.js

@@ -0,0 +1,140 @@
+/**
+ * A `MarkContext2D` that records every rect a painter fills, in paint order —
+ * `fillRect` and path `rect` alike, so a shape that batches by colour records
+ * the same list as one that fills per instance. A path traced with
+ * `moveTo`/`lineTo` and filled records its bounding box, which is what a
+ * shape whose hit test answers a polygon's box (the variant inversion
+ * triangle) is held to.
+ *
+ * A **stroked** path records one rect per `moveTo`/`lineTo` edge, each the
+ * edge's bounding box widened by half the current `lineWidth` — the extent a
+ * round cap reaches on all four sides. Per edge rather than per `stroke()`,
+ * because a painter that batches a colour run into one path (dotplot's) would
+ * otherwise record the run's hull as a single instance. `fillStyle` on such a
+ * record is the `strokeStyle` it went down in; the field is the colour of the
+ * ink either way.
+ */
+export function recordingContext() {
+    const calls = [];
+    const points = [];
+    const edges = [];
+    const ctx = {
+        fillStyle: '',
+        strokeStyle: '',
+        lineWidth: 1,
+        lineCap: 'butt',
+        save() { },
+        restore() { },
+        beginPath() {
+            points.length = 0;
+            edges.length = 0;
+        },
+        clip() { },
+        moveTo(x, y) {
+            points.push([x, y]);
+        },
+        lineTo(x, y) {
+            const from = points.at(-1);
+            if (from) {
+                edges.push([from[0], from[1], x, y]);
+            }
+            points.push([x, y]);
+        },
+        arc() { },
+        closePath() { },
+        fill() {
+            if (points.length > 0) {
+                const xs = points.map(p => p[0]);
+                const ys = points.map(p => p[1]);
+                const x = Math.min(...xs);
+                const y = Math.min(...ys);
+                calls.push({
+                    x,
+                    y,
+                    w: Math.max(...xs) - x,
+                    h: Math.max(...ys) - y,
+                    fillStyle: this.fillStyle,
+                });
+                points.length = 0;
+                edges.length = 0;
+            }
+        },
+        stroke() {
+            const half = this.lineWidth / 2;
+            for (const [ax, ay, bx, by] of edges) {
+                const x = Math.min(ax, bx) - half;
+                const y = Math.min(ay, by) - half;
+                calls.push({
+                    x,
+                    y,
+                    w: Math.max(ax, bx) + half - x,
+                    h: Math.max(ay, by) + half - y,
+                    fillStyle: this.strokeStyle,
+                });
+            }
+            points.length = 0;
+            edges.length = 0;
+        },
+        rect(x, y, w, h) {
+            calls.push({ x, y, w, h, fillStyle: this.fillStyle });
+        },
+        fillRect(x, y, w, h) {
+            calls.push({ x, y, w, h, fillStyle: this.fillStyle });
+        },
+    };
+    return { ctx: ctx, calls };
+}
+function contains(r, x, y) {
+    return x >= r.x && x <= r.x + r.w && y >= r.y && y <= r.y + r.h;
+}
+/**
+ * The draw-against-hit gate for a shape whose instances paint as rects: paint
+ * the block, then walk it in `step` px and hold `hitNearest` to what the
+ * painter recorded. A hit at distance 0 has to sit on the rect of the index it
+ * names, and a point on a rect has to answer that rect — the last-painted one
+ * where rects overlap, since the sweep hands candidates in back to front.
+ *
+ * Returns the violations rather than asserting, so a test reads as
+ * `expect(sweep(...)).toEqual([])`. `maxDistSq` is the caller's, because a
+ * shape whose hit target is wider than its ink (`point`) needs a bound that
+ * admits the whole rect.
+ */
+export function sweepDrawAgainstHit(shape, channels, block, frame, params, { maxDistSq, step = 0.5 }) {
+    const violations = [];
+    const { ctx, calls: rects } = recordingContext();
+    shape.paintBlock(ctx, channels, block, frame, params);
+    if (rects.length !== channels.count) {
+        return [`painted ${rects.length} rects for ${channels.count} instances`];
+    }
+    const candidates = Array.from({ length: channels.count }, (_, k) => channels.count - 1 - k);
+    let yMin = Infinity;
+    let yMax = -Infinity;
+    for (const r of rects) {
+        yMin = Math.min(yMin, r.y);
+        yMax = Math.max(yMax, r.y + r.h);
+    }
+    const x0 = Math.min(block.screenStartPx, block.screenEndPx) - 1;
+    const x1 = Math.max(block.screenStartPx, block.screenEndPx) + 1;
+    for (let y = Math.floor(yMin) - 1; y <= yMax + 1; y += step) {
+        for (let x = x0; x <= x1; x += step) {
+            let expected = -1;
+            for (let k = rects.length - 1; k >= 0; k--) {
+                if (contains(rects[k], x, y)) {
+                    expected = k;
+                    break;
+                }
+            }
+            const hit = shape.hitNearest(channels, block, frame, params, x, y, candidates, maxDistSq);
+            if (hit && hit.distSq === 0 && !contains(rects[hit.index], x, y)) {
+                violations.push(`(${x}, ${y}) answered ${hit.index} at distance 0, off its rect`);
+            }
+            if (expected !== -1 && hit?.index !== expected) {
+                violations.push(`(${x}, ${y}) is on rect ${expected}, answered ${hit?.index ?? 'nothing'}`);
+            }
+            if (violations.length >= 10) {
+                return violations;
+            }
+        }
+    }
+    return violations;
+}

package/esm/marks/glyphPaint.d.ts

@@ -0,0 +1,16 @@
+import type { MarkContext2D } from './types.ts';
+/**
+ * Append one of the `point` shape's glyphs to the current path, centred on
+ * `(cx, y)`.
+ *
+ * The disc/crisp-square split and the square's snap are pointGlyph.slang's
+ * (adr-051), so the painter cannot drift from the shader about where the split
+ * is. The caller owns `beginPath`/`fill`, which is what lets a run of one
+ * colour batch into a single fill.
+ *
+ * Its own module, not `pointMark.ts`'s: this is the half of the shape a
+ * consumer can want without the pass, and importing it through the shape would
+ * hand that consumer the shader's WGSL and GLSL strings. Wiggle's scatter mode
+ * is that consumer.
+ */
+export declare function appendGlyph(ctx: MarkContext2D, glyph: number, cx: number, y: number, diameter: number): void;

package/esm/marks/glyphPaint.js

@@ -0,0 +1,41 @@
+import { SMALL_POINT_MAX_DIAMETER } from '../shaders/pointGlyph.generated.js';
+import { crispSquareTopLeftPx } from '../shaders/pointGlyph.js.generated.js';
+import { DIAMOND_GLYPH_SCALE, GLYPH_DIAMOND, GLYPH_TRIANGLE, } from '../shaders/pointMark.consts.generated.js';
+/**
+ * Append one of the `point` shape's glyphs to the current path, centred on
+ * `(cx, y)`.
+ *
+ * The disc/crisp-square split and the square's snap are pointGlyph.slang's
+ * (adr-051), so the painter cannot drift from the shader about where the split
+ * is. The caller owns `beginPath`/`fill`, which is what lets a run of one
+ * colour batch into a single fill.
+ *
+ * Its own module, not `pointMark.ts`'s: this is the half of the shape a
+ * consumer can want without the pass, and importing it through the shape would
+ * hand that consumer the shader's WGSL and GLSL strings. Wiggle's scatter mode
+ * is that consumer.
+ */
+export function appendGlyph(ctx, glyph, cx, y, diameter) {
+    const r = diameter / 2;
+    if (glyph === GLYPH_TRIANGLE) {
+        ctx.moveTo(cx - r, y - r);
+        ctx.lineTo(cx + r, y - r);
+        ctx.lineTo(cx, y + r);
+        ctx.closePath();
+    }
+    else if (glyph === GLYPH_DIAMOND) {
+        const ri = r * DIAMOND_GLYPH_SCALE;
+        ctx.moveTo(cx, y - ri);
+        ctx.lineTo(cx + ri, y);
+        ctx.lineTo(cx, y + ri);
+        ctx.lineTo(cx - ri, y);
+        ctx.closePath();
+    }
+    else if (diameter <= SMALL_POINT_MAX_DIAMETER) {
+        ctx.rect(crispSquareTopLeftPx(cx, diameter), crispSquareTopLeftPx(y, diameter), diameter, diameter);
+    }
+    else {
+        ctx.moveTo(cx + r, y);
+        ctx.arc(cx, y, r, 0, Math.PI * 2);
+    }
+}

package/esm/marks/index.d.ts

@@ -0,0 +1,9 @@
+export { defineMark } from './types.ts';
+export { paintMarkBlocks } from './markPaint.ts';
+export { pointMark } from './pointMark.ts';
+export { spanMark } from './spanMark.ts';
+export { appendGlyph } from './glyphPaint.ts';
+export { abgrToCssRgba, makeAbgrFill } from './colorFill.ts';
+export type { Mark, MarkBand, MarkContext2D, MarkFrame, MarkHit, MarkShape, StagedUniforms, } from './types.ts';
+export type { PointChannels, PointParams } from './pointMark.ts';
+export type { SpanChannels, SpanParams } from './spanMark.ts';

package/esm/marks/index.js

@@ -0,0 +1,6 @@
+export { defineMark } from './types.js';
+export { paintMarkBlocks } from './markPaint.js';
+export { pointMark } from './pointMark.js';
+export { spanMark } from './spanMark.js';
+export { appendGlyph } from './glyphPaint.js';
+export { abgrToCssRgba, makeAbgrFill } from './colorFill.js';

package/esm/marks/markBackend.d.ts

@@ -0,0 +1,87 @@
+import { Canvas2DPerRegionRenderingBackend, GpuPerRegionRenderingBackend } from '../perRegionRenderingBackend.ts';
+import type { BlockClipResult } from '../blockClipUtils.ts';
+import type { GpuHal } from '../hal/index.ts';
+import type { SampleCount } from '../hal/types.ts';
+import type { InstancePass } from '../instancePass.ts';
+import type { ClearColor, PerRegionRenderingBackend } from '../perRegionRenderingBackend.ts';
+import type { RenderBlock } from '../renderBlock.ts';
+import type { FrameDimensions } from '../renderingBackendBase.ts';
+import type { Mark } from './types.ts';
+/**
+ * Pack and upload one region's buffers for a mark list — every mark that owns
+ * one, which is the whole list minus those drawing off another's (`bufferOf`).
+ * That skip is the reason a display's upload is this call rather than a loop:
+ * uploading to a borrowed pass is silent, and its buffer is the lender's.
+ */
+export declare function uploadMarks<TRegion, TState extends FrameDimensions>(hal: GpuHal, regionKey: number, marks: readonly Mark<TRegion, TState>[], data: TRegion): void;
+/**
+ * Draw one already-clipped block through a mark list.
+ *
+ * **The viewport is this helper's, the scissor is the caller's.** Every shape
+ * maps bp across the block column, so nobody wants a viewport narrower than the
+ * clip; a caller does want a narrower scissor, which is how alignments clips a
+ * coverage strip inside the column it hands over. `GpuPerRegionRenderingBackend`
+ * sets both per block already, so for a backend on that scaffold the viewport
+ * set here is the same rect twice.
+ */
+export declare function drawMarks<TRegion, TState extends FrameDimensions>(hal: GpuHal, scratch: ArrayBuffer, marks: readonly Mark<TRegion, TState>[], block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState, regionKey: number): void;
+/**
+ * The HAL-side half of `createMarkBackend`, exported so a display's mark list
+ * can be driven against `MockHal`: which marks upload, which draw off another's
+ * buffer, and which blocks a shape declines.
+ */
+export declare class GpuMarkBackend<TRegion, TState extends FrameDimensions> extends GpuPerRegionRenderingBackend<TRegion, TState> {
+    private marks;
+    private clear?;
+    protected regionPasses: InstancePass<TRegion>[];
+    constructor(hal: GpuHal, marks: readonly Mark<TRegion, TState>[], clear?: ((state: TState) => ClearColor) | undefined);
+    protected clearColor(state: TState): ClearColor;
+    upload(regionKey: number, data: TRegion): void;
+    private boundRamps;
+    private bindRamp;
+    protected drawRegion(block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState): void;
+}
+/**
+ * The Canvas2D half, exported for the same reason `GpuMarkBackend` is: a
+ * display's frame scaffold — the ground it clears to, the blocks it paints — is
+ * a property of the pair, and a suite pinning it on one backend has to pin it
+ * on the other.
+ */
+export declare class Canvas2DMarkBackend<TRegion, TState extends FrameDimensions> extends Canvas2DPerRegionRenderingBackend<TRegion, TState> {
+    private marks;
+    private clear?;
+    constructor(canvas: HTMLCanvasElement, marks: readonly Mark<TRegion, TState>[], clear?: ((state: TState) => ClearColor) | undefined);
+    protected clearColor(state: TState): ClearColor | undefined;
+    protected draw(blocks: RenderBlock[], regions: ReadonlyMap<number, TRegion>, state: TState): void;
+}
+/**
+ * Build a display's rendering backend from its mark declarations.
+ *
+ * **This is the only module on the mark path that reaches the HAL**, which is
+ * why it is not on the `marks` subpath: a display's declaration, its painter
+ * and its hit test are all things a state model can legitimately reach, and a
+ * state model is eager (ADR-091). Reaching the backend costs the GPU stack at
+ * plugin-install time, so it is a separate import a display makes once, from
+ * the factory the component hands to `DisplayChrome`.
+ *
+ * This is the whole of what a display used to spell as a `GpuXxxRenderer`
+ * class, a `Canvas2DXxxRenderer` class, a pass list and a factory: the passes
+ * are the marks' own and each backend walks the same list.
+ *
+ * One uniform buffer serves every mark because each writes its own layout into
+ * the scratch immediately before its own `drawPass`, which is what the HAL's
+ * write-then-draw ordering already guarantees for a multi-pass renderer — or
+ * draws off the struct the previous mark of the same block already staged, per
+ * `StagedUniforms`.
+ */
+export declare function createMarkBackend<TRegion, TState extends FrameDimensions>(canvas: HTMLCanvasElement, marks: readonly Mark<TRegion, TState>[], opts?: {
+    sampleCount?: SampleCount;
+    /**
+     * What the frame is cleared to, when transparent is the wrong answer. The
+     * GPU side hands it to `beginFrame` and the Canvas2D side fills it after
+     * `prepareCanvas`, so both backends composite over the same colour — which
+     * synteny needs, its indel wedges being pre-blended against the band's
+     * ground rather than composited over it.
+     */
+    clearColor?: (state: TState) => ClearColor;
+}): Promise<PerRegionRenderingBackend<TRegion, TState>>;

package/esm/marks/markBackend.js

@@ -0,0 +1,133 @@
+import { COLOR_RAMP_LUT_ENTRIES, uploadColorRampLut } from '../colorRampLut.js';
+import { createRenderingBackend } from '../createRenderingBackend.js';
+import { uploadPass } from '../instancePass.js';
+import { Canvas2DPerRegionRenderingBackend, GpuPerRegionRenderingBackend, } from '../perRegionRenderingBackend.js';
+import { paintMarkBlocks } from './markPaint.js';
+/**
+ * Pack and upload one region's buffers for a mark list — every mark that owns
+ * one, which is the whole list minus those drawing off another's (`bufferOf`).
+ * That skip is the reason a display's upload is this call rather than a loop:
+ * uploading to a borrowed pass is silent, and its buffer is the lender's.
+ */
+export function uploadMarks(hal, regionKey, marks, data) {
+    for (const mark of marks) {
+        if (!mark.bufferOf) {
+            uploadPass(hal, regionKey, mark.pass, data);
+        }
+    }
+}
+/**
+ * Draw one already-clipped block through a mark list.
+ *
+ * **The viewport is this helper's, the scissor is the caller's.** Every shape
+ * maps bp across the block column, so nobody wants a viewport narrower than the
+ * clip; a caller does want a narrower scissor, which is how alignments clips a
+ * coverage strip inside the column it hands over. `GpuPerRegionRenderingBackend`
+ * sets both per block already, so for a backend on that scaffold the viewport
+ * set here is the same rect twice.
+ */
+export function drawMarks(hal, scratch, marks, block, clip, region, state, regionKey) {
+    hal.setViewport(clip.pxX, 0, clip.pxW, clip.pxH);
+    // One call is one block, which is exactly the life of a `StagedUniforms`
+    const staged = { writer: undefined, params: undefined };
+    for (const mark of marks) {
+        mark.drawRegion(hal, scratch, block, clip, region, state, regionKey, staged);
+    }
+}
+// What a textured pass binds while its mark names no ramp: a shader declares
+// its sampler unconditionally, and a textured pass with no texture never draws
+// on the WebGPU HAL.
+const INERT_RAMP = new Uint8Array(COLOR_RAMP_LUT_ENTRIES * 4);
+/**
+ * The HAL-side half of `createMarkBackend`, exported so a display's mark list
+ * can be driven against `MockHal`: which marks upload, which draw off another's
+ * buffer, and which blocks a shape declines.
+ */
+export class GpuMarkBackend extends GpuPerRegionRenderingBackend {
+    marks;
+    clear;
+    // `upload` runs `uploadMarks` in place of the base's loop, so nothing reads
+    // this — the `bufferOf` skip is stated once, there
+    regionPasses = [];
+    constructor(hal, marks, clear) {
+        super(hal);
+        this.marks = marks;
+        this.clear = clear;
+    }
+    clearColor(state) {
+        return this.clear ? this.clear(state) : super.clearColor(state);
+    }
+    upload(regionKey, data) {
+        uploadMarks(this.hal, regionKey, this.marks, data);
+    }
+    // The ramp each textured pass holds, by the table's identity — the mirror of
+    // the one texture the HAL keeps per pass, so an unchanged ramp costs a frame
+    // nothing and a backend rebuilt after context loss re-uploads. Per pass and
+    // per backend, never per region.
+    boundRamps = new Map();
+    bindRamp(mark, region, state) {
+        if (mark.texture) {
+            const ramp = mark.texture(state, region) ?? INERT_RAMP;
+            if (ramp !== this.boundRamps.get(mark.pass.id)) {
+                uploadColorRampLut(this.hal, ramp, [mark.pass.id]);
+                this.boundRamps.set(mark.pass.id, ramp);
+            }
+        }
+    }
+    drawRegion(block, clip, region, state) {
+        for (const mark of this.marks) {
+            this.bindRamp(mark, region, state);
+        }
+        drawMarks(this.hal, this.uniformData, this.marks, block, clip, region, state, block.displayedRegionIndex);
+    }
+}
+/**
+ * The Canvas2D half, exported for the same reason `GpuMarkBackend` is: a
+ * display's frame scaffold — the ground it clears to, the blocks it paints — is
+ * a property of the pair, and a suite pinning it on one backend has to pin it
+ * on the other.
+ */
+export class Canvas2DMarkBackend extends Canvas2DPerRegionRenderingBackend {
+    marks;
+    clear;
+    constructor(canvas, marks, clear) {
+        super(canvas);
+        this.marks = marks;
+        this.clear = clear;
+    }
+    clearColor(state) {
+        return this.clear ? this.clear(state) : super.clearColor(state);
+    }
+    draw(blocks, regions, state) {
+        paintMarkBlocks(this.ctx, this.marks, regions, blocks, state);
+    }
+}
+/**
+ * Build a display's rendering backend from its mark declarations.
+ *
+ * **This is the only module on the mark path that reaches the HAL**, which is
+ * why it is not on the `marks` subpath: a display's declaration, its painter
+ * and its hit test are all things a state model can legitimately reach, and a
+ * state model is eager (ADR-091). Reaching the backend costs the GPU stack at
+ * plugin-install time, so it is a separate import a display makes once, from
+ * the factory the component hands to `DisplayChrome`.
+ *
+ * This is the whole of what a display used to spell as a `GpuXxxRenderer`
+ * class, a `Canvas2DXxxRenderer` class, a pass list and a factory: the passes
+ * are the marks' own and each backend walks the same list.
+ *
+ * One uniform buffer serves every mark because each writes its own layout into
+ * the scratch immediately before its own `drawPass`, which is what the HAL's
+ * write-then-draw ordering already guarantees for a multi-pass renderer — or
+ * draws off the struct the previous mark of the same block already staged, per
+ * `StagedUniforms`.
+ */
+export function createMarkBackend(canvas, marks, opts = {}) {
+    const { clearColor } = opts;
+    return createRenderingBackend(canvas, {
+        passes: marks.map(m => m.pass),
+        sampleCount: opts.sampleCount,
+        createGpuBackend: hal => new GpuMarkBackend(hal, marks, clearColor),
+        createCanvas2DBackend: c => new Canvas2DMarkBackend(c, marks, clearColor),
+    });
+}

package/esm/marks/markPaint.d.ts

@@ -0,0 +1,13 @@
+import type { RenderBlock } from '../renderBlock.ts';
+import type { Mark, MarkContext2D, MarkFrame } from './types.ts';
+/**
+ * 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 declare function paintMarkBlocks<TRegion, TState extends MarkFrame>(ctx: MarkContext2D, marks: readonly Mark<TRegion, TState>[], regions: ReadonlyMap<number, TRegion>, blocks: RenderBlock[], state: TState): void;