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

package/esm/ui/MenuTypes.d.ts

@@ -127,11 +127,20 @@ export interface RadioMenuItem extends BaseMenuItem {
     checked: boolean;
     onClick: MenuItemClickHandler;
 }
-/** #menuItem subMenu | nests another `MenuItem[]`, to any depth */
+/**
+ * #menuItem subMenu | nests another `MenuItem[]`, or a function building one, to any depth
+ *
+ * The function form is called when the submenu opens (or a walker asks for its
+ * rows), not when the parent menu is built — for a submenu whose rows cost a
+ * scan of the display's data to name. Read the field through `resolveSubMenu`
+ * rather than by hand, so the two forms stay one thing to the renderer, the
+ * pin-coverage walk and every test helper that flattens a menu.
+ */
 export interface SubMenuItem extends BaseMenuItem {
     type?: 'subMenu';
-    subMenu: MenuItem[];
+    subMenu: MenuItem[] | (() => MenuItem[]);
 }
+export declare function resolveSubMenu(item: SubMenuItem): MenuItem[];
 /**
  * #menuItem custom | renders arbitrary React content inline, e.g. a slider
  *

package/esm/ui/MenuTypes.js

@@ -1,3 +1,6 @@
+export function resolveSubMenu(item) {
+    return typeof item.subMenu === 'function' ? item.subMenu() : item.subMenu;
+}
 // #endregion
 /**
  * Whether clicking a row leaves the menu up — the rule `CascadingMenu` applies,

package/esm/ui/PaletteContext.d.ts

@@ -40,8 +40,9 @@ export interface ThemeModeSession {
  * hook and the provider in one.
  *
  * How the host knows its own mode is the host's business — an attribute on
- * `<html>`, a `prefers-color-scheme` media query, a design-system context —
- * and deliberately not this hook's.
+ * `<html>`, a design-system context, a toggle in its own state. Pass no mode
+ * and JBrowse follows `prefers-color-scheme` instead, tracking OS changes; a
+ * host whose mode is only ever the OS preference has nothing to write.
  *
  * **Both halves are load-bearing, which is why the pairing is published as a
  * component.** The palette is what *React* draws with; the config `theme` slot
@@ -55,7 +56,7 @@ export interface ThemeModeSession {
  * the previous palette. That is a frame on a canvas that is about to be
  * redrawn anyway; it is not somewhere to add a suspense boundary.
  */
-export declare function useSessionPalette(session: ThemeModeSession, mode: 'light' | 'dark'): JBrowsePalette;
+export declare function useSessionPalette(session: ThemeModeSession, mode?: 'light' | 'dark'): JBrowsePalette;
 /**
  * #api
  * Make JBrowse follow the host's light/dark state — the whole of it, in one
@@ -67,6 +68,12 @@ export declare function useSessionPalette(session: ThemeModeSession, mode: 'ligh
  * </SessionPaletteProvider>
  * ```
  *
+ * `mode` is optional. Left out, JBrowse follows `prefers-color-scheme` and
+ * re-themes when the OS preference changes, through the same session write an
+ * explicit mode takes — so a host whose dark mode *is* the OS preference mounts
+ * this with a session and nothing else. Pass a mode as soon as the host has a
+ * toggle of its own, since the media query cannot see it.
+ *
  * A component rather than a documented pair of calls because the pair has a
  * half that can be left out with nothing to show for it. `PaletteProvider` is
  * the name a host reaches for, and it colors the React side alone; the session
@@ -80,6 +87,6 @@ export declare function useSessionPalette(session: ThemeModeSession, mode: 'ligh
  */
 export declare function SessionPaletteProvider({ session, mode, children, }: {
     session: ThemeModeSession;
-    mode: 'light' | 'dark';
+    mode?: 'light' | 'dark';
     children: ReactNode;
 }): import("react").JSX.Element;

package/esm/ui/PaletteContext.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, use, useEffect, useMemo } from 'react';
+import { createContext, use, useEffect, useMemo, useSyncExternalStore, } from 'react';
 import { defaultStyleTheme } from './styleTheme.js';
 /**
  * How a React component asks for JBrowse's design tokens.
@@ -47,6 +47,27 @@ export function useStyleTheme() {
 export function usePalette() {
     return useStyleTheme().palette;
 }
+function darkSchemeQuery() {
+    return typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-color-scheme: dark)')
+        : undefined;
+}
+function subscribeToColorScheme(onChange) {
+    const media = darkSchemeQuery();
+    media?.addEventListener('change', onChange);
+    return () => {
+        media?.removeEventListener('change', onChange);
+    };
+}
+function readColorScheme() {
+    return darkSchemeQuery()?.matches ? 'dark' : 'light';
+}
+const alwaysLight = () => 'light';
+const subscribeToNothing = () => () => { };
+function useResolvedMode(mode) {
+    const systemMode = useSyncExternalStore(mode === undefined ? subscribeToColorScheme : subscribeToNothing, mode === undefined ? readColorScheme : alwaysLight, alwaysLight);
+    return mode === undefined ? systemMode : mode;
+}
 /**
  * Point a session at light or dark and get back the palette it resolves to,
  * for a host that wants the palette itself — to read a color out of, or to
@@ -55,8 +76,9 @@ export function usePalette() {
  * hook and the provider in one.
  *
  * How the host knows its own mode is the host's business — an attribute on
- * `<html>`, a `prefers-color-scheme` media query, a design-system context —
- * and deliberately not this hook's.
+ * `<html>`, a design-system context, a toggle in its own state. Pass no mode
+ * and JBrowse follows `prefers-color-scheme` instead, tracking OS changes; a
+ * host whose mode is only ever the OS preference has nothing to write.
  *
  * **Both halves are load-bearing, which is why the pairing is published as a
  * component.** The palette is what *React* draws with; the config `theme` slot
@@ -71,9 +93,10 @@ export function usePalette() {
  * redrawn anyway; it is not somewhere to add a suspense boundary.
  */
 export function useSessionPalette(session, mode) {
+    const resolved = useResolvedMode(mode);
     useEffect(() => {
-        session.setThemeMode(mode);
-    }, [session, mode]);
+        session.setThemeMode(resolved);
+    }, [session, resolved]);
     return session.palette;
 }
 /**
@@ -87,6 +110,12 @@ export function useSessionPalette(session, mode) {
  * </SessionPaletteProvider>
  * ```
  *
+ * `mode` is optional. Left out, JBrowse follows `prefers-color-scheme` and
+ * re-themes when the OS preference changes, through the same session write an
+ * explicit mode takes — so a host whose dark mode *is* the OS preference mounts
+ * this with a session and nothing else. Pass a mode as soon as the host has a
+ * toggle of its own, since the media query cannot see it.
+ *
  * A component rather than a documented pair of calls because the pair has a
  * half that can be left out with nothing to show for it. `PaletteProvider` is
  * the name a host reaches for, and it colors the React side alone; the session

package/esm/ui/PinAdornment.js

@@ -38,25 +38,31 @@ function pinPredicate(onValue) {
 }
 // The click, which is not the state the pin draws: an outline pin applies the
 // value to the open tracks, a filled one clears the default it stands for.
+//
+// The aria-label carries "of this type" wherever the tooltip does: it used to
+// stop at "for all open tracks", stating a wider blast radius than the control
+// has.
 function pinCopy(label, onValue, isDefault) {
     return isDefault
         ? {
             title: `${label} is ${pinPredicate(onValue)} for all tracks of this type (click to clear)`,
-            ariaLabel: `clear the default for ${label}`,
+            ariaLabel: `clear the default for ${label} for all tracks of this type`,
         }
         : typeof onValue === 'boolean'
             ? {
                 title: `Turn ${label} ${onValue ? 'on' : 'off'} for all open tracks of this type`,
-                ariaLabel: `turn ${label} ${onValue ? 'on' : 'off'} for all open tracks`,
+                ariaLabel: `turn ${label} ${onValue ? 'on' : 'off'} for all open tracks of this type`,
             }
             : {
                 title: `Apply ${label} to all open tracks of this type`,
-                ariaLabel: `apply ${label} to all open tracks`,
+                ariaLabel: `apply ${label} to all open tracks of this type`,
             };
 }
-// Trailing pin for a promotable setting, rendered as a menu item's
-// `endAdornment` beside the value check. A ToggleButton (native button a11y + a
-// clear selected tint) with a pin — distinct from the value checkbox.
+// Trailing pin for a promotable setting, drawn beside the value check from the
+// row's `pin` declaration (`menuItemAdornment` builds this; a row never
+// constructs it, which is what keeps MUI out of the eager menu-builder graph). A
+// ToggleButton (native button a11y + a clear selected tint) with a pin —
+// distinct from the value checkbox.
 //
 // **The click and the state are two different things.** One click writes the
 // value into every open track of this display type and raises a snackbar

package/esm/ui/index.d.ts

@@ -70,7 +70,7 @@ export type { SlotExtensionPointName, SlotProps, WrapperProps, } from './wrapCom
 export { matchesTrackSelector } from './extensionSelectors.ts';
 export type { TrackSelector } from './extensionSelectors.ts';
 export type { BaseMenuItem, CheckboxMenuItem, ClickableMenuItem, CustomMenuItem, MenuDivider, MenuItem, MenuItemClickHandler, MenuItemsGetter, MenuSubHeader, NormalMenuItem, RadioMenuItem, SubMenuItem, } from './MenuTypes.ts';
-export { staysOpenOnClick } from './MenuTypes.ts';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.ts';
 export { LAUNCH_LABEL, pushIntoSubMenu, pushLaunchViewMenuItem, } from './launchViewMenu.ts';
 export { launchTargetsMenuItem } from './launchTargetsMenuItem.ts';
 export { default as Crosshairs } from './Crosshairs.tsx';

package/esm/ui/index.js

@@ -65,7 +65,7 @@ export { default as PluggableElements } from './PluggableElements.js';
 export { addExtensionElement } from './addExtensionElement.js';
 export { wrapComponent } from './wrapComponent.js';
 export { matchesTrackSelector } from './extensionSelectors.js';
-export { staysOpenOnClick } from './MenuTypes.js';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.js';
 export { LAUNCH_LABEL, pushIntoSubMenu, pushLaunchViewMenuItem, } from './launchViewMenu.js';
 export { launchTargetsMenuItem } from './launchTargetsMenuItem.js';
 export { default as Crosshairs } from './Crosshairs.js';

package/esm/ui/launchViewMenu.js

@@ -10,7 +10,13 @@ export const LAUNCH_LABEL = 'Launch';
 export function pushIntoSubMenu(items, label, item) {
     const existing = items.find((i) => i.type === 'subMenu' && i.label === label);
     if (existing) {
-        existing.subMenu.push(item);
+        const { subMenu } = existing;
+        if (typeof subMenu === 'function') {
+            existing.subMenu = () => [...subMenu(), item];
+        }
+        else {
+            subMenu.push(item);
+        }
     }
     else {
         items.push({ label, type: 'subMenu', subMenu: [item] });

package/esm/ui/legendMenuItem.d.ts

@@ -14,11 +14,11 @@ import type { MenuItem } from './MenuTypes.ts';
  * values legitimately differ (a Hi-C color scale is off by default, a variant
  * genotype key on), and their descriptions describe genuinely different legends.
  * What they now share is being *promotable* — pass `opts.pin` and the row gains
- * the pin that makes the current state this display type's session-wide
- * default. Every display whose legend is backed by a config slot passes one,
- * and gets it from `LegendMixin`'s `showLegendDisplayTypeDefault` rather than
- * calling `makePin` itself: the slot is the per-display half, the accessors
- * over it are not.
+ * the pin that applies the current state to every open track of this display
+ * type, offering the display-type default as its snackbar's one action. Every
+ * display whose legend is backed by a config slot passes one, and gets it from
+ * `LegendMixin`'s `showLegendDisplayTypeDefault` rather than calling `makePin`
+ * itself: the slot is the per-display half, the accessors over it are not.
  *
  * `pin` is optional because two callers have no slot to promote: the Manhattan
  * plot's LD legend and `LinearBasicDisplay`'s color key are a volatile and a

package/esm/ui/legendMenuItem.js

@@ -14,11 +14,11 @@ import { checkboxItem } from './toggleMenuItems.js';
  * values legitimately differ (a Hi-C color scale is off by default, a variant
  * genotype key on), and their descriptions describe genuinely different legends.
  * What they now share is being *promotable* — pass `opts.pin` and the row gains
- * the pin that makes the current state this display type's session-wide
- * default. Every display whose legend is backed by a config slot passes one,
- * and gets it from `LegendMixin`'s `showLegendDisplayTypeDefault` rather than
- * calling `makePin` itself: the slot is the per-display half, the accessors
- * over it are not.
+ * the pin that applies the current state to every open track of this display
+ * type, offering the display-type default as its snackbar's one action. Every
+ * display whose legend is backed by a config slot passes one, and gets it from
+ * `LegendMixin`'s `showLegendDisplayTypeDefault` rather than calling `makePin`
+ * itself: the slot is the per-display half, the accessors over it are not.
  *
  * `pin` is optional because two callers have no slot to promote: the Manhattan
  * plot's LD legend and `LinearBasicDisplay`'s color key are a volatile and a

package/esm/ui/makeSizeMenu.js

@@ -51,7 +51,7 @@ export function makeSizeSubMenu(opts) {
 // The same row over a **promotable** slot, which derives both halves the plain
 // form takes by hand — the reset button's enablement (`isSlotCustomized`) and
 // the "default for all tracks of this type" pin — from the one slot name. A
-// slider has no fixed on-value, so the pin promotes whatever the track is
+// slider has no fixed on-value, so the pin carries whatever the track is
 // currently showing.
 //
 // Naming the slot once is the point: the call sites used to spell it twice, in

package/esm/ui/menuItems.d.ts

@@ -24,5 +24,5 @@ export { makeRadioSubMenu } from './radioSubMenu.ts';
 export { showLegendCheckboxItem } from './legendMenuItem.ts';
 export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from './promotableMenuItems.ts';
 export type { RadioOption, SettingRowOptions } from './toggleMenuItems.ts';
-export { staysOpenOnClick } from './MenuTypes.ts';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.ts';
 export type { BaseMenuItem, CheckboxMenuItem, ClickableMenuItem, CustomMenuItem, MenuDivider, MenuItem, MenuItemClickHandler, MenuItemPin, MenuItemsGetter, MenuSubHeader, NormalMenuItem, RadioMenuItem, SubMenuItem, } from './MenuTypes.ts';

package/esm/ui/menuItems.js

@@ -23,4 +23,4 @@ export { withHint } from './menuLabels.js';
 export { makeRadioSubMenu } from './radioSubMenu.js';
 export { showLegendCheckboxItem } from './legendMenuItem.js';
 export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from './promotableMenuItems.js';
-export { staysOpenOnClick } from './MenuTypes.js';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.js';

package/esm/ui/promotableMenuItems.js

@@ -10,10 +10,10 @@ import { checkboxItem, radioItem, radioItems } from './toggleMenuItems.js';
 // written that way — `checkboxItem` / `radioItems` build the row — so the
 // promotable and plain forms of a row can differ only by the pin.
 // A promotable setting as one native checkbox menu row: the value toggles the
-// track (inheriting native hover/sizing/keyboard), and a trailing pin
-// (endAdornment) applies this value to every open track of the display type,
-// offering the display-type default as its snackbar's one action. Always shown
-// so the capability is discoverable.
+// track (inheriting native hover/sizing/keyboard), and a trailing pin applies
+// this value to every open track of the display type, offering the display-type
+// default as its snackbar's one action. Always shown so the capability is
+// discoverable.
 //
 // **The row itself is `checkboxItem`'s**, so the two builders can only ever
 // differ by the pin. They used to be two literals, and had already drifted: this
@@ -61,8 +61,10 @@ export function promotableRadioItem({ label, checked, onClick, pin, ...opts }) {
 }
 // A whole promotable radio group: `radioItems` plus one pin per option. The
 // plural form of the builder above, and the one to reach for on a group whose
-// options differ only in their value — which is all four of them today
-// (`heightMode`, `displayMode`, `subfeatureLabels`, `sashimiArcsMode`).
+// options differ only in their value — which is all five of them today
+// (`heightMode`, `displayMode`, `showLabels`, `subfeatureLabels`,
+// `sashimiArcsMode`; the two label groups reach it through canvas's
+// `inlineRadioGroup`).
 //
 // **Every option in a group gets a pin, the `promotedBase` value included** —
 // once a non-base value is promoted, pinning the base back is the only per-value

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
@@ -61,7 +62,7 @@ export function pinnedSlots(items) {
                 found.add(item.pin.control.slot);
             }
             if ('subMenu' in item) {
-                walk(item.subMenu);
+                walk(resolveSubMenu(item));
             }
         }
     };

package/esm/ui/toggleMenuItems.d.ts

@@ -26,11 +26,9 @@ export declare function checkboxItem(label: string, checked: boolean, onToggle:
 export declare function toggleItem(label: string, value: boolean, setValue: (value: boolean) => void, opts?: SettingRowOptions): 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 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[];

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

@@ -110,6 +110,7 @@ export interface ActiveFetch {
  * passes a {@link createStatusChannel}, which is one volatile instead of two
  * fields and an action.
  */
+export type StopTokenRotation = ReturnType<typeof createStopTokenRotation>;
 export declare function createStopTokenRotation(self: IStateTreeNode, report: StatusReporter): {
     begin(): ActiveFetch;
     cancel: () => void;

package/esm/util/createStopTokenRotation.js

@@ -28,33 +28,6 @@ export function createStatusChannel() {
         },
     };
 }
-/**
- * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
- * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
- * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
- * `begin()` aborts the prior fetch's token and returns a fresh one plus an
- * `isCurrent()` guard that captures this run's token — gate every post-await
- * write on it and a superseded or torn-down fetch can never clobber fresher
- * data. The guard is the return value, so a caller can't forget to compare a
- * token by hand.
- *
- * `end()` in the run's `finally` is the other half, and for the same reason —
- * see {@link ActiveFetch.end} for the two things it does together.
- *
- * Owns the token mechanics and the status channel; the caller keeps its own
- * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
- * (so `cancelFetch` can reach it), `installFetch` one per installation (every
- * other fetch in the tree runs on that skeleton), and the synteny diagonalize
- * progress wrapper (`withDiagonalizeProgress`) directly.
- *
- * `report` is passed rather than read off `self`, so where the status lands is
- * the caller's decision and not a shape this imposes. A display passes itself —
- * its status fields are part of its own API, and one composing `FetchMixin`
- * passes the model-wide window along with them (see `StatusReporter`).
- * Anything with one operation to narrate and no status vocabulary of its own
- * passes a {@link createStatusChannel}, which is one volatile instead of two
- * fields and an action.
- */
 export function createStopTokenRotation(self, report) {
     let currentStopToken;
     // The host's window when it has one, so a display composing `FetchMixin` has
@@ -124,6 +97,13 @@ export function createStopTokenRotation(self, report) {
                 statusCallback: stream.statusCallback,
                 end() {
                     ended = true;
+                    // A completed fetch's token is released here, not only on supersede
+                    // or cancel — otherwise it pins its AbortSignal controllers (and blob
+                    // URL) until the next `begin()`, forever for a one-shot fetch that
+                    // succeeds and never reruns. `stopStopToken` is guarded, so the
+                    // superseded and cancelled runs that arrive here already-stopped cost
+                    // nothing.
+                    stopStopToken(stopToken);
                     if (openStream === stream) {
                         openStream = undefined;
                     }

package/esm/util/fetchContext.d.ts

@@ -39,8 +39,8 @@ export interface FetchContext {
 }
 /**
  * Build a {@link FetchContext} over a live fetch's primitives. One
- * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
- * carries the same `callRpc` envelope.
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
  *
  * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
  * means a track or something under it.** `rpcSessionId` is declared by

package/esm/util/fetchContext.js

@@ -3,8 +3,8 @@ import { createStatusFanOut } from './progress.js';
 import { getRpcHost } from './sessionServices.js';
 /**
  * Build a {@link FetchContext} over a live fetch's primitives. One
- * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
- * carries the same `callRpc` envelope.
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
  *
  * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
  * means a track or something under it.** `rpcSessionId` is declared by