@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/analytics.js

@@ -9,11 +9,10 @@ export async function writeAWSAnalytics(rootModel, initialTimestamp, sessionQuer
     try {
         const url = 'https://analytics.jbrowse.org/api/v1';
         const multiAssemblyTracks = rootModel.jbrowse.tracks.filter(track => readConfObject(track, 'assemblyNames').length > 1).length;
-        // which rendering backend is actually drawing (WebGPU/WebGL2/Canvas2D) —
-        // capabilities *and* any page-wide pin, so a session that fell back to
-        // Canvas2D is counted as Canvas2D rather than as what the hardware could
-        // have done. Reporting the capability answer here is what made "how many
-        // users end up on Canvas2D" unanswerable.
+        // The rung createGpuHal built where a display has built one by idle time,
+        // else the ladder's prediction with any page-wide pin applied — so a
+        // session that fell back to Canvas2D is counted as Canvas2D rather than as
+        // what the hardware could have done.
         const capabilities = await getGraphicsCapabilities();
         const renderer = effectiveRenderer(capabilities);
         // The coarse bit only. `glRenderer` names the exact driver and stays local
@@ -120,14 +119,48 @@ export function doAnalytics(rootModel, initialTimestamp, initialSessionQuery) {
         !analyticsSent &&
         !readConfObject(rootModel.jbrowse.configuration, 'disableAnalytics')) {
         analyticsSent = true;
-        // Defer off the critical load path: writeGAAnalytics injects a third-party
-        // Google Analytics script and writeAWSAnalytics probes graphics
-        // capabilities, together ~hundreds of ms of main-thread work at startup.
-        // loadTime is still measured from initialTimestamp, so the reported metric
-        // is unaffected by running these when the browser is idle.
-        rIC(() => {
-            void writeAWSAnalytics(rootModel, initialTimestamp, initialSessionQuery);
-            void writeGAAnalytics(rootModel, initialTimestamp);
+        // writeGAAnalytics injects Google's scripts and writeAWSAnalytics probes
+        // graphics capabilities, hundreds of ms of main-thread work together. Idle
+        // time alone is not late enough: a load spends most of its time idle,
+        // waiting on the network, so rIC ran them mid-boot. The writers measure
+        // loadTime up to when they run, so the start they get is moved forward by
+        // the wait, and loadTime still ends here.
+        const calledAt = Date.now();
+        afterAppReady(() => {
+            rIC(() => {
+                const start = initialTimestamp + (Date.now() - calledAt);
+                void writeAWSAnalytics(rootModel, start, initialSessionQuery);
+                void writeGAAnalytics(rootModel, start);
+            });
         });
     }
 }
+// `[data-app-phase="ready"]`, or a timeout for a page that never shows one
+// (Desktop's start screen)
+function afterAppReady(callback, maxWaitMs = 10_000) {
+    const isReady = () => document.querySelector('[data-app-phase="ready"]') !== null;
+    if (isReady()) {
+        callback();
+        return;
+    }
+    let done = false;
+    const finish = () => {
+        if (!done) {
+            done = true;
+            observer.disconnect();
+            clearTimeout(timer);
+            callback();
+        }
+    };
+    const observer = new MutationObserver(() => {
+        if (isReady()) {
+            finish();
+        }
+    });
+    const timer = setTimeout(finish, maxWaitMs);
+    observer.observe(document.body, {
+        subtree: true,
+        childList: true,
+        attributeFilter: ['data-app-phase'],
+    });
+}

package/esm/util/animationAllowed.d.ts

@@ -15,3 +15,12 @@ import type { AnimationMode } from './types/index.ts';
  * honors it.
  */
 export declare function animationAllowed(mode: AnimationMode): boolean;
+/** how long a layout morph takes from where it drew to where it now draws */
+export declare const MORPH_DURATION_MS = 300;
+export declare function easeInOutCubic(t: number): number;
+/**
+ * The wall clock a morph is timed on. Falls back to the epoch clock rather than
+ * a constant where `performance` is missing: a clock that never advances
+ * leaves a frame loop at progress 0 forever.
+ */
+export declare function morphClockMs(): number;

package/esm/util/animationAllowed.js

@@ -20,3 +20,16 @@ export function animationAllowed(mode) {
     return (hasFrameClock &&
         (mode === 'enabled' || (mode === 'system' && !prefersReduced)));
 }
+/** how long a layout morph takes from where it drew to where it now draws */
+export const MORPH_DURATION_MS = 300;
+export function easeInOutCubic(t) {
+    return t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+}
+/**
+ * The wall clock a morph is timed on. Falls back to the epoch clock rather than
+ * a constant where `performance` is missing: a clock that never advances
+ * leaves a frame loop at progress 0 forever.
+ */
+export function morphClockMs() {
+    return typeof performance === 'undefined' ? Date.now() : performance.now();
+}

package/esm/util/applyRowResizeWheel.d.ts

@@ -1,10 +1,15 @@
-interface RowResizeTarget {
+import type { VirtualScrollModel } from './useVirtualScrollWheel.ts';
+export interface RowResizeTarget extends VirtualScrollModel {
+    /** resolved, never the 0/fit sentinel — this is divided by */
     effectiveRowHeight: number;
-    scrollTop: number;
     nrow: number;
-    viewportHeight: number;
     setRowHeight: (n: number) => void;
-    setScrollTop: (n: number) => void;
 }
+/**
+ * shift+wheel over a row stack: resize the rows, pinning the row under the
+ * cursor. The floor is the fit height, so rows never shrink past filling the
+ * viewport. The cap stops a gesture but never moves rows on its own, so it
+ * rises to a current height already above it (a pinned `rowHeight` is
+ * unbounded).
+ */
 export declare function applyRowResizeWheel(e: WheelEvent, el: HTMLElement, model: RowResizeTarget): void;
-export {};

package/esm/util/applyRowResizeWheel.js

@@ -1,30 +1,19 @@
-// shift+wheel resizes the sample rows (a vertical-zoom gesture) rather than
-// scrolling, keeping the row under the cursor pinned in place as the height
-// changes. Shared by every row-stack display — both variant displays and MAF —
-// so the gesture stays identical wherever rows have a resolved height and a
-// scroll offset. setScrollTop clamps to the new scrollableHeight, so the raw
-// target is passed through unclamped.
 import { normalizeWheelDelta } from './wheelZoom.js';
 const MAX_ROW_HEIGHT = 20;
-// px of row-height change per pixel of normalized wheel scroll. A mouse notch
-// (~100px) nudges the height ~0.4px; a trackpad's small continuous deltas
-// accumulate smoothly instead of the old sign-based ±1-per-event, which flew
-// through the whole range on a trackpad's event flood.
+// A mouse notch (~100px) nudges the height ~0.4px, and a trackpad's small
+// deltas accumulate smoothly rather than flying through the range.
 const RESIZE_PX_PER_WHEEL_PX = 1 / 240;
+/**
+ * shift+wheel over a row stack: resize the rows, pinning the row under the
+ * cursor. The floor is the fit height, so rows never shrink past filling the
+ * viewport. The cap stops a gesture but never moves rows on its own, so it
+ * rises to a current height already above it (a pinned `rowHeight` is
+ * unbounded).
+ */
 export function applyRowResizeWheel(e, el, model) {
     e.preventDefault();
-    // scroll up (deltaY < 0) grows rows; proportional to the normalized delta so
-    // the speed is consistent across mice/trackpads and finer than ±1/event.
     const delta = -normalizeWheelDelta(e.deltaY, e.deltaMode) * RESIZE_PX_PER_WHEEL_PX;
-    // guard nrow=0 (no samples) so the auto-fit floor stays finite
-    const minRowHeight = model.viewportHeight / Math.max(1, model.nrow);
-    // The cap may stop the gesture going further; it may never move the rows on
-    // its own. So both heights that can already sit above MAX_ROW_HEIGHT raise
-    // it: the auto-fit floor (few samples), and the current height (a pinned
-    // `rowHeight` — the config slot and the "Custom..." dialog are both
-    // unbounded, and MAF's own docs example is 12 while a bases-mode row wants
-    // more). Without the second, a 40px pinned row met `min(20, 40.4)` on the
-    // first notch of a *grow* gesture and halved.
+    const minRowHeight = model.scrollViewportHeight / Math.max(1, model.nrow);
     const maxRowHeight = Math.max(MAX_ROW_HEIGHT, minRowHeight, model.effectiveRowHeight);
     const newRowHeight = Math.max(minRowHeight, Math.min(maxRowHeight, model.effectiveRowHeight + delta));
     const mouseY = e.clientY - el.getBoundingClientRect().top;

package/esm/util/bandHeight.d.ts

@@ -51,3 +51,13 @@ export declare function boundBandHeight(n: number, { min, max }?: BandBounds): n
  *   display height so the plot below cannot be squashed to nothing
  */
 export declare function clampBandHeight(current: number, target: number, bounds?: BandBounds): number;
+/**
+ * #api core/util
+ * Heights after growing or shrinking a stack of bands by `distance` px in all:
+ * the one rule every whole-stack resize uses. Each band takes its share of the
+ * height it has above `floor`, so the tall bands give and take the most, and
+ * none goes below `floor`, or below its own height if it already sits under it
+ * (the {@link clampBandHeight} rule). Whole pixels, rounded by largest
+ * remainder, so the stack moves by exactly the rounded distance.
+ */
+export declare function scaleBandHeights(heights: number[], distance: number, floor?: number): number[];

package/esm/util/bandHeight.js

@@ -54,3 +54,32 @@ export function clampBandHeight(current, target, bounds = {}) {
     const { min = MIN_BAND_HEIGHT } = bounds;
     return boundBandHeight(target, { ...bounds, min: Math.min(min, current) });
 }
+/**
+ * #api core/util
+ * Heights after growing or shrinking a stack of bands by `distance` px in all:
+ * the one rule every whole-stack resize uses. Each band takes its share of the
+ * height it has above `floor`, so the tall bands give and take the most, and
+ * none goes below `floor`, or below its own height if it already sits under it
+ * (the {@link clampBandHeight} rule). Whole pixels, rounded by largest
+ * remainder, so the stack moves by exactly the rounded distance.
+ */
+export function scaleBandHeights(heights, distance, floor = MIN_BAND_HEIGHT) {
+    const floors = heights.map(h => Math.min(h, floor));
+    const room = heights.map((h, i) => h - floors[i]);
+    const roomTotal = room.reduce((a, b) => a + b, 0);
+    const target = Math.max(0, Math.round(roomTotal + distance));
+    const exact = room.map(r => roomTotal > 0 ? (r * target) / roomTotal : target / heights.length);
+    const whole = exact.map(e => Math.floor(e));
+    let left = target - whole.reduce((a, b) => a + b, 0);
+    const byRemainder = exact
+        .map((e, i) => ({ i, frac: e - whole[i] }))
+        .sort((a, b) => b.frac - a.frac);
+    for (const { i } of byRemainder) {
+        if (left <= 0) {
+            break;
+        }
+        whole[i] = whole[i] + 1;
+        left -= 1;
+    }
+    return whole.map((w, i) => w + floors[i]);
+}

package/esm/util/bandLayout.d.ts

@@ -39,11 +39,11 @@ export interface BandStack<K extends string> {
 /**
  * #api core/util
  * Fold an ordered set of bands into tops and a bottom. The order is the
- * argument, so a display states its band order exactly once; reserve, paint
- * and pick all read the same fold, which is what keeps "the reserver and the
- * painter read one function" true by construction rather than by prose.
+ * argument, so a display states its band order exactly once. Reserve, paint
+ * and pick all call this function, so the reserved and painted positions
+ * cannot disagree.
  *
- * Only the fold is shared. What varies per display stays there: per-lane
+ * Only the fold is shared; the rest stays in each display. Per-lane
  * iteration runs this once per lane, sticky-vs-scrolling is a property of how
  * the result is projected to the screen, and a band drawn outside its
  * reservation (an overlay) carries its own draw rect beside the stack.

package/esm/util/bandLayout.js

@@ -14,11 +14,11 @@ export function reservedPx(band) {
 /**
  * #api core/util
  * Fold an ordered set of bands into tops and a bottom. The order is the
- * argument, so a display states its band order exactly once; reserve, paint
- * and pick all read the same fold, which is what keeps "the reserver and the
- * painter read one function" true by construction rather than by prose.
+ * argument, so a display states its band order exactly once. Reserve, paint
+ * and pick all call this function, so the reserved and painted positions
+ * cannot disagree.
  *
- * Only the fold is shared. What varies per display stays there: per-lane
+ * Only the fold is shared; the rest stays in each display. Per-lane
  * iteration runs this once per lane, sticky-vs-scrolling is a property of how
  * the result is projected to the screen, and a band drawn outside its
  * reservation (an overlay) carries its own draw rect beside the stack.

package/esm/util/bezierConnector.d.ts

@@ -1,5 +1,6 @@
-export declare const BEZIER_CONNECTOR_MAX_REACH_PX: number;
-export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dip, }: {
+export declare const CUBIC_APEX_RATIO = 0.75;
+export declare const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
+export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dipPx, }: {
     x1: number;
     y1: number;
     x2: number;
@@ -10,5 +11,5 @@ export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd
     reversed1?: boolean;
     reversed2?: boolean;
     maxHandlePx?: number;
-    dip?: boolean;
+    dipPx?: number;
 }): string;

package/esm/util/bezierConnector.js

@@ -19,43 +19,38 @@ const SPAN_FACTOR = 0.3;
 // its leading end: unbounded, that hook grows with the arc, and a full-width
 // inversion flings a ~500px curl back across unrelated reads.
 const MAX_HANDLE_PX = 200;
+// A symmetric cubic's extreme sits 3/4 of the way from its baseline to its
+// control points, so an arc asked to reach a given apex puts its controls 4/3
+// past it. Exported because the sashimi overlay solves the same equation in the
+// other direction, and the two spellings drifting apart would put the insert-
+// size ruler's labels at heights nothing plots at.
+export const CUBIC_APEX_RATIO = 0.75;
 // Vertical bow applied to a connection whose two endpoints share (or nearly
 // share) a row — e.g. a chain whose split segments are all laid out on one
 // pileup row. Without it the horizontal-only handles collapse the cubic to a
 // flat, invisible line lying on the row; the bow lifts the control points so
 // the curve arcs into a visible hump. This is the control-point lift, not the
-// height the curve reaches: a cubic with both control points lifted by `bow`
-// apexes at 0.75 * bow.
+// height the curve reaches.
 const MAX_BOW_PX = 30;
 // A discordant connection bows *down* instead of up, so the two classes read
 // apart at a glance. Both renderers follow this: BreakpointSplitView dips its
-// same-level discordant links, and the pileup overlay dips every curve it draws
-// (its normal-orientation pairs are plain lines, so a curve there is always
-// discordant). Keep it that way — a renderer that opts out makes "below the
-// reads" mean two different things in two views of the same data.
+// same-level discordant links, and the pileup overlay dips every discordant
+// curve it draws (a normal-orientation pair is a plain line, or bows up over its
+// row where a hidden-segment one would lie on a chain's connecting line). Keep
+// it that way — a renderer that opts out makes "below the reads" mean two
+// different things in two views of the same data.
 //
-// Depth comes from the connection's own horizontal span
-// rather than reaching for some fixed row: with "view as pairs" / "link
-// supplementary alignments" every qname lands on one row, so dipping to a
-// shared row bottoms every curve out at the same depth and they collapse into
-// spaghetti. Keying on span makes the depth mean something — wide events dive
-// deeper than narrow ones — and lets the curves nest.
-//
-// Depth saturates toward MAX_DIP_PX rather than clamping at it. A hard cap
-// reintroduces exactly the problem being fixed: every connection wider than the
-// cap point bottoms out at an identical depth, and at any plausible cap a
-// typical view is mostly wider. This form stays strictly increasing in span at
-// every width while staying bounded. DIP_HALF_SPAN_PX is the span at which the
-// dip reaches half its maximum.
-const MAX_DIP_PX = 110;
-const DIP_HALF_SPAN_PX = 500;
-// How far a curve can stray outside the band between its two endpoints. A cubic
-// with both control points offset by `d` apexes at 0.75 * d, and the dip — the
-// deeper of the two shaping terms — saturates toward MAX_DIP_PX, so this bounds
-// both. A caller that culls off-screen curves has to pad its viewport test by
-// this: the shaping is applied to the *control points*, so a curve whose two
+// HOW DEEP is the renderer's call, not this file's. Depth is the mark's one free
+// channel, and only the renderer knows the band the ink has to survive in — the
+// pileup clips each section at its band bottom, and the split view bleeds a
+// too-deep dip into the panel below. So callers pass the depth they want and
+// `discordantDipPx` (@jbrowse/sv-core) is the law the two of them share.
+// How far a curve can stray outside the band between its two endpoints. The dip
+// is the deeper of the two shaping terms, so this is a ceiling on it, applied
+// here rather than trusted to a caller: a culler pads its viewport test by this,
+// and the shaping is applied to the *control points*, so a curve whose two
 // endpoints both sit just outside the viewport can still have a visible body.
-export const BEZIER_CONNECTOR_MAX_REACH_PX = 0.75 * MAX_DIP_PX;
+export const BEZIER_CONNECTOR_MAX_REACH_PX = 110;
 // Sign (+1/-1) of an endpoint's horizontal control handle. The handle leaves a
 // trailing (3') endpoint along the read's reading direction (`strand`); at a
 // split junction's leading (5') endpoint it flips, so the curve arrives flowing
@@ -75,19 +70,6 @@ function shapingBudget(p1, p2) {
 function bowHeight(p1, p2, budget) {
     return Math.min(budget, Math.max(0, MAX_BOW_PX - Math.abs(p2.y - p1.y)));
 }
-// Negative = the control points drop below the reads (see MAX_DIP_PX). Keyed on
-// horizontal span alone: two reads a few px apart describe a small event and get
-// a small dip, however tall their track happens to be.
-//
-// Budget-clamped like the bow. At the current tuning the saturating curve
-// already resolves under the budget at every span (worst ratio ~0.73, as span
-// → 0), so this is inert — it's here so retuning MAX_DIP_PX / DIP_HALF_SPAN_PX
-// can't silently reintroduce the fold-back squiggle SPAN_FACTOR exists to
-// prevent. Pinned by 'the dip never outgrows its shaping budget'.
-function dipHeight(p1, p2, budget) {
-    const span = Math.abs(p2.x - p1.x);
-    return -Math.min(budget, MAX_DIP_PX * (span / (span + DIP_HALF_SPAN_PX)));
-}
 function cubicPath(from, ctrl1, ctrl2, to) {
     return `M ${from.x} ${from.y} C ${ctrl1.x} ${ctrl1.y} ${ctrl2.x} ${ctrl2.y} ${to.x} ${to.y}`;
 }
@@ -95,14 +77,25 @@ export function bezierConnectorPath({ x1, y1, x2, y2, s1, s2,
 // The second endpoint is a split junction's 5' leading edge (its handle flips
 // to fold the curve into the next segment); false for a paired mate's 3' edge.
 leadingEnd2 = false, reversed1 = false, reversed2 = false, maxHandlePx = MAX_HANDLE_PX, 
-// This connection is discordant (aberrant pair orientation, or a split
-// junction's strand flip): it dips below the reads instead of arcing over
-// them, so the two classes are tellable apart by shape alone.
-dip = false, }) {
+// Depth, in px, of the dip a discordant connection draws instead of the bow a
+// concordant one gets — aberrant pair orientation, or a split junction's
+// strand flip, so the two classes are tellable apart by shape alone. It is
+// the depth of the curve's APEX — what a caller can bound by the room it has —
+// and CUBIC_APEX_RATIO converts it to the control-point drop that puts the ink
+// there. Leave it out to bow up.
+dipPx, }) {
     const from = { x: x1, y: y1 };
     const to = { x: x2, y: y2 };
     const budget = shapingBudget(from, to);
     const handle = Math.min(maxHandlePx, budget);
-    const bow = dip ? dipHeight(from, to, budget) : bowHeight(from, to, budget);
+    // The dip is deliberately not clamped to the budget, unlike the bow. The
+    // budget stops the cubic folding back over itself, and only the horizontal
+    // handles can do that — a vertical offset leaves x(t) monotonic however deep
+    // it goes, so a big event squeezed into a few px draws a narrow trough rather
+    // than a squiggle. Pinned by 'a dipped connection never overshoots its
+    // endpoints in x'.
+    const bow = dipPx === undefined
+        ? bowHeight(from, to, budget)
+        : -Math.min(dipPx, BEZIER_CONNECTOR_MAX_REACH_PX) / CUBIC_APEX_RATIO;
     return cubicPath(from, { x: x1 + handle * tangentSign(s1, false, reversed1), y: y1 - bow }, { x: x2 + handle * tangentSign(s2, leadingEnd2, reversed2), y: y2 - bow }, to);
 }

package/esm/util/bgzfWorkerPool.d.ts

@@ -1,78 +1,24 @@
 import type { BgzfWorkerPool } from '@gmod/bgzf-filehandle';
 /**
- * The BGZF inflate pool the indexed-format libraries decompress their chunks
- * on, instead of decompressing them on the thread that asked.
- *
- * BGZF decompression is 70-90% of a cold query (`@gmod/bam` ADR 0003) and BGZF
- * blocks are independently inflatable, so spreading them across workers is the
- * largest remaining lever in the read path. Measured 1.95x end to end on the
- * BAM side: a 22-view pan / zoom out / pan back over 1000x long-read data, real
- * HTTP, headless Chrome, 4 workers, with both arms returning the same 38,246
- * records.
- *
- * ## One pool per JS context, like the cache budgets
- *
- * Same scope and same reason as `decompressedBytesBudget` — see
- * {@link ./cacheBudgets.ts} — so one per RPC worker plus one on the main
- * thread. That is the scope with spare cores: a track's queries are sticky to a
- * single RPC worker, so without a pool every chunk of every query inflates on
- * that one thread while the rest of the machine idles. `getSharedWorkerPool()`
- * memoizes per context, so every adapter in a worker shares its four workers
- * rather than each opening its own.
- *
- * ## Call it, don't hoist it
- *
- * This is a function and not an exported constant on purpose: it spawns workers
- * the first time it is called, and a module-level call would spawn them on
- * import, in every context that pulls in anything from `util`, whether or not a
- * bgzip-backed track is ever opened. Call it where a file is constructed.
- *
- * ## The dynamic import is about bundle weight, and only that
- *
- * `@gmod/bgzf-filehandle` inlines its worker bundle as a base64 string, and
- * `getSharedWorkerPool` is what reaches it, so a **static** import pins that
- * blob into the initial bundle of every entry point that reaches this helper.
- * Measured with esbuild, splitting and minifying, on the import alone:
- *
- * ```
- * static    entry 54.7kb  (23.4kb gzipped) — the blob is in the initial bundle
- * dynamic   entry 114b    (141b  gzipped) + 123.9kb in a split chunk
- * ```
- *
- * So ~23kb gzipped off every bundle that can reach a bgzip adapter, deferred to
- * a chunk that is only fetched once such a track is actually opened. Core's
- * `util/unzip.ts` and `fetchAndMaybeUnzip.ts` dodge it the same way. It costs
- * nothing to do, because the libraries want a promise anyway — their callers'
- * `configure()` is synchronous and the pool is only available asynchronously.
- *
- * **It is not about test speed**, though it has been described that way. That
- * claim was checked here and did not reproduce: three jbrowse-web variant
- * suites ran 13.887s static against 13.856s dynamic, warm cache, and a 29s
- * reading that started this off turned out to be a cold jest transform cache in
- * a fresh worktree. Don't reintroduce a static import on the grounds that the
- * jest argument was wrong — the bundle argument above is the real one, and it
- * stands on its own.
- *
- * The `catch` is deliberate, but for a plain reason rather than a specific
- * failure: a pool is an optimization, `@gmod/bam` and `@gmod/tabix` both await
- * this, and anything going wrong here has to degrade to inflating in process
- * rather than break every read. A documented CJS-interop throw under jest was
- * the original motivation; that no longer reproduces (core's own suite, the
- * BamAdapter suites and jbrowse-web's Alignments suite all pass with the catch
- * removed), so keep it for the invariant, not the anecdote.
- *
- * ## Safe to pass unconditionally
- *
- * Returns a promise, and the libraries await it at the point of use rather than
- * at construction — which is what lets a synchronous `configure()` hand the
- * pending pool straight over. It resolves to `undefined` wherever Workers
- * cannot be created (node, jest), and `@gmod/bam` and `@gmod/tabix` then take
- * their in-process path, so no caller needs an environment check and the test
- * suites are unaffected.
- *
- * Needs no cross-origin isolation: each worker's range is transferred to it as
- * an ArrayBuffer rather than shared, so this works on an ordinary page. That
- * was the point of dropping SharedArrayBuffer in `@gmod/bgzf-filehandle` 6.4.0
- * — measured, the shared transport was at parity at best.
+ * The BGZF inflate pool the indexed-format libraries decompress large chunks on,
+ * one per JS context like `decompressedBytesBudget`: one per RPC worker plus one
+ * on the main thread. BGZF decompression is 70-90% of a cold query (`@gmod/bam`
+ * ADR 0003), and its blocks inflate independently.
+ *
+ * Holding it costs nothing. `@gmod/bgzf-filehandle` 6.7 starts the workers only
+ * when a chunk of at least `POOL_MIN_DECOMPRESSED_BYTES` (0.4MB inflated)
+ * arrives, inflates in process while they boot, and inflates in process for good
+ * if one of them fails, so no read waits on a worker. What it is worth per
+ * format, and why GFF3 and GTF go without it: reference/BGZF_WORKER_POOL.md.
+ *
+ * A function over a dynamic import because the library inlines its worker bundle
+ * as a base64 string, and a static import pins it into every entry point that
+ * can reach this helper: measured with esbuild, 23.4kb gzipped against 141b. Test
+ * speed is not a reason either way; three jbrowse-web variant suites ran 13.887s
+ * static against 13.856s dynamic.
+ *
+ * Resolves to `undefined` wherever Workers cannot be created (node, jest), which
+ * keeps `@gmod/bam` and `@gmod/tabix` on their in-process path, and the `catch`
+ * keeps anything else going wrong here on it too.
  */
 export declare function sharedBgzfWorkerPool(): Promise<BgzfWorkerPool | undefined>;

package/esm/util/bgzfWorkerPool.js

@@ -1,78 +1,24 @@
 /**
- * The BGZF inflate pool the indexed-format libraries decompress their chunks
- * on, instead of decompressing them on the thread that asked.
- *
- * BGZF decompression is 70-90% of a cold query (`@gmod/bam` ADR 0003) and BGZF
- * blocks are independently inflatable, so spreading them across workers is the
- * largest remaining lever in the read path. Measured 1.95x end to end on the
- * BAM side: a 22-view pan / zoom out / pan back over 1000x long-read data, real
- * HTTP, headless Chrome, 4 workers, with both arms returning the same 38,246
- * records.
- *
- * ## One pool per JS context, like the cache budgets
- *
- * Same scope and same reason as `decompressedBytesBudget` — see
- * {@link ./cacheBudgets.ts} — so one per RPC worker plus one on the main
- * thread. That is the scope with spare cores: a track's queries are sticky to a
- * single RPC worker, so without a pool every chunk of every query inflates on
- * that one thread while the rest of the machine idles. `getSharedWorkerPool()`
- * memoizes per context, so every adapter in a worker shares its four workers
- * rather than each opening its own.
- *
- * ## Call it, don't hoist it
- *
- * This is a function and not an exported constant on purpose: it spawns workers
- * the first time it is called, and a module-level call would spawn them on
- * import, in every context that pulls in anything from `util`, whether or not a
- * bgzip-backed track is ever opened. Call it where a file is constructed.
- *
- * ## The dynamic import is about bundle weight, and only that
- *
- * `@gmod/bgzf-filehandle` inlines its worker bundle as a base64 string, and
- * `getSharedWorkerPool` is what reaches it, so a **static** import pins that
- * blob into the initial bundle of every entry point that reaches this helper.
- * Measured with esbuild, splitting and minifying, on the import alone:
- *
- * ```
- * static    entry 54.7kb  (23.4kb gzipped) — the blob is in the initial bundle
- * dynamic   entry 114b    (141b  gzipped) + 123.9kb in a split chunk
- * ```
- *
- * So ~23kb gzipped off every bundle that can reach a bgzip adapter, deferred to
- * a chunk that is only fetched once such a track is actually opened. Core's
- * `util/unzip.ts` and `fetchAndMaybeUnzip.ts` dodge it the same way. It costs
- * nothing to do, because the libraries want a promise anyway — their callers'
- * `configure()` is synchronous and the pool is only available asynchronously.
- *
- * **It is not about test speed**, though it has been described that way. That
- * claim was checked here and did not reproduce: three jbrowse-web variant
- * suites ran 13.887s static against 13.856s dynamic, warm cache, and a 29s
- * reading that started this off turned out to be a cold jest transform cache in
- * a fresh worktree. Don't reintroduce a static import on the grounds that the
- * jest argument was wrong — the bundle argument above is the real one, and it
- * stands on its own.
- *
- * The `catch` is deliberate, but for a plain reason rather than a specific
- * failure: a pool is an optimization, `@gmod/bam` and `@gmod/tabix` both await
- * this, and anything going wrong here has to degrade to inflating in process
- * rather than break every read. A documented CJS-interop throw under jest was
- * the original motivation; that no longer reproduces (core's own suite, the
- * BamAdapter suites and jbrowse-web's Alignments suite all pass with the catch
- * removed), so keep it for the invariant, not the anecdote.
- *
- * ## Safe to pass unconditionally
- *
- * Returns a promise, and the libraries await it at the point of use rather than
- * at construction — which is what lets a synchronous `configure()` hand the
- * pending pool straight over. It resolves to `undefined` wherever Workers
- * cannot be created (node, jest), and `@gmod/bam` and `@gmod/tabix` then take
- * their in-process path, so no caller needs an environment check and the test
- * suites are unaffected.
- *
- * Needs no cross-origin isolation: each worker's range is transferred to it as
- * an ArrayBuffer rather than shared, so this works on an ordinary page. That
- * was the point of dropping SharedArrayBuffer in `@gmod/bgzf-filehandle` 6.4.0
- * — measured, the shared transport was at parity at best.
+ * The BGZF inflate pool the indexed-format libraries decompress large chunks on,
+ * one per JS context like `decompressedBytesBudget`: one per RPC worker plus one
+ * on the main thread. BGZF decompression is 70-90% of a cold query (`@gmod/bam`
+ * ADR 0003), and its blocks inflate independently.
+ *
+ * Holding it costs nothing. `@gmod/bgzf-filehandle` 6.7 starts the workers only
+ * when a chunk of at least `POOL_MIN_DECOMPRESSED_BYTES` (0.4MB inflated)
+ * arrives, inflates in process while they boot, and inflates in process for good
+ * if one of them fails, so no read waits on a worker. What it is worth per
+ * format, and why GFF3 and GTF go without it: reference/BGZF_WORKER_POOL.md.
+ *
+ * A function over a dynamic import because the library inlines its worker bundle
+ * as a base64 string, and a static import pins it into every entry point that
+ * can reach this helper: measured with esbuild, 23.4kb gzipped against 141b. Test
+ * speed is not a reason either way; three jbrowse-web variant suites ran 13.887s
+ * static against 13.856s dynamic.
+ *
+ * Resolves to `undefined` wherever Workers cannot be created (node, jest), which
+ * keeps `@gmod/bam` and `@gmod/tabix` on their in-process path, and the `catch`
+ * keeps anything else going wrong here on it too.
  */
 export function sharedBgzfWorkerPool() {
     return import('@gmod/bgzf-filehandle')

package/esm/util/binnedAggregate.d.ts

@@ -0,0 +1,17 @@
+import type { AggregateStep, BinStep } from './markEncodingTypes.ts';
+import type { Staged } from './stepTables.ts';
+/**
+ * Whether an interval `bin` and the `aggregate` behind it run as one kernel:
+ * the aggregate groups by the bin's two edges, and every field it reads is a
+ * plain name, so a piece's value is its row's or one the bin wrote.
+ */
+export declare function fusesBinAggregate(bin: BinStep, agg: AggregateStep): boolean;
+/**
+ * An interval `bin` and the `aggregate` grouped by its edges as one walk: each
+ * row's bins accumulate straight into their group's sums, with no piece table,
+ * the way `binRawRegion` bins a BigWig's raw section. The groups come out in
+ * the order the pieces would have met them and each sum adds its pieces in
+ * the pieces' order, so the answer is the two steps' to the bit. Undefined
+ * where the bins spread too thinly over the region for a dense index.
+ */
+export declare function binnedAggregate({ table, bounds }: Staged, bin: BinStep, agg: AggregateStep): Staged | undefined;