@jbrowse/product-core 4.2.1 → 5.0.0-beta.1

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,56 @@
+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;
+    }[];
+}
+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:
+ * display settings a user is *inheriting* from a promoted display-type default
+ * live in their own browser, never in the session, so a raw snapshot replays
+ * differently 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,91 @@
+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:
+ * display settings a user is *inheriting* from a promoted display-type default
+ * live in their own browser, never in the session, so a raw snapshot replays
+ * differently 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/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 };
+}

package/esm/pruneUnbuildableNodes.d.ts

@@ -0,0 +1,109 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { PluggableElementTypeGroup } from '@jbrowse/core/PluginManager';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * A session snapshot that arrives from somewhere else — a share link, a desktop
+ * "export to web" URL, a session.json — can name a pluggable type this build has
+ * no plugin for. Every such collection is `types.map`/`types.array` over a bare
+ * `pluggableMstType` union with no dispatcher, so one entry the union cannot
+ * match throws `No type is applicable for the union` out of the `cast` in
+ * `setSession` — outside the try that `filterSessionInPlace` sits in. The whole
+ * session is lost, and jbrowse-web's fallback then advises the recipient to ask
+ * for a link made with the Share button, which is often exactly what they were
+ * sent.
+ *
+ * Two routes reach it and neither is exotic. A desktop export carries session
+ * state built from desktop's own core plugins — `blat` registers
+ * `UcscResultsWidget`, and every BLAT or in-silico PCR search leaves one in the
+ * drawer — which jbrowse-web does not have (see
+ * `scripts/check-core-plugin-sets.ts` for the exact relation between the
+ * products' lists). And a runtime plugin that fails to load is already
+ * tolerated: `notifyPluginLoadFailures` says the session opens without it, which
+ * was untrue for any session actually using its types.
+ *
+ * So the node comes out of the tree and the session opens. `dropped` is what the
+ * caller tells the user, which is the only part of this a person can act on.
+ *
+ * **The node is held, not discarded.** Taking it out of the tree is only half
+ * the job: jbrowse-web autosaves `getSnapshot(session)` on a 400ms debounce
+ * (`rootModel/persistence.ts`), so a recipient who merely opens a shared link
+ * without the plugin writes the reduced session back over the stored row — and
+ * reshares it that way. The removed nodes ride along under
+ * `heldForMissingPlugins` instead, and a build that has the plugin puts them
+ * back. Installing the plugin and reloading is then enough to get the session
+ * whole again, which is what makes a plugin removable at all.
+ *
+ * **The session schema is read off the session MST type, not written down here.**
+ * One walk descends `(type, snapshot)` in lockstep: at any `types.array` or
+ * `types.map` whose element type is one of the `pluggableMstType` unions it
+ * admits, holds or restores each entry, and everywhere else it recurses
+ * structurally. That is what reaches a synteny view's `levels[].tracks` and the
+ * session's `connectionInstances`, which a hand-written list of `views` /
+ * `tracks` / `displays` / `widgets` did not, and what will reach the next
+ * container someone adds without anyone editing this file.
+ *
+ * **A node is held only when all three tests fail**: its `type` names no
+ * registered element, no element declares it as an `alias`, and
+ * the real MST union refuses the snapshot. The last two are what keep a renamed
+ * type alive — an element can declare `aliases`, and a model's own
+ * `preProcessSnapshot` can rewrite the type literal
+ * (`LinearMultiSampleVariantDisplay` does both for the old
+ * `MultiLinearVariantDisplay`), neither of which the registry's names show. The
+ * first is what keeps this from quietly swallowing a *malformed* snapshot of a
+ * type this build does have: that still throws, exactly as before, because
+ * holding it would hide a real bug behind a message about plugins.
+ */
+type Group = PluggableElementTypeGroup;
+export interface UnbuildableNode {
+    group: Group;
+    type: string;
+    cascade?: true;
+}
+/**
+ * One node taken out of the tree, with the anchor that puts it back.
+ *
+ * The anchor is a parent **id** plus a position, never a path: paths are
+ * index-based and every edit the recipient makes shifts them, while a view id
+ * and a track id are stable for as long as the container exists. A held node
+ * whose parent the recipient has since deleted is not restorable and is not
+ * meant to be — the container going is the user saying so.
+ */
+export interface HeldNode {
+    group: Group;
+    /** map key, for a node that came out of a `types.map` */
+    key?: string;
+    /**
+     * id of the nearest enclosing node that has one — the view a track came out
+     * of, the track a display came out of, the synteny level a level's track came
+     * out of. Absent for a container on the session itself.
+     */
+    parent?: string;
+    /**
+     * position in the list it came out of, so a restore lands where it was.
+     * Absent for a map entry, which `key` places instead.
+     */
+    index?: number;
+    snapshot: Record<string, unknown>;
+}
+/**
+ * Takes the session-snapshot nodes whose pluggable type this plugin manager
+ * cannot build out of the tree and holds them under `heldForMissingPlugins`,
+ * and puts back the ones already held that it now can build — in one walk of
+ * the session type, so the two can never disagree about where a node lives.
+ * Returns the snapshot unchanged (by identity) when there is nothing to do
+ * either way, which is every session this build produced itself.
+ */
+export declare function pruneUnbuildableNodes(snapshot: Record<string, unknown>, pluginManager: PluginManager, sessionModelType: IAnyType): {
+    snapshot: Record<string, unknown>;
+    dropped: UnbuildableNode[];
+};
+/**
+ * The user-facing summary of one prune, or undefined when nothing was dropped.
+ * Names the missing types rather than counting nodes: the plugin a person has to
+ * install is the actionable half, and one missing display type can take several
+ * nodes with it. Says what a person can do about it, because the nodes are not
+ * gone — they ride along under `heldForMissingPlugins` and come back the moment
+ * a build that has the plugin opens the session.
+ */
+export declare function describeUnbuildableNodes(dropped: UnbuildableNode[]): string | undefined;
+export {};