@jbrowse/render-core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/RenderCanvas.d.ts

@@ -25,7 +25,7 @@ export interface RenderCanvasHandle {
  * render-prop body on the same value for the displays on the chrome, which it
  * does *not* get for free from the `renderError` unmount (that covers only a
  * reported loss — see the `canvasKey` note in useRenderingBackend.ts).
- * GPU_RENDERING.md said so and ended with "any new consumer rendering its own
+ * GPU_DISPLAY_LIFECYCLE.md said so and ended with "any new consumer rendering its own
  * banner must too" — a rule enforced by remembering to read the doc. Rendering
  * the element here makes it structural instead: there is no way to mount this
  * canvas without the key.
@@ -47,11 +47,11 @@ export default function RenderCanvas({ handle, drawn, phase, ...canvasProps }: {
     /**
      * Whether this canvas holds finished content — each view's own `settled`, the
      * same flag its `*_canvas_done` testid is built from. Published as
-     * `data-display-drawn`, which is what `PENDING_DISPLAYS`
+     * `data-display-drawn`, the attribute `PENDING_DISPLAYS`
      * (`@jbrowse/browser-test-utils`) selects on, so these views answer "has
      * everything painted?" with the same attribute every LGV display does.
      *
-     * Required, and that is the point: `PENDING_DISPLAYS` used to name
+     * The prop is required because `PENDING_DISPLAYS` used to name
      * `synteny_canvas` explicitly and simply **forgot dotplot**, so an unpainted
      * dotplot counted as finished and a capture could land on it blank. A new
      * drop-to-primitive view would have been forgotten the same way.

package/esm/RenderCanvas.js

@@ -16,7 +16,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * render-prop body on the same value for the displays on the chrome, which it
  * does *not* get for free from the `renderError` unmount (that covers only a
  * reported loss — see the `canvasKey` note in useRenderingBackend.ts).
- * GPU_RENDERING.md said so and ended with "any new consumer rendering its own
+ * GPU_DISPLAY_LIFECYCLE.md said so and ended with "any new consumer rendering its own
  * banner must too" — a rule enforced by remembering to read the doc. Rendering
  * the element here makes it structural instead: there is no way to mount this
  * canvas without the key.

package/esm/RenderLifecycleMixin.d.ts

@@ -25,6 +25,13 @@ export interface RenderingBackendCallbacks<B> {
      * depend on.
      */
     render: (backend: B) => boolean;
+    /**
+     * Hand back whatever the backend allocated for a canvas that is no longer on
+     * the page. Called after every render tick while the display is off screen,
+     * drawn or not, so it has to be idempotent and must not leave the backend
+     * unable to draw the next frame.
+     */
+    releaseTargets: (backend: B) => void;
 }
 /**
  * Owns the GPU draw lifecycle for any display that paints to a canvas.
@@ -45,9 +52,9 @@ export interface RenderingBackendCallbacks<B> {
  *    recovery. Autoruns read it each tick so they re-fire against the new
  *    one without being reinstalled.
  *  - `renderTick` — counter the render autorun observes; bumped by
- *    `renderNow()` (tab-visibility restore) and after every upload
- *    (ensures render re-fires when an upload happens but renderState
- *    identity stays stable).
+ *    `renderNow()` after every upload that reached the backend, on
+ *    tab-visibility restore, and when a circular ring backend starts. None of
+ *    those is a pan or zoom, so off screen a moved tick means new data.
  *  - `autorunsInstalled` — guards `attachRenderingBackend` so the autorun
  *    pair is spawned once per model instance, not once per backend
  *    assignment.
@@ -64,10 +71,12 @@ export interface RenderingBackendCallbacks<B> {
  */
 export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree").IModelType<{}, {
     canvasDrawn: boolean;
+    paintCount: number;
     currentRenderingBackend: unknown;
     renderTick: number;
     autorunsInstalled: boolean;
     renderError: unknown;
+    offScreen: boolean;
 } & {
     /**
      * #getter
@@ -95,22 +104,21 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * never called and `canvasDrawn` can never flip).
      *
      * Lives here, beside `canvasDrawn`, because every consumer of "has this
-     * display painted" needs the pair — and until 2026-08 each family
-     * declared its own copy (per-region hard-coded `true`, global carried the
-     * hook for LD), so a display could express the state only to whichever
-     * family it happened to compose. See `painted` below for the reader that
-     * was missed.
+     * display painted" needs the pair. Both LGV fetch foundations fill it
+     * with `!fetchInert`, so a display there states its placeholder once,
+     * through that hook; the raw default reaches only a display composing
+     * this mixin outside them. See `painted` below for the reader that was
+     * missed while the two were separate overrides.
      */
     readonly rendersCanvas: boolean;
     /**
      * #getter
      * Overridable hook (default false): the display has reached a state it
      * will not paint its way out of, so `painted` below should answer
-     * *finished* rather than *pending*. Both LGV fetch families fill it with
-     * `!!error` — a fetch that failed before first paint keeps its canvas
-     * mounted, since the error bar is an overlay rather than a subtree
-     * replacement, so nothing ever draws into it. Named for `fetchInert` on
-     * the comparative side.
+     * *finished* rather than *pending*. Both LGV fetch families fill it
+     * through `foundationPaintInert`: a failed fetch, a standing cancel, no
+     * content on screen, or the too-large banner in the canvas's place. Named
+     * for `fetchInert` on the comparative side.
      *
      * A hook rather than a read of `error` here, for two reasons that both
      * bite: this package is a leaf and `error` belongs to the fetch mixins,
@@ -119,13 +127,30 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * and the two families compose the two mixins in opposite orders.
      */
     readonly paintInert: boolean;
+    /**
+     * #getter
+     * Overridable hook (default false): what is on the canvas was painted
+     * from data a later change has made wrong, so `painted` below should
+     * answer *pending* until the repaint lands even though `canvasDrawn` is
+     * still true. The per-region fetch foundation fills it with
+     * `staleSettingsDrawn` — held data drawn under settings that have since
+     * moved — which is the state `clearAllRpcData` used to express by
+     * resetting `canvasDrawn` on every settings change, blanking the display
+     * to do it. A capture waiting on `data-display-drawn` then waits for the
+     * refetch rather than snapshotting the previous setting's pixels.
+     *
+     * A hook and not a reset of the flag, because the flag is re-marked by
+     * any redraw — a pan between the settings change and the refetch would
+     * report the stale canvas drawn — and a derivation cannot be raced.
+     */
+    readonly paintSuperseded: boolean;
 } & {
     /**
      * #getter
      * **The first-paint answer every consumer outside the display should
      * read**, `canvasDrawn` being only the raw flag: a display that is
-     * deliberately not painting a canvas has finished, and saying otherwise
-     * is a lie that never resolves.
+     * deliberately not painting a canvas has finished, and reporting it
+     * unfinished leaves every waiter on it waiting forever.
      *
      * The two `rendersCanvas: false` states each had three of their four
      * consumers wired by hand — the loading scrim (`rendersCanvas` /
@@ -133,14 +158,17 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * while the fourth, `data-display-drawn`, went on publishing `"false"`
      * forever off the raw flag. That attribute is what `PENDING_DISPLAYS`
      * (`@jbrowse/browser-test-utils`) selects on, so a zoomed-out reference
-     * sequence track made every `waitForDisplaysDone` on the page burn its
-     * full timeout — silently, since that wait swallows its own. Same shape
-     * as `fetchInert` on the comparative side: the reader you forget is the
-     * one outside the display, so the display has to publish one name for it.
+     * sequence track made every capture wait on the page run to its
+     * full timeout, and that wait swallows its own timeout without reporting
+     * it. `fetchInert` on the comparative side has the same problem: the
+     * forgotten reader is the one outside the display, so the display has to
+     * publish one name for it.
      *
      * `paintInert` is the third term and the same argument once more, for the
      * state where a display *would* paint a canvas and never gets to — a fetch
-     * that failed before first paint. See that hook.
+     * that failed before first paint. `paintSuperseded` is the fourth, and
+     * the one that subtracts: a canvas painted from data a settings change
+     * has made wrong is drawn and not finished. See both hooks.
      */
     readonly painted: boolean;
 } & {
@@ -160,6 +188,10 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * #action
      */
     renderNow(): void;
+    /**
+     * #action
+     */
+    setOffScreen(offScreen: boolean): void;
     /**
      * #action
      * set/clear the render-backend error. Called by `useRenderingBackend`:

package/esm/RenderLifecycleMixin.js

@@ -19,9 +19,9 @@ import { namedAutorun } from './namedReactions.js';
  *    recovery. Autoruns read it each tick so they re-fire against the new
  *    one without being reinstalled.
  *  - `renderTick` — counter the render autorun observes; bumped by
- *    `renderNow()` (tab-visibility restore) and after every upload
- *    (ensures render re-fires when an upload happens but renderState
- *    identity stays stable).
+ *    `renderNow()` after every upload that reached the backend, on
+ *    tab-visibility restore, and when a circular ring backend starts. None of
+ *    those is a pan or zoom, so off screen a moved tick means new data.
  *  - `autorunsInstalled` — guards `attachRenderingBackend` so the autorun
  *    pair is spawned once per model instance, not once per backend
  *    assignment.
@@ -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.
@@ -74,6 +81,22 @@ export function RenderLifecycleMixin() {
          * the scrim) and by `DisplayChrome` (shows the retry overlay).
          */
         renderError: undefined,
+        /**
+         * #volatile
+         * the display's canvas has scrolled out of the page, so the render
+         * autorun skips pan and zoom redraws, still draws new data, and hands its
+         * GPU targets back after every tick. Written
+         * by `useRenderingBackend`, which watches the canvas element itself —
+         * false everywhere `IntersectionObserver` is absent, which is every unit
+         * test and every non-browser host.
+         *
+         * A whole view that scrolls away is already unmounted
+         * (`useViewVisibility`) and a minimized track never mounts, so what this
+         * covers is the track below the fold of a view that IS mounted: the
+         * display list is not windowed, and each of those tracks holds a
+         * full-height multisampled target.
+         */
+        offScreen: false,
     }))
         .views(() => ({
         /**
@@ -104,11 +127,11 @@ export function RenderLifecycleMixin() {
          * never called and `canvasDrawn` can never flip).
          *
          * Lives here, beside `canvasDrawn`, because every consumer of "has this
-         * display painted" needs the pair — and until 2026-08 each family
-         * declared its own copy (per-region hard-coded `true`, global carried the
-         * hook for LD), so a display could express the state only to whichever
-         * family it happened to compose. See `painted` below for the reader that
-         * was missed.
+         * display painted" needs the pair. Both LGV fetch foundations fill it
+         * with `!fetchInert`, so a display there states its placeholder once,
+         * through that hook; the raw default reaches only a display composing
+         * this mixin outside them. See `painted` below for the reader that was
+         * missed while the two were separate overrides.
          */
         get rendersCanvas() {
             return true;
@@ -117,11 +140,10 @@ export function RenderLifecycleMixin() {
          * #getter
          * Overridable hook (default false): the display has reached a state it
          * will not paint its way out of, so `painted` below should answer
-         * *finished* rather than *pending*. Both LGV fetch families fill it with
-         * `!!error` — a fetch that failed before first paint keeps its canvas
-         * mounted, since the error bar is an overlay rather than a subtree
-         * replacement, so nothing ever draws into it. Named for `fetchInert` on
-         * the comparative side.
+         * *finished* rather than *pending*. Both LGV fetch families fill it
+         * through `foundationPaintInert`: a failed fetch, a standing cancel, no
+         * content on screen, or the too-large banner in the canvas's place. Named
+         * for `fetchInert` on the comparative side.
          *
          * A hook rather than a read of `error` here, for two reasons that both
          * bite: this package is a leaf and `error` belongs to the fetch mixins,
@@ -132,14 +154,33 @@ export function RenderLifecycleMixin() {
         get paintInert() {
             return false;
         },
+        /**
+         * #getter
+         * Overridable hook (default false): what is on the canvas was painted
+         * from data a later change has made wrong, so `painted` below should
+         * answer *pending* until the repaint lands even though `canvasDrawn` is
+         * still true. The per-region fetch foundation fills it with
+         * `staleSettingsDrawn` — held data drawn under settings that have since
+         * moved — which is the state `clearAllRpcData` used to express by
+         * resetting `canvasDrawn` on every settings change, blanking the display
+         * to do it. A capture waiting on `data-display-drawn` then waits for the
+         * refetch rather than snapshotting the previous setting's pixels.
+         *
+         * A hook and not a reset of the flag, because the flag is re-marked by
+         * any redraw — a pan between the settings change and the refetch would
+         * report the stale canvas drawn — and a derivation cannot be raced.
+         */
+        get paintSuperseded() {
+            return false;
+        },
     }))
         .views(self => ({
         /**
          * #getter
          * **The first-paint answer every consumer outside the display should
          * read**, `canvasDrawn` being only the raw flag: a display that is
-         * deliberately not painting a canvas has finished, and saying otherwise
-         * is a lie that never resolves.
+         * deliberately not painting a canvas has finished, and reporting it
+         * unfinished leaves every waiter on it waiting forever.
          *
          * The two `rendersCanvas: false` states each had three of their four
          * consumers wired by hand — the loading scrim (`rendersCanvas` /
@@ -147,17 +188,22 @@ export function RenderLifecycleMixin() {
          * while the fourth, `data-display-drawn`, went on publishing `"false"`
          * forever off the raw flag. That attribute is what `PENDING_DISPLAYS`
          * (`@jbrowse/browser-test-utils`) selects on, so a zoomed-out reference
-         * sequence track made every `waitForDisplaysDone` on the page burn its
-         * full timeout — silently, since that wait swallows its own. Same shape
-         * as `fetchInert` on the comparative side: the reader you forget is the
-         * one outside the display, so the display has to publish one name for it.
+         * sequence track made every capture wait on the page run to its
+         * full timeout, and that wait swallows its own timeout without reporting
+         * it. `fetchInert` on the comparative side has the same problem: the
+         * forgotten reader is the one outside the display, so the display has to
+         * publish one name for it.
          *
          * `paintInert` is the third term and the same argument once more, for the
          * state where a display *would* paint a canvas and never gets to — a fetch
-         * that failed before first paint. See that hook.
+         * that failed before first paint. `paintSuperseded` is the fourth, and
+         * the one that subtracts: a canvas painted from data a settings change
+         * has made wrong is drawn and not finished. See both hooks.
          */
         get painted() {
-            return self.canvasDrawn || !self.rendersCanvas || self.paintInert;
+            return ((self.canvasDrawn && !self.paintSuperseded) ||
+                !self.rendersCanvas ||
+                self.paintInert);
         },
     }))
         .actions(self => ({
@@ -165,6 +211,7 @@ export function RenderLifecycleMixin() {
          * #action
          */
         markCanvasDrawn() {
+            self.paintCount += 1;
             if (!self.canvasDrawn) {
                 self.canvasDrawn = true;
             }
@@ -190,6 +237,14 @@ export function RenderLifecycleMixin() {
         renderNow() {
             self.renderTick += 1;
         },
+        /**
+         * #action
+         */
+        setOffScreen(offScreen) {
+            if (self.offScreen !== offScreen) {
+                self.offScreen = offScreen;
+            }
+        },
         /**
          * #action
          * set/clear the render-backend error. Called by `useRenderingBackend`:
@@ -225,6 +280,7 @@ export function RenderLifecycleMixin() {
             // un-installed and the next backend can try again.
             const cbs = setup();
             self.autorunsInstalled = true;
+            let drawnTick = -1;
             namedAutorun(self, () => {
                 const b = self.currentRenderingBackend;
                 if (b === undefined || !self.canRender) {
@@ -253,7 +309,7 @@ export function RenderLifecycleMixin() {
             }, { name: 'RenderLifecycle:upload' });
             namedAutorun(self, () => {
                 const b = self.currentRenderingBackend;
-                void self.renderTick;
+                const tick = self.renderTick;
                 if (b === undefined || !self.canRender) {
                     return;
                 }
@@ -265,10 +321,20 @@ export function RenderLifecycleMixin() {
                 // Same loop caveat as the upload autorun above: the
                 // unmount-and-dispose that prevents re-fire is DisplayChrome's,
                 // not a shared canvas's.
+                // Off screen, only a re-fire with no `renderNow()` behind it (a
+                // pan, a zoom) is skipped: new data draws wherever the canvas is,
+                // so `painted` never stands over a partial picture. The tick is
+                // recorded even when the render answers false, since Canvas2D
+                // resizes before answering.
                 try {
-                    if (cbs.render(b)) {
+                    const skip = self.offScreen && self.canvasDrawn && tick === drawnTick;
+                    drawnTick = tick;
+                    if (!skip && cbs.render(b)) {
                         self.markCanvasDrawn();
                     }
+                    if (self.offScreen) {
+                        cbs.releaseTargets(b);
+                    }
                 }
                 catch (e) {
                     self.setRenderError(e);

package/esm/canvas2dUtils.d.ts

@@ -109,7 +109,7 @@ export interface ClipContext2D {
  * Clip to one rect, paint, unclip — the `save`/`clip`/`restore` triple with the
  * `restore` in a `finally`.
  *
- * The `finally` is the whole point, and the cost of missing it is not local: an
+ * The `finally` is required, and missing it breaks more than the one frame: an
  * on-screen ctx outlives the frame and `prepareCanvas`'s setTransform/clearRect
  * do **not** reset clip state, so one painter throwing once leaves every later
  * frame drawing through a stale clip. A transient error becomes permanent
@@ -120,8 +120,11 @@ export interface ClipContext2D {
  * own. Reach for this one for the clips *nested inside* a block — a display
  * whose bands each own a horizontal strip of the canvas (alignments clips its
  * coverage, pileup and arc bands separately within one block clip), where the
- * nesting is what makes a hand-rolled pairing easy to get wrong: an early
+ * nesting makes a hand-rolled pairing easy to get wrong: an early
  * `return` inside the band body unbalances the block's `save` too.
+ *
+ * An empty rect paints nothing, as the GPU's empty scissor does; the SVG export
+ * would otherwise record every path of a band nothing can show.
  */
 export declare function withClip(ctx: ClipContext2D, x: number, y: number, w: number, h: number, paint: () => void): void;
 /**
@@ -203,13 +206,62 @@ export declare function strokeRectInside(ctx: {
  * Scalar in, scalar out: runs per feature per frame, so it must not allocate.
  */
 export declare function spanLeft(x1: number, x2: number, width: number): number;
+/**
+ * The `fillRect` x and width a genomic span paints as, given a bare
+ * `makeBpMapper`: `spanLeft`'s pivot and the min-width floor that goes with it,
+ * as one value a painter and its hit box can both read.
+ *
+ * `minWidth` defaults to 0, which makes this plain screen ordering — the
+ * leftmost projected edge and the unsigned distance. Pass a floor and the span
+ * grows away from `startBp`, which is the reversed-block rule `spanLeft` owns:
+ * anchoring the leftmost edge instead slides a sub-pixel mark by up to the floor
+ * on a flipped region and never on a forward one.
+ *
+ * Reach for this over `spanLeft` wherever the *numbers* are wanted rather than a
+ * fill — a hover box, an SVG rect, a cull test, an overlay div — which is where
+ * the pivot and the floor were being restated separately. The multi-row painter
+ * and the hover box it has to line up with each spelled out both.
+ * `fillBpSpan` is the same span when a `fillRect` is the only consumer.
+ *
+ * Not for a per-instance paint loop: this allocates a result per call, so the
+ * span mark's painter and wiggle's two bar loops take `spanLeft` and the two
+ * numbers inline, and stay the last hand-written copies of this arithmetic.
+ */
+export declare function spanRect(toX: (bp: number) => number, startBp: number, endBp: number, minWidth?: number): {
+    left: number;
+    width: number;
+};
 export declare function makeRampFillStyleLut(ramp: Uint8Array): (t: number) => string;
-export declare function bpToScreenPx(absBp: number, regionStart: number, regionEnd: number, screenStartPx: number, screenEndPx: number, reversed?: boolean): number;
+/**
+ * A block's bp→px projection as four numbers, for a placement function reading
+ * its block off a frame object. `makeBpMapper` closes over the same four.
+ */
+export interface BpProjection {
+    originPx: number;
+    startBp: number;
+    spanBp: number;
+    signedSpanPx: number;
+}
+export declare function bpProjection(bounds: BpRegionBounds): BpProjection;
+export declare function projectBp(p: BpProjection, bp: number): number;
+/**
+ * One closure literal for both orientations. Split per orientation, a paint
+ * loop's mapper call goes megamorphic on a view mixing them, and the loop ran
+ * 1.9-2.3x slower (`benches/bpMapper.bench.ts`).
+ */
 export declare function makeBpMapper(bounds: BpRegionBounds): (bp: number) => number;
 /**
- * Left edge of the **1bp cell** covering `bp` — for painters that fill a rect
- * per base (MAF alignment cells, the alignments pileup's mismatch /
- * modification / per-base quality+letter / soft-clip base layers).
+ * Screen px one base occupies in this region: the scale factor, unsigned, with
+ * the block's direction left to `makeBpMapper` and `spanLeft`. Shared so a mark
+ * sized against it in a draw pass and hit-tested against it in a component
+ * read one number.
+ */
+export declare function pxPerBpOf(bounds: BpRegionBounds): number;
+/**
+ * Left edge of the **1bp cell** covering `bp`, for a painter filling a rect
+ * exactly one base wide. A cell floored wider than its base grows from the
+ * base's low-coordinate edge instead, leftward on a reversed block, as the
+ * alignments pileup's `cellPlacement` does.
  *
  * Use this, not `makeBpMapper`, whenever the mark is a cell rather than a point
  * or a two-edge span. `makeBpMapper(bp)` is the cell's left edge only on a
@@ -226,22 +278,7 @@ export declare function makeBpMapper(bounds: BpRegionBounds): (bp: number) => nu
  * `bpToClipX(pos)`→`bpToClipX(pos+1)` unflipped and mirror via `flipX` — and
  * gets its own pivot from `writeBpRangeUniforms`.
  *
- * Callers own the cell *width*: it's a per-plugin rule (MAF uses the raw
- * bp-scale; the pileup floors at 1px and adds a seam fudge). Only the pivot is
- * shared.
- */
-/**
- * Screen px one base occupies in this region — the scale factor, unsigned, with
- * the block's direction deliberately left out (that lives in `makeBpMapper` and
- * `spanLeft`, and folding it in here would make a *scale* carry an orientation).
- *
- * Shared because it is usually an input to something a second painter has to
- * reproduce exactly: a mark sized against it in a draw pass and hit-tested
- * against it in a component is two spellings of one number, and the hit target
- * silently stops covering the mark if they ever drift. Trivial arithmetic, but
- * the drift is not.
  */
-export declare function pxPerBpOf(bounds: BpRegionBounds): number;
 export declare function makeCellLeftMapper(bounds: BpRegionBounds): (bp: number) => number;
 /**
  * Fill the rect covering genomic `[startBp, endBp)`, given a bare
@@ -251,7 +288,7 @@ export declare function makeCellLeftMapper(bounds: BpRegionBounds): (bp: number)
  *
  * Prefer this to `makeCellLeftMapper` + a caller-computed width for anything
  * wider than one base. The pivot in `makeCellLeftMapper` is exactly one base,
- * which is right for a 1bp cell and silently wrong for an N-bp span — it
+ * which is right for a 1bp cell and wrong for an N-bp span — it
  * anchors the rect one base from the correct edge and then grows it the wrong
  * way. `fillBpSpan(bp, bp + 1)` is *identical* to the cell-mapper spelling, so
  * a per-base painter can use this too and never think about orientation again.
@@ -308,7 +345,7 @@ export declare function fillBpSpan(ctx: {
  * `14468.9936` — and rounding the *offset* and then adding such an anchor
  * returns the anchor's fraction untouched. The result is then not a base at
  * all, and every caller that indexes one by equality (a mismatch column, a
- * coverage bin, the sort-at-this-column anchor) misses silently: the pileup
+ * coverage bin, the sort-at-this-column anchor) finds no match: the pileup
  * offered no SNP submenu over a mismatch it was drawing. Rounding
  * `whole + fraction + offset` in one step instead fixes that and hands back the
  * genome-scale addend the paragraph above exists to keep out, so the whole base
@@ -370,3 +407,33 @@ export declare function regionAtPixel<R extends {
     screenStartPx: number;
     screenEndPx: number;
 }>(regions: readonly R[], px: number): R | undefined;
+/**
+ * CSS px a Canvas2D painter adds to the drawn width of a rect whose neighbours
+ * abut it. `fillRect` antialiases each edge on its own, so two rects meeting on
+ * a fractional column each take partial coverage of it and a hairline of
+ * background shows through; abutting GPU quads share an exact clip-space edge
+ * and the rasterizer fills it once, so a shader grows no matching pad.
+ */
+export declare const CANVAS_SEAM_PX = 0.8;
+export interface PathPaintContext {
+    beginPath(): void;
+    fill(): void;
+    stroke(): void;
+}
+/**
+ * One batched Canvas2D path of many shapes, painted in pieces a browser will
+ * rasterize. Opens a path on construction; call `add()` before appending each
+ * shape and `flush()` to paint what it holds and reopen.
+ */
+export declare class CappedPath {
+    private shapes;
+    private readonly ctx;
+    private readonly paint;
+    constructor(ctx: PathPaintContext, paint: 'fill' | 'stroke');
+    /**
+     * True when the path was full and has been painted and reopened, so a
+     * polyline must `moveTo` its pen again.
+     */
+    add(): boolean;
+    flush(): void;
+}