@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/services/{asset-processing-service → assets/asset-processing-service}/asset-processing.service.js

@@ -1,25 +1,34 @@
 import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../constants";
-import { appLogger } from "../../global/app-logger";
-import { rapidhash } from "../../utils/hash";
+import { RESOLVED_ASSETS_DIR } from "../../../config/constants.js";
+import { appLogger } from "../../../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
-import { isHmrAware } from "./processor.interface";
-import { ProcessorRegistry } from "./processor.registry";
+import { deduplicateAssetDependencies, getAssetDependencyKey } from "./asset-dependency-keys.js";
+import {
+  partitionGroupedContentScriptDependencies,
+  processGroupedDependencyBundles
+} from "./grouped-content-bundles.js";
+import { isHmrAware } from "./processor.interface.js";
+import { ProcessorRegistry } from "./processor.registry.js";
+import { processUngroupedDependency } from "./ungrouped-dependency-processing.js";
 import {
   ContentScriptProcessor,
   ContentStylesheetProcessor,
   FileScriptProcessor,
   FileStylesheetProcessor,
   NodeModuleScriptProcessor
-} from "./processors";
+} from "./processors/index.js";
 class AssetProcessingService {
-  constructor(config) {
-    this.config = config;
-  }
   static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
   registry = new ProcessorRegistry();
   hmrManager;
   cache = /* @__PURE__ */ new Map();
+  config;
+  /**
+   * Creates the asset-processing service bound to one finalized app config.
+   */
+  constructor(config) {
+    this.config = config;
+  }
   /**
    * Set the HMR manager for the asset processing service.
    * @param hmrManager The HMR manager to set.
@@ -47,106 +56,87 @@ class AssetProcessingService {
     }
     this.registry.register(kind, variant, processor);
   }
+  /**
+   * Processes one dependency list into normalized emitted assets.
+   *
+   * @remarks
+   * Dependencies are deduplicated before processor execution so repeated
+   * declarations across the render tree reuse the same emitted outputs and cache
+   * entries.
+   */
   async processDependencies(deps, key) {
     const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
     fileSystem.ensureDir(depsDir);
-    const dedupedDeps = this.deduplicateDependencies(deps);
+    const dedupedDeps = deduplicateAssetDependencies(deps);
     const results = await this.processDependenciesParallel(dedupedDeps, key);
     await this.optimizeDependencies(results);
     return results;
   }
-  deduplicateDependencies(deps) {
-    const seen = /* @__PURE__ */ new Map();
-    for (const dep of deps) {
-      const key = this.getDependencyKey(dep);
-      if (!seen.has(key)) {
-        seen.set(key, dep);
-      }
-    }
-    return Array.from(seen.values());
-  }
-  getScriptDependencyBuildSignature(dep) {
-    if (dep.kind !== "script") {
-      return void 0;
-    }
-    const pluginNames = dep.bundleOptions?.plugins?.map((plugin) => plugin.name) ?? [];
-    const signature = {
-      bundle: dep.bundle,
-      inline: dep.inline,
-      excludeFromHtml: dep.excludeFromHtml,
-      naming: dep.bundleOptions?.naming,
-      external: dep.bundleOptions?.external,
-      minify: dep.bundleOptions?.minify,
-      plugins: pluginNames
-    };
-    return this.generateHash(JSON.stringify(signature));
-  }
-  getDependencyKey(dep) {
-    const parts = [dep.kind, dep.source];
-    if ("filepath" in dep) {
-      parts.push(dep.filepath);
-    } else if ("content" in dep) {
-      parts.push(`content:${this.generateHash(dep.content)}`);
-    } else if ("importPath" in dep) {
-      parts.push(dep.importPath);
-    }
-    if ("position" in dep && dep.position) {
-      parts.push(dep.position);
-    }
-    const scriptBuildSignature = this.getScriptDependencyBuildSignature(dep);
-    if (scriptBuildSignature) {
-      parts.push(`build:${scriptBuildSignature}`);
-    }
-    return parts.join(":");
-  }
-  generateHash(content) {
-    return rapidhash(content).toString();
-  }
+  /**
+   * Processes deduplicated dependencies grouped by processor type.
+   *
+   * @remarks
+   * Grouping keeps cache and processor behavior isolated by asset kind/source
+   * pair, while still allowing the overall dependency set to resolve in
+   * parallel.
+   */
   async processDependenciesParallel(deps, key) {
     const grouped = this.groupDependenciesByType(deps);
     const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
-      const typePromises = typeDeps.map(async (dep) => {
-        const depKey = this.getDependencyKey(dep);
-        const cached = this.getCachedAsset(dep, depKey);
-        if (cached) {
-          return { key, ...cached };
-        }
-        const processor = this.registry.getProcessor(dep.kind, dep.source);
-        if (!processor) {
-          appLogger.error(`No processor found for ${dep.kind}/${dep.source}`);
-          return null;
-        }
-        if (dep.source === "file" && "filepath" in dep) {
-          const fileExists = fileSystem.exists(dep.filepath);
-          if (!fileExists) {
-            appLogger.warn(`Skipping missing ${dep.kind} file: ${dep.filepath}`);
-            return null;
+      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),
+          resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
+          setCachedAsset: (assetDep, depKey, processed) => this.setCachedAsset(assetDep, depKey, processed),
+          logMissingProcessor: (assetDep) => {
+            appLogger.error(`No processor found for ${assetDep.kind}/${assetDep.source}`);
+          },
+          logMissingFile: (assetDep) => {
+            appLogger.warn(`Skipping missing ${assetDep.kind} file: ${assetDep.filepath}`);
+          },
+          logProcessingError: (assetDep, error) => {
+            appLogger.error(
+              `Failed to process dependency: ${error instanceof Error ? error.message : String(error)} for ${assetDep.kind}/${assetDep.source}`
+            );
+            appLogger.debug(error);
           }
-        }
-        try {
-          const processed = await processor.process(dep);
-          const srcUrl = this.resolveProcessedAssetSrcUrl(processed);
-          const processedWithKey = {
-            key,
-            ...processed,
-            srcUrl
-          };
-          this.setCachedAsset(dep, depKey, processedWithKey);
-          return processedWithKey;
-        } catch (error) {
+        })
+      );
+      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"),
+        resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
+        setCachedAsset: (dep, depKey, processed) => this.setCachedAsset(dep, depKey, processed),
+        logError: (error) => {
           appLogger.error(
-            `Failed to process dependency: ${error instanceof Error ? error.message : String(error)} for ${dep.kind}/${dep.source}`
+            `Failed to process grouped dependency bundle: ${error instanceof Error ? error.message : String(error)}`
           );
           appLogger.debug(error);
-          return null;
         }
       });
       const typeResults = await Promise.all(typePromises);
-      return typeResults.filter((result) => result !== null);
+      const processedTypeResults = typeResults.flatMap((result) => {
+        if (!result) {
+          return [];
+        }
+        return Array.isArray(result) ? result : [result];
+      });
+      return [...processedTypeResults, ...groupedResults];
     });
     const allTypeResults = await Promise.all(groupPromises);
     return allTypeResults.flat();
   }
+  /**
+   * Groups dependencies by processor bucket.
+   */
   groupDependenciesByType(deps) {
     return deps.reduce(
       (acc, dep) => {
@@ -158,6 +148,9 @@ class AssetProcessingService {
       {}
     );
   }
+  /**
+   * Converts a dist-local file path into its public URL.
+   */
   getSrcUrl(filepath) {
     const distDir = this.config.absolutePaths.distDir;
     if (!filepath.startsWith(distDir)) return void 0;
@@ -165,6 +158,9 @@ class AssetProcessingService {
     const urlPath = relativePath.startsWith("/") ? relativePath : `/${relativePath}`;
     return urlPath.replace(/\\/g, "/");
   }
+  /**
+   * Normalizes the public source URL for one processed asset.
+   */
   resolveProcessedAssetSrcUrl(processed) {
     if (processed.srcUrl) {
       if (this.isFilesystemPath(processed.srcUrl)) {
@@ -179,6 +175,10 @@ class AssetProcessingService {
     }
     return void 0;
   }
+  /**
+   * Returns whether a value should be interpreted as a filesystem path instead
+   * of an already-public URL.
+   */
   isFilesystemPath(value) {
     if (value.startsWith("http://") || value.startsWith("https://") || value.startsWith("//")) {
       return false;
@@ -192,6 +192,13 @@ class AssetProcessingService {
     }
     return /^[A-Za-z]:\\/.test(value);
   }
+  /**
+   * Applies post-processing for emitted production assets.
+   *
+   * @remarks
+   * Current optimization is intentionally conservative: only generated CSS and
+   * JavaScript files inside the app dist directory are gzipped.
+   */
   async optimizeDependencies(processedAssets) {
     if (process.env.NODE_ENV !== "production") {
       return;
@@ -215,16 +222,38 @@ class AssetProcessingService {
       }
     }
   }
+  /**
+   * Returns the cached processed asset for a dependency key when available.
+   */
   getCachedAsset(dep, depKey) {
+    if (process.env.NODE_ENV !== "production" && dep.source === "file" && dep.kind === "stylesheet") {
+      return null;
+    }
     const cached = this.cache.get(depKey);
-    return cached?.asset ?? null;
+    if (!cached) {
+      return null;
+    }
+    if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
+      this.cache.delete(depKey);
+      return null;
+    }
+    return cached.asset;
   }
+  /**
+   * Stores one processed asset in the dependency cache.
+   */
   setCachedAsset(dep, depKey, asset) {
     this.cache.set(depKey, { asset });
   }
+  /**
+   * Clears all cached processed assets.
+   */
   clearCache() {
     this.cache.clear();
   }
+  /**
+   * Removes cached assets that were produced from the given file path.
+   */
   invalidateCacheForFile(filepath) {
     for (const [key, value] of this.cache.entries()) {
       if (value.asset.filepath === filepath) {
@@ -232,6 +261,9 @@ class AssetProcessingService {
       }
     }
   }
+  /**
+   * Creates a service prewired with the default core processors.
+   */
   static createWithDefaultProcessors(appConfig) {
     const service = new AssetProcessingService(appConfig);
     service.registerProcessor("script", "content", new ContentScriptProcessor({ appConfig }));
@@ -241,6 +273,9 @@ class AssetProcessingService {
     service.registerProcessor("stylesheet", "file", new FileStylesheetProcessor({ appConfig }));
     return service;
   }
+  /**
+   * Returns the processor registry owned by this service.
+   */
   getRegistry() {
     return this.registry;
   }

package/src/services/{asset-processing-service → assets/asset-processing-service}/asset.factory.d.ts

@@ -1,4 +1,4 @@
-import type { ContentScriptAsset, ContentStylesheetAsset, FileScriptAsset, FileStylesheetAsset, InlineContentScriptAsset, InlineContentStylesheetAsset, InlineFileScriptAsset, JsonScriptAsset, NodeModuleScriptAsset } from './assets.types';
+import type { ContentScriptAsset, ContentStylesheetAsset, FileScriptAsset, FileStylesheetAsset, InlineContentScriptAsset, InlineContentStylesheetAsset, InlineFileScriptAsset, JsonScriptAsset, NodeModuleScriptAsset } from './assets.types.js';
 type CreateAssetOptions<T> = Omit<T, 'kind' | 'source' | 'inline'>;
 export declare class AssetFactory {
     static readonly RESOLVED_ASSETS_DIR = "assets";

package/src/services/{asset-processing-service → assets/asset-processing-service}/asset.factory.js

@@ -1,5 +1,5 @@
-import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from "../../constants";
-import { deepMerge } from "../../utils/deep-merge";
+import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from "../../../config/constants.js";
+import { deepMerge } from "../../../utils/deep-merge.js";
 class AssetFactory {
   static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
   static RESOLVED_ASSETS_VENDORS_DIR = RESOLVED_ASSETS_VENDORS_DIR;

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

@@ -1,20 +1,31 @@
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../../build/build-types.js';
 export type AssetSource = 'content' | 'file' | 'node-module';
 export type AssetKind = 'script' | 'stylesheet';
 export type AssetPosition = 'head' | 'body';
+export type AssetPackageRole = 'page-script' | 'page-style' | 'runtime' | 'keep-separate' | 'dynamic-chunk';
+export type GroupedScriptBundle = {
+    id: string;
+    entryName: string;
+};
 export interface BaseAsset {
     kind: AssetKind;
     source: AssetSource;
     attributes?: Record<string, string>;
     position?: AssetPosition;
+    packageRole?: AssetPackageRole;
+    bundledSourceFilepaths?: string[];
 }
 export interface ScriptAsset extends BaseAsset {
     kind: 'script';
     inline?: boolean;
     bundle?: boolean;
+    groupedBundle?: GroupedScriptBundle;
     bundleOptions?: {
+        define?: Record<string, string>;
         minify?: boolean;
         external?: string[];
+        splitting?: boolean;
+        excludeAppBuildPlugins?: string[];
         naming?: string;
         plugins?: EcoBuildPlugin[];
     };
@@ -77,6 +88,7 @@ export interface JsonScriptAsset extends ScriptAsset {
 }
 export type ProcessedAsset = {
     filepath?: string;
+    sourceFilepath?: string;
     srcUrl?: string;
     content?: string;
     kind: AssetKind;
@@ -84,5 +96,8 @@ export type ProcessedAsset = {
     attributes?: Record<string, string>;
     inline?: boolean;
     excludeFromHtml?: boolean;
+    packageRole?: AssetPackageRole;
+    groupedBundle?: GroupedScriptBundle;
+    bundledSourceFilepaths?: string[];
 };
 export type AssetDefinition = ContentScriptAsset | FileScriptAsset | NodeModuleScriptAsset | JsonScriptAsset | ContentStylesheetAsset | FileStylesheetAsset;

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

@@ -0,0 +1,57 @@
+import type { EcoBuildPlugin } from '../../../build/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: {
+    readonly type: "module";
+    readonly defer: "";
+};
+/**
+ * Builds the public vendor URL used for generated browser runtime assets.
+ */
+export declare function buildBrowserRuntimeAssetUrl(fileName: string): string;
+/**
+ * Declares a browser runtime script asset backed by one importable module.
+ *
+ * @remarks
+ * Runtime assets are emitted as excluded head scripts because integrations often
+ * need the bundler output and specifier registration without injecting the raw
+ * asset directly into HTML during dependency resolution.
+ */
+export declare function createBrowserRuntimeScriptAsset(options: {
+    importPath: string;
+    name: string;
+    fileName: string;
+    bundleOptions?: {
+        define?: Record<string, string>;
+        minify?: boolean;
+        external?: string[];
+        excludeAppBuildPlugins?: string[];
+        naming?: string;
+        plugins?: EcoBuildPlugin[];
+    };
+    attributes?: Record<string, string>;
+}): AssetDefinition;
+/**
+ * Creates a browser runtime asset from a generated re-export entry module.
+ *
+ * @remarks
+ * This is the shared "module list -> generated entry file -> runtime asset"
+ * path used by integrations that need browser-side runtime bundles without
+ * owning bespoke entry-file generation logic.
+ */
+export declare function createBrowserRuntimeModuleAsset(options: {
+    modules: BrowserRuntimeEntryModuleConfig[];
+    name: string;
+    fileName: string;
+    cacheDirName?: string;
+    rootDir?: string;
+    bundleOptions?: {
+        define?: Record<string, string>;
+        minify?: boolean;
+        external?: string[];
+        excludeAppBuildPlugins?: string[];
+        naming?: string;
+        plugins?: EcoBuildPlugin[];
+    };
+    attributes?: Record<string, string>;
+}): AssetDefinition;

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

@@ -0,0 +1,49 @@
+import { AssetFactory } from "./asset.factory.js";
+import {
+  createBrowserRuntimeEntryModule
+} from "./browser-runtime-entry.factory.js";
+const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES = {
+  type: "module",
+  defer: ""
+};
+function buildBrowserRuntimeAssetUrl(fileName) {
+  return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+}
+function createBrowserRuntimeScriptAsset(options) {
+  return AssetFactory.createNodeModuleScript({
+    position: "head",
+    importPath: options.importPath,
+    name: options.name,
+    packageRole: "runtime",
+    excludeFromHtml: true,
+    bundleOptions: {
+      naming: options.fileName,
+      ...options.bundleOptions
+    },
+    attributes: {
+      ...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+      ...options.attributes ?? {}
+    }
+  });
+}
+function createBrowserRuntimeModuleAsset(options) {
+  const importPath = createBrowserRuntimeEntryModule({
+    modules: options.modules,
+    fileName: `${options.name}-entry.mjs`,
+    rootDir: options.rootDir,
+    cacheDirName: options.cacheDirName
+  });
+  return createBrowserRuntimeScriptAsset({
+    importPath,
+    name: options.name,
+    fileName: options.fileName,
+    bundleOptions: options.bundleOptions,
+    attributes: options.attributes
+  });
+}
+export {
+  BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+  buildBrowserRuntimeAssetUrl,
+  createBrowserRuntimeModuleAsset,
+  createBrowserRuntimeScriptAsset
+};

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

@@ -0,0 +1,20 @@
+export type BrowserRuntimeEntryModuleConfig = {
+    specifier: string;
+    defaultExport?: boolean;
+};
+/**
+ * Creates a generated ESM entry module that re-exports runtime modules through
+ * one stable file.
+ *
+ * @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.
+ */
+export declare function createBrowserRuntimeEntryModule(options: {
+    modules: BrowserRuntimeEntryModuleConfig[];
+    fileName: string;
+    rootDir?: string;
+    cacheDirName?: string;
+}): string;

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

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+function createBrowserRuntimeEntryModule(options) {
+  const rootDir = options.rootDir ?? process.cwd();
+  const artifactsDir = path.join(
+    rootDir,
+    "node_modules",
+    ".cache",
+    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 = [];
+  for (const module of options.modules) {
+    if (module.defaultExport) {
+      statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+      statements.push("export default __ecopages_default_export__;");
+    }
+    const exportNames = getModuleExportNames(module.specifier, requireFromRoot).filter(
+      (name) => !seenExports.has(name)
+    );
+    if (exportNames.length > 0) {
+      statements.push(`export { ${exportNames.join(", ")} } from '${module.specifier}';`);
+      for (const exportName of exportNames) {
+        seenExports.add(exportName);
+      }
+    }
+  }
+  const filePath = path.join(artifactsDir, options.fileName);
+  fs.writeFileSync(filePath, statements.join("\n"), "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/grouped-content-bundles.d.ts

@@ -0,0 +1,30 @@
+import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
+/**
+ * Splits grouped content-script dependencies from ordinary dependencies so callers can
+ * route them through `processGrouped` without changing ordering for the remaining assets.
+ */
+export declare function partitionGroupedContentScriptDependencies(typeDeps: AssetDefinition[]): {
+    groupedBundleDeps: Map<string, AssetDefinition[]>;
+    ungroupedDeps: AssetDefinition[];
+};
+type GroupedBundleProcessor = {
+    processGrouped?: (deps: AssetDefinition[]) => Promise<ProcessedAsset[]>;
+};
+type ProcessGroupedDependencyBundlesOptions = {
+    bundles: AssetDefinition[][];
+    key: string;
+    getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
+    getDependencyKey: (dep: AssetDefinition) => string;
+    getGroupedProcessor: () => GroupedBundleProcessor | undefined;
+    resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined;
+    setCachedAsset: (dep: AssetDefinition, depKey: string, processed: ProcessedAsset) => void;
+    logError: (error: unknown) => void;
+};
+/**
+ * Processes grouped content-script bundles while preserving per-entry cache keys.
+ *
+ * When every dependency in a bundle already has a cached processed asset, the cached
+ * entries are returned directly and the grouped processor is skipped.
+ */
+export declare function processGroupedDependencyBundles(options: ProcessGroupedDependencyBundlesOptions): Promise<ProcessedAsset[]>;
+export {};

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

@@ -0,0 +1,65 @@
+function partitionGroupedContentScriptDependencies(typeDeps) {
+  const groupedBundleDeps = /* @__PURE__ */ new Map();
+  const ungroupedDeps = [];
+  for (const dep of typeDeps) {
+    if (dep.kind === "script" && dep.source === "content" && dep.groupedBundle?.id) {
+      const existing = groupedBundleDeps.get(dep.groupedBundle.id) ?? [];
+      existing.push(dep);
+      groupedBundleDeps.set(dep.groupedBundle.id, existing);
+      continue;
+    }
+    ungroupedDeps.push(dep);
+  }
+  return {
+    groupedBundleDeps,
+    ungroupedDeps
+  };
+}
+async function processGroupedDependencyBundles(options) {
+  const {
+    bundles,
+    key,
+    getCachedAsset,
+    getDependencyKey,
+    getGroupedProcessor,
+    resolveProcessedAssetSrcUrl,
+    setCachedAsset,
+    logError
+  } = options;
+  const groupedPromises = bundles.map(async (bundleDeps) => {
+    const cachedResults = bundleDeps.map((dep) => {
+      const cached = getCachedAsset(dep, getDependencyKey(dep));
+      return cached ? { key, ...cached } : null;
+    });
+    if (cachedResults.every((result) => result !== null)) {
+      return cachedResults.filter((result) => result !== null);
+    }
+    const processor = getGroupedProcessor();
+    if (!processor?.processGrouped) {
+      return [];
+    }
+    try {
+      const processedResults = await processor.processGrouped(bundleDeps);
+      return processedResults.map((processed, index) => {
+        const dep = bundleDeps[index];
+        const depKey = getDependencyKey(dep);
+        const srcUrl = resolveProcessedAssetSrcUrl(processed);
+        const processedWithKey = {
+          key,
+          ...processed,
+          srcUrl
+        };
+        setCachedAsset(dep, depKey, processedWithKey);
+        return processedWithKey;
+      });
+    } catch (error) {
+      logError(error);
+      return [];
+    }
+  });
+  return (await Promise.all(groupedPromises)).flat();
+}
+export {
+  partitionGroupedContentScriptDependencies,
+  processGroupedDependencyBundles
+};

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

@@ -0,0 +1,6 @@
+export * from './asset.factory.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';

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

@@ -0,0 +1,6 @@
+export * from "./asset.factory.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";

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

@@ -0,0 +1,6 @@
+import type { PagePackageResult } from '../../../types/public-types.js';
+import type { ProcessedAsset } from './assets.types.js';
+import type { PageBrowserGraphResult } from '../../../types/public-types.js';
+export declare function createPagePackage(assets: ProcessedAsset[], options?: {
+    pageBrowserGraph?: PageBrowserGraphResult;
+}): PagePackageResult;