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

package/esm/Session/temporaryAssemblyTracks.js

@@ -0,0 +1,38 @@
+import { namesTemporaryAssembly } from '@jbrowse/core/util';
+/**
+ * Dev-only check that a track config being written into a session or config list
+ * is one something can still draw tomorrow. No-op in production.
+ *
+ * A config naming nothing but a temporary assembly is dead the moment its view
+ * closes, and no list outside that view has anyone to sweep it — which is the
+ * whole of ADR-084. A track only one view can draw carries its config on the
+ * track instead (`showTrackGeneric`'s `inlineConf`), so reaching a session list
+ * with one is the mistake, not the cleanup afterwards.
+ *
+ * **This reports a write, not a click.** The two flows a user can drive into it
+ * are answered before they get here — the track menu greys its copy actions, and
+ * `addTrackFromWidget` opens the track inline instead of adding it — so what
+ * survives to report is a caller that had `inlineConf` available and did not
+ * take it. That is the reading the message is written for.
+ *
+ * `console.error` and never `throw`, matching `assertDisplayContract`: these
+ * writes happen inside launchers and menu handlers where an exception is caught
+ * and reported as a failed track, which would hide the violation. The jest gate
+ * (`config/jest/contractGate.js`) is what listens.
+ */
+export function assertTrackConfOutlivesItsAssemblies(session, trackConf, destination) {
+    if (process.env.NODE_ENV === 'production') {
+        return;
+    }
+    if (!namesTemporaryAssembly(session, trackConf)) {
+        return;
+    }
+    const { trackId } = trackConf;
+    console.error(`[jbrowse session contract] ${destination} was given "${trackId}", ` +
+        `which names a temporary assembly — one a comparative view synthesized ` +
+        `and gives back when it closes, so this config outlives the only ` +
+        `assembly that could draw it and nothing sweeps the list it landed in. ` +
+        `A track only one view can draw passes its config to that view's ` +
+        `showTrack as \`inlineConf\` instead, which puts it on the track and ` +
+        `takes it out with the view. See ADR-084.`);
+}

package/esm/assertExtends.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Compile-time assertion that `Actual` is assignable to `Expected`, evaluating
+ * to `Actual`. There is no runtime component — referencing the alias forces the
+ * check, and a mismatch surfaces as a type error at the reference site.
+ *
+ * The main use is binding a hand-written "shadow" contract to the real type it
+ * shadows so the two can't silently drift. MST's `getParent<T>(self)` is an
+ * unchecked assertion (`T` has no structural link to the actual parent), so a
+ * child model that reaches into its parent via a local shape can keep compiling
+ * after the real parent renames or drops a member — until it throws at runtime.
+ * Pinning `AssertExtends<RealRootModel, ShadowParent>` turns that into a build
+ * error:
+ *
+ * ```ts
+ * interface SessionModelParent {
+ *   version: string
+ *   assemblyManager: AssemblyManager
+ * }
+ * // real root must satisfy the shadow the session reaches for
+ * export type _Check = AssertExtends<ViewModel, SessionModelParent>
+ * ```
+ */
+export type AssertExtends<Actual extends Expected, Expected> = Actual;
+/**
+ * Compile-time assertion that a type has not degraded to `any`. Pass it the
+ * `IsAny` of the type you are pinning; a failure reads `Type 'true' does not
+ * satisfy the constraint 'false'`.
+ *
+ * ```ts
+ * export type _ViewIsTyped = AssertNotAny<IsAny<ViewModel['session']['view']>>
+ * ```
+ *
+ * This is the one check the others cannot make for you. `any` satisfies every
+ * `AssertExtends`, implements every `SessionWith*` contract, and passes tsc,
+ * jest and lint — so a surface that silently becomes `any` switches off type
+ * checking everywhere downstream while every gate stays green.
+ *
+ * Composed MST models are where it happens here. `types.compose`'s overloads
+ * are declared over `IModelType<P, O, FC, FS>`, so a model passed in as a naked
+ * type parameter has nothing to infer those four from and the composed result
+ * degrades.
+ *
+ * Naming `any` twice at the call site is not an oversight. It takes the computed
+ * boolean because the constraint has to be checked where it is concrete, and all
+ * three single-argument spellings were tried and fail:
+ *
+ * - `AssertNotAny<T> = AssertExtends<IsAny<T>, false>` — unbound, `IsAny<T>` is
+ *   `boolean`, so the alias fails at its own declaration.
+ * - `AssertNotAny<T, _ extends false = IsAny<T>> = T` — the tempting one. Same
+ *   declaration-site failure, and it does not even catch: instantiated at `any`
+ *   it reports nothing.
+ * - `AssertNotAny<T extends IsAny<T> extends true ? never : unknown>` — TS2313,
+ *   circular constraint.
+ */
+export type AssertNotAny<IsItAny extends false> = IsItAny;

package/esm/assertExtends.js

@@ -0,0 +1 @@
+export {};

package/esm/controllerTracks.d.ts

@@ -0,0 +1,56 @@
+import type { BlobLocation } from '@jbrowse/core/util';
+import type { LooseTrackInput } from '@jbrowse/core/util/tracks';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export type TrackConf = Record<string, unknown>;
+/**
+ * What a controller accepts per track: a full config, a bare data-file URL, or
+ * `{ uri, index?, ...extra }`. The loose forms expand through core's
+ * `guessTrackConf`, the same inference the "Add track" flow runs.
+ */
+export type TrackInput = string | TrackConf;
+interface ControllerView {
+    tracks: {
+        configuration: {
+            trackId: string;
+        };
+    }[];
+    showTrack: (trackId: string) => unknown;
+    hideTrack: (trackId: string) => unknown;
+}
+export interface ControllerSession extends IStateTreeNode {
+    view: ControllerView;
+    getTrackById: (trackId: string) => unknown;
+    addSessionTrackConf: (conf: TrackConf) => unknown;
+}
+export declare function isLooseTrack(track: TrackInput): track is string | LooseTrackInput;
+/**
+ * Stamp the view's assembly onto a full-config track that omits
+ * `assemblyNames`. A single-view embed has exactly one assembly, so it is
+ * unambiguous — and doing it here frees every host (R htmlwidgets, anywidget,
+ * vanilla JS) from computing the name itself, which it often cannot: the
+ * assembly may have arrived as a hub name only the view resolved. Loose tracks
+ * take the same name through `guessTrackConf`'s `assemblyName` argument.
+ */
+export declare function withAssemblyName(track: TrackConf, assemblyName?: string): TrackConf;
+/**
+ * Expand every loose entry into a full track config; stamp the assembly name
+ * onto the ones already written out. `node` is any node of the live tree — the
+ * pluginManager whose format plugins drive the guess comes off its env.
+ */
+export declare function resolveTracks(tracks: TrackInput[], node: IStateTreeNode, assemblyName?: string, localFiles?: Record<string, BlobLocation>): TrackConf[];
+/**
+ * Register each track config only if the session cannot already resolve it, then
+ * show it. `getTrackById` resolves catalog + connection + session tracks, so a
+ * config already seeded into the catalog is left alone rather than shadowed by a
+ * duplicate in `sessionTracks` — which is also what `addSessionTrackConf`
+ * dedupes on, so this states the intent rather than supplying it.
+ *
+ * Session-scoped: these are the host's declared tracks for one embed, not a
+ * catalog an admin curates.
+ */
+export declare function openTracks(session: ControllerSession, tracks: TrackConf[]): void;
+/** Open every wanted track and close any others the view currently shows. */
+export declare function reconcileTracks(session: ControllerSession, tracks: TrackConf[]): void;
+/** Merge a hub's own search adapters with the ones the caller supplied. */
+export declare function mergeSearchAdapters<T>(a: readonly T[] | undefined, b: readonly T[] | undefined): T[] | undefined;
+export {};

package/esm/controllerTracks.js

@@ -0,0 +1,77 @@
+import { getEnv } from '@jbrowse/core/util';
+import { guessTrackConf } from '@jbrowse/core/util/tracks';
+import { resolveLocalFileUris } from './localFiles.js';
+export function isLooseTrack(track) {
+    return typeof track === 'string' || (!('adapter' in track) && 'uri' in track);
+}
+/**
+ * Stamp the view's assembly onto a full-config track that omits
+ * `assemblyNames`. A single-view embed has exactly one assembly, so it is
+ * unambiguous — and doing it here frees every host (R htmlwidgets, anywidget,
+ * vanilla JS) from computing the name itself, which it often cannot: the
+ * assembly may have arrived as a hub name only the view resolved. Loose tracks
+ * take the same name through `guessTrackConf`'s `assemblyName` argument.
+ */
+export function withAssemblyName(track, assemblyName) {
+    return assemblyName !== undefined && !('assemblyNames' in track)
+        ? { ...track, assemblyNames: [assemblyName] }
+        : track;
+}
+/**
+ * Expand every loose entry into a full track config; stamp the assembly name
+ * onto the ones already written out. `node` is any node of the live tree — the
+ * pluginManager whose format plugins drive the guess comes off its env.
+ */
+export function resolveTracks(tracks, node, assemblyName, localFiles) {
+    const { pluginManager } = getEnv(node);
+    return tracks.map(track => {
+        const conf = isLooseTrack(track)
+            ? guessTrackConf(track, pluginManager, assemblyName)
+            : // full configs are stamped here too, not just in the build() catalog
+                // seed: a config that first appears through addTrack never passes
+                // through that seed, and would otherwise reach addSessionTrackConf with no
+                // assemblyNames and silently fail to display
+                withAssemblyName(track, assemblyName);
+        // after the guess, so the adapter has already derived its index sibling
+        // from the uri string and both get swapped for blobs together
+        return localFiles ? resolveLocalFileUris(conf, localFiles) : conf;
+    });
+}
+/**
+ * Register each track config only if the session cannot already resolve it, then
+ * show it. `getTrackById` resolves catalog + connection + session tracks, so a
+ * config already seeded into the catalog is left alone rather than shadowed by a
+ * duplicate in `sessionTracks` — which is also what `addSessionTrackConf`
+ * dedupes on, so this states the intent rather than supplying it.
+ *
+ * Session-scoped: these are the host's declared tracks for one embed, not a
+ * catalog an admin curates.
+ */
+export function openTracks(session, tracks) {
+    for (const conf of tracks) {
+        const trackId = conf.trackId;
+        if (!session.getTrackById(trackId)) {
+            session.addSessionTrackConf(conf);
+        }
+        session.view.showTrack(trackId);
+    }
+}
+/** Open every wanted track and close any others the view currently shows. */
+export function reconcileTracks(session, tracks) {
+    const { view } = session;
+    const wanted = new Set(tracks.map(t => t.trackId));
+    openTracks(session, tracks);
+    // materialize the ids first: hideTrack splices view.tracks, so iterating it
+    // live would skip entries
+    const unwanted = view.tracks
+        .map(track => track.configuration.trackId)
+        .filter(trackId => !wanted.has(trackId));
+    for (const trackId of unwanted) {
+        view.hideTrack(trackId);
+    }
+}
+/** Merge a hub's own search adapters with the ones the caller supplied. */
+export function mergeSearchAdapters(a, b) {
+    const merged = [...(a ?? []), ...(b ?? [])];
+    return merged.length ? merged : undefined;
+}

package/esm/destroyViewState.d.ts

@@ -0,0 +1,21 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface EmbeddedRoot extends IStateTreeNode {
+    session?: unknown;
+    rpcManager: {
+        destroy: () => void;
+    };
+}
+/**
+ * Tear down an engine built by an embedded product's `createViewState`:
+ * terminate its RPC worker threads and destroy the MST tree so its
+ * `addDisposer`'d autoruns stop.
+ *
+ * Unmounting the React tree is not enough — the engine is not owned by React.
+ * A host that builds and discards engines (a Jupyter cell re-run, an SPA route
+ * change, a controller's `destroy()`) otherwise orphans a whole worker pool and
+ * a live autorun set per discarded engine. A component that owns one engine for
+ * the lifetime of the page never needs this.
+ *
+ * Idempotent: destroying an already-destroyed engine is a no-op.
+ */
+export declare function destroyViewState(viewState: EmbeddedRoot): void;

package/esm/destroyViewState.js

@@ -0,0 +1,29 @@
+import { destroy, isAlive } from '@jbrowse/mobx-state-tree';
+/**
+ * Tear down an engine built by an embedded product's `createViewState`:
+ * terminate its RPC worker threads and destroy the MST tree so its
+ * `addDisposer`'d autoruns stop.
+ *
+ * Unmounting the React tree is not enough — the engine is not owned by React.
+ * A host that builds and discards engines (a Jupyter cell re-run, an SPA route
+ * change, a controller's `destroy()`) otherwise orphans a whole worker pool and
+ * a live autorun set per discarded engine. A component that owns one engine for
+ * the lifetime of the page never needs this.
+ *
+ * Idempotent: destroying an already-destroyed engine is a no-op.
+ */
+export function destroyViewState(viewState) {
+    if (isAlive(viewState)) {
+        // Materialize the session before killing the tree. MST snapshots each dying
+        // node on the way down, and snapshotting a node that was never observed
+        // instantiates it right then — running its afterAttach during death
+        // finalization, where creating a further observable (the config it reads)
+        // throws "the creation of the observable instance must be done on the
+        // initializing phase". Reachable whenever an engine is destroyed before it
+        // ever rendered, which is exactly what React StrictMode does to the
+        // build-in-a-ref-callback pattern: mount, clean up, mount again.
+        void viewState.session;
+        viewState.rpcManager.destroy();
+        destroy(viewState);
+    }
+}

package/esm/index.d.ts

@@ -1,4 +1,31 @@
-export * from './RootModel/index.ts';
-export * from './Session/index.ts';
-export * from './ui/index.ts';
-export * from './rpcWorker.ts';
+export type { AssertExtends, AssertNotAny } from './assertExtends.ts';
+export { asRoot, asSession } from './siblingCast.ts';
+export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.ts';
+export { BaseRootModelFactory, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, HierarchicalConfigSchemaFactory, InternetAccountsRootModelMixin, PreferencesConfigSchemaFactory, createConfigModel, exportSessionMenuItem, importSessionMenuItem, isRootModel, newSessionMenuItem, openConnectionMenuItem, openTrackMenuItem, pluginStoreMenuItem, preferencesMenuItem, redoMenuItem, undoMenuItem, workspacesMenuItem, } from './RootModel/index.ts';
+export type { BaseRootModel, BaseRootModelType, RootConfigurationSnapshot, RootModelWithInternetAccounts, RootModelWithInternetAccountsType, } from './RootModel/index.ts';
+export { BaseSessionModel, ConnectionManagementSessionMixin, DrawerWidgetSessionMixin, MultipleViewsSessionMixin, PreferencesSessionMixin, ReferenceManagementSessionMixin, SessionTracksManagerSessionMixin, ThemeManagerSessionMixin, TrackMenuItemsSessionMixin, TrackMenuSessionMixin, TracksManagerSessionMixin, aboutTrackMenuItem, bakePromotedDefaultsIntoSnapshot, bakeSessionCascades, getShareableSessionSnapshot, copyTrackSnapshot, finalizeSession, isBaseSession, isSession, isSessionWithConnections, isSessionWithDrawerWidgets, isSessionWithMultipleViews, isSessionWithReferenceManagement, isSessionWithThemes, isSessionWithTracks, pluginExtraTrackItems, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './Session/index.ts';
+export type { AssertSessionModel, BaseSession, BaseSessionType, ConnectionTrackConfigEntry, EditableTrackConfig, PlainTrackConfig, ReferringNode, SessionWithConnections, SessionWithConnectionsType, SessionWithDrawerWidgets, SessionWithDrawerWidgetsType, SessionWithMultipleViews, SessionWithMultipleViewsType, SessionWithReferenceManagement, SessionWithReferenceManagementType, SessionWithSessionTracks, SessionWithSessionTracksType, SessionWithThemes, SessionWithThemesType, SessionWithTracks, SessionWithTracksType, } from './Session/index.ts';
+export { AboutDialog, Drawer, DrawerControls, DrawerHeader, DrawerWidget, DrawerWidgetSelector, ModalWidget, ModalWidgetAppBar, PreferencesDialog, WidgetBody, WidgetHeading, drawerGridTemplateColumns, } from './ui/index.ts';
+export type { PreferencesDialogSession, PreferencesPanelDescriptor, } from './ui/index.ts';
+export { initializeWorker } from './rpcWorker.ts';
+export { toPluginLoadRecord } from './pluginInput.ts';
+export type { PluginInput } from './pluginInput.ts';
+export { loadRuntimePlugins } from './loadPlugins.ts';
+export type { LoadPluginsArgs } from './loadPlugins.ts';
+export { decodeSessionFromUrl, encodeSessionToUrl } from './sessionUrl.ts';
+export type { SessionSnapshot } from './sessionUrl.ts';
+export { mergeLocalFiles, normalizeAdapterSnapshots, registerLocalFiles, resolveLocalFileUris, } from './localFiles.ts';
+export type { LocalFileInput } from './localFiles.ts';
+export { isLooseTrack, mergeSearchAdapters, openTracks, reconcileTracks, resolveTracks, withAssemblyName, } from './controllerTracks.ts';
+export type { ControllerSession, TrackConf, TrackInput, } from './controllerTracks.ts';
+export { resolveAssemblies, resolveAssembly } from './resolveAssemblies.ts';
+export type { AssemblyInput, ResolvedAssemblies } from './resolveAssemblies.ts';
+export { destroyViewState } from './destroyViewState.ts';
+export { useCreateOnce, useDestroyOnUnmount } from './useEngineLifecycle.ts';
+export { getSessionSnapshot, observeSession } from './observeSession.ts';
+export type { SessionObservers, ViewLocation } from './observeSession.ts';
+export { MIGRATED_DISPLAY_INSTANCE_KEYS, migrateConfigSnapshot, migrateSessionSnapshot, } from './sessionMigrations/index.ts';
+export { DEFAULT_WEB_BASE_URL, analyzeWebPortability, buildWebExportUrl, filterSessionInPlace, planWebExport, } from './sessionUtils.ts';
+export type { AssemblySnapshot, DroppedSessionNode, HostedBaseConfig, NonPortableLocation, SelfContainedReason, TrackSnapshot, WebExportInput, WebExportPlan, WebPortabilityReport, } from './sessionUtils.ts';
+export { describeUnbuildableNodes, pruneUnbuildableNodes, } from './pruneUnbuildableNodes.ts';
+export type { HeldNode, UnbuildableNode } from './pruneUnbuildableNodes.ts';

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 './scheduleDetachedDestroy.js';
+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, bakePromotedDefaultsIntoSnapshot, bakeSessionCascades, getShareableSessionSnapshot, copyTrackSnapshot, finalizeSession, isBaseSession, isSession, isSessionWithConnections, isSessionWithDrawerWidgets, isSessionWithMultipleViews, isSessionWithReferenceManagement, isSessionWithThemes, isSessionWithTracks, pluginExtraTrackItems, trackActionItems, trackActionMenuItems, trackListMenuItems, } from './Session/index.js';
+export { AboutDialog, 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 { mergeLocalFiles, normalizeAdapterSnapshots, registerLocalFiles, resolveLocalFileUris, } from './localFiles.js';
+// the track half of an imperative controller: loose track specs -> configs, and
+// opening exactly the wanted set
+export { isLooseTrack, mergeSearchAdapters, openTracks, reconcileTracks, resolveTracks, withAssemblyName, } from './controllerTracks.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 { useCreateOnce, 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 { MIGRATED_DISPLAY_INSTANCE_KEYS, migrateConfigSnapshot, migrateSessionSnapshot, } 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,33 @@
+import type { LoadedPlugin } 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.
+ */
+export declare function loadRuntimePlugins(pluginDefinitions: PluginDefinition[], { dropVendored, jbrowseVersion, ...args }: LoadPluginsArgs & {
+    dropVendored: boolean;
+    jbrowseVersion: string;
+}): Promise<import("@jbrowse/core/PluginLoader").PluginRecord[]>;

package/esm/loadPlugins.js

@@ -0,0 +1,38 @@
+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.
+ */
+export async function loadRuntimePlugins(pluginDefinitions, { dropVendored, jbrowseVersion, ...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 pluginLoader = new PluginLoader(dropVendored ? dropVendoredPlugins(definitions) : definitions, args);
+    pluginLoader.installGlobalReExports(window);
+    // 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 pluginLoader.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;