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

package/esm/marks/drawAgainstHit.js

@@ -1,10 +1,13 @@
+import { inkOnRect, shapeHitNearest } from './markHit.js';
+const IDENTITY = [1, 0, 0, 1, 0, 0];
 /**
- * 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
@@ -13,34 +16,121 @@
  * 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 function recordingContext() {
     const calls = [];
     const points = [];
     const edges = [];
+    let m = [...IDENTITY];
+    const stack = [];
+    const px = (x, y) => m[0] * x + m[2] * y + m[4];
+    const py = (x, y) => m[1] * x + m[3] * y + m[5];
+    const pushPoint = (x, y) => {
+        points.push([px(x, y), py(x, y)]);
+    };
+    // The transformed box of an axis-aligned rect. An axis-aligned CTM scales the
+    // extents directly rather than differencing two mapped corners, so an
+    // untranslated rect records the width the painter asked for and not a value
+    // one ulp off it; only a rotation falls back to the four-corner hull.
+    const boxOf = (x, y, w, h) => {
+        if (m[1] === 0 && m[2] === 0) {
+            const x0 = px(x, y);
+            const y0 = py(x, y);
+            const dx = m[0] * w;
+            const dy = m[3] * h;
+            return {
+                x: Math.min(x0, x0 + dx),
+                y: Math.min(y0, y0 + dy),
+                w: Math.abs(dx),
+                h: Math.abs(dy),
+            };
+        }
+        const xs = [px(x, y), px(x + w, y), px(x, y + h), px(x + w, y + h)];
+        const ys = [py(x, y), py(x + w, y), py(x, y + h), py(x + w, y + h)];
+        const left = Math.min(...xs);
+        const top = Math.min(...ys);
+        return {
+            x: left,
+            y: top,
+            w: Math.max(...xs) - left,
+            h: Math.max(...ys) - top,
+        };
+    };
     const ctx = {
         fillStyle: '',
         strokeStyle: '',
         lineWidth: 1,
         lineCap: 'butt',
-        save() { },
-        restore() { },
+        lineJoin: 'miter',
+        save() {
+            const { fillStyle, strokeStyle, lineWidth, lineCap } = this;
+            stack.push({ m: [...m], fillStyle, strokeStyle, lineWidth, lineCap });
+        },
+        restore() {
+            const saved = stack.pop();
+            if (saved) {
+                m = saved.m;
+                this.fillStyle = saved.fillStyle;
+                this.strokeStyle = saved.strokeStyle;
+                this.lineWidth = saved.lineWidth;
+                this.lineCap = saved.lineCap;
+            }
+        },
+        translate(x, y) {
+            m = [m[0], m[1], m[2], m[3], px(x, y), py(x, y)];
+        },
+        scale(x, y) {
+            m = [m[0] * x, m[1] * x, m[2] * y, m[3] * y, m[4], m[5]];
+        },
+        rotate(angle) {
+            const c = Math.cos(angle);
+            const s = Math.sin(angle);
+            m = [
+                m[0] * c + m[2] * s,
+                m[1] * c + m[3] * s,
+                m[2] * c - m[0] * s,
+                m[3] * c - m[1] * s,
+                m[4],
+                m[5],
+            ];
+        },
         beginPath() {
             points.length = 0;
             edges.length = 0;
         },
         clip() { },
+        setLineDash() { },
         moveTo(x, y) {
-            points.push([x, y]);
+            pushPoint(x, y);
         },
         lineTo(x, y) {
             const from = points.at(-1);
+            pushPoint(x, y);
+            const to = points.at(-1);
             if (from) {
-                edges.push([from[0], from[1], x, y]);
+                edges.push([from[0], from[1], to[0], to[1]]);
             }
-            points.push([x, y]);
         },
-        arc() { },
+        bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) {
+            pushPoint(cp1x, cp1y);
+            pushPoint(cp2x, cp2y);
+            pushPoint(x, y);
+        },
+        arc(x, y, radius) {
+            pushPoint(x - radius, y - radius);
+            pushPoint(x + radius, y + radius);
+        },
+        ellipse(x, y, radiusX, radiusY) {
+            pushPoint(x - radiusX, y - radiusY);
+            pushPoint(x + radiusX, y + radiusY);
+        },
         closePath() { },
         fill() {
             if (points.length > 0) {
@@ -76,57 +166,189 @@ export function recordingContext() {
             edges.length = 0;
         },
         rect(x, y, w, h) {
-            calls.push({ x, y, w, h, fillStyle: this.fillStyle });
+            calls.push({ ...boxOf(x, y, w, h), fillStyle: this.fillStyle });
         },
         fillRect(x, y, w, h) {
-            calls.push({ x, y, w, h, fillStyle: this.fillStyle });
+            calls.push({ ...boxOf(x, y, w, h), fillStyle: this.fillStyle });
+        },
+        strokeRect(x, y, w, h) {
+            const half = this.lineWidth / 2;
+            const box = boxOf(x, y, w, h);
+            calls.push({
+                x: box.x - half,
+                y: box.y - half,
+                w: box.w + this.lineWidth,
+                h: box.h + this.lineWidth,
+                fillStyle: this.strokeStyle,
+            });
         },
     };
-    return { ctx: ctx, calls };
+    return { ctx, calls };
+}
+function contains(r, x, y, slack = 0) {
+    return (x >= r.x - slack &&
+        x <= r.x + r.w + slack &&
+        y >= r.y - slack &&
+        y <= r.y + r.h + slack);
 }
-function contains(r, x, y) {
-    return x >= r.x && x <= r.x + r.w && y >= r.y && y <= r.y + r.h;
+function unionBox(rs) {
+    let box;
+    for (const r of rs) {
+        box = box
+            ? {
+                x: Math.min(box.x, r.x),
+                y: Math.min(box.y, r.y),
+                w: Math.max(box.x + box.w, r.x + r.w) - Math.min(box.x, r.x),
+                h: Math.max(box.y + box.h, r.y + r.h) - Math.min(box.y, r.y),
+            }
+            : { x: r.x, y: r.y, w: r.w, h: r.h };
+    }
+    return box;
 }
+// The float slack the two distance comparisons take. Both sides are px
+// arithmetic over the same projection, so a real disagreement is orders of
+// magnitude above this and a rounding one is below it.
+const EPS = 1e-9;
 /**
- * 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
  * shape whose hit target is wider than its ink (`point`) needs a bound that
  * admits the whole rect.
  */
-export function sweepDrawAgainstHit(shape, channels, block, frame, params, { maxDistSq, step = 0.5 }) {
+export function sweepDrawAgainstHit(shape, channels, block, frame, params, { maxDistSq, step = 0.5, sliceOne, inkSlackPx = 1, }) {
+    const { count } = channels;
     const violations = [];
-    const { ctx, calls: rects } = recordingContext();
-    shape.paintBlock(ctx, channels, block, frame, params);
-    if (rects.length !== channels.count) {
-        return [`painted ${rects.length} rects for ${channels.count} instances`];
+    const paint = (c) => {
+        const { ctx, calls } = recordingContext();
+        shape.paintBlock(ctx, c, block, frame, params);
+        return calls;
+    };
+    const rects = paint(channels);
+    // Positional attribution, and the licence for the containment claim below.
+    const perRect = rects.length === count;
+    if (!perRect && !sliceOne) {
+        return [`painted ${rects.length} rects for ${count} instances`];
+    }
+    const boxes = sliceOne
+        ? Array.from({ length: count }, (_, i) => unionBox(paint(sliceOne(channels, i))))
+        : rects.map(r => ({ x: r.x, y: r.y, w: r.w, h: r.h }));
+    if (shape.ink) {
+        for (let i = 0; i < count; i++) {
+            const r = shape.ink(channels, block, frame, params, i);
+            const b = boxes[i];
+            if (r && !b) {
+                violations.push(`${i} painted nothing but has ink`);
+            }
+            else if (b && !r) {
+                violations.push(`${i} painted but has no ink`);
+            }
+            else if (b && r) {
+                const gaps = [
+                    b.x - r.left,
+                    r.left + r.width - (b.x + b.w),
+                    b.y - r.top,
+                    r.top + r.height - (b.y + b.h),
+                ];
+                if (gaps.some(g => g < -EPS)) {
+                    violations.push(`${i} painted (${b.x}, ${b.y}, ${b.w}, ${b.h}) outside its ink (${r.left}, ${r.top}, ${r.width}, ${r.height})`);
+                }
+                else if (gaps.some(g => g > inkSlackPx + EPS)) {
+                    violations.push(`${i}'s ink (${r.left}, ${r.top}, ${r.width}, ${r.height}) is more than ${inkSlackPx}px outside its painting (${b.x}, ${b.y}, ${b.w}, ${b.h})`);
+                }
+            }
+            if (violations.length >= 10) {
+                return violations;
+            }
+        }
     }
-    const candidates = Array.from({ length: channels.count }, (_, k) => channels.count - 1 - k);
+    const hitNearest = shapeHitNearest(shape);
+    if (!hitNearest) {
+        return [`${shape.id} has no hit test`];
+    }
+    const candidates = Array.from({ length: count }, (_, k) => count - 1 - k);
     let yMin = Infinity;
     let yMax = -Infinity;
-    for (const r of rects) {
-        yMin = Math.min(yMin, r.y);
-        yMax = Math.max(yMax, r.y + r.h);
+    for (const b of boxes) {
+        if (b) {
+            yMin = Math.min(yMin, b.y);
+            yMax = Math.max(yMax, b.y + b.h);
+        }
+    }
+    if (yMin === Infinity) {
+        return [`painted nothing for ${count} instances`];
     }
     const x0 = Math.min(block.screenStartPx, block.screenEndPx) - 1;
     const x1 = Math.max(block.screenStartPx, block.screenEndPx) + 1;
     for (let y = Math.floor(yMin) - 1; y <= yMax + 1; y += step) {
         for (let x = x0; x <= x1; x += step) {
             let expected = -1;
-            for (let k = rects.length - 1; k >= 0; k--) {
-                if (contains(rects[k], x, y)) {
-                    expected = k;
-                    break;
+            if (perRect) {
+                for (let k = count - 1; k >= 0; k--) {
+                    if (contains(boxes[k], x, y)) {
+                        expected = k;
+                        break;
+                    }
                 }
             }
-            const hit = shape.hitNearest(channels, block, frame, params, x, y, candidates, maxDistSq);
-            if (hit && hit.distSq === 0 && !contains(rects[hit.index], x, y)) {
-                violations.push(`(${x}, ${y}) answered ${hit.index} at distance 0, off its rect`);
+            const hit = hitNearest(channels, block, frame, params, x, y, candidates, maxDistSq);
+            const box = hit && boxes[hit.index];
+            if (hit && !box) {
+                violations.push(`(${x}, ${y}) answered ${hit.index}, which painted nothing`);
+            }
+            else if (hit && box) {
+                if (!contains(box, hit.x, hit.y, EPS)) {
+                    violations.push(`(${x}, ${y}) answered ${hit.index} with ink at (${hit.x}, ${hit.y}), off its painting`);
+                }
+                const toBox = inkOnRect(x, y, box.x, box.y, box.w, box.h).distSq;
+                if (hit.distSq < toBox - EPS) {
+                    violations.push(`(${x}, ${y}) answered ${hit.index} at ${hit.distSq}, nearer than its painting (${toBox})`);
+                }
+                const toPoint = (x - hit.x) ** 2 + (y - hit.y) ** 2;
+                if (Math.abs(hit.distSq - toPoint) > EPS * Math.max(1, toPoint)) {
+                    violations.push(`(${x}, ${y}) answered ${hit.index} at ${hit.distSq}, which is not the distance to the ink it named (${toPoint})`);
+                }
             }
             if (expected !== -1 && hit?.index !== expected) {
                 violations.push(`(${x}, ${y}) is on rect ${expected}, answered ${hit?.index ?? 'nothing'}`);

package/esm/marks/glyphPaint.d.ts

@@ -1,4 +1,6 @@
-import type { MarkContext2D } from './types.ts';
+import type { InkRect, MarkContext2D } from './types.ts';
+/** The path calls a glyph is built from — what a recorder has to answer. */
+export type GlyphPath = Pick<MarkContext2D, 'moveTo' | 'lineTo' | 'closePath' | 'rect' | 'arc'>;
 /**
  * Append one of the `point` shape's glyphs to the current path, centred on
  * `(cx, y)`.
@@ -13,4 +15,10 @@ import type { MarkContext2D } from './types.ts';
  * hand that consumer the shader's WGSL and GLSL strings. Wiggle's scatter mode
  * is that consumer.
  */
-export declare function appendGlyph(ctx: MarkContext2D, glyph: number, cx: number, y: number, diameter: number): void;
+export declare function appendGlyph(ctx: GlyphPath, glyph: number, cx: number, y: number, diameter: number): void;
+/**
+ * The box `appendGlyph` paints inside, by the same split and snap: the
+ * diamond is scaled by `DIAMOND_GLYPH_SCALE` and the small square snaps to
+ * the pixel grid, so neither is the diameter about the centre.
+ */
+export declare function glyphBox(glyph: number, cx: number, y: number, diameter: number): InkRect;

package/esm/marks/glyphPaint.js

@@ -39,3 +39,24 @@ export function appendGlyph(ctx, glyph, cx, y, diameter) {
         ctx.arc(cx, y, r, 0, Math.PI * 2);
     }
 }
+/**
+ * The box `appendGlyph` paints inside, by the same split and snap: the
+ * diamond is scaled by `DIAMOND_GLYPH_SCALE` and the small square snaps to
+ * the pixel grid, so neither is the diameter about the centre.
+ */
+export function glyphBox(glyph, cx, y, diameter) {
+    const r = diameter / 2;
+    if (glyph === GLYPH_DIAMOND) {
+        const ri = r * DIAMOND_GLYPH_SCALE;
+        return { left: cx - ri, top: y - ri, width: 2 * ri, height: 2 * ri };
+    }
+    if (glyph !== GLYPH_TRIANGLE && diameter <= SMALL_POINT_MAX_DIAMETER) {
+        return {
+            left: crispSquareTopLeftPx(cx, diameter),
+            top: crispSquareTopLeftPx(y, diameter),
+            width: diameter,
+            height: diameter,
+        };
+    }
+    return { left: cx - r, top: y - r, width: diameter, height: diameter };
+}

package/esm/marks/index.d.ts

@@ -1,9 +1,16 @@
 export { defineMark } from './types.ts';
 export { paintMarkBlocks } from './markPaint.ts';
+export { planMarks } from './markPlan.ts';
+export { inkOfInstances } from './markInk.ts';
+export { barMark } from './barMark.ts';
 export { pointMark } from './pointMark.ts';
-export { spanMark } from './spanMark.ts';
+export { blockPx, spanMark } from './spanMark.ts';
 export { appendGlyph } from './glyphPaint.ts';
 export { abgrToCssRgba, makeAbgrFill } from './colorFill.ts';
-export type { Mark, MarkBand, MarkContext2D, MarkFrame, MarkHit, MarkShape, StagedUniforms, } from './types.ts';
+export type { MarkPlan } from './markPlan.ts';
+export type { MarkInstance } from './markInk.ts';
+export type { Mark, MarkBand, MarkContext2D, MarkFrame, MarkImage, MarkRamp, MarkTexture, MarkValueScaleType, InkRect, MarkHit, MarkShape, PlannedPass, StagedUniforms, } from './types.ts';
+export type { BarChannels, BarParams } from './barMark.ts';
 export type { PointChannels, PointParams } from './pointMark.ts';
 export type { SpanChannels, SpanParams } from './spanMark.ts';
+export type { ColorChannel } from './markRamp.ts';

package/esm/marks/index.js

@@ -1,6 +1,9 @@
 export { defineMark } from './types.js';
 export { paintMarkBlocks } from './markPaint.js';
+export { planMarks } from './markPlan.js';
+export { inkOfInstances } from './markInk.js';
+export { barMark } from './barMark.js';
 export { pointMark } from './pointMark.js';
-export { spanMark } from './spanMark.js';
+export { blockPx, spanMark } from './spanMark.js';
 export { appendGlyph } from './glyphPaint.js';
 export { abgrToCssRgba, makeAbgrFill } from './colorFill.js';

package/esm/marks/markBackend.d.ts

@@ -6,13 +6,9 @@ import type { InstancePass } from '../instancePass.ts';
 import type { ClearColor, PerRegionRenderingBackend } from '../perRegionRenderingBackend.ts';
 import type { RenderBlock } from '../renderBlock.ts';
 import type { FrameDimensions } from '../renderingBackendBase.ts';
+import type { MarkPlan } from './markPlan.ts';
 import type { Mark } from './types.ts';
-/**
- * Pack and upload one region's buffers for a mark list — every mark that owns
- * one, which is the whole list minus those drawing off another's (`bufferOf`).
- * That skip is the reason a display's upload is this call rather than a loop:
- * uploading to a borrowed pass is silent, and its buffer is the lender's.
- */
+/** Pack and upload one region's buffers for a mark list. */
 export declare function uploadMarks<TRegion, TState extends FrameDimensions>(hal: GpuHal, regionKey: number, marks: readonly Mark<TRegion, TState>[], data: TRegion): void;
 /**
  * Draw one already-clipped block through a mark list.
@@ -23,8 +19,25 @@ export declare function uploadMarks<TRegion, TState extends FrameDimensions>(hal
  * coverage strip inside the column it hands over. `GpuPerRegionRenderingBackend`
  * sets both per block already, so for a backend on that scaffold the viewport
  * set here is the same rect twice.
+ *
+ * A caller that narrows it must hand over marks declaring no `band`, and that
+ * is the one way the two clips do not compose: a banded mark scissors to its
+ * strip and hands the BLOCK COLUMN back rather than what the caller had. The
+ * split is deliberate — `render-core/CLAUDE.md` §Drawing has which displays
+ * take which side — but nothing enforces it, so it is stated at both.
  */
 export declare function drawMarks<TRegion, TState extends FrameDimensions>(hal: GpuHal, scratch: ArrayBuffer, marks: readonly Mark<TRegion, TState>[], block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState, regionKey: number): void;
+/**
+ * Draw one block's planned passes off the uniforms the caller has already
+ * staged for it. No gate, no lens, no write: `planMarks` settled the frame
+ * question and the caller's own `hal.writeUniforms` settled the block's, so
+ * what is left per mark is the `drawPass` — the loop a display with its own
+ * frame scaffold was already running over a hand-kept pass list.
+ *
+ * Viewport and scissor are the caller's, as with `drawMarks`' scissor: a
+ * plan's marks declare no `band`, so nothing here narrows or restores either.
+ */
+export declare function drawPlannedPasses(hal: GpuHal, plan: Pick<MarkPlan<never, never>, 'passes'>, regionKey: number): void;
 /**
  * The HAL-side half of `createMarkBackend`, exported so a display's mark list
  * can be driven against `MockHal`: which marks upload, which draw off another's
@@ -36,9 +49,8 @@ export declare class GpuMarkBackend<TRegion, TState extends FrameDimensions> ext
     protected regionPasses: InstancePass<TRegion>[];
     constructor(hal: GpuHal, marks: readonly Mark<TRegion, TState>[], clear?: ((state: TState) => ClearColor) | undefined);
     protected clearColor(state: TState): ClearColor;
-    upload(regionKey: number, data: TRegion): void;
-    private boundRamps;
-    private bindRamp;
+    private boundTextures;
+    private bindTexture;
     protected drawRegion(block: RenderBlock, clip: BlockClipResult, region: TRegion, state: TState): void;
 }
 /**

package/esm/marks/markBackend.js

@@ -3,17 +3,17 @@ import { createRenderingBackend } from '../createRenderingBackend.js';
 import { uploadPass } from '../instancePass.js';
 import { Canvas2DPerRegionRenderingBackend, GpuPerRegionRenderingBackend, } from '../perRegionRenderingBackend.js';
 import { paintMarkBlocks } from './markPaint.js';
-/**
- * Pack and upload one region's buffers for a mark list — every mark that owns
- * one, which is the whole list minus those drawing off another's (`bufferOf`).
- * That skip is the reason a display's upload is this call rather than a loop:
- * uploading to a borrowed pass is silent, and its buffer is the lender's.
- */
+// The passes a mark list owns a buffer for: the whole list minus those drawing
+// off another's (`bufferOf`). Uploading to a borrowed pass is silent and its
+// buffer is the lender's, so the skip is stated once, here — module-local,
+// because `marks/backend` is a published subpath and nothing outside wants it.
+function ownedPasses(marks) {
+    return marks.filter(m => !m.bufferOf).map(m => m.pass);
+}
+/** Pack and upload one region's buffers for a mark list. */
 export function uploadMarks(hal, regionKey, marks, data) {
-    for (const mark of marks) {
-        if (!mark.bufferOf) {
-            uploadPass(hal, regionKey, mark.pass, data);
-        }
+    for (const pass of ownedPasses(marks)) {
+        uploadPass(hal, regionKey, pass, data);
     }
 }
 /**
@@ -25,6 +25,12 @@ export function uploadMarks(hal, regionKey, marks, data) {
  * coverage strip inside the column it hands over. `GpuPerRegionRenderingBackend`
  * sets both per block already, so for a backend on that scaffold the viewport
  * set here is the same rect twice.
+ *
+ * A caller that narrows it must hand over marks declaring no `band`, and that
+ * is the one way the two clips do not compose: a banded mark scissors to its
+ * strip and hands the BLOCK COLUMN back rather than what the caller had. The
+ * split is deliberate — `render-core/CLAUDE.md` §Drawing has which displays
+ * take which side — but nothing enforces it, so it is stated at both.
  */
 export function drawMarks(hal, scratch, marks, block, clip, region, state, regionKey) {
     hal.setViewport(clip.pxX, 0, clip.pxW, clip.pxH);
@@ -34,9 +40,28 @@ export function drawMarks(hal, scratch, marks, block, clip, region, state, regio
         mark.drawRegion(hal, scratch, block, clip, region, state, regionKey, staged);
     }
 }
+/**
+ * Draw one block's planned passes off the uniforms the caller has already
+ * staged for it. No gate, no lens, no write: `planMarks` settled the frame
+ * question and the caller's own `hal.writeUniforms` settled the block's, so
+ * what is left per mark is the `drawPass` — the loop a display with its own
+ * frame scaffold was already running over a hand-kept pass list.
+ *
+ * Viewport and scissor are the caller's, as with `drawMarks`' scissor: a
+ * plan's marks declare no `band`, so nothing here narrows or restores either.
+ */
+export function drawPlannedPasses(hal, plan, regionKey) {
+    const { passes } = plan;
+    for (let i = 0; i < passes.length; i++) {
+        const pass = passes[i];
+        hal.drawPass(pass.id, regionKey, pass.bufferOf);
+    }
+}
 // What a textured pass binds while its mark names no ramp: a shader declares
 // its sampler unconditionally, and a textured pass with no texture never draws
-// on the WebGPU HAL.
+// on the WebGPU HAL. A mark declaring no `texture` at all is the same case —
+// `pointMark` carries a sampler for the shapes that ramp, and Manhattan draws
+// it without one.
 const INERT_RAMP = new Uint8Array(COLOR_RAMP_LUT_ENTRIES * 4);
 /**
  * The HAL-side half of `createMarkBackend`, exported so a display's mark list
@@ -46,37 +71,46 @@ const INERT_RAMP = new Uint8Array(COLOR_RAMP_LUT_ENTRIES * 4);
 export class GpuMarkBackend extends GpuPerRegionRenderingBackend {
     marks;
     clear;
-    // `upload` runs `uploadMarks` in place of the base's loop, so nothing reads
-    // this — the `bufferOf` skip is stated once, there
-    regionPasses = [];
+    // The base's upload loop already IS the mark walk, so this backend names its
+    // passes instead of overriding `upload` with a second spelling of it.
+    regionPasses;
     constructor(hal, marks, clear) {
         super(hal);
         this.marks = marks;
         this.clear = clear;
+        this.regionPasses = ownedPasses(marks);
     }
     clearColor(state) {
         return this.clear ? this.clear(state) : super.clearColor(state);
     }
-    upload(regionKey, data) {
-        uploadMarks(this.hal, regionKey, this.marks, data);
-    }
-    // The ramp each textured pass holds, by the table's identity — the mirror of
-    // the one texture the HAL keeps per pass, so an unchanged ramp costs a frame
-    // nothing and a backend rebuilt after context loss re-uploads. Per pass and
-    // per backend, never per region.
-    boundRamps = new Map();
-    bindRamp(mark, region, state) {
-        if (mark.texture) {
-            const ramp = mark.texture(state, region) ?? INERT_RAMP;
-            if (ramp !== this.boundRamps.get(mark.pass.id)) {
-                uploadColorRampLut(this.hal, ramp, [mark.pass.id]);
-                this.boundRamps.set(mark.pass.id, ramp);
+    // The texture each textured pass holds, by identity — the mirror of the one
+    // texture the HAL keeps per pass, so an unchanged ramp or strip costs a
+    // frame nothing and a backend rebuilt after context loss re-uploads. Per
+    // pass and per backend, never per region. A lens answering nothing for a
+    // region leaves the pass's texture where it is, and binds the inert table
+    // only while the pass has none at all: a ring canvas draws one region per
+    // pass, and a lens with no opinion on the other regions must not swap the
+    // strip out and back on every frame.
+    boundTextures = new Map();
+    bindTexture(mark, region, state) {
+        if (mark.pass.textures) {
+            const bound = this.boundTextures.get(mark.pass.id);
+            const texture = mark.texture?.(state, region) ?? bound ?? INERT_RAMP;
+            if (texture !== bound) {
+                if (texture instanceof Uint8Array) {
+                    uploadColorRampLut(this.hal, texture, [mark.pass.id]);
+                }
+                else {
+                    const { image, width, height } = texture;
+                    this.hal.uploadTexture(mark.pass.id, image, width, height);
+                }
+                this.boundTextures.set(mark.pass.id, texture);
             }
         }
     }
     drawRegion(block, clip, region, state) {
         for (const mark of this.marks) {
-            this.bindRamp(mark, region, state);
+            this.bindTexture(mark, region, state);
         }
         drawMarks(this.hal, this.uniformData, this.marks, block, clip, region, state, block.displayedRegionIndex);
     }