@persona/layout-editor-remote-module 0.9.0 → 0.11.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:
@@ -168,3 +180,24 @@ const { modules } = parseRemoteModuleManifest(await response.json());
 It throws `RemoteModuleManifestParseError` (with `.issues` and a prettified `.message`) on a
 malformed document; `safeParseRemoteModuleManifest` returns `{ success, data | error }` instead of
 throwing.
+
+### Rendering a config panel
+
+A host stores a placed module's config under a `config` property, so its RJSF form edits
+`{ config }`. The `./config-form` entry adapts a manifest to that shape, with no React or RJSF
+dependency:
+
+```ts
+import {
+  nestRemoteConfigSchema,
+  nestRemoteUiConfigSchema,
+  remoteConfigDefaults,
+} from '@persona/layout-editor-remote-module/config-form';
+
+const schema = nestRemoteConfigSchema(module.configSchema); // `$ref`s rewritten to match
+const uiSchema = nestRemoteUiConfigSchema(module.uiConfigSchema);
+const initialConfig = remoteConfigDefaults(module.configSchema); // top-level `default`s
+```
+
+Render the form with `schema`, `uiSchema` and `formData: { config }`, and read the edited config
+back from `formData.config`.

package/dist/bridge-frame.d.mts

@@ -1,4 +1,5 @@
-import { n as Json, t as RemoteModuleContext } from "./protocol-Dqnl8JTs.mjs";
+import { t as Json } from "./types-CBSiNsDJ.mjs";
+import { t as RemoteModuleContext } from "./protocol-ClWDYwW2.mjs";
 import { ReactNode } from "react";
 
 //#region src/bridge/origin.d.ts
@@ -12,6 +13,7 @@ type ModuleBridgeInitPayload = {
 type CreateModuleBridgeOptions = {
   allowedHostOrigins?: (string | RegExp)[] | ((origin: string) => boolean);
   resolveTimeoutMs?: number;
+  signalsLoaded?: boolean;
 };
 type ModuleBridge = {
   ready: () => Promise<ModuleBridgeInitPayload>;
@@ -21,6 +23,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-BfjTaW1S.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,4 +1,5 @@
-import { n as Json, t as RemoteModuleContext } from "./protocol-Dqnl8JTs.mjs";
+import { t as Json } from "./types-CBSiNsDJ.mjs";
+import { t as RemoteModuleContext } from "./protocol-ClWDYwW2.mjs";
 import { CSSProperties, ReactNode, Ref } from "react";
 
 //#region src/bridge/host/buildModuleSrc.d.ts
@@ -36,6 +37,8 @@ type RemoteModuleFrameProps = {
   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,
@@ -58,7 +61,8 @@ declare function RemoteModuleFrame({
   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 { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-BfjTaW1S.mjs";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { jsx } from "react/jsx-runtime";
+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,7 +184,7 @@ 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, iframeRef: externalIframeRef, 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));
@@ -154,6 +193,7 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 	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) {
@@ -184,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,
@@ -197,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 () => {
@@ -217,7 +258,7 @@ 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", {
+	const iframe = /* @__PURE__ */ jsx("iframe", {
 		ref: setRefs,
 		src,
 		title,
@@ -232,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/config-form.d.mts

@@ -0,0 +1,23 @@
+import { n as JsonSchemaObject, t as Json } from "./types-CBSiNsDJ.mjs";
+
+//#region src/config-form.d.ts
+
+/** JSON pointer, in the nested schema, of the module's own config schema. */
+declare const REMOTE_CONFIG_POINTER_PREFIX = "#/properties/config";
+/**
+ * Nest a manifest `configSchema` under a top-level `config` property, rewriting `$ref`s so they
+ * still resolve. Drops `$schema` and `$id`; keeps `$defs` / `definitions` at the root.
+ */
+declare function nestRemoteConfigSchema(configSchema: JsonSchemaObject): JsonSchemaObject;
+/**
+ * Nest a manifest `uiConfigSchema` to match {@link nestRemoteConfigSchema}, hiding the wrapper
+ * object's title so the module's fields render as if top level.
+ */
+declare function nestRemoteUiConfigSchema(uiConfigSchema: JsonSchemaObject | undefined): JsonSchemaObject;
+/**
+ * A config holding each top-level `configSchema` property's `default`. Properties without one are
+ * left unset; defaults are cloned so the result can be mutated freely.
+ */
+declare function remoteConfigDefaults(configSchema: JsonSchemaObject | undefined): Record<string, Json>;
+//#endregion
+export { REMOTE_CONFIG_POINTER_PREFIX, nestRemoteConfigSchema, nestRemoteUiConfigSchema, remoteConfigDefaults };

package/dist/config-form.mjs

@@ -0,0 +1,79 @@
+//#region src/config-form.ts
+/** JSON pointer, in the nested schema, of the module's own config schema. */
+const REMOTE_CONFIG_POINTER_PREFIX = "#/properties/config";
+/** Keywords whose values are instance data, never schemas, so a `$ref` key inside them is data. */
+const LITERAL_KEYWORDS = new Set([
+	"const",
+	"default",
+	"enum",
+	"examples"
+]);
+/** Keywords whose values map arbitrary names to schemas, so a name like `default` is a schema. */
+const SCHEMA_MAP_KEYWORDS = new Set([
+	"$defs",
+	"definitions",
+	"dependentSchemas",
+	"patternProperties",
+	"properties"
+]);
+function rewriteSchemaMap(value, schemaId) {
+	if (value == null || typeof value !== "object" || Array.isArray(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([name, schema]) => [name, rewriteReferences(schema, schemaId)]));
+}
+function rewriteReferences(value, schemaId) {
+	if (Array.isArray(value)) return value.map((item) => rewriteReferences(item, schemaId));
+	if (value == null || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+		if (key === "$ref" && typeof child === "string") return [key, rewriteReference(child, schemaId)];
+		if (LITERAL_KEYWORDS.has(key)) return [key, child];
+		if (SCHEMA_MAP_KEYWORDS.has(key)) return [key, rewriteSchemaMap(child, schemaId)];
+		return [key, rewriteReferences(child, schemaId)];
+	}));
+}
+function rewriteReference(reference, schemaId) {
+	if (schemaId != null) {
+		if (reference === schemaId) return REMOTE_CONFIG_POINTER_PREFIX;
+		if (reference.startsWith(`${schemaId}#`)) return rewriteReference(reference.slice(schemaId.length));
+	}
+	if (reference === "#") return REMOTE_CONFIG_POINTER_PREFIX;
+	if (reference.startsWith("#/$defs/") || reference.startsWith("#/definitions/")) return reference;
+	if (reference.startsWith("#/")) return `${REMOTE_CONFIG_POINTER_PREFIX}${reference.slice(1)}`;
+	return reference;
+}
+/**
+* Nest a manifest `configSchema` under a top-level `config` property, rewriting `$ref`s so they
+* still resolve. Drops `$schema` and `$id`; keeps `$defs` / `definitions` at the root.
+*/
+function nestRemoteConfigSchema(configSchema) {
+	const { $defs, definitions, $id, ...rest } = configSchema;
+	const body = Object.fromEntries(Object.entries(rest).filter(([key]) => key !== "$schema"));
+	const schemaId = typeof $id === "string" ? $id : void 0;
+	return {
+		type: "object",
+		properties: { config: rewriteReferences(body, schemaId) },
+		...$defs != null && { $defs: rewriteSchemaMap($defs, schemaId) },
+		...definitions != null && { definitions: rewriteSchemaMap(definitions, schemaId) }
+	};
+}
+/**
+* Nest a manifest `uiConfigSchema` to match {@link nestRemoteConfigSchema}, hiding the wrapper
+* object's title so the module's fields render as if top level.
+*/
+function nestRemoteUiConfigSchema(uiConfigSchema) {
+	return { config: {
+		...uiConfigSchema,
+		"ui:title": ""
+	} };
+}
+/**
+* A config holding each top-level `configSchema` property's `default`. Properties without one are
+* left unset; defaults are cloned so the result can be mutated freely.
+*/
+function remoteConfigDefaults(configSchema) {
+	const properties = configSchema?.properties;
+	if (properties == null || typeof properties !== "object" || Array.isArray(properties)) return {};
+	return Object.fromEntries(Object.entries(properties).filter(([, propertySchema]) => typeof propertySchema === "object" && propertySchema != null && !Array.isArray(propertySchema) && "default" in propertySchema).map(([key, propertySchema]) => [key, structuredClone(propertySchema.default)]));
+}
+
+//#endregion
+export { REMOTE_CONFIG_POINTER_PREFIX, nestRemoteConfigSchema, nestRemoteUiConfigSchema, remoteConfigDefaults };

package/dist/{protocol-D_pdVZjs.mjs → protocol-BfjTaW1S.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/dist/{protocol-Dqnl8JTs.d.mts → protocol-ClWDYwW2.d.mts}

@@ -1,14 +1,7 @@
 import { z } from "zod";
 
-//#region src/types.d.ts
-
-type Json = boolean | JsonObject | JsonValue[] | null | number | string;
-type JsonObject = {
-  [key: string]: Json;
-};
-type JsonValue = Json;
-//#endregion
 //#region src/bridge/protocol.d.ts
+
 /**
  * Runtime facts about where the module is rendered, owned by the host and not
  * derivable by the module itself. Distinct from `data`, which is the module's
@@ -24,4 +17,4 @@ declare const remoteModuleContextSchema: z.ZodObject<{
 }, z.core.$strip>;
 type RemoteModuleContext = z.infer<typeof remoteModuleContextSchema>;
 //#endregion
-export { Json as n, RemoteModuleContext as t };
+export { RemoteModuleContext as t };

package/dist/types-CBSiNsDJ.d.mts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+//#region src/types.d.ts
+
+type Json = boolean | JsonObject | JsonValue[] | null | number | string;
+/**
+ * Loose JSON Schema object. Deliberately not a full JSON Schema type system —
+ * this package only needs to carry what `z.toJSONSchema()` emits for consumers
+ * to validate or render.
+ */
+type JsonSchemaObject = Record<string, unknown>;
+type JsonObject = {
+  [key: string]: Json;
+};
+type JsonValue = Json;
+//#endregion
+export { JsonSchemaObject as n, Json as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.9.0",
+  "version": "0.11.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",
@@ -15,6 +15,9 @@
       ],
       "bridge-frame": [
         "dist/bridge-frame.d.mts"
+      ],
+      "config-form": [
+        "dist/config-form.d.mts"
       ]
     }
   },
@@ -111,6 +114,10 @@
       "types": "./dist/bridge-host.d.mts",
       "import": "./dist/bridge-host.mjs"
     },
+    "./config-form": {
+      "types": "./dist/config-form.d.mts",
+      "import": "./dist/config-form.mjs"
+    },
     "./bridge-frame": {
       "types": "./dist/bridge-frame.d.mts",
       "import": "./dist/bridge-frame.mjs"

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`.