@persona/layout-editor-remote-module 0.5.0 → 0.5.2

package/README.md

@@ -1,8 +1,8 @@
 # @persona/layout-editor-remote-module
 
 Shared manifest format and Vite plugin for remotely-defined dashboard layout modules — used by
-app-builder Apps and `sa-*` subapps to declare a layout module directly in their own
-`vite.config.ts`, without editing persona-web.
+Persona dashboard apps to declare a layout module directly in a typical app's `vite.config.ts`,
+without editing the host.
 
 ## Install
 
@@ -81,6 +81,23 @@ import { RemoteModuleFrame } from '@persona/layout-editor-remote-module/bridge-h
 
 The required `sandbox` value is chosen by the host.
 
+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:
+
+```tsx
+import {
+  LayoutModuleBridge,
+  personaDashboardHostOrigins,
+} from '@persona/layout-editor-remote-module/bridge-frame';
+
+<LayoutModuleBridge
+  allowedHostOrigins={(origin) => personaDashboardHostOrigins(origin) || myDevHost(origin)}
+>
+  {({ data }) => <RiskSummary data={data} />}
+</LayoutModuleBridge>;
+```
+
 The document entry uses `LayoutModuleBridge` as a render-prop component:
 
 ```tsx
@@ -108,11 +125,11 @@ cannot derive itself:
 iframe it arrives through `ready()`, `getContext()`, and the `context` render prop (all
 `RemoteModuleContext | null` until init).
 
-The host still appends `access_token`, `environment_id`, and `locale` as query parameters. The
-builder app or `sa-*` subapp hosting the module consumes and strips those parameters itself, so by
-the time `LayoutModuleBridge` runs they have already been handled; the bridge neither reads nor
-strips them. Keep the host iframe's `referrerpolicy` at its default `no-referrer` (or use
-`strict-origin`) so the URL parameters cannot leak through subsequent requests.
+The host still appends `access_token`, `environment_id`, and `locale` as query parameters. The app
+hosting the module consumes and strips those parameters itself, so by the time `LayoutModuleBridge`
+runs they have already been handled; the bridge neither reads nor strips them. Keep the host
+iframe's `referrerpolicy` at its default `no-referrer` (or use `strict-origin`) so the URL
+parameters cannot leak through subsequent requests.
 
 The bridge's security model is intentionally narrow:
 

package/dist/bridge-frame.d.mts

@@ -1,6 +1,9 @@
 import { n as Json, t as RemoteModuleContext } from "./protocol-edoRdXpF.mjs";
 import { ReactNode } from "react";
 
+//#region src/bridge/origin.d.ts
+declare function personaDashboardHostOrigins(origin: string): boolean;
+//#endregion
 //#region src/bridge/iframe/createModuleBridge.d.ts
 type ModuleBridgeInitPayload = {
   data: Json;
@@ -42,4 +45,4 @@ declare function LayoutModuleBridge({
   children
 }: LayoutModuleBridgeProps): ReactNode;
 //#endregion
-export { type Json, LayoutModuleBridge, type LayoutModuleBridgeProps, type LayoutModuleBridgeRenderProps, type RemoteModuleContext };
+export { type Json, LayoutModuleBridge, type LayoutModuleBridgeProps, type LayoutModuleBridgeRenderProps, type RemoteModuleContext, personaDashboardHostOrigins };

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-DMsysRFd.mjs";
+import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-Dz3ZX59L.mjs";
 import { Component, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
@@ -347,4 +347,4 @@ function LayoutModuleBridge({ allowedHostOrigins, resolveTimeoutMs, observeHeigh
 }
 
 //#endregion
-export { LayoutModuleBridge };
+export { LayoutModuleBridge, personaDashboardHostOrigins };

package/dist/bridge-host.mjs

@@ -1,4 +1,4 @@
-import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-DMsysRFd.mjs";
+import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-Dz3ZX59L.mjs";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 

package/dist/{define-Dt8sbrVO.d.mts → define-C-3P4CFz.d.mts}

@@ -79,31 +79,20 @@ type RemoteModuleRegistrationManifestV1Schema = typeof remoteModuleRegistrationM
 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 from one side
- * to whatever a consumer (e.g. persona-web's own `JsonSchemaObject`) does with
- * it on the other.
+ * this package only needs to carry what `z.toJSONSchema()` emits for consumers
+ * to validate or render.
  */
 type JsonSchemaObject = Record<string, unknown>;
-/**
- * Mirrors persona-web's `LayoutType`
- * (front-end/dashboard/modules/lib/types.ts).
- */
+/** Mirrors the host's supported layout values. */
 type LayoutType = z.infer<typeof layoutTypeSchema>;
-/**
- * Mirrors persona-web's `ModuleBadge`
- * (front-end/dashboard/modules/lib/config-constants.tsx).
- */
+/** Mirrors the host's supported module badges. */
 type ModuleBadge = z.infer<typeof moduleBadgeSchema>;
-/**
- * Mirrors persona-web's `ModuleCategory` values
- * (front-end/dashboard/modules/lib/module-library-config.ts).
- */
+/** Mirrors the host's module-library categories. */
 type ModuleCategory = z.infer<typeof moduleCategorySchema>;
 /**
- * Options passed to a remote module's `defaultConfig` export. Deliberately
- * narrower than persona-web's own `ModuleDefaultConfigOptions` — the migration
- * flags on that type (e.g. `unifiedDataDisplayEnabled`) are host-internal
- * scaffolding a remote module has no business branching on.
+ * Options passed to a remote module's `defaultConfig` export. Narrower than the
+ * host's default-config options; host-internal flags are not exposed to remote
+ * modules.
  */
 interface RemoteModuleDefaultConfigOptions {
   layoutType: LayoutType;
@@ -119,7 +108,7 @@ type RemoteModuleDelivery = z.infer<typeof remoteDeliverySchema>;
  * optional and feature-detected by name — see the "one URL, conventional
  * named exports" design decision. Rendering/sandboxing `render` is out of
  * scope for this package; only `defaultConfig` has a concrete consumer here
- * (persona-web's default-config loader). Not applicable to a `document`
+ * (the host's default-config loader). Not applicable to a `document`
  * delivery — nothing is ever imported for those, so none of these exports are
  * reachable.
  */
@@ -133,10 +122,8 @@ interface RemoteModuleExports {
  * Wire format for a remotely-defined layout module. Must stay
  * JSON-serializable: no functions, no ReactNode, no zod.
  *
- * Producers: `defineLayoutModule()` + the Vite plugin (this package), or
- * app-builder's own build pipeline using the same shape.
- * Consumers: persona-web's `manifestToRegistration()`
- * (front-end/dashboard/modules/lib/remote/adapt.ts).
+ * Producers: `defineLayoutModule()` and this package's Vite plugin.
+ * Consumers: the host application.
  */
 type RemoteModuleRegistrationManifestV1 = z.infer<typeof remoteModuleRegistrationManifestV1Schema>;
 type JsonObject = {

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as JsonSchemaObject, c as ModuleCategory, d as RemoteModuleExports, f as RemoteModuleRegistrationManifestV1, i as Json, l as RemoteModuleDefaultConfigOptions, m as remoteModuleRegistrationManifestV1Schema, n as LayoutModuleEntry, o as LayoutType, p as RemoteModuleRegistrationManifestV1Schema, r as defineLayoutModule, s as ModuleBadge, t as LayoutModuleDefinitionInput, u as RemoteModuleDelivery } from "./define-Dt8sbrVO.mjs";
+import { a as JsonSchemaObject, c as ModuleCategory, d as RemoteModuleExports, f as RemoteModuleRegistrationManifestV1, i as Json, l as RemoteModuleDefaultConfigOptions, m as remoteModuleRegistrationManifestV1Schema, n as LayoutModuleEntry, o as LayoutType, p as RemoteModuleRegistrationManifestV1Schema, r as defineLayoutModule, s as ModuleBadge, t as LayoutModuleDefinitionInput, u as RemoteModuleDelivery } from "./define-C-3P4CFz.mjs";
 import { z } from "zod";
 
 //#region src/manifest-path.d.ts

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-BeI8GdXS.mjs";
+import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-Bc3ZwB8y.mjs";
 import { z } from "zod";
 
 //#region src/parse.ts

package/dist/{protocol-DMsysRFd.mjs → protocol-Dz3ZX59L.mjs}

@@ -2,11 +2,9 @@ import { z } from "zod";
 
 //#region src/bridge/origin.ts
 const dashboardHostOriginPattern = /^https:\/\/([a-z0-9-]+\.)*withpersona(-staging)?\.com$/;
-const pagesHostOriginPattern = /^https:\/\/[a-z0-9-]+\.persona-web\.pages\.dev$/;
-const coderHostOriginPattern = /^https:\/\/[a-z0-9-]+\.coder\.development\.personerds\.com$/;
 const localHostOriginPattern = /^http:\/\/(?:localhost|127\.0\.0\.1):\d+$/;
 function personaDashboardHostOrigins(origin) {
-	return dashboardHostOriginPattern.test(origin) || pagesHostOriginPattern.test(origin) || coderHostOriginPattern.test(origin) || localHostOriginPattern.test(origin);
+	return dashboardHostOriginPattern.test(origin) || localHostOriginPattern.test(origin);
 }
 function resolveAllowedHostOrigins(allowedHostOrigins) {
 	if (allowedHostOrigins === void 0) return personaDashboardHostOrigins;
@@ -32,10 +30,8 @@ function assertNotSelfOrigin(moduleOrigin) {
 //#endregion
 //#region src/schema.ts
 /**
-* Mirrors persona-web's `LAYOUT_COLUMN_TOTAL`
-* (front-end/dashboard/modules/lib/constants.ts). The enum schemas below
-* mirror persona-web's corresponding enum values and are kept in sync by hand;
-* this package has no dependency on persona-web.
+* Mirrors the host's layout grid column count; the enum schemas below must
+* match the host's values.
 */
 const MAX_GRID_COLUMNS = 12;
 const layoutTypeSchema = z.enum([

package/dist/{schema-BeI8GdXS.mjs → schema-Bc3ZwB8y.mjs}

@@ -28,10 +28,8 @@ const DEFAULT_MANIFEST_PATH = "/_layout_modules_manifest.json";
 //#endregion
 //#region src/schema.ts
 /**
-* Mirrors persona-web's `LAYOUT_COLUMN_TOTAL`
-* (front-end/dashboard/modules/lib/constants.ts). The enum schemas below
-* mirror persona-web's corresponding enum values and are kept in sync by hand;
-* this package has no dependency on persona-web.
+* Mirrors the host's layout grid column count; the enum schemas below must
+* match the host's values.
 */
 const MAX_GRID_COLUMNS = 12;
 const layoutTypeSchema = z.enum([

package/dist/vite-plugin.d.mts

@@ -1,4 +1,4 @@
-import { n as LayoutModuleEntry, r as defineLayoutModule, t as LayoutModuleDefinitionInput } from "./define-Dt8sbrVO.mjs";
+import { n as LayoutModuleEntry, r as defineLayoutModule, t as LayoutModuleDefinitionInput } from "./define-C-3P4CFz.mjs";
 import { Plugin } from "vite";
 
 //#region src/vite-plugin.d.ts
@@ -33,7 +33,7 @@ interface PersonaLayoutModulesOptions {
  * wires every `code`-delivered entry into the build as an addressable ESM
  * chunk, ensures every `document`-delivered (`.html`) entry is actually
  * built/served, and emits a `RemoteModuleRegistrationManifestV1[]` document
- * persona-web can intake.
+ * the host can consume.
  *
  * Modules are configured directly here, not discovered by globbing the
  * source tree — a module IS whatever's in `options.modules`, full stop.

package/dist/vite-plugin.mjs

@@ -1,4 +1,4 @@
-import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-BeI8GdXS.mjs";
+import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-Bc3ZwB8y.mjs";
 import { z } from "zod";
 import { build } from "esbuild";
 import { existsSync } from "node:fs";
@@ -123,7 +123,7 @@ function ensureRemoteShimFiles() {
 * wires every `code`-delivered entry into the build as an addressable ESM
 * chunk, ensures every `document`-delivered (`.html`) entry is actually
 * built/served, and emits a `RemoteModuleRegistrationManifestV1[]` document
-* persona-web can intake.
+* the host can consume.
 *
 * Modules are configured directly here, not discovered by globbing the
 * source tree — a module IS whatever's in `options.modules`, full stop.
@@ -135,15 +135,17 @@ function personaLayoutModules(options) {
 	let definitions = [];
 	return {
 		async closeBundle() {
-			if (definitions.length === 0 || resolvedConfig.command !== "build") return;
-			const outDir = path.isAbsolute(resolvedConfig.build.outDir) ? resolvedConfig.build.outDir : path.resolve(root, resolvedConfig.build.outDir);
+			const envConfig = this.environment?.config;
+			if (definitions.length === 0 || envConfig?.command !== "build") return;
+			if (envConfig.consumer !== "client") return;
+			const outDir = path.isAbsolute(envConfig.build.outDir) ? envConfig.build.outDir : path.resolve(root, envConfig.build.outDir);
 			const input = {};
 			for (const definition of definitions) if (definition.render.kind === "code") input[entryNameFor(definition)] = definition.render.absolutePath;
 			let emitted = [];
 			if (Object.keys(input).length > 0) {
 				const shimAlias = await ensureRemoteShimFiles();
 				const result = await build$1({
-					base: resolvedConfig.base,
+					base: envConfig.base,
 					build: {
 						emptyOutDir: false,
 						outDir,
@@ -159,14 +161,14 @@ function personaLayoutModules(options) {
 					mode: "production",
 					plugins: options.modulePlugins?.() ?? [],
 					resolve: { alias: {
-						...resolveAliasForEsbuild(resolvedConfig),
+						...resolveAliasForEsbuild(envConfig),
 						...shimAlias
 					} },
 					root
 				});
 				emitted = (Array.isArray(result) ? result : [result]).flatMap((output) => "output" in output ? output.output : []);
 			}
-			const base = resolvedConfig.base ?? "/";
+			const base = envConfig.base ?? "/";
 			const manifests = [];
 			for (const definition of definitions) {
 				const render = resolveManifestDelivery(definition, definition.render, emitted, root, base);
@@ -188,15 +190,18 @@ function personaLayoutModules(options) {
 			await mkdir(path.dirname(manifestFilePath), { recursive: true });
 			await writeFile(manifestFilePath, JSON.stringify({ modules: manifests }, null, 2), "utf8");
 		},
-		async config(config, env) {
+		async config(config) {
 			root = config.root ? path.resolve(config.root) : process.cwd();
 			definitions = options.modules.map((input) => ({
 				definitionFilePath: input.key,
 				input,
 				render: resolveEntry(root, input.render)
 			}));
+		},
+		configEnvironment(name, envConfig, env) {
 			if (env.command !== "build") return;
-			const existingInputs = absoluteInputPaths(config, root);
+			if ((envConfig.consumer ?? (name === "client" ? "client" : "server")) !== "client") return;
+			const existingInputs = absoluteInputPaths(envConfig, root);
 			const toInject = {};
 			for (const definition of definitions) {
 				const delivery = definition.render;
@@ -205,14 +210,10 @@ function personaLayoutModules(options) {
 					existingInputs.add(delivery.absolutePath);
 				}
 			}
-			if (Object.keys(toInject).length > 0) {
-				config.build ??= {};
-				config.build.rollupOptions ??= {};
-				config.build.rollupOptions.input = {
-					...toInputRecord(config.build.rollupOptions.input, root),
-					...toInject
-				};
-			}
+			if (Object.keys(toInject).length > 0) return { build: { rollupOptions: { input: {
+				...toInputRecord(envConfig.build?.rollupOptions?.input, root),
+				...toInject
+			} } } };
 		},
 		configResolved(config) {
 			resolvedConfig = config;
@@ -366,8 +367,7 @@ function matchDevBundleRequest(url, definitions) {
 * array) into an array of `{ find, replacement }`. esbuild's own `alias`
 * option only accepts exact string keys (no RegExp, no partial-path
 * matching) — a real limitation this doesn't try to hide, just the common
-* case: a plain string-to-string alias map, which is what every `sa-*`
-* subapp's `vite.config.ts` actually uses.
+* case: a plain string-to-string alias map, which many apps use.
 */
 function resolveAliasForEsbuild(resolvedConfig) {
 	const alias = {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.5.0",
-  "description": "Shared manifest format, Vite plugin, and host/iframe bridge for remotely-defined dashboard layout modules (app-builder Apps and sa-* subapps).",
+  "version": "0.5.2",
+  "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",
   "types": "./dist/index.d.mts",
@@ -41,7 +41,7 @@
     "esbuild": ">=0.21.0 <1",
     "react": "^17 || ^18 || ^19",
     "react-dom": "^17 || ^18 || ^19",
-    "vite": "^5 || ^6 || ^7 || ^8",
+    "vite": "^6 || ^7 || ^8",
     "zod": "^4.3"
   },
   "peerDependenciesMeta": {

package/skills/getting-started/SKILL.md

@@ -1,37 +1,27 @@
 ---
 name: getting-started
 description: >
-  Wire up @persona/layout-editor-remote-module in a sa-* subapp or app-builder app: register
-  personaLayoutModules in vite.config.ts, author modules with defineLayoutModule using a document
-  (.html) render delivery, add a zod configSchema and an RJSF uiConfigSchema, 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.
+  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.
 metadata:
   type: core
   library: '@persona/layout-editor-remote-module'
-  library_version: '0.4.0'
-sources:
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/vite-plugin.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/define.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/schema.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/manifest-path.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/bridge/iframe/index.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/bridge/iframe/LayoutModuleBridge.tsx'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/bridge/iframe/createModuleBridge.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/src/bridge/protocol.ts'
-  - 'persona-id/persona-layout-editor:packages/remote-module/README.md'
 ---
 
 # Getting started with @persona/layout-editor-remote-module
 
-Shared manifest format and Vite plugin for remotely-defined dashboard layout modules — lets a `sa-*`
-subapp or app-builder App declare a layout module directly in its own `vite.config.ts`, without
-editing persona-web. The plugin builds each module and emits a
-`{ modules: RemoteModuleRegistrationManifestV1[] }` JSON document persona-web fetches and intakes.
+Shared manifest format and Vite plugin for remotely-defined dashboard layout modules — lets Persona
+dashboard apps declare a layout module directly in a typical app's `vite.config.ts`, without editing
+the host. The plugin builds each module and emits a
+`{ modules: RemoteModuleRegistrationManifestV1[] }` JSON document the host fetches and validates.
 
 This package is publicly available from the npm registry.
 
@@ -92,11 +82,11 @@ not relative to `vite.config.ts`'s own directory when `root` is overridden elsew
 
 ### Document delivery — iframed page
 
-A module's `render.entry` must end in `.html`: persona-web iframes it rather than importing
-anything. Any other extension (`.ts`/`.tsx`/`.js`) builds as a `code` delivery, which the plugin and
-manifest still accept but persona-web does not render yet — the module shows up in the library and
-renders nothing. Use `path` for a client-routed SPA whose `index.html` already renders the whole app
-— it names the logical route the SPA's own router should land on, not the file's build output path:
+A module's `render.entry` must end in `.html`: the host iframes it rather than importing anything.
+Any other extension (`.ts`/`.tsx`/`.js`) builds as a `code` delivery, which the plugin and manifest
+still accept but the host does not render yet — the module shows up in the library and renders
+nothing. Use `path` for a client-routed SPA whose `index.html` already renders the whole app — it
+names the logical route the SPA's own router should land on, not the file's build output path:
 
 ```ts
 defineLayoutModule({
@@ -115,7 +105,7 @@ plugin detects that and doesn't inject it again.
 
 ### `configSchema` — validated module configuration
 
-Author config as zod; the plugin converts it to JSON Schema (`z.toJSONSchema()`) for persona-web's
+Author config as zod; the plugin converts it to JSON Schema (`z.toJSONSchema()`) for the host's
 config panel:
 
 ```ts
@@ -134,9 +124,9 @@ as static JSON Schema, not re-executed as zod on the consuming side.
 
 ### `uiConfigSchema` — config panel layout
 
-persona-web renders the config panel with RJSF. Pass an RJSF `uiSchema` (widget choice, field order,
-labels) as `uiConfigSchema`; it is already plain data, so the plugin copies it into the manifest
-unchanged:
+The host renders the config panel with RJSF. Pass an RJSF `uiSchema` as `uiConfigSchema`; it is
+already plain data, so the plugin copies it into the manifest unchanged. Its top-level keys are the
+`configSchema` property names, and each one holds that property's `ui:*` entries:
 
 ```ts
 defineLayoutModule({
@@ -152,11 +142,109 @@ defineLayoutModule({
 });
 ```
 
+- **Labels and help text** come from the property's JSON Schema `title` / `description` — set them
+  with zod's `.meta({ title, description })` — and fall back to the property name. Override them per
+  field with `'ui:options': { title, description }`; the description shows as the label's tooltip.
+- **Field order** is `'ui:order'` at the top level (use `'*'` for "everything else").
+- **Controls are picked from the schema** without a `uiConfigSchema` entry: an enum renders as a
+  dropdown, an array of enum values with `uniqueItems: true` in its JSON Schema as a multi-select, a
+  boolean as a checkbox, and an array of objects as a list whose items open in an editing panel.
+- **Everything is JSON.** The manifest is static JSON, so function-valued RJSF options
+  (`createItem`, `itemLabel`, …) and custom React fields/widgets cannot be supplied by a module —
+  only the `ui:field` names and options the host already registers, listed below.
+
+#### `DataSourceField` — pick a value from the record
+
+`'ui:field': 'DataSourceField'` turns a property into the host's data-source input: an
+autocompleting method-chain input (e.g. `current_case.id`, or `query.<variable>` for a layout
+variable) checked against the platform schema. Declare the property as a **string** — the field then
+stores the chain itself as a string:
+
+```ts
+defineLayoutModule({
+  // ...
+  layouts: ['account'],
+  defaultSize: { account: { width: 6, height: 24 } },
+  configSchema: z.object({
+    accountId: z.string().optional(),
+  }),
+  uiConfigSchema: {
+    accountId: {
+      'ui:field': 'DataSourceField',
+      'ui:options': {
+        title: 'Account ID',
+        description: 'Account whose transactions are monitored',
+      },
+    },
+  },
+});
+```
+
+`ui:options` it reads:
+
+- `title`, `description` — label and tooltip; default to the schema's `title` / `description`.
+- `expectedSchemaType` — the platform object type the chain must resolve to (e.g. `'case'`,
+  `'user'`); a chain resolving to another type is flagged. Unset means any chain is accepted. An
+  empty value is never validated.
+- `rootPath` — limits validation to chains under one top-level property (e.g. `'current_case'`).
+  Only set it when `layouts` names a single layout that has that root; a chain outside `rootPath`
+  still saves but is not validated.
+
+The config holds the **chain, not its value**. Resolve it at render time with `resolveDataPath` from
+`LayoutModuleBridge` (below), skipping an unset field:
+
+```tsx
+import { useEffect, useState } from 'react';
+import {
+  type Json,
+  type LayoutModuleBridgeRenderProps,
+} from '@persona/layout-editor-remote-module/bridge-frame';
+
+function TransactionMonitor({
+  data,
+  resolveDataPath,
+}: Pick<LayoutModuleBridgeRenderProps, 'data' | 'resolveDataPath'>) {
+  const chain = (data as { accountId?: string } | null)?.accountId;
+  const [accountId, setAccountId] = useState<Json>(null);
+
+  useEffect(() => {
+    setAccountId(null);
+    if (!chain) return;
+    let current = true;
+    resolveDataPath(chain).then(
+      (value) => current && setAccountId(value),
+      () => current && setAccountId(null),
+    );
+    return () => {
+      current = false;
+    };
+  }, [chain, resolveDataPath]);
+
+  // ...
+}
+```
+
+The host pushes config updates into the mounted module, so the chain can change or be cleared at any
+time: reset the resolved value whenever it does, and ignore responses to an outdated chain.
+`resolveDataPath` resolves to `null` when the chain can't be resolved on the current record and
+rejects on a host error or timeout, so handle both.
+
+#### Other `ui:options`
+
+- `errorMessages` — per-keyword validation messages, e.g.
+  `{ 'ui:options': { errorMessages: { pattern: 'Use letters only.' } } }` (keys are JSON Schema
+  keywords: `pattern`, `minLength`, `maximum`, …).
+- On an enum multi-select: `unsetSelectsAll: true` shows an unset value as every option selected,
+  for a key whose absence means "all" and should stay absent.
+- On an array of objects: `identifierField` (item property that labels each row), `emptyText`,
+  `editLabel` (the editing panel's title), `listAriaLabel`, and `inlineItems: true` to render the
+  items inline instead of as a list with an editing panel.
+
 ### `bridge-frame` — talking to the host from the iframed document
 
-The host (persona-web / layout editor) renders a document-delivered module in an iframe and speaks
-to it over `postMessage`. Wrap the module's React root in `LayoutModuleBridge` from the
-`bridge-frame` entry; it owns the whole handshake and hands the module a render prop:
+The host renders a document-delivered module in an iframe and speaks to it over `postMessage`. Wrap
+the module's React root in `LayoutModuleBridge` from the `bridge-frame` entry; it owns the whole
+handshake and hands the module a render prop:
 
 ```tsx
 import { LayoutModuleBridge } from '@persona/layout-editor-remote-module/bridge-frame';
@@ -179,7 +267,7 @@ export function App() {
 - `context` (`RemoteModuleContext`) is where the module is rendered — host-owned facts the module
   cannot derive itself. It arrives with the initial data and re-renders whenever it changes (see
   below).
-- `resolveDataPath(dataPath, variableMap?)` returns `Promise<Json>`; the host (persona-web) owns the
+- `resolveDataPath(dataPath, variableMap?)` returns `Promise<Json>`; the host owns the
   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.
@@ -189,9 +277,23 @@ export function App() {
 - Mount exactly one `LayoutModuleBridge` per document.
 
 Props: `fallback?: ReactNode`, `observeHeight?: boolean` (default `true`),
-`resolveTimeoutMs?: number`, `allowedHostOrigins?` (only needed to embed from a host origin outside
-the built-in Persona allow-list — `*.withpersona.com`, staging, `*.persona-web.pages.dev`, Coder,
-`localhost`).
+`resolveTimeoutMs?: number`, `allowedHostOrigins?` (to add host origins outside the built-in
+allow-list). Built-in origins include `*.withpersona.com`, `*.withpersona-staging.com`, `localhost`,
+and `127.0.0.1`. Dev and preview dashboards must be added explicitly; compose the built-in predicate
+with an app-specific check:
+
+```tsx
+import {
+  LayoutModuleBridge,
+  personaDashboardHostOrigins,
+} from '@persona/layout-editor-remote-module/bridge-frame';
+
+<LayoutModuleBridge
+  allowedHostOrigins={(origin) => personaDashboardHostOrigins(origin) || myDevHost(origin)}
+>
+  {({ data }) => <RiskSummary data={data} />}
+</LayoutModuleBridge>;
+```
 
 #### Host context
 
@@ -223,11 +325,11 @@ function RiskSummary({ context }: { context: RemoteModuleContext | null }) {
 
 #### Access token and environment id
 
-The host still appends `access_token`, `environment_id`, and `locale` to the iframe `src`. The
-builder app or `sa-*` subapp hosting the module consumes and strips those parameters itself, so by
-the time `LayoutModuleBridge` runs they have already been handled; the bridge neither reads nor
-strips them. Keep the host iframe's `referrerpolicy` at its default `no-referrer` (or use
-`strict-origin`) so the URL parameters cannot leak through subsequent requests.
+The host still appends `access_token`, `environment_id`, and `locale` to the iframe `src`. The app
+hosting the module consumes and strips those parameters itself, so by the time `LayoutModuleBridge`
+runs they have already been handled; the bridge neither reads nor strips them. Keep the host
+iframe's `referrerpolicy` at its default `no-referrer` (or use `strict-origin`) so the URL
+parameters cannot leak through subsequent requests.
 
 ## Common Mistakes
 
@@ -276,6 +378,21 @@ resolve to `null` and `children` renders, so a stuck fallback is always a host/o
 
 Source: `src/bridge/iframe/createModuleBridge.ts`, `src/bridge/origin.ts`.
 
+### [HIGH] `DataSourceField` on a non-string property, or read as the resolved value
+
+Declare a `DataSourceField` property as `z.string()`. On a non-string property the host stores a
+structured data-source object instead of the chain string, and `resolveDataPath` only accepts a
+string — it resolves to `null`. On a string property the stored value is the method chain the user
+typed (e.g. `"current_account.id"`), not the account ID: pass `data.accountId` to `resolveDataPath`
+rather than using it directly.
+
+### [MEDIUM] A `ui:field` name the host doesn't register
+
+A `ui:field` name the host has no component for falls back to RJSF's default field for the
+property's type — no build or validation error, just a plain input instead of the intended control.
+Spell `'DataSourceField'` exactly; module-supplied field components are not possible (see
+"Everything is JSON" above).
+
 ### [HIGH] `key` uses the wrong charset or collides with another module
 
 Wrong: