@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/plugin-manager/submission-record-target.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @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.
+ */
+/**
+ * WHERE A FORM'S SUBMISSION IS ALSO SAVED AS A RECORD (AGL-3080).
+ *
+ * A form on a published page can file every submission as a record another
+ * plugin keeps — a row in a dataset, today. The form is one plugin's element
+ * and the record is another plugin's storage, so neither may know the other:
+ * this is the contract between them, and core names neither the target nor
+ * where it keeps anything.
+ *
+ * It has two halves, because the decision of where a record lands must be
+ * made where the visitor cannot reach it:
+ *
+ * 1. {@link stampFormRecordTargets} — the page's composition hands the target
+ *    the tree it is about to ship, and the target stamps each form it will
+ *    write for with whatever it needs to trust at submit time (a signed
+ *    binding). The submit route is public and unauthenticated, so nothing
+ *    the body says on its own may choose a destination.
+ * 2. {@link writeFormRecordTarget} — the submit route hands the target the
+ *    submission as posted, after the submission itself is stored. The target
+ *    reads back what it stamped, writes the record or refuses it, and answers
+ *    what to note on the submission (`routing`) so the Inbox can say where it
+ *    went or why it did not.
+ *
+ * ## Declared, then registered — and an absent target is loud
+ *
+ * The target registers from its plugin's `serverDeclarations` entry, which
+ * every app runs at boot, and also DECLARES itself in `plugins.config.json`
+ * (`formRecordTarget`), compiled into core. A registry alone would read a
+ * failed boot as "no form writes anywhere", and every bound form would keep
+ * accepting submissions while its records quietly stopped — the AGL-3025
+ * shape. With the declaration the three cases are distinct:
+ *
+ * - nothing declared — this deployment ships no plugin that keeps records; no
+ *   form is stamped and no submission writes one, which is a real answer;
+ * - declared and registered — the target answers;
+ * - declared and NOT registered — the app's declarations step runs again. If
+ *   the target is still missing, a page carrying a form THROWS at render (the
+ *   cache keeps the last good page, and the logs are red), and a submission
+ *   is kept — the Inbox copy is written before this is asked — with the
+ *   failure logged and noted on it under `routing.recordTargetUnavailable`.
+ *
+ * Server-only, and reached by path, never through a barrel.
+ */
+/** One submission, as the route stored it. */
+export interface FormRecordWriteRequest {
+    /** The site the form was submitted on. */
+    hostId: string;
+    /** The organization that owns the site, when it has one. */
+    orgId: string | null;
+    /** The organization's billing document — the entitlements a write is held to. */
+    orgBilling: unknown;
+    /**
+     * The request body as posted. The target reads back only what it stamped
+     * onto the form, and must trust nothing else in it.
+     */
+    body: Readonly<Record<string, unknown>>;
+    /** The submitted values, sanitized, keyed by the name each field submits under. */
+    fields: Readonly<Record<string, string>>;
+}
+/** What a target answers for one submission. */
+export interface FormRecordWriteOutcome {
+    /**
+     * Written as the stored submission's `routing` when present: where the
+     * record went, or why it was refused. Absent when the form writes nowhere.
+     */
+    routing?: Record<string, unknown>;
+}
+/** A plugin that keeps the records forms may file into. */
+export interface FormRecordTarget {
+    /**
+     * Stamps each form in a composed tree this target will write for. Never
+     * mutates `nodes`, and answers the same object when it stamps nothing.
+     */
+    stamp<N extends Record<string, unknown>>(nodes: N, hostId: string): Promise<N>;
+    /**
+     * Writes one submission's record, or refuses it. Never rejects: a record
+     * that cannot be written is no reason to fail a submission already stored.
+     */
+    write(request: FormRecordWriteRequest): Promise<FormRecordWriteOutcome>;
+}
+/** The compiled declaration: which plugin keeps the records forms file into. */
+export interface FormRecordTargetDeclaration {
+    pluginId: string;
+    id: string;
+}
+/** The plugin declared as the forms' record target, or `null` when none is. */
+export declare function declaredFormRecordTarget(): FormRecordTargetDeclaration | null;
+interface RegisteredTarget {
+    pluginId: string;
+    target: FormRecordTarget;
+}
+/**
+ * Registers the target. The owner is the plugin whose register fn is running,
+ * or the `pluginId` passed for a boot declaration; with neither, or from a
+ * plugin other than the one declared, it throws. The same plugin registering
+ * again replaces its target. Returns the unregister.
+ */
+export declare function registerFormRecordTarget(target: FormRecordTarget, options?: {
+    pluginId?: string;
+}): () => void;
+/** The registered target with its owner, or `null`. */
+export declare function formRecordTarget(): RegisteredTarget | null;
+/** Only for specs: forgets the registered target. */
+export declare function resetFormRecordTargetForTests(): void;
+/**
+ * The declared target's registration was not found, even after the app's
+ * declarations step ran again.
+ */
+export declare class FormRecordTargetUnavailableError extends Error {
+    readonly declared: FormRecordTargetDeclaration;
+    constructor(declared: FormRecordTargetDeclaration);
+}
+/**
+ * The tree a page ships, with each form the target writes for stamped.
+ *
+ * A tree with no form asks nobody and comes back as the same object. A tree
+ * with one THROWS when the declared target is missing — see the module note.
+ */
+export declare function stampFormRecordTargets<N extends Record<string, unknown>>(nodes: N, hostId: string): Promise<N>;
+/**
+ * Files one stored submission as a record where the page's form said to.
+ *
+ * Never rejects. With no target declared it answers nothing; with the declared
+ * target missing it logs the failure and answers a `routing` note saying so,
+ * because the submission is already kept and losing it now would be worse.
+ */
+export declare function writeFormRecordTarget(request: FormRecordWriteRequest): Promise<FormRecordWriteOutcome>;
+export {};

package/src/lib/plugin-manager/submission-record-target.js

@@ -0,0 +1,125 @@
+/**
+ * @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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { FORM_COMPONENT_ID } from "../app-utils/forms.js";
+import { PLUGIN_FORM_RECORD_TARGET_DECLARED } from "./first-party-plugins.generated.js";
+import { runPluginDeclarationsRepair } from "./plugin-declarations-repair.js";
+/** The plugin declared as the forms' record target, or `null` when none is. */ export function declaredFormRecordTarget() {
+    return PLUGIN_FORM_RECORD_TARGET_DECLARED;
+}
+/**
+ * One slot per process, on `globalThis` (AGL-3412): the app registers from
+ * `instrumentation.ts`, which Next compiles apart from the routes that read.
+ */ const TARGET_KEY = Symbol.for('@aglyn/aglyn:submission-record-target');
+const globalScope = globalThis;
+/**
+ * Registers the target. The owner is the plugin whose register fn is running,
+ * or the `pluginId` passed for a boot declaration; with neither, or from a
+ * plugin other than the one declared, it throws. The same plugin registering
+ * again replaces its target. Returns the unregister.
+ */ export function registerFormRecordTarget(target, options) {
+    var _ref, _getRegisteringPluginId;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error('the form record target was registered with no owner: pass ' + '{ pluginId } when registering outside a plugin register fn');
+    }
+    const declared = declaredFormRecordTarget();
+    if (declared && declared.pluginId !== pluginId) {
+        throw new Error(`the form record target is declared by "${declared.pluginId}"; ` + `refused "${pluginId}"`);
+    }
+    const held = globalScope[TARGET_KEY];
+    if (held && held.pluginId !== pluginId) {
+        throw new Error(`the form record target is already registered by "${held.pluginId}"; ` + `refused "${pluginId}"`);
+    }
+    const entry = {
+        pluginId,
+        target
+    };
+    globalScope[TARGET_KEY] = entry;
+    return ()=>{
+        if (globalScope[TARGET_KEY] === entry) globalScope[TARGET_KEY] = null;
+    };
+}
+/** The registered target with its owner, or `null`. */ export function formRecordTarget() {
+    var _globalScope_TARGET_KEY;
+    return (_globalScope_TARGET_KEY = globalScope[TARGET_KEY]) != null ? _globalScope_TARGET_KEY : null;
+}
+/** Only for specs: forgets the registered target. */ export function resetFormRecordTargetForTests() {
+    globalScope[TARGET_KEY] = null;
+}
+/**
+ * The declared target's registration was not found, even after the app's
+ * declarations step ran again.
+ */ export class FormRecordTargetUnavailableError extends Error {
+    constructor(declared){
+        super(`the form record target is declared by "${declared.pluginId}" but none ` + 'is registered in this process — its server declarations did not run. ' + 'Refusing to treat bound forms as writing nowhere.'), this.declared = declared;
+        this.name = 'FormRecordTargetUnavailableError';
+    }
+}
+/** The declared target, repaired once if missing; `null` when none is declared. */ async function requireDeclaredTarget() {
+    const declared = declaredFormRecordTarget();
+    if (!declared) return null;
+    let registered = formRecordTarget();
+    if (!registered) {
+        try {
+            await runPluginDeclarationsRepair();
+        } catch (error) {
+            console.error('[submission-record-target] the declarations repair failed', error);
+        }
+        registered = formRecordTarget();
+    }
+    if (!registered) throw new FormRecordTargetUnavailableError(declared);
+    return registered.target;
+}
+const placesAForm = (nodes)=>Object.values(nodes).some((node)=>(node == null ? void 0 : node.componentId) === FORM_COMPONENT_ID);
+/**
+ * The tree a page ships, with each form the target writes for stamped.
+ *
+ * A tree with no form asks nobody and comes back as the same object. A tree
+ * with one THROWS when the declared target is missing — see the module note.
+ */ export async function stampFormRecordTargets(nodes, hostId) {
+    if (!placesAForm(nodes)) return nodes;
+    const target = await requireDeclaredTarget();
+    return target ? target.stamp(nodes, hostId) : nodes;
+}
+/**
+ * Files one stored submission as a record where the page's form said to.
+ *
+ * Never rejects. With no target declared it answers nothing; with the declared
+ * target missing it logs the failure and answers a `routing` note saying so,
+ * because the submission is already kept and losing it now would be worse.
+ */ export async function writeFormRecordTarget(request) {
+    let target;
+    try {
+        target = await requireDeclaredTarget();
+    } catch (error) {
+        console.error('[submission-record-target] a submission could not be filed', error);
+        return {
+            routing: {
+                recordTargetUnavailable: true
+            }
+        };
+    }
+    if (!target) return {};
+    try {
+        return await target.write(request);
+    } catch (error) {
+        console.error('[submission-record-target] the target failed a write', error);
+        return {};
+    }
+}
+
+//# sourceMappingURL=submission-record-target.js.map

package/src/lib/plugin-manager/submission-record-target.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/submission-record-target.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 { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport { FORM_COMPONENT_ID } from '../app-utils/forms'\nimport { PLUGIN_FORM_RECORD_TARGET_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * WHERE A FORM'S SUBMISSION IS ALSO SAVED AS A RECORD (AGL-3080).\n *\n * A form on a published page can file every submission as a record another\n * plugin keeps — a row in a dataset, today. The form is one plugin's element\n * and the record is another plugin's storage, so neither may know the other:\n * this is the contract between them, and core names neither the target nor\n * where it keeps anything.\n *\n * It has two halves, because the decision of where a record lands must be\n * made where the visitor cannot reach it:\n *\n * 1. {@link stampFormRecordTargets} — the page's composition hands the target\n *    the tree it is about to ship, and the target stamps each form it will\n *    write for with whatever it needs to trust at submit time (a signed\n *    binding). The submit route is public and unauthenticated, so nothing\n *    the body says on its own may choose a destination.\n * 2. {@link writeFormRecordTarget} — the submit route hands the target the\n *    submission as posted, after the submission itself is stored. The target\n *    reads back what it stamped, writes the record or refuses it, and answers\n *    what to note on the submission (`routing`) so the Inbox can say where it\n *    went or why it did not.\n *\n * ## Declared, then registered — and an absent target is loud\n *\n * The target registers from its plugin's `serverDeclarations` entry, which\n * every app runs at boot, and also DECLARES itself in `plugins.config.json`\n * (`formRecordTarget`), compiled into core. A registry alone would read a\n * failed boot as \"no form writes anywhere\", and every bound form would keep\n * accepting submissions while its records quietly stopped — the AGL-3025\n * shape. With the declaration the three cases are distinct:\n *\n * - nothing declared — this deployment ships no plugin that keeps records; no\n *   form is stamped and no submission writes one, which is a real answer;\n * - declared and registered — the target answers;\n * - declared and NOT registered — the app's declarations step runs again. If\n *   the target is still missing, a page carrying a form THROWS at render (the\n *   cache keeps the last good page, and the logs are red), and a submission\n *   is kept — the Inbox copy is written before this is asked — with the\n *   failure logged and noted on it under `routing.recordTargetUnavailable`.\n *\n * Server-only, and reached by path, never through a barrel.\n */\n\n/** One submission, as the route stored it. */\nexport interface FormRecordWriteRequest {\n  /** The site the form was submitted on. */\n  hostId: string\n  /** The organization that owns the site, when it has one. */\n  orgId: string | null\n  /** The organization's billing document — the entitlements a write is held to. */\n  orgBilling: unknown\n  /**\n   * The request body as posted. The target reads back only what it stamped\n   * onto the form, and must trust nothing else in it.\n   */\n  body: Readonly<Record<string, unknown>>\n  /** The submitted values, sanitized, keyed by the name each field submits under. */\n  fields: Readonly<Record<string, string>>\n}\n\n/** What a target answers for one submission. */\nexport interface FormRecordWriteOutcome {\n  /**\n   * Written as the stored submission's `routing` when present: where the\n   * record went, or why it was refused. Absent when the form writes nowhere.\n   */\n  routing?: Record<string, unknown>\n}\n\n/** A plugin that keeps the records forms may file into. */\nexport interface FormRecordTarget {\n  /**\n   * Stamps each form in a composed tree this target will write for. Never\n   * mutates `nodes`, and answers the same object when it stamps nothing.\n   */\n  stamp<N extends Record<string, unknown>>(nodes: N, hostId: string): Promise<N>\n  /**\n   * Writes one submission's record, or refuses it. Never rejects: a record\n   * that cannot be written is no reason to fail a submission already stored.\n   */\n  write(request: FormRecordWriteRequest): Promise<FormRecordWriteOutcome>\n}\n\n/** The compiled declaration: which plugin keeps the records forms file into. */\nexport interface FormRecordTargetDeclaration {\n  pluginId: string\n  id: string\n}\n\n/** The plugin declared as the forms' record target, or `null` when none is. */\nexport function declaredFormRecordTarget(): FormRecordTargetDeclaration | null {\n  return PLUGIN_FORM_RECORD_TARGET_DECLARED\n}\n\ninterface RegisteredTarget {\n  pluginId: string\n  target: FormRecordTarget\n}\n\n/**\n * One slot per process, on `globalThis` (AGL-3412): the app registers from\n * `instrumentation.ts`, which Next compiles apart from the routes that read.\n */\nconst TARGET_KEY = Symbol.for('@aglyn/aglyn:submission-record-target')\n\nconst globalScope = globalThis as typeof globalThis & {\n  [TARGET_KEY]?: RegisteredTarget | null\n}\n\n/**\n * Registers the target. The owner is the plugin whose register fn is running,\n * or the `pluginId` passed for a boot declaration; with neither, or from a\n * plugin other than the one declared, it throws. The same plugin registering\n * again replaces its target. Returns the unregister.\n */\nexport function registerFormRecordTarget(\n  target: FormRecordTarget,\n  options?: { pluginId?: string },\n): () => void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      'the form record target was registered with no owner: pass ' +\n        '{ pluginId } when registering outside a plugin register fn',\n    )\n  }\n  const declared = declaredFormRecordTarget()\n  if (declared && declared.pluginId !== pluginId) {\n    throw new Error(\n      `the form record target is declared by \"${declared.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  const held = globalScope[TARGET_KEY]\n  if (held && held.pluginId !== pluginId) {\n    throw new Error(\n      `the form record target is already registered by \"${held.pluginId}\"; ` +\n        `refused \"${pluginId}\"`,\n    )\n  }\n  const entry: RegisteredTarget = { pluginId, target }\n  globalScope[TARGET_KEY] = entry\n  return () => {\n    if (globalScope[TARGET_KEY] === entry) globalScope[TARGET_KEY] = null\n  }\n}\n\n/** The registered target with its owner, or `null`. */\nexport function formRecordTarget(): RegisteredTarget | null {\n  return globalScope[TARGET_KEY] ?? null\n}\n\n/** Only for specs: forgets the registered target. */\nexport function resetFormRecordTargetForTests(): void {\n  globalScope[TARGET_KEY] = null\n}\n\n/**\n * The declared target's registration was not found, even after the app's\n * declarations step ran again.\n */\nexport class FormRecordTargetUnavailableError extends Error {\n  constructor(readonly declared: FormRecordTargetDeclaration) {\n    super(\n      `the form record target is declared by \"${declared.pluginId}\" but none ` +\n        'is registered in this process — its server declarations did not run. ' +\n        'Refusing to treat bound forms as writing nowhere.',\n    )\n    this.name = 'FormRecordTargetUnavailableError'\n  }\n}\n\n/** The declared target, repaired once if missing; `null` when none is declared. */\nasync function requireDeclaredTarget(): Promise<FormRecordTarget | null> {\n  const declared = declaredFormRecordTarget()\n  if (!declared) return null\n  let registered = formRecordTarget()\n  if (!registered) {\n    try {\n      await runPluginDeclarationsRepair()\n    } catch (error) {\n      console.error('[submission-record-target] the declarations repair failed', error)\n    }\n    registered = formRecordTarget()\n  }\n  if (!registered) throw new FormRecordTargetUnavailableError(declared)\n  return registered.target\n}\n\nconst placesAForm = (nodes: Record<string, unknown>): boolean =>\n  Object.values(nodes).some(\n    (node) =>\n      (node as { componentId?: unknown } | null)?.componentId === FORM_COMPONENT_ID,\n  )\n\n/**\n * The tree a page ships, with each form the target writes for stamped.\n *\n * A tree with no form asks nobody and comes back as the same object. A tree\n * with one THROWS when the declared target is missing — see the module note.\n */\nexport async function stampFormRecordTargets<N extends Record<string, unknown>>(\n  nodes: N,\n  hostId: string,\n): Promise<N> {\n  if (!placesAForm(nodes)) return nodes\n  const target = await requireDeclaredTarget()\n  return target ? target.stamp(nodes, hostId) : nodes\n}\n\n/**\n * Files one stored submission as a record where the page's form said to.\n *\n * Never rejects. With no target declared it answers nothing; with the declared\n * target missing it logs the failure and answers a `routing` note saying so,\n * because the submission is already kept and losing it now would be worse.\n */\nexport async function writeFormRecordTarget(\n  request: FormRecordWriteRequest,\n): Promise<FormRecordWriteOutcome> {\n  let target: FormRecordTarget | null\n  try {\n    target = await requireDeclaredTarget()\n  } catch (error) {\n    console.error('[submission-record-target] a submission could not be filed', error)\n    return { routing: { recordTargetUnavailable: true } }\n  }\n  if (!target) return {}\n  try {\n    return await target.write(request)\n  } catch (error) {\n    console.error('[submission-record-target] the target failed a write', error)\n    return {}\n  }\n}\n"],"names":["getRegisteringPluginId","FORM_COMPONENT_ID","PLUGIN_FORM_RECORD_TARGET_DECLARED","runPluginDeclarationsRepair","declaredFormRecordTarget","TARGET_KEY","Symbol","for","globalScope","globalThis","registerFormRecordTarget","target","options","pluginId","trim","Error","declared","held","entry","formRecordTarget","resetFormRecordTargetForTests","FormRecordTargetUnavailableError","name","requireDeclaredTarget","registered","error","console","placesAForm","nodes","Object","values","some","node","componentId","stampFormRecordTargets","hostId","stamp","writeFormRecordTarget","request","routing","recordTargetUnavailable","write"],"mappings":"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"}

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.