@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/plugin-manager/usage-alert-contributors.d.ts

@@ -15,14 +15,22 @@
  * limitations under the License.
  */
 /**
- * Staff alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
+ * Alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
  *
  * The usage-alerts cron walks every org, reads its usage once, and sends
  * core's own alerts: the plan quotas, the customer's budget and the free
  * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling
  * core knows nothing about registers a contributor here from its
- * `serverDeclarations` entry, and the sweep hands the contributor each org's
- * reading after the budget alert and before the bandwidth cap.
+ * `serverDeclarations` entry, in either or both of two shapes:
+ *
+ * - `quotaChecks` answers the bands the WORKSPACE is warned about — a used
+ *   figure against a limit, how often it may be announced, what happens at
+ *   it, and the words for approaching and reaching it. The sweep runs them
+ *   after its own quota checks, through the same approach threshold, guards
+ *   and both channels, so a plugin's band warns exactly as a platform band
+ *   does.
+ * - `evaluate` decides STAFF alerts, and the sweep hands it each org's
+ *   reading after the budget alert and before the bandwidth cap.
  *
  * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due
  * and what it says; the context does everything else:
@@ -57,6 +65,7 @@
  * loaded the declarations, and a list that followed it could send and report
  * one org's alerts in a different order per process.
  */
+import type { NotificationLevel } from '../app-utils/notifications';
 import type { OrgSpendBreakdown, UsageAlertGuard } from '../app-utils/usage-budget';
 /** One staff alert, as the sweep delivers and reports it. */
 export interface UsageStaffAlert {
@@ -72,6 +81,12 @@ export interface UsageStaffAlert {
     link: string;
     /** The email's tag and log label. */
     emailContext: string;
+    /**
+     * How loud the bell draws it (AGL-3437). A contributor's threshold is its
+     * own unit, not a percentage, so only the contributor can say; absent, the
+     * `billing.usage` default answers.
+     */
+    level?: NotificationLevel;
 }
 /** What the sweep hands a contributor for one org. */
 export interface UsageAlertContext {
@@ -94,19 +109,74 @@ export interface UsageAlertContext {
     /** Delivers one staff alert through the sweep's senders and reports it. */
     alertStaff: (alert: UsageStaffAlert) => Promise<void>;
 }
+/**
+ * One band a workspace is warned about as it approaches and reaches it — the
+ * shape of a plugin's quota check.
+ *
+ * The sweep owns everything past the numbers and the words: the approach
+ * percentage, the guard under `key`, the first-sweep seeding, both channels,
+ * and the sentence every notice opens with — the workspace, then the figures,
+ * then `noun` ("The Acme workspace has used 2,300 of the 2,750 AI assist
+ * credits your plan includes this month").
+ */
+export interface UsageQuotaCheck {
+    /** The guard key; named for what it measures, never one of core's. */
+    key: string;
+    /** How the alert's title names the band: "AI assist credits". */
+    label: string;
+    /** What the figures count, in the opening sentence. */
+    noun: string;
+    used: number;
+    /** `UNLIMITED` or anything not above 0 is skipped. */
+    limit: number;
+    /**
+     * How often one threshold may be announced: `crossing` for something the
+     * workspace HAS, announced once when reached and again only after usage
+     * falls back below; `monthly` for a meter that resets on the 1st.
+     */
+    cadence: 'crossing' | 'monthly';
+    /**
+     * What happens at the band, which the notice has to say because the three
+     * call for different actions: `stops` (new use is refused, nothing is
+     * charged), `bills` (it keeps working and starts charging) or `continues`
+     * (nothing is refused and nothing is charged).
+     */
+    outcome: 'stops' | 'bills' | 'continues';
+    /** What is true now, at or past the band. */
+    reached: string;
+    /** What will happen at the band, said while approaching it. */
+    approach: string;
+    /** Replaces the generic title at 100%, when that would not be true. */
+    reachedTitle?: string;
+}
+/** What the sweep hands a contributor's quota checks for one org. */
+export interface UsageQuotaContext {
+    orgId: string;
+    /** The org document as the sweep read it. */
+    org: Readonly<Record<string, unknown>>;
+    /** The `YYYY-MM` month the sweep dedupes against. */
+    month: string;
+    /** The org's spend this month, built from the figures the sweep read. */
+    spend: Readonly<OrgSpendBreakdown>;
+}
 /** A plugin's rule for the usage-alerts sweep. */
 export interface UsageAlertContributor {
     pluginId: string;
     /** Unique within the plugin; two plugins may use the same id. */
     id: string;
-    /** Evaluates one org, sending only through the context. */
-    evaluate: (context: UsageAlertContext) => Promise<void>;
+    /** Evaluates one org's STAFF alerts, sending only through the context. */
+    evaluate?: (context: UsageAlertContext) => Promise<void>;
+    /**
+     * The bands the WORKSPACE is warned about, which the sweep runs after its
+     * own through the same thresholds, guards and senders.
+     */
+    quotaChecks?: (context: UsageQuotaContext) => Promise<readonly UsageQuotaCheck[]>;
 }
 /**
  * Registers a contributor. Idempotent per plugin and id: registering the same
  * pair again replaces the earlier contributor in place, so a declarations
  * module evaluated twice does not alert twice. A contributor with no plugin,
- * no id or no `evaluate` throws.
+ * no id, or neither `evaluate` nor `quotaChecks` throws.
  */
 export declare function registerUsageAlertContributor(contributor: UsageAlertContributor): void;
 /** Every registered contributor, in the order the sweep runs them. */

package/src/lib/plugin-manager/usage-alert-contributors.js

@@ -14,14 +14,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ /**
- * Staff alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
+ * Alerts a plugin contributes to the usage-alerts sweep (AGL-2984).
  *
  * The usage-alerts cron walks every org, reads its usage once, and sends
  * core's own alerts: the plan quotas, the customer's budget and the free
  * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling
  * core knows nothing about registers a contributor here from its
- * `serverDeclarations` entry, and the sweep hands the contributor each org's
- * reading after the budget alert and before the bandwidth cap.
+ * `serverDeclarations` entry, in either or both of two shapes:
+ *
+ * - `quotaChecks` answers the bands the WORKSPACE is warned about — a used
+ *   figure against a limit, how often it may be announced, what happens at
+ *   it, and the words for approaching and reaching it. The sweep runs them
+ *   after its own quota checks, through the same approach threshold, guards
+ *   and both channels, so a plugin's band warns exactly as a platform band
+ *   does.
+ * - `evaluate` decides STAFF alerts, and the sweep hands it each org's
+ *   reading after the budget alert and before the bandwidth cap.
  *
  * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due
  * and what it says; the context does everything else:
@@ -73,7 +81,7 @@ function catalogRank(pluginId) {
  * Registers a contributor. Idempotent per plugin and id: registering the same
  * pair again replaces the earlier contributor in place, so a declarations
  * module evaluated twice does not alert twice. A contributor with no plugin,
- * no id or no `evaluate` throws.
+ * no id, or neither `evaluate` nor `quotaChecks` throws.
  */ export function registerUsageAlertContributor(contributor) {
     var _contributor_pluginId, _contributor_id;
     const pluginId = String((_contributor_pluginId = contributor.pluginId) != null ? _contributor_pluginId : '').trim();
@@ -81,14 +89,19 @@ function catalogRank(pluginId) {
     if (!pluginId || !id) {
         throw new Error('a usage alert contributor needs a pluginId and an id');
     }
-    if (typeof contributor.evaluate !== 'function') {
-        throw new Error(`usage alert contributor "${pluginId}:${id}" has no evaluate function`);
+    const evaluate = typeof contributor.evaluate === 'function' ? contributor.evaluate : undefined;
+    const quotaChecks = typeof contributor.quotaChecks === 'function' ? contributor.quotaChecks : undefined;
+    if (!evaluate && !quotaChecks) {
+        throw new Error(`usage alert contributor "${pluginId}:${id}" has neither an evaluate ` + 'nor a quotaChecks function');
     }
-    const entry = {
+    const entry = _extends({
         pluginId,
-        id,
-        evaluate: contributor.evaluate
-    };
+        id
+    }, evaluate ? {
+        evaluate
+    } : {}, quotaChecks ? {
+        quotaChecks
+    } : {});
     const index = registrations.findIndex((existing)=>existing.pluginId === pluginId && existing.id === id);
     if (index >= 0) registrations[index] = entry;
     else registrations.push(entry);

package/src/lib/plugin-manager/usage-alert-contributors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/usage-alert-contributors.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 * Staff alerts a plugin contributes to the usage-alerts sweep (AGL-2984).\n *\n * The usage-alerts cron walks every org, reads its usage once, and sends\n * core's own alerts: the plan quotas, the customer's budget and the free\n * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling\n * core knows nothing about registers a contributor here from its\n * `serverDeclarations` entry, and the sweep hands the contributor each org's\n * reading after the budget alert and before the bandwidth cap.\n *\n * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due\n * and what it says; the context does everything else:\n *\n * - `recordAlert(key, threshold)` records the dedupe guard and answers\n *   whether the alert may be SENT. On an org's first, silent evaluation it\n *   records the guard as though the alert went out and answers `false`, so a\n *   contributor that sends only on `true` honors the first-sweep seeding\n *   without knowing when it applies.\n * - `alertStaff(alert)` is the sweep's own sender: the staff bell, then the\n *   staff inbox, then a row in the run's report saying whether the mail went\n *   out. On an org's first, silent evaluation it sends nothing, whoever calls\n *   it.\n * - `guards` is the org's guard map as the sweep read it. A contributor reads\n *   it to dedupe and never writes a guard itself: the sweep writes what\n *   `recordAlert` recorded, once, with the rest of the org's update.\n *\n * Guard keys share one map with core's own checks (`hosts`, `bandwidth`,\n * `budget` and the rest), so a contributor names its keys for what it\n * measures and never reuses one of core's.\n *\n * Contributors run one at a time and are ISOLATED: a throw is logged against\n * the contributor and the next one runs. A guard the failed contributor\n * recorded for an alert it never delivered is dropped rather than written, so\n * the next sweep tries that alert again instead of counting it as announced.\n * One plugin's failure costs no other plugin's alert, none of core's, and not\n * the rest of the sweep.\n *\n * The order is deterministic: the catalog order of `FIRST_PARTY_PLUGINS`,\n * then any other plugin id in code-unit order, then registration order within\n * a plugin. The order contributors REGISTER in depends on how each process\n * loaded the declarations, and a list that followed it could send and report\n * one org's alerts in a different order per process.\n */\n\nimport type {\n  OrgSpendBreakdown,\n  UsageAlertGuard,\n} from '../app-utils/usage-budget'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\n\n/** One staff alert, as the sweep delivers and reports it. */\nexport interface UsageStaffAlert {\n  /** The guard key the alert was recorded under; the report row's `quota`. */\n  quota: string\n  /** The threshold passed to `recordAlert`; the report row's `threshold`. */\n  threshold: number\n  /** The bell's title and the email's subject: one set of words for both. */\n  title: string\n  /** The bell's body. The email carries it verbatim, followed by the link. */\n  body: string\n  /** A console path. The bell links it; the email makes it absolute. */\n  link: string\n  /** The email's tag and log label. */\n  emailContext: string\n}\n\n/** What the sweep hands a contributor for one org. */\nexport interface UsageAlertContext {\n  orgId: string\n  /** The org's slug, or `null` when the document carries none. */\n  orgSlug: string | null\n  /** The org document as the sweep read it. */\n  org: Readonly<Record<string, unknown>>\n  /** The `YYYY-MM` month the sweep dedupes against, fixed for the whole run. */\n  month: string\n  /** The org's spend this month, built from the figures the sweep read. */\n  spend: Readonly<OrgSpendBreakdown>\n  /** The org's guard map as the sweep read it, before this run's updates. */\n  guards: Readonly<Record<string, Readonly<UsageAlertGuard>>>\n  /**\n   * Records the guard for `key` at `threshold` and answers whether the alert\n   * may be sent. Call it once the alert is due, and send only on `true`.\n   */\n  recordAlert: (key: string, threshold: number) => boolean\n  /** Delivers one staff alert through the sweep's senders and reports it. */\n  alertStaff: (alert: UsageStaffAlert) => Promise<void>\n}\n\n/** A plugin's rule for the usage-alerts sweep. */\nexport interface UsageAlertContributor {\n  pluginId: string\n  /** Unique within the plugin; two plugins may use the same id. */\n  id: string\n  /** Evaluates one org, sending only through the context. */\n  evaluate: (context: UsageAlertContext) => Promise<void>\n}\n\nconst registrations: UsageAlertContributor[] = []\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\n/** Code-unit order, which no locale can reorder. */\nfunction codeUnitOrder(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0\n}\n\n/**\n * Registers a contributor. Idempotent per plugin and id: registering the same\n * pair again replaces the earlier contributor in place, so a declarations\n * module evaluated twice does not alert twice. A contributor with no plugin,\n * no id or no `evaluate` throws.\n */\nexport function registerUsageAlertContributor(\n  contributor: UsageAlertContributor,\n): void {\n  const pluginId = String(contributor.pluginId ?? '').trim()\n  const id = String(contributor.id ?? '').trim()\n  if (!pluginId || !id) {\n    throw new Error('a usage alert contributor needs a pluginId and an id')\n  }\n  if (typeof contributor.evaluate !== 'function') {\n    throw new Error(\n      `usage alert contributor \"${pluginId}:${id}\" has no evaluate function`,\n    )\n  }\n  const entry: UsageAlertContributor = {\n    pluginId,\n    id,\n    evaluate: contributor.evaluate,\n  }\n  const index = registrations.findIndex(\n    (existing) => existing.pluginId === pluginId && existing.id === id,\n  )\n  if (index >= 0) registrations[index] = entry\n  else registrations.push(entry)\n}\n\n/** Every registered contributor, in the order the sweep runs them. */\nexport function listUsageAlertContributors(): UsageAlertContributor[] {\n  return registrations\n    .map((entry, sequence) => ({ entry, sequence }))\n    .sort(\n      (a, b) =>\n        catalogRank(a.entry.pluginId) - catalogRank(b.entry.pluginId) ||\n        codeUnitOrder(a.entry.pluginId, b.entry.pluginId) ||\n        a.sequence - b.sequence,\n    )\n    .map(({ entry }) => ({ ...entry }))\n}\n\n/** Test seam: forget every contributor. */\nexport function resetUsageAlertContributorsForTests(): void {\n  registrations.length = 0\n}\n"],"names":["FIRST_PARTY_PLUGINS","registrations","CATALOG_ORDER","Map","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","codeUnitOrder","a","b","registerUsageAlertContributor","contributor","String","trim","Error","evaluate","entry","findIndex","existing","push","listUsageAlertContributors","sequence","sort","resetUsageAlertContributorsForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CC;AAMD,SAASA,mBAAmB,QAAQ,uBAAmB;AAiDvD,MAAMC,gBAAyC,EAAE;AAEjD,MAAMC,gBAAgB,IAAIC,IACxBH,oBAAoBI,GAAG,CAAC,CAACC,QAAQC,QAAU;QAACD,OAAOE,EAAE;QAAED;KAAM;AAG/D,SAASE,YAAYC,QAAgB;QAC5BP;IAAP,QAAOA,qBAAAA,cAAcQ,GAAG,CAACD,qBAAlBP,qBAA+BS,OAAOC,gBAAgB;AAC/D;AAEA,kDAAkD,GAClD,SAASC,cAAcC,CAAS,EAAEC,CAAS;IACzC,OAAOD,IAAIC,IAAI,CAAC,IAAID,IAAIC,IAAI,IAAI;AAClC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,8BACdC,WAAkC;QAEVA,uBACNA;IADlB,MAAMR,WAAWS,QAAOD,wBAAAA,YAAYR,QAAQ,YAApBQ,wBAAwB,IAAIE,IAAI;IACxD,MAAMZ,KAAKW,QAAOD,kBAAAA,YAAYV,EAAE,YAAdU,kBAAkB,IAAIE,IAAI;IAC5C,IAAI,CAACV,YAAY,CAACF,IAAI;QACpB,MAAM,IAAIa,MAAM;IAClB;IACA,IAAI,OAAOH,YAAYI,QAAQ,KAAK,YAAY;QAC9C,MAAM,IAAID,MACR,CAAC,yBAAyB,EAAEX,SAAS,CAAC,EAAEF,GAAG,0BAA0B,CAAC;IAE1E;IACA,MAAMe,QAA+B;QACnCb;QACAF;QACAc,UAAUJ,YAAYI,QAAQ;IAChC;IACA,MAAMf,QAAQL,cAAcsB,SAAS,CACnC,CAACC,WAAaA,SAASf,QAAQ,KAAKA,YAAYe,SAASjB,EAAE,KAAKA;IAElE,IAAID,SAAS,GAAGL,aAAa,CAACK,MAAM,GAAGgB;SAClCrB,cAAcwB,IAAI,CAACH;AAC1B;AAEA,oEAAoE,GACpE,OAAO,SAASI;IACd,OAAOzB,cACJG,GAAG,CAAC,CAACkB,OAAOK,WAAc,CAAA;YAAEL;YAAOK;QAAS,CAAA,GAC5CC,IAAI,CACH,CAACd,GAAGC,IACFP,YAAYM,EAAEQ,KAAK,CAACb,QAAQ,IAAID,YAAYO,EAAEO,KAAK,CAACb,QAAQ,KAC5DI,cAAcC,EAAEQ,KAAK,CAACb,QAAQ,EAAEM,EAAEO,KAAK,CAACb,QAAQ,KAChDK,EAAEa,QAAQ,GAAGZ,EAAEY,QAAQ,EAE1BvB,GAAG,CAAC,CAAC,EAAEkB,KAAK,EAAE,GAAM,aAAKA;AAC9B;AAEA,yCAAyC,GACzC,OAAO,SAASO;IACd5B,cAAc6B,MAAM,GAAG;AACzB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/usage-alert-contributors.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 * Alerts a plugin contributes to the usage-alerts sweep (AGL-2984).\n *\n * The usage-alerts cron walks every org, reads its usage once, and sends\n * core's own alerts: the plan quotas, the customer's budget and the free\n * plan's bandwidth cap. A plugin that meters a cost or enforces a ceiling\n * core knows nothing about registers a contributor here from its\n * `serverDeclarations` entry, in either or both of two shapes:\n *\n * - `quotaChecks` answers the bands the WORKSPACE is warned about — a used\n *   figure against a limit, how often it may be announced, what happens at\n *   it, and the words for approaching and reaching it. The sweep runs them\n *   after its own quota checks, through the same approach threshold, guards\n *   and both channels, so a plugin's band warns exactly as a platform band\n *   does.\n * - `evaluate` decides STAFF alerts, and the sweep hands it each org's\n *   reading after the budget alert and before the bandwidth cap.\n *\n * THE PIPELINE IS THE SWEEP'S. A contributor decides whether an alert is due\n * and what it says; the context does everything else:\n *\n * - `recordAlert(key, threshold)` records the dedupe guard and answers\n *   whether the alert may be SENT. On an org's first, silent evaluation it\n *   records the guard as though the alert went out and answers `false`, so a\n *   contributor that sends only on `true` honors the first-sweep seeding\n *   without knowing when it applies.\n * - `alertStaff(alert)` is the sweep's own sender: the staff bell, then the\n *   staff inbox, then a row in the run's report saying whether the mail went\n *   out. On an org's first, silent evaluation it sends nothing, whoever calls\n *   it.\n * - `guards` is the org's guard map as the sweep read it. A contributor reads\n *   it to dedupe and never writes a guard itself: the sweep writes what\n *   `recordAlert` recorded, once, with the rest of the org's update.\n *\n * Guard keys share one map with core's own checks (`hosts`, `bandwidth`,\n * `budget` and the rest), so a contributor names its keys for what it\n * measures and never reuses one of core's.\n *\n * Contributors run one at a time and are ISOLATED: a throw is logged against\n * the contributor and the next one runs. A guard the failed contributor\n * recorded for an alert it never delivered is dropped rather than written, so\n * the next sweep tries that alert again instead of counting it as announced.\n * One plugin's failure costs no other plugin's alert, none of core's, and not\n * the rest of the sweep.\n *\n * The order is deterministic: the catalog order of `FIRST_PARTY_PLUGINS`,\n * then any other plugin id in code-unit order, then registration order within\n * a plugin. The order contributors REGISTER in depends on how each process\n * loaded the declarations, and a list that followed it could send and report\n * one org's alerts in a different order per process.\n */\n\nimport type { NotificationLevel } from '../app-utils/notifications'\nimport type {\n  OrgSpendBreakdown,\n  UsageAlertGuard,\n} from '../app-utils/usage-budget'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\n\n/** One staff alert, as the sweep delivers and reports it. */\nexport interface UsageStaffAlert {\n  /** The guard key the alert was recorded under; the report row's `quota`. */\n  quota: string\n  /** The threshold passed to `recordAlert`; the report row's `threshold`. */\n  threshold: number\n  /** The bell's title and the email's subject: one set of words for both. */\n  title: string\n  /** The bell's body. The email carries it verbatim, followed by the link. */\n  body: string\n  /** A console path. The bell links it; the email makes it absolute. */\n  link: string\n  /** The email's tag and log label. */\n  emailContext: string\n  /**\n   * How loud the bell draws it (AGL-3437). A contributor's threshold is its\n   * own unit, not a percentage, so only the contributor can say; absent, the\n   * `billing.usage` default answers.\n   */\n  level?: NotificationLevel\n}\n\n/** What the sweep hands a contributor for one org. */\nexport interface UsageAlertContext {\n  orgId: string\n  /** The org's slug, or `null` when the document carries none. */\n  orgSlug: string | null\n  /** The org document as the sweep read it. */\n  org: Readonly<Record<string, unknown>>\n  /** The `YYYY-MM` month the sweep dedupes against, fixed for the whole run. */\n  month: string\n  /** The org's spend this month, built from the figures the sweep read. */\n  spend: Readonly<OrgSpendBreakdown>\n  /** The org's guard map as the sweep read it, before this run's updates. */\n  guards: Readonly<Record<string, Readonly<UsageAlertGuard>>>\n  /**\n   * Records the guard for `key` at `threshold` and answers whether the alert\n   * may be sent. Call it once the alert is due, and send only on `true`.\n   */\n  recordAlert: (key: string, threshold: number) => boolean\n  /** Delivers one staff alert through the sweep's senders and reports it. */\n  alertStaff: (alert: UsageStaffAlert) => Promise<void>\n}\n\n/**\n * One band a workspace is warned about as it approaches and reaches it — the\n * shape of a plugin's quota check.\n *\n * The sweep owns everything past the numbers and the words: the approach\n * percentage, the guard under `key`, the first-sweep seeding, both channels,\n * and the sentence every notice opens with — the workspace, then the figures,\n * then `noun` (\"The Acme workspace has used 2,300 of the 2,750 AI assist\n * credits your plan includes this month\").\n */\nexport interface UsageQuotaCheck {\n  /** The guard key; named for what it measures, never one of core's. */\n  key: string\n  /** How the alert's title names the band: \"AI assist credits\". */\n  label: string\n  /** What the figures count, in the opening sentence. */\n  noun: string\n  used: number\n  /** `UNLIMITED` or anything not above 0 is skipped. */\n  limit: number\n  /**\n   * How often one threshold may be announced: `crossing` for something the\n   * workspace HAS, announced once when reached and again only after usage\n   * falls back below; `monthly` for a meter that resets on the 1st.\n   */\n  cadence: 'crossing' | 'monthly'\n  /**\n   * What happens at the band, which the notice has to say because the three\n   * call for different actions: `stops` (new use is refused, nothing is\n   * charged), `bills` (it keeps working and starts charging) or `continues`\n   * (nothing is refused and nothing is charged).\n   */\n  outcome: 'stops' | 'bills' | 'continues'\n  /** What is true now, at or past the band. */\n  reached: string\n  /** What will happen at the band, said while approaching it. */\n  approach: string\n  /** Replaces the generic title at 100%, when that would not be true. */\n  reachedTitle?: string\n}\n\n/** What the sweep hands a contributor's quota checks for one org. */\nexport interface UsageQuotaContext {\n  orgId: string\n  /** The org document as the sweep read it. */\n  org: Readonly<Record<string, unknown>>\n  /** The `YYYY-MM` month the sweep dedupes against. */\n  month: string\n  /** The org's spend this month, built from the figures the sweep read. */\n  spend: Readonly<OrgSpendBreakdown>\n}\n\n/** A plugin's rule for the usage-alerts sweep. */\nexport interface UsageAlertContributor {\n  pluginId: string\n  /** Unique within the plugin; two plugins may use the same id. */\n  id: string\n  /** Evaluates one org's STAFF alerts, sending only through the context. */\n  evaluate?: (context: UsageAlertContext) => Promise<void>\n  /**\n   * The bands the WORKSPACE is warned about, which the sweep runs after its\n   * own through the same thresholds, guards and senders.\n   */\n  quotaChecks?: (context: UsageQuotaContext) => Promise<readonly UsageQuotaCheck[]>\n}\n\nconst registrations: UsageAlertContributor[] = []\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\n/** Code-unit order, which no locale can reorder. */\nfunction codeUnitOrder(a: string, b: string): number {\n  return a < b ? -1 : a > b ? 1 : 0\n}\n\n/**\n * Registers a contributor. Idempotent per plugin and id: registering the same\n * pair again replaces the earlier contributor in place, so a declarations\n * module evaluated twice does not alert twice. A contributor with no plugin,\n * no id, or neither `evaluate` nor `quotaChecks` throws.\n */\nexport function registerUsageAlertContributor(\n  contributor: UsageAlertContributor,\n): void {\n  const pluginId = String(contributor.pluginId ?? '').trim()\n  const id = String(contributor.id ?? '').trim()\n  if (!pluginId || !id) {\n    throw new Error('a usage alert contributor needs a pluginId and an id')\n  }\n  const evaluate =\n    typeof contributor.evaluate === 'function' ? contributor.evaluate : undefined\n  const quotaChecks =\n    typeof contributor.quotaChecks === 'function'\n      ? contributor.quotaChecks\n      : undefined\n  if (!evaluate && !quotaChecks) {\n    throw new Error(\n      `usage alert contributor \"${pluginId}:${id}\" has neither an evaluate ` +\n        'nor a quotaChecks function',\n    )\n  }\n  const entry: UsageAlertContributor = {\n    pluginId,\n    id,\n    ...(evaluate ? { evaluate } : {}),\n    ...(quotaChecks ? { quotaChecks } : {}),\n  }\n  const index = registrations.findIndex(\n    (existing) => existing.pluginId === pluginId && existing.id === id,\n  )\n  if (index >= 0) registrations[index] = entry\n  else registrations.push(entry)\n}\n\n/** Every registered contributor, in the order the sweep runs them. */\nexport function listUsageAlertContributors(): UsageAlertContributor[] {\n  return registrations\n    .map((entry, sequence) => ({ entry, sequence }))\n    .sort(\n      (a, b) =>\n        catalogRank(a.entry.pluginId) - catalogRank(b.entry.pluginId) ||\n        codeUnitOrder(a.entry.pluginId, b.entry.pluginId) ||\n        a.sequence - b.sequence,\n    )\n    .map(({ entry }) => ({ ...entry }))\n}\n\n/** Test seam: forget every contributor. */\nexport function resetUsageAlertContributorsForTests(): void {\n  registrations.length = 0\n}\n"],"names":["FIRST_PARTY_PLUGINS","registrations","CATALOG_ORDER","Map","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","codeUnitOrder","a","b","registerUsageAlertContributor","contributor","String","trim","Error","evaluate","undefined","quotaChecks","entry","findIndex","existing","push","listUsageAlertContributors","sequence","sort","resetUsageAlertContributorsForTests","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDC;AAOD,SAASA,mBAAmB,QAAQ,uBAAmB;AAgHvD,MAAMC,gBAAyC,EAAE;AAEjD,MAAMC,gBAAgB,IAAIC,IACxBH,oBAAoBI,GAAG,CAAC,CAACC,QAAQC,QAAU;QAACD,OAAOE,EAAE;QAAED;KAAM;AAG/D,SAASE,YAAYC,QAAgB;QAC5BP;IAAP,QAAOA,qBAAAA,cAAcQ,GAAG,CAACD,qBAAlBP,qBAA+BS,OAAOC,gBAAgB;AAC/D;AAEA,kDAAkD,GAClD,SAASC,cAAcC,CAAS,EAAEC,CAAS;IACzC,OAAOD,IAAIC,IAAI,CAAC,IAAID,IAAIC,IAAI,IAAI;AAClC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,8BACdC,WAAkC;QAEVA,uBACNA;IADlB,MAAMR,WAAWS,QAAOD,wBAAAA,YAAYR,QAAQ,YAApBQ,wBAAwB,IAAIE,IAAI;IACxD,MAAMZ,KAAKW,QAAOD,kBAAAA,YAAYV,EAAE,YAAdU,kBAAkB,IAAIE,IAAI;IAC5C,IAAI,CAACV,YAAY,CAACF,IAAI;QACpB,MAAM,IAAIa,MAAM;IAClB;IACA,MAAMC,WACJ,OAAOJ,YAAYI,QAAQ,KAAK,aAAaJ,YAAYI,QAAQ,GAAGC;IACtE,MAAMC,cACJ,OAAON,YAAYM,WAAW,KAAK,aAC/BN,YAAYM,WAAW,GACvBD;IACN,IAAI,CAACD,YAAY,CAACE,aAAa;QAC7B,MAAM,IAAIH,MACR,CAAC,yBAAyB,EAAEX,SAAS,CAAC,EAAEF,GAAG,0BAA0B,CAAC,GACpE;IAEN;IACA,MAAMiB,QAA+B;QACnCf;QACAF;OACIc,WAAW;QAAEA;IAAS,IAAI,CAAC,GAC3BE,cAAc;QAAEA;IAAY,IAAI,CAAC;IAEvC,MAAMjB,QAAQL,cAAcwB,SAAS,CACnC,CAACC,WAAaA,SAASjB,QAAQ,KAAKA,YAAYiB,SAASnB,EAAE,KAAKA;IAElE,IAAID,SAAS,GAAGL,aAAa,CAACK,MAAM,GAAGkB;SAClCvB,cAAc0B,IAAI,CAACH;AAC1B;AAEA,oEAAoE,GACpE,OAAO,SAASI;IACd,OAAO3B,cACJG,GAAG,CAAC,CAACoB,OAAOK,WAAc,CAAA;YAAEL;YAAOK;QAAS,CAAA,GAC5CC,IAAI,CACH,CAAChB,GAAGC,IACFP,YAAYM,EAAEU,KAAK,CAACf,QAAQ,IAAID,YAAYO,EAAES,KAAK,CAACf,QAAQ,KAC5DI,cAAcC,EAAEU,KAAK,CAACf,QAAQ,EAAEM,EAAES,KAAK,CAACf,QAAQ,KAChDK,EAAEe,QAAQ,GAAGd,EAAEc,QAAQ,EAE1BzB,GAAG,CAAC,CAAC,EAAEoB,KAAK,EAAE,GAAM,aAAKA;AAC9B;AAEA,yCAAyC,GACzC,OAAO,SAASO;IACd9B,cAAc+B,MAAM,GAAG;AACzB"}

package/src/lib/plugin-manager/video-embed-provider.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A choice the Video element makes for each player it frames. A declaration
+ * says how its player spells each one it supports; one it does not name is
+ * never sent.
+ *
+ *  - `autoPlay` — start as soon as the player is ready. ON unless the caller
+ *    passes exactly `false`: the usual frame is the one a visitor's press
+ *    loads, and a second play button inside it would ask them twice.
+ *  - `doNotTrack` — ask the host not to record the viewing session.
+ *  - `muted` — start without sound.
+ *  - `loop` — restart at the end.
+ */
+export type VideoEmbedPlayerOption = 'autoPlay' | 'doNotTrack' | 'muted' | 'loop';
+export declare const VIDEO_EMBED_PLAYER_OPTIONS: readonly VideoEmbedPlayerOption[];
+export type VideoEmbedPlayerOptions = Partial<Record<VideoEmbedPlayerOption, boolean>>;
+/**
+ * One query parameter of a player address, in the order the declaration
+ * lists them. Either `value`, sent on every address, or an `option` whose
+ * state picks `on` or `off`; a state with no value leaves the parameter out.
+ */
+export type VideoEmbedPlayerParam = {
+    param: string;
+    value: string;
+} | {
+    param: string;
+    option: VideoEmbedPlayerOption;
+    on?: string;
+    off?: string;
+};
+export interface VideoEmbedProviderDeclaration {
+    /** Stable id, unique across plugins. */
+    id: string;
+    /** The host's name as an author knows it, for labels and help text. */
+    label: string;
+    /**
+     * The domains a link's host must equal or end in (after a dot). Exact or
+     * dot-anchored only, so a domain that merely contains one is refused.
+     */
+    domains: readonly string[];
+    /**
+     * Regular expressions over a link's PATH, anchored at both ends, whose
+     * first capture group is the media id. The host is checked separately,
+     * against {@link domains}.
+     */
+    mediaIdPaths: readonly string[];
+    /** A regular expression, anchored at both ends, a media id must match. */
+    mediaIdPattern: string;
+    /** The one origin the host's player is framed from. */
+    playerOrigin: string;
+    /** The player page's path on {@link playerOrigin}; `{id}` is the media id. */
+    playerPath: string;
+    /** The query every player address carries, in this order. */
+    playerQuery?: readonly VideoEmbedPlayerParam[];
+}
+/** A declaration, with the plugin that made it. */
+export interface ResolvedVideoEmbedProvider extends VideoEmbedProviderDeclaration {
+    pluginId: string;
+}
+/** A link a declared host recognized. */
+export interface VideoEmbed {
+    provider: ResolvedVideoEmbedProvider;
+    /** The media id the link named, and nothing else of it. */
+    mediaId: string;
+    /**
+     * The player page with no per-visit options — what a `VideoObject`
+     * publishes as `embedUrl`.
+     */
+    embedUrl: string;
+}
+/** Every host a first-party plugin declares. */
+export declare function videoEmbedProviders(): readonly ResolvedVideoEmbedProvider[];
+/**
+ * The declared host a link belongs to, with the media id it names, or
+ * `undefined` for anything else: a value that is not an http(s) URL, a host
+ * nothing declares, or a path that names no id the host's pattern accepts.
+ */
+export declare function videoEmbedOf(value: unknown, providers?: readonly ResolvedVideoEmbedProvider[]): VideoEmbed | undefined;
+/** The player page for a declared host's link, with no per-visit options. */
+export declare function videoEmbedUrl(value: unknown, providers?: readonly ResolvedVideoEmbedProvider[]): string | undefined;
+/**
+ * The address of a declared host's player frame for this visit, carrying the
+ * declaration's query in its own order. See {@link VideoEmbedPlayerOption}
+ * for what each option means and which way it defaults.
+ */
+export declare function videoEmbedPlayerSrc(value: unknown, options?: VideoEmbedPlayerOptions, providers?: readonly ResolvedVideoEmbedProvider[]): string | undefined;
+/**
+ * Every origin a declared player is framed from: what a published page's
+ * `frame-src` admits for the Video element.
+ */
+export declare function videoEmbedPlayerOrigins(providers?: readonly ResolvedVideoEmbedProvider[]): string[];
+/** The declared hosts' names, as an author knows them. */
+export declare function videoEmbedProviderLabels(providers?: readonly ResolvedVideoEmbedProvider[]): string[];

package/src/lib/plugin-manager/video-embed-provider.js

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * A VIDEO HOST WHOSE OWN PLAYER A VIDEO PLAYS IN (AGL-3080).
+ *
+ * Some video hosts hand an author a link to a page, not to a file: the film
+ * plays only inside the host's player, framed from the host's origin. The
+ * Video element recognizes such a link, keeps only the media id it names,
+ * and frames the host's player for it. Core never names a host. A plugin
+ * DECLARES one — the domains its links live on, where in the path the media
+ * id sits, the one origin its player is framed from, and the query that
+ * player reads — and core's resolvers answer from the declarations alone.
+ *
+ * This sits beside `media-delivery-provider.ts` and is not that seam. A
+ * delivery provider is where the platform serves ITS OWN copy of a file
+ * from; an embed provider is a host whose player the author chose, which the
+ * platform never serves a byte of.
+ *
+ * ## Only the media id survives
+ *
+ * The string an author pasted never reaches a frame. {@link videoEmbedOf}
+ * reads the media id out of it, and every address below is rebuilt from the
+ * declaration and that id alone, so a declared player is framed from its
+ * declared origin and nowhere else. That closed set is what lets a published
+ * page's `frame-src` name the origin for every site
+ * ({@link videoEmbedPlayerOrigins}). The id must match the declaration's own
+ * pattern AND {@link SAFE_MEDIA_ID}, so no declaration can widen the path it
+ * is put into.
+ *
+ * ## Compiled, and deliberately without a runtime registrar
+ *
+ * The readers are the published page and its policy: the Video element that
+ * plays the link, the `VideoObject` a crawler reads, the built-in entry page
+ * that decides whether a featured film can play, and the tenant middleware
+ * whose `frame-src` must admit the player. None of them loads a plugin's
+ * console code, and the middleware loads no plugin at all. A registry one of
+ * them had not filled would render a customer's link as a `<video>` pointed
+ * at an HTML page, or refuse the frame, and nothing would go red — the
+ * AGL-3025 shape, on the customer's own film. So a first-party plugin
+ * declares its hosts under `videoEmbedProviders` in `plugins.config.json`,
+ * `tools/scripts/generate-plugin-manifests.mjs` validates and compiles them,
+ * and this module reads the compiled list.
+ *
+ * A marketplace plugin cannot add a host this way, and that is the point
+ * rather than a gap: a declaration widens every published page's
+ * `frame-src`, which is a platform decision, not one a plugin's own code
+ * makes at runtime.
+ *
+ * ## What "absent" means
+ *
+ * A link no declaration recognizes is an ordinary URL, rendered exactly as
+ * any other link is. Removing a declaration therefore turns its links back
+ * into plain URLs, which play nothing — so the declaring plugin's spec holds
+ * the declaration to the links it must keep reading.
+ */ import { FIRST_PARTY_VIDEO_EMBED_PROVIDERS } from "./first-party-plugins.generated.js";
+export const VIDEO_EMBED_PLAYER_OPTIONS = [
+    'autoPlay',
+    'doNotTrack',
+    'muted',
+    'loop'
+];
+/**
+ * The floor every media id stands on, whatever a declaration's own pattern
+ * admits: no separator, dot, query or fragment can reach the player path.
+ */ const SAFE_MEDIA_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** The placeholder a `playerPath` names the media id with. */ const ID_PLACEHOLDER = '{id}';
+/** Every host a first-party plugin declares. */ export function videoEmbedProviders() {
+    return FIRST_PARTY_VIDEO_EMBED_PROVIDERS;
+}
+const compiled = new WeakMap();
+function compile(provider) {
+    let answer = compiled.get(provider);
+    if (!answer) {
+        answer = {
+            paths: provider.mediaIdPaths.map((source)=>new RegExp(source)),
+            mediaId: new RegExp(provider.mediaIdPattern)
+        };
+        compiled.set(provider, answer);
+    }
+    return answer;
+}
+function onDomain(hostname, domains) {
+    return domains.some((domain)=>hostname === domain || hostname.endsWith(`.${domain}`));
+}
+/**
+ * The declared host a link belongs to, with the media id it names, or
+ * `undefined` for anything else: a value that is not an http(s) URL, a host
+ * nothing declares, or a path that names no id the host's pattern accepts.
+ */ export function videoEmbedOf(value, providers = videoEmbedProviders()) {
+    if (typeof value !== 'string' || !providers.length) return undefined;
+    let url;
+    try {
+        url = new URL(value.trim());
+    } catch (unused) {
+        return undefined;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined;
+    for (const provider of providers){
+        if (!onDomain(url.hostname, provider.domains)) continue;
+        const { paths, mediaId } = compile(provider);
+        for (const pattern of paths){
+            var _pattern_exec;
+            const id = (_pattern_exec = pattern.exec(url.pathname)) == null ? void 0 : _pattern_exec[1];
+            if (id && mediaId.test(id) && SAFE_MEDIA_ID.test(id)) {
+                return {
+                    provider,
+                    mediaId: id,
+                    embedUrl: `${provider.playerOrigin}${provider.playerPath.replace(ID_PLACEHOLDER, id)}`
+                };
+            }
+        }
+    }
+    return undefined;
+}
+/** The player page for a declared host's link, with no per-visit options. */ export function videoEmbedUrl(value, providers) {
+    var _videoEmbedOf;
+    return (_videoEmbedOf = videoEmbedOf(value, providers)) == null ? void 0 : _videoEmbedOf.embedUrl;
+}
+/**
+ * The address of a declared host's player frame for this visit, carrying the
+ * declaration's query in its own order. See {@link VideoEmbedPlayerOption}
+ * for what each option means and which way it defaults.
+ */ export function videoEmbedPlayerSrc(value, options = {}, providers) {
+    var _embed_provider_playerQuery;
+    const embed = videoEmbedOf(value, providers);
+    if (!embed) return undefined;
+    const params = new URLSearchParams();
+    for (const entry of (_embed_provider_playerQuery = embed.provider.playerQuery) != null ? _embed_provider_playerQuery : []){
+        if ('value' in entry) {
+            params.set(entry.param, entry.value);
+            continue;
+        }
+        const on = entry.option === 'autoPlay' ? options.autoPlay !== false : Boolean(options[entry.option]);
+        const sent = on ? entry.on : entry.off;
+        if (sent !== undefined) params.set(entry.param, sent);
+    }
+    const query = params.toString();
+    return query ? `${embed.embedUrl}?${query}` : embed.embedUrl;
+}
+/**
+ * Every origin a declared player is framed from: what a published page's
+ * `frame-src` admits for the Video element.
+ */ export function videoEmbedPlayerOrigins(providers = videoEmbedProviders()) {
+    return [
+        ...new Set(providers.map((provider)=>provider.playerOrigin))
+    ];
+}
+/** The declared hosts' names, as an author knows them. */ export function videoEmbedProviderLabels(providers = videoEmbedProviders()) {
+    return providers.map((provider)=>provider.label);
+}
+
+//# sourceMappingURL=video-embed-provider.js.map

package/src/lib/plugin-manager/video-embed-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/video-embed-provider.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A VIDEO HOST WHOSE OWN PLAYER A VIDEO PLAYS IN (AGL-3080).\n *\n * Some video hosts hand an author a link to a page, not to a file: the film\n * plays only inside the host's player, framed from the host's origin. The\n * Video element recognizes such a link, keeps only the media id it names,\n * and frames the host's player for it. Core never names a host. A plugin\n * DECLARES one — the domains its links live on, where in the path the media\n * id sits, the one origin its player is framed from, and the query that\n * player reads — and core's resolvers answer from the declarations alone.\n *\n * This sits beside `media-delivery-provider.ts` and is not that seam. A\n * delivery provider is where the platform serves ITS OWN copy of a file\n * from; an embed provider is a host whose player the author chose, which the\n * platform never serves a byte of.\n *\n * ## Only the media id survives\n *\n * The string an author pasted never reaches a frame. {@link videoEmbedOf}\n * reads the media id out of it, and every address below is rebuilt from the\n * declaration and that id alone, so a declared player is framed from its\n * declared origin and nowhere else. That closed set is what lets a published\n * page's `frame-src` name the origin for every site\n * ({@link videoEmbedPlayerOrigins}). The id must match the declaration's own\n * pattern AND {@link SAFE_MEDIA_ID}, so no declaration can widen the path it\n * is put into.\n *\n * ## Compiled, and deliberately without a runtime registrar\n *\n * The readers are the published page and its policy: the Video element that\n * plays the link, the `VideoObject` a crawler reads, the built-in entry page\n * that decides whether a featured film can play, and the tenant middleware\n * whose `frame-src` must admit the player. None of them loads a plugin's\n * console code, and the middleware loads no plugin at all. A registry one of\n * them had not filled would render a customer's link as a `<video>` pointed\n * at an HTML page, or refuse the frame, and nothing would go red — the\n * AGL-3025 shape, on the customer's own film. So a first-party plugin\n * declares its hosts under `videoEmbedProviders` in `plugins.config.json`,\n * `tools/scripts/generate-plugin-manifests.mjs` validates and compiles them,\n * and this module reads the compiled list.\n *\n * A marketplace plugin cannot add a host this way, and that is the point\n * rather than a gap: a declaration widens every published page's\n * `frame-src`, which is a platform decision, not one a plugin's own code\n * makes at runtime.\n *\n * ## What \"absent\" means\n *\n * A link no declaration recognizes is an ordinary URL, rendered exactly as\n * any other link is. Removing a declaration therefore turns its links back\n * into plain URLs, which play nothing — so the declaring plugin's spec holds\n * the declaration to the links it must keep reading.\n */\n\nimport { FIRST_PARTY_VIDEO_EMBED_PROVIDERS } from './first-party-plugins.generated'\n\n/**\n * A choice the Video element makes for each player it frames. A declaration\n * says how its player spells each one it supports; one it does not name is\n * never sent.\n *\n *  - `autoPlay` — start as soon as the player is ready. ON unless the caller\n *    passes exactly `false`: the usual frame is the one a visitor's press\n *    loads, and a second play button inside it would ask them twice.\n *  - `doNotTrack` — ask the host not to record the viewing session.\n *  - `muted` — start without sound.\n *  - `loop` — restart at the end.\n */\nexport type VideoEmbedPlayerOption = 'autoPlay' | 'doNotTrack' | 'muted' | 'loop'\n\nexport const VIDEO_EMBED_PLAYER_OPTIONS: readonly VideoEmbedPlayerOption[] = [\n  'autoPlay',\n  'doNotTrack',\n  'muted',\n  'loop',\n]\n\nexport type VideoEmbedPlayerOptions = Partial<\n  Record<VideoEmbedPlayerOption, boolean>\n>\n\n/**\n * One query parameter of a player address, in the order the declaration\n * lists them. Either `value`, sent on every address, or an `option` whose\n * state picks `on` or `off`; a state with no value leaves the parameter out.\n */\nexport type VideoEmbedPlayerParam =\n  | { param: string; value: string }\n  | {\n      param: string\n      option: VideoEmbedPlayerOption\n      on?: string\n      off?: string\n    }\n\nexport interface VideoEmbedProviderDeclaration {\n  /** Stable id, unique across plugins. */\n  id: string\n  /** The host's name as an author knows it, for labels and help text. */\n  label: string\n  /**\n   * The domains a link's host must equal or end in (after a dot). Exact or\n   * dot-anchored only, so a domain that merely contains one is refused.\n   */\n  domains: readonly string[]\n  /**\n   * Regular expressions over a link's PATH, anchored at both ends, whose\n   * first capture group is the media id. The host is checked separately,\n   * against {@link domains}.\n   */\n  mediaIdPaths: readonly string[]\n  /** A regular expression, anchored at both ends, a media id must match. */\n  mediaIdPattern: string\n  /** The one origin the host's player is framed from. */\n  playerOrigin: string\n  /** The player page's path on {@link playerOrigin}; `{id}` is the media id. */\n  playerPath: string\n  /** The query every player address carries, in this order. */\n  playerQuery?: readonly VideoEmbedPlayerParam[]\n}\n\n/** A declaration, with the plugin that made it. */\nexport interface ResolvedVideoEmbedProvider\n  extends VideoEmbedProviderDeclaration {\n  pluginId: string\n}\n\n/** A link a declared host recognized. */\nexport interface VideoEmbed {\n  provider: ResolvedVideoEmbedProvider\n  /** The media id the link named, and nothing else of it. */\n  mediaId: string\n  /**\n   * The player page with no per-visit options — what a `VideoObject`\n   * publishes as `embedUrl`.\n   */\n  embedUrl: string\n}\n\n/**\n * The floor every media id stands on, whatever a declaration's own pattern\n * admits: no separator, dot, query or fragment can reach the player path.\n */\nconst SAFE_MEDIA_ID = /^[A-Za-z0-9_-]{1,64}$/\n\n/** The placeholder a `playerPath` names the media id with. */\nconst ID_PLACEHOLDER = '{id}'\n\n/** Every host a first-party plugin declares. */\nexport function videoEmbedProviders(): readonly ResolvedVideoEmbedProvider[] {\n  return FIRST_PARTY_VIDEO_EMBED_PROVIDERS\n}\n\ninterface CompiledProvider {\n  paths: RegExp[]\n  mediaId: RegExp\n}\n\nconst compiled = new WeakMap<VideoEmbedProviderDeclaration, CompiledProvider>()\n\nfunction compile(provider: VideoEmbedProviderDeclaration): CompiledProvider {\n  let answer = compiled.get(provider)\n  if (!answer) {\n    answer = {\n      paths: provider.mediaIdPaths.map((source) => new RegExp(source)),\n      mediaId: new RegExp(provider.mediaIdPattern),\n    }\n    compiled.set(provider, answer)\n  }\n  return answer\n}\n\nfunction onDomain(hostname: string, domains: readonly string[]): boolean {\n  return domains.some(\n    (domain) => hostname === domain || hostname.endsWith(`.${domain}`),\n  )\n}\n\n/**\n * The declared host a link belongs to, with the media id it names, or\n * `undefined` for anything else: a value that is not an http(s) URL, a host\n * nothing declares, or a path that names no id the host's pattern accepts.\n */\nexport function videoEmbedOf(\n  value: unknown,\n  providers: readonly ResolvedVideoEmbedProvider[] = videoEmbedProviders(),\n): VideoEmbed | undefined {\n  if (typeof value !== 'string' || !providers.length) return undefined\n  let url: URL\n  try {\n    url = new URL(value.trim())\n  } catch {\n    return undefined\n  }\n  if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined\n  for (const provider of providers) {\n    if (!onDomain(url.hostname, provider.domains)) continue\n    const { paths, mediaId } = compile(provider)\n    for (const pattern of paths) {\n      const id = pattern.exec(url.pathname)?.[1]\n      if (id && mediaId.test(id) && SAFE_MEDIA_ID.test(id)) {\n        return {\n          provider,\n          mediaId: id,\n          embedUrl: `${provider.playerOrigin}${provider.playerPath.replace(ID_PLACEHOLDER, id)}`,\n        }\n      }\n    }\n  }\n  return undefined\n}\n\n/** The player page for a declared host's link, with no per-visit options. */\nexport function videoEmbedUrl(\n  value: unknown,\n  providers?: readonly ResolvedVideoEmbedProvider[],\n): string | undefined {\n  return videoEmbedOf(value, providers)?.embedUrl\n}\n\n/**\n * The address of a declared host's player frame for this visit, carrying the\n * declaration's query in its own order. See {@link VideoEmbedPlayerOption}\n * for what each option means and which way it defaults.\n */\nexport function videoEmbedPlayerSrc(\n  value: unknown,\n  options: VideoEmbedPlayerOptions = {},\n  providers?: readonly ResolvedVideoEmbedProvider[],\n): string | undefined {\n  const embed = videoEmbedOf(value, providers)\n  if (!embed) return undefined\n  const params = new URLSearchParams()\n  for (const entry of embed.provider.playerQuery ?? []) {\n    if ('value' in entry) {\n      params.set(entry.param, entry.value)\n      continue\n    }\n    const on =\n      entry.option === 'autoPlay'\n        ? options.autoPlay !== false\n        : Boolean(options[entry.option])\n    const sent = on ? entry.on : entry.off\n    if (sent !== undefined) params.set(entry.param, sent)\n  }\n  const query = params.toString()\n  return query ? `${embed.embedUrl}?${query}` : embed.embedUrl\n}\n\n/**\n * Every origin a declared player is framed from: what a published page's\n * `frame-src` admits for the Video element.\n */\nexport function videoEmbedPlayerOrigins(\n  providers: readonly ResolvedVideoEmbedProvider[] = videoEmbedProviders(),\n): string[] {\n  return [...new Set(providers.map((provider) => provider.playerOrigin))]\n}\n\n/** The declared hosts' names, as an author knows them. */\nexport function videoEmbedProviderLabels(\n  providers: readonly ResolvedVideoEmbedProvider[] = videoEmbedProviders(),\n): string[] {\n  return providers.map((provider) => provider.label)\n}\n"],"names":["FIRST_PARTY_VIDEO_EMBED_PROVIDERS","VIDEO_EMBED_PLAYER_OPTIONS","SAFE_MEDIA_ID","ID_PLACEHOLDER","videoEmbedProviders","compiled","WeakMap","compile","provider","answer","get","paths","mediaIdPaths","map","source","RegExp","mediaId","mediaIdPattern","set","onDomain","hostname","domains","some","domain","endsWith","videoEmbedOf","value","providers","length","undefined","url","URL","trim","protocol","pattern","id","exec","pathname","test","embedUrl","playerOrigin","playerPath","replace","videoEmbedUrl","videoEmbedPlayerSrc","options","embed","params","URLSearchParams","entry","playerQuery","param","on","option","autoPlay","Boolean","sent","off","query","toString","videoEmbedPlayerOrigins","Set","videoEmbedProviderLabels","label"],"mappings":"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"}

package/src/lib/types/nodes.d.ts

@@ -363,8 +363,8 @@ export interface NodeSchema<P = JSX.AnyProps> extends NodeI<P> {
      *
      * ## Shape
      *
-     * Deliberately the same `HostAction` the automations engine already takes,
-     * so nothing about the runtime changes: the selector is stamped from this
+     * Deliberately the same `SiteInteraction` a site-wide interaction is, so
+     * nothing about the runtime changes: the selector is stamped from this
      * node's own id when the page is composed, and the compiled result is the
      * shape the client engine has always consumed. `trigger.selector` is
      * therefore ignored here — the node IS the selector.