@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/components/paper.js

@@ -0,0 +1,202 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import * as Aglyn from "@aglyn/aglyn";
+import { mdiFileDocumentOutline } from "@aglyn/shared-data-mdi";
+import MuiPaper from "@mui/material/Paper";
+import { forwardRef } from "react";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { applySemanticElement, semanticElementAttribute, semanticElementLabelAttribute } from "../utils/element-picker.js";
+import { dropClearedProps } from "../utils/drop-cleared-props.js";
+import { generatePresetId } from "../utils/generate-preset-id.js";
+// Component ids are persisted in screen documents; never rename.
+export const ID = 'muiPaper';
+/** MUI's shadow scale tops out at 24; anything above renders unshadowed. */ export const MAX_ELEVATION = 24;
+/**
+ * Coerces a persisted elevation to the number MUI's shadow lookup needs.
+ *
+ * Number-typed attribute fields round-trip through the document as
+ * strings often enough that this can't be assumed away: `elevation="3"`
+ * indexes MUI's shadow array with a string and yields `undefined`, i.e. a
+ * paper the author gave a shadow renders completely flat.
+ */ export function toElevation(value) {
+    if (value === '' || value == null) return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) return undefined;
+    return Math.min(Math.max(Math.round(parsed), 0), MAX_ELEVATION);
+}
+/**
+ * Surface primitive (https://mui.com/material-ui/react-paper/): the
+ * themed background + shadow that Card, Accordion and Drawer are all
+ * built on, exposed on its own for panels and callouts.
+ */ const PaperElement = /*#__PURE__*/ forwardRef((rawProps, ref)=>{
+    // Cleared props dropped before anything reads them (AGL-1451): `square`
+    // and everything else in `rest` spread straight into MUI, where a `null`
+    // from the field's ✕ (AGL-1226) is a value rather than an absence.
+    const props = dropClearedProps(rawProps);
+    const { elevation, variant, children } = props, rest = _object_without_properties_loose(props, [
+        "elevation",
+        "variant",
+        "children"
+    ]);
+    const resolved = toElevation(elevation);
+    return /*#__PURE__*/ _jsx(MuiPaper, _extends({
+        ref: ref,
+        // `outlined` has no shadow; passing an elevation alongside it is
+        // silently ignored by MUI, so don't pretend otherwise.
+        variant: variant === 'outlined' ? 'outlined' : 'elevation',
+        elevation: variant === 'outlined' ? undefined : resolved
+    }, applySemanticElement(rest), {
+        children: children
+    }));
+});
+PaperElement.displayName = 'AglynPaper';
+/** Elevation only means anything on the (default) `elevation` variant. */ const ELEVATION_ONLY = {
+    when: 'variant',
+    is: 'outlined',
+    notMatch: true
+};
+export const schema = {
+    $id: ID,
+    pluginId: BUNDLE_ID,
+    displayName: 'Paper',
+    description: 'Themed surface with a shadow or an outline.',
+    category: Aglyn.ComponentCategory.SURFACE,
+    icon: {
+        path: mdiFileDocumentOutline.path,
+        sx: {
+            color: '#2196f3'
+        }
+    },
+    attributes: [
+        semanticElementAttribute('this surface'),
+        semanticElementLabelAttribute(),
+        {
+            name: 'variant',
+            label: 'Variant',
+            description: 'Elevation raises the surface with a shadow; outlined draws a ' + '1px border instead and has no shadow.',
+            component: Aglyn.FieldComponentType.SELECT,
+            // A real sentinel rather than a deletion (AGL-1451): unlike Container,
+            // "elevation" is not a second name for something else in the list —
+            // it is MUI's own variant value, the other half of a two-way choice,
+            // and the one the Elevation control below is conditioned on. It was
+            // spelled `''`, which the attributes form strips on change (AGL-1191),
+            // so picking it reverted the field on save.
+            options: [
+                {
+                    value: 'elevation',
+                    label: 'Elevation (default)'
+                },
+                {
+                    value: 'outlined',
+                    label: 'Outlined'
+                }
+            ]
+        },
+        {
+            name: 'elevation',
+            label: 'Elevation',
+            description: 'Shadow depth from 0 (flat) to 24. In dark mode MUI also lightens ' + 'the background as this rises.',
+            component: Aglyn.FieldComponentType.TEXT_FIELD,
+            type: 'number',
+            // Offering a shadow control on the outlined variant would be a
+            // control that silently does nothing.
+            condition: ELEVATION_ONLY
+        },
+        {
+            name: 'square',
+            label: 'Square corners?',
+            description: 'If true, the corners are not rounded.',
+            component: Aglyn.FieldComponentType.SWITCH
+        }
+    ]
+};
+export const presets = [
+    {
+        $id: generatePresetId(ID),
+        type: Aglyn.NodeType.PRESET,
+        displayName: 'Paper',
+        pluginId: BUNDLE_ID,
+        description: 'Raised surface for panels and callouts',
+        category: Aglyn.ComponentCategory.SURFACE,
+        icon: schema.icon,
+        data: {
+            $id: null,
+            componentId: ID,
+            pluginId: BUNDLE_ID,
+            props: {
+                elevation: 1
+            },
+            // Node-level sx (AGL-1346) — the record the Styles panel edits.
+            sx: {
+                paddingTop: 2,
+                paddingRight: 2,
+                paddingBottom: 2,
+                paddingLeft: 2
+            },
+            nodes: [
+                {
+                    $id: null,
+                    componentId: 'muiTypography',
+                    pluginId: BUNDLE_ID,
+                    props: {
+                        variant: 'body1',
+                        children: 'Paper is a themed surface. Drop anything inside it.'
+                    }
+                }
+            ]
+        }
+    },
+    {
+        $id: generatePresetId(ID, 'outlined'),
+        type: Aglyn.NodeType.PRESET,
+        displayName: 'Paper Outlined',
+        pluginId: BUNDLE_ID,
+        description: 'Flat surface with a border instead of a shadow',
+        category: Aglyn.ComponentCategory.SURFACE,
+        icon: schema.icon,
+        data: {
+            $id: null,
+            componentId: ID,
+            pluginId: BUNDLE_ID,
+            props: {
+                variant: 'outlined'
+            },
+            sx: {
+                paddingTop: 2,
+                paddingRight: 2,
+                paddingBottom: 2,
+                paddingLeft: 2
+            },
+            nodes: [
+                {
+                    $id: null,
+                    componentId: 'muiTypography',
+                    pluginId: BUNDLE_ID,
+                    props: {
+                        variant: 'body1',
+                        children: 'Outlined paper has a border and no shadow.'
+                    }
+                }
+            ]
+        }
+    }
+];
+export default PaperElement;
+
+//# sourceMappingURL=paper.js.map

package/src/lib/components/paper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/mui/src/lib/components/paper.tsx"],"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 * as Aglyn from '@aglyn/aglyn'\nimport { mdiFileDocumentOutline } from '@aglyn/shared-data-mdi'\nimport MuiPaper from '@mui/material/Paper'\nimport { forwardRef, type ReactNode } from 'react'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport {\n  applySemanticElement,\n  semanticElementAttribute,\n  semanticElementLabelAttribute,\n} from '../utils/element-picker'\nimport { dropClearedProps } from '../utils/drop-cleared-props'\nimport { generatePresetId } from '../utils/generate-preset-id'\n\n// Component ids are persisted in screen documents; never rename.\nexport const ID: Aglyn.ComponentId = 'muiPaper'\n\nexport interface PaperElementProps {\n  /** Shadow depth, 0–24. Ignored by MUI when `variant` is `outlined`. */\n  elevation?: number | string\n  variant?: 'elevation' | 'outlined'\n  /** If true, corners are not rounded. */\n  square?: boolean\n  children?: ReactNode\n}\n\n/** MUI's shadow scale tops out at 24; anything above renders unshadowed. */\nexport const MAX_ELEVATION = 24\n\n/**\n * Coerces a persisted elevation to the number MUI's shadow lookup needs.\n *\n * Number-typed attribute fields round-trip through the document as\n * strings often enough that this can't be assumed away: `elevation=\"3\"`\n * indexes MUI's shadow array with a string and yields `undefined`, i.e. a\n * paper the author gave a shadow renders completely flat.\n */\nexport function toElevation(value: unknown): number | undefined {\n  if (value === '' || value == null) return undefined\n  const parsed = Number(value)\n  if (!Number.isFinite(parsed)) return undefined\n  return Math.min(Math.max(Math.round(parsed), 0), MAX_ELEVATION)\n}\n\n/**\n * Surface primitive (https://mui.com/material-ui/react-paper/): the\n * themed background + shadow that Card, Accordion and Drawer are all\n * built on, exposed on its own for panels and callouts.\n */\nconst PaperElement = forwardRef<HTMLDivElement, PaperElementProps>(\n  (rawProps, ref) => {\n    // Cleared props dropped before anything reads them (AGL-1451): `square`\n    // and everything else in `rest` spread straight into MUI, where a `null`\n    // from the field's ✕ (AGL-1226) is a value rather than an absence.\n    const props = dropClearedProps(rawProps)\n    const { elevation, variant, children, ...rest } = props\n    const resolved = toElevation(elevation)\n    return (\n      <MuiPaper\n        ref={ref}\n        // `outlined` has no shadow; passing an elevation alongside it is\n        // silently ignored by MUI, so don't pretend otherwise.\n        variant={variant === 'outlined' ? 'outlined' : 'elevation'}\n        elevation={variant === 'outlined' ? undefined : resolved}\n        {...applySemanticElement(rest as Record<string, unknown>)}\n      >\n        {children}\n      </MuiPaper>\n    )\n  },\n)\nPaperElement.displayName = 'AglynPaper'\n\n/** Elevation only means anything on the (default) `elevation` variant. */\nconst ELEVATION_ONLY = { when: 'variant', is: 'outlined', notMatch: true }\n\nexport const schema: Aglyn.ComponentSchema<PaperElementProps> = {\n  $id: ID,\n  pluginId: BUNDLE_ID,\n  displayName: 'Paper',\n  description: 'Themed surface with a shadow or an outline.',\n  category: Aglyn.ComponentCategory.SURFACE,\n  icon: { path: mdiFileDocumentOutline.path, sx: { color: '#2196f3' } },\n  attributes: [\n    semanticElementAttribute('this surface'),\n    semanticElementLabelAttribute(),\n    {\n      name: 'variant',\n      label: 'Variant',\n      description:\n        'Elevation raises the surface with a shadow; outlined draws a ' +\n        '1px border instead and has no shadow.',\n      component: Aglyn.FieldComponentType.SELECT,\n      // A real sentinel rather than a deletion (AGL-1451): unlike Container,\n      // \"elevation\" is not a second name for something else in the list —\n      // it is MUI's own variant value, the other half of a two-way choice,\n      // and the one the Elevation control below is conditioned on. It was\n      // spelled `''`, which the attributes form strips on change (AGL-1191),\n      // so picking it reverted the field on save.\n      options: [\n        { value: 'elevation', label: 'Elevation (default)' },\n        { value: 'outlined', label: 'Outlined' },\n      ],\n    },\n    {\n      name: 'elevation',\n      label: 'Elevation',\n      description:\n        'Shadow depth from 0 (flat) to 24. In dark mode MUI also lightens ' +\n        'the background as this rises.',\n      component: Aglyn.FieldComponentType.TEXT_FIELD,\n      type: 'number',\n      // Offering a shadow control on the outlined variant would be a\n      // control that silently does nothing.\n      condition: ELEVATION_ONLY,\n    },\n    {\n      name: 'square',\n      label: 'Square corners?',\n      description: 'If true, the corners are not rounded.',\n      component: Aglyn.FieldComponentType.SWITCH,\n    },\n  ],\n}\n\nexport const presets: Aglyn.PresetSchema[] = [\n  {\n    $id: generatePresetId(ID),\n    type: Aglyn.NodeType.PRESET,\n    displayName: 'Paper',\n    pluginId: BUNDLE_ID,\n    description: 'Raised surface for panels and callouts',\n    category: Aglyn.ComponentCategory.SURFACE,\n    icon: schema.icon,\n    data: {\n      $id: null,\n      componentId: ID,\n      pluginId: BUNDLE_ID,\n      props: { elevation: 1 },\n      // Node-level sx (AGL-1346) — the record the Styles panel edits.\n      sx: { paddingTop: 2, paddingRight: 2, paddingBottom: 2, paddingLeft: 2 },\n      nodes: [\n        {\n          $id: null,\n          componentId: 'muiTypography',\n          pluginId: BUNDLE_ID,\n          props: {\n            variant: 'body1',\n            children: 'Paper is a themed surface. Drop anything inside it.',\n          },\n        },\n      ],\n    },\n  },\n  {\n    $id: generatePresetId(ID, 'outlined'),\n    type: Aglyn.NodeType.PRESET,\n    displayName: 'Paper Outlined',\n    pluginId: BUNDLE_ID,\n    description: 'Flat surface with a border instead of a shadow',\n    category: Aglyn.ComponentCategory.SURFACE,\n    icon: schema.icon,\n    data: {\n      $id: null,\n      componentId: ID,\n      pluginId: BUNDLE_ID,\n      props: { variant: 'outlined' },\n      sx: { paddingTop: 2, paddingRight: 2, paddingBottom: 2, paddingLeft: 2 },\n      nodes: [\n        {\n          $id: null,\n          componentId: 'muiTypography',\n          pluginId: BUNDLE_ID,\n          props: {\n            variant: 'body1',\n            children: 'Outlined paper has a border and no shadow.',\n          },\n        },\n      ],\n    },\n  },\n]\n\nexport default PaperElement\n"],"names":["Aglyn","mdiFileDocumentOutline","MuiPaper","forwardRef","BUNDLE_ID","applySemanticElement","semanticElementAttribute","semanticElementLabelAttribute","dropClearedProps","generatePresetId","ID","MAX_ELEVATION","toElevation","value","undefined","parsed","Number","isFinite","Math","min","max","round","PaperElement","rawProps","ref","props","elevation","variant","children","rest","resolved","displayName","ELEVATION_ONLY","when","is","notMatch","schema","$id","pluginId","description","category","ComponentCategory","SURFACE","icon","path","sx","color","attributes","name","label","component","FieldComponentType","SELECT","options","TEXT_FIELD","type","condition","SWITCH","presets","NodeType","PRESET","data","componentId","paddingTop","paddingRight","paddingBottom","paddingLeft","nodes"],"mappings":"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"}

package/src/lib/components/plugin-frame.d.ts

@@ -0,0 +1,64 @@
+import * as Aglyn from '@aglyn/aglyn';
+import type { SxProps } from '@mui/material/styles';
+/**
+ * Host-side sandboxed plugin runtime (AGL-45), per AGL-43 §2. Renders an
+ * installed executable plugin inside a cross-origin sandboxed iframe and
+ * talks to it only through the capability-scoped postMessage bridge — the
+ * plugin never runs in the console/tenant realm, so it has no ambient
+ * access to host Firestore, auth, storage, or the DOM. Renders a safe
+ * placeholder (never the plugin) whenever it can't run safely: no plugin
+ * origin configured, the origin isn't cross-origin to this app, or the
+ * version is revoked (kill switch).
+ *
+ * SANDBOX NOTE: `allow-scripts allow-same-origin` is correct HERE and only
+ * here because `src` is a DEDICATED cross-origin (`pluginOrigin`). For a
+ * cross-origin frame, `allow-same-origin` grants the frame ITS OWN
+ * (plugin) origin's privileges — not the parent's — so it stays walled off
+ * from the app while still being able to load its own bundle and honor the
+ * plugin-origin CSP's `connect-src`. The combination is only unsafe for a
+ * SAME-origin frame; `isCrossOrigin` below refuses that case.
+ *
+ * SERVER RENDER: the origin comparison needs `window.location.origin`, so a
+ * server render cannot make it and neither render that has to agree with the
+ * server makes it. Both emit the frame with no `src` — the plugin URL is
+ * attached on the render after mount, once the origin has actually been
+ * checked. That keeps the server HTML and the first client render identical
+ * whatever `pluginOrigin` is set to, and it keeps an unverified origin out of
+ * the markup a browser would start loading before any of this code runs.
+ */
+export interface PluginFrameProps {
+    /** Dedicated plugin origin, e.g. `https://plugins.aglyn.app`. */
+    pluginOrigin?: string;
+    /** Host id, for scoping host-mediated fetch (AGL-191). */
+    hostId?: string;
+    listingId: string;
+    /**
+     * Which DECLARED element of the plugin to render (AGL-1031).
+     *
+     * A FRAME prop, never a member of `pluginProps`: those are filtered against
+     * the manifest allowlist, so an element id routed through them would be
+     * dropped for every plugin that had not thought to declare `elementId` as a
+     * settable prop — silently, and only for declared elements. It is host
+     * metadata like `version` and `sha256`, and travels with them.
+     */
+    elementId?: string;
+    version: string;
+    sha256: string;
+    /** Manifest capabilities (event allowlist, declared size). */
+    capabilities?: Aglyn.PluginCapabilities;
+    /** Props to pass in; filtered to the manifest allowlist before sending. */
+    pluginProps?: Record<string, unknown>;
+    /** True when the pinned version is revoked (from the revocations doc). */
+    revoked?: boolean;
+    scheme?: 'light' | 'dark';
+    title?: string;
+    /**
+     * Authored node styles, handed over by the renderer rather than typed
+     * into an attribute — recomposed below so the Styles panel's values are
+     * merged rather than replaced (AGL-1284).
+     */
+    sx?: SxProps;
+}
+declare const PluginFrame: import("react").ForwardRefExoticComponent<PluginFrameProps & import("react").RefAttributes<HTMLIFrameElement>>;
+export { PluginFrame };
+export default PluginFrame;

package/src/lib/components/plugin-frame.js

@@ -0,0 +1,335 @@
+/**
+ * @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.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as Aglyn from "@aglyn/aglyn";
+import Box from "@mui/material/Box";
+import { forwardRef, useEffect, useMemo, useRef, useState } from "react";
+/**
+ * Does `pluginOrigin` resolve to an origin other than the app's own?
+ *
+ * True is the only answer that lets the frame render: the sandbox pair in
+ * the SANDBOX NOTE is containment exactly while the frame's origin differs
+ * from the page's, and is a no-op when it doesn't.
+ *
+ * Browser-only, and unavoidably so. The app's origin is
+ * `window.location.origin` and no constant stands in for it — a site answers
+ * on both its platform address and any custom domain attached to it, and the
+ * console, a preview, a self-host container and a dev server each run this
+ * under a different one. Callers ask only once mounted; the `catch` refuses
+ * an unparsable origin, and refuses a call made without a `window` for the
+ * same reason — an origin nothing compared is not an origin anything cleared.
+ */ function isCrossOrigin(pluginOrigin) {
+    try {
+        return new URL(pluginOrigin).origin !== window.location.origin;
+    } catch (unused) {
+        return false;
+    }
+}
+const Placeholder = /*#__PURE__*/ forwardRef(({ message, height }, ref)=>/*#__PURE__*/ _jsx(Box, {
+        ref: ref,
+        sx: {
+            minHeight: height != null ? height : 120,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            border: '1px dashed',
+            borderColor: 'divider',
+            borderRadius: 1,
+            color: 'text.secondary',
+            fontSize: 13,
+            fontFamily: 'system-ui, sans-serif',
+            p: 2,
+            textAlign: 'center'
+        },
+        children: message
+    }));
+Placeholder.displayName = 'PluginFramePlaceholder';
+const PluginFrame = /*#__PURE__*/ forwardRef((props, ref)=>{
+    var _ref;
+    var _capabilities_size;
+    const { pluginOrigin, hostId, listingId, elementId, version, sha256, capabilities, pluginProps, revoked, scheme, title } = props, rest = _object_without_properties_loose(props, [
+        "pluginOrigin",
+        "hostId",
+        "listingId",
+        "elementId",
+        "version",
+        "sha256",
+        "capabilities",
+        "pluginProps",
+        "revoked",
+        "scheme",
+        "title"
+    ]);
+    // Node styles ride the renderer-merged sx; recompose (stack.ts pattern).
+    const nodeSx = Array.isArray(props['sx']) ? props['sx'] : [
+        props['sx']
+    ];
+    const frameRef = useRef(null);
+    const [state, setState] = useState('loading');
+    const [height, setHeight] = useState((_ref = capabilities == null ? void 0 : (_capabilities_size = capabilities.size) == null ? void 0 : _capabilities_size.height) != null ? _ref : 120);
+    /**
+     * Whether this render is running in a browser, where `isCrossOrigin` can
+     * be answered.
+     *
+     * Every other input here is a prop or a build-time env and so reads the
+     * same on both sides; the origin comparison is the one that doesn't, and
+     * a render that branches on it disagrees with the server for any
+     * `pluginOrigin` that is same-origin to the app. Deferring it to the
+     * render after mount costs nothing visible: the frame is hidden until the
+     * guest posts `ready`, and the listener that hears `ready` is registered
+     * in an effect, so no plugin has ever painted before this point either.
+     */ const [mounted, setMounted] = useState(false);
+    useEffect(()=>setMounted(true), []);
+    const allowedEvents = capabilities == null ? void 0 : capabilities.events;
+    const allowedProps = capabilities == null ? void 0 : capabilities.props;
+    const filteredProps = useMemo(()=>Aglyn.filterPluginProps(pluginProps, allowedProps), [
+        pluginProps,
+        allowedProps
+    ]);
+    // Stable dependency for the props-update effect.
+    const filteredPropsKey = useMemo(()=>JSON.stringify(filteredProps), [
+        filteredProps
+    ]);
+    /**
+     * Three answers, not two: `null` while the check is still unanswerable,
+     * `false` once the browser has refused the origin. Collapsing them would
+     * put the refusal placeholder in the server HTML of every correctly
+     * configured site, which is the same mismatch pointing the other way.
+     */ const crossOrigin = mounted && pluginOrigin ? isCrossOrigin(pluginOrigin) : null;
+    const originUsable = !revoked && crossOrigin === true;
+    // Undefined, never `''`: an empty `src` is still an `src`, and the frame
+    // must carry no address at all until the origin behind it has cleared.
+    const src = useMemo(()=>{
+        if (!originUsable) return undefined;
+        const url = new URL('/load', String(pluginOrigin));
+        url.searchParams.set('listing', listingId);
+        url.searchParams.set('v', version);
+        url.searchParams.set('sha', sha256);
+        if (elementId) url.searchParams.set('element', elementId);
+        // The framing host (AGL-884): the origin resolves this to the site's
+        // VERIFIED custom domain and widens frame-ancestors to exactly that —
+        // never to caller-supplied origins.
+        if (hostId) url.searchParams.set('host', hostId);
+        return url.toString();
+    }, [
+        originUsable,
+        pluginOrigin,
+        hostId,
+        listingId,
+        elementId,
+        version,
+        sha256
+    ]);
+    // Bridge: validate every inbound message by origin + source + schema,
+    // then honor resize / surface events / flag errors. Never eval or graft
+    // anything from the frame — only sized output and named events.
+    useEffect(()=>{
+        if (!originUsable) return;
+        const expectedOrigin = new URL(String(pluginOrigin)).origin;
+        const handleMessage = (event)=>{
+            var _frameRef_current;
+            if (event.origin !== expectedOrigin) return;
+            if (event.source !== ((_frameRef_current = frameRef.current) == null ? void 0 : _frameRef_current.contentWindow)) return;
+            const message = Aglyn.parseGuestMessage(event.data, allowedEvents);
+            if (!message) return;
+            switch(message.type){
+                case 'ready':
+                    var _frameRef_current_contentWindow, _frameRef_current1;
+                    setState('ready');
+                    (_frameRef_current1 = frameRef.current) == null ? void 0 : (_frameRef_current_contentWindow = _frameRef_current1.contentWindow) == null ? void 0 : _frameRef_current_contentWindow.postMessage(_extends({
+                        type: 'init',
+                        v: Aglyn.PLUGIN_BRIDGE_VERSION,
+                        props: filteredProps
+                    }, scheme ? {
+                        scheme
+                    } : {}), expectedOrigin);
+                    break;
+                case 'resize':
+                    setHeight(Math.max(24, message.height));
+                    break;
+                case 'event':
+                    var _Aglyn_emitter_emit, _Aglyn_emitter;
+                    (_Aglyn_emitter = Aglyn.emitter) == null ? void 0 : (_Aglyn_emitter_emit = _Aglyn_emitter.emit) == null ? void 0 : _Aglyn_emitter_emit.call(_Aglyn_emitter, `plugin:${listingId}:${message.name}`, {
+                        listingId,
+                        name: message.name,
+                        payload: message.payload
+                    });
+                    break;
+                case 'fetch-request':
+                    {
+                        // Host-mediated fetch (AGL-191): proxy through the host API,
+                        // which re-checks the manifest allowlist server-side. Reply on
+                        // the same id; a disallowed/failed call resolves ok:false.
+                        const requestId = message.id;
+                        const respond = (payload)=>{
+                            var _frameRef_current_contentWindow, _frameRef_current;
+                            return (_frameRef_current = frameRef.current) == null ? void 0 : (_frameRef_current_contentWindow = _frameRef_current.contentWindow) == null ? void 0 : _frameRef_current_contentWindow.postMessage(_extends({
+                                type: 'fetch-response',
+                                v: Aglyn.PLUGIN_BRIDGE_VERSION,
+                                id: requestId
+                            }, payload), expectedOrigin);
+                        };
+                        if (!hostId) {
+                            respond({
+                                ok: false,
+                                status: 0,
+                                error: 'No host context'
+                            });
+                            break;
+                        }
+                        void fetch('/api/plugins/fetch', {
+                            method: 'POST',
+                            headers: {
+                                'Content-Type': 'application/json'
+                            },
+                            body: JSON.stringify({
+                                hostId,
+                                listingId,
+                                url: message.url,
+                                method: message.method,
+                                body: message.body
+                            })
+                        }).then((response)=>response.json()).then((payload)=>{
+                            var _ref;
+                            return respond({
+                                ok: Boolean(payload == null ? void 0 : payload.ok),
+                                status: Number((_ref = payload == null ? void 0 : payload.status) != null ? _ref : 0),
+                                body: payload == null ? void 0 : payload.body,
+                                error: payload == null ? void 0 : payload.error
+                            });
+                        }).catch(()=>respond({
+                                ok: false,
+                                status: 0,
+                                error: 'Fetch failed'
+                            }));
+                        break;
+                    }
+                case 'error':
+                    setState('error');
+                    break;
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        return ()=>window.removeEventListener('message', handleMessage);
+    // filteredProps is re-sent by the effect below; init uses the latest.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        originUsable,
+        pluginOrigin,
+        hostId,
+        listingId,
+        allowedEvents,
+        scheme,
+        src
+    ]);
+    // Push prop updates to an already-ready frame.
+    useEffect(()=>{
+        var _frameRef_current_contentWindow, _frameRef_current;
+        if (state !== 'ready' || !originUsable) return;
+        const expectedOrigin = new URL(String(pluginOrigin)).origin;
+        (_frameRef_current = frameRef.current) == null ? void 0 : (_frameRef_current_contentWindow = _frameRef_current.contentWindow) == null ? void 0 : _frameRef_current_contentWindow.postMessage({
+            type: 'props',
+            v: Aglyn.PLUGIN_BRIDGE_VERSION,
+            props: filteredProps
+        }, expectedOrigin);
+    // filteredPropsKey captures the serialized props identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        filteredPropsKey,
+        state,
+        originUsable,
+        pluginOrigin
+    ]);
+    if (revoked) {
+        return /*#__PURE__*/ _jsx(Placeholder, {
+            message: "This plugin has been disabled by the platform."
+        });
+    }
+    if (!pluginOrigin) {
+        return /*#__PURE__*/ _jsx(Placeholder, {
+            message: "Plugins are not enabled on this deployment."
+        });
+    }
+    // A refusal the browser actually made. `null` — not yet checked — falls
+    // through to the frame below, which carries no `src` until it clears.
+    if (crossOrigin === false) {
+        return /*#__PURE__*/ _jsx(Placeholder, {
+            message: "Plugin cannot be loaded safely here."
+        });
+    }
+    return /*#__PURE__*/ _jsx(Box, {
+        sx: {
+            position: 'relative',
+            width: '100%'
+        },
+        children: state === 'error' ? /*#__PURE__*/ _jsx(Placeholder, {
+            message: "This plugin failed to load.",
+            height: height
+        }) : /*#__PURE__*/ _jsx(Box, _extends({
+            component: "iframe",
+            ref: (node)=>{
+                frameRef.current = node;
+                if (typeof ref === 'function') ref(node);
+                else if (ref) ref.current = node;
+            },
+            src: src,
+            title: title != null ? title : 'Plugin',
+            loading: "lazy",
+            onError: ()=>setState('error')
+        }, rest, {
+            // AFTER the spread, deliberately (AGL-2484). See SANDBOX NOTE —
+            // this pair is safe only because `src` is a dedicated
+            // cross-origin, and JSX resolves a duplicate attribute by taking
+            // the LAST one, so listing them before `{...rest}` made the
+            // frame's only containment overridable by whatever a caller
+            // happened to spread in. No caller passes either today and
+            // `PluginFrameProps` declares neither; the props here do arrive
+            // from renderers that forward author-controlled bags, which is
+            // how "no caller does this" stops being true.
+            sandbox: "allow-scripts allow-same-origin",
+            referrerPolicy: "no-referrer",
+            // MERGE, never replace (AGL-1284). The spread in the old literal
+            // LOOKED like a merge and merged nothing — it folded in a local
+            // conditional, not the node's `sx`, so every style an author set
+            // on a plugin element was discarded. Order matters: the frame's
+            // own box goes first so the author can override it, and the
+            // load-time hide goes LAST so an authored `visibility` can never
+            // reveal a frame that has not finished loading.
+            sx: [
+                {
+                    width: '100%',
+                    height,
+                    border: 0,
+                    display: 'block'
+                },
+                ...nodeSx,
+                ...state === 'loading' ? [
+                    {
+                        visibility: 'hidden'
+                    }
+                ] : []
+            ]
+        }))
+    });
+});
+PluginFrame.displayName = 'AglynPluginFrame';
+export { PluginFrame };
+export default PluginFrame;
+
+//# sourceMappingURL=plugin-frame.js.map