@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/layouts/placeRect.js

@@ -0,0 +1,97 @@
+/**
+ * Minimal row-packing primitive for integer-indexed 1D layouts.
+ *
+ * `rows[y]` is a flat `[s1,e1,s2,e2,...]` sorted ascending by start, where
+ * intervals within a row never overlap. `placeRect` finds the first row
+ * with no collision (or appends a new row), inserts `[start, end+2]`,
+ * and returns the row INDEX (0, 1, 2, ...).
+ *
+ * How this differs from `GranularRectLayout` in this same folder, and
+ * why this exists as a separate primitive:
+ *
+ * - **Keys:** GranularRectLayout keys rectangles by string ID in a
+ *   `Map`, so re-adding an id returns the row it already holds;
+ *   `placeRect` has no ID and no rectangle object. Callers with numeric
+ *   indices (e.g. BAM read indices) don't pay the cost of allocating
+ *   string IDs, Rectangle objects, or the outer Map — they use a
+ *   `Uint16Array` of row indices instead.
+ *
+ * - **Scaling / height:** GranularRectLayout has `pitchX`, `pitchY`,
+ *   multi-row rectangle heights, `maxHeight` / `hardRowLimit`, and
+ *   returns pixel `top` values. `placeRect` is unit-agnostic (bp or
+ *   px), one-row-per-rect, no limits, and returns a row index.
+ *
+ * - **State ownership:** GranularRectLayout is a class with internal
+ *   state; `placeRect` is a pure function operating on a caller-owned
+ *   `number[][]` array, so memory lifetime matches the caller's scope.
+ *
+ * Neither hit-tests: both are packing only, and consumers that need
+ * hit-testing build a Flatbush over the result.
+ *
+ * Use `placeRect` for tight per-call layouts over typed-array data
+ * (alignments pileup and chain rendering). Use `GranularRectLayout`
+ * when rects have variable heights or the layout needs a row limit
+ * (feature/gene tracks).
+ *
+ * Per-row complexity:
+ *   - O(1) append when the row's last end ≤ new start (start-sorted
+ *     input — the common case)
+ *   - O(log M) collision + insertion-point lookup for wide rows via
+ *     binary search on ends. Ends are monotone within a row because
+ *     intervals are non-overlapping and sorted by start.
+ *   - O(M) for the splice shift when inserting mid-row; only taken
+ *     once per placement, and only when the fast-path misses.
+ *
+ * @param rows  mutable `number[][]` — each row is `[s1,e1,s2,e2,...]`
+ * @param start rect start (any numeric unit — bp, px, etc.)
+ * @param end   rect end (exclusive)
+ * @returns     the row index the rect was placed in
+ */
+export function placeRect(rows, start, end) {
+    const paddedEnd = end + 2;
+    let y = rows.length;
+    for (let r = 0; r < rows.length; r++) {
+        const row = rows[r];
+        const len = row.length;
+        // Fast path: entire row ends before new start → O(1) append.
+        if (row[len - 1] <= start) {
+            row.push(start, paddedEnd);
+            y = r;
+            break;
+        }
+        // Find j = first index where interval end > start. Only intervals
+        // at/after j can possibly collide with [start, paddedEnd).
+        let j;
+        if (len < 32) {
+            j = 0;
+            while (row[j + 1] <= start) {
+                j += 2;
+            }
+        }
+        else {
+            let lo = 0;
+            let hi = len >>> 1;
+            while (lo < hi) {
+                const mid = (lo + hi) >>> 1;
+                if (row[(mid << 1) + 1] <= start) {
+                    lo = mid + 1;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            j = lo << 1;
+        }
+        // Only interval j can collide — if its start is past paddedEnd there
+        // is a gap and we insert at j; otherwise we collide and try next row.
+        if (row[j] >= paddedEnd) {
+            row.splice(j, 0, start, paddedEnd);
+            y = r;
+            break;
+        }
+    }
+    if (y === rows.length) {
+        rows.push([start, paddedEnd]);
+    }
+    return y;
+}

package/esm/util/leadingEdgeAutorun.d.ts

@@ -0,0 +1,40 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface LeadingEdgeAutorunOptions {
+    /** autorun name, for the MobX devtools/spy stream */
+    name: string;
+    /** how long to coalesce reruns once the body has started work once */
+    delay: number;
+}
+/**
+ * An autorun that runs on the leading edge until its body reports having
+ * started work, and debounces every run after that.
+ *
+ * MobX's own `autorun(fn, { delay })` is trailing-edge only: it schedules the
+ * *first* run through `setTimeout` too, so a cold open waits the whole delay
+ * for no interaction to coalesce, and that latency lands directly on first
+ * paint. Measured on the per-region fetch autorun, display creation to first
+ * `fetchNeeded`: 683 ms under `{ delay: 600 }`, 112 ms under this.
+ *
+ * **The body returns `true` when it started the work the delay exists to
+ * coalesce**, and that is what arms the debounce. Runs that bail on a guard —
+ * a view not measured yet, a minimized track, a prerequisite that has not
+ * landed — return nothing and stay on the leading edge, so the timer is never
+ * armed by work that did not happen. Priming off the body's return rather than
+ * an imperative `prime()` call is what makes a bail-out path unable to arm it
+ * by accident: there is nothing to forget and nothing to misplace.
+ *
+ * **The leading edge is a microtask, not the install call itself**, and that
+ * one hop is what keeps the debounce's whole point. A model is routinely built
+ * and then configured in the same synchronous block — a session applying a
+ * display setting, a caller flipping a mode right after `create` — and a fetch
+ * issued between those two lines is issued against the un-configured state,
+ * invalidated by the setting that follows, and reissued. Yielding once collapses
+ * every such pair back into one run, while still starting three orders of
+ * magnitude sooner than the timer did. What it deliberately does not coalesce is
+ * a change that arrives after an await: that is a later decision, and it costs
+ * the refetch it should.
+ *
+ * The debounce is per-installation, so two autoruns on one model coalesce
+ * independently.
+ */
+export declare function leadingEdgeAutorun(self: IAnyStateTreeNode, body: () => boolean | void, { name, delay }: LeadingEdgeAutorunOptions): import("mobx").IReactionDisposer;

package/esm/util/leadingEdgeAutorun.js

@@ -0,0 +1,51 @@
+import { namedAutorun } from '@jbrowse/render-core/namedReactions';
+/**
+ * An autorun that runs on the leading edge until its body reports having
+ * started work, and debounces every run after that.
+ *
+ * MobX's own `autorun(fn, { delay })` is trailing-edge only: it schedules the
+ * *first* run through `setTimeout` too, so a cold open waits the whole delay
+ * for no interaction to coalesce, and that latency lands directly on first
+ * paint. Measured on the per-region fetch autorun, display creation to first
+ * `fetchNeeded`: 683 ms under `{ delay: 600 }`, 112 ms under this.
+ *
+ * **The body returns `true` when it started the work the delay exists to
+ * coalesce**, and that is what arms the debounce. Runs that bail on a guard —
+ * a view not measured yet, a minimized track, a prerequisite that has not
+ * landed — return nothing and stay on the leading edge, so the timer is never
+ * armed by work that did not happen. Priming off the body's return rather than
+ * an imperative `prime()` call is what makes a bail-out path unable to arm it
+ * by accident: there is nothing to forget and nothing to misplace.
+ *
+ * **The leading edge is a microtask, not the install call itself**, and that
+ * one hop is what keeps the debounce's whole point. A model is routinely built
+ * and then configured in the same synchronous block — a session applying a
+ * display setting, a caller flipping a mode right after `create` — and a fetch
+ * issued between those two lines is issued against the un-configured state,
+ * invalidated by the setting that follows, and reissued. Yielding once collapses
+ * every such pair back into one run, while still starting three orders of
+ * magnitude sooner than the timer did. What it deliberately does not coalesce is
+ * a change that arrives after an await: that is a later decision, and it costs
+ * the refetch it should.
+ *
+ * The debounce is per-installation, so two autoruns on one model coalesce
+ * independently.
+ */
+export function leadingEdgeAutorun(self, body, { name, delay }) {
+    let primed = false;
+    return namedAutorun(self, () => {
+        if (body()) {
+            primed = true;
+        }
+    }, {
+        name,
+        scheduler: run => {
+            if (primed) {
+                setTimeout(run, delay);
+            }
+            else {
+                queueMicrotask(run);
+            }
+        },
+    });
+}

package/esm/util/librpc.d.ts

@@ -1,2 +1,5 @@
-export { RpcClient, RpcServer, deserializeError, rpcResult, serializeError, } from 'librpc-web-mod';
-export type { RpcResult } from 'librpc-web-mod';
+export { default as RpcClient } from '../rpc/RpcClient.ts';
+export { default as RpcServer, rpcResult, rpcResultWithArrayBuffers, } from '../rpc/RpcServer.ts';
+export type { RpcResult } from '../rpc/RpcServer.ts';
+export { isRpcResult, unwrapRpcResult } from './rpc.ts';
+export { deserializeError, serializeError, } from '../rpc/serializeError/index.ts';

package/esm/util/librpc.js

@@ -1 +1,6 @@
-export { RpcClient, RpcServer, deserializeError, rpcResult, serializeError, } from 'librpc-web-mod';
+export { default as RpcClient } from '../rpc/RpcClient.js';
+export { default as RpcServer, rpcResult, rpcResultWithArrayBuffers, } from '../rpc/RpcServer.js';
+// the inverse of rpcResult, for a deserializeReturn rebuilding the caller's
+// value out of what the worker sent
+export { isRpcResult, unwrapRpcResult } from './rpc.js';
+export { deserializeError, serializeError, } from '../rpc/serializeError/index.js';

package/esm/util/linkify.js

@@ -1,3 +1,5 @@
+// based on autolink-js, license MIT
+// https://github.com/bryanwoods/autolink-js/blob/1418049970152c56ced73d43dcc62d80b320fb71/autolink.js#L9
 const URL_PATTERN = /(^|[\s\n]|<[A-Za-z]*\/?>)((?:https?|ftp):\/\/[-A-Z0-9+\u0026\u2019@#/%?=()~_|!:,.;]*[-A-Z0-9+\u0026@#/%=~()_|])/gi;
 export function linkify(s) {
     URL_PATTERN.lastIndex = 0;

package/esm/util/locString.d.ts

@@ -5,5 +5,77 @@ export interface ParsedLocString {
     end?: number;
     reversed?: boolean;
 }
+export declare class UnknownRefNameError extends Error {
+    name: string;
+}
 export declare function parseLocStringOneBased(locString: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): ParsedLocString;
 export declare function parseLocString(locString: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): ParsedLocString;
+/**
+ * Assemble a 1-based "locString" from an interbase genomic location
+ * @param region - Region
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ assemblyName: 'hg19', refName: 'chr1', start: 0, end: 100 })
+ * // ↳ '{hg19}chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1' })
+ * // ↳ 'chr1'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0 })
+ * // ↳ 'chr1:1..'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 1 })
+ * // ↳ 'chr1:1'
+ * ```
+ */
+export declare function assembleLocString(region: ParsedLocString): string;
+/**
+ * Same as {@link assembleLocString}, but with the coordinates left unformatted:
+ * no thousand separators, and never affected by the `numberGrouping` display
+ * preference. Use this wherever the result is compared, keyed on, or parsed
+ * rather than read — block keys, dedup buckets, locStrings handed back to
+ * `parseLocString` — both because it is faster (block calculations assemble a
+ * great many of these) and because a display convention shifting under an
+ * identity string is a correctness bug, not a cosmetic one.
+ */
+export declare function assembleLocStringRaw(region: ParsedLocString): string;
+/**
+ * One space-separated string for a set of regions — what the header of a
+ * multi-region view says it is showing, and what an export of those regions
+ * labels itself with.
+ *
+ * The assembly name appears only when the regions disagree about it: naming it
+ * on every one of a dozen same-assembly blocks is noise, and dropping it where
+ * they differ loses the only thing telling them apart.
+ */
+export declare function assembleLocStrings(regions: ParsedLocString[]): string;
+export declare function compareLocs(locA: ParsedLocString, locB: ParsedLocString): number;
+export declare function compareLocStrings(a: string, b: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): number;
+/**
+ * A cursor/coordinate readout: `{assembly}chr1:1,234`, with the refName
+ * shortened and the coordinate locale-grouped. The *display* counterpart to
+ * {@link assembleLocString} — this one is for showing a single position to a
+ * user, never for a location string that will be parsed back.
+ */
+export declare function stringify({ refName, coord, assemblyName, oob, }: {
+    assemblyName?: string;
+    coord: number;
+    refName?: string;
+    oob?: boolean;
+}, useAssemblyName?: boolean): string;

package/esm/util/locString.js

@@ -1,57 +1,89 @@
-const COORD_REGEX = /^(-?\d+)(?:(?:\.\.|[-–])(-?\d+))?(\.\.|[-–])?$/;
+import { BP_QUANTITY_SOURCE, parseBpString } from './bpUtils.js';
+import { toLocale } from './numericUtils.js';
+import { shorten } from './stringUtils.js';
+// Thrown when the input doesn't resolve to any known refName. Callers
+// (e.g. the LGV locstring path) catch this to fall back to alternative
+// interpretations like "refname start end" triplets — string-matching
+// the error message would be brittle.
+export class UnknownRefNameError extends Error {
+    name = 'UnknownRefNameError';
+}
+// matches coordinate strings: "100", "100-200", "100..200", "100.." (open-ended).
+// Each coordinate may carry a metric unit suffix, so "34M-35M" and "1.5kb..2kb"
+// parse too; the numbers are converted eagerly here and nothing downstream ever
+// sees the shorthand. Assembled locStrings are always plain digits, so this is
+// a spelling the parser accepts and the formatter never emits.
+// groups: [1]=start [2]=end (if range) [3]=trailing separator (if open-ended)
+const COORD_REGEX = new RegExp(String.raw `^(${BP_QUANTITY_SOURCE})(?:(?:\.\.|[-–])(${BP_QUANTITY_SOURCE}))?(\.\.|[-–])?$`, 'i');
+// matches optional "{assemblyName}" prefix followed by the rest of the location
+// groups: [1]=assemblyName (without braces) [2]=remainder
 const ASSEMBLY_REGEX = /^(?:\{([^}]+)\})?(.+)/;
 function parseCoords(suffix, locString) {
+    // strip commas before matching so regex only needs to handle plain digits
     const match = COORD_REGEX.exec(suffix.replaceAll(',', ''));
-    if (!match) {
+    const [, startStr, endStr, trailing] = match ?? [];
+    const start = startStr === undefined ? undefined : parseBpString(startStr);
+    if (start === undefined) {
         throw new Error(`could not parse range "${suffix}" on location "${locString}"`);
     }
-    const [, startStr, endStr, trailing] = match;
-    const start = +startStr;
-    return { start, end: endStr ? +endStr : trailing ? undefined : start };
+    return {
+        start,
+        end: endStr ? parseBpString(endStr) : trailing ? undefined : start,
+    };
 }
 export function parseLocStringOneBased(locString, isValidRefName) {
     if (!locString) {
         throw new Error('no location string provided, could not parse');
     }
+    // handle reverse strand notation e.g. "chr1:1-100[rev]"
     let reversed = false;
     if (locString.endsWith('[rev]')) {
         reversed = true;
         locString = locString.slice(0, -5);
     }
     locString = locString.replaceAll(/\s/g, '');
+    // extract optional assembly name in braces e.g. "{hg19}chr1:1-100"
     const assemblyMatch = ASSEMBLY_REGEX.exec(locString);
     if (!assemblyMatch) {
         throw new Error(`invalid location string: "${locString}"`);
     }
     const [, assemblyName, location] = assemblyMatch;
+    // reject empty braces e.g. "{}chr1:1-100"
     if (!assemblyName && location.startsWith('{}')) {
         throw new Error(`no assembly name was provided in location "${location}"`);
     }
+    // refNames can contain colons (see SAM spec), so find the last colon to split
     const lastColonIdx = location.lastIndexOf(':');
+    // no colon means just a refName with no coordinates e.g. "chr1"
     if (lastColonIdx === -1) {
         if (isValidRefName(location, assemblyName)) {
             return { assemblyName, refName: location, reversed };
         }
-        throw new Error(`Unknown feature or sequence "${location}"`);
+        throw new UnknownRefNameError(`Unknown feature or sequence "${location}"`);
     }
+    // split into refName (prefix) and coordinate part (suffix) at the last colon
     const prefix = location.slice(0, lastColonIdx);
     const suffix = location.slice(lastColonIdx + 1);
     const prefixValid = isValidRefName(prefix, assemblyName);
     const locationValid = isValidRefName(location, assemblyName);
+    // both interpretations valid is ambiguous e.g. refName "chr1:1" and "chr1" both exist
     if (prefixValid && locationValid) {
         throw new Error(`ambiguous location string: "${locString}"`);
     }
+    // the colon is part of the refName, not a coordinate separator
     if (locationValid) {
         return { assemblyName, refName: location, reversed };
     }
+    // standard case: prefix is refName, suffix is coordinates
     if (prefixValid) {
+        // colon with no suffix means just refName e.g. "chr1:"
         if (!suffix) {
             return { assemblyName, refName: prefix, reversed };
         }
         const coords = parseCoords(suffix, locString);
         return { assemblyName, refName: prefix, reversed, ...coords };
     }
-    throw new Error(`unknown reference sequence name in location "${locString}"`);
+    throw new UnknownRefNameError(`unknown reference sequence name in location "${locString}"`);
 }
 export function parseLocString(locString, isValidRefName) {
     const parsed = parseLocStringOneBased(locString, isValidRefName);
@@ -60,3 +92,142 @@ export function parseLocString(locString, isValidRefName) {
     }
     return parsed;
 }
+/**
+ * Assemble a 1-based "locString" from an interbase genomic location
+ * @param region - Region
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ assemblyName: 'hg19', refName: 'chr1', start: 0, end: 100 })
+ * // ↳ '{hg19}chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1' })
+ * // ↳ 'chr1'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0 })
+ * // ↳ 'chr1:1..'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 1 })
+ * // ↳ 'chr1:1'
+ * ```
+ */
+export function assembleLocString(region) {
+    return assembleLocStringWith(region, toLocale);
+}
+/**
+ * Same as {@link assembleLocString}, but with the coordinates left unformatted:
+ * no thousand separators, and never affected by the `numberGrouping` display
+ * preference. Use this wherever the result is compared, keyed on, or parsed
+ * rather than read — block keys, dedup buckets, locStrings handed back to
+ * `parseLocString` — both because it is faster (block calculations assemble a
+ * great many of these) and because a display convention shifting under an
+ * identity string is a correctness bug, not a cosmetic one.
+ */
+export function assembleLocStringRaw(region) {
+    return assembleLocStringWith(region);
+}
+/**
+ * One space-separated string for a set of regions — what the header of a
+ * multi-region view says it is showing, and what an export of those regions
+ * labels itself with.
+ *
+ * The assembly name appears only when the regions disagree about it: naming it
+ * on every one of a dozen same-assembly blocks is noise, and dropping it where
+ * they differ loses the only thing telling them apart.
+ */
+export function assembleLocStrings(regions) {
+    const sameAssembly = regions.every(r => r.assemblyName === regions[0].assemblyName);
+    return regions
+        .map(r => assembleLocString({
+        ...r,
+        assemblyName: sameAssembly ? undefined : r.assemblyName,
+    }))
+        .join(' ');
+}
+function assembleLocStringWith(region, cb = (n) => n) {
+    const { assemblyName, refName, start, end, reversed } = region;
+    const assemblyNameString = assemblyName ? `{${assemblyName}}` : '';
+    let startString;
+    if (start !== undefined) {
+        startString = `:${cb(start + 1)}`;
+    }
+    else if (end !== undefined) {
+        startString = ':1';
+    }
+    else {
+        startString = '';
+    }
+    let endString;
+    if (end !== undefined) {
+        endString = start !== undefined && start + 1 === end ? '' : `..${cb(end)}`;
+    }
+    else {
+        endString = start !== undefined ? '..' : '';
+    }
+    let rev = '';
+    if (reversed) {
+        rev = '[rev]';
+    }
+    return `${assemblyNameString}${refName}${startString}${endString}${rev}`;
+}
+export function compareLocs(locA, locB) {
+    const assemblyComp = locA.assemblyName || locB.assemblyName
+        ? (locA.assemblyName || '').localeCompare(locB.assemblyName || '')
+        : 0;
+    if (assemblyComp) {
+        return assemblyComp;
+    }
+    const refComp = locA.refName || locB.refName
+        ? (locA.refName || '').localeCompare(locB.refName || '')
+        : 0;
+    if (refComp) {
+        return refComp;
+    }
+    if (locA.start !== undefined && locB.start !== undefined) {
+        const startComp = locA.start - locB.start;
+        if (startComp) {
+            return startComp;
+        }
+    }
+    if (locA.end !== undefined && locB.end !== undefined) {
+        const endComp = locA.end - locB.end;
+        if (endComp) {
+            return endComp;
+        }
+    }
+    return 0;
+}
+export function compareLocStrings(a, b, isValidRefName) {
+    const locA = parseLocString(a, isValidRefName);
+    const locB = parseLocString(b, isValidRefName);
+    return compareLocs(locA, locB);
+}
+/**
+ * A cursor/coordinate readout: `{assembly}chr1:1,234`, with the refName
+ * shortened and the coordinate locale-grouped. The *display* counterpart to
+ * {@link assembleLocString} — this one is for showing a single position to a
+ * user, never for a location string that will be parsed back.
+ */
+export function stringify({ refName, coord, assemblyName, oob, }, useAssemblyName) {
+    return [
+        assemblyName && useAssemblyName ? `{${assemblyName}}` : '',
+        refName
+            ? `${shorten(refName)}:${toLocale(coord)}${oob ? ' (out of bounds)' : ''}`
+            : '',
+    ].join('');
+}

package/esm/util/locStringsToRegions.d.ts

@@ -0,0 +1,10 @@
+import type { Region } from './types/data.ts';
+export interface RefNameSource {
+    isValidRefName: (refName: string) => boolean;
+    getCanonicalRefName2: (refName: string) => string;
+    regions?: readonly {
+        refName: string;
+        end: number;
+    }[];
+}
+export declare function locStringsToRegions(locStrings: string, assembly: RefNameSource, assemblyName: string): Region[];

package/esm/util/locStringsToRegions.js

@@ -0,0 +1,35 @@
+import { parseLocString } from './locString.js';
+// Parses locstrings a user wrote -- into a dialog's region field, or into a
+// display's `clusterRegion` in a session -- to the regions a fetch runs over.
+// Throws on an unparsable ref name or an empty range, so a caller surfaces the
+// typo rather than quietly running over something else. Whitespace separates
+// regions, so a multi-region rubberband selection round-trips through a field,
+// and a setting can name more than one locus.
+//
+// A bare refName means the whole contig, so its length is required, not a
+// fallback: defaulting a missing length to 0 turned "this contig has no length
+// on record" into "empty region", which reads as the user having typed a bad
+// range.
+export function locStringsToRegions(locStrings, assembly, assemblyName) {
+    return locStrings
+        .trim()
+        .split(/\s+/)
+        .map(locString => {
+        const parsed = parseLocString(locString, refName => assembly.isValidRefName(refName));
+        const refName = assembly.getCanonicalRefName2(parsed.refName);
+        // scans rather than calling the assembly's getRegionForRefName, because
+        // `RefNameSource` is a narrow duck type several fakes satisfy — growing it
+        // a method to save a scan over a list this reads once per typed locstring
+        // is the wrong trade
+        const refLength = assembly.regions?.find(r => r.refName === refName)?.end;
+        if (refLength === undefined) {
+            throw new Error(`no length on record for "${refName}"`);
+        }
+        const start = Math.max(parsed.start ?? 0, 0);
+        const end = Math.min(parsed.end ?? refLength, refLength);
+        if (end <= start) {
+            throw new Error(`empty region: "${locString}"`);
+        }
+        return { assemblyName, refName, start, end };
+    });
+}

package/esm/util/localStorage.d.ts

@@ -0,0 +1,36 @@
+export declare const localStorageAvailable: () => boolean, localStorageGetItem: (key: string) => string | undefined, localStorageSetItem: (key: string, value: string) => boolean, localStorageRemoveItem: (key: string) => boolean;
+/**
+ * Call `fn` whenever `key` changes — in another tab, or here via
+ * {@link notifyLocalStorageKey}. Returns the unsubscribe.
+ *
+ * `fn` takes no argument on purpose: it is told that the key changed, and reads
+ * the store itself. A payload would be a second copy of the value, and a
+ * `clear()` has none to hand over.
+ */
+export declare function subscribeToLocalStorageKey(key: string, fn: () => void): () => void;
+/** Announce a write made in this tab, which `storage` never reports back. */
+export declare function notifyLocalStorageKey(key: string): void;
+export declare function localStorageGetNumber(key: string, defaultVal: number): number;
+export declare function localStorageGetJSON<T>(key: string, defaultVal: T): T;
+/**
+ * The list of strings at `key` — absent, unreadable, malformed, or holding
+ * anything else all read as empty.
+ *
+ * The element filter is the part {@link localStorageGetJSON} cannot do: a
+ * stored array of the wrong element type parses fine and then behaves as a list
+ * of values that match nothing, which looks the same as an empty list except
+ * that it is never noticed. Three keys wanted exactly this and each spelled it
+ * out — hidden facet columns, trusted plugin URLs, and the desktop safe-mode
+ * marker, which additionally has to survive the bare `1` older builds wrote
+ * there.
+ */
+export declare function localStorageGetStringArray(key: string): string[];
+/**
+ * Writes `val` as JSON, except when it is null/undefined — those are skipped
+ * rather than stored, so a tri-state setting whose "unset" value means "follow
+ * the config" leaves whatever was there instead of pinning `null` over it.
+ */
+export declare function localStorageSetJSON(key: string, val: unknown): void;
+export declare function localStorageGetBoolean(key: string, defaultVal: boolean): boolean;
+export declare function localStorageSetBoolean(key: string, value: boolean): void;
+export declare function localStorageSetNumber(key: string, value: number): void;