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

package/esm/index.js

@@ -1,4 +1,31 @@
-export * from "./RootModel/index.js";
-export * from "./Session/index.js";
-export * from "./ui/index.js";
-export * from "./rpcWorker.js";
+export { asRoot, asSession } from './siblingCast.js';
+export { scheduleDetachedDestroy } from '@jbrowse/core/util';
+export { BaseRootModelFactory, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, HierarchicalConfigSchemaFactory, InternetAccountsRootModelMixin, PreferencesConfigSchemaFactory, createConfigModel, exportSessionMenuItem, importSessionMenuItem, isRootModel, newSessionMenuItem, openConnectionMenuItem, openTrackMenuItem, pluginStoreMenuItem, preferencesMenuItem, redoMenuItem, undoMenuItem, workspacesMenuItem, } from './RootModel/index.js';
+export { BaseSessionModel, ConnectionManagementSessionMixin, DrawerWidgetSessionMixin, MultipleViewsSessionMixin, PreferencesSessionMixin, ReferenceManagementSessionMixin, SessionTracksManagerSessionMixin, ThemeManagerSessionMixin, TrackMenuItemsSessionMixin, TrackMenuSessionMixin, TracksManagerSessionMixin, aboutTrackMenuItem, bakeSessionCascades, getShareableSessionSnapshot, copyTrackSnapshot, finalizeSession, hydratedForms, isBaseSession, isSession, isSessionWithConnections, isSessionWithDrawerWidgets, isSessionWithMultipleViews, isSessionWithReferenceManagement, isSessionWithThemes, isSessionWithTracks, pluginExtraTrackItems, storedThemeArgs, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './Session/index.js';
+export { AboutDialog, AppReadyMarker, Drawer, DrawerControls, DrawerHeader, DrawerWidget, DrawerWidgetSelector, ModalWidget, ModalWidgetAppBar, PreferencesDialog, WidgetBody, WidgetHeading, drawerGridTemplateColumns, } from './ui/index.js';
+export { initializeWorker } from './rpcWorker.js';
+export { toPluginLoadRecord } from './pluginInput.js';
+export { loadRuntimePlugins } from './loadPlugins.js';
+export { decodeSessionFromUrl, encodeSessionToUrl } from './sessionUrl.js';
+// in-memory files as tracks, for hosts whose data lives in a process rather
+// than at a URL (a notebook kernel, an R session) — read by byte range, so an
+// indexed file stays indexed
+export { normalizeAdapterSnapshots, registerLocalFiles, resolveLocalFileUris, } from './localFiles.js';
+export { searchIndexKey, withHostOverrides } from './controllerTracks.js';
+// the lifecycle behind each single-view product's imperative controller
+export { createEmbeddedController } from './embeddedController.js';
+// hub names, sequence URIs and hub configs -> assembly configs, so every
+// product takes the same assembly vocabulary
+export { resolveAssemblies, resolveAssembly } from './resolveAssemblies.js';
+// engine teardown, for a host that builds and discards engines — React unmount
+// alone leaves the RPC workers and autoruns running
+export { destroyViewState } from './destroyViewState.js';
+// the two halves of "React owns this engine", both of which have a StrictMode
+// trap in them that the obvious spelling walks straight into
+export { useAsyncEngineLifecycle, useCreateOnce, useCreateOnceAsync, useDestroyOnUnmount, } from './useEngineLifecycle.js';
+// the JS -> host direction of an embedded controller: where each view is
+// looking, what got selected, and the layout as plain JSON
+export { getSessionSnapshot, observeSession } from './observeSession.js';
+export { migrateSessionSnapshot, migratedDisplayInstanceKeys, } from './sessionMigrations/index.js';
+export { DEFAULT_WEB_BASE_URL, analyzeWebPortability, buildWebExportUrl, filterSessionInPlace, planWebExport, } from './sessionUtils.js';
+export { describeUnbuildableNodes, pruneUnbuildableNodes, } from './pruneUnbuildableNodes.js';

package/esm/loadPlugins.d.ts

@@ -0,0 +1,38 @@
+import type { LoadedPlugin, ReExportRegistryLoader } from '@jbrowse/core/PluginLoader';
+import type { PluginDefinition } from '@jbrowse/core/pluginDefinitions';
+export interface LoadPluginsArgs {
+    fetchESM?: (url: string) => Promise<LoadedPlugin>;
+    /**
+     * Resolve relative plugin urls against this instead of the page. A config
+     * fetched from somewhere else names its plugins relative to itself, so pass
+     * that config's url — otherwise a `"url": "umd_plugin.js"` entry is looked
+     * for next to your own app and 404s.
+     */
+    baseUri?: string;
+    /** @deprecated the pre-4.4 spelling of `baseUri` */
+    baseUrl?: string;
+}
+/**
+ * The body of every embedded product's `loadPlugins`. Each product keeps its own
+ * one-line wrapper, because the doc comment on it is the published API surface
+ * and names that product's own entry points — but the behavior is here, so the
+ * two things that differed between the copies can't drift again: react-app's
+ * accepted no `baseUrl`, and only two of the three defaulted the base url at
+ * all.
+ *
+ * `dropVendored` is the one difference that is real, so it is a required
+ * argument rather than a default. A product that bundles the vendored plugins
+ * (see `vendoredPluginNames`) must drop a config's entry for them or it installs
+ * a second copy beside its own; a product that does not bundle them — the
+ * circular-genome-view build has neither MafViewer nor GWAS in its corePlugins —
+ * must still fetch one a config names, or the config silently loses the plugin.
+ *
+ * `reExports` is the product's `reExports.generated.ts`, which serves every
+ * `@jbrowse` package the product bundles. Required for the same reason: a
+ * plugin handed core's map alone cannot read the rest.
+ */
+export declare function loadRuntimePlugins(pluginDefinitions: PluginDefinition[], { dropVendored, jbrowseVersion, reExports, ...args }: LoadPluginsArgs & {
+    dropVendored: boolean;
+    jbrowseVersion: string;
+    reExports: ReExportRegistryLoader;
+}): Promise<never[] | import("@jbrowse/core/PluginLoader").PluginRecord[]>;

package/esm/loadPlugins.js

@@ -0,0 +1,45 @@
+import PluginLoader from '@jbrowse/core/PluginLoader';
+import { dropVendoredPlugins } from '@jbrowse/core/pluginDefinitions';
+import { resolveStorePluginRefs } from '@jbrowse/core/util';
+/**
+ * The body of every embedded product's `loadPlugins`. Each product keeps its own
+ * one-line wrapper, because the doc comment on it is the published API surface
+ * and names that product's own entry points — but the behavior is here, so the
+ * two things that differed between the copies can't drift again: react-app's
+ * accepted no `baseUrl`, and only two of the three defaulted the base url at
+ * all.
+ *
+ * `dropVendored` is the one difference that is real, so it is a required
+ * argument rather than a default. A product that bundles the vendored plugins
+ * (see `vendoredPluginNames`) must drop a config's entry for them or it installs
+ * a second copy beside its own; a product that does not bundle them — the
+ * circular-genome-view build has neither MafViewer nor GWAS in its corePlugins —
+ * must still fetch one a config names, or the config silently loses the plugin.
+ *
+ * `reExports` is the product's `reExports.generated.ts`, which serves every
+ * `@jbrowse` package the product bundles. Required for the same reason: a
+ * plugin handed core's map alone cannot read the rest.
+ */
+export async function loadRuntimePlugins(pluginDefinitions, { dropVendored, jbrowseVersion, reExports, ...args }) {
+    // Before dropVendoredPlugins, which matches on the UMD name a ref does not
+    // carry until the store supplies it. `jbrowseVersion` is required rather than
+    // defaulted so a product that forgets it fails to compile instead of quietly
+    // resolving every range against the wrong host.
+    const { definitions, failures } = await resolveStorePluginRefs(pluginDefinitions, jbrowseVersion);
+    // This path ends in `load`, which is all-or-nothing (see below) — so a ref
+    // that resolved to nothing is a failure now rather than a plugin the embedder
+    // silently never receives.
+    if (failures[0]) {
+        throw failures[0].error;
+    }
+    const toLoad = dropVendored ? dropVendoredPlugins(definitions) : definitions;
+    // the default matters: `new URL('umd_plugin.js', undefined)` throws, so a
+    // relative plugin url used to fail outright instead of resolving against the
+    // page the way every other relative url does
+    const base = args.baseUri ?? args.baseUrl;
+    return toLoad.length
+        ? new PluginLoader(toLoad, args)
+            .installGlobalReExports(window, reExports)
+            .load(base ?? window.location.href)
+        : [];
+}

package/esm/localFiles.d.ts

@@ -0,0 +1,74 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { BlobLocation } from '@jbrowse/core/util';
+/**
+ * Bytes for one browser-local file, keyed by the name a track config refers to
+ * it by. `Blob`/`File` pass through; anything else (a `Uint8Array` from a
+ * notebook kernel's binary channel, an `ArrayBuffer` from a fetch) is wrapped.
+ */
+export type LocalFileInput = Record<string, Blob | BufferSource>;
+/**
+ * Register in-memory bytes as browser-local files JBrowse can read, returning
+ * the `name -> BlobLocation` map {@link resolveLocalFileUris} substitutes with.
+ *
+ * This is the escape from "the data has to be on a web server first". A
+ * `BlobLocation` opens as a `BlobFile`, which serves byte ranges out of
+ * `Blob.slice()` — so a bgzipped+tabixed file, a BAM with its `.bai`, or a
+ * bigWig is *seeked into* exactly as if it were remote, and only the bytes the
+ * current view needs are ever touched. That is the whole point of doing this
+ * rather than inlining features into a config: a 200k-feature table is ~20MB of
+ * JSON to serialize, ship, and hold in memory, while the same data as a tabix
+ * file is a few MB the view reads a few KB of at a time.
+ *
+ * For hosts that hold their data in a process rather than at a URL — a notebook
+ * kernel, an R session, a desktop app — this is the way in, and it needs no web
+ * server, no CORS, and no temporary public bucket.
+ */
+export declare function registerLocalFiles(files: LocalFileInput): {
+    [k: string]: BlobLocation;
+};
+/**
+ * Fold newly-offered files into a controller's registered map, registering only
+ * the names it has not seen. Registering is what mints the blobIds, so a host
+ * re-stating its whole file set on every update — which is what a declarative
+ * host does — pays for each file once rather than once per update.
+ *
+ * Only ever adds: a name already registered keeps its existing blob, because a
+ * live track config points at that blobId and swapping it underneath would
+ * leave the track reading bytes nothing else references.
+ */
+export declare function mergeLocalFiles(current: Record<string, BlobLocation>, files: LocalFileInput): {
+    [x: string]: BlobLocation;
+};
+/**
+ * Expand every shorthand adapter snapshot (`{ type, uri }`) in a config to the
+ * canonical location keys its config schema declares, using that adapter type's
+ * own `normalizeSnapshot` — the hook that exists so "downstream code can read
+ * location keys without knowing each shorthand".
+ *
+ * {@link resolveLocalFileUris} has to run on the expanded form, and this is the
+ * difference between `localFiles` working and silently doing nothing: the
+ * shorthand puts `uri` on the *adapter*, so substituting there would replace
+ * `{ type: 'BamAdapter', uri: 'x.bam' }` with a bare BlobLocation and take the
+ * adapter's type with it. Expanding first moves the name onto `bamLocation`,
+ * where it is a location node and substitution is what it looks like. The
+ * expansion also derives the conventional index sibling (`.bai`/`.tbi`/`.crai`)
+ * from the same string, so registering `x.bam` and `x.bam.bai` is enough and no
+ * caller has to know which adapter wanted which file.
+ *
+ * Idempotent, and a no-op for an already-canonical config or an adapter type
+ * that declares no shorthand.
+ */
+export declare function normalizeAdapterSnapshots<T>(config: T, pluginManager: PluginManager): T;
+/**
+ * Rewrite every `{ uri: <a registered name> }` in a track config to that file's
+ * `BlobLocation`, in place of nothing else — unregistered URIs are left alone,
+ * so a config can mix local and remote files freely.
+ *
+ * Runs on a config whose locations are already canonical, which is what
+ * `guessTrackConf` (for a loose track spec) and {@link normalizeAdapterSnapshots}
+ * (for a written-out one) each produce. So a host registers `peaks.bed.gz` and
+ * `peaks.bed.gz.tbi` under their plain names, the config names both under
+ * `bedGzLocation` and `index.location`, and this swaps both for blobs — index
+ * and all, with no host-side knowledge of which adapter wanted which sibling.
+ */
+export declare function resolveLocalFileUris<T>(config: T, locations: Record<string, BlobLocation>): T;

package/esm/localFiles.js

@@ -0,0 +1,156 @@
+import { storeBlobLocation } from '@jbrowse/core/util';
+/**
+ * Register in-memory bytes as browser-local files JBrowse can read, returning
+ * the `name -> BlobLocation` map {@link resolveLocalFileUris} substitutes with.
+ *
+ * This is the escape from "the data has to be on a web server first". A
+ * `BlobLocation` opens as a `BlobFile`, which serves byte ranges out of
+ * `Blob.slice()` — so a bgzipped+tabixed file, a BAM with its `.bai`, or a
+ * bigWig is *seeked into* exactly as if it were remote, and only the bytes the
+ * current view needs are ever touched. That is the whole point of doing this
+ * rather than inlining features into a config: a 200k-feature table is ~20MB of
+ * JSON to serialize, ship, and hold in memory, while the same data as a tabix
+ * file is a few MB the view reads a few KB of at a time.
+ *
+ * For hosts that hold their data in a process rather than at a URL — a notebook
+ * kernel, an R session, a desktop app — this is the way in, and it needs no web
+ * server, no CORS, and no temporary public bucket.
+ */
+export function registerLocalFiles(files) {
+    return Object.fromEntries(Object.entries(files).map(([name, data]) => [name, register(name, data)]));
+}
+/**
+ * Fold newly-offered files into a controller's registered map, registering only
+ * the names it has not seen. Registering is what mints the blobIds, so a host
+ * re-stating its whole file set on every update — which is what a declarative
+ * host does — pays for each file once rather than once per update.
+ *
+ * Only ever adds: a name already registered keeps its existing blob, because a
+ * live track config points at that blobId and swapping it underneath would
+ * leave the track reading bytes nothing else references.
+ */
+export function mergeLocalFiles(current, files) {
+    const fresh = Object.fromEntries(Object.entries(files).filter(([name]) => !current[name]));
+    return { ...current, ...registerLocalFiles(fresh) };
+}
+// Registering the same bytes twice used to mint a second blobId and leave the
+// first in core's process-global blobMap forever. Nothing collects that map, so
+// a host that hands the same `localFiles` to a new controller each time it
+// rebuilds — which is how a host swaps genome or track set, now that the
+// controller has no setters that rebuild internally — grew it without bound.
+//
+// Keyed on the caller's own object, which is the only identity available: bytes
+// are not comparable cheaply, and two Uint8Arrays over the same buffer are
+// legitimately different files. A WeakMap so a host dropping its reference to
+// the data lets the entry go, and per name inside it because the same bytes can
+// legitimately be registered under two names and a BlobLocation carries one.
+const registered = new WeakMap();
+function register(name, data) {
+    const byName = registered.get(data) ?? new Map();
+    const seen = byName.get(name);
+    if (seen) {
+        return seen;
+    }
+    const location = storeBlobLocation({
+        blob: data instanceof File ? data : new File([data], name),
+    });
+    byName.set(name, location);
+    registered.set(data, byName);
+    return location;
+}
+// A location node is `{ uri }` and at most the two keys that travel with it.
+// Anything else carrying a `uri` is a shorthand adapter (`{ type, uri }`), and
+// telling the two apart is what stops resolveLocalFileUris replacing a whole
+// adapter with a bare location — see its comment.
+const LOCATION_KEYS = new Set(['uri', 'baseUri', 'locationType']);
+function isLocationNode(record) {
+    return Object.keys(record).every(key => LOCATION_KEYS.has(key));
+}
+/**
+ * Expand every shorthand adapter snapshot (`{ type, uri }`) in a config to the
+ * canonical location keys its config schema declares, using that adapter type's
+ * own `normalizeSnapshot` — the hook that exists so "downstream code can read
+ * location keys without knowing each shorthand".
+ *
+ * {@link resolveLocalFileUris} has to run on the expanded form, and this is the
+ * difference between `localFiles` working and silently doing nothing: the
+ * shorthand puts `uri` on the *adapter*, so substituting there would replace
+ * `{ type: 'BamAdapter', uri: 'x.bam' }` with a bare BlobLocation and take the
+ * adapter's type with it. Expanding first moves the name onto `bamLocation`,
+ * where it is a location node and substitution is what it looks like. The
+ * expansion also derives the conventional index sibling (`.bai`/`.tbi`/`.crai`)
+ * from the same string, so registering `x.bam` and `x.bam.bai` is enough and no
+ * caller has to know which adapter wanted which file.
+ *
+ * Idempotent, and a no-op for an already-canonical config or an adapter type
+ * that declares no shorthand.
+ */
+export function normalizeAdapterSnapshots(config, pluginManager) {
+    if (Array.isArray(config)) {
+        return config.map(item => normalizeAdapterSnapshots(item, pluginManager));
+    }
+    if (typeof config === 'object' && config !== null) {
+        const record = config;
+        // `type` names a track, a display and an adapter alike, so this asks
+        // whether the name is an adapter rather than demanding that it is —
+        // getAdapterType throws on a miss, and 'AlignmentsTrack' is a miss
+        const normalize = typeof record.type === 'string' &&
+            pluginManager.hasAdapterType(record.type)
+            ? pluginManager.getAdapterType(record.type).normalizeSnapshot
+            : undefined;
+        const normalized = normalize?.(record) ?? record;
+        // Every normalizeSnapshot returns its argument unchanged when there was no
+        // shorthand to expand, so identity is the signal that `uri` was consumed —
+        // and it then has to GO. The same function runs again as the config
+        // schema's preProcessSnapshot when MST builds the tree, and a surviving
+        // `uri` makes that second pass rebuild the location from the string,
+        // overwriting the BlobLocation just substituted into it. That failure is
+        // invisible: the track ends up pointing at a relative URL named
+        // `volvox-sorted.bam`, which 404s against the host page's own origin.
+        const expanded = normalized === record
+            ? record
+            : Object.fromEntries(Object.entries(normalized).filter(([key]) => key !== 'uri'));
+        return Object.fromEntries(Object.entries(expanded).map(([key, value]) => [
+            key,
+            normalizeAdapterSnapshots(value, pluginManager),
+        ]));
+    }
+    return config;
+}
+/**
+ * Rewrite every `{ uri: <a registered name> }` in a track config to that file's
+ * `BlobLocation`, in place of nothing else — unregistered URIs are left alone,
+ * so a config can mix local and remote files freely.
+ *
+ * Runs on a config whose locations are already canonical, which is what
+ * `guessTrackConf` (for a loose track spec) and {@link normalizeAdapterSnapshots}
+ * (for a written-out one) each produce. So a host registers `peaks.bed.gz` and
+ * `peaks.bed.gz.tbi` under their plain names, the config names both under
+ * `bedGzLocation` and `index.location`, and this swaps both for blobs — index
+ * and all, with no host-side knowledge of which adapter wanted which sibling.
+ */
+export function resolveLocalFileUris(config, locations) {
+    if (Array.isArray(config)) {
+        return config.map(item => resolveLocalFileUris(item, locations));
+    }
+    if (typeof config === 'object' && config !== null) {
+        const record = config;
+        const uri = record.uri;
+        // the whole location node is replaced: a BlobLocation carries blobId and
+        // its own locationType, and leaving the old uri alongside would make it
+        // fail isBlobLocation's discrimination. Only a *location* node, though — a
+        // shorthand adapter also has a `uri`, and replacing that node discards the
+        // adapter's type and every sibling key, which the config schema then papers
+        // over with its `/path/to/my.bam` default: a track that loads nothing, with
+        // nothing logged. normalizeAdapterSnapshots is what turns the shorthand
+        // into a location node so this substitutes it.
+        if (typeof uri === 'string' && locations[uri] && isLocationNode(record)) {
+            return locations[uri];
+        }
+        return Object.fromEntries(Object.entries(record).map(([key, value]) => [
+            key,
+            resolveLocalFileUris(value, locations),
+        ]));
+    }
+    return config;
+}

package/esm/observeSession.d.ts

@@ -0,0 +1,55 @@
+import type { SessionSnapshot } from './sessionUrl.ts';
+type OpenTracks = {
+    configuration: {
+        trackId: string;
+    };
+}[];
+interface ObservedView {
+    id?: string;
+    coarseVisibleLocStrings?: string;
+    views?: {
+        coarseVisibleLocStrings?: string;
+    }[];
+    tracks?: OpenTracks;
+    levels?: {
+        tracks: OpenTracks;
+    }[];
+}
+export interface ObservedSession {
+    name: string;
+    views: ObservedView[];
+    selection?: unknown;
+}
+interface ObservedRoot {
+    session?: ObservedSession;
+}
+/** where one view is looking: a locstring, or one per panel for a comparative view */
+export type ViewLocation = string | string[] | undefined;
+export interface SessionObservers {
+    /** fires with every view's visible region when the layout settles */
+    onLocationChange?: (locations: ViewLocation[]) => void;
+    /** fires with the serialized feature when one is selected in any view */
+    onFeatureSelect?: (feature: unknown) => void;
+    /**
+     * fires with a plain-JSON snapshot of the layout the user built, in the shape
+     * the `session` option takes — so "save this arrangement" is storing this
+     * value and reopening it is passing it back
+     */
+    onSessionChange?: (session: SessionSnapshot) => void;
+}
+/**
+ * The live session as a plain JSON snapshot, ready to hand straight back as a
+ * product's `session` option (or its controller's `setSession`). The
+ * uncompressed twin of `encodeSession`, for hosts that move JSON rather than
+ * URLs — a notebook kernel, an R session, a "save this layout" button.
+ *
+ * Not a plain `getSnapshot`, and for the same reason `encodeSession` isn't: a
+ * workspace arrangement turned on by the sender's preference is not in the
+ * snapshot, so a raw one replays as a classic stack for whoever opens it.
+ */
+export declare function getSessionSnapshot(session: ObservedSession): SessionSnapshot;
+/**
+ * Wire the read-backs a host asked for, returning one disposer for all of them.
+ */
+export declare function observeSession(root: ObservedRoot, { onLocationChange, onFeatureSelect, onSessionChange }: SessionObservers): () => void;
+export {};

package/esm/observeSession.js

@@ -0,0 +1,90 @@
+import { isFeature } from '@jbrowse/core/util';
+import { autorun, untracked } from 'mobx';
+import { getShareableSessionSnapshot } from './Session/shareableSnapshot.js';
+/**
+ * The live session as a plain JSON snapshot, ready to hand straight back as a
+ * product's `session` option (or its controller's `setSession`). The
+ * uncompressed twin of `encodeSession`, for hosts that move JSON rather than
+ * URLs — a notebook kernel, an R session, a "save this layout" button.
+ *
+ * Not a plain `getSnapshot`, and for the same reason `encodeSession` isn't: a
+ * workspace arrangement turned on by the sender's preference is not in the
+ * snapshot, so a raw one replays as a classic stack for whoever opens it.
+ */
+export function getSessionSnapshot(session) {
+    // `name` is restated rather than the whole thing cast: the bake returns an
+    // open record, but the model guarantees the session has one
+    return {
+        ...getShareableSessionSnapshot(session),
+        name: session.name,
+    };
+}
+// A linear view reports its visible region as one coarseVisibleLocStrings
+// string; a comparative view (synteny/dotplot) has no single string, so report
+// one entry per panel instead.
+function viewLocation(view) {
+    return typeof view.coarseVisibleLocStrings === 'string'
+        ? view.coarseVisibleLocStrings || undefined
+        : view.views
+            ?.map(v => v.coarseVisibleLocStrings)
+            .filter(loc => loc !== undefined);
+}
+// Every trackId a view has open. A synteny view keeps its tracks per level
+// rather than in one flat list, so reading `tracks` alone reports none of them —
+// and the read-back then never fired when a synteny track was opened.
+function viewTracks(view) {
+    return (view.tracks ?? view.levels?.flatMap(l => l.tracks) ?? [])
+        .map(t => t.configuration.trackId)
+        .join(',');
+}
+// The coarse signal the read-backs ride on: which views exist, what each has
+// open, and where each is looking. Deliberately NOT the whole snapshot —
+// depending on that would pull in offsetPx, and a snapshot is kilobytes, so a
+// drag would push one per pointer event across the host's wire.
+// coarseVisibleLocStrings is JBrowse's own debounced location, so this settles
+// after a pan rather than firing during it.
+//
+// A plain function, not an action: actions run untracked, and computing this is
+// precisely what subscribes the autorun below.
+function layoutSignal(views) {
+    return views
+        .map(v => `${v.id}:${JSON.stringify(viewLocation(v))}:${viewTracks(v)}`)
+        .join('|');
+}
+/**
+ * Wire the read-backs a host asked for, returning one disposer for all of them.
+ */
+export function observeSession(root, { onLocationChange, onFeatureSelect, onSessionChange }) {
+    const disposers = [];
+    // `session` is read inside each autorun and never captured: setSession
+    // replaces the whole node (`self.session = cast(...)` in BaseRootModel), so a
+    // captured one is a dead MST node the moment a session is restored, and the
+    // read-back would go silent for the rest of the product's life.
+    if (onLocationChange ?? onSessionChange) {
+        disposers.push(autorun(() => {
+            const { session } = root;
+            if (!session) {
+                return;
+            }
+            // the only dependency this autorun should have
+            layoutSignal(session.views);
+            onLocationChange?.(session.views.map(viewLocation));
+            // untracked, so reading the snapshot adds no dependencies of its own
+            // eslint-disable-next-line no-restricted-syntax -- effect input: the callback consumes the snapshot, the views are the trigger
+            onSessionChange?.(untracked(() => getSessionSnapshot(session)));
+        }));
+    }
+    if (onFeatureSelect) {
+        disposers.push(autorun(() => {
+            const selection = root.session?.selection;
+            if (isFeature(selection)) {
+                onFeatureSelect(selection.toJSON());
+            }
+        }));
+    }
+    return () => {
+        for (const dispose of disposers) {
+            dispose();
+        }
+    };
+}

package/esm/parallelChunkLoading.d.ts

@@ -0,0 +1,30 @@
+type ChunkId = string | number;
+type ChunkHandler = (chunkId: ChunkId, promises: Promise<unknown>[]) => void;
+export interface WebpackChunkRuntime {
+    f?: Record<string, ChunkHandler | undefined>;
+}
+export interface WorkerScope {
+    importScripts: (url: string) => void;
+    location: {
+        href: string;
+    };
+    fetch: (url: string) => Promise<{
+        arrayBuffer: () => Promise<unknown>;
+    }>;
+}
+/**
+ * Download the chunks of a dynamic import together in a classic web worker.
+ *
+ * Webpack's worker chunk handler (`f.i`) runs `importScripts` for one chunk at
+ * a time, and `importScripts` blocks until its file has arrived, so an import
+ * spanning 26 chunks waits on 26 round trips in a row. This handler asks the
+ * original which url it would load (none, if the chunk is installed), fetches
+ * it, and runs `importScripts` once the fetch lands, by then a cache read. A
+ * chunk file only registers module factories, so install order is free.
+ *
+ * Only same-origin http(s) chunks are prefetched: another origin would need
+ * CORS for `fetch`, and a `file:` worker (Desktop) has no round trip to save.
+ */
+export declare function parallelizeChunkLoading(runtime: WebpackChunkRuntime | undefined, scope: WorkerScope): void;
+export declare function parallelizeWorkerChunkLoading(): void;
+export {};

package/esm/parallelChunkLoading.js

@@ -0,0 +1,71 @@
+/**
+ * Download the chunks of a dynamic import together in a classic web worker.
+ *
+ * Webpack's worker chunk handler (`f.i`) runs `importScripts` for one chunk at
+ * a time, and `importScripts` blocks until its file has arrived, so an import
+ * spanning 26 chunks waits on 26 round trips in a row. This handler asks the
+ * original which url it would load (none, if the chunk is installed), fetches
+ * it, and runs `importScripts` once the fetch lands, by then a cache read. A
+ * chunk file only registers module factories, so install order is free.
+ *
+ * Only same-origin http(s) chunks are prefetched: another origin would need
+ * CORS for `fetch`, and a `file:` worker (Desktop) has no round trip to save.
+ */
+export function parallelizeChunkLoading(runtime, scope) {
+    const handlers = runtime?.f;
+    const original = handlers?.i;
+    if (!handlers || !original) {
+        return;
+    }
+    const { origin, protocol } = new URL(scope.location.href);
+    if (protocol !== 'http:' && protocol !== 'https:') {
+        return;
+    }
+    const importScripts = scope.importScripts.bind(scope);
+    const loading = new Map();
+    const urlOriginalWouldLoad = (chunkId, promises) => {
+        let url;
+        scope.importScripts = (u) => {
+            url = u;
+        };
+        try {
+            original(chunkId, promises);
+        }
+        finally {
+            scope.importScripts = importScripts;
+        }
+        return url;
+    };
+    handlers.i = (chunkId, promises) => {
+        const url = urlOriginalWouldLoad(chunkId, promises);
+        if (url === undefined) {
+            return;
+        }
+        if (new URL(url, scope.location.href).origin !== origin) {
+            importScripts(url);
+            return;
+        }
+        let pending = loading.get(url);
+        if (!pending) {
+            pending = scope
+                .fetch(url)
+                .then(r => r.arrayBuffer())
+                .then(() => { }, () => { })
+                .then(() => {
+                importScripts(url);
+            });
+            pending.catch(() => {
+                loading.delete(url);
+            });
+            loading.set(url, pending);
+        }
+        promises.push(pending);
+    };
+}
+export function parallelizeWorkerChunkLoading() {
+    parallelizeChunkLoading(
+    // eslint-disable-next-line unicorn/no-typeof-undefined -- undeclared outside webpack, so a direct read throws
+    typeof __webpack_require__ === 'undefined'
+        ? undefined
+        : __webpack_require__, globalThis);
+}

package/esm/pluginInput.d.ts

@@ -0,0 +1,32 @@
+import type { PluginConstructor } from '@jbrowse/core/Plugin';
+import type { PluginRecord } from '@jbrowse/core/PluginLoader';
+/**
+ * A plugin an embedded product's caller can register: either the class itself,
+ * or the `{ plugin, definition }` record `loadPlugins` returns.
+ *
+ * Prefer passing the record straight through. The `definition` is what lets the
+ * RPC worker load the same plugin on its side — hand it only the class and the
+ * plugin exists on the main thread but not in the worker, so anything it
+ * contributes that runs there (an adapter, most commonly) fails to resolve.
+ */
+export type PluginInput = PluginConstructor | PluginRecord;
+/**
+ * Turn caller-supplied plugins into `PluginManager` load records, keeping each
+ * runtime plugin's `definition` when it has one.
+ *
+ * That definition is the whole point: `PluginManager.addPlugin` only records
+ * `runtimePluginDefinitions` for records that carry one, and `RpcManager` ships
+ * that list to the RPC worker as its boot config so the worker can fetch the
+ * same plugin. Dropping it leaves the plugin main-thread-only, and the failure
+ * surfaces far away — as an unknown adapter/track type inside the worker.
+ *
+ * Shared by every embedded product rather than restated, because getting it
+ * wrong is invisible until someone combines a runtime plugin with a worker.
+ */
+export declare function toPluginLoadRecord(p: PluginInput): {
+    plugin: import("@jbrowse/core/Plugin").default;
+    definition?: undefined;
+} | {
+    plugin: import("@jbrowse/core/Plugin").default;
+    definition: import("@jbrowse/core/pluginDefinitions").PluginDefinition;
+};

package/esm/pluginInput.js

@@ -0,0 +1,19 @@
+/**
+ * Turn caller-supplied plugins into `PluginManager` load records, keeping each
+ * runtime plugin's `definition` when it has one.
+ *
+ * That definition is the whole point: `PluginManager.addPlugin` only records
+ * `runtimePluginDefinitions` for records that carry one, and `RpcManager` ships
+ * that list to the RPC worker as its boot config so the worker can fetch the
+ * same plugin. Dropping it leaves the plugin main-thread-only, and the failure
+ * surfaces far away — as an unknown adapter/track type inside the worker.
+ *
+ * Shared by every embedded product rather than restated, because getting it
+ * wrong is invisible until someone combines a runtime plugin with a worker.
+ */
+export function toPluginLoadRecord(p) {
+    // a plugin class is a function; a loadPlugins record is a plain object
+    return typeof p === 'function'
+        ? { plugin: new p() }
+        : { plugin: new p.plugin(), definition: p.definition };
+}