@ecopages/core 0.2.0-beta.7 → 0.2.0-beta.9

package/src/plugins/integration-plugin.d.ts

@@ -6,10 +6,12 @@ import type { EcoPagesElement } from '../types/public-types.js';
 import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
 import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
 export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
 /**
  * Type-erased integration plugin stored in app-level registries.
@@ -47,13 +49,6 @@ export interface IntegrationPluginConfig {
      * They are not specific to any particular page or component.
      */
     integrationDependencies?: AssetDefinition[];
-    /**
-     * The strategy to use for static building.
-     * - 'render': Execute component function directly (faster, efficient).
-     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
-     * @default 'render'
-     */
-    staticBuildStep?: 'render' | 'fetch';
     /**
      * Declares runtime-specific requirements that must be satisfied before the
      * app can start with this integration enabled.
@@ -96,7 +91,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly name: string;
     readonly extensions: string[];
     abstract renderer: RendererClass<C>;
-    readonly staticBuildStep: 'render' | 'fetch';
     readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     readonly jsxImportSource?: string;
     protected integrationDependencies: AssetDefinition[];
@@ -213,6 +207,23 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this integration's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
+    /**
+     * Runs integration-specific setup before static page generation begins.
+     *
+     * @remarks
+     * Integrations that need build-scoped SSR preload or worker sessions should
+     * start them here rather than per-page inside the renderer.
+     */
+    beforeStaticExport?(_context: StaticExportContext): Promise<void>;
+    /**
+     * Releases resources started in {@link beforeStaticExport}.
+     */
+    afterStaticExport?(_context: StaticExportContext): Promise<void>;
     /**
      * Performs runtime-only integration setup after config build has already
      * sealed manifest contributions.

package/src/plugins/integration-plugin.js

@@ -15,7 +15,6 @@ function assertIntegrationInvariant(condition, message) {
 class IntegrationPlugin {
   name;
   extensions;
-  staticBuildStep;
   runtimeCapability;
   jsxImportSource;
   integrationDependencies;
@@ -60,7 +59,6 @@ class IntegrationPlugin {
     this.name = config.name;
     this.extensions = config.extensions;
     this.integrationDependencies = config.integrationDependencies || [];
-    this.staticBuildStep = config.staticBuildStep || "render";
     this.runtimeCapability = config.runtimeCapability;
     this.jsxImportSource = config.jsxImportSource;
   }
@@ -169,6 +167,13 @@ class IntegrationPlugin {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this integration's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   /**
    * Performs runtime-only integration setup after config build has already
    * sealed manifest contributions.

package/src/plugins/processor.d.ts

@@ -80,6 +80,11 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
      * warming or watcher registration should stay in `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this processor's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
     abstract setup(): Promise<void>;
     abstract teardown(): Promise<void>;
     abstract process(input: unknown, filePath?: string): Promise<unknown>;

package/src/plugins/processor.js

@@ -54,6 +54,13 @@ class Processor {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this processor's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   getCachePath(key) {
     return `${this.context?.cache}/${key}`;
   }

package/src/plugins/source-transform.d.ts

@@ -4,9 +4,21 @@ export interface EcoSourceTransformResult {
     code: string;
     map?: unknown;
 }
+/**
+ * Bundler-neutral source transform registered on {@link EcoPagesAppConfig.sourceTransforms}.
+ *
+ * @remarks
+ * Prefer this shape over a competing {@link EcoBuildPlugin} `onLoad` handler when
+ * the transform only rewrites module source. Browser/HMR builds run source
+ * transforms after first-wins `onLoad` plugins, so metadata injection and similar
+ * passes still run on rewritten output from boundary/runtime plugins.
+ */
 export interface EcoSourceTransform {
+    /** Stable transform name. Also used to dedupe loader plugins in browser builds. */
     name: string;
+    /** File-path filter tested against {@link normalizeTransformId | normalized ids}. */
     filter: RegExp;
+    /** Runs before default transforms, or after them when set to `post`. */
     enforce?: 'pre' | 'post';
     transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
 }
@@ -24,8 +36,27 @@ export declare function normalizeTransformId(id: string): string;
  * Applies one source transform if the normalized id matches its filter.
  */
 export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * Applies app-owned source transforms in deterministic `pre` → default → `post` order.
+ *
+ * @remarks
+ * Used by the Rolldown plugin bridge after `onLoad` plugins produce final module
+ * contents. Transforms that do not match `filter` are skipped; matching transforms
+ * are chained left-to-right on the current source string.
+ *
+ * @param transforms - App-owned transforms, usually from {@link getAppSourceTransforms}.
+ * @param code - Current module source.
+ * @param id - Module id forwarded to each transform after query/hash normalization.
+ * @returns The transformed source, or the original `code` when no transform matches.
+ */
+export declare function applySourceTransforms(transforms: readonly EcoSourceTransform[], code: string, id: string): string;
 /**
  * Adapts a source transform into the existing Ecopages build-plugin contract.
+ *
+ * @remarks
+ * Server-oriented builds and loader registration still use this adapter.
+ * Browser/HMR builds should register the transform in `appConfig.sourceTransforms`
+ * instead so the Rolldown bridge can run it after competing `onLoad` plugins.
  */
 export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
 /**

package/src/plugins/source-transform.js

@@ -13,6 +13,27 @@ function applySourceTransform(transform, code, id) {
   }
   return transform.transform(code, normalizedId);
 }
+const SOURCE_TRANSFORM_ENFORCE_ORDER = {
+  pre: 0,
+  default: 1,
+  post: 2
+};
+function getSourceTransformEnforceOrder(transform) {
+  return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? "default"];
+}
+function applySourceTransforms(transforms, code, id) {
+  let current = code;
+  for (const transform of [...transforms].sort(
+    (left, right) => getSourceTransformEnforceOrder(left) - getSourceTransformEnforceOrder(right)
+  )) {
+    const result = applySourceTransform(transform, current, id);
+    if (!result) {
+      continue;
+    }
+    current = typeof result === "string" ? result : result.code;
+  }
+  return current;
+}
 function inferLoaderFromPath(filePath) {
   const extension = path.extname(filePath).toLowerCase();
   switch (extension) {
@@ -56,13 +77,14 @@ function createVitePluginFromSourceTransform(transform) {
   };
 }
 function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
+  return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
 }
 function createVitePluginsFromAppSourceTransforms(appConfig) {
   return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
 }
 export {
   applySourceTransform,
+  applySourceTransforms,
   createEcoBuildPluginFromSourceTransform,
   createVitePluginFromSourceTransform,
   createVitePluginsFromAppSourceTransforms,

package/src/route-renderer/GRAPH.md

@@ -33,11 +33,11 @@ flowchart TD
 
 ## 2) Route Render Flow
 
-`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderFlow`.
+`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderOrchestrator`.
 
 ```mermaid
 flowchart TD
-  A[IntegrationRenderer.execute] --> B[RouteRenderFlow.prepareRenderOptions]
+  A[IntegrationRenderer.execute] --> B[RouteRenderOrchestrator.prepareRenderOptions]
   B --> C[resolvePageModule]
   C --> D[ownershipValidationService.validate]
   D --> E[resolvePageData]
@@ -121,7 +121,7 @@ flowchart TD
 The most useful reading order is:
 
 1. `route-renderer.ts`
-2. `orchestration/route-render-flow.ts`
+2. `orchestration/route-render-orchestrator.ts`
 3. `orchestration/integration-renderer.ts`
 4. `orchestration/ownership-validation.service.ts`
 5. `orchestration/ownership-planning.service.ts`
@@ -134,7 +134,7 @@ The most useful reading order is:
 ## 7) Key Files
 
 - `packages/core/src/route-renderer/route-renderer.ts`
-- `packages/core/src/route-renderer/orchestration/route-render-flow.ts`
+- `packages/core/src/route-renderer/orchestration/route-render-orchestrator.ts`
 - `packages/core/src/route-renderer/orchestration/integration-renderer.ts`
 - `packages/core/src/route-renderer/orchestration/ownership-validation.service.ts`
 - `packages/core/src/route-renderer/orchestration/ownership-planning.service.ts`

package/src/route-renderer/README.md

@@ -27,7 +27,7 @@ These concepts intentionally live in different places:
 - `component-render-context.ts` intercepts foreign children during active component render
 - `queued-foreign-subtree-resolution.service.ts` resolves queued foreign subtrees for renderers that cannot hand them off inline
 - `integration-renderer.ts` owns renderer-to-renderer delegation and shared shell composition
-- `route-render-flow.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+- `route-render-orchestrator.ts` owns route preparation, final response capture, and unresolved artifact enforcement
 
 ## Main Files
 
@@ -38,7 +38,7 @@ These concepts intentionally live in different places:
 
 ### `orchestration/`
 
-- `route-render-flow.ts`: one route render from page-module loading through final HTML output
+- `route-render-orchestrator.ts`: one route render from page-module loading through final HTML output
 - `integration-renderer.ts`: abstract base class for route rendering, explicit view rendering, and foreign-child delegation
 - `ownership-planning.service.ts`: declared ownership graph construction
 - `ownership-validation.service.ts`: up-front ownership validation for route roots and declared descendants
@@ -56,11 +56,11 @@ These concepts intentionally live in different places:
 The route-render contract is:
 
 1. `RouteRendererFactory` selects the owning integration renderer.
-2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderFlow`.
-3. `RouteRenderFlow.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
+2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderOrchestrator`.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
 4. The integration renderer performs page, layout, and document-shell rendering. When it encounters a foreign child, it delegates that child back to the owning renderer.
 5. If a renderer needs queued handoff, it emits internal foreign-subtree tokens and resolves them before returning final HTML.
-6. `RouteRenderFlow.execute()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
+6. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
 
 Important:
 
@@ -115,4 +115,5 @@ Not every integration needs queue-based handoff.
 ## Current Limits
 
 - `ownershipPlan` is still diagnostic and preparatory metadata; it does not yet drive a full route-composer execution model.
+- `integration-renderer.ts` remains large (~1,400 lines); document-shell helpers and foreign-subtree wiring are the likely future extraction targets.
 - Different integrations still own different foreign-child runtime strategies, which is intentional where child transport or hydration behavior differs.

package/src/route-renderer/orchestration/foreign-subtree-execution.service.js

@@ -5,9 +5,7 @@ import {
 import {
   QueuedForeignSubtreeResolutionService
 } from "./queued-foreign-subtree-resolution.service.js";
-function isMarkupNodeLike(value) {
-  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && (!("outerHTML" in value) || typeof value.outerHTML === "string");
-}
+import { isMarkupNodeLike } from "./render-output.utils.js";
 class ForeignSubtreeExecutionService {
   queuedForeignSubtreeResolutionService;
   constructor(queuedForeignSubtreeResolutionService = new QueuedForeignSubtreeResolutionService()) {

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -4,7 +4,7 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, PagePackageResult, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
 import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
@@ -59,7 +59,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected pageModuleLoaderService: PageModuleLoaderService;
     protected routeRenderOrchestrator: RouteRenderOrchestrator;
     protected readonly foreignSubtreeExecutionService: ForeignSubtreeExecutionService;
+    /**
+     * Serializes route and view renders that mutate `htmlTransformer` state.
+     *
+     * Integration renderers are cached per integration, so concurrent static builds
+     * and overlapping SSR requests must not share one transformer page package.
+     */
+    private renderExclusiveChain;
     protected DOC_TYPE: string;
+    private runRenderExclusive;
     /**
      * Loads one route module through the owning renderer's import path.
      *
@@ -351,7 +359,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     }): Promise<ComponentRenderResult | undefined>;
     protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
     protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
-    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
+    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
     /**
      * Prepares the render options for the integration renderer.
      * It imports the page file, collects dependencies, and prepares the render options.

package/src/route-renderer/orchestration/integration-renderer.js

@@ -10,15 +10,12 @@ import { OwnershipValidationService } from "./ownership-validation.service.js";
 import {
   RouteRenderOrchestrator
 } from "./route-render-orchestrator.js";
-import { normalizeUnresolvedMarkerArtifactHtml } from "./render-output.utils.js";
+import { normalizeUnresolvedMarkerArtifactHtml, isMarkupNodeLike } from "./render-output.utils.js";
 import {
   ForeignSubtreeExecutionService
 } from "./foreign-subtree-execution.service.js";
 import {} from "./queued-foreign-subtree-resolution.service.js";
 import { buildProcessedAssetDedupeKey } from "./processed-asset-dedupe.js";
-function isMarkupNodeLike(value) {
-  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && "outerHTML" in value && typeof value.outerHTML === "string";
-}
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -31,7 +28,22 @@ class IntegrationRenderer {
   pageModuleLoaderService;
   routeRenderOrchestrator;
   foreignSubtreeExecutionService = new ForeignSubtreeExecutionService();
+  /**
+   * Serializes route and view renders that mutate `htmlTransformer` state.
+   *
+   * Integration renderers are cached per integration, so concurrent static builds
+   * and overlapping SSR requests must not share one transformer page package.
+   */
+  renderExclusiveChain = Promise.resolve();
   DOC_TYPE = "<!DOCTYPE html>";
+  runRenderExclusive(operation) {
+    const run = this.renderExclusiveChain.then(operation, operation);
+    this.renderExclusiveChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
   /**
    * Loads one route module through the owning renderer's import path.
    *
@@ -397,7 +409,7 @@ class IntegrationRenderer {
    * @returns Structured component render result for orchestration paths.
    */
   async renderStringComponentWithSerializedChildren(input, component) {
-    const serializedChildren = input.children === void 0 ? void 0 : typeof input.children === "string" ? input.children : isMarkupNodeLike(input.children) ? input.children.outerHTML : void 0;
+    const serializedChildren = input.children === void 0 ? void 0 : typeof input.children === "string" ? input.children : isMarkupNodeLike(input.children) && typeof input.children.outerHTML === "string" ? input.children.outerHTML : void 0;
     if (input.children !== void 0 && serializedChildren === void 0) {
       const componentFile = input.component.config?.__eco?.file ?? "unknown component";
       const childTag = Object.prototype.toString.call(input.children);
@@ -533,7 +545,7 @@ class IntegrationRenderer {
    * @returns The imported module.
    */
   async importPageFile(file, options) {
-    const bypassCache = options?.bypassCache ?? (typeof Bun !== "undefined" && process.env.NODE_ENV === "development");
+    const bypassCache = options?.bypassCache ?? false;
     const pageModule = this.usesIntegrationPageImporter(file) ? await this.importIntegrationPageFile(file, {
       bypassCache,
       cacheScope: options?.cacheScope
@@ -633,7 +645,7 @@ class IntegrationRenderer {
       resolveRoutePageComponentRender: (input) => this.resolveRoutePageComponentRender(input),
       renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
       getRouteHtmlFinalization: (renderOptions) => this.getRouteHtmlFinalization(renderOptions),
-      transformRouteResponse: (response, htmlContributions) => this.transformRouteResponse(response, htmlContributions)
+      transformRouteResponse: (response, htmlContributions, pagePackage) => this.transformRouteResponse(response, htmlContributions, pagePackage)
     };
   }
   async resolveRouteRenderInputs(routeOptions) {
@@ -706,8 +718,13 @@ class IntegrationRenderer {
       }
     };
   }
-  async transformRouteResponse(response, htmlContributions) {
-    const transformedResponse = await this.htmlTransformer.transform(response, htmlContributions);
+  async transformRouteResponse(response, htmlContributions, pagePackage) {
+    const resolvedPagePackage = this.htmlTransformer.getPagePackage() ?? pagePackage;
+    const transformedResponse = await this.htmlTransformer.transform(
+      response,
+      htmlContributions,
+      resolvedPagePackage
+    );
     return transformedResponse.body ?? await transformedResponse.text();
   }
   /**
@@ -752,9 +769,12 @@ class IntegrationRenderer {
    * @returns Rendered route body plus effective cache strategy.
    */
   async execute(options) {
-    const adapter = this.createRouteRenderOrchestratorAdapter();
-    const renderOptions = await this.prepareRenderOptions(options, adapter);
-    return this.routeRenderOrchestrator.executePrepared(renderOptions, adapter);
+    return this.runRenderExclusive(async () => {
+      this.htmlTransformer.setProcessedDependencies([]);
+      const adapter = this.createRouteRenderOrchestratorAdapter();
+      const renderOptions = await this.prepareRenderOptions(options, adapter);
+      return this.routeRenderOrchestrator.executePrepared(renderOptions, adapter);
+    });
   }
   /**
    * Finalizes already-resolved HTML for explicit renderer-owned paths.

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

@@ -21,6 +21,8 @@ type MarkupNodeLikeShape = {
  * @typeParam T Expected resolved type of the thenable.
  */
 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;
 /**
  * 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

@@ -82,6 +82,9 @@ function isTemplateContentShape(value) {
 function isMarkupNodeLikeShape(value) {
   return typeof value === "object" && value !== null && typeof value.nodeType === "number";
 }
+function isMarkupNodeLike(value) {
+  return isMarkupNodeLikeShape(value);
+}
 function injectTriggerAttributeIntoString(content, triggerId) {
   const str = content;
   let i = 0;
@@ -165,6 +168,7 @@ export {
   addTriggerAttribute,
   decodeHtmlEntities,
   inspectUnresolvedMarkerArtifactHtml,
+  isMarkupNodeLike,
   isThenable,
   normalizeUnresolvedMarkerArtifactHtml,
   wrapWithScriptsInjector

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 } from '../../types/public-types.js';
+import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, PagePackageResult, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type 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';
@@ -64,7 +64,7 @@ export interface RouteRenderOrchestratorAdapter<C> {
     /**
      * Runs SSR-policy response transformation and returns the body value exposed to callers.
      */
-    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
+    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
 }
 /**
  * Captured route-render output in both replayable body and string HTML forms.

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

@@ -205,21 +205,20 @@ class RouteRenderOrchestrator {
       return result.assetsByRoute;
     }
     const cacheKey = input.integrationName;
-    const cached = this.groupedPageBrowserGraphCache.get(cacheKey);
-    if (cached) {
-      return await cached;
-    }
-    const pendingGroupedAssets = this.buildGroupedPageBrowserAssets(input, currentContribution).then((result) => {
-      if (result.hasCollectionFailures) {
+    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);
-      }
-      return result.assetsByRoute;
-    }).catch((error) => {
-      this.groupedPageBrowserGraphCache.delete(cacheKey);
-      throw error;
-    });
-    this.groupedPageBrowserGraphCache.set(cacheKey, pendingGroupedAssets);
-    return await pendingGroupedAssets;
+        throw error;
+      });
+      this.groupedPageBrowserGraphCache.set(cacheKey, pending);
+    }
+    return await pending;
   }
   /**
    * Builds the shared grouped page-browser asset map for one integration.
@@ -362,7 +361,8 @@ class RouteRenderOrchestrator {
             "Content-Type": "text/html"
           }
         }),
-        htmlFinalization.htmlContributions
+        htmlFinalization.htmlContributions,
+        renderOptions.pagePackage
       );
       return {
         body: body2,
@@ -376,7 +376,8 @@ class RouteRenderOrchestrator {
           "Content-Type": "text/html"
         }
       }),
-      htmlFinalization.htmlContributions
+      htmlFinalization.htmlContributions,
+      renderOptions.pagePackage
     );
     return {
       body,

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

@@ -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/browser-runtime-asset.factory.d.ts

@@ -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.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,37 +1,57 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../../../config/constants.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) {
+    const importSpecifier = resolveEntryImportSpecifier(module.specifier, requireFromRoot, entryDir);
     if (module.defaultExport) {
-      statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+      statements.push(`import __ecopages_default_export__ from '${importSpecifier}';`);
       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}';`);
+      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 resolveEntryImportSpecifier(specifier, requireFromRoot, entryDir) {
+  if (specifier.startsWith("node:") || specifier.startsWith("file:")) {
+    return specifier;
+  }
+  const resolvedPath = requireFromRoot.resolve(specifier);
+  let relativePath = path.relative(entryDir, resolvedPath).replace(/\\/g, "/");
+  if (!relativePath.startsWith(".")) {
+    relativePath = `./${relativePath}`;
+  }
+  return relativePath;
+}
 function getModuleExportNames(specifier, requireFromRoot) {
   const moduleExports = requireFromRoot(specifier);
   return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();