@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-loader.js

@@ -0,0 +1,223 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Dynamic plugin activation (AGL-417). Apps never import @aglyn/plugins-*;
+ * they hand this loader a GENERATED manifest of `() => import(...)` thunks
+ * (see tools/scripts/generate-plugin-manifests.mjs) and activate plugins at
+ * runtime from `org.enabledPlugins` (AGL-416). Loading is cached per
+ * entry+surface and registration per entry+surface+use, and `ensure` returns
+ * a stable promise per (ids, surfaces, use) so React `use()` can suspend on
+ * it during SSR — the canvas never renders before its components are
+ * registered (the blank-canvas invariant, AGL-52).
+ */ // From the leaf module, not the API route registry that re-exports it: this
+// loader is on every published page, and the registry is server-only.
+import { setRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { plugins } from "../aglyn.js";
+/** Whether an earlier registration already covers this use context. */ function covers(done, use) {
+    if (!done) return false;
+    if (done.all) return true;
+    // An unbounded ask is never covered by a narrow one: the plugin was handed
+    // a list, so it registered a list.
+    if (!(use == null ? void 0 : use.componentIds)) return false;
+    return use.componentIds.every((id)=>done.componentIds.has(id));
+}
+/**
+ * A use context as a cache key.
+ *
+ * Absent is its own key, and a different one from an empty list: a surface
+ * that cannot say what it uses asks for everything, where one that places no
+ * component asks for nothing.
+ */ function keyForUse(use) {
+    return (use == null ? void 0 : use.componentIds) ? `c:${[
+        ...use.componentIds
+    ].sort().join(',')}` : '*';
+}
+export function createPluginLoader(manifest) {
+    const loads = new Map();
+    const registered = new Map();
+    const bootstrapped = new Set();
+    const ensures = new Map();
+    const prefixToId = new Map();
+    for (const entry of manifest){
+        var _entry_apiPrefixes;
+        for (const prefix of (_entry_apiPrefixes = entry.apiPrefixes) != null ? _entry_apiPrefixes : [])prefixToId.set(prefix, entry.id);
+    }
+    /** The module `surface` registers from, loaded once per module. */ const loadOnce = (entry, surface)=>{
+        var _entry_loads;
+        const own = (_entry_loads = entry.loads) == null ? void 0 : _entry_loads[surface];
+        const key = own ? `${entry.id}:${surface}` : entry.id;
+        let promise = loads.get(key);
+        if (!promise) {
+            promise = own ? own() : entry.load();
+            loads.set(key, promise);
+        }
+        return promise;
+    };
+    /**
+   * Fetches what `surfaces` register from, and hands back the registration
+   * itself as a step to run later.
+   *
+   * The two are separated because registration is now AWAITED (AGL-3141): a
+   * plugin that imports the components the surface uses returns a promise,
+   * and a register fn that yields would otherwise overlap another plugin's —
+   * leaving `setRegisteringPluginId` naming the wrong owner for whatever the
+   * first one registers after it resumes. Loading still runs for every plugin
+   * at once, which is where the time is; only the registrations are ordered.
+   */ const prepare = async (entry, surfaces)=>{
+        const wanted = surfaces.filter((surface)=>entry.register[surface]);
+        if (!wanted.length) return async ()=>undefined;
+        // Dev-mode load metrics (AGL-436): slow plugins show up in the
+        // console instead of hiding inside the gate's total.
+        const startedAt = Date.now();
+        const modules = await Promise.all(wanted.map((surface)=>loadOnce(entry, surface)));
+        const loadMs = Date.now() - startedAt;
+        return async (use)=>{
+            for (const [index, surface] of wanted.entries()){
+                var _ref, _ref1;
+                const mod = modules[index];
+                const key = `${entry.id}:${surface}`;
+                const done = registered.get(key);
+                if (covers(done, use)) continue;
+                registered.set(key, {
+                    all: (done == null ? void 0 : done.all) || !(use == null ? void 0 : use.componentIds),
+                    componentIds: new Set([
+                        ...(_ref = done == null ? void 0 : done.componentIds) != null ? _ref : [],
+                        ...(_ref1 = use == null ? void 0 : use.componentIds) != null ? _ref1 : []
+                    ])
+                });
+                const fnName = entry.register[surface];
+                const fn = mod[fnName];
+                if (typeof fn !== 'function') {
+                    // A manifest/plugin drift bug — surface loudly, don't crash the app.
+                    console.error(`plugin ${entry.id}: missing register fn ${fnName}`);
+                    continue;
+                }
+                // Mark ownership while the register fn runs so registerPluginApiRoute
+                // records exact path→plugin attribution for the per-org gate.
+                setRegisteringPluginId(entry.id);
+                try {
+                    await fn(use);
+                } finally{
+                    setRegisteringPluginId(undefined);
+                }
+            }
+            if (process.env.NODE_ENV !== 'production') {
+                console.debug(`[plugin-loader] ${entry.id} [${wanted.join(',')}] ` + `load ${loadMs}ms, total ${Date.now() - startedAt}ms`);
+            }
+        };
+    };
+    /**
+   * Bootstrap phase (AGL-429, Strapi register→bootstrap parity): after
+   * EVERY plugin in an ensure batch has registered a surface, each loaded
+   * module's optional `bootstrap<Surface>()` export runs (manifest order,
+   * once per plugin+surface) — the sanctioned place for cross-plugin
+   * wiring, because by then the other plugins' registrations are in the
+   * registries. Plugins loaded by a LATER ensure bootstrap in that batch;
+   * wiring must therefore tolerate registrations that arrive afterwards
+   * (prefer lazy list*() reads over captured snapshots).
+   */ const bootstrap = async (targets, surfaces)=>{
+        for (const entry of targets){
+            const wanted = surfaces.filter((surface)=>entry.register[surface]);
+            if (!wanted.length) continue;
+            for (const surface of wanted){
+                const mod = await loadOnce(entry, surface);
+                const key = `${entry.id}:${surface}`;
+                if (bootstrapped.has(key)) continue;
+                bootstrapped.add(key);
+                const fnName = `bootstrap${surface[0].toUpperCase()}${surface.slice(1)}`;
+                const fn = mod[fnName];
+                if (typeof fn !== 'function') continue;
+                setRegisteringPluginId(entry.id);
+                try {
+                    ;
+                    fn();
+                } catch (error) {
+                    // A broken bootstrap must not take the surface down.
+                    console.error(`plugin ${entry.id}: ${fnName} failed`, error);
+                } finally{
+                    setRegisteringPluginId(undefined);
+                }
+            }
+        }
+    };
+    /**
+   * After a batch settles, any target still WAITING is stuck: a dependency it
+   * declared was never activated, so its register fn never ran and its
+   * besigner category is empty (AGL-759). Before the reverse-dependency fix
+   * this was silent — say so now, naming the bundle and what it waited on, so
+   * the failure is a console line rather than a mysteriously empty drawer.
+   */ const warnStuck = (targets)=>{
+        const targetIds = new Set(targets.map((entry)=>entry.id));
+        for (const { id, waitingOn } of plugins.getStuckDependencies()){
+            if (!targetIds.has(id)) continue;
+            console.warn(`[plugin-loader] ${id} is stuck WAITING on ` + `${waitingOn.join(', ') || 'an unregistered dependency'} — its ` + 'components never registered, so its besigner category will be ' + 'empty. Check that the dependency is in the manifest and activated ' + '(AGL-759).');
+        }
+    };
+    const ensure = (ids, surfaces, use)=>{
+        // The use context is part of the key, not just of the bookkeeping: a
+        // second page that places components the first did not must get its own
+        // run, or it would be handed the first page's settled promise and render
+        // its extra elements against nothing (AGL-52).
+        const key = `${[
+            ...ids
+        ].sort().join(',')}|${[
+            ...surfaces
+        ].sort().join(',')}` + `|${keyForUse(use)}`;
+        let promise = ensures.get(key);
+        if (!promise) {
+            const targets = manifest.filter((entry)=>entry.alwaysOn || ids.includes(entry.id));
+            const run = async ()=>{
+                const steps = await Promise.all(targets.map((entry)=>prepare(entry, surfaces)));
+                for (const step of steps)await step(use);
+                await bootstrap(targets, surfaces);
+                warnStuck(targets);
+            };
+            promise = run();
+            // Stamp React's thenable contract (`status`/`value`/`reason`) onto the
+            // cached promise once it settles (AGL-1541). `use()` can only unwrap a
+            // thenable SYNCHRONOUSLY when it carries a status; a bare native
+            // promise — even a resolved one — suspends every first `use()` per
+            // render. On the server that suspension pushed the ENTIRE page out of
+            // the streamed shell into a late Suspense segment whose reveal and
+            // hydration retry both ride on `requestAnimationFrame`, which never
+            // fires in hidden/occluded/prerendered tabs — pages that never
+            // hydrate, analytics that never fire. With the stamp, any render after
+            // the first settle (every warm request; every client render after the
+            // chunks load) unwraps inline and never enters that path.
+            const tracked = promise;
+            tracked.then(()=>{
+                tracked.status = 'fulfilled';
+                tracked.value = undefined;
+            }, (reason)=>{
+                tracked.status = 'rejected';
+                tracked.reason = reason;
+            });
+            ensures.set(key, promise);
+        }
+        return promise;
+    };
+    return {
+        ensure,
+        ensureAll: (surfaces)=>ensure(manifest.map((entry)=>entry.id), surfaces),
+        pluginIdForApiPath: (path)=>{
+            var _path_replace_split_;
+            const prefix = (_path_replace_split_ = path.replace(/^\/+/, '').split('/')[0]) != null ? _path_replace_split_ : '';
+            return prefixToId.get(prefix);
+        }
+    };
+}
+
+//# sourceMappingURL=plugin-loader.js.map

package/src/lib/plugin-manager/plugin-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-loader.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Dynamic plugin activation (AGL-417). Apps never import @aglyn/plugins-*;\n * they hand this loader a GENERATED manifest of `() => import(...)` thunks\n * (see tools/scripts/generate-plugin-manifests.mjs) and activate plugins at\n * runtime from `org.enabledPlugins` (AGL-416). Loading is cached per\n * entry+surface and registration per entry+surface+use, and `ensure` returns\n * a stable promise per (ids, surfaces, use) so React `use()` can suspend on\n * it during SSR — the canvas never renders before its components are\n * registered (the blank-canvas invariant, AGL-52).\n */\n\nexport interface PluginLoadEntry {\n  /** Stable plugin id — matches FIRST_PARTY_PLUGINS / org.enabledPlugins. */\n  id: string\n  /** Loaded regardless of the org switchboard (base components). */\n  alwaysOn?: boolean\n  /** `/api/<prefix>/...` paths this plugin's handlers own (server gate). */\n  apiPrefixes?: string[]\n  /** surface → exported register-fn name on the loaded module. */\n  register: Partial<Record<string, string>>\n  load: () => Promise<Record<string, unknown>>\n  /**\n   * The module a surface loads from, when it is not `load`'s (AGL-3116).\n   *\n   * A package entry imported with `import()` is a namespace the loader reads\n   * by name, so the bundler keeps every export it has: a site surface loaded\n   * from the package root carried the console registrar, its nav objects and\n   * its lazy pages onto every published page that used the plugin. A surface\n   * with a module of its own carries only what that module exports.\n   */\n  loads?: Partial<Record<string, () => Promise<Record<string, unknown>>>>\n  /**\n   * What this plugin declares it contributes, and where (AGL-3142).\n   *\n   * The loader never reads it: `ensure` is told which plugins to activate and\n   * activates them. It rides on the entry because the manifest is the one list\n   * of plugins an app holds, and an app that loads by presence has to answer\n   * \"which of these belongs on this screen\" before it names any ids — from\n   * data, not by running a plugin, which is the cost being avoided.\n   *\n   * Written into a manifest whose app reads it and left off the others: the\n   * published page decides presence from the nodes it places, so the tenant\n   * manifest would carry a declaration nothing there consults.\n   */\n  contributes?: PluginContributions\n}\n\nexport type PluginLoadManifest = readonly PluginLoadEntry[]\n\nexport interface PluginLoader {\n  /**\n   * Loads + registers the given plugins' surfaces. `ids` may include unknown\n   * ids (marketplace realm plugins — ignored here); manifest entries marked\n   * alwaysOn activate regardless of `ids`.\n   *\n   * `use` is what the surface actually uses (AGL-3141), carried unchanged to\n   * every register function: the page computes it, the loader carries it, a\n   * plugin reads it or ignores it. Omitting it asks for everything, which is\n   * what a surface that cannot narrow must do.\n   *\n   * A surface registers once per plugin per use context. A second page that\n   * places a component the first did not still reaches the plugin, so the\n   * element it added has a component to render (AGL-52); one whose use is\n   * already covered costs nothing.\n   */\n  ensure(\n    ids: readonly string[],\n    surfaces: readonly string[],\n    use?: PluginUse,\n  ): Promise<void>\n  /** Every manifest plugin, for `ensureAll` semantics (server dispatchers). */\n  ensureAll(surfaces: readonly string[]): Promise<void>\n  /** The plugin owning an api path ('bookings/slots' → 'bookings'). */\n  pluginIdForApiPath(path: string): string | undefined\n}\n\n/**\n * A register function as the loader calls it: handed the surface's use\n * context, and awaited, because a plugin that imports what the surface uses\n * returns a promise.\n */\ntype PluginRegisterFn = (use?: PluginUse) => void | Promise<void>\n\n/** What one plugin+surface has already registered for. */\ninterface RegisteredFor {\n  /** It registered with no use context, so it registered all of itself. */\n  all: boolean\n  /** The component ids it has been handed so far. */\n  componentIds: Set<string>\n}\n\n// From the leaf module, not the API route registry that re-exports it: this\n// loader is on every published page, and the registry is server-only.\nimport { setRegisteringPluginId } from '../app-utils/registering-plugin'\nimport type { PluginContributions, PluginUse } from './plugin-contributions'\nimport { plugins } from '../aglyn'\n\n/** Whether an earlier registration already covers this use context. */\nfunction covers(done: RegisteredFor | undefined, use?: PluginUse): boolean {\n  if (!done) return false\n  if (done.all) return true\n  // An unbounded ask is never covered by a narrow one: the plugin was handed\n  // a list, so it registered a list.\n  if (!use?.componentIds) return false\n  return use.componentIds.every((id) => done.componentIds.has(id))\n}\n\n/**\n * A use context as a cache key.\n *\n * Absent is its own key, and a different one from an empty list: a surface\n * that cannot say what it uses asks for everything, where one that places no\n * component asks for nothing.\n */\nfunction keyForUse(use?: PluginUse): string {\n  return use?.componentIds ? `c:${[...use.componentIds].sort().join(',')}` : '*'\n}\n\nexport function createPluginLoader(manifest: PluginLoadManifest): PluginLoader {\n  const loads = new Map<string, Promise<Record<string, unknown>>>()\n  const registered = new Map<string, RegisteredFor>()\n  const bootstrapped = new Set<string>()\n  const ensures = new Map<string, Promise<void>>()\n  const prefixToId = new Map<string, string>()\n  for (const entry of manifest) {\n    for (const prefix of entry.apiPrefixes ?? []) prefixToId.set(prefix, entry.id)\n  }\n\n  /** The module `surface` registers from, loaded once per module. */\n  const loadOnce = (entry: PluginLoadEntry, surface: string) => {\n    const own = entry.loads?.[surface]\n    const key = own ? `${entry.id}:${surface}` : entry.id\n    let promise = loads.get(key)\n    if (!promise) {\n      promise = own ? own() : entry.load()\n      loads.set(key, promise)\n    }\n    return promise\n  }\n\n  /**\n   * Fetches what `surfaces` register from, and hands back the registration\n   * itself as a step to run later.\n   *\n   * The two are separated because registration is now AWAITED (AGL-3141): a\n   * plugin that imports the components the surface uses returns a promise,\n   * and a register fn that yields would otherwise overlap another plugin's —\n   * leaving `setRegisteringPluginId` naming the wrong owner for whatever the\n   * first one registers after it resumes. Loading still runs for every plugin\n   * at once, which is where the time is; only the registrations are ordered.\n   */\n  const prepare = async (\n    entry: PluginLoadEntry,\n    surfaces: readonly string[],\n  ): Promise<(use?: PluginUse) => Promise<void>> => {\n    const wanted = surfaces.filter((surface) => entry.register[surface])\n    if (!wanted.length) return async () => undefined\n    // Dev-mode load metrics (AGL-436): slow plugins show up in the\n    // console instead of hiding inside the gate's total.\n    const startedAt = Date.now()\n    const modules = await Promise.all(\n      wanted.map((surface) => loadOnce(entry, surface)),\n    )\n    const loadMs = Date.now() - startedAt\n    return async (use?: PluginUse) => {\n      for (const [index, surface] of wanted.entries()) {\n        const mod = modules[index]\n        const key = `${entry.id}:${surface}`\n        const done = registered.get(key)\n        if (covers(done, use)) continue\n        registered.set(key, {\n          all: done?.all || !use?.componentIds,\n          componentIds: new Set([\n            ...(done?.componentIds ?? []),\n            ...(use?.componentIds ?? []),\n          ]),\n        })\n        const fnName = entry.register[surface] as string\n        const fn = mod[fnName]\n        if (typeof fn !== 'function') {\n          // A manifest/plugin drift bug — surface loudly, don't crash the app.\n          console.error(`plugin ${entry.id}: missing register fn ${fnName}`)\n          continue\n        }\n        // Mark ownership while the register fn runs so registerPluginApiRoute\n        // records exact path→plugin attribution for the per-org gate.\n        setRegisteringPluginId(entry.id)\n        try {\n          await (fn as PluginRegisterFn)(use)\n        } finally {\n          setRegisteringPluginId(undefined)\n        }\n      }\n      if (process.env.NODE_ENV !== 'production') {\n        console.debug(\n          `[plugin-loader] ${entry.id} [${wanted.join(',')}] ` +\n            `load ${loadMs}ms, total ${Date.now() - startedAt}ms`,\n        )\n      }\n    }\n  }\n\n  /**\n   * Bootstrap phase (AGL-429, Strapi register→bootstrap parity): after\n   * EVERY plugin in an ensure batch has registered a surface, each loaded\n   * module's optional `bootstrap<Surface>()` export runs (manifest order,\n   * once per plugin+surface) — the sanctioned place for cross-plugin\n   * wiring, because by then the other plugins' registrations are in the\n   * registries. Plugins loaded by a LATER ensure bootstrap in that batch;\n   * wiring must therefore tolerate registrations that arrive afterwards\n   * (prefer lazy list*() reads over captured snapshots).\n   */\n  const bootstrap = async (\n    targets: readonly PluginLoadEntry[],\n    surfaces: readonly string[],\n  ): Promise<void> => {\n    for (const entry of targets) {\n      const wanted = surfaces.filter((surface) => entry.register[surface])\n      if (!wanted.length) continue\n      for (const surface of wanted) {\n        const mod = await loadOnce(entry, surface)\n        const key = `${entry.id}:${surface}`\n        if (bootstrapped.has(key)) continue\n        bootstrapped.add(key)\n        const fnName = `bootstrap${surface[0].toUpperCase()}${surface.slice(1)}`\n        const fn = mod[fnName]\n        if (typeof fn !== 'function') continue\n        setRegisteringPluginId(entry.id)\n        try {\n          ;(fn as () => void)()\n        } catch (error) {\n          // A broken bootstrap must not take the surface down.\n          console.error(`plugin ${entry.id}: ${fnName} failed`, error)\n        } finally {\n          setRegisteringPluginId(undefined)\n        }\n      }\n    }\n  }\n\n  /**\n   * After a batch settles, any target still WAITING is stuck: a dependency it\n   * declared was never activated, so its register fn never ran and its\n   * besigner category is empty (AGL-759). Before the reverse-dependency fix\n   * this was silent — say so now, naming the bundle and what it waited on, so\n   * the failure is a console line rather than a mysteriously empty drawer.\n   */\n  const warnStuck = (targets: readonly PluginLoadEntry[]): void => {\n    const targetIds = new Set(targets.map((entry) => entry.id))\n    for (const { id, waitingOn } of plugins.getStuckDependencies()) {\n      if (!targetIds.has(id)) continue\n      console.warn(\n        `[plugin-loader] ${id} is stuck WAITING on ` +\n          `${waitingOn.join(', ') || 'an unregistered dependency'} — its ` +\n          'components never registered, so its besigner category will be ' +\n          'empty. Check that the dependency is in the manifest and activated ' +\n          '(AGL-759).',\n      )\n    }\n  }\n\n  const ensure = (\n    ids: readonly string[],\n    surfaces: readonly string[],\n    use?: PluginUse,\n  ): Promise<void> => {\n    // The use context is part of the key, not just of the bookkeeping: a\n    // second page that places components the first did not must get its own\n    // run, or it would be handed the first page's settled promise and render\n    // its extra elements against nothing (AGL-52).\n    const key =\n      `${[...ids].sort().join(',')}|${[...surfaces].sort().join(',')}` +\n      `|${keyForUse(use)}`\n    let promise = ensures.get(key)\n    if (!promise) {\n      const targets = manifest.filter(\n        (entry) => entry.alwaysOn || ids.includes(entry.id),\n      )\n      const run = async (): Promise<void> => {\n        const steps = await Promise.all(\n          targets.map((entry) => prepare(entry, surfaces)),\n        )\n        for (const step of steps) await step(use)\n        await bootstrap(targets, surfaces)\n        warnStuck(targets)\n      }\n      promise = run()\n      // Stamp React's thenable contract (`status`/`value`/`reason`) onto the\n      // cached promise once it settles (AGL-1541). `use()` can only unwrap a\n      // thenable SYNCHRONOUSLY when it carries a status; a bare native\n      // promise — even a resolved one — suspends every first `use()` per\n      // render. On the server that suspension pushed the ENTIRE page out of\n      // the streamed shell into a late Suspense segment whose reveal and\n      // hydration retry both ride on `requestAnimationFrame`, which never\n      // fires in hidden/occluded/prerendered tabs — pages that never\n      // hydrate, analytics that never fire. With the stamp, any render after\n      // the first settle (every warm request; every client render after the\n      // chunks load) unwraps inline and never enters that path.\n      const tracked = promise as Promise<void> & {\n        status?: 'fulfilled' | 'rejected'\n        value?: void\n        reason?: unknown\n      }\n      tracked.then(\n        () => {\n          tracked.status = 'fulfilled'\n          tracked.value = undefined\n        },\n        (reason) => {\n          tracked.status = 'rejected'\n          tracked.reason = reason\n        },\n      )\n      ensures.set(key, promise)\n    }\n    return promise\n  }\n\n  return {\n    ensure,\n    ensureAll: (surfaces) =>\n      ensure(\n        manifest.map((entry) => entry.id),\n        surfaces,\n      ),\n    pluginIdForApiPath: (path) => {\n      const prefix = path.replace(/^\\/+/, '').split('/')[0] ?? ''\n      return prefixToId.get(prefix)\n    },\n  }\n}\n"],"names":["setRegisteringPluginId","plugins","covers","done","use","all","componentIds","every","id","has","keyForUse","sort","join","createPluginLoader","manifest","loads","Map","registered","bootstrapped","Set","ensures","prefixToId","entry","prefix","apiPrefixes","set","loadOnce","surface","own","key","promise","get","load","prepare","surfaces","wanted","filter","register","length","undefined","startedAt","Date","now","modules","Promise","map","loadMs","index","entries","mod","fnName","fn","console","error","process","env","NODE_ENV","debug","bootstrap","targets","add","toUpperCase","slice","warnStuck","targetIds","waitingOn","getStuckDependencies","warn","ensure","ids","alwaysOn","includes","run","steps","step","tracked","then","status","value","reason","ensureAll","pluginIdForApiPath","path","replace","split"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-manager.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { MdiIconProps } from '../types/nodes';
+import type { Aglyn } from '../aglyn';
+export declare enum PluginStatus {
+    WAITING = "waiting",
+    LOADING = "loading",
+    LOADED = "loaded",
+    UNLOADING = "unloading"
+}
+import type { PluginId } from '../foundation';
+export type { PluginId };
+export type PluginStatusById = Record<PluginId, PluginStatus>;
+export type PluginsById = Record<PluginId, Plugin>;
+export type PluginDependencies = Record<PluginId, true>;
+export type Dependents = Record<PluginId, true>;
+export type PluginDependents = Record<PluginId, Dependents>;
+export interface Plugin {
+    $id?: PluginId;
+    displayName?: string;
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    icon?: MdiIconProps;
+    dependencies?: PluginDependencies;
+    load?(...args: any[]): void;
+    destroy?(...args: any[]): void;
+}
+export declare class PluginManager {
+    protected aglyn?: Aglyn;
+    dependencies: PluginsById;
+    dependencyStatusById: PluginStatusById;
+    dependencyDependentsById: PluginDependents;
+    constructor(aglyn?: Aglyn);
+    getDependency(dependencyId: PluginId): Plugin | undefined;
+    getDependencyDependents(dependencyId: PluginId): Dependents | undefined;
+    getDependencyStatus(dependencyId: PluginId): PluginStatus | undefined;
+    hasDependency(dependencyId: PluginId): boolean;
+    isDependencyWaiting(dependencyId: PluginId): boolean;
+    isDependencyLoading(dependencyId: PluginId): boolean;
+    isDependencyLoaded(dependencyId: PluginId): boolean;
+    isDependencyUnloading(dependencyId: PluginId): boolean;
+    areAllDependenciesLoaded(dependentId: PluginId): boolean;
+    addDependency(dependency: Plugin): void;
+    addDependencies(dependencies?: Array<Plugin>): void;
+    destroyDependencies(): void;
+    removeDependency($id: PluginId): void;
+    loadDependency($id: PluginId): void;
+    unloadDependency($id: PluginId): void;
+    getDependencyCopy(dependencyId: PluginId): Readonly<Plugin> | undefined;
+    /**
+     * Every registered dependency still parked in WAITING, paired with the
+     * dependencies it is waiting on that have not loaded (AGL-759).
+     *
+     * A bundle lands here when a dependency it declared never reached LOADED.
+     * With the reverse-dependency edge fixed, a bundle that registers before
+     * its dependency is recovered as soon as the dependency finishes — so the
+     * only thing left in this list once a batch has settled is a bundle whose
+     * dependency was never activated at all (a manifest/enablement gap). That
+     * used to present as an empty besigner drawer with no error: the bundle's
+     * components simply never registered. Callers report this at a settle
+     * point (the plugin loader, after an `ensure`) so the gap says so instead.
+     */
+    getStuckDependencies(): Array<{
+        id: PluginId;
+        waitingOn: PluginId[];
+    }>;
+    private handleSettingDependencyProperties;
+    private handleSettingDependencyDependents;
+    private handleRemovingDependencyDependents;
+    private handleRemovingDependencyProperties;
+    private handleLoadingDependencyDependents;
+    private handleLoadingDependency;
+    private handleUnloadingDependencyDependents;
+    private handleUnloadingDependency;
+    private handleAddingDependencyAndDependents;
+    private handleLoadingDependencyAndDependents;
+    private handleUnloadingDependencyAndDependents;
+    private handleRemovingDependencyAndDependents;
+}
+export default PluginManager;