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

package/esm/PluginManager.js

@@ -3,6 +3,7 @@ import CorePlugin from './CorePlugin.js';
 import PhasedScheduler from './PhasedScheduler.js';
 import { getReExportRegistry } from './ReExports/registry.js';
 import { ConfigurationSchema, isBareConfigurationSchemaType, } from './configuration/index.js';
+import LazyStateModelElement from './pluggableElementTypes/LazyStateModelElement.js';
 import createJexlInstance from './util/jexl.js';
 import { expandLooseTrackConfig } from './util/tracks.js';
 /**
@@ -24,6 +25,20 @@ export const pluggableElementTypeGroups = [
     'internet account',
     'add track workflow',
 ];
+function pluggableUnionName(groupName, fieldName) {
+    return `pluggable(${groupName} ${fieldName})`;
+}
+/**
+ * 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 function pluggableStateModelGroup(type) {
+    return pluggableElementTypeGroups.find(group => type.name === pluggableUnionName(group, 'stateModel'));
+}
+function isUnloadedLazyElement(element) {
+    return element instanceof LazyStateModelElement && !element.isStateModelLoaded;
+}
 /** internal class that holds the info for a certain element type */
 class TypeRecord {
     registeredTypes = {};
@@ -90,6 +105,17 @@ function nextAccumulator(name, accumulator, result) {
 function logCallbackError(name, error) {
     console.error(`error in a ${name} extension point callback`, error);
 }
+/**
+ * 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 function corePluginRecords(plugins) {
+    return plugins.map(P => ({ plugin: new P(), metadata: { isCore: true } }));
+}
 export default class PluginManager {
     plugins = [];
     jexl = createJexlInstance();
@@ -113,26 +139,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({
@@ -292,9 +333,28 @@ export default class PluginManager {
                 console.warn(`${groupName} ${newElement.name} already registered, cannot register it again`);
             }
             else {
-                typeRecord.add(newElement.name, this.evaluateExtensionPoint(
+                const extend = () => this.evaluateExtensionPoint(
                 /** #extensionPoint Core-extendPluggableElement | sync | Mutate any pluggable element after it is created */
-                'Core-extendPluggableElement', newElement, { group: groupName }));
+                'Core-extendPluggableElement', newElement, { group: groupName });
+                // A lazily registered state model is not there for a callback to
+                // extend yet, so the point fires when the loader resolves instead.
+                // agent-docs/reference/EAGER_BUNDLE.md
+                if (isUnloadedLazyElement(newElement)) {
+                    newElement.onStateModelLoaded = () => {
+                        const extended = extend();
+                        if (extended !== newElement) {
+                            typeRecord.add(newElement.name, extended);
+                            if (extended instanceof LazyStateModelElement &&
+                                extended.isStateModelLoaded) {
+                                newElement.stateModel = extended.stateModel;
+                            }
+                        }
+                    };
+                    typeRecord.add(newElement.name, newElement);
+                }
+                else {
+                    typeRecord.add(newElement.name, extend());
+                }
             }
         });
         return this;
@@ -326,18 +386,43 @@ 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)
-            .all()
-            .map(t => t[fieldName])
-            .filter(t => isType(t) && isModelType(t));
-        if (pluggableTypes.length === 0) {
+        const record = this.getElementTypeRecord(groupName);
+        const fieldOf = (t) => isUnloadedLazyElement(t)
+            ? undefined
+            : t[fieldName];
+        const anyMember = record.all().some(t => {
+            const field = fieldOf(t);
+            return ((isType(field) && isModelType(field)) ||
+                typeof t[`${fieldName}Loader`] === 'function');
+        });
+        if (!anyMember) {
             return fallback;
         }
-        return types.union(...pluggableTypes);
+        const modelsOf = () => record
+            .all()
+            .map(t => fieldOf(t))
+            .filter(t => isType(t) && isModelType(t));
+        let members = modelsOf();
+        return types.union({
+            name: pluggableUnionName(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 */
+    /**
+     * The union of every registered config schema of a pluggable element group,
+     * whose instance reads as a config node naming its `type`.
+     */
     pluggableConfigSchemaType(typeGroup, fieldName = 'configSchema') {
         const pluggableTypes = this.getElementTypeRecord(typeGroup)
             .all()
@@ -346,21 +431,19 @@ export default class PluginManager {
         if (pluggableTypes.length === 0) {
             pluggableTypes.push(ConfigurationSchema('Null', {}));
         }
-        // deliberately unannotated: this really is a union, not a model type, and
-        // the `as IAnyModelType` it used to carry was checked against the whole
-        // repo and needed by nothing. Claiming model-ness here is also what makes a
+        // a union, not a model type: claiming model-ness here is what made a
         // schema taking its base from this look concrete while its own slot reads
-        // have already degraded to `any` — see configuration/CLAUDE.md.
+        // had already degraded to `any` — see configuration/CLAUDE.md.
         const union = types.union(...pluggableTypes);
         // A track union dispatches on `type`, so the loose `{ trackId, uri }` form
         // has to become a full config before the union sees it. Here rather than
         // at each array that holds tracks, so a session track, a connection track
         // and a direct `create` all take it.
-        return typeGroup === 'track'
+        return (typeGroup === 'track'
             ? types.snapshotProcessor(union, {
                 preProcessor: (snap) => expandLooseTrackConfig(snap, this),
             })
-            : union;
+            : union);
     }
     jbrequireCache = new Map();
     // populated by PluginLoader once a runtime plugin is actually being loaded,
@@ -384,7 +467,7 @@ export default class PluginManager {
         if (typeof lib === 'string') {
             const pack = this.lib[lib];
             if (!pack) {
-                throw new TypeError(`No jbrequire re-export defined for package '${lib}'. If this package must be shared between plugins, add it to ReExports/list.ts. If it does not need to be shared, just import it normally.`);
+                throw new TypeError(`No jbrequire re-export defined for '${lib}'. The host serves what @jbrowse/core/ReExports/list names: the framework singletons, Material UI, and every subpath the bundled @jbrowse packages publish. Anything else, bundle into the plugin.`);
             }
             return pack;
         }
@@ -422,6 +505,71 @@ export default class PluginManager {
     getViewType(typeName) {
         return this.viewTypes.get(typeName);
     }
+    /**
+     * 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.
+     */
+    sessionElementTypes(sessionSnapshot) {
+        const names = new Set();
+        const walk = (node) => {
+            if (Array.isArray(node)) {
+                for (const item of node) {
+                    walk(item);
+                }
+            }
+            else if (node && typeof node === 'object') {
+                for (const [key, value] of Object.entries(node)) {
+                    if (key === 'type' && typeof value === 'string') {
+                        names.add(value);
+                    }
+                    else {
+                        walk(value);
+                    }
+                }
+            }
+        };
+        walk(sessionSnapshot);
+        return [...names].flatMap(name => {
+            const display = this.resolveDisplayTypeRecord(name);
+            return [
+                ...(this.viewTypes.has(name) ? [this.getViewType(name)] : []),
+                ...(display ? [display] : []),
+            ];
+        });
+    }
+    /**
+     * Every async code path that hands a snapshot to a synchronous session
+     * instantiation (`setSession`, `cast`) must await this first.
+     */
+    async preloadSessionTypes(sessionSnapshot) {
+        await Promise.all(this.sessionElementTypes(sessionSnapshot).map(t => t.loadStateModel()));
+    }
+    unloadedSessionTypes(sessionSnapshot) {
+        return this.sessionElementTypes(sessionSnapshot)
+            .filter(t => !t.isStateModelLoaded)
+            .map(t => t.name);
+    }
+    /**
+     * 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);
     }
@@ -451,7 +599,7 @@ export default class PluginManager {
             const displays = this.getElementTypesInGroup('display');
             for (const display of displays) {
                 // track may have already added the displayType in its cb
-                if (display.trackType === track.name &&
+                if ([display.trackType].flat().includes(track.name) &&
                     !track.displayTypes.includes(display)) {
                     track.addDisplayType(display);
                 }

package/esm/ReExports/MuiDataGridReExports.d.ts

@@ -1,2 +1,3 @@
 import type { ComponentType } from 'react';
+export declare const DATA_GRID_NAMES: string[];
 export declare const DataGridEntries: Record<string, ComponentType<any>>;

package/esm/ReExports/MuiDataGridReExports.js

@@ -3,7 +3,7 @@ import { lazy } from 'react';
 // export off it, so they're generated from a name list rather than written out
 // 45 times. The static import specifier means webpack still emits a single
 // x-data-grid chunk shared by all entries.
-const names = [
+export const DATA_GRID_NAMES = [
     'DataGrid',
     'GridActionsCellItem',
     'GridAddIcon',
@@ -51,7 +51,7 @@ const names = [
     'GridViewHeadlineIcon',
     'GridViewStreamIcon',
 ];
-export const DataGridEntries = Object.fromEntries(names.map(name => [
+export const DataGridEntries = Object.fromEntries(DATA_GRID_NAMES.map(name => [
     name,
     lazy(() => import('@mui/x-data-grid').then(m => ({
         default: m[name],

package/esm/ReExports/coreModules.generated.d.ts

@@ -0,0 +1,2 @@
+declare const libs: Record<string, unknown>;
+export default libs;