@ethisyscore/vite-plugin 1.74.0 → 1.76.0

package/dist/index.d.cts

@@ -468,6 +468,8 @@ interface BuildPlatformReactPagesOptions {
     external?: readonly string[];
     /** Module specifier the generated entry imports `definePluginPage` from. */
     definePluginPageSpecifier?: string;
+    /** Module specifier the generated overlay entry imports `definePluginOverlay` from. */
+    definePluginOverlaySpecifier?: string;
     /** Source dir stripped when rewriting manifest paths to the alias. Default `src`. */
     srcDir?: string;
     /** Alias prefix manifest `src/…` paths are rewritten to. Default `@` (→ `@/…`). */
@@ -491,18 +493,24 @@ interface BuildPlatformReactPagesOptions {
     /** Injectable file writer. Default `fs.writeFileSync` (creating dirs). */
     writeFile?: (path: string, contents: string) => void;
 }
+/** One built surface (a page, or the singular overlay) as recorded in the companion summary. */
+interface PlatformReactSurfaceSummary {
+    id: string;
+    exportName: string;
+    title: string | null;
+    bundlePath: string;
+    source: string;
+}
+/** One emitted bundle's SHA-256, keyed by its dist-relative path. */
+interface PlatformReactDigest {
+    path: string;
+    sha256: string;
+}
 interface PlatformReactBuildSummary {
-    pages: Array<{
-        id: string;
-        exportName: string;
-        title: string | null;
-        bundlePath: string;
-        source: string;
-    }>;
-    digests: Array<{
-        path: string;
-        sha256: string;
-    }>;
+    pages: PlatformReactSurfaceSummary[];
+    /** The singular overlay, when the manifest declares `ui.platformReactOverlay`. */
+    overlay?: PlatformReactSurfaceSummary;
+    digests: PlatformReactDigest[];
     summaryPath: string | null;
     digestMapPath: string | null;
 }

package/dist/index.d.ts

@@ -468,6 +468,8 @@ interface BuildPlatformReactPagesOptions {
     external?: readonly string[];
     /** Module specifier the generated entry imports `definePluginPage` from. */
     definePluginPageSpecifier?: string;
+    /** Module specifier the generated overlay entry imports `definePluginOverlay` from. */
+    definePluginOverlaySpecifier?: string;
     /** Source dir stripped when rewriting manifest paths to the alias. Default `src`. */
     srcDir?: string;
     /** Alias prefix manifest `src/…` paths are rewritten to. Default `@` (→ `@/…`). */
@@ -491,18 +493,24 @@ interface BuildPlatformReactPagesOptions {
     /** Injectable file writer. Default `fs.writeFileSync` (creating dirs). */
     writeFile?: (path: string, contents: string) => void;
 }
+/** One built surface (a page, or the singular overlay) as recorded in the companion summary. */
+interface PlatformReactSurfaceSummary {
+    id: string;
+    exportName: string;
+    title: string | null;
+    bundlePath: string;
+    source: string;
+}
+/** One emitted bundle's SHA-256, keyed by its dist-relative path. */
+interface PlatformReactDigest {
+    path: string;
+    sha256: string;
+}
 interface PlatformReactBuildSummary {
-    pages: Array<{
-        id: string;
-        exportName: string;
-        title: string | null;
-        bundlePath: string;
-        source: string;
-    }>;
-    digests: Array<{
-        path: string;
-        sha256: string;
-    }>;
+    pages: PlatformReactSurfaceSummary[];
+    /** The singular overlay, when the manifest declares `ui.platformReactOverlay`. */
+    overlay?: PlatformReactSurfaceSummary;
+    digests: PlatformReactDigest[];
     summaryPath: string | null;
     digestMapPath: string | null;
 }

package/dist/index.js

@@ -948,6 +948,7 @@ var PLATFORM_REACT_DEDUPE = [
 var DEFAULT_OUT_DIR = "dist";
 var DEFAULT_OUTPUT_PREFIX = "platform-react";
 var DEFAULT_DEFINE_PLUGIN_PAGE = "@/app/definePluginPage";
+var DEFAULT_DEFINE_PLUGIN_OVERLAY = "@/app/definePluginOverlay";
 var DEFAULT_SRC_DIR = "src";
 var DEFAULT_ALIAS_PREFIX = "@";
 var SUMMARY_FILENAME = "platform-react-pages.json";
@@ -996,6 +997,31 @@ export default definePluginPage(Page, { ${names.join(", ")} });
     }
   };
 }
+function virtualOverlayEntry(overlay, config) {
+  const VIRTUAL_ID = `\0virtual:surface/${overlay.id}`;
+  const views = overlay.views ?? {};
+  const names = Object.keys(views);
+  const viewImports = names.map((n) => `import { ${n} } from ${JSON.stringify(config.toAlias(views[n]))};`).join("\n");
+  const exportName = typeof overlay.exportName === "string" && overlay.exportName.length > 0 ? overlay.exportName : "default";
+  const overlayModule = JSON.stringify(config.toAlias(overlay.moduleSpecifier));
+  const overlayImport = exportName === "default" ? `import Overlay from ${overlayModule};` : `import { ${exportName} as Overlay } from ${overlayModule};`;
+  const overlayExport = exportName === "default" ? `export default definePluginOverlay(Overlay, { ${names.join(", ")} });` : `const __ehxOverlay = definePluginOverlay(Overlay, { ${names.join(", ")} });
+export { __ehxOverlay as ${exportName} };
+export default __ehxOverlay;`;
+  const src = `${overlayImport}
+${viewImports}
+import { definePluginOverlay } from ${JSON.stringify(config.definePluginOverlaySpecifier)};
+${overlayExport}
+`;
+  return {
+    id: VIRTUAL_ID,
+    plugin: {
+      name: `virtual-surface-${overlay.id}`,
+      resolveId: (id) => id === VIRTUAL_ID ? VIRTUAL_ID : null,
+      load: (id) => id === VIRTUAL_ID ? src : null
+    }
+  };
+}
 function defaultWriteFile(path, contents) {
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, contents);
@@ -1066,13 +1092,19 @@ 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");
+  const ui = manifest?.ui;
+  const declared = ui?.platformReactPages;
+  const overlayDecl = ui?.platformReactOverlay;
+  const hasPages = Array.isArray(declared) && declared.length > 0;
+  const hasOverlay = overlayDecl !== void 0 && overlayDecl !== null;
+  if (!hasPages && !hasOverlay) {
+    logger.warn(
+      "[build-pages] no platformReactPages or platformReactOverlay declared \u2014 nothing to build"
+    );
     return { pages: [], digests: [], summaryPath: null, digestMapPath: null };
   }
   const seen = /* @__PURE__ */ new Set();
-  const pages = declared.map((raw, i) => {
+  const pages = (hasPages ? 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).`);
@@ -1086,6 +1118,22 @@ async function buildPlatformReactPages(options = {}) {
     }
     return decl;
   });
+  let overlay = null;
+  if (hasOverlay) {
+    const decl = overlayDecl;
+    if (typeof decl?.id !== "string" || decl.id.length === 0) {
+      throw new Error(`[build-pages] ui.platformReactOverlay.id is required (non-empty string).`);
+    }
+    if (seen.has(decl.id)) {
+      throw new Error(
+        `[build-pages] ui.platformReactOverlay.id "${decl.id}" collides with a page id \u2014 ids must be unique across pages and the overlay.`
+      );
+    }
+    if (typeof decl.moduleSpecifier !== "string" || decl.moduleSpecifier.length === 0) {
+      throw new Error(`[build-pages] ui.platformReactOverlay "${decl.id}" has no moduleSpecifier in the manifest.`);
+    }
+    overlay = decl;
+  }
   const outDir = options.outDir ?? DEFAULT_OUT_DIR;
   const outDirAbs = isAbsolute(outDir) ? outDir : resolve(root, outDir);
   const outputPrefix = (options.outputPrefix ?? DEFAULT_OUTPUT_PREFIX).replace(/^\/+|\/+$/g, "");
@@ -1095,6 +1143,7 @@ async function buildPlatformReactPages(options = {}) {
   const alias = options.alias ?? [];
   const plugins = options.plugins ?? [];
   const definePluginPageSpecifier = options.definePluginPageSpecifier ?? DEFAULT_DEFINE_PLUGIN_PAGE;
+  const definePluginOverlaySpecifier = options.definePluginOverlaySpecifier ?? DEFAULT_DEFINE_PLUGIN_OVERLAY;
   const srcDir = options.srcDir ?? DEFAULT_SRC_DIR;
   const aliasPrefix = options.aliasPrefix ?? DEFAULT_ALIAS_PREFIX;
   const srcRe = new RegExp(`^${escapeRegExp(srcDir)}/`);
@@ -1130,6 +1179,28 @@ async function buildPlatformReactPages(options = {}) {
       sourcemap: options.sourcemap ?? true
     });
   }
+  if (overlay) {
+    const { id: entryId, plugin: surfacePlugin } = virtualOverlayEntry(overlay, {
+      definePluginOverlaySpecifier,
+      toAlias
+    });
+    logger.log(`[build-pages] ${overlay.id} \u2190 ${overlay.moduleSpecifier} (overlay)`);
+    await runBuild({
+      pageId: overlay.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",
@@ -1137,18 +1208,35 @@ async function buildPlatformReactPages(options = {}) {
     bundlePath: `${outputPrefix}/${p.id}.js`,
     source: p.moduleSpecifier
   }));
+  const summaryOverlay = overlay ? {
+    id: overlay.id,
+    exportName: overlay.exportName ?? "default",
+    title: overlay.title ?? null,
+    bundlePath: `${outputPrefix}/${overlay.id}.js`,
+    source: overlay.moduleSpecifier
+  } : void 0;
   const summaryPath = resolve(outputPrefixDir, SUMMARY_FILENAME);
-  write(summaryPath, JSON.stringify({ pages: summaryPages }, null, 2));
-  const digests = pages.map((p) => `${outputPrefix}/${p.id}.js`).sort().map((relPath) => {
+  write(
+    summaryPath,
+    JSON.stringify(
+      summaryOverlay ? { pages: summaryPages, overlay: summaryOverlay } : { pages: summaryPages },
+      null,
+      2
+    )
+  );
+  const digests = [
+    ...pages.map((p) => `${outputPrefix}/${p.id}.js`),
+    ...overlay ? [`${outputPrefix}/${overlay.id}.js`] : []
+  ].sort().map((relPath) => {
     const code = read(resolve(outDirAbs, relPath));
     return { path: relPath, sha256: createHash("sha256").update(code, "utf8").digest("hex") };
   });
   const digestMapPath = 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)`
+    `[build-pages] emitted ${pages.length} page(s)${overlay ? " + 1 overlay" : ""} + summary + digest map (${digests.length} digests)`
   );
-  return { pages: summaryPages, digests, summaryPath, digestMapPath };
+  return { pages: summaryPages, overlay: summaryOverlay, digests, summaryPath, digestMapPath };
 }
 
 // src/platform-react/page-bundles.ts