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

package/src/route-renderer/orchestration/page-browser-graph.service.js

@@ -3,6 +3,12 @@ import { fileSystem } from "@ecopages/file-system";
 import {
 } from "../../services/assets/asset-processing-service/index.js";
 import { appLogger } from "../../global/app-logger.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
+import {
+  collectPageBrowserGraphDependencyPaths,
+  createPageBrowserGraphEntryFingerprint,
+  getAppPageBrowserGraphSession
+} from "./page-browser-graph-session.js";
 function isGroupedContentScriptAsset(asset) {
   return asset.kind === "script" && asset.source === "content" && Boolean(asset.groupedBundle?.id);
 }
@@ -12,76 +18,106 @@ function getGroupedBundleAssetKey(groupedBundle) {
 class PageBrowserGraphService {
   appConfig;
   assetProcessingService;
-  pageBrowserGraphCache = /* @__PURE__ */ new Map();
-  groupedPageBrowserGraphCache = /* @__PURE__ */ new Map();
   constructor(appConfig, assetProcessingService) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
   }
   async resolvePageBrowserGraph(input) {
-    if (this.isHmrEnabled()) {
-      return await this.buildPageBrowserGraph(input);
+    return await this.getOrBuild(input);
+  }
+  /**
+   * Resolves or builds one Page Browser Graph under the given policy.
+   */
+  async getOrBuild(input) {
+    const policy = input.policy ?? this.resolveGraphPolicy();
+    const session = getAppPageBrowserGraphSession(this.appConfig);
+    if (!this.isHmrEnabled()) {
+      const cachedByRoute = session.getGraphByRoute(input.integrationName, input.routeFile, policy);
+      if (cachedByRoute) {
+        return cachedByRoute;
+      }
     }
-    const cacheKey = `${input.integrationName}:${input.routeFile}`;
-    const cachedGraph = this.pageBrowserGraphCache.get(cacheKey);
-    if (cachedGraph) {
-      return await cachedGraph;
+    const contribution = await input.collectContribution(input.routeFile);
+    if (!contribution) {
+      return void 0;
     }
-    const pendingGraph = this.buildPageBrowserGraph(input).catch((error) => {
-      this.pageBrowserGraphCache.delete(cacheKey);
-      throw error;
-    });
-    this.pageBrowserGraphCache.set(cacheKey, pendingGraph);
-    return await pendingGraph;
+    const entryFingerprint = createPageBrowserGraphEntryFingerprint(contribution);
+    return await session.resolveGraph(
+      {
+        integrationName: input.integrationName,
+        routeFile: input.routeFile,
+        entryFingerprint,
+        policy
+      },
+      async () => this.buildPageBrowserGraphRecord(input, contribution)
+    );
+  }
+  resolveGraphPolicy() {
+    return this.isHmrEnabled() ? "development" : "production";
   }
   isHmrEnabled() {
     return typeof this.assetProcessingService.getHmrManager === "function" && this.assetProcessingService.getHmrManager()?.isEnabled() === true;
   }
-  async buildPageBrowserGraph(input) {
-    const contribution = await input.collectContribution(input.routeFile);
-    if (!contribution) {
+  async buildPageBrowserGraphRecord(input, contribution) {
+    const result = await this.materializePageBrowserGraph(input, contribution);
+    if (!result) {
       return void 0;
     }
+    startupTrace.markFirstPageBrowserGraphReady(getAppPageBrowserGraphSession(this.appConfig).getBuildCount());
+    return result;
+  }
+  async materializePageBrowserGraph(input, contribution) {
     const groupedDependencies = (contribution.dependencies ?? []).filter((dep) => isGroupedContentScriptAsset(dep));
     const ungroupedDependencies = (contribution.dependencies ?? []).filter(
       (dep) => !isGroupedContentScriptAsset(dep)
     );
-    const groupedAssets = groupedDependencies.length ? (await this.resolveGroupedPageBrowserAssets(input, contribution)).get(input.routeFile) ?? [] : [];
+    const groupedAssets = groupedDependencies.length ? (await this.resolveGroupedPageBrowserAssets(input, contribution)).assetsByRoute.get(input.routeFile) ?? [] : [];
     const processedDependencies = ungroupedDependencies.length ? await this.assetProcessingService.processDependencies(
       ungroupedDependencies,
       `${input.integrationName}:${input.routeFile}`
     ) : [];
     const resolvedAssets = [...processedDependencies, ...groupedAssets, ...contribution.assets ?? []];
-    return this.partitionPageBrowserGraphAssets(resolvedAssets);
+    const result = this.partitionPageBrowserGraphAssets(resolvedAssets);
+    const dependencyPaths = collectPageBrowserGraphDependencyPaths(input.routeFile, contribution, resolvedAssets);
+    return {
+      result,
+      dependencyPaths
+    };
   }
   async resolveGroupedPageBrowserAssets(input, currentContribution) {
     if (this.isHmrEnabled()) {
-      const result = await this.buildGroupedPageBrowserAssets(input, currentContribution);
-      return result.assetsByRoute;
+      return await this.buildGroupedPageBrowserAssets(input, currentContribution);
     }
-    const cacheKey = input.integrationName;
-    let pending = this.groupedPageBrowserGraphCache.get(cacheKey);
-    if (!pending) {
-      pending = this.buildGroupedPageBrowserAssets(input, currentContribution).then((result) => {
-        if (result.hasCollectionFailures) {
-          this.groupedPageBrowserGraphCache.delete(cacheKey);
-        }
-        return result.assetsByRoute;
-      }).catch((error) => {
-        this.groupedPageBrowserGraphCache.delete(cacheKey);
-        throw error;
-      });
-      this.groupedPageBrowserGraphCache.set(cacheKey, pending);
-    }
-    return await pending;
+    const session = getAppPageBrowserGraphSession(this.appConfig);
+    const assetsByRoute = await session.resolveGroupedGraph(input.integrationName, async () => {
+      const built = await this.buildGroupedPageBrowserAssets(input, currentContribution);
+      if (built.hasCollectionFailures) {
+        return {
+          skipCache: true,
+          assetsByRoute: built.assetsByRoute,
+          dependencyPaths: built.dependencyPaths
+        };
+      }
+      return {
+        assetsByRoute: built.assetsByRoute,
+        dependencyPaths: built.dependencyPaths,
+        generation: 0
+      };
+    });
+    return {
+      assetsByRoute,
+      dependencyPaths: /* @__PURE__ */ new Set(),
+      hasCollectionFailures: false
+    };
   }
   async buildGroupedPageBrowserAssets(input, currentContribution) {
-    const routeFiles = await this.listIntegrationRouteFiles(input.integrationName);
+    const routeFiles = this.isHmrEnabled() ? [input.routeFile] : await this.listIntegrationRouteFiles(input.integrationName);
     const currentRouteGroupedDependencies = (currentContribution.dependencies ?? []).filter(
       (dep) => isGroupedContentScriptAsset(dep)
     );
     const groupedDependencies = [...currentRouteGroupedDependencies];
     const groupedAssetKeysByRoute = /* @__PURE__ */ new Map();
+    const dependencyPaths = /* @__PURE__ */ new Set([path.resolve(input.routeFile)]);
     let hasCollectionFailures = false;
     if (currentRouteGroupedDependencies.length > 0) {
       groupedAssetKeysByRoute.set(
@@ -103,9 +139,6 @@ class PageBrowserGraphService {
         );
         continue;
       }
-      if (this.isHmrEnabled()) {
-        continue;
-      }
       if (!contribution?.dependencies?.length) {
         continue;
       }
@@ -120,13 +153,20 @@ class PageBrowserGraphService {
         routeFile,
         new Set(routeGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle)))
       );
+      dependencyPaths.add(path.resolve(routeFile));
     }
     if (groupedDependencies.length === 0) {
       return {
         assetsByRoute: /* @__PURE__ */ new Map(),
+        dependencyPaths,
         hasCollectionFailures
       };
     }
+    for (const dependency of groupedDependencies) {
+      if (dependency.source === "file") {
+        dependencyPaths.add(path.resolve(dependency.filepath));
+      }
+    }
     const processedGroupedDependencies = await this.assetProcessingService.processDependencies(
       groupedDependencies,
       `${input.integrationName}:grouped-page-browser-graph`
@@ -146,8 +186,17 @@ class PageBrowserGraphService {
       }
       groupedAssetsByRoute.set(routeFile, matchedAssets);
     }
+    for (const asset of processedGroupedDependencies) {
+      if (asset.sourceFilepath) {
+        dependencyPaths.add(path.resolve(asset.sourceFilepath));
+      }
+      for (const bundledSourceFilepath of asset.bundledSourceFilepaths ?? []) {
+        dependencyPaths.add(path.resolve(bundledSourceFilepath));
+      }
+    }
     return {
       assetsByRoute: groupedAssetsByRoute,
+      dependencyPaths,
       hasCollectionFailures
     };
   }

package/src/route-renderer/orchestration/render-output.utils.d.ts

@@ -23,6 +23,20 @@ type MarkupNodeLikeShape = {
 export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
 /** Returns whether a value looks like a DOM-like markup node from SSR integrations. */
 export declare function isMarkupNodeLike(value: unknown): value is MarkupNodeLikeShape;
+/**
+ * Returns whether a value is a plain opaque object that string serializers would
+ * coerce via `String(value)` rather than render as markup.
+ *
+ * @remarks
+ * Template results (`strings`/`values`), markup nodes, arrays, and framework
+ * element markers (`$$typeof`) are not opaque. Cross-integration children that
+ * are only plain objects must use EcoEmbed or already-serialized HTML.
+ */
+export declare function isOpaqueForeignChildValue(children: unknown): boolean;
+/**
+ * Throws when foreign-path children would be coerced from an opaque object.
+ */
+export declare function assertForeignChildrenNotOpaque(children: unknown, context: string): void;
 /**
  * Injects `data-eco-trigger` into the first real HTML element opening tag of
  * a component's rendered output string.

package/src/route-renderer/orchestration/render-output.utils.js

@@ -85,6 +85,34 @@ function isMarkupNodeLikeShape(value) {
 function isMarkupNodeLike(value) {
   return isMarkupNodeLikeShape(value);
 }
+function isOpaqueForeignChildValue(children) {
+  if (children === null || typeof children !== "object") {
+    return false;
+  }
+  if (Array.isArray(children)) {
+    return false;
+  }
+  if ("$$typeof" in children) {
+    return false;
+  }
+  if ("strings" in children && Array.isArray(children.strings)) {
+    return false;
+  }
+  if (isMarkupNodeLikeShape(children)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(children);
+  return prototype === Object.prototype || prototype === null;
+}
+function assertForeignChildrenNotOpaque(children, context) {
+  if (!isOpaqueForeignChildValue(children)) {
+    return;
+  }
+  const childTag = Object.prototype.toString.call(children);
+  throw new TypeError(
+    `[ecopages] ${context} refused to coerce opaque foreign children (${childTag}). Use EcoEmbed for cross-integration children or pass already-serialized HTML.`
+  );
+}
 function injectTriggerAttributeIntoString(content, triggerId) {
   const str = content;
   let i = 0;
@@ -166,9 +194,11 @@ function inspectUnresolvedMarkerArtifactHtml(html) {
 }
 export {
   addTriggerAttribute,
+  assertForeignChildrenNotOpaque,
   decodeHtmlEntities,
   inspectUnresolvedMarkerArtifactHtml,
   isMarkupNodeLike,
+  isOpaqueForeignChildValue,
   isThenable,
   normalizeUnresolvedMarkerArtifactHtml,
   wrapWithScriptsInjector

package/src/route-renderer/orchestration/route-html-finalization.service.d.ts

@@ -8,7 +8,6 @@ export type RouteHtmlFinalizationContext<C> = {
         renderOptions: IntegrationRendererRenderOptions<C>;
         partial: boolean;
     }) => HtmlDocumentContribution[] | undefined;
-    applyAttributesToFirstBodyElement: (html: string, attributes: Record<string, string>) => string;
     applyAttributesToHtmlElement: (html: string, attributes: Record<string, string>) => string;
 };
 /**

package/src/route-renderer/orchestration/route-html-finalization.service.js

@@ -1,23 +1,18 @@
 function buildRouteHtmlFinalization(context) {
   const { renderOptions } = context;
-  const componentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0 ? renderOptions.componentRender.rootAttributes : void 0;
   const documentAttributes = context.getDocumentAttributes(renderOptions);
   const htmlContributions = context.getHtmlDocumentContributions({ renderOptions, partial: false });
-  const hasStructuralFinalization = componentRootAttributes && Object.keys(componentRootAttributes).length > 0 || documentAttributes && Object.keys(documentAttributes).length > 0;
+  const hasStructuralFinalization = documentAttributes && Object.keys(documentAttributes).length > 0;
   if (!hasStructuralFinalization && (!htmlContributions || htmlContributions.length === 0)) {
     return {};
   }
   return {
     htmlContributions,
     finalizeHtml: (html) => {
-      let renderedHtml = html;
-      if (componentRootAttributes) {
-        renderedHtml = context.applyAttributesToFirstBodyElement(renderedHtml, componentRootAttributes);
+      if (!documentAttributes || Object.keys(documentAttributes).length === 0) {
+        return html;
       }
-      if (documentAttributes) {
-        renderedHtml = context.applyAttributesToHtmlElement(renderedHtml, documentAttributes);
-      }
-      return renderedHtml;
+      return context.applyAttributesToHtmlElement(html, documentAttributes);
     }
   };
 }

package/src/route-renderer/orchestration/route-prepared-options.builder.d.ts

@@ -1,5 +1,5 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphResult, PageMetadataProps, EcoPageLayoutEntry, RouteRendererOptions } from '../../types/public-types.js';
+import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphResult, PageMetadataProps, EcoPageLayoutEntry, RouteRendererOptions } from '../../types/public-types.js';
 import { type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 type PreparedRenderInputs = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
@@ -20,7 +20,6 @@ export declare function buildPreparedRenderOptions<C = unknown>(input: {
     resolvedDependencies: ProcessedAsset[];
     allDependencies: ProcessedAsset[];
     pageBrowserGraph?: PageBrowserGraphResult;
-    componentRender?: ComponentRenderResult;
     appConfig: EcoPagesAppConfig;
 }): IntegrationRendererRenderOptions<C>;
 export {};

package/src/route-renderer/orchestration/route-prepared-options.builder.js

@@ -2,15 +2,7 @@ import { createPagePackage } from "../../services/assets/asset-processing-servic
 import { dedupeProcessedAssets } from "./processed-asset-dedupe.js";
 import { createPageLocalsProxy } from "./route-prepared-options.utils.js";
 function buildPreparedRenderOptions(input) {
-  const {
-    routeOptions,
-    resolvedInputs,
-    resolvedDependencies,
-    allDependencies,
-    pageBrowserGraph,
-    componentRender,
-    appConfig
-  } = input;
+  const { routeOptions, resolvedInputs, resolvedDependencies, allDependencies, pageBrowserGraph, appConfig } = input;
   const { Page, HtmlTemplate, Layouts, Layout, layoutEntries, props, metadata, integrationSpecificProps } = resolvedInputs;
   const dedupedDependencies = dedupeProcessedAssets(allDependencies);
   const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
@@ -29,7 +21,6 @@ function buildPreparedRenderOptions(input) {
     ...routeOptions,
     resolvedDependencies,
     pagePackage,
-    componentRender,
     HtmlTemplate,
     Layouts,
     Layout,

package/src/route-renderer/orchestration/route-render-orchestrator.d.ts

@@ -1,5 +1,5 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../types/public-types.js';
+import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../types/public-types.js';
 import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 import { OwnershipValidationService } from './ownership-validation.service.js';
@@ -46,15 +46,6 @@ export interface RouteRenderOrchestratorAdapter<C> {
      * Collects declarative Page Browser Graph requirements for one route.
      */
     collectPageBrowserGraphContribution(routeFile: string): Promise<PageBrowserGraphContribution | undefined>;
-    /**
-     * Resolves the optional page-root render through the foreign-child-aware component contract.
-     */
-    resolveRoutePageComponentRender(input: {
-        Page: EcoComponent;
-        Layout?: EcoComponent;
-        props: Record<string, unknown>;
-        routeOptions: RouteRendererOptions;
-    }): Promise<ComponentRenderResult | undefined>;
     /**
      * Executes the Integration-specific route render.
      */
@@ -100,8 +91,8 @@ export declare class RouteRenderOrchestrator {
      * Builds normalized route render options before the integration render runs.
      *
      * This preparation step validates route-root ownership, resolves page data,
-     * collects processed assets, captures optional page-root render metadata, and
-     * produces the page package consumed by downstream HTML transformation.
+     * collects processed assets, and produces the page package consumed by downstream
+     * HTML transformation.
      */
     prepareRenderOptions<C = unknown>(routeOptions: RouteRendererOptions, adapter: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
     resolveDeclaredPageBrowserGraph(input: {

package/src/route-renderer/orchestration/route-render-orchestrator.js

@@ -23,12 +23,12 @@ class RouteRenderOrchestrator {
    * Builds normalized route render options before the integration render runs.
    *
    * This preparation step validates route-root ownership, resolves page data,
-   * collects processed assets, captures optional page-root render metadata, and
-   * produces the page package consumed by downstream HTML transformation.
+   * collects processed assets, and produces the page package consumed by downstream
+   * HTML transformation.
    */
   async prepareRenderOptions(routeOptions, adapter) {
     const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
-    const { Page, HtmlTemplate, Layouts, Layout } = resolvedInputs;
+    const { Page, HtmlTemplate, Layouts } = resolvedInputs;
     const validationErrors = this.ownershipValidationService.validate({
       currentIntegrationName: adapter.name,
       roots: [
@@ -39,7 +39,7 @@ class RouteRenderOrchestrator {
     });
     throwIfOwnershipInvalid(validationErrors);
     const componentsToResolve = [HtmlTemplate, ...Layouts, Page];
-    const [{ resolvedDependencies }, pageBrowserGraph, componentRender] = await Promise.all([
+    const [{ resolvedDependencies }, pageBrowserGraph] = await Promise.all([
       adapter.resolveRouteDependencies({
         components: componentsToResolve
       }),
@@ -47,21 +47,12 @@ class RouteRenderOrchestrator {
         routeFile: routeOptions.file,
         integrationName: adapter.name,
         collectContribution: async (routeFile) => await adapter.collectPageBrowserGraphContribution(routeFile)
-      }),
-      adapter.resolveRoutePageComponentRender({
-        Page,
-        Layout,
-        props: resolvedInputs.props,
-        routeOptions
       })
     ]);
     const allDependencies = [
       ...resolvedDependencies,
       ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name)
     ];
-    if (componentRender?.assets?.length) {
-      allDependencies.push(...componentRender.assets);
-    }
     const triggers = collectResolvedLazyTriggersFromGraph(componentsToResolve, adapter.name);
     const [globalAssets, eagerSsrLazyAssets] = await Promise.all([
       triggers.length > 0 ? buildGlobalInjectorAssets(this.appConfig, this.assetProcessingService, triggers, adapter.name) : Promise.resolve([]),
@@ -74,7 +65,6 @@ class RouteRenderOrchestrator {
       resolvedDependencies,
       allDependencies,
       pageBrowserGraph,
-      componentRender,
       appConfig: this.appConfig
     });
   }

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

@@ -16,7 +16,7 @@ import { materializeContentScriptAsset } from "./materialize-content-script-asse
 import {
   getDevBrowserScriptCacheEntry,
   setDevBrowserScriptCacheEntry
-} from "../../../build/dev-browser-script-cache.js";
+} from "../../../build/cache/dev-browser-script-cache.js";
 import {
   ContentScriptProcessor,
   ContentStylesheetProcessor,

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: {

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;

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

@@ -1,5 +1,4 @@
 import { appLogger } from "../../../../../global/app-logger.js";
-import { getAppBrowserBuildPlugins } from "../../../../../build/build-adapter.js";
 import { fileSystem } from "@ecopages/file-system";
 import path from "node:path";
 import { BaseProcessor } from "./base-processor.js";
@@ -22,14 +21,6 @@ class BaseScriptProcessor extends BaseProcessor {
     }
     return dep.bundleOptions || {};
   }
-  collectBuildPlugins(excludePluginNames) {
-    const buildPlugins = getAppBrowserBuildPlugins(this.appConfig);
-    if (!excludePluginNames || excludePluginNames.length === 0) {
-      return buildPlugins;
-    }
-    const excluded = new Set(excludePluginNames);
-    return buildPlugins.filter((plugin) => !excluded.has(plugin.name));
-  }
   async bundleScript({
     entrypoint,
     outdir,
@@ -37,8 +28,6 @@ class BaseScriptProcessor extends BaseProcessor {
     plugins: additionalPlugins,
     ...rest
   }) {
-    const buildPlugins = this.collectBuildPlugins(excludeAppBuildPlugins);
-    const allPlugins = additionalPlugins ? [...additionalPlugins, ...buildPlugins] : buildPlugins;
     const buildResult = await this.browserBundleService.bundle({
       profile: "browser-script",
       entrypoints: [entrypoint],
@@ -47,7 +36,7 @@ class BaseScriptProcessor extends BaseProcessor {
       excludeAppBuildPlugins,
       splitting: true,
       naming: "[name]-[hash].[ext]",
-      plugins: allPlugins,
+      plugins: additionalPlugins,
       ...rest
     });
     if (!buildResult.success) {
@@ -86,8 +75,6 @@ class BaseScriptProcessor extends BaseProcessor {
     plugins: additionalPlugins,
     ...rest
   }) {
-    const buildPlugins = this.collectBuildPlugins(excludeAppBuildPlugins);
-    const allPlugins = additionalPlugins ? [...additionalPlugins, ...buildPlugins] : buildPlugins;
     const buildResult = await this.browserBundleService.bundleGroupedEntries(entries, {
       profile: "browser-script",
       outdir,
@@ -96,7 +83,7 @@ class BaseScriptProcessor extends BaseProcessor {
       ...rest,
       splitting: true,
       naming: "[name]-[hash].[ext]",
-      plugins: allPlugins
+      plugins: additionalPlugins
     });
     if (!buildResult.success) {
       for (const log of buildResult.logs) {

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

@@ -1,7 +1,7 @@
 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 { shouldUseDevBrowserScriptCache } from "../../../../../build/cache/dev-browser-script-cache.js";
 import { BaseScriptProcessor } from "../base/base-script-processor.js";
 class ContentScriptProcessor extends BaseScriptProcessor {
   getContentScriptEntryDir() {

package/src/services/assets/browser-bundle.service.d.ts

@@ -1,6 +1,24 @@
-import type { BuildResult, BuildTranspileProfile } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { BuildResult } from '../../build/build-adapter.js';
+import type { BuildTranspileProfile } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Browser-oriented build request accepted by {@link BrowserBundleService}.
+ *
+ * @remarks
+ * `profile` is a {@link BuildTranspileProfile} (transpile settings only).
+ * `executor` selects the {@link BuildRuntime} concurrency slot:
+ * - `'hmr'` + (`hmr-entrypoint` | `hmr-runtime`) → `'browser-hmr'`
+ * - everything else (including `browser-script`, and `'build'`) → `'route-module'`
+ *
+ * Defaults `executor` to `'hmr'`. Request options are always assembled with
+ * browser-hmr *defaults* via {@link createBrowserBuildRequest}; only the
+ * concurrency/dedupe wrapper differs.
+ *
+ * Uses request-scope {@link requestBuildDedupe} plus in-flight
+ * {@link DedupingBuildExecutor} coalescing; both key on
+ * {@link createBuildRequestIdentity}.
+ */
 export type BrowserBundleOptions = {
     entrypoints: string[] | Record<string, string>;
     outdir?: string;
@@ -17,28 +35,10 @@ export type BrowserBundleOptions = {
     external?: string[];
     plugins?: EcoBuildPlugin[];
     executor?: 'build' | 'hmr';
-    [key: string]: unknown;
-    profile: BuildTranspileProfile;
-    excludeAppBuildPlugins?: string[];
-};
-type BrowserBundleGroupedOptions = {
-    outdir?: string;
-    outbase?: string;
-    naming?: string;
-    conditions?: string[];
-    define?: Record<string, string>;
-    minify?: boolean;
-    treeshaking?: boolean;
-    splitting?: boolean;
-    root?: string;
-    bundle?: boolean;
-    externalPackages?: boolean;
-    external?: string[];
-    plugins?: EcoBuildPlugin[];
-    [key: string]: unknown;
     profile: BuildTranspileProfile;
     excludeAppBuildPlugins?: string[];
 };
+type BrowserBundleGroupedOptions = Omit<BrowserBundleOptions, 'entrypoints'>;
 export interface BrowserBundleExecutor {
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
 }
@@ -50,24 +50,20 @@ export type BrowserBundleGroupedEntry = {
  * App-owned boundary for browser-oriented bundle work.
  *
  * @remarks
- * This service owns the shared browser transpile defaults and ensures browser
- * builds always run through the app-owned executor rather than direct backend
- * calls scattered across HMR and asset processing paths.
+ * Owns shared browser transpile defaults and ensures browser builds run through
+ * the app-owned executor rather than direct backend calls. Assembles a complete
+ * request via {@link createBrowserBuildRequest} before scheduling.
  */
 export declare class BrowserBundleService implements BrowserBundleExecutor {
     private readonly appConfig;
-    /**
-     * Creates the browser bundle boundary for one finalized app instance.
-     */
     constructor(appConfig: EcoPagesAppConfig);
     /**
      * Runs one browser-targeted build through the app-owned executor.
      *
      * @remarks
-     * Browser defaults and app-owned browser build plugins are applied here so HMR
-     * and runtime asset generation do not have to recreate that policy at each call
-     * site. Also forwards {@link getAppSourceTransforms | app source transforms} so
-     * metadata injection runs after boundary/runtime `onLoad` rewrites.
+     * Browser defaults, app-owned browser plugins, and
+     * {@link getAppSourceTransforms | app source transforms} are applied here
+     * so HMR and asset generation do not recreate that policy at each call site.
      */
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
     bundleGroupedEntries(entries: BrowserBundleGroupedEntry[], options: BrowserBundleGroupedOptions): Promise<BuildResult>;