@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/PluginManager.js

@@ -1,28 +1,35 @@
 import { isModelType, isType, types } from '@jbrowse/mobx-state-tree';
-import CorePlugin from "./CorePlugin.js";
-import PhasedScheduler from "./PhasedScheduler.js";
-import ReExports from "./ReExports/index.js";
-import { ConfigurationSchema, isBareConfigurationSchemaType, } from "./configuration/index.js";
-import AdapterType from "./pluggableElementTypes/AdapterType.js";
-import AddTrackWorkflowType from "./pluggableElementTypes/AddTrackWorkflowType.js";
-import ConnectionType from "./pluggableElementTypes/ConnectionType.js";
-import DisplayType from "./pluggableElementTypes/DisplayType.js";
-import GlyphType from "./pluggableElementTypes/GlyphType.js";
-import InternetAccountType from "./pluggableElementTypes/InternetAccountType.js";
-import RpcMethodType from "./pluggableElementTypes/RpcMethodType.js";
-import TextSearchAdapterType from "./pluggableElementTypes/TextSearchAdapterType.js";
-import TrackType from "./pluggableElementTypes/TrackType.js";
-import ViewType from "./pluggableElementTypes/ViewType.js";
-import WidgetType from "./pluggableElementTypes/WidgetType.js";
-import RendererType from "./pluggableElementTypes/renderers/RendererType.js";
-import createJexlInstance from "./util/jexl.js";
+import CorePlugin from './CorePlugin.js';
+import PhasedScheduler from './PhasedScheduler.js';
+import { getReExportRegistry } from './ReExports/registry.js';
+import { ConfigurationSchema, isBareConfigurationSchemaType, } from './configuration/index.js';
+import createJexlInstance from './util/jexl.js';
+import { expandLooseTrackConfig } from './util/tracks.js';
+/**
+ * Every pluggable element group, in the order `elementCreationSchedule` builds
+ * them. The array is the declaration and the union is derived from it, so a
+ * consumer that has to visit every group — `pruneUnbuildableNodes` walking a
+ * session snapshot for containers of a pluggable union — enumerates them at
+ * runtime instead of keeping a second hand-written list that goes stale.
+ */
+export const pluggableElementTypeGroups = [
+    'adapter',
+    'text search adapter',
+    'display',
+    'track',
+    'connection',
+    'view',
+    'widget',
+    'rpc method',
+    'internet account',
+    'add track workflow',
+];
+/** internal class that holds the info for a certain element type */
 class TypeRecord {
-    typeName;
-    baseClass;
     registeredTypes = {};
-    constructor(typeName, baseClass) {
+    typeName;
+    constructor(typeName) {
         this.typeName = typeName;
-        this.baseClass = baseClass;
     }
     add(name, t) {
         this.registeredTypes[name] = t;
@@ -30,44 +37,126 @@ class TypeRecord {
     has(name) {
         return name in this.registeredTypes;
     }
+    // The message a build with the wrong plugin set gets, and usually the ONLY
+    // one. The lookups that reach here are mostly registration-time and
+    // cross-plugin — `pm.getDisplayType('LinearAlignmentsDisplay')` from a track's
+    // install — so in an embedded product, whose consumer supplies the plugin
+    // array, this throw is what lands in `pluginManagerError` and replaces the
+    // whole app. Naming the missing type alone still leaves "which plugin" to
+    // guess, which is what the registered list answers: a build short one plugin
+    // is visibly short that plugin's group of names.
     get(name) {
-        if (!this.has(name)) {
-            throw new Error(`${this.typeName} '${name}' not found, perhaps its plugin is not loaded or its plugin has not added it.`);
+        const type = this.registeredTypes[name];
+        if (!type) {
+            throw new Error(`${this.typeName} '${name}' is not registered: a plugin providing it either failed to load or is not in this build's plugin list. Registered ${this.typeName}s: ${this.registeredNames()}`);
+        }
+        return type;
+    }
+    registeredNames() {
+        const names = Object.keys(this.registeredTypes).sort();
+        if (names.length === 0) {
+            // distinguishable from "the plugin is missing", and a different bug: a
+            // getter called before createPluggableElements() sees every record empty
+            return 'none at all, so this ran before createPluggableElements()';
         }
-        return this.registeredTypes[name];
+        const shown = names.slice(0, 25);
+        const rest = names.length - shown.length;
+        return rest > 0 ? `${shown.join(', ')}, and ${rest} more` : shown.join(', ');
     }
     all() {
         return Object.values(this.registeredTypes);
     }
 }
+/**
+ * Marks a component built by wrapping the one the extension point accumulated
+ * so far, so {@link PluginManager.evaluateComponentExtensionPoint} can tell
+ * composition (two plugins each wrapping, both still visible) from a genuine
+ * clobber (a second plugin discarding the first). Set by `wrapComponent`.
+ */
+export const wrappedComponent = Symbol.for('jbrowse.wrappedComponent');
+// a callback that forgets to return hands `undefined` to every later callback
+// and to the producer, which is a silent no-op the author has no way to see —
+// the accumulator survives instead, since "return what you were passed" is the
+// documented way to opt out
+function nextAccumulator(name, accumulator, result) {
+    let next = result;
+    if (result === undefined && accumulator !== undefined) {
+        console.warn(`a ${name} extension point callback returned undefined instead of the value it was passed, so its result was ignored`);
+        next = accumulator;
+    }
+    return next;
+}
+// a bare stack from minified plugin code names nothing, so say which point
+function logCallbackError(name, error) {
+    console.error(`error in a ${name} extension point callback`, error);
+}
 export default class PluginManager {
     plugins = [];
     jexl = createJexlInstance();
     pluginMetadata = {};
     runtimePluginDefinitions = [];
-    elementCreationSchedule = new PhasedScheduler('glyph', 'renderer', 'adapter', 'text search adapter', 'display', 'track', 'connection', 'view', 'widget', 'rpc method', 'internet account', 'add track workflow');
-    glyphTypes = new TypeRecord('GlyphType', GlyphType);
-    rendererTypes = new TypeRecord('RendererType', RendererType);
-    adapterTypes = new TypeRecord('AdapterType', AdapterType);
-    textSearchAdapterTypes = new TypeRecord('TextSearchAdapterType', TextSearchAdapterType);
-    trackTypes = new TypeRecord('TrackType', TrackType);
-    displayTypes = new TypeRecord('DisplayType', DisplayType);
-    connectionTypes = new TypeRecord('ConnectionType', ConnectionType);
-    viewTypes = new TypeRecord('ViewType', ViewType);
-    widgetTypes = new TypeRecord('WidgetType', WidgetType);
-    rpcMethods = new TypeRecord('RpcMethodType', RpcMethodType);
-    addTrackWidgets = new TypeRecord('AddTrackWorkflow', AddTrackWorkflowType);
-    internetAccountTypes = new TypeRecord('InternetAccountType', InternetAccountType);
+    elementCreationSchedule = new PhasedScheduler(...pluggableElementTypeGroups);
+    pluggableElementsCreated = false;
+    adapterTypes = new TypeRecord('AdapterType');
+    textSearchAdapterTypes = new TypeRecord('TextSearchAdapterType');
+    trackTypes = new TypeRecord('TrackType');
+    displayTypes = new TypeRecord('DisplayType');
+    connectionTypes = new TypeRecord('ConnectionType');
+    viewTypes = new TypeRecord('ViewType');
+    widgetTypes = new TypeRecord('WidgetType');
+    rpcMethods = new TypeRecord('RpcMethodType');
+    addTrackWidgets = new TypeRecord('AddTrackWorkflow');
+    internetAccountTypes = new TypeRecord('InternetAccountType');
     configured = false;
     rootModel;
     extensionPoints = new Map();
+    // 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();
+    /**
+     * 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, 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.
+     *
+     * 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, which is why this
+     * is a memo and not a cache with a lifecycle to expose.
+     */
+    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({
             plugin: new CorePlugin(),
             metadata: {
                 isCore: true,
             },
         });
+        // add all the initial plugins
         for (const plugin of initialPlugins) {
             this.addPlugin(plugin);
         }
@@ -82,25 +171,19 @@ export default class PluginManager {
         return configurationSchemas;
     }
     pluginConfigurationUnnamespacedSchemas() {
-        let configurationSchemas = {};
+        const configurationSchemas = {};
         for (const plugin of this.plugins) {
             if (plugin.configurationSchemaUnnamespaced) {
-                configurationSchemas = {
-                    ...configurationSchemas,
-                    ...plugin.configurationSchemaUnnamespaced,
-                };
+                Object.assign(configurationSchemas, plugin.configurationSchemaUnnamespaced);
             }
         }
         return configurationSchemas;
     }
     pluginConfigurationRootSchemas() {
-        let configurationSchemas = {};
+        const configurationSchemas = {};
         for (const plugin of this.plugins) {
             if (plugin.rootConfigurationSchema) {
-                configurationSchemas = {
-                    ...configurationSchemas,
-                    ...plugin.rootConfigurationSchema(this),
-                };
+                Object.assign(configurationSchemas, plugin.rootConfigurationSchema(this));
             }
         }
         return configurationSchemas;
@@ -109,11 +192,29 @@ export default class PluginManager {
         if (this.configured) {
             throw new Error('JBrowse already configured, cannot add plugins');
         }
-        const [plugin, metadata = {}] = 'install' in load && 'configure' in load
-            ? [load, {}]
-            : [load.plugin, load.metadata];
-        if (this.plugins.includes(plugin)) {
-            throw new Error('plugin already installed');
+        const [plugin, metadata] = 'plugin' in load
+            ? [load.plugin, load.metadata ?? {}]
+            : [load, {}];
+        // Refuse a second copy of the same plugin, matched by name rather than by
+        // object identity: the two copies of a plugin a product bundles AND a
+        // config names are different classes from different bundles, so an
+        // identity check never sees them.
+        //
+        // The pluggable-element registry has its own first-wins guard, but a
+        // plugin's install()/configure() side effects have none — appendToMenu is a
+        // plain push, so a second copy silently doubles that plugin's menu items.
+        // Enforcing it here means a product does not have to remember to drop the
+        // config entry for everything it vendors.
+        //
+        // Warn and skip rather than throw. A config naming a plugin some product
+        // bundles is a legitimate config — jbrowse.org's hub configs do exactly
+        // that, so Web (which bundles less than Desktop) still gets the plugin —
+        // and failing the whole session over it would be worse than the duplicate
+        // this prevents. First registration wins, which is the core copy, since
+        // core plugins are added before a config's.
+        if (this.plugins.some(p => p.name === plugin.name)) {
+            console.warn(`plugin ${plugin.name} is already installed, ignoring the second copy`);
+            return this;
         }
         this.pluginMetadata[plugin.name] = metadata;
         if ('definition' in load) {
@@ -129,10 +230,23 @@ export default class PluginManager {
     hasPlugin(name) {
         return this.getPlugin(name) !== undefined;
     }
+    removePlugin(pluginName) {
+        const plugin = this.getPlugin(pluginName);
+        if (!plugin) {
+            throw new Error(`Plugin '${pluginName}' not found`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        plugin.uninstall?.(this);
+        this.plugins = this.plugins.filter(p => p.name !== pluginName);
+        delete this.pluginMetadata[pluginName];
+        return this;
+    }
     createPluggableElements() {
-        if (this.elementCreationSchedule) {
+        // run the creation callbacks for each element type in order.
+        // see elementCreationSchedule above for the creation order
+        if (!this.pluggableElementsCreated) {
             this.elementCreationSchedule.run();
-            this.elementCreationSchedule = undefined;
+            this.pluggableElementsCreated = true;
         }
         return this;
     }
@@ -160,8 +274,6 @@ export default class PluginManager {
                 return this.connectionTypes;
             case 'widget':
                 return this.widgetTypes;
-            case 'renderer':
-                return this.rendererTypes;
             case 'display':
                 return this.displayTypes;
             case 'track':
@@ -174,8 +286,6 @@ export default class PluginManager {
                 return this.internetAccountTypes;
             case 'add track workflow':
                 return this.addTrackWidgets;
-            case 'glyph':
-                return this.glyphTypes;
             default:
                 throw new Error(`invalid element type '${groupName}'`);
         }
@@ -184,8 +294,11 @@ export default class PluginManager {
         if (typeof creationCallback !== 'function') {
             throw new Error('must provide a callback function that returns the new type object');
         }
+        if (this.pluggableElementsCreated) {
+            throw new Error(`Cannot add element type after createPluggableElements() has been called`);
+        }
         const typeRecord = this.getElementTypeRecord(groupName);
-        this.elementCreationSchedule?.add(groupName, () => {
+        this.elementCreationSchedule.add(groupName, () => {
             const newElement = creationCallback(this);
             if (!newElement.name) {
                 throw new Error(`cannot add a ${groupName} with no name`);
@@ -194,7 +307,9 @@ export default class PluginManager {
                 console.warn(`${groupName} ${newElement.name} already registered, cannot register it again`);
             }
             else {
-                typeRecord.add(newElement.name, this.evaluateExtensionPoint('Core-extendPluggableElement', newElement));
+                typeRecord.add(newElement.name, this.evaluateExtensionPoint(
+                /** #extensionPoint Core-extendPluggableElement | sync | Mutate any pluggable element after it is created */
+                'Core-extendPluggableElement', newElement, { group: groupName }));
             }
         });
         return this;
@@ -226,17 +341,38 @@ export default class PluginManager {
     getAdapterElements() {
         return this.getElementTypesInGroup('adapter');
     }
+    /**
+     * 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 && typeof jest === 'undefined') {
-            console.warn(`No pluggable types found matching ('${groupName}','${fieldName}')`);
-            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') {
         const pluggableTypes = this.getElementTypeRecord(typeGroup)
             .all()
@@ -245,42 +381,70 @@ export default class PluginManager {
         if (pluggableTypes.length === 0) {
             pluggableTypes.push(ConfigurationSchema('Null', {}));
         }
-        return types.union(...pluggableTypes);
+        // 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
+        // schema taking its base from this look concrete while its own slot reads
+        // have 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'
+            ? types.snapshotProcessor(union, {
+                preProcessor: (snap) => expandLooseTrackConfig(snap, this),
+            })
+            : union;
     }
     jbrequireCache = new Map();
-    lib = ReExports;
+    // populated by PluginLoader once a runtime plugin is actually being loaded,
+    // which is the only thing that can call jbrequire — see ReExports/registry.ts
+    get lib() {
+        return getReExportRegistry();
+    }
     load = (lib) => {
         if (!this.jbrequireCache.has(lib)) {
             this.jbrequireCache.set(lib, lib(this));
         }
         return this.jbrequireCache.get(lib);
     };
+    /**
+     * Get the re-exported version of the given package name.
+     * Throws an error if the package is not re-exported by the plugin manager.
+     *
+     * @returns the library's default export
+     */
     jbrequire = (lib) => {
         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.js. If it does not need to be shared, just import it normally.`);
+                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.`);
             }
             return pack;
         }
         else if (typeof lib === 'function') {
             return this.load(lib);
         }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         else if (lib.default) {
             console.warn('initiated jbrequire on a {default:Function}');
             return this.jbrequire(lib.default);
         }
         throw new TypeError('lib passed to jbrequire must be either a string or a function');
     };
-    getRendererType(typeName) {
-        return this.rendererTypes.get(typeName);
-    }
-    getRendererTypes() {
-        return this.rendererTypes.all();
-    }
     getAdapterType(typeName) {
         return this.adapterTypes.get(typeName);
     }
+    /**
+     * Whether an adapter type is registered, for a caller walking a config where
+     * `type` names a track, a display and an adapter alike — `getAdapterType`
+     * throws on a miss, which is right when the name came from a config that
+     * claims to be an adapter and wrong when you are asking whether it is one.
+     */
+    hasAdapterType(typeName) {
+        return this.adapterTypes.has(typeName);
+    }
     getTextSearchAdapterType(typeName) {
         return this.textSearchAdapterTypes.get(typeName);
     }
@@ -293,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);
     }
@@ -308,9 +568,6 @@ export default class PluginManager {
     getInternetAccountType(name) {
         return this.internetAccountTypes.get(name);
     }
-    addRendererType(cb) {
-        return this.addElementType('renderer', cb);
-    }
     addAdapterType(cb) {
         return this.addElementType('adapter', cb);
     }
@@ -318,10 +575,13 @@ export default class PluginManager {
         return this.addElementType('text search adapter', cb);
     }
     addTrackType(cb) {
+        // Goes through the already-created displays and registers the ones that
+        // specify this track type
         const callback = () => {
             const track = cb(this);
             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 &&
                     !track.displayTypes.includes(display)) {
                     track.addDisplayType(display);
@@ -339,6 +599,8 @@ export default class PluginManager {
             const newView = cb(this);
             const displays = this.getElementTypesInGroup('display');
             for (const display of displays) {
+                // view may have already added the displayType in its callback
+                // see ViewType for description of extendedName
                 if ((display.viewType === newView.name ||
                     display.viewType === newView.extendedName) &&
                     !newView.displayTypes.includes(display)) {
@@ -364,16 +626,82 @@ export default class PluginManager {
     addAddTrackWorkflowType(cb) {
         return this.addElementType('add track workflow', cb);
     }
-    addGlyphType(cb) {
-        return this.addElementType('glyph', cb);
-    }
-    getGlyphType(typeName) {
-        return this.glyphTypes.get(typeName);
+    /**
+     * Contribute entries to an accumulating point.
+     *
+     * The callback is handed only the props and returns what it wants to add —
+     * one entry, several, or `undefined` to add nothing. It never receives the
+     * array, which is the whole point: the concatenation happens here, once, so
+     * no plugin can write the `[MyEntry]` that silently drops every other
+     * plugin's entries. That mistake looked correct to whoever made it, because
+     * with one plugin registered there is nothing to drop.
+     */
+    contributeToExtensionPoint(extensionPointName, callback) {
+        this.pushExtensionPointCallback(extensionPointName, (entries, props) => {
+            const contributed = callback(props);
+            const accumulated = entries;
+            return contributed === undefined
+                ? accumulated
+                : [
+                    ...accumulated,
+                    ...(Array.isArray(contributed) ? contributed : [contributed]),
+                ];
+        });
     }
-    getGlyphTypes() {
-        return this.glyphTypes.all();
+    /**
+     * Listen to a notification point — one that carries its payload in `props`
+     * and whose return value nothing reads. The callback returns nothing;
+     * `addToExtensionPoint` rejects these names, so this is the only way in.
+     *
+     * The reason it is the only way in is the async join below, not the shorter
+     * callback. A handler that works asynchronously states so by returning a
+     * promise, and the producer waits on the folded value; written by hand
+     * through `addToExtensionPoint`, the second async handler's promise silently
+     * replaced the first's, so the producer stopped waiting as soon as the
+     * *last*-registered handler finished rather than when they all had. That is
+     * not a mistake a plugin author can see, which is why it is not left to them.
+     */
+    listenToExtensionPoint(extensionPointName, callback) {
+        this.pushExtensionPointCallback(extensionPointName, (extendee, props) => {
+            const ret = callback(props);
+            // An async handler is awaited — by evaluateAsyncExtensionPoint, or by a
+            // producer that checks the folded value for a thenable to learn when
+            // handlers have finished. A sync one passes through whatever an earlier
+            // handler left, so its promise is not dropped on the way past.
+            //
+            // Two async ones are joined rather than the later replacing the earlier;
+            // under the sync runner nothing awaits between callbacks. waitForAssembly
+            // is the producer that depends on it.
+            if (!(ret instanceof Promise)) {
+                return extendee;
+            }
+            return extendee instanceof Promise
+                ? Promise.all([extendee, ret]).then(() => undefined)
+                : ret.then(() => undefined);
+        });
     }
     addToExtensionPoint(extensionPointName, callback) {
+        this.pushExtensionPointCallback(extensionPointName, callback);
+    }
+    /**
+     * The one place a callback joins a point's chain. The three public
+     * registration methods go through this rather than through each other:
+     * `contributeToExtensionPoint` and `listenToExtensionPoint` register on exactly
+     * the point names their own signatures reject, so routing them via
+     * `addToExtensionPoint` would either fail to compile or force its guard to be
+     * loose enough to let a plugin do the same thing by hand.
+     */
+    pushExtensionPointCallback(extensionPointName, callback) {
+        // `Core-extendPluggableElement` fires once per element, inside
+        // createPluggableElements(). Registering after that run joins a fold that
+        // has already happened, so the extension never applies — the same mistake
+        // `addElementType` throws on, and the reason it throws: from `configure()`
+        // instead of `install()`, an extendViewType call compiles, runs, and
+        // silently extends nothing.
+        if (extensionPointName === 'Core-extendPluggableElement' &&
+            this.pluggableElementsCreated) {
+            throw new Error("Cannot register on Core-extendPluggableElement after createPluggableElements() has been called: the point has already fired for every element, so this callback would never run. Register it from a plugin's install(), not configure().");
+        }
         let callbacks = this.extensionPoints.get(extensionPointName);
         if (!callbacks) {
             callbacks = [];
@@ -387,28 +715,72 @@ export default class PluginManager {
         if (callbacks) {
             for (const callback of callbacks) {
                 try {
-                    accumulator = callback(accumulator, props);
+                    accumulator = nextAccumulator(extensionPointName, accumulator, callback(accumulator, props));
+                }
+                catch (error) {
+                    logCallbackError(extensionPointName, error);
+                }
+            }
+        }
+        return accumulator;
+    }
+    evaluateComponentExtensionPoint(extensionPointName, extendee, props) {
+        const callbacks = this.extensionPoints.get(extensionPointName);
+        let accumulator = extendee;
+        let claims = 0;
+        if (callbacks) {
+            for (const callback of callbacks) {
+                try {
+                    const result = nextAccumulator(extensionPointName, accumulator, callback(accumulator, props));
+                    if (result !== accumulator &&
+                        result?.[wrappedComponent] !== accumulator) {
+                        claims++;
+                    }
+                    accumulator = result;
                 }
                 catch (error) {
-                    console.error(error);
+                    logCallbackError(extensionPointName, error);
                 }
             }
         }
+        if (claims > 1 && !this.warnedClobber.has(extensionPointName)) {
+            this.warnedClobber.add(extensionPointName);
+            console.warn(`more than one plugin replaced the ${extensionPointName} slot; only the last one registered is visible. Use a wrapper if the intent was to add to the default rather than replace it`);
+        }
         return accumulator;
     }
+    /**
+     * How many callbacks are registered on `extensionPointName`. For a caller
+     * that has to tell "every handler declined" apart from "nobody was
+     * listening" — the two look identical in the folded result, and
+     * assemblyManager waits out the first but not the second.
+     */
+    extensionPointCallbackCount(extensionPointName) {
+        return this.extensionPoints.get(extensionPointName)?.length ?? 0;
+    }
     async evaluateAsyncExtensionPoint(extensionPointName, extendee, props) {
         const callbacks = this.extensionPoints.get(extensionPointName);
         let accumulator = extendee;
         if (callbacks) {
             for (const callback of callbacks) {
                 try {
-                    accumulator = await callback(accumulator, props);
+                    accumulator = nextAccumulator(extensionPointName, accumulator, await callback(accumulator, props));
                 }
                 catch (error) {
-                    console.error(error);
+                    logCallbackError(extensionPointName, error);
                 }
             }
         }
         return accumulator;
     }
+    async evaluateAsyncExtensionPointStrict(extensionPointName, extendee, props) {
+        const callbacks = this.extensionPoints.get(extensionPointName);
+        let accumulator = extendee;
+        if (callbacks) {
+            for (const callback of callbacks) {
+                accumulator = nextAccumulator(extensionPointName, accumulator, await callback(accumulator, props));
+            }
+        }
+        return accumulator;
+    }
 }