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

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.
@@ -366,8 +366,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.1",
+  "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",

package/skills/getting-started/SKILL.md

@@ -1,37 +1,26 @@
 ---
 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, 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 +81,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 +104,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,7 +123,7 @@ 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,
+The host 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:
 
@@ -154,9 +143,9 @@ defineLayoutModule({
 
 ### `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 +168,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 +178,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 +226,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