@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/TimeTraveller.js

@@ -1,5 +1,11 @@
-import { applySnapshot, getEnv, getSnapshot, onSnapshot, resolvePath, types, } from '@jbrowse/mobx-state-tree';
+// adapted from https://github.com/mobxjs/mobx-state-tree
+import { applySnapshot, getEnv, getSnapshot, onPatch, resolvePath, types, } from '@jbrowse/mobx-state-tree';
 const MAX_HISTORY_LENGTH = 20;
+/**
+ * #stateModel TimeTraveller
+ * Undo/redo history for a target state-tree node: records snapshots as it
+ * changes and exposes canUndo/canRedo with undo/redo actions.
+ */
 const TimeTraveller = types
     .model('TimeTraveller', {
     undoIdx: -1,
@@ -22,7 +28,71 @@ const TimeTraveller = types
     let snapshotDisposer;
     let skipNextUndoState = false;
     let debounceTimer;
-    let pendingSnapshot;
+    // When the last patch arrived, so one armed timer can decide on its own
+    // whether the store has gone quiet — see `armRecording`.
+    let lastPatchMs = 0;
+    const debounceMs = 300;
+    /**
+     * Record a snapshot once the target has been quiet for {@link debounceMs}.
+     *
+     * A debounce that re-times itself rather than one that is torn down and
+     * rebuilt per patch: a wheel zoom writes the view on every animation frame,
+     * and clearing plus reinstalling a timer for each of those patches was 320
+     * timer installs over a ten-second gesture. An armed timer that finds the
+     * store still busy re-arms for the remaining wait instead, so a burst of any
+     * length costs one timer.
+     */
+    const armRecording = (record) => {
+        lastPatchMs = Date.now();
+        const fire = () => {
+            const quietFor = Date.now() - lastPatchMs;
+            if (quietFor < debounceMs) {
+                debounceTimer = setTimeout(fire, debounceMs - quietFor);
+            }
+            else {
+                debounceTimer = undefined;
+                record();
+            }
+        };
+        debounceTimer ??= setTimeout(fire, debounceMs);
+    };
+    /**
+     * Apply `history[undoIdx]` to the target without recording it. The flag
+     * brackets the whole `applySnapshot` — patches are emitted synchronously
+     * inside it, and there are as many as there are changed leaves — and is
+     * lowered in a `finally` so a rejected snapshot can't leave recording off
+     * for good. Lowering it here rather than in the patch handler is the point:
+     * the handler cannot tell the last patch of an applySnapshot from the first
+     * patch of the user's next edit.
+     *
+     * A local function, not an action, so it stays off the model's API.
+     */
+    function applyHistoryState(index) {
+        if (!targetStore) {
+            return;
+        }
+        const snapshot = self.history[index];
+        skipNextUndoState = true;
+        try {
+            // ADR-069. `applySnapshot` reconciles by identifier, so it DESTROYS
+            // every node the target snapshot does not keep — in place, inside this
+            // action, with the components still mounted over them and the action's
+            // reactions due at its `endBatch`. That is the sequence `removeView`
+            // detaches to avoid, reached through a door it does not cover, so a
+            // view leaving by undo goes out the same one first.
+            //
+            // Inside the flag, and that is the point of taking the snapshot above:
+            // a detach patches the tree, and outside the bracket it would be
+            // recorded as an undoable step of its own and shift the history under
+            // the index we are applying.
+            const target = targetStore;
+            target.takeOutViewsMissingFrom?.(snapshot);
+            applySnapshot(targetStore, snapshot);
+        }
+        finally {
+            skipNextUndoState = false;
+        }
+    }
     return {
         stopTrackingUndo() {
             self.notTrackingUndo = true;
@@ -34,10 +104,6 @@ const TimeTraveller = types
             if (self.notTrackingUndo) {
                 return;
             }
-            if (skipNextUndoState) {
-                skipNextUndoState = false;
-                return;
-            }
             self.history.splice(self.undoIdx + 1);
             self.history.push(snapshot);
             if (self.history.length > MAX_HISTORY_LENGTH) {
@@ -46,11 +112,20 @@ const TimeTraveller = types
             self.undoIdx = self.history.length - 1;
         },
         beforeDestroy() {
-            snapshotDisposer();
+            // initialize() only runs once a session exists, so a root torn down
+            // before that (a failed boot, a test) has no disposer to call
+            snapshotDisposer?.();
             if (debounceTimer) {
                 clearTimeout(debounceTimer);
             }
         },
+        /**
+         * Start recording history for the target store. Re-runs whenever the root
+         * swaps in a new session node, so it must be idempotent: the previous
+         * registration is disposed and the history reset, because `history` is
+         * volatile while `undoIdx` is a persisted prop — carrying the old
+         * session's snapshots forward would make undo apply them to the new one.
+         */
         initialize() {
             targetStore = self.targetPath
                 ? resolvePath(self, self.targetPath)
@@ -58,36 +133,64 @@ const TimeTraveller = types
             if (!targetStore) {
                 throw new Error('Failed to find target store for TimeTraveller. Please provide `targetPath` property, or a `targetStore` in the environment');
             }
-            snapshotDisposer = onSnapshot(targetStore, snapshot => {
-                if (self.notTrackingUndo || skipNextUndoState) {
+            snapshotDisposer?.();
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+                debounceTimer = undefined;
+            }
+            skipNextUndoState = false;
+            self.history = [];
+            self.undoIdx = -1;
+            // read the target's current state rather than a snapshot captured per
+            // change: any change inside the debounce window re-times it, so when it
+            // does fire the two agree
+            const record = () => {
+                if (targetStore) {
+                    this.addUndoState(getSnapshot(targetStore));
+                }
+            };
+            // onPatch, not onSnapshot: this only needs to know *that* the target
+            // changed, and the snapshot is taken once per debounce window below.
+            // onSnapshot would serialize the whole target on every single change to
+            // hand the callback a snapshot we then throw away — debouncing the
+            // handler does not debounce that, because MST has to build the snapshot
+            // to call the handler at all. Measured on a LinearGenomeView drag, this
+            // was the only listener in the app firing every frame, re-serializing
+            // the entire session ~120 times per second to record it ~3 times.
+            // Patches fire synchronously on the same changes, so the flag handling
+            // below keeps its original ordering.
+            snapshotDisposer = onPatch(targetStore, () => {
+                if (self.notTrackingUndo) {
                     return;
                 }
-                pendingSnapshot = snapshot;
-                if (debounceTimer) {
-                    clearTimeout(debounceTimer);
+                // undo/redo raises this flag around its applySnapshot, so the state
+                // it applies is never recorded as an undoable action of its own.
+                // Cancel any debounce still pending from the change being undone
+                // while we're here. The flag is lowered by undo/redo once
+                // applySnapshot has returned, NOT on the first patch: applySnapshot
+                // emits one patch per changed leaf, so lowering it here left every
+                // patch after the first to schedule a recording of the undone state —
+                // which truncated the forward history (redo went dead) and re-pushed
+                // the state just restored, so the next undo landed on it again and
+                // appeared to do nothing.
+                if (skipNextUndoState) {
+                    if (debounceTimer) {
+                        clearTimeout(debounceTimer);
+                        debounceTimer = undefined;
+                    }
+                    return;
                 }
-                debounceTimer = setTimeout(() => {
-                    debounceTimer = undefined;
-                    this.addUndoState(pendingSnapshot);
-                }, 300);
+                armRecording(record);
             });
-            if (self.history.length === 0) {
-                this.addUndoState(getSnapshot(targetStore));
-            }
+            this.addUndoState(getSnapshot(targetStore));
         },
         undo() {
             self.undoIdx--;
-            skipNextUndoState = true;
-            if (targetStore) {
-                applySnapshot(targetStore, self.history[self.undoIdx]);
-            }
+            applyHistoryState(self.undoIdx);
         },
         redo() {
             self.undoIdx++;
-            skipNextUndoState = true;
-            if (targetStore) {
-                applySnapshot(targetStore, self.history[self.undoIdx]);
-            }
+            applyHistoryState(self.undoIdx);
         },
     };
 });

package/esm/util/aborting.d.ts

@@ -1,10 +1,62 @@
-import { Observable } from 'rxjs';
 declare class AbortError extends Error {
     code: string | undefined;
 }
-export declare function checkAbortSignal(signal?: AbortSignal): void;
-export declare function abortBreakPoint(signal?: AbortSignal): Promise<void>;
 export declare function makeAbortError(): AbortError | DOMException;
-export declare function observeAbortSignal(signal?: AbortSignal): Observable<Event>;
+/**
+ * The one way a fetch's catch block answers a thrown error, shared by every
+ * fetch family (FetchMixin's runFetch, the comparative installer, chord): an
+ * abort is the ordinary end of a superseded or cancelled fetch and is
+ * swallowed, and so is any failure of a fetch that is no longer the current
+ * one — a superseded fetch's error is routinely its teardown's side effect,
+ * and it must not overwrite the error slot (or the console) its successor
+ * owns. Only a current fetch's real failure is logged and published. The
+ * three sites used to spell this independently and had drifted on whether the
+ * log was currency-guarded; the comparative family's pin ("does not let a
+ * superseded fetch raise its error") is the semantic that was deliberate.
+ */
+export declare function handleFetchError(exception: unknown, isCurrent: () => boolean, setError: (e: unknown) => void): void;
+/**
+ * check if the given exception was caused by an operation being intentionally aborted
+ * @param exception -
+ */
 export declare function isAbortException(exception: unknown): boolean;
+/**
+ * Throw an AbortError if `signal` has aborted. A `signal.aborted` read, so it
+ * is cheap enough for the body of a loop; place it after any await and in any
+ * per-item callback a reader hands you.
+ */
+export declare function checkAbortSignal(signal?: AbortSignal): void;
+/**
+ * Run an awaited stage under `signal`: checked before it starts, and again
+ * once it settles. The check after is the one that gets left out when the two
+ * are placed by hand — a stop landing during a long await otherwise goes
+ * unseen until the next stage.
+ */
+export declare function withAbortCheck<T>(signal: AbortSignal | undefined, fn: () => T | Promise<T>): Promise<T>;
+export interface AbortBreakpoint {
+    /** True once every ~50 ms of wall time, otherwise a counter bump. */
+    due(): boolean;
+    /** Yield a task so a posted abort can land, then throw if it did. */
+    yield(): Promise<void>;
+}
+/**
+ * Cancellation for a loop that can run for seconds without awaiting — a
+ * whole-genome projection, a matrix fill. A `signal.aborted` read inside such a
+ * loop never changes, because the abort is a posted message; the loop has to
+ * give the event loop a turn now and then. A loop bounded by the byte gate or
+ * one region's features finishes before this would matter and only checks.
+ *
+ *     const breakpoint = createAbortBreakpoint(signal)
+ *     for (const row of rows) {
+ *       if (breakpoint.due()) {
+ *         await breakpoint.yield()
+ *       }
+ *       …
+ *     }
+ *
+ * Two calls rather than one because an `await` on a non-promise still costs a
+ * microtask, about 60 ns against 2 ns for the `due()` read, and a loop over
+ * every read in a pileup notices the difference.
+ */
+export declare function createAbortBreakpoint(signal?: AbortSignal): AbortBreakpoint;
 export {};

package/esm/util/aborting.js

@@ -1,25 +1,8 @@
-import { Observable, fromEvent } from 'rxjs';
+import { isElectron, isNode } from './environment.js';
+import { createTimeGate } from './timeGate.js';
 class AbortError extends Error {
     code;
 }
-export function checkAbortSignal(signal) {
-    if (!signal) {
-        return;
-    }
-    if (!(signal instanceof AbortSignal)) {
-        throw new TypeError('must pass an AbortSignal');
-    }
-    if (signal.aborted) {
-        throw makeAbortError();
-    }
-}
-function timeout(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-export async function abortBreakPoint(signal) {
-    await timeout(1);
-    checkAbortSignal(signal);
-}
 export function makeAbortError() {
     if (typeof DOMException !== 'undefined') {
         return new DOMException('aborted', 'AbortError');
@@ -28,15 +11,119 @@ export function makeAbortError() {
     e.code = 'ERR_ABORTED';
     return e;
 }
-export function observeAbortSignal(signal) {
-    if (!signal) {
-        return new Observable();
+/**
+ * The one way a fetch's catch block answers a thrown error, shared by every
+ * fetch family (FetchMixin's runFetch, the comparative installer, chord): an
+ * abort is the ordinary end of a superseded or cancelled fetch and is
+ * swallowed, and so is any failure of a fetch that is no longer the current
+ * one — a superseded fetch's error is routinely its teardown's side effect,
+ * and it must not overwrite the error slot (or the console) its successor
+ * owns. Only a current fetch's real failure is logged and published. The
+ * three sites used to spell this independently and had drifted on whether the
+ * log was currency-guarded; the comparative family's pin ("does not let a
+ * superseded fetch raise its error") is the semantic that was deliberate.
+ */
+export function handleFetchError(exception, isCurrent, setError) {
+    if (!isAbortException(exception) && isCurrent()) {
+        console.error(exception);
+        setError(exception);
     }
-    return fromEvent(signal, 'abort');
 }
+/**
+ * check if the given exception was caused by an operation being intentionally aborted
+ * @param exception -
+ */
 export function isAbortException(exception) {
-    return (exception instanceof Error &&
+    return (
+    // The message test is for an abort whose name did not survive a boundary
+    // (Electron IPC, RpcServer's message-only fallback). A timeout is a failure
+    // even though Node words it "The operation was aborted due to timeout".
+    exception instanceof Error &&
+        exception.name !== 'TimeoutError' &&
         (exception.name === 'AbortError' ||
-            exception.code === 'ERR_ABORTED' ||
+            // standard-ish non-DOM abort exception
+            (exception instanceof AbortError && exception.code === 'ERR_ABORTED') ||
             /\b(aborted|aborterror)\b/i.test(exception.message)));
 }
+/**
+ * Throw an AbortError if `signal` has aborted. A `signal.aborted` read, so it
+ * is cheap enough for the body of a loop; place it after any await and in any
+ * per-item callback a reader hands you.
+ */
+export function checkAbortSignal(signal) {
+    if (signal?.aborted) {
+        throw makeAbortError();
+    }
+}
+/**
+ * Run an awaited stage under `signal`: checked before it starts, and again
+ * once it settles. The check after is the one that gets left out when the two
+ * are placed by hand — a stop landing during a long await otherwise goes
+ * unseen until the next stage.
+ */
+export async function withAbortCheck(signal, fn) {
+    checkAbortSignal(signal);
+    const result = await fn();
+    checkAbortSignal(signal);
+    return result;
+}
+const YIELD_INTERVAL_MS = 50;
+/**
+ * Give the event loop one turn. A worker learns of an abort through a posted
+ * message, and a message is a task: an `await` on an already-settled promise
+ * drains only microtasks and delivers nothing. A browser realm, Electron's
+ * included, gets a MessageChannel task, which unlike `setTimeout` is not
+ * clamped. Not `scheduler.yield`: Chromium runs its continuation ahead of a
+ * posted message, so a worker loop yielding that way never sees the abort.
+ * Plain Node and jsdom get the timer: a MessagePort turn there runs no due
+ * timer, and under jest the abort is one.
+ */
+const yieldToEventLoop = (() => {
+    if ((isElectron || !isNode) && typeof MessageChannel !== 'undefined') {
+        const channel = new MessageChannel();
+        let resolvers = [];
+        channel.port1.onmessage = () => {
+            const pending = resolvers;
+            resolvers = [];
+            for (const resolve of pending) {
+                resolve();
+            }
+        };
+        return () => new Promise(resolve => {
+            resolvers.push(resolve);
+            channel.port2.postMessage(0);
+        });
+    }
+    return () => new Promise(resolve => {
+        setTimeout(resolve, 0);
+    });
+})();
+/**
+ * Cancellation for a loop that can run for seconds without awaiting — a
+ * whole-genome projection, a matrix fill. A `signal.aborted` read inside such a
+ * loop never changes, because the abort is a posted message; the loop has to
+ * give the event loop a turn now and then. A loop bounded by the byte gate or
+ * one region's features finishes before this would matter and only checks.
+ *
+ *     const breakpoint = createAbortBreakpoint(signal)
+ *     for (const row of rows) {
+ *       if (breakpoint.due()) {
+ *         await breakpoint.yield()
+ *       }
+ *       …
+ *     }
+ *
+ * Two calls rather than one because an `await` on a non-promise still costs a
+ * microtask, about 60 ns against 2 ns for the `due()` read, and a loop over
+ * every read in a pileup notices the difference.
+ */
+export function createAbortBreakpoint(signal) {
+    const gate = createTimeGate();
+    return {
+        due: () => gate(YIELD_INTERVAL_MS),
+        async yield() {
+            await yieldToEventLoop();
+            checkAbortSignal(signal);
+        },
+    };
+}

package/esm/util/adapterMetadata.d.ts

@@ -0,0 +1,20 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * A display's adapter header metadata (VCF INFO/FORMAT descriptions, and
+ * whatever else `CoreGetMetadata` answers for the adapter), fetched once per
+ * adapter config and reused across every feature-details open.
+ *
+ * Every open otherwise round-trips the worker to re-read a header the fetch
+ * that put the feature on screen already parsed. Canvas and the multi-sample
+ * variant base each carried this memo by hand; the copies had already drifted
+ * on nothing but were one more thing a third display would write a third way.
+ *
+ * Keyed on the adapter config rather than memoized for the display's life, so
+ * a track re-pointed in the config editor stops serving the old header's
+ * descriptions. Cleared on failure so a later click retries. No signal and
+ * no status: nothing to narrate, and nothing a cancel could save — the widget
+ * opens on the result.
+ */
+export declare function createAdapterMetadataFetch(self: IStateTreeNode & {
+    adapterConfig: Record<string, unknown>;
+}): () => Promise<unknown>;

package/esm/util/adapterMetadata.js

@@ -0,0 +1,40 @@
+import { isDataCurrent } from './isDataCurrent.js';
+import { getRpcSessionId } from './parentWalk.js';
+import { getRpcHost } from './sessionServices.js';
+/**
+ * A display's adapter header metadata (VCF INFO/FORMAT descriptions, and
+ * whatever else `CoreGetMetadata` answers for the adapter), fetched once per
+ * adapter config and reused across every feature-details open.
+ *
+ * Every open otherwise round-trips the worker to re-read a header the fetch
+ * that put the feature on screen already parsed. Canvas and the multi-sample
+ * variant base each carried this memo by hand; the copies had already drifted
+ * on nothing but were one more thing a third display would write a third way.
+ *
+ * Keyed on the adapter config rather than memoized for the display's life, so
+ * a track re-pointed in the config editor stops serving the old header's
+ * descriptions. Cleared on failure so a later click retries. No signal and
+ * no status: nothing to narrate, and nothing a cancel could save — the widget
+ * opens on the result.
+ */
+export function createAdapterMetadataFetch(self) {
+    let cached;
+    return () => {
+        const { adapterConfig } = self;
+        if (!cached || !isDataCurrent(cached.adapterConfig, adapterConfig)) {
+            const promise = getRpcHost(self)
+                // eslint-disable-next-line no-restricted-syntax -- nothing to narrate, nothing a cancel could save
+                .rpcManager.call(getRpcSessionId(self), 'CoreGetMetadata', {
+                adapterConfig,
+            })
+                .catch((e) => {
+                if (cached?.promise === promise) {
+                    cached = undefined;
+                }
+                throw e;
+            });
+            cached = { adapterConfig, promise };
+        }
+        return cached.promise;
+    };
+}

package/esm/util/addAndShowTrack.d.ts

@@ -0,0 +1,19 @@
+import type { SessionWithAddSessionTrack } from './types/index.ts';
+/**
+ * Add a track config to the session, then reveal it in `view` (when given).
+ * Shared by the features that stand a track up on the user's behalf — a GC
+ * content track off a sequence track's menu, a consensus opened as variants, a
+ * multi-wiggle built from a selection — which all add a track and then show it
+ * by trackId. Returns the added config, or undefined if it was invalid
+ * (surfaced as a snackbar) — see SessionTracks.addSessionTrackConf.
+ *
+ * Session-scoped, not published: none of these is a catalog entry, so an admin
+ * clicking one must not write it into the config.json every visitor is served.
+ * The Add-track workflows, which do mean that, go through
+ * `addTrackFromWidget`.
+ */
+export declare function addAndShowTrack(session: SessionWithAddSessionTrack, conf: Parameters<SessionWithAddSessionTrack['addSessionTrackConf']>[0] & {
+    trackId: string;
+}, view?: {
+    launchTrack: (trackId: string) => Promise<unknown>;
+}): import("../configuration/types.ts").AnyConfigurationModel | undefined;

package/esm/util/addAndShowTrack.js

@@ -0,0 +1,27 @@
+/**
+ * Add a track config to the session, then reveal it in `view` (when given).
+ * Shared by the features that stand a track up on the user's behalf — a GC
+ * content track off a sequence track's menu, a consensus opened as variants, a
+ * multi-wiggle built from a selection — which all add a track and then show it
+ * by trackId. Returns the added config, or undefined if it was invalid
+ * (surfaced as a snackbar) — see SessionTracks.addSessionTrackConf.
+ *
+ * Session-scoped, not published: none of these is a catalog entry, so an admin
+ * clicking one must not write it into the config.json every visitor is served.
+ * The Add-track workflows, which do mean that, go through
+ * `addTrackFromWidget`.
+ */
+export function addAndShowTrack(session, conf, view) {
+    const added = session.addSessionTrackConf(conf);
+    // 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) {
+        void view?.launchTrack(conf.trackId);
+    }
+    return added;
+}

package/esm/util/addRelativeUris.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stamp `baseUri` next to every `uri` in a config, and beside a MultiWiggle
+ * `bigWigs` array of bare URI strings, so relative URIs resolve against the
+ * location the config itself was loaded from. A file written as a bare string
+ * where a location object can go (a search index, `refNameAliases`,
+ * `cytobands`, a `bedLocations` entry) has no object to stamp, so it becomes
+ * `{ uri, baseUri }`.
+ * jbrowse-web runs this when it fetches a config.json from a URL; anything that
+ * injects a fetched config as an object (a hub, a track hub connection, a
+ * headless render) has to run it too, or the config's relative data URIs
+ * resolve against the page.
+ *
+ * Lives in core because core is what consumes the result — the assembly config
+ * schema and expandAssemblyConfigShorthand read `baseUri` back out.
+ */
+export declare function addRelativeUris(config: Record<string, unknown> | null, base: URL): void;
+/**
+ * A copy of `config` with every relative URI stamped against the page, which
+ * is what the page itself would resolve it against. An RPC worker started from
+ * a `blob:` URL has no such base, so a location it receives without one fails
+ * to parse there.
+ */
+export declare function withPageBaseUri<T>(config: T): T;
+/**
+ * Inverse of {@link addRelativeUris}: recursively delete every synthetic
+ * `baseUri` key (mutates in place), e.g. before serializing a config snapshot
+ * back out in the admin "Save config" flow or a "Copy config" button.
+ */
+export declare function stripBaseUris<T>(config: T): T;

package/esm/util/addRelativeUris.js

@@ -0,0 +1,78 @@
+/**
+ * Stamp `baseUri` next to every `uri` in a config, and beside a MultiWiggle
+ * `bigWigs` array of bare URI strings, so relative URIs resolve against the
+ * location the config itself was loaded from. A file written as a bare string
+ * where a location object can go (a search index, `refNameAliases`,
+ * `cytobands`, a `bedLocations` entry) has no object to stamp, so it becomes
+ * `{ uri, baseUri }`.
+ * jbrowse-web runs this when it fetches a config.json from a URL; anything that
+ * injects a fetched config as an object (a hub, a track hub connection, a
+ * headless render) has to run it too, or the config's relative data URIs
+ * resolve against the page.
+ *
+ * Lives in core because core is what consumes the result — the assembly config
+ * schema and expandAssemblyConfigShorthand read `baseUri` back out.
+ */
+export function addRelativeUris(config, base) {
+    if (typeof config === 'object' && config !== null) {
+        for (const key of Object.keys(config)) {
+            const value = liftBareFiles(key, config[key]);
+            if (value !== config[key]) {
+                config[key] = value;
+            }
+            if (typeof value === 'object' && value !== null) {
+                addRelativeUris(value, base);
+            }
+            if (key === 'uri' || (key === 'bigWigs' && Array.isArray(value))) {
+                config.baseUri ??= base.href;
+            }
+        }
+    }
+}
+// the keys whose value may be a file written as a bare string, which has no
+// object to carry a baseUri until it becomes `{ uri }`
+const FILE_KEYS = new Set(['textSearchAdapter', 'refNameAliases', 'cytobands']);
+const FILE_LIST_KEYS = new Set(['aggregateTextSearchAdapters', 'bedLocations']);
+function liftBareFiles(key, value) {
+    const lift = (file) => typeof file === 'string' ? { uri: file } : file;
+    return FILE_KEYS.has(key)
+        ? lift(value)
+        : FILE_LIST_KEYS.has(key) &&
+            Array.isArray(value) &&
+            value.some(file => typeof file === 'string')
+            ? value.map(lift)
+            : value;
+}
+/**
+ * A copy of `config` with every relative URI stamped against the page, which
+ * is what the page itself would resolve it against. An RPC worker started from
+ * a `blob:` URL has no such base, so a location it receives without one fails
+ * to parse there.
+ */
+export function withPageBaseUri(config) {
+    if (typeof document === 'undefined' || config === undefined) {
+        return config;
+    }
+    const copy = structuredClone(config);
+    addRelativeUris(copy, new URL(document.baseURI));
+    return copy;
+}
+/**
+ * Inverse of {@link addRelativeUris}: recursively delete every synthetic
+ * `baseUri` key (mutates in place), e.g. before serializing a config snapshot
+ * back out in the admin "Save config" flow or a "Copy config" button.
+ */
+export function stripBaseUris(config) {
+    if (typeof config === 'object' && config !== null) {
+        for (const key of Object.keys(config)) {
+            const obj = config;
+            if (key === 'baseUri') {
+                delete obj[key];
+            }
+            else {
+                stripBaseUris(obj[key]);
+            }
+        }
+    }
+    return config;
+}