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

package/esm/ui/palette.js

@@ -231,16 +231,16 @@ const darkNeutrals = {
 export const colorFwdStrand = '#EC8B8B';
 /** #color alignments-strand | Reverse strand | Read maps to the reverse strand */
 export const colorRevStrand = '#8F8FD8';
-/** #color alignments-pair-orientation | LR (→ ←, normal proper pair) | Concordant */
+/** #color alignments-pair-orientation | LR (→ ←) | Normal proper pair */
 export const colorPairLR = '#d3d3d3';
 // Dimmer grey for dark mode: the light #d3d3d3 reads as near-white glaring
 // blocks against a dark track background. Wired into the dark alignmentFill.
 export const colorPairLRDark = '#8a8a8a';
-/** #color alignments-pair-orientation | RL (← →, mates point away from each other) | Abnormal orientation */
+/** #color alignments-pair-orientation | RL (← →) | Mates point away from each other */
 export const colorPairRL = '#0099bb';
-/** #color alignments-pair-orientation | LL (→ →, both mates forward strand) | Abnormal orientation */
+/** #color alignments-pair-orientation | LL (→ →) | Both mates on the forward strand */
 export const colorPairLL = '#4d9a4d';
-/** #color alignments-pair-orientation | RR (← ←, both mates reverse strand) | Abnormal orientation */
+/** #color alignments-pair-orientation | RR (← ←) | Both mates on the reverse strand */
 export const colorPairRR = '#5555bb';
 // Was `colorNostrand`, which named the one thing it essentially never paints. A
 // SAM record's strand is DEFINED from the reverse flag inside the adapter's
@@ -266,8 +266,8 @@ export const colorPairRR = '#5555bb';
 // settle it, and the dark-mode half is `agent-docs/TODO.md`.
 export const colorNeutralRead = '#c8c8c8';
 /**
- * #color alignments-pair-orientation | Inter-chromosomal | Mate maps to a different chromosome; colored distinctly rather than by orientation
- * #color alignments-insert-size | Mate on a different chromosome | Suggests an inter-chromosomal event
+ * #color alignments-pair-orientation | Inter-chromosomal | Mate on another chromosome
+ * #color alignments-insert-size | Inter-chromosomal | Mate on another chromosome
  */
 // THIS SLOT AND `colorUnmappedMate` WERE CHOSEN TOGETHER, and reading either one
 // alone is how the previous pair got stuck. Both are warm, both belong to all
@@ -299,9 +299,9 @@ export const colorNeutralRead = '#c8c8c8';
 // neighbour that must not be confusable: red means "insert too long", and a
 // second red would read as a second statement about insert size.
 export const colorInterchrom = '#af4d19';
-/** #color alignments-insert-size | Insert larger than expected | Suggests a deletion spanning the pair */
+/** #color alignments-insert-size | Insert larger than expected | Deletion between the mates */
 export const colorLongInsert = '#ff0000';
-/** #color alignments-insert-size | Insert smaller than expected | Suggests an insertion between the pair */
+/** #color alignments-insert-size | Insert smaller than expected | Insertion between the mates */
 // This slot has TWO neighbours it must stay clear of, and every past value has
 // solved one by walking into the other. They sit at opposite ends of the
 // lightness axis, which is what makes it a balance rather than a direction:
@@ -349,8 +349,8 @@ export const colorLongInsert = '#ff0000';
 // them.
 export const colorShortInsert = '#f582c0';
 /**
- * #color alignments-pair-orientation | Mate unmapped | The other end of the pair aligned nowhere, so orientation and insert size say nothing
- * #color alignments-insert-size | Mate unmapped | The other end of the pair aligned nowhere, so insert size says nothing
+ * #color alignments-pair-orientation | Mate unmapped | Mate aligned nowhere
+ * #color alignments-insert-size | Mate unmapped | Mate aligned nowhere
  */
 // A NON-COLOUR, at the dark end of the neutral scale on BOTH themes. It takes
 // the first half of the `readOverlap` pattern and not the second, and that split
@@ -421,7 +421,7 @@ export const colorUnmappedMate = '#000000';
 // the least that still reads as a read rather than as a hole.
 export const colorUnmappedMateDark = '#4a4a4a';
 export const colorLongreadInv = '#7755bb';
-/** #color alignments-pair-orientation | Split paired-end read (inverted) | A paired read's supplementary segment maps opposite-strand to its primary, so the junction is inverted — an inversion or an inverted duplication */
+/** #color alignments-pair-orientation | Split read (inverted) | Supplementary segment on the opposite strand to its primary */
 export const colorSplitReadInversion = '#9b30b0';
 export const colorSupplementary = '#f0b878';
 // Qualitative palette for coloring reads by an arbitrary tag value (e.g. the HP

package/esm/ui/promotablePinCoverage.d.ts

@@ -26,10 +26,24 @@ export declare function displayTypesWithPromotableSlots(displayTypes: readonly {
  * Reads `pin.control.slot` and nothing else. A raw `endAdornment` is
  * deliberately not counted: it is an arbitrary element (synteny's colour
  * swatch), so it cannot say which slot it promotes, and a pin built by hand
- * rather than through `promotableToggleItem`/`promotableRadioItem` is a thing to
- * find, not to accept.
+ * rather than through `makePin`/`makeTogglePin` is a thing to find, not to
+ * accept.
  */
 export declare function pinnedSlots(items: MenuItem[]): Set<string>;
+/**
+ * Rows whose pin is the wrong kind for the row, submenus included: a checkbox
+ * row carrying a value pin, or a radio row carrying a toggle pin. Empty is the
+ * healthy answer.
+ *
+ * The row builders type the option so this cannot happen through them; this
+ * is for a `pin` written by hand as a literal, which the type system lets
+ * through as the union. A checkbox row's pin has to be the toggle kind because
+ * that is what a click beside a checkbox is read as — "turn this on for all" —
+ * and a value pin there applies the row's *current* state instead, which
+ * beside an unchecked box is a visible no-op. That shipped once (2026-09-07)
+ * and was caught in a live session, not by a test; this is the test.
+ */
+export declare function misKindedPins(items: MenuItem[]): string[];
 /**
  * A display's promotable slots that its own track menu offers no pin for,
  * sorted. Empty is the healthy answer.

package/esm/ui/promotablePinCoverage.js

@@ -23,6 +23,7 @@
  * result against a baseline.
  */
 import { promotableSlotNames } from '../configuration/promotableSlots.js';
+import { resolveSubMenu } from './MenuTypes.js';
 /**
  * The registered display types whose config schema declares a promotable slot,
  * sorted — the set a pin-coverage check has to reach, answered off the
@@ -50,8 +51,8 @@ export function displayTypesWithPromotableSlots(displayTypes) {
  * Reads `pin.control.slot` and nothing else. A raw `endAdornment` is
  * deliberately not counted: it is an arbitrary element (synteny's colour
  * swatch), so it cannot say which slot it promotes, and a pin built by hand
- * rather than through `promotableToggleItem`/`promotableRadioItem` is a thing to
- * find, not to accept.
+ * rather than through `makePin`/`makeTogglePin` is a thing to find, not to
+ * accept.
  */
 export function pinnedSlots(items) {
     const found = new Set();
@@ -61,7 +62,43 @@ export function pinnedSlots(items) {
                 found.add(item.pin.control.slot);
             }
             if ('subMenu' in item) {
-                walk(item.subMenu);
+                walk(resolveSubMenu(item));
+            }
+        }
+    };
+    walk(items);
+    return found;
+}
+/**
+ * Rows whose pin is the wrong kind for the row, submenus included: a checkbox
+ * row carrying a value pin, or a radio row carrying a toggle pin. Empty is the
+ * healthy answer.
+ *
+ * The row builders type the option so this cannot happen through them; this
+ * is for a `pin` written by hand as a literal, which the type system lets
+ * through as the union. A checkbox row's pin has to be the toggle kind because
+ * that is what a click beside a checkbox is read as — "turn this on for all" —
+ * and a value pin there applies the row's *current* state instead, which
+ * beside an unchecked box is a visible no-op. That shipped once (2026-09-07)
+ * and was caught in a live session, not by a test; this is the test.
+ */
+export function misKindedPins(items) {
+    const found = [];
+    const walk = (list) => {
+        for (const item of list) {
+            if ('pin' in item && item.pin && 'type' in item) {
+                const { kind } = item.pin.control;
+                const wanted = item.type === 'checkbox'
+                    ? 'toggle'
+                    : item.type === 'radio'
+                        ? 'value'
+                        : undefined;
+                if (wanted && kind !== wanted) {
+                    found.push(`${item.pin.label}: ${kind} pin on a ${item.type} row`);
+                }
+            }
+            if ('subMenu' in item) {
+                walk(resolveSubMenu(item));
             }
         }
     };

package/esm/ui/theme.js

@@ -209,6 +209,11 @@ const baseThemeOptions = {
         MuiFormLabel: {
             styleOverrides: darkModeContrastOverride(['&.Mui-focused']),
         },
+        // the rail, track and thumb are all `currentColor` off the root, so a
+        // midnight root paints the whole control dark-on-dark
+        MuiSlider: {
+            styleOverrides: darkModeContrastOverride(),
+        },
         MuiAccordionSummary: {
             styleOverrides: {
                 root: ({ theme: t }) => ({

package/esm/ui/toggleMenuItems.d.ts

@@ -1,3 +1,4 @@
+import type { TogglePin, ValuePin } from '../configuration/promotablePin.ts';
 import type { CheckboxMenuItem, MenuItem, RadioMenuItem } from './MenuTypes.ts';
 export interface SettingRowOptions {
     helpText?: string;
@@ -5,8 +6,14 @@ export interface SettingRowOptions {
     disabledHelpText?: string;
     keepMenuOpen?: boolean;
 }
-/** #menuBuilder checkboxItem | one checkbox setting row */
-export declare function checkboxItem(label: string, checked: boolean, onToggle: () => void, opts?: SettingRowOptions): CheckboxMenuItem;
+export interface CheckboxRowOptions extends SettingRowOptions {
+    pin?: TogglePin;
+}
+export interface RadioRowOptions extends SettingRowOptions {
+    pin?: ValuePin;
+}
+/** #menuBuilder checkboxItem | one checkbox setting row, with a toggle pin when the setting is promotable */
+export declare function checkboxItem(label: string, checked: boolean, onToggle: () => void, opts?: CheckboxRowOptions): CheckboxMenuItem;
 /**
  * #menuBuilder toggleItem | a checkbox row whose setter takes the new value
  *
@@ -23,17 +30,15 @@ export declare function checkboxItem(label: string, checked: boolean, onToggle:
  * `SettingRowOptions` to a hand-narrowed one-field bag — the exact drift the
  * comment on that interface warns about.
  */
-export declare function toggleItem(label: string, value: boolean, setValue: (value: boolean) => void, opts?: SettingRowOptions): CheckboxMenuItem;
+export declare function toggleItem(label: string, value: boolean, setValue: (value: boolean) => void, opts?: CheckboxRowOptions): CheckboxMenuItem;
 /** #menuBuilder radioItem | one radio setting row; the singular of `radioItems` */
-export declare function radioItem(label: string, checked: boolean, onClick: () => void, opts?: SettingRowOptions): RadioMenuItem;
-export interface RadioOption<T extends string> {
+export declare function radioItem(label: string, checked: boolean, onClick: () => void, opts?: RadioRowOptions): RadioMenuItem;
+export interface RadioOption<T extends string> extends SettingRowOptions {
     value: T;
     label: string;
-    helpText?: string;
-    keepMenuOpen?: boolean;
 }
-/** #menuBuilder radioItems | a radio group, one row per option */
-export declare function radioItems<T extends string>(options: readonly RadioOption<T>[], current: T | undefined, setMode: (m: T) => void): RadioMenuItem[];
+/** #menuBuilder radioItems | a radio group, one row per option, with a value pin per option when the setting is promotable */
+export declare function radioItems<T extends string>(options: readonly RadioOption<T>[], current: T | undefined, setMode: (m: T) => void, pin?: (value: T) => ValuePin): RadioMenuItem[];
 /**
  * #menuBuilder withSubHeader | a section heading, present only if the section is
  *

package/esm/ui/toggleMenuItems.js

@@ -1,12 +1,16 @@
-/** #menuBuilder checkboxItem | one checkbox setting row */
-export function checkboxItem(label, checked, onToggle, opts) {
-    return {
+function withPin(row, pin) {
+    return pin ? { ...row, pin: { control: pin, label: row.label } } : row;
+}
+/** #menuBuilder checkboxItem | one checkbox setting row, with a toggle pin when the setting is promotable */
+export function checkboxItem(label, checked, onToggle, opts = {}) {
+    const { pin, ...rest } = opts;
+    return withPin({
         label,
         type: 'checkbox',
         checked,
         onClick: onToggle,
-        ...opts,
-    };
+        ...rest,
+    }, pin);
 }
 /**
  * #menuBuilder toggleItem | a checkbox row whose setter takes the new value
@@ -29,24 +33,37 @@ export function toggleItem(label, value, setValue, opts) {
         setValue(!value);
     }, opts);
 }
-// One radio row. The singular of `radioItems`, and what
-// `promotableRadioItem` builds through, so a lone radio row and a member of a
-// group are the same object plus or minus its pin.
+// One radio row. The singular of `radioItems`, for a group the plural form
+// can't express: a row with no single value to promote yet (the colorBy
+// "Tag..." row before a tag is picked), a display whose slot isn't promotable
+// at all (the shared colorBy menu on gwas/variants), or a group gated row by
+// row and mixing in a non-promotable peer (the alignments size presets and
+// their "Custom..." row). **Reach for `radioItems` first**: every option in a
+// group has to get a pin, and hand-naming the rows is what leaves one without.
 /** #menuBuilder radioItem | one radio setting row; the singular of `radioItems` */
-export function radioItem(label, checked, onClick, opts) {
-    return {
+export function radioItem(label, checked, onClick, opts = {}) {
+    const { pin, ...rest } = opts;
+    return withPin({
         label,
         type: 'radio',
         checked,
         onClick,
-        ...opts,
-    };
+        ...rest,
+    }, pin);
 }
-/** #menuBuilder radioItems | a radio group, one row per option */
-export function radioItems(options, current, setMode) {
+// `pin` is a factory rather than a per-option field so a promotable group can't
+// be a row short. **Every option in a group gets a pin, the `promotedBase`
+// value included**: once a non-base value is promoted, taking the base row's
+// offer is the per-value way to undo it, and a radio group with one row silently
+// missing its trailing control reads as a bug. `sashimiArcsMode`'s base looked
+// unpinnable precisely because each row had been named by hand. Pass
+// `value => makePin(self, slot, value)`, or a model member of that shape where
+// the menu module is handed a duck-typed model (alignments).
+/** #menuBuilder radioItems | a radio group, one row per option, with a value pin per option when the setting is promotable */
+export function radioItems(options, current, setMode, pin) {
     return options.map(({ value, label, ...opts }) => radioItem(label, current === value, () => {
         setMode(value);
-    }, opts));
+    }, { ...opts, pin: pin?.(value) }));
 }
 /**
  * #menuBuilder withSubHeader | a section heading, present only if the section is

package/esm/util/Base1DUtils.d.ts

@@ -121,7 +121,7 @@ export declare function bpToPx({ refName, coord, displayedRegionIndex, self, }:
  * Undefined when no displayed region holds the coord, same as `bpToPx`; a
  * caller that means "as far as the region goes" clamps before asking.
  */
-export declare function bpToOffset({ refName, coord, displayedRegions, }: {
+export declare function bpToOffset({ refName, coord, displayedRegions, displayedRegionIndex, }: {
     refName: string;
     coord: number;
     displayedRegions: {
@@ -130,6 +130,7 @@ export declare function bpToOffset({ refName, coord, displayedRegions, }: {
         end: number;
         reversed?: boolean;
     }[];
+    displayedRegionIndex?: number;
 }): BpOffset | undefined;
 /**
  * Where a 0-based genomic coord sits in the LINEARIZED bp space — the
@@ -145,7 +146,7 @@ export declare function bpToOffset({ refName, coord, displayedRegions, }: {
  * `undefined` when no displayed region holds the coord, exactly as `bpToPx`
  * answers: a refName the view is not showing has no place on its screen.
  */
-export declare function bpToLinearBp({ refName, coord, displayedRegions, }: {
+export declare function bpToLinearBp({ refName, coord, displayedRegions, displayedRegionIndex, }: {
     refName: string;
     coord: number;
     displayedRegions: {
@@ -154,6 +155,7 @@ export declare function bpToLinearBp({ refName, coord, displayedRegions, }: {
         end: number;
         reversed?: boolean;
     }[];
+    displayedRegionIndex?: number;
 }): number | undefined;
 /**
  * Screen order of two {@link BpOffset}s: negative when `a` is to the left of

package/esm/util/Base1DUtils.js

@@ -187,9 +187,12 @@ export function bpToPx({ refName, coord, displayedRegionIndex, self, }) {
  * Undefined when no displayed region holds the coord, same as `bpToPx`; a
  * caller that means "as far as the region goes" clamps before asking.
  */
-export function bpToOffset({ refName, coord, displayedRegions, }) {
+export function bpToOffset({ refName, coord, displayedRegions, displayedRegionIndex, }) {
     for (const [index, r] of displayedRegions.entries()) {
-        if (refName === r.refName && coord >= r.start && coord <= r.end) {
+        if (refName === r.refName &&
+            coord >= r.start &&
+            coord <= r.end &&
+            (displayedRegionIndex === undefined || displayedRegionIndex === index)) {
             return { refName, index, offset: bpOffsetInRegion(r, coord) };
         }
     }
@@ -209,8 +212,13 @@ export function bpToOffset({ refName, coord, displayedRegions, }) {
  * `undefined` when no displayed region holds the coord, exactly as `bpToPx`
  * answers: a refName the view is not showing has no place on its screen.
  */
-export function bpToLinearBp({ refName, coord, displayedRegions, }) {
-    const at = bpToOffset({ refName, coord, displayedRegions });
+export function bpToLinearBp({ refName, coord, displayedRegions, displayedRegionIndex, }) {
+    const at = bpToOffset({
+        refName,
+        coord,
+        displayedRegions,
+        displayedRegionIndex,
+    });
     return at ? cumulativeBp(displayedRegions, at.index, at.offset) : undefined;
 }
 /**

package/esm/util/SvgCanvas.js

@@ -479,9 +479,10 @@ export class SvgCanvas {
     // The family goes through, not just the size: `measureText` switches to the
     // fixed monospace advance on seeing one, so dropping it measured a monospace
     // string against the proportional table — the same string, laid out one way on
-    // a real canvas and another in the export, with nothing to show which. No draw
-    // function calls ctx.measureText today; this is here so the first one to do it
-    // doesn't inherit a silent discrepancy.
+    // a real canvas and another in the export, with nothing to show which. An
+    // estimate all the same: a draw whose layout turns on a width (synteny's
+    // off-screen mate labels) measures through a real canvas and passes the
+    // result in, so the figure names what the screen named.
     measureText(text) {
         const { size, family } = parseFont(this.font);
         return { width: measureTextWidth(text, Number(size), family) };

package/esm/util/adapterConfigKey.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The adapter-config axis of a fetch key: the config a fetch was issued
+ * against, as one string. Every fetch that refetches on an adapter edit folds
+ * this in — the comparative displays, the prerequisite reads, the density
+ * tier, the global family's signature — so the axis is spelled once and cannot
+ * drift between them.
+ *
+ * Not `adapterConfigCacheKey`: that one short-circuits on `adapterId`, which is
+ * right for sharing one adapter instance and wrong for freshness, where an
+ * edit to a config carrying an id still has to read as a different fetch.
+ */
+export declare function adapterConfigKey(adapterConfig: Record<string, unknown>): string;

package/esm/util/adapterConfigKey.js

@@ -0,0 +1,14 @@
+/**
+ * The adapter-config axis of a fetch key: the config a fetch was issued
+ * against, as one string. Every fetch that refetches on an adapter edit folds
+ * this in — the comparative displays, the prerequisite reads, the density
+ * tier, the global family's signature — so the axis is spelled once and cannot
+ * drift between them.
+ *
+ * Not `adapterConfigCacheKey`: that one short-circuits on `adapterId`, which is
+ * right for sharing one adapter instance and wrong for freshness, where an
+ * edit to a config carrying an id still has to read as a different fetch.
+ */
+export function adapterConfigKey(adapterConfig) {
+    return JSON.stringify(adapterConfig);
+}

package/esm/util/adapterMetadata.js

@@ -1,3 +1,4 @@
+import { adapterConfigKey } from './adapterConfigKey.js';
 import { getRpcSessionId } from './parentWalk.js';
 import { getRpcHost } from './sessionServices.js';
 /**
@@ -19,7 +20,7 @@ import { getRpcHost } from './sessionServices.js';
 export function createAdapterMetadataFetch(self) {
     let cached;
     return () => {
-        const key = JSON.stringify(self.adapterConfig);
+        const key = adapterConfigKey(self.adapterConfig);
         if (cached?.key !== key) {
             const promise = getRpcHost(self)
                 // eslint-disable-next-line no-restricted-syntax -- nothing to narrate, nothing a cancel could save

package/esm/util/addAndShowTrack.d.ts

@@ -15,7 +15,7 @@ import type { SessionWithAddSessionTrack } from './types/index.ts';
 export declare function addAndShowTrack(session: SessionWithAddSessionTrack, conf: Parameters<SessionWithAddSessionTrack['addSessionTrackConf']>[0] & {
     trackId: string;
 }, view?: {
-    showTrack: (trackId: string) => void;
+    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;

package/esm/util/addAndShowTrack.js

@@ -16,8 +16,12 @@ export function addAndShowTrack(session, conf, view) {
     // addSessionTrackConf already notified on an invalid conf; showing a trackId
     // that was never added would only add a second "Could not resolve identifier"
     // snackbar
+    //
+    // `launchTrack`, voided: the display's state model may still be a dynamic
+    // import away, and every caller here is a menu item or a dialog button whose
+    // return value is the added config rather than the opened track
     if (added) {
-        view?.showTrack(conf.trackId);
+        void view?.launchTrack(conf.trackId);
     }
     return added;
 }

package/esm/util/addTrackFromWidget.js

@@ -68,7 +68,7 @@ export function addTrackFromWidget({ model, session, conf, }) {
             session.notify(`Could not add "${conf.name ?? conf.trackId}": the view it was being added to has closed, and it uses an assembly that only that view had.`, 'warning');
             return undefined;
         }
-        trackContainer.showTrack(conf.trackId, {}, {}, conf);
+        void trackContainer.launchTrack(conf.trackId, {}, {}, conf);
         finishAddTrack(model, session);
         return conf;
     }
@@ -77,7 +77,7 @@ export function addTrackFromWidget({ model, session, conf, }) {
         return undefined;
     }
     if (containerDisplaysAssembly(trackContainer, conf.assemblyNames, session.assemblyManager)) {
-        trackContainer?.showTrack(conf.trackId);
+        void trackContainer?.launchTrack(conf.trackId);
     }
     else {
         const assemblies = conf.assemblyNames?.filter(a => !!a) ?? [];

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

package/esm/util/cacheBudgets.d.ts

@@ -1,10 +1,10 @@
 import { SharedBudget } from '@gmod/shared-read-cache';
 /**
- * Ceilings on what the indexed-format libraries retain, shared by every adapter
- * in this JS context — so one per RPC worker, plus one on the main thread,
- * which is the scope that actually runs out of memory.
+ * The ceiling on what the indexed-format libraries retain, shared by every
+ * adapter in this JS context — so one per RPC worker, plus one on the main
+ * thread, which is the scope that actually runs out of memory.
  *
- * ## Why these are not per file
+ * ## Why this is not per file
  *
  * `@gmod/bam`, `@gmod/tabix` and `@gmod/cram` each take a per-file budget,
  * sized so that a single track panning never falls off the cliff where a cache
@@ -29,24 +29,27 @@ import { SharedBudget } from '@gmod/shared-read-cache';
  * at hand their space to the one being panned, so the active track keeps a
  * whole working set however many are open.
  *
- * ## The numbers are not new
+ * ## The number is not new
  *
- * Both are the libraries' own per-file defaults, moved from per-file to
- * per-context. That makes this a strict tightening — retention can only fall —
- * and avoids inventing a number that would need its own justification. The
- * budget still has to clear one query's working set or the cliff returns, and
- * on that workload 512 MB shared across three tracks already cost 43 refills
- * where 1 GB cost 4.
+ * 1 GB is the libraries' own per-file default (`DEFAULT_MAX_CACHE_BYTES` in
+ * both `@gmod/bam` and `@gmod/cram`), moved from per-file to per-context. That
+ * makes this a strict tightening — retention can only fall — and avoids
+ * inventing a number that would need its own justification. With one file open
+ * the two ceilings coincide; from the second file on, this one is the one that
+ * binds. The budget still has to clear one query's working set or the cliff
+ * returns, and on that workload 512 MB shared across three tracks already cost
+ * 43 refills where 1 GB cost 4.
  *
- * ## Two budgets, because units cannot mix
+ * ## One budget, because every member weighs bytes
  *
  * `SharedBudget.total` is a sum over its members, so they must all weigh in the
- * same unit. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes;
- * `@gmod/cram` weighs decoded records, because a decoded record has no cheap
- * size. A single budget spanning them would add records to bytes and bound
- * neither. `sizeOf` is opaque, so nothing can catch that at runtime — hence two
- * budgets named for their units.
+ * same unit, and `sizeOf` is opaque, so nothing could catch a mismatch at
+ * runtime. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes, and since 14
+ * `@gmod/cram` weighs a decoded slice by `DecodedSlice.byteLength` — its typed
+ * columns exactly and its strings by estimate, within 1–8% of the measured heap
+ * (its ADR 0013). Before that a CRAM slice weighed its record count, which is
+ * why this used to be two budgets named for their units: a million records
+ * could not be added to bytes, and never bound long-read data either, where a
+ * 6 MB slice counted as 37.
  */
 export declare const decompressedBytesBudget: SharedBudget;
-/** See {@link decompressedBytesBudget}. Records, not bytes — CRAM only. */
-export declare const decodedRecordsBudget: SharedBudget;

package/esm/util/cacheBudgets.js

@@ -1,10 +1,10 @@
 import { SharedBudget } from '@gmod/shared-read-cache';
 /**
- * Ceilings on what the indexed-format libraries retain, shared by every adapter
- * in this JS context — so one per RPC worker, plus one on the main thread,
- * which is the scope that actually runs out of memory.
+ * The ceiling on what the indexed-format libraries retain, shared by every
+ * adapter in this JS context — so one per RPC worker, plus one on the main
+ * thread, which is the scope that actually runs out of memory.
  *
- * ## Why these are not per file
+ * ## Why this is not per file
  *
  * `@gmod/bam`, `@gmod/tabix` and `@gmod/cram` each take a per-file budget,
  * sized so that a single track panning never falls off the cliff where a cache
@@ -29,24 +29,27 @@ import { SharedBudget } from '@gmod/shared-read-cache';
  * at hand their space to the one being panned, so the active track keeps a
  * whole working set however many are open.
  *
- * ## The numbers are not new
+ * ## The number is not new
  *
- * Both are the libraries' own per-file defaults, moved from per-file to
- * per-context. That makes this a strict tightening — retention can only fall —
- * and avoids inventing a number that would need its own justification. The
- * budget still has to clear one query's working set or the cliff returns, and
- * on that workload 512 MB shared across three tracks already cost 43 refills
- * where 1 GB cost 4.
+ * 1 GB is the libraries' own per-file default (`DEFAULT_MAX_CACHE_BYTES` in
+ * both `@gmod/bam` and `@gmod/cram`), moved from per-file to per-context. That
+ * makes this a strict tightening — retention can only fall — and avoids
+ * inventing a number that would need its own justification. With one file open
+ * the two ceilings coincide; from the second file on, this one is the one that
+ * binds. The budget still has to clear one query's working set or the cliff
+ * returns, and on that workload 512 MB shared across three tracks already cost
+ * 43 refills where 1 GB cost 4.
  *
- * ## Two budgets, because units cannot mix
+ * ## One budget, because every member weighs bytes
  *
  * `SharedBudget.total` is a sum over its members, so they must all weigh in the
- * same unit. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes;
- * `@gmod/cram` weighs decoded records, because a decoded record has no cheap
- * size. A single budget spanning them would add records to bytes and bound
- * neither. `sizeOf` is opaque, so nothing can catch that at runtime — hence two
- * budgets named for their units.
+ * same unit, and `sizeOf` is opaque, so nothing could catch a mismatch at
+ * runtime. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes, and since 14
+ * `@gmod/cram` weighs a decoded slice by `DecodedSlice.byteLength` — its typed
+ * columns exactly and its strings by estimate, within 1–8% of the measured heap
+ * (its ADR 0013). Before that a CRAM slice weighed its record count, which is
+ * why this used to be two budgets named for their units: a million records
+ * could not be added to bytes, and never bound long-read data either, where a
+ * 6 MB slice counted as 37.
  */
 export const decompressedBytesBudget = new SharedBudget(1024 * 2 ** 20);
-/** See {@link decompressedBytesBudget}. Records, not bytes — CRAM only. */
-export const decodedRecordsBudget = new SharedBudget(1_000_000);

package/esm/util/clampToContig.d.ts

@@ -24,3 +24,20 @@ export declare function clampToContig(assembly: Assembly, region: {
     start: number;
     end: number;
 }): Region | undefined;
+/**
+ * `clampToContig` for a refName that may not be on the assembly at all, which
+ * is the shape a location nobody requested arrives in — a BAM's `nextRef`, an
+ * SA record's contig (REFNAME_NAMESPACES.md). `clampToContig` alone passes an
+ * unknown name through with nothing to clamp against, so it cannot tell "past
+ * the end of a contig we have" from "a contig we do not have", and both callers
+ * need that apart to say which happened.
+ */
+export declare function clampToListedContig(assembly: Assembly, region: {
+    refName: string;
+    start: number;
+    end: number;
+}): {
+    refName: string;
+    onAssembly: boolean;
+    region: Region | undefined;
+};