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

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 dropping the gate silently
+ * would draw on the GPU 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 dropping the gate silently
+ * would draw on the GPU 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,43 @@
+import type { MarkRamp, MarkValueScaleType } from './types.ts';
+/**
+ * A colour channel as a shape reads it: `color`, the packed ABGR the worker
+ * resolved, or `colorValue`, the raw values a frame's {@link MarkRamp} turns
+ * into colours here. A shape reading a ramp declares both optional and asks
+ * {@link colorBits} for the GPU and {@link paintColors} for Canvas2D.
+ */
+export interface ColorChannel {
+    color?: Uint32Array;
+    colorValue?: Float32Array;
+    /** The Canvas2D bake, memoized on the payload; nothing else writes it. */
+    rampBake?: RampBake;
+}
+interface RampBake {
+    min: number;
+    max: number;
+    log: boolean;
+    lut: Uint8Array;
+    colors: Uint32Array;
+}
+/** `scoreScale`'s scale-type code for a declared value scale. */
+export declare function valueScaleTypeCode(scale: MarkValueScaleType | undefined): 0 | 1;
+/** `markColor.slang`'s three uniforms for a frame's ramp, or for none. */
+export declare function rampUniforms(ramp: MarkRamp | undefined): {
+    rampMode: number;
+    rampMin: number;
+    rampMax: number;
+};
+/**
+ * The 4-byte instance lane, for the packer. Under a ramp 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 ramp adds no lane.
+ */
+export declare function colorBits(c: ColorChannel): ArrayLike<number>;
+/**
+ * The packed colours a painter fills with. Under a ramp the values are baked
+ * against the domain once and kept on the payload, so a repaint at an
+ * unchanged domain — 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 or the ramp's bytes move.
+ */
+export declare function paintColors(c: ColorChannel, count: number, ramp: MarkRamp | undefined): ArrayLike<number>;
+export {};

package/esm/marks/markRamp.js

@@ -0,0 +1,68 @@
+import { RAMP_LINEAR, RAMP_LOG, RAMP_NONE, } from '../shaders/markColor.generated.js';
+import { SCALE_TYPE_LOG } from '../shaders/scoreScale.generated.js';
+import { normalizeScore } from '../shaders/scoreScale.js.generated.js';
+const NO_COLORS = new Uint32Array(0);
+/** `scoreScale`'s scale-type code for a declared value scale. */
+export function valueScaleTypeCode(scale) {
+    return scale === 'log' ? SCALE_TYPE_LOG : 0;
+}
+/** `markColor.slang`'s three uniforms for a frame's ramp, or for none. */
+export function rampUniforms(ramp) {
+    return ramp
+        ? {
+            rampMode: ramp.scale === 'log' ? RAMP_LOG : RAMP_LINEAR,
+            rampMin: ramp.domain[0],
+            rampMax: ramp.domain[1],
+        }
+        : { rampMode: RAMP_NONE, rampMin: 0, rampMax: 1 };
+}
+/**
+ * The 4-byte instance lane, for the packer. Under a ramp 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 ramp adds no lane.
+ */
+export function colorBits(c) {
+    const { colorValue } = c;
+    return colorValue
+        ? new Uint32Array(colorValue.buffer, colorValue.byteOffset, colorValue.length)
+        : (c.color ?? NO_COLORS);
+}
+/**
+ * The packed colours a painter fills with. Under a ramp the values are baked
+ * against the domain once and kept on the payload, so a repaint at an
+ * unchanged domain — 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 or the ramp's bytes move.
+ */
+export function paintColors(c, count, ramp) {
+    const { colorValue } = c;
+    if (!ramp || !colorValue) {
+        return c.color ?? NO_COLORS;
+    }
+    const [min, max] = ramp.domain;
+    const log = ramp.scale === 'log';
+    const { lut } = ramp;
+    const bake = c.rampBake;
+    if (bake &&
+        bake.min === min &&
+        bake.max === max &&
+        bake.log === log &&
+        bake.lut === lut &&
+        bake.colors.length >= count) {
+        return bake.colors;
+    }
+    const entries = lut.length / 4;
+    const colors = new Uint32Array(count);
+    for (let i = 0; i < count; i++) {
+        const t = normalizeScore(colorValue[i], min, max, log ? SCALE_TYPE_LOG : 0, 1);
+        const o = Math.round(t * (entries - 1)) * 4;
+        colors[i] =
+            ((lut[o + 3] << 24) |
+                (lut[o + 2] << 16) |
+                (lut[o + 1] << 8) |
+                lut[o]) >>>
+                0;
+    }
+    c.rampBake = { min, max, log, lut, colors };
+    return colors;
+}

package/esm/marks/pointMark.d.ts

@@ -1,4 +1,5 @@
-import type { MarkShape } from './types.ts';
+import type { ColorChannel } from './markRamp.ts';
+import type { MarkRamp, MarkShape, MarkValueScaleType } 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.
@@ -7,17 +8,20 @@ import type { MarkShape } from './types.ts';
  * 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 {
+export interface PointChannels extends ColorChannel {
     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. */
+    /** `[min, max]` `y` is read through. */
     domain: [number, number];
+    /** How that domain is read; linear when absent. */
+    scaleType?: MarkValueScaleType;
+    /** The quantitative colour scale, for a point whose colour is a ramp. */
+    ramp?: MarkRamp;
     /** Glyph diameter in CSS px. */
     diameterPx: number;
 }

package/esm/marks/pointMark.js

@@ -1,16 +1,18 @@
 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 { pointDrawsBar, valueToYPxScaled, } from '../shaders/pointMark.js.generated.js';
 import { slangPass } from '../slangPass.js';
 import { abgrToCssRgba } from './colorFill.js';
-import { appendGlyph } from './glyphPaint.js';
+import { appendGlyph, glyphBox } from './glyphPaint.js';
 import { inkAtPoint, inkOnRect, nearestInk } from './markHit.js';
+import { colorBits, paintColors, rampUniforms, valueScaleTypeCode, } from './markRamp.js';
+import { blockPx } from './spanMark.js';
 export const pointMark = {
     id: 'point',
     pass: {
         ...slangPass({ id: 'point', mod: shader }),
-        pack: c => shader.packInstances(c, c.count),
+        pack: c => shader.packInstances({ ...c, color: colorBits(c) }, c.count),
     },
     writeUniforms(scratch, clip, block, frame, params) {
         shader.writeUniforms(scratch, {
@@ -18,6 +20,8 @@ export const pointMark = {
             canvasHeight: frame.canvasHeight,
             domainMin: params.domain[0],
             domainMax: params.domain[1],
+            valueScaleType: valueScaleTypeCode(params.scaleType),
+            ...rampUniforms(params.ramp),
             zero: 0,
             // viewportWidth and radiusPx stay in CSS units to match canvasHeight:
             // mixing a DPR-scaled radius with a CSS-scaled height draws vertically
@@ -28,15 +32,17 @@ export const pointMark = {
         });
     },
     paintBlock(ctx, channels, block, frame, params) {
-        const { x, x2, y, color, glyph, count } = channels;
+        const { x, x2, y, glyph, count } = channels;
         if (count === 0) {
             return;
         }
+        const color = paintColors(channels, count, params.ramp);
         const { diameterPx, domain } = params;
         const r = diameterPx / 2;
         const canvasHeight = frame.canvasHeight;
         const domainMin = domain[0];
         const domainMax = domain[1];
+        const st = valueScaleTypeCode(params.scaleType);
         // 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.
@@ -56,7 +62,7 @@ export const pointMark = {
             }
             const xStart = bpToPx(x[i]);
             const xEnd = bpToPx(x2[i]);
-            const yPx = valueToYPx(y[i], domainMin, domainMax, canvasHeight);
+            const yPx = valueToYPxScaled(y[i], domainMin, domainMax, canvasHeight, st);
             const widthPx = Math.abs(xEnd - xStart);
             if (pointDrawsBar(widthPx, r)) {
                 ctx.rect(Math.min(xStart, xEnd), yPx - r, widthPx, diameterPx);
@@ -67,6 +73,25 @@ export const pointMark = {
         }
         ctx.fill();
     },
+    // A bar is the rect the painter fills, unpadded on every side; a glyph is
+    // the box `appendGlyph` paints inside.
+    ink(channels, block, frame, params, i) {
+        const { x, x2, y, glyph } = channels;
+        const { diameterPx, domain } = params;
+        const xStart = blockPx(block, x[i]);
+        const xEnd = blockPx(block, x2[i]);
+        const cy = valueToYPxScaled(y[i], domain[0], domain[1], frame.canvasHeight, valueScaleTypeCode(params.scaleType));
+        const lo = Math.min(xStart, xEnd);
+        const hi = Math.max(xStart, xEnd);
+        const r = diameterPx / 2;
+        return pointDrawsBar(hi - lo, r)
+            ? { left: lo, top: cy - r, width: hi - lo, height: diameterPx }
+            : glyphBox(glyph[i], xStart, cy, diameterPx);
+    },
+    // Its own rather than the one `ink` implies, for the glyph: a dense plot
+    // stacks glyphs whose boxes all contain the cursor at distance 0, and the
+    // one under the cursor is the nearest CENTRE, which no box can say. A bar
+    // is grabbed anywhere inside the rect it fills, as the derived test would.
     hitNearest(channels, block, frame, params, xPx, yPx, candidates, maxDistSq) {
         const { x, x2, y } = channels;
         const bpToPx = makeBpMapper(block);
@@ -74,13 +99,11 @@ export const pointMark = {
         const domainMin = domain[0];
         const domainMax = domain[1];
         const canvasHeight = frame.canvasHeight;
+        const st = valueScaleTypeCode(params.scaleType);
         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 cy = valueToYPxScaled(y[i], domainMin, domainMax, canvasHeight, st);
             const lo = Math.min(xStart, xEnd);
             const hi = Math.max(xStart, xEnd);
             return pointDrawsBar(hi - lo, diameterPx / 2)

package/esm/marks/spanMark.d.ts

@@ -1,3 +1,4 @@
+import type { RenderBlock } from '../renderBlock.ts';
 import type { MarkShape } from './types.ts';
 /**
  * The `span` shape's channels: a coloured rectangle from `x` to `x2` on the
@@ -7,6 +8,12 @@ export interface SpanChannels {
     x: Uint32Array;
     x2: Uint32Array;
     row: Uint32Array;
+    /**
+     * Packed ABGR, resolved in the worker — a span's colour has no ramp arm.
+     * `rowRect`'s uniform struct is shared with four other consumers, and a
+     * sampler on it would move all of them for a channel no config asks for
+     * on a span (ADR-113).
+     */
     color: Uint32Array;
     count: number;
 }
@@ -42,4 +49,5 @@ export interface SpanParams {
     /** Rows-area scroll offset in CSS px; 0 for a canvas sized to its content. */
     scrollTop: number;
 }
+export declare function blockPx(block: RenderBlock, bp: number): number;
 export declare const spanMark: MarkShape<SpanChannels, SpanParams>;

package/esm/marks/spanMark.js

@@ -1,10 +1,15 @@
 import { bpRangeXTuple } from '../blockClipUtils.js';
-import { makeBpMapper, spanLeft } from '../canvas2dUtils.js';
+import { bpToScreenPx, makeBpMapper, spanLeft } from '../canvas2dUtils.js';
 import { drawnRowHeightPx, rowBandOffsetPx, } from '../shaders/rowRect.js.generated.js';
 import * as shader from '../shaders/spanMark.generated.js';
 import { slangPass } from '../slangPass.js';
 import { makeAbgrFill } from './colorFill.js';
-import { inkOnRect, nearestInk } from './markHit.js';
+// Per instance rather than through `makeBpMapper`: `ink` is asked one
+// instance at a time, and a closure per ask is the allocation the mapper
+// exists to hoist out of a loop.
+export function blockPx(block, bp) {
+    return bpToScreenPx(bp, block.start, block.end, block.screenStartPx, block.screenEndPx, block.reversed);
+}
 export const spanMark = {
     id: 'span',
     pass: {
@@ -41,19 +46,19 @@ export const spanMark = {
             ctx.fillRect(spanLeft(xa, xb, width), offset + rowHeight * row[i] - scrollTop, width + seamPx, h);
         }
     },
-    hitNearest(channels, block, _frame, params, xPx, yPx, candidates, maxDistSq) {
+    ink(channels, block, _frame, params, i) {
         const { x, x2, row } = channels;
         const { rowHeight, rowProportion, minWidthPx, scrollTop } = params;
-        const h = drawnRowHeightPx(rowHeight, rowProportion);
-        const offset = rowBandOffsetPx(rowHeight, rowProportion);
-        const bpToPx = makeBpMapper(block);
-        return nearestInk(candidates, maxDistSq, i => {
-            const xa = bpToPx(x[i]);
-            const xb = bpToPx(x2[i]);
-            const width = Math.max(minWidthPx, Math.abs(xb - xa));
-            // the rect `paintBlock` fills, less `seamPx`, which is painter-only
-            // overdraw
-            return inkOnRect(xPx, yPx, spanLeft(xa, xb, width), offset + rowHeight * row[i] - scrollTop, width, h);
-        });
+        const xa = blockPx(block, x[i]);
+        const xb = blockPx(block, x2[i]);
+        const width = Math.max(minWidthPx, Math.abs(xb - xa));
+        return {
+            left: spanLeft(xa, xb, width),
+            top: rowBandOffsetPx(rowHeight, rowProportion) +
+                rowHeight * row[i] -
+                scrollTop,
+            width,
+            height: drawnRowHeightPx(rowHeight, rowProportion),
+        };
     },
 };

package/esm/marks/types.d.ts

@@ -31,8 +31,35 @@ export interface MarkContext2D extends ClipContext2D {
     closePath(): void;
     fill(): void;
     stroke(): void;
+    drawImage?(image: CanvasImageSource, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
 }
+/**
+ * A canvas a mark's pass samples in place of a colour ramp, with the size the
+ * texture is allocated at. A fresh object per repaint of the canvas: the
+ * backend uploads on identity, and a canvas element's identity never moves.
+ */
+export interface MarkImage {
+    image: HTMLCanvasElement | OffscreenCanvas;
+    width: number;
+    height: number;
+}
+/** What a mark's pass binds: a 256-entry RGBA ramp, or a canvas. */
+export type MarkTexture = Uint8Array | MarkImage;
 export type MarkFrame = FrameDimensions;
+/** How a declared value scale reads its domain. */
+export type MarkValueScaleType = 'linear' | 'log';
+/**
+ * The quantitative colour scale a frame paints a ramp channel through: the
+ * domain, unioned over the loaded regions by the display; the declared scale
+ * type; and the 256-entry RGBA LUT the pass's sampler binds. A shape that
+ * reads it takes the raw values in `colorValue` and resolves them per frame,
+ * so a pan that widens the domain uploads no instance bytes.
+ */
+export interface MarkRamp {
+    domain: [number, number];
+    scale: MarkValueScaleType;
+    lut: Uint8Array;
+}
 /** A horizontal strip of the canvas, in CSS px down from its top edge. */
 export interface MarkBand {
     top: number;
@@ -45,6 +72,13 @@ export interface MarkHit {
     y: number;
     distSq: number;
 }
+/** An axis-aligned box of the canvas, in CSS px. */
+export interface InkRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
 /**
  * A shape: one hand-written `.slang`, one packer, one Canvas2D painter and one
  * hit test, all reading the same channel arrays.
@@ -82,6 +116,19 @@ export interface MarkShape<TChannels, TParams> {
      * and its triangles turn off together.
      */
     paintsBlock?(block: RenderBlock, frame: MarkFrame, params: TParams): boolean;
+    /**
+     * The rect `paintBlock` fills for instance `i`, or undefined for an instance
+     * it skips — a row the viewport has scrolled past, a bar with no height. A
+     * shape whose every instance is one box declares this and nothing about
+     * hovering: `defineMark` derives `hitNearest` from it where none is
+     * declared, and a display's highlight guide reads it for the instances it
+     * names. A shape whose ink is not a box (a ribbon, an arc, a capsule) leaves
+     * it off and keeps its own hit test.
+     *
+     * Painter-only overdraw — `span`'s seam — is not ink; `drawAgainstHit.ts`
+     * holds the two to each other within a pixel.
+     */
+    ink?(channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams, i: number): InkRect | undefined;
     /**
      * The nearest drawn ink to `(xPx, yPx)` among `candidates`, or undefined if
      * nothing beats `maxDistSq`.
@@ -100,7 +147,8 @@ export interface MarkShape<TChannels, TParams> {
      *
      * Optional, because a shape earns it from a consumer like any other member.
      * MAF answers a hit from row/column arithmetic over the alignment rather than
-     * from `span`'s channels, so it reads none.
+     * from `span`'s channels, so it reads none. A shape with `ink` and no hit test
+     * gets `inkHitNearest` — the nearest of its boxes — through `shapeHitNearest`.
      */
     hitNearest?(channels: TChannels, block: RenderBlock, frame: MarkFrame, params: TParams, xPx: number, yPx: number, candidates: Iterable<number>, maxDistSq: number): MarkHit | undefined;
 }
@@ -126,6 +174,15 @@ export interface StagedUniforms {
     writer: unknown;
     params: unknown;
 }
+/**
+ * A mark's pass as a frame plan draws it: what `hal.drawPass(id, regionKey,
+ * bufferOf)` takes and nothing else, resolved once per frame so the per-block
+ * loop reads two fields per mark.
+ */
+export interface PlannedPass {
+    readonly id: string;
+    readonly bufferOf: string | undefined;
+}
 /**
  * A shape bound to one display's region payload and render state — what
  * `defineMark` returns and what a display actually holds.
@@ -150,10 +207,33 @@ export interface Mark<TRegion, TState extends MarkFrame> {
      * undefined case — a shader owns its sampler unconditionally, and a textured
      * pass with no texture never draws on the WebGPU HAL.
      */
-    readonly texture?: (state: TState, region: TRegion) => Uint8Array | undefined;
+    readonly texture?: (state: TState, region: TRegion) => MarkTexture | undefined;
+    /**
+     * The frame-level gate: whether the mark draws at all under `state`, read
+     * off the display-wide state and nothing else. `planMarks` asks it once per
+     * frame; `drawRegion`, `paintBlock` and `hitNearest` ask it per block, so a
+     * list drawn through `drawMarks` gates like one drawn through a plan — and
+     * so does the hit test, which is what stops a switched-off layer answering a
+     * hover over blank pixels. A question about the block is `paintsBlock`, on
+     * the shape.
+     */
+    readonly enabled?: (state: TState) => boolean;
+    /**
+     * The pass a frame plan draws for this mark, or undefined for a mark the plan
+     * form cannot carry: one with a `band` (a plan's caller owns the scissor) or a
+     * `paintsBlock` (a plan asks the block nothing).
+     */
+    readonly planned?: PlannedPass;
     drawRegion(hal: GpuHal, scratch: ArrayBuffer, block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState, regionKey: number, staged?: StagedUniforms): void;
     paintBlock(ctx: MarkContext2D, region: TRegion, block: RenderBlock, state: TState): void;
     hitNearest?(region: TRegion, block: RenderBlock, state: TState, xPx: number, yPx: number, candidates: Iterable<number>, maxDistSq: number): MarkHit | undefined;
+    /**
+     * The box instance `i` painted under the mark's gates, clipped to its band
+     * where it has one: what a highlight guide draws for the instance a display
+     * names. Undefined off a shape with no `ink`, and for an instance nothing
+     * drew.
+     */
+    ink?(region: TRegion, block: RenderBlock, state: TState, i: number): InkRect | undefined;
 }
 /**
  * `{ shape, channels }` over typed arrays — the declaration a display writes in
@@ -205,6 +285,12 @@ export interface Mark<TRegion, TState extends MarkFrame> {
  * nothing, and the shape still places Y against the whole canvas — the band is
  * a clip, never an offset, which is what lets one `scrollTop` serve both
  * backends. A mark without one paints wherever its shape puts ink.
+ *
+ * `enabled` is the setting that turns the mark off for a whole frame — the
+ * pileup's "show mismatches" — and it is one gate for the three consumers: a
+ * mark that does not draw does not answer a hover either. It reads the state
+ * alone so `planMarks` can resolve it once per frame; a gate that needs the
+ * block is the shape's `paintsBlock`.
  */
 export declare function defineMark<TRegion, TState extends MarkFrame, TChannels, TParams>(spec: {
     shape: MarkShape<TChannels, TParams>;
@@ -212,5 +298,6 @@ export declare function defineMark<TRegion, TState extends MarkFrame, TChannels,
     params: (state: TState, region: TRegion, block: RenderBlock) => TParams;
     bufferOf?: Mark<TRegion, TState>;
     band?: (state: TState) => MarkBand;
-    texture?: (state: TState, region: TRegion) => Uint8Array | undefined;
+    texture?: (state: TState, region: TRegion) => MarkTexture | undefined;
+    enabled?: (state: TState) => boolean;
 }): Mark<TRegion, TState>;

package/esm/marks/types.js

@@ -1,4 +1,5 @@
 import { devicePxBand, withClip } from '../canvas2dUtils.js';
+import { shapeHitNearest } from './markHit.js';
 /**
  * `{ shape, channels }` over typed arrays — the declaration a display writes in
  * place of a `GpuXxxRenderer` class, a `Canvas2DXxxRenderer` class, a factory
@@ -49,9 +50,17 @@ import { devicePxBand, withClip } from '../canvas2dUtils.js';
  * nothing, and the shape still places Y against the whole canvas — the band is
  * a clip, never an offset, which is what lets one `scrollTop` serve both
  * backends. A mark without one paints wherever its shape puts ink.
+ *
+ * `enabled` is the setting that turns the mark off for a whole frame — the
+ * pileup's "show mismatches" — and it is one gate for the three consumers: a
+ * mark that does not draw does not answer a hover either. It reads the state
+ * alone so `planMarks` can resolve it once per frame; a gate that needs the
+ * block is the shape's `paintsBlock`.
  */
 export function defineMark(spec) {
-    const { shape, channels, params, band, texture } = spec;
+    const { shape, channels, params, band, texture, enabled } = spec;
+    const hitNearest = shapeHitNearest(shape);
+    const shapeInk = shape.ink?.bind(shape);
     const lender = spec.bufferOf?.pass;
     if (lender &&
         (lender.instanceStride !== shape.pass.instanceStride ||
@@ -60,6 +69,7 @@ export function defineMark(spec) {
         throw new Error(`mark ${shape.id} draws off ${lender.id}'s buffer but declares a different instance struct`);
     }
     const bufferOf = lender?.id;
+    const planned = band || shape.paintsBlock ? undefined : { id: shape.pass.id, bufferOf };
     return {
         pass: {
             ...shape.pass,
@@ -70,7 +80,12 @@ export function defineMark(spec) {
         },
         bufferOf,
         texture,
+        enabled,
+        planned,
         drawRegion(hal, scratch, block, clip, region, state, regionKey, staged) {
+            if (enabled && !enabled(state)) {
+                return;
+            }
             const strip = band?.(state);
             const scissor = strip
                 ? devicePxBand(strip.top, strip.height, clip.scaleY, clip.pxH)
@@ -98,6 +113,9 @@ export function defineMark(spec) {
             }
         },
         paintBlock(ctx, region, block, state) {
+            if (enabled && !enabled(state)) {
+                return;
+            }
             const strip = band?.(state);
             const c = channels(region);
             if ((!strip || strip.height > 0) && c !== undefined) {
@@ -115,7 +133,7 @@ export function defineMark(spec) {
                 }
             }
         },
-        hitNearest: shape.hitNearest
+        hitNearest: hitNearest
             ? (region, block, state, xPx, yPx, candidates, maxDistSq) => {
                 const strip = band?.(state);
                 const c = channels(region);
@@ -125,19 +143,53 @@ export function defineMark(spec) {
                 // either. The cursor being inside the strip is a fourth, and the ink
                 // being inside it the fifth: a band is a CLIP, so ink outside one was
                 // never drawn and cannot be the nearest thing to anything.
-                if ((!strip || strip.height > 0) &&
+                //
+                // The fifth gate REJECTS rather than re-runs, and that is the one
+                // conservative edge here: the shape picks its winner without knowing
+                // about the band, so a clipped-away nearest masks a farther candidate
+                // whose ink IS inside the strip, and the mark answers nothing instead
+                // of that one. Safe in the direction that matters — it never claims a
+                // hover over pixels neither backend drew — and closing it would mean
+                // pushing the band down into every shape's own ink test, where the
+                // band is deliberately not.
+                if ((!enabled || enabled(state)) &&
+                    (!strip || strip.height > 0) &&
                     c !== undefined &&
                     !bandExcludes(strip, yPx)) {
                     const p = params(state, region, block);
                     if (!shape.paintsBlock || shape.paintsBlock(block, state, p)) {
-                        hit = shape.hitNearest(c, block, state, p, xPx, yPx, candidates, maxDistSq);
+                        hit = hitNearest(c, block, state, p, xPx, yPx, candidates, maxDistSq);
                     }
                 }
                 return hit && !bandExcludes(strip, hit.y) ? hit : undefined;
             }
             : undefined,
+        ink: shapeInk
+            ? (region, block, state, i) => {
+                const strip = band?.(state);
+                const c = channels(region);
+                if ((enabled && !enabled(state)) ||
+                    (strip && strip.height <= 0) ||
+                    c === undefined) {
+                    return undefined;
+                }
+                const p = params(state, region, block);
+                if (shape.paintsBlock && !shape.paintsBlock(block, state, p)) {
+                    return undefined;
+                }
+                const r = shapeInk(c, block, state, p, i);
+                return r && strip ? clipToBand(r, strip) : r;
+            }
+            : undefined,
     };
 }
+function clipToBand(r, strip) {
+    const top = Math.max(r.top, strip.top);
+    const bottom = Math.min(r.top + r.height, strip.top + strip.height);
+    return bottom > top
+        ? { left: r.left, top, width: r.width, height: bottom - top }
+        : undefined;
+}
 // What a mark with nothing in this region packs. An empty pack IS the release
 // — every HAL deletes the pass's prior buffer before it looks at the count.
 const NOTHING = new ArrayBuffer(0);