@ecopages/core 0.2.0-beta.24 → 0.2.0-beta.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.24",
+  "version": "0.2.0-beta.26",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.24",
+    "@ecopages/file-system": "0.2.0-beta.26",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -26,6 +26,7 @@
     "esbuild": "^0.28.0",
     "ghtml": "^4.0.2",
     "oxc-parser": "^0.124.0",
+    "oxc-resolver": "^11.24.2",
     "rolldown": "^1.1.0",
     "ws": "^8.20.1",
     "@standard-schema/spec": "^1.1.0",
@@ -219,6 +220,14 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
+    "./plugins/alias-resolver-plugin": {
+      "types": "./src/plugins/alias-resolver-plugin.d.ts",
+      "default": "./src/plugins/alias-resolver-plugin.js"
+    },
+    "./plugins/tsconfig-import-resolver": {
+      "types": "./src/plugins/tsconfig-import-resolver.d.ts",
+      "default": "./src/plugins/tsconfig-import-resolver.js"
+    },
     "./plugins/jsx-import-source.utils": {
       "types": "./src/plugins/jsx-import-source.utils.d.ts",
       "default": "./src/plugins/jsx-import-source.utils.js"
@@ -432,6 +441,14 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
+    "./plugins/alias-resolver-plugin.ts": {
+      "types": "./src/plugins/alias-resolver-plugin.d.ts",
+      "default": "./src/plugins/alias-resolver-plugin.js"
+    },
+    "./plugins/tsconfig-import-resolver.ts": {
+      "types": "./src/plugins/tsconfig-import-resolver.d.ts",
+      "default": "./src/plugins/tsconfig-import-resolver.js"
+    },
     "./plugins/jsx-import-source.utils.ts": {
       "types": "./src/plugins/jsx-import-source.utils.d.ts",
       "default": "./src/plugins/jsx-import-source.utils.js"

package/src/build/build-adapter.js

@@ -120,16 +120,16 @@ import {
   setupAppRuntimePlugins
 } from "./app-build-manifest-runtime.js";
 function getAppServerBuildPlugins(appConfig) {
-  const srcDir = appConfig.absolutePaths?.srcDir;
-  const aliasPlugin = srcDir ? [createAliasResolverPlugin(srcDir)] : [];
+  const projectDir = appConfig.absolutePaths?.projectDir;
+  const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
   return [...aliasPlugin, ...getServerBuildPlugins(getAppBuildManifest(appConfig))];
 }
 function getAppBrowserBuildPlugins(appConfig) {
   const manifest = getAppBuildManifest(appConfig);
   const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
   const browserPlugins = getBrowserBuildPlugins(manifest).filter((plugin) => !sourceTransformNames.has(plugin.name));
-  const srcDir = appConfig.absolutePaths?.srcDir;
-  const aliasPlugin = srcDir ? [createAliasResolverPlugin(srcDir)] : [];
+  const projectDir = appConfig.absolutePaths?.projectDir;
+  const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
   return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
 }
 function build(options, executor = defaultRolldownBuildAdapter) {

package/src/build/rolldown-adapter-helpers.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { isBarePackageImportSpecifier } from "../plugins/tsconfig-import-resolver.js";
 import { collectBrowserRuntimeImportRewriteMap, rewriteBrowserRuntimeImports } from "./browser-runtime-plugin.js";
 import { createServerSideCssShimPlugin } from "./server-side-css-shim-plugin.js";
 import { createRolldownPluginBridge } from "./rolldown-plugin-bridge.js";
@@ -48,8 +49,8 @@ function transpileProfileToOptions(profile) {
       };
   }
 }
-function isPackageImport(id) {
-  return !id.startsWith(".") && !path.isAbsolute(id) && !id.startsWith("/") && !id.startsWith("node:") && !id.startsWith("@/") && !id.startsWith("~/") && !id.startsWith("#") && !id.includes(":");
+function isPackageImport(id, contextRoot) {
+  return isBarePackageImportSpecifier(id, contextRoot);
 }
 function tryResolveModule(id, resolver) {
   try {
@@ -92,7 +93,7 @@ function createExternalMatcher(options, appRootRequireCache) {
     if (explicitExternals.has(id)) {
       return true;
     }
-    if (!externalPackages || !isPackageImport(id)) {
+    if (!externalPackages || !isPackageImport(id, contextRoot)) {
       return false;
     }
     return !shouldBundlePackageImport(id, contextRoot, appRootRequireCache);

package/src/build/runtime-build-output-normalizer.js

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { isBarePackageImportSpecifier } from "../plugins/tsconfig-import-resolver.js";
 const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
 const appDeclaredPackageCache = /* @__PURE__ */ new Map();
 const appWorkspacePackageCache = /* @__PURE__ */ new Map();
@@ -13,9 +14,6 @@ function tryResolveRuntimeImport(specifier, resolver) {
     return void 0;
   }
 }
-function isBareRuntimeImport(specifier) {
-  return !specifier.startsWith(".") && !path.isAbsolute(specifier) && !specifier.startsWith("/") && !specifier.startsWith("node:") && !specifier.startsWith("@/") && !specifier.startsWith("~/") && !specifier.startsWith("#") && !specifier.includes(":");
-}
 function extractPackageNameFromFileUrl(specifier) {
   if (!specifier.startsWith("file://")) {
     return void 0;
@@ -108,7 +106,7 @@ function isDeclaredInResolutionChain(specifier, rootDir) {
   return isDeclaredAppPackageImport(specifier, rootDir);
 }
 function rewriteRuntimeImportSpecifier(specifier, quote, rootDir) {
-  if (!isBareRuntimeImport(specifier)) {
+  if (!isBarePackageImportSpecifier(specifier, rootDir)) {
     return void 0;
   }
   if (isDeclaredInResolutionChain(specifier, rootDir)) {

package/src/eco/eco.types.d.ts

@@ -72,7 +72,18 @@ export interface ComponentOptions<P, E = EcoPagesElement> {
     render: (props: P) => E | Promise<E>;
 }
 export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
-export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E> & {
+    /**
+     * Marks this layout as mounting shared client runtime state such as React context
+     * providers or query clients.
+     *
+     * @remarks
+     * When any layout in the app sets this flag, only flagged layouts participate in
+     * React auto-vendoring discovery. This keeps shell-only layouts out of provider
+     * scans while persisted SPA navigation stays on one shared vendor instance.
+     */
+    runtimeProvider?: boolean;
+};
 /**
  * Base options shared by all page variants
  */

package/src/plugins/alias-resolver-cache.d.ts

@@ -1,17 +1,14 @@
 /**
- * Per-plugin cache for `@/...` alias resolution.
+ * Per-plugin cache for tsconfig path alias resolution.
  *
  * @remarks
- * The `ecopages-alias-resolver` plugin resolves project aliases like
- * `@/components/Button` to concrete file paths under the app's `srcDir`.
- * Each resolution can trigger up to 22 `existsSync` calls and (when
- * the resolved path is a barrel) a `readFileSync` to detect
- * `export * from './...'` forwarding.
+ * The `ecopages-alias-resolver` plugin resolves project path aliases to
+ * concrete file paths using the app's tsconfig `paths`. Each resolution goes
+ * through oxc-resolver and may read barrel re-export targets.
  *
- * This cache memoizes the result keyed by `(srcDir, specifier)`. It is
+ * This cache memoizes the result keyed by `(projectRoot, specifier)`. It is
  * process-local and not currently invalidated by the file watcher —
- * `srcDir` contents are assumed to be stable for the lifetime of the
- * process.
+ * project contents are assumed to be stable for the lifetime of the process.
  */
 export declare class AliasResolverCache {
     private readonly entries;

package/src/plugins/alias-resolver-plugin.d.ts

@@ -1,6 +1,6 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import { AliasResolverCache } from './alias-resolver-cache.js';
-export declare function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined;
-export declare function createAliasResolverPlugin(srcDir: string, options?: {
+export declare function createAliasResolverPlugin(projectRoot: string, options?: {
     cache?: AliasResolverCache;
 }): EcoBuildPlugin;
+export { isBarePackageImportSpecifier, matchesTsconfigPathPrefix, loadTsconfigPathPrefixes, resolveProjectImportPath, resolveProjectModulePath, } from './tsconfig-import-resolver.js';

package/src/plugins/alias-resolver-plugin.js

@@ -1,65 +1,52 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
 import { AliasResolverCache } from "./alias-resolver-cache.js";
-const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
-function findResolvablePath(candidate) {
-  if (path.extname(candidate)) {
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const fileCandidate = `${candidate}${extension}`;
-    if (existsSync(fileCandidate)) {
-      return fileCandidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const indexCandidate = path.join(candidate, `index${extension}`);
-    if (existsSync(indexCandidate)) {
-      return indexCandidate;
-    }
-  }
-  return void 0;
-}
-function resolveAliasedBarrelTarget(resolvedPath) {
-  if (!path.basename(resolvedPath).startsWith("index.")) {
-    return resolvedPath;
-  }
-  const source = readFileSync(resolvedPath, "utf8").trim();
-  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
-  if (!match?.[1]?.startsWith(".")) {
-    return resolvedPath;
-  }
-  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
-  return target ?? resolvedPath;
+import { loadTsconfigPathPrefixes, resolveProjectImportPath } from "./tsconfig-import-resolver.js";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function resolveAppSourceAliasPath(srcDir, specifier) {
-  if (!specifier.startsWith("@/")) {
-    return void 0;
+function buildPathPrefixFilter(prefix) {
+  if (prefix.endsWith("/")) {
+    return new RegExp(`^${escapeRegExp(prefix)}`);
   }
-  const candidate = path.join(srcDir, specifier.slice(2));
-  const resolved = findResolvablePath(candidate);
-  return resolved ? resolveAliasedBarrelTarget(resolved) : void 0;
+  return new RegExp(`^${escapeRegExp(prefix)}(?:/|$)`);
 }
-function createAliasResolverPlugin(srcDir, options) {
+function createAliasResolverPlugin(projectRoot, options) {
   const cache = options?.cache ?? new AliasResolverCache();
+  const pathPrefixes = loadTsconfigPathPrefixes(projectRoot);
   return {
     name: "ecopages-alias-resolver",
     setup(build) {
-      build.onResolve({ filter: /^@\// }, (args) => {
-        const cached = cache.get(srcDir, args.path);
-        if (cached.hit) {
-          return cached.resolved ? { path: cached.resolved } : {};
-        }
-        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
-        cache.set(srcDir, args.path, resolved);
-        return resolved ? { path: resolved } : {};
-      });
+      if (pathPrefixes.length === 0) {
+        return;
+      }
+      for (const prefix of pathPrefixes) {
+        build.onResolve({ filter: buildPathPrefixFilter(prefix) }, (args) => {
+          if (!args.importer) {
+            return void 0;
+          }
+          const cached = cache.get(projectRoot, args.path);
+          if (cached.hit) {
+            return cached.resolved ? { path: cached.resolved } : void 0;
+          }
+          const resolved = resolveProjectImportPath(projectRoot, args.importer, args.path);
+          cache.set(projectRoot, args.path, resolved);
+          return resolved ? { path: resolved } : void 0;
+        });
+      }
     }
   };
 }
+import {
+  isBarePackageImportSpecifier,
+  matchesTsconfigPathPrefix,
+  loadTsconfigPathPrefixes as loadTsconfigPathPrefixes2,
+  resolveProjectImportPath as resolveProjectImportPath2,
+  resolveProjectModulePath
+} from "./tsconfig-import-resolver.js";
 export {
   createAliasResolverPlugin,
-  resolveAppSourceAliasPath
+  isBarePackageImportSpecifier,
+  loadTsconfigPathPrefixes2 as loadTsconfigPathPrefixes,
+  matchesTsconfigPathPrefix,
+  resolveProjectImportPath2 as resolveProjectImportPath,
+  resolveProjectModulePath
 };

package/src/plugins/tsconfig-import-resolver.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Loads `compilerOptions.paths` keys from tsconfig, following `extends` recursively.
+ */
+export declare function loadTsconfigPathPrefixes(projectRoot: string): string[];
+export declare function matchesTsconfigPathPrefix(specifier: string, prefixes: readonly string[]): boolean;
+/**
+ * Returns true when `specifier` looks like a bare npm package import rather than
+ * a relative path, absolute path, node built-in, tsconfig alias, or `#` import map.
+ */
+export declare function isBarePackageImportSpecifier(specifier: string, projectRoot?: string): boolean;
+/**
+ * Resolves a relative or tsconfig path alias import (via oxc-resolver).
+ */
+export declare function resolveProjectModulePath(projectRoot: string, fromFile: string, specifier: string): string | undefined;
+/**
+ * Resolves a TS path alias import using the app's tsconfig `paths` (via oxc-resolver).
+ */
+export declare function resolveProjectImportPath(projectRoot: string, fromFile: string, specifier: string): string | undefined;

package/src/plugins/tsconfig-import-resolver.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { ResolverFactory } from "oxc-resolver";
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx"];
+const resolverCache = /* @__PURE__ */ new Map();
+const pathPrefixCache = /* @__PURE__ */ new Map();
+function stripJsonComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+function findTsconfigPath(projectRoot) {
+  const candidate = path.join(projectRoot, "tsconfig.json");
+  return existsSync(candidate) ? candidate : void 0;
+}
+function readJsonFile(filePath) {
+  const source = readFileSync(filePath, "utf8");
+  try {
+    return JSON.parse(source);
+  } catch {
+    return JSON.parse(stripJsonComments(source));
+  }
+}
+function loadTsconfigPathPrefixes(projectRoot) {
+  const cached = pathPrefixCache.get(projectRoot);
+  if (cached) {
+    return cached;
+  }
+  const tsconfigPath = findTsconfigPath(projectRoot);
+  if (!tsconfigPath) {
+    pathPrefixCache.set(projectRoot, []);
+    return [];
+  }
+  const prefixes = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const collectFromConfig = (configPath) => {
+    const normalized = path.resolve(configPath);
+    if (visited.has(normalized)) {
+      return;
+    }
+    visited.add(normalized);
+    let config;
+    try {
+      config = readJsonFile(normalized);
+    } catch {
+      return;
+    }
+    if (typeof config.extends === "string") {
+      const parentPath = path.resolve(path.dirname(normalized), config.extends);
+      collectFromConfig(parentPath);
+    }
+    for (const key of Object.keys(config.compilerOptions?.paths ?? {})) {
+      if (key.endsWith("/*")) {
+        prefixes.add(key.slice(0, -1));
+        continue;
+      }
+      if (key.endsWith("*")) {
+        prefixes.add(key.slice(0, -1));
+        continue;
+      }
+      prefixes.add(key);
+    }
+  };
+  collectFromConfig(tsconfigPath);
+  const resolvedPrefixes = [...prefixes];
+  pathPrefixCache.set(projectRoot, resolvedPrefixes);
+  return resolvedPrefixes;
+}
+function matchesTsconfigPathPrefix(specifier, prefixes) {
+  return prefixes.some((prefix) => {
+    if (prefix.endsWith("/")) {
+      return specifier.startsWith(prefix);
+    }
+    return specifier === prefix || specifier.startsWith(`${prefix}/`);
+  });
+}
+function isBarePackageImportSpecifier(specifier, projectRoot) {
+  if (specifier.startsWith(".") || path.isAbsolute(specifier) || specifier.startsWith("/")) {
+    return false;
+  }
+  if (specifier.startsWith("node:") || specifier.startsWith("#") || specifier.includes(":")) {
+    return false;
+  }
+  if (projectRoot && matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+    return false;
+  }
+  return true;
+}
+function getResolverFactory(projectRoot) {
+  const cached = resolverCache.get(projectRoot);
+  if (cached) {
+    return cached;
+  }
+  const tsconfigPath = findTsconfigPath(projectRoot);
+  if (!tsconfigPath) {
+    return void 0;
+  }
+  const resolver = new ResolverFactory({
+    tsconfig: {
+      configFile: tsconfigPath
+    },
+    extensions: [...RESOLVABLE_EXTENSIONS]
+  });
+  resolverCache.set(projectRoot, resolver);
+  return resolver;
+}
+function resolveAliasedBarrelTarget(resolvedPath) {
+  if (!path.basename(resolvedPath).startsWith("index.")) {
+    return resolvedPath;
+  }
+  const source = readFileSync(resolvedPath, "utf8").trim();
+  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+  if (!match?.[1]?.startsWith(".")) {
+    return resolvedPath;
+  }
+  const targetDir = path.dirname(resolvedPath);
+  const targetBase = path.resolve(targetDir, match[1]);
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const candidate = `${targetBase}${extension}`;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const candidate = path.join(targetBase, `index${extension}`);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return resolvedPath;
+}
+function resolveProjectModulePath(projectRoot, fromFile, specifier) {
+  const prefixes = loadTsconfigPathPrefixes(projectRoot);
+  const isRelative = specifier.startsWith(".");
+  const isPathAlias = matchesTsconfigPathPrefix(specifier, prefixes);
+  if (!isRelative && !isPathAlias) {
+    return void 0;
+  }
+  const resolver = getResolverFactory(projectRoot);
+  if (!resolver) {
+    return void 0;
+  }
+  const result = resolver.sync(path.dirname(fromFile), specifier);
+  if (!result.path) {
+    return void 0;
+  }
+  return resolveAliasedBarrelTarget(realpathSync(result.path));
+}
+function resolveProjectImportPath(projectRoot, fromFile, specifier) {
+  if (!matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+    return void 0;
+  }
+  return resolveProjectModulePath(projectRoot, fromFile, specifier);
+}
+export {
+  isBarePackageImportSpecifier,
+  loadTsconfigPathPrefixes,
+  matchesTsconfigPathPrefix,
+  resolveProjectImportPath,
+  resolveProjectModulePath
+};

package/src/services/assets/asset-processing-service/asset-dependency-keys.d.ts

@@ -1,3 +1,16 @@
 import type { AssetDefinition } from './assets.types.js';
+/**
+ * Stable identity for dependency deduplication and {@link AssetProcessingService} cache lookups.
+ *
+ * @remarks
+ * Script dependencies include a build signature derived from bundle flags, grouped-bundle
+ * metadata, and selected `bundleOptions` fields (`naming`, `external`, `minify`, plugin names).
+ * HTML-affecting script `attributes` are hashed into the key so dedupe and cache reuse do not
+ * collapse declarations that would emit different `<script>` tags. Full plugin objects and
+ * `NODE_ENV` are excluded from the key.
+ *
+ * Runtime minify in {@link ContentScriptProcessor} still follows `NODE_ENV` via
+ * `isProduction`, not `bundleOptions.minify`.
+ */
 export declare function getAssetDependencyKey(dep: AssetDefinition): string;
 export declare function deduplicateAssetDependencies(deps: AssetDefinition[]): AssetDefinition[];

package/src/services/assets/asset-processing-service/asset-dependency-keys.js

@@ -34,6 +34,9 @@ function getAssetDependencyKey(dep) {
   if ("packageRole" in dep && dep.packageRole) {
     parts.push(`package:${dep.packageRole}`);
   }
+  if (dep.kind === "script" && dep.attributes) {
+    parts.push(`attrs:${generateHash(JSON.stringify(dep.attributes))}`);
+  }
   const scriptBuildSignature = getScriptDependencyBuildSignature(dep);
   if (scriptBuildSignature) {
     parts.push(`build:${scriptBuildSignature}`);

package/src/services/assets/asset-processing-service/asset-processing.service.d.ts

@@ -39,7 +39,9 @@ export declare class AssetProcessingService {
      * @remarks
      * Dependencies are deduplicated before processor execution so repeated
      * declarations across the render tree reuse the same emitted outputs and cache
-     * entries.
+     * entries. Returned asset order is unspecified — consumers must re-associate
+     * outputs with inputs via dependency metadata such as `groupedBundle`, not by
+     * array index alignment with the input list.
      */
     processDependencies(deps: AssetDefinition[], key: string): Promise<ProcessedAsset[]>;
     private prepareDependenciesForProcessing;

package/src/services/assets/asset-processing-service/asset-processing.service.js

@@ -69,7 +69,9 @@ class AssetProcessingService {
    * @remarks
    * Dependencies are deduplicated before processor execution so repeated
    * declarations across the render tree reuse the same emitted outputs and cache
-   * entries.
+   * entries. Returned asset order is unspecified — consumers must re-associate
+   * outputs with inputs via dependency metadata such as `groupedBundle`, not by
+   * array index alignment with the input list.
    */
   async processDependencies(deps, key) {
     const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);

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

@@ -0,0 +1,52 @@
+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.
+ */
+export declare function resolvePackageEsmEntryPath(specifier: string, rootDir: string): string | undefined;
+/**
+ * Builds a relative import path from a generated runtime entry file to a resolved module path.
+ */
+export declare function toRelativeEntryImport(entryDir: string, resolvedPath: string): string;
+/**
+ * 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.
+ */
+export declare function resolveBrowserRuntimeEntryImport(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    entryDir: string;
+    rootDir: string;
+}): string;
+/**
+ * Decides whether a generated runtime entry should re-export a default binding.
+ *
+ * @remarks
+ * ESM-only packages such as `@tanstack/react-query` expose named exports only.
+ * Legacy CJS packages such as `react` assign `module.exports` directly and have
+ * no `.default` under `require()`, but still need a default re-export for
+ * `import React from 'react'` in browser bundles.
+ *
+ * ESM source inspection is a best-effort fast path; when it is inconclusive the
+ * policy falls back to the shape returned by `require()`.
+ */
+export declare function inferBrowserRuntimeDefaultExportPolicy(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    rootDir: string;
+}): BrowserRuntimeDefaultExportPolicy;
+/**
+ * Reads the named runtime exports that should be re-exported from a generated runtime entry module.
+ *
+ * @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.
+ */
+export declare function listBrowserRuntimeModuleExportNames(specifier: string, requireFromRoot: RequireFromRoot): string[];
+export {};

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

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { isBarePackageImportSpecifier } from "../../../plugins/tsconfig-import-resolver.js";
+function resolvePackageEsmEntryPath(specifier, rootDir) {
+  try {
+    return fileURLToPath(import.meta.resolve(specifier, pathToFileURL(path.join(rootDir, "package.json")).href));
+  } catch {
+    return void 0;
+  }
+}
+function toRelativeEntryImport(entryDir, resolvedPath) {
+  let relativePath = path.relative(entryDir, resolvedPath).replace(/\\/g, "/");
+  if (!relativePath.startsWith(".")) {
+    relativePath = `./${relativePath}`;
+  }
+  return relativePath;
+}
+function resolveBrowserRuntimeEntryImport(options) {
+  const { specifier, requireFromRoot, entryDir, rootDir } = options;
+  if (specifier.startsWith("node:") || specifier.startsWith("file:")) {
+    return specifier;
+  }
+  if (specifier.startsWith(".")) {
+    const resolvedPath2 = requireFromRoot.resolve(specifier);
+    return toRelativeEntryImport(entryDir, resolvedPath2);
+  }
+  if (isBarePackageImportSpecifier(specifier, rootDir)) {
+    const esmResolvedPath = resolvePackageEsmEntryPath(specifier, rootDir);
+    if (esmResolvedPath) {
+      return toRelativeEntryImport(entryDir, esmResolvedPath);
+    }
+  }
+  const resolvedPath = requireFromRoot.resolve(specifier);
+  const esmSibling = resolvedPath.endsWith(".cjs") ? `${resolvedPath.slice(0, -4)}.js` : resolvedPath.endsWith(".cts") ? `${resolvedPath.slice(0, -4)}.ts` : void 0;
+  if (esmSibling && fs.existsSync(esmSibling)) {
+    return toRelativeEntryImport(entryDir, esmSibling);
+  }
+  return toRelativeEntryImport(entryDir, resolvedPath);
+}
+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)) {
+      return "emit-default";
+    }
+    if (/\bexport\s+(?:[\w*{]|const|let|var|function|class)/.test(source)) {
+      return "skip-default";
+    }
+  }
+  try {
+    const moduleExports = requireFromRoot(specifier);
+    if (moduleExports.default !== void 0) {
+      return "emit-default";
+    }
+    return moduleExports.__esModule === true ? "skip-default" : "emit-default";
+  } catch {
+    return "skip-default";
+  }
+}
+function listBrowserRuntimeModuleExportNames(specifier, requireFromRoot) {
+  let moduleExports;
+  try {
+    moduleExports = requireFromRoot(specifier);
+  } catch {
+    return [];
+  }
+  return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();
+}
+export {
+  inferBrowserRuntimeDefaultExportPolicy,
+  listBrowserRuntimeModuleExportNames,
+  resolveBrowserRuntimeEntryImport,
+  resolvePackageEsmEntryPath,
+  toRelativeEntryImport
+};

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

@@ -2,6 +2,11 @@ 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";
 function createBrowserRuntimeEntryModule(options) {
   if (options.modules.some((module) => !module.specifier.startsWith("node:")) && !options.rootDir) {
     throw new Error("createBrowserRuntimeEntryModule requires rootDir to resolve package specifiers");
@@ -20,12 +25,17 @@ function createBrowserRuntimeEntryModule(options) {
   const filePath = path.join(artifactsDir, options.fileName);
   const entryDir = path.dirname(filePath);
   for (const module of options.modules) {
-    const importSpecifier = resolveEntryImportSpecifier(module.specifier, requireFromRoot, entryDir);
-    if (module.defaultExport) {
+    const importSpecifier = resolveBrowserRuntimeEntryImport({
+      specifier: module.specifier,
+      requireFromRoot,
+      entryDir,
+      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 = getModuleExportNames(module.specifier, requireFromRoot).filter(
+    const exportNames = listBrowserRuntimeModuleExportNames(module.specifier, requireFromRoot).filter(
       (name) => !seenExports.has(name)
     );
     if (exportNames.length > 0) {
@@ -41,21 +51,6 @@ function createBrowserRuntimeEntryModule(options) {
   }
   return filePath;
 }
-function resolveEntryImportSpecifier(specifier, requireFromRoot, entryDir) {
-  if (specifier.startsWith("node:") || specifier.startsWith("file:")) {
-    return specifier;
-  }
-  const resolvedPath = requireFromRoot.resolve(specifier);
-  let relativePath = path.relative(entryDir, resolvedPath).replace(/\\/g, "/");
-  if (!relativePath.startsWith(".")) {
-    relativePath = `./${relativePath}`;
-  }
-  return relativePath;
-}
-function getModuleExportNames(specifier, requireFromRoot) {
-  const moduleExports = requireFromRoot(specifier);
-  return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();
-}
 export {
   createBrowserRuntimeEntryModule
 };

package/src/services/assets/asset-processing-service/grouped-content-bundles.js

@@ -1,5 +1,8 @@
 import { isDevelopmentRuntime } from "../../../utils/runtime.js";
 import { finalizeProcessedAsset } from "./finalize-processed-asset.js";
+function getGroupedBundleAssetKey(groupedBundle) {
+  return `${groupedBundle.id}:${groupedBundle.entryName}`;
+}
 function ensureGroupedContentScriptsBundle(dependencies) {
   if (isDevelopmentRuntime()) {
     return;
@@ -54,12 +57,25 @@ async function processGroupedDependencyBundles(options) {
     }
     try {
       const processedResults = await processor.processGrouped(bundleDeps);
-      return processedResults.map((processed, index) => {
-        const dep = bundleDeps[index];
+      const processedByEntryKey = /* @__PURE__ */ new Map();
+      for (const processed of processedResults) {
+        if (!processed.groupedBundle) {
+          continue;
+        }
+        processedByEntryKey.set(getGroupedBundleAssetKey(processed.groupedBundle), processed);
+      }
+      return bundleDeps.flatMap((dep) => {
+        if (dep.kind !== "script" || dep.source !== "content" || !dep.groupedBundle) {
+          return [];
+        }
+        const processed = processedByEntryKey.get(getGroupedBundleAssetKey(dep.groupedBundle));
+        if (!processed) {
+          return [];
+        }
         const depKey = getDependencyKey(dep);
         const finalized = finalizeProcessedAsset(processed, resolveProcessedAssetSrcUrl);
         setCachedAsset(dep, depKey, finalized);
-        return finalized;
+        return [finalized];
       });
     } catch (error) {
       logError(error);

package/src/services/assets/asset-processing-service/index.d.ts

@@ -5,3 +5,4 @@ export * from './asset-processing.service.js';
 export * from './assets.types.js';
 export * from './browser-runtime-asset.factory.js';
 export * from './browser-runtime-entry.factory.js';
+export * from './browser-runtime-entry-resolution.js';

package/src/services/assets/asset-processing-service/index.js

@@ -5,3 +5,4 @@ export * from "./asset-processing.service.js";
 export * from "./assets.types.js";
 export * from "./browser-runtime-asset.factory.js";
 export * from "./browser-runtime-entry.factory.js";
+export * from "./browser-runtime-entry-resolution.js";

package/src/services/assets/asset-processing-service/inline-content-script-body.d.ts

@@ -0,0 +1,11 @@
+import type { ContentScriptAsset } from './assets.types.js';
+/**
+ * Resolves the script body to embed when a content script is marked inline.
+ *
+ * @remarks
+ * `inline` means embed in HTML, not "use declaration source." When bundling has
+ * already run, only the output file is valid browser script; `dep.content` may
+ * still contain build-time import paths. Processor emission and cache
+ * materialization must share this rule so they cannot drift.
+ */
+export declare function resolveInlineContentScriptBody(dep: Pick<ContentScriptAsset, 'inline' | 'bundle' | 'content'>, filepath: string): string | undefined;

package/src/services/assets/asset-processing-service/inline-content-script-body.js

@@ -0,0 +1,17 @@
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../../global/app-logger.js";
+function resolveInlineContentScriptBody(dep, filepath) {
+  if (!dep.inline) {
+    return void 0;
+  }
+  if (dep.bundle !== false && fileSystem.exists(filepath)) {
+    return fileSystem.readFileSync(filepath);
+  }
+  if (dep.bundle !== false) {
+    appLogger.warn(`Missing bundled inline script output at ${filepath}; falling back to declaration source.`);
+  }
+  return dep.content;
+}
+export {
+  resolveInlineContentScriptBody
+};

package/src/services/assets/asset-processing-service/materialize-content-script-asset.d.ts

@@ -1,11 +1,9 @@
 import type { ContentScriptAsset, ProcessedAsset } from './assets.types.js';
 /**
- * Builds a processed content-script asset from one dependency declaration and a
- * previously emitted output file.
- *
  * @remarks
- * Dev disk cache entries store only output paths. Callers must materialize the
- * full processed asset from the originating dependency so HTML and page-browser
- * graph assembly receive grouped-bundle metadata and script attributes.
+ * {@link AssetProcessingService} cache and dev disk cache entries usually keep
+ * only an output path. Dependency declarations still carry the metadata HTML and
+ * page-browser graph assembly need (`groupedBundle`, attributes, roles), so cache
+ * hits must be rehydrated from both sources rather than returned verbatim.
  */
 export declare function materializeContentScriptAsset(dep: ContentScriptAsset, filepath: string): ProcessedAsset;

package/src/services/assets/asset-processing-service/materialize-content-script-asset.js

@@ -1,9 +1,10 @@
+import { resolveInlineContentScriptBody } from "./inline-content-script-body.js";
 function materializeContentScriptAsset(dep, filepath) {
   return {
     filepath,
     kind: "script",
     inline: dep.inline ?? false,
-    content: dep.inline ? dep.content : void 0,
+    content: resolveInlineContentScriptBody(dep, filepath),
     position: dep.position,
     attributes: dep.attributes,
     excludeFromHtml: dep.excludeFromHtml,

package/src/services/assets/asset-processing-service/processors/script/content-script.processor.d.ts

@@ -3,11 +3,12 @@ import { BaseScriptProcessor } from '../base/base-script-processor.js';
 export declare class ContentScriptProcessor extends BaseScriptProcessor<ContentScriptAsset> {
     private getContentScriptEntryDir;
     private getContentScriptEntryPath;
-    private createBundleConfigHash;
-    private createContentScriptCacheKey;
     private toProcessedAsset;
     private removeContentScriptEntry;
     processGrouped(deps: ContentScriptAsset[]): Promise<ProcessedAsset[]>;
     private getGroupedBundlerOptions;
+    /**
+     * Emits one content script asset. Cache reuse is owned by {@link AssetProcessingService}.
+     */
     process(dep: ContentScriptAsset): Promise<ProcessedAsset>;
 }

package/src/services/assets/asset-processing-service/processors/script/content-script.processor.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
+import { resolveInlineContentScriptBody } from "../../inline-content-script-body.js";
 import { shouldUseDevBrowserScriptCache } from "../../../../../build/dev-browser-script-cache.js";
 import { BaseScriptProcessor } from "../base/base-script-processor.js";
 class ContentScriptProcessor extends BaseScriptProcessor {
@@ -11,24 +12,10 @@ class ContentScriptProcessor extends BaseScriptProcessor {
   getContentScriptEntryPath(contentHash) {
     return path.join(this.getContentScriptEntryDir(), `${contentHash}.js`);
   }
-  createBundleConfigHash(dep, shouldBundle) {
-    return this.generateHash(
-      JSON.stringify({
-        bundle: shouldBundle,
-        minify: shouldBundle && this.isProduction,
-        opts: dep.bundleOptions
-      })
-    );
-  }
-  createContentScriptCacheKey(dep, shouldBundle) {
-    const contentHash = this.generateHash(dep.content);
-    const configHash = this.createBundleConfigHash(dep, shouldBundle);
-    return `${this.buildCacheKey(`content-script:${contentHash}`, contentHash, dep)}:${configHash}`;
-  }
-  toProcessedAsset(dep, filepath, inlineContent) {
+  toProcessedAsset(dep, filepath) {
     return {
       filepath,
-      content: dep.inline ? inlineContent : void 0,
+      content: resolveInlineContentScriptBody(dep, filepath),
       kind: "script",
       position: dep.position,
       attributes: dep.attributes,
@@ -81,11 +68,7 @@ class ContentScriptProcessor extends BaseScriptProcessor {
         if (!bundledFilePath) {
           throw new Error(`Missing grouped bundle output for ${entryName}`);
         }
-        return this.toProcessedAsset(
-          dep,
-          bundledFilePath,
-          dep.inline ? fileSystem.readFileSync(bundledFilePath).toString() : void 0
-        );
+        return this.toProcessedAsset(dep, bundledFilePath);
       });
     } finally {
       for (const { contentHash } of tempEntries) {
@@ -104,41 +87,37 @@ class ContentScriptProcessor extends BaseScriptProcessor {
     }
     return options;
   }
+  /**
+   * Emits one content script asset. Cache reuse is owned by {@link AssetProcessingService}.
+   */
   async process(dep) {
     const shouldBundle = this.shouldBundle(dep);
-    const cacheKey = this.createContentScriptCacheKey(dep, shouldBundle);
-    return this.getOrProcess(cacheKey, async () => {
-      const hash = this.generateHash(dep.content);
-      const filename = dep.name ? `${dep.name}.js` : `script-${hash}.js`;
-      const filepath = path.join(this.getAssetsDir(), "scripts", filename);
-      if (!shouldBundle) {
-        if (!dep.inline) {
-          fileSystem.write(filepath, dep.content);
-        }
-        return this.toProcessedAsset(dep, filepath, dep.inline ? dep.content : void 0);
+    const hash = this.generateHash(dep.content);
+    const filename = dep.name ? `${dep.name}.js` : `script-${hash}.js`;
+    const filepath = path.join(this.getAssetsDir(), "scripts", filename);
+    if (!shouldBundle) {
+      if (!dep.inline) {
+        fileSystem.write(filepath, dep.content);
       }
-      if (!dep.content) {
-        throw new Error("No content found for script asset");
-      }
-      const entryPath = this.getContentScriptEntryPath(hash);
-      fileSystem.write(entryPath, dep.content);
-      try {
-        const bundledFilePath = await this.bundleScript({
-          entrypoint: entryPath,
-          outdir: this.getAssetsDir(),
-          minify: this.isProduction,
-          naming: `${path.parse(filename).name}-[hash].[ext]`,
-          ...this.getBundlerOptions(dep)
-        });
-        return this.toProcessedAsset(
-          dep,
-          bundledFilePath,
-          dep.inline ? fileSystem.readFileSync(bundledFilePath).toString() : void 0
-        );
-      } finally {
-        this.removeContentScriptEntry(hash);
-      }
-    });
+      return this.toProcessedAsset(dep, filepath);
+    }
+    if (!dep.content) {
+      throw new Error("No content found for script asset");
+    }
+    const entryPath = this.getContentScriptEntryPath(hash);
+    fileSystem.write(entryPath, dep.content);
+    try {
+      const bundledFilePath = await this.bundleScript({
+        entrypoint: entryPath,
+        outdir: this.getAssetsDir(),
+        minify: this.isProduction,
+        naming: `${path.parse(filename).name}-[hash].[ext]`,
+        ...this.getBundlerOptions(dep)
+      });
+      return this.toProcessedAsset(dep, bundledFilePath);
+    } finally {
+      this.removeContentScriptEntry(hash);
+    }
   }
 }
 export {