@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.26

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

@@ -0,0 +1,285 @@
+import path from "node:path";
+import { RESOLVED_ASSETS_DIR } from "../../../config/constants.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { fileSystem } from "@ecopages/file-system";
+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/index.js";
+class AssetProcessingService {
+  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.
+   */
+  setHmrManager(hmrManager) {
+    this.hmrManager = hmrManager;
+    for (const processor of this.registry.getAllProcessors().values()) {
+      if (isHmrAware(processor)) {
+        processor.setHmrManager(hmrManager);
+      }
+    }
+  }
+  getHmrManager() {
+    return this.hmrManager;
+  }
+  /**
+   * Register a processor for a specific asset kind and source.
+   * @param kind The asset kind.
+   * @param variant The asset source.
+   * @param processor The processor to register.
+   */
+  registerProcessor(kind, variant, processor) {
+    if (this.hmrManager && isHmrAware(processor)) {
+      processor.setHmrManager(this.hmrManager);
+    }
+    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 = deduplicateAssetDependencies(deps);
+    const results = await this.processDependenciesParallel(dedupedDeps, key);
+    await this.optimizeDependencies(results);
+    return results;
+  }
+  /**
+   * 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 { 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);
+          }
+        })
+      );
+      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 grouped dependency bundle: ${error instanceof Error ? error.message : String(error)}`
+          );
+          appLogger.debug(error);
+        }
+      });
+      const typeResults = await Promise.all(typePromises);
+      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) => {
+        const key = `${dep.kind}_${dep.source}`;
+        if (!acc[key]) acc[key] = [];
+        acc[key].push(dep);
+        return acc;
+      },
+      {}
+    );
+  }
+  /**
+   * 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;
+    const relativePath = filepath.slice(distDir.length);
+    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)) {
+        const srcUrlFromPath = this.getSrcUrl(processed.srcUrl);
+        if (srcUrlFromPath) return srcUrlFromPath;
+      } else {
+        return processed.srcUrl;
+      }
+    }
+    if (processed.filepath) {
+      return this.getSrcUrl(processed.filepath);
+    }
+    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;
+    }
+    if (value.startsWith(this.config.absolutePaths.distDir)) {
+      return true;
+    }
+    const rootDir = this.config.rootDir;
+    if (rootDir && value.startsWith(rootDir)) {
+      return true;
+    }
+    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;
+    }
+    const filesToGzip = /* @__PURE__ */ new Set();
+    for (const asset of processedAssets) {
+      if (!asset.filepath) {
+        continue;
+      }
+      if (!asset.filepath.startsWith(this.config.absolutePaths.distDir)) {
+        continue;
+      }
+      const extension = path.extname(asset.filepath).slice(1);
+      if (extension === "css" || extension === "js") {
+        filesToGzip.add(asset.filepath);
+      }
+    }
+    for (const filePath of filesToGzip) {
+      if (fileSystem.exists(filePath)) {
+        fileSystem.gzipFile(filePath);
+      }
+    }
+  }
+  /**
+   * 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);
+    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) {
+        this.cache.delete(key);
+      }
+    }
+  }
+  /**
+   * Creates a service prewired with the default core processors.
+   */
+  static createWithDefaultProcessors(appConfig) {
+    const service = new AssetProcessingService(appConfig);
+    service.registerProcessor("script", "content", new ContentScriptProcessor({ appConfig }));
+    service.registerProcessor("script", "file", new FileScriptProcessor({ appConfig }));
+    service.registerProcessor("script", "node-module", new NodeModuleScriptProcessor({ appConfig }));
+    service.registerProcessor("stylesheet", "content", new ContentStylesheetProcessor({ appConfig }));
+    service.registerProcessor("stylesheet", "file", new FileStylesheetProcessor({ appConfig }));
+    return service;
+  }
+  /**
+   * Returns the processor registry owned by this service.
+   */
+  getRegistry() {
+    return this.registry;
+  }
+}
+export {
+  AssetProcessingService
+};

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

@@ -0,0 +1,17 @@
+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";
+    static readonly RESOLVED_ASSETS_VENDORS_DIR: string;
+    static createContentScript(options: CreateAssetOptions<ContentScriptAsset>): ContentScriptAsset;
+    static createInlineContentScript(options: CreateAssetOptions<InlineContentScriptAsset>): InlineContentScriptAsset;
+    static createFileScript(options: CreateAssetOptions<FileScriptAsset>): FileScriptAsset;
+    static createInlineFileScript(options: CreateAssetOptions<InlineFileScriptAsset>): InlineFileScriptAsset;
+    static createNodeModuleScript(options: CreateAssetOptions<NodeModuleScriptAsset>): NodeModuleScriptAsset;
+    static createInlineNodeModuleScript(options: CreateAssetOptions<NodeModuleScriptAsset>): NodeModuleScriptAsset;
+    static createJsonScript(options: CreateAssetOptions<JsonScriptAsset>): JsonScriptAsset;
+    static createContentStylesheet(options: CreateAssetOptions<ContentStylesheetAsset>): ContentStylesheetAsset;
+    static createInlineContentStylesheet(options: CreateAssetOptions<InlineContentStylesheetAsset>): InlineContentStylesheetAsset;
+    static createFileStylesheet(options: CreateAssetOptions<FileStylesheetAsset>): FileStylesheetAsset;
+}
+export {};

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

@@ -0,0 +1,82 @@
+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;
+  static createContentScript(options) {
+    return {
+      kind: "script",
+      source: "content",
+      position: options.position || "body",
+      ...options
+    };
+  }
+  static createInlineContentScript(options) {
+    return {
+      ...AssetFactory.createContentScript(options),
+      inline: true
+    };
+  }
+  static createFileScript(options) {
+    return {
+      kind: "script",
+      source: "file",
+      position: options.position || "body",
+      ...options
+    };
+  }
+  static createInlineFileScript(options) {
+    return {
+      ...AssetFactory.createFileScript(options),
+      inline: true
+    };
+  }
+  static createNodeModuleScript(options) {
+    return {
+      kind: "script",
+      source: "node-module",
+      position: options.position || "body",
+      ...options
+    };
+  }
+  static createInlineNodeModuleScript(options) {
+    return {
+      ...AssetFactory.createNodeModuleScript(options),
+      inline: true
+    };
+  }
+  static createJsonScript(options) {
+    return {
+      kind: "script",
+      source: "content",
+      attributes: deepMerge(options.attributes, { type: "application/json" }),
+      position: options.position || "body",
+      ...options
+    };
+  }
+  static createContentStylesheet(options) {
+    return {
+      kind: "stylesheet",
+      source: "content",
+      position: "head",
+      ...options
+    };
+  }
+  static createInlineContentStylesheet(options) {
+    return {
+      ...AssetFactory.createContentStylesheet(options),
+      inline: true
+    };
+  }
+  static createFileStylesheet(options) {
+    return {
+      kind: "stylesheet",
+      source: "file",
+      position: options.position || "head",
+      ...options
+    };
+  }
+}
+export {
+  AssetFactory
+};

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

@@ -0,0 +1,100 @@
+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;
+}
+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[];
+    };
+    /**
+     * Whether to exclude this asset from the HTML output.
+     * @default false
+     */
+    excludeFromHtml?: boolean;
+}
+export interface StylesheetAsset extends BaseAsset {
+    kind: 'stylesheet';
+    inline?: boolean;
+}
+export interface ContentScriptAsset extends ScriptAsset {
+    source: 'content';
+    content: string;
+    name?: string;
+}
+export interface InlineContentScriptAsset extends ContentScriptAsset {
+    inline: true;
+}
+export interface ContentStylesheetAsset extends StylesheetAsset {
+    source: 'content';
+    content: string;
+}
+export interface InlineContentStylesheetAsset extends ContentStylesheetAsset {
+    inline: true;
+}
+export interface FileScriptAsset extends ScriptAsset {
+    source: 'file';
+    filepath: string;
+    name?: string;
+}
+export interface InlineFileScriptAsset extends FileScriptAsset {
+    inline: true;
+}
+export interface FileStylesheetAsset extends StylesheetAsset {
+    source: 'file';
+    filepath: string;
+    name?: string;
+}
+export interface InlineFileStylesheetAsset extends FileStylesheetAsset {
+    inline: true;
+}
+export interface NodeModuleScriptAsset extends ScriptAsset {
+    kind: 'script';
+    source: 'node-module';
+    importPath: string;
+    name?: string;
+}
+export interface InlineNodeModuleScriptAsset extends NodeModuleScriptAsset {
+    inline: true;
+}
+export interface InlineNodeModuleScriptAsset extends NodeModuleScriptAsset {
+    inline: true;
+}
+export interface JsonScriptAsset extends ScriptAsset {
+    source: 'content';
+    content: string;
+}
+export type ProcessedAsset = {
+    filepath?: string;
+    srcUrl?: string;
+    content?: string;
+    kind: AssetKind;
+    position?: AssetPosition;
+    attributes?: Record<string, string>;
+    inline?: boolean;
+    excludeFromHtml?: boolean;
+    packageRole?: AssetPackageRole;
+    groupedBundle?: GroupedScriptBundle;
+};
+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,55 @@
+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[];
+        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[];
+        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 {};