@persona/layout-editor-remote-module 0.8.1 → 0.10.0

package/README.md

@@ -71,12 +71,24 @@ import { RemoteModuleFrame } from '@persona/layout-editor-remote-module/bridge-h
   data={moduleData}
   context={moduleContext}
   dynamicHeight
+  loadingFallback={<div>Loading module…</div>}
   resolveDataPath={resolveDataPath}
 />;
 ```
 
 The required `sandbox` value is chosen by the host.
 
+`loadingFallback` is drawn over the iframe until the module has rendered. `LayoutModuleBridge`
+advertises the `loaded` message automatically after its first render and waits for the first height
+measurement before sending it when height observation is enabled. A module that needs a loading
+state should render it on its first render; `LayoutModuleBridge`'s `fallback` is hidden under the
+host overlay until then and remains available for render errors.
+
+- `createModuleBridge` and `useRemoteModuleBridge` keep legacy behavior by default; direct bridge
+  users opt in with `signalsLoaded: true` and call `bridge.signalLoaded()` after rendering.
+- Frames without the `loaded` capability are treated as legacy: `ready`, another bridge message, or
+  a silent-frame timeout after iframe load dismisses the overlay.
+
 By default, the bridge accepts host origins matching `*.withpersona.com`,
 `*.withpersona-staging.com`, `localhost`, and `127.0.0.1`. Add development or preview origins with
 `allowedHostOrigins`, optionally composing the exported `personaDashboardHostOrigins` helper:

package/dist/bridge-frame.d.mts

@@ -12,6 +12,7 @@ type ModuleBridgeInitPayload = {
 type CreateModuleBridgeOptions = {
   allowedHostOrigins?: (string | RegExp)[] | ((origin: string) => boolean);
   resolveTimeoutMs?: number;
+  signalsLoaded?: boolean;
 };
 type ModuleBridge = {
   ready: () => Promise<ModuleBridgeInitPayload>;
@@ -21,6 +22,7 @@ type ModuleBridge = {
   reportRenderError: (message: string) => void;
   resolveDataPath: (dataPath: string, variableMap?: Record<string, string | number>) => Promise<Json>;
   observeHeight: (element: Element) => () => void;
+  signalLoaded: () => void;
   destroy: () => void;
 };
 //#endregion

package/dist/bridge-frame.mjs

@@ -1,4 +1,4 @@
-import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-D_pdVZjs.mjs";
+import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-Br3C6FM7.mjs";
 import { Component, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
@@ -70,7 +70,7 @@ const measureDocumentHeight = (element) => {
 	}
 	return Math.ceil(rect.top + window.scrollY + rect.height + trailing);
 };
-function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins, resolveTimeoutMs = 3e4 } = {}) {
+function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins, resolveTimeoutMs = 3e4, signalsLoaded = false } = {}) {
 	const isEmbedded = typeof window !== "undefined" && window.parent !== window;
 	const allowedOrigin = resolveAllowedHostOrigins(allowedHostOrigins);
 	if (!isEmbedded) {
@@ -88,6 +88,7 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 				throw notEmbeddedError;
 			},
 			observeHeight: () => () => {},
+			signalLoaded: () => {},
 			destroy: () => {}
 		};
 	}
@@ -96,8 +97,12 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 	let data = null;
 	let context = null;
 	let readyResolved = false;
+	let initialReadyPosted = false;
+	let loadedRequested = false;
+	let loadedPosted = false;
 	const listeners = /* @__PURE__ */ new Set();
 	const observers = /* @__PURE__ */ new Set();
+	const pendingHeightObservers = /* @__PURE__ */ new Set();
 	const pendingRequests = createPendingRequests();
 	const queuedRequests = /* @__PURE__ */ new Map();
 	let resolveReady;
@@ -107,7 +112,18 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 		rejectReady = reject;
 	});
 	const post = (message) => {
-		if (hostOrigin) window.parent.postMessage(message, hostOrigin);
+		if (!destroyed && hostOrigin) {
+			window.parent.postMessage(message, hostOrigin);
+			return true;
+		}
+		return false;
+	};
+	const flushLoaded = () => {
+		if (!destroyed && loadedRequested && !loadedPosted && hostOrigin && pendingHeightObservers.size === 0) loadedPosted = post({
+			source: SOURCE,
+			protocolVersion: PROTOCOL_VERSION,
+			type: "loaded"
+		});
 	};
 	const flushQueuedRequests = () => {
 		if (!hostOrigin) return;
@@ -127,7 +143,6 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 		if (!allowedOrigin(origin)) return false;
 		if (hostOrigin !== void 0 && hostOrigin !== origin) return false;
 		hostOrigin = origin;
-		flushQueuedRequests();
 		return true;
 	};
 	const notify = () => {
@@ -137,6 +152,17 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 		if (destroyed || event.source !== window.parent) return;
 		const message = parseHostToModuleMessage(event.data);
 		if (!message || !pinHostOrigin(event.origin)) return;
+		if (message.type === "init" && signalsLoaded && !initialReadyPosted) {
+			initialReadyPosted = true;
+			post({
+				source: SOURCE,
+				protocolVersion: PROTOCOL_VERSION,
+				type: "ready",
+				capabilities: { loaded: true }
+			});
+		}
+		flushQueuedRequests();
+		flushLoaded();
 		switch (message.type) {
 			case "init":
 				data = message.data;
@@ -166,11 +192,15 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 	};
 	window.addEventListener("message", onMessage);
 	const parentOrigin = candidateParentOrigin();
-	if (parentOrigin && allowedOrigin(parentOrigin)) window.parent.postMessage({
-		source: SOURCE,
-		protocolVersion: PROTOCOL_VERSION,
-		type: "ready"
-	}, parentOrigin);
+	if (parentOrigin && allowedOrigin(parentOrigin)) {
+		window.parent.postMessage({
+			source: SOURCE,
+			protocolVersion: PROTOCOL_VERSION,
+			type: "ready",
+			...signalsLoaded ? { capabilities: { loaded: true } } : {}
+		}, parentOrigin);
+		initialReadyPosted = true;
+	}
 	return {
 		ready: () => readyPromise,
 		getData: () => data,
@@ -202,17 +232,19 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 			let lastHeight;
 			let frame;
 			let disconnected = false;
+			let observer;
 			const postHeight = (height) => {
 				if (disconnected || height === lastHeight) return;
-				lastHeight = height;
-				post({
+				if (!post({
 					source: SOURCE,
 					protocolVersion: PROTOCOL_VERSION,
 					type: "set-height",
 					height
-				});
+				})) return;
+				lastHeight = height;
+				if (pendingHeightObservers.delete(observer)) flushLoaded();
 			};
-			const observer = new ResizeObserver(() => {
+			observer = new ResizeObserver(() => {
 				if (frame !== void 0) return;
 				const callback = () => {
 					frame = void 0;
@@ -221,6 +253,7 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 				frame = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame(callback) : window.setTimeout(callback, 0);
 			});
 			observers.add(observer);
+			pendingHeightObservers.add(observer);
 			observer.observe(element);
 			const body = element.ownerDocument?.body;
 			if (body && body !== element) observer.observe(body);
@@ -232,14 +265,21 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 				}
 				observer.disconnect();
 				observers.delete(observer);
+				if (pendingHeightObservers.delete(observer)) flushLoaded();
 			};
 		},
+		signalLoaded() {
+			if (destroyed || loadedRequested) return;
+			loadedRequested = true;
+			flushLoaded();
+		},
 		destroy() {
 			if (destroyed) return;
 			destroyed = true;
 			window.removeEventListener("message", onMessage);
 			for (const observer of observers) observer.disconnect();
 			observers.clear();
+			pendingHeightObservers.clear();
 			queuedRequests.clear();
 			const error = new BridgeDestroyedError();
 			pendingRequests.rejectAll(error);
@@ -320,7 +360,8 @@ var BridgeErrorBoundary = class extends Component {
 function LayoutModuleBridge({ allowedHostOrigins, resolveTimeoutMs, observeHeight = true, fallback = null, children }) {
 	const { bridge, context, data, ready, resolveDataPath } = useRemoteModuleBridge({
 		allowedHostOrigins,
-		resolveTimeoutMs
+		resolveTimeoutMs,
+		signalsLoaded: true
 	});
 	const rootRef = useRef(null);
 	useEffect(() => {
@@ -338,6 +379,9 @@ function LayoutModuleBridge({ allowedHostOrigins, resolveTimeoutMs, observeHeigh
 		observeHeight,
 		ready
 	]);
+	useEffect(() => {
+		if (ready && bridge) bridge.signalLoaded();
+	}, [bridge, ready]);
 	if (!ready || !bridge) return fallback;
 	return /* @__PURE__ */ jsx(BridgeErrorBoundary, {
 		bridge,

package/dist/bridge-host.d.mts

@@ -1,5 +1,5 @@
 import { n as Json, t as RemoteModuleContext } from "./protocol-Dqnl8JTs.mjs";
-import { CSSProperties, ReactNode } from "react";
+import { CSSProperties, ReactNode, Ref } from "react";
 
 //#region src/bridge/host/buildModuleSrc.d.ts
 type BuildModuleSrcOptions = {
@@ -30,10 +30,14 @@ type RemoteModuleFrameProps = {
   minHeight?: number;
   className?: string;
   style?: CSSProperties;
+  /** Receives the underlying <iframe> so a host can attach extra postMessage bridges. */
+  iframeRef?: Ref<HTMLIFrameElement>;
   data: Json;
   context: RemoteModuleContext;
   resolveDataPath: ResolveDataPath;
   onRenderError?: (message: string) => void;
+  /** Rendered over the iframe until the module reports that it has loaded. */
+  loadingFallback?: ReactNode;
 };
 declare function RemoteModuleFrame({
   documentUrl,
@@ -52,10 +56,12 @@ declare function RemoteModuleFrame({
   minHeight,
   className,
   style,
+  iframeRef: externalIframeRef,
   data,
   context,
   resolveDataPath,
-  onRenderError
+  onRenderError,
+  loadingFallback
 }: RemoteModuleFrameProps): ReactNode;
 //#endregion
 export { type Json, type RemoteModuleContext, RemoteModuleFrame, type RemoteModuleFrameProps, type ResolveDataPath };

package/dist/bridge-host.mjs

@@ -1,6 +1,6 @@
-import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-D_pdVZjs.mjs";
-import { useEffect, useMemo, useRef, useState } from "react";
-import { jsx } from "react/jsx-runtime";
+import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-Br3C6FM7.mjs";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/bridge/host/buildModuleSrc.ts
 const reservedParams = new Set([
@@ -24,11 +24,15 @@ function buildModuleSrc(documentUrl, options = {}) {
 
 //#endregion
 //#region src/bridge/host/createHostBridge.ts
-function createHostBridge({ iframe, moduleOrigin, getData, getContext, resolveDataPath, onHeight, onRenderError, initRetryMs = 250, initRetryTimeoutMs = 1e4 }) {
+function createHostBridge({ iframe, moduleOrigin, getData, getContext, resolveDataPath, onHeight, onRenderError, onLoaded, initRetryMs = 250, initRetryTimeoutMs = 1e4 }) {
 	assertNotSelfOrigin(moduleOrigin);
 	if (moduleOrigin === "*") throw new Error("Remote module origin must be explicit");
 	let destroyed = false;
 	let initialized = false;
+	let capable;
+	let loaded = false;
+	let fallbackTimer;
+	let fallbackTimerStarted = false;
 	let initRetryTimer;
 	const clearInitRetry = () => {
 		if (initRetryTimer !== void 0) {
@@ -36,6 +40,18 @@ function createHostBridge({ iframe, moduleOrigin, getData, getContext, resolveDa
 			initRetryTimer = void 0;
 		}
 	};
+	const clearFallbackTimer = () => {
+		if (fallbackTimer !== void 0) {
+			clearTimeout(fallbackTimer);
+			fallbackTimer = void 0;
+		}
+	};
+	const markLoaded = () => {
+		if (loaded) return;
+		loaded = true;
+		clearFallbackTimer();
+		onLoaded?.();
+	};
 	const post = (message) => {
 		if (!destroyed) iframe.contentWindow?.postMessage(message, moduleOrigin);
 	};
@@ -72,17 +88,38 @@ function createHostBridge({ iframe, moduleOrigin, getData, getContext, resolveDa
 		});
 	};
 	const onLoad = () => {
-		if (!destroyed) startInitRetry();
+		if (!destroyed) {
+			if (!fallbackTimerStarted) {
+				fallbackTimerStarted = true;
+				fallbackTimer = setTimeout(() => {
+					fallbackTimer = void 0;
+					if (capable === void 0) markLoaded();
+				}, Math.max(initRetryTimeoutMs, 0) + 500);
+			}
+			startInitRetry();
+		}
 	};
 	const onMessage = (event) => {
 		if (destroyed || event.origin !== moduleOrigin || event.source !== iframe.contentWindow) return;
 		const message = parseModuleToHostMessage(event.data);
 		if (!message) return;
 		clearInitRetry();
+		if (message.type === "ready") {
+			if (capable === void 0) {
+				capable = message.capabilities?.loaded === true;
+				if (!capable) markLoaded();
+			}
+		} else if (message.type !== "loaded" && message.type !== "render-error" && capable === void 0) {
+			capable = false;
+			markLoaded();
+		}
 		switch (message.type) {
 			case "ready":
 				sendInit();
 				break;
+			case "loaded":
+				markLoaded();
+				break;
 			case "request-data":
 				sendData(getData(), message.requestId);
 				break;
@@ -90,6 +127,7 @@ function createHostBridge({ iframe, moduleOrigin, getData, getContext, resolveDa
 				onHeight?.(message.height);
 				break;
 			case "render-error":
+				markLoaded();
 				onRenderError?.(message.message);
 				break;
 			case "resolve-data-path":
@@ -131,6 +169,7 @@ function createHostBridge({ iframe, moduleOrigin, getData, getContext, resolveDa
 			if (destroyed) return;
 			destroyed = true;
 			clearInitRetry();
+			clearFallbackTimer();
 			window.removeEventListener("message", onMessage);
 			iframe.removeEventListener("load", onLoad);
 		}
@@ -145,14 +184,28 @@ function withDynamicHeight(context, dynamicHeight) {
 		dynamicHeight
 	};
 }
-function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environmentId, locale, extraParams, title, sandbox, referrerPolicy = "no-referrer", initRetryMs, initRetryTimeoutMs, dynamicHeight = false, heightOffset = 0, minHeight, className, style, data, context, resolveDataPath, onRenderError }) {
+function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environmentId, locale, extraParams, title, sandbox, referrerPolicy = "no-referrer", initRetryMs, initRetryTimeoutMs, dynamicHeight = false, heightOffset = 0, minHeight, className, style, iframeRef: externalIframeRef, data, context, resolveDataPath, onRenderError, loadingFallback }) {
 	const iframeRef = useRef(null);
 	const dataRef = useRef(data);
 	const contextRef = useRef(withDynamicHeight(context, dynamicHeight));
 	const onRenderErrorRef = useRef(onRenderError);
 	const resolveDataPathRef = useRef(resolveDataPath);
 	const bridgeRef = useRef(void 0);
+	const externalCleanupRef = useRef(void 0);
 	const [height, setHeight] = useState();
+	const [loadedSrc, setLoadedSrc] = useState();
+	const setRefs = useCallback((node) => {
+		iframeRef.current = node;
+		if (typeof externalIframeRef === "function") if (node) {
+			const cleanup = externalIframeRef(node);
+			externalCleanupRef.current = typeof cleanup === "function" ? cleanup : void 0;
+		} else if (externalCleanupRef.current) {
+			const cleanup = externalCleanupRef.current;
+			externalCleanupRef.current = void 0;
+			cleanup();
+		} else externalIframeRef(null);
+		else if (externalIframeRef) externalIframeRef.current = node;
+	}, [externalIframeRef]);
 	const hostContext = useMemo(() => withDynamicHeight(context, dynamicHeight), [context, dynamicHeight]);
 	dataRef.current = data;
 	contextRef.current = hostContext;
@@ -171,10 +224,10 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 		locale
 	]);
 	useEffect(() => {
-		const iframe = iframeRef.current;
-		if (!iframe) return;
+		const iframe$1 = iframeRef.current;
+		if (!iframe$1) return;
 		const bridge = createHostBridge({
-			iframe,
+			iframe: iframe$1,
 			moduleOrigin,
 			getData: () => dataRef.current,
 			getContext: () => contextRef.current,
@@ -184,7 +237,8 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 			onHeight: (nextHeight) => {
 				setHeight(nextHeight);
 			},
-			onRenderError: (message) => onRenderErrorRef.current?.(message)
+			onRenderError: (message) => onRenderErrorRef.current?.(message),
+			onLoaded: () => setLoadedSrc(src)
 		});
 		bridgeRef.current = bridge;
 		return () => {
@@ -204,8 +258,8 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 		bridgeRef.current?.pushContext(hostContext);
 	}, [hostContext]);
 	const computedHeight = dynamicHeight && height !== void 0 ? `${Math.max(height + heightOffset, minHeight ?? 0)}px` : minHeight === void 0 ? "100%" : `${minHeight}px`;
-	return /* @__PURE__ */ jsx("iframe", {
-		ref: iframeRef,
+	const iframe = /* @__PURE__ */ jsx("iframe", {
+		ref: setRefs,
 		src,
 		title,
 		sandbox,
@@ -219,6 +273,20 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 			border: "none"
 		}
 	}, src);
+	return /* @__PURE__ */ jsxs("div", {
+		style: {
+			position: "relative",
+			width: "100%",
+			height: computedHeight === "100%" ? "100%" : void 0
+		},
+		children: [iframe, loadingFallback !== void 0 && !(loadedSrc === src) && /* @__PURE__ */ jsx("div", {
+			style: {
+				position: "absolute",
+				inset: 0
+			},
+			children: loadingFallback
+		})]
+	});
 }
 
 //#endregion

package/dist/{protocol-D_pdVZjs.mjs → protocol-Br3C6FM7.mjs}

@@ -117,7 +117,12 @@ const requestIdSchema = z.string().min(1);
 const variableMapSchema = z.record(z.string(), z.union([z.string(), z.number()]));
 const readySchema = z.object({
 	...envelopeSchema,
-	type: z.literal("ready")
+	type: z.literal("ready"),
+	capabilities: z.object({ loaded: z.boolean().optional() }).optional()
+});
+const loadedSchema = z.object({
+	...envelopeSchema,
+	type: z.literal("loaded")
 });
 const requestDataSchema = z.object({
 	...envelopeSchema,
@@ -161,6 +166,7 @@ const remoteModuleContextSchema = z.object({
 });
 const moduleToHostMessageSchema = z.discriminatedUnion("type", [
 	readySchema,
+	loadedSchema,
 	requestDataSchema,
 	setHeightSchema,
 	renderErrorSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Shared manifest format, Vite plugin, and host/iframe bridge for remotely-defined dashboard layout modules in Persona dashboard apps.",
   "license": "SEE LICENSE",
   "type": "module",

package/skills/getting-started/SKILL.md

@@ -6,11 +6,11 @@ description: >
   document entry, add a zod configSchema and an RJSF uiConfigSchema (labels, field order,
   DataSourceField pickers), and talk to the host from the iframe with LayoutModuleBridge (layout
   data, host context such as layoutType / layoutObjectId / isReadOnly / dynamicHeight,
-  resolveDataPath, height). Activate when adding a layout module, integrating this package for the
-  first time, wiring a module document to the dashboard host, or debugging a manifest that fails to
-  build or validate (duplicate key, missing defaultSize entry, render path not found), a module that
-  never receives data from the host, or an iframe whose height collapses or keeps growing under
-  dynamic height.
+  resolveDataPath, height, loaded signal). Activate when adding a layout module, integrating this
+  package for the first time, wiring a module document to the dashboard host, or debugging a
+  manifest that fails to build or validate (duplicate key, missing defaultSize entry, render path
+  not found), a module that never receives data from the host, a host loading card that never
+  clears, or an iframe whose height collapses or keeps growing under dynamic height.
 metadata:
   type: core
   library: '@persona/layout-editor-remote-module'
@@ -266,7 +266,7 @@ import { LayoutModuleBridge } from '@persona/layout-editor-remote-module/bridge-
 
 export function App() {
   return (
-    <LayoutModuleBridge fallback={<Spinner />}>
+    <LayoutModuleBridge>
       {({ data, context, resolveDataPath }) => (
         <RiskSummary data={data} context={context} resolveDataPath={resolveDataPath} />
       )}
@@ -276,7 +276,9 @@ export function App() {
 ```
 
 - `children` is only invoked once the host has sent the initial layout data — it never sees
-  `data: undefined`. Until then `fallback` (default `null`) is rendered.
+  `data: undefined`. Until then `fallback` (default `null`) is rendered, hidden under the host's
+  loading card. After the first render the bridge posts `loaded` and the host removes the card, so
+  render any data-loading state from `children`.
 - `data` is the module's persisted config as JSON, and re-renders whenever the host pushes an
   update.
 - `context` (`RemoteModuleContext`) is where the module is rendered — host-owned facts the module
@@ -291,7 +293,8 @@ export function App() {
   borders, so the host can size the iframe (`observeHeight={false}` to opt out). The host uses the
   reported height only when [`context.dynamicHeight`](#host-context) is true; otherwise, the iframe
   keeps its grid size.
-- A render error thrown inside `children` is caught, reported to the host, and `fallback` is shown.
+- A render error thrown inside `children` is caught, reported to the host, and `fallback` is shown
+  after the host loading overlay is dismissed.
 - Mount exactly one `LayoutModuleBridge` per document.
 
 Props: `fallback?: ReactNode`, `observeHeight?: boolean` (default `true`),
@@ -373,17 +376,18 @@ from there.
 
 Source: `src/bridge/iframe/LayoutModuleBridge.tsx`.
 
-### [MEDIUM] Module renders forever in `fallback` when embedded
+### [MEDIUM] Host loading card stays visible forever when embedded
 
-`children` never running means the handshake didn't complete. Check, in order: the document is
-really cross-origin-embedded by a Persona host (the default `allowedHostOrigins` predicate rejects
-unknown parents — pass your own only for a non-Persona dev host); the frame's
+The host removes its loading card once `LayoutModuleBridge` has rendered `children`, so a card that
+never clears usually means the handshake didn't complete. Check, in order: the document is really
+cross-origin-embedded by a Persona host (the default `allowedHostOrigins` predicate rejects unknown
+parents — pass your own only for a non-Persona dev host); the frame's
 `@persona/layout-editor-remote-module` is 0.5.3 or later (a frame on 0.5.2 or older rejects an
 `init` whose context has keys it doesn't know, e.g. `dynamicHeight`, sent by hosts on 0.8.0+, so
 `children` never runs); and the host is rendering it through `RemoteModuleFrame` (bare `<iframe>`s
-never send `init`). Opening the document directly in a tab is _not_ embedded — `data` and `context`
-resolve to `null` and `children` renders, so a stuck fallback is always a host, origin, or frame
-version problem.
+never send `init`). For a direct `createModuleBridge` integration, also confirm that a bridge
+created with `signalsLoaded: true` calls `signalLoaded()`. Opening the document directly in a tab is
+_not_ embedded — `data` and `context` resolve to `null` and `children` renders.
 
 Source: `src/bridge/iframe/createModuleBridge.ts`, `src/bridge/origin.ts`, `src/bridge/protocol.ts`.