@persona/layout-editor-remote-module 0.8.0 → 0.9.0

package/README.md

@@ -56,8 +56,9 @@ contract, including the optional `path` field for a client-routed SPA.
 
 ## Communicating with the host
 
-Document-delivered modules can use the browser bridge to receive layout data, report their height,
-and resolve data paths through the host. The host renders the document with `RemoteModuleFrame`:
+Document-delivered modules can use the browser bridge to receive layout data, report the height
+their document needs (including `body` and ancestor margins and padding), and resolve data paths
+through the host. The host renders the document with `RemoteModuleFrame`:
 
 ```tsx
 import { RemoteModuleFrame } from '@persona/layout-editor-remote-module/bridge-host';
@@ -116,10 +117,12 @@ cannot derive itself:
 - `isInEditor` — the module is rendered inside the layout editor rather than on a live record
 - `isUsingStubData` — the host is feeding placeholder/stub data instead of a real record
 - `dynamicHeight` — whether the host sizes the iframe to the height the bridge reports
-  (`RemoteModuleFrame`'s `dynamicHeight`). A module that fills a fixed-height iframe with viewport
-  units (`100vh`) should size to its content when it's set, or the reported height just follows the
-  iframe. `RemoteModuleFrame` sets it from its `dynamicHeight` prop, overriding any value in the
-  `context` prop.
+  (`RemoteModuleFrame`'s `dynamicHeight`). The reported height covers the whole frame document,
+  including `body` and ancestor margins and padding. A module that fills a fixed-height iframe with
+  viewport units (`100vh`) should size to its content when it's set — combined with any `body`
+  margin or padding the reported height exceeds the iframe, so it grows on every report.
+  `RemoteModuleFrame` sets it from its `dynamicHeight` prop, overriding any value in the `context`
+  prop.
 
 `context` is sent with `init` and pushed again whenever it changes, just like `data`; inside the
 iframe it arrives through `ready()`, `getContext()`, and the `context` render prop (all
@@ -140,10 +143,10 @@ The bridge's security model is intentionally narrow:
 - The iframe derives the ready target from `ancestorOrigins` or the referrer, and the host retries
   `init` until the frame answers.
 - Messages use a versioned protocol that stays compatible with frames built against older releases
-  (from the release after 0.5.1): receivers ignore message types they don't know and strip keys they
-  don't know, and fields are never removed, renamed or narrowed. `context.layoutType` can be a
-  layout type added later, so handle values you don't know. Credentials remain in the iframe URL and
-  are never handled through bridge messages.
+  (from 0.5.3): receivers ignore message types they don't know and strip keys they don't know, and
+  fields are never removed, renamed or narrowed. `context.layoutType` can be a layout type added
+  later, so handle values you don't know. Credentials remain in the iframe URL and are never handled
+  through bridge messages.
 - `extraParams` rejects reserved names and credential-like keys.
 
 ### Consuming a manifest

package/dist/bridge-frame.mjs

@@ -61,6 +61,15 @@ function createPendingRequests() {
 
 //#endregion
 //#region src/bridge/iframe/createModuleBridge.ts
+const measureDocumentHeight = (element) => {
+	const rect = element.getBoundingClientRect();
+	let trailing = 0;
+	for (let ancestor = element.parentElement; ancestor; ancestor = ancestor.parentElement) {
+		const style = window.getComputedStyle(ancestor);
+		trailing += parseFloat(style.paddingBottom) + parseFloat(style.borderBottomWidth) + parseFloat(style.marginBottom);
+	}
+	return Math.ceil(rect.top + window.scrollY + rect.height + trailing);
+};
 function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins, resolveTimeoutMs = 3e4 } = {}) {
 	const isEmbedded = typeof window !== "undefined" && window.parent !== window;
 	const allowedOrigin = resolveAllowedHostOrigins(allowedHostOrigins);
@@ -203,20 +212,18 @@ function createModuleBridge({ allowedHostOrigins = personaDashboardHostOrigins,
 					height
 				});
 			};
-			const observer = new ResizeObserver((entries) => {
-				const entry = entries[0];
-				if (!entry) return;
-				const borderBoxSize = entry.borderBoxSize;
-				const height = (Array.isArray(borderBoxSize) ? borderBoxSize[0]?.blockSize : void 0) ?? entry.contentRect.height;
+			const observer = new ResizeObserver(() => {
 				if (frame !== void 0) return;
 				const callback = () => {
 					frame = void 0;
-					postHeight(height);
+					postHeight(measureDocumentHeight(element));
 				};
 				frame = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame(callback) : window.setTimeout(callback, 0);
 			});
 			observers.add(observer);
 			observer.observe(element);
+			const body = element.ownerDocument?.body;
+			if (body && body !== element) observer.observe(body);
 			return () => {
 				disconnected = true;
 				if (frame !== void 0) {
@@ -337,6 +344,7 @@ function LayoutModuleBridge({ allowedHostOrigins, resolveTimeoutMs, observeHeigh
 		fallback,
 		render: () => /* @__PURE__ */ jsx("div", {
 			ref: rootRef,
+			style: { display: "flow-root" },
 			children: children({
 				context,
 				data,

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,6 +30,8 @@ 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;
@@ -52,6 +54,7 @@ declare function RemoteModuleFrame({
   minHeight,
   className,
   style,
+  iframeRef: externalIframeRef,
   data,
   context,
   resolveDataPath,

package/dist/bridge-host.mjs

@@ -1,5 +1,5 @@
 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 { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/bridge/host/buildModuleSrc.ts
@@ -145,14 +145,27 @@ 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 }) {
 	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 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;
@@ -205,7 +218,7 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 	}, [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,
+		ref: setRefs,
 		src,
 		title,
 		sandbox,
@@ -214,6 +227,7 @@ function RemoteModuleFrame({ documentUrl, moduleOrigin, accessToken, environment
 		style: {
 			...style,
 			height: computedHeight,
+			display: style?.display ?? "block",
 			width: "100%",
 			border: "none"
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.8.0",
+  "version": "0.9.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

@@ -2,15 +2,15 @@
 name: getting-started
 description: >
   Wire up @persona/layout-editor-remote-module in a Persona dashboard app: register
-  personaLayoutModules in a typical app's vite.config.ts, author modules with defineLayoutModule
-  using a document (.html) render delivery, add a zod configSchema and an RJSF uiConfigSchema
-  (labels, field order, DataSourceField data-source pickers), and talk to the host from the iframed
-  document with LayoutModuleBridge from the bridge-frame entry (layout data, host context such as
-  layoutType / layoutObjectId / isReadOnly, resolveDataPath, and height). Activate when adding a new
-  layout module to an app, 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) or a module that never receives data from the
-  host.
+  personaLayoutModules in vite.config.ts, author modules with defineLayoutModule using an .html
+  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.
 metadata:
   type: core
   library: '@persona/layout-editor-remote-module'
@@ -31,8 +31,13 @@ This package is publicly available from the npm registry.
 yarn add @persona/layout-editor-remote-module
 ```
 
-`vite` and `zod` are peer dependencies; `react` / `react-dom` (`^17 || ^18 || ^19`) are optional
-peers needed only by the `bridge-frame` entry.
+`vite` (`^6 || ^7 || ^8`) and `zod` are peer dependencies. Vite 5 is unsupported because the plugin
+relies on the Vite 6 Environment API; `react` / `react-dom` (`^17 || ^18 || ^19`) are optional peers
+needed only by the `bridge-frame` entry.
+
+Build the iframed document against `@persona/layout-editor-remote-module` 0.5.3 or later. Older
+frames reject any host message that carries a key they don't know, so they stop working once the
+host sends new context fields such as `dynamicHeight`.
 
 ## Setup (vite.config.ts)
 
@@ -65,8 +70,10 @@ export default defineConfig({
 An empty or omitted `layouts` makes the module available in every layout. When `layouts` lists
 specific layouts, `defaultSize` must provide an entry for each one.
 
-Optional fields: `allowDynamicHeight` (expose the dynamic-height option in the module's
-configuration), `badge` (`'beta' | 'deprecated' | 'improved' | 'new'`), `category`
+Optional fields: `allowDynamicHeight` (exposes the option only; the host sizes the iframe to the
+module's reported height only when the user turns "dynamic height" on for that placement, and the
+module learns this through [`context.dynamicHeight`](#host-context)), `badge`
+(`'beta' | 'deprecated' | 'improved' | 'new'`), `category`
 (`'build_your_own' | 'components' | 'management' | 'related_records'`; the host defaults to
 `build_your_own`), `categoryCustom` (a free-form module-library category label, up to 80 characters;
 the host renders it verbatim — it is not translated — and groups modules that share the same
@@ -81,6 +88,12 @@ narrow visibility, never widen it), and `configSchema` / `uiConfigSchema` (below
 `entry` is resolved relative to the Vite **root** (`config.root`, or `process.cwd()` when unset) —
 not relative to `vite.config.ts`'s own directory when `root` is overridden elsewhere in the config.
 
+In a multi-environment build (e.g. with `@cloudflare/vite-plugin`), the plugin adds module documents
+only to the `client` environment's build inputs and writes the manifest only into the client
+environment's `build.outDir`. Non-client environments (workers/SSR) never see the `.html` entries.
+
+Source: `src/vite-plugin.ts` (`configEnvironment`, `closeBundle`).
+
 ## Core Patterns
 
 ### Document delivery — iframed page
@@ -273,8 +286,11 @@ export function App() {
   implementation. It rejects if the host reports an error or does not answer within
   `resolveTimeoutMs` (default 30s). Outside an iframe it rejects immediately, so a module opened
   directly in a tab still renders.
-- Height is reported automatically: the bridge wraps `children` in a `div` and observes it with a
-  `ResizeObserver` so the host can size the iframe (`observeHeight={false}` to opt out).
+- Height is reported automatically: the bridge wraps `children` in a `display: flow-root` div and
+  reports the height the frame document needs, including `body` and ancestor margins, padding, and
+  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.
 - Mount exactly one `LayoutModuleBridge` per document.
 
@@ -301,15 +317,24 @@ import {
 
 `RemoteModuleContext` (exported as a type from `bridge-frame`) has:
 
-- `layoutType` — `'account' | 'case' | 'transaction'`, the layout the module is placed on.
+- `layoutType` — known values are `'account' | 'case' | 'transaction'`, but its type is
+  `LayoutType | (string & {})` and the bridge accepts layout types added after the module's release.
+  Handle unknown values with a default branch rather than a switch that tries to cover every case.
 - `layoutObjectId` — the ID of the object the layout is rendered for (e.g. the viewed case's ID on a
   `case` layout), or `null` when there is none.
 - `isReadOnly` — the host object is locked for edits; hide or disable mutating actions.
 - `isInEditor` — rendered inside the layout editor rather than on a live record.
 - `isUsingStubData` — the host is feeding placeholder data instead of a real record; skip network
   calls or side effects keyed off the record.
+- `dynamicHeight` — `boolean`, optional in the type; `RemoteModuleFrame` always sets it. It is true
+  when the host sizes the iframe to the height the bridge reports. When true, size to content
+  (`height: auto`) instead of filling the viewport. When false or absent, the iframe has a fixed
+  grid height, so filling it (`100vh`) is fine. Treat a `null` context (not embedded) like false;
+  see
+  [Viewport-relative height under dynamic height](#high-viewport-relative-height-under-dynamic-height).
 
-`context` is `null` only when the document is not embedded (opened directly in a tab).
+`context` is `null` only when the document is not embedded (opened directly in a tab); inside
+`children` it is otherwise always set, because `children` runs only after `init`.
 
 ```tsx
 import {
@@ -325,6 +350,11 @@ function RiskSummary({ context }: { context: RemoteModuleContext | null }) {
 }
 ```
 
+The protocol only ever adds fields. Receivers built on 0.5.3+ ignore unknown message types and strip
+unknown keys, so new context fields may appear in later host releases without a frame upgrade.
+
+Source: `src/bridge/protocol.ts`.
+
 #### Access token and environment id
 
 The host still appends `access_token`, `environment_id`, and `locale` to the iframe `src`. The app
@@ -337,35 +367,9 @@ parameters cannot leak through subsequent requests.
 
 ### [HIGH] Reading layout data outside `LayoutModuleBridge`
 
-Wrong:
-
-```tsx
-const data = await requestDataSomehow(); // no such API
-const resolveDataPath = window.resolveDataPath; // no such API
-```
-
-Correct:
-
-```tsx
-function Module({
-  data,
-  resolveDataPath,
-}: {
-  data: Json;
-  resolveDataPath: (
-    dataPath: string,
-    variableMap?: Record<string, string | number>,
-  ) => Promise<Json>;
-}) {
-  // ...
-}
-
-<LayoutModuleBridge>
-  {({ data, resolveDataPath }) => <Module data={data} resolveDataPath={resolveDataPath} />}
-</LayoutModuleBridge>;
-```
-
-`data` and `resolveDataPath` only exist inside the render prop.
+Do not invent APIs such as `requestDataSomehow()` or `window.resolveDataPath`. `data` and
+`resolveDataPath` exist only in the `LayoutModuleBridge` render prop; pass them to nested components
+from there.
 
 Source: `src/bridge/iframe/LayoutModuleBridge.tsx`.
 
@@ -373,12 +377,34 @@ Source: `src/bridge/iframe/LayoutModuleBridge.tsx`.
 
 `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 module is a `.html` document
-delivery, not a script entry; the host is rendering it through `RemoteModuleFrame` (bare `<iframe>`s
+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 problem.
+resolve to `null` and `children` renders, so a stuck fallback is always a host, origin, or frame
+version problem.
+
+Source: `src/bridge/iframe/createModuleBridge.ts`, `src/bridge/origin.ts`, `src/bridge/protocol.ts`.
+
+### [HIGH] Viewport-relative height under dynamic height
+
+Wrong: the module root uses `height: 100vh` or `min-height: 100vh` (or `height: 100%` on `html` /
+`body` / root) regardless of context. With dynamic height on, the bridge reports the iframe's own
+height, so the module can never shrink. And because the reported height includes the frame
+document's `body`/ancestor margin and padding, `100vh` or `min-height: 100vh` combined with any body
+margin or padding reports a height larger than the iframe, so the iframe grows on every report.
+
+Correct: switch to `auto` when `context?.dynamicHeight` is true:
+
+```tsx
+const sizing = context?.dynamicHeight ? 'content' : 'viewport';
+// root: height: sizing === 'content' ? 'auto' : '100vh'
+//       min-height: sizing === 'content' ? 'auto' : '100vh'
+```
 
-Source: `src/bridge/iframe/createModuleBridge.ts`, `src/bridge/origin.ts`.
+Source: `src/bridge/protocol.ts` (`remoteModuleContextSchema.dynamicHeight`),
+`src/bridge/host/RemoteModuleFrame.tsx`.
 
 ### [HIGH] `DataSourceField` on a non-string property, or read as the resolved value
 
@@ -397,19 +423,6 @@ Spell `'DataSourceField'` exactly; module-supplied field components are not poss
 
 ### [HIGH] `key` uses the wrong charset or collides with another module
 
-Wrong:
-
-```ts
-defineLayoutModule({ key: 'risk-summary' /* ... */ }); // hyphens
-defineLayoutModule({ key: 'Risk_Summary' /* ... */ }); // uppercase
-```
-
-Correct:
-
-```ts
-defineLayoutModule({ key: 'risk_summary' /* ... */ });
-```
-
 `key` must match `^[a-z0-9_]+$` and be unique within the app — it's embedded verbatim into a
 persisted module identity string and DOM ids. A bad charset fails zod validation at build time
 (`closeBundle`); a duplicate throws
@@ -470,28 +483,11 @@ Source: `src/vite-plugin.ts` (`checkDeliveryExists`).
 
 ### [MEDIUM] `manifestPath` set to a directory instead of a file
 
-Wrong:
-
-```ts
-personaLayoutModules({ manifestPath: '/manifests/', modules: [] });
-```
-
-Correct:
-
-```ts
-personaLayoutModules({ manifestPath: '/manifests/my-app.json', modules: [] });
-```
-
-`manifestPath` must include the full JSON file name — it defaults to `DEFAULT_MANIFEST_PATH`
-(`/_layout_modules_manifest.json`). A leading `/` is optional and stripped either way.
-
-Code outside `vite.config.ts` that needs the default path (e.g. a subapp server adding CORS on the
-manifest route) should import the constant from the runtime-safe `.` entry rather than hardcoding it
-— this avoids pulling in Vite:
-
-```ts
-import { DEFAULT_MANIFEST_PATH } from '@persona/layout-editor-remote-module';
-```
+Use a file path such as `/manifests/my-app.json`, not a directory such as `/manifests/`.
+`manifestPath` defaults to `DEFAULT_MANIFEST_PATH` (`/_layout_modules_manifest.json`); a leading `/`
+is optional and stripped either way. Code outside `vite.config.ts` that needs the default (e.g. a
+subapp server adding CORS on the manifest route) should import `DEFAULT_MANIFEST_PATH` from the
+runtime-safe `.` entry to avoid pulling in Vite.
 
 Source: `src/vite-plugin.ts` (`PersonaLayoutModulesOptions.manifestPath` doc comment),
 `src/manifest-path.ts`.