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

package/esm/RootModel/BaseRootModel.js

@@ -87,6 +87,7 @@ export function BaseRootModelFactory({ pluginManager, jbrowseModelType, sessionM
             const unbuildable = [];
             let migrated = sessionSnapshot;
             if (sessionSnapshot && typeof sessionSnapshot === 'object') {
+                pluginManager.assertSessionTypesLoaded(sessionSnapshot);
                 // before the cast, because a type this build has no plugin for is a
                 // union failure the try below never gets to see
                 const pruned = pruneUnbuildableNodes(migrateSessionSnapshot(sessionSnapshot), pluginManager, sessionModelType);

package/esm/RootModel/PreferencesConfig.d.ts

@@ -50,4 +50,19 @@ export declare function PreferencesConfigSchemaFactory(): import("@jbrowse/core/
         readonly type: "boolean";
         readonly defaultValue: false;
     };
+    /**
+     * #slot configuration.preferences.developerMode
+     * when true, the ordering-contract checks a display or plugin can break
+     * report themselves in the app rather than only in a development build.
+     * Off by default and deliberately not in the Preferences dialog: the
+     * messages are about code, and a reader who cannot change the code cannot
+     * act on one. Turn it on for a site that is running a plugin under
+     * development; a plugin author needs nothing here, since a plugin served
+     * from localhost arms the same channel on its own, as does
+     * `localStorage.jbrowseDeveloperMode`. Takes effect on reload.
+     */
+    readonly developerMode: {
+        readonly type: "boolean";
+        readonly defaultValue: false;
+    };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;

package/esm/RootModel/PreferencesConfig.js

@@ -57,5 +57,20 @@ export function PreferencesConfigSchemaFactory() {
             type: 'boolean',
             defaultValue: false,
         },
+        /**
+         * #slot configuration.preferences.developerMode
+         * when true, the ordering-contract checks a display or plugin can break
+         * report themselves in the app rather than only in a development build.
+         * Off by default and deliberately not in the Preferences dialog: the
+         * messages are about code, and a reader who cannot change the code cannot
+         * act on one. Turn it on for a site that is running a plugin under
+         * development; a plugin author needs nothing here, since a plugin served
+         * from localhost arms the same channel on its own, as does
+         * `localStorage.jbrowseDeveloperMode`. Takes effect on reload.
+         */
+        developerMode: {
+            type: 'boolean',
+            defaultValue: false,
+        },
     });
 }

package/esm/RootModel/createConfigModel.d.ts

@@ -66,6 +66,10 @@ declare function rootConfigurationSchema(): import("@jbrowse/core/configuration/
             readonly type: "boolean";
             readonly defaultValue: false;
         };
+        readonly developerMode: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
+        };
     }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
     readonly formatDetails: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
         readonly feature: {
@@ -178,6 +182,10 @@ export declare function createConfigModel(pluginManager: PluginManager, assembly
                 readonly type: "boolean";
                 readonly defaultValue: false;
             };
+            readonly developerMode: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
         }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
         readonly formatDetails: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
             readonly feature: {

package/esm/Session/BaseSession.d.ts

@@ -322,6 +322,8 @@ export declare function BaseSessionModel<ROOT_MODEL_TYPE extends BaseRootModelTy
     pushSnackbarMessage(message: string, level?: import("@jbrowse/core/util").NotificationLevel, actions?: import("@jbrowse/core/util").SnackAction[]): void;
     popSnackbarMessage(): import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage | undefined;
     removeSnackbarMessage(message: string): void;
+} & {
+    afterAttach(): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 /** Session mixin MST type for the most basic session */
 export type BaseSessionType = ReturnType<typeof BaseSessionModel>;

package/esm/Session/BaseSession.js

@@ -6,6 +6,7 @@ import { isFeature, unwrapFeature } from '@jbrowse/core/util/simpleFeature';
 import { ElementId } from '@jbrowse/core/util/types/mst';
 import { getParent, isStateTreeNode, types } from '@jbrowse/mobx-state-tree';
 import { observable } from 'mobx';
+import { applyDeveloperMode } from './developerMode.js';
 function isAnimationMode(val) {
     return val === 'system' || val === 'enabled' || val === 'disabled';
 }
@@ -490,7 +491,16 @@ export function BaseSessionModel(_pluginManager) {
             self.queueOfDialogs = [...self.queueOfDialogs, [component, props]];
         },
     }));
-    return types.compose(baseModel, SnackbarModel());
+    return types.compose(baseModel, SnackbarModel()).actions(self => ({
+        // after the compose rather than in the afterAttach above, because the
+        // notices land in the snackbar this line is the first place to hold both
+        // halves of. Web and desktop reach it a second time once the user's stored
+        // overrides are loaded (`PreferencesSessionMixin`), and our MST fork
+        // auto-chains both hooks.
+        afterAttach() {
+            applyDeveloperMode(self);
+        },
+    }));
 }
 /** Type guard for BaseSession */
 export function isBaseSession(thing) {

package/esm/Session/MultipleViews.d.ts

@@ -1,4 +1,5 @@
 import type PluginManager from '@jbrowse/core/PluginManager';
+import type { ViewSnapshotInput } from '@jbrowse/core/PluginManager';
 import type { IBaseViewModel } from '@jbrowse/core/pluggableElementTypes';
 import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
 /**
@@ -1678,6 +1679,8 @@ export declare function MultipleViewsSessionMixin(pluginManager: PluginManager):
     pushSnackbarMessage(message: string, level?: import("@jbrowse/core/util").NotificationLevel, actions?: import("@jbrowse/core/util").SnackAction[]): void;
     popSnackbarMessage(): import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage | undefined;
     removeSnackbarMessage(message: string): void;
+} & {
+    afterAttach(): void;
 } & {
     readonly visibleWidget: import("@jbrowse/core/util").Widget | undefined;
 } & {
@@ -1752,8 +1755,10 @@ export declare function MultipleViewsSessionMixin(pluginManager: PluginManager):
     orderViews(ids: string[]): void;
     /**
      * #action
+     * Requires the view type's state model to be loaded; for a lazily
+     * registered type use `launchView`.
      */
-    addView(typeName: string, initialState?: any): any;
+    addView<N extends string>(typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): any;
     /**
      * #action
      * swap `view` for a new view of `typeName`, in the slot it occupied.
@@ -1783,7 +1788,7 @@ export declare function MultipleViewsSessionMixin(pluginManager: PluginManager):
      * its panel, and the launch that offers a replace is a click on that
      * view's own menu.
      */
-    replaceView(view: IBaseViewModel, typeName: string, initialState?: any): any;
+    replaceView<N extends string>(view: IBaseViewModel, typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): any;
     /**
      * #action
      */
@@ -1845,6 +1850,16 @@ export declare function MultipleViewsSessionMixin(pluginManager: PluginManager):
      */
     resetUseWorkspaces(): void;
     afterAttach(): void;
+} & {
+    /**
+     * #action
+     * `addView` for view types whose state model may be lazily loaded. The
+     * view is not in `session.views` until the promise resolves.
+     * `getViewType` first so an unknown type name fails by that name; the
+     * snapshot walk skips unregistered names and covers the displays of the
+     * tracks a launch opens with.
+     */
+    launchView<N extends string>(typeName: N, initialState?: NoInfer<ViewSnapshotInput<N>>): Promise<any>;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree").ModelSnapshotType<Omit<Omit<Omit<{
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
     name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;

package/esm/Session/MultipleViews.js

@@ -54,10 +54,24 @@ function dropRefsInto(holder, view) {
     }
     return found;
 }
+// A session snapshot's `views`, or undefined for anything that is not one
+function viewsOfSessionSnapshot(snapshot) {
+    const views = typeof snapshot === 'object' && snapshot !== null && 'views' in snapshot
+        ? snapshot.views
+        : undefined;
+    return Array.isArray(views) ? views : undefined;
+}
 /**
  * #stateModel MultipleViewsSessionMixin
  */
 export function MultipleViewsSessionMixin(pluginManager) {
+    // an unknown type name passes through to fail at the union as it always has
+    function assertViewStateModelLoaded(typeName) {
+        if (pluginManager.getElementTypeRecord('view').has(typeName) &&
+            !pluginManager.getViewType(typeName).isStateModelLoaded) {
+            throw new Error(`state model for view type ${typeName} is not loaded yet — use launchView(), or await getViewType('${typeName}').loadStateModel() first`);
+        }
+    }
     return types
         .compose(BaseSessionModel(pluginManager), DrawerWidgetSessionMixin(pluginManager), types.model({
         /**
@@ -208,8 +222,11 @@ export function MultipleViewsSessionMixin(pluginManager) {
             },
             /**
              * #action
+             * Requires the view type's state model to be loaded; for a lazily
+             * registered type use `launchView`.
              */
-            addView(typeName, initialState = {}) {
+            addView(typeName, initialState) {
+                assertViewStateModelLoaded(typeName);
                 const length = self.views.push({
                     ...initialState,
                     type: typeName,
@@ -245,7 +262,8 @@ export function MultipleViewsSessionMixin(pluginManager) {
              * its panel, and the launch that offers a replace is a click on that
              * view's own menu.
              */
-            replaceView(view, typeName, initialState = {}) {
+            replaceView(view, typeName, initialState) {
+                assertViewStateModelLoaded(typeName);
                 // read before the removal, which is what makes both stale
                 const idx = self.views.indexOf(view);
                 // `idx` first, so a view already gone from the session short-circuits
@@ -305,7 +323,13 @@ export function MultipleViewsSessionMixin(pluginManager) {
              * lands, which is why ADR-069's rule stops there.
              */
             takeOutViewsMissingFrom(snapshot) {
-                const incoming = snapshot?.views ?? [];
+                const incoming = viewsOfSessionSnapshot(snapshot);
+                // an argument that is not a session snapshot used to read as "keep
+                // none" and close every view: an agent introspecting the actions
+                // called this with a tab id and a keep-list and lost its session
+                if (!incoming) {
+                    throw new Error('takeOutViewsMissingFrom takes a session snapshot (it is what undo and redo call to close the views a snapshot no longer has); to close one view, session.removeView(view)');
+                }
                 const kept = new Map(incoming.map(v => [v.id, v.type]));
                 // a copy, because `takeOut` splices the array it is iterating
                 for (const view of [...self.views]) {
@@ -359,6 +383,23 @@ export function MultipleViewsSessionMixin(pluginManager) {
             },
         };
     })
+        .actions(self => ({
+        /**
+         * #action
+         * `addView` for view types whose state model may be lazily loaded. The
+         * view is not in `session.views` until the promise resolves.
+         * `getViewType` first so an unknown type name fails by that name; the
+         * snapshot walk skips unregistered names and covers the displays of the
+         * tracks a launch opens with.
+         */
+        async launchView(typeName, initialState) {
+            await pluginManager.getViewType(typeName).loadStateModel();
+            await pluginManager.preloadSessionTypes({
+                views: [{ type: typeName, ...initialState }],
+            });
+            return self.addView(typeName, initialState);
+        },
+    }))
         .postProcessSnapshot(snap => {
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (!snap) {

package/esm/Session/Preferences.d.ts

@@ -1662,4 +1662,6 @@ export declare function PreferencesSessionMixin(pluginManager: PluginManager): i
     removeSnackbarMessage(message: string): void;
 } & {
     afterAttach(): void;
+} & {
+    afterAttach(): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;

package/esm/Session/Preferences.js

@@ -3,6 +3,7 @@ import { freezeDeep } from '@jbrowse/core/util/freezeDeep';
 import { addDisposer, types } from '@jbrowse/mobx-state-tree';
 import { autorun } from 'mobx';
 import { BaseSessionModel } from './BaseSession.js';
+import { applyDeveloperMode } from './developerMode.js';
 const PREFS_KEY = 'jbrowsePreferences';
 function loadStoredPreferences() {
     const stored = localStorageGetItem(PREFS_KEY);
@@ -43,6 +44,10 @@ export function PreferencesSessionMixin(pluginManager) {
             // main-thread update would leave the app formatted two ways at once.
             // The dialog says a reload is needed; this is where the reload lands.
             setNumberGrouping(self.numberGrouping);
+            // and the same second pass for the developer-notice channel, whose
+            // admin default BaseSession already read: a user's stored override is
+            // only loaded a line above this
+            applyDeveloperMode(self);
             addDisposer(self, autorun(function persistPreferences() {
                 // observable.map doesn't JSON-serialize to an object on its own;
                 // fromEntries also reads every key so the autorun re-persists on

package/esm/Session/SessionTracks.d.ts

@@ -1689,6 +1689,8 @@ export declare function SessionTracksManagerSessionMixin(pluginManager: PluginMa
     pushSnackbarMessage(message: string, level?: import("@jbrowse/core/util").NotificationLevel, actions?: import("@jbrowse/core/util").SnackAction[]): void;
     popSnackbarMessage(): import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage | undefined;
     removeSnackbarMessage(message: string): void;
+} & {
+    afterAttach(): void;
 } & {
     getReferringMultiple(trackIds: string[]): Map<string, import("./ReferenceManagement.ts").ReferringNode[]>;
 } & {

package/esm/Session/SessionTracks.js

@@ -4,6 +4,7 @@ import { expandLooseTrackConfig } from '@jbrowse/core/util/tracks';
 import { applySnapshot, getSnapshot, isStateTreeNode, types, } from '@jbrowse/mobx-state-tree';
 import { compareStructural } from 'mobx';
 import { TracksManagerSessionMixin } from './Tracks.js';
+import { assertNotReaddedDifferently } from './readdedTrackConf.js';
 import { assertTrackConfOutlivesItsAssemblies } from './temporaryAssemblyTracks.js';
 // jbrowse.tracks holds frozen plain objects (app-core, web/desktop) or MST
 // config nodes (product-core, embedded react views); the delta math reads both
@@ -342,6 +343,13 @@ export function SessionTracksManagerSessionMixin(pluginManager) {
             // and dropping its trackConfigDeltas override semantics.
             const existing = self.getTrackById(trackId);
             if (existing) {
+                if (self.sessionTracks.includes(existing)) {
+                    assertNotReaddedDifferently(pluginManager, existing, {
+                        ...trackConf,
+                        trackId,
+                        type,
+                    });
+                }
                 return existing;
             }
             // sessionTracks is a typed MST array (unlike the frozen

package/esm/Session/TrackMenu.js

@@ -44,7 +44,7 @@ export function trackActionItems({ session, config, view, canEdit, isSessionOver
     // visitor is served, one per click since the copy's stamped trackId defeats
     // the dedupe, and a non-admin's lands as the dead `sessionTracks` entry
     // ADR-084 removed the sweep for. Neither is worth offering, so the item says
-    // so instead of producing garbage; the dev-only contract check on the adders
+    // so instead of producing garbage; the contract check on the adders
     // is what found this.
     //
     // Greying a row tells nobody anything, and this reason is one nobody guesses:
@@ -86,7 +86,7 @@ export function trackActionItems({ session, config, view, canEdit, isSessionOver
             onClick: () => {
                 const snap = makeCopy();
                 if (session.publishTrackConf(snap)) {
-                    view.showTrack(snap.trackId);
+                    void view.launchTrack(snap.trackId);
                 }
             },
         },

package/esm/Session/Tracks.d.ts

@@ -1657,6 +1657,8 @@ export declare function TracksManagerSessionMixin(pluginManager: PluginManager):
     pushSnackbarMessage(message: string, level?: import("@jbrowse/core/util").NotificationLevel, actions?: import("@jbrowse/core/util").SnackAction[]): void;
     popSnackbarMessage(): import("@jbrowse/core/ui/SnackbarModel").SnackbarMessage | undefined;
     removeSnackbarMessage(message: string): void;
+} & {
+    afterAttach(): void;
 } & {
     getReferringMultiple(trackIds: string[]): Map<string, import("./ReferenceManagement.ts").ReferringNode[]>;
 } & {

package/esm/Session/Tracks.js

@@ -1,8 +1,10 @@
+import { expandLooseTrackConfig } from '@jbrowse/core/util/tracks';
 import { types } from '@jbrowse/mobx-state-tree';
 import { 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
@@ -24,6 +26,14 @@ export function TracksManagerSessionMixin(pluginManager) {
         // 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.
+        //
+        // `keepAlive` is what makes that last sentence true, and it is load
+        // bearing: an unobserved computed re-derives on EVERY read, and this one
+        // walks every track, assembly and connection the session can resolve. A
+        // reader inside a reaction or an MST action was already fine — MobX
+        // caches within a batch, which is why the resolvers and `showTrackGeneric`
+        // never showed it. Ranking search hits is the caller that is neither, and
+        // it cost 33ms per search on a 2000-track config against 0.07ms held.
         const tracksByIdRecord = computed(() => {
             const temporaryAssemblies = 'temporaryAssemblies' in self
                 ? self.temporaryAssemblies
@@ -49,7 +59,7 @@ export function TracksManagerSessionMixin(pluginManager) {
                     e.config,
                 ]),
             ]);
-        });
+        }, { keepAlive: true });
         // 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
@@ -108,6 +118,19 @@ export function TracksManagerSessionMixin(pluginManager) {
          */
         addSessionTrackConf(trackConf) {
             assertTrackConfOutlivesItsAssemblies(self, trackConf, 'jbrowse.tracks');
+            // the config's own adder appends without looking, so a re-add under a
+            // known id used to leave two entries with the first one winning
+            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);
         },
         /**

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

@@ -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

@@ -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/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/DisplayDefaultsSection.js

@@ -60,6 +60,6 @@ const DisplayDefaultsSection = observer(function DisplayDefaultsSection({ sessio
     }));
     return changes.length ? (_jsxs(_Fragment, { children: [_jsx(Typography, { children: "These apply to every track of a display type that hasn't set its own value. Clear one to put those tracks back on the setting's default." }), _jsx(SettingsChangesTable, { changes: changes, onResetRow: change => {
                     session.setDisplayTypeDefault(change.path[0], change.path[1], undefined);
-                } })] })) : (_jsx(Typography, { children: "None set. The pin beside a setting in a track menu makes that value the default for every track of the same display type." }));
+                } })] })) : (_jsx(Typography, { children: "None set. The pin beside a setting in a track menu applies that value to every open track of the same display type, and then offers to keep it as the default for the ones you open later." }));
 });
 export default DisplayDefaultsSection;

package/esm/useEngineLifecycle.d.ts

@@ -1,5 +1,11 @@
 import type { EmbeddedRoot } from './destroyViewState.ts';
-export { useCreateOnce } from '@jbrowse/core/util/hooks';
+export { useCreateOnce, useCreateOnceAsync } from '@jbrowse/core/util/hooks';
+/**
+ * Async `useCreateOnce` + `useDestroyOnUnmount`: undefined until the engine is
+ * ready. An engine resolving after the final unmount is destroyed on arrival
+ * instead of orphaning its worker pool and autoruns.
+ */
+export declare function useAsyncEngineLifecycle<T extends EmbeddedRoot>(create: () => Promise<T>): T | undefined;
 /**
  * Destroy an engine when its component really unmounts — terminating its RPC
  * worker threads and stopping its autoruns.

package/esm/useEngineLifecycle.js

@@ -1,10 +1,32 @@
-import { useFinalUnmount } from '@jbrowse/core/util/hooks';
+import { useRef } from 'react';
+import { useCreateOnceAsync, useFinalUnmount } from '@jbrowse/core/util/hooks';
 import { destroyViewState } from './destroyViewState.js';
 // `useCreateOnce` is core's, and is re-exported rather than wrapped: an engine
 // is only the most expensive thing StrictMode's double-invoked state
 // initializer can build twice, not the only one. The faceted track selector's
 // MST model hit the same trap in a plugin, which cannot reach this package.
-export { useCreateOnce } from '@jbrowse/core/util/hooks';
+export { useCreateOnce, useCreateOnceAsync } from '@jbrowse/core/util/hooks';
+/**
+ * Async `useCreateOnce` + `useDestroyOnUnmount`: undefined until the engine is
+ * ready. An engine resolving after the final unmount is destroyed on arrival
+ * instead of orphaning its worker pool and autoruns.
+ */
+export function useAsyncEngineLifecycle(create) {
+    const unmounted = useRef(false);
+    const engine = useCreateOnceAsync(() => create().then(built => {
+        if (unmounted.current) {
+            destroyViewState(built);
+        }
+        return built;
+    }));
+    useFinalUnmount(() => {
+        unmounted.current = true;
+        if (engine) {
+            destroyViewState(engine);
+        }
+    });
+    return engine;
+}
 /**
  * Destroy an engine when its component really unmounts — terminating its RPC
  * worker threads and stopping its autoruns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/product-core",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "type": "module",
   "sideEffects": false,
   "description": "JBrowse 2 code shared between products but not used by plugins",
@@ -26,11 +26,12 @@
   ],
   "dependencies": {
     "@jbrowse/mobx-state-tree": "^6.5.1",
-    "@mui/icons-material": "^9.3.1",
-    "@mui/material": "^9.3.1",
+    "@mui/icons-material": "^9.4.0",
+    "@mui/material": "^9.4.0",
     "mobx": "^7.0.3",
     "mobx-react": "^10.0.2",
-    "@jbrowse/core": "^5.0.0-beta.1"
+    "@jbrowse/core": "^5.0.0-beta.2",
+    "@jbrowse/render-core": "^5.0.0-beta.2"
   },
   "peerDependencies": {
     "react": ">=19.0.0",