@jbrowse/product-core 4.3.0 → 5.0.0-beta.10

package/esm/resolveAssemblies.d.ts

@@ -0,0 +1,68 @@
+import type { LooseSearchIndex } from '@jbrowse/core/util/expandLooseSearchIndex';
+export type AssemblyConfig = Record<string, unknown>;
+export interface TextSearchAdapterConfig {
+    type: string;
+    [key: string]: unknown;
+}
+type SearchAdapters = TextSearchAdapterConfig[] | undefined;
+export interface HubTrackConfig {
+    trackId: string;
+    [key: string]: unknown;
+}
+/**
+ * The shapes an assembly can take, discriminated at resolve time: a sequence
+ * file URL (`'.../hg38.fa.gz'`, `.2bit`, ...) built into an assembly via
+ * `makeAssembly`; a hub name (`'hg38'`, `'GCF_...'`) fetched from jbrowse.org;
+ * a full hub config (as `fetchHub` returns); or a bare assembly config (e.g.
+ * from `makeAssembly`) — the latter two both being plain config objects.
+ */
+export type AssemblyInput = string | AssemblyConfig;
+export interface ResolvedAssembly {
+    assembly: AssemblyConfig;
+    /** whatever search adapters the hub this came from carried */
+    aggregateTextSearchAdapters?: SearchAdapters;
+    /**
+     * the hub's track catalog, which its search index names its hits against, so
+     * a host keeping the index keeps these too
+     */
+    tracks?: HubTrackConfig[];
+}
+export interface ResolvedAssemblies<Track extends object = HubTrackConfig, Index extends LooseSearchIndex = TextSearchAdapterConfig> {
+    assemblies: AssemblyConfig[];
+    /** the hubs' search adapters, then the host's own */
+    aggregateTextSearchAdapters?: (TextSearchAdapterConfig | Index)[];
+    /** the hubs' track catalogs, then the host's own tracks */
+    tracks?: (HubTrackConfig | Track)[];
+}
+/** What a host already has, to merge with what its hubs bring. */
+export interface HostCatalog<Track extends object, Index extends LooseSearchIndex> {
+    tracks?: readonly Track[];
+    aggregateTextSearchAdapters?: readonly Index[];
+}
+/** One assembly in any of the four accepted shapes. */
+export declare function resolveAssembly(input: AssemblyInput): Promise<ResolvedAssembly>;
+/**
+ * Resolve a whole list of assembly inputs, so a multi-assembly product takes
+ * the same vocabulary the single-view one does — `['hg38', 'mm39']` as readily
+ * as two hand-written configs.
+ *
+ * A hub brings a track catalog and a search index that names hits by those
+ * tracks' ids, so both come back beside the assemblies. Pass the host's own
+ * `tracks` and `aggregateTextSearchAdapters` as `host` and they come back merged
+ * in, the host's winning an id, which makes spreading the result into
+ * `createApp`'s options correct:
+ *
+ * ```ts
+ * createApp(el, { ...options, ...(await resolveAssemblies(names, options)) })
+ * ```
+ *
+ * A key neither the hubs nor the host supplied is left out rather than set to
+ * `undefined`, so a spread never clears one.
+ *
+ * Exported because the resolution is async and `createApp` is not: an engine
+ * that resolved its own genomes would have to hand back a controller whose
+ * `viewState` is undefined until the fetches land. A host builds its options
+ * asynchronously already (runtime plugins), so this belongs in that step.
+ */
+export declare function resolveAssemblies<Track extends object = HubTrackConfig, Index extends LooseSearchIndex = TextSearchAdapterConfig>(inputs: AssemblyInput[], host?: HostCatalog<Track, Index>): Promise<ResolvedAssemblies<Track, Index>>;
+export {};

package/esm/resolveAssemblies.js

@@ -0,0 +1,77 @@
+import { expandLooseSearchIndex } from '@jbrowse/core/util/expandLooseSearchIndex';
+import { fetchHub } from '@jbrowse/core/util/fetchHub';
+import { isSequenceUri, makeAssembly } from '@jbrowse/core/util/makeAssembly';
+import { searchIndexKey, withHostOverrides } from './controllerTracks.js';
+// A hub is one assembly, so an index it writes short is on that assembly: it is
+// expanded here, before the merge puts it beside other hubs' assemblies where no
+// single one would fill it. What still names no adapter type cannot be
+// constructed, so it is dropped rather than cast.
+function searchAdaptersOf(hub) {
+    const name = hub.assemblies?.[0]?.name;
+    const found = (hub.aggregateTextSearchAdapters ?? [])
+        .map(index => expandLooseSearchIndex(index, typeof name === 'string' ? [name] : []))
+        .filter((a) => typeof a?.type === 'string');
+    return found.length ? found : undefined;
+}
+function tracksOf(hub) {
+    const found = (hub.tracks ?? []).filter((t) => typeof t.trackId === 'string');
+    return found.length ? found : undefined;
+}
+function fromHubConfig(hub) {
+    const assembly = hub.assemblies?.[0];
+    if (!assembly) {
+        throw new Error('hub config has no assemblies');
+    }
+    return {
+        assembly,
+        aggregateTextSearchAdapters: searchAdaptersOf(hub),
+        tracks: tracksOf(hub),
+    };
+}
+/** One assembly in any of the four accepted shapes. */
+export async function resolveAssembly(input) {
+    if (typeof input === 'string') {
+        return isSequenceUri(input)
+            ? { assembly: makeAssembly({ fastaUri: input }) }
+            : fromHubConfig(await fetchHub(input));
+    }
+    else if ('assemblies' in input) {
+        return fromHubConfig(input);
+    }
+    else {
+        return { assembly: input };
+    }
+}
+/**
+ * Resolve a whole list of assembly inputs, so a multi-assembly product takes
+ * the same vocabulary the single-view one does — `['hg38', 'mm39']` as readily
+ * as two hand-written configs.
+ *
+ * A hub brings a track catalog and a search index that names hits by those
+ * tracks' ids, so both come back beside the assemblies. Pass the host's own
+ * `tracks` and `aggregateTextSearchAdapters` as `host` and they come back merged
+ * in, the host's winning an id, which makes spreading the result into
+ * `createApp`'s options correct:
+ *
+ * ```ts
+ * createApp(el, { ...options, ...(await resolveAssemblies(names, options)) })
+ * ```
+ *
+ * A key neither the hubs nor the host supplied is left out rather than set to
+ * `undefined`, so a spread never clears one.
+ *
+ * Exported because the resolution is async and `createApp` is not: an engine
+ * that resolved its own genomes would have to hand back a controller whose
+ * `viewState` is undefined until the fetches land. A host builds its options
+ * asynchronously already (runtime plugins), so this belongs in that step.
+ */
+export async function resolveAssemblies(inputs, host = {}) {
+    const resolved = await Promise.all(inputs.map(resolveAssembly));
+    const tracks = withHostOverrides(resolved.flatMap(r => r.tracks ?? []), host.tracks, 'trackId');
+    const adapters = withHostOverrides(resolved.flatMap(r => r.aggregateTextSearchAdapters ?? []), host.aggregateTextSearchAdapters, searchIndexKey);
+    return {
+        assemblies: resolved.map(r => r.assembly),
+        ...(tracks.length ? { tracks } : {}),
+        ...(adapters.length ? { aggregateTextSearchAdapters: adapters } : {}),
+    };
+}

package/esm/rpcWorker.d.ts

@@ -1,12 +1,44 @@
 import { RpcServer } from '@jbrowse/core/util/librpc';
 import type { PluginConstructor } from '@jbrowse/core/Plugin';
-import type { LoadedPlugin } from '@jbrowse/core/PluginLoader';
+import type { LoadedPlugin, ReExportRegistryLoader } from '@jbrowse/core/PluginLoader';
 declare global {
     interface Window {
         rpcServer?: RpcServer;
     }
 }
-export declare function initializeWorker(corePlugins: PluginConstructor[], opts: {
+export interface WorkerOptions {
     fetchESM?: (url: string) => Promise<LoadedPlugin>;
-    fetchCJS?: (url: string) => Promise<LoadedPlugin>;
-}): Promise<void>;
+    /**
+     * The product's `workerReExports.generated.ts`, so a runtime plugin loading
+     * here reads the host's copy of every `@jbrowse` package the product
+     * bundles.
+     */
+    reExports: ReExportRegistryLoader;
+}
+type RpcFunc = (args: unknown) => Promise<unknown>;
+/**
+ * Wire the method's `statusCallback` to the status channel the driver opened
+ * for this call — and to nothing at all when it opened none.
+ *
+ * The `channel` is the driver's statement of whether anyone is listening
+ * (`WebWorkerHandle.call`), so a method run without one has to see the
+ * `undefined` its caller passed. Injecting a callback regardless made every
+ * "no statusCallback" branch in the worker unreachable: the byte reporter an
+ * adapter hands its reader, the emit `createProgressReporter` gates, and the
+ * postMessage each of those cost to reach a main-thread listener that dropped
+ * it.
+ *
+ * `channel` is transport bookkeeping and comes back OFF here, the mirror of
+ * `BaseRpcDriver.call` stripping `statusCallback` on the way out. It used to
+ * ride through into every worker method's arguments, where nothing read it and
+ * `RpcExecuteArgs<M>` did not declare it — a key the main-thread driver never
+ * adds, so the two drivers handed `execute` different bags. `rpcDriverParity`
+ * is what says so.
+ *
+ * Exported for its test and not from the package barrel: `initializeWorker` is
+ * the only thing a product's worker entry calls, and the branch here is a claim
+ * about the driver on the other side of postMessage that nothing else asserts.
+ */
+export declare function wrapForRpc(func: RpcFunc): (args: unknown) => Promise<unknown>;
+export declare function initializeWorker(corePlugins: PluginConstructor[], opts: WorkerOptions): Promise<void>;
+export {};

package/esm/rpcWorker.js

@@ -1,13 +1,34 @@
-import PluginLoader from '@jbrowse/core/PluginLoader';
+import PluginLoader, { preloadUMDBundles } from '@jbrowse/core/PluginLoader';
 import PluginManager from '@jbrowse/core/PluginManager';
+import { setNumberGrouping, throttleStatusEmits } from '@jbrowse/core/util';
 import { RpcServer, serializeError } from '@jbrowse/core/util/librpc';
-function receiveConfiguration() {
+import { setStackTraceLimit } from '@jbrowse/core/util/setStackTraceLimit';
+import { parallelizeWorkerChunkLoading } from './parallelChunkLoading.js';
+/**
+ * Start downloading what a boot configuration naming these plugins will load.
+ * A page that started this worker early sends the hint once it has resolved
+ * its plugins, which is well before it can send the configuration: that waits
+ * for the page to evaluate them and build its session. The configuration is
+ * still what the worker loads.
+ */
+function preloadHintedPlugins({ plugins, windowHref }, opts) {
+    if (plugins.length) {
+        opts.reExports().catch(() => { });
+        preloadUMDBundles(plugins, windowHref);
+    }
+}
+// waits for a message from the main thread containing our configuration, which
+// must be sent on boot
+function receiveConfiguration(opts) {
     const configurationP = new Promise(resolve => {
         function listener(e) {
-            if (e.data.message === 'config') {
+            if (e.data.message === 'config' && e.data.config) {
                 resolve(e.data.config);
                 removeEventListener('message', listener);
             }
+            else if (e.data.message === 'preloadPlugins' && e.data.hint) {
+                preloadHintedPlugins(e.data.hint, opts);
+            }
         }
         self.addEventListener('message', listener);
     });
@@ -15,43 +36,128 @@ function receiveConfiguration() {
     return configurationP;
 }
 async function getPluginManager(corePlugins, opts) {
-    const config = await receiveConfiguration();
-    const pluginLoader = new PluginLoader(config.plugins, opts).installGlobalReExports(self);
+    const config = await receiveConfiguration(opts);
+    // this realm formats its own strings — a jexl `mouseover` slot renders a
+    // tooltip against the full feature here rather than shipping it back — so it
+    // needs the main thread's display preference before any RPC method runs
+    setNumberGrouping(config.numberGrouping);
+    // Keep each runtime plugin's `definition` on its load record (mirroring the
+    // main thread's createPluginManager) so PluginManager populates
+    // runtimePluginDefinitions. A plugin that resolves a sibling asset from its
+    // own bundle url in the worker — e.g. GraphGenomeView's Bandage layout
+    // engine — needs its definition here, not just its instance.
+    const runtimePlugins = config.plugins.length
+        ? await new PluginLoader(config.plugins, opts)
+            .installGlobalReExports(self, opts.reExports)
+            .load(config.windowHref)
+        : [];
     return new PluginManager([
-        ...corePlugins.map(p => ({ plugin: p })),
-        ...(await pluginLoader.load(config.windowHref)),
-    ].map(P => new P.plugin()))
+        ...corePlugins.map(P => ({ plugin: new P() })),
+        ...runtimePlugins.map(({ plugin: P, definition }) => ({
+            plugin: new P(),
+            definition,
+        })),
+    ])
         .createPluggableElements()
         .configure();
 }
-function wrapForRpc(func) {
+/**
+ * Wire the method's `statusCallback` to the status channel the driver opened
+ * for this call — and to nothing at all when it opened none.
+ *
+ * The `channel` is the driver's statement of whether anyone is listening
+ * (`WebWorkerHandle.call`), so a method run without one has to see the
+ * `undefined` its caller passed. Injecting a callback regardless made every
+ * "no statusCallback" branch in the worker unreachable: the byte reporter an
+ * adapter hands its reader, the emit `createProgressReporter` gates, and the
+ * postMessage each of those cost to reach a main-thread listener that dropped
+ * it.
+ *
+ * `channel` is transport bookkeeping and comes back OFF here, the mirror of
+ * `BaseRpcDriver.call` stripping `statusCallback` on the way out. It used to
+ * ride through into every worker method's arguments, where nothing read it and
+ * `RpcExecuteArgs<M>` did not declare it — a key the main-thread driver never
+ * adds, so the two drivers handed `execute` different bags. `rpcDriverParity`
+ * is what says so.
+ *
+ * Exported for its test and not from the package barrel: `initializeWorker` is
+ * the only thing a product's worker entry calls, and the branch here is a claim
+ * about the driver on the other side of postMessage that nothing else asserts.
+ */
+export function wrapForRpc(func) {
     return (args) => {
-        const wrappedArgs = args;
-        const { channel, rpcDriverClassName } = wrappedArgs;
-        return func({
-            ...wrappedArgs,
-            statusCallback: (message) => {
-                self.rpcServer?.emit(channel, message);
-            },
-        }, rpcDriverClassName);
+        const { channel, ...rest } = args;
+        return func(channel === undefined
+            ? rest
+            : {
+                ...rest,
+                // thinned here rather than only where it lands: every emit costs a
+                // postMessage, a task and a clone on the main thread, which then
+                // throttles the same stream again to decide what to draw
+                statusCallback: throttleStatusEmits((message) => {
+                    self.rpcServer?.emit(channel, message);
+                }),
+            });
     };
 }
 export async function initializeWorker(corePlugins, opts) {
+    // a worker error's stack is captured here, not on the main thread, so the
+    // frame limit has to be raised in this scope to deepen it
+    setStackTraceLimit();
+    parallelizeWorkerChunkLoading();
     self.addEventListener('error', event => {
         console.error('[Worker uncaught error]', event.error || event.message);
     });
     self.addEventListener('unhandledrejection', event => {
         console.error('[Worker unhandled rejection]', event.reason);
     });
+    // the page posts calls without waiting for 'ready', and only the server
+    // built once the plugins have loaded can answer them
+    const early = [];
+    const hold = (e) => {
+        if (e.data.libRpc) {
+            early.push(e);
+        }
+    };
+    self.addEventListener('message', hold);
     try {
         const pluginManager = await getPluginManager(corePlugins, opts);
         const rpcConfig = Object.fromEntries(pluginManager
             .getRpcElements()
-            .map(e => [e.name, wrapForRpc(e.execute.bind(e))]));
-        self.rpcServer = new RpcServer(rpcConfig);
+            // `invoke`, not `execute`: it deserializes the arguments before handing
+            // them on, which is what makes the blob map current and the declared
+            // arg types true. MainThreadRpcDriver binds the same one.
+            .map(e => [e.name, wrapForRpc(e.invoke.bind(e))]));
+        const server = new RpcServer(rpcConfig);
+        self.rpcServer = server;
+        self.removeEventListener('message', hold);
+        for (const e of early) {
+            server.handler(e);
+        }
         postMessage({ message: 'ready' });
     }
     catch (e) {
-        postMessage({ message: 'error', error: serializeError(e) });
+        // The boot handshake's last frame, and it must never fail to send — for the
+        // reason RpcServer.throw must not, one level worse. `serializeError` copies
+        // an error's own-enumerable properties and skips only the ones that are
+        // themselves functions, so an error carrying an object with a method on it
+        // (a `cause` that is a Response, an adapter instance) makes this postMessage
+        // throw DataCloneError. This runs floating, so that throw becomes an
+        // unhandled rejection the listener above only logs: no 'ready', no 'error',
+        // and no ErrorEvent either, since a rejected promise is not a script error.
+        // The boot promise in WebWorkerRpcDriver then never settles, and because
+        // `invalidate` hangs off its rejection, the pool hands every later caller
+        // the same pending promise — every RPC on that slot awaits forever, showing
+        // a spinner and no error, until the page is reloaded. One worker's failure
+        // to report a failure takes the whole session's worth of calls with it.
+        //
+        // deserializeError accepts a bare string, which is what makes the fallback
+        // sound: a string always clones.
+        try {
+            postMessage({ message: 'error', error: serializeError(e) });
+        }
+        catch {
+            postMessage({ message: 'error', error: `${e}` });
+        }
     }
 }

package/esm/sessionMigrations/index.d.ts

@@ -0,0 +1,15 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+/**
+ * Every display-instance key an old session may carry and have honoured, by
+ * display type, `*` for any display, so `jbrowse validate` reports one as
+ * stale rather than dead.
+ */
+export declare function migratedDisplayInstanceKeys(pluginManager: PluginManager): Record<string, string[]>;
+/**
+ * Returns the snapshot by identity when nothing in it is retired, which is
+ * every session this build wrote.
+ *
+ * An app session holds `views`; a single-view embedded product's session holds
+ * one `view`, and a share link written by either reaches both.
+ */
+export declare function migrateSessionSnapshot(snapshot: Record<string, unknown>, pluginManager: PluginManager): Record<string, unknown>;

package/esm/sessionMigrations/index.js

@@ -0,0 +1,178 @@
+import { getConfigurationSchemaMetadata, liftRetiredSpellings, } from '@jbrowse/core/configuration';
+function resolverFor(pluginManager) {
+    const byName = new Map();
+    for (const display of pluginManager.getDisplayElements()) {
+        byName.set(display.name, { display });
+        for (const retired of display.retiredTypes) {
+            byName.set(retired.type, { display, retired });
+        }
+    }
+    return type => (typeof type === 'string' ? byName.get(type) : undefined);
+}
+/**
+ * Every display-instance key an old session may carry and have honoured, by
+ * display type, `*` for any display, so `jbrowse validate` reports one as
+ * stale rather than dead.
+ */
+export function migratedDisplayInstanceKeys(pluginManager) {
+    return {
+        '*': ['heightPreConfig'],
+        ...Object.fromEntries(pluginManager
+            .getDisplayElements()
+            .flatMap(d => d.retiredState ? [[d.name, [...d.retiredState.keys]]] : [])),
+    };
+}
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function migrateDisplay(display, trackConfigId, resolve, collected) {
+    const resolved = resolve(display.type);
+    if (!resolved) {
+        return display;
+    }
+    const { display: displayType, retired } = resolved;
+    const state = displayType.retiredState;
+    const shed = ['heightPreConfig', ...(state?.keys ?? [])].filter(k => k in display);
+    if (!retired && shed.length === 0) {
+        return display;
+    }
+    const { configuration } = display;
+    if (typeof configuration !== 'string') {
+        return { ...display, type: displayType.name };
+    }
+    const lifted = {
+        ...state?.lift(display),
+        ...(typeof display.heightPreConfig === 'number'
+            ? { height: display.heightPreConfig }
+            : {}),
+    };
+    const migrated = retired?.migrate?.(lifted) ?? lifted;
+    const meta = getConfigurationSchemaMetadata(displayType.configSchema);
+    const settings = meta ? liftRetiredSpellings(meta, migrated) : migrated;
+    const displayId = retired && configuration === `${trackConfigId}-${retired.type}`
+        ? `${trackConfigId}-${displayType.name}`
+        : configuration;
+    if (trackConfigId && Object.keys(settings).length > 0) {
+        collected.push({
+            trackConfigId,
+            displayId,
+            displayType: displayType.name,
+            settings,
+        });
+    }
+    const rest = { ...display };
+    for (const key of shed) {
+        delete rest[key];
+    }
+    return { ...rest, type: displayType.name, configuration: displayId };
+}
+function migrateTrack(track, resolve, collected) {
+    if (!isObject(track) || !Array.isArray(track.displays)) {
+        return track;
+    }
+    const trackConfigId = typeof track.configuration === 'string' ? track.configuration : undefined;
+    const displays = track.displays;
+    const next = displays.map(d => isObject(d) ? migrateDisplay(d, trackConfigId, resolve, collected) : d);
+    return next.some((d, i) => d !== displays[i])
+        ? { ...track, displays: next }
+        : track;
+}
+function migrateView(view, resolve, collected) {
+    let result = view;
+    const { tracks, views } = view;
+    if (Array.isArray(tracks)) {
+        const next = tracks.map(t => migrateTrack(t, resolve, collected));
+        if (next.some((t, i) => t !== tracks[i])) {
+            result = { ...result, tracks: next };
+        }
+    }
+    // a synteny view's panels are views of their own
+    if (Array.isArray(views)) {
+        const next = views.map(v => isObject(v) ? migrateView(v, resolve, collected) : v);
+        if (next.some((v, i) => v !== views[i])) {
+            result = { ...result, views: next };
+        }
+    }
+    return result;
+}
+// The entry the settings belong to is the one under their id, else the one
+// whose type loads as the same display: a session track still spelling the
+// retired type holds it under the retired type's id.
+function mergeSettingsIntoTrackConfig(track, { displayId, displayType, settings }, resolve) {
+    const list = Array.isArray(track.displays)
+        ? track.displays
+        : [];
+    const index = [
+        (d) => isObject(d) && d.displayId === displayId,
+        (d) => isObject(d) && resolve(d.type)?.display.name === displayType,
+    ]
+        .map(matches => list.findIndex(matches))
+        .find(i => i !== -1);
+    const displays = index === undefined
+        ? [...list, { type: displayType, displayId, ...settings }]
+        : list.map((d, i) => i === index ? { ...d, ...settings } : d);
+    return { ...track, displays };
+}
+function applyExtractedSettings(snapshot, collected, resolve) {
+    if (collected.length === 0) {
+        return snapshot;
+    }
+    const sessionTracks = Array.isArray(snapshot.sessionTracks)
+        ? [...snapshot.sessionTracks]
+        : [];
+    const sessionTrackIndex = new Map(sessionTracks.map((t, i) => [isObject(t) ? t.trackId : undefined, i]));
+    const deltas = isObject(snapshot.trackConfigDeltas)
+        ? { ...snapshot.trackConfigDeltas }
+        : {};
+    let sessionTracksChanged = false;
+    let deltasChanged = false;
+    for (const extracted of collected) {
+        const { trackConfigId } = extracted;
+        const index = sessionTrackIndex.get(trackConfigId);
+        const sessionTrack = index === undefined ? undefined : sessionTracks[index];
+        if (index !== undefined && isObject(sessionTrack)) {
+            sessionTracks[index] = mergeSettingsIntoTrackConfig(sessionTrack, extracted, resolve);
+            sessionTracksChanged = true;
+        }
+        else {
+            const existing = deltas[trackConfigId];
+            deltas[trackConfigId] = mergeSettingsIntoTrackConfig(isObject(existing) ? existing : { trackId: trackConfigId }, extracted, resolve);
+            deltasChanged = true;
+        }
+    }
+    return {
+        ...snapshot,
+        ...(sessionTracksChanged ? { sessionTracks } : {}),
+        ...(deltasChanged ? { trackConfigDeltas: deltas } : {}),
+    };
+}
+/**
+ * Returns the snapshot by identity when nothing in it is retired, which is
+ * every session this build wrote.
+ *
+ * An app session holds `views`; a single-view embedded product's session holds
+ * one `view`, and a share link written by either reaches both.
+ */
+export function migrateSessionSnapshot(snapshot, pluginManager) {
+    const { views, view } = snapshot;
+    const many = Array.isArray(views);
+    if (!many && !isObject(view)) {
+        return snapshot;
+    }
+    const resolve = resolverFor(pluginManager);
+    const collected = [];
+    let result = snapshot;
+    if (many) {
+        const next = views.map(v => isObject(v) ? migrateView(v, resolve, collected) : v);
+        if (next.some((v, i) => v !== views[i])) {
+            result = { ...result, views: next };
+        }
+    }
+    if (isObject(view)) {
+        const next = migrateView(view, resolve, collected);
+        if (next !== view) {
+            result = { ...result, view: next };
+        }
+    }
+    return applyExtractedSettings(result, collected, resolve);
+}

package/esm/sessionUrl.d.ts

@@ -0,0 +1,40 @@
+import type { AbstractSessionModel } from '@jbrowse/core/util';
+/**
+ * A serialized session. Open-shaped on purpose: the concrete shape is the
+ * session model's `SnapshotIn`, which grows with every plugin a host loads.
+ */
+export interface SessionSnapshot {
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Serialize a live session into a compact, URL-safe string for a query param or
+ * hash fragment. Deflated then base64url-encoded, so it survives a URL intact
+ * and stays far smaller than raw JSON.
+ *
+ * Not a plain `getSnapshot`: a workspace arrangement turned on by the sender's
+ * preference is not in the snapshot, so a raw one renders as a classic stack
+ * for whoever opens the link. `getShareableSessionSnapshot` stamps it first.
+ *
+ * The session travels but the config does not — the receiving app supplies its
+ * own assembly/tracks. Put the result somewhere the server never sees (the hash
+ * fragment) if it may be long: a query string can exceed the request-line limit
+ * and get a 414, which is why jbrowse-web moved its own there.
+ *
+ * Carries `ENCODED_PREFIX`, the same `?session=encoded-…` value jbrowse-web's
+ * SessionLoader decodes, so a link built by an embedded product opens in
+ * jbrowse.org/jb2 and vice versa. The format is `encodeSessionParam`'s `long`
+ * mode; sessionUrl.test.ts asserts the two stay byte-identical.
+ */
+export declare function encodeSessionToUrl(session: AbstractSessionModel): Promise<string>;
+/**
+ * Inverse of {@link encodeSessionToUrl}, and of the `json-` form jbrowse-web's
+ * share dialog writes. Accepts an `encoded-` value with or without its prefix,
+ * so a raw `?session=` value from either app passes straight through.
+ *
+ * Throws on anything that isn't a decodable session — a truncated link, or a
+ * `share-`/`spec-` param an embedded product doesn't handle — so a host can
+ * fall back to its own declarative launch state instead of opening a
+ * half-built session.
+ */
+export declare function decodeSessionFromUrl(value: string): Promise<SessionSnapshot>;