@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,343 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { makeAutoObservable } from "mobx";
+import { lifecycleEvent } from "../lifecycle.js";
+import { AglynEvent } from "../emit-manager/index.js";
+export var PluginStatus = /*#__PURE__*/ function(PluginStatus) {
+    PluginStatus["WAITING"] = "waiting";
+    PluginStatus["LOADING"] = "loading";
+    PluginStatus["LOADED"] = "loaded";
+    PluginStatus["UNLOADING"] = "unloading";
+    return PluginStatus;
+}({});
+// export const plugins: Record<PluginId, Plugin> = {}
+//
+// export function getBundle(pluginId: PluginId) {
+//   return plugins[pluginId]
+// }
+//
+// export function hasBundle(pluginId: PluginId) {
+//   return pluginId && _hasOwnProperty(pluginId, plugins)
+// }
+//
+// export function registerBundle(schema: Plugin) {
+//   const { $id: pluginId } = schema
+//   lifecycleEvent(
+//     () => {
+//       addDependency(schema)
+//       plugins[pluginId] = schema
+//       // for (const preset of schema.presets || []) {
+//       //   emitter.emit(AglynEvent.PRESET_REGISTER, { preset })
+//       // }
+//     },
+//     {
+//       beforeEvent: AglynEvent.PLUGIN_REGISTERING,
+//       beforePayload: [{ schema }],
+//       afterEvent: AglynEvent.PLUGIN_REGISTERED,
+//       afterPayload: [{ schema }],
+//     },
+//   )
+// }
+//
+// export function unregisterBundle(pluginId: PluginId) {
+//   const bundle = plugins[pluginId]
+//   lifecycleEvent(
+//     () => {
+//       if (!bundle) throw new Error(`No bundle exists with $id ${pluginId}`)
+//
+//       // for (const componentId of bundle.componentIds || []) {
+//       //   emitter.emit(AglynEvent.COMPONENT_UNREGISTER, { componentId, pluginId })
+//       // }
+//       delete plugins[pluginId]
+//     },
+//     {
+//       beforeEvent: AglynEvent.PLUGIN_UNREGISTERING,
+//       beforePayload: [{ pluginId }],
+//       afterEvent: AglynEvent.PLUGIN_UNREGISTERED,
+//       afterPayload: [{ pluginId }],
+//     },
+//   )
+// }
+export class PluginManager {
+    getDependency(dependencyId) {
+        return this.dependencies[dependencyId];
+    }
+    getDependencyDependents(dependencyId) {
+        return this.dependencyDependentsById[dependencyId];
+    }
+    getDependencyStatus(dependencyId) {
+        return this.dependencyStatusById[dependencyId];
+    }
+    hasDependency(dependencyId) {
+        return Boolean(dependencyId && this.getDependency(dependencyId));
+    }
+    isDependencyWaiting(dependencyId) {
+        return this.getDependencyStatus(dependencyId) === "waiting";
+    }
+    isDependencyLoading(dependencyId) {
+        return this.getDependencyStatus(dependencyId) === "loading";
+    }
+    isDependencyLoaded(dependencyId) {
+        return this.getDependencyStatus(dependencyId) === "loaded";
+    }
+    isDependencyUnloading(dependencyId) {
+        return this.getDependencyStatus(dependencyId) === "unloading";
+    }
+    areAllDependenciesLoaded(dependentId) {
+        var _this_getDependency;
+        for (const dependencyId of Object.keys(((_this_getDependency = this.getDependency(dependentId)) == null ? void 0 : _this_getDependency.dependencies) || {})){
+            if (!this.isDependencyLoaded(dependencyId)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    addDependency(dependency) {
+        lifecycleEvent(()=>{
+            this.handleAddingDependencyAndDependents(dependency);
+        }, {
+            beforeEvent: AglynEvent.PLUGIN_REGISTERING,
+            beforePayload: [
+                {
+                    schema: dependency
+                }
+            ],
+            afterEvent: AglynEvent.PLUGIN_REGISTERED,
+            afterPayload: [
+                {
+                    schema: dependency
+                }
+            ]
+        });
+        return;
+    }
+    addDependencies(dependencies) {
+        const _dependencies = Array.isArray(dependencies) ? dependencies : [];
+        for (const dependency of _dependencies){
+            this.addDependency(dependency);
+        }
+    }
+    destroyDependencies() {
+        const dependencyIds = Object.keys(this.dependencies);
+        for (const $id of dependencyIds){
+            this.removeDependency($id);
+        }
+    }
+    removeDependency($id) {
+        lifecycleEvent(()=>{
+            this.handleRemovingDependencyAndDependents($id);
+        }, {
+            beforeEvent: AglynEvent.PLUGIN_UNREGISTERING,
+            beforePayload: [
+                {
+                    $id
+                }
+            ],
+            afterEvent: AglynEvent.PLUGIN_UNREGISTERED,
+            afterPayload: [
+                {
+                    $id
+                }
+            ]
+        });
+        return;
+    }
+    loadDependency($id) {
+        return this.handleLoadingDependencyAndDependents($id);
+    }
+    unloadDependency($id) {
+        return this.handleUnloadingDependencyAndDependents($id);
+    }
+    getDependencyCopy(dependencyId) {
+        const dependency = this.getDependency(dependencyId);
+        return dependency ? _extends({}, dependency) : 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() {
+        const stuck = [];
+        for (const id of Object.keys(this.dependencyStatusById)){
+            var _this_getDependency;
+            if (!this.isDependencyWaiting(id)) continue;
+            const waitingOn = Object.keys(((_this_getDependency = this.getDependency(id)) == null ? void 0 : _this_getDependency.dependencies) || {}).filter((dependencyId)=>!this.isDependencyLoaded(dependencyId));
+            stuck.push({
+                id,
+                waitingOn
+            });
+        }
+        return stuck;
+    }
+    //     ____  __________  _____             ____ _    ________
+    //    / __ \/ ____/ __ \/ ___/            / __ \ |  / /_  __/
+    //   / / / / __/ / /_/ /\__ \   ______   / /_/ / | / / / /
+    //  / /_/ / /___/ ____/___/ /  /_____/  / ____/| |/ / / /
+    // /_____/_____/_/    /____/           /_/     |___/ /_/
+    // 👇
+    handleSettingDependencyProperties(dependencyId, dependency) {
+        var _this_dependencyDependentsById, _dependencyId;
+        this.dependencyStatusById[dependencyId] = "waiting";
+        (_this_dependencyDependentsById = this.dependencyDependentsById)[_dependencyId = dependencyId] || (_this_dependencyDependentsById[_dependencyId] = {});
+        this.dependencies[dependencyId] = dependency;
+        return;
+    }
+    handleSettingDependencyDependents(dependencyId) {
+        var _this_getDependency;
+        for (const dependentId of Object.keys(((_this_getDependency = this.getDependency(dependencyId)) == null ? void 0 : _this_getDependency.dependencies) || {})){
+            // Read the bucket back instead of using the value of `||= {}` (AGL-759).
+            // This class is `makeAutoObservable`, so assigning a plain `{}` stores an
+            // observable COPY of it — while `x ||= {}` evaluates to the plain object
+            // that was assigned, not the copy that was stored. Mutating that captured
+            // object wrote into something already detached from the manager.
+            //
+            // Only the FIRST dependent of any given dependency was lost, because
+            // every later one found the key present and short-circuited onto the real
+            // observable. In manifest order that made `bookings` — the first bundle
+            // depending on mui — permanently WAITING on every besigner, with no
+            // error: its components simply never registered and the drawer was short
+            // a category. `plugins.dependencyDependentsById` reads empty for that
+            // first edge, which is the fingerprint.
+            if (!this.dependencyDependentsById[dependentId]) {
+                this.dependencyDependentsById[dependentId] = {};
+            }
+            this.dependencyDependentsById[dependentId][dependencyId] = true;
+        }
+        return;
+    }
+    handleRemovingDependencyDependents(dependencyId) {
+        var _this_getDependency;
+        for (const dependentId of Object.keys(((_this_getDependency = this.getDependency(dependencyId)) == null ? void 0 : _this_getDependency.dependencies) || {})){
+            var _this_dependencyDependentsById_dependentId;
+            (_this_dependencyDependentsById_dependentId = this.dependencyDependentsById[dependentId]) == null ? true : delete _this_dependencyDependentsById_dependentId[dependencyId];
+        }
+        return;
+    }
+    handleRemovingDependencyProperties(dependencyId) {
+        delete this.dependencyDependentsById[dependencyId];
+        delete this.dependencyStatusById[dependencyId];
+        delete this.dependencies[dependencyId];
+        return;
+    }
+    handleLoadingDependencyDependents(dependencyId) {
+        for (const dependentId of Object.keys(this.getDependencyDependents(dependencyId) || {})){
+            if (!this.isDependencyLoaded(dependentId)) {
+                this.handleLoadingDependencyAndDependents(dependentId);
+            }
+        }
+        return;
+    }
+    handleLoadingDependency(dependencyId) {
+        if (this.isDependencyWaiting(dependencyId)) {
+            var _this_getDependency_load, _this_getDependency;
+            this.dependencyStatusById[dependencyId] = "loading";
+            (_this_getDependency = this.getDependency(dependencyId)) == null ? void 0 : (_this_getDependency_load = _this_getDependency.load) == null ? void 0 : _this_getDependency_load.call(_this_getDependency);
+            this.dependencyStatusById[dependencyId] = "loaded";
+        }
+        return;
+    }
+    handleUnloadingDependencyDependents(dependencyId) {
+        for (const dependentId of Object.keys(this.getDependencyDependents(dependencyId) || {})){
+            this.handleUnloadingDependencyAndDependents(dependentId);
+        }
+        return;
+    }
+    handleUnloadingDependency(dependencyId) {
+        if (this.isDependencyLoaded(dependencyId)) {
+            var _this_getDependency_destroy, _this_getDependency;
+            this.dependencyStatusById[dependencyId] = "unloading";
+            (_this_getDependency = this.getDependency(dependencyId)) == null ? void 0 : (_this_getDependency_destroy = _this_getDependency.destroy) == null ? void 0 : _this_getDependency_destroy.call(_this_getDependency);
+            this.dependencyStatusById[dependencyId] = "waiting";
+        }
+        return;
+    }
+    handleAddingDependencyAndDependents(dependency) {
+        if (!dependency) throw new Error('Invalid dependency');
+        const dependencyId = dependency.$id;
+        if (!dependencyId) throw new Error('Invalid dependencyId');
+        /**
+     * Set properties on local dependencies object
+     */ this.handleSettingDependencyProperties(dependencyId, dependency);
+        /**
+     * Set dependencies' dependent relationships
+     */ this.handleSettingDependencyDependents(dependencyId);
+        /**
+     * Load applicable dependencies
+     */ this.handleLoadingDependencyAndDependents(dependencyId);
+        return;
+    }
+    handleLoadingDependencyAndDependents(dependencyId) {
+        if (!this.hasDependency(dependencyId)) return;
+        /**
+     * Verify all dependencies are loaded
+     */ if (!this.areAllDependenciesLoaded(dependencyId)) return;
+        /**
+     * Load the self dependency
+     */ this.handleLoadingDependency(dependencyId);
+        /**
+     * Load waiting dependents
+     */ this.handleLoadingDependencyDependents(dependencyId);
+        return;
+    }
+    handleUnloadingDependencyAndDependents(dependencyId) {
+        if (!this.hasDependency(dependencyId)) return;
+        /**
+     * Unload all dependents of the dependency
+     */ this.handleUnloadingDependencyDependents(dependencyId);
+        /**
+     * Unload self dependency
+     */ this.handleUnloadingDependency(dependencyId);
+        return;
+    }
+    handleRemovingDependencyAndDependents(dependencyId) {
+        if (!this.hasDependency(dependencyId)) return;
+        /**
+     * Unload dependency and its dependents
+     */ this.handleUnloadingDependencyAndDependents(dependencyId);
+        /**
+     * Remove dependencies dependent relationships
+     */ this.handleRemovingDependencyDependents(dependencyId);
+        /**
+     * Remove self from local dependencies property
+     */ this.handleRemovingDependencyProperties(dependencyId);
+        return;
+    }
+    constructor(aglyn){
+        this.aglyn = aglyn;
+        //     ____  __________  _______   _______________________
+        //    / __ \/ ____/ __ \/ ____/ | / / ____/  _/ ____/ ___/
+        //   / / / / __/ / /_/ / __/ /  |/ / /    / // __/  \__ \
+        //  / /_/ / /___/ ____/ /___/ /|  / /____/ // /___ ___/ /
+        // /_____/_____/_/   /_____/_/ |_/\____/___/_____//____/
+        //
+        this.dependencies = {};
+        this.dependencyStatusById = {};
+        this.dependencyDependentsById = {};
+        makeAutoObservable(this);
+    }
+}
+export default PluginManager;
+
+//# sourceMappingURL=plugin-manager.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-manager.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\nimport type { MdiIconProps } from '../types/nodes'\nimport { makeAutoObservable } from 'mobx'\nimport type { Aglyn } from '../aglyn'\nimport { lifecycleEvent } from '../lifecycle'\nimport { AglynEvent } from '../emit-manager'\n\nexport enum PluginStatus {\n  WAITING = 'waiting',\n  LOADING = 'loading',\n  LOADED = 'loaded',\n  UNLOADING = 'unloading',\n}\n\nimport type { PluginId } from '../foundation'\nexport type { PluginId }\nexport type PluginStatusById = Record<PluginId, PluginStatus>\nexport type PluginsById = Record<PluginId, Plugin>\nexport type PluginDependencies = Record<PluginId, true>\nexport type Dependents = Record<PluginId, true>\nexport type PluginDependents = Record<PluginId, Dependents>\n\nexport interface Plugin {\n  $id?: PluginId\n  displayName?: string\n  title?: string\n  subtitle?: string\n  description?: string\n  icon?: MdiIconProps\n  dependencies?: PluginDependencies\n  load?(...args: any[]): void\n  destroy?(...args: any[]): void\n}\n\n// export const plugins: Record<PluginId, Plugin> = {}\n//\n// export function getBundle(pluginId: PluginId) {\n//   return plugins[pluginId]\n// }\n//\n// export function hasBundle(pluginId: PluginId) {\n//   return pluginId && _hasOwnProperty(pluginId, plugins)\n// }\n//\n// export function registerBundle(schema: Plugin) {\n//   const { $id: pluginId } = schema\n//   lifecycleEvent(\n//     () => {\n//       addDependency(schema)\n//       plugins[pluginId] = schema\n//       // for (const preset of schema.presets || []) {\n//       //   emitter.emit(AglynEvent.PRESET_REGISTER, { preset })\n//       // }\n//     },\n//     {\n//       beforeEvent: AglynEvent.PLUGIN_REGISTERING,\n//       beforePayload: [{ schema }],\n//       afterEvent: AglynEvent.PLUGIN_REGISTERED,\n//       afterPayload: [{ schema }],\n//     },\n//   )\n// }\n//\n// export function unregisterBundle(pluginId: PluginId) {\n//   const bundle = plugins[pluginId]\n//   lifecycleEvent(\n//     () => {\n//       if (!bundle) throw new Error(`No bundle exists with $id ${pluginId}`)\n//\n//       // for (const componentId of bundle.componentIds || []) {\n//       //   emitter.emit(AglynEvent.COMPONENT_UNREGISTER, { componentId, pluginId })\n//       // }\n//       delete plugins[pluginId]\n//     },\n//     {\n//       beforeEvent: AglynEvent.PLUGIN_UNREGISTERING,\n//       beforePayload: [{ pluginId }],\n//       afterEvent: AglynEvent.PLUGIN_UNREGISTERED,\n//       afterPayload: [{ pluginId }],\n//     },\n//   )\n// }\n\nexport class PluginManager {\n  //     ____  __________  _______   _______________________\n  //    / __ \\/ ____/ __ \\/ ____/ | / / ____/  _/ ____/ ___/\n  //   / / / / __/ / /_/ / __/ /  |/ / /    / // __/  \\__ \\\n  //  / /_/ / /___/ ____/ /___/ /|  / /____/ // /___ ___/ /\n  // /_____/_____/_/   /_____/_/ |_/\\____/___/_____//____/\n  //\n\n  public dependencies: PluginsById = {}\n  public dependencyStatusById: PluginStatusById = {}\n  public dependencyDependentsById: PluginDependents = {}\n\n  constructor(protected aglyn?: Aglyn) {\n    makeAutoObservable(this)\n  }\n\n  public getDependency(dependencyId: PluginId): Plugin | undefined {\n    return this.dependencies[dependencyId]\n  }\n\n  public getDependencyDependents(\n    dependencyId: PluginId,\n  ): Dependents | undefined {\n    return this.dependencyDependentsById[dependencyId]\n  }\n\n  public getDependencyStatus(dependencyId: PluginId): PluginStatus | undefined {\n    return this.dependencyStatusById[dependencyId]\n  }\n\n  public hasDependency(dependencyId: PluginId): boolean {\n    return Boolean(dependencyId && this.getDependency(dependencyId))\n  }\n\n  public isDependencyWaiting(dependencyId: PluginId): boolean {\n    return this.getDependencyStatus(dependencyId) === PluginStatus.WAITING\n  }\n\n  public isDependencyLoading(dependencyId: PluginId): boolean {\n    return this.getDependencyStatus(dependencyId) === PluginStatus.LOADING\n  }\n\n  public isDependencyLoaded(dependencyId: PluginId): boolean {\n    return this.getDependencyStatus(dependencyId) === PluginStatus.LOADED\n  }\n\n  public isDependencyUnloading(dependencyId: PluginId): boolean {\n    return this.getDependencyStatus(dependencyId) === PluginStatus.UNLOADING\n  }\n\n  public areAllDependenciesLoaded(dependentId: PluginId): boolean {\n    for (const dependencyId of Object.keys(\n      this.getDependency(dependentId)?.dependencies || {},\n    )) {\n      if (!this.isDependencyLoaded(dependencyId)) {\n        return false\n      }\n    }\n    return true\n  }\n\n  public addDependency(dependency: Plugin) {\n    lifecycleEvent(\n      () => {\n        this.handleAddingDependencyAndDependents(dependency)\n      },\n      {\n        beforeEvent: AglynEvent.PLUGIN_REGISTERING,\n        beforePayload: [{ schema: dependency }],\n        afterEvent: AglynEvent.PLUGIN_REGISTERED,\n        afterPayload: [{ schema: dependency }],\n      },\n    )\n    return\n  }\n\n  public addDependencies(dependencies?: Array<Plugin>) {\n    const _dependencies = Array.isArray(dependencies) ? dependencies : []\n    for (const dependency of _dependencies) {\n      this.addDependency(dependency)\n    }\n  }\n\n  public destroyDependencies() {\n    const dependencyIds = Object.keys(this.dependencies)\n    for (const $id of dependencyIds) {\n      this.removeDependency($id)\n    }\n  }\n\n  public removeDependency($id: PluginId) {\n    lifecycleEvent(\n      () => {\n        this.handleRemovingDependencyAndDependents($id)\n      },\n      {\n        beforeEvent: AglynEvent.PLUGIN_UNREGISTERING,\n        beforePayload: [{ $id }],\n        afterEvent: AglynEvent.PLUGIN_UNREGISTERED,\n        afterPayload: [{ $id }],\n      },\n    )\n    return\n  }\n\n  public loadDependency($id: PluginId) {\n    return this.handleLoadingDependencyAndDependents($id)\n  }\n\n  public unloadDependency($id: PluginId) {\n    return this.handleUnloadingDependencyAndDependents($id)\n  }\n\n  public getDependencyCopy(\n    dependencyId: PluginId,\n  ): Readonly<Plugin> | undefined {\n    const dependency = this.getDependency(dependencyId)\n    return dependency ? { ...dependency } : undefined\n  }\n\n  /**\n   * Every registered dependency still parked in WAITING, paired with the\n   * dependencies it is waiting on that have not loaded (AGL-759).\n   *\n   * A bundle lands here when a dependency it declared never reached LOADED.\n   * With the reverse-dependency edge fixed, a bundle that registers before\n   * its dependency is recovered as soon as the dependency finishes — so the\n   * only thing left in this list once a batch has settled is a bundle whose\n   * dependency was never activated at all (a manifest/enablement gap). That\n   * used to present as an empty besigner drawer with no error: the bundle's\n   * components simply never registered. Callers report this at a settle\n   * point (the plugin loader, after an `ensure`) so the gap says so instead.\n   */\n  public getStuckDependencies(): Array<{\n    id: PluginId\n    waitingOn: PluginId[]\n  }> {\n    const stuck: Array<{ id: PluginId; waitingOn: PluginId[] }> = []\n    for (const id of Object.keys(this.dependencyStatusById)) {\n      if (!this.isDependencyWaiting(id)) continue\n      const waitingOn = Object.keys(\n        this.getDependency(id)?.dependencies || {},\n      ).filter((dependencyId) => !this.isDependencyLoaded(dependencyId))\n      stuck.push({ id, waitingOn })\n    }\n    return stuck\n  }\n\n  //     ____  __________  _____             ____ _    ________\n  //    / __ \\/ ____/ __ \\/ ___/            / __ \\ |  / /_  __/\n  //   / / / / __/ / /_/ /\\__ \\   ______   / /_/ / | / / / /\n  //  / /_/ / /___/ ____/___/ /  /_____/  / ____/| |/ / / /\n  // /_____/_____/_/    /____/           /_/     |___/ /_/\n  // 👇\n\n  private handleSettingDependencyProperties(\n    dependencyId: PluginId,\n    dependency: Plugin,\n  ) {\n    this.dependencyStatusById[dependencyId] = PluginStatus.WAITING\n    this.dependencyDependentsById[dependencyId] ||= {}\n    this.dependencies[dependencyId] = dependency\n    return\n  }\n\n  private handleSettingDependencyDependents(dependencyId: PluginId) {\n    for (const dependentId of Object.keys(\n      this.getDependency(dependencyId)?.dependencies || {},\n    )) {\n      // Read the bucket back instead of using the value of `||= {}` (AGL-759).\n      // This class is `makeAutoObservable`, so assigning a plain `{}` stores an\n      // observable COPY of it — while `x ||= {}` evaluates to the plain object\n      // that was assigned, not the copy that was stored. Mutating that captured\n      // object wrote into something already detached from the manager.\n      //\n      // Only the FIRST dependent of any given dependency was lost, because\n      // every later one found the key present and short-circuited onto the real\n      // observable. In manifest order that made `bookings` — the first bundle\n      // depending on mui — permanently WAITING on every besigner, with no\n      // error: its components simply never registered and the drawer was short\n      // a category. `plugins.dependencyDependentsById` reads empty for that\n      // first edge, which is the fingerprint.\n      if (!this.dependencyDependentsById[dependentId]) {\n        this.dependencyDependentsById[dependentId] = {}\n      }\n      this.dependencyDependentsById[dependentId][dependencyId] = true\n    }\n    return\n  }\n\n  private handleRemovingDependencyDependents(dependencyId: PluginId) {\n    for (const dependentId of Object.keys(\n      this.getDependency(dependencyId)?.dependencies || {},\n    )) {\n      delete this.dependencyDependentsById[dependentId]?.[dependencyId]\n    }\n    return\n  }\n\n  private handleRemovingDependencyProperties(dependencyId: PluginId) {\n    delete this.dependencyDependentsById[dependencyId]\n    delete this.dependencyStatusById[dependencyId]\n    delete this.dependencies[dependencyId]\n    return\n  }\n\n  private handleLoadingDependencyDependents(dependencyId: PluginId) {\n    for (const dependentId of Object.keys(\n      this.getDependencyDependents(dependencyId) || {},\n    )) {\n      if (!this.isDependencyLoaded(dependentId)) {\n        this.handleLoadingDependencyAndDependents(dependentId)\n      }\n    }\n    return\n  }\n\n  private handleLoadingDependency(dependencyId: PluginId) {\n    if (this.isDependencyWaiting(dependencyId)) {\n      this.dependencyStatusById[dependencyId] = PluginStatus.LOADING\n      this.getDependency(dependencyId)?.load?.()\n      this.dependencyStatusById[dependencyId] = PluginStatus.LOADED\n    }\n    return\n  }\n\n  private handleUnloadingDependencyDependents(dependencyId: PluginId) {\n    for (const dependentId of Object.keys(\n      this.getDependencyDependents(dependencyId) || {},\n    )) {\n      this.handleUnloadingDependencyAndDependents(dependentId)\n    }\n    return\n  }\n\n  private handleUnloadingDependency(dependencyId: PluginId) {\n    if (this.isDependencyLoaded(dependencyId)) {\n      this.dependencyStatusById[dependencyId] = PluginStatus.UNLOADING\n      this.getDependency(dependencyId)?.destroy?.()\n      this.dependencyStatusById[dependencyId] = PluginStatus.WAITING\n    }\n    return\n  }\n\n  private handleAddingDependencyAndDependents(dependency: Plugin) {\n    if (!dependency) throw new Error('Invalid dependency')\n    const dependencyId: PluginId = dependency.$id\n    if (!dependencyId) throw new Error('Invalid dependencyId')\n    /**\n     * Set properties on local dependencies object\n     */\n    this.handleSettingDependencyProperties(dependencyId, dependency)\n    /**\n     * Set dependencies' dependent relationships\n     */\n    this.handleSettingDependencyDependents(dependencyId)\n    /**\n     * Load applicable dependencies\n     */\n    this.handleLoadingDependencyAndDependents(dependencyId)\n    return\n  }\n\n  private handleLoadingDependencyAndDependents(dependencyId: PluginId) {\n    if (!this.hasDependency(dependencyId)) return\n    /**\n     * Verify all dependencies are loaded\n     */\n    if (!this.areAllDependenciesLoaded(dependencyId)) return\n    /**\n     * Load the self dependency\n     */\n    this.handleLoadingDependency(dependencyId)\n    /**\n     * Load waiting dependents\n     */\n    this.handleLoadingDependencyDependents(dependencyId)\n    return\n  }\n\n  private handleUnloadingDependencyAndDependents(dependencyId: PluginId) {\n    if (!this.hasDependency(dependencyId)) return\n    /**\n     * Unload all dependents of the dependency\n     */\n    this.handleUnloadingDependencyDependents(dependencyId)\n    /**\n     * Unload self dependency\n     */\n    this.handleUnloadingDependency(dependencyId)\n    return\n  }\n\n  private handleRemovingDependencyAndDependents(dependencyId: PluginId) {\n    if (!this.hasDependency(dependencyId)) return\n    /**\n     * Unload dependency and its dependents\n     */\n    this.handleUnloadingDependencyAndDependents(dependencyId)\n\n    /**\n     * Remove dependencies dependent relationships\n     */\n    this.handleRemovingDependencyDependents(dependencyId)\n\n    /**\n     * Remove self from local dependencies property\n     */\n    this.handleRemovingDependencyProperties(dependencyId)\n    return\n  }\n}\n\nexport default PluginManager\n"],"names":["makeAutoObservable","lifecycleEvent","AglynEvent","PluginStatus","PluginManager","getDependency","dependencyId","dependencies","getDependencyDependents","dependencyDependentsById","getDependencyStatus","dependencyStatusById","hasDependency","Boolean","isDependencyWaiting","isDependencyLoading","isDependencyLoaded","isDependencyUnloading","areAllDependenciesLoaded","dependentId","Object","keys","addDependency","dependency","handleAddingDependencyAndDependents","beforeEvent","PLUGIN_REGISTERING","beforePayload","schema","afterEvent","PLUGIN_REGISTERED","afterPayload","addDependencies","_dependencies","Array","isArray","destroyDependencies","dependencyIds","$id","removeDependency","handleRemovingDependencyAndDependents","PLUGIN_UNREGISTERING","PLUGIN_UNREGISTERED","loadDependency","handleLoadingDependencyAndDependents","unloadDependency","handleUnloadingDependencyAndDependents","getDependencyCopy","undefined","getStuckDependencies","stuck","id","waitingOn","filter","push","handleSettingDependencyProperties","handleSettingDependencyDependents","handleRemovingDependencyDependents","handleRemovingDependencyProperties","handleLoadingDependencyDependents","handleLoadingDependency","load","handleUnloadingDependencyDependents","handleUnloadingDependency","destroy","Error","aglyn"],"mappings":"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"}

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

@@ -0,0 +1,97 @@
+/**
+ * @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.
+ */
+/** One plugin's claim on one line. */
+export interface PluginMeteredLineClaim {
+    /**
+     * The line the sweep knows, e.g. the assist-overage line. Core's own name
+     * for a figure it already computes — not a plugin's internal name for it.
+     */
+    lineId: string;
+    /** The plugin that bills it. */
+    pluginId: string;
+    /**
+     * The first month (`YYYY-MM`) the plugin bills the line for, or `null`
+     * while the plugin has registered the claim but not yet been switched on.
+     *
+     * A function rather than a value because the answer comes from deployment
+     * configuration that can change without a restart, and because a claim
+     * evaluated once at boot would pin the cutover to whenever the process
+     * happened to start.
+     */
+    billsFrom: () => string | null;
+    /**
+     * Called once per workspace for a month this sweep has CLOSED, so a plugin
+     * billing the line can settle what is left of it.
+     *
+     * A plugin that charges as usage accrues always has a remainder: the part
+     * that never reached its threshold before the month ended. Something has to
+     * bill that, and the sweep that closes the month is the one thing that
+     * already knows every workspace, its month and its Stripe customer — which
+     * is why this is a hook here rather than a second cron with a second
+     * schedule to keep in step with this one.
+     *
+     * Called whether or not the meter reported for the workspace, because the
+     * remainder is owed either way. Errors are logged and never the sweep's:
+     * this is money the plugin bills, and failing the platform's own metering
+     * over it would be the larger loss. A plugin makes it idempotent; it is
+     * called again every day the sweep runs.
+     */
+    closeMonth?: (context: PluginMeteredLineMonthContext) => Promise<void>;
+}
+/** What a plugin is told about one workspace's closed month. */
+export interface PluginMeteredLineMonthContext {
+    orgId: string;
+    /** `YYYY-MM`, the month that closed. */
+    month: string;
+    /** The workspace's own document, as the sweep already read it. */
+    org: Record<string, unknown>;
+    /** Its Stripe customer, or `null` when it has none. */
+    stripeCustomerId: string | null;
+}
+/**
+ * Claims a meter line. One plugin per line: a second plugin claiming a line
+ * another already holds throws, because two plugins each believing they bill
+ * a line is how it reaches no invoice at all.
+ *
+ * The same plugin re-registering replaces its own claim, so a module
+ * evaluated twice leaves one claim rather than two.
+ */
+export declare function registerPluginMeteredLine(claim: Omit<PluginMeteredLineClaim, 'pluginId'> & {
+    pluginId?: string;
+}): void;
+/**
+ * Does a plugin bill this line for this month, so the sweep must leave it
+ * out of the meter figure?
+ *
+ * A claim whose `billsFrom` throws answers `false` and logs: the sweep is
+ * the only thing that bills the line while a claim is broken, and a throw
+ * that propagated would fail the whole month's billing for every workspace.
+ */
+export declare function pluginBillsMeteredLine(lineId: string, month: string): boolean;
+/**
+ * Runs the claiming plugin's close-out for one workspace's closed month.
+ *
+ * `false` when no plugin claims the line, when it does not bill this month,
+ * or when it registered no close-out — three different "nothing happened"s
+ * that the sweep does not need to tell apart, and the plugin is the only
+ * thing that could.
+ */
+export declare function runPluginMeteredLineClose(lineId: string, context: PluginMeteredLineMonthContext): Promise<boolean>;
+/** The plugin billing a line, for diagnostics and staff readouts. */
+export declare function pluginMeteredLineOwner(lineId: string): string | null;
+/** Test seam: forget every claim. */
+export declare function resetPluginMeteredLinesForTests(): void;

package/src/lib/plugin-manager/plugin-metered-lines.js

@@ -0,0 +1,123 @@
+/**
+ * @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.
+ */ /**
+ * A METER LINE A PLUGIN BILLS FOR ITSELF (AGL-3011).
+ *
+ * The monthly usage sweep prices several lines into one figure and posts it
+ * as a single Stripe meter event. A plugin that bills one of those lines its
+ * own way — charging it as it accrues, say — must have that line LEFT OUT of
+ * the meter figure from the month it takes over, or the customer is billed
+ * for it twice.
+ *
+ * That claim is what this registry holds: a line id, the plugin that owns
+ * the billing of it, and the first month from which the plugin bills it. The
+ * sweep asks by line id and gets a yes or a no. It never learns how the
+ * plugin bills, and the plugin never edits the sweep.
+ *
+ * ## Only the billing moves, never the measurement
+ *
+ * A claimed line is still measured, still priced and still written to the
+ * month's audit fields. What changes is whether its dollars enter the figure
+ * the meter event carries. "We stopped billing it here" and "we stopped
+ * counting it" must stay different facts, or a claim would erase a month of
+ * usage history along with its invoice line.
+ *
+ * ## Unclaimed is the safe answer
+ *
+ * A line nobody claimed, a month before the claim's start, an unparseable
+ * start month and a plugin that failed to register all answer the same way:
+ * the sweep bills the line as it always has. Every failure mode therefore
+ * bills through the channel that already works, rather than through neither.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const claims = new Map();
+/**
+ * Claims a meter line. One plugin per line: a second plugin claiming a line
+ * another already holds throws, because two plugins each believing they bill
+ * a line is how it reaches no invoice at all.
+ *
+ * The same plugin re-registering replaces its own claim, so a module
+ * evaluated twice leaves one claim rather than two.
+ */ export function registerPluginMeteredLine(claim) {
+    var _ref, _getRegisteringPluginId;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : claim.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`metered line "${claim.lineId}" claimed with no owner: pass ` + '{ pluginId } when registering outside a plugin register fn');
+    }
+    const held = claims.get(claim.lineId);
+    if (held && held.pluginId !== pluginId) {
+        throw new Error(`metered line "${claim.lineId}" is already billed by plugin ` + `"${held.pluginId}"; "${pluginId}" cannot claim it too`);
+    }
+    claims.set(claim.lineId, {
+        lineId: claim.lineId,
+        pluginId,
+        billsFrom: claim.billsFrom,
+        closeMonth: claim.closeMonth
+    });
+}
+/**
+ * Does a plugin bill this line for this month, so the sweep must leave it
+ * out of the meter figure?
+ *
+ * A claim whose `billsFrom` throws answers `false` and logs: the sweep is
+ * the only thing that bills the line while a claim is broken, and a throw
+ * that propagated would fail the whole month's billing for every workspace.
+ */ export function pluginBillsMeteredLine(lineId, month) {
+    const claim = claims.get(lineId);
+    if (!claim) return false;
+    let from;
+    try {
+        from = claim.billsFrom();
+    } catch (error) {
+        console.error(`[plugins] ${claim.pluginId} failed to answer for ${lineId}`, error);
+        return false;
+    }
+    const start = String(from != null ? from : '').trim();
+    if (!/^\d{4}-\d{2}$/.test(start)) return false;
+    if (!/^\d{4}-\d{2}$/.test(month)) return false;
+    // Zero-padded fixed-width `YYYY-MM` orders identically as a string and as
+    // a date; the format checks above are what make that true rather than
+    // lucky. The same comparison `billsEmailSendOverage` makes on its own gate.
+    return month >= start;
+}
+/**
+ * Runs the claiming plugin's close-out for one workspace's closed month.
+ *
+ * `false` when no plugin claims the line, when it does not bill this month,
+ * or when it registered no close-out — three different "nothing happened"s
+ * that the sweep does not need to tell apart, and the plugin is the only
+ * thing that could.
+ */ export async function runPluginMeteredLineClose(lineId, context) {
+    const claim = claims.get(lineId);
+    if (!(claim == null ? void 0 : claim.closeMonth)) return false;
+    if (!pluginBillsMeteredLine(lineId, context.month)) return false;
+    try {
+        await claim.closeMonth(context);
+        return true;
+    } catch (error) {
+        console.error(`[plugins] ${claim.pluginId} failed to close ${lineId} for ${context.orgId}`, error);
+        return false;
+    }
+}
+/** The plugin billing a line, for diagnostics and staff readouts. */ export function pluginMeteredLineOwner(lineId) {
+    var _ref;
+    var _claims_get;
+    return (_ref = (_claims_get = claims.get(lineId)) == null ? void 0 : _claims_get.pluginId) != null ? _ref : null;
+}
+/** Test seam: forget every claim. */ export function resetPluginMeteredLinesForTests() {
+    claims.clear();
+}
+
+//# sourceMappingURL=plugin-metered-lines.js.map

package/src/lib/plugin-manager/plugin-metered-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-metered-lines.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 * A METER LINE A PLUGIN BILLS FOR ITSELF (AGL-3011).\n *\n * The monthly usage sweep prices several lines into one figure and posts it\n * as a single Stripe meter event. A plugin that bills one of those lines its\n * own way — charging it as it accrues, say — must have that line LEFT OUT of\n * the meter figure from the month it takes over, or the customer is billed\n * for it twice.\n *\n * That claim is what this registry holds: a line id, the plugin that owns\n * the billing of it, and the first month from which the plugin bills it. The\n * sweep asks by line id and gets a yes or a no. It never learns how the\n * plugin bills, and the plugin never edits the sweep.\n *\n * ## Only the billing moves, never the measurement\n *\n * A claimed line is still measured, still priced and still written to the\n * month's audit fields. What changes is whether its dollars enter the figure\n * the meter event carries. \"We stopped billing it here\" and \"we stopped\n * counting it\" must stay different facts, or a claim would erase a month of\n * usage history along with its invoice line.\n *\n * ## Unclaimed is the safe answer\n *\n * A line nobody claimed, a month before the claim's start, an unparseable\n * start month and a plugin that failed to register all answer the same way:\n * the sweep bills the line as it always has. Every failure mode therefore\n * bills through the channel that already works, rather than through neither.\n */\n\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** One plugin's claim on one line. */\nexport interface PluginMeteredLineClaim {\n  /**\n   * The line the sweep knows, e.g. the assist-overage line. Core's own name\n   * for a figure it already computes — not a plugin's internal name for it.\n   */\n  lineId: string\n  /** The plugin that bills it. */\n  pluginId: string\n  /**\n   * The first month (`YYYY-MM`) the plugin bills the line for, or `null`\n   * while the plugin has registered the claim but not yet been switched on.\n   *\n   * A function rather than a value because the answer comes from deployment\n   * configuration that can change without a restart, and because a claim\n   * evaluated once at boot would pin the cutover to whenever the process\n   * happened to start.\n   */\n  billsFrom: () => string | null\n  /**\n   * Called once per workspace for a month this sweep has CLOSED, so a plugin\n   * billing the line can settle what is left of it.\n   *\n   * A plugin that charges as usage accrues always has a remainder: the part\n   * that never reached its threshold before the month ended. Something has to\n   * bill that, and the sweep that closes the month is the one thing that\n   * already knows every workspace, its month and its Stripe customer — which\n   * is why this is a hook here rather than a second cron with a second\n   * schedule to keep in step with this one.\n   *\n   * Called whether or not the meter reported for the workspace, because the\n   * remainder is owed either way. Errors are logged and never the sweep's:\n   * this is money the plugin bills, and failing the platform's own metering\n   * over it would be the larger loss. A plugin makes it idempotent; it is\n   * called again every day the sweep runs.\n   */\n  closeMonth?: (context: PluginMeteredLineMonthContext) => Promise<void>\n}\n\n/** What a plugin is told about one workspace's closed month. */\nexport interface PluginMeteredLineMonthContext {\n  orgId: string\n  /** `YYYY-MM`, the month that closed. */\n  month: string\n  /** The workspace's own document, as the sweep already read it. */\n  org: Record<string, unknown>\n  /** Its Stripe customer, or `null` when it has none. */\n  stripeCustomerId: string | null\n}\n\nconst claims = new Map<string, PluginMeteredLineClaim>()\n\n/**\n * Claims a meter line. One plugin per line: a second plugin claiming a line\n * another already holds throws, because two plugins each believing they bill\n * a line is how it reaches no invoice at all.\n *\n * The same plugin re-registering replaces its own claim, so a module\n * evaluated twice leaves one claim rather than two.\n */\nexport function registerPluginMeteredLine(\n  claim: Omit<PluginMeteredLineClaim, 'pluginId'> & { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? claim.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      `metered line \"${claim.lineId}\" claimed with no owner: pass ` +\n        '{ pluginId } when registering outside a plugin register fn',\n    )\n  }\n  const held = claims.get(claim.lineId)\n  if (held && held.pluginId !== pluginId) {\n    throw new Error(\n      `metered line \"${claim.lineId}\" is already billed by plugin ` +\n        `\"${held.pluginId}\"; \"${pluginId}\" cannot claim it too`,\n    )\n  }\n  claims.set(claim.lineId, {\n    lineId: claim.lineId,\n    pluginId,\n    billsFrom: claim.billsFrom,\n    closeMonth: claim.closeMonth,\n  })\n}\n\n/**\n * Does a plugin bill this line for this month, so the sweep must leave it\n * out of the meter figure?\n *\n * A claim whose `billsFrom` throws answers `false` and logs: the sweep is\n * the only thing that bills the line while a claim is broken, and a throw\n * that propagated would fail the whole month's billing for every workspace.\n */\nexport function pluginBillsMeteredLine(lineId: string, month: string): boolean {\n  const claim = claims.get(lineId)\n  if (!claim) return false\n  let from: string | null\n  try {\n    from = claim.billsFrom()\n  } catch (error) {\n    console.error(`[plugins] ${claim.pluginId} failed to answer for ${lineId}`, error)\n    return false\n  }\n  const start = String(from ?? '').trim()\n  if (!/^\\d{4}-\\d{2}$/.test(start)) return false\n  if (!/^\\d{4}-\\d{2}$/.test(month)) return false\n  // Zero-padded fixed-width `YYYY-MM` orders identically as a string and as\n  // a date; the format checks above are what make that true rather than\n  // lucky. The same comparison `billsEmailSendOverage` makes on its own gate.\n  return month >= start\n}\n\n/**\n * Runs the claiming plugin's close-out for one workspace's closed month.\n *\n * `false` when no plugin claims the line, when it does not bill this month,\n * or when it registered no close-out — three different \"nothing happened\"s\n * that the sweep does not need to tell apart, and the plugin is the only\n * thing that could.\n */\nexport async function runPluginMeteredLineClose(\n  lineId: string,\n  context: PluginMeteredLineMonthContext,\n): Promise<boolean> {\n  const claim = claims.get(lineId)\n  if (!claim?.closeMonth) return false\n  if (!pluginBillsMeteredLine(lineId, context.month)) return false\n  try {\n    await claim.closeMonth(context)\n    return true\n  } catch (error) {\n    console.error(\n      `[plugins] ${claim.pluginId} failed to close ${lineId} for ${context.orgId}`,\n      error,\n    )\n    return false\n  }\n}\n\n/** The plugin billing a line, for diagnostics and staff readouts. */\nexport function pluginMeteredLineOwner(lineId: string): string | null {\n  return claims.get(lineId)?.pluginId ?? null\n}\n\n/** Test seam: forget every claim. */\nexport function resetPluginMeteredLinesForTests(): void {\n  claims.clear()\n}\n"],"names":["getRegisteringPluginId","claims","Map","registerPluginMeteredLine","claim","pluginId","trim","Error","lineId","held","get","set","billsFrom","closeMonth","pluginBillsMeteredLine","month","from","error","console","start","String","test","runPluginMeteredLineClose","context","orgId","pluginMeteredLineOwner","resetPluginMeteredLinesForTests","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AAoDxE,MAAMC,SAAS,IAAIC;AAEnB;;;;;;;CAOC,GACD,OAAO,SAASC,0BACdC,KAAuE;QAErDJ,MAAAA;IAAlB,MAAMK,WAAW,EAACL,QAAAA,0BAAAA,oCAAAA,0BAA4BI,MAAMC,QAAQ,YAA1CL,OAA8C,IAAIM,IAAI;IACxE,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,CAAC,cAAc,EAAEH,MAAMI,MAAM,CAAC,8BAA8B,CAAC,GAC3D;IAEN;IACA,MAAMC,OAAOR,OAAOS,GAAG,CAACN,MAAMI,MAAM;IACpC,IAAIC,QAAQA,KAAKJ,QAAQ,KAAKA,UAAU;QACtC,MAAM,IAAIE,MACR,CAAC,cAAc,EAAEH,MAAMI,MAAM,CAAC,8BAA8B,CAAC,GAC3D,CAAC,CAAC,EAAEC,KAAKJ,QAAQ,CAAC,IAAI,EAAEA,SAAS,qBAAqB,CAAC;IAE7D;IACAJ,OAAOU,GAAG,CAACP,MAAMI,MAAM,EAAE;QACvBA,QAAQJ,MAAMI,MAAM;QACpBH;QACAO,WAAWR,MAAMQ,SAAS;QAC1BC,YAAYT,MAAMS,UAAU;IAC9B;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,uBAAuBN,MAAc,EAAEO,KAAa;IAClE,MAAMX,QAAQH,OAAOS,GAAG,CAACF;IACzB,IAAI,CAACJ,OAAO,OAAO;IACnB,IAAIY;IACJ,IAAI;QACFA,OAAOZ,MAAMQ,SAAS;IACxB,EAAE,OAAOK,OAAO;QACdC,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEb,MAAMC,QAAQ,CAAC,sBAAsB,EAAEG,QAAQ,EAAES;QAC5E,OAAO;IACT;IACA,MAAME,QAAQC,OAAOJ,eAAAA,OAAQ,IAAIV,IAAI;IACrC,IAAI,CAAC,gBAAgBe,IAAI,CAACF,QAAQ,OAAO;IACzC,IAAI,CAAC,gBAAgBE,IAAI,CAACN,QAAQ,OAAO;IACzC,0EAA0E;IAC1E,sEAAsE;IACtE,4EAA4E;IAC5E,OAAOA,SAASI;AAClB;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeG,0BACpBd,MAAc,EACde,OAAsC;IAEtC,MAAMnB,QAAQH,OAAOS,GAAG,CAACF;IACzB,IAAI,EAACJ,yBAAAA,MAAOS,UAAU,GAAE,OAAO;IAC/B,IAAI,CAACC,uBAAuBN,QAAQe,QAAQR,KAAK,GAAG,OAAO;IAC3D,IAAI;QACF,MAAMX,MAAMS,UAAU,CAACU;QACvB,OAAO;IACT,EAAE,OAAON,OAAO;QACdC,QAAQD,KAAK,CACX,CAAC,UAAU,EAAEb,MAAMC,QAAQ,CAAC,iBAAiB,EAAEG,OAAO,KAAK,EAAEe,QAAQC,KAAK,EAAE,EAC5EP;QAEF,OAAO;IACT;AACF;AAEA,mEAAmE,GACnE,OAAO,SAASQ,uBAAuBjB,MAAc;;QAC5CP;IAAP,gBAAOA,cAAAA,OAAOS,GAAG,CAACF,4BAAXP,YAAoBI,QAAQ,mBAAI;AACzC;AAEA,mCAAmC,GACnC,OAAO,SAASqB;IACdzB,OAAO0B,KAAK;AACd"}