@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.32

package/src/build/browser/browser-runtime-plugin.js

@@ -1,173 +1,219 @@
-import path from "node:path";
-import { existsSync, readFileSync } from "node:fs";
-import { cachedParseSync } from "../../cache/module-parse-cache.js";
-import { getBrowserRuntimeSpecifierMap } from "./browser-runtime-manifest.js";
-import { buildSpecifierFilter } from "./browser-runtime-plugin-helpers.js";
-const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = /* @__PURE__ */ Symbol.for("ecopages.browserRuntimeImportRewriteMap");
-const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = "browser-runtime-plugin";
+/**
+ * Unified browser-runtime plugin factory.
+ *
+ * @remarks
+ * Single factory that exposes the union of behaviors for the browser
+ * runtime:
+ *
+ * - `onResolve` for manifest specifiers → mapped public URL, marked external
+ * - `onResolve` for paths starting with `/` whose target is in the manifest's
+ *   public path set → marked external
+ * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
+ *   manifest specifier set, with a `code.includes(specifier)` fast path
+ *
+ * The plugin object carries the manifest's `specifier → publicPath` map
+ * under `BROWSER_RUNTIME_IMPORT_REWRITE_MAP` so
+ * `collectBrowserRuntimeImportRewriteMap` and the post-build rewriter can
+ * read it without re-walking the manifest.
+ *
+ * This is the single source of truth for browser-runtime plugin behavior.
+ * Per-bundler bridges can treat it as a single plugin.
+ */
+import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { cachedParseSync } from '../../cache/module-parse-cache.js';
+import { getBrowserRuntimeSpecifierMap } from './browser-runtime-manifest.js';
+import { buildSpecifierFilter } from './browser-runtime-plugin-helpers.js';
+/**
+ * Symbol used to attach the manifest's `specifier → publicPath` map to a
+ * plugin instance. Consumers read it via `getBrowserRuntimeImportRewriteMap`
+ * or `collectBrowserRuntimeImportRewriteMap`.
+ */
+export const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = Symbol.for('ecopages.browserRuntimeImportRewriteMap');
+/**
+ * Default name used by `createBrowserRuntimePlugin` when the caller
+ * does not provide one.
+ */
+export const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = 'browser-runtime-plugin';
 function isRecord(value) {
-  return Boolean(value) && typeof value === "object";
+    return Boolean(value) && typeof value === 'object';
 }
 function inferLoaderFromPath(filePath) {
-  const extension = path.extname(filePath).toLowerCase();
-  switch (extension) {
-    case ".mts":
-    case ".cts":
-    case ".ts":
-      return "ts";
-    case ".tsx":
-      return "tsx";
-    case ".jsx":
-      return "jsx";
-    default:
-      return "js";
-  }
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.mts':
+        case '.cts':
+        case '.ts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        case '.jsx':
+            return 'jsx';
+        default:
+            return 'js';
+    }
 }
 function queueReplacement(options) {
-  if (!isRecord(options.source) || typeof options.source.value !== "string") {
-    return;
-  }
-  const mappedPath = options.specifierMap.get(options.source.value);
-  if (!mappedPath || typeof options.source.start !== "number" || typeof options.source.end !== "number") {
-    return;
-  }
-  const quote = options.code[options.source.start] === "'" ? "'" : '"';
-  options.edits.push({
-    start: options.source.start,
-    end: options.source.end,
-    replacement: `${quote}${mappedPath}${quote}`
-  });
-}
-function rewriteBrowserRuntimeImports(code, specifierMap, filePath = "browser-runtime-imports.js") {
-  if (specifierMap.size === 0) {
-    return code;
-  }
-  const edits = [];
-  try {
-    const result = cachedParseSync(filePath, code, {
-      sourceType: "module",
-      lang: path.extname(filePath).endsWith("x") ? "tsx" : "ts"
-    });
-    const walk = (node) => {
-      if (!isRecord(node)) {
+    if (!isRecord(options.source) || typeof options.source.value !== 'string') {
         return;
-      }
-      if (node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration") {
-        queueReplacement({ code, source: node.source, specifierMap, edits });
-      }
-      if (node.type === "ImportExpression" && isRecord(node.source)) {
-        if (node.source.type === "StringLiteral" || node.source.type === "Literal") {
-          queueReplacement({ code, source: node.source, specifierMap, edits });
-        }
-      }
-      for (const value of Object.values(node)) {
-        if (Array.isArray(value)) {
-          for (const child of value) {
-            walk(child);
-          }
-        } else {
-          walk(value);
-        }
-      }
-    };
-    walk(result.program);
-  } catch {
-    return code;
-  }
-  if (edits.length === 0) {
-    return code;
-  }
-  edits.sort((left, right) => right.start - left.start);
-  let rewritten = code;
-  for (const edit of edits) {
-    rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
-  }
-  return rewritten;
-}
-function getBrowserRuntimeImportRewriteMap(plugin) {
-  return plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP];
+    }
+    const mappedPath = options.specifierMap.get(options.source.value);
+    if (!mappedPath || typeof options.source.start !== 'number' || typeof options.source.end !== 'number') {
+        return;
+    }
+    const quote = options.code[options.source.start] === "'" ? "'" : '"';
+    options.edits.push({
+        start: options.source.start,
+        end: options.source.end,
+        replacement: `${quote}${mappedPath}${quote}`,
+    });
 }
-function collectBrowserRuntimeImportRewriteMap(plugins) {
-  const merged = /* @__PURE__ */ new Map();
-  for (const plugin of plugins ?? []) {
-    const specifierMap = getBrowserRuntimeImportRewriteMap(plugin);
-    if (!specifierMap) {
-      continue;
+/**
+ * Rewrites static ESM import/export specifiers and string-literal dynamic imports
+ * from manifest-owned runtime specifiers to concrete browser public URLs.
+ *
+ * Exposed for the post-build rewriter and for tests.
+ */
+export function rewriteBrowserRuntimeImports(code, specifierMap, filePath = 'browser-runtime-imports.js') {
+    if (specifierMap.size === 0) {
+        return code;
+    }
+    const edits = [];
+    try {
+        const result = cachedParseSync(filePath, code, {
+            sourceType: 'module',
+            lang: path.extname(filePath).endsWith('x') ? 'tsx' : 'ts',
+        });
+        const walk = (node) => {
+            if (!isRecord(node)) {
+                return;
+            }
+            if (node.type === 'ImportDeclaration' ||
+                node.type === 'ExportNamedDeclaration' ||
+                node.type === 'ExportAllDeclaration') {
+                queueReplacement({ code, source: node.source, specifierMap, edits });
+            }
+            if (node.type === 'ImportExpression' && isRecord(node.source)) {
+                if (node.source.type === 'StringLiteral' || node.source.type === 'Literal') {
+                    queueReplacement({ code, source: node.source, specifierMap, edits });
+                }
+            }
+            for (const value of Object.values(node)) {
+                if (Array.isArray(value)) {
+                    for (const child of value) {
+                        walk(child);
+                    }
+                }
+                else {
+                    walk(value);
+                }
+            }
+        };
+        walk(result.program);
+    }
+    catch {
+        return code;
     }
-    for (const [specifier, publicPath] of specifierMap.entries()) {
-      if (!merged.has(specifier)) {
-        merged.set(specifier, publicPath);
-      }
+    if (edits.length === 0) {
+        return code;
     }
-  }
-  return merged;
+    edits.sort((left, right) => right.start - left.start);
+    let rewritten = code;
+    for (const edit of edits) {
+        rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
+    }
+    return rewritten;
+}
+export function getBrowserRuntimeImportRewriteMap(plugin) {
+    return plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP];
 }
-function createBrowserRuntimePlugin(options) {
-  const { manifest } = options;
-  const specifierMap = getBrowserRuntimeSpecifierMap(manifest);
-  const specifierFilter = buildSpecifierFilter(specifierMap);
-  if (!specifierFilter) {
-    return null;
-  }
-  const external = options.external ?? true;
-  const rewriteImports = options.rewriteImports ?? true;
-  const matchPublicPaths = options.matchPublicPaths ?? true;
-  const publicPathSet = new Set(specifierMap.values());
-  const specifierKeys = Array.from(specifierMap.keys());
-  const plugin = {
-    name: options.name ?? DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
-    setup(build) {
-      build.onResolve({ filter: specifierFilter }, (args) => {
-        const mappedPath = specifierMap.get(args.path);
-        if (!mappedPath) {
-          return void 0;
+export function collectBrowserRuntimeImportRewriteMap(plugins) {
+    const merged = new Map();
+    for (const plugin of plugins ?? []) {
+        const specifierMap = getBrowserRuntimeImportRewriteMap(plugin);
+        if (!specifierMap) {
+            continue;
+        }
+        for (const [specifier, publicPath] of specifierMap.entries()) {
+            if (!merged.has(specifier)) {
+                merged.set(specifier, publicPath);
+            }
         }
-        return {
-          path: mappedPath,
-          external
-        };
-      });
-      if (matchPublicPaths) {
-        build.onResolve({ filter: /^\// }, (args) => {
-          if (!publicPathSet.has(args.path)) {
-            return void 0;
-          }
-          return {
-            path: args.path,
-            external: true
-          };
-        });
-      }
-      if (rewriteImports) {
-        build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
-          if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
-            return void 0;
-          }
-          const code = readFileSync(args.path, "utf-8");
-          if (!specifierKeys.some((specifier) => code.includes(specifier))) {
-            return void 0;
-          }
-          const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
-          if (rewritten === code) {
-            return void 0;
-          }
-          return {
-            contents: rewritten,
-            loader: inferLoaderFromPath(args.path),
-            resolveDir: path.dirname(args.path)
-          };
-        });
-      }
     }
-  };
-  plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
-  return plugin;
+    return merged;
+}
+/**
+ * Creates a build plugin that exposes the union of browser-runtime
+ * manifest behaviors (alias resolution, public-path matching, and source
+ * import/export rewrite). See {@link CreateBrowserRuntimePluginOptions}
+ * for per-behavior toggles.
+ *
+ * Returns `null` for an empty manifest so callers can short-circuit
+ * registration without sprinkling `if (plugin)` everywhere.
+ */
+export function createBrowserRuntimePlugin(options) {
+    const { manifest } = options;
+    const specifierMap = getBrowserRuntimeSpecifierMap(manifest);
+    const specifierFilter = buildSpecifierFilter(specifierMap);
+    if (!specifierFilter) {
+        return null;
+    }
+    const external = options.external ?? true;
+    const rewriteImports = options.rewriteImports ?? true;
+    const matchPublicPaths = options.matchPublicPaths ?? true;
+    const publicPathSet = new Set(specifierMap.values());
+    const specifierKeys = Array.from(specifierMap.keys());
+    const plugin = {
+        name: options.name ?? DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
+        setup(build) {
+            build.onResolve({ filter: specifierFilter }, (args) => {
+                const mappedPath = specifierMap.get(args.path);
+                if (!mappedPath) {
+                    return undefined;
+                }
+                return {
+                    path: mappedPath,
+                    external,
+                };
+            });
+            if (matchPublicPaths) {
+                build.onResolve({ filter: /^\// }, (args) => {
+                    if (!publicPathSet.has(args.path)) {
+                        return undefined;
+                    }
+                    return {
+                        path: args.path,
+                        external: true,
+                    };
+                });
+            }
+            if (rewriteImports) {
+                build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
+                    if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
+                        return undefined;
+                    }
+                    const code = readFileSync(args.path, 'utf-8');
+                    /**
+                     * Fast-path optimization: skip AST parsing for files that don't contain
+                     * any manifest-owned specifiers. This avoids expensive oxc-parser calls
+                     * on every JS/TS file in the dependency graph.
+                     */
+                    if (!specifierKeys.some((specifier) => code.includes(specifier))) {
+                        return undefined;
+                    }
+                    const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
+                    if (rewritten === code) {
+                        return undefined;
+                    }
+                    return {
+                        contents: rewritten,
+                        loader: inferLoaderFromPath(args.path),
+                        resolveDir: path.dirname(args.path),
+                    };
+                });
+            }
+        },
+    };
+    plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
+    return plugin;
 }
-export {
-  BROWSER_RUNTIME_IMPORT_REWRITE_MAP,
-  DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
-  collectBrowserRuntimeImportRewriteMap,
-  createBrowserRuntimePlugin,
-  getBrowserRuntimeImportRewriteMap,
-  rewriteBrowserRuntimeImports
-};

package/src/build/browser/jsx-ownership-plugins.js

@@ -1,41 +1,55 @@
-import { createForeignJsxOverridePlugin } from "../../plugins/foreign-jsx-override-plugin.js";
-import { collectJsxExtensions, filterJsxSourceExtensions } from "../../plugins/jsx-import-source.utils.js";
+import { createForeignJsxOverridePlugin } from '../../plugins/foreign-jsx-override-plugin.js';
+import { collectJsxExtensions, filterJsxSourceExtensions } from '../../plugins/jsx-import-source.utils.js';
 function collectJsxExtensionEntries(appConfig) {
-  return (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
-    (integration) => filterJsxSourceExtensions(integration.extensions).map((extension) => ({ integration, extension }))
-  ).sort((left, right) => right.extension.length - left.extension.length);
+    return (appConfig.integrations ?? [])
+        .filter((integration) => integration.jsxImportSource)
+        .flatMap((integration) => filterJsxSourceExtensions(integration.extensions).map((extension) => ({ integration, extension })))
+        .sort((left, right) => right.extension.length - left.extension.length);
 }
-function getJsxOwnershipPlugins(appConfig) {
-  const jsxExtensions = collectJsxExtensionEntries(appConfig);
-  return jsxExtensions.map(
-    ({ integration, extension }) => createForeignJsxOverridePlugin({
-      hostJsxImportSource: integration.jsxImportSource,
-      foreignExtensions: [extension],
-      excludeExtensions: jsxExtensions.filter((candidate) => candidate.extension.length > extension.length).filter((candidate) => candidate.extension.endsWith(extension)).map((candidate) => candidate.extension),
-      name: `ecopages-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, "-")}`
-    })
-  );
+/**
+ * Foreign JSX override plugins for mixed-integration app builds.
+ *
+ * Each plugin rewrites files for one `(integration, extension)` pair with that
+ * integration's own `@jsxImportSource` so the bundler preserves the owning JSX
+ * runtime for native extension ownership.
+ *
+ * Extensions are sorted longest-first so `.page.react.tsx` wins over `.tsx`.
+ */
+export function getJsxOwnershipPlugins(appConfig) {
+    const jsxExtensions = collectJsxExtensionEntries(appConfig);
+    return jsxExtensions.map(({ integration, extension }) => createForeignJsxOverridePlugin({
+        hostJsxImportSource: integration.jsxImportSource,
+        foreignExtensions: [extension],
+        excludeExtensions: jsxExtensions
+            .filter((candidate) => candidate.extension.length > extension.length)
+            .filter((candidate) => candidate.extension.endsWith(extension))
+            .map((candidate) => candidate.extension),
+        name: `ecopages-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, '-')}`,
+    }));
 }
-function getHostScopedJsxOwnershipPlugins(appConfig, hostIntegrationName, options) {
-  const hostIntegration = (appConfig.integrations ?? []).find(
-    (integration) => integration.name === hostIntegrationName
-  );
-  const hostJsxImportSource = hostIntegration?.jsxImportSource;
-  if (!hostJsxImportSource) {
-    return [];
-  }
-  const foreignExtensions = collectJsxExtensions(appConfig.integrations ?? [], {
-    excludeIntegrationName: hostIntegrationName
-  });
-  return [
-    createForeignJsxOverridePlugin({
-      name: options?.name ?? `ecopages-jsx-ownership-host-${hostIntegrationName}`,
-      hostJsxImportSource,
-      foreignExtensions
-    })
-  ];
+/**
+ * Host-scoped JSX override plugins for one integration's client bundle graph.
+ *
+ * When a host integration (for example React) bundles foreign `.tsx` files, those
+ * files must compile with the host JSX runtime instead of the project default.
+ * Use this helper for host-owned client bundles. For app-wide transpilation that
+ * should preserve each integration's native JSX runtime, use
+ * {@link getJsxOwnershipPlugins} instead.
+ */
+export function getHostScopedJsxOwnershipPlugins(appConfig, hostIntegrationName, options) {
+    const hostIntegration = (appConfig.integrations ?? []).find((integration) => integration.name === hostIntegrationName);
+    const hostJsxImportSource = hostIntegration?.jsxImportSource;
+    if (!hostJsxImportSource) {
+        return [];
+    }
+    const foreignExtensions = collectJsxExtensions(appConfig.integrations ?? [], {
+        excludeIntegrationName: hostIntegrationName,
+    });
+    return [
+        createForeignJsxOverridePlugin({
+            name: options?.name ?? `ecopages-jsx-ownership-host-${hostIntegrationName}`,
+            hostJsxImportSource,
+            foreignExtensions,
+        }),
+    ];
 }
-export {
-  getHostScopedJsxOwnershipPlugins,
-  getJsxOwnershipPlugins
-};

package/src/build/browser/lit-static-render-worker-context.js

@@ -1,6 +1,4 @@
-function isLitStaticRenderWorkerThread() {
-  return process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === "true";
+/** Returns whether the current thread is the Lit static-render worker. */
+export function isLitStaticRenderWorkerThread() {
+    return process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === 'true';
 }
-export {
-  isLitStaticRenderWorkerThread
-};