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

package/esm/RenderLifecycleMixin.d.ts

@@ -64,6 +64,7 @@ export interface RenderingBackendCallbacks<B> {
  */
 export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree").IModelType<{}, {
     canvasDrawn: boolean;
+    paintCount: number;
     currentRenderingBackend: unknown;
     renderTick: number;
     autorunsInstalled: boolean;

package/esm/RenderLifecycleMixin.js

@@ -45,6 +45,13 @@ export function RenderLifecycleMixin() {
          * flips true on first paint; read by test selectors to detect render
          */
         canvasDrawn: false,
+        /**
+         * #volatile
+         * bumped after every frame the backend painted, so a consumer that
+         * reads this display's canvas — the circular view's ring, which copies
+         * the strip into a texture — knows when the pixels moved
+         */
+        paintCount: 0,
         /**
          * #volatile
          * current backend reference, updated on context-loss recovery.
@@ -188,6 +195,7 @@ export function RenderLifecycleMixin() {
          * #action
          */
         markCanvasDrawn() {
+            self.paintCount += 1;
             if (!self.canvasDrawn) {
                 self.canvasDrawn = true;
             }

package/esm/gpuContextLostError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Flagged rather than matched by message or `instanceof`, so the error UI can
+ * offer the remedy specific to a loss (switch the page to Canvas2D) without
+ * offering it for render errors whose remedy differs (an over-allocation says to
+ * zoom in).
+ *
+ * A lost WebGPU device carries the same flag deliberately: the two causes
+ * differ, but the remedy on offer — take the page off the GPU — is the same one.
+ *
+ * React-free, and split out of `useRenderingBackend` for that reason: the HAL
+ * raises the surface error below and must not import a hook to do it.
+ * `useRenderingBackend` re-exports these, so every existing import site keeps
+ * working.
+ */
+export declare function createGpuContextLostError(message?: string): Error & {
+    gpuContextLost: true;
+};
+export declare function createGpuDeviceLostError(): Error & {
+    gpuContextLost: true;
+};
+/**
+ * A canvas whose swap-chain image the driver refuses. Distinct from a device
+ * loss, because the device is fine and still renders offscreen, and distinct
+ * from an over-limit allocation, because zooming in does not fix it. Canvas2D
+ * does, which is why this carries the flag that puts that button on the banner.
+ */
+export declare function createGpuSurfaceLostError(detail: string): Error & {
+    gpuContextLost: true;
+};
+export declare function isGpuContextLostError(error: unknown): error is object & Record<"gpuContextLost", unknown>;

package/esm/gpuContextLostError.js

@@ -0,0 +1,40 @@
+const CONTEXT_LOST_MESSAGE = 'WebGL context lost. The browser reclaimed the GPU context for this display, ' +
+    'usually because too many GPU-rendered views are open at once.';
+const DEVICE_LOST_MESSAGE = 'WebGPU device lost. The GPU device backing this display went away and kept ' +
+    'going away after several attempts to rebuild on a fresh one.';
+const SURFACE_LOST_MESSAGE = 'WebGPU could not give this display a drawable surface. The GPU driver ' +
+    'rejected the canvas image, so every frame this display submits is discarded.';
+/**
+ * Flagged rather than matched by message or `instanceof`, so the error UI can
+ * offer the remedy specific to a loss (switch the page to Canvas2D) without
+ * offering it for render errors whose remedy differs (an over-allocation says to
+ * zoom in).
+ *
+ * A lost WebGPU device carries the same flag deliberately: the two causes
+ * differ, but the remedy on offer — take the page off the GPU — is the same one.
+ *
+ * React-free, and split out of `useRenderingBackend` for that reason: the HAL
+ * raises the surface error below and must not import a hook to do it.
+ * `useRenderingBackend` re-exports these, so every existing import site keeps
+ * working.
+ */
+export function createGpuContextLostError(message = CONTEXT_LOST_MESSAGE) {
+    return Object.assign(new Error(message), {
+        gpuContextLost: true,
+    });
+}
+export function createGpuDeviceLostError() {
+    return createGpuContextLostError(DEVICE_LOST_MESSAGE);
+}
+/**
+ * A canvas whose swap-chain image the driver refuses. Distinct from a device
+ * loss, because the device is fine and still renders offscreen, and distinct
+ * from an over-limit allocation, because zooming in does not fix it. Canvas2D
+ * does, which is why this carries the flag that puts that button on the banner.
+ */
+export function createGpuSurfaceLostError(detail) {
+    return createGpuContextLostError(`${SURFACE_LOST_MESSAGE} (${detail})`);
+}
+export function isGpuContextLostError(error) {
+    return (typeof error === 'object' && error !== null && 'gpuContextLost' in error);
+}

package/esm/gpuDevice.js

@@ -154,8 +154,11 @@ async function createDevice() {
         // Surface any WebGPU validation / out-of-memory / internal errors that
         // would otherwise be silently swallowed. Without this, a bad draw/pipeline
         // results in a blank canvas with no console output.
+        // The constructor name, because the message alone does not say whether a
+        // failure is validation, out-of-memory or internal — and that is what
+        // decides which `pushErrorScope` filter could have caught it.
         d.addEventListener('uncapturederror', (event) => {
-            console.error('[GPU] UNCAPTURED ERROR:', event.error.message);
+            console.error(`[GPU] UNCAPTURED ${event.error.constructor.name}:`, event.error.message);
         });
         void d.lost.then(info => {
             // Identity check: if the shared device has already been replaced (test

package/esm/hal/gpuHalBase.d.ts

@@ -1,6 +1,6 @@
 import { OomReporter } from './oomReporter.ts';
 import { RegionRegistry } from './regionRegistry.ts';
-import type { PipelineDescriptor, TextureBinding } from './types.ts';
+import type { PipelineDescriptor, TextureBinding, TextureSource } from './types.ts';
 /**
  * The device ceilings the shared upload shells refuse past. WebGPU asks the
  * device, WebGL2 has no such parameter for buffers and carries its own constant
@@ -42,7 +42,7 @@ export declare abstract class GpuHalBase<Buf extends {
      * reached for a pass that declares a binding, and only within
      * `maxTextureDimensionPx`.
      */
-    protected abstract createTexture(passId: string, binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    protected abstract createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     /** Release this HAL's own GPU objects. Runs exactly once, from `dispose`. */
     protected abstract releaseResources(): void;
     setErrorHandler(handler: (error: Error) => void): void;
@@ -50,6 +50,6 @@ export declare abstract class GpuHalBase<Buf extends {
     getBufferCount(regionKey: number, passId: string): number;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    uploadTexture(passId: string, data: Uint8Array, width: number, height: number): void;
+    uploadTexture(passId: string, data: TextureSource, width: number, height: number): void;
     dispose(): void;
 }

package/esm/hal/index.d.ts

@@ -4,4 +4,4 @@ export { assertUniquePassIds } from './passIds.ts';
 export { WebGL2Hal } from './webgl2Hal.ts';
 export { WebGPUHal } from './webgpuHal.ts';
 export type { GpuHalOptions } from './createHal.ts';
-export type { BlendState, VertexAttributeLayout, GpuHal, PipelineDescriptor, SampleCount, ShaderBinding, TextureBinding, } from './types.ts';
+export type { BlendState, VertexAttributeLayout, GpuHal, PipelineDescriptor, SampleCount, ShaderBinding, TextureBinding, TextureSource, } from './types.ts';

package/esm/hal/mockHal.d.ts

@@ -1,5 +1,5 @@
 import { GpuHalBase } from './gpuHalBase.ts';
-import type { GpuHal, PipelineDescriptor, TextureBinding } from './types.ts';
+import type { GpuHal, PipelineDescriptor, TextureBinding, TextureSource } from './types.ts';
 export interface MockCall {
     method: string;
     args: unknown[];
@@ -90,7 +90,7 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
     };
     protected destroyBuffer(): void;
     private textures;
-    protected createTexture(passId: string, _binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    protected createTexture(passId: string, _binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     protected releaseResources(): void;
     private record;
     errorHandler: ((error: Error) => void) | null;
@@ -120,7 +120,7 @@ export declare class MockHal extends GpuHalBase<MockBuffer> implements GpuHal {
     getUniformWritesF32(): Float32Array<ArrayBuffer>[];
     getUniformWritesU32(): Uint32Array<ArrayBuffer>[];
     getBuffer(regionKey: number, passId: string): MockBuffer | undefined;
-    getTexture(passId: string): Uint8Array<ArrayBufferLike> | undefined;
+    getTexture(passId: string): TextureSource | undefined;
     callsOf(method: string): MockCall[];
     /**
      * Every draw of the frame with the state it went out under, in order — the

package/esm/hal/mockHal.js

@@ -77,8 +77,9 @@ export class MockHal extends GpuHalBase {
     // samples needs the bytes, not the byteLength the call log records.
     textures = new Map();
     createTexture(passId, _binding, data, width, height) {
-        this.textures.set(passId, data.slice());
-        this.record('uploadTexture', passId, data.byteLength, width, height);
+        const bytes = data instanceof Uint8Array;
+        this.textures.set(passId, bytes ? data.slice() : data);
+        this.record('uploadTexture', passId, bytes ? data.byteLength : 'canvas', width, height);
     }
     releaseResources() {
         this.record('dispose');

package/esm/hal/oomReporter.d.ts

@@ -12,4 +12,11 @@ export declare class OomReporter {
     constructor(hal: string);
     setHandler(handler: (error: Error) => void): void;
     report(message: string): void;
+    /**
+     * Report an error the HAL has already classified, for a failure whose remedy
+     * is not `report`'s "zoom in". Kept separate so the classification stays with
+     * the caller that knows it — flagging every over-limit allocation as a context
+     * loss would offer "Use Canvas2D" for a view that only needs zooming.
+     */
+    reportClassified(error: Error): void;
 }

package/esm/hal/oomReporter.js

@@ -19,4 +19,14 @@ export class OomReporter {
         console.error(`[${this.hal}] ${message}`);
         this.handler?.(new Error(message));
     }
+    /**
+     * Report an error the HAL has already classified, for a failure whose remedy
+     * is not `report`'s "zoom in". Kept separate so the classification stays with
+     * the caller that knows it — flagging every over-limit allocation as a context
+     * loss would offer "Use Canvas2D" for a view that only needs zooming.
+     */
+    reportClassified(error) {
+        console.error(`[${this.hal}] ${error.message}`);
+        this.handler?.(error);
+    }
 }

package/esm/hal/types.d.ts

@@ -55,6 +55,13 @@ export interface ShaderBinding {
     kind: 'uniform' | 'texture' | 'sampler' | 'storage' | 'read-only-storage';
     name: string;
 }
+/**
+ * What a pass's texture is filled from: RGBA bytes, or a canvas whose pixels
+ * are copied on the GPU — the circular view's ring samples a linear display's
+ * finished strip that way. A canvas source lands premultiplied, so a shader
+ * reading one returns its sample under `//! blend: premultiplied`.
+ */
+export type TextureSource = Uint8Array | HTMLCanvasElement | OffscreenCanvas;
 export interface TextureBinding {
     textureBinding: number;
     samplerBinding: number;
@@ -106,7 +113,7 @@ export interface GpuHal {
     getBufferCount(regionKey: number, passId: string): number;
     deleteBuffer(regionKey: number, passId: string): void;
     deleteRegion(regionKey: number): void;
-    uploadTexture(passId: string, data: Uint8Array, width: number, height: number): void;
+    uploadTexture(passId: string, data: TextureSource, width: number, height: number): void;
     writeUniforms(data: ArrayBuffer): void;
     beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;
     drawPass(passId: string, regionKey: number, bufferPassId?: string): void;

package/esm/hal/webgl2Hal.d.ts

@@ -1,5 +1,5 @@
 import { GpuHalBase } from './gpuHalBase.ts';
-import type { GpuHal, PipelineDescriptor, TextureBinding } from './types.ts';
+import type { GpuHal, PipelineDescriptor, TextureBinding, TextureSource } from './types.ts';
 interface RegionPassBuffer {
     vbo: WebGLBuffer;
     count: number;
@@ -30,7 +30,7 @@ export declare class WebGL2Hal extends GpuHalBase<RegionPassBuffer> implements G
     private compilePass;
     private getPass;
     resize(width: number, height: number): import("./types.ts").CanvasScale;
-    protected createTexture(passId: string, binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    protected createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     writeUniforms(data: ArrayBuffer): void;
     beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;
     setScissor(x: number, y: number, w: number, h: number): void;

package/esm/hal/webgl2Hal.js

@@ -324,7 +324,14 @@ export class WebGL2Hal extends GpuHalBase {
         }
         const tex = gl.createTexture();
         gl.bindTexture(gl.TEXTURE_2D, tex);
-        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
+        if (data instanceof Uint8Array) {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
+        }
+        else {
+            gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, data);
+            gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+        }
         const filter = binding.filter === 'linear' ? gl.LINEAR : gl.NEAREST;
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);

package/esm/hal/webgpuHal.d.ts

@@ -1,5 +1,5 @@
 import { GpuHalBase } from './gpuHalBase.ts';
-import type { GpuHal, PipelineDescriptor, SampleCount, TextureBinding } from './types.ts';
+import type { GpuHal, PipelineDescriptor, SampleCount, TextureBinding, TextureSource } from './types.ts';
 interface RegionPassBuffer {
     dataBuffer: GPUBuffer;
     count: number;
@@ -47,6 +47,7 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
     private appliedViewport;
     private warnedSwapChainLoss;
     private swapChainUnrecoverable;
+    private reportedSurfaceFailure;
     private constructor();
     protected limits(): {
         maxBufferBytes: number;
@@ -97,7 +98,7 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
      */
     private destroyWhenIdle;
     private drainPendingDestroy;
-    protected createTexture(passId: string, binding: TextureBinding, data: Uint8Array, width: number, height: number): void;
+    protected createTexture(passId: string, binding: TextureBinding, data: TextureSource, width: number, height: number): void;
     writeUniforms(data: ArrayBuffer): void;
     /**
      * The canvas texture to draw this frame into, or null when the swap chain is
@@ -120,6 +121,15 @@ export declare class WebGPUHal extends GpuHalBase<RegionPassBuffer> implements G
      * Retry is what builds a fresh HAL.
      */
     private acquireTextureView;
+    /**
+     * Once per HAL, not once per frame: the refusal holds for every frame at this
+     * canvas size, and dotplot and synteny keep their canvas mounted through a
+     * `renderError`, so a per-frame report there never stops.
+     *
+     * Not terminal — a refusal tracks the canvas dimensions, so a resize can clear
+     * it. `swapChainUnrecoverable` stays for the case it was written for.
+     */
+    private reportSurfaceFailure;
     beginFrame(clearR: number, clearG: number, clearB: number, clearA?: number): void;
     drawPass(passId: string, regionKey: number, bufferPassId?: string): void;
     /**

package/esm/hal/webgpuHal.js

@@ -1,6 +1,7 @@
 /// <reference types="@webgpu/types" />
 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';
@@ -198,6 +199,7 @@ export class WebGPUHal extends GpuHalBase {
     // than once per frame, and a reconfigure that failed is not attempted again.
     warnedSwapChainLoss = false;
     swapChainUnrecoverable = false;
+    reportedSurfaceFailure = false;
     constructor(device, canvas, context, descriptors, sampleCount, pipelines, layouts) {
         super(descriptors, 'WebGPUHal');
         this.device = device;
@@ -383,12 +385,20 @@ export class WebGPUHal extends GpuHalBase {
             // safe.
             this.destroyWhenIdle(existing.texture);
         }
+        const bytes = data instanceof Uint8Array;
         const texture = this.device.createTexture({
             size: [width, height],
             format: 'rgba8unorm',
-            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                (bytes ? 0 : GPUTextureUsage.RENDER_ATTACHMENT),
         });
-        this.device.queue.writeTexture({ texture }, data, { bytesPerRow: width * 4 }, { width, height });
+        if (bytes) {
+            this.device.queue.writeTexture({ texture }, data, { bytesPerRow: width * 4 }, { width, height });
+        }
+        else {
+            this.device.queue.copyExternalImageToTexture({ source: data }, { texture, premultipliedAlpha: true }, { width, height });
+        }
         const sampler = this.device.createSampler({
             magFilter: binding.filter,
             minFilter: binding.filter,
@@ -474,6 +484,21 @@ export class WebGPUHal extends GpuHalBase {
             }
         }
     }
+    /**
+     * Once per HAL, not once per frame: the refusal holds for every frame at this
+     * canvas size, and dotplot and synteny keep their canvas mounted through a
+     * `renderError`, so a per-frame report there never stops.
+     *
+     * Not terminal — a refusal tracks the canvas dimensions, so a resize can clear
+     * it. `swapChainUnrecoverable` stays for the case it was written for.
+     */
+    reportSurfaceFailure(message) {
+        if (this.reportedSurfaceFailure) {
+            return;
+        }
+        this.reportedSurfaceFailure = true;
+        this.oom.reportClassified(createGpuSurfaceLostError(message));
+    }
     beginFrame(clearR, clearG, clearB, clearA = 1) {
         // Skip the frame entirely rather than encode one that cannot be valid.
         // Zero-size canvas: nothing to draw. Missing MSAA target while MSAA is
@@ -489,10 +514,23 @@ export class WebGPUHal extends GpuHalBase {
             (this.sampleCount > 1 && !this.msaaView)) {
             return;
         }
-        // Before the error scopes, so a failed acquisition needs no unwinding: the
-        // scopes stay pushed iff an encoder is created, which is what endFrame's
-        // early-return on !currentEncoder is paired with.
+        // A driver can refuse the canvas image without throwing — Dawn returns an
+        // error texture and an error view, and the frame encodes against it — so the
+        // acquisition needs a scope, and its own rather than the frame's: those stay
+        // pushed iff an encoder is created, and one left on the device's stack
+        // swallows every later frame's errors. Popped before the guard below, so
+        // every path balances. Awaiting the pop here would suspend across a
+        // GPU-process round trip and destroy the canvas texture mid-frame.
+        this.device.pushErrorScope('validation');
         const textureView = this.acquireTextureView();
+        void this.device
+            .popErrorScope()
+            .then(err => {
+            if (err) {
+                this.reportSurfaceFailure(err.message);
+            }
+        })
+            .catch(() => { });
         if (!textureView) {
             return;
         }

package/esm/marks/barMark.d.ts

@@ -0,0 +1,28 @@
+import type { ColorChannel } from './markRamp.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.
+ */
+export interface BarChannels extends ColorChannel {
+    x: Uint32Array;
+    x2: Uint32Array;
+    y: Float32Array;
+    count: number;
+}
+export interface BarParams {
+    /** `[min, max]` `y` and `origin` are read through. */
+    domain: [number, number];
+    /** How that domain is read; linear when absent. */
+    scaleType?: MarkValueScaleType;
+    /** The quantitative colour scale, for a bar whose colour is a ramp. */
+    ramp?: MarkRamp;
+    /** The value bars grow from; a bar below it hangs down. */
+    origin: number;
+    /**
+     * Narrowest a bar is painted, in CSS px, grown off the start edge. Zero is
+     * a no-op for a caller whose bars tile.
+     */
+    minWidthPx: number;
+}
+export declare const barMark: MarkShape<BarChannels, BarParams>;

package/esm/marks/barMark.js

@@ -0,0 +1,63 @@
+import { bpRangeXTuple } from '../blockClipUtils.js';
+import { getDpr, makeBpMapper, spanLeft } from '../canvas2dUtils.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';
+// 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) {
+    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 top = Math.min(valueY, originY);
+    const height = Math.abs(valueY - originY);
+    return height === 0
+        ? undefined
+        : { left: spanLeft(xa, xb, width), top, width, height };
+}
+export const barMark = {
+    id: 'bar',
+    pass: {
+        ...slangPass({ id: 'bar', mod: shader }),
+        pack: c => shader.packInstances({ ...c, color: colorBits(c) }, c.count),
+    },
+    writeUniforms(scratch, clip, block, frame, params) {
+        shader.writeUniforms(scratch, {
+            bpRangeX: bpRangeXTuple(clip, block.reversed),
+            canvasHeight: frame.canvasHeight,
+            domainMin: params.domain[0],
+            domainMax: params.domain[1],
+            valueScaleType: valueScaleTypeCode(params.scaleType),
+            ...rampUniforms(params.ramp),
+            origin: params.origin,
+            zero: 0,
+            minCellDenomPx: clip.scissorW,
+            minWidthPx: params.minWidthPx,
+            devicePixelRatio: getDpr(),
+        });
+    },
+    paintBlock(ctx, channels, block, frame, params) {
+        const { x, x2, y, count } = channels;
+        const color = paintColors(channels, count, params.ramp);
+        const bpToPx = makeBpMapper(block);
+        const setFill = makeAbgrFill(ctx);
+        for (let i = 0; i < count; i++) {
+            const r = barRect(bpToPx, x[i], x2[i], y[i], params, frame.canvasHeight);
+            if (r) {
+                setFill(color[i]);
+                ctx.fillRect(r.left, r.top, r.width, 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);
+    },
+};

package/esm/marks/drawAgainstHit.d.ts

@@ -5,15 +5,16 @@ export interface RecordedRect {
     y: number;
     w: number;
     h: number;
-    fillStyle: string;
+    fillStyle: MarkContext2D['fillStyle'];
 }
 /**
- * A `MarkContext2D` that records every rect a painter fills, in paint order —
- * `fillRect` and path `rect` alike, so a shape that batches by colour records
- * the same list as one that fills per instance. A path traced with
- * `moveTo`/`lineTo` and filled records its bounding box, which is what a
- * shape whose hit test answers a polygon's box (the variant inversion
- * triangle) is held to.
+ * A `MarkContext2D` that records every rect a painter fills, in paint order and
+ * 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
+ * points, whose hull contains it.
  *
  * A **stroked** path records one rect per `moveTo`/`lineTo` edge, each the
  * edge's bounding box widened by half the current `lineWidth` — the extent a
@@ -22,17 +23,85 @@ export interface RecordedRect {
  * otherwise record the run's hull as a single instance. `fillStyle` on such a
  * record is the `strokeStyle` it went down in; the field is the colour of the
  * ink either way.
+ *
+ * `save`/`restore` bracket the transform and the styles the way a real context
+ * does, and every recorded point goes through the CTM. The half-widths — a
+ * stroke's and a `strokeRect`'s — are measured AFTER it, so they are exact under
+ * a translation and approximate under a scale; no shape in tree strokes under
+ * one, and a rotated CTM records the ink's axis-aligned box rather than its
+ * silhouette.
  */
 export declare function recordingContext(): {
-    ctx: MarkContext2D;
+    ctx: {
+        fillStyle: string;
+        strokeStyle: string;
+        lineWidth: number;
+        lineCap: "butt";
+        lineJoin: "miter";
+        save(): void;
+        restore(): void;
+        translate(x: number, y: number): void;
+        scale(x: number, y: number): void;
+        rotate(angle: number): void;
+        beginPath(): void;
+        clip(): void;
+        setLineDash(): void;
+        moveTo(x: number, y: number): void;
+        lineTo(x: number, y: number): void;
+        bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+        arc(x: number, y: number, radius: number): void;
+        ellipse(x: number, y: number, radiusX: number, radiusY: number): void;
+        closePath(): void;
+        fill(): void;
+        stroke(): void;
+        rect(x: number, y: number, w: number, h: number): void;
+        fillRect(x: number, y: number, w: number, h: number): void;
+        strokeRect(x: number, y: number, w: number, h: number): void;
+    };
     calls: RecordedRect[];
 };
 /**
- * The draw-against-hit gate for a shape whose instances paint as rects: paint
- * the block, then walk it in `step` px and hold `hitNearest` to what the
- * painter recorded. A hit at distance 0 has to sit on the rect of the index it
- * names, and a point on a rect has to answer that rect — the last-painted one
- * where rects overlap, since the sweep hands candidates in back to front.
+ * 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.
+ *
+ * Four claims, all of them one-directional and true of every shape:
+ *
+ * - 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
+ *   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
+ *   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.
+ *
+ * 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.
  *
  * Returns the violations rather than asserting, so a test reads as
  * `expect(sweep(...)).toEqual([])`. `maxDistSq` is the caller's, because a
@@ -41,7 +110,9 @@ export declare function recordingContext(): {
  */
 export declare function sweepDrawAgainstHit<C extends {
     count: number;
-}, P>(shape: MarkShape<C, P>, channels: C, block: RenderBlock, frame: MarkFrame, params: P, { maxDistSq, step }: {
+}, 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[];