@persona/layout-editor-remote-module 0.0.0-bootstrap.0 → 0.5.0

package/skills/getting-started/SKILL.md

@@ -0,0 +1,371 @@
+---
+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.
+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.
+
+This package is publicly available from the npm registry.
+
+## Install
+
+```sh
+yarn add @persona/layout-editor-remote-module
+```
+
+`vite`, `esbuild`, and `zod` are peer dependencies; `react` / `react-dom` (`^17 || ^18 || ^19`) are
+optional peers needed only by the `bridge-frame` entry. Add `esbuild` to your own `devDependencies`
+if your package manager warns about an unmet peer — the plugin's dev-mode bundling calls esbuild
+directly and should resolve to the same copy Vite already pulls in.
+
+## Setup (vite.config.ts)
+
+```ts
+import { defineConfig } from 'vite';
+import {
+  defineLayoutModule,
+  personaLayoutModules,
+} from '@persona/layout-editor-remote-module/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    personaLayoutModules({
+      modules: [
+        defineLayoutModule({
+          key: 'investigation_console',
+          displayName: 'Investigation Console',
+          descriptionShort: 'Full investigation workspace',
+          allowAddingToLayout: true,
+          layouts: ['case'],
+          defaultSize: { case: { width: 12, height: 40 } },
+          render: { entry: './index.html' },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+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`
+(`'build_your_own' | 'components' | 'management' | 'related_records'`; the host defaults to
+`build_your_own`), `icon` (an image path relative to the module's origin, such as
+`/assets/icon.svg`; the library shows a generic icon when it's omitted, fails to load, or is
+rejected as a cross-origin or non-http(s) URL), `internalUsersOnly` (a hint the host may use to
+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.
+
+## Core Patterns
+
+### 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:
+
+```ts
+defineLayoutModule({
+  key: 'investigation_console',
+  displayName: 'Investigation Console',
+  descriptionShort: 'Full investigation workspace',
+  allowAddingToLayout: true,
+  layouts: ['case'],
+  defaultSize: { case: { width: 12, height: 40 } },
+  render: { entry: './index.html', path: '/embed/investigations/console' },
+});
+```
+
+If the `.html` file is already one of the app's own build entries (its main `index.html`), the
+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
+config panel:
+
+```ts
+import { z } from 'zod';
+
+defineLayoutModule({
+  // ...
+  configSchema: z.object({
+    threshold: z.number().min(0).max(1).default(0.7),
+  }),
+});
+```
+
+Keep `configSchema` to a plain data shape (objects, primitives, enums, arrays) — it crosses the wire
+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:
+
+```ts
+defineLayoutModule({
+  // ...
+  configSchema: z.object({
+    threshold: z.number().min(0).max(1).default(0.7),
+    title: z.string().optional(),
+  }),
+  uiConfigSchema: {
+    'ui:order': ['title', 'threshold'],
+    threshold: { 'ui:widget': 'range' },
+  },
+});
+```
+
+### `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:
+
+```tsx
+import { LayoutModuleBridge } from '@persona/layout-editor-remote-module/bridge-frame';
+
+export function App() {
+  return (
+    <LayoutModuleBridge fallback={<Spinner />}>
+      {({ data, context, resolveDataPath }) => (
+        <RiskSummary data={data} context={context} resolveDataPath={resolveDataPath} />
+      )}
+    </LayoutModuleBridge>
+  );
+}
+```
+
+- `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` 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
+  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
+  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).
+- A render error thrown inside `children` is caught, reported to the host, and `fallback` is shown.
+- 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`).
+
+#### Host context
+
+`RemoteModuleContext` (exported as a type from `bridge-frame`) has:
+
+- `layoutType` — `'account' | 'case' | 'transaction'`, the layout the module is placed on.
+- `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.
+
+`context` is `null` only when the document is not embedded (opened directly in a tab).
+
+```tsx
+import {
+  LayoutModuleBridge,
+  type RemoteModuleContext,
+} from '@persona/layout-editor-remote-module/bridge-frame';
+
+function RiskSummary({ context }: { context: RemoteModuleContext | null }) {
+  if (!context?.layoutObjectId) {
+    return <EmptyState />;
+  }
+  return <RiskScore caseId={context.layoutObjectId} readOnly={context.isReadOnly} />;
+}
+```
+
+#### 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.
+
+## Common Mistakes
+
+### [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.
+
+Source: `src/bridge/iframe/LayoutModuleBridge.tsx`.
+
+### [MEDIUM] Module renders forever in `fallback` 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 module is a `.html` document
+delivery, not a script entry; 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.
+
+Source: `src/bridge/iframe/createModuleBridge.ts`, `src/bridge/origin.ts`.
+
+### [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
+`duplicate module key "..." — keys must be unique within an app`. Never change a released module's
+`key` — it's written into saved layouts.
+
+Source: `src/schema.ts` (`moduleKeySchema`), `src/vite-plugin.ts` (`assertUniqueKeys`).
+
+### [HIGH] `defaultSize` missing an entry for a listed layout
+
+Wrong:
+
+```ts
+defineLayoutModule({
+  layouts: ['case', 'account'],
+  defaultSize: { case: { width: 4, height: 20 } }, // no `account` entry
+});
+```
+
+Correct:
+
+```ts
+defineLayoutModule({
+  layouts: ['case', 'account'],
+  defaultSize: {
+    case: { width: 4, height: 20 },
+    account: { width: 6, height: 24 },
+  },
+});
+```
+
+The manifest schema requires an entry in `defaultSize` for every layout named in `layouts`; a
+missing one fails validation in `closeBundle` with
+`defaultSize must have an entry for every layout in \`layouts\``. This error surfaces at build time,
+not at the defineLayoutModule call site.
+
+This requirement applies to each listed layout; an empty `layouts` imposes no `defaultSize`
+requirement, and the host falls back to its own default size.
+
+Source: `src/schema.ts` (`remoteModuleRegistrationManifestV1Schema` `.refine`).
+
+### [MEDIUM] `render.entry` doesn't resolve to a real file
+
+`personaLayoutModules` fails fast in `configResolved` — before running a full build — when an entry
+path doesn't exist on disk: `render "..." does not resolve to a file (...)`. This is nearly always a
+relative-path mistake: `entry` resolves against the Vite **root**, not against `vite.config.ts`'s
+directory, so a non-default `root` in the same config changes what a given relative `entry` points
+at.
+
+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/esbuild:
+
+```ts
+import { DEFAULT_MANIFEST_PATH } from '@persona/layout-editor-remote-module';
+```
+
+Source: `src/vite-plugin.ts` (`PersonaLayoutModulesOptions.manifestPath` doc comment),
+`src/manifest-path.ts`.