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

package/src/router/client/navigation-coordinator.js

@@ -176,8 +176,8 @@ function createEcoNavigationRuntime() {
         if (!registration?.reloadCurrentPage) {
           continue;
         }
-        await registration.reloadCurrentPage(request);
-        return true;
+        const handled = await registration.reloadCurrentPage(request);
+        return handled !== false;
       }
       return false;
     },
@@ -198,6 +198,16 @@ function createEcoNavigationRuntime() {
       await runtime.cleanupOwner(owner);
     }
   };
+  if (typeof window !== "undefined") {
+    window.addEventListener("pageshow", (event) => {
+      if (event.persisted) {
+        runtime.cancelCurrentNavigationTransaction();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      runtime.cancelCurrentNavigationTransaction();
+    });
+  }
   return runtime;
 }
 function getEcoNavigationRuntime(windowObject = window) {

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,9 +39,12 @@ 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;
     /**
      * Processes deduplicated dependencies grouped by processor type.
      *
@@ -80,6 +83,8 @@ export declare class AssetProcessingService {
      * Returns the cached processed asset for a dependency key when available.
      */
     private getCachedAsset;
+    private getCachedContentScriptAsset;
+    private resolveCachedContentScriptFilepath;
     /**
      * Stores one processed asset in the dependency cache.
      */

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

@@ -4,12 +4,19 @@ import { appLogger } from "../../../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
 import { deduplicateAssetDependencies, getAssetDependencyKey } from "./asset-dependency-keys.js";
 import {
+  ensureGroupedContentScriptsBundle,
   partitionGroupedContentScriptDependencies,
   processGroupedDependencyBundles
 } from "./grouped-content-bundles.js";
+import { resolveIntegrationPluginForProcessingKey } from "./resolve-integration-plugin.js";
 import { isHmrAware } from "./processor.interface.js";
 import { ProcessorRegistry } from "./processor.registry.js";
 import { processUngroupedDependency } from "./ungrouped-dependency-processing.js";
+import { materializeContentScriptAsset } from "./materialize-content-script-asset.js";
+import {
+  getDevBrowserScriptCacheEntry,
+  setDevBrowserScriptCacheEntry
+} from "../../../build/cache/dev-browser-script-cache.js";
 import {
   ContentScriptProcessor,
   ContentStylesheetProcessor,
@@ -62,16 +69,24 @@ 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);
     fileSystem.ensureDir(depsDir);
     const dedupedDeps = deduplicateAssetDependencies(deps);
-    const results = await this.processDependenciesParallel(dedupedDeps, key);
+    const preparedDeps = this.prepareDependenciesForProcessing(dedupedDeps, key);
+    ensureGroupedContentScriptsBundle(preparedDeps);
+    const results = await this.processDependenciesParallel(preparedDeps);
     await this.optimizeDependencies(results);
     return results;
   }
+  prepareDependenciesForProcessing(deps, processingKey) {
+    const plugin = resolveIntegrationPluginForProcessingKey(this.config, processingKey);
+    return plugin?.prepareAssetDependencies?.(deps) ?? deps;
+  }
   /**
    * Processes deduplicated dependencies grouped by processor type.
    *
@@ -80,14 +95,13 @@ class AssetProcessingService {
    * pair, while still allowing the overall dependency set to resolve in
    * parallel.
    */
-  async processDependenciesParallel(deps, key) {
+  async processDependenciesParallel(deps) {
     const grouped = this.groupDependenciesByType(deps);
     const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
       const { groupedBundleDeps, ungroupedDeps } = partitionGroupedContentScriptDependencies(typeDeps);
       const typePromises = ungroupedDeps.map(
         (dep) => processUngroupedDependency({
           dep,
-          key,
           depKey: getAssetDependencyKey(dep),
           getCachedAsset: (assetDep, depKey) => this.getCachedAsset(assetDep, depKey),
           getProcessor: (assetDep) => this.registry.getProcessor(assetDep.kind, assetDep.source),
@@ -109,7 +123,6 @@ class AssetProcessingService {
       );
       const groupedResults = await processGroupedDependencyBundles({
         bundles: Array.from(groupedBundleDeps.values()),
-        key,
         getCachedAsset: (dep, depKey) => this.getCachedAsset(dep, depKey),
         getDependencyKey: getAssetDependencyKey,
         getGroupedProcessor: () => this.registry.getProcessor("script", "content"),
@@ -229,6 +242,9 @@ class AssetProcessingService {
     if (process.env.NODE_ENV !== "production" && dep.source === "file" && dep.kind === "stylesheet") {
       return null;
     }
+    if (dep.kind === "script" && dep.source === "content") {
+      return this.getCachedContentScriptAsset(dep, depKey);
+    }
     const cached = this.cache.get(depKey);
     if (!cached) {
       return null;
@@ -239,11 +255,34 @@ class AssetProcessingService {
     }
     return cached.asset;
   }
+  getCachedContentScriptAsset(dep, depKey) {
+    const filepath = this.resolveCachedContentScriptFilepath(depKey) ?? getDevBrowserScriptCacheEntry(this.config, depKey)?.filepath;
+    if (!filepath) {
+      return null;
+    }
+    const materialized = materializeContentScriptAsset(dep, filepath);
+    this.cache.set(depKey, { asset: materialized });
+    return materialized;
+  }
+  resolveCachedContentScriptFilepath(depKey) {
+    const cached = this.cache.get(depKey);
+    if (!cached?.asset.filepath) {
+      return void 0;
+    }
+    if (!fileSystem.exists(cached.asset.filepath)) {
+      this.cache.delete(depKey);
+      return void 0;
+    }
+    return cached.asset.filepath;
+  }
   /**
    * Stores one processed asset in the dependency cache.
    */
   setCachedAsset(dep, depKey, asset) {
     this.cache.set(depKey, { asset });
+    if (dep.kind === "script" && dep.source === "content") {
+      setDevBrowserScriptCacheEntry(this.config, depKey, asset);
+    }
   }
   /**
    * Clears all cached processed assets.

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

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../../build/contracts/build-types.js';
 export type AssetSource = 'content' | 'file' | 'node-module';
 export type AssetKind = 'script' | 'stylesheet';
 export type AssetPosition = 'head' | 'body';

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

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../../build/contracts/build-types.js';
 import type { AssetDefinition } from './assets.types.js';
 import { type BrowserRuntimeEntryModuleConfig } from './browser-runtime-entry.factory.js';
 export declare const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES: {
@@ -45,6 +45,7 @@ export declare function createBrowserRuntimeModuleAsset(options: {
     fileName: string;
     cacheDirName?: string;
     rootDir?: string;
+    workDir?: string;
     bundleOptions?: {
         define?: Record<string, string>;
         minify?: boolean;

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

@@ -31,6 +31,7 @@ function createBrowserRuntimeModuleAsset(options) {
     modules: options.modules,
     fileName: `${options.name}-entry.mjs`,
     rootDir: options.rootDir,
+    workDir: options.workDir,
     cacheDirName: options.cacheDirName
   });
   return createBrowserRuntimeScriptAsset({

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.d.ts

@@ -9,12 +9,14 @@ export type BrowserRuntimeEntryModuleConfig = {
  * @remarks
  * Integrations use this helper when they need a browser runtime asset composed
  * from multiple bare specifiers but do not want to own temporary file assembly
- * logic themselves. The generated file lives under a cache directory inside the
- * consuming app root so repeated runs can reuse the same location.
+ * 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.
  */
 export declare function createBrowserRuntimeEntryModule(options: {
     modules: BrowserRuntimeEntryModuleConfig[];
     fileName: string;
     rootDir?: string;
+    workDir?: string;
     cacheDirName?: string;
 }): string;

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

@@ -1,41 +1,56 @@
 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");
+  }
   const rootDir = options.rootDir ?? process.cwd();
+  const workDir = options.workDir ?? path.join(rootDir, DEFAULT_ECOPAGES_WORK_DIR);
   const artifactsDir = path.join(
-    rootDir,
-    "node_modules",
-    ".cache",
+    workDir,
+    ".browser-runtime-entries",
     options.cacheDirName ?? "ecopages-browser-runtime"
   );
   fs.mkdirSync(artifactsDir, { recursive: true });
   const requireFromRoot = createRequire(path.join(rootDir, "package.json"));
   const seenExports = /* @__PURE__ */ new Set();
   const statements = [];
+  const filePath = path.join(artifactsDir, options.fileName);
+  const entryDir = path.dirname(filePath);
   for (const module of options.modules) {
-    if (module.defaultExport) {
-      statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+    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) {
-      statements.push(`export { ${exportNames.join(", ")} } from '${module.specifier}';`);
+      statements.push(`export { ${exportNames.join(", ")} } from '${importSpecifier}';`);
       for (const exportName of exportNames) {
         seenExports.add(exportName);
       }
     }
   }
-  const filePath = path.join(artifactsDir, options.fileName);
-  fs.writeFileSync(filePath, statements.join("\n"), "utf-8");
+  const content = statements.join("\n");
+  if (!fs.existsSync(filePath) || fs.readFileSync(filePath, "utf-8") !== content) {
+    fs.writeFileSync(filePath, content, "utf-8");
+  }
   return filePath;
 }
-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/finalize-processed-asset.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessedAsset } from './assets.types.js';
+/** Applies the public source URL to one processed asset when available. */
+export declare function finalizeProcessedAsset(processed: ProcessedAsset, resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined): ProcessedAsset;

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

@@ -0,0 +1,7 @@
+function finalizeProcessedAsset(processed, resolveProcessedAssetSrcUrl) {
+  const srcUrl = resolveProcessedAssetSrcUrl(processed);
+  return srcUrl ? { ...processed, srcUrl } : processed;
+}
+export {
+  finalizeProcessedAsset
+};

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

@@ -1,4 +1,6 @@
 import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
+/** Forces grouped content scripts to run through the bundler in production builds. */
+export declare function ensureGroupedContentScriptsBundle(dependencies: AssetDefinition[]): void;
 /**
  * Splits grouped content-script dependencies from ordinary dependencies so callers can
  * route them through `processGrouped` without changing ordering for the remaining assets.
@@ -12,7 +14,6 @@ type GroupedBundleProcessor = {
 };
 type ProcessGroupedDependencyBundlesOptions = {
     bundles: AssetDefinition[][];
-    key: string;
     getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
     getDependencyKey: (dep: AssetDefinition) => string;
     getGroupedProcessor: () => GroupedBundleProcessor | undefined;

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

@@ -1,3 +1,21 @@
+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;
+  }
+  for (const dependency of dependencies) {
+    if (dependency.kind !== "script" || dependency.source !== "content" || !dependency.groupedBundle?.id) {
+      continue;
+    }
+    if (dependency.bundle === false) {
+      dependency.bundle = true;
+    }
+  }
+}
 function partitionGroupedContentScriptDependencies(typeDeps) {
   const groupedBundleDeps = /* @__PURE__ */ new Map();
   const ungroupedDeps = [];
@@ -18,7 +36,6 @@ function partitionGroupedContentScriptDependencies(typeDeps) {
 async function processGroupedDependencyBundles(options) {
   const {
     bundles,
-    key,
     getCachedAsset,
     getDependencyKey,
     getGroupedProcessor,
@@ -29,7 +46,7 @@ async function processGroupedDependencyBundles(options) {
   const groupedPromises = bundles.map(async (bundleDeps) => {
     const cachedResults = bundleDeps.map((dep) => {
       const cached = getCachedAsset(dep, getDependencyKey(dep));
-      return cached ? { key, ...cached } : null;
+      return cached ? finalizeProcessedAsset(cached, resolveProcessedAssetSrcUrl) : null;
     });
     if (cachedResults.every((result) => result !== null)) {
       return cachedResults.filter((result) => result !== null);
@@ -40,17 +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 srcUrl = resolveProcessedAssetSrcUrl(processed);
-        const processedWithKey = {
-          key,
-          ...processed,
-          srcUrl
-        };
-        setCachedAsset(dep, depKey, processedWithKey);
-        return processedWithKey;
+        const finalized = finalizeProcessedAsset(processed, resolveProcessedAssetSrcUrl);
+        setCachedAsset(dep, depKey, finalized);
+        return [finalized];
       });
     } catch (error) {
       logError(error);
@@ -60,6 +85,7 @@ async function processGroupedDependencyBundles(options) {
   return (await Promise.all(groupedPromises)).flat();
 }
 export {
+  ensureGroupedContentScriptsBundle,
   partitionGroupedContentScriptDependencies,
   processGroupedDependencyBundles
 };

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

@@ -1,6 +1,8 @@
 export * from './asset.factory.js';
+export * from './grouped-content-bundles.js';
 export * from './page-package.js';
 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

@@ -1,6 +1,8 @@
 export * from "./asset.factory.js";
+export * from "./grouped-content-bundles.js";
 export * from "./page-package.js";
 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

@@ -0,0 +1,9 @@
+import type { ContentScriptAsset, ProcessedAsset } from './assets.types.js';
+/**
+ * @remarks
+ * {@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

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

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

@@ -1,5 +1,4 @@
 import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
-import type { EcoBuildPlugin } from '../../../../../build/build-types.js';
 import type { ScriptAsset } from '../../assets.types.js';
 import { BaseProcessor } from './base-processor.js';
 import { type BrowserBundleGroupedEntry } from '../../../browser-bundle.service.js';
@@ -10,7 +9,6 @@ export declare abstract class BaseScriptProcessor<T extends ScriptAsset> extends
     });
     protected shouldBundle(dep: T): boolean;
     protected getBundlerOptions(dep: T): Record<string, any>;
-    protected collectBuildPlugins(excludePluginNames?: string[]): EcoBuildPlugin[];
     protected bundleScript({ entrypoint, outdir, excludeAppBuildPlugins, plugins: additionalPlugins, ...rest }: {
         entrypoint: string;
         outdir: string;