@ethisyscore/vite-plugin 1.31.0 → 1.33.0

package/dist/index.cjs

@@ -607,6 +607,221 @@ function titleCase(s) {
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+var PLATFORM_REACT_EXTERNALS = [
+  "react",
+  "react/jsx-runtime",
+  "react-dom",
+  "@mui/material",
+  "@mui/icons-material",
+  "@emotion/react",
+  "@emotion/styled",
+  "date-fns",
+  "@ethisyscore/components-react",
+  "@ethisyscore/extension-runtime",
+  "@ethisyscore/extension-runtime/plugin"
+];
+var PLATFORM_REACT_DEDUPE = [
+  "@tanstack/react-query",
+  "react",
+  "react-dom",
+  "@ethisyscore/extension-runtime"
+];
+var DEFAULT_OUT_DIR = "dist";
+var DEFAULT_OUTPUT_PREFIX = "platform-react";
+var DEFAULT_DEFINE_PLUGIN_PAGE = "@/app/definePluginPage";
+var DEFAULT_SRC_DIR = "src";
+var DEFAULT_ALIAS_PREFIX = "@";
+var SUMMARY_FILENAME = "platform-react-pages.json";
+var DIGEST_MAP_FILENAME = "platform-react-digest-map.json";
+function rewriteAliasedExternalImports() {
+  return {
+    name: "rewrite-aliased-external-imports",
+    renderChunk(code) {
+      let counter = 0;
+      let changed = false;
+      const out = code.replace(
+        // Optional default binding (`import Foo, { … }`) then the named braces.
+        /\bimport\s+(?:([\w$]+)\s*,\s*)?\{([^{}]*)\}\s*from\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')\s*;?/g,
+        (full, def, specs, mod) => {
+          if (!/\sas\s/.test(specs)) return full;
+          changed = true;
+          const ns = `__ns_imp_${counter++}`;
+          const decls = specs.split(",").map((s) => s.trim()).filter(Boolean).map((s) => {
+            const [imported, local] = s.split(/\s+as\s+/).map((t) => t.trim());
+            return `${local ?? imported} = ${ns}.${imported}`;
+          }).join(", ");
+          const defPart = def ? `import ${def} from ${mod}; ` : "";
+          return `${defPart}import * as ${ns} from ${mod}; const ${decls};`;
+        }
+      );
+      return changed ? { code: out, map: null } : null;
+    }
+  };
+}
+function virtualPageEntry(page, config) {
+  const VIRTUAL_ID = `\0virtual:surface/${page.id}`;
+  const views = page.views ?? {};
+  const names = Object.keys(views);
+  const viewImports = names.map((n) => `import { ${n} } from ${JSON.stringify(config.toAlias(views[n]))};`).join("\n");
+  const src = `import Page from ${JSON.stringify(config.toAlias(page.moduleSpecifier))};
+${viewImports}
+import { definePluginPage } from ${JSON.stringify(config.definePluginPageSpecifier)};
+export default definePluginPage(Page, { ${names.join(", ")} });
+`;
+  return {
+    id: VIRTUAL_ID,
+    plugin: {
+      name: `virtual-surface-${page.id}`,
+      resolveId: (id) => id === VIRTUAL_ID ? VIRTUAL_ID : null,
+      load: (id) => id === VIRTUAL_ID ? src : null
+    }
+  };
+}
+function defaultWriteFile(path$1, contents) {
+  fs.mkdirSync(path.dirname(path$1), { recursive: true });
+  fs.writeFileSync(path$1, contents);
+}
+function readManifest(options, root) {
+  if (options.manifest !== void 0) {
+    return options.manifest;
+  }
+  const rel = options.manifestPath ?? "feature.manifest.json";
+  const abs = path.isAbsolute(rel) ? rel : path.resolve(root, rel);
+  if (!fs.existsSync(abs)) {
+    return null;
+  }
+  const raw = fs.readFileSync(abs, "utf-8");
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(
+      `[ethisys-platform-react] Failed to parse manifest at "${abs}": ${e.message}`
+    );
+  }
+}
+function makeDefaultBuild(viteBuild) {
+  return async (ctx) => {
+    const build = viteBuild ?? (await import('vite')).build;
+    await build({
+      root: ctx.root,
+      configFile: false,
+      plugins: [ctx.surfacePlugin, ...ctx.plugins, rewriteAliasedExternalImports()],
+      resolve: {
+        dedupe: [...ctx.dedupe],
+        alias: ctx.alias
+      },
+      build: {
+        target: ctx.target,
+        outDir: ctx.outDir,
+        emptyOutDir: false,
+        assetsDir: "",
+        minify: ctx.minify,
+        sourcemap: ctx.sourcemap,
+        rollupOptions: {
+          input: { [ctx.pageId]: ctx.entryId },
+          preserveEntrySignatures: "strict",
+          external: [...ctx.external],
+          output: {
+            format: "es",
+            inlineDynamicImports: true,
+            entryFileNames: `${ctx.outputPrefix}/[name].js`,
+            chunkFileNames: `${ctx.outputPrefix}/[name]-[hash].js`,
+            assetFileNames: `${ctx.outputPrefix}/[name][extname]`
+          }
+        }
+      },
+      logLevel: "warn"
+    });
+  };
+}
+async function buildPlatformReactPages(options = {}) {
+  const root = options.root ?? process.cwd();
+  const logger = options.logger ?? console;
+  const manifest = readManifest(options, root);
+  const declared = manifest?.ui?.platformReactPages;
+  if (!Array.isArray(declared) || declared.length === 0) {
+    logger.warn("[build-pages] no platformReactPages declared \u2014 nothing to build");
+    return { pages: [], digests: [], summaryPath: null, digestMapPath: null };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const pages = declared.map((raw, i) => {
+    const decl = raw;
+    if (typeof decl?.id !== "string" || decl.id.length === 0) {
+      throw new Error(`[build-pages] ui.platformReactPages[${i}].id is required (non-empty string).`);
+    }
+    if (seen.has(decl.id)) {
+      throw new Error(`[build-pages] Duplicate page id "${decl.id}".`);
+    }
+    seen.add(decl.id);
+    if (typeof decl.moduleSpecifier !== "string" || decl.moduleSpecifier.length === 0) {
+      throw new Error(`[build-pages] surface "${decl.id}" has no moduleSpecifier in the manifest.`);
+    }
+    return decl;
+  });
+  const outDir = options.outDir ?? DEFAULT_OUT_DIR;
+  const outDirAbs = path.isAbsolute(outDir) ? outDir : path.resolve(root, outDir);
+  const outputPrefix = (options.outputPrefix ?? DEFAULT_OUTPUT_PREFIX).replace(/^\/+|\/+$/g, "");
+  const outputPrefixDir = path.resolve(outDirAbs, outputPrefix);
+  const external = options.external ?? PLATFORM_REACT_EXTERNALS;
+  const dedupe = options.dedupe ?? PLATFORM_REACT_DEDUPE;
+  const alias = options.alias ?? [];
+  const plugins = options.plugins ?? [];
+  const definePluginPageSpecifier = options.definePluginPageSpecifier ?? DEFAULT_DEFINE_PLUGIN_PAGE;
+  const srcDir = options.srcDir ?? DEFAULT_SRC_DIR;
+  const aliasPrefix = options.aliasPrefix ?? DEFAULT_ALIAS_PREFIX;
+  const srcRe = new RegExp(`^${escapeRegExp(srcDir)}/`);
+  const toAlias = (p) => `${aliasPrefix}/${p.replace(srcRe, "")}`;
+  const write = options.writeFile ?? defaultWriteFile;
+  const read = options.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+  const runBuild = options.build ?? makeDefaultBuild(options.viteBuild);
+  if (options.clean ?? true) {
+    if (fs.existsSync(outDirAbs)) {
+      fs.rmSync(outDirAbs, { recursive: true, force: true });
+    }
+    fs.mkdirSync(outputPrefixDir, { recursive: true });
+  }
+  for (const page of pages) {
+    const { id: entryId, plugin: surfacePlugin } = virtualPageEntry(page, {
+      definePluginPageSpecifier,
+      toAlias
+    });
+    logger.log(`[build-pages] ${page.id} \u2190 ${page.moduleSpecifier}`);
+    await runBuild({
+      pageId: page.id,
+      entryId,
+      surfacePlugin,
+      root,
+      outDir: outDirAbs,
+      outputPrefix,
+      external,
+      dedupe,
+      alias,
+      plugins,
+      target: options.target ?? "es2022",
+      minify: options.minify ?? false,
+      sourcemap: options.sourcemap ?? true
+    });
+  }
+  const summaryPages = pages.map((p) => ({
+    id: p.id,
+    exportName: p.exportName ?? "default",
+    title: p.title ?? null,
+    bundlePath: `${outputPrefix}/${p.id}.js`,
+    source: p.moduleSpecifier
+  }));
+  const summaryPath = path.resolve(outputPrefixDir, SUMMARY_FILENAME);
+  write(summaryPath, JSON.stringify({ pages: summaryPages }, null, 2));
+  const digests = pages.map((p) => `${outputPrefix}/${p.id}.js`).sort().map((relPath) => {
+    const code = read(path.resolve(outDirAbs, relPath));
+    return { path: relPath, sha256: crypto.createHash("sha256").update(code, "utf8").digest("hex") };
+  });
+  const digestMapPath = path.resolve(outputPrefixDir, DIGEST_MAP_FILENAME);
+  write(digestMapPath, JSON.stringify({ digests }, null, 2));
+  logger.log(
+    `[build-pages] emitted ${pages.length} page(s) + summary + digest map (${digests.length} digests)`
+  );
+  return { pages: summaryPages, digests, summaryPath, digestMapPath };
+}
 
 // src/platform-react/page-bundles.ts
 var ID_REGEX = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/i;
@@ -640,6 +855,7 @@ function ethisysPlatformReactPlugin(options = {}) {
   let resolvedRoot;
   let manifestAbsPath;
   let pages = [];
+  let overlay = null;
   function resolveRoot() {
     if (resolvedRoot) {
       return resolvedRoot;
@@ -664,54 +880,94 @@ function ethisysPlatformReactPlugin(options = {}) {
   }
   function validate() {
     pages = [];
+    overlay = null;
     const manifest = readManifest3();
     if (manifest === null) {
       return;
     }
     const declared = manifest.ui?.platformReactPages;
-    if (!Array.isArray(declared) || declared.length === 0) {
-      return;
+    if (Array.isArray(declared) && declared.length > 0) {
+      const seenIds = /* @__PURE__ */ new Set();
+      for (let i = 0; i < declared.length; i++) {
+        const decl = declared[i];
+        const where = `ui.platformReactPages[${i}]`;
+        if (typeof decl?.id !== "string" || decl.id.length === 0) {
+          throw new Error(
+            `[ethisys-platform-react] ${where}.id is required (non-empty string).`
+          );
+        }
+        if (!ID_REGEX.test(decl.id)) {
+          throw new Error(
+            `[ethisys-platform-react] ${where}.id "${decl.id}" must match [a-z0-9_-]+ (URL-safe; case-insensitive).`
+          );
+        }
+        if (seenIds.has(decl.id)) {
+          throw new Error(
+            `[ethisys-platform-react] Duplicate page id "${decl.id}".`
+          );
+        }
+        seenIds.add(decl.id);
+        if (typeof decl.moduleSpecifier !== "string" || decl.moduleSpecifier.length === 0) {
+          throw new Error(
+            `[ethisys-platform-react] ${where}.moduleSpecifier is required (non-empty relative path).`
+          );
+        }
+        assertHostOriginRelativePath2(decl.moduleSpecifier, `${where}.moduleSpecifier`);
+        const absPath = path.resolve(resolvedRoot, decl.moduleSpecifier);
+        if (!fs.existsSync(absPath)) {
+          throw new Error(
+            `[ethisys-platform-react] ${where}.moduleSpecifier "${decl.moduleSpecifier}" does not exist on disk (resolved: ${absPath}).`
+          );
+        }
+        const exportName = typeof decl.exportName === "string" && decl.exportName.length > 0 ? decl.exportName : "default";
+        pages.push({
+          id: decl.id,
+          exportName,
+          title: typeof decl.title === "string" && decl.title.length > 0 ? decl.title : null,
+          moduleSpecifierRel: decl.moduleSpecifier,
+          moduleSpecifierAbs: absPath
+        });
+      }
     }
-    const seenIds = /* @__PURE__ */ new Set();
-    for (let i = 0; i < declared.length; i++) {
-      const decl = declared[i];
-      const where = `ui.platformReactPages[${i}]`;
-      if (typeof decl?.id !== "string" || decl.id.length === 0) {
+    const overlayDecl = manifest.ui?.platformReactOverlay;
+    if (overlayDecl !== void 0 && overlayDecl !== null) {
+      const where = "ui.platformReactOverlay";
+      if (typeof overlayDecl.id !== "string" || overlayDecl.id.length === 0) {
         throw new Error(
           `[ethisys-platform-react] ${where}.id is required (non-empty string).`
         );
       }
-      if (!ID_REGEX.test(decl.id)) {
+      if (!ID_REGEX.test(overlayDecl.id)) {
         throw new Error(
-          `[ethisys-platform-react] ${where}.id "${decl.id}" must match [a-z0-9_-]+ (URL-safe; case-insensitive).`
+          `[ethisys-platform-react] ${where}.id "${overlayDecl.id}" must match [a-z0-9_-]+ (URL-safe; case-insensitive).`
         );
       }
-      if (seenIds.has(decl.id)) {
+      if (typeof overlayDecl.moduleSpecifier !== "string" || overlayDecl.moduleSpecifier.length === 0) {
         throw new Error(
-          `[ethisys-platform-react] Duplicate page id "${decl.id}".`
+          `[ethisys-platform-react] ${where}.moduleSpecifier is required (non-empty relative path).`
         );
       }
-      seenIds.add(decl.id);
-      if (typeof decl.moduleSpecifier !== "string" || decl.moduleSpecifier.length === 0) {
+      assertHostOriginRelativePath2(overlayDecl.moduleSpecifier, `${where}.moduleSpecifier`);
+      const absPath = path.resolve(resolvedRoot, overlayDecl.moduleSpecifier);
+      if (!fs.existsSync(absPath)) {
         throw new Error(
-          `[ethisys-platform-react] ${where}.moduleSpecifier is required (non-empty relative path).`
+          `[ethisys-platform-react] ${where}.moduleSpecifier "${overlayDecl.moduleSpecifier}" does not exist on disk (resolved: ${absPath}).`
         );
       }
-      assertHostOriginRelativePath2(decl.moduleSpecifier, `${where}.moduleSpecifier`);
-      const absPath = path.resolve(resolvedRoot, decl.moduleSpecifier);
-      if (!fs.existsSync(absPath)) {
+      const collidingPage = pages.find((p) => p.id === overlayDecl.id);
+      if (collidingPage !== void 0) {
         throw new Error(
-          `[ethisys-platform-react] ${where}.moduleSpecifier "${decl.moduleSpecifier}" does not exist on disk (resolved: ${absPath}).`
+          `[ethisys-platform-react] ui.platformReactOverlay.id "${overlayDecl.id}" collides with a declared page id \u2014 ids must be unique across pages and the overlay.`
         );
       }
-      const exportName = typeof decl.exportName === "string" && decl.exportName.length > 0 ? decl.exportName : "default";
-      pages.push({
-        id: decl.id,
+      const exportName = typeof overlayDecl.exportName === "string" && overlayDecl.exportName.length > 0 ? overlayDecl.exportName : "default";
+      overlay = {
+        id: overlayDecl.id,
         exportName,
-        title: typeof decl.title === "string" && decl.title.length > 0 ? decl.title : null,
-        moduleSpecifierRel: decl.moduleSpecifier,
+        title: typeof overlayDecl.title === "string" && overlayDecl.title.length > 0 ? overlayDecl.title : null,
+        moduleSpecifierRel: overlayDecl.moduleSpecifier,
         moduleSpecifierAbs: absPath
-      });
+      };
     }
   }
   let isBuild = false;
@@ -731,6 +987,15 @@ function ethisysPlatformReactPlugin(options = {}) {
       }
       return {
         build: {
+          // CRITICAL: emit NON-MINIFIED ESM. The host loads each bundle by
+          // fetching it as text and REGEX-rewriting its bare-specifier imports
+          // (`import { x } from "react"` → `const { x } = registry["react"]`) —
+          // the host's rewriter (hostModuleRegistry) assumes non-minified ESM,
+          // so a minified bundle leaves `react`/`react-dom`/MUI unrewritten and
+          // they resolve to `undefined`/`null` at mount (the overlay/page then
+          // throws on the first hook). Vite minifies production builds by
+          // default, so this MUST be forced off for every PlatformReact surface.
+          minify: false,
           rollupOptions: {
             // CRITICAL: single-file ESM output per page. The host loads each
             // page via `import(url)` at mount time and reads the declared
@@ -744,10 +1009,20 @@ function ethisysPlatformReactPlugin(options = {}) {
               chunkFileNames: `${outputPrefix}[name]-[hash].js`,
               assetFileNames: `${outputPrefix}[name][extname]`
             },
-            // Auto-externalise the host-ui-externals specifier so the host's
-            // module-registry rewriter resolves it to the live `@coreconnect/gogo-ui`
-            // instance at runtime — Tier T remotes never ship their own Gogo copy.
-            external: ["@ethisyscore/host-ui-externals"]
+            // Externalise every host-realm specifier so the host's module-registry
+            // rewriter resolves them to the live host singletons at runtime — react,
+            // react-dom, MUI, emotion, components-react, extension-runtime (the shared
+            // PLATFORM_REACT_EXTERNALS contract) PLUS host-ui-externals. This is
+            // CRITICAL: if react is NOT externalised it gets bundled, the surface then
+            // runs against a SECOND React instance, and hooks throw (invalid-hook /
+            // "reading useEffect of null"). Must match the programmatic build-pages
+            // externals so config-hook plugins (cc-scaffolded) behave identically.
+            external: [...PLATFORM_REACT_EXTERNALS, "@ethisyscore/host-ui-externals"],
+            // Nothing inside the build imports the entry module, so the bundler's
+            // default entry tree-shaking would drop the declared `exportName`
+            // (e.g. the overlay's `Overlay`). Pin entry signatures so the host
+            // loader can read `bundle[exportName]` at mount time.
+            preserveEntrySignatures: "strict"
           }
         }
       };
@@ -770,13 +1045,16 @@ function ethisysPlatformReactPlugin(options = {}) {
         return;
       }
       validate();
-      if (pages.length === 0) {
+      if (pages.length === 0 && overlay === null) {
         return;
       }
       const input = {};
       for (const page of pages) {
         input[page.id] = slash2(page.moduleSpecifierAbs);
       }
+      if (overlay !== null) {
+        input[overlay.id] = slash2(overlay.moduleSpecifierAbs);
+      }
       const writable = config;
       writable.build ??= {};
       writable.build.rollupOptions ??= {};
@@ -806,7 +1084,7 @@ function ethisysPlatformReactPlugin(options = {}) {
      * having to re-parse the manifest.
      */
     generateBundle(_options, bundle) {
-      if (pages.length === 0) {
+      if (pages.length === 0 && overlay === null) {
         return;
       }
       const digests = [];
@@ -828,6 +1106,15 @@ function ethisysPlatformReactPlugin(options = {}) {
           source: p.moduleSpecifierRel
         }))
       };
+      if (overlay !== null) {
+        summary.overlay = {
+          id: overlay.id,
+          exportName: overlay.exportName,
+          title: overlay.title,
+          bundlePath: `${outputPrefix}${overlay.id}.js`,
+          source: overlay.moduleSpecifierRel
+        };
+      }
       this.emitFile({
         type: "asset",
         fileName: `${outputPrefix}platform-react-pages.json`,
@@ -929,221 +1216,6 @@ function parsePlatformReactPages(manifestPath, options = {}) {
   }
   return result;
 }
-var PLATFORM_REACT_EXTERNALS = [
-  "react",
-  "react/jsx-runtime",
-  "react-dom",
-  "@mui/material",
-  "@mui/icons-material",
-  "@emotion/react",
-  "@emotion/styled",
-  "date-fns",
-  "@ethisyscore/components-react",
-  "@ethisyscore/extension-runtime",
-  "@ethisyscore/extension-runtime/plugin"
-];
-var PLATFORM_REACT_DEDUPE = [
-  "@tanstack/react-query",
-  "react",
-  "react-dom",
-  "@ethisyscore/extension-runtime"
-];
-var DEFAULT_OUT_DIR = "dist";
-var DEFAULT_OUTPUT_PREFIX = "platform-react";
-var DEFAULT_DEFINE_PLUGIN_PAGE = "@/app/definePluginPage";
-var DEFAULT_SRC_DIR = "src";
-var DEFAULT_ALIAS_PREFIX = "@";
-var SUMMARY_FILENAME = "platform-react-pages.json";
-var DIGEST_MAP_FILENAME = "platform-react-digest-map.json";
-function rewriteAliasedExternalImports() {
-  return {
-    name: "rewrite-aliased-external-imports",
-    renderChunk(code) {
-      let counter = 0;
-      let changed = false;
-      const out = code.replace(
-        // Optional default binding (`import Foo, { … }`) then the named braces.
-        /\bimport\s+(?:([\w$]+)\s*,\s*)?\{([^{}]*)\}\s*from\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')\s*;?/g,
-        (full, def, specs, mod) => {
-          if (!/\sas\s/.test(specs)) return full;
-          changed = true;
-          const ns = `__ns_imp_${counter++}`;
-          const decls = specs.split(",").map((s) => s.trim()).filter(Boolean).map((s) => {
-            const [imported, local] = s.split(/\s+as\s+/).map((t) => t.trim());
-            return `${local ?? imported} = ${ns}.${imported}`;
-          }).join(", ");
-          const defPart = def ? `import ${def} from ${mod}; ` : "";
-          return `${defPart}import * as ${ns} from ${mod}; const ${decls};`;
-        }
-      );
-      return changed ? { code: out, map: null } : null;
-    }
-  };
-}
-function virtualPageEntry(page, config) {
-  const VIRTUAL_ID = `\0virtual:surface/${page.id}`;
-  const views = page.views ?? {};
-  const names = Object.keys(views);
-  const viewImports = names.map((n) => `import { ${n} } from ${JSON.stringify(config.toAlias(views[n]))};`).join("\n");
-  const src = `import Page from ${JSON.stringify(config.toAlias(page.moduleSpecifier))};
-${viewImports}
-import { definePluginPage } from ${JSON.stringify(config.definePluginPageSpecifier)};
-export default definePluginPage(Page, { ${names.join(", ")} });
-`;
-  return {
-    id: VIRTUAL_ID,
-    plugin: {
-      name: `virtual-surface-${page.id}`,
-      resolveId: (id) => id === VIRTUAL_ID ? VIRTUAL_ID : null,
-      load: (id) => id === VIRTUAL_ID ? src : null
-    }
-  };
-}
-function defaultWriteFile(path$1, contents) {
-  fs.mkdirSync(path.dirname(path$1), { recursive: true });
-  fs.writeFileSync(path$1, contents);
-}
-function readManifest(options, root) {
-  if (options.manifest !== void 0) {
-    return options.manifest;
-  }
-  const rel = options.manifestPath ?? "feature.manifest.json";
-  const abs = path.isAbsolute(rel) ? rel : path.resolve(root, rel);
-  if (!fs.existsSync(abs)) {
-    return null;
-  }
-  const raw = fs.readFileSync(abs, "utf-8");
-  try {
-    return JSON.parse(raw);
-  } catch (e) {
-    throw new Error(
-      `[ethisys-platform-react] Failed to parse manifest at "${abs}": ${e.message}`
-    );
-  }
-}
-function makeDefaultBuild(viteBuild) {
-  return async (ctx) => {
-    const build = viteBuild ?? (await import('vite')).build;
-    await build({
-      root: ctx.root,
-      configFile: false,
-      plugins: [ctx.surfacePlugin, ...ctx.plugins, rewriteAliasedExternalImports()],
-      resolve: {
-        dedupe: [...ctx.dedupe],
-        alias: ctx.alias
-      },
-      build: {
-        target: ctx.target,
-        outDir: ctx.outDir,
-        emptyOutDir: false,
-        assetsDir: "",
-        minify: ctx.minify,
-        sourcemap: ctx.sourcemap,
-        rollupOptions: {
-          input: { [ctx.pageId]: ctx.entryId },
-          preserveEntrySignatures: "strict",
-          external: [...ctx.external],
-          output: {
-            format: "es",
-            inlineDynamicImports: true,
-            entryFileNames: `${ctx.outputPrefix}/[name].js`,
-            chunkFileNames: `${ctx.outputPrefix}/[name]-[hash].js`,
-            assetFileNames: `${ctx.outputPrefix}/[name][extname]`
-          }
-        }
-      },
-      logLevel: "warn"
-    });
-  };
-}
-async function buildPlatformReactPages(options = {}) {
-  const root = options.root ?? process.cwd();
-  const logger = options.logger ?? console;
-  const manifest = readManifest(options, root);
-  const declared = manifest?.ui?.platformReactPages;
-  if (!Array.isArray(declared) || declared.length === 0) {
-    logger.warn("[build-pages] no platformReactPages declared \u2014 nothing to build");
-    return { pages: [], digests: [], summaryPath: null, digestMapPath: null };
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const pages = declared.map((raw, i) => {
-    const decl = raw;
-    if (typeof decl?.id !== "string" || decl.id.length === 0) {
-      throw new Error(`[build-pages] ui.platformReactPages[${i}].id is required (non-empty string).`);
-    }
-    if (seen.has(decl.id)) {
-      throw new Error(`[build-pages] Duplicate page id "${decl.id}".`);
-    }
-    seen.add(decl.id);
-    if (typeof decl.moduleSpecifier !== "string" || decl.moduleSpecifier.length === 0) {
-      throw new Error(`[build-pages] surface "${decl.id}" has no moduleSpecifier in the manifest.`);
-    }
-    return decl;
-  });
-  const outDir = options.outDir ?? DEFAULT_OUT_DIR;
-  const outDirAbs = path.isAbsolute(outDir) ? outDir : path.resolve(root, outDir);
-  const outputPrefix = (options.outputPrefix ?? DEFAULT_OUTPUT_PREFIX).replace(/^\/+|\/+$/g, "");
-  const outputPrefixDir = path.resolve(outDirAbs, outputPrefix);
-  const external = options.external ?? PLATFORM_REACT_EXTERNALS;
-  const dedupe = options.dedupe ?? PLATFORM_REACT_DEDUPE;
-  const alias = options.alias ?? [];
-  const plugins = options.plugins ?? [];
-  const definePluginPageSpecifier = options.definePluginPageSpecifier ?? DEFAULT_DEFINE_PLUGIN_PAGE;
-  const srcDir = options.srcDir ?? DEFAULT_SRC_DIR;
-  const aliasPrefix = options.aliasPrefix ?? DEFAULT_ALIAS_PREFIX;
-  const srcRe = new RegExp(`^${escapeRegExp(srcDir)}/`);
-  const toAlias = (p) => `${aliasPrefix}/${p.replace(srcRe, "")}`;
-  const write = options.writeFile ?? defaultWriteFile;
-  const read = options.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
-  const runBuild = options.build ?? makeDefaultBuild(options.viteBuild);
-  if (options.clean ?? true) {
-    if (fs.existsSync(outDirAbs)) {
-      fs.rmSync(outDirAbs, { recursive: true, force: true });
-    }
-    fs.mkdirSync(outputPrefixDir, { recursive: true });
-  }
-  for (const page of pages) {
-    const { id: entryId, plugin: surfacePlugin } = virtualPageEntry(page, {
-      definePluginPageSpecifier,
-      toAlias
-    });
-    logger.log(`[build-pages] ${page.id} \u2190 ${page.moduleSpecifier}`);
-    await runBuild({
-      pageId: page.id,
-      entryId,
-      surfacePlugin,
-      root,
-      outDir: outDirAbs,
-      outputPrefix,
-      external,
-      dedupe,
-      alias,
-      plugins,
-      target: options.target ?? "es2022",
-      minify: options.minify ?? false,
-      sourcemap: options.sourcemap ?? true
-    });
-  }
-  const summaryPages = pages.map((p) => ({
-    id: p.id,
-    exportName: p.exportName ?? "default",
-    title: p.title ?? null,
-    bundlePath: `${outputPrefix}/${p.id}.js`,
-    source: p.moduleSpecifier
-  }));
-  const summaryPath = path.resolve(outputPrefixDir, SUMMARY_FILENAME);
-  write(summaryPath, JSON.stringify({ pages: summaryPages }, null, 2));
-  const digests = pages.map((p) => `${outputPrefix}/${p.id}.js`).sort().map((relPath) => {
-    const code = read(path.resolve(outDirAbs, relPath));
-    return { path: relPath, sha256: crypto.createHash("sha256").update(code, "utf8").digest("hex") };
-  });
-  const digestMapPath = path.resolve(outputPrefixDir, DIGEST_MAP_FILENAME);
-  write(digestMapPath, JSON.stringify({ digests }, null, 2));
-  logger.log(
-    `[build-pages] emitted ${pages.length} page(s) + summary + digest map (${digests.length} digests)`
-  );
-  return { pages: summaryPages, digests, summaryPath, digestMapPath };
-}
 var DEFAULT_SCHEMA = "https://ethisys.dev/schemas/feature-manifest.json";
 function computePlatformReactPages(input) {
   const routePrefix = `/extensions/${input.slug}/`;
@@ -1231,16 +1303,26 @@ function generatePlatformReactManifest(config) {
   });
   const schema = config.manifest.schema ?? DEFAULT_SCHEMA;
   const renderMode = config.manifest.renderMode ?? "platform-react";
+  const overlayEntry = config.overlay;
   const featureManifest = {
     $schema: schema,
     id: config.manifest.id,
     name: config.manifest.name,
     version: config.manifest.version,
     renderMode,
-    ui: { platformReactPages: entries }
+    ui: {
+      platformReactPages: entries,
+      ...overlayEntry !== void 0 ? { platformReactOverlay: overlayEntry } : {}
+    }
   };
   const featureManifestPath = path.resolve(root, featureManifestRel);
   fs.writeFileSync(featureManifestPath, JSON.stringify(featureManifest, null, 2) + "\n");
+  const overlayWireEntry = overlayEntry !== void 0 ? {
+    id: overlayEntry.id,
+    moduleSpecifier: overlayEntry.moduleSpecifier,
+    exportName: overlayEntry.exportName,
+    title: overlayEntry.title
+  } : void 0;
   const overlay = {
     $schema: schema,
     ui: {
@@ -1250,7 +1332,8 @@ function generatePlatformReactManifest(config) {
         exportName,
         ...route !== void 0 ? { route } : {},
         title
-      }))
+      })),
+      ...overlayWireEntry !== void 0 ? { platformReactOverlay: overlayWireEntry } : {}
     }
   };
   const overlayPath = path.resolve(root, overlayRel);