@jbrowse/core 5.0.0-beta.7 → 5.0.0-beta.9

package/esm/util/aborting.js

@@ -1,3 +1,5 @@
+import { isElectron, isNode } from './environment.js';
+import { createTimeGate } from './timeGate.js';
 class AbortError extends Error {
     code;
 }
@@ -45,3 +47,85 @@ export function isAbortException(exception) {
             (exception instanceof AbortError && exception.code === 'ERR_ABORTED') ||
             /\b(aborted|aborterror)\b/i.test(exception.message)));
 }
+/**
+ * Throw an AbortError if `signal` has aborted. A `signal.aborted` read, so it
+ * is cheap enough for the body of a loop; place it after any await and in any
+ * per-item callback a reader hands you.
+ */
+export function checkAbortSignal(signal) {
+    if (signal?.aborted) {
+        throw makeAbortError();
+    }
+}
+/**
+ * Run an awaited stage under `signal`: checked before it starts, and again
+ * once it settles. The check after is the one that gets left out when the two
+ * are placed by hand — a stop landing during a long await otherwise goes
+ * unseen until the next stage.
+ */
+export async function withAbortCheck(signal, fn) {
+    checkAbortSignal(signal);
+    const result = await fn();
+    checkAbortSignal(signal);
+    return result;
+}
+const YIELD_INTERVAL_MS = 50;
+/**
+ * Give the event loop one turn. A worker learns of an abort through a posted
+ * message, and a message is a task: an `await` on an already-settled promise
+ * drains only microtasks and delivers nothing. A browser realm, Electron's
+ * included, gets a MessageChannel task, which unlike `setTimeout` is not
+ * clamped. Not `scheduler.yield`: Chromium runs its continuation ahead of a
+ * posted message, so a worker loop yielding that way never sees the abort.
+ * Plain Node and jsdom get the timer: a MessagePort turn there runs no due
+ * timer, and under jest the abort is one.
+ */
+const yieldToEventLoop = (() => {
+    if ((isElectron || !isNode) && typeof MessageChannel !== 'undefined') {
+        const channel = new MessageChannel();
+        let resolvers = [];
+        channel.port1.onmessage = () => {
+            const pending = resolvers;
+            resolvers = [];
+            for (const resolve of pending) {
+                resolve();
+            }
+        };
+        return () => new Promise(resolve => {
+            resolvers.push(resolve);
+            channel.port2.postMessage(0);
+        });
+    }
+    return () => new Promise(resolve => {
+        setTimeout(resolve, 0);
+    });
+})();
+/**
+ * Cancellation for a loop that can run for seconds without awaiting — a
+ * whole-genome projection, a matrix fill. A `signal.aborted` read inside such a
+ * loop never changes, because the abort is a posted message; the loop has to
+ * give the event loop a turn now and then. A loop bounded by the byte gate or
+ * one region's features finishes before this would matter and only checks.
+ *
+ *     const breakpoint = createAbortBreakpoint(signal)
+ *     for (const row of rows) {
+ *       if (breakpoint.due()) {
+ *         await breakpoint.yield()
+ *       }
+ *       …
+ *     }
+ *
+ * Two calls rather than one because an `await` on a non-promise still costs a
+ * microtask, about 60 ns against 2 ns for the `due()` read, and a loop over
+ * every read in a pileup notices the difference.
+ */
+export function createAbortBreakpoint(signal) {
+    const gate = createTimeGate();
+    return {
+        due: () => gate(YIELD_INTERVAL_MS),
+        async yield() {
+            await yieldToEventLoop();
+            checkAbortSignal(signal);
+        },
+    };
+}

package/esm/util/adapterMetadata.d.ts

@@ -11,7 +11,7 @@ import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
  *
  * Keyed on the adapter config rather than memoized for the display's life, so
  * a track re-pointed in the config editor stops serving the old header's
- * descriptions. Cleared on failure so a later click retries. No stop token and
+ * descriptions. Cleared on failure so a later click retries. No signal and
  * no status: nothing to narrate, and nothing a cancel could save — the widget
  * opens on the result.
  */

package/esm/util/adapterMetadata.js

@@ -1,4 +1,4 @@
-import { adapterConfigKey } from './adapterConfigKey.js';
+import { isDataCurrent } from './isDataCurrent.js';
 import { getRpcSessionId } from './parentWalk.js';
 import { getRpcHost } from './sessionServices.js';
 /**
@@ -13,19 +13,19 @@ import { getRpcHost } from './sessionServices.js';
  *
  * Keyed on the adapter config rather than memoized for the display's life, so
  * a track re-pointed in the config editor stops serving the old header's
- * descriptions. Cleared on failure so a later click retries. No stop token and
+ * descriptions. Cleared on failure so a later click retries. No signal and
  * no status: nothing to narrate, and nothing a cancel could save — the widget
  * opens on the result.
  */
 export function createAdapterMetadataFetch(self) {
     let cached;
     return () => {
-        const key = adapterConfigKey(self.adapterConfig);
-        if (cached?.key !== key) {
+        const { adapterConfig } = self;
+        if (!cached || !isDataCurrent(cached.adapterConfig, adapterConfig)) {
             const promise = getRpcHost(self)
                 // eslint-disable-next-line no-restricted-syntax -- nothing to narrate, nothing a cancel could save
                 .rpcManager.call(getRpcSessionId(self), 'CoreGetMetadata', {
-                adapterConfig: self.adapterConfig,
+                adapterConfig,
             })
                 .catch((e) => {
                 if (cached?.promise === promise) {
@@ -33,7 +33,7 @@ export function createAdapterMetadataFetch(self) {
                 }
                 throw e;
             });
-            cached = { key, promise };
+            cached = { adapterConfig, promise };
         }
         return cached.promise;
     };

package/esm/util/addAndShowTrack.d.ts

@@ -16,7 +16,4 @@ export declare function addAndShowTrack(session: SessionWithAddSessionTrack, con
     trackId: string;
 }, view?: {
     launchTrack: (trackId: string) => Promise<unknown>;
-}): (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<Record<string, any>> & {
-    setSubschema(slotName: string, data: Record<string, unknown>): any;
-    setSlot(slotName: string, value: unknown): void;
-} & import("@jbrowse/mobx-state-tree").IStateTreeNode<import("../configuration/types.ts").AnyConfigurationSchemaType>) | undefined;
+}): import("../configuration/types.ts").AnyConfigurationModel | undefined;

package/esm/util/addRelativeUris.d.ts

@@ -1,6 +1,7 @@
 /**
- * Stamp `baseUri` next to every `uri` in a config so relative URIs resolve
- * against the location the config itself was loaded from. jbrowse-web runs this
+ * Stamp `baseUri` next to every `uri` in a config, and beside a MultiWiggle
+ * `bigWigs` array of bare URI strings, so relative URIs resolve against the
+ * location the config itself was loaded from. jbrowse-web runs this
  * when it fetches a config.json from a URL; anything that injects a fetched
  * config as an object (a hub, a track hub connection, a headless render) has to
  * run it too, or the config's relative data URIs resolve against the page.
@@ -9,6 +10,13 @@
  * schema and expandAssemblyConfigShorthand read `baseUri` back out.
  */
 export declare function addRelativeUris(config: Record<string, unknown> | null, base: URL): void;
+/**
+ * A copy of `config` with every relative URI stamped against the page, which
+ * is what the page itself would resolve it against. An RPC worker started from
+ * a `blob:` URL has no such base, so a location it receives without one fails
+ * to parse there.
+ */
+export declare function withPageBaseUri<T>(config: T): T;
 /**
  * Inverse of {@link addRelativeUris}: recursively delete every synthetic
  * `baseUri` key (mutates in place), e.g. before serializing a config snapshot

package/esm/util/addRelativeUris.js

@@ -1,6 +1,7 @@
 /**
- * Stamp `baseUri` next to every `uri` in a config so relative URIs resolve
- * against the location the config itself was loaded from. jbrowse-web runs this
+ * Stamp `baseUri` next to every `uri` in a config, and beside a MultiWiggle
+ * `bigWigs` array of bare URI strings, so relative URIs resolve against the
+ * location the config itself was loaded from. jbrowse-web runs this
  * when it fetches a config.json from a URL; anything that injects a fetched
  * config as an object (a hub, a track hub connection, a headless render) has to
  * run it too, or the config's relative data URIs resolve against the page.
@@ -11,16 +12,30 @@
 export function addRelativeUris(config, base) {
     if (typeof config === 'object' && config !== null) {
         for (const key of Object.keys(config)) {
-            if (typeof config[key] === 'object' && config[key] !== null) {
-                addRelativeUris(config[key], base);
+            const value = config[key];
+            if (typeof value === 'object' && value !== null) {
+                addRelativeUris(value, base);
             }
-            else if (key === 'uri') {
-                // fill only when absent, so a node carrying its own baseUri wins
-                config.baseUri = config.baseUri ?? base.href;
+            if (key === 'uri' || (key === 'bigWigs' && Array.isArray(value))) {
+                config.baseUri ??= base.href;
             }
         }
     }
 }
+/**
+ * A copy of `config` with every relative URI stamped against the page, which
+ * is what the page itself would resolve it against. An RPC worker started from
+ * a `blob:` URL has no such base, so a location it receives without one fails
+ * to parse there.
+ */
+export function withPageBaseUri(config) {
+    if (typeof document === 'undefined' || config === undefined) {
+        return config;
+    }
+    const copy = structuredClone(config);
+    addRelativeUris(copy, new URL(document.baseURI));
+    return copy;
+}
 /**
  * Inverse of {@link addRelativeUris}: recursively delete every synthetic
  * `baseUri` key (mutates in place), e.g. before serializing a config snapshot

package/esm/util/addTrackFromWidget.d.ts

@@ -82,13 +82,10 @@ export declare function addTrackFromWidget({ model, session, conf, }: {
         name?: string;
         assemblyNames?: (string | undefined)[];
     };
-}): (import("@jbrowse/mobx-state-tree").$EmptyObjectBrand & Partial<{
+}): import("../configuration/types.ts").AnyConfigurationModel | (import("@jbrowse/mobx-state-tree").$EmptyObjectBrand & Partial<{
     [x: string]: any;
 }> & {
     trackId: string;
     name?: string;
     assemblyNames?: (string | undefined)[];
-}) | (import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<Record<string, any>> & {
-    setSubschema(slotName: string, data: Record<string, unknown>): any;
-    setSlot(slotName: string, value: unknown): void;
-} & IStateTreeNode<import("../configuration/types.ts").AnyConfigurationSchemaType>) | undefined;
+}) | undefined;

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/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.js

@@ -29,10 +29,11 @@ const MAX_HANDLE_PX = 200;
 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

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/cachedSetup.d.ts

@@ -17,7 +17,7 @@ type OnProgress = (current: number, total?: number) => void;
  *   moment that fetch was superseded — the display's latest-wins guard gates the
  *   old callback off — so the fetch replacing it awaited a multi-GB parse behind
  *   a blank loading overlay.
- * - **`stopToken` is withheld from the shared work.** Honoring one caller's
+ * - **`signal` is withheld from the shared work.** Honoring one caller's
  *   cancel would abort a parse the caller replacing it is already waiting on,
  *   and reject them both. A superseded fetch just stops listening. Cancellation
  *   stays with the per-call work (indexed range queries), which no one else is

package/esm/util/cachedSetup.js

@@ -15,7 +15,7 @@ import { downloadStatus } from './progress.js';
  *   moment that fetch was superseded — the display's latest-wins guard gates the
  *   old callback off — so the fetch replacing it awaited a multi-GB parse behind
  *   a blank loading overlay.
- * - **`stopToken` is withheld from the shared work.** Honoring one caller's
+ * - **`signal` is withheld from the shared work.** Honoring one caller's
  *   cancel would abort a parse the caller replacing it is already waiting on,
  *   and reject them both. A superseded fetch just stops listening. Cancellation
  *   stays with the per-call work (indexed range queries), which no one else is
@@ -39,7 +39,7 @@ export function cachedSetup({ setup, label, }) {
     const run = (opts, onProgress) => {
         cached ??= setup({
             ...opts,
-            stopToken: undefined,
+            signal: undefined,
             statusCallback: status => {
                 for (const cb of waiting) {
                     cb(status);