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

package/esm/Session/Tracks.js

@@ -1,8 +1,10 @@
-import { types } from '@jbrowse/mobx-state-tree';
-import { computed } from 'mobx';
+import { expandLooseTrackConfig } from '@jbrowse/core/util/tracks';
+import { addDisposer, types } from '@jbrowse/mobx-state-tree';
+import { autorun, computed } from 'mobx';
 import { BaseSessionModel, isBaseSession } from './BaseSession.js';
 import { isSessionWithConnections } from './Connections.js';
 import { ReferenceManagementSessionMixin } from './ReferenceManagement.js';
+import { assertNotReaddedDifferently } from './readdedTrackConf.js';
 import { assertTrackConfOutlivesItsAssemblies } from './temporaryAssemblyTracks.js';
 /**
  * #stateModel TracksManagerSessionMixin
@@ -22,8 +24,11 @@ export function TracksManagerSessionMixin(pluginManager) {
         // One index trackId → config for all tracks, assembly sequences, and
         // connection tracks. Frozen jbrowse.tracks entries stay plain objects
         // here; hydration to MST nodes happens lazily in TrackConfigurationReference
-        // on first access. Cached, so the N per-id lookups below share one rebuild
-        // per change rather than each re-scanning.
+        // on first access. Held hot by the autorun in afterAttach, so a reader
+        // outside any reaction (ranking search hits: 33ms per search unheld on a
+        // 2000-track config, 0.07ms held) gets the cache too. Not `keepAlive`: that
+        // subscription never ends, and it reaches jbrowse.tracks on the root, so
+        // it pinned every superseded session for the tab's life.
         const tracksByIdRecord = computed(() => {
             const temporaryAssemblies = 'temporaryAssemblies' in self
                 ? self.temporaryAssemblies
@@ -49,7 +54,7 @@ export function TracksManagerSessionMixin(pluginManager) {
                     e.config,
                 ]),
             ]);
-        });
+        }, { name: 'tracksByIdRecord' });
         // Per-id computed cache backing getTrackById. Resolving one track's config
         // subscribes only to that id's computed, so editing track A leaves track
         // B's observers untouched: an unedited id's entry keeps its object identity
@@ -92,96 +97,114 @@ export function TracksManagerSessionMixin(pluginManager) {
         };
     })
         .actions(self => ({
-        /**
-         * #action
-         * Add a track config to *this session*.
-         *
-         * This mixin's session has no separate session-track store, so the
-         * destination is the jbrowse config — which in the products that compose
-         * it (desktop) is the single user's own file rather than something a
-         * server hands other visitors, so the two scopes are the same place.
-         * Defined here anyway so that every session has it: a feature standing a
-         * track up on the user's behalf can then call one action everywhere
-         * instead of asking which mixin it landed on.
-         * `SessionTracksManagerSessionMixin` overrides it with the real
-         * session-scoped store.
-         */
-        addSessionTrackConf(trackConf) {
-            assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
-            return self.jbrowse.addTrackConf(trackConf);
+        afterAttach() {
+            addDisposer(self, autorun(() => {
+                self.getTracksById();
+            }));
         },
-        /**
-         * #action
-         * Add a track config wherever *this user's* catalog edits belong — the
-         * "Add track" workflows, where an admin adding a track means to add it
-         * for the whole site. `SessionTracksManagerSessionMixin` overrides it to
-         * send a non-admin's to the session instead; here there is only the one
-         * destination.
-         *
-         * Anything that is not an Add-track workflow wants
-         * `addSessionTrackConf`: a track a feature stands up on the user's behalf
-         * — a search result, a computed consensus, a reconstruction's labels — is
-         * not a catalog entry, and publishing one writes it into the config.json
-         * every visitor is served, once per click.
-         */
-        publishTrackConf(trackConf) {
-            assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
-            return self.jbrowse.addTrackConf(trackConf);
-        },
-        /**
-         * #action
-         * Deprecated alias of `addSessionTrackConf`. Call that, or
-         * `publishTrackConf`, which say which destination they mean.
-         *
-         * @deprecated
-         *
-         * Kept because a prebuilt plugin bundle reaches this by name at runtime
-         * and cannot be recompiled — `jbrowse-plugin-protein3d` calls it, and a
-         * member lookup that stops resolving throws nothing at all
-         * (`pluginFacingSessionApi.test.ts` is the guard). It now means the
-         * session, which is the destination every such caller wanted: a track a
-         * plugin stands up for one user is not a catalog entry. Nothing in tree
-         * may call it — `no-restricted-syntax` says so.
-         *
-         * Spelled out rather than delegating through `this`, for the reason
-         * `SessionTracks.addToSession` is a plain closure: an action whose return
-         * type is inferred from a sibling's makes the pair circular.
-         */
-        addTrackConf(trackConf) {
+    }))
+        .actions(self => {
+        function addToSession(trackConf) {
             assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
-            return self.jbrowse.addTrackConf(trackConf);
-        },
-        /**
-         * #action
-         * Persist edited track config back to the in-memory jbrowse config. The
-         * session-tracks mixin overrides this so a non-admin's edits become a
-         * shareable session-track override instead.
-         */
-        updateTrackConfiguration(trackConf) {
-            // an opened connection track lives in connectionTrackConfigs, not
-            // jbrowse.tracks; persist its edit there (jbrowse.updateTrackConf would
-            // no-op, since the track isn't in the config). Desktop uses this base
-            // mixin, so without this branch a connection-track edit is lost on
-            // reload.
-            if (isSessionWithConnections(self) &&
-                trackConf.trackId in self.connectionTrackConfigs) {
-                self.updateConnectionTrackConfig(trackConf);
-            }
-            else {
-                self.jbrowse.updateTrackConf(trackConf);
-            }
-        },
-        /**
-         * #action
-         */
-        deleteTrackConf(trackConf) {
-            const { trackId } = trackConf;
-            self.dereferenceTrack(trackId, self.getReferring(trackId));
-            if (self.adminMode) {
-                return self.jbrowse.deleteTrackConf(trackConf);
+            const expanded = expandLooseTrackConfig(trackConf, pluginManager);
+            const { trackId, type } = expanded;
+            const existing = self.getTrackById(trackId);
+            if (existing) {
+                assertNotReaddedDifferently(pluginManager, existing, {
+                    ...expanded,
+                    trackId,
+                    type,
+                });
+                return existing;
             }
-        },
-    }));
+            return self.jbrowse.addTrackConf(trackConf);
+        }
+        return {
+            /**
+             * #action
+             * Add a track config to *this session*.
+             *
+             * This mixin's session has no separate session-track store, so the
+             * destination is the jbrowse config — which in the products that compose
+             * it (desktop) is the single user's own file rather than something a
+             * server hands other visitors, so the two scopes are the same place.
+             * Defined here anyway so that every session has it: a feature standing a
+             * track up on the user's behalf can then call one action everywhere
+             * instead of asking which mixin it landed on.
+             * `SessionTracksManagerSessionMixin` overrides it with the real
+             * session-scoped store.
+             */
+            addSessionTrackConf(trackConf) {
+                return addToSession(trackConf);
+            },
+            /**
+             * #action
+             * Add a track config wherever *this user's* catalog edits belong — the
+             * "Add track" workflows, where an admin adding a track means to add it
+             * for the whole site. `SessionTracksManagerSessionMixin` overrides it to
+             * send a non-admin's to the session instead; here there is only the one
+             * destination.
+             *
+             * Anything that is not an Add-track workflow wants
+             * `addSessionTrackConf`: a track a feature stands up on the user's behalf
+             * — a search result, a computed consensus, a reconstruction's labels — is
+             * not a catalog entry, and publishing one writes it into the config.json
+             * every visitor is served, once per click.
+             */
+            publishTrackConf(trackConf) {
+                assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
+                return self.jbrowse.addTrackConf(trackConf);
+            },
+            /**
+             * #action
+             * Deprecated alias of `addSessionTrackConf`. Call that, or
+             * `publishTrackConf`, which say which destination they mean.
+             *
+             * @deprecated
+             *
+             * Kept because a prebuilt plugin bundle reaches this by name at runtime
+             * and cannot be recompiled — `jbrowse-plugin-protein3d` calls it, and a
+             * member lookup that stops resolving throws nothing at all
+             * (`pluginFacingSessionApi.test.ts` is the guard). It now means the
+             * session, which is the destination every such caller wanted: a track a
+             * plugin stands up for one user is not a catalog entry. Nothing in tree
+             * may call it — `no-restricted-syntax` says so.
+             */
+            addTrackConf(trackConf) {
+                return addToSession(trackConf);
+            },
+            /**
+             * #action
+             * Persist edited track config back to the in-memory jbrowse config. The
+             * session-tracks mixin overrides this so a non-admin's edits become a
+             * shareable session-track override instead.
+             */
+            updateTrackConfiguration(trackConf) {
+                // an opened connection track lives in connectionTrackConfigs, not
+                // jbrowse.tracks; persist its edit there (jbrowse.updateTrackConf would
+                // no-op, since the track isn't in the config). Desktop uses this base
+                // mixin, so without this branch a connection-track edit is lost on
+                // reload.
+                if (isSessionWithConnections(self) &&
+                    trackConf.trackId in self.connectionTrackConfigs) {
+                    self.updateConnectionTrackConfig(trackConf);
+                }
+                else {
+                    self.jbrowse.updateTrackConf(trackConf);
+                }
+            },
+            /**
+             * #action
+             */
+            deleteTrackConf(trackConf) {
+                const { trackId } = trackConf;
+                self.dereferenceTrack(trackId, self.getReferring(trackId));
+                if (self.adminMode) {
+                    return self.jbrowse.deleteTrackConf(trackConf);
+                }
+            },
+        };
+    });
 }
 /** Type guard for SessionWithTracks */
 export function isSessionWithTracks(thing) {

package/esm/Session/developerMode.d.ts

@@ -0,0 +1,7 @@
+import type { NotificationSink } from '@jbrowse/core/util/types';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+interface DeveloperModeHost extends IStateTreeNode, Pick<NotificationSink, 'notify'> {
+    getPreference: (key: string) => unknown;
+}
+export declare function applyDeveloperMode(self: DeveloperModeHost): void;
+export {};

package/esm/Session/developerMode.js

@@ -0,0 +1,43 @@
+import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
+import { enableContractReports, setContractReportSink, } from '@jbrowse/render-core/contractReports';
+/**
+ * What a plugin author sees when their display breaks an ordering contract in
+ * somebody else's production build.
+ *
+ * The checks themselves have always run and always reported; what they had no
+ * way to reach was this population, which is the one least able to diagnose the
+ * symptom and the one nobody can write a test for. A `console.error` surviving
+ * the build would not have fixed that — nobody has a console open on a page
+ * they did not write — so the report has to land in the app, in the session the
+ * broken display is in, and it has to explain itself: the reader did not turn
+ * this on deliberately in the common case (a plugin served from their own
+ * machine did), and a message they cannot place reads as the app being broken.
+ *
+ * `warning` rather than `error`: an error snackbar in this app means the user's
+ * data or their request failed, and every word here is about code they are
+ * writing. Warnings persist until dismissed, which is what a message with a fix
+ * in it wants, and identical ones collapse in the snackbar — so a violation
+ * repeating across ten tracks of one broken type is still one notice.
+ */
+function notification({ family, message, armedBy }) {
+    return (`JBrowse ${family} contract broken — a bug in code, not in your data or ` +
+        `configuration.\n\n${message}\n\n` +
+        `Shown because ${armedBy}. These notices can be turned on anywhere with ` +
+        `localStorage.jbrowseDeveloperMode = 1, or site-wide with ` +
+        `configuration.preferences.developerMode.`);
+}
+export function applyDeveloperMode(self) {
+    if (self.getPreference('developerMode') === true) {
+        enableContractReports('this site sets configuration.preferences.developerMode');
+    }
+    addDisposer(self, setContractReportSink(report => {
+        // out of whatever reaction, fetch handler or upload found the violation:
+        // `notify` writes observables, and a diagnostic that throws where it is
+        // read is worse than the bug it describes
+        queueMicrotask(() => {
+            if (isAlive(self)) {
+                self.notify(notification(report), 'warning');
+            }
+        });
+    }));
+}

package/esm/Session/readdedTrackConf.d.ts

@@ -0,0 +1,8 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
+type TrackConfInput = {
+    trackId: string;
+    type: string;
+} & Record<string, unknown>;
+export declare function assertNotReaddedDifferently(pluginManager: PluginManager, existing: AnyConfigurationModel | TrackConfInput, trackConf: TrackConfInput): void;
+export {};

package/esm/Session/readdedTrackConf.js

@@ -0,0 +1,25 @@
+import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { compareStructural } from 'mobx';
+// What a config means once its defaults are resolved: a live config node
+// answers with its snapshot, and a plain object (desktop's `jbrowse.tracks` is
+// frozen, so its entries are the input as written) is hydrated through the
+// same schema first. Two inputs that would build the same node compare equal.
+function resolvedTrackConf(pluginManager, conf) {
+    return isStateTreeNode(conf)
+        ? getSnapshot(conf)
+        : getSnapshot(pluginManager
+            .pluggableConfigSchemaType('track')
+            .create(conf, { pluginManager }));
+}
+// Re-adding a trackId the session already holds returns the existing config,
+// which is what keeps a content-hashed trackId idempotent. It is also the trap
+// a recomputed track walks into: the new features arrive under the old id, the
+// old config is handed back, nothing is said, and the track keeps showing the
+// first values it saw. Same id with different content is therefore refused,
+// naming the two-step that works.
+export function assertNotReaddedDifferently(pluginManager, existing, trackConf) {
+    const same = compareStructural(resolvedTrackConf(pluginManager, existing), resolvedTrackConf(pluginManager, trackConf));
+    if (!same) {
+        throw new Error(`Track "${trackConf.trackId}" is already in this session with a different configuration, and adding it again would keep the old one. Delete it first (session.deleteTrackConf(session.getTrackById("${trackConf.trackId}"))), then add — and give a recomputed FromConfigAdapter a new adapterId, since the adapter cache is keyed on it.`);
+    }
+}

package/esm/Session/temporaryAssemblyTracks.d.ts

@@ -1,7 +1,7 @@
 import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
 /**
- * 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.
+ * Checks that a track config being written into a session or config list is one
+ * something can still draw tomorrow.
  *
  * 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
@@ -18,6 +18,7 @@ import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
  * `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.
+ * (`config/jest/contractGate.js`) is what listens in tree; out of tree
+ * `contractReports` does, once a host arms it.
  */
 export declare function assertTrackConfOutlivesItsAssemblies(session: unknown, trackConf: AnyConfigurationModel | Record<string, unknown>, destination: string): void;

package/esm/Session/temporaryAssemblyTracks.js

@@ -1,7 +1,8 @@
 import { namesTemporaryAssembly } from '@jbrowse/core/util';
+import { reportContractViolation } from '@jbrowse/render-core/contractReports';
 /**
- * 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.
+ * Checks that a track config being written into a session or config list is one
+ * something can still draw tomorrow.
  *
  * 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
@@ -18,17 +19,15 @@ import { namesTemporaryAssembly } from '@jbrowse/core/util';
  * `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.
+ * (`config/jest/contractGate.js`) is what listens in tree; out of tree
+ * `contractReports` does, once a host arms it.
  */
 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}", ` +
+    reportContractViolation('session', `${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. ` +

package/esm/controllerTracks.d.ts

@@ -14,7 +14,7 @@ interface ControllerView {
             trackId: string;
         };
     }[];
-    showTrack: (trackId: string) => unknown;
+    launchTrack: (trackId: string) => Promise<unknown>;
     hideTrack: (trackId: string) => unknown;
 }
 export interface ControllerSession extends IStateTreeNode {
@@ -48,9 +48,9 @@ export declare function resolveTracks(tracks: TrackInput[], node: IStateTreeNode
  * 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;
+export declare function openTracks(session: ControllerSession, tracks: TrackConf[]): Promise<void>;
 /** Open every wanted track and close any others the view currently shows. */
-export declare function reconcileTracks(session: ControllerSession, tracks: TrackConf[]): void;
+export declare function reconcileTracks(session: ControllerSession, tracks: TrackConf[]): Promise<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

@@ -1,5 +1,6 @@
 import { getEnv } from '@jbrowse/core/util';
 import { guessTrackConf } from '@jbrowse/core/util/tracks';
+import { isAlive } from '@jbrowse/mobx-state-tree';
 import { resolveLocalFileUris } from './localFiles.js';
 export function isLooseTrack(track) {
     return typeof track === 'string' || (!('adapter' in track) && 'uri' in track);
@@ -47,20 +48,32 @@ export function resolveTracks(tracks, node, assemblyName, localFiles) {
  * Session-scoped: these are the host's declared tracks for one embed, not a
  * catalog an admin curates.
  */
-export function openTracks(session, tracks) {
+export async function openTracks(session, tracks) {
+    // sequential, not Promise.all: each display's state model may be a separate
+    // dynamic import, and racing them would land the tracks on the view in
+    // whatever order the chunks happen to resolve rather than the caller's
     for (const conf of tracks) {
+        // the engine can be destroyed while a chunk is in flight (an unmounted
+        // embed); reading the dead tree from this floating promise would throw
+        // uncatchably
+        if (!isAlive(session.view)) {
+            return;
+        }
         const trackId = conf.trackId;
         if (!session.getTrackById(trackId)) {
             session.addSessionTrackConf(conf);
         }
-        session.view.showTrack(trackId);
+        await session.view.launchTrack(trackId);
     }
 }
 /** Open every wanted track and close any others the view currently shows. */
-export function reconcileTracks(session, tracks) {
+export async function reconcileTracks(session, tracks) {
     const { view } = session;
     const wanted = new Set(tracks.map(t => t.trackId));
-    openTracks(session, tracks);
+    await openTracks(session, tracks);
+    if (!isAlive(view)) {
+        return;
+    }
     // materialize the ids first: hideTrack splices view.tracks, so iterating it
     // live would skip entries
     const unwanted = view.tracks

package/esm/index.d.ts

@@ -1,6 +1,6 @@
 export type { AssertExtends, AssertNotAny } from './assertExtends.ts';
 export { asRoot, asSession } from './siblingCast.ts';
-export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.ts';
+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.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';
@@ -21,7 +21,7 @@ export type { ControllerSession, TrackConf, TrackInput, } from './controllerTrac
 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 { useAsyncEngineLifecycle, useCreateOnce, useCreateOnceAsync, 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';

package/esm/index.js

@@ -1,5 +1,5 @@
 export { asRoot, asSession } from './siblingCast.js';
-export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.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, 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';
@@ -22,7 +22,7 @@ export { resolveAssemblies, resolveAssembly } from './resolveAssemblies.js';
 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';
+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';

package/esm/loadPlugins.d.ts

@@ -30,4 +30,4 @@ export interface LoadPluginsArgs {
 export declare function loadRuntimePlugins(pluginDefinitions: PluginDefinition[], { dropVendored, jbrowseVersion, ...args }: LoadPluginsArgs & {
     dropVendored: boolean;
     jbrowseVersion: string;
-}): Promise<import("@jbrowse/core/PluginLoader").PluginRecord[]>;
+}): Promise<never[] | import("@jbrowse/core/PluginLoader").PluginRecord[]>;

package/esm/loadPlugins.js

@@ -28,11 +28,14 @@ export async function loadRuntimePlugins(pluginDefinitions, { dropVendored, jbro
     if (failures[0]) {
         throw failures[0].error;
     }
-    const pluginLoader = new PluginLoader(dropVendored ? dropVendoredPlugins(definitions) : definitions, args);
-    pluginLoader.installGlobalReExports(window);
+    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 pluginLoader.load(base ?? window.location.href);
+    return toLoad.length
+        ? new PluginLoader(toLoad, args)
+            .installGlobalReExports(window)
+            .load(base ?? window.location.href)
+        : [];
 }

package/esm/pruneUnbuildableNodes.js

@@ -12,8 +12,11 @@ const HELD_NODES_KEY = 'heldForMissingPlugins';
 // widen the plugin ABI for nothing.
 function buildableElements(pluginManager, group) {
     return pluginManager.getElementTypesInGroup(group).filter(t => {
-        const { stateModel } = t;
-        return isType(stateModel) && isModelType(stateModel);
+        const element = t;
+        if (element.isStateModelLoaded === false) {
+            return false;
+        }
+        return isType(element.stateModel) && isModelType(element.stateModel);
     });
 }
 // optional/stripDefault/late/snapshotProcessor all report the type they wrap,

package/esm/rpcWorker.js

@@ -3,7 +3,6 @@ import PluginManager from '@jbrowse/core/PluginManager';
 import { setNumberGrouping, throttleStatusEmits } from '@jbrowse/core/util';
 import { RpcServer, serializeError } from '@jbrowse/core/util/librpc';
 import { setStackTraceLimit } from '@jbrowse/core/util/setStackTraceLimit';
-import { enableStaticRendering } from 'mobx-react';
 // waits for a message from the main thread containing our configuration, which
 // must be sent on boot
 function receiveConfiguration() {
@@ -25,13 +24,16 @@ async function getPluginManager(corePlugins, opts) {
     // 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);
-    const pluginLoader = new PluginLoader(config.plugins, opts).installGlobalReExports(self);
     // 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 = await pluginLoader.load(config.windowHref);
+    const runtimePlugins = config.plugins.length
+        ? await new PluginLoader(config.plugins, opts)
+            .installGlobalReExports(self)
+            .load(config.windowHref)
+        : [];
     return new PluginManager([
         ...corePlugins.map(P => ({ plugin: new P() })),
         ...runtimePlugins.map(({ plugin: P, definition }) => ({
@@ -92,7 +94,6 @@ export async function initializeWorker(corePlugins, opts) {
     // copies meant a fifth product would silently ship without it — the plugins
     // that could trip it are not loaded until getPluginManager below, so this is
     // still ahead of anything that observes.
-    enableStaticRendering(true);
     // Add global error handler to catch uncaught errors in the worker
     self.addEventListener('error', event => {
         console.error('[Worker uncaught error]', event.error || event.message);

package/esm/ui/AboutDialogContents.js

@@ -9,6 +9,7 @@ import { makeStyles } from '@jbrowse/core/util/tss-react';
 import { isStateTreeNode } from '@jbrowse/mobx-state-tree';
 import { observer } from 'mobx-react';
 import AssemblyInfoPanel from './AssemblyInfoPanel.js';
+import DescriptionPanel from './DescriptionPanel.js';
 import FileInfoPanel from './FileInfoPanel.js';
 import HeaderButtons from './HeaderButtons.js';
 import RefNameInfoDialog from './RefNameInfoDialog.js';
@@ -49,7 +50,7 @@ const AboutDialogContents = observer(function AboutDialogContents({ config, sess
         session,
         pluginManager,
     });
-    return (_jsxs("div", { className: classes.content, children: [_jsxs(BaseCard, { title: "Configuration", children: [_jsx(HeaderButtons, { conf: conf, hideUris: hideUris, fromDisplayTypeDefaults: fromDisplayTypeDefaults, setShowRefNames: setShowRefNames }), _jsx(Attributes, { attributes: shown, omit: [...hideFields, 'metadata'], hideUris: hideUris })] }), shown.metadata ? (_jsx(BaseCard, { title: "Metadata", children: _jsx(Attributes, { attributes: shown.metadata, hideUris: hideUris }) })) : null, _jsx(AssemblyInfoPanel, { config: config, session: session, hideUris: hideUris }), _jsx(PluggableComponents, { pluginManager: pluginManager, 
+    return (_jsxs("div", { className: classes.content, children: [_jsxs(BaseCard, { title: "Configuration", children: [_jsx(HeaderButtons, { conf: conf, hideUris: hideUris, fromDisplayTypeDefaults: fromDisplayTypeDefaults, setShowRefNames: setShowRefNames }), _jsx(Attributes, { attributes: shown, omit: [...hideFields, 'metadata'], hideUris: hideUris })] }), shown.metadata ? (_jsx(BaseCard, { title: "Metadata", children: _jsx(Attributes, { attributes: shown.metadata, hideUris: hideUris }) })) : null, _jsx(DescriptionPanel, { config: config, session: session }), _jsx(AssemblyInfoPanel, { config: config, session: session, hideUris: hideUris }), _jsx(PluggableComponents, { pluginManager: pluginManager, 
                 /** #extensionPoint Core-extraAboutPanel | sync | Add extra panels to a track's About dialog */
                 name: "Core-extraAboutPanel", props: { session, config } }), hideUris ? null : _jsx(FileInfoPanel, { config: config, session: session }), showRefNames ? (_jsx(RefNameInfoDialog, { session: session, config: config, onClose: () => {
                     setShowRefNames(false);

package/esm/ui/DescriptionPanel.d.ts

@@ -0,0 +1,3 @@
+import type { AboutPanelProps } from './util.ts';
+declare const DescriptionPanel: ({ config, }: AboutPanelProps) => import("react").JSX.Element | null;
+export default DescriptionPanel;

package/esm/ui/DescriptionPanel.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import BaseCard from '@jbrowse/core/BaseFeatureWidget/BaseFeatureDetail/BaseCard';
+import { ErrorBanner, LoadingEllipses, SanitizedHTML } from '@jbrowse/core/ui';
+import { openLocation } from '@jbrowse/core/util/io';
+import { makeStyles } from '@jbrowse/core/util/tss-react';
+import { useFetch } from '@jbrowse/core/util/useFetch';
+import { Link, Typography } from '@mui/material';
+import { observer } from 'mobx-react';
+import { getDescriptionHtmlUrl, rebaseDescriptionHtml, } from './descriptionHtml.js';
+const useStyles = makeStyles()(theme => ({
+    provenance: {
+        marginBottom: theme.spacing(1),
+    },
+}));
+const DescriptionCard = observer(function DescriptionCard({ url, }) {
+    const { classes } = useStyles();
+    const { data: html, error, isLoading, } = useFetch(['trackDescriptionHtml', url], async (_name, url) => rebaseDescriptionHtml(await openLocation({ uri: url, locationType: 'UriLocation' }).readFile('utf8'), url));
+    return (_jsxs(BaseCard, { title: "Description", children: [_jsxs(Typography, { variant: "caption", color: "textSecondary", component: "div", className: classes.provenance, children: ["From the track hub, written for the UCSC Genome Browser \u2014 some display options it describes differ in JBrowse.", ' ', _jsx(Link, { href: url, target: "_blank", rel: "noopener noreferrer", children: "View original" })] }), error ? (_jsx(ErrorBanner, { error: error })) : isLoading || html === undefined ? (_jsx(LoadingEllipses, { message: "Loading description" })) : (_jsx(SanitizedHTML, { html: html }))] }));
+});
+const DescriptionPanel = observer(function DescriptionPanel({ config, }) {
+    const url = getDescriptionHtmlUrl(config);
+    return url ? _jsx(DescriptionCard, { url: url }) : null;
+});
+export default DescriptionPanel;