@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,244 @@
+/**
+ * @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.
+ */
+/**
+ * What a plugin contributes, and where (AGL-3116).
+ *
+ * A plugin loads only where something uses it. Installing one loads nothing:
+ * a published page fetches a plugin's code when the page places one of its
+ * elements or the site runs one of its features, and a console screen
+ * fetches it when the screen renders one of its slots or routes, or when the
+ * plugin draws something the shell renders on every screen.
+ *
+ * The loaders cannot learn that by running a plugin, because running it is
+ * the cost being avoided. So each plugin DECLARES its contributions:
+ * first-party plugins in `plugins.config.json`, marketplace plugins in the
+ * manifest they publish (`contributes`). The declaration is the whole of what
+ * a loader reads, and it is data: this module is dependency-free so the
+ * server, both apps, the verifier and the build tools share one reading.
+ *
+ * A declared surface only narrows where to look. Presence is the rule: a
+ * plugin that declares a component loads on the pages that place it, not on
+ * every page of the site that installed it.
+ *
+ * ## A plugin that declares nothing
+ *
+ * Every marketplace version published before this contract has no
+ * `contributes`. Such a plugin keeps working under one default:
+ *
+ * - **On a published page it loads only where its element is placed**: a
+ *   node whose `pluginId` names the plugin (its manifest id or its listing
+ *   id). That is the one presence signal a page carries without running the
+ *   bundle, and it is the only way a page can show an element the plugin
+ *   registers. A site runtime of an undeclared plugin does not load, and the
+ *   publish pipeline refuses a bundle that registers one without declaring
+ *   it, so the only plugins this default governs are the ones already
+ *   published.
+ * - **In the console it loads with the workspace shell**, as it always did,
+ *   because a nav tab or a provider is only discoverable by running
+ *   `register()`. Nothing on a published page depends on this.
+ */
+/** What a plugin adds to a published site. */
+export interface PluginSiteContributions {
+    /**
+     * Canvas component ids the plugin registers: the elements a page places. A
+     * published page loads the plugin only when its node tree places one.
+     */
+    components?: string[];
+    /**
+     * Site features: runtimes the plugin mounts on every page of a site that
+     * switched it on (an announcement bar, an experiment runner), named by the
+     * `runtimeId` it registers. A plugin with a feature loads on every page of
+     * such a site, which is what a feature is.
+     */
+    features?: string[];
+}
+/** What a plugin adds to the console. */
+export interface PluginConsoleContributions {
+    /**
+     * The widget slots its widgets fill: the `CONSOLE_WIDGET_SLOTS` zones, the
+     * panels the shell draws as slots (the assistant dock `assistPanel`, the
+     * besigner's `besignerInspector`), and zones another plugin hosts. A screen
+     * that renders one of them loads the plugin.
+     */
+    slots?: string[];
+    /** Site-level console routes it serves (`/forms`), beneath `/hosts/[host]`. */
+    routes?: string[];
+    /** Organization-level console routes it serves (`/outreach`). */
+    orgRoutes?: string[];
+    /**
+     * The shell draws something of it on every screen of a workspace: a nav
+     * tab, an organization tab, a staff tab or a provider. Such a plugin loads
+     * with the shell, because every screen renders it.
+     */
+    shell?: boolean;
+}
+export interface PluginContributions {
+    site?: PluginSiteContributions;
+    console?: PluginConsoleContributions;
+}
+/** Bound on each declared list, so a manifest cannot hand a loader a novel. */
+export declare const PLUGIN_MAX_CONTRIBUTIONS = 128;
+type Sanitized = {
+    ok: true;
+    contributions: PluginContributions;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validates a declared `contributes` block.
+ *
+ * Malformed input is REFUSED rather than trimmed: a loader reads this to
+ * decide where a plugin runs, so a declaration that silently lost an entry
+ * would stop the plugin loading where it is used, and nobody would see why.
+ * Duplicates are collapsed and empty lists dropped, because neither changes
+ * what the declaration means.
+ *
+ * `{}` is valid and means "contributes nothing anywhere", which is a
+ * different statement from an absent block (see the module note).
+ */
+export declare function sanitizePluginContributions(input: unknown): Sanitized;
+/**
+ * A declared `contributes` block as a loader may trust it: the sanitized
+ * block, or `undefined` for one that is absent or does not validate.
+ *
+ * Loaders read this from stored documents (a pinned version's manifest), and
+ * a malformed stored block is treated as UNDECLARED — the default applies —
+ * never as "contributes nothing", which would stop a plugin that is in use.
+ */
+export declare function readPluginContributions(input: unknown): PluginContributions | undefined;
+/**
+ * What the surface a plugin is being registered into actually uses
+ * (AGL-3141).
+ *
+ * The loaders carry this from the surface that computed it to each plugin's
+ * register function, unchanged. A plugin that can register a part of itself
+ * reads it; one that cannot ignores it, and the platform's behavior is the
+ * same either way.
+ *
+ * An absent field means "everything of that kind". A surface that cannot say
+ * what it uses must be handed all of it, because an element the surface
+ * places and the set omits has no registered component and renders NOTHING,
+ * silently (the blank-canvas invariant, AGL-52). Narrowing is an optimization
+ * and must fail toward the whole.
+ */
+export interface PluginUse {
+    /**
+     * Canvas component ids the surface places, read from the FULL composed
+     * document the way `pagePresence` reads it — withheld lazy-panel subtrees
+     * included, because an element inside a panel the visitor opens later is
+     * still this page's element.
+     */
+    componentIds?: readonly string[];
+}
+/** A node as presence reads it: the two ids a placed element carries. */
+export interface PresenceNode {
+    componentId?: string;
+    pluginId?: string;
+}
+/** What a published page places: its component ids and the plugin ids stamped on its nodes. */
+export interface PagePresence {
+    componentIds: ReadonlySet<string>;
+    pluginIds: ReadonlySet<string>;
+}
+/**
+ * The component ids and plugin ids a node tree places.
+ *
+ * Read from the FULL composed document — layouts, grafted reusable
+ * components and withheld lazy panels included — because an element inside
+ * a panel the visitor opens later is still this page's element.
+ */
+export declare function pagePresence(nodes: Record<string, PresenceNode | null | undefined> | null | undefined): PagePresence;
+/** A plugin as the presence rules see it. */
+export interface PresenceSubject {
+    /** The plugin's own id (a manifest `id`, or a first-party catalog id). */
+    pluginId?: string;
+    /** A marketplace plugin's listing id, which its elements may carry instead. */
+    listingId?: string;
+    /** Its declaration; `undefined` when it declares nothing. */
+    contributes?: PluginContributions;
+}
+/**
+ * Whether a published page uses a plugin, so the page must load it.
+ *
+ * - An element of it is placed: a node stamped with the plugin's id, or,
+ *   for a declared plugin, a node whose component id it declares.
+ * - It declares a site feature. The caller only asks about plugins the site
+ *   has switched on, and a feature runs on every page of such a site.
+ *
+ * A plugin that declares nothing is present only through its stamped
+ * elements — the default in the module note.
+ */
+export declare function isPluginUsedOnPage(subject: PresenceSubject, page: PagePresence): boolean;
+/**
+ * Where a plugin's console code loads, resolved with the default applied: a
+ * plugin that declares nothing loads with the shell, as it always did.
+ */
+export interface ConsoleLoadPoints {
+    shell: boolean;
+    slots: readonly string[];
+    routes: readonly string[];
+    orgRoutes: readonly string[];
+}
+export declare function consoleLoadPoints(contributes: PluginContributions | undefined): ConsoleLoadPoints;
+/**
+ * Whether a declared route serves `href`: the route itself, or a path beneath
+ * it on a segment boundary, the way the shell's page resolver matches a nav
+ * item that owns its subtree. `/products` serves `/products/orders` and never
+ * `/products-archive`.
+ */
+export declare function routeServes(route: string, href: string): boolean;
+/**
+ * A place in the console that loads plugins, as the surface drawing it names
+ * itself (AGL-3142).
+ *
+ * - `shell`: the workspace chrome every screen has. It draws whatever a
+ *   plugin adds to every screen — a nav tab, an organization tab, a staff
+ *   tab, a provider — so a plugin that declares any of those loads here, and
+ *   so does one that declares nothing at all.
+ * - `slots`: the zones a screen renders. The zones it names, not the plugins
+ *   it expects in them: a screen must never hold a plugin id.
+ * - `route`: the path the reader has open, plugin-relative (`/products`,
+ *   `/products/orders`), on the level its route tree serves — `site` beneath
+ *   `/hosts/[host]`, `org` beneath the organization.
+ */
+export type ConsoleLoadWhere = {
+    at: 'shell';
+} | {
+    at: 'slots';
+    slots: readonly string[];
+} | {
+    at: 'route';
+    href: string;
+    level: 'site' | 'org';
+};
+/**
+ * Whether a console surface uses a plugin, so it must load it.
+ *
+ * The console twin of {@link isPluginUsedOnPage}, and the same rule: a
+ * declaration says where a plugin's code belongs, and the surface that draws
+ * that place is the one that fetches it. A screen asks about the zones it
+ * renders and the path it serves; it never asks about a plugin by name.
+ *
+ * A plugin that declares nothing loads with the shell — the default in the
+ * module note, and the reason the shell branch reads
+ * {@link consoleLoadPoints} rather than the raw block. Its nav tab or its
+ * provider is only discoverable by running `register()`, so narrowing it
+ * anywhere else would take a tab away with no way to notice.
+ */
+export declare function isPluginUsedInConsole(contributes: PluginContributions | undefined, where: ConsoleLoadWhere): boolean;
+export {};

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

@@ -0,0 +1,283 @@
+/**
+ * @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.
+ */ /**
+ * What a plugin contributes, and where (AGL-3116).
+ *
+ * A plugin loads only where something uses it. Installing one loads nothing:
+ * a published page fetches a plugin's code when the page places one of its
+ * elements or the site runs one of its features, and a console screen
+ * fetches it when the screen renders one of its slots or routes, or when the
+ * plugin draws something the shell renders on every screen.
+ *
+ * The loaders cannot learn that by running a plugin, because running it is
+ * the cost being avoided. So each plugin DECLARES its contributions:
+ * first-party plugins in `plugins.config.json`, marketplace plugins in the
+ * manifest they publish (`contributes`). The declaration is the whole of what
+ * a loader reads, and it is data: this module is dependency-free so the
+ * server, both apps, the verifier and the build tools share one reading.
+ *
+ * A declared surface only narrows where to look. Presence is the rule: a
+ * plugin that declares a component loads on the pages that place it, not on
+ * every page of the site that installed it.
+ *
+ * ## A plugin that declares nothing
+ *
+ * Every marketplace version published before this contract has no
+ * `contributes`. Such a plugin keeps working under one default:
+ *
+ * - **On a published page it loads only where its element is placed**: a
+ *   node whose `pluginId` names the plugin (its manifest id or its listing
+ *   id). That is the one presence signal a page carries without running the
+ *   bundle, and it is the only way a page can show an element the plugin
+ *   registers. A site runtime of an undeclared plugin does not load, and the
+ *   publish pipeline refuses a bundle that registers one without declaring
+ *   it, so the only plugins this default governs are the ones already
+ *   published.
+ * - **In the console it loads with the workspace shell**, as it always did,
+ *   because a nav tab or a provider is only discoverable by running
+ *   `register()`. Nothing on a published page depends on this.
+ */ /** What a plugin adds to a published site. */ /** Bound on each declared list, so a manifest cannot hand a loader a novel. */ export const PLUGIN_MAX_CONTRIBUTIONS = 128;
+/**
+ * A component, feature or slot id: an identifier with the separators ids in
+ * the platform use (`muiTypography`, `marketplacePlugin`, `ai.assist`).
+ */ const CONTRIBUTION_ID = /^[A-Za-z_][A-Za-z0-9_.:-]{0,79}$/;
+/**
+ * A console route: one or more path segments, as a nav item's `href` names
+ * them. Never a URL, never `..`.
+ */ const CONTRIBUTION_ROUTE = /^(\/[A-Za-z0-9_-]+){1,8}$/;
+/**
+ * Validates a declared `contributes` block.
+ *
+ * Malformed input is REFUSED rather than trimmed: a loader reads this to
+ * decide where a plugin runs, so a declaration that silently lost an entry
+ * would stop the plugin loading where it is used, and nobody would see why.
+ * Duplicates are collapsed and empty lists dropped, because neither changes
+ * what the declaration means.
+ *
+ * `{}` is valid and means "contributes nothing anywhere", which is a
+ * different statement from an absent block (see the module note).
+ */ export function sanitizePluginContributions(input) {
+    if (!isPlainObject(input)) {
+        return {
+            ok: false,
+            error: 'contributes must be an object'
+        };
+    }
+    const out = {};
+    for (const key of Object.keys(input)){
+        if (key !== 'site' && key !== 'console') {
+            return {
+                ok: false,
+                error: `contributes.${key} is not a known surface`
+            };
+        }
+    }
+    if (input['site'] !== undefined) {
+        const site = input['site'];
+        if (!isPlainObject(site)) {
+            return {
+                ok: false,
+                error: 'contributes.site must be an object'
+            };
+        }
+        const next = {};
+        for (const key of Object.keys(site)){
+            if (key !== 'components' && key !== 'features') {
+                return {
+                    ok: false,
+                    error: `contributes.site.${key} is not a known contribution`
+                };
+            }
+            const list = idList(site[key], `contributes.site.${key}`, CONTRIBUTION_ID);
+            if (list.ok === false) return {
+                ok: false,
+                error: list.error
+            };
+            if (list.values.length) next[key] = list.values;
+        }
+        if (Object.keys(next).length) out.site = next;
+    }
+    if (input['console'] !== undefined) {
+        const consoleInput = input['console'];
+        if (!isPlainObject(consoleInput)) {
+            return {
+                ok: false,
+                error: 'contributes.console must be an object'
+            };
+        }
+        const next = {};
+        for (const key of Object.keys(consoleInput)){
+            if (key === 'shell') {
+                if (typeof consoleInput['shell'] !== 'boolean') {
+                    return {
+                        ok: false,
+                        error: 'contributes.console.shell must be true or false'
+                    };
+                }
+                if (consoleInput['shell']) next.shell = true;
+                continue;
+            }
+            if (key !== 'slots' && key !== 'routes' && key !== 'orgRoutes') {
+                return {
+                    ok: false,
+                    error: `contributes.console.${key} is not a known contribution`
+                };
+            }
+            const list = idList(consoleInput[key], `contributes.console.${key}`, key === 'slots' ? CONTRIBUTION_ID : CONTRIBUTION_ROUTE);
+            if (list.ok === false) return {
+                ok: false,
+                error: list.error
+            };
+            if (list.values.length) next[key] = list.values;
+        }
+        if (Object.keys(next).length) out.console = next;
+    }
+    return {
+        ok: true,
+        contributions: out
+    };
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function idList(value, where, pattern) {
+    if (!Array.isArray(value)) return {
+        ok: false,
+        error: `${where} must be a list`
+    };
+    if (value.length > PLUGIN_MAX_CONTRIBUTIONS) {
+        return {
+            ok: false,
+            error: `${where} lists more than ${PLUGIN_MAX_CONTRIBUTIONS}`
+        };
+    }
+    const values = [];
+    for (const entry of value){
+        if (typeof entry !== 'string' || !pattern.test(entry)) {
+            return {
+                ok: false,
+                error: `${where} has an invalid entry "${String(entry)}"`
+            };
+        }
+        if (!values.includes(entry)) values.push(entry);
+    }
+    return {
+        ok: true,
+        values
+    };
+}
+/**
+ * A declared `contributes` block as a loader may trust it: the sanitized
+ * block, or `undefined` for one that is absent or does not validate.
+ *
+ * Loaders read this from stored documents (a pinned version's manifest), and
+ * a malformed stored block is treated as UNDECLARED — the default applies —
+ * never as "contributes nothing", which would stop a plugin that is in use.
+ */ export function readPluginContributions(input) {
+    if (input === undefined || input === null) return undefined;
+    const verdict = sanitizePluginContributions(input);
+    return verdict.ok ? verdict.contributions : undefined;
+}
+/**
+ * The component ids and plugin ids a node tree places.
+ *
+ * Read from the FULL composed document — layouts, grafted reusable
+ * components and withheld lazy panels included — because an element inside
+ * a panel the visitor opens later is still this page's element.
+ */ export function pagePresence(nodes) {
+    const componentIds = new Set();
+    const pluginIds = new Set();
+    for (const node of Object.values(nodes != null ? nodes : {})){
+        if (typeof (node == null ? void 0 : node.componentId) === 'string' && node.componentId) {
+            componentIds.add(node.componentId);
+        }
+        if (typeof (node == null ? void 0 : node.pluginId) === 'string' && node.pluginId) {
+            pluginIds.add(node.pluginId);
+        }
+    }
+    return {
+        componentIds,
+        pluginIds
+    };
+}
+/**
+ * Whether a published page uses a plugin, so the page must load it.
+ *
+ * - An element of it is placed: a node stamped with the plugin's id, or,
+ *   for a declared plugin, a node whose component id it declares.
+ * - It declares a site feature. The caller only asks about plugins the site
+ *   has switched on, and a feature runs on every page of such a site.
+ *
+ * A plugin that declares nothing is present only through its stamped
+ * elements — the default in the module note.
+ */ export function isPluginUsedOnPage(subject, page) {
+    var _site_components;
+    var _subject_contributes, _site_features;
+    if (subject.pluginId && page.pluginIds.has(subject.pluginId)) return true;
+    if (subject.listingId && page.pluginIds.has(subject.listingId)) return true;
+    const site = (_subject_contributes = subject.contributes) == null ? void 0 : _subject_contributes.site;
+    if (!site) return false;
+    if ((_site_features = site.features) == null ? void 0 : _site_features.length) return true;
+    return ((_site_components = site.components) != null ? _site_components : []).some((id)=>page.componentIds.has(id));
+}
+export function consoleLoadPoints(contributes) {
+    var _contributes_console, _declared_slots, _declared_routes, _declared_orgRoutes;
+    if (!contributes) return {
+        shell: true,
+        slots: [],
+        routes: [],
+        orgRoutes: []
+    };
+    const declared = (_contributes_console = contributes.console) != null ? _contributes_console : {};
+    return {
+        shell: Boolean(declared.shell),
+        slots: (_declared_slots = declared.slots) != null ? _declared_slots : [],
+        routes: (_declared_routes = declared.routes) != null ? _declared_routes : [],
+        orgRoutes: (_declared_orgRoutes = declared.orgRoutes) != null ? _declared_orgRoutes : []
+    };
+}
+/**
+ * Whether a declared route serves `href`: the route itself, or a path beneath
+ * it on a segment boundary, the way the shell's page resolver matches a nav
+ * item that owns its subtree. `/products` serves `/products/orders` and never
+ * `/products-archive`.
+ */ export function routeServes(route, href) {
+    return href === route || href.startsWith(`${route}/`);
+}
+/**
+ * Whether a console surface uses a plugin, so it must load it.
+ *
+ * The console twin of {@link isPluginUsedOnPage}, and the same rule: a
+ * declaration says where a plugin's code belongs, and the surface that draws
+ * that place is the one that fetches it. A screen asks about the zones it
+ * renders and the path it serves; it never asks about a plugin by name.
+ *
+ * A plugin that declares nothing loads with the shell — the default in the
+ * module note, and the reason the shell branch reads
+ * {@link consoleLoadPoints} rather than the raw block. Its nav tab or its
+ * provider is only discoverable by running `register()`, so narrowing it
+ * anywhere else would take a tab away with no way to notice.
+ */ export function isPluginUsedInConsole(contributes, where) {
+    const points = consoleLoadPoints(contributes);
+    if (where.at === 'shell') return points.shell;
+    if (where.at === 'slots') {
+        return points.slots.some((slot)=>where.slots.includes(slot));
+    }
+    const routes = where.level === 'org' ? points.orgRoutes : points.routes;
+    return routes.some((route)=>routeServes(route, where.href));
+}
+
+//# sourceMappingURL=plugin-contributions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-contributions.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 * What a plugin contributes, and where (AGL-3116).\n *\n * A plugin loads only where something uses it. Installing one loads nothing:\n * a published page fetches a plugin's code when the page places one of its\n * elements or the site runs one of its features, and a console screen\n * fetches it when the screen renders one of its slots or routes, or when the\n * plugin draws something the shell renders on every screen.\n *\n * The loaders cannot learn that by running a plugin, because running it is\n * the cost being avoided. So each plugin DECLARES its contributions:\n * first-party plugins in `plugins.config.json`, marketplace plugins in the\n * manifest they publish (`contributes`). The declaration is the whole of what\n * a loader reads, and it is data: this module is dependency-free so the\n * server, both apps, the verifier and the build tools share one reading.\n *\n * A declared surface only narrows where to look. Presence is the rule: a\n * plugin that declares a component loads on the pages that place it, not on\n * every page of the site that installed it.\n *\n * ## A plugin that declares nothing\n *\n * Every marketplace version published before this contract has no\n * `contributes`. Such a plugin keeps working under one default:\n *\n * - **On a published page it loads only where its element is placed**: a\n *   node whose `pluginId` names the plugin (its manifest id or its listing\n *   id). That is the one presence signal a page carries without running the\n *   bundle, and it is the only way a page can show an element the plugin\n *   registers. A site runtime of an undeclared plugin does not load, and the\n *   publish pipeline refuses a bundle that registers one without declaring\n *   it, so the only plugins this default governs are the ones already\n *   published.\n * - **In the console it loads with the workspace shell**, as it always did,\n *   because a nav tab or a provider is only discoverable by running\n *   `register()`. Nothing on a published page depends on this.\n */\n\n/** What a plugin adds to a published site. */\nexport interface PluginSiteContributions {\n  /**\n   * Canvas component ids the plugin registers: the elements a page places. A\n   * published page loads the plugin only when its node tree places one.\n   */\n  components?: string[]\n  /**\n   * Site features: runtimes the plugin mounts on every page of a site that\n   * switched it on (an announcement bar, an experiment runner), named by the\n   * `runtimeId` it registers. A plugin with a feature loads on every page of\n   * such a site, which is what a feature is.\n   */\n  features?: string[]\n}\n\n/** What a plugin adds to the console. */\nexport interface PluginConsoleContributions {\n  /**\n   * The widget slots its widgets fill: the `CONSOLE_WIDGET_SLOTS` zones, the\n   * panels the shell draws as slots (the assistant dock `assistPanel`, the\n   * besigner's `besignerInspector`), and zones another plugin hosts. A screen\n   * that renders one of them loads the plugin.\n   */\n  slots?: string[]\n  /** Site-level console routes it serves (`/forms`), beneath `/hosts/[host]`. */\n  routes?: string[]\n  /** Organization-level console routes it serves (`/outreach`). */\n  orgRoutes?: string[]\n  /**\n   * The shell draws something of it on every screen of a workspace: a nav\n   * tab, an organization tab, a staff tab or a provider. Such a plugin loads\n   * with the shell, because every screen renders it.\n   */\n  shell?: boolean\n}\n\nexport interface PluginContributions {\n  site?: PluginSiteContributions\n  console?: PluginConsoleContributions\n}\n\n/** Bound on each declared list, so a manifest cannot hand a loader a novel. */\nexport const PLUGIN_MAX_CONTRIBUTIONS = 128\n\n/**\n * A component, feature or slot id: an identifier with the separators ids in\n * the platform use (`muiTypography`, `marketplacePlugin`, `ai.assist`).\n */\nconst CONTRIBUTION_ID = /^[A-Za-z_][A-Za-z0-9_.:-]{0,79}$/\n\n/**\n * A console route: one or more path segments, as a nav item's `href` names\n * them. Never a URL, never `..`.\n */\nconst CONTRIBUTION_ROUTE = /^(\\/[A-Za-z0-9_-]+){1,8}$/\n\ntype Sanitized =\n  | { ok: true; contributions: PluginContributions }\n  | { ok: false; error: string }\n\n/**\n * Validates a declared `contributes` block.\n *\n * Malformed input is REFUSED rather than trimmed: a loader reads this to\n * decide where a plugin runs, so a declaration that silently lost an entry\n * would stop the plugin loading where it is used, and nobody would see why.\n * Duplicates are collapsed and empty lists dropped, because neither changes\n * what the declaration means.\n *\n * `{}` is valid and means \"contributes nothing anywhere\", which is a\n * different statement from an absent block (see the module note).\n */\nexport function sanitizePluginContributions(input: unknown): Sanitized {\n  if (!isPlainObject(input)) {\n    return { ok: false, error: 'contributes must be an object' }\n  }\n  const out: PluginContributions = {}\n  for (const key of Object.keys(input)) {\n    if (key !== 'site' && key !== 'console') {\n      return { ok: false, error: `contributes.${key} is not a known surface` }\n    }\n  }\n\n  if (input['site'] !== undefined) {\n    const site = input['site']\n    if (!isPlainObject(site)) {\n      return { ok: false, error: 'contributes.site must be an object' }\n    }\n    const next: PluginSiteContributions = {}\n    for (const key of Object.keys(site)) {\n      if (key !== 'components' && key !== 'features') {\n        return { ok: false, error: `contributes.site.${key} is not a known contribution` }\n      }\n      const list = idList(site[key], `contributes.site.${key}`, CONTRIBUTION_ID)\n      if (list.ok === false) return { ok: false, error: list.error }\n      if (list.values.length) next[key] = list.values\n    }\n    if (Object.keys(next).length) out.site = next\n  }\n\n  if (input['console'] !== undefined) {\n    const consoleInput = input['console']\n    if (!isPlainObject(consoleInput)) {\n      return { ok: false, error: 'contributes.console must be an object' }\n    }\n    const next: PluginConsoleContributions = {}\n    for (const key of Object.keys(consoleInput)) {\n      if (key === 'shell') {\n        if (typeof consoleInput['shell'] !== 'boolean') {\n          return { ok: false, error: 'contributes.console.shell must be true or false' }\n        }\n        if (consoleInput['shell']) next.shell = true\n        continue\n      }\n      if (key !== 'slots' && key !== 'routes' && key !== 'orgRoutes') {\n        return {\n          ok: false,\n          error: `contributes.console.${key} is not a known contribution`,\n        }\n      }\n      const list = idList(\n        consoleInput[key],\n        `contributes.console.${key}`,\n        key === 'slots' ? CONTRIBUTION_ID : CONTRIBUTION_ROUTE,\n      )\n      if (list.ok === false) return { ok: false, error: list.error }\n      if (list.values.length) next[key] = list.values\n    }\n    if (Object.keys(next).length) out.console = next\n  }\n\n  return { ok: true, contributions: out }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n}\n\nfunction idList(\n  value: unknown,\n  where: string,\n  pattern: RegExp,\n): { ok: true; values: string[] } | { ok: false; error: string } {\n  if (!Array.isArray(value)) return { ok: false, error: `${where} must be a list` }\n  if (value.length > PLUGIN_MAX_CONTRIBUTIONS) {\n    return { ok: false, error: `${where} lists more than ${PLUGIN_MAX_CONTRIBUTIONS}` }\n  }\n  const values: string[] = []\n  for (const entry of value) {\n    if (typeof entry !== 'string' || !pattern.test(entry)) {\n      return { ok: false, error: `${where} has an invalid entry \"${String(entry)}\"` }\n    }\n    if (!values.includes(entry)) values.push(entry)\n  }\n  return { ok: true, values }\n}\n\n/**\n * A declared `contributes` block as a loader may trust it: the sanitized\n * block, or `undefined` for one that is absent or does not validate.\n *\n * Loaders read this from stored documents (a pinned version's manifest), and\n * a malformed stored block is treated as UNDECLARED — the default applies —\n * never as \"contributes nothing\", which would stop a plugin that is in use.\n */\nexport function readPluginContributions(\n  input: unknown,\n): PluginContributions | undefined {\n  if (input === undefined || input === null) return undefined\n  const verdict = sanitizePluginContributions(input)\n  return verdict.ok ? verdict.contributions : undefined\n}\n\n/**\n * What the surface a plugin is being registered into actually uses\n * (AGL-3141).\n *\n * The loaders carry this from the surface that computed it to each plugin's\n * register function, unchanged. A plugin that can register a part of itself\n * reads it; one that cannot ignores it, and the platform's behavior is the\n * same either way.\n *\n * An absent field means \"everything of that kind\". A surface that cannot say\n * what it uses must be handed all of it, because an element the surface\n * places and the set omits has no registered component and renders NOTHING,\n * silently (the blank-canvas invariant, AGL-52). Narrowing is an optimization\n * and must fail toward the whole.\n */\nexport interface PluginUse {\n  /**\n   * Canvas component ids the surface places, read from the FULL composed\n   * document the way `pagePresence` reads it — withheld lazy-panel subtrees\n   * included, because an element inside a panel the visitor opens later is\n   * still this page's element.\n   */\n  componentIds?: readonly string[]\n}\n\n/** A node as presence reads it: the two ids a placed element carries. */\nexport interface PresenceNode {\n  componentId?: string\n  pluginId?: string\n}\n\n/** What a published page places: its component ids and the plugin ids stamped on its nodes. */\nexport interface PagePresence {\n  componentIds: ReadonlySet<string>\n  pluginIds: ReadonlySet<string>\n}\n\n/**\n * The component ids and plugin ids a node tree places.\n *\n * Read from the FULL composed document — layouts, grafted reusable\n * components and withheld lazy panels included — because an element inside\n * a panel the visitor opens later is still this page's element.\n */\nexport function pagePresence(\n  nodes: Record<string, PresenceNode | null | undefined> | null | undefined,\n): PagePresence {\n  const componentIds = new Set<string>()\n  const pluginIds = new Set<string>()\n  for (const node of Object.values(nodes ?? {})) {\n    if (typeof node?.componentId === 'string' && node.componentId) {\n      componentIds.add(node.componentId)\n    }\n    if (typeof node?.pluginId === 'string' && node.pluginId) {\n      pluginIds.add(node.pluginId)\n    }\n  }\n  return { componentIds, pluginIds }\n}\n\n/** A plugin as the presence rules see it. */\nexport interface PresenceSubject {\n  /** The plugin's own id (a manifest `id`, or a first-party catalog id). */\n  pluginId?: string\n  /** A marketplace plugin's listing id, which its elements may carry instead. */\n  listingId?: string\n  /** Its declaration; `undefined` when it declares nothing. */\n  contributes?: PluginContributions\n}\n\n/**\n * Whether a published page uses a plugin, so the page must load it.\n *\n * - An element of it is placed: a node stamped with the plugin's id, or,\n *   for a declared plugin, a node whose component id it declares.\n * - It declares a site feature. The caller only asks about plugins the site\n *   has switched on, and a feature runs on every page of such a site.\n *\n * A plugin that declares nothing is present only through its stamped\n * elements — the default in the module note.\n */\nexport function isPluginUsedOnPage(\n  subject: PresenceSubject,\n  page: PagePresence,\n): boolean {\n  if (subject.pluginId && page.pluginIds.has(subject.pluginId)) return true\n  if (subject.listingId && page.pluginIds.has(subject.listingId)) return true\n  const site = subject.contributes?.site\n  if (!site) return false\n  if (site.features?.length) return true\n  return (site.components ?? []).some((id) => page.componentIds.has(id))\n}\n\n/**\n * Where a plugin's console code loads, resolved with the default applied: a\n * plugin that declares nothing loads with the shell, as it always did.\n */\nexport interface ConsoleLoadPoints {\n  shell: boolean\n  slots: readonly string[]\n  routes: readonly string[]\n  orgRoutes: readonly string[]\n}\n\nexport function consoleLoadPoints(\n  contributes: PluginContributions | undefined,\n): ConsoleLoadPoints {\n  if (!contributes) return { shell: true, slots: [], routes: [], orgRoutes: [] }\n  const declared = contributes.console ?? {}\n  return {\n    shell: Boolean(declared.shell),\n    slots: declared.slots ?? [],\n    routes: declared.routes ?? [],\n    orgRoutes: declared.orgRoutes ?? [],\n  }\n}\n\n/**\n * Whether a declared route serves `href`: the route itself, or a path beneath\n * it on a segment boundary, the way the shell's page resolver matches a nav\n * item that owns its subtree. `/products` serves `/products/orders` and never\n * `/products-archive`.\n */\nexport function routeServes(route: string, href: string): boolean {\n  return href === route || href.startsWith(`${route}/`)\n}\n\n/**\n * A place in the console that loads plugins, as the surface drawing it names\n * itself (AGL-3142).\n *\n * - `shell`: the workspace chrome every screen has. It draws whatever a\n *   plugin adds to every screen — a nav tab, an organization tab, a staff\n *   tab, a provider — so a plugin that declares any of those loads here, and\n *   so does one that declares nothing at all.\n * - `slots`: the zones a screen renders. The zones it names, not the plugins\n *   it expects in them: a screen must never hold a plugin id.\n * - `route`: the path the reader has open, plugin-relative (`/products`,\n *   `/products/orders`), on the level its route tree serves — `site` beneath\n *   `/hosts/[host]`, `org` beneath the organization.\n */\nexport type ConsoleLoadWhere =\n  | { at: 'shell' }\n  | { at: 'slots'; slots: readonly string[] }\n  | { at: 'route'; href: string; level: 'site' | 'org' }\n\n/**\n * Whether a console surface uses a plugin, so it must load it.\n *\n * The console twin of {@link isPluginUsedOnPage}, and the same rule: a\n * declaration says where a plugin's code belongs, and the surface that draws\n * that place is the one that fetches it. A screen asks about the zones it\n * renders and the path it serves; it never asks about a plugin by name.\n *\n * A plugin that declares nothing loads with the shell — the default in the\n * module note, and the reason the shell branch reads\n * {@link consoleLoadPoints} rather than the raw block. Its nav tab or its\n * provider is only discoverable by running `register()`, so narrowing it\n * anywhere else would take a tab away with no way to notice.\n */\nexport function isPluginUsedInConsole(\n  contributes: PluginContributions | undefined,\n  where: ConsoleLoadWhere,\n): boolean {\n  const points = consoleLoadPoints(contributes)\n  if (where.at === 'shell') return points.shell\n  if (where.at === 'slots') {\n    return points.slots.some((slot) => where.slots.includes(slot))\n  }\n  const routes = where.level === 'org' ? points.orgRoutes : points.routes\n  return routes.some((route) => routeServes(route, where.href))\n}\n"],"names":["PLUGIN_MAX_CONTRIBUTIONS","CONTRIBUTION_ID","CONTRIBUTION_ROUTE","sanitizePluginContributions","input","isPlainObject","ok","error","out","key","Object","keys","undefined","site","next","list","idList","values","length","consoleInput","shell","console","contributions","value","Boolean","Array","isArray","where","pattern","entry","test","String","includes","push","readPluginContributions","verdict","pagePresence","nodes","componentIds","Set","pluginIds","node","componentId","add","pluginId","isPluginUsedOnPage","subject","page","has","listingId","contributes","features","components","some","id","consoleLoadPoints","declared","slots","routes","orgRoutes","routeServes","route","href","startsWith","isPluginUsedInConsole","points","at","slot","level"],"mappings":"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"}