@persona/layout-editor-remote-module 0.5.3 → 0.7.0

package/README.md

@@ -10,11 +10,7 @@ without editing the host.
 yarn add @persona/layout-editor-remote-module
 ```
 
-`vite`, `esbuild`, and `zod` are peer dependencies. The plugin's dev-mode bundling uses `esbuild`
-directly, and declaring it as a peer means it resolves to the same copy `vite` already pulls in
-rather than a second version. With Yarn's `node-modules` linker the hoisted transitive copy usually
-satisfies it; add `esbuild` to your own `devDependencies` if your package manager warns about an
-unmet peer.
+`vite` and `zod` are peer dependencies.
 
 The optional `react` and `react-dom` peer dependencies are required only when using the React bridge
 components.
@@ -42,9 +38,8 @@ export default defineConfig({
           allowAddingToLayout: true,
           layouts: ['case'],
           defaultSize: { case: { width: 4, height: 20 } },
-          // `.tsx`/`.js` — a `code` delivery, imported and rendered directly
-          // in the host's own React tree.
-          render: { entry: './src/layout-modules/risk-summary/render.tsx' },
+          // The host loads this HTML page in an iframe.
+          render: { entry: './src/layout-modules/risk-summary/index.html' },
         }),
       ],
     }),
@@ -55,9 +50,9 @@ 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.
 
-An `.html` entry (rather than `.tsx`/`.js`) is a `document` delivery instead — the host iframes it
-rather than importing anything. See `LayoutModuleEntry`'s doc comment in `src/define.ts` for the
-full contract, including the optional `path` field for a client-routed SPA.
+Entries must be `.html` documents, which the host loads in an iframe. Non-HTML entries fail during
+Vite config resolution. See `LayoutModuleEntry`'s doc comment in `src/define.ts` for the full
+contract, including the optional `path` field for a client-routed SPA.
 
 ## Communicating with the host
 
@@ -141,9 +136,9 @@ The bridge's security model is intentionally narrow:
   `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` and
-  `defaultConfig`'s `layoutType` can be layout types added later, so handle values you don't know.
-  Credentials remain in the iframe URL and are never handled through bridge messages.
+  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

@@ -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-BgGlnuFn.mjs";
+import { c as resolveAllowedHostOrigins, n as SOURCE, o as candidateParentOrigin, r as parseHostToModuleMessage, s as personaDashboardHostOrigins, t as PROTOCOL_VERSION } from "./protocol-Dr_M54Kt.mjs";
 import { Component, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 

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-BgGlnuFn.mjs";
+import { a as assertNotSelfOrigin, i as parseModuleToHostMessage, n as SOURCE, t as PROTOCOL_VERSION } from "./protocol-Dr_M54Kt.mjs";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 

package/dist/{define-D0nvEX_B.d.mts → define-Bxk_kfEr.d.mts}

@@ -19,15 +19,11 @@ declare const moduleBadgeSchema: z.ZodEnum<{
   new: "new";
 }>;
 /**
- * `code` (a chunk URL, direct-`import()`ed) and `document` (a page URL, host
- * iframes it instead) are mutually exclusive — a delivery is one or the
- * other, never both, never neither.
+ * The module's main view is a page URL that the host iframes.
  */
-declare const remoteDeliverySchema: z.ZodUnion<readonly [z.ZodObject<{
-  code: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+declare const remoteDeliverySchema: z.ZodObject<{
   document: z.ZodString;
-}, z.core.$strip>]>;
+}, z.core.$strip>;
 declare const remoteModuleRegistrationManifestV1Schema: z.ZodObject<{
   allowAddingToLayout: z.ZodBoolean;
   allowDynamicHeight: z.ZodOptional<z.ZodBoolean>;
@@ -43,6 +39,7 @@ declare const remoteModuleRegistrationManifestV1Schema: z.ZodObject<{
     management: "management";
     related_records: "related_records";
   }>>;
+  categoryCustom: z.ZodOptional<z.ZodString>;
   configSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   defaultSize: z.ZodRecord<z.ZodEnum<{
     account: "account";
@@ -64,12 +61,9 @@ declare const remoteModuleRegistrationManifestV1Schema: z.ZodObject<{
   }>>>;
   manifestVersion: z.ZodLiteral<"v1">;
   remote: z.ZodObject<{
-    css: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    render: z.ZodUnion<readonly [z.ZodObject<{
-      code: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
+    render: z.ZodObject<{
       document: z.ZodString;
-    }, z.core.$strip>]>;
+    }, z.core.$strip>;
   }, z.core.$strip>;
   uiConfigSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
@@ -89,36 +83,8 @@ type LayoutType = z.infer<typeof layoutTypeSchema>;
 type ModuleBadge = z.infer<typeof moduleBadgeSchema>;
 /** Mirrors the host's module-library categories. */
 type ModuleCategory = z.infer<typeof moduleCategorySchema>;
-/**
- * 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 {
-  /** Can be a layout type added after the module's release; handle values you don't know. */
-  layoutType: LayoutType | (string & {});
-  position?: {
-    x: number;
-    y: number;
-  };
-}
-/** See `RemoteModuleRegistrationManifestV1['remote']['render']`. */
+/** A page URL loaded by the host in an iframe. */
 type RemoteModuleDelivery = z.infer<typeof remoteDeliverySchema>;
-/**
- * Conventional named exports a `{ code }` delivery's module may provide. All
- * 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
- * (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.
- */
-interface RemoteModuleExports {
-  defaultConfig?: (opts: RemoteModuleDefaultConfigOptions) => {
-    config: Json;
-  };
-  render?: unknown;
-}
 /**
  * Wire format for a remotely-defined layout module. Must stay
  * JSON-serializable: no functions, no ReactNode, no zod.
@@ -138,9 +104,8 @@ type JsonValue = Json;
  * it carries a source/page path (`render`, resolved relative to the Vite root)
  * and a live zod schema (`configSchema`), which
  * the Vite plugin (./vite.ts) resolves into a `RemoteModuleRegistrationManifestV1`
- * at build time: a code entry becomes a hashed chunk URL, an html entry
- * becomes its (possibly `path`-overridden) served URL, and `configSchema`
- * becomes JSON Schema via `z.toJSONSchema()`.
+ * at build time: an html entry becomes its (possibly `path`-overridden)
+ * served URL, and `configSchema` becomes JSON Schema via `z.toJSONSchema()`.
  */
 interface LayoutModuleDefinitionInput {
   /**
@@ -154,6 +119,8 @@ interface LayoutModuleDefinitionInput {
   allowDynamicHeight?: boolean;
   badge?: ModuleBadge;
   category?: ModuleCategory;
+  /** Free-form module-library category label; takes precedence over `category` when both are set. */
+  categoryCustom?: string;
   /** Authored as zod; converted to JSON Schema by the plugin. */
   configSchema?: z.ZodType;
   defaultSize: Partial<Record<LayoutType, {
@@ -189,24 +156,17 @@ interface LayoutModuleDefinitionInput {
  * definition file anymore; modules are configured directly wherever
  * `personaLayoutModules()` is called (typically vite.config.ts).
  *
- * `entry`'s FILE EXTENSION decides delivery kind:
- *   - `.html` — a `document` delivery: the host iframes it instead of
- *     importing anything. The plugin ensures Vite actually builds/serves
- *     this file, detecting whether it's already one of the app's own build
- *     entries (e.g. its main `index.html`) and doing nothing extra if so —
- *     only injecting it into the build when it isn't already there.
- *   - anything else (`.ts`/`.tsx`/`.js`/`.jsx`) — a `code` delivery: built
- *     into a chunk and executed directly in the host's own React tree.
- *     Exports are feature-detected by conventional name — see
- *     `RemoteModuleExports` in types.ts.
+ * `entry` must point to an `.html` document that the host iframes. The plugin
+ * ensures Vite builds/serves the file, detecting whether it's already one of
+ * the app's own build entries (e.g. its main `index.html`) and injecting it
+ * into the build only when it isn't already there.
  *
- * `path` is only meaningful alongside an `.html` entry, for a client-routed
- * SPA whose `index.html` already renders the whole app: rather than iframing
+ * `path` is for a client-routed SPA whose `index.html` already renders the
+ * whole app: rather than iframing
  * the SPA's root, this names the LOGICAL route its own router should land on
  * (e.g. `/embed/runs/1`) — the final `document` URL IS that path, not the
  * html file's physical output path, since a static/SPA-fallback server
- * serves the same `index.html` either way. Ignored (and meaningless) for a
- * non-`.html` entry.
+ * serves the same `index.html` either way.
  */
 interface LayoutModuleEntry {
   entry: string;
@@ -221,4 +181,4 @@ interface LayoutModuleEntry {
  */
 declare function defineLayoutModule(input: LayoutModuleDefinitionInput): LayoutModuleDefinitionInput;
 //#endregion
-export { JsonSchemaObject as a, ModuleCategory as c, RemoteModuleExports as d, RemoteModuleRegistrationManifestV1 as f, Json as i, RemoteModuleDefaultConfigOptions as l, remoteModuleRegistrationManifestV1Schema as m, LayoutModuleEntry as n, LayoutType as o, RemoteModuleRegistrationManifestV1Schema as p, defineLayoutModule as r, ModuleBadge as s, LayoutModuleDefinitionInput as t, RemoteModuleDelivery as u };
+export { JsonSchemaObject as a, ModuleCategory as c, RemoteModuleRegistrationManifestV1Schema as d, remoteModuleRegistrationManifestV1Schema as f, Json as i, RemoteModuleDelivery as l, LayoutModuleEntry as n, LayoutType as o, defineLayoutModule as r, ModuleBadge as s, LayoutModuleDefinitionInput as t, RemoteModuleRegistrationManifestV1 as u };

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-D0nvEX_B.mjs";
+import { a as JsonSchemaObject, c as ModuleCategory, d as RemoteModuleRegistrationManifestV1Schema, f as remoteModuleRegistrationManifestV1Schema, i as Json, l as RemoteModuleDelivery, n as LayoutModuleEntry, o as LayoutType, r as defineLayoutModule, s as ModuleBadge, t as LayoutModuleDefinitionInput, u as RemoteModuleRegistrationManifestV1 } from "./define-Bxk_kfEr.mjs";
 import { z } from "zod";
 
 //#region src/manifest-path.d.ts
@@ -10,7 +10,7 @@ import { z } from "zod";
  * one place that actually uses it) so it can also be re-exported from the
  * runtime-safe `.` entry — a consumer wiring up something like CORS for the
  * manifest route in its own server, outside of vite.config.ts, needs this
- * default without pulling in vite/esbuild.
+ * default without pulling in Vite.
  */
 declare const DEFAULT_MANIFEST_PATH = "/_layout_modules_manifest.json";
 //#endregion
@@ -44,6 +44,7 @@ declare const remoteModuleManifestDocumentSchema: z.ZodObject<{
       management: "management";
       related_records: "related_records";
     }>>;
+    categoryCustom: z.ZodOptional<z.ZodString>;
     configSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     defaultSize: z.ZodRecord<z.ZodEnum<{
       account: "account";
@@ -65,12 +66,9 @@ declare const remoteModuleManifestDocumentSchema: z.ZodObject<{
     }>>>;
     manifestVersion: z.ZodLiteral<"v1">;
     remote: z.ZodObject<{
-      css: z.ZodOptional<z.ZodArray<z.ZodString>>;
-      render: z.ZodUnion<readonly [z.ZodObject<{
-        code: z.ZodString;
-      }, z.core.$strip>, z.ZodObject<{
+      render: z.ZodObject<{
         document: z.ZodString;
-      }, z.core.$strip>]>;
+      }, z.core.$strip>;
     }, z.core.$strip>;
     uiConfigSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   }, z.core.$strip>>;
@@ -95,4 +93,4 @@ declare function parseRemoteModuleManifest(json: unknown): RemoteModuleManifestD
 /** Non-throwing variant of `parseRemoteModuleManifest`. */
 declare function safeParseRemoteModuleManifest(json: unknown): RemoteModuleManifestParseResult;
 //#endregion
-export { DEFAULT_MANIFEST_PATH, type Json, type JsonSchemaObject, type LayoutModuleDefinitionInput, type LayoutModuleEntry, type LayoutType, type ModuleBadge, type ModuleCategory, type RemoteModuleDefaultConfigOptions, type RemoteModuleDelivery, type RemoteModuleExports, type RemoteModuleManifestDocument, RemoteModuleManifestParseError, type RemoteModuleManifestParseResult, type RemoteModuleRegistrationManifestV1, type RemoteModuleRegistrationManifestV1Schema, defineLayoutModule, parseRemoteModuleManifest, remoteModuleManifestDocumentSchema, remoteModuleRegistrationManifestV1Schema, safeParseRemoteModuleManifest };
+export { DEFAULT_MANIFEST_PATH, type Json, type JsonSchemaObject, type LayoutModuleDefinitionInput, type LayoutModuleEntry, type LayoutType, type ModuleBadge, type ModuleCategory, type RemoteModuleDelivery, type RemoteModuleManifestDocument, RemoteModuleManifestParseError, type RemoteModuleManifestParseResult, type RemoteModuleRegistrationManifestV1, type RemoteModuleRegistrationManifestV1Schema, defineLayoutModule, parseRemoteModuleManifest, remoteModuleManifestDocumentSchema, remoteModuleRegistrationManifestV1Schema, safeParseRemoteModuleManifest };

package/dist/index.mjs

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

package/dist/{protocol-BgGlnuFn.mjs → protocol-Dr_M54Kt.mjs}

@@ -63,15 +63,10 @@ const gridSizeSchema = z.object({
 	width: z.number().int().min(1).max(MAX_GRID_COLUMNS)
 });
 /**
-* `code` (a chunk URL, direct-`import()`ed) and `document` (a page URL, host
-* iframes it instead) are mutually exclusive — a delivery is one or the
-* other, never both, never neither.
+* The module's main view is a page URL that the host iframes.
 */
-const remoteDeliverySchema = z.union([z.object({ code: z.string().min(1) }), z.object({ document: z.string().min(1) })]);
-const remoteEntrySchema = z.object({
-	css: z.array(z.string()).optional(),
-	render: remoteDeliverySchema
-});
+const remoteDeliverySchema = z.object({ document: z.string().min(1) });
+const remoteEntrySchema = z.object({ render: remoteDeliverySchema });
 /**
 * Loose check shared by `configSchema` and `uiConfigSchema` — this validates
 * the manifest envelope, not the arbitrary object either one carries. Both
@@ -85,6 +80,7 @@ const remoteModuleRegistrationManifestV1Schema = z.object({
 	allowDynamicHeight: z.boolean().optional(),
 	badge: moduleBadgeSchema.optional(),
 	category: moduleCategorySchema.optional(),
+	categoryCustom: z.string().trim().min(1).max(80).optional(),
 	configSchema: looseObjectSchema.optional(),
 	defaultSize: z.partialRecord(layoutTypeSchema, gridSizeSchema),
 	descriptionShort: z.string().min(1),

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

@@ -21,7 +21,7 @@ function defineLayoutModule(input) {
 * one place that actually uses it) so it can also be re-exported from the
 * runtime-safe `.` entry — a consumer wiring up something like CORS for the
 * manifest route in its own server, outside of vite.config.ts, needs this
-* default without pulling in vite/esbuild.
+* default without pulling in Vite.
 */
 const DEFAULT_MANIFEST_PATH = "/_layout_modules_manifest.json";
 
@@ -61,15 +61,10 @@ const gridSizeSchema = z.object({
 	width: z.number().int().min(1).max(MAX_GRID_COLUMNS)
 });
 /**
-* `code` (a chunk URL, direct-`import()`ed) and `document` (a page URL, host
-* iframes it instead) are mutually exclusive — a delivery is one or the
-* other, never both, never neither.
+* The module's main view is a page URL that the host iframes.
 */
-const remoteDeliverySchema = z.union([z.object({ code: z.string().min(1) }), z.object({ document: z.string().min(1) })]);
-const remoteEntrySchema = z.object({
-	css: z.array(z.string()).optional(),
-	render: remoteDeliverySchema
-});
+const remoteDeliverySchema = z.object({ document: z.string().min(1) });
+const remoteEntrySchema = z.object({ render: remoteDeliverySchema });
 /**
 * Loose check shared by `configSchema` and `uiConfigSchema` — this validates
 * the manifest envelope, not the arbitrary object either one carries. Both
@@ -83,6 +78,7 @@ const remoteModuleRegistrationManifestV1Schema = z.object({
 	allowDynamicHeight: z.boolean().optional(),
 	badge: moduleBadgeSchema.optional(),
 	category: moduleCategorySchema.optional(),
+	categoryCustom: z.string().trim().min(1).max(80).optional(),
 	configSchema: looseObjectSchema.optional(),
 	defaultSize: z.partialRecord(layoutTypeSchema, gridSizeSchema),
 	descriptionShort: z.string().min(1),

package/dist/vite-plugin.d.mts

@@ -1,4 +1,4 @@
-import { n as LayoutModuleEntry, r as defineLayoutModule, t as LayoutModuleDefinitionInput } from "./define-D0nvEX_B.mjs";
+import { n as LayoutModuleEntry, r as defineLayoutModule, t as LayoutModuleDefinitionInput } from "./define-Bxk_kfEr.mjs";
 import { Plugin } from "vite";
 
 //#region src/vite-plugin.d.ts
@@ -12,28 +12,12 @@ interface PersonaLayoutModulesOptions {
    * either form resolves to the same path.
    */
   manifestPath?: string;
-  /**
-   * Plugins the production build of `code`-delivered layout-module entries
-   * needs (e.g. `react()`, `tailwindcss()`) — called once. These entries are
-   * built via a SEPARATE, isolated `vite.build()` call (see the
-   * `closeBundle` hook), deliberately not part of the app's own build graph
-   * — see its doc comment for why — so the app's own plugin list isn't
-   * inherited automatically. Omit if your modules only need plain TS/JSX
-   * (Vite's built-in esbuild transform already handles that with no plugin).
-   * `document` (`.html`) entries never need this — they run through the
-   * app's own build graph and its own configured plugins directly.
-   */
-  modulePlugins?: () => Plugin[];
   /** Every module this app registers — passed directly, not discovered. */
   modules: LayoutModuleDefinitionInput[];
 }
 /**
- * Vite plugin that takes a statically-declared list of layout modules
- * (`options.modules`, authored via `defineLayoutModule` — see ./define.ts),
- * 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
- * the host can consume.
+ * Vite plugin that ensures declared module documents are built/served and
+ * emits a `RemoteModuleRegistrationManifestV1[]` document for the host.
  *
  * 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,129 +1,13 @@
-import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-Bc3ZwB8y.mjs";
+import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-DU2LTDDC.mjs";
 import { z } from "zod";
-import { build } from "esbuild";
 import { existsSync } from "node:fs";
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { build as build$1 } from "vite";
-import { tmpdir } from "node:os";
 
-//#region src/remote-shims.ts
-/**
-* Specifiers a remote module bundle must NOT carry its own copy of — each is
-* redirected (via esbuild/Vite `alias`) to a tiny CJS shim that reads the
-* host's own instance off `globalThis.__PERSONA_REMOTE_MODULE_DEPS__` instead
-* of bundling the real package.
-*
-* Why this exists: hooks require the calling code's React module instance to
-* be the exact one actively rendering the tree. A remote module built with
-* its own bundled `react` (the default, before this) creates a SECOND,
-* unrelated React instance — any hook call from code using that instance
-* (including styled-components' own `useContext` inside `ThemeProvider`, and
-* anything in `@persona/design-system`, which itself just imports `react`)
-* reads a dispatcher that was never set, producing exactly
-* "Cannot read properties of null (reading 'useContext')". Sharing the
-* instance via a runtime global — rather than bundling it — fixes this for
-* every remote module, not just one that happens to avoid hooks.
-*
-* `styled-components` needs the same treatment for a subtler reason: even
-* with a shared React, a SEPARATE `styled-components` package instance would
-* call `React.createContext()` itself and produce a DIFFERENT Context object
-* than the host's — a `<ThemeProvider>` from one instance is invisible to
-* `styled.div` definitions from the other, no matter how the React inside
-* them is shared.
-*/
-/**
-* Order matters: Vite's alias resolution (via its wrapped
-* `@rollup/plugin-alias`) treats a string `find` as a PREFIX match, not just
-* exact — `importee === find || importee.startsWith(find + '/')` — and takes
-* the FIRST entry (in object key / array order) that matches. Since
-* `'react/jsx-runtime'.startsWith('react/')` is true, listing `'react'`
-* before `'react/jsx-runtime'` would make every `react/jsx-runtime` import
-* resolve against the 'react' shim's path (e.g.
-* `.../react.cjs/jsx-runtime`, ENOTDIR) instead of its own shim. The more
-* specific specifier must come first.
-*/
-const SHIMMABLE_SPECIFIERS = [
-	"react/jsx-runtime",
-	"react/jsx-dev-runtime",
-	"react",
-	"react-dom",
-	"styled-components"
-];
-const HOST_DEPS_GLOBAL = "__PERSONA_REMOTE_MODULE_DEPS__";
-/**
-* `module.exports = ...` (not a static ESM re-export) deliberately — an ESM
-* `export` list has to be known at author time, but the shimmed value's
-* actual shape lives on a runtime global. esbuild's own CJS interop
-* (`__toESM`) forwards named-import access to a CJS module's properties
-* dynamically, at RUNTIME, regardless of what the bundler could see
-* statically — the same mechanism that already makes `import { useState }
-* from 'react'` work today, since React itself ships as CJS.
-*
-* Consuming apps with `esModuleInterop` off in tsconfig (allowed by TS —
-* `allowSyntheticDefaultImports` permits the import *syntax* without it) get
-* esbuild's "Node mode" CJS interop for a DEFAULT import of an aliased CJS
-* file: `target.default = mod` (the whole `module.exports`), unconditionally
-* — `mod.__esModule` is NOT consulted in that mode, so it can't be used to
-* steer this. That's a correct model for a module whose "the module" and "the
-* default export" are the same thing (true for `react`/`react-dom`, which
-* have no own `.default`). It's wrong for `styled-components`: its
-* module.exports has BOTH a whole-module shape (ThemeProvider, css, ... as
-* plain properties) AND a separate own `.default` (the callable `styled` tag
-* function) — Node mode's `target.default = mod` picks the whole-module
-* shape, so `styled.div`/`.attrs(...)` throws on `undefined`.
-*
-* The fix: make OUR module.exports itself resolve the ambiguity — if the
-* host's real module has its own `.default` distinct from itself, export
-* THAT (with the rest of the module's named properties copied onto it, so
-* `styled.ThemeProvider`-style access — not used by styled-components itself,
-* but keeps this general — and named imports both still resolve). Mutating
-* the host's real default value (rather than building a fresh wrapper) is
-* deliberate: styled-components' internals sometimes compare a component
-* against the exact `styled` function reference (e.g. `isStyledComponent`);
-* a copy would break that. Ordinary functions/objects aren't frozen, so this
-* is safe for every specifier actually on this list.
-*/
-function shimModuleSource(specifier) {
-	const globalAccess = `globalThis.${HOST_DEPS_GLOBAL} && globalThis.${HOST_DEPS_GLOBAL}[${JSON.stringify(specifier)}]`;
-	const missingMessage = `[persona-layout-modules] the host did not expose "${specifier}" via globalThis.${HOST_DEPS_GLOBAL} before this module loaded`;
-	return [
-		`var __persona_dep = ${globalAccess} || (() => { throw new Error(${JSON.stringify(missingMessage)}); })();`,
-		`var __persona_base = (__persona_dep && 'default' in __persona_dep && __persona_dep.default !== __persona_dep) ? __persona_dep.default : __persona_dep;`,
-		`module.exports = Object.assign(__persona_base, __persona_dep, { __esModule: true, default: __persona_base });`,
-		""
-	].join("\n");
-}
-let cachedShimPaths;
-/**
-* Writes one `.cjs` shim file per specifier to a temp dir (once per process
-* — the content is static, not per-request) and returns a specifier -> path
-* map suitable for esbuild's/Vite's `alias` option. `.cjs` is deliberate: it
-* forces CommonJS treatment regardless of any ambient `package.json#type`.
-*/
-function ensureRemoteShimFiles() {
-	if (!cachedShimPaths) cachedShimPaths = (async () => {
-		const dir = await mkdtemp(path.join(tmpdir(), "persona-layout-module-shims-"));
-		const entries = await Promise.all(SHIMMABLE_SPECIFIERS.map(async (specifier) => {
-			const fileName = `${specifier.replace(/[\\/]/g, "_")}.cjs`;
-			const filePath = path.join(dir, fileName);
-			await writeFile(filePath, shimModuleSource(specifier), "utf8");
-			return [specifier, filePath];
-		}));
-		return Object.fromEntries(entries);
-	})();
-	return cachedShimPaths;
-}
-
-//#endregion
 //#region src/vite-plugin.ts
 /**
-* Vite plugin that takes a statically-declared list of layout modules
-* (`options.modules`, authored via `defineLayoutModule` — see ./define.ts),
-* 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
-* the host can consume.
+* Vite plugin that ensures declared module documents are built/served and
+* emits a `RemoteModuleRegistrationManifestV1[]` document for the host.
 *
 * Modules are configured directly here, not discovered by globbing the
 * source tree — a module IS whatever's in `options.modules`, full stop.
@@ -139,63 +23,27 @@ function personaLayoutModules(options) {
 			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: envConfig.base,
-					build: {
-						emptyOutDir: false,
-						outDir,
-						rollupOptions: {
-							input,
-							preserveEntrySignatures: "exports-only"
-						},
-						write: true
-					},
-					configFile: false,
-					esbuild: { jsx: "automatic" },
-					logLevel: "warn",
-					mode: "production",
-					plugins: options.modulePlugins?.() ?? [],
-					resolve: { alias: {
-						...resolveAliasForEsbuild(envConfig),
-						...shimAlias
-					} },
-					root
-				});
-				emitted = (Array.isArray(result) ? result : [result]).flatMap((output) => "output" in output ? output.output : []);
-			}
 			const base = envConfig.base ?? "/";
-			const manifests = [];
-			for (const definition of definitions) {
-				const render = resolveManifestDelivery(definition, definition.render, emitted, root, base);
-				const css = /* @__PURE__ */ new Set();
-				if (render.chunk) collectCss(render.chunk, css);
+			const manifests = definitions.map((definition) => {
 				const manifest = {
 					...buildManifestBase(definition),
-					remote: {
-						css: css.size > 0 ? [...css].map((fileName) => joinUrl(base, fileName)) : void 0,
-						render: render.value
-					}
+					remote: { render: { document: documentUrlFor(root, base, definition.render) } }
 				};
-				const result2 = remoteModuleRegistrationManifestV1Schema.safeParse(manifest);
-				if (!result2.success) throw new Error(`[persona-layout-modules] ${definition.definitionFilePath}: invalid manifest for "${definition.input.key}":\n${z.prettifyError(result2.error)}`);
-				manifests.push(manifest);
-			}
+				const result = remoteModuleRegistrationManifestV1Schema.safeParse(manifest);
+				if (!result.success) throw new Error(`[persona-layout-modules] ${definition.definitionFilePath}: invalid manifest for "${definition.input.key}":\n${z.prettifyError(result.error)}`);
+				return manifest;
+			});
 			assertUniqueKeys(manifests);
 			const manifestFilePath = path.join(outDir, manifestPath);
 			await mkdir(path.dirname(manifestFilePath), { recursive: true });
 			await writeFile(manifestFilePath, JSON.stringify({ modules: manifests }, null, 2), "utf8");
 		},
-		async config(config) {
+		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)
+				render: resolveEntry(root, input.key, input.render)
 			}));
 		},
 		configEnvironment(name, envConfig, env) {
@@ -205,7 +53,7 @@ function personaLayoutModules(options) {
 			const toInject = {};
 			for (const definition of definitions) {
 				const delivery = definition.render;
-				if (delivery.kind === "document" && !existingInputs.has(delivery.absolutePath)) {
+				if (!existingInputs.has(delivery.absolutePath)) {
 					toInject[entryNameFor(definition)] = delivery.absolutePath;
 					existingInputs.add(delivery.absolutePath);
 				}
@@ -220,47 +68,28 @@ function personaLayoutModules(options) {
 			for (const definition of definitions) checkDeliveryExists(definition, definition.render);
 		},
 		configureServer(server) {
-			server.middlewares.use(async (req, res, next) => {
-				if (req.url === `/${manifestPath}`) {
-					const base = resolvedConfig.base ?? "/";
-					const devManifests = definitions.map((definition$1) => ({
-						...buildManifestBase(definition$1),
-						remote: { render: devManifestDelivery(root, base, definition$1, definition$1.render) }
-					}));
-					res.setHeader("Content-Type", "application/json");
-					res.setHeader("Access-Control-Allow-Origin", "*");
-					res.end(JSON.stringify({ modules: devManifests }, null, 2));
-					return;
-				}
-				const bundleTarget = matchDevBundleRequest(req.url, definitions);
-				if (!bundleTarget) {
+			server.middlewares.use((req, res, next) => {
+				if (req.url !== `/${manifestPath}`) {
 					next();
 					return;
 				}
-				const { absolutePath, definition } = bundleTarget;
-				try {
-					const code = await bundleForDev(absolutePath, root, resolvedConfig);
-					res.setHeader("Content-Type", "application/javascript; charset=utf-8");
-					res.setHeader("Access-Control-Allow-Origin", "*");
-					res.setHeader("Cache-Control", "no-store");
-					res.end(code);
-				} catch (error) {
-					server.config.logger.error(`[persona-layout-modules] failed to dev-bundle ${definition.definitionFilePath}: ${String(error)}`);
-					res.statusCode = 500;
-					res.setHeader("Content-Type", "text/plain; charset=utf-8");
-					res.end(`[persona-layout-modules] failed to bundle: ${String(error)}`);
-				}
+				const base = resolvedConfig.base ?? "/";
+				const devManifests = definitions.map((definition) => ({
+					...buildManifestBase(definition),
+					remote: { render: { document: documentUrlFor(root, base, definition.render) } }
+				}));
+				res.setHeader("Content-Type", "application/json");
+				res.setHeader("Access-Control-Allow-Origin", "*");
+				res.end(JSON.stringify({ modules: devManifests }, null, 2));
 			});
 		},
 		name: "persona-layout-modules"
 	};
 }
-const DEV_BUNDLE_PREFIX = "/@persona-layout-module";
 /**
-* Every absolute path Vite is ALREADY going to build, per whatever the app's
-* own `build.rollupOptions.input` says (or the implicit default — Vite
-* treats `<root>/index.html` as the one entry when nothing is configured).
-* Used to decide whether a `document` entry needs injecting at all.
+* Every absolute path Vite is already going to build, per the app's
+* `build.rollupOptions.input` (or the implicit default — Vite treats
+* `<root>/index.html` as the one entry when nothing is configured).
 */
 function absoluteInputPaths(config, root) {
 	const input = config.build?.rollupOptions?.input;
@@ -284,6 +113,7 @@ function buildManifestBase(definition) {
 		allowDynamicHeight: input.allowDynamicHeight,
 		badge: input.badge,
 		category: input.category,
+		categoryCustom: input.categoryCustom,
 		configSchema: input.configSchema ? z.toJSONSchema(input.configSchema) : void 0,
 		defaultSize: input.defaultSize,
 		descriptionShort: input.descriptionShort,
@@ -296,50 +126,16 @@ function buildManifestBase(definition) {
 		uiConfigSchema: input.uiConfigSchema
 	};
 }
-/**
-* Bundles a single `code` entry (with its dependencies inlined) for dev-mode
-* cross-origin serving. Deliberately re-run on every request rather than
-* cached — these are small files and esbuild is fast enough that freshness
-* on every reload matters more than shaving milliseconds.
-*/
-async function bundleForDev(absolutePath, root, resolvedConfig) {
-	const shimAlias = await ensureRemoteShimFiles();
-	const [output] = (await build({
-		absWorkingDir: root,
-		alias: {
-			...resolveAliasForEsbuild(resolvedConfig),
-			...shimAlias
-		},
-		bundle: true,
-		entryPoints: [absolutePath],
-		format: "esm",
-		jsx: "automatic",
-		sourcemap: "inline",
-		write: false
-	})).outputFiles;
-	if (!output) throw new Error("esbuild produced no output");
-	return output.text;
-}
 function checkDeliveryExists(definition, delivery) {
 	if (!existsSync(delivery.absolutePath)) throw new Error(`[persona-layout-modules] ${definition.definitionFilePath}: render "${delivery.sourcePath}" does not resolve to a file (${delivery.absolutePath})`);
 }
-function collectCss(chunk, into) {
-	for (const fileName of chunk.viteMetadata?.importedCss ?? []) into.add(fileName);
-}
-function devBundleUrl(definition) {
-	return `${DEV_BUNDLE_PREFIX}/${entryNameFor(definition)}.js`;
-}
-function devManifestDelivery(root, base, definition, delivery) {
-	if (delivery.kind === "document") return { document: documentUrlFor(root, base, delivery) };
-	return { code: devBundleUrl(definition) };
-}
 /**
-* A `document` delivery's final PRODUCTION URL: the author's `path` override
-* when given (a logical SPA route, not a file location — used as-is, never
-* joined with `base`, matching how a subapp's own manifest URLs work),
-* otherwise the html file's own path relative to root (which Vite preserves
-* in its build output for multi-page entries) joined with `base`, since
-* that IS a real build-output location.
+* A document's manifest URL: the author's `path` override when given (a
+* logical SPA route, not a file location — used as-is, never joined with
+* `base`), otherwise the html file's path relative to root (which Vite
+* preserves in its build output for multi-page entries) joined with `base`.
+* Vite's dev server serves files at the same `base`-relative paths, so dev and
+* build share this.
 */
 function documentUrlFor(root, base, delivery) {
 	if (delivery.path) return delivery.path;
@@ -348,72 +144,24 @@ function documentUrlFor(root, base, delivery) {
 function entryNameFor(definition) {
 	return `layout-module--${definition.input.key}`;
 }
-function findChunkByFacadeModule(emitted, facadeModuleId) {
-	for (const file of emitted) if (file.type === "chunk" && file.facadeModuleId === facadeModuleId) return file;
-}
 function joinUrl(base, fileName) {
 	return `${base.endsWith("/") ? base : `${base}/`}${fileName}`.replace(/\/{2,}/g, "/");
 }
-function matchDevBundleRequest(url, definitions) {
-	if (!url?.startsWith(`${DEV_BUNDLE_PREFIX}/`) || !url.endsWith(".js")) return;
-	const name = url.slice(24, -3);
-	for (const definition of definitions) if (definition.render.kind === "code" && name === entryNameFor(definition)) return {
-		absolutePath: definition.render.absolutePath,
-		definition
-	};
-}
-/**
-* Vite normalizes `resolve.alias` (however the user wrote it — object or
-* 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 many apps use.
-*/
-function resolveAliasForEsbuild(resolvedConfig) {
-	const alias = {};
-	for (const entry of resolvedConfig.resolve?.alias ?? []) if (typeof entry.find === "string") alias[entry.find] = entry.replacement;
-	return alias;
-}
-/** `.html` → `document`; anything else (`.ts`/`.tsx`/`.js`/`.jsx`) → `code`. */
-function resolveEntry(root, spec) {
-	const absolutePath = path.resolve(root, spec.entry);
-	if (absolutePath.endsWith(".html")) return {
-		absolutePath,
-		kind: "document",
-		path: spec.path,
-		sourcePath: spec.entry
-	};
+function resolveEntry(root, key, spec) {
+	if (path.extname(spec.entry) !== ".html") throw new Error(`[persona-layout-modules] ${key}: render "${spec.entry}" must be an .html document — only document-delivered modules are supported`);
 	return {
-		absolutePath,
-		kind: "code",
+		absolutePath: path.resolve(root, spec.entry),
+		path: spec.path,
 		sourcePath: spec.entry
 	};
 }
 /**
-* Resolves the `render` delivery into its final manifest value for the
-* PRODUCTION path. `document` uses `documentUrlFor` and touches nothing else —
-* no chunk lookup, since it was never part of this plugin's own isolated
-* build. `code` becomes `{ code: <hashed chunk URL> }`, throwing if the
-* isolated build didn't emit a chunk for it. Also returns the chunk itself
-* (when there is one) so the caller can collect its CSS without a second
-* lookup.
-*/
-function resolveManifestDelivery(definition, delivery, emitted, root, base) {
-	if (delivery.kind === "document") return { value: { document: documentUrlFor(root, base, delivery) } };
-	const chunk = findChunkByFacadeModule(emitted, delivery.absolutePath);
-	if (!chunk) throw new Error(`[persona-layout-modules] ${definition.definitionFilePath}: could not locate the emitted chunk for render "${delivery.sourcePath}" in the isolated module build.`);
-	return {
-		chunk,
-		value: { code: joinUrl(base, chunk.fileName) }
-	};
-}
-/**
 * Normalizes whatever shape `build.rollupOptions.input` currently has (unset,
-* a string, an array, or already an object) into the object form, so a newly
-* injected `document` entry can be merged in as an additional key WITHOUT
-* dropping whatever was already configured — including the implicit default
-* `index.html` entry when nothing was configured at all, which would
-* otherwise silently disappear the moment this plugin assigns an object here.
+* a string, an array, or already an object) into the object form, so an
+* injected document entry can be merged in as an additional key WITHOUT
+* dropping what was already configured — including the implicit default
+* `index.html` entry, which would otherwise silently disappear the moment this
+* plugin assigns an object here.
 */
 function toInputRecord(input, root) {
 	if (input == null) return { index: path.join(root, "index.html") };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.5.3",
+  "version": "0.7.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",
@@ -38,7 +38,6 @@
     "release": "semantic-release"
   },
   "peerDependencies": {
-    "esbuild": ">=0.21.0 <1",
     "react": "^17 || ^18 || ^19",
     "react-dom": "^17 || ^18 || ^19",
     "vite": "^6 || ^7 || ^8",
@@ -68,10 +67,8 @@
     "playwright": "1.62.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rollup": "^4.0.0",
     "semantic-release": "^25.0.7",
     "semantic-release-monorepo": "^8.0.2",
-    "styled-components": "^5.3.5",
     "tsdown": "^0.18.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vite": "^7.0.0",
@@ -95,7 +92,7 @@
         "@semantic-release/exec",
         {
           "prepareCmd": "yarn version ${nextRelease.version}",
-          "publishCmd": "yarn npm publish --staged --access public"
+          "publishCmd": "yarn npm publish --access public"
         }
       ],
       "@semantic-release/github"

package/skills/getting-started/SKILL.md

@@ -20,7 +20,7 @@ metadata:
 
 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
+the host. The plugin ensures each module's HTML document is built and emits a
 `{ modules: RemoteModuleRegistrationManifestV1[] }` JSON document the host fetches and validates.
 
 This package is publicly available from the npm registry.
@@ -31,10 +31,8 @@ This package is publicly available from the npm registry.
 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.
+`vite` and `zod` are peer dependencies; `react` / `react-dom` (`^17 || ^18 || ^19`) are optional
+peers needed only by the `bridge-frame` entry.
 
 ## Setup (vite.config.ts)
 
@@ -70,7 +68,12 @@ 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
+`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
+trimmed, case-sensitive string, even across different module sources. When both are set,
+`categoryCustom` overrides `category`, and a label equal to one of the host's built-in category
+labels lands in "Other"; keep setting `category` as a fallback for hosts that predate
+`categoryCustom`), `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).
@@ -82,11 +85,10 @@ 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`: 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:
+A module's `render.entry` must end in `.html`: the host iframes the page. Any other extension fails
+during Vite config resolution with a clear error. 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({
@@ -449,6 +451,13 @@ requirement, and the host falls back to its own default size.
 
 Source: `src/schema.ts` (`remoteModuleRegistrationManifestV1Schema` `.refine`).
 
+### [MEDIUM] `render.entry` is not an HTML document
+
+The entry must be an `.html` document. Other extensions fail in `config()` before the plugin checks
+whether the file exists:
+
+`[persona-layout-modules] <key>: render "<entry>" must be an .html document — only document-delivered modules are supported`
+
 ### [MEDIUM] `render.entry` doesn't resolve to a real file
 
 `personaLayoutModules` fails fast in `configResolved` — before running a full build — when an entry
@@ -478,7 +487,7 @@ personaLayoutModules({ manifestPath: '/manifests/my-app.json', modules: [] });
 
 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:
+— this avoids pulling in Vite:
 
 ```ts
 import { DEFAULT_MANIFEST_PATH } from '@persona/layout-editor-remote-module';