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

package/dist/vite-plugin.mjs

@@ -0,0 +1,435 @@
+import { n as DEFAULT_MANIFEST_PATH, r as defineLayoutModule, t as remoteModuleRegistrationManifestV1Schema } from "./schema-BeI8GdXS.mjs";
+import { z } from "zod";
+import { build } from "esbuild";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, 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
+* persona-web can intake.
+*
+* Modules are configured directly here, not discovered by globbing the
+* source tree — a module IS whatever's in `options.modules`, full stop.
+*/
+function personaLayoutModules(options) {
+	const manifestPath = (options.manifestPath ?? DEFAULT_MANIFEST_PATH).replace(/^\/+/, "");
+	let root = process.cwd();
+	let resolvedConfig;
+	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 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,
+					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(resolvedConfig),
+						...shimAlias
+					} },
+					root
+				});
+				emitted = (Array.isArray(result) ? result : [result]).flatMap((output) => "output" in output ? output.output : []);
+			}
+			const base = resolvedConfig.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 manifest = {
+					...buildManifestBase(definition),
+					remote: {
+						css: css.size > 0 ? [...css].map((fileName) => joinUrl(base, fileName)) : void 0,
+						render: render.value
+					}
+				};
+				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);
+			}
+			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, env) {
+			root = config.root ? path.resolve(config.root) : process.cwd();
+			definitions = options.modules.map((input) => ({
+				definitionFilePath: input.key,
+				input,
+				render: resolveEntry(root, input.render)
+			}));
+			if (env.command !== "build") return;
+			const existingInputs = absoluteInputPaths(config, root);
+			const toInject = {};
+			for (const definition of definitions) {
+				const delivery = definition.render;
+				if (delivery.kind === "document" && !existingInputs.has(delivery.absolutePath)) {
+					toInject[entryNameFor(definition)] = delivery.absolutePath;
+					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
+				};
+			}
+		},
+		configResolved(config) {
+			resolvedConfig = config;
+			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) {
+					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)}`);
+				}
+			});
+		},
+		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.
+*/
+function absoluteInputPaths(config, root) {
+	const input = config.build?.rollupOptions?.input;
+	if (input == null) return new Set([path.join(root, "index.html")]);
+	if (typeof input === "string") return new Set([path.resolve(root, input)]);
+	if (Array.isArray(input)) return new Set(input.map((entry) => path.resolve(root, entry)));
+	return new Set(Object.values(input).map((entry) => path.resolve(root, entry)));
+}
+function assertUniqueKeys(manifests) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const manifest of manifests) {
+		if (seen.has(manifest.key)) throw new Error(`[persona-layout-modules] duplicate module key "${manifest.key}" — keys must be unique within an app`);
+		seen.add(manifest.key);
+	}
+}
+/** Fields shared between the prod and dev manifest — everything but `remote`. */
+function buildManifestBase(definition) {
+	const { input } = definition;
+	return {
+		allowAddingToLayout: input.allowAddingToLayout,
+		allowDynamicHeight: input.allowDynamicHeight,
+		badge: input.badge,
+		category: input.category,
+		configSchema: input.configSchema ? z.toJSONSchema(input.configSchema) : void 0,
+		defaultSize: input.defaultSize,
+		descriptionShort: input.descriptionShort,
+		displayName: input.displayName,
+		icon: input.icon,
+		internalUsersOnly: input.internalUsersOnly,
+		key: input.key,
+		layouts: input.layouts ?? [],
+		manifestVersion: "v1",
+		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.
+*/
+function documentUrlFor(root, base, delivery) {
+	if (delivery.path) return delivery.path;
+	return joinUrl(base, path.relative(root, delivery.absolutePath).split(path.sep).join("/"));
+}
+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 is what every `sa-*`
+* subapp's `vite.config.ts` actually uses.
+*/
+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
+	};
+	return {
+		absolutePath,
+		kind: "code",
+		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.
+*/
+function toInputRecord(input, root) {
+	if (input == null) return { index: path.join(root, "index.html") };
+	if (typeof input === "string") return { index: path.resolve(root, input) };
+	if (Array.isArray(input)) {
+		const record$1 = {};
+		for (const entry of input) {
+			const absolutePath = path.resolve(root, entry);
+			record$1[path.basename(absolutePath, path.extname(absolutePath))] = absolutePath;
+		}
+		return record$1;
+	}
+	const record = {};
+	for (const [name, entry] of Object.entries(input)) record[name] = path.resolve(root, entry);
+	return record;
+}
+
+//#endregion
+export { defineLayoutModule, personaLayoutModules };

package/package.json

@@ -1,10 +1,123 @@
 {
   "name": "@persona/layout-editor-remote-module",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder release. Use 0.5.0 or later.",
+  "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).",
   "license": "SEE LICENSE",
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "vite-plugin": [
+        "dist/vite-plugin.d.mts"
+      ],
+      "bridge-host": [
+        "dist/bridge-host.d.mts"
+      ],
+      "bridge-frame": [
+        "dist/bridge-frame.d.mts"
+      ]
+    }
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
   "files": [
+    "dist",
+    "skills",
     "LICENSE"
   ],
-  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
-}
+  "keywords": [
+    "tanstack-intent"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "check": "yarn build && yarn skills:check && yarn test:run",
+    "skills:check": "intent validate",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "release": "semantic-release"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.21.0 <1",
+    "react": "^17 || ^18 || ^19",
+    "react-dom": "^17 || ^18 || ^19",
+    "vite": "^5 || ^6 || ^7 || ^8",
+    "zod": "^4.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@semantic-release/exec": "^7.1.0",
+    "@tanstack/intent": "^0.3.6",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "@vitest/browser": "~4.1.11",
+    "@vitest/browser-playwright": "~4.1.11",
+    "esbuild": "^0.28.0",
+    "jsdom": "^30.0.1",
+    "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",
+    "vitest": "~4.1.11",
+    "zod": "4.3.6"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "release": {
+    "extends": "semantic-release-monorepo",
+    "branches": [
+      "main"
+    ],
+    "tagFormat": "remote-module-v${version}",
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "yarn version ${nextRelease.version}",
+          "publishCmd": "yarn npm publish --staged --access public"
+        }
+      ],
+      "@semantic-release/github"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin.d.mts",
+      "import": "./dist/vite-plugin.mjs"
+    },
+    "./bridge-host": {
+      "types": "./dist/bridge-host.d.mts",
+      "import": "./dist/bridge-host.mjs"
+    },
+    "./bridge-frame": {
+      "types": "./dist/bridge-frame.d.mts",
+      "import": "./dist/bridge-frame.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}