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

package/esm/PluginLoader.js

@@ -1,6 +1,6 @@
-import { setReExportRegistry } from './ReExports/registry.js';
-import { isCJSPluginDefinition, isESMPluginDefinition, isUMDPluginDefinition, pluginDescriptionString, } from './pluginDefinitions.js';
-import { isElectron } from './util/index.js';
+import { enableContractReports } from '@jbrowse/render-core/contractReports';
+import { loudOnMissingModule, setReExportRegistry, } from './ReExports/registry.js';
+import { isESMPluginDefinition, isUMDPluginDefinition, maybePluginUrl, pluginDescriptionString, pluginLabel, } from './pluginDefinitions.js';
 import { isWebWorker } from './util/isWebWorker.js';
 /**
  * A definition names exactly one loader. More than one is malformed — no real
@@ -11,7 +11,6 @@ import { isWebWorker } from './util/isWebWorker.js';
  */
 function assertSingleKind(def) {
     const kinds = [
-        isCJSPluginDefinition(def) ? 'CJS' : undefined,
         isESMPluginDefinition(def) ? 'ESM' : undefined,
         isUMDPluginDefinition(def) ? 'UMD' : undefined,
     ].filter(kind => kind !== undefined);
@@ -19,6 +18,20 @@ function assertSingleKind(def) {
         throw new Error(`Plugin definition names more than one plugin type (${kinds.join(', ')}), refusing to load: ${JSON.stringify(def)}`);
     }
 }
+/**
+ * A `cjsUrl` definition loaded by writing the bundle to a temp file and
+ * `require`ing it in Electron's renderer, the one loader that needed Node. That
+ * renderer runs UMD and ESM, and a plugin reaching the main process does it
+ * through `window.require('electron')` whatever format it ships in, so the
+ * format bought nothing its two peers do not. Name the successor rather than
+ * letting the definition fall through to "could not determine plugin type",
+ * which reads as a malformed config.
+ */
+function assertRetiredKinds(def) {
+    if ('cjsUrl' in def) {
+        throw new Error(`CJS plugins are no longer loaded (${String(def.cjsUrl)}). Publish the plugin as UMD or ESM and name it with umdUrl or esmUrl.`);
+    }
+}
 function promisifiedLoadScript(src, integrity) {
     return new Promise((resolve, reject) => {
         const script = document.createElement('script');
@@ -45,22 +58,48 @@ 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}`;
+}
+const workerPrefetches = new Map();
+/**
+ * `importScripts` blocks until its file arrives, so a worker loading its
+ * plugins with it waited one round trip per plugin, in a row. Fetching them all
+ * first makes each `importScripts` a cache read — provided the fetch is the
+ * request `importScripts` makes: no-cors, with credentials. Chrome and Firefox
+ * both re-download for any other mode (probe-worker-script-cache.ts).
+ */
+function prefetchWorkerScript(url) {
+    if (!workerPrefetches.has(url)) {
+        workerPrefetches.set(url, fetch(url, { mode: 'no-cors', credentials: 'include' })
+            .then(r => r.arrayBuffer())
+            .then(() => { }, () => { }));
+    }
+}
 async function loadScript(scriptUrl, integrity) {
     const scope = globalThis;
     if (!isWebWorker()) {
         return promisifiedLoadScript(scriptUrl, integrity);
     }
     else if (hasImportScripts(scope)) {
+        await workerPrefetches.get(scriptUrl);
         try {
             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 +136,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;
@@ -105,22 +172,66 @@ function addCacheBuster(url) {
     u.searchParams.set('_cb', Date.now().toString());
     return u.href;
 }
+function umdPluginUrl(def, baseUri) {
+    return 'url' in def
+        ? resolvePluginUrl(def.url, baseUri)
+        : 'umdUrl' in def
+            ? resolvePluginUrl(def.umdUrl, baseUri)
+            : resolvePluginUrl(def.umdLoc.uri, def.umdLoc.baseUri);
+}
+/**
+ * The registry has to be published before a plugin bundle runs, but not before
+ * it downloads, so each bundle is preloaded while the registry is fetched.
+ * Skipped under the cache-buster, whose query string differs per request.
+ *
+ * Exported for a worker told its plugins ahead of its boot configuration.
+ */
+export function preloadUMDBundles(defs, baseUri) {
+    if ('__jbrowseCacheBuster' in globalThis) {
+        return;
+    }
+    if (isWebWorker()) {
+        for (const def of defs) {
+            if (isUMDPluginDefinition(def)) {
+                try {
+                    prefetchWorkerScript(umdPluginUrl(def, baseUri).href);
+                }
+                catch {
+                    // loadPlugin reports a url it cannot resolve
+                }
+            }
+        }
+        return;
+    }
+    if (typeof document === 'undefined') {
+        return;
+    }
+    for (const def of defs) {
+        if (isUMDPluginDefinition(def)) {
+            try {
+                const link = document.createElement('link');
+                link.rel = 'preload';
+                link.as = 'script';
+                if (def.integrity) {
+                    link.setAttribute('integrity', def.integrity);
+                    link.setAttribute('crossorigin', 'anonymous');
+                }
+                link.href = umdPluginUrl(def, baseUri).href;
+                document.head.append(link);
+            }
+            catch {
+                // loadPlugin reports a url it cannot resolve
+            }
+        }
+    }
+}
 export default class PluginLoader {
     definitions = [];
     fetchESM;
-    fetchCJS;
     constructor(defs = [], args) {
         this.fetchESM = args?.fetchESM;
-        this.fetchCJS = args?.fetchCJS;
         this.definitions = structuredClone(defs);
     }
-    async loadCJSPlugin(def, baseUri) {
-        const parsedUrl = resolvePluginUrl(def.cjsUrl, baseUri);
-        if (!this.fetchCJS) {
-            throw new Error('No fetchCJS callback provided');
-        }
-        return this.fetchCJS(parsedUrl.href);
-    }
     async loadESMPlugin(def, baseUri) {
         const parsedUrl = 'esmUrl' in def
             ? resolvePluginUrl(def.esmUrl, baseUri)
@@ -136,11 +247,7 @@ export default class PluginLoader {
         return plugin;
     }
     async loadUMDPlugin(def, baseUri) {
-        const parsedUrl = 'url' in def
-            ? resolvePluginUrl(def.url, baseUri)
-            : 'umdUrl' in def
-                ? resolvePluginUrl(def.umdUrl, baseUri)
-                : resolvePluginUrl(def.umdLoc.uri, def.umdLoc.baseUri);
+        const parsedUrl = umdPluginUrl(def, baseUri);
         const moduleName = def.name;
         const umdName = `JBrowsePlugin${moduleName}`;
         // a cache buster query string would change the bytes the browser hashes for
@@ -154,15 +261,11 @@ export default class PluginLoader {
         return plugin;
     }
     async loadPlugin(def, baseUri) {
+        assertRetiredKinds(def);
         assertSingleKind(def);
+        armIfUnderDevelopment(def);
         let plugin;
-        if (isCJSPluginDefinition(def)) {
-            if (!isElectron) {
-                throw new Error(`CommonJS plugin found, but not in a NodeJS environment: ${JSON.stringify(def)}`);
-            }
-            plugin = await this.loadCJSPlugin(def, baseUri);
-        }
-        else if (isESMPluginDefinition(def)) {
+        if (isESMPluginDefinition(def)) {
             plugin = await this.loadESMPlugin(def, baseUri);
         }
         else if (isUMDPluginDefinition(def)) {
@@ -177,35 +280,36 @@ export default class PluginLoader {
         }
         return plugin.default;
     }
-    reExportTarget;
+    reExports;
     /**
      * Ask for the runtime ABI (`JBrowseExports`) to be published on `target`
-     * before any plugin bundle is evaluated. Records the target; the registry
-     * itself is fetched in `loadSettled` below.
+     * before any plugin bundle is evaluated. Records the target and the loader;
+     * `loadSettled` fetches the registry, a ~126 KB gzipped module only a runtime
+     * plugin can use (see `ReExports/registry.ts` for why it cannot shrink).
      *
-     * The split is the point. Every product calls this at startup, synchronously,
-     * whether or not the config names a plugin — so importing the registry here
-     * put it in every host's first paint. It is a ~126 KB gzipped module (see
-     * `ReExports/registry.ts` for why it cannot shrink) that only a runtime plugin
-     * can use, and loading one is async anyway.
+     * `registry` is the product's generated map — `reExports.generated.ts` on
+     * the main thread, `workerReExports.generated.ts` in its worker — which
+     * serves every `@jbrowse` package the product bundles. The caller names it
+     * because the registry serves this module: an `import()` of it from here is
+     * a cycle rolldown keeps in any host bundling this file, whether or not
+     * anything loads a plugin (EAGER_BUNDLE.md §3).
      */
-    installGlobalReExports(target) {
-        this.reExportTarget = target;
+    installGlobalReExports(target, registry) {
+        this.reExports = { target, registry };
         return this;
     }
     async publishReExports() {
-        const target = this.reExportTarget;
-        if (!target) {
+        if (!this.reExports) {
             return;
         }
-        const { default: ReExports } = await import('./ReExports/index.js');
-        target.JBrowseExports = {
-            ...ReExports,
-        };
+        const { target, registry } = this.reExports;
+        const { default: ReExports } = await registry();
+        target.JBrowseExports =
+            loudOnMissingModule({ ...ReExports });
         // the synchronous half: `pluginManager.jbrequire(name)` is what a CJS
         // plugin calls, and it cannot await
         setReExportRegistry(ReExports);
-        this.reExportTarget = undefined;
+        this.reExports = undefined;
     }
     /**
      * Loads every definition and separates the ones that worked from the ones
@@ -224,6 +328,7 @@ export default class PluginLoader {
      * fail renders with a much worse message) keep using `load`.
      */
     async loadSettled(baseUri) {
+        preloadUMDBundles(this.definitions, baseUri);
         // before the first plugin script evaluates — a UMD bundle reads
         // `JBrowseExports` off the global at module scope
         await this.publishReExports();
@@ -249,9 +354,20 @@ export default class PluginLoader {
     async load(baseUri) {
         const { records, failures } = await this.loadSettled(baseUri);
         // rethrown by definition order rather than by which rejected first, so the
-        // error a strict caller sees doesn't depend on network timing
-        if (failures[0]) {
-            throw failures[0].error;
+        // error a strict caller sees doesn't depend on network timing.
+        //
+        // Named, because the RPC worker calls this: a plugin that throws while
+        // evaluating takes the whole RpcServer with it, and the bare error is
+        // whatever the bundle's module scope said — `Cannot read properties of
+        // undefined`, or the missing ABI key — with nothing saying which plugin
+        // read it. The message is carried rather than the error, since this one
+        // crosses postMessage and `serializeError` cannot clone an arbitrary
+        // `cause`.
+        const failure = failures[0];
+        if (failure) {
+            const { definition, error } = failure;
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`plugin ${pluginLabel(definition)} failed: ${detail}`);
         }
         return records;
     }

package/esm/PluginManager.d.ts

@@ -1,6 +1,8 @@
 import PhasedScheduler from './PhasedScheduler.ts';
 import './util/tracks.ts';
 import type Plugin from './Plugin.ts';
+import type { PluginConstructor } from './Plugin.ts';
+import type { PluggableConfigNode } from './configuration/index.ts';
 import type AdapterType from './pluggableElementTypes/AdapterType.ts';
 import type AddTrackWorkflowType from './pluggableElementTypes/AddTrackWorkflowType.ts';
 import type ConnectionType from './pluggableElementTypes/ConnectionType.ts';
@@ -20,8 +22,14 @@ 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, IAnyType, IStateTreeNode, IType, SnapshotIn } from '@jbrowse/mobx-state-tree';
 import type { ComponentType, ReactNode } from 'react';
+/**
+ * What `pluggableConfigSchemaType` builds: a union whose members are checked
+ * at runtime, read as a config node carrying the `type` every member names
+ * itself by; a member's other slots read through `getConf`.
+ */
+export type PluggableConfigSchemaType = IType<any, any, PluggableConfigNode>;
 /**
  * Every pluggable element group, in the order `elementCreationSchedule` builds
  * them. The array is the declaration and the union is derived from it, so a
@@ -31,6 +39,12 @@ import type { ComponentType, ReactNode } from 'react';
  */
 export declare const pluggableElementTypeGroups: readonly ['adapter', 'text search adapter', 'display', 'track', 'connection', 'view', 'widget', 'rpc method', 'internet account', 'add track workflow'];
 export type PluggableElementTypeGroup = (typeof pluggableElementTypeGroups)[number];
+/**
+ * The group a `pluggableMstType(group, 'stateModel')` union holds, read off
+ * its name: with every member a lazy model not yet loaded, the union has no
+ * members to recognise it by.
+ */
+export declare function pluggableStateModelGroup(type: IAnyType): "adapter" | "add track workflow" | "connection" | "display" | "internet account" | "rpc method" | "text search adapter" | "track" | "view" | "widget" | undefined;
 /** internal class that holds the info for a certain element type */
 declare class TypeRecord<ElementClass extends PluggableElementBase> {
     registeredTypes: Record<string, ElementClass>;
@@ -110,8 +124,10 @@ type WidgetModel = FeatureWidgetModel & {
 export interface FeaturePanelProps {
     /** has `trackId` and `trackType` */
     model: FeatureWidgetModel;
-    /** snapshot of the feature being shown */
+    /** snapshot of the feature being shown, as `formatDetails` reshaped it */
     feature: SimpleFeatureSerialized;
+    /** the same feature before `formatDetails` ran */
+    unformatted?: SimpleFeatureSerialized;
     /**
      * how far down the subfeature tree this card is: 0 is the feature the user
      * clicked, 1 its subfeatures, and so on. The point fires for every card, so a
@@ -137,7 +153,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 +175,33 @@ 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>;
+/**
+ * what a plugin knows of an assembly the session does not hold, answered
+ * without connecting anything: its assembly config as the config holding it
+ * writes it, a relative uri carrying the `baseUri` it resolves against, and
+ * the adapter of its gene track. A multi-way synteny display holds the
+ * assembly as a temporary one while it draws that genome's lane, so renaming
+ * reaches its sequence and aliases the way it reaches any assembly's
+ */
+export interface AssemblyDescription {
+    assembly?: Record<string, unknown>;
+    geneAdapter?: Record<string, unknown>;
+}
 export interface ExtensionPointRegistry {
     'Core-extendSession': {
         args: IAnyModelType;
@@ -167,6 +221,14 @@ export interface ExtensionPointRegistry {
             session?: unknown;
         };
     };
+    'Core-describeAssemblies': {
+        args: Record<string, AssemblyDescription>;
+        result: Record<string, AssemblyDescription>;
+        props: {
+            assemblyNames: string[];
+            session?: unknown;
+        };
+    };
     'Core-extendPluggableElement': {
         args: PluggableElementType;
         result: PluggableElementType;
@@ -264,18 +326,28 @@ export interface PluginLoadRecord {
     metadata?: PluginMetadata;
     plugin: Plugin;
 }
+/**
+ * Instantiate an application's bundled plugin list as `isCore` load records —
+ * what tells the plugin store these came with the bundle rather than being
+ * installed by the user, so `InstalledPluginsList` filters them out and the
+ * About widget lists them. Every product and every test harness builds its
+ * manager from one of these lists, and a harness that passed bare instances
+ * silently disagreed with the app it was testing.
+ */
+export declare function corePluginRecords(plugins: PluginConstructor[]): PluginLoadRecord[];
 export interface RuntimePluginLoadRecord extends PluginLoadRecord {
     definition: PluginDefinition;
 }
 export default class PluginManager {
+    #private;
     plugins: Plugin[];
     jexl: import("@jbrowse/jexl").Jexl;
     pluginMetadata: Record<string, PluginMetadata>;
     runtimePluginDefinitions: PluginDefinition[];
     elementCreationSchedule: PhasedScheduler<"adapter" | "add track workflow" | "connection" | "display" | "internet account" | "rpc method" | "text search adapter" | "track" | "view" | "widget">;
     pluggableElementsCreated: boolean;
-    adapterTypes: TypeRecord<AdapterType>;
-    textSearchAdapterTypes: TypeRecord<TextSearchAdapterType>;
+    adapterTypes: TypeRecord<AdapterType<any>>;
+    textSearchAdapterTypes: TypeRecord<TextSearchAdapterType<any>>;
     trackTypes: TypeRecord<TrackType>;
     displayTypes: TypeRecord<DisplayType>;
     connectionTypes: TypeRecord<ConnectionType>;
@@ -289,25 +361,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,10 +404,17 @@ 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;
+    /**
+     * The union of every registered config schema of a pluggable element group,
+     * whose instance reads as a config node naming its `type`.
+     */
+    pluggableConfigSchemaType(typeGroup: PluggableElementTypeGroup, fieldName?: string): PluggableConfigSchemaType;
     jbrequireCache: Map<any, any>;
     get lib(): Record<string, unknown>;
     load: <FTYPE extends AnyFunction>(lib: FTYPE) => ReturnType<FTYPE>;
@@ -346,7 +427,7 @@ export default class PluginManager {
     jbrequire: (lib: string | AnyFunction | {
         default: AnyFunction;
     }) => any;
-    getAdapterType(typeName: string): AdapterType;
+    getAdapterType(typeName: string): AdapterType<any>;
     /**
      * Whether an adapter type is registered, for a caller walking a config where
      * `type` names a track, a display and an adapter alike — `getAdapterType`
@@ -354,10 +435,35 @@ export default class PluginManager {
      * claims to be an adapter and wrong when you are asking whether it is one.
      */
     hasAdapterType(typeName: string): boolean;
-    getTextSearchAdapterType(typeName: string): TextSearchAdapterType;
+    getTextSearchAdapterType(typeName: string): TextSearchAdapterType<any>;
     getTrackType(typeName: string): TrackType;
     getDisplayType(typeName: string): DisplayType;
+    getViewType<N extends ViewTypeName>(typeName: N): Omit<ViewType, 'stateModel'> & {
+        stateModel: ViewTypeRegistry[N];
+    };
     getViewType(typeName: string): ViewType;
+    /**
+     * The registered view and display types a snapshot names, from every `type`
+     * string anywhere in it — `heldForMissingPlugins` included. Over-collection
+     * is harmless: a name that resolves to neither is dropped here.
+     */
+    private sessionElementTypes;
+    /**
+     * 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;