@jbrowse/render-core 4.3.0 → 5.0.0-beta.10

package/esm/marks/markBackend.d.ts

@@ -0,0 +1,118 @@
+import { Canvas2DPerRegionRenderingBackend, GpuPerRegionRenderingBackend } from '../perRegionRenderingBackend.ts';
+import type { BlockClipResult } from '../blockClipUtils.ts';
+import type { CanvasScale } from '../canvas2dUtils.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 { MarkPlan } from './markPlan.ts';
+import type { Mark, MarkTexture, TextureBinder } 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, textures?: TextureBinder): void;
+/**
+ * Draw one block's planned passes off the uniforms the caller has already
+ * staged for it. No gate, no lens, no write: `planMarks` settled the frame
+ * question and the caller's own `hal.writeUniforms` settled the block's, so
+ * what is left per mark is the `drawPass` — the loop a display with its own
+ * frame scaffold was already running over a hand-kept pass list.
+ *
+ * Viewport and scissor are the caller's, as with `drawMarks`' scissor: a
+ * plan's marks declare no `band`, so nothing here narrows or restores either.
+ */
+export declare function drawPlannedPasses(hal: GpuHal, plan: Pick<MarkPlan<never, never>, 'passes'>, regionKey: number): void;
+/**
+ * The texture each textured pass holds, by identity — the mirror of the one
+ * texture the HAL keeps per pass, so an unchanged ramp, strip or table costs a
+ * frame nothing and a backend rebuilt after context loss re-uploads. Per pass
+ * and per backend, never per region: a lens answering nothing for a region
+ * leaves the pass's texture where it is, and binds the inert table only while
+ * the pass has none at all, since a ring canvas draws one region per pass and
+ * a lens with no opinion on the other regions must not swap the strip out and
+ * back on every frame.
+ */
+export declare class MarkTextureBinder implements TextureBinder {
+    private hal;
+    private bound;
+    constructor(hal: GpuHal);
+    bind(passId: string, sampler: string, texture: MarkTexture | undefined): 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 clear?;
+    protected regionPasses: InstancePass<TRegion>[];
+    private textures;
+    private blockMarks;
+    private viewMarks;
+    constructor(hal: GpuHal, marks: readonly Mark<TRegion, TState>[], clear?: ((state: TState) => ClearColor) | undefined);
+    protected clearColor(state: TState): ClearColor;
+    private drawWith;
+    protected drawRegion(block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState): void;
+    protected drawOverBlocks(regions: ReadonlyMap<number, TRegion>, state: TState, scale: CanvasScale): boolean;
+}
+/**
+ * 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 `drawPass`, the ordering the HAL's
+ * write-then-draw contract 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,196 @@
+import { clipBlock } from '../blockClipUtils.js';
+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 { canvasWideBlock } from '../renderBlock.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, textures) {
+    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, textures);
+    }
+}
+/**
+ * Draw one block's planned passes off the uniforms the caller has already
+ * staged for it. No gate, no lens, no write: `planMarks` settled the frame
+ * question and the caller's own `hal.writeUniforms` settled the block's, so
+ * what is left per mark is the `drawPass` — the loop a display with its own
+ * frame scaffold was already running over a hand-kept pass list.
+ *
+ * Viewport and scissor are the caller's, as with `drawMarks`' scissor: a
+ * plan's marks declare no `band`, so nothing here narrows or restores either.
+ */
+export function drawPlannedPasses(hal, plan, regionKey) {
+    const { passes } = plan;
+    for (let i = 0; i < passes.length; i++) {
+        const pass = passes[i];
+        hal.drawPass(pass.id, regionKey, pass.bufferOf);
+    }
+}
+// What a textured pass binds while its mark names no ramp: a shader declares
+// its sampler unconditionally, and a textured pass missing a texture draws
+// nothing on either GPU HAL. A mark declaring no `texture` at all is the same case —
+// `pointMark` carries a sampler for the shapes that ramp, and a point of a
+// constant colour draws it without one.
+const INERT_RAMP = new Uint8Array(COLOR_RAMP_LUT_ENTRIES * 4);
+/**
+ * The texture each textured pass holds, by identity — the mirror of the one
+ * texture the HAL keeps per pass, so an unchanged ramp, strip or table costs a
+ * frame nothing and a backend rebuilt after context loss re-uploads. Per pass
+ * and per backend, never per region: a lens answering nothing for a region
+ * leaves the pass's texture where it is, and binds the inert table only while
+ * the pass has none at all, since a ring canvas draws one region per pass and
+ * a lens with no opinion on the other regions must not swap the strip out and
+ * back on every frame.
+ */
+export class MarkTextureBinder {
+    hal;
+    bound = new Map();
+    constructor(hal) {
+        this.hal = hal;
+    }
+    bind(passId, sampler, texture) {
+        const key = `${passId}\u0000${sampler}`;
+        const bound = this.bound.get(key);
+        const next = texture ?? bound ?? INERT_RAMP;
+        if (next !== bound) {
+            if (next instanceof Uint8Array) {
+                uploadColorRampLut(this.hal, next, [passId], sampler);
+            }
+            else if ('image' in next) {
+                this.hal.uploadTexture(passId, next.image, next.width, next.height, sampler);
+            }
+            else {
+                this.hal.uploadTexture(passId, next.bytes, next.width, next.height, sampler);
+            }
+            this.bound.set(key, next);
+        }
+    }
+}
+/**
+ * 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 {
+    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;
+    textures;
+    blockMarks;
+    viewMarks;
+    constructor(hal, marks, clear) {
+        super(hal);
+        this.clear = clear;
+        this.regionPasses = ownedPasses(marks);
+        this.textures = new MarkTextureBinder(hal);
+        this.blockMarks = marks.filter(m => !m.spansView);
+        this.viewMarks = marks.filter(m => m.spansView);
+    }
+    clearColor(state) {
+        return this.clear ? this.clear(state) : super.clearColor(state);
+    }
+    drawWith(marks, block, clip, region, state) {
+        drawMarks(this.hal, this.uniformData, marks, block, clip, region, state, block.displayedRegionIndex, this.textures);
+    }
+    drawRegion(block, clip, region, state) {
+        this.drawWith(this.blockMarks, block, clip, region, state);
+    }
+    drawOverBlocks(regions, state, scale) {
+        if (this.viewMarks.length === 0 || regions.size === 0) {
+            return false;
+        }
+        const { canvasWidth, canvasHeight } = state;
+        for (const [key, region] of regions) {
+            const block = canvasWideBlock(key, canvasWidth);
+            const clip = clipBlock(block, canvasWidth, canvasHeight, scale);
+            if (clip) {
+                this.drawWith(this.viewMarks, block, clip, region, state);
+            }
+        }
+        return true;
+    }
+}
+/**
+ * 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 `drawPass`, the ordering the HAL's
+ * write-then-draw contract 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,32 @@
+import type { MarkHit, MarkShape } 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, so a caller that iterates back to front gets the mark on top.
+ * Five shapes used to spell that rule out separately.
+ *
+ * `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;
+/**
+ * The hit test a shape's `ink` implies: the nearest of its boxes, edges
+ * included, so a point inside one answers it at distance 0.
+ */
+export declare function inkHitNearest<C, P>(ink: NonNullable<MarkShape<C, P>['ink']>): NonNullable<MarkShape<C, P>['hitNearest']>;
+/** A shape's own `hitNearest`, else the one its `ink` implies, else none. */
+export declare function shapeHitNearest<C, P>(shape: MarkShape<C, P>): MarkShape<C, P>['hitNearest'];

package/esm/marks/markHit.js

@@ -0,0 +1,61 @@
+/**
+ * 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, so a caller that iterates back to front gets the mark on top.
+ * Five shapes used to spell that rule out separately.
+ *
+ * `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;
+}
+/**
+ * The hit test a shape's `ink` implies: the nearest of its boxes, edges
+ * included, so a point inside one answers it at distance 0.
+ */
+export function inkHitNearest(ink) {
+    return (channels, block, frame, params, xPx, yPx, candidates, maxDistSq) => nearestInk(candidates, maxDistSq, i => {
+        const r = ink(channels, block, frame, params, i);
+        return r && inkOnRect(xPx, yPx, r.left, r.top, r.width, r.height);
+    });
+}
+/** A shape's own `hitNearest`, else the one its `ink` implies, else none. */
+export function shapeHitNearest(shape) {
+    return (shape.hitNearest ??
+        (shape.ink ? inkHitNearest(shape.ink.bind(shape)) : undefined));
+}

package/esm/marks/markInk.d.ts

@@ -0,0 +1,18 @@
+import type { RenderBlock } from '../renderBlock.ts';
+import type { InkRect, Mark, MarkFrame } from './types.ts';
+/** `r` moved by (`dx`, `dy`), its stroke with it. */
+export declare function shiftInk<R extends InkRect>(r: R, dx: number, dy: number): R;
+/** One instance of one mark in a display's list, as a highlight names it. */
+export interface MarkInstance {
+    mark: number;
+    index: number;
+}
+/**
+ * The boxes a set of instances painted this frame: each mark's `ink` for the
+ * instances a display names in each region, clipped to the block's column the
+ * way the painter was, or to the canvas for a mark spanning the view, asked
+ * over `regionKeys` (the blocks' own by default). What a highlight guide
+ * draws, so a display says WHICH instances are lit and nothing about where
+ * they are.
+ */
+export declare function inkOfInstances<TRegion, TState extends MarkFrame>(marks: readonly Mark<TRegion, TState>[], blocks: readonly RenderBlock[], regionOf: (displayedRegionIndex: number) => TRegion | undefined, state: TState, instancesOf: (displayedRegionIndex: number) => Iterable<MarkInstance> | undefined, regionKeys?: Iterable<number>): InkRect[];

package/esm/marks/markInk.js

@@ -0,0 +1,71 @@
+import { canvasWideBlock } from '../renderBlock.js';
+/** `r` moved by (`dx`, `dy`), its stroke with it. */
+export function shiftInk(r, dx, dy) {
+    const { stroke } = r;
+    return {
+        ...r,
+        left: r.left + dx,
+        top: r.top + dy,
+        ...(stroke
+            ? {
+                stroke: {
+                    ...stroke,
+                    originX: stroke.originX + dx,
+                    originY: stroke.originY + dy,
+                },
+            }
+            : {}),
+    };
+}
+function clippedTo(r, x0, x1) {
+    const left = Math.max(r.left, x0);
+    const right = Math.min(r.left + r.width, x1);
+    return right >= left ? { ...r, left, width: right - left } : undefined;
+}
+/**
+ * The boxes a set of instances painted this frame: each mark's `ink` for the
+ * instances a display names in each region, clipped to the block's column the
+ * way the painter was, or to the canvas for a mark spanning the view, asked
+ * over `regionKeys` (the blocks' own by default). What a highlight guide
+ * draws, so a display says WHICH instances are lit and nothing about where
+ * they are.
+ */
+export function inkOfInstances(marks, blocks, regionOf, state, instancesOf, regionKeys) {
+    const rects = [];
+    for (const block of blocks) {
+        const region = regionOf(block.displayedRegionIndex);
+        const instances = region && instancesOf(block.displayedRegionIndex);
+        if (!instances) {
+            continue;
+        }
+        const x0 = Math.min(block.screenStartPx, block.screenEndPx);
+        const x1 = Math.max(block.screenStartPx, block.screenEndPx);
+        for (const { mark, index } of instances) {
+            const m = marks[mark];
+            const r = m && !m.spansView && m.ink?.(region, block, state, index);
+            const clipped = r && clippedTo(r, x0, x1);
+            if (clipped) {
+                rects.push(clipped);
+            }
+        }
+    }
+    if (marks.some(m => m.spansView)) {
+        for (const key of regionKeys ?? blocks.map(b => b.displayedRegionIndex)) {
+            const region = regionOf(key);
+            const instances = region && instancesOf(key);
+            if (!instances) {
+                continue;
+            }
+            const block = canvasWideBlock(key, state.canvasWidth);
+            for (const { mark, index } of instances) {
+                const m = marks[mark];
+                const r = m?.spansView && m.ink?.(region, block, state, index);
+                const clipped = r && clippedTo(r, 0, state.canvasWidth);
+                if (clipped) {
+                    rects.push(clipped);
+                }
+            }
+        }
+    }
+    return rects;
+}

package/esm/marks/markPaint.d.ts

@@ -0,0 +1,14 @@
+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. A mark that spans the view paints
+ * after the blocks, over the whole canvas, from every region in `regions`.
+ *
+ * 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,32 @@
+import { forEachClippedBlock, withClip } from '../canvas2dUtils.js';
+import { canvasWideBlock } from '../renderBlock.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. A mark that spans the view paints
+ * after the blocks, over the whole canvas, from every region in `regions`.
+ *
+ * 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) {
+    const blockMarks = marks.filter(m => !m.spansView);
+    forEachClippedBlock(ctx, blocks, state.canvasWidth, state.canvasHeight, block => regions.get(block.displayedRegionIndex), (region, block) => {
+        for (const mark of blockMarks) {
+            mark.paintBlock(ctx, region, block, state);
+        }
+    });
+    const viewMarks = marks.filter(m => m.spansView);
+    if (viewMarks.length > 0) {
+        withClip(ctx, 0, 0, state.canvasWidth, state.canvasHeight, () => {
+            for (const [key, region] of regions) {
+                const block = canvasWideBlock(key, state.canvasWidth);
+                for (const mark of viewMarks) {
+                    mark.paintBlock(ctx, region, block, state);
+                }
+            }
+        });
+    }
+}

package/esm/marks/markPlan.d.ts

@@ -0,0 +1,25 @@
+import type { Mark, MarkFrame, PlannedPass } from './types.ts';
+/**
+ * A mark list resolved against one frame's state: the marks whose `enabled`
+ * said yes, in list order, and the passes they draw.
+ *
+ * `drawMarks` asks every mark's gate, lens and staged compare per block, which
+ * is the right shape for a display that stages its uniforms through the marks
+ * — and at 120 section blocks a frame it is the whole cost the pileup measured
+ * and declined (`benches/pileupUniformWrite.bench.ts` has the table). A
+ * display that writes the uniforms itself, once per section, has nothing left
+ * for the per-block walk to decide: `planMarks` answers the frame question
+ * once, `drawPlannedPasses` issues a `drawPass` per planned mark against
+ * whatever the caller staged, and `marks` is the painter's list.
+ */
+export interface MarkPlan<TRegion, TState extends MarkFrame> {
+    readonly marks: readonly Mark<TRegion, TState>[];
+    readonly passes: readonly PlannedPass[];
+}
+/**
+ * Resolve which marks draw this frame. Throws for an enabled mark the plan
+ * form cannot carry — one with a `band` or a `paintsBlock` — since a plan
+ * neither scissors nor asks the block anything, and without the throw the GPU
+ * would draw what Canvas2D declines.
+ */
+export declare function planMarks<TRegion, TState extends MarkFrame>(marks: readonly Mark<TRegion, TState>[], state: TState): MarkPlan<TRegion, TState>;

package/esm/marks/markPlan.js

@@ -0,0 +1,20 @@
+/**
+ * Resolve which marks draw this frame. Throws for an enabled mark the plan
+ * form cannot carry — one with a `band` or a `paintsBlock` — since a plan
+ * neither scissors nor asks the block anything, and without the throw the GPU
+ * would draw what Canvas2D declines.
+ */
+export function planMarks(marks, state) {
+    const enabled = [];
+    const passes = [];
+    for (const mark of marks) {
+        if (!mark.enabled || mark.enabled(state)) {
+            if (!mark.planned) {
+                throw new Error(`mark ${mark.pass.id} declares a band or a block gate, which a frame plan does not carry; draw it through drawMarks`);
+            }
+            enabled.push(mark);
+            passes.push(mark.planned);
+        }
+    }
+    return { marks: enabled, passes };
+}

package/esm/marks/markRamp.d.ts

@@ -0,0 +1,72 @@
+import type { MarkColorScale, MarkThreshold } from './types.ts';
+/**
+ * A colour channel as a shape reads it: `color`, the packed ABGR the worker
+ * resolved — one per instance, or one number for all of them — or
+ * `colorValue`, the raw values a frame's {@link MarkColorScale} turns into
+ * colours here. A shape reading a scale declares both optional and asks
+ * {@link colorBits} for the GPU and {@link paintColors} for Canvas2D.
+ */
+export interface ColorChannel {
+    color?: Uint32Array | number;
+    colorValue?: Float32Array;
+    /** The Canvas2D bake, memoized on the payload; nothing else writes it. */
+    rampBake?: RampBake;
+    /** A constant `color` as Canvas2D paints it, memoized as `rampBake` is. */
+    constantBake?: Uint32Array;
+}
+interface RampBake {
+    values: Float32Array;
+    scale: MarkColorScale;
+    colors: Uint32Array;
+}
+/** Whether a colour scale is a threshold rather than a ramp. */
+export declare function isThreshold(scale: MarkColorScale): scale is MarkThreshold;
+type Rgba = [number, number, number, number];
+type Bands = [Rgba, Rgba, Rgba, Rgba, Rgba, Rgba, Rgba, Rgba, Rgba];
+/**
+ * `markColor.slang`'s uniforms for a frame's colour scale, or for none: the
+ * mode, a ramp's domain and middle, and a threshold's cuts and band colours.
+ * Every valued shape's uniform block carries the set.
+ */
+export declare function rampUniforms(scale: MarkColorScale | undefined): {
+    rampMode: number;
+    rampMin: number;
+    rampMax: number;
+    rampMidNorm: number;
+    colorCutCount: number;
+    colorCuts: [Rgba, Rgba];
+    colorBands: Bands;
+};
+/**
+ * The 4-byte instance lane, for the packer. Under a scale it is the value's
+ * float32 bits viewed as the `uint` the attribute declares — the reinterpret
+ * `markColor.slang`'s `asfloat` undoes, and the reason a quantitative colour
+ * adds no lane. A constant colour fills a lane for the pack alone, which the
+ * payload never holds.
+ */
+export declare function colorBits(c: ColorChannel, count: number): ArrayLike<number>;
+/** Instance `i`'s `color` alone, as a one-instance channel carries it. */
+export declare function instanceColor(color: ColorChannel['color'], i: number): number | Uint32Array<ArrayBufferLike> | undefined;
+/** A value lane's float32 values viewed as their bits. */
+export declare function rampValueBits(values: Float32Array): Uint32Array<ArrayBufferLike>;
+/**
+ * A value lane's values kept where `keep` says, copied as bits: a JS number
+ * read out of the lane may lose the payload `RAMP_NO_VALUE_BITS` marks a
+ * feature with no value by.
+ */
+export declare function keepRampValues(values: Float32Array, keep: (value: number, index: number) => boolean): Float32Array<ArrayBuffer>;
+/**
+ * The interval a value is in on a threshold: how many of the ascending cuts it
+ * is at or past, `thresholdIndex`'s rule and the shader's `thresholdBand`.
+ */
+export declare function thresholdBandOf(value: number, cuts: readonly number[]): number;
+/**
+ * The packed colours a painter fills with. Under a scale the values are baked
+ * against it once and kept on the payload, so a repaint at an unchanged scale
+ * — every pan and every hover — walks no values and the painters' fill
+ * batching still sees runs of one colour. The bake reruns when the domain, the
+ * scale type, the ramp's bytes or a threshold's cuts or colours move. A
+ * constant colour expands once and is kept the same way.
+ */
+export declare function paintColors(c: ColorChannel, count: number, scale: MarkColorScale | undefined): ArrayLike<number>;
+export {};