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

package/esm/util/installInitAutorun.d.ts

@@ -1,13 +1,13 @@
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 interface InitAutorunHost<T> extends IStateTreeNode {
-    init?: T;
-    setInit: (init?: T) => void;
+    pendingLaunch?: T;
+    setLaunch: (launch?: T) => void;
     setError: (error: unknown) => void;
 }
 export interface InitApplyContext {
     /**
      * True once this init can no longer be the one being applied: the node is
-     * gone, or a newer `setInit` has replaced it. Any mid-apply wait that can
+     * gone, or a newer `setLaunch` has replaced it. Any mid-apply wait that can
      * park indefinitely must fold this into its condition — an unbounded wait on
      * state that never arrives holds the drain open, and the newer init that
      * would have superseded it is exactly what gets stranded. This is the causal
@@ -26,35 +26,36 @@ interface InitAutorunOptions<T> {
      */
     ready: () => boolean;
     /**
-     * Whether the view has materialized — the same line each view's
-     * postProcessSnapshot draws for persistence (dotplot: assemblyNames set;
-     * synteny: rows built). Decides the failure policy, see below.
+     * Whether the view has materialized — the line `withLaunchInput`'s
+     * `materialized` draws for persistence, read from the live node (dotplot:
+     * assemblyNames set; synteny: rows built). Decides the failure policy, see
+     * below.
      */
     materialized: () => boolean;
     /** Apply one init blob. Owns the ordered steps; never clears `init`. */
     apply: (init: T, ctx: InitApplyContext) => Promise<void>;
 }
 /**
- * The init state machine shared by the views that take a declarative `init`
+ * The launch state machine shared by the views that take a declarative launch
  * blob (LinearGenomeView, DotplotView, LinearSyntenyView): the re-entry guard,
  * the readiness gate, the serialized drain, the identity-checked clear, the
  * isAlive guards, and one failure policy.
  *
- * The failure policy keys off `materialized`, the same line each view's
- * postProcessSnapshot already draws for persistence:
+ * The failure policy keys off `materialized`, the same line `withLaunchInput`
+ * draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - Not materialized — nothing is on screen and `launch` is still persisted, so
  *   keep it for a reload retry and `setError`. That flips the view onto its
  *   import form, which renders the error in its own banner; a snackbar would
  *   state the same failure twice and the banner is the one that persists.
  * - Materialized — the view works, so a later failure is one sub-step's
  *   problem and must not take the view down with it. `setError` would, since
  *   showImportForm keys off `error` alone and would discard rows that loaded
- *   fine, so report it as a snackbar instead. Clearing `init` is also what
+ *   fine, so report it as a snackbar instead. Clearing `launch` is also what
  *   disarms the re-fire: `ready` usually folds in the measured width, so
- *   leaving it set lets any resize re-run `apply` over a half-applied init.
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
  *
- * `apply` therefore never clears `init` and never catches for reporting — it
+ * `apply` therefore never clears `launch` and never catches for reporting — it
  * catches only the failures it wants to keep going through (a bad locstring in
  * one row), and everything it lets escape is fatal-as-of-that-point.
  */

package/esm/util/installInitAutorun.js

@@ -1,19 +1,19 @@
 import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
 import { getNotificationSink } from './sessionServices.js';
-// Clear only when `init` is still the exact object we applied. A setInit that
-// lands while `apply` is awaiting (React StrictMode remounts, a programmatic
-// re-launch) swaps in a new object; clearing unconditionally would silently
-// drop that pending init. Leaving it lets the drain loop apply it next.
+// Clear only when the pending blob is still the exact object we applied. A
+// setLaunch that lands while `apply` is awaiting (React StrictMode remounts, a
+// programmatic re-launch) swaps in a new object; clearing unconditionally would
+// silently drop it. Leaving it lets the drain loop apply it next.
 function clearIfUnchanged(self, init) {
-    if (isAlive(self) && self.init === init) {
-        self.setInit(undefined);
+    if (isAlive(self) && self.pendingLaunch === init) {
+        self.setLaunch(undefined);
     }
 }
 async function applyInitOnce(self, init, { apply, materialized }) {
     try {
         await apply(init, {
-            superseded: () => !isAlive(self) || self.init !== init,
+            superseded: () => !isAlive(self) || self.pendingLaunch !== init,
         });
         clearIfUnchanged(self, init);
     }
@@ -34,7 +34,7 @@ async function applyInitOnce(self, init, { apply, materialized }) {
     }
 }
 function currentInit(self, { ready }) {
-    return isAlive(self) && ready() ? self.init : undefined;
+    return isAlive(self) && ready() ? self.pendingLaunch : undefined;
 }
 // Apply pending inits one at a time until none remain. Serializing (rather
 // than letting the autorun run `apply` concurrently) is what keeps re-entrant
@@ -47,32 +47,32 @@ async function drainInit(self, opts) {
     while (pending !== undefined) {
         await applyInitOnce(self, pending, opts);
         const next = currentInit(self, opts);
-        // a fatal failure keeps `init` for a reload retry; the same object still
+        // a fatal failure keeps `launch` for a reload retry; the same object still
         // sitting there means it was not consumed, so stop rather than spin on it
         pending = next === pending ? undefined : next;
     }
 }
 /**
- * The init state machine shared by the views that take a declarative `init`
+ * The launch state machine shared by the views that take a declarative launch
  * blob (LinearGenomeView, DotplotView, LinearSyntenyView): the re-entry guard,
  * the readiness gate, the serialized drain, the identity-checked clear, the
  * isAlive guards, and one failure policy.
  *
- * The failure policy keys off `materialized`, the same line each view's
- * postProcessSnapshot already draws for persistence:
+ * The failure policy keys off `materialized`, the same line `withLaunchInput`
+ * draws for persistence:
  *
- * - Not materialized — nothing is on screen and `init` is still persisted, so
+ * - Not materialized — nothing is on screen and `launch` is still persisted, so
  *   keep it for a reload retry and `setError`. That flips the view onto its
  *   import form, which renders the error in its own banner; a snackbar would
  *   state the same failure twice and the banner is the one that persists.
  * - Materialized — the view works, so a later failure is one sub-step's
  *   problem and must not take the view down with it. `setError` would, since
  *   showImportForm keys off `error` alone and would discard rows that loaded
- *   fine, so report it as a snackbar instead. Clearing `init` is also what
+ *   fine, so report it as a snackbar instead. Clearing `launch` is also what
  *   disarms the re-fire: `ready` usually folds in the measured width, so
- *   leaving it set lets any resize re-run `apply` over a half-applied init.
+ *   leaving it set lets any resize re-run `apply` over a half-applied blob.
  *
- * `apply` therefore never clears `init` and never catches for reporting — it
+ * `apply` therefore never clears `launch` and never catches for reporting — it
  * catches only the failures it wants to keep going through (a bad locstring in
  * one row), and everything it lets escape is fatal-as-of-that-point.
  */
@@ -93,7 +93,7 @@ export function installInitAutorun(self, opts) {
         // reading a detached node throws — here into an unawaited promise.
         const alive = isAlive(self);
         const isReady = alive && opts.ready();
-        const init = alive ? self.init : undefined;
+        const init = alive ? self.pendingLaunch : undefined;
         if (isReady && init !== undefined && !draining) {
             draining = true;
             try {

package/esm/util/installPrerequisiteFetch.d.ts

@@ -0,0 +1,115 @@
+import type { StatusReporter } from './createAbortRotation.ts';
+import type { FetchContext } from './fetchContext.ts';
+import type { FetchSkeletonHost } from './installFetch.ts';
+/**
+ * What a prerequisite read needs of the display it runs on, beside the
+ * skeleton's own three. Duck-typed rather than a foundation's `Instance` type,
+ * because the hosts compose different foundations — one per fetch family, and
+ * the comparative displays compose none of them — and this is the only thing
+ * they have in common.
+ */
+export interface PrerequisiteFetchHost extends FetchSkeletonHost {
+    /**
+     * Read in `prepare`, so it is **tracked**: an adapter edited in the config
+     * editor has to re-read, and `run`'s own reads are untracked by contract.
+     */
+    adapterConfig: Record<string, unknown>;
+    isMinimized: boolean;
+}
+/**
+ * A prerequisite read's answer, stamped with the adapter config it answers.
+ * A display holds the latest one and reads it through `readFor`, so an answer
+ * never outlives its adapter config and no failure path has to clear it.
+ */
+export interface AdapterRead<T> {
+    adapterConfig: Record<string, unknown>;
+    value: T;
+}
+/**
+ * `read`'s value while it answers the adapter config `host` holds; undefined
+ * until a read of that config commits, which a failed read never does.
+ *
+ * Equal by value, as the fetch key is: an undo rebuilds the track's config,
+ * handing back an equal adapter config the fetch declines to read again.
+ */
+export declare function readFor<T>(host: {
+    adapterConfig: Record<string, unknown>;
+}, read: AdapterRead<T> | undefined): T | undefined;
+/**
+ * A **prerequisite read**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Four in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for;
+ * and the mark display's source list, which gives each listed source a row —
+ * and they sit on three different fetch foundations, which is why this sits in
+ * core beside the skeleton and not beside any of them.
+ *
+ * They had the shape below hand-copied, comment for comment, and each term is a
+ * rule rather than a preference:
+ *
+ * - **the adapter config is the whole trigger and the whole key.** Tracked in
+ *   `prepare` so a config-editor edit re-reads; keyed on the same value so an
+ *   un-minimize over the same file re-reads nothing. Getting one without the
+ *   other gives either a stale header or a walk of a `.hic` norm-vector index on
+ *   every expand.
+ * - **the answer carries the same key** (`AdapterRead`), and a display reads
+ *   it through `readFor`, so an answer to a previous adapter config is never
+ *   read as the current one, and a failed read leaves nothing to clear.
+ * - **an answer to a config the display no longer holds is dropped**, and so is
+ *   its error. An undo that brings back the config already answered makes the
+ *   skeleton decline a re-read, while the read of the abandoned config runs
+ *   on, still current; landing, it would stamp its key, force a second read of
+ *   the held one and hand the display a list for another file, on which the
+ *   variant display resets its arrangement.
+ * - **minimized is the gate**, and a display with a second condition of its own
+ *   passes `gate` — the sample-list read waits for the LGV to be measured as
+ *   well, so a full-file scan does not start ahead of the display's own first
+ *   fetch, and the tier read waits on the track declaring a tier threshold at
+ *   all.
+ * - **no `contract`.** This is the second fetch on a display whose foundation
+ *   installed both checks already: `assertDisplayContract` would report the
+ *   double-attach it exists to catch, and a second retry check would consume the
+ *   same `reloadCounter` bumps as the first.
+ * - **where the status goes is the caller's** (`report`). The two LGV reads
+ *   lend the display's own status window, so the read takes a slot beside the
+ *   primary fetch rather than opening a second writer over the one status field
+ *   (ADR-081) — and it matters more here than for most fetches: a prerequisite
+ *   runs inside the pre-first-paint window, where the scrim is up because
+ *   nothing is drawn rather than because `isLoading` is, so `statusMessage` is
+ *   the only thing that can say what is happening. The tier read narrates
+ *   nothing; a header is not a load.
+ *
+ * `createAdapterMetadataFetch` keys on the same adapter config and is
+ * deliberately NOT one of these: no trigger, no signal and no status,
+ * because it is fetched lazily when a details widget opens and the widget opens
+ * on the result. A prerequisite read is the one a display's own fetch waits on.
+ *
+ * **A declaration, not the skeleton this name used to be.** There was an
+ * `installPrerequisiteFetch` until 2026-08-23, and `3c5aa7fce2` deleted it for
+ * a good reason: it carried a `runOne` of its own — a fifth copy of begin →
+ * clear → run → commit-if-current → `handleFetchError` → end — and once
+ * `installFetch` owned that sequence, a second one was pure drift surface. This
+ * one adds no sequence, no rotation and no error rule; it is terms handed to
+ * `installFetch`, the same shape `installGlobalFetchAutorun` and
+ * `installComparativeFetchAutorun` are. Add nothing here that a family could
+ * not state as an option to the skeleton.
+ *
+ * Everything the skeleton gives it is the point of going through the skeleton:
+ * the latest-wins rotation (so a superseding read aborts the one it replaced,
+ * and only a superseding read does — a user cancel of the primary fetch cannot
+ * strand the display the way sharing its signal would), the clear at the start,
+ * the currency-guarded error rule, the unconditional `reloadCounter` read that
+ * makes the chrome's Retry re-run this, and the retired status slot that keeps a
+ * failed read from leaving a progress chip up for good.
+ */
+export declare function installPrerequisiteFetch<TResult>(self: PrerequisiteFetchHost, { name, delay, report, gate, run, commit, setError, }: {
+    name: string;
+    delay: number;
+    report: StatusReporter;
+    /** an extra term of the display's own, ANDed under `!isMinimized` */
+    gate?: () => boolean;
+    run: (adapterConfig: Record<string, unknown>, ctx: FetchContext) => Promise<TResult | undefined>;
+    commit: (read: AdapterRead<TResult>) => void;
+    setError: (error?: unknown) => void;
+}): void;

package/esm/util/installPrerequisiteFetch.js

@@ -0,0 +1,111 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { installFetch } from './installFetch.js';
+import { isDataCurrent } from './isDataCurrent.js';
+/**
+ * `read`'s value while it answers the adapter config `host` holds; undefined
+ * until a read of that config commits, which a failed read never does.
+ *
+ * Equal by value, as the fetch key is: an undo rebuilds the track's config,
+ * handing back an equal adapter config the fetch declines to read again.
+ */
+export function readFor(host, read) {
+    return read !== undefined &&
+        isDataCurrent(read.adapterConfig, host.adapterConfig)
+        ? read.value
+        : undefined;
+}
+/**
+ * A **prerequisite read**: one RPC about the adapter itself, beside the
+ * display's primary fetch. Four in the tree — HiC's `CoreGetInfo` header read,
+ * whose `resolutions` every contacts fetch waits on; the multi-sample sample
+ * list, which `fetchNeeded` declines until; the tiered alignment file's
+ * `CoreGetInfo` header, which decides the LOD tier a synteny fetch asks for;
+ * and the mark display's source list, which gives each listed source a row —
+ * and they sit on three different fetch foundations, which is why this sits in
+ * core beside the skeleton and not beside any of them.
+ *
+ * They had the shape below hand-copied, comment for comment, and each term is a
+ * rule rather than a preference:
+ *
+ * - **the adapter config is the whole trigger and the whole key.** Tracked in
+ *   `prepare` so a config-editor edit re-reads; keyed on the same value so an
+ *   un-minimize over the same file re-reads nothing. Getting one without the
+ *   other gives either a stale header or a walk of a `.hic` norm-vector index on
+ *   every expand.
+ * - **the answer carries the same key** (`AdapterRead`), and a display reads
+ *   it through `readFor`, so an answer to a previous adapter config is never
+ *   read as the current one, and a failed read leaves nothing to clear.
+ * - **an answer to a config the display no longer holds is dropped**, and so is
+ *   its error. An undo that brings back the config already answered makes the
+ *   skeleton decline a re-read, while the read of the abandoned config runs
+ *   on, still current; landing, it would stamp its key, force a second read of
+ *   the held one and hand the display a list for another file, on which the
+ *   variant display resets its arrangement.
+ * - **minimized is the gate**, and a display with a second condition of its own
+ *   passes `gate` — the sample-list read waits for the LGV to be measured as
+ *   well, so a full-file scan does not start ahead of the display's own first
+ *   fetch, and the tier read waits on the track declaring a tier threshold at
+ *   all.
+ * - **no `contract`.** This is the second fetch on a display whose foundation
+ *   installed both checks already: `assertDisplayContract` would report the
+ *   double-attach it exists to catch, and a second retry check would consume the
+ *   same `reloadCounter` bumps as the first.
+ * - **where the status goes is the caller's** (`report`). The two LGV reads
+ *   lend the display's own status window, so the read takes a slot beside the
+ *   primary fetch rather than opening a second writer over the one status field
+ *   (ADR-081) — and it matters more here than for most fetches: a prerequisite
+ *   runs inside the pre-first-paint window, where the scrim is up because
+ *   nothing is drawn rather than because `isLoading` is, so `statusMessage` is
+ *   the only thing that can say what is happening. The tier read narrates
+ *   nothing; a header is not a load.
+ *
+ * `createAdapterMetadataFetch` keys on the same adapter config and is
+ * deliberately NOT one of these: no trigger, no signal and no status,
+ * because it is fetched lazily when a details widget opens and the widget opens
+ * on the result. A prerequisite read is the one a display's own fetch waits on.
+ *
+ * **A declaration, not the skeleton this name used to be.** There was an
+ * `installPrerequisiteFetch` until 2026-08-23, and `3c5aa7fce2` deleted it for
+ * a good reason: it carried a `runOne` of its own — a fifth copy of begin →
+ * clear → run → commit-if-current → `handleFetchError` → end — and once
+ * `installFetch` owned that sequence, a second one was pure drift surface. This
+ * one adds no sequence, no rotation and no error rule; it is terms handed to
+ * `installFetch`, the same shape `installGlobalFetchAutorun` and
+ * `installComparativeFetchAutorun` are. Add nothing here that a family could
+ * not state as an option to the skeleton.
+ *
+ * Everything the skeleton gives it is the point of going through the skeleton:
+ * the latest-wins rotation (so a superseding read aborts the one it replaced,
+ * and only a superseding read does — a user cancel of the primary fetch cannot
+ * strand the display the way sharing its signal would), the clear at the start,
+ * the currency-guarded error rule, the unconditional `reloadCounter` read that
+ * makes the chrome's Retry re-run this, and the retired status slot that keeps a
+ * failed read from leaving a progress chip up for good.
+ */
+export function installPrerequisiteFetch(self, { name, delay, report, gate = () => true, run, commit, setError, }) {
+    installFetch(self, {
+        name,
+        delay,
+        report,
+        gate: () => !self.isMinimized && gate(),
+        prepare: () => ({ adapterConfig: self.adapterConfig }),
+        fetchKey: ({ adapterConfig }) => adapterConfig,
+        run: async ({ adapterConfig }, ctx) => {
+            const held = () => isAlive(self) && isDataCurrent(adapterConfig, self.adapterConfig);
+            try {
+                const value = await run(adapterConfig, ctx);
+                return held() ? value : undefined;
+            }
+            catch (e) {
+                if (held()) {
+                    throw e;
+                }
+                return undefined;
+            }
+        },
+        commit: (value, { adapterConfig }) => {
+            commit({ adapterConfig, value });
+        },
+        setError,
+    });
+}

package/esm/util/intervals.js

@@ -28,10 +28,15 @@ export function mergeIntervals(intervals, padding = 5000) {
  * features. `padding` carries the same per-side meaning.
  */
 export function gatherOverlaps(regions, padding = 5000) {
-    const memo = {};
+    const memo = new Map();
     for (const x of regions) {
-        memo[x.refName] ??= [];
-        memo[x.refName].push(x);
+        const group = memo.get(x.refName);
+        if (group) {
+            group.push(x);
+        }
+        else {
+            memo.set(x.refName, [x]);
+        }
     }
-    return Object.values(memo).flatMap(group => mergeIntervals(group, padding));
+    return [...memo.values()].flatMap(group => mergeIntervals(group, padding));
 }

package/esm/util/io/index.js

@@ -19,18 +19,26 @@ export function resolveUriLocation(location) {
         : location;
 }
 /**
- * The local path a `file:` URI names, or undefined for any other scheme. A
- * Windows URL parses as `/C:/data/x.bam`, whose leading slash is part of the URL
- * grammar rather than the path.
+ * The local path a `file:` URI or a bare absolute path names, or undefined for
+ * anything else. A Windows URL parses as `/C:/data/x.bam`, whose leading slash
+ * is part of the URL grammar rather than the path, and a host is a network
+ * share: `\\server\share\x.bam` is `file://server/share/x.bam`.
  */
-function fileUrlToLocalPath(uri) {
+function uriToLocalPath(uri) {
+    if (uri.startsWith('/') || /^[a-z]:[\\/]/i.test(uri)) {
+        return uri;
+    }
     if (!uri.startsWith('file:')) {
         return undefined;
     }
     try {
-        const { pathname } = new URL(uri);
+        const { host, pathname } = new URL(uri);
         const decoded = decodeURIComponent(pathname);
-        return /^\/[a-z]:/i.test(decoded) ? decoded.slice(1) : decoded;
+        return host && host !== 'localhost'
+            ? `//${host}${decoded}`
+            : /^\/[a-z]:/i.test(decoded)
+                ? decoded.slice(1)
+                : decoded;
     }
     catch {
         return undefined;
@@ -69,7 +77,9 @@ export function openLocation(location, pluginManager) {
         if (!file) {
             throw new Error(`file ("${location.name}") requires permission. Please reopen the file from track settings`);
         }
-        return new CachedFilehandle(new BlobFile(file), `filehandle://${location.handleId}`);
+        // A File is a snapshot: the handle yields a new one once the file changes
+        // on disk, and its chunks must not be the old snapshot's
+        return new CachedFilehandle(new BlobFile(file), `filehandle://${location.handleId}@${file.lastModified}:${file.size}`);
     }
     if (isUriLocation(location)) {
         // Check for empty string
@@ -82,14 +92,11 @@ export function openLocation(location, pluginManager) {
         // a config that names its files relative to itself found no account at all
         // and read every one of them unauthenticated.
         const absoluteLocation = resolveUriLocation(location);
-        // A file: URI names a path on this machine, not something to fetch. Desktop
-        // reaches this by way of the shorthand forms: a config.json opened from disk
-        // carries a baseUri of its own directory, so `{ type: 'BamAdapter', uri:
-        // 'reads.bam' }` resolves here as file:///dir/reads.bam — and so does every
-        // sibling the shorthand derived from it (.bai, .fai, .gzi). Reading them as
-        // localPath keeps that whole chain on the one code path that can open a
-        // local file, instead of a fetch that no range request survives.
-        const localPath = fileUrlToLocalPath(absoluteLocation.uri);
+        // A file: URI or a bare absolute path names a file on this machine. A
+        // config.json opened from disk resolves `uri: 'reads.bam'` against its own
+        // directory to file:///dir/reads.bam, and a session built over MCP writes
+        // `uri: '/dir/reads.bam'` with no baseUri at all; fetched, either is a 404.
+        const localPath = uriToLocalPath(absoluteLocation.uri);
         if (localPath !== undefined && (isNode || isElectron)) {
             return openLocation({ localPath, locationType: 'LocalPathLocation' });
         }

package/esm/util/isDataCurrent.d.ts

@@ -1,7 +1,9 @@
 /**
- * The signature-based analog of the spatial `viewportWithinLoadedData`
- * (MultiRegionDisplayMixin) freshness check, for a display whose liveness is one
- * string rather than a per-region coverage map. An `undefined` loaded signature
- * is nothing fetched yet, so never current.
+ * Whether the key held data was committed under still equals the key a fetch
+ * issued now would carry. Keys are values compared structurally, so a stamp
+ * that kept its identity short-circuits on `===`, and an `undefined`-valued
+ * field or a fieldless class instance is still a distinct state — the two
+ * shapes `JSON.stringify` flattened. An `undefined` loaded key is nothing
+ * fetched yet, so never current.
  */
-export declare function isDataCurrent(loadedSignature: string | undefined, currentSignature: string | undefined): boolean;
+export declare function isDataCurrent(loaded: unknown, current: unknown): boolean;

package/esm/util/isDataCurrent.js

@@ -1,9 +1,12 @@
+import { compareStructural } from 'mobx';
 /**
- * The signature-based analog of the spatial `viewportWithinLoadedData`
- * (MultiRegionDisplayMixin) freshness check, for a display whose liveness is one
- * string rather than a per-region coverage map. An `undefined` loaded signature
- * is nothing fetched yet, so never current.
+ * Whether the key held data was committed under still equals the key a fetch
+ * issued now would carry. Keys are values compared structurally, so a stamp
+ * that kept its identity short-circuits on `===`, and an `undefined`-valued
+ * field or a fieldless class instance is still a distinct state — the two
+ * shapes `JSON.stringify` flattened. An `undefined` loaded key is nothing
+ * fetched yet, so never current.
  */
-export function isDataCurrent(loadedSignature, currentSignature) {
-    return loadedSignature !== undefined && loadedSignature === currentSignature;
+export function isDataCurrent(loaded, current) {
+    return loaded !== undefined && compareStructural(loaded, current);
 }

package/esm/util/isTextEntryFocused.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the user is typing into a text field, for a document-level shortcut
+ * that must leave that field's own keys alone: ctrl+z undoing typing rather
+ * than the session, ctrl+arrow moving the caret rather than the view. A
+ * `<textarea>` counts, which the multiline config and JSON editors render.
+ */
+export declare function isTextEntryFocused(): boolean;

package/esm/util/isTextEntryFocused.js

@@ -0,0 +1,16 @@
+/**
+ * Whether the user is typing into a text field, for a document-level shortcut
+ * that must leave that field's own keys alone: ctrl+z undoing typing rather
+ * than the session, ctrl+arrow moving the caret rather than the view. A
+ * `<textarea>` counts, which the multiline config and JSON editors render.
+ */
+export function isTextEntryFocused() {
+    const el = document.activeElement;
+    if (!(el instanceof HTMLElement)) {
+        return false;
+    }
+    const tag = el.tagName.toUpperCase();
+    // coerced: isContentEditable is declared boolean but is undefined in jsdom,
+    // so the raw expression returns undefined for an ordinary focused element
+    return tag === 'INPUT' || tag === 'TEXTAREA' || !!el.isContentEditable;
+}

package/esm/util/jexl.js

@@ -1,23 +1,10 @@
 import { Jexl } from '@jbrowse/jexl';
+import { categoricalColor } from '../ui/colors.js';
 import { randomColor } from './color/index.js';
 import { colord } from './colord.js';
 import { jexlFeatureProxy, unwrapFeature } from './simpleFeature.js';
 export default function JexlF( /* config?: any*/) {
     const j = new Jexl();
-    // Memoize compilation on the instance itself. A compiled Expression closes
-    // over this instance's grammar (its registered functions), so the cache
-    // belongs here and is naturally per-instance — there is no shared cache that
-    // could bind an expression to the wrong instance's functions.
-    const rawCompile = j.compile.bind(j);
-    const cache = new Map();
-    j.compile = (code) => {
-        let expr = cache.get(code);
-        if (expr === undefined) {
-            expr = rawCompile(code);
-            cache.set(code, expr);
-        }
-        return expr;
-    };
     // someday will make sure all of configs callbacks are added in, including
     // ones passed in
     // below are core functions
@@ -31,15 +18,29 @@ export default function JexlF( /* config?: any*/) {
         return p ? jexlFeatureProxy(p) : undefined;
     });
     j.addFunction('id', (feature) => unwrapFeature(feature).id());
+    /**
+     * #jexlFunction Feature operations - getInherited | getInherited(feature, 'gene_biotype') | the attribute from the feature, or from its nearest ancestor that has it, so a CDS reads its gene's value
+     */
+    j.addFunction('getInherited', (feature, name) => {
+        let cur = unwrapFeature(feature);
+        while (cur !== undefined) {
+            const value = cur.get(name);
+            if (value !== undefined) {
+                return value;
+            }
+            cur = cur.parent?.();
+        }
+        return undefined;
+    });
     // let user cast a jexl type into a javascript type
     j.addFunction('cast', (arg) => arg);
-    // math
-    // addfunction added in jexl 2.3 but types/jexl still on 2.2
-    /** #jexlFunction Math functions | max(0, 2) */
-    j.addFunction('max', Math.max);
-    /** #jexlFunction Math functions | min(0, 2) */
-    j.addFunction('min', Math.min);
-    /** #jexlFunction Math functions | sqrt(4) */
+    // jexl's own list-aware min and max take varargs too; a Math.min
+    // registration would replace them
+    /**
+     * #jexlFunction Math functions | max(0, 2)
+     * #jexlFunction Math functions | min(feature.INFO.AF)
+     * #jexlFunction Math functions | sqrt(4)
+     */
     j.addFunction('sqrt', Math.sqrt);
     /** #jexlFunction Math functions | ceil(0.5) */
     j.addFunction('ceil', Math.ceil);
@@ -148,6 +149,8 @@ export default function JexlF( /* config?: any*/) {
     // color helpers
     /** #jexlFunction Color functions | randomColor(feature.type) | deterministic color from a string (e.g. a feature type) */
     j.addFunction('randomColor', randomColor);
+    /** #jexlFunction Color functions | categoricalColor(getInherited(feature, 'biotype'), ['protein_coding']) | a palette color per value: the values listed take the palette (an optional third argument) in order, any other value a stable color no listed value paints, a missing one grey */
+    j.addFunction('categoricalColor', categoricalColor);
     // These take and return CSS color *strings*, not Colord objects: a config
     // `jexl:` expression has no way to construct a Colord, and a color slot
     // holding one resolves to the invalid-color sentinel rather than a color. So