@ecopages/core 0.2.0-rc.2 → 0.2.0-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.0-rc.3",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-rc.2",
+    "@ecopages/file-system": "0.2.0-rc.3",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.141.0",
@@ -31,7 +31,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-rc.2"
+    "@ecopages/dev-toolbar": "0.2.0-rc.3"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {

package/src/services/README.md

@@ -28,6 +28,8 @@ The asset-processing service caches emitted file assets by source identity in de
 When a source file changes, its source hash or explicit invalidation removes the cached asset before the next render,
 so shared layout styles do not need to be rebuilt for every navigated page while HMR remains fresh.
 
+Browser runtime module assets resolve bare package roots through their ESM import target. For legacy packages without an `exports` map, they prefer `package.json#module` over CJS `main`; CJS resolution is only a compatibility fallback. Generated entries use `export *` for ESM files and explicit named re-exports for CJS files (so bindings such as React `jsx` exist on the vendor). A default binding is added only when the selected entry exposes one. Runtime vendors are package-root contracts: subpath imports need their own vendor declaration or remain in the consuming bundle.
+
 ## Design Rule
 
 If a concern affects more than one integration or more than one runtime adapter, it usually belongs here instead of in a package-specific implementation.

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.d.ts

@@ -2,9 +2,21 @@ import type { createRequire } from 'node:module';
 export type BrowserRuntimeDefaultExportPolicy = 'emit-default' | 'skip-default';
 type RequireFromRoot = ReturnType<typeof createRequire>;
 /**
- * Resolves a package specifier to its ESM entry file path from the app root.
+ * Resolves a package specifier through Node's ESM import conditions from the app root.
  */
 export declare function resolvePackageEsmEntryPath(specifier: string, rootDir: string): string | undefined;
+/**
+ * Resolves a browser runtime specifier to the absolute file that the generated
+ * vendor entry will import, when that import is a path.
+ *
+ * @remarks
+ * `node:` specifiers have no file path. `file:` URLs are converted to paths.
+ */
+export declare function resolveBrowserRuntimeEntryPath(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    rootDir: string;
+}): string | undefined;
 /**
  * Builds a relative import path from a generated runtime entry file to a resolved module path.
  */
@@ -13,10 +25,9 @@ export declare function toRelativeEntryImport(entryDir: string, resolvedPath: st
  * Resolves a browser runtime entry import to an ESM file path when possible.
  *
  * @remarks
- * `createRequire().resolve()` follows the `require` export condition and can
- * land on `.cjs` entrypoints. Browser vendor bundles then emit runtime
- * `require()` calls for React externals. Prefer Node's ESM resolver first, then
- * a `.cjs` → `.js` sibling fallback.
+ * Browser vendor entries resolve through ESM import conditions first. A package
+ * root without `exports` may instead select its legacy `module` field; CJS
+ * resolution is the final compatibility fallback.
  */
 export declare function resolveBrowserRuntimeEntryImport(options: {
     specifier: string;
@@ -42,11 +53,21 @@ export declare function inferBrowserRuntimeDefaultExportPolicy(options: {
     rootDir: string;
 }): BrowserRuntimeDefaultExportPolicy;
 /**
- * Reads the named runtime exports that should be re-exported from a generated runtime entry module.
+ * Returns true when the resolved vendor file is an ESM module that Rolldown can
+ * re-export with `export *`.
+ *
+ * @remarks
+ * React's published "import" files are still CJS wrappers. `export *` from those
+ * files does not emit named ESM bindings such as `jsx`.
+ */
+export declare function browserRuntimeEntryHasEsmExports(entryPath: string | undefined): boolean;
+/**
+ * Reads enumerable CJS exports from the same file the generated entry imports.
  *
  * @remarks
- * Default exports are handled separately because generated runtime entry files need to emit a
- * synthetic default binding only when the caller explicitly asks for it.
+ * Used only when {@link browserRuntimeEntryHasEsmExports} is false. ESM entries
+ * must not harvest names from `require()`, which copies class statics that are
+ * not ESM named exports.
  */
-export declare function listBrowserRuntimeModuleExportNames(specifier: string, requireFromRoot: RequireFromRoot): string[];
+export declare function listBrowserRuntimeCjsExportNames(moduleId: string, requireFromRoot: RequireFromRoot): string[];
 export {};

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.js

@@ -2,8 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { isBarePackageImportSpecifier } from '../../../plugins/tsconfig-import-resolver.js';
+import { toPackageRootSpecifier } from '../../../plugins/package-specifier.js';
 /**
- * Resolves a package specifier to its ESM entry file path from the app root.
+ * Resolves a package specifier through Node's ESM import conditions from the app root.
  */
 export function resolvePackageEsmEntryPath(specifier, rootDir) {
     try {
@@ -13,6 +14,71 @@ export function resolvePackageEsmEntryPath(specifier, rootDir) {
         return undefined;
     }
 }
+function resolveLegacyPackageModuleEntry(options) {
+    if (!isBarePackageImportSpecifier(options.specifier, options.rootDir)) {
+        return undefined;
+    }
+    const packageRoot = toPackageRootSpecifier(options.specifier);
+    if (options.specifier !== packageRoot) {
+        return undefined;
+    }
+    try {
+        const packageJsonPath = options.requireFromRoot.resolve(`${packageRoot}/package.json`);
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        if (packageJson.exports !== undefined || typeof packageJson.module !== 'string') {
+            return undefined;
+        }
+        const modulePath = path.resolve(path.dirname(packageJsonPath), packageJson.module);
+        return fs.existsSync(modulePath) ? modulePath : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const ESM_DEFAULT_EXPORT = /\bexport\s+default\b/;
+const ESM_NAMED_EXPORT = /\bexport\s+(?:[\w*{]|const|let|var|function|class)/;
+const EXPORTABLE_BINDING_NAME = /^[$A-Z_a-z][$\w]*$/;
+/**
+ * Resolves a browser runtime specifier to the absolute file that the generated
+ * vendor entry will import, when that import is a path.
+ *
+ * @remarks
+ * `node:` specifiers have no file path. `file:` URLs are converted to paths.
+ */
+export function resolveBrowserRuntimeEntryPath(options) {
+    const { specifier, requireFromRoot, rootDir } = options;
+    if (specifier.startsWith('node:')) {
+        return undefined;
+    }
+    if (specifier.startsWith('file:')) {
+        return fileURLToPath(specifier);
+    }
+    if (specifier.startsWith('.')) {
+        return requireFromRoot.resolve(specifier);
+    }
+    const esmResolvedPath = isBarePackageImportSpecifier(specifier, rootDir)
+        ? resolvePackageEsmEntryPath(specifier, rootDir)
+        : undefined;
+    const legacyModulePath = resolveLegacyPackageModuleEntry({ specifier, requireFromRoot, rootDir });
+    if (legacyModulePath) {
+        return legacyModulePath;
+    }
+    if (esmResolvedPath) {
+        return esmResolvedPath;
+    }
+    try {
+        const resolvedPath = requireFromRoot.resolve(specifier);
+        const esmSibling = resolvedPath.endsWith('.cjs')
+            ? `${resolvedPath.slice(0, -4)}.js`
+            : resolvedPath.endsWith('.cts')
+                ? `${resolvedPath.slice(0, -4)}.ts`
+                : undefined;
+        return esmSibling && fs.existsSync(esmSibling) ? esmSibling : resolvedPath;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Builds a relative import path from a generated runtime entry file to a resolved module path.
  */
@@ -27,36 +93,20 @@ export function toRelativeEntryImport(entryDir, resolvedPath) {
  * Resolves a browser runtime entry import to an ESM file path when possible.
  *
  * @remarks
- * `createRequire().resolve()` follows the `require` export condition and can
- * land on `.cjs` entrypoints. Browser vendor bundles then emit runtime
- * `require()` calls for React externals. Prefer Node's ESM resolver first, then
- * a `.cjs` → `.js` sibling fallback.
+ * Browser vendor entries resolve through ESM import conditions first. A package
+ * root without `exports` may instead select its legacy `module` field; CJS
+ * resolution is the final compatibility fallback.
  */
 export function resolveBrowserRuntimeEntryImport(options) {
     const { specifier, requireFromRoot, entryDir, rootDir } = options;
     if (specifier.startsWith('node:') || specifier.startsWith('file:')) {
         return specifier;
     }
-    if (specifier.startsWith('.')) {
-        const resolvedPath = requireFromRoot.resolve(specifier);
-        return toRelativeEntryImport(entryDir, resolvedPath);
-    }
-    if (isBarePackageImportSpecifier(specifier, rootDir)) {
-        const esmResolvedPath = resolvePackageEsmEntryPath(specifier, rootDir);
-        if (esmResolvedPath) {
-            return toRelativeEntryImport(entryDir, esmResolvedPath);
-        }
+    const entryPath = resolveBrowserRuntimeEntryPath({ specifier, requireFromRoot, rootDir });
+    if (!entryPath) {
+        throw new Error(`Unable to resolve browser runtime entry for "${specifier}" from "${rootDir}"`);
     }
-    const resolvedPath = requireFromRoot.resolve(specifier);
-    const esmSibling = resolvedPath.endsWith('.cjs')
-        ? `${resolvedPath.slice(0, -4)}.js`
-        : resolvedPath.endsWith('.cts')
-            ? `${resolvedPath.slice(0, -4)}.ts`
-            : undefined;
-    if (esmSibling && fs.existsSync(esmSibling)) {
-        return toRelativeEntryImport(entryDir, esmSibling);
-    }
-    return toRelativeEntryImport(entryDir, resolvedPath);
+    return toRelativeEntryImport(entryDir, entryPath);
 }
 /**
  * Decides whether a generated runtime entry should re-export a default binding.
@@ -72,13 +122,13 @@ export function resolveBrowserRuntimeEntryImport(options) {
  */
 export function inferBrowserRuntimeDefaultExportPolicy(options) {
     const { specifier, requireFromRoot, rootDir } = options;
-    const esmPath = resolvePackageEsmEntryPath(specifier, rootDir);
-    if (esmPath && fs.existsSync(esmPath)) {
-        const source = fs.readFileSync(esmPath, 'utf8');
-        if (/\bexport\s+default\b/.test(source)) {
+    const entryPath = resolveBrowserRuntimeEntryPath({ specifier, requireFromRoot, rootDir });
+    if (entryPath && fs.existsSync(entryPath)) {
+        const source = fs.readFileSync(entryPath, 'utf8');
+        if (ESM_DEFAULT_EXPORT.test(source)) {
             return 'emit-default';
         }
-        if (/\bexport\s+(?:[\w*{]|const|let|var|function|class)/.test(source)) {
+        if (ESM_NAMED_EXPORT.test(source)) {
             return 'skip-default';
         }
     }
@@ -94,22 +144,38 @@ export function inferBrowserRuntimeDefaultExportPolicy(options) {
     }
 }
 /**
- * Reads the named runtime exports that should be re-exported from a generated runtime entry module.
+ * Returns true when the resolved vendor file is an ESM module that Rolldown can
+ * re-export with `export *`.
+ *
+ * @remarks
+ * React's published "import" files are still CJS wrappers. `export *` from those
+ * files does not emit named ESM bindings such as `jsx`.
+ */
+export function browserRuntimeEntryHasEsmExports(entryPath) {
+    if (!entryPath || !fs.existsSync(entryPath)) {
+        return true;
+    }
+    const source = fs.readFileSync(entryPath, 'utf8');
+    return ESM_DEFAULT_EXPORT.test(source) || ESM_NAMED_EXPORT.test(source);
+}
+/**
+ * Reads enumerable CJS exports from the same file the generated entry imports.
  *
  * @remarks
- * Default exports are handled separately because generated runtime entry files need to emit a
- * synthetic default binding only when the caller explicitly asks for it.
+ * Used only when {@link browserRuntimeEntryHasEsmExports} is false. ESM entries
+ * must not harvest names from `require()`, which copies class statics that are
+ * not ESM named exports.
  */
-export function listBrowserRuntimeModuleExportNames(specifier, requireFromRoot) {
+export function listBrowserRuntimeCjsExportNames(moduleId, requireFromRoot) {
     let moduleExports;
     try {
-        moduleExports = requireFromRoot(specifier);
+        moduleExports = requireFromRoot(moduleId);
     }
     catch {
         return [];
     }
     return Object.keys(moduleExports)
         .filter((name) => name !== '__esModule' && name !== 'default')
-        .filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name))
+        .filter((name) => EXPORTABLE_BINDING_NAME.test(name))
         .sort();
 }

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.d.ts

@@ -12,6 +12,8 @@ export type BrowserRuntimeEntryModuleConfig = {
  * logic themselves. The generated file lives under the app work directory so
  * repeated runs can reuse the same location without placing sources inside
  * `node_modules`, which can cause bundlers to externalize bare imports.
+ * ESM entries use `export *`. CJS entries emit explicit named re-exports from
+ * that same file so Rolldown can synthesize ESM bindings such as `jsx`.
  */
 export declare function createBrowserRuntimeEntryModule(options: {
     modules: BrowserRuntimeEntryModuleConfig[];

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { DEFAULT_ECOPAGES_WORK_DIR } from '../../../config/constants.js';
-import { inferBrowserRuntimeDefaultExportPolicy, listBrowserRuntimeModuleExportNames, resolveBrowserRuntimeEntryImport, } from './browser-runtime-entry-resolution.js';
+import { browserRuntimeEntryHasEsmExports, inferBrowserRuntimeDefaultExportPolicy, listBrowserRuntimeCjsExportNames, resolveBrowserRuntimeEntryImport, resolveBrowserRuntimeEntryPath, } from './browser-runtime-entry-resolution.js';
 /**
  * Creates a generated ESM entry module that re-exports runtime modules through
  * one stable file.
@@ -13,6 +13,8 @@ import { inferBrowserRuntimeDefaultExportPolicy, listBrowserRuntimeModuleExportN
  * logic themselves. The generated file lives under the app work directory so
  * repeated runs can reuse the same location without placing sources inside
  * `node_modules`, which can cause bundlers to externalize bare imports.
+ * ESM entries use `export *`. CJS entries emit explicit named re-exports from
+ * that same file so Rolldown can synthesize ESM bindings such as `jsx`.
  */
 export function createBrowserRuntimeEntryModule(options) {
     if (options.modules.some((module) => !module.specifier.startsWith('node:')) && !options.rootDir) {
@@ -34,13 +36,22 @@ export function createBrowserRuntimeEntryModule(options) {
             entryDir,
             rootDir,
         });
+        const entryPath = resolveBrowserRuntimeEntryPath({
+            specifier: module.specifier,
+            requireFromRoot,
+            rootDir,
+        });
         if (module.defaultExport &&
             inferBrowserRuntimeDefaultExportPolicy({ specifier: module.specifier, requireFromRoot, rootDir }) ===
                 'emit-default') {
             statements.push(`import __ecopages_default_export__ from '${importSpecifier}';`);
             statements.push('export default __ecopages_default_export__;');
         }
-        const exportNames = listBrowserRuntimeModuleExportNames(module.specifier, requireFromRoot).filter((name) => !seenExports.has(name));
+        if (browserRuntimeEntryHasEsmExports(entryPath)) {
+            statements.push(`export * from '${importSpecifier}';`);
+            continue;
+        }
+        const exportNames = listBrowserRuntimeCjsExportNames(entryPath ?? module.specifier, requireFromRoot).filter((name) => !seenExports.has(name));
         if (exportNames.length > 0) {
             statements.push(`export { ${exportNames.join(', ')} } from '${importSpecifier}';`);
             for (const exportName of exportNames) {