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

package/README.md

@@ -402,8 +402,11 @@ not be the thing that discovers this. Callers fall back to treating it as the
 plain object it is.
 
 Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating the
-same entry twice returns the same node and a track that gets opened later reuses
-it.
+same entry twice returns the same node — and in admin/embedded sessions a track
+opened later resolves to that same node. A non-admin's open track does not: it
+resolves to the session's private working copy (ADR-032) and this is the
+pristine mirror beside it. The two agree in content, which is what the caller
+needs; `CopyConfigEntryPoints.test.ts` pins both halves.
 
 ```js
 // type signature
@@ -432,6 +435,18 @@ the check off (`HostChecksSlotNames`).
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
 
+### launchOrReplaceView
+
+`addOrReplaceView` for view types whose state model may be lazily loaded; the
+synchronous `addOrReplaceView` requires it loaded already.
+
+```js
+// type signature
+(args: { session: AbstractViewContainer; typeName: string; initialState?: Record<string, unknown> | undefined; replacing?: AbstractViewModel | undefined; }) => Promise<...>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/mstUtils.ts)
+
 ### makePin
 
 The pin for one promotable slot: "apply this value to every open track of this
@@ -648,6 +663,24 @@ at the point where the connection is cut.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/configuration/promotableDefaults.ts)
 
+### runLazyAfterAttach
+
+Run a display's `afterAttach` body from a module loaded on demand, so the
+autorun installers stay out of the display's eager bundle.
+
+One policy for the gap the `await` opens: a node torn down before the module
+lands installs nothing, and a module that fails to load is reported where the
+user can see it rather than onto the display's own error slot — that slot is
+what `reload()` clears, and nothing would re-run the install behind it. Three
+displays hand-rolled this IIFE and each drew the lines differently.
+
+```js
+// type signature
+<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>) => void
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/util/lazyAfterAttach.ts)
+
 ### sampleColorRamp
 
 The color at `t` in `[0, 1]` across a list of EVENLY SPACED stops, linearly
@@ -671,6 +704,12 @@ Make JBrowse follow the host's light/dark state — the whole of it, in one moun
 </SessionPaletteProvider>
 ```
 
+`mode` is optional. Left out, JBrowse follows `prefers-color-scheme` and
+re-themes when the OS preference changes, through the same session write an
+explicit mode takes — so a host whose dark mode _is_ the OS preference mounts
+this with a session and nothing else. Pass a mode as soon as the host has a
+toggle of its own, since the media query cannot see it.
+
 A component rather than a documented pair of calls because the pair has a half
 that can be left out with nothing to show for it. `PaletteProvider` is the name
 a host reaches for, and it colors the React side alone; the session write is
@@ -684,7 +723,7 @@ colors of its own mounts `PaletteProvider` directly instead.
 
 ```js
 // type signature
-({ session, mode, children, }: { session: ThemeModeSession; mode: "dark" | "light"; children: ReactNode; }) => Element
+({ session, mode, children, }: { session: ThemeModeSession; mode?: "dark" | "light" | undefined; children: ReactNode; }) => Element
 ```
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/core/src/ui/PaletteContext.tsx)

package/esm/BaseFeatureWidget/SequenceFeatureDetails/test_data/NCDN.d.ts

@@ -48,9 +48,9 @@ declare const _default: {
             uniqueId: string;
             parentId: string;
             id?: undefined;
+            name?: undefined;
             note?: undefined;
             protein_id?: undefined;
-            name?: undefined;
         } | {
             transcript_id?: undefined;
             source: string;
@@ -94,6 +94,7 @@ declare const _default: {
         transcript_id: string;
         subfeatures: ({
             id?: undefined;
+            name?: undefined;
             note?: undefined;
             protein_id?: undefined;
             source: string;
@@ -111,7 +112,6 @@ declare const _default: {
             transcript_id: string;
             uniqueId: string;
             parentId: string;
-            name?: undefined;
         } | {
             transcript_id?: undefined;
             source: string;

package/esm/PluginLoader.d.ts

@@ -12,6 +12,7 @@ export interface PluginLoadFailure {
     definition: PluginDefinition;
     error: unknown;
 }
+export declare function workerScriptLoadMessage(scriptUrl: string, error: unknown): string;
 export default class PluginLoader {
     definitions: PluginDefinition[];
     fetchESM?: (url: string) => Promise<LoadedPlugin>;

package/esm/PluginLoader.js

@@ -1,5 +1,6 @@
+import { enableContractReports } from '@jbrowse/render-core/contractReports';
 import { setReExportRegistry } from './ReExports/registry.js';
-import { isCJSPluginDefinition, isESMPluginDefinition, isUMDPluginDefinition, pluginDescriptionString, } from './pluginDefinitions.js';
+import { isCJSPluginDefinition, isESMPluginDefinition, isUMDPluginDefinition, maybePluginUrl, pluginDescriptionString, } from './pluginDefinitions.js';
 import { isElectron } from './util/index.js';
 import { isWebWorker } from './util/isWebWorker.js';
 /**
@@ -45,6 +46,19 @@ function promisifiedLoadScript(src, integrity) {
 function hasImportScripts(scope) {
     return 'importScripts' in scope;
 }
+// A *module* worker has importScripts on its global but throws from it — the
+// spec forbids it there, and the browser says so ("Module scripts don't support
+// importScripts"). That is the whole failure for a UMD plugin in a bundler
+// configured for module workers (Vite's `worker.format: 'es'`), and it reads as
+// a broken plugin unless named. Every other throw is the script's own — a 404,
+// or a bundle that dereferences `window` in a realm that has none — and the
+// script's words are the diagnosis, so they are kept rather than replaced.
+export function workerScriptLoadMessage(scriptUrl, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return /module script/i.test(detail)
+        ? `Failed to load ${scriptUrl} in the worker. A UMD plugin is loaded there via importScripts, which module workers do not support — either build the worker as a classic worker, or use a plugin published as ESM.`
+        : `Failed to load ${scriptUrl} in the worker: ${detail}`;
+}
 async function loadScript(scriptUrl, integrity) {
     const scope = globalThis;
     if (!isWebWorker()) {
@@ -55,12 +69,9 @@ async function loadScript(scriptUrl, integrity) {
             scope.importScripts(scriptUrl);
         }
         catch (error) {
-            // A *module* worker has importScripts on its global but throws from it —
-            // the spec forbids it there. That is the whole failure for a UMD plugin
-            // in a bundler configured for module workers (Vite's `worker.format:
-            // 'es'`), and the raw TypeError names none of it, so it reads as a broken
-            // plugin rather than an incompatible pairing.
-            throw new Error(`Failed to load ${scriptUrl} in the worker. A UMD plugin is loaded there via importScripts, which module workers do not support — either build the worker as a classic worker, or use a plugin published as ESM.`, { cause: error });
+            throw new Error(workerScriptLoadMessage(scriptUrl, error), {
+                cause: error,
+            });
         }
         return;
     }
@@ -97,6 +108,34 @@ function resolvePluginUrl(spec, base) {
     }
     return url;
 }
+// A plugin served from the developer's own machine into an app built for
+// production is the one arrangement that can only be a plugin under
+// development: a shipped site serves its plugins from its own origin, and a
+// developer running the app itself from source already has a development build.
+// So it is the evidence that arms the contract channel without anything for the
+// author to know about first — which is the whole difficulty the channel had,
+// since the population it is written for is the one with nobody to ask. See
+// `@jbrowse/render-core/contractReports`.
+function armIfUnderDevelopment(def) {
+    const url = maybePluginUrl(def);
+    if (url !== undefined && servedFromThisMachine(url)) {
+        enableContractReports(`the plugin at ${url} is served from this machine`);
+    }
+}
+function servedFromThisMachine(url) {
+    try {
+        const { hostname, protocol } = new URL(url);
+        return ((protocol === 'http:' || protocol === 'https:') &&
+            (hostname === 'localhost' ||
+                hostname === '127.0.0.1' ||
+                hostname === '[::1]'));
+    }
+    catch {
+        // a relative url is a plugin shipped beside this index.html, which is the
+        // site's own rather than one under development
+        return false;
+    }
+}
 function addCacheBuster(url) {
     if (!('__jbrowseCacheBuster' in globalThis)) {
         return url;
@@ -155,6 +194,7 @@ export default class PluginLoader {
     }
     async loadPlugin(def, baseUri) {
         assertSingleKind(def);
+        armIfUnderDevelopment(def);
         let plugin;
         if (isCJSPluginDefinition(def)) {
             if (!isElectron) {
@@ -198,7 +238,11 @@ export default class PluginLoader {
         if (!target) {
             return;
         }
-        const { default: ReExports } = await import('./ReExports/index.js');
+        // a worker never renders: the same keys, with the UI ones stubbed, so a
+        // plugin bundle evaluates there without fetching react-dom and Material UI
+        const { default: ReExports } = isWebWorker()
+            ? await import('./ReExports/workerModules.js')
+            : await import('./ReExports/index.js');
         target.JBrowseExports = {
             ...ReExports,
         };

package/esm/PluginManager.d.ts

@@ -20,7 +20,7 @@ import './ui/buildExtraTrackMenuItems.ts';
 import './ui/multiTrackMenuItems.ts';
 import './util/addTrackComponent.ts';
 import type { AbstractRootModel, AbstractSessionModel, SimpleFeatureSerialized } from './util/index.ts';
-import type { IAnyModelType, IStateTreeNode, IAnyType } from '@jbrowse/mobx-state-tree';
+import type { IAnyModelType, IStateTreeNode, IAnyType, SnapshotIn } from '@jbrowse/mobx-state-tree';
 import type { ComponentType, ReactNode } from 'react';
 /**
  * Every pluggable element group, in the order `elementCreationSchedule` builds
@@ -137,7 +137,18 @@ export interface ReplaceWidgetProps {
  *
  * That is what makes `extendViewType(pm, 'LinearGenomeView', …)` hand back a
  * typed state model, and a misspelled or renamed name a compile error rather
- * than an extension that quietly never applies. Declaring them here rather than
+ * than an extension that quietly never applies. `getViewType` reads it too, so
+ * a caller composing another view's model into its own gets the real type
+ * instead of `IAnyModelType`.
+ *
+ * AN AUGMENTATION IS HAND-WRITTEN, so each registration annotates the model it
+ * passes to `ViewType` against its own entry here (`const stateModel:
+ * ViewTypeRegistry['CircularView'] = …`). That one line is what makes the
+ * registry earn what `getViewType` promises: without it a drifted entry is
+ * worse than the `IAnyModelType` it replaced, since a caller would get a
+ * confidently wrong type rather than an unchecked one. It cannot live on
+ * `ViewType`'s constructor — TypeScript forbids type parameters there, and a
+ * class parameter widens `name` to `string`, so the conditional never fires. Declaring them here rather than
  * beside the helpers is load-bearing: an interface can only be augmented
  * through the module that declares it, and a barrel re-exporting the type would
  * give every augmentation its own unrelated copy.
@@ -148,6 +159,21 @@ export interface DisplayTypeRegistry {
 }
 export type ViewTypeName = keyof ViewTypeRegistry;
 export type DisplayTypeName = keyof DisplayTypeRegistry;
+/**
+ * What `addView(name, snapshot)` takes for a view type name. A registered name
+ * gets the view's authored shape — the snapshot type `withLaunchInput` widened
+ * to accept the launch keys beside the declared properties — so a misspelled
+ * key is a compile error at the literal site. `type` is optional because
+ * `addView` writes it. An unregistered name stays `Record<string, unknown>`,
+ * which is what an out-of-tree view's `addView` has always been.
+ *
+ * Read off `ViewTypeRegistry` rather than registered a second time, so the
+ * snapshot type cannot drift from the model: a view that augments the registry
+ * has typed `addView`, `replaceView` and `addOrReplaceView` for free.
+ */
+export type ViewSnapshotInput<N extends string> = N extends ViewTypeName ? Omit<SnapshotIn<ViewTypeRegistry[N]>, 'type'> & {
+    type?: N;
+} : Record<string, unknown>;
 export interface ExtensionPointRegistry {
     'Core-extendSession': {
         args: IAnyModelType;
@@ -268,6 +294,7 @@ export interface RuntimePluginLoadRecord extends PluginLoadRecord {
     definition: PluginDefinition;
 }
 export default class PluginManager {
+    #private;
     plugins: Plugin[];
     jexl: import("@jbrowse/jexl").Jexl;
     pluginMetadata: Record<string, PluginMetadata>;
@@ -289,25 +316,27 @@ export default class PluginManager {
     extensionPoints: Map<string, ExtensionPointCallback[]>;
     warnedClobber: Set<string>;
     /**
-     * Lazy-hydration cache for `TrackConfigurationReference`/
-     * `DisplayConfigurationReference` (configuration/configurationSchema.ts).
+     * The lazily-hydrated MST config node for one frozen track config, built by
+     * `build` on first ask and returned by identity after that.
+     * `configuration/configurationSchema.ts` is the only caller.
+     *
      * `jbrowse.tracks` is `types.frozen` for large-tracklist performance, so a
-     * track config is a plain JS object until first referenced; hydrating it
-     * into an MST node is deferred to that read. MST's custom-reference
-     * `getValue` has no memoization of its own — it reruns on every property
-     * access — so without this cache, every read of `track.configuration` would
-     * fabricate a fresh, non-identical MST node. Keyed by schemaType (each track
-     * type's config schema is rebuilt fresh per PluginManager instance, see
-     * addTrackType) then by the frozen object itself, so a cache hit can only
-     * ever come from this same PluginManager instance and this same track type.
-     * See ADR-031.
+     * track config is a plain JS object until first referenced; hydrating it into
+     * an MST node is deferred to that read. MST's custom-reference `getValue` has
+     * no memoization of its own — it reruns on every property access — so without
+     * this, every read of `track.configuration` would fabricate a fresh,
+     * non-identical node. Keyed by schemaType (each track type's config schema is
+     * rebuilt fresh per PluginManager instance, see addTrackType) then by the
+     * frozen object, so a hit can only ever come from this same instance and this
+     * same track type. See ADR-031.
      *
-     * This node is never mutated: admin edits replace the frozen entry (new
+     * The node is never mutated: admin edits replace the frozen entry (new
      * identity drops the WeakMap entry), and a non-admin's edits go to a private
      * session working copy, not here (ADR-032). Both levels are `WeakMap`s so
-     * entries collect normally — no manual invalidation needed.
+     * entries collect normally — no manual invalidation needed, which is why this
+     * is a memo and not a cache with a lifecycle to expose.
      */
-    trackConfigHydrationCache: WeakMap<object, WeakMap<object, unknown>>;
+    hydratedTrackConfig(schemaType: IAnyType, frozen: object, build: () => unknown): unknown;
     constructor(initialPlugins?: (Plugin | PluginLoadRecord | RuntimePluginLoadRecord)[]);
     pluginConfigurationNamespacedSchemas(): Record<string, unknown>;
     pluginConfigurationUnnamespacedSchemas(): Record<string, unknown>;
@@ -330,7 +359,11 @@ export default class PluginManager {
     getRpcElements(): RpcMethodType[];
     getDisplayElements(): DisplayType[];
     getAdapterElements(): AdapterType[];
-    /** get a MST type for the union of all specified pluggable MST types */
+    /**
+     * get a MST type for the union of all specified pluggable MST types.
+     * Membership is late-bound, so a lazily registered state model joins when
+     * its loader resolves; a snapshot naming one cannot be cast until then.
+     */
     pluggableMstType(groupName: PluggableElementTypeGroup, fieldName: string, fallback?: IAnyType): IAnyType;
     /** get a MST type for the union of all specified pluggable config schemas */
     pluggableConfigSchemaType(typeGroup: PluggableElementTypeGroup, fieldName?: string): IAnyType;
@@ -357,7 +390,27 @@ export default class PluginManager {
     getTextSearchAdapterType(typeName: string): TextSearchAdapterType;
     getTrackType(typeName: string): TrackType;
     getDisplayType(typeName: string): DisplayType;
+    getViewType<N extends ViewTypeName>(typeName: N): Omit<ViewType, 'stateModel'> & {
+        stateModel: ViewTypeRegistry[N];
+    };
     getViewType(typeName: string): ViewType;
+    private sessionTypeNames;
+    /**
+     * Every async code path that hands a snapshot to a synchronous session
+     * instantiation (`setSession`, `cast`) must await this first.
+     */
+    preloadSessionTypes(sessionSnapshot: unknown): Promise<void>;
+    unloadedSessionTypes(sessionSnapshot: unknown): string[];
+    /**
+     * Without this, a snapshot naming an unloaded lazy type fails inside MST as
+     * a union mismatch that reads like a corrupt snapshot.
+     */
+    assertSessionTypesLoaded(sessionSnapshot: unknown): void;
+    /**
+     * Aliases resolve here because a legacy session names the alias, and the
+     * model that remaps it cannot be consulted before it is loaded.
+     */
+    resolveDisplayTypeRecord(name: string): DisplayType | undefined;
     getAddTrackWorkflow(typeName: string): AddTrackWorkflowType;
     getWidgetType(typeName: string): WidgetType;
     getConnectionType(typeName: string): ConnectionType;

package/esm/PluginManager.js

@@ -113,26 +113,41 @@ export default class PluginManager {
     // singular component points are re-evaluated on every render, so the
     // clobber warning is emitted once per point per app
     warnedClobber = new Set();
+    #trackConfigHydrationCache = new WeakMap();
     /**
-     * Lazy-hydration cache for `TrackConfigurationReference`/
-     * `DisplayConfigurationReference` (configuration/configurationSchema.ts).
+     * The lazily-hydrated MST config node for one frozen track config, built by
+     * `build` on first ask and returned by identity after that.
+     * `configuration/configurationSchema.ts` is the only caller.
+     *
      * `jbrowse.tracks` is `types.frozen` for large-tracklist performance, so a
-     * track config is a plain JS object until first referenced; hydrating it
-     * into an MST node is deferred to that read. MST's custom-reference
-     * `getValue` has no memoization of its own — it reruns on every property
-     * access — so without this cache, every read of `track.configuration` would
-     * fabricate a fresh, non-identical MST node. Keyed by schemaType (each track
-     * type's config schema is rebuilt fresh per PluginManager instance, see
-     * addTrackType) then by the frozen object itself, so a cache hit can only
-     * ever come from this same PluginManager instance and this same track type.
-     * See ADR-031.
+     * track config is a plain JS object until first referenced; hydrating it into
+     * an MST node is deferred to that read. MST's custom-reference `getValue` has
+     * no memoization of its own — it reruns on every property access — so without
+     * this, every read of `track.configuration` would fabricate a fresh,
+     * non-identical node. Keyed by schemaType (each track type's config schema is
+     * rebuilt fresh per PluginManager instance, see addTrackType) then by the
+     * frozen object, so a hit can only ever come from this same instance and this
+     * same track type. See ADR-031.
      *
-     * This node is never mutated: admin edits replace the frozen entry (new
+     * The node is never mutated: admin edits replace the frozen entry (new
      * identity drops the WeakMap entry), and a non-admin's edits go to a private
      * session working copy, not here (ADR-032). Both levels are `WeakMap`s so
-     * entries collect normally — no manual invalidation needed.
+     * entries collect normally — no manual invalidation needed, which is why this
+     * is a memo and not a cache with a lifecycle to expose.
      */
-    trackConfigHydrationCache = new WeakMap();
+    hydratedTrackConfig(schemaType, frozen, build) {
+        let byFrozen = this.#trackConfigHydrationCache.get(schemaType);
+        if (!byFrozen) {
+            byFrozen = new WeakMap();
+            this.#trackConfigHydrationCache.set(schemaType, byFrozen);
+        }
+        let node = byFrozen.get(frozen);
+        if (!node) {
+            node = build();
+            byFrozen.set(frozen, node);
+        }
+        return node;
+    }
     constructor(initialPlugins = []) {
         // add the core plugin
         this.addPlugin({
@@ -326,16 +341,36 @@ export default class PluginManager {
     getAdapterElements() {
         return this.getElementTypesInGroup('adapter');
     }
-    /** get a MST type for the union of all specified pluggable MST types */
+    /**
+     * get a MST type for the union of all specified pluggable MST types.
+     * Membership is late-bound, so a lazily registered state model joins when
+     * its loader resolves; a snapshot naming one cannot be cast until then.
+     */
     pluggableMstType(groupName, fieldName, fallback = types.maybe(types.null)) {
-        const pluggableTypes = this.getElementTypeRecord(groupName)
+        const record = this.getElementTypeRecord(groupName);
+        const anyMember = record.all().some(t => {
+            const element = t;
+            const field = element[fieldName];
+            return ((isType(field) && isModelType(field)) ||
+                typeof element[`${fieldName}Loader`] === 'function');
+        });
+        if (!anyMember) {
+            return fallback;
+        }
+        const modelsOf = () => record
             .all()
             .map(t => t[fieldName])
             .filter(t => isType(t) && isModelType(t));
-        if (pluggableTypes.length === 0) {
-            return fallback;
-        }
-        return types.union(...pluggableTypes);
+        let members = modelsOf();
+        return types.union({
+            name: `pluggable(${groupName} ${fieldName})`,
+            members: () => {
+                if (members.length !== modelsOf().length) {
+                    members = modelsOf();
+                }
+                return members;
+            },
+        });
     }
     /** get a MST type for the union of all specified pluggable config schemas */
     pluggableConfigSchemaType(typeGroup, fieldName = 'configSchema') {
@@ -422,6 +457,102 @@ export default class PluginManager {
     getViewType(typeName) {
         return this.viewTypes.get(typeName);
     }
+    sessionTypeNames(sessionSnapshot) {
+        const viewNames = new Set();
+        const displayNames = new Set();
+        const collectTracks = (tracks) => {
+            if (Array.isArray(tracks)) {
+                for (const track of tracks) {
+                    const { displays } = track && typeof track === 'object'
+                        ? track
+                        : {};
+                    if (Array.isArray(displays)) {
+                        for (const display of displays) {
+                            const type = display && typeof display === 'object'
+                                ? display.type
+                                : undefined;
+                            if (typeof type === 'string') {
+                                displayNames.add(type);
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        const collectViews = (views) => {
+            if (Array.isArray(views)) {
+                for (const view of views) {
+                    if (view && typeof view === 'object') {
+                        const { type, views: children, tracks, levels, } = view;
+                        if (typeof type === 'string') {
+                            viewNames.add(type);
+                        }
+                        collectViews(children);
+                        collectTracks(tracks);
+                        if (Array.isArray(levels)) {
+                            for (const level of levels) {
+                                collectTracks(level && typeof level === 'object'
+                                    ? level.tracks
+                                    : undefined);
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        if (sessionSnapshot && typeof sessionSnapshot === 'object') {
+            const { view, views } = sessionSnapshot;
+            collectViews(views);
+            collectViews(view ? [view] : undefined);
+        }
+        return { viewNames, displayNames };
+    }
+    /**
+     * Every async code path that hands a snapshot to a synchronous session
+     * instantiation (`setSession`, `cast`) must await this first.
+     */
+    async preloadSessionTypes(sessionSnapshot) {
+        const { viewNames, displayNames } = this.sessionTypeNames(sessionSnapshot);
+        await Promise.all([
+            ...[...viewNames]
+                .filter(name => this.viewTypes.has(name))
+                .map(name => this.getViewType(name).loadStateModel()),
+            ...[...displayNames]
+                .map(name => this.resolveDisplayTypeRecord(name))
+                .flatMap(display => (display ? [display.loadStateModel()] : [])),
+        ]);
+    }
+    unloadedSessionTypes(sessionSnapshot) {
+        const { viewNames, displayNames } = this.sessionTypeNames(sessionSnapshot);
+        return [
+            ...[...viewNames].filter(name => this.viewTypes.has(name) &&
+                !this.getViewType(name).isStateModelLoaded),
+            ...[...displayNames].filter(name => {
+                const display = this.resolveDisplayTypeRecord(name);
+                return display !== undefined && !display.isStateModelLoaded;
+            }),
+        ];
+    }
+    /**
+     * Without this, a snapshot naming an unloaded lazy type fails inside MST as
+     * a union mismatch that reads like a corrupt snapshot.
+     */
+    assertSessionTypesLoaded(sessionSnapshot) {
+        const unloaded = this.unloadedSessionTypes(sessionSnapshot);
+        if (unloaded.length > 0) {
+            throw new Error(`session names lazily loaded types that are not loaded yet: ${unloaded.join(', ')}. Await pluginManager.preloadSessionTypes(snapshot) before setting the session`);
+        }
+    }
+    /**
+     * Aliases resolve here because a legacy session names the alias, and the
+     * model that remaps it cannot be consulted before it is loaded.
+     */
+    resolveDisplayTypeRecord(name) {
+        if (this.displayTypes.has(name)) {
+            return this.getDisplayType(name);
+        }
+        return this.getDisplayElements().find(d => d.aliases?.includes(name));
+    }
     getAddTrackWorkflow(typeName) {
         return this.addTrackWidgets.get(typeName);
     }