@jbrowse/render-core 4.3.0 → 5.0.0-beta.10

package/esm/canvas2dUtils.js

@@ -216,7 +216,7 @@ export function clipBlockForCanvas(block, canvasWidth) {
  * 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
@@ -227,10 +227,16 @@ export function clipBlockForCanvas(block, canvasWidth) {
  * 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 function withClip(ctx, x, y, w, h, paint) {
+    if (w <= 0 || h <= 0) {
+        return;
+    }
     ctx.save();
     ctx.beginPath();
     ctx.rect(x, y, w, h);
@@ -334,6 +340,33 @@ export function strokeRectInside(ctx, x, y, w, h, lineWidth = 1) {
 export function spanLeft(x1, x2, width) {
     return x2 < x1 ? x1 - width : x1;
 }
+/**
+ * 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 function spanRect(toX, startBp, endBp, minWidth = 0) {
+    const x1 = toX(startBp);
+    const x2 = toX(endBp);
+    const width = Math.max(minWidth, Math.abs(x2 - x1));
+    return { left: spanLeft(x1, x2, width), width };
+}
 // Quantize a 0..1 ramp position to a 256-entry index. Shared so the direct
 // lookup and the fillStyle LUT below can't quantize differently — a half-step
 // of drift between them shows up as a one-shade mismatch between a cell's fill
@@ -359,26 +392,42 @@ export function makeRampFillStyleLut(ramp) {
         return s;
     };
 }
-export function bpToScreenPx(absBp, regionStart, regionEnd, screenStartPx, screenEndPx, reversed) {
-    const frac = (absBp - regionStart) / (regionEnd - regionStart);
+export function bpProjection(bounds) {
+    const { start, end, screenStartPx, screenEndPx, reversed } = bounds;
     const w = screenEndPx - screenStartPx;
-    return reversed ? screenEndPx - frac * w : screenStartPx + frac * w;
+    return {
+        originPx: reversed ? screenEndPx : screenStartPx,
+        startBp: start,
+        spanBp: end - start,
+        signedSpanPx: reversed ? -w : w,
+    };
 }
-// Closure-style bp→screen-px mapper bound to one region. Consumers that walk
-// many bp positions inside one block (label/peptide overlays, rect/line draws)
-// want a 1-arg call instead of repeating 6 args at every site.
+export function projectBp(p, bp) {
+    return p.originPx + ((bp - p.startBp) / p.spanBp) * p.signedSpanPx;
+}
+/**
+ * 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 function makeBpMapper(bounds) {
-    const { start, end, screenStartPx, screenEndPx, reversed } = bounds;
-    const span = end - start;
-    const w = screenEndPx - screenStartPx;
-    return reversed
-        ? (bp) => screenEndPx - ((bp - start) / span) * w
-        : (bp) => screenStartPx + ((bp - start) / span) * w;
+    const { originPx, startBp, spanBp, signedSpanPx } = bpProjection(bounds);
+    return (bp) => originPx + ((bp - startBp) / spanBp) * signedSpanPx;
+}
+/**
+ * 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 function pxPerBpOf(bounds) {
+    return ((bounds.screenEndPx - bounds.screenStartPx) / (bounds.end - bounds.start));
 }
 /**
- * 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).
+ * 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
@@ -395,24 +444,7 @@ export function makeBpMapper(bounds) {
  * `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 function pxPerBpOf(bounds) {
-    return ((bounds.screenEndPx - bounds.screenStartPx) / (bounds.end - bounds.start));
-}
 export function makeCellLeftMapper(bounds) {
     const toX = makeBpMapper(bounds);
     const pxPerBp = pxPerBpOf(bounds);
@@ -429,7 +461,7 @@ export function makeCellLeftMapper(bounds) {
  *
  * 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.
@@ -488,7 +520,7 @@ export function fillBpSpan(ctx, toX, startBp, endBp, top, height, seam = 0) {
  * `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
@@ -562,3 +594,54 @@ export function bpAtPxExact(px, bounds) {
 export function regionAtPixel(regions, px) {
     return regions.find(r => px >= r.screenStartPx && px < r.screenEndPx);
 }
+/**
+ * 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 const CANVAS_SEAM_PX = 0.8;
+/**
+ * Shapes a `CappedPath` holds before it paints and reopens. Chrome's
+ * GPU-rasterized canvas, which is desktop Chrome with a GPU and headless Chrome
+ * with the GPU blocklist off, silently paints nothing for a path past about
+ * 16 MiB: 180,000 discs, 453,000 rects or 931,000 line segments.
+ * `pnpm check-canvas-path-limits` drives the painters past it in a real browser.
+ */
+const MAX_SHAPES_PER_PATH = 10_000;
+/**
+ * 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 class CappedPath {
+    shapes = 0;
+    ctx;
+    paint;
+    constructor(ctx, paint) {
+        this.ctx = ctx;
+        this.paint = paint;
+        ctx.beginPath();
+    }
+    /**
+     * True when the path was full and has been painted and reopened, so a
+     * polyline must `moveTo` its pen again.
+     */
+    add() {
+        if (this.shapes === MAX_SHAPES_PER_PATH) {
+            this.flush();
+            this.shapes = 1;
+            return true;
+        }
+        this.shapes++;
+        return false;
+    }
+    flush() {
+        if (this.shapes > 0) {
+            this.ctx[this.paint]();
+            this.ctx.beginPath();
+            this.shapes = 0;
+        }
+    }
+}

package/esm/colorRampLut.d.ts

@@ -9,9 +9,9 @@ export declare const COLOR_RAMP_LUT_ENTRIES = 256;
 /**
  * Upload a 256-entry RGBA colour-ramp LUT as each named pass's 256×1 texture —
  * the runtime half of the shared ramp mechanism whose shader half is
- * `shaders/colorRampLut.slang`. HiC, LD (whose two shader variants are the
- * reason this takes a pass list) and wiggle density all put their ramps behind
- * their samplers through this one call; each keeps its own scale and its own
- * LUT contents.
+ * `shaders/colorRampLut.slang`. Called by `createMarkBackend` alone now, for
+ * every mark declaring a `texture`: hic, LD's two shader variants and wiggle
+ * density all put their ramps behind their samplers through it, each keeping
+ * its own scale and its own LUT contents.
  */
-export declare function uploadColorRampLut(hal: GpuHal, ramp: Uint8Array, passIds: readonly string[]): void;
+export declare function uploadColorRampLut(hal: GpuHal, ramp: Uint8Array, passIds: readonly string[], sampler?: string): void;

package/esm/colorRampLut.js

@@ -9,17 +9,17 @@ export const COLOR_RAMP_LUT_ENTRIES = RAMP_LUT_ENTRIES;
 /**
  * Upload a 256-entry RGBA colour-ramp LUT as each named pass's 256×1 texture —
  * the runtime half of the shared ramp mechanism whose shader half is
- * `shaders/colorRampLut.slang`. HiC, LD (whose two shader variants are the
- * reason this takes a pass list) and wiggle density all put their ramps behind
- * their samplers through this one call; each keeps its own scale and its own
- * LUT contents.
+ * `shaders/colorRampLut.slang`. Called by `createMarkBackend` alone now, for
+ * every mark declaring a `texture`: hic, LD's two shader variants and wiggle
+ * density all put their ramps behind their samplers through it, each keeping
+ * its own scale and its own LUT contents.
  */
-export function uploadColorRampLut(hal, ramp, passIds) {
+export function uploadColorRampLut(hal, ramp, passIds, sampler) {
     if (ramp.length !== COLOR_RAMP_LUT_ENTRIES * 4) {
         throw new Error(`uploadColorRampLut: expected a ${COLOR_RAMP_LUT_ENTRIES}-entry RGBA LUT ` +
             `(${COLOR_RAMP_LUT_ENTRIES * 4} bytes), got ${ramp.length} bytes`);
     }
     for (const passId of passIds) {
-        hal.uploadTexture(passId, ramp, COLOR_RAMP_LUT_ENTRIES, 1);
+        hal.uploadTexture(passId, ramp, COLOR_RAMP_LUT_ENTRIES, 1, sampler);
     }
 }

package/esm/computePipeline.d.ts

@@ -0,0 +1,14 @@
+import type { ShaderBinding, ShaderSource } from './hal/index.ts';
+export interface ComputePipelineState {
+    device: GPUDevice;
+    pipeline: GPUComputePipeline;
+    bindGroupLayout: GPUBindGroupLayout;
+    bindings: readonly ShaderBinding[];
+}
+/**
+ * One compute pipeline per kernel, built on first use against the current
+ * device and rebuilt after a device loss. Concurrent first callers share the
+ * one async build, which is also when the kernel's WGSL is loaded; a failed
+ * one is retried by the next caller rather than kept.
+ */
+export declare function makeComputePipelineCache(source: Pick<ShaderSource, 'wgsl'>, entryPoint: string, bindings: readonly ShaderBinding[]): (device: GPUDevice) => Promise<ComputePipelineState>;

package/esm/computePipeline.js

@@ -0,0 +1,62 @@
+/// <reference types="@webgpu/types" />
+import { onDeviceLost } from './gpuDevice.js';
+import { stageVisibility } from './webgpuUtils.js';
+// Built from the kernel's own reflected binding table rather than restated by
+// the caller, so a mismatch shows up as a validation failure at pipeline
+// creation rather than as a wrong buffer under a right-looking index.
+function makeBindGroupLayout(device, bindings) {
+    return device.createBindGroupLayout({
+        entries: bindings.map(b => {
+            if (b.kind === 'texture' || b.kind === 'sampler') {
+                throw new Error(`compute kernel: binding ${b.index} ('${b.name}') is a ${b.kind}, ` +
+                    `which a buffer-only dispatch does not bind`);
+            }
+            return {
+                binding: b.index,
+                visibility: stageVisibility(b.stages),
+                buffer: { type: b.kind },
+            };
+        }),
+    });
+}
+/**
+ * One compute pipeline per kernel, built on first use against the current
+ * device and rebuilt after a device loss. Concurrent first callers share the
+ * one async build, which is also when the kernel's WGSL is loaded; a failed
+ * one is retried by the next caller rather than kept.
+ */
+export function makeComputePipelineCache(source, entryPoint, bindings) {
+    let state = null;
+    let statePromise = null;
+    onDeviceLost(() => {
+        state = null;
+        statePromise = null;
+    });
+    return async function ensurePipeline(device) {
+        if (state?.device === device) {
+            return state;
+        }
+        if (statePromise) {
+            return statePromise;
+        }
+        statePromise = (async () => {
+            try {
+                const { WGSL_SOURCE } = await source.wgsl();
+                const module = device.createShaderModule({ code: WGSL_SOURCE });
+                const bindGroupLayout = makeBindGroupLayout(device, bindings);
+                const pipeline = await device.createComputePipelineAsync({
+                    layout: device.createPipelineLayout({
+                        bindGroupLayouts: [bindGroupLayout],
+                    }),
+                    compute: { module, entryPoint },
+                });
+                state = { device, pipeline, bindGroupLayout, bindings };
+                return state;
+            }
+            finally {
+                statePromise = null;
+            }
+        })();
+        return statePromise;
+    };
+}

package/esm/contractReports.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A contract family — the `<family>` in the `[jbrowse <family> contract]`
+ * prefix every contract check in the tree reports under.
+ * `config/jest/console.js` matches `\w+`, so a new one reaches the test gate
+ * without touching it.
+ */
+export type ContractFamily = 'display' | 'session' | 'figure';
+export interface ContractReport {
+    family: ContractFamily;
+    message: string;
+    /** what armed the channel, so a host can say why it is showing this */
+    armedBy: string;
+}
+/**
+ * Whether the checks should run at all.
+ *
+ * Read it where a check costs something to run — the `MutationObserver` a live
+ * figure installs, the per-frame payload walk in `installUpload`. A check whose
+ * cost is a `WeakSet` lookup should run unconditionally and report through
+ * {@link reportContractViolation} instead, so that arming the channel late
+ * still surfaces what it found.
+ */
+export declare function contractReportsOn(): boolean;
+/**
+ * Turn the channel on in a production build, saying what turned it on.
+ *
+ * The reason is not decoration: a notification that appears in an app the
+ * reader did not build has to answer "why am I seeing this" in its own text, or
+ * it reads as the app being broken rather than as a plugin being under
+ * development. First caller wins, so the earliest evidence is the one quoted.
+ */
+export declare function enableContractReports(reason: string): void;
+/**
+ * Where a host puts contract violations that reach a user — a session
+ * notification in the apps. Installing one drains whatever was found before the
+ * host existed, and the disposer only clears the sink it installed, so a
+ * session torn down after its replacement was built does not take the live
+ * one's sink with it.
+ */
+export declare function setContractReportSink(fn: (report: ContractReport) => void): () => void;
+/**
+ * Report a violation of an ordering contract no type can state.
+ *
+ * In tree this is the `console.error` it has always been, and the jest gate is
+ * what listens. Out of tree it is the only thing that reaches a plugin author
+ * at all: their display runs in a production build of somebody's app, which
+ * strips nothing here, and a violation surfaces the moment anything arms the
+ * channel — a `localStorage` flag, a plugin loaded from localhost, or a site
+ * whose config asks for it.
+ *
+ * `agent-docs/reference/ARCHITECTURAL_LIMITS.md` §"Ordering is the contract" is
+ * the register of what reports here.
+ */
+export declare function reportContractViolation(family: ContractFamily, message: string): void;

package/esm/contractReports.js

@@ -0,0 +1,112 @@
+const DEVELOPER_MODE_KEY = 'jbrowseDeveloperMode';
+// The flag a plugin author can set on any deployed JBrowse without owning it or
+// asking anyone, which is the population this whole channel is for.
+function storageFlag() {
+    try {
+        return typeof localStorage === 'undefined' ||
+            localStorage.getItem(DEVELOPER_MODE_KEY) === null
+            ? undefined
+            : `localStorage.${DEVELOPER_MODE_KEY} is set`;
+    }
+    catch {
+        // storage can be denied outright, and a diagnostic is not the thing to take
+        // the app down with
+        return undefined;
+    }
+}
+// Module scope for the same reason `numberGrouping` is: a check is called from
+// a mixin factory, an MST action and a React effect that cannot share a
+// closure, and each realm resolves this once at startup rather than through an
+// observable a worker could not see.
+let armedBy = process.env.NODE_ENV === 'production'
+    ? storageFlag()
+    : 'this is a development build';
+let sink;
+const unlogged = [];
+const undelivered = [];
+const PENDING_LIMIT = 20;
+function remember(queue, found) {
+    if (queue.length < PENDING_LIMIT) {
+        queue.push(found);
+    }
+}
+/**
+ * Whether the checks should run at all.
+ *
+ * Read it where a check costs something to run — the `MutationObserver` a live
+ * figure installs, the per-frame payload walk in `installUpload`. A check whose
+ * cost is a `WeakSet` lookup should run unconditionally and report through
+ * {@link reportContractViolation} instead, so that arming the channel late
+ * still surfaces what it found.
+ */
+export function contractReportsOn() {
+    return armedBy !== undefined;
+}
+/**
+ * Turn the channel on in a production build, saying what turned it on.
+ *
+ * The reason is not decoration: a notification that appears in an app the
+ * reader did not build has to answer "why am I seeing this" in its own text, or
+ * it reads as the app being broken rather than as a plugin being under
+ * development. First caller wins, so the earliest evidence is the one quoted.
+ */
+export function enableContractReports(reason) {
+    armedBy ??= reason;
+    for (const found of unlogged.splice(0)) {
+        emit(found, armedBy);
+    }
+}
+/**
+ * Where a host puts contract violations that reach a user — a session
+ * notification in the apps. Installing one drains whatever was found before the
+ * host existed, and the disposer only clears the sink it installed, so a
+ * session torn down after its replacement was built does not take the live
+ * one's sink with it.
+ */
+export function setContractReportSink(fn) {
+    sink = fn;
+    if (armedBy !== undefined) {
+        for (const found of undelivered.splice(0)) {
+            fn({ ...found, armedBy });
+        }
+    }
+    return () => {
+        if (sink === fn) {
+            sink = undefined;
+        }
+    };
+}
+function emit(found, armed) {
+    // `console.error`, never a throw: an error escaping `afterAttach` is read by
+    // the session loader as an invalid track and the display is silently dropped,
+    // which would hide the very violation being reported. The prefix is what
+    // `config/jest/console.js` buffers and `contractGate.js` fails a test on.
+    console.error(`[jbrowse ${found.family} contract] ${found.message}`);
+    if (sink === undefined) {
+        remember(undelivered, found);
+    }
+    else {
+        sink({ ...found, armedBy: armed });
+    }
+}
+/**
+ * Report a violation of an ordering contract no type can state.
+ *
+ * In tree this is the `console.error` it has always been, and the jest gate is
+ * what listens. Out of tree it is the only thing that reaches a plugin author
+ * at all: their display runs in a production build of somebody's app, which
+ * strips nothing here, and a violation surfaces the moment anything arms the
+ * channel — a `localStorage` flag, a plugin loaded from localhost, or a site
+ * whose config asks for it.
+ *
+ * `agent-docs/reference/ARCHITECTURAL_LIMITS.md` §"Ordering is the contract" is
+ * the register of what reports here.
+ */
+export function reportContractViolation(family, message) {
+    if (armedBy === undefined) {
+        remember(unlogged, { family, message });
+    }
+    else {
+        emit({ family, message }, armedBy);
+    }
+}

package/esm/coverageBand.d.ts

@@ -1,6 +1,5 @@
 import type { CoverageBandBuffers } from './coverageBandBuffers.ts';
 import type { InstancePass } from './instancePass.ts';
-export { coverageBandBuffers } from './coverageBandBuffers.ts';
 export type { CoverageBandBuffers } from './coverageBandBuffers.ts';
 export declare const COVERAGE_BAND_UNIFORMS_SIZE_BYTES = 112;
 /**
@@ -15,10 +14,10 @@ export interface CoverageBandModBuffer {
 /**
  * One draw layer of the coverage band, and the id of the GPU pass that draws it.
  *
- * The band is the same five marks wherever it appears — a display either has a
+ * The band is the same six marks wherever it appears — a display either has a
  * layer's data or does not, and no display reorders them.
  */
-export type CoverageLayerId = 'coverage' | 'snpCov' | 'modCov' | 'interbase' | 'indicator';
+export type CoverageLayerId = 'coverage' | 'snpCov' | 'modCov' | 'interbase' | 'indicator' | 'clipStrip';
 /**
  * The band's z-order, back to front: the depth bars, the SNP slices stacked
  * inside them, the modification slices stacked on those, the interbase histogram
@@ -47,6 +46,12 @@ export declare const COVERAGE_BAND_LAYER_ORDER: readonly CoverageLayerId[];
  */
 export declare function orderCoverageBandLayers<T>(byId: Record<CoverageLayerId, T | undefined>): (T & ({} | null))[];
 export declare const COVERAGE_BAR_PASS: InstancePass<Pick<CoverageBandBuffers, 'coveragePackedBuffer'>>;
+/**
+ * The clip strips over the depth bars the domain cut, off the bar pass's own
+ * buffer and last in the order, since every layer between stacks inside the
+ * bar and would paint over a strip drawn with it.
+ */
+export declare const COVERAGE_CLIP_PASS: InstancePass<Pick<CoverageBandBuffers, 'coveragePackedBuffer'>>;
 export declare const COVERAGE_SNP_PASS: InstancePass<Pick<CoverageBandBuffers, 'snpPackedBuffer'>>;
 export declare const COVERAGE_MOD_PASS: InstancePass<CoverageBandModBuffer>;
 export declare const COVERAGE_INTERBASE_PASS: InstancePass<Pick<CoverageBandBuffers, 'interbasePackedBuffer'>>;
@@ -81,7 +86,7 @@ export interface CoverageBandUniformValues {
     covHeight: number;
     covYOffset: number;
     covTop: number;
-    /** The region's own peak depth, which is what the buffers' `relDepth` is a fraction of. */
+    /** The region's peak depth; the buffers' `relDepth` is a fraction of it. */
     regionMaxDepth: number;
     /** The display's autoscaled depth domain. `undefined` max = not resolved yet. */
     domainMin: number;
@@ -99,9 +104,9 @@ export interface CoverageBandUniformValues {
  * Fill the coverage band's uniform buffer. Total-write (the generated packer),
  * so a field left out is a compile error rather than last frame's value.
  *
- * `hpZero` is derived here rather than at each call site because getting it
- * wrong is a silently wrong band, not a broken one: it MUST be 0, since the HP
- * math materializes +inf as `1/hpZero` to stop the compiler folding the hi/lo
- * split it exists to preserve.
+ * `hpZero` is derived here rather than at each call site because a wrong value
+ * draws a plausible but wrong band and raises no error: it MUST be 0, since the
+ * HP math adds it to a clamp floor to keep that floor off the compiler's
+ * constant table and so stop it folding the hi/lo split away.
  */
 export declare function writeCoverageBandUniforms(buf: ArrayBuffer, v: CoverageBandUniformValues): void;

package/esm/coverageBand.js

@@ -1,10 +1,10 @@
 import * as coverageBarShader from './shaders/coverageBar.generated.js';
+import * as coverageClipShader from './shaders/coverageClip.generated.js';
 import * as coverageIndicatorShader from './shaders/coverageIndicator.generated.js';
 import * as coverageInterbaseShader from './shaders/coverageInterbase.generated.js';
 import * as coverageModShader from './shaders/coverageMod.generated.js';
 import * as coverageSnpShader from './shaders/coverageSnp.generated.js';
 import { slangPass } from './slangPass.js';
-export { coverageBandBuffers } from './coverageBandBuffers.js';
 export const COVERAGE_BAND_UNIFORMS_SIZE_BYTES = coverageBarShader.UNIFORMS_SIZE_BYTES;
 /**
  * The band's z-order, back to front: the depth bars, the SNP slices stacked
@@ -27,6 +27,7 @@ export const COVERAGE_BAND_LAYER_ORDER = [
     'modCov',
     'interbase',
     'indicator',
+    'clipStrip',
 ];
 /**
  * Whatever a display attaches to each band layer — a GPU pass, a Canvas2D
@@ -50,6 +51,15 @@ export const COVERAGE_BAR_PASS = {
     ...slangPass({ id: 'coverage', mod: coverageBarShader }),
     pack: data => data.coveragePackedBuffer,
 };
+/**
+ * The clip strips over the depth bars the domain cut, off the bar pass's own
+ * buffer and last in the order, since every layer between stacks inside the
+ * bar and would paint over a strip drawn with it.
+ */
+export const COVERAGE_CLIP_PASS = {
+    ...slangPass({ id: 'clipStrip', mod: coverageClipShader }),
+    pack: data => data.coveragePackedBuffer,
+};
 export const COVERAGE_SNP_PASS = {
     ...slangPass({ id: 'snpCov', mod: coverageSnpShader }),
     pack: data => data.snpPackedBuffer,
@@ -70,10 +80,10 @@ export const COVERAGE_INDICATOR_PASS = {
  * Fill the coverage band's uniform buffer. Total-write (the generated packer),
  * so a field left out is a compile error rather than last frame's value.
  *
- * `hpZero` is derived here rather than at each call site because getting it
- * wrong is a silently wrong band, not a broken one: it MUST be 0, since the HP
- * math materializes +inf as `1/hpZero` to stop the compiler folding the hi/lo
- * split it exists to preserve.
+ * `hpZero` is derived here rather than at each call site because a wrong value
+ * draws a plausible but wrong band and raises no error: it MUST be 0, since the
+ * HP math adds it to a clamp floor to keep that floor off the compiler's
+ * constant table and so stop it folding the hi/lo split away.
  */
 export function writeCoverageBandUniforms(buf, v) {
     const { domainMax, colors } = v;

package/esm/coverageBandBuffers.d.ts

@@ -7,9 +7,8 @@
  *
  * Structural rather than nominal, and named after the layout rather than after
  * either display: the alignments worker's `CoverageUploadData` and the MAF
- * worker's `MafCoverageRegion` both satisfy it, which is what lets the passes
- * in `coverageBand.ts` carry their own packers instead of each plugin
- * restating four field reads.
+ * worker's `MafCoverageRegion` both satisfy it, so the passes in
+ * `coverageBand.ts` carry the packers and no plugin restates four field reads.
  *
  * Its own module, apart from the GPU passes in `coverageBand.ts`: a state
  * model reaching for just this shape has no reason to statically pull in
@@ -22,9 +21,3 @@ export interface CoverageBandBuffers {
     interbasePackedBuffer: ArrayBuffer;
     indicatorPackedBuffer: ArrayBuffer;
 }
-/**
- * Just the band's four buffers out of a wider per-region payload — the field set
- * stated once, so a display carrying them into its own upload payload cannot
- * spell three of them.
- */
-export declare function coverageBandBuffers(src: CoverageBandBuffers): CoverageBandBuffers;

package/esm/coverageBandBuffers.js

@@ -1,13 +1 @@
-/**
- * Just the band's four buffers out of a wider per-region payload — the field set
- * stated once, so a display carrying them into its own upload payload cannot
- * spell three of them.
- */
-export function coverageBandBuffers(src) {
-    return {
-        coveragePackedBuffer: src.coveragePackedBuffer,
-        snpPackedBuffer: src.snpPackedBuffer,
-        interbasePackedBuffer: src.interbasePackedBuffer,
-        indicatorPackedBuffer: src.indicatorPackedBuffer,
-    };
-}
+export {};