@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/bandHeight.d.ts

@@ -0,0 +1,53 @@
+export declare const MIN_BAND_HEIGHT = 20;
+/** The legal range for one band. Both ends are optional and both are px. */
+export interface BandBounds {
+    /** Defaults to {@link MIN_BAND_HEIGHT}. */
+    min?: number;
+    /** Defaults to unbounded. A band above a plot should always state one. */
+    max?: number;
+}
+/**
+ * #api core/util
+ * Bound a band height to its legal range — a config value, a menu choice, or a
+ * slider position, i.e. anywhere the number is being *stated* rather than
+ * dragged.
+ *
+ * The **floor** keeps the band operable at its smallest: for a drag-resized
+ * band that means keeping the handle grabbable, for a menu-sized one it is the
+ * height below which its content stops reading. The **ceiling** stops a band
+ * from swallowing the plot it sits over — every display floors its plot area at
+ * 0, so an unbounded band takes the rows to zero height rather than to a
+ * scrollbar, and takes the band's own handle off-screen with them.
+ *
+ * The bounds differ per band and the rule does not, which is why this takes them
+ * rather than each band re-deriving the reasoning — that is how the two
+ * `clampBandHeight`s in this repo drifted apart, each ending up with one half of
+ * this rule and a doc comment claiming to be the whole of it.
+ */
+export declare function boundBandHeight(n: number, { min, max }?: BandBounds): number;
+/**
+ * #api core/util
+ * Clamp one *resize* of a drag-resizable band: {@link boundBandHeight}, plus the
+ * one rule a resize needs that a stated height does not.
+ *
+ * The floor becomes `min(bounds.min, current)`, never the bare bound: a band
+ * whose config declares it smaller than the floor must stay where it is. Taking
+ * the bare floor instead made the *first* drag on such a band jump it up to the
+ * floor before honoring the delta. A band at or above the floor is unaffected,
+ * one below it can still be dragged but never smaller than it already is, and
+ * one dragged back past the floor regains it.
+ *
+ * The ceiling is not relaxed the same way — a band already over its ceiling is
+ * the state the user is trying to escape, so a resize brings it back inside.
+ *
+ * `ResizeHandle` emits one delta per animation frame, so callers driving a drag
+ * pass `current + distance` as the target and read `current` inside the action —
+ * a component computing the target from a rendered height drops every tick that
+ * lands before React re-renders.
+ *
+ * @param current - the band's height right now, in px
+ * @param target - the height this resize is asking for, in px
+ * @param bounds - the band's legal range; `max` should be derived from the
+ *   display height so the plot below cannot be squashed to nothing
+ */
+export declare function clampBandHeight(current: number, target: number, bounds?: BandBounds): number;

package/esm/util/bandHeight.js

@@ -0,0 +1,56 @@
+// Default floor for a user-resizable band (an alignments coverage / arc /
+// sashimi band, a MAF coverage / conservation band), in px. It exists so the
+// drag handle stays grabbable, which is a constraint on dragging, not on what
+// config may declare. Bands with their own vocabulary of "too small" pass their
+// own (the variant lane's 8 is where a record stops reading as a mark).
+export const MIN_BAND_HEIGHT = 20;
+/**
+ * #api core/util
+ * Bound a band height to its legal range — a config value, a menu choice, or a
+ * slider position, i.e. anywhere the number is being *stated* rather than
+ * dragged.
+ *
+ * The **floor** keeps the band operable at its smallest: for a drag-resized
+ * band that means keeping the handle grabbable, for a menu-sized one it is the
+ * height below which its content stops reading. The **ceiling** stops a band
+ * from swallowing the plot it sits over — every display floors its plot area at
+ * 0, so an unbounded band takes the rows to zero height rather than to a
+ * scrollbar, and takes the band's own handle off-screen with them.
+ *
+ * The bounds differ per band and the rule does not, which is why this takes them
+ * rather than each band re-deriving the reasoning — that is how the two
+ * `clampBandHeight`s in this repo drifted apart, each ending up with one half of
+ * this rule and a doc comment claiming to be the whole of it.
+ */
+export function boundBandHeight(n, { min = MIN_BAND_HEIGHT, max = Number.POSITIVE_INFINITY } = {}) {
+    return Math.min(max, Math.max(min, Math.round(n)));
+}
+/**
+ * #api core/util
+ * Clamp one *resize* of a drag-resizable band: {@link boundBandHeight}, plus the
+ * one rule a resize needs that a stated height does not.
+ *
+ * The floor becomes `min(bounds.min, current)`, never the bare bound: a band
+ * whose config declares it smaller than the floor must stay where it is. Taking
+ * the bare floor instead made the *first* drag on such a band jump it up to the
+ * floor before honoring the delta. A band at or above the floor is unaffected,
+ * one below it can still be dragged but never smaller than it already is, and
+ * one dragged back past the floor regains it.
+ *
+ * The ceiling is not relaxed the same way — a band already over its ceiling is
+ * the state the user is trying to escape, so a resize brings it back inside.
+ *
+ * `ResizeHandle` emits one delta per animation frame, so callers driving a drag
+ * pass `current + distance` as the target and read `current` inside the action —
+ * a component computing the target from a rendered height drops every tick that
+ * lands before React re-renders.
+ *
+ * @param current - the band's height right now, in px
+ * @param target - the height this resize is asking for, in px
+ * @param bounds - the band's legal range; `max` should be derived from the
+ *   display height so the plot below cannot be squashed to nothing
+ */
+export function clampBandHeight(current, target, bounds = {}) {
+    const { min = MIN_BAND_HEIGHT } = bounds;
+    return boundBandHeight(target, { ...bounds, min: Math.min(min, current) });
+}

package/esm/util/bandLayout.d.ts

@@ -0,0 +1,51 @@
+import type { BandBounds } from './bandHeight.ts';
+/**
+ * #api core/util
+ * One band of a display's vertical stack — a coverage histogram, an arc strip,
+ * a conservation row, a variant lane. The contract is the pair: `active` is
+ * whether the band exists right now (the display pre-ANDs its settings half,
+ * `showX`, with its data half, "some lane has ink"), and `height` is the stated
+ * height when it does. Consumers read pixels through {@link reservedPx} or
+ * {@link stackBands}, never by re-combining the pair — the re-combination is
+ * where the reserver and the painter historically drifted.
+ */
+export interface Band {
+    active: boolean;
+    /** The stated height in px, meaningful only while `active`. */
+    height: number;
+    /**
+     * Present ⇒ `height` is bound at read time ({@link boundBandHeight}), for a
+     * band whose stored value may be stale or hand-edited. Absent ⇒ the stated
+     * height is trusted as-is; the setters are the only gate.
+     */
+    bounds?: BandBounds;
+}
+/**
+ * #api core/util
+ * The pixels a band takes from the plot below it: 0 when off, the (optionally
+ * bound) stated height when on. This is the single spelling of "off spends
+ * 0 px".
+ */
+export declare function reservedPx(band: Band): number;
+/** What {@link stackBands} derives: one top per band, and where the stack ends. */
+export interface BandStack<K extends string> {
+    /** Content-space y where each band begins, in stack order. */
+    top: Record<K, number>;
+    /** Each band's {@link reservedPx}. */
+    reserved: Record<K, number>;
+    /** Where the content below the stack begins — the sum of every reserved px. */
+    bottom: number;
+}
+/**
+ * #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.
+ *
+ * Only the fold is shared. What varies per display stays there: 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.
+ */
+export declare function stackBands<K extends string>(order: readonly K[], bands: Record<K, Band>): BandStack<K>;

package/esm/util/bandLayout.js

@@ -0,0 +1,36 @@
+import { boundBandHeight } from './bandHeight.js';
+/**
+ * #api core/util
+ * The pixels a band takes from the plot below it: 0 when off, the (optionally
+ * bound) stated height when on. This is the single spelling of "off spends
+ * 0 px".
+ */
+export function reservedPx(band) {
+    if (!band.active) {
+        return 0;
+    }
+    return band.bounds ? boundBandHeight(band.height, band.bounds) : band.height;
+}
+/**
+ * #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.
+ *
+ * Only the fold is shared. What varies per display stays there: 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.
+ */
+export function stackBands(order, bands) {
+    const top = {};
+    const reserved = {};
+    let y = 0;
+    for (const key of order) {
+        top[key] = y;
+        reserved[key] = reservedPx(bands[key]);
+        y += reserved[key];
+    }
+    return { top, reserved, bottom: y };
+}

package/esm/util/bezierConnector.d.ts

@@ -0,0 +1,14 @@
+export declare const BEZIER_CONNECTOR_MAX_REACH_PX: number;
+export declare function bezierConnectorPath({ x1, y1, x2, y2, s1, s2, leadingEnd2, reversed1, reversed2, maxHandlePx, dip, }: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    s1: number;
+    s2: number;
+    leadingEnd2?: boolean;
+    reversed1?: boolean;
+    reversed2?: boolean;
+    maxHandlePx?: number;
+    dip?: boolean;
+}): string;

package/esm/util/bezierConnector.js

@@ -0,0 +1,108 @@
+// One horizontal-tangent "oval" connector curve, shared by the alignments
+// linked-read bezier overlay (PileupBezierOverlay) and BreakpointSplitView's
+// AlignmentConnections so the two renderers draw a connection identically. Both
+// describe the same thing — two read endpoints (from the shared
+// connectionEndpoints rule), each segment's strand, and whether the second end
+// is a split junction's 5' edge — and this owns the curve geometry, so the
+// direction logic can't drift between them.
+// A handle or bow larger than the endpoints' own separation folds the cubic
+// back over itself: the curve leaves along its tangent, overshoots the far
+// endpoint, and has to curl back to arrive — the "loop-de-loop"/squiggle seen
+// on tightly-spaced reads. So every shaping term stays under this fraction of
+// the span the curve actually has to cover. Endpoints that nearly touch
+// therefore get no shaping at all and draw as the straight line they should be.
+const SPAN_FACTOR = 0.3;
+// Ceiling on the control-handle length. The span budget is what actually scales
+// the handle — it resolves below this for any connection whose endpoints are
+// closer than ~667px apart, which is nearly all of them — so this only bites on
+// very wide arcs. There it bounds the fold-back hook that an inversion draws at
+// 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;
+// 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.
+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.
+//
+// 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
+// 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;
+// 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
+// *into* the next segment (a fwd→rev inversion folds back instead of cutting
+// straight across). `reversed` flips screen-x for a reverse-complemented region.
+function tangentSign(strand, leading, reversed) {
+    return strand * (leading ? -1 : 1) * (reversed ? -1 : 1);
+}
+// How much shaping (handle length, bow height) this curve may spend: a fraction
+// of the distance it has to cover.
+function shapingBudget(p1, p2) {
+    return Math.hypot(p2.x - p1.x, p2.y - p1.y) * SPAN_FACTOR;
+}
+// Fades to zero as the endpoints' rows separate, since a cross-row curve
+// already has vertical extent — and via the budget as they close in
+// horizontally, since a short connector is legible without a hump.
+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}`;
+}
+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, }) {
+    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);
+    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

@@ -0,0 +1,78 @@
+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.
+ */
+export declare function sharedBgzfWorkerPool(): Promise<BgzfWorkerPool | undefined>;

package/esm/util/bgzfWorkerPool.js

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+export function sharedBgzfWorkerPool() {
+    return import('@gmod/bgzf-filehandle')
+        .then(m => m.getSharedWorkerPool())
+        .catch(() => undefined);
+}

package/esm/util/blockTypes.d.ts

@@ -1,59 +1,78 @@
+interface BlockData {
+    key: string;
+    offsetPx: number;
+    widthPx: number;
+    assemblyName?: string;
+    refName?: string;
+    start?: number;
+    end?: number;
+    reversed?: boolean;
+    displayedRegionIndex?: number;
+    isLeftEndOfDisplayedRegion?: boolean;
+    isRightEndOfDisplayedRegion?: boolean;
+    variant?: 'boundary';
+}
+export interface ContentBlock extends BlockData {
+    type: 'ContentBlock';
+    assemblyName: string;
+    refName: string;
+    start: number;
+    end: number;
+}
+export interface ElidedBlock extends BlockData {
+    type: 'ElidedBlock';
+}
+export interface InterRegionPaddingBlock extends BlockData {
+    type: 'InterRegionPaddingBlock';
+}
+export type BaseBlock = ContentBlock | ElidedBlock | InterRegionPaddingBlock;
+/**
+ * A content block as a region that addresses whole bases.
+ *
+ * `calculateDynamicBlocks` says in its own docstring that start/end may be
+ * FRACTIONAL — a block is a span of screen, and the view is only at a whole
+ * base when the pan and the zoom both happen to land there. Anything naming
+ * bases rather than pixels needs this: a sequence fetch, a bookmark, and above
+ * all a locString, since `BP_QUANTITY_SOURCE` rejects a bare fractional
+ * coordinate on purpose ("a bare '1.5' as a coordinate is a mistake").
+ *
+ * `reversed` is dropped with the pixels. It orients a projection, and a region
+ * that has left the screen is not being projected; carrying it only reached
+ * `assembleLocString`, which spells it `[rev]` in a field the user is about to
+ * read.
+ */
+export declare function wholeBaseRegion(block: ContentBlock): {
+    assemblyName: string;
+    refName: string;
+    start: number;
+    end: number;
+};
+export declare function wholeBaseRegions(blocks: ContentBlock[]): {
+    assemblyName: string;
+    refName: string;
+    start: number;
+    end: number;
+}[];
 type Func<T> = (value: BaseBlock, index: number, array: BaseBlock[]) => T;
 export declare class BlockSet {
     blocks: BaseBlock[];
     constructor(blocks?: BaseBlock[]);
-    [Symbol.iterator](): Generator<BaseBlock, void, unknown>;
     push(block: BaseBlock): void;
-    getBlocks(): BaseBlock[];
-    getRegions(): {
-        refName: string;
-        start: number;
-        end: number;
-        assemblyName: string;
-        reversed: boolean | undefined;
-    }[];
+    /**
+     * Widen a trailing elided run by widthPx, reporting whether there was one to
+     * widen. `push` keeps nothing but the width off an ElidedBlock it merges, so
+     * a caller holding the width can skip building the block that would have
+     * carried it — which at whole-genome zoom is nearly every region, see
+     * calculateDynamicBlocks.
+     */
+    growElidedRun(widthPx: number): boolean;
     map<T, U = this>(func: Func<T>, thisarg?: U): T[];
     forEach<T, U = this>(func: Func<T>, thisarg?: U): void;
     get length(): number;
     get totalWidthPx(): number;
     get totalWidthPxWithoutBorders(): number;
     get offsetPx(): number;
-    get contentBlocks(): BaseBlock[];
+    get contentBlocks(): ContentBlock[];
     get totalBp(): number;
 }
-export declare class BaseBlock {
-    type: string;
-    regionNumber?: number;
-    reversed?: boolean;
-    refName: string;
-    start: number;
-    end: number;
-    assemblyName: string;
-    key: string;
-    offsetPx: number;
-    widthPx: number;
-    variant?: string;
-    isLeftEndOfDisplayedRegion?: boolean;
-    constructor(data: Record<string, any>);
-    toRegion(): {
-        refName: string;
-        start: number;
-        end: number;
-        assemblyName: string;
-        reversed: boolean | undefined;
-    };
-}
-export declare class ContentBlock extends BaseBlock {
-    type: string;
-}
-export declare class ElidedBlock extends BaseBlock {
-    type: string;
-    widthPx: number;
-    elidedBlockCount: number;
-    constructor(data: Record<string, any>);
-    push(otherBlock: ElidedBlock): void;
-}
-export declare class InterRegionPaddingBlock extends BaseBlock {
-    type: string;
-}
 export {};