@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -4,17 +4,16 @@
  * @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, 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';
 import { HttpError } from '../../errors/http-error.js';
 import { DependencyResolverService } from '../page-loading/dependency-resolver.js';
 import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
-import { type RouteHtmlFinalization, RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
+import { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
 import type { ForeignChildRuntime } from './component-render-context.js';
-import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer } from './foreign-subtree-execution.service.js';
-import { type QueuedForeignSubtreeResolutionContext } from './queued-foreign-subtree-resolution.service.js';
+import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer, type ForeignSubtreeQueuedHtmlOptions, type QueuedForeignSubtreeResolutionContext } from './foreign-subtree-execution.service.js';
 /**
  * Controls how one route module is loaded outside the normal render path.
  *
@@ -59,7 +58,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.
      *
@@ -69,34 +76,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * with raw transpiler access.
      */
     loadPageModule(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
-    /**
-     * Reads the execution-scoped owning-renderer cache from one render input.
-     *
-     * Shared page/layout/document shell helpers pass one cache through
-     * `integrationContext` so repeated delegation to the same foreign integration
-     * can reuse a single initialized renderer instance during one render flow.
-     * The cache is deliberately scoped to the current render execution rather than
-     * stored on the renderer, which avoids leaking mutable integration state across
-     * requests while still preventing redundant renderer initialization.
-     *
-     * @param integrationContext - Optional render context carried with one render input.
-     * @returns The current execution cache when present.
-     */
-    private getOwningRendererCache;
-    private getForeignOwnerIntegrationName;
-    /**
-     * Attaches an execution-scoped owning-renderer cache to one render input.
-     *
-     * Foreign-owned page, layout, or document shells may delegate several times in
-     * the same render flow. Threading the cache through `integrationContext`
-     * preserves renderer reuse without changing the public render input contract.
-     * Existing integration-specific context is preserved and augmented.
-     *
-     * @param input - Original render input.
-     * @param rendererCache - Execution-scoped renderer cache to propagate.
-     * @returns Render input augmented with the shared renderer cache.
-     */
-    private withOwningRendererCache;
     protected getRendererModuleValue(key: string): unknown;
     protected getRendererModuleString(key: string): string | undefined;
     protected getRendererBootstrapDependencies(partial?: boolean): ProcessedAsset[];
@@ -219,20 +198,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         documentProps?: Record<string, unknown>;
         transformDocumentHtml?: (html: string) => string;
     }): Promise<string>;
-    private composeDocumentShell;
-    /**
-     * Renders one string-first component with serialized children and collects its assets.
-     *
-     * String-oriented integrations frequently share the same component contract:
-     * pass serialized children through props, coerce the render result to HTML, and
-     * attach any component-scoped dependencies. This helper centralizes that flow
-     * so integrations can opt into shared orchestration without repeating the same
-     * string-render boilerplate.
-     *
-     * @param input - Component render input.
-     * @param component - String-oriented component implementation to execute.
-     * @returns Structured component render result for orchestration paths.
-     */
     protected renderStringComponentWithSerializedChildren(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
     protected getForeignSubtreeTokenPrefix(): string;
     protected getForeignSubtreeResolutionContextKey(): string;
@@ -244,6 +209,10 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         createRuntimeContext?: (integrationContext: BaseIntegrationContext & Record<string, unknown>, rendererCache: Map<string, unknown>) => TContext;
     }): ForeignChildRuntime;
     protected getQueuedForeignSubtreeResolutionContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput): TContext | undefined;
+    protected resolveQueuedForeignSubtreeHtml<TContext extends QueuedForeignSubtreeResolutionContext>(html: string, runtimeContext: TContext | undefined, renderQueuedChildren: ForeignSubtreeQueuedHtmlOptions<TContext>['renderQueuedChildren'], queueLabel?: string): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
     /**
      * Renders a string-first component, then resolves any queued foreign
      * boundaries before returning final component HTML.
@@ -350,8 +319,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         routeOptions: RouteRendererOptions;
     }): 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.
@@ -413,6 +381,8 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * other runtime coordination markers without relying on script sniffing.
      */
     protected getDocumentAttributes(_renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    protected applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    protected applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
     /**
      * Returns declarative HTML fragments that core should inject into the final document.
      *
@@ -451,12 +421,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * renderer's nested foreign-child handoff.
      */
     renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    /**
-     * Compatibility foreign-subtree contract that exposes a narrower payload shape for
-     * future route-composition work while preserving the current
-     * `renderComponentWithForeignChildren()` runtime semantics.
-     */
-    renderForeignSubtree(input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload>;
     private normalizeComponentRenderOutput;
     protected normalizeUnresolvedMarkerArtifactHtml(html: string): string;
     /**

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

@@ -7,18 +7,23 @@ import { HttpError } from "../../errors/http-error.js";
 import { DependencyResolverService } from "../page-loading/dependency-resolver.js";
 import { PageModuleLoaderService } from "../page-loading/page-module-loader.js";
 import { OwnershipValidationService } from "./ownership-validation.service.js";
+import { hasForeignChildDescendantsInGraph } from "./component-graph-collectors.js";
 import {
   RouteRenderOrchestrator
 } from "./route-render-orchestrator.js";
-import { normalizeUnresolvedMarkerArtifactHtml } from "./render-output.utils.js";
+import { createIntegrationRouteRenderAdapter } from "./integration-route-render-adapter.js";
+import { loadPageBrowserGraphContribution } from "./page-browser-graph-contribution.loader.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";
-}
+import {
+  applyDocumentShellAttributeStamping,
+  composeDocumentShell,
+  renderPageDocumentShell
+} from "./document-shell-render.service.js";
+import { resolveInnermostPageLayout, resolvePageLayoutComponents } from "./layout-shell-props.service.js";
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -31,7 +36,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.
    *
@@ -43,52 +63,6 @@ class IntegrationRenderer {
   async loadPageModule(file, options) {
     return this.importPageFile(file, options);
   }
-  /**
-   * Reads the execution-scoped owning-renderer cache from one render input.
-   *
-   * Shared page/layout/document shell helpers pass one cache through
-   * `integrationContext` so repeated delegation to the same foreign integration
-   * can reuse a single initialized renderer instance during one render flow.
-   * The cache is deliberately scoped to the current render execution rather than
-   * stored on the renderer, which avoids leaking mutable integration state across
-   * requests while still preventing redundant renderer initialization.
-   *
-   * @param integrationContext - Optional render context carried with one render input.
-   * @returns The current execution cache when present.
-   */
-  getOwningRendererCache(integrationContext) {
-    if (integrationContext?.rendererCache instanceof Map) {
-      return integrationContext.rendererCache;
-    }
-    return void 0;
-  }
-  getForeignOwnerIntegrationName(component) {
-    const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
-    if (!integrationName || integrationName === this.name) {
-      return void 0;
-    }
-    return this.appConfig.integrations.some((integration) => integration.name === integrationName) ? integrationName : void 0;
-  }
-  /**
-   * Attaches an execution-scoped owning-renderer cache to one render input.
-   *
-   * Foreign-owned page, layout, or document shells may delegate several times in
-   * the same render flow. Threading the cache through `integrationContext`
-   * preserves renderer reuse without changing the public render input contract.
-   * Existing integration-specific context is preserved and augmented.
-   *
-   * @param input - Original render input.
-   * @param rendererCache - Execution-scoped renderer cache to propagate.
-   * @returns Render input augmented with the shared renderer cache.
-   */
-  withOwningRendererCache(input, rendererCache) {
-    const integrationContext = input.integrationContext;
-    const sharedRendererCache = rendererCache;
-    return {
-      ...input,
-      integrationContext: integrationContext ? { ...integrationContext, rendererCache: sharedRendererCache } : { rendererCache: sharedRendererCache }
-    };
-  }
   getRendererModuleValue(key) {
     if (!this.rendererModules || typeof this.rendererModules !== "object") {
       return void 0;
@@ -184,10 +158,11 @@ class IntegrationRenderer {
     return await this.routeRenderOrchestrator.resolveDeclaredPageBrowserGraph({
       routeFile: filePath,
       integrationName: this.name,
-      collectContribution: async (routeFile) => {
-        const pageModule = await this.importPageFile(routeFile);
-        return await this.collectPageBrowserGraphContribution({ file: routeFile, pageModule });
-      }
+      collectContribution: (routeFile) => loadPageBrowserGraphContribution(
+        routeFile,
+        (targetFile) => this.importPageFile(targetFile),
+        (context) => this.collectPageBrowserGraphContribution(context)
+      )
     });
   }
   mergePageBrowserGraphIntoPagePackage(pageBrowserGraph) {
@@ -313,19 +288,25 @@ class IntegrationRenderer {
     await this.prepareViewDependencies(input.view, input.layout);
     const HtmlTemplate = await this.getHtmlTemplate();
     const metadata = await this.resolveViewMetadata(input.view, input.props);
-    const { documentHtml } = await this.composeDocumentShell({
-      primaryComponent: input.view,
-      primaryProps: normalizedProps,
-      layout: input.layout ? {
-        component: input.layout,
-        props: {}
-      } : void 0,
-      htmlTemplate: HtmlTemplate,
-      documentProps: {
-        metadata,
-        pageProps: normalizedProps
+    const { documentHtml } = await composeDocumentShell(
+      {
+        renderComponentWithForeignChildren: (renderInput) => this.renderComponentWithForeignChildren(renderInput),
+        appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups)
+      },
+      {
+        primaryComponent: input.view,
+        primaryProps: normalizedProps,
+        layout: input.layout ? {
+          component: input.layout,
+          props: {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
+        documentProps: {
+          metadata,
+          pageProps: normalizedProps
+        }
       }
-    });
+    );
     const html = await this.finalizeResolvedHtml({
       html: `${this.DOC_TYPE}${documentHtml}`,
       partial: false
@@ -345,59 +326,17 @@ class IntegrationRenderer {
    * @returns Final serialized document HTML including the doctype prefix.
    */
   async renderPageWithDocumentShell(input) {
-    const { documentHtml: composedDocumentHtml } = await this.composeDocumentShell({
-      primaryComponent: input.page.component,
-      primaryProps: input.page.props,
-      layout: input.layout,
-      htmlTemplate: input.htmlTemplate,
-      documentProps: {
-        metadata: input.metadata,
-        pageProps: input.pageProps,
-        ...input.documentProps ?? {}
-      }
-    });
-    const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(composedDocumentHtml) : composedDocumentHtml;
-    return `${this.DOC_TYPE}${documentHtml}`;
-  }
-  async composeDocumentShell(input) {
-    const rendererCache = /* @__PURE__ */ new Map();
-    const primaryRender = await this.renderComponentWithForeignChildren({
-      component: input.primaryComponent,
-      props: input.primaryProps,
-      integrationContext: { rendererCache }
-    });
-    const layoutRender = input.layout ? await this.renderComponentWithForeignChildren({
-      component: input.layout.component,
-      props: input.layout.props ?? {},
-      children: primaryRender.html,
-      integrationContext: { rendererCache }
-    }) : void 0;
-    const documentRender = await this.renderComponentWithForeignChildren({
-      component: input.htmlTemplate,
-      props: input.documentProps,
-      children: layoutRender?.html ?? primaryRender.html,
-      integrationContext: { rendererCache }
-    });
-    this.appendProcessedDependencies(primaryRender.assets, layoutRender?.assets, documentRender.assets);
-    return {
-      documentHtml: documentRender.html
-    };
+    return renderPageDocumentShell(
+      {
+        renderComponentWithForeignChildren: (renderInput) => this.renderComponentWithForeignChildren(renderInput),
+        appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups)
+      },
+      input,
+      this.DOC_TYPE
+    );
   }
-  /**
-   * Renders one string-first component with serialized children and collects its assets.
-   *
-   * String-oriented integrations frequently share the same component contract:
-   * pass serialized children through props, coerce the render result to HTML, and
-   * attach any component-scoped dependencies. This helper centralizes that flow
-   * so integrations can opt into shared orchestration without repeating the same
-   * string-render boilerplate.
-   *
-   * @param input - Component render input.
-   * @param component - String-oriented component implementation to execute.
-   * @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);
@@ -438,6 +377,18 @@ class IntegrationRenderer {
       this.getForeignSubtreeResolutionContextKey()
     );
   }
+  async resolveQueuedForeignSubtreeHtml(html, runtimeContext, renderQueuedChildren, queueLabel = this.name) {
+    return this.foreignSubtreeExecutionService.resolveQueuedHtml({
+      currentIntegrationName: this.name,
+      html,
+      runtimeContext,
+      queueLabel,
+      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
+      applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+      renderQueuedChildren
+    });
+  }
   /**
    * Renders a string-first component, then resolves any queued foreign
    * boundaries before returning final component HTML.
@@ -533,7 +484,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
@@ -622,19 +573,20 @@ class IntegrationRenderer {
    * subclasses continue to override protected renderer behavior directly.
    */
   createRouteRenderOrchestratorAdapter() {
-    return {
+    return createIntegrationRouteRenderAdapter({
       name: this.name,
       resolveRouteRenderInputs: (routeOptions) => this.resolveRouteRenderInputs(routeOptions),
       resolveRouteDependencies: (input) => this.resolveRouteDependencies(input),
-      collectPageBrowserGraphContribution: async (routeFile) => {
-        const pageModule = await this.importPageFile(routeFile);
-        return await this.collectPageBrowserGraphContribution({ file: routeFile, pageModule });
-      },
+      importPageFile: (file) => this.importPageFile(file),
+      collectPageBrowserGraphContribution: (context) => this.collectPageBrowserGraphContribution(context),
       resolveRoutePageComponentRender: (input) => this.resolveRoutePageComponentRender(input),
       renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
-      getRouteHtmlFinalization: (renderOptions) => this.getRouteHtmlFinalization(renderOptions),
-      transformRouteResponse: (response, htmlContributions) => this.transformRouteResponse(response, htmlContributions)
-    };
+      getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
+      getHtmlDocumentContributions: (options) => this.getHtmlDocumentContributions(options),
+      applyAttributesToFirstBodyElement: (html, attributes) => this.applyAttributesToFirstBodyElement(html, attributes),
+      applyAttributesToHtmlElement: (html, attributes) => this.applyAttributesToHtmlElement(html, attributes),
+      transformRouteResponse: (response, htmlContributions, pagePackage) => this.transformRouteResponse(response, htmlContributions, pagePackage)
+    });
   }
   async resolveRouteRenderInputs(routeOptions) {
     const pageModule = await this.pageModuleLoaderService.resolvePageModule({
@@ -643,7 +595,8 @@ class IntegrationRenderer {
     });
     const { Page, integrationSpecificProps } = pageModule;
     const HtmlTemplate = await this.getHtmlTemplate();
-    const Layout = Page.config?.layout;
+    const Layouts = resolvePageLayoutComponents(Page.config?.layouts);
+    const Layout = resolveInnermostPageLayout(Layouts);
     const { props, metadata } = await this.pageModuleLoaderService.resolvePageData({
       pageModule,
       routeOptions
@@ -651,7 +604,9 @@ class IntegrationRenderer {
     return {
       Page,
       HtmlTemplate,
+      Layouts,
       Layout,
+      layoutEntries: Page.config?.layoutEntries,
       props,
       metadata,
       integrationSpecificProps
@@ -681,33 +636,13 @@ class IntegrationRenderer {
   async renderRouteBody(renderOptions) {
     return this.render(renderOptions);
   }
-  getRouteHtmlFinalization(renderOptions) {
-    const componentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0 ? renderOptions.componentRender.rootAttributes : void 0;
-    const documentAttributes = this.getDocumentAttributes(renderOptions);
-    const htmlContributions = this.getHtmlDocumentContributions({ renderOptions, partial: false });
-    const hasStructuralFinalization = componentRootAttributes && Object.keys(componentRootAttributes).length > 0 || documentAttributes && Object.keys(documentAttributes).length > 0;
-    if (!hasStructuralFinalization && (!htmlContributions || htmlContributions.length === 0)) {
-      return {};
-    }
-    return {
+  async transformRouteResponse(response, htmlContributions, pagePackage) {
+    const resolvedPagePackage = this.htmlTransformer.getPagePackage() ?? pagePackage;
+    const transformedResponse = await this.htmlTransformer.transform(
+      response,
       htmlContributions,
-      finalizeHtml: (html) => {
-        let renderedHtml = html;
-        if (componentRootAttributes) {
-          renderedHtml = this.htmlTransformer.applyAttributesToFirstBodyElement(
-            renderedHtml,
-            componentRootAttributes
-          );
-        }
-        if (documentAttributes) {
-          renderedHtml = this.htmlTransformer.applyAttributesToHtmlElement(renderedHtml, documentAttributes);
-        }
-        return renderedHtml;
-      }
-    };
-  }
-  async transformRouteResponse(response, htmlContributions) {
-    const transformedResponse = await this.htmlTransformer.transform(response, htmlContributions);
+      resolvedPagePackage
+    );
     return transformedResponse.body ?? await transformedResponse.text();
   }
   /**
@@ -752,9 +687,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.
@@ -766,13 +704,17 @@ class IntegrationRenderer {
   async finalizeResolvedHtml(options) {
     const rendererBootstrapDependencies = this.getRendererBootstrapDependencies(options.partial);
     this.appendProcessedDependencies(rendererBootstrapDependencies);
-    let html = options.html;
-    if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
-      html = this.htmlTransformer.applyAttributesToFirstBodyElement(html, options.componentRootAttributes);
-    }
-    if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
-      html = this.htmlTransformer.applyAttributesToHtmlElement(html, options.documentAttributes);
-    }
+    let html = applyDocumentShellAttributeStamping(
+      options.html,
+      {
+        applyAttributesToFirstBodyElement: (nextHtml, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(nextHtml, attributes),
+        applyAttributesToHtmlElement: (nextHtml, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(nextHtml, attributes)
+      },
+      {
+        componentRootAttributes: options.componentRootAttributes,
+        documentAttributes: options.documentAttributes
+      }
+    );
     const shouldTransform = options.transformHtml ?? !options.partial;
     if (!shouldTransform) {
       return html;
@@ -797,6 +739,12 @@ class IntegrationRenderer {
   getDocumentAttributes(_renderOptions) {
     return void 0;
   }
+  applyAttributesToFirstBodyElement(html, attributes) {
+    return this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes);
+  }
+  applyAttributesToHtmlElement(html, attributes) {
+    return this.htmlTransformer.applyAttributesToHtmlElement(html, attributes);
+  }
   /**
    * Returns declarative HTML fragments that core should inject into the final document.
    *
@@ -859,22 +807,6 @@ class IntegrationRenderer {
       getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache)
     });
   }
-  /**
-   * Compatibility foreign-subtree contract that exposes a narrower payload shape for
-   * future route-composition work while preserving the current
-   * `renderComponentWithForeignChildren()` runtime semantics.
-   */
-  async renderForeignSubtree(input) {
-    const result = await this.renderComponentWithForeignChildren(input);
-    return {
-      html: result.html,
-      assets: result.assets ?? [],
-      rootTag: result.rootTag,
-      rootAttributes: result.rootAttributes,
-      attachmentPolicy: result.canAttachAttributes ? { kind: "first-element" } : { kind: "none" },
-      integrationName: result.integrationName
-    };
-  }
   normalizeComponentRenderOutput(result) {
     const normalizedHtml = this.normalizeUnresolvedMarkerArtifactHtml(result.html);
     return normalizedHtml === result.html ? result : {
@@ -893,21 +825,7 @@ class IntegrationRenderer {
    * directly without paying the queue orchestration cost.
    */
   hasForeignChildDescendants(component) {
-    const stack = [component];
-    const seen = /* @__PURE__ */ new Set();
-    while (stack.length > 0) {
-      const current = stack.pop();
-      if (!current || seen.has(current)) {
-        continue;
-      }
-      seen.add(current);
-      const integrationName = current.config?.integration ?? current.config?.__eco?.integration;
-      if (integrationName && integrationName !== this.name) {
-        return true;
-      }
-      stack.push(...current.config?.dependencies?.components ?? []);
-    }
-    return false;
+    return hasForeignChildDescendantsInGraph(component, this.name);
   }
   /**
    * Render a single component and return structured output for orchestration paths.

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

@@ -0,0 +1,38 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
+import type { ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PagePackageResult, RouteRendererBody, RouteRendererOptions } from '../../types/public-types.js';
+import type { RouteHtmlFinalization, RouteRenderOrchestratorAdapter, RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
+/**
+ * Host surface required to build the orchestrator adapter for one integration renderer.
+ */
+export type IntegrationRouteRenderAdapterHost<C> = {
+    readonly name: string;
+    resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    resolveRouteDependencies(input: {
+        components: (EcoComponent | Partial<EcoComponent>)[];
+    }): Promise<{
+        resolvedDependencies: ProcessedAsset[];
+    }>;
+    importPageFile(file: string): Promise<EcoPageFile>;
+    collectPageBrowserGraphContribution(context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
+    resolveRoutePageComponentRender(input: {
+        Page: EcoComponent;
+        Layout?: EcoComponent;
+        props: Record<string, unknown>;
+        routeOptions: RouteRendererOptions;
+    }): Promise<ComponentRenderResult | undefined>;
+    renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    getHtmlDocumentContributions(options: {
+        renderOptions: IntegrationRendererRenderOptions<C>;
+        partial: boolean;
+    }): HtmlDocumentContribution[] | undefined;
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
+};
+/**
+ * Builds the internal route-render adapter consumed by `RouteRenderOrchestrator`.
+ */
+export declare function createIntegrationRouteRenderAdapter<C>(host: IntegrationRouteRenderAdapterHost<C>): RouteRenderOrchestratorAdapter<C>;
+export type { RouteHtmlFinalization };

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

@@ -0,0 +1,27 @@
+import { loadPageBrowserGraphContribution } from "./page-browser-graph-contribution.loader.js";
+import { buildRouteHtmlFinalization } from "./route-html-finalization.service.js";
+function createIntegrationRouteRenderAdapter(host) {
+  return {
+    name: host.name,
+    resolveRouteRenderInputs: (routeOptions) => host.resolveRouteRenderInputs(routeOptions),
+    resolveRouteDependencies: (input) => host.resolveRouteDependencies(input),
+    collectPageBrowserGraphContribution: (routeFile) => loadPageBrowserGraphContribution(
+      routeFile,
+      (file) => host.importPageFile(file),
+      (context) => host.collectPageBrowserGraphContribution(context)
+    ),
+    resolveRoutePageComponentRender: (input) => host.resolveRoutePageComponentRender(input),
+    renderRouteBody: (renderOptions) => host.renderRouteBody(renderOptions),
+    getRouteHtmlFinalization: (renderOptions) => buildRouteHtmlFinalization({
+      renderOptions,
+      getDocumentAttributes: (options) => host.getDocumentAttributes(options),
+      getHtmlDocumentContributions: (options) => host.getHtmlDocumentContributions(options),
+      applyAttributesToFirstBodyElement: (html, attributes) => host.applyAttributesToFirstBodyElement(html, attributes),
+      applyAttributesToHtmlElement: (html, attributes) => host.applyAttributesToHtmlElement(html, attributes)
+    }),
+    transformRouteResponse: (response, htmlContributions, pagePackage) => host.transformRouteResponse(response, htmlContributions, pagePackage)
+  };
+}
+export {
+  createIntegrationRouteRenderAdapter
+};