@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,88 @@
+/**
+ * @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 { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { pluginArtifactPath } from "../app-utils/plugin-manifest.js";
+import { isCompatibleHostAbi, verifyRealmBundle } from "./realm-plugins.js";
+let loadedPromise;
+export function remoteServerBundlesEnabled() {
+    return process.env.PLUGIN_REMOTE_SERVER === 'enabled';
+}
+export async function loadRemoteServerBundles(source) {
+    if (!remoteServerBundlesEnabled()) return [];
+    if (!loadedPromise) {
+        loadedPromise = (async ()=>{
+            var _process_env_PLUGIN_REMOTE_SERVER_BUNDLES;
+            const loaded = [];
+            const publicKey = process.env.PLUGIN_TRUST_PUBLIC_KEY;
+            if (!publicKey) {
+                console.error('PLUGIN_REMOTE_SERVER is enabled but PLUGIN_TRUST_PUBLIC_KEY is ' + 'not set — refusing to load any remote server bundle.');
+                return loaded;
+            }
+            const allowlist = ((_process_env_PLUGIN_REMOTE_SERVER_BUNDLES = process.env.PLUGIN_REMOTE_SERVER_BUNDLES) != null ? _process_env_PLUGIN_REMOTE_SERVER_BUNDLES : '').split(',').map((entry)=>entry.trim()).filter(Boolean);
+            if (!allowlist.length) return loaded;
+            const cacheDir = mkdtempSync(join(tmpdir(), 'aglyn-realm-'));
+            for (const entry of allowlist){
+                try {
+                    var _mod_registerApi;
+                    var _mod_default;
+                    const [listingId, version] = entry.split('@');
+                    if (!listingId || !version) throw new Error('malformed allowlist entry');
+                    const pinned = await source.resolveVersion(listingId, version);
+                    if (!pinned) throw new Error('unknown listing version');
+                    if (pinned.trust !== 'realm') throw new Error('not realm-trusted');
+                    if (!isCompatibleHostAbi(pinned.hostAbi)) {
+                        throw new Error(`built for host ABI ${pinned.hostAbi}`);
+                    }
+                    const url = `${source.artifactsBase.replace(/\/+$/, '')}/${pluginArtifactPath(listingId, version, pinned.sha256)}`;
+                    const response = await fetch(url);
+                    if (!response.ok) throw new Error(`fetch ${response.status}`);
+                    const bytes = await response.arrayBuffer();
+                    const verdict = await verifyRealmBundle(bytes, {
+                        listingId,
+                        version,
+                        sha256: pinned.sha256,
+                        trust: 'realm',
+                        signature: pinned.signature
+                    }, publicKey);
+                    if (verdict.ok === false) throw new Error(verdict.reason);
+                    const file = join(cacheDir, `${listingId}-${version}.mjs`);
+                    writeFileSync(file, Buffer.from(bytes));
+                    const mod = await import(/* webpackIgnore: true */ pathToFileURL(file).href);
+                    const registerApi = (_mod_registerApi = mod.registerApi) != null ? _mod_registerApi : (_mod_default = mod.default) == null ? void 0 : _mod_default.registerApi;
+                    if (typeof registerApi !== 'function') {
+                        throw new Error('bundle exports no registerApi()');
+                    }
+                    registerApi();
+                    loaded.push({
+                        listingId,
+                        version,
+                        sha256: pinned.sha256
+                    });
+                    console.info(`remote server bundle loaded: ${entry}`);
+                } catch (error) {
+                    console.error(`remote server bundle ${entry} skipped:`, error);
+                }
+            }
+            return loaded;
+        })();
+    }
+    return loadedPromise;
+}
+
+//# sourceMappingURL=realm-server.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/realm-server.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 { mkdtempSync, writeFileSync } from 'node:fs'\nimport { tmpdir } from 'node:os'\nimport { join } from 'node:path'\nimport { pathToFileURL } from 'node:url'\nimport { pluginArtifactPath } from '../app-utils/plugin-manifest'\nimport {\n  isCompatibleHostAbi,\n  type RealmPluginInstall,\n  verifyRealmBundle,\n} from './realm-plugins'\n\n/**\n * Remote SERVER handler bundles (AGL-420) — the highest-risk switch in the\n * platform, default OFF everywhere. When explicitly enabled, the API\n * dispatchers load staff-signed bundles that register plugin API routes\n * in-process. Guardrails, all mandatory (unlike the client tier, none are\n * optional here):\n *\n * - `PLUGIN_REMOTE_SERVER=enabled` — the master switch.\n * - `PLUGIN_REMOTE_SERVER_BUNDLES` — an explicit per-deploy allowlist of\n *   `listingId@version` entries; nothing loads implicitly from installs.\n * - `PLUGIN_TRUST_PUBLIC_KEY` — REQUIRED; every bundle must carry a valid\n *   platform Ed25519 signature over its sha256. No key, no loading.\n * - sha256 content-addressing against the version doc, same as the client.\n *\n * Verified bytes are written to a private temp file and imported by\n * `file://` URL (node can't import blob URLs); the module's exported\n * `registerApi()` runs with the same registries first-party `/server`\n * entries use. Failures log and skip — a broken remote bundle must not\n * take the API surface down (its own paths simply stay unregistered).\n */\n\nexport interface RemoteServerBundleSource {\n  /** Resolves a listing version doc to its pinned hash + signature. */\n  resolveVersion(\n    listingId: string,\n    version: string,\n  ): Promise<{\n    sha256: string\n    signature?: string\n    trust?: string\n    hostAbi?: number\n  } | null>\n  /** Base URL of the content-addressed artifacts origin. */\n  artifactsBase: string\n}\n\nlet loadedPromise: Promise<LoadedServerBundle[]> | undefined\n\nexport function remoteServerBundlesEnabled(): boolean {\n  return process.env.PLUGIN_REMOTE_SERVER === 'enabled'\n}\n\nexport interface LoadedServerBundle {\n  listingId: string\n  version: string\n  sha256: string\n}\n\nexport async function loadRemoteServerBundles(\n  source: RemoteServerBundleSource,\n): Promise<LoadedServerBundle[]> {\n  if (!remoteServerBundlesEnabled()) return []\n  if (!loadedPromise) {\n    loadedPromise = (async () => {\n      const loaded: LoadedServerBundle[] = []\n      const publicKey = process.env.PLUGIN_TRUST_PUBLIC_KEY\n      if (!publicKey) {\n        console.error(\n          'PLUGIN_REMOTE_SERVER is enabled but PLUGIN_TRUST_PUBLIC_KEY is ' +\n            'not set — refusing to load any remote server bundle.',\n        )\n        return loaded\n      }\n      const allowlist = (process.env.PLUGIN_REMOTE_SERVER_BUNDLES ?? '')\n        .split(',')\n        .map((entry) => entry.trim())\n        .filter(Boolean)\n      if (!allowlist.length) return loaded\n      const cacheDir = mkdtempSync(join(tmpdir(), 'aglyn-realm-'))\n\n      for (const entry of allowlist) {\n        try {\n          const [listingId, version] = entry.split('@')\n          if (!listingId || !version) throw new Error('malformed allowlist entry')\n          const pinned = await source.resolveVersion(listingId, version)\n          if (!pinned) throw new Error('unknown listing version')\n          if (pinned.trust !== 'realm') throw new Error('not realm-trusted')\n          if (!isCompatibleHostAbi(pinned.hostAbi)) {\n            throw new Error(`built for host ABI ${pinned.hostAbi}`)\n          }\n          const url = `${source.artifactsBase.replace(/\\/+$/, '')}/${pluginArtifactPath(\n            listingId,\n            version,\n            pinned.sha256,\n          )}`\n          const response = await fetch(url)\n          if (!response.ok) throw new Error(`fetch ${response.status}`)\n          const bytes = await response.arrayBuffer()\n          const verdict = await verifyRealmBundle(\n            bytes,\n            {\n              listingId,\n              version,\n              sha256: pinned.sha256,\n              trust: 'realm',\n              signature: pinned.signature,\n            } satisfies RealmPluginInstall,\n            publicKey,\n          )\n          if (verdict.ok === false) throw new Error(verdict.reason)\n          const file = join(cacheDir, `${listingId}-${version}.mjs`)\n          writeFileSync(file, Buffer.from(bytes))\n          const mod = (await import(\n            /* webpackIgnore: true */ pathToFileURL(file).href\n          )) as {\n            registerApi?: () => void\n            default?: { registerApi?: () => void }\n          }\n          const registerApi = mod.registerApi ?? mod.default?.registerApi\n          if (typeof registerApi !== 'function') {\n            throw new Error('bundle exports no registerApi()')\n          }\n          registerApi()\n          loaded.push({ listingId, version, sha256: pinned.sha256 })\n          console.info(`remote server bundle loaded: ${entry}`)\n        } catch (error) {\n          console.error(`remote server bundle ${entry} skipped:`, error)\n        }\n      }\n      return loaded\n    })()\n  }\n  return loadedPromise\n}\n"],"names":["mkdtempSync","writeFileSync","tmpdir","join","pathToFileURL","pluginArtifactPath","isCompatibleHostAbi","verifyRealmBundle","loadedPromise","remoteServerBundlesEnabled","process","env","PLUGIN_REMOTE_SERVER","loadRemoteServerBundles","source","loaded","publicKey","PLUGIN_TRUST_PUBLIC_KEY","console","error","allowlist","PLUGIN_REMOTE_SERVER_BUNDLES","split","map","entry","trim","filter","Boolean","length","cacheDir","mod","listingId","version","Error","pinned","resolveVersion","trust","hostAbi","url","artifactsBase","replace","sha256","response","fetch","ok","status","bytes","arrayBuffer","verdict","signature","reason","file","Buffer","from","href","registerApi","default","push","info"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,WAAW,EAAEC,aAAa,QAAQ,UAAS;AACpD,SAASC,MAAM,QAAQ,UAAS;AAChC,SAASC,IAAI,QAAQ,YAAW;AAChC,SAASC,aAAa,QAAQ,WAAU;AACxC,SAASC,kBAAkB,QAAQ,kCAA8B;AACjE,SACEC,mBAAmB,EAEnBC,iBAAiB,QACZ,qBAAiB;AAsCxB,IAAIC;AAEJ,OAAO,SAASC;IACd,OAAOC,QAAQC,GAAG,CAACC,oBAAoB,KAAK;AAC9C;AAQA,OAAO,eAAeC,wBACpBC,MAAgC;IAEhC,IAAI,CAACL,8BAA8B,OAAO,EAAE;IAC5C,IAAI,CAACD,eAAe;QAClBA,gBAAgB,AAAC,CAAA;gBAUIE;YATnB,MAAMK,SAA+B,EAAE;YACvC,MAAMC,YAAYN,QAAQC,GAAG,CAACM,uBAAuB;YACrD,IAAI,CAACD,WAAW;gBACdE,QAAQC,KAAK,CACX,oEACE;gBAEJ,OAAOJ;YACT;YACA,MAAMK,YAAY,EAACV,4CAAAA,QAAQC,GAAG,CAACU,4BAA4B,YAAxCX,4CAA4C,IAC5DY,KAAK,CAAC,KACNC,GAAG,CAAC,CAACC,QAAUA,MAAMC,IAAI,IACzBC,MAAM,CAACC;YACV,IAAI,CAACP,UAAUQ,MAAM,EAAE,OAAOb;YAC9B,MAAMc,WAAW7B,YAAYG,KAAKD,UAAU;YAE5C,KAAK,MAAMsB,SAASJ,UAAW;gBAC7B,IAAI;wBAqCkBU;wBAAmBA;oBApCvC,MAAM,CAACC,WAAWC,QAAQ,GAAGR,MAAMF,KAAK,CAAC;oBACzC,IAAI,CAACS,aAAa,CAACC,SAAS,MAAM,IAAIC,MAAM;oBAC5C,MAAMC,SAAS,MAAMpB,OAAOqB,cAAc,CAACJ,WAAWC;oBACtD,IAAI,CAACE,QAAQ,MAAM,IAAID,MAAM;oBAC7B,IAAIC,OAAOE,KAAK,KAAK,SAAS,MAAM,IAAIH,MAAM;oBAC9C,IAAI,CAAC3B,oBAAoB4B,OAAOG,OAAO,GAAG;wBACxC,MAAM,IAAIJ,MAAM,CAAC,mBAAmB,EAAEC,OAAOG,OAAO,EAAE;oBACxD;oBACA,MAAMC,MAAM,GAAGxB,OAAOyB,aAAa,CAACC,OAAO,CAAC,QAAQ,IAAI,CAAC,EAAEnC,mBACzD0B,WACAC,SACAE,OAAOO,MAAM,GACZ;oBACH,MAAMC,WAAW,MAAMC,MAAML;oBAC7B,IAAI,CAACI,SAASE,EAAE,EAAE,MAAM,IAAIX,MAAM,CAAC,MAAM,EAAES,SAASG,MAAM,EAAE;oBAC5D,MAAMC,QAAQ,MAAMJ,SAASK,WAAW;oBACxC,MAAMC,UAAU,MAAMzC,kBACpBuC,OACA;wBACEf;wBACAC;wBACAS,QAAQP,OAAOO,MAAM;wBACrBL,OAAO;wBACPa,WAAWf,OAAOe,SAAS;oBAC7B,GACAjC;oBAEF,IAAIgC,QAAQJ,EAAE,KAAK,OAAO,MAAM,IAAIX,MAAMe,QAAQE,MAAM;oBACxD,MAAMC,OAAOhD,KAAK0B,UAAU,GAAGE,UAAU,CAAC,EAAEC,QAAQ,IAAI,CAAC;oBACzD/B,cAAckD,MAAMC,OAAOC,IAAI,CAACP;oBAChC,MAAMhB,MAAO,MAAM,MAAM,CACvB,uBAAuB,GAAG1B,cAAc+C,MAAMG,IAAI;oBAKpD,MAAMC,eAAczB,mBAAAA,IAAIyB,WAAW,YAAfzB,oBAAmBA,eAAAA,IAAI0B,OAAO,qBAAX1B,aAAayB,WAAW;oBAC/D,IAAI,OAAOA,gBAAgB,YAAY;wBACrC,MAAM,IAAItB,MAAM;oBAClB;oBACAsB;oBACAxC,OAAO0C,IAAI,CAAC;wBAAE1B;wBAAWC;wBAASS,QAAQP,OAAOO,MAAM;oBAAC;oBACxDvB,QAAQwC,IAAI,CAAC,CAAC,6BAA6B,EAAElC,OAAO;gBACtD,EAAE,OAAOL,OAAO;oBACdD,QAAQC,KAAK,CAAC,CAAC,qBAAqB,EAAEK,MAAM,SAAS,CAAC,EAAEL;gBAC1D;YACF;YACA,OAAOJ;QACT,CAAA;IACF;IACA,OAAOP;AACT"}

package/src/lib/plugin-manager/record-zone-props.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @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 the record zones hand a widget (AGL-2917): `recordInsights` on a
+ * business record's page, `recordEmail` in a one-to-one composer, and
+ * `importMapping` in a spreadsheet import. Types only: the catalog re-exports
+ * each zone's props from here, and a type-only re-export adds nothing to a
+ * published page, so the types a zone's props are built from are imported
+ * from this module rather than from the catalog.
+ *
+ * The plugin that owns the records hosts each zone through the renderer
+ * `useConsoleWidgetSlot` hands down, as the product editor hosts
+ * `seoFields`, so every gate a console page's slot applies applies there. A
+ * widget in any of them proposes, and the host writes: the record's own task
+ * form and stage route, the composer's Send, the import's Import.
+ */
+/** The record a record zone is about (AGL-2917). */
+export interface ConsoleRecordRef {
+    /** The kind of record, in the owning plugin's words: `contact`, `company`, `deal`, `lead`. */
+    kind: string;
+    id: string;
+    /** The record's name as the page shows it, for a widget's own words. */
+    name: string;
+}
+/** A follow-up a widget proposes, which the page opens in its own task form (AGL-2917). */
+export interface ConsoleProposedTask {
+    title: string;
+    notes: string;
+    kind: 'call' | 'email' | 'meeting' | 'todo';
+    priority: 'low' | 'normal' | 'high';
+    /** Days from today the task is due; the form sets the time of day. */
+    dueInDays: number;
+}
+/** One stage a record can move to (AGL-2917). */
+export interface ConsoleRecordStage {
+    id: string;
+    name: string;
+}
+/** What the `recordInsights` zone hands each widget (AGL-2917). */
+export interface ConsoleRecordInsightsZoneProps {
+    /** The site the page is under, or `null` at the organization level. */
+    hostId: string | null;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    record: ConsoleRecordRef;
+    /**
+     * Opens the page's own task form with the proposal filled in, linked to the
+     * record; the form's Save is the write. Absent where the record takes no
+     * task.
+     */
+    proposeTask?: (task: ConsoleProposedTask, key: string) => void;
+    /** The open stages the record can move to, in order; absent for a record without stages. */
+    stages?: readonly ConsoleRecordStage[];
+    /** The stage the record is in, beside `stages`. */
+    stageId?: string;
+    /**
+     * Asks the member to confirm the move, then moves the record through the
+     * page's own stage route. Absent for a record without stages.
+     */
+    proposeStage?: (stageId: string, key: string) => void;
+}
+/** A subject and a message a widget proposes for a composer (AGL-2917). */
+export interface ConsoleRecordEmailDraft {
+    subject: string;
+    /** Plain text; a blank line starts a paragraph, and merge fields are filled at send. */
+    body: string;
+}
+/** What the `recordEmail` zone hands each widget (AGL-2917). */
+export interface ConsoleRecordEmailZoneProps {
+    /** The site the composer is under, or `null` at the organization level. */
+    hostId: string | null;
+    /** The org the composer names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** The record the message is written from: a contact, a deal (its contact) or a lead. */
+    record: ConsoleRecordRef;
+    /** What the composer holds now. */
+    subject: string;
+    body: string;
+    /**
+     * Puts the draft in the composer, asking first when a message is already
+     * written. The composer's Send is the only write.
+     */
+    proposeDraft: (draft: ConsoleRecordEmailDraft, key: string) => void;
+}
+/**
+ * What a column of a file holds, read in the browser from its cells
+ * (AGL-2917): the one thing a widget is told about a column's values.
+ */
+export type ConsoleImportColumnShape = 'empty' | 'email' | 'phone' | 'number' | 'date' | 'yes-no' | 'url' | 'text';
+/** One column of a file being imported (AGL-2917). */
+export interface ConsoleImportColumn {
+    header: string;
+    shape: ConsoleImportColumnShape;
+}
+/** What the `importMapping` zone hands each widget (AGL-2917). */
+export interface ConsoleImportMappingZoneProps {
+    /** The site the file is imported into, or `null` at the organization level. */
+    hostId: string | null;
+    /** The org the drawer names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** What the file is imported as, in the owning plugin's words: `contacts`, `companies`, `deals`, `leads`. */
+    collection: string;
+    /** The file's columns in order: each header and its shape, never a cell. */
+    columns: readonly ConsoleImportColumn[];
+    /** The matching the drawer holds now: column index to field key. */
+    mapping: Readonly<Record<number, string>>;
+    /**
+     * Replaces the drawer's matching. A field the drawer does not offer is
+     * dropped, and one field takes one column.
+     */
+    proposeMapping: (mapping: Readonly<Record<number, string>>, key: string) => void;
+}

package/src/lib/plugin-manager/record-zone-props.js

@@ -0,0 +1,31 @@
+/**
+ * @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 the record zones hand a widget (AGL-2917): `recordInsights` on a
+ * business record's page, `recordEmail` in a one-to-one composer, and
+ * `importMapping` in a spreadsheet import. Types only: the catalog re-exports
+ * each zone's props from here, and a type-only re-export adds nothing to a
+ * published page, so the types a zone's props are built from are imported
+ * from this module rather than from the catalog.
+ *
+ * The plugin that owns the records hosts each zone through the renderer
+ * `useConsoleWidgetSlot` hands down, as the product editor hosts
+ * `seoFields`, so every gate a console page's slot applies applies there. A
+ * widget in any of them proposes, and the host writes: the record's own task
+ * form and stage route, the composer's Send, the import's Import.
+ */ /** The record a record zone is about (AGL-2917). */ /** What the `importMapping` zone hands each widget (AGL-2917). */ export { };
+
+//# sourceMappingURL=record-zone-props.js.map

package/src/lib/plugin-manager/record-zone-props.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/record-zone-props.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 the record zones hand a widget (AGL-2917): `recordInsights` on a\n * business record's page, `recordEmail` in a one-to-one composer, and\n * `importMapping` in a spreadsheet import. Types only: the catalog re-exports\n * each zone's props from here, and a type-only re-export adds nothing to a\n * published page, so the types a zone's props are built from are imported\n * from this module rather than from the catalog.\n *\n * The plugin that owns the records hosts each zone through the renderer\n * `useConsoleWidgetSlot` hands down, as the product editor hosts\n * `seoFields`, so every gate a console page's slot applies applies there. A\n * widget in any of them proposes, and the host writes: the record's own task\n * form and stage route, the composer's Send, the import's Import.\n */\n\n/** The record a record zone is about (AGL-2917). */\nexport interface ConsoleRecordRef {\n  /** The kind of record, in the owning plugin's words: `contact`, `company`, `deal`, `lead`. */\n  kind: string\n  id: string\n  /** The record's name as the page shows it, for a widget's own words. */\n  name: string\n}\n\n/** A follow-up a widget proposes, which the page opens in its own task form (AGL-2917). */\nexport interface ConsoleProposedTask {\n  title: string\n  notes: string\n  kind: 'call' | 'email' | 'meeting' | 'todo'\n  priority: 'low' | 'normal' | 'high'\n  /** Days from today the task is due; the form sets the time of day. */\n  dueInDays: number\n}\n\n/** One stage a record can move to (AGL-2917). */\nexport interface ConsoleRecordStage {\n  id: string\n  name: string\n}\n\n/** What the `recordInsights` zone hands each widget (AGL-2917). */\nexport interface ConsoleRecordInsightsZoneProps {\n  /** The site the page is under, or `null` at the organization level. */\n  hostId: string | null\n  /** The org the page names; `undefined` while it resolves. */\n  orgId: string | undefined\n  record: ConsoleRecordRef\n  /**\n   * Opens the page's own task form with the proposal filled in, linked to the\n   * record; the form's Save is the write. Absent where the record takes no\n   * task.\n   */\n  proposeTask?: (task: ConsoleProposedTask, key: string) => void\n  /** The open stages the record can move to, in order; absent for a record without stages. */\n  stages?: readonly ConsoleRecordStage[]\n  /** The stage the record is in, beside `stages`. */\n  stageId?: string\n  /**\n   * Asks the member to confirm the move, then moves the record through the\n   * page's own stage route. Absent for a record without stages.\n   */\n  proposeStage?: (stageId: string, key: string) => void\n}\n\n/** A subject and a message a widget proposes for a composer (AGL-2917). */\nexport interface ConsoleRecordEmailDraft {\n  subject: string\n  /** Plain text; a blank line starts a paragraph, and merge fields are filled at send. */\n  body: string\n}\n\n/** What the `recordEmail` zone hands each widget (AGL-2917). */\nexport interface ConsoleRecordEmailZoneProps {\n  /** The site the composer is under, or `null` at the organization level. */\n  hostId: string | null\n  /** The org the composer names; `undefined` while it resolves. */\n  orgId: string | undefined\n  /** The record the message is written from: a contact, a deal (its contact) or a lead. */\n  record: ConsoleRecordRef\n  /** What the composer holds now. */\n  subject: string\n  body: string\n  /**\n   * Puts the draft in the composer, asking first when a message is already\n   * written. The composer's Send is the only write.\n   */\n  proposeDraft: (draft: ConsoleRecordEmailDraft, key: string) => void\n}\n\n/**\n * What a column of a file holds, read in the browser from its cells\n * (AGL-2917): the one thing a widget is told about a column's values.\n */\nexport type ConsoleImportColumnShape =\n  | 'empty'\n  | 'email'\n  | 'phone'\n  | 'number'\n  | 'date'\n  | 'yes-no'\n  | 'url'\n  | 'text'\n\n/** One column of a file being imported (AGL-2917). */\nexport interface ConsoleImportColumn {\n  header: string\n  shape: ConsoleImportColumnShape\n}\n\n/** What the `importMapping` zone hands each widget (AGL-2917). */\nexport interface ConsoleImportMappingZoneProps {\n  /** The site the file is imported into, or `null` at the organization level. */\n  hostId: string | null\n  /** The org the drawer names; `undefined` while it resolves. */\n  orgId: string | undefined\n  /** What the file is imported as, in the owning plugin's words: `contacts`, `companies`, `deals`, `leads`. */\n  collection: string\n  /** The file's columns in order: each header and its shape, never a cell. */\n  columns: readonly ConsoleImportColumn[]\n  /** The matching the drawer holds now: column index to field key. */\n  mapping: Readonly<Record<number, string>>\n  /**\n   * Replaces the drawer's matching. A field the drawer does not offer is\n   * dropped, and one field takes one column.\n   */\n  proposeMapping: (mapping: Readonly<Record<number, string>>, key: string) => void\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;CAaC,GAED,kDAAkD,GA8FlD,gEAAgE,GAChE,WAgBC"}

package/src/lib/plugin-manager/site-page-hooks.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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.
+ */
+/**
+ * Tenant page-composition extension points (AGL-418): plugins hook the
+ * site loader (`load-page-data`) from their `/server` entries instead of
+ * the app importing plugin domain code. Three kinds, run in this order:
+ *
+ * 1. REDIRECT RESOLVERS — may answer a request with a redirect before any
+ *    route resolution (plugins-redirects' rule engine, AGL-155).
+ * 2. PAGE RESOLVERS — may fully resolve a path into page props
+ *    (plugins-commerce's PDP/PLP template composition for /products/* and
+ *    /collections/*, AGL-299). First non-undefined answer wins.
+ * 3. ENRICHERS — contribute extra props onto an already-resolved screen
+ *    page (plugins-marketing's overlays/experiments/client-automations).
+ *    Outputs are shallow-merged into the page props in registration order.
+ *
+ * Handlers run server-side (node runtime) and may use firebase-admin.
+ * Errors in enrichers are isolated (a broken plugin never 500s the site);
+ * resolver errors propagate because their output IS the page.
+ */
+export interface SitePageContext {
+    hostId: string;
+    /** The resolved host doc. */
+    host: any;
+    /** The org billing doc (entitlement source); undefined pre-billing. */
+    org?: any;
+    /** Request path, '/a/b' form ('/' for the site root). */
+    path: string;
+    slugSegments: string[];
+    /**
+     * This surface has NO single request path, so `path` above is a
+     * placeholder and nothing may be targeted by it (AGL-2511).
+     *
+     * One surface sets it: the host's designed 404 body. The `not-found`
+     * boundary fetches it by host and the response is cached per HOST — one
+     * compose a minute however many missing URLs are hit, which is the whole
+     * reason a scan of ten thousand dead URLs is cheap. Enriching it per path
+     * would key that cache per URL and make the same scan ten thousand
+     * composes.
+     *
+     * An enricher that reads `path` must, when this is set, contribute only
+     * what is path-INDEPENDENT and drop the rest — never substitute a plausible
+     * path. A site-wide announcement bar is path-independent and shows; an
+     * overlay pinned to `/pricing` cannot be evaluated and does not.
+     */
+    pathUnknown?: boolean;
+    screenId?: string;
+    /** The resolved screen doc (enrichers only). */
+    screen?: any;
+    /**
+     * The composed node tree for the page — layout applied, versions and
+     * references denormalized (enrichers only, AGL-659).
+     *
+     * An enricher that wants to seed a block's data server-side has to know
+     * which blocks are actually on the page and how each one is configured;
+     * the screen doc alone does not say, because composition pulls in layout
+     * and referenced nodes.
+     */
+    nodes?: any;
+}
+export interface SiteRedirectAnswer {
+    destination: string;
+    statusCode: number;
+}
+export type SiteRedirectResolver = (context: SitePageContext) => Promise<SiteRedirectAnswer | undefined> | SiteRedirectAnswer | undefined;
+/** A fully-composed page (the loader returns it verbatim as `props`). */
+export type SitePageAnswer = Record<string, unknown>;
+export type SitePageResolver = (context: SitePageContext) => Promise<SitePageAnswer | undefined>;
+export type SitePageEnricher = (context: SitePageContext) => Promise<Record<string, unknown> | undefined>;
+export declare function registerSiteRedirectResolver(fn: SiteRedirectResolver): void;
+export declare function registerSitePageResolver(fn: SitePageResolver): void;
+export declare function registerSitePageEnricher(fn: SitePageEnricher): void;
+export declare function resolveSiteRedirect(context: SitePageContext): Promise<SiteRedirectAnswer | undefined>;
+export declare function resolveSitePage(context: SitePageContext): Promise<SitePageAnswer | undefined>;
+export interface SitePageEnrichment {
+    /** The merged contributions, spread into the page props as before. */
+    props: Record<string, unknown>;
+    /** Plugins that returned something non-empty for THIS page. */
+    contributors: string[];
+    /**
+     * True when an enricher produced work but could not be attributed to a
+     * plugin — registered outside a plugin's register fn, so the loader's
+     * marker was unset. Callers narrowing on `contributors` must treat this as
+     * "cannot narrow": an unattributed contribution belongs to somebody.
+     */
+    unattributed: boolean;
+}
+export declare function runSitePageEnrichers(context: SitePageContext): Promise<SitePageEnrichment>;

package/src/lib/plugin-manager/site-page-hooks.js

@@ -0,0 +1,114 @@
+/**
+ * @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.
+ */ // The leaf module, NOT `api-plugins` — that one is reachable only through the
+// `/server` entry, and importing it from this shared barrel formed a cycle
+// that left the binding missing at runtime (AGL-1289).
+import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const redirectResolvers = [];
+const pageResolvers = [];
+const enrichers = [];
+/**
+ * Which plugin registered which enricher (AGL-1289). Recorded from the loader's
+ * existing "currently registering" marker — the same mechanism that gives
+ * `registerPluginApiRoute` its path→plugin ownership — so plugins need no new
+ * API and nothing has to be kept in sync by hand.
+ */ const enricherOwners = new WeakMap();
+export function registerSiteRedirectResolver(fn) {
+    redirectResolvers.push(fn);
+}
+export function registerSitePageResolver(fn) {
+    pageResolvers.push(fn);
+}
+export function registerSitePageEnricher(fn) {
+    enrichers.push(fn);
+    const owner = getRegisteringPluginId();
+    if (owner) enricherOwners.set(fn, owner);
+}
+export async function resolveSiteRedirect(context) {
+    for (const resolver of redirectResolvers){
+        const answer = await resolver(context);
+        if (answer) return answer;
+    }
+    return undefined;
+}
+export async function resolveSitePage(context) {
+    for (const resolver of pageResolvers){
+        const answer = await resolver(context);
+        if (answer) return answer;
+    }
+    return undefined;
+}
+/** Null/undefined, an empty array or an empty object — nothing to render. */ function isEmptyContribution(value) {
+    if (value == null) return true;
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'object') return Object.keys(value).length === 0;
+    return false;
+}
+export async function runSitePageEnrichers(context) {
+    const merged = {};
+    const contributors = new Set();
+    let unattributed = false;
+    // CONCURRENT, MERGED IN REGISTRATION ORDER (2026-08-26).
+    //
+    // This was a sequential `for … await`, so every enricher waited on the one
+    // before it for no reason: each takes the same immutable `context`, returns
+    // its own prop slice, and shares nothing. Production timing put the phase at
+    // a flat ~85–120 ms on EVERY render — including pages whose entire loader
+    // was 137 ms — because it is a fixed number of round trips, not work that
+    // scales with the page.
+    //
+    // `allSettled` rather than `all`: a broken plugin must drop its slice, never
+    // the page, which is the isolation the per-enricher try/catch gave and the
+    // plugin docs promise. Results are merged in ARRAY order, which `allSettled`
+    // preserves — so two enrichers contributing the same key resolve exactly as
+    // they did when the loop was sequential, and `contributors` keeps its
+    // insertion order.
+    const settled = await Promise.allSettled(enrichers.map(async (enricher)=>{
+        var _ref;
+        return (_ref = await enricher(context)) != null ? _ref : {};
+    }));
+    for (const [index, outcome] of settled.entries()){
+        const enricher = enrichers[index];
+        try {
+            if (outcome.status === 'rejected') throw outcome.reason;
+            const result = outcome.value;
+            Object.assign(merged, result);
+            // "Contributed" means produced something with content, not merely
+            // returned a key. Every marketing enricher returns its full key set on
+            // every page — `announcementBar: null`, `experiments: []` — so keying
+            // off presence would mark it a contributor everywhere and the
+            // attribution would be worth nothing.
+            if (Object.values(result).some((value)=>!isEmptyContribution(value))) {
+                const owner = enricherOwners.get(enricher);
+                if (owner) contributors.add(owner);
+                else unattributed = true;
+            }
+        } catch (error) {
+            // A broken plugin must not take the site down — the page renders
+            // without that plugin's contribution.
+            console.error('site page enricher failed', error);
+        }
+    }
+    return {
+        props: merged,
+        contributors: [
+            ...contributors
+        ],
+        unattributed
+    };
+}
+
+//# sourceMappingURL=site-page-hooks.js.map

package/src/lib/plugin-manager/site-page-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/site-page-hooks.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// The leaf module, NOT `api-plugins` — that one is reachable only through the\n// `/server` entry, and importing it from this shared barrel formed a cycle\n// that left the binding missing at runtime (AGL-1289).\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/**\n * Tenant page-composition extension points (AGL-418): plugins hook the\n * site loader (`load-page-data`) from their `/server` entries instead of\n * the app importing plugin domain code. Three kinds, run in this order:\n *\n * 1. REDIRECT RESOLVERS — may answer a request with a redirect before any\n *    route resolution (plugins-redirects' rule engine, AGL-155).\n * 2. PAGE RESOLVERS — may fully resolve a path into page props\n *    (plugins-commerce's PDP/PLP template composition for /products/* and\n *    /collections/*, AGL-299). First non-undefined answer wins.\n * 3. ENRICHERS — contribute extra props onto an already-resolved screen\n *    page (plugins-marketing's overlays/experiments/client-automations).\n *    Outputs are shallow-merged into the page props in registration order.\n *\n * Handlers run server-side (node runtime) and may use firebase-admin.\n * Errors in enrichers are isolated (a broken plugin never 500s the site);\n * resolver errors propagate because their output IS the page.\n */\n\nexport interface SitePageContext {\n  hostId: string\n  /** The resolved host doc. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  host: any\n  /** The org billing doc (entitlement source); undefined pre-billing. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  org?: any\n  /** Request path, '/a/b' form ('/' for the site root). */\n  path: string\n  slugSegments: string[]\n  /**\n   * This surface has NO single request path, so `path` above is a\n   * placeholder and nothing may be targeted by it (AGL-2511).\n   *\n   * One surface sets it: the host's designed 404 body. The `not-found`\n   * boundary fetches it by host and the response is cached per HOST — one\n   * compose a minute however many missing URLs are hit, which is the whole\n   * reason a scan of ten thousand dead URLs is cheap. Enriching it per path\n   * would key that cache per URL and make the same scan ten thousand\n   * composes.\n   *\n   * An enricher that reads `path` must, when this is set, contribute only\n   * what is path-INDEPENDENT and drop the rest — never substitute a plausible\n   * path. A site-wide announcement bar is path-independent and shows; an\n   * overlay pinned to `/pricing` cannot be evaluated and does not.\n   */\n  pathUnknown?: boolean\n  screenId?: string\n  /** The resolved screen doc (enrichers only). */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  screen?: any\n  /**\n   * The composed node tree for the page — layout applied, versions and\n   * references denormalized (enrichers only, AGL-659).\n   *\n   * An enricher that wants to seed a block's data server-side has to know\n   * which blocks are actually on the page and how each one is configured;\n   * the screen doc alone does not say, because composition pulls in layout\n   * and referenced nodes.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  nodes?: any\n}\n\nexport interface SiteRedirectAnswer {\n  destination: string\n  statusCode: number\n}\nexport type SiteRedirectResolver = (\n  context: SitePageContext,\n) => Promise<SiteRedirectAnswer | undefined> | SiteRedirectAnswer | undefined\n\n/** A fully-composed page (the loader returns it verbatim as `props`). */\nexport type SitePageAnswer = Record<string, unknown>\nexport type SitePageResolver = (\n  context: SitePageContext,\n) => Promise<SitePageAnswer | undefined>\n\nexport type SitePageEnricher = (\n  context: SitePageContext,\n) => Promise<Record<string, unknown> | undefined>\n\nconst redirectResolvers: SiteRedirectResolver[] = []\nconst pageResolvers: SitePageResolver[] = []\nconst enrichers: SitePageEnricher[] = []\n/**\n * Which plugin registered which enricher (AGL-1289). Recorded from the loader's\n * existing \"currently registering\" marker — the same mechanism that gives\n * `registerPluginApiRoute` its path→plugin ownership — so plugins need no new\n * API and nothing has to be kept in sync by hand.\n */\nconst enricherOwners = new WeakMap<SitePageEnricher, string>()\n\nexport function registerSiteRedirectResolver(fn: SiteRedirectResolver): void {\n  redirectResolvers.push(fn)\n}\nexport function registerSitePageResolver(fn: SitePageResolver): void {\n  pageResolvers.push(fn)\n}\nexport function registerSitePageEnricher(fn: SitePageEnricher): void {\n  enrichers.push(fn)\n  const owner = getRegisteringPluginId()\n  if (owner) enricherOwners.set(fn, owner)\n}\n\nexport async function resolveSiteRedirect(\n  context: SitePageContext,\n): Promise<SiteRedirectAnswer | undefined> {\n  for (const resolver of redirectResolvers) {\n    const answer = await resolver(context)\n    if (answer) return answer\n  }\n  return undefined\n}\n\nexport async function resolveSitePage(\n  context: SitePageContext,\n): Promise<SitePageAnswer | undefined> {\n  for (const resolver of pageResolvers) {\n    const answer = await resolver(context)\n    if (answer) return answer\n  }\n  return undefined\n}\n\n/** Null/undefined, an empty array or an empty object — nothing to render. */\nfunction isEmptyContribution(value: unknown): boolean {\n  if (value == null) return true\n  if (Array.isArray(value)) return value.length === 0\n  if (typeof value === 'object') return Object.keys(value).length === 0\n  return false\n}\n\nexport interface SitePageEnrichment {\n  /** The merged contributions, spread into the page props as before. */\n  props: Record<string, unknown>\n  /** Plugins that returned something non-empty for THIS page. */\n  contributors: string[]\n  /**\n   * True when an enricher produced work but could not be attributed to a\n   * plugin — registered outside a plugin's register fn, so the loader's\n   * marker was unset. Callers narrowing on `contributors` must treat this as\n   * \"cannot narrow\": an unattributed contribution belongs to somebody.\n   */\n  unattributed: boolean\n}\n\nexport async function runSitePageEnrichers(\n  context: SitePageContext,\n): Promise<SitePageEnrichment> {\n  const merged: Record<string, unknown> = {}\n  const contributors = new Set<string>()\n  let unattributed = false\n\n  // CONCURRENT, MERGED IN REGISTRATION ORDER (2026-08-26).\n  //\n  // This was a sequential `for … await`, so every enricher waited on the one\n  // before it for no reason: each takes the same immutable `context`, returns\n  // its own prop slice, and shares nothing. Production timing put the phase at\n  // a flat ~85–120 ms on EVERY render — including pages whose entire loader\n  // was 137 ms — because it is a fixed number of round trips, not work that\n  // scales with the page.\n  //\n  // `allSettled` rather than `all`: a broken plugin must drop its slice, never\n  // the page, which is the isolation the per-enricher try/catch gave and the\n  // plugin docs promise. Results are merged in ARRAY order, which `allSettled`\n  // preserves — so two enrichers contributing the same key resolve exactly as\n  // they did when the loop was sequential, and `contributors` keeps its\n  // insertion order.\n  const settled = await Promise.allSettled(\n    enrichers.map(async (enricher) => (await enricher(context)) ?? {}),\n  )\n\n  for (const [index, outcome] of settled.entries()) {\n    const enricher = enrichers[index]\n    try {\n      if (outcome.status === 'rejected') throw outcome.reason\n      const result = outcome.value\n      Object.assign(merged, result)\n      // \"Contributed\" means produced something with content, not merely\n      // returned a key. Every marketing enricher returns its full key set on\n      // every page — `announcementBar: null`, `experiments: []` — so keying\n      // off presence would mark it a contributor everywhere and the\n      // attribution would be worth nothing.\n      if (Object.values(result).some((value) => !isEmptyContribution(value))) {\n        const owner = enricherOwners.get(enricher)\n        if (owner) contributors.add(owner)\n        else unattributed = true\n      }\n    } catch (error) {\n      // A broken plugin must not take the site down — the page renders\n      // without that plugin's contribution.\n      console.error('site page enricher failed', error)\n    }\n  }\n  return { props: merged, contributors: [...contributors], unattributed }\n}\n"],"names":["getRegisteringPluginId","redirectResolvers","pageResolvers","enrichers","enricherOwners","WeakMap","registerSiteRedirectResolver","fn","push","registerSitePageResolver","registerSitePageEnricher","owner","set","resolveSiteRedirect","context","resolver","answer","undefined","resolveSitePage","isEmptyContribution","value","Array","isArray","length","Object","keys","runSitePageEnrichers","merged","contributors","Set","unattributed","settled","Promise","allSettled","map","enricher","index","outcome","entries","status","reason","result","assign","values","some","get","add","error","console","props"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,8EAA8E;AAC9E,2EAA2E;AAC3E,uDAAuD;AACvD,SAASA,sBAAsB,QAAQ,qCAAiC;AAoFxE,MAAMC,oBAA4C,EAAE;AACpD,MAAMC,gBAAoC,EAAE;AAC5C,MAAMC,YAAgC,EAAE;AACxC;;;;;CAKC,GACD,MAAMC,iBAAiB,IAAIC;AAE3B,OAAO,SAASC,6BAA6BC,EAAwB;IACnEN,kBAAkBO,IAAI,CAACD;AACzB;AACA,OAAO,SAASE,yBAAyBF,EAAoB;IAC3DL,cAAcM,IAAI,CAACD;AACrB;AACA,OAAO,SAASG,yBAAyBH,EAAoB;IAC3DJ,UAAUK,IAAI,CAACD;IACf,MAAMI,QAAQX;IACd,IAAIW,OAAOP,eAAeQ,GAAG,CAACL,IAAII;AACpC;AAEA,OAAO,eAAeE,oBACpBC,OAAwB;IAExB,KAAK,MAAMC,YAAYd,kBAAmB;QACxC,MAAMe,SAAS,MAAMD,SAASD;QAC9B,IAAIE,QAAQ,OAAOA;IACrB;IACA,OAAOC;AACT;AAEA,OAAO,eAAeC,gBACpBJ,OAAwB;IAExB,KAAK,MAAMC,YAAYb,cAAe;QACpC,MAAMc,SAAS,MAAMD,SAASD;QAC9B,IAAIE,QAAQ,OAAOA;IACrB;IACA,OAAOC;AACT;AAEA,2EAA2E,GAC3E,SAASE,oBAAoBC,KAAc;IACzC,IAAIA,SAAS,MAAM,OAAO;IAC1B,IAAIC,MAAMC,OAAO,CAACF,QAAQ,OAAOA,MAAMG,MAAM,KAAK;IAClD,IAAI,OAAOH,UAAU,UAAU,OAAOI,OAAOC,IAAI,CAACL,OAAOG,MAAM,KAAK;IACpE,OAAO;AACT;AAgBA,OAAO,eAAeG,qBACpBZ,OAAwB;IAExB,MAAMa,SAAkC,CAAC;IACzC,MAAMC,eAAe,IAAIC;IACzB,IAAIC,eAAe;IAEnB,yDAAyD;IACzD,EAAE;IACF,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,0EAA0E;IAC1E,wBAAwB;IACxB,EAAE;IACF,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,sEAAsE;IACtE,mBAAmB;IACnB,MAAMC,UAAU,MAAMC,QAAQC,UAAU,CACtC9B,UAAU+B,GAAG,CAAC,OAAOC;YAAc;gBAAA,OAAA,MAAMA,SAASrB,oBAAf,OAA4B,CAAC;;IAGlE,KAAK,MAAM,CAACsB,OAAOC,QAAQ,IAAIN,QAAQO,OAAO,GAAI;QAChD,MAAMH,WAAWhC,SAAS,CAACiC,MAAM;QACjC,IAAI;YACF,IAAIC,QAAQE,MAAM,KAAK,YAAY,MAAMF,QAAQG,MAAM;YACvD,MAAMC,SAASJ,QAAQjB,KAAK;YAC5BI,OAAOkB,MAAM,CAACf,QAAQc;YACtB,kEAAkE;YAClE,uEAAuE;YACvE,sEAAsE;YACtE,8DAA8D;YAC9D,sCAAsC;YACtC,IAAIjB,OAAOmB,MAAM,CAACF,QAAQG,IAAI,CAAC,CAACxB,QAAU,CAACD,oBAAoBC,SAAS;gBACtE,MAAMT,QAAQP,eAAeyC,GAAG,CAACV;gBACjC,IAAIxB,OAAOiB,aAAakB,GAAG,CAACnC;qBACvBmB,eAAe;YACtB;QACF,EAAE,OAAOiB,OAAO;YACd,iEAAiE;YACjE,sCAAsC;YACtCC,QAAQD,KAAK,CAAC,6BAA6BA;QAC7C;IACF;IACA,OAAO;QAAEE,OAAOtB;QAAQC,cAAc;eAAIA;SAAa;QAAEE;IAAa;AACxE"}

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

@@ -0,0 +1,57 @@
+/**
+ * @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 { ComponentType } from 'react';
+/**
+ * Site-runtime registry (AGL-419): non-visual (or overlay) components a
+ * plugin runs on every rendered tenant page — experiment runners,
+ * automation engines, announcement bars/popups. Registered from the
+ * plugin's SITE register fn (same surface as canvas components) and
+ * rendered generically by the tenant catch-all, which passes the page
+ * props bag; each runtime picks the slices it owns (the shapes it wrote
+ * server-side via its page enricher).
+ */
+export interface SiteRuntimeProps {
+    hostId?: string;
+    /** Host routing map (screen id → path) for rename-safe navigation. */
+    screens?: Record<string, string>;
+    /** The page props composed by load-page-data (enricher output included). */
+    page: Record<string, any>;
+}
+/**
+ * Context handed to {@link SiteRuntimeEntry.loadPreviewProps} (AGL-830). The
+ * besigner Preview renders draft nodes with no server enricher, so a runtime
+ * that needs page-props (e.g. the marketing automations engine) rebuilds its
+ * own slice client-side from the passed Firestore instance.
+ */
+export interface SiteRuntimePreviewContext {
+    hostId?: string;
+    /** Client Firestore instance (typed `unknown` to avoid a firebase dep here). */
+    firestore: unknown;
+}
+export interface SiteRuntimeEntry {
+    pluginId: string;
+    runtimeId: string;
+    Component: ComponentType<SiteRuntimeProps>;
+    /**
+     * Optional (AGL-830): build this runtime's `page`-props slice client-side
+     * for the editor Preview, where no server enricher runs. The returned bag
+     * is passed as the runtime's `page` prop. Absent → the runtime gets `{}`.
+     */
+    loadPreviewProps?: (ctx: SiteRuntimePreviewContext) => Promise<Record<string, unknown>>;
+}
+export declare function registerSiteRuntime(entry: SiteRuntimeEntry): void;
+export declare function listSiteRuntimes(): readonly SiteRuntimeEntry[];

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

@@ -0,0 +1,25 @@
+/**
+ * @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.
+ */ const runtimes = [];
+export function registerSiteRuntime(entry) {
+    if (runtimes.some((r)=>r.runtimeId === entry.runtimeId)) return;
+    runtimes.push(entry);
+}
+export function listSiteRuntimes() {
+    return runtimes;
+}
+
+//# sourceMappingURL=site-runtime.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/site-runtime.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 { ComponentType } from 'react'\n\n/**\n * Site-runtime registry (AGL-419): non-visual (or overlay) components a\n * plugin runs on every rendered tenant page — experiment runners,\n * automation engines, announcement bars/popups. Registered from the\n * plugin's SITE register fn (same surface as canvas components) and\n * rendered generically by the tenant catch-all, which passes the page\n * props bag; each runtime picks the slices it owns (the shapes it wrote\n * server-side via its page enricher).\n */\nexport interface SiteRuntimeProps {\n  hostId?: string\n  /** Host routing map (screen id → path) for rename-safe navigation. */\n  screens?: Record<string, string>\n  /** The page props composed by load-page-data (enricher output included). */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  page: Record<string, any>\n}\n\n/**\n * Context handed to {@link SiteRuntimeEntry.loadPreviewProps} (AGL-830). The\n * besigner Preview renders draft nodes with no server enricher, so a runtime\n * that needs page-props (e.g. the marketing automations engine) rebuilds its\n * own slice client-side from the passed Firestore instance.\n */\nexport interface SiteRuntimePreviewContext {\n  hostId?: string\n  /** Client Firestore instance (typed `unknown` to avoid a firebase dep here). */\n  firestore: unknown\n}\n\nexport interface SiteRuntimeEntry {\n  pluginId: string\n  runtimeId: string\n  Component: ComponentType<SiteRuntimeProps>\n  /**\n   * Optional (AGL-830): build this runtime's `page`-props slice client-side\n   * for the editor Preview, where no server enricher runs. The returned bag\n   * is passed as the runtime's `page` prop. Absent → the runtime gets `{}`.\n   */\n  loadPreviewProps?: (\n    ctx: SiteRuntimePreviewContext,\n  ) => Promise<Record<string, unknown>>\n}\n\nconst runtimes: SiteRuntimeEntry[] = []\n\nexport function registerSiteRuntime(entry: SiteRuntimeEntry): void {\n  if (runtimes.some((r) => r.runtimeId === entry.runtimeId)) return\n  runtimes.push(entry)\n}\n\nexport function listSiteRuntimes(): readonly SiteRuntimeEntry[] {\n  return runtimes\n}\n"],"names":["runtimes","registerSiteRuntime","entry","some","r","runtimeId","push","listSiteRuntimes"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAgDD,MAAMA,WAA+B,EAAE;AAEvC,OAAO,SAASC,oBAAoBC,KAAuB;IACzD,IAAIF,SAASG,IAAI,CAAC,CAACC,IAAMA,EAAEC,SAAS,KAAKH,MAAMG,SAAS,GAAG;IAC3DL,SAASM,IAAI,CAACJ;AAChB;AAEA,OAAO,SAASK;IACd,OAAOP;AACT"}