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

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. */
+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.
+ *
+ * A caller that narrows it must hand over marks declaring no `band`, and that
+ * is the one way the two clips do not compose: a banded mark scissors to its
+ * strip and hands the BLOCK COLUMN back rather than what the caller had. The
+ * split is deliberate — `render-core/CLAUDE.md` §Drawing has which displays
+ * take which side — but nothing enforces it, so it is stated at both.
+ */
+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;
+    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,137 @@
+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';
+// The passes a mark list owns a buffer for: the whole list minus those drawing
+// off another's (`bufferOf`). Uploading to a borrowed pass is silent and its
+// buffer is the lender's, so the skip is stated once, here — module-local,
+// because `marks/backend` is a published subpath and nothing outside wants it.
+function ownedPasses(marks) {
+    return marks.filter(m => !m.bufferOf).map(m => m.pass);
+}
+/** Pack and upload one region's buffers for a mark list. */
+export function uploadMarks(hal, regionKey, marks, data) {
+    for (const pass of ownedPasses(marks)) {
+        uploadPass(hal, regionKey, 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.
+ *
+ * A caller that narrows it must hand over marks declaring no `band`, and that
+ * is the one way the two clips do not compose: a banded mark scissors to its
+ * strip and hands the BLOCK COLUMN back rather than what the caller had. The
+ * split is deliberate — `render-core/CLAUDE.md` §Drawing has which displays
+ * take which side — but nothing enforces it, so it is stated at both.
+ */
+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;
+    // The base's upload loop already IS the mark walk, so this backend names its
+    // passes instead of overriding `upload` with a second spelling of it.
+    regionPasses;
+    constructor(hal, marks, clear) {
+        super(hal);
+        this.marks = marks;
+        this.clear = clear;
+        this.regionPasses = ownedPasses(marks);
+    }
+    clearColor(state) {
+        return this.clear ? this.clear(state) : super.clearColor(state);
+    }
+    // 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/markHit.d.ts

@@ -0,0 +1,25 @@
+import type { MarkHit } from './types.ts';
+/** One instance's ink measured against a cursor — a `MarkHit` before it is one. */
+export type InkHit = Omit<MarkHit, 'index'>;
+/**
+ * Where a rect's ink sits nearest `(xPx, yPx)`, and how far: the point itself
+ * where the cursor is inside, else the nearest point on the edge.
+ */
+export declare function inkOnRect(xPx: number, yPx: number, left: number, top: number, width: number, height: number): InkHit;
+/** The same for a mark with no extent to clamp into. */
+export declare function inkAtPoint(xPx: number, yPx: number, x: number, y: number): InkHit;
+/**
+ * The nearest of `candidates` by where each one's ink is, or undefined when
+ * none beats `maxDistSq`.
+ *
+ * This is the whole of every shape's `hitNearest` but the geometry: `inkAt`
+ * answers where instance `i` put ink and how far that is, and this keeps the
+ * closest. Only a STRICTLY nearer candidate replaces the best, so on a tie the
+ * first wins — which is what makes a caller that iterates back to front get the
+ * mark on top, and it is a rule that used to be spelled out five times over.
+ *
+ * `inkAt` may answer `undefined` for an instance that drew nothing at all, as
+ * against one that drew somewhere far away: a bar clipped out of its band has
+ * no ink to be near.
+ */
+export declare function nearestInk(candidates: Iterable<number>, maxDistSq: number, inkAt: (index: number) => InkHit | undefined): MarkHit | undefined;

package/esm/marks/markHit.js

@@ -0,0 +1,46 @@
+/**
+ * Where a rect's ink sits nearest `(xPx, yPx)`, and how far: the point itself
+ * where the cursor is inside, else the nearest point on the edge.
+ */
+export function inkOnRect(xPx, yPx, left, top, width, height) {
+    const x = Math.min(Math.max(xPx, left), left + width);
+    const y = Math.min(Math.max(yPx, top), top + height);
+    const dx = xPx - x;
+    const dy = yPx - y;
+    return { x, y, distSq: dx * dx + dy * dy };
+}
+/** The same for a mark with no extent to clamp into. */
+export function inkAtPoint(xPx, yPx, x, y) {
+    const dx = xPx - x;
+    const dy = yPx - y;
+    return { x, y, distSq: dx * dx + dy * dy };
+}
+/**
+ * The nearest of `candidates` by where each one's ink is, or undefined when
+ * none beats `maxDistSq`.
+ *
+ * This is the whole of every shape's `hitNearest` but the geometry: `inkAt`
+ * answers where instance `i` put ink and how far that is, and this keeps the
+ * closest. Only a STRICTLY nearer candidate replaces the best, so on a tie the
+ * first wins — which is what makes a caller that iterates back to front get the
+ * mark on top, and it is a rule that used to be spelled out five times over.
+ *
+ * `inkAt` may answer `undefined` for an instance that drew nothing at all, as
+ * against one that drew somewhere far away: a bar clipped out of its band has
+ * no ink to be near.
+ */
+export function nearestInk(candidates, maxDistSq, inkAt) {
+    let best;
+    let bestDistSq = maxDistSq;
+    for (const index of candidates) {
+        const ink = inkAt(index);
+        if (ink && ink.distSq < bestDistSq) {
+            bestDistSq = ink.distSq;
+            // Field by field, not `{ index, ...ink }`, which is both slower and one
+            // shape away from minting a hidden class per ink source and making every
+            // downstream `hit.x` read polymorphic.
+            best = { index, x: ink.x, y: ink.y, distSq: ink.distSq };
+        }
+    }
+    return best;
+}

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;

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,91 @@
+import { bpRangeXTuple } from '../blockClipUtils.js';
+import { getDpr, makeBpMapper } from '../canvas2dUtils.js';
+import * as shader from '../shaders/pointMark.generated.js';
+import { pointDrawsBar, valueToYPx } from '../shaders/pointMark.js.generated.js';
+import { slangPass } from '../slangPass.js';
+import { abgrToCssRgba } from './colorFill.js';
+import { appendGlyph } from './glyphPaint.js';
+import { inkAtPoint, inkOnRect, nearestInk } from './markHit.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 (pointDrawsBar(widthPx, r)) {
+                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;
+        return nearestInk(candidates, maxDistSq, i => {
+            const xStart = bpToPx(x[i]);
+            const xEnd = bpToPx(x2[i]);
+            const cy = valueToYPx(y[i], domainMin, domainMax, canvasHeight);
+            // A bar is the rect the painter fills, unpadded on every side, so the
+            // drawn bar and this box are one rectangle. A glyph has no rect to clamp
+            // into and offers its centre.
+            const lo = Math.min(xStart, xEnd);
+            const hi = Math.max(xStart, xEnd);
+            return pointDrawsBar(hi - lo, diameterPx / 2)
+                ? inkOnRect(xPx, yPx, lo, cy - diameterPx / 2, hi - lo, diameterPx)
+                : inkAtPoint(xPx, yPx, xStart, cy);
+        });
+    },
+};