@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/measureText.js

@@ -0,0 +1,51 @@
+// prettier-ignore
+const widths = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0.2796875, 0.2765625, 0.3546875, 0.5546875, 0.5546875, 0.8890625, 0.665625, 0.190625, 0.3328125, 0.3328125, 0.3890625, 0.5828125, 0.2765625, 0.3328125, 0.2765625, 0.3015625, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.2765625, 0.2765625, 0.584375, 0.5828125, 0.584375, 0.5546875, 1.0140625, 0.665625, 0.665625, 0.721875, 0.721875, 0.665625, 0.609375, 0.7765625, 0.721875, 0.2765625, 0.5, 0.665625, 0.5546875, 0.8328125, 0.721875, 0.7765625, 0.665625, 0.7765625, 0.721875, 0.665625, 0.609375, 0.721875, 0.665625, 0.94375, 0.665625, 0.665625, 0.609375, 0.2765625, 0.3546875, 0.2765625, 0.4765625, 0.5546875, 0.3328125, 0.5546875, 0.5546875, 0.5, 0.5546875, 0.5546875, 0.2765625, 0.5546875, 0.5546875, 0.221875, 0.240625, 0.5, 0.221875, 0.8328125, 0.5546875, 0.5546875, 0.5546875, 0.5546875, 0.3328125, 0.5, 0.2765625, 0.5546875, 0.5, 0.721875, 0.5, 0.5, 0.5, 0.3546875, 0.259375, 0.353125, 0.5890625];
+const avgWidth = 0.5279276315789471;
+// Advance width of one monospace glyph, in em — the same for every character,
+// which is what makes the table above unusable for one: it is Helvetica, where
+// `i` is 0.22em and `m` is 0.94em, so a monospace string of narrow letters
+// measures far too small and one of wide letters far too large. The mainstream
+// faces cluster tightly here (Courier and DejaVu Sans Mono 0.600, Menlo 0.602,
+// Liberation Mono 0.600, Consolas 0.550), and rounding *up* is the safe
+// direction for every caller: all of them measure to reserve room.
+const MONOSPACE_EM = 0.61;
+// xref https://gist.github.com/tophtucker/62f93a4658387bb61e4510c37e2e97cf
+//
+// `fontFamily` is only consulted to pick monospace, which is a different metric
+// rather than a different table. Proportional families are all measured against
+// the Helvetica table: it is what the app renders in, and for the two other
+// families the SVG export can be asked for it is close (system-ui) or narrower
+// (serif, which over-reserves — the harmless direction).
+export function measureText(str, fontSize = 10, fontFamily) {
+    const s = String(str);
+    if (fontFamily?.includes('monospace')) {
+        return s.length * MONOSPACE_EM * fontSize;
+    }
+    let total = 0;
+    for (let i = 0, l = s.length; i < l; i++) {
+        total += widths[s.charCodeAt(i)] ?? avgWidth;
+    }
+    return total * fontSize;
+}
+/**
+ * A CSS font string and its own measurement, built from one set of inputs so a
+ * caller cannot paint in one font and reserve room in another.
+ *
+ * Two files describing one font is the normal shape — something measures to
+ * decide whether a label fits, something else sets `ctx.font` and draws it — and
+ * the two drift silently, because a label that overflows its box by a pixel
+ * looks like a label. plugin-maf drew its deletion count in `bold 10px Courier
+ * New,monospace` and measured it here without naming the family, so a monospace
+ * label was answered from the Helvetica table above: 0.55px short per digit,
+ * which its 2px of padding covered for exactly three digits and no more.
+ *
+ * `weight` reaches the CSS and not the measurement, which is right for the
+ * digits these callers measure — monospace bold and regular share an advance,
+ * and Helvetica's ten digits are one width in either.
+ */
+export function measuredFont(fontSize, fontFamily, weight) {
+    return {
+        css: `${weight ? `${weight} ` : ''}${fontSize}px ${fontFamily}`,
+        measure: text => measureText(text, fontSize, fontFamily),
+    };
+}

package/esm/util/mst-reflection.d.ts

@@ -1,11 +1,21 @@
-import type { IAnyComplexType, IAnyType, IModelReflectionPropertiesData, ISimpleType, UnionStringArray } from '@jbrowse/mobx-state-tree';
+import type { IAnyType, IModelReflectionPropertiesData, ISimpleType, UnionStringArray } from '@jbrowse/mobx-state-tree';
 export interface ILiteralType<T> extends ISimpleType<T> {
     value: T;
 }
+/**
+ * get the inner type of an MST optional, refinement, array, map, or late type
+ */
 export declare function getSubType(type: IAnyType): IAnyType;
-export declare function getUnionSubTypes(unionType: IAnyType): IAnyType[];
+/**
+ * get the type of one of the properties of the given MST model type
+ */
 export declare function getPropertyType(type: IModelReflectionPropertiesData, propertyName: string): IAnyType;
+/**
+ * get the default value out of an MST optional type
+ */
 export declare function getDefaultValue(type: IAnyType): any;
 export type IEnumerationType<T extends string> = ISimpleType<UnionStringArray<T[]>>;
-export declare function getEnumerationValues(type: IAnyComplexType): string[];
-export declare function resolveLateType(maybeLate: IAnyType): any;
+/** get the string values of an MST enumeration type */
+export declare function getEnumerationValues(type: IAnyType): string[];
+export declare function resolveLateType(maybeLate: IAnyType): IAnyType;
+export { getUnionSubtypes as getUnionSubTypes } from '@jbrowse/mobx-state-tree';

package/esm/util/mst-reflection.js

@@ -1,54 +1,55 @@
-import { isArrayType, isLateType, isMapType, isOptionalType, isUnionType, } from '@jbrowse/mobx-state-tree';
-export function getSubType(type) {
-    let t;
-    if (isOptionalType(type)) {
-        t = type._subtype || type.type;
-    }
-    else if (isArrayType(type) || isMapType(type)) {
-        t = type._subtype || type._subType || type.subType;
-    }
-    else if (typeof type.getSubType === 'function') {
-        return type.getSubType();
-    }
-    else {
-        throw new TypeError('unsupported mst type');
-    }
-    if (!t) {
-        throw new Error('failed to get subtype');
-    }
-    return t;
+import { getUnionSubtypes, isArrayType, isLateType, isMapType, isOptionalType, isUnionType, } from '@jbrowse/mobx-state-tree';
+// MST's getSubTypes() returns this sentinel string when a type can't report a
+// single subtype. It isn't exported by name, so we detect it structurally: a
+// real subtype is an IAnyType object, never a string or null.
+function isSubtype(t) {
+    return typeof t === 'object' && t !== null;
 }
-export function getUnionSubTypes(unionType) {
-    if (!isUnionType(unionType)) {
-        throw new TypeError('not an MST union type');
+/**
+ * get the inner type of an MST optional, refinement, array, map, or late type
+ */
+export function getSubType(type) {
+    // optional/refinement/late report their wrapped type here; union returns an
+    // array (handled by getUnionSubTypes) and array/map return null
+    const sub = type.getSubTypes();
+    if (isSubtype(sub)) {
+        return sub;
     }
-    const t = unionType._types ||
-        unionType.types ||
-        getSubType(unionType)._types ||
-        getSubType(unionType).types;
-    if (!t) {
-        throw new Error('failed to extract subtypes from mst union');
+    if (isArrayType(type) || isMapType(type)) {
+        return type.getChildType();
     }
-    return t;
+    throw new TypeError('unsupported mst type');
 }
+/**
+ * get the type of one of the properties of the given MST model type
+ */
 export function getPropertyType(type, propertyName) {
     return type.properties[propertyName];
 }
+/**
+ * get the default value out of an MST optional type
+ */
 export function getDefaultValue(type) {
     if (!isOptionalType(type)) {
         throw new TypeError('type must be an optional type');
     }
-    return type._defaultValue || type.defaultValue;
+    // isOptionalType is a same-type guard, so narrow to the optional interface
+    // that publishes getDefaultInstanceOrSnapshot
+    return type.getDefaultInstanceOrSnapshot();
 }
+/** get the string values of an MST enumeration type */
 export function getEnumerationValues(type) {
-    const subtypes = getUnionSubTypes(type);
+    const subtypes = getUnionSubtypes(type);
+    // the subtypes should all be literals with a value member
     return subtypes.map(t => t.value);
 }
 export function resolveLateType(maybeLate) {
     if (!isUnionType(maybeLate) &&
         !isArrayType(maybeLate) &&
         isLateType(maybeLate)) {
-        return maybeLate.getSubType();
+        const sub = maybeLate.getSubTypes();
+        return isSubtype(sub) ? sub : maybeLate;
     }
     return maybeLate;
 }
+export { getUnionSubtypes as getUnionSubTypes } from '@jbrowse/mobx-state-tree';

package/esm/util/mstUtils.d.ts

@@ -0,0 +1,100 @@
+import type PluginManager from '../PluginManager.ts';
+import type { AbstractDisplayModel, AbstractSessionModel, AbstractViewContainer, AbstractTrackModel, AbstractViewModel } from './types/index.ts';
+import type { AssemblyHost, RenderingServices } from './types/renderingServices.ts';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+export { findParentThat, findParentThatIs, getRpcSessionId, } from './parentWalk.ts';
+/**
+ * #api core/util
+ * Returns the JBrowse session model for any node in the state tree. Throws if
+ * the node has no session ancestor.
+ */
+export declare function getSession(node: IAnyStateTreeNode): AbstractSessionModel;
+/**
+ * #api core/util
+ * Returns the view model that contains the given node. Throws if the node has no
+ * containing view.
+ */
+export declare function getContainingView(node: IAnyStateTreeNode): AbstractViewModel;
+/**
+ * #api core/util
+ * Returns the track model that contains the given node. Throws if the node has
+ * no containing track.
+ */
+export declare function getContainingTrack(node: IAnyStateTreeNode): AbstractTrackModel;
+/**
+ * #api core/util
+ * Returns the display model that contains the given node. Throws if the node has
+ * no containing display.
+ */
+export declare function getContainingDisplay(node: IAnyStateTreeNode): AbstractDisplayModel;
+/**
+ * #api core/util
+ * The host's assembly manager, for a module that resolves names and nothing
+ * else.
+ *
+ * Unlike the accessors in `sessionServices.ts` this one buys the caller no
+ * smaller type graph — an `AssemblyManager` is an MST model a `PluginManager`
+ * built, so naming it costs what naming a session costs. It is here to say
+ * which service is wanted, and because that cost is the finding: the assembly
+ * manager is the one thing on `AbstractSessionModel` a third-party host cannot
+ * simply implement.
+ */
+export declare function getAssemblyHost(node: IAnyStateTreeNode): AssemblyHost;
+/**
+ * #api core/util
+ * Everything a display needs of its host in order to draw a region: the
+ * assemblies, the RPC entry point and the colors.
+ */
+export declare function getRenderingServices(node: IAnyStateTreeNode): RenderingServices;
+/**
+ * #api core/util
+ * Resolve user-authored refName text against the assembly of the view
+ * containing `node` — the one normalization layer, which resolves aliases and
+ * casing together. Falls back to the input when the assembly is absent or its
+ * aliases have not loaded.
+ *
+ * Keyed off the VIEW's assembly rather than the track's, because the view is
+ * what the comparison is against: displayed regions, loaded regions and blocks
+ * all carry the refNames the view laid out.
+ *
+ * Reach for this wherever a refName a *person* wrote is about to be compared
+ * against regions, features or blocks, which carry the assembly's canonical
+ * name. A refName a display copied off a region is canonical already and needs
+ * nothing; one that arrived in a session spec, a config slot or a URL is
+ * whatever the author read out of the location box.
+ *
+ * Skipping it fails silently and, worse, assembly-dependently: `chr12` matches
+ * on an assembly canonicalized `chr12` and matches nothing on one canonicalized
+ * `12`, so the same spec key works on one config and quietly does nothing on
+ * the next, with no error for anyone to act on.
+ *
+ * Resolves through `getCanonicalRefName2`, whose fallback is what keeps a spec
+ * read before the alias file has loaded from throwing — and the getters that
+ * read user specs do run from the first render.
+ *
+ * Takes a refName, not a spec that might hold one: the resolver reads
+ * `refName.toLowerCase()`, so anything else throws once the aliases are there,
+ * and a caller reading an untyped `frozen` slot has to establish that it names
+ * a refName at all before this is the right question to ask of it.
+ */
+export declare function canonicalizeViewRefName(node: IAnyStateTreeNode, refName: string): string;
+/**
+ * #api core/util
+ * Returns the MST environment for a node, which carries the `pluginManager`.
+ */
+export declare function getEnv(obj: IAnyStateTreeNode): {
+    pluginManager: PluginManager;
+};
+/**
+ * #api core/util
+ * `addOrReplaceView` for view types whose state model may be lazily loaded;
+ * the synchronous `addOrReplaceView` requires it loaded already.
+ */
+export declare function launchOrReplaceView(args: {
+    session: AbstractViewContainer;
+    typeName: string;
+    initialState?: Record<string, unknown>;
+    replacing?: AbstractViewModel;
+}): Promise<AbstractViewModel>;
+export declare function hashCode(str: string): number;
+export declare function objectHash(obj: object): string;

package/esm/util/mstUtils.js

@@ -0,0 +1,140 @@
+import { getEnv as getEnvMST, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { cachedParent, findParentThatIs } from './parentWalk.js';
+import { addOrReplaceView, isDisplayModel, isSessionModel, isTrackModel, isViewModel, } from './types/index.js';
+export { findParentThat, findParentThatIs, getRpcSessionId, } from './parentWalk.js';
+const containingDisplayCache = new WeakMap();
+const containingTrackCache = new WeakMap();
+const containingViewCache = new WeakMap();
+const sessionCache = new WeakMap();
+/**
+ * #api core/util
+ * Returns the JBrowse session model for any node in the state tree. Throws if
+ * the node has no session ancestor.
+ */
+export function getSession(node) {
+    return cachedParent(sessionCache, node, () => findParentThatIs(node, isSessionModel), 'no session model found!');
+}
+/**
+ * #api core/util
+ * Returns the view model that contains the given node. Throws if the node has no
+ * containing view.
+ */
+export function getContainingView(node) {
+    return cachedParent(containingViewCache, node, () => findParentThatIs(node, isViewModel), 'no containing view found');
+}
+/**
+ * #api core/util
+ * Returns the track model that contains the given node. Throws if the node has
+ * no containing track.
+ */
+export function getContainingTrack(node) {
+    return cachedParent(containingTrackCache, node, () => findParentThatIs(node, isTrackModel), 'no containing track found');
+}
+/**
+ * #api core/util
+ * Returns the display model that contains the given node. Throws if the node has
+ * no containing display.
+ */
+export function getContainingDisplay(node) {
+    return cachedParent(containingDisplayCache, node, () => findParentThatIs(node, isDisplayModel), 'no containing display found');
+}
+/**
+ * #api core/util
+ * The host's assembly manager, for a module that resolves names and nothing
+ * else.
+ *
+ * Unlike the accessors in `sessionServices.ts` this one buys the caller no
+ * smaller type graph — an `AssemblyManager` is an MST model a `PluginManager`
+ * built, so naming it costs what naming a session costs. It is here to say
+ * which service is wanted, and because that cost is the finding: the assembly
+ * manager is the one thing on `AbstractSessionModel` a third-party host cannot
+ * simply implement.
+ */
+export function getAssemblyHost(node) {
+    return getSession(node);
+}
+/**
+ * #api core/util
+ * Everything a display needs of its host in order to draw a region: the
+ * assemblies, the RPC entry point and the colors.
+ */
+export function getRenderingServices(node) {
+    return getSession(node);
+}
+/**
+ * #api core/util
+ * Resolve user-authored refName text against the assembly of the view
+ * containing `node` — the one normalization layer, which resolves aliases and
+ * casing together. Falls back to the input when the assembly is absent or its
+ * aliases have not loaded.
+ *
+ * Keyed off the VIEW's assembly rather than the track's, because the view is
+ * what the comparison is against: displayed regions, loaded regions and blocks
+ * all carry the refNames the view laid out.
+ *
+ * Reach for this wherever a refName a *person* wrote is about to be compared
+ * against regions, features or blocks, which carry the assembly's canonical
+ * name. A refName a display copied off a region is canonical already and needs
+ * nothing; one that arrived in a session spec, a config slot or a URL is
+ * whatever the author read out of the location box.
+ *
+ * Skipping it fails silently and, worse, assembly-dependently: `chr12` matches
+ * on an assembly canonicalized `chr12` and matches nothing on one canonicalized
+ * `12`, so the same spec key works on one config and quietly does nothing on
+ * the next, with no error for anyone to act on.
+ *
+ * Resolves through `getCanonicalRefName2`, whose fallback is what keeps a spec
+ * read before the alias file has loaded from throwing — and the getters that
+ * read user specs do run from the first render.
+ *
+ * Takes a refName, not a spec that might hold one: the resolver reads
+ * `refName.toLowerCase()`, so anything else throws once the aliases are there,
+ * and a caller reading an untyped `frozen` slot has to establish that it names
+ * a refName at all before this is the right question to ask of it.
+ */
+export function canonicalizeViewRefName(node, refName) {
+    const { assemblyManager } = getSession(node);
+    const name = getContainingView(node).assemblyNames?.[0];
+    const assembly = name ? assemblyManager.get(name) : undefined;
+    return assembly?.getCanonicalRefName2(refName) ?? refName;
+}
+/**
+ * #api core/util
+ * Returns the MST environment for a node, which carries the `pluginManager`.
+ */
+export function getEnv(obj) {
+    return getEnvMST(obj);
+}
+/**
+ * #api core/util
+ * `addOrReplaceView` for view types whose state model may be lazily loaded;
+ * the synchronous `addOrReplaceView` requires it loaded already.
+ */
+export async function launchOrReplaceView(args) {
+    // a test's fake session is not an MST node; addView's own guard is the
+    // error path there
+    if (isStateTreeNode(args.session)) {
+        const { pluginManager } = getEnvMST(args.session);
+        await pluginManager?.getViewType(args.typeName).loadStateModel();
+        // the displays of the tracks a launch opens with are dynamic imports too
+        await pluginManager?.preloadSessionTypes({
+            views: [{ type: args.typeName, ...args.initialState }],
+        });
+    }
+    return addOrReplaceView(args);
+}
+export function hashCode(str) {
+    let hash = 0;
+    if (str.length === 0) {
+        return hash;
+    }
+    for (let i = 0; i < str.length; i++) {
+        const chr = str.charCodeAt(i);
+        hash = (hash << 5) - hash + chr;
+        hash |= 0;
+    }
+    return hash;
+}
+export function objectHash(obj) {
+    return `${hashCode(JSON.stringify(obj))}`;
+}

package/esm/util/nanoid.d.ts

@@ -1,5 +1 @@
-export declare const urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
-export declare const random: (bytes: number) => Uint8Array<ArrayBuffer>;
-export declare const customRandom: (alphabet: string, defaultSize: number, getRandom: (bytes: number) => Uint8Array) => (size?: number) => string;
-export declare const customAlphabet: (alphabet: string, size?: number) => (size?: number) => string;
 export declare const nanoid: (size?: number) => string;

package/esm/util/nanoid.js

@@ -1,29 +1,19 @@
-export const urlAlphabet = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
-export const random = (bytes) => crypto.getRandomValues(new Uint8Array(bytes));
-export const customRandom = (alphabet, defaultSize, getRandom) => {
-    const mask = (2 << (Math.log(alphabet.length - 1) / Math.LN2)) - 1;
-    const step = -~((1.6 * mask * defaultSize) / alphabet.length);
-    return (size = defaultSize) => {
-        let id = '';
-        while (true) {
-            const bytes = getRandom(step);
-            let j = step;
-            while (j--) {
-                id += alphabet[bytes[j] & mask] || '';
-                if (id.length === size) {
-                    return id;
-                }
-            }
-        }
-    };
-};
-export const customAlphabet = (alphabet, size = 21) => customRandom(alphabet, size, random);
+// The web-crypto branch of nanoid (https://github.com/ai/nanoid, MIT), reduced
+// to the one generator we call. The custom-alphabet machinery was carried along
+// unused; restore it from upstream if a non-default alphabet is ever needed.
 export const nanoid = (size = 21) => crypto.getRandomValues(new Uint8Array(size)).reduce((id, byte) => {
+    // It is incorrect to use bytes exceeding the alphabet size.
+    // The following mask reduces the random byte in the 0-255 value
+    // range to the 0-63 value range. Therefore, adding hacks, such
+    // as empty string fallback or magic numbers, is unnecessary because
+    // the bitmask trims bytes down to the alphabet size.
     byte &= 63;
     if (byte < 36) {
+        // `0-9a-z`
         id += byte.toString(36);
     }
     else if (byte < 62) {
+        // `A-Z`
         id += (byte - 26).toString(36).toUpperCase();
     }
     else if (byte > 62) {

package/esm/util/numericUtils.d.ts

@@ -0,0 +1,20 @@
+export declare function clamp(num: number, min: number, max: number): number;
+export declare function minmax(a: number, b: number): readonly [number, number];
+export declare function max(arr: ArrayLike<number>, init?: number): number;
+export declare function maxFinite(arr: ArrayLike<number>, init?: number): number;
+export declare function min(arr: ArrayLike<number>, init?: number): number;
+export declare function sum(arr: ArrayLike<number>): number;
+export declare function avg(arr: ArrayLike<number>): number;
+export declare function setNumberGrouping(enabled: boolean): void;
+export declare function getNumberGrouping(): boolean;
+export declare function toLocale(n: number): string;
+export declare function toPrecision(s: number, n?: number): number;
+export declare function reducePrecision(s: number, n?: number): string;
+/**
+ * A byte count as a person reads it. Shared by the region-too-large banner and
+ * the save-track-data dialog, which quote the same index estimate and would
+ * otherwise word the same number two ways.
+ */
+export declare function getDisplayStr(totalBytes: number): string;
+export declare function radToDeg(radians: number): number;
+export declare function polarToCartesian(rho: number, theta: number): [number, number];

package/esm/util/numericUtils.js

@@ -0,0 +1,127 @@
+export function clamp(num, min, max) {
+    if (num < min) {
+        return min;
+    }
+    if (num > max) {
+        return max;
+    }
+    return num;
+}
+export function minmax(a, b) {
+    return [Math.min(a, b), Math.max(a, b)];
+}
+// Index iteration so these accept both arrays and typed arrays (e.g.
+// Float32Array) without requiring Iterable.
+export function max(arr, init = Number.NEGATIVE_INFINITY) {
+    let max = init;
+    for (let i = 0; i < arr.length; i++) {
+        max = Math.max(arr[i], max);
+    }
+    return max;
+}
+// Like max() but skips NaN/Infinity entries rather than propagating them (a
+// single NaN poisons Math.max). Used where an array can legitimately carry
+// gaps, e.g. a score series with unmeasured bins in it.
+export function maxFinite(arr, init = Number.NEGATIVE_INFINITY) {
+    let max = init;
+    for (let i = 0; i < arr.length; i++) {
+        const v = arr[i];
+        if (Number.isFinite(v) && v > max) {
+            max = v;
+        }
+    }
+    return max;
+}
+export function min(arr, init = Number.POSITIVE_INFINITY) {
+    let min = init;
+    for (let i = 0; i < arr.length; i++) {
+        min = Math.min(arr[i], min);
+    }
+    return min;
+}
+export function sum(arr) {
+    let sum = 0;
+    for (let i = 0; i < arr.length; i++) {
+        sum += arr[i];
+    }
+    return sum;
+}
+export function avg(arr) {
+    return sum(arr) / arr.length;
+}
+// Thousand separators are a display convention, not part of the number. They
+// make a coordinate readable, but they survive a copy-paste into tools that
+// then choke on them, so users who copy coordinates out of the app more than
+// they read them can turn them off (the `numberGrouping` preference).
+//
+// A plain variable rather than an observable, because every number the app
+// displays funnels through here — including strings built worker-side, where a
+// jexl `mouseover` slot formats a tooltip against the full feature. A
+// main-thread-only reactive value would leave those stale, so the app would sit
+// half-formatted until every track refetched. Instead each realm sets this once
+// at startup (the worker gets it in its boot configuration, see RpcManager) and
+// the preference asks for a reload, which buys uniformity for one page load.
+let numberGrouping = true;
+export function setNumberGrouping(enabled) {
+    numberGrouping = enabled;
+}
+// read when handing the setting to another realm; not a display path
+export function getNumberGrouping() {
+    return numberGrouping;
+}
+// Fast number formatter with thousand separators.
+// Benchmarked at 5-67x faster than toLocaleString('en-US')
+export function toLocale(n) {
+    const abs = Math.abs(n);
+    // `!(abs >= 1000)` also covers NaN, which has no digits to group, and
+    // String() switches to exponential form at 1e21 and for Infinity, where a
+    // thousands separator is meaningless
+    if (!numberGrouping || !(abs >= 1000) || abs >= 1e21) {
+        return String(n);
+    }
+    const str = String(abs);
+    // separators count from the decimal point, not the end of the string
+    const intLen = Number.isInteger(abs) ? str.length : str.indexOf('.');
+    let result = n < 0 ? '-' : '';
+    for (let i = 0; i < intLen; i++) {
+        if (i > 0 && (intLen - i) % 3 === 0) {
+            result += ',';
+        }
+        result += str[i];
+    }
+    return intLen === str.length ? result : result + str.slice(intLen);
+}
+// numeric significant-figure rounding; reducePrecision is the formatted form
+export function toPrecision(s, n = 3) {
+    return Number.parseFloat(s.toPrecision(n));
+}
+export function reducePrecision(s, n = 3) {
+    return toLocale(toPrecision(s, n));
+}
+/**
+ * A byte count as a person reads it. Shared by the region-too-large banner and
+ * the save-track-data dialog, which quote the same index estimate and would
+ * otherwise word the same number two ways.
+ */
+export function getDisplayStr(totalBytes) {
+    // pick the unit from the rounded value so e.g. 999,999 bytes reads "1 Mb"
+    // rather than "1000 Kb"
+    const mb = toPrecision(totalBytes / 1_000_000);
+    const kb = toPrecision(totalBytes / 1000);
+    if (mb >= 1) {
+        return `${mb} Mb`;
+    }
+    else if (kb >= 1) {
+        return `${kb} Kb`;
+    }
+    else {
+        return `${Math.floor(totalBytes)} bytes`;
+    }
+}
+const oneEightyOverPi = 180 / Math.PI;
+export function radToDeg(radians) {
+    return (radians * oneEightyOverPi) % 360;
+}
+export function polarToCartesian(rho, theta) {
+    return [rho * Math.cos(theta), rho * Math.sin(theta)];
+}

package/esm/util/objectUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function isObject(x: unknown): x is Record<string | symbol | number, unknown>;
+export declare function isPlainObject(x: unknown): x is Record<string, unknown>;

package/esm/util/objectUtils.js

@@ -0,0 +1,9 @@
+// MIT https://github.com/inspect-js/is-object
+export function isObject(x) {
+    return typeof x === 'object' && x !== null;
+}
+// `isObject` minus arrays: the branch `deepEqual` and `deepMerge` recurse into
+// key by key, as opposed to the one they walk by index.
+export function isPlainObject(x) {
+    return isObject(x) && !Array.isArray(x);
+}

package/esm/util/offscreenCanvasPonyfill.d.ts

@@ -1,5 +1,6 @@
-export { collectTransferables, isDetachedBuffer } from './transferables.ts';
-export declare function isImageBitmap(value: unknown): value is ImageBitmap;
+/**
+ * Paint a worker-produced image onto a 2d context: either a real
+ * ImageBitmap/canvas, or the serialized canvas-sequencer command list a worker
+ * without OffscreenCanvas sends instead.
+ */
 export declare function drawImageOntoCanvasContext(imageData: any, context: CanvasRenderingContext2D): void;
-export declare function createCanvas(width: number, height: number): any;
-export declare function createImageBitmap(canvas: any): Promise<unknown>;