@jbrowse/render-core 5.0.0-beta.7 → 5.0.0-beta.9

package/esm/hal/webgpuHal.js

@@ -3,8 +3,8 @@ import { syncCanvasSize } from '../canvas2dUtils.js';
 import { canvasConfiguredBy, canvasContextError, noteCanvasConfigured, noteCanvasContext, } from '../canvasContext.js';
 import { createGpuSurfaceLostError } from '../gpuContextLostError.js';
 import { getGpuDevice } from '../gpuDevice.js';
-import { STANDARD_BLEND_STATE, createUniformOnlyBindGroup, createVertexBuffer, toGpuVertexFormat, } from '../webgpuUtils.js';
-import { getDeviceLayouts, getOrBuildPipeline } from './deviceGpuCache.js';
+import { createVertexBuffer } from '../webgpuUtils.js';
+import { bindGroupLayoutEntries, getOrBuildPipeline, getPassLayout, pipelineRecipe, } from './deviceGpuCache.js';
 import { GpuHalBase } from './gpuHalBase.js';
 class ShaderCompileError extends Error {
     constructor(passId, details) {
@@ -13,22 +13,16 @@ class ShaderCompileError extends Error {
     }
 }
 // Maximum number of writeUniforms() calls per frame. Each call occupies one
-// aligned slot in the uniform ring buffer.
-//
-// The ring is allocated eagerly at this many slots, as a GPU buffer AND a CPU
-// staging array, whether a renderer writes 4 slots or 1900 — so the cost is per
-// display, and both terms are in it. A display whose uniform fits the 256-byte
-// minimum alignment pays 512 KB each side; alignments' 640-byte uniform aligns
-// to 768, so 1.5 MiB each side, per track. A frame is measured using 2-4 of
-// those slots, which is what makes the count above the oversized term rather
-// than any struct:
-// agent-docs/ideas/size-the-uniform-ring-to-its-measured-occupancy.md.
+// aligned slot in the uniform ring, allocated eagerly per display as a GPU
+// buffer and a CPU staging array. A frame is measured using 2-4 slots, so the
+// count rather than any struct is the oversized term:
+// agent-docs/reference/ARCHITECTURAL_LIMITS.md §"The uniform ring is allocated
+// at 2048 slots".
 //
 // Exhausting it does not throw: the write is dropped and its draws render
-// against the previous batch's uniforms, which is wrong data rather than stale
-// data. If we ever hit the cap, switch to a dynamic-growth buffer (recreate
-// buffer + every region's bind group) rather than just bumping the constant
-// again.
+// against another batch's uniforms. If we ever hit the cap, grow the buffer and
+// recreate every bind group in `passBindGroups` rather than bumping the
+// constant again.
 const MAX_UNIFORM_SLOTS = 2048;
 // Warn while there is still headroom, because the cap itself is not a place to
 // find out. A renderer's per-frame write count is rarely one number: alignments
@@ -38,58 +32,22 @@ const MAX_UNIFORM_SLOTS = 2048;
 // the "~50 writes/frame" this file used to claim, and nothing reported the
 // difference between 50 and 1900.
 const UNIFORM_SLOT_WARN_AT = MAX_UNIFORM_SLOTS / 2;
-function gpuBlendState(bs) {
-    // Max ignores its factors, but WebGPU still validates them and rejects
-    // anything but 'one' on both channels ("Destination blend factor ... is
-    // defined and not BlendFactor::One when blend operation is
-    // BlendOperation::Max"). Same blend as webgl2Hal's bare glBlendEquation(MAX).
-    const max = { srcFactor: 'one', dstFactor: 'one', operation: 'max' };
-    // Otherwise RGB uses the caller-supplied factors and alpha always accumulates
-    // through ONE / ONE_MINUS_SRC_ALPHA (matches webgl2Hal.applyBlendState).
-    return bs.op === 'max'
-        ? { color: max, alpha: max }
-        : {
-            color: { srcFactor: bs.srcFactor, dstFactor: bs.dstFactor },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
-        };
-}
-// Every pass reads per-instance data from a vertex buffer (no storage binding
-// at 0) because Slang-generated shaders cross-compile to GLSL ES, which has no
-// SSBOs. The two @group(0) layouts a pass is built against — uniform-only, and
-// uniform + texture + sampler — belong to the device, not to this HAL, and live
-// in `deviceGpuCache.ts` with the pipelines.
-async function buildPipeline(device, desc, layouts, sampleCount) {
-    const module = device.createShaderModule({ code: desc.wgslSource });
+// Every pass reads per-instance data from a vertex buffer, because Slang's
+// GLSL ES target has no SSBOs.
+async function buildPipeline(device, recipe, passId) {
+    const module = device.createShaderModule({ code: recipe.wgslSource });
     const info = await module.getCompilationInfo();
     const errors = info.messages.filter(m => m.type === 'error');
     if (errors.length > 0) {
         const details = errors
             .map(m => `line ${m.lineNum}: ${m.message}`)
             .join('; ');
-        throw new ShaderCompileError(desc.id, details);
-    }
-    const blend = desc.blend
-        ? desc.blendState
-            ? gpuBlendState(desc.blendState)
-            : STANDARD_BLEND_STATE
-        : undefined;
-    // Every pass feeds @location(N) inputs from a bound vertex buffer.
-    const vertexBuffers = [
-        {
-            arrayStride: desc.instanceStride,
-            stepMode: 'instance',
-            attributes: desc.vertexAttributes.map((attr, i) => ({
-                shaderLocation: i,
-                offset: attr.offsetBytes,
-                format: toGpuVertexFormat(attr),
-            })),
-        },
-    ];
+        throw new ShaderCompileError(passId, details);
+    }
+    const { blend } = recipe;
     return device.createRenderPipelineAsync({
-        layout: desc.textures?.length
-            ? layouts.texturedPipelineLayout
-            : layouts.uniformOnlyPipelineLayout,
-        vertex: { module, entryPoint: 'vs_main', buffers: vertexBuffers },
+        layout: getPassLayout(device, recipe.bindGroupLayout).pipelineLayout,
+        vertex: { module, entryPoint: 'vs_main', buffers: [recipe.vertexBuffer] },
         fragment: {
             module,
             entryPoint: 'fs_main',
@@ -100,17 +58,18 @@ async function buildPipeline(device, desc, layouts, sampleCount) {
                 },
             ],
         },
-        primitive: { topology: desc.topology ?? 'triangle-list' },
-        multisample: sampleCount === 1 ? undefined : { count: sampleCount },
+        primitive: { topology: recipe.topology },
+        multisample: recipe.sampleCount === 1 ? undefined : { count: recipe.sampleCount },
     });
 }
-// Resolve every declared pass to its pipeline, taking the device-wide cache's
-// answer wherever another display of this type already built one. Still every
-// pass up front rather than on first draw — the WebGL2 side compiles lazily
-// (`getPass`) and this side does not; see ARCHITECTURAL_LIMITS.md §"Every
-// WebGPU display resolves its whole pass list before it can paint".
+// Every declared pass up front, unlike WebGL2's first-draw link; see
+// ARCHITECTURAL_LIMITS.md §"Every WebGPU display resolves its whole pass list
+// before it can paint". Each pass compiles as soon as its own WGSL arrives.
 async function resolvePipelines(device, descriptors, sampleCount) {
-    const built = await Promise.all(descriptors.map(desc => getOrBuildPipeline(device, desc, sampleCount, (layouts, count) => buildPipeline(device, desc, layouts, count))));
+    const built = await Promise.all(descriptors.map(async (desc) => {
+        const { WGSL_SOURCE } = await desc.source.wgsl();
+        return getOrBuildPipeline(device, pipelineRecipe(desc, WGSL_SOURCE, sampleCount), recipe => buildPipeline(device, recipe, desc.id));
+    }));
     return new Map(descriptors.map((desc, i) => [desc.id, built[i]]));
 }
 // Behavioral parity with WebGL2Hal is enforced by tests, not by this file:
@@ -128,14 +87,13 @@ export class WebGPUHal extends GpuHalBase {
     context;
     pipelines;
     passTextures = new Map();
-    // One bind group per textured pass, built lazily by `getBindGroup` and
-    // dropped when `uploadTexture` swaps that pass's texture. Uniform-only passes
-    // are not stored here — they all share `uniformOnlyBindGroup`.
+    // Every pass's bind group, by the pass drawn. A pass that binds no texture
+    // has one from construction, shared with each pass over the same layout; a
+    // textured pass gets its own when its texture arrives, dropped when
+    // `uploadTexture` replaces the texture. The layouts are the device's, shared
+    // with every display on it; the groups are this HAL's, since they name its
+    // uniform ring buffer.
     passBindGroups = new Map();
-    // The device's layouts, not this HAL's — shared with every other display on
-    // the same device. The bind GROUPS above stay per-HAL: they reference this
-    // HAL's uniform ring buffer.
-    layouts;
     // Uniform ring buffer: holds up to MAX_UNIFORM_SLOTS sets of uniforms so
     // that all draw calls in a frame can reference different uniform data via
     // dynamic offsets, enabling a single command encoder + submit per frame.
@@ -147,10 +105,6 @@ export class WebGPUHal extends GpuHalBase {
     // console the developer stops reading, and the fact is about the renderer
     // rather than about this frame.
     warnedUniformSlots = false;
-    // Shared bind group for every uniform-only pass — only references
-    // `uniformRingBuffer` (via dynamic offset at draw time), so one instance
-    // serves all passes/regions instead of allocating a fresh one per upload.
-    uniformOnlyBindGroup;
     // Samples per pixel this display renders at, stated by whoever built it (see
     // `RenderingBackendOptions.sampleCount`). Every render-pass, texture and
     // pipeline decision below reads it, so the two shapes cannot mismatch — and
@@ -178,7 +132,7 @@ export class WebGPUHal extends GpuHalBase {
      * selection spanning two sections re-uploads `OVERLAY_REGION` once per
      * section, inside the block loop.
      *
-     * Deferring is what makes mid-frame replacement legal instead of merely
+     * Deferring the destroy makes mid-frame replacement legal instead of merely
      * warned about; synteny's `ensureUploaded` has always deleted a pass mid-frame
      * that the open pass never referenced, and that case was never the bug.
      */
@@ -200,13 +154,12 @@ export class WebGPUHal extends GpuHalBase {
     warnedSwapChainLoss = false;
     swapChainUnrecoverable = false;
     reportedSurfaceFailure = false;
-    constructor(device, canvas, context, descriptors, sampleCount, pipelines, layouts) {
+    constructor(device, canvas, context, descriptors, sampleCount, pipelines) {
         super(descriptors, 'WebGPUHal');
         this.device = device;
         this.canvas = canvas;
         this.context = context;
         this.pipelines = pipelines;
-        this.layouts = layouts;
         this.sampleCount = sampleCount;
         // Align uniform slots to device requirements for dynamic offsets
         const alignment = device.limits.minUniformBufferOffsetAlignment;
@@ -218,9 +171,51 @@ export class WebGPUHal extends GpuHalBase {
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         this.uniformStaging = new Uint8Array(ringSize);
-        this.uniformOnlyBindGroup = createUniformOnlyBindGroup(device, layouts.uniformOnlyBindGroupLayout, this.uniformRingBuffer, this.alignedUniformSize);
+        const byLayout = new Map();
+        for (const desc of descriptors) {
+            if (!desc.bindings.some(b => b.kind === 'texture')) {
+                const layout = this.bindGroupLayoutOf(desc.bindings);
+                let group = byLayout.get(layout);
+                if (!group) {
+                    group = this.createBindGroup(desc.bindings, layout);
+                    byLayout.set(layout, group);
+                }
+                this.passBindGroups.set(desc.id, group);
+            }
+        }
         this.configureContext();
     }
+    bindGroupLayoutOf(bindings) {
+        return getPassLayout(this.device, bindGroupLayoutEntries(bindings))
+            .bindGroupLayout;
+    }
+    // One entry per binding in the pass's table, the same table its layout was
+    // built from, so the group cannot name a binding the layout lacks.
+    createBindGroup(bindings, layout, texture) {
+        return this.device.createBindGroup({
+            layout,
+            entries: bindings.map(b => ({
+                binding: b.index,
+                resource: this.bindingResource(b, texture),
+            })),
+        });
+    }
+    bindingResource(b, texture) {
+        if (b.kind === 'uniform') {
+            return {
+                buffer: this.uniformRingBuffer,
+                offset: 0,
+                size: this.alignedUniformSize,
+            };
+        }
+        if (texture && b.kind === 'texture') {
+            return texture.texture.createView();
+        }
+        if (texture && b.kind === 'sampler') {
+            return texture.sampler;
+        }
+        throw new Error(`[WebGPUHal] nothing to bind for the ${b.kind} '${b.name}' at binding ${b.index}`);
+    }
     limits() {
         const { maxBufferSize, maxTextureDimension2D } = this.device.limits;
         return {
@@ -256,11 +251,10 @@ export class WebGPUHal extends GpuHalBase {
             return null;
         }
         // Resolve pipelines BEFORE acquiring the canvas's webgpu context. A canvas's
-        // context type is permanent once acquired, so if shader compilation throws
-        // here the canvas stays pristine and createGpuHal's WebGL2 fallback can
-        // still claim it — otherwise a partial WebGPU init would drop us all the way
-        // to Canvas2D on a WebGL2-capable machine.
-        const layouts = getDeviceLayouts(device);
+        // context type is permanent once acquired, so if a shader fails to load or
+        // compile here the canvas stays pristine and createGpuHal's WebGL2 fallback
+        // can still claim it — otherwise a partial WebGPU init would drop us all the
+        // way to Canvas2D on a WebGL2-capable machine.
         const pipelines = await resolvePipelines(device, descriptors, sampleCount);
         const context = canvas.getContext('webgpu');
         if (!context) {
@@ -271,7 +265,7 @@ export class WebGPUHal extends GpuHalBase {
             throw canvasContextError(canvas, 'webgpu');
         }
         noteCanvasContext(canvas, 'webgpu');
-        return new WebGPUHal(device, canvas, context, descriptors, sampleCount, pipelines, layouts);
+        return new WebGPUHal(device, canvas, context, descriptors, sampleCount, pipelines);
     }
     resize(width, height) {
         const { changed, scale } = syncCanvasSize(this.canvas, width, height);
@@ -314,43 +308,22 @@ export class WebGPUHal extends GpuHalBase {
      * (and a dropped draw) the moment one side samples a texture.
      *
      * Nothing in a bind group varies per region either: it references the
-     * HAL-wide uniform ring buffer plus the pass's own texture/sampler. So
-     * uniform-only passes all share `uniformOnlyBindGroup`, and a textured pass
-     * gets exactly one, cached until `uploadTexture` replaces its texture.
-     * Returns undefined when a pass needs a texture that hasn't arrived yet;
-     * drawPass skips those.
+     * HAL-wide uniform ring buffer plus the pass's own texture/sampler. Returns
+     * undefined when a pass needs a texture that hasn't arrived yet; drawPass
+     * skips those.
      */
     getBindGroup(passId) {
-        const tb = this.descriptors.get(passId)?.textures?.[0];
-        if (tb) {
-            let bindGroup = this.passBindGroups.get(passId);
-            if (!bindGroup) {
-                const texState = this.passTextures.get(passId);
-                if (texState) {
-                    bindGroup = this.device.createBindGroup({
-                        layout: this.layouts.texturedBindGroupLayout,
-                        entries: [
-                            {
-                                binding: 1,
-                                resource: {
-                                    buffer: this.uniformRingBuffer,
-                                    offset: 0,
-                                    size: this.alignedUniformSize,
-                                },
-                            },
-                            {
-                                binding: tb.textureBinding,
-                                resource: texState.texture.createView(),
-                            },
-                            { binding: tb.samplerBinding, resource: texState.sampler },
-                        ],
-                    });
-                    this.passBindGroups.set(passId, bindGroup);
-                }
-            }
-            return bindGroup;
+        return this.passBindGroups.get(passId) ?? this.bindTexture(passId);
+    }
+    bindTexture(passId) {
+        const texture = this.passTextures.get(passId);
+        const desc = this.descriptors.get(passId);
+        if (!texture || !desc) {
+            return undefined;
         }
-        return this.uniformOnlyBindGroup;
+        const group = this.createBindGroup(desc.bindings, this.bindGroupLayoutOf(desc.bindings), texture);
+        this.passBindGroups.set(passId, group);
+        return group;
     }
     /**
      * The one place a GPU resource this HAL owns is released — see

package/esm/instancePass.d.ts

@@ -5,7 +5,8 @@ import type { GpuHal, PipelineDescriptor } from './hal';
  * A pass id, the packer that fills its buffer, and the upload that joins them
  * are three statements of one fact, and renderers kept them in three places —
  * so a pass could be registered and drawn while nothing uploaded to it, which
- * paints nothing, silently, on the GPU backend only. Here they are one object:
+ * paints nothing, on the GPU backend only. `InstancePass`
+ * makes them one object:
  *
  * ```ts
  * export const GAP_PASS = {

package/esm/mapUploadSync.d.ts

@@ -9,8 +9,8 @@ export interface MapUploadTarget<K, T, B> {
  * re-uploads), and re-uploads everything when the backend identity changes —
  * a context-loss recovery hands a fresh backend with empty GPU buffers.
  *
- * Returns whether anything reached the backend, which is what lets the upload
- * autorun skip the redraw it would otherwise force after every run.
+ * Returns whether anything reached the backend, so the upload autorun can skip
+ * the redraw it would otherwise force after every run.
  *
  * For the skip to fire, the map must keep **stable references** for unchanged
  * entries across recomputes. With an always-fresh map every entry re-uploads,

package/esm/mapUploadSync.js

@@ -5,8 +5,8 @@
  * re-uploads), and re-uploads everything when the backend identity changes —
  * a context-loss recovery hands a fresh backend with empty GPU buffers.
  *
- * Returns whether anything reached the backend, which is what lets the upload
- * autorun skip the redraw it would otherwise force after every run.
+ * Returns whether anything reached the backend, so the upload autorun can skip
+ * the redraw it would otherwise force after every run.
  *
  * For the skip to fire, the map must keep **stable references** for unchanged
  * entries across recomputes. With an always-fresh map every entry re-uploads,

package/esm/marks/barMark.d.ts

@@ -1,16 +1,17 @@
 import type { ColorChannel } from './markRamp.ts';
+import type { RowChannel, RowParams } from './rowLane.ts';
 import type { MarkRamp, MarkShape, MarkValueScaleType } from './types.ts';
 /**
  * The `bar` shape's channels: a rectangle from `x` to `x2` standing between
- * the baseline and `y` on the value scale.
+ * the baseline and `y` on the value scale, in the band of its `row`.
  */
-export interface BarChannels extends ColorChannel {
+export interface BarChannels extends ColorChannel, RowChannel {
     x: Uint32Array;
     x2: Uint32Array;
     y: Float32Array;
     count: number;
 }
-export interface BarParams {
+export interface BarParams extends RowParams {
     /** `[min, max]` `y` and `origin` are read through. */
     domain: [number, number];
     /** How that domain is read; linear when absent. */
@@ -24,5 +25,7 @@ export interface BarParams {
      * a no-op for a caller whose bars tile.
      */
     minWidthPx: number;
+    /** CSS px the painter alone adds to the drawn width; see `SpanParams.seamPx`. */
+    seamPx: number;
 }
 export declare const barMark: MarkShape<BarChannels, BarParams>;

package/esm/marks/barMark.js

@@ -1,21 +1,23 @@
 import { bpRangeXTuple } from '../blockClipUtils.js';
 import { getDpr, makeBpMapper, spanLeft } from '../canvas2dUtils.js';
+import { scaleTypeCode } from '../scoreScale.js';
 import * as shader from '../shaders/barMark.generated.js';
 import { valueToYPxScaled } from '../shaders/pointMark.js.generated.js';
 import { slangPass } from '../slangPass.js';
 import { makeAbgrFill } from './colorFill.js';
-import { colorBits, paintColors, rampUniforms, valueScaleTypeCode, } from './markRamp.js';
-import { blockPx } from './spanMark.js';
+import { colorBits, paintColors, rampUniforms } from './markRamp.js';
+import { valueWindow } from './nearestMarkHit.js';
+import { bandHeightPx, bandTopPx, rowLane } from './rowLane.js';
 // The rect one instance paints, in the frame's CSS px, or undefined for a bar
 // with no height — which draws nothing and so cannot be hovered.
-function barRect(bpToPx, x, x2, y, params, canvasHeight) {
+function barRect(bpToPx, x, x2, y, bandTop, band, params) {
     const xa = bpToPx(x);
     const xb = bpToPx(x2);
     const width = Math.max(params.minWidthPx, Math.abs(xb - xa));
     const [domainMin, domainMax] = params.domain;
-    const st = valueScaleTypeCode(params.scaleType);
-    const valueY = valueToYPxScaled(y, domainMin, domainMax, canvasHeight, st);
-    const originY = valueToYPxScaled(params.origin, domainMin, domainMax, canvasHeight, st);
+    const st = scaleTypeCode(params.scaleType);
+    const valueY = bandTop + valueToYPxScaled(y, domainMin, domainMax, band, st);
+    const originY = bandTop + valueToYPxScaled(params.origin, domainMin, domainMax, band, st);
     const top = Math.min(valueY, originY);
     const height = Math.abs(valueY - originY);
     return height === 0
@@ -26,7 +28,7 @@ export const barMark = {
     id: 'bar',
     pass: {
         ...slangPass({ id: 'bar', mod: shader }),
-        pack: c => shader.packInstances({ ...c, color: colorBits(c) }, c.count),
+        pack: c => shader.packInstances({ ...c, color: colorBits(c), row: rowLane(c.row, c.count) }, c.count),
     },
     writeUniforms(scratch, clip, block, frame, params) {
         shader.writeUniforms(scratch, {
@@ -34,9 +36,10 @@ export const barMark = {
             canvasHeight: frame.canvasHeight,
             domainMin: params.domain[0],
             domainMax: params.domain[1],
-            valueScaleType: valueScaleTypeCode(params.scaleType),
+            valueScaleType: scaleTypeCode(params.scaleType),
             ...rampUniforms(params.ramp),
             origin: params.origin,
+            rowHeight: bandHeightPx(params, frame.canvasHeight),
             zero: 0,
             minCellDenomPx: clip.scissorW,
             minWidthPx: params.minWidthPx,
@@ -44,20 +47,23 @@ export const barMark = {
         });
     },
     paintBlock(ctx, channels, block, frame, params) {
-        const { x, x2, y, count } = channels;
+        const { x, x2, y, row, count } = channels;
         const color = paintColors(channels, count, params.ramp);
         const bpToPx = makeBpMapper(block);
         const setFill = makeAbgrFill(ctx);
+        const band = bandHeightPx(params, frame.canvasHeight);
         for (let i = 0; i < count; i++) {
-            const r = barRect(bpToPx, x[i], x2[i], y[i], params, frame.canvasHeight);
+            const r = barRect(bpToPx, x[i], x2[i], y[i], bandTopPx(row, i, band), band, params);
             if (r) {
                 setFill(color[i]);
-                ctx.fillRect(r.left, r.top, r.width, r.height);
+                ctx.fillRect(r.left, r.top, r.width + params.seamPx, r.height);
             }
         }
     },
     ink(channels, block, frame, params, i) {
-        const { x, x2, y } = channels;
-        return barRect(bp => blockPx(block, bp), x[i], x2[i], y[i], params, frame.canvasHeight);
+        const { x, x2, y, row } = channels;
+        const band = bandHeightPx(params, frame.canvasHeight);
+        return barRect(makeBpMapper(block), x[i], x2[i], y[i], bandTopPx(row, i, band), band, params);
     },
+    valueWindow,
 };

package/esm/marks/drawAgainstHit.d.ts

@@ -1,5 +1,5 @@
 import type { RenderBlock } from '../renderBlock.ts';
-import type { MarkContext2D, MarkFrame, MarkShape } from './types.ts';
+import type { Mark, MarkContext2D, MarkFrame } from './types.ts';
 export interface RecordedRect {
     x: number;
     y: number;
@@ -12,8 +12,8 @@ export interface RecordedRect {
  * in CANVAS coordinates — `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`/`bezierCurveTo` 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 curve contributes its control
+ * bounding box, the extent a shape whose hit test answers a polygon's box
+ * (the variant inversion triangle) is checked against; a curve contributes its control
  * points, whose hull contains it.
  *
  * A **stroked** path records one rect per `moveTo`/`lineTo` edge, each the
@@ -60,59 +60,78 @@ export declare function recordingContext(): {
     };
     calls: RecordedRect[];
 };
+/** The extent of a painting, in canvas px. */
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface Counted {
+    count: number;
+}
+export interface SweepOptions<C> {
+    maxDistSq?: number;
+    step?: number;
+    sliceOne?: (channels: C, index: number) => C;
+    inkSlackPx?: number;
+    contains?: (index: number, xPx: number, yPx: number) => boolean;
+}
+/**
+ * The ink clause of {@link sweepMarkAgainstHit} alone, for a mark with no
+ * `hitNearest`: `boxes[i]` is what the painter recorded for instance `i`.
+ */
+export declare function inkViolations<C, S extends MarkFrame>(mark: Mark<C, S>, channels: C, block: RenderBlock, state: S, boxes: readonly (Box | undefined)[], inkSlackPx: number): string[];
 /**
  * The draw-against-hit gate: paint the block, then walk it in `step` px and
  * hold `hitNearest` to what the painter actually put on the canvas.
  *
  * **What the painter drew for instance `i` has to be attributed to `i`,** and
- * there are two ways to get that. A shape whose every instance is one
- * `fillRect` gets it positionally, which is the default and needs nothing. A
- * shape that batches a colour run into one path (`point`'s glyphs), or that
- * skips an instance the view has scrolled past (`cell`'s off-canvas rows),
- * cannot be read that way at all — the batch has fewer rects than instances, or
- * the wrong ones. `sliceOne` is the way in for those: hand back one instance's
- * channels and the sweep paints it alone, so the attribution holds by
- * construction and a culled instance is visibly an empty painting.
+ * there are two ways to get that. A mark whose every instance is one `fillRect`
+ * gets it positionally, which is the default and needs nothing. A mark that
+ * batches a colour run into one path (`point`'s glyphs), or that skips an
+ * instance the view has scrolled past (`cell`'s off-canvas rows), cannot be read
+ * that way at all — the batch has fewer rects than instances, or the wrong ones.
+ * `sliceOne` is the way in for those: hand back one instance's channels and the
+ * sweep paints it alone, so the attribution holds by construction and a culled
+ * instance is visibly an empty painting.
  *
- * Four claims, all of them one-directional and true of every shape:
+ * Four claims, all of them one-directional and true of every mark:
  *
  * - an instance that painted nothing is never the answer,
- * - `hit.x`/`hit.y` — where the shape says its ink is — lies inside the box the
+ * - `hit.x`/`hit.y` — where the mark says its ink is — lies inside the box the
  *   painter drew for the instance the hit names,
  * - `hit.distSq` is no smaller than the distance to that box, since the box
  *   contains the ink and cannot be farther than it,
  * - `hit.distSq` IS the distance to `hit.x`/`hit.y`, which is `MarkHit`'s own
- *   contract rather than a fact about the painting: a shape that answers a
+ *   contract rather than a fact about the painting: a mark that answers a
  *   distance its own reported point does not support has two spellings of where
  *   its ink is, and the nearest-wins walk is resolved by the one the caller
  *   cannot see.
  *
- * The fourth claim is the strongest and is not universal: **a point on the box
- * has to answer that box**, the last-painted one where boxes overlap, since the
- * sweep hands candidates back to front. It holds only where the painted box IS
- * the hit target — every `fillRect` shape, and `cell`'s inversion triangle,
- * which answers as its bounding box on purpose — and not for a glyph, whose box
- * is a superset of its ink. So it runs exactly when the batch painted one rect
- * per instance, which is that set.
+ * The fifth is the containment rule: **a point the rule contains answers the
+ * nearest painted instance it contains**, the last-painted where tied, since the
+ * sweep hands candidates back to front. The default rule is the painted box, so
+ * a point on a box answers that box, and off every box a hit target wider than
+ * its ink may still answer. The default holds only where the box IS the hit
+ * target — every `fillRect` mark, and `cell`'s inversion triangle, which answers
+ * as its bounding box on purpose — and not for a glyph, whose box is a superset
+ * of its ink, so it runs exactly when the batch painted one rect per instance. A
+ * mark whose hit rule is not its box (the pileup's bp containment) passes
+ * `contains`, which is then the whole rule: the sweep covers the whole canvas,
+ * and a point the rule contains nowhere answers nothing.
  *
- * A shape declaring `ink` is held to a second clause, per instance: the box
- * the painter recorded for `i` lies inside `ink(i)`, and each edge of `ink(i)`
- * lies within `inkSlackPx` (default 1) of the painting's — so the rect is
- * tight to the ink within a pixel on every side, which admits a seam overdraw
- * or a pixel snap and rejects a rect that is the wrong row, the wrong width or
- * the whole canvas. An instance that painted nothing must answer no ink, and
- * one with ink must have painted.
+ * A mark declaring `ink` is held to one more clause, per instance: the box the
+ * painter recorded for `i` lies inside `ink(i)`, and each edge of `ink(i)` lies
+ * within `inkSlackPx` (default 1) of the painting's — so the rect is tight to
+ * the ink within a pixel on every side, which admits a seam overdraw or a pixel
+ * snap and rejects a rect that is the wrong row, the wrong width or the whole
+ * canvas. An instance that painted nothing must answer no ink, and one with ink
+ * must have painted.
  *
  * 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.
+ * `expect(sweep(...)).toEqual([])`. `maxDistSq` is the bound the hit test is
+ * asked with, `Infinity` unless the caller's differs.
  */
-export declare function sweepDrawAgainstHit<C extends {
-    count: number;
-}, P>(shape: MarkShape<C, P>, channels: C, block: RenderBlock, frame: MarkFrame, params: P, { maxDistSq, step, sliceOne, inkSlackPx, }: {
-    maxDistSq: number;
-    step?: number;
-    sliceOne?: (channels: C, index: number) => C;
-    inkSlackPx?: number;
-}): string[];
+export declare function sweepMarkAgainstHit<C extends Counted, S extends MarkFrame>(mark: Mark<NoInfer<C>, S>, channels: C, block: RenderBlock, state: S, { maxDistSq, step, sliceOne, inkSlackPx, contains: rule, }?: SweepOptions<C>): string[];
+export {};