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

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

@@ -4,16 +4,16 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-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 { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, EcoPagesElement, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, 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 { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
-import type { ForeignChildRuntime } from './component-render-context.js';
-import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer, type ForeignSubtreeQueuedHtmlOptions, type QueuedForeignSubtreeResolutionContext } from './foreign-subtree-execution.service.js';
+import { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-pipeline/route-render-orchestrator.js';
+import type { ForeignChildRuntime } from './foreign-child/component-render-context.js';
+import { ForeignSubtreeExecutionService } from './foreign-child/foreign-subtree-execution.service.js';
 /**
  * Controls how one route module is loaded outside the normal render path.
  *
@@ -67,6 +67,14 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     private renderExclusiveChain;
     protected DOC_TYPE: string;
     private runRenderExclusive;
+    /**
+     * Activates the owning integration runtime on first render or graph use.
+     */
+    protected ensureIntegrationRuntimeActivated(): Promise<void>;
+    /**
+     * Prebuilds the production Page Browser Graph for one route file.
+     */
+    prebuildProductionPageBrowserGraph(routeFile: string): Promise<void>;
     /**
      * Loads one route module through the owning renderer's import path.
      *
@@ -110,7 +118,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
     protected resolvePageBrowserGraphForFile(filePath: string): Promise<PageBrowserGraphResult | undefined>;
-    protected mergePageBrowserGraphIntoPagePackage(pageBrowserGraph?: PageBrowserGraphResult): PageBrowserGraphResult | undefined;
     /**
      * Merges component-scoped assets into the active HTML transformer state.
      *
@@ -170,6 +177,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         props: P;
         ctx: RenderToResponseContext;
         layout?: EcoComponent;
+        transformDocumentHtml?: (html: string) => string;
     }): Promise<Response>;
     /**
      * Renders a route page through optional layout and document shells.
@@ -199,20 +207,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         transformDocumentHtml?: (html: string) => string;
     }): Promise<string>;
     protected renderStringComponentWithSerializedChildren(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
-    protected getForeignSubtreeTokenPrefix(): string;
-    protected getForeignSubtreeResolutionContextKey(): string;
-    protected createQueuedForeignSubtreeExecutionRuntime<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
-        renderInput: ComponentRenderInput;
-        rendererCache: Map<string, IntegrationRenderer<any>>;
-        runtimeContextKey?: string;
-        tokenPrefix?: string;
-        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.
@@ -225,16 +219,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         rendererModules?: unknown;
         runtimeOrigin: string;
     });
-    /**
-     * Returns the HTML path from the provided file path.
-     * It extracts the path relative to the pages directory and removes the 'index' part if present.
-     *
-     * @param file - The file path to extract the HTML path from.
-     * @returns The extracted HTML path.
-     */
-    protected getHtmlPath({ file }: {
-        file: string;
-    }): string;
     /**
      * Returns the HTML template component.
      * It imports the HTML template from the specified path in the app configuration.
@@ -262,27 +246,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns The resolved dependency path.
      */
     protected resolveDependencyPath(componentDir: string, pathUrl: string): string;
-    /**
-     * Extracts the dependencies from the provided component configuration.
-     * It resolves the paths for scripts and stylesheets based on the component directory.
-     *
-     * @param componentDir - The component directory path.
-     * @param scripts - The scripts to extract.
-     * @param stylesheets - The stylesheets to extract.
-     * @returns The extracted dependencies.
-     */
-    protected extractDependencies({ componentDir, scripts, stylesheets, }: {
-        componentDir: string;
-    } & EcoComponentDependencies): EcoComponentDependencies;
-    /**
-     * Resolves lazy script paths to public asset URLs.
-     * Converts source paths to their final bundled output paths.
-     *
-     * @param componentDir - The component directory path.
-     * @param scripts - The lazy script paths to resolve.
-     * @returns Comma-separated string of resolved public script paths.
-     */
-    protected resolveLazyScripts(componentDir: string, scripts: string[]): string;
     /**
      * Collects the dependencies for the provided components.
      * Combines component-specific dependencies with global integration dependencies.
@@ -312,14 +275,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     }): Promise<{
         resolvedDependencies: ProcessedAsset[];
     }>;
-    protected resolveRoutePageComponentRender(input: {
-        Page: EcoComponent;
-        Layout?: EcoComponent;
-        props: Record<string, unknown>;
-        routeOptions: RouteRendererOptions;
-    }): Promise<ComponentRenderResult | undefined>;
     protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): 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.
@@ -328,19 +284,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns The prepared render options.
      */
     protected prepareRenderOptions(options: RouteRendererOptions, adapter?: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
-    /**
-     * Controls whether the page root should be rendered through `renderComponent()`
-     * during route option preparation in component-capable modes.
-     *
-     * Integrations that already own page-level hydration (for example router-driven
-     * React rendering) can override this and return `false` to avoid duplicate root
-     * mount assets and competing hydration entrypoints.
-     */
-    protected shouldRenderPageComponent(_input: {
-        Page: EcoComponent;
-        Layout?: EcoComponent;
-        options: RouteRendererOptions;
-    }): boolean;
     /**
      * Executes the integration renderer with the provided options.
      *
@@ -348,7 +291,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * 1. Build normalized render options (`prepareRenderOptions`).
      * 2. Render the route body once.
      * 3. Reject unresolved route-level eco-marker artifacts.
-     * 4. Optionally apply root attributes for page/component root boundaries.
+     * 4. Optionally apply document attributes for integration-owned document boundaries.
      * 5. Run HTML transformer with final dependency set.
      *
      * Stream-safety note: the first render result is normalized to a string once,
@@ -359,21 +302,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns Rendered route body plus effective cache strategy.
      */
     execute(options: RouteRendererOptions): Promise<RouteRenderResult>;
-    /**
-     * Finalizes already-resolved HTML for explicit renderer-owned paths.
-     *
-     * This keeps document and root-attribute stamping plus HTML transformation
-     * available after a renderer has completed nested foreign-subtree resolution without
-     * routing back through shared route execution.
-     */
-    protected finalizeResolvedHtml(options: {
-        html: string;
-        partial?: boolean;
-        componentRootAttributes?: Record<string, string>;
-        documentAttributes?: Record<string, string>;
-        transformHtml?: boolean;
-        htmlContributions?: HtmlDocumentContribution[];
-    }): Promise<string>;
     /**
      * Returns document-level attributes to stamp onto the rendered `<html>` tag.
      *
@@ -393,17 +321,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * response finalization logic.
      */
     protected getHtmlDocumentContributions(_options: HtmlDocumentContributionContext<C>): HtmlDocumentContribution[] | undefined;
-    /**
-     * Returns a renderer instance for a given integration name.
-     *
-     * Uses a per-execution cache to avoid repeated renderer initialization.
-     *
-     * @param integrationName Target integration name.
-     * @param cache Render-pass renderer cache.
-     * @returns Renderer for the requested integration.
-     * @throws Error when no integration plugin matches `integrationName`.
-     */
-    protected getIntegrationRendererForName(integrationName: string, cache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
     /**
      * Abstract method to render the integration-specific component.
      * This method should be implemented by the specific integration renderer.

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

@@ -6,24 +6,31 @@ import { invariant } from "../../utils/invariant.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 { OwnershipValidationService } from "./ownership-validation.service.js";
-import { hasForeignChildDescendantsInGraph } from "./component-graph-collectors.js";
+import { OwnershipValidationService } from "./ownership-graph/ownership-validation.service.js";
+import { hasForeignChildDescendantsInGraph } from "./ownership-graph/component-graph-collectors.js";
 import {
   RouteRenderOrchestrator
-} from "./route-render-orchestrator.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";
+} from "./route-pipeline/route-render-orchestrator.js";
+import { createIntegrationRouteRenderAdapter } from "./route-pipeline/integration-route-render-adapter.js";
+import { loadPageBrowserGraphContribution } from "./page-browser-graph/page-browser-graph-contribution.loader.js";
+import { normalizeUnresolvedMarkerArtifactHtml } from "./route-pipeline/marker-artifact.utils.js";
+import { isMarkupNodeLike } from "./foreign-child/foreign-child-output.utils.js";
 import {
-  ForeignSubtreeExecutionService
-} from "./foreign-subtree-execution.service.js";
-import { buildProcessedAssetDedupeKey } from "./processed-asset-dedupe.js";
+  getForeignSubtreeResolutionContextKey,
+  getForeignSubtreeTokenPrefix,
+  resolveOwningIntegrationRenderer
+} from "./foreign-child/owning-renderer-resolution.js";
+import { ensureIntegrationRuntimeReady } from "../../build/app-build-manifest-runtime.js";
+import { ForeignSubtreeExecutionService } from "./foreign-child/foreign-subtree-execution.service.js";
 import {
-  applyDocumentShellAttributeStamping,
   composeDocumentShell,
+  finalizeDocumentShellHtml,
   renderPageDocumentShell
-} from "./document-shell-render.service.js";
-import { resolveInnermostPageLayout, resolvePageLayoutComponents } from "./layout-shell-props.service.js";
+} from "./document-shell/document-shell-render.service.js";
+import {
+  resolveInnermostPageLayout,
+  resolvePageLayoutComponents
+} from "./document-shell/layout-shell-props.service.js";
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -45,13 +52,33 @@ class IntegrationRenderer {
   renderExclusiveChain = Promise.resolve();
   DOC_TYPE = "<!DOCTYPE html>";
   runRenderExclusive(operation) {
-    const run = this.renderExclusiveChain.then(operation, operation);
+    const run = this.renderExclusiveChain.then(async () => {
+      await this.ensureIntegrationRuntimeActivated();
+      return operation();
+    });
     this.renderExclusiveChain = run.then(
       () => void 0,
       () => void 0
     );
     return run;
   }
+  /**
+   * Activates the owning integration runtime on first render or graph use.
+   */
+  async ensureIntegrationRuntimeActivated() {
+    await ensureIntegrationRuntimeReady({
+      appConfig: this.appConfig,
+      integrationName: this.name,
+      runtimeOrigin: this.runtimeOrigin
+    });
+  }
+  /**
+   * Prebuilds the production Page Browser Graph for one route file.
+   */
+  async prebuildProductionPageBrowserGraph(routeFile) {
+    await this.ensureIntegrationRuntimeActivated();
+    await this.resolvePageBrowserGraphForFile(routeFile);
+  }
   /**
    * Loads one route module through the owning renderer's import path.
    *
@@ -165,36 +192,6 @@ class IntegrationRenderer {
       )
     });
   }
-  mergePageBrowserGraphIntoPagePackage(pageBrowserGraph) {
-    if (!pageBrowserGraph) {
-      return void 0;
-    }
-    const currentPagePackage = this.htmlTransformer.getPagePackage();
-    const mergedPageBrowserGraph = currentPagePackage?.pageBrowserGraph ? {
-      entryAssets: this.htmlTransformer.dedupeProcessedAssets([
-        ...currentPagePackage.pageBrowserGraph.entryAssets,
-        ...pageBrowserGraph.entryAssets
-      ]),
-      chunkAssets: this.htmlTransformer.dedupeProcessedAssets([
-        ...currentPagePackage.pageBrowserGraph.chunkAssets,
-        ...pageBrowserGraph.chunkAssets
-      ])
-    } : pageBrowserGraph;
-    const pageBrowserGraphAssetKeys = new Set(
-      [...mergedPageBrowserGraph.entryAssets, ...mergedPageBrowserGraph.chunkAssets].map(
-        (asset) => buildProcessedAssetDedupeKey(asset)
-      )
-    );
-    const baseAssets = currentPagePackage ? currentPagePackage.assets.filter(
-      (asset) => !pageBrowserGraphAssetKeys.has(buildProcessedAssetDedupeKey(asset))
-    ) : this.htmlTransformer.getProcessedDependencies();
-    this.htmlTransformer.setPagePackage(
-      createPagePackage(this.htmlTransformer.dedupeProcessedAssets(baseAssets), {
-        pageBrowserGraph: mergedPageBrowserGraph
-      })
-    );
-    return mergedPageBrowserGraph;
-  }
   /**
    * Merges component-scoped assets into the active HTML transformer state.
    *
@@ -281,9 +278,13 @@ class IntegrationRenderer {
    * @returns HTML response for the explicit view render.
    */
   async renderViewWithDocumentShell(input) {
+    await this.ensureIntegrationRuntimeActivated();
     const normalizedProps = input.props ?? {};
     if (input.ctx.partial) {
-      return this.renderPartialViewResponse(input);
+      return this.renderPartialViewResponse({
+        ...input,
+        transformHtml: input.transformDocumentHtml
+      });
     }
     await this.prepareViewDependencies(input.view, input.layout);
     const HtmlTemplate = await this.getHtmlTemplate();
@@ -307,9 +308,12 @@ class IntegrationRenderer {
         }
       }
     );
-    const html = await this.finalizeResolvedHtml({
-      html: `${this.DOC_TYPE}${documentHtml}`,
-      partial: false
+    const transformedDocumentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(documentHtml) : documentHtml;
+    this.appendProcessedDependencies(this.getRendererBootstrapDependencies(false));
+    const html = await finalizeDocumentShellHtml(this.htmlTransformer, {
+      html: `${this.DOC_TYPE}${transformedDocumentHtml}`,
+      partial: false,
+      htmlContributions: this.getHtmlDocumentContributions({ partial: false })
     });
     return this.createHtmlResponse(html, input.ctx);
   }
@@ -346,7 +350,14 @@ class IntegrationRenderer {
     }
     const props = serializedChildren === void 0 ? input.props : { ...input.props, children: serializedChildren };
     const content = await component(props);
-    const html = String(content);
+    if (typeof content !== "string") {
+      const componentFile = input.component.config?.__eco?.file ?? "unknown component";
+      const contentTag = Object.prototype.toString.call(content);
+      throw new TypeError(
+        `[ecopages] ${this.name} renderer expected a string render result for ${componentFile}, received ${contentTag}.`
+      );
+    }
+    const html = content;
     const assets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : void 0;
     return {
       html,
@@ -356,39 +367,6 @@ class IntegrationRenderer {
       assets
     };
   }
-  getForeignSubtreeTokenPrefix() {
-    return `__${this.name}_foreign_subtree__`;
-  }
-  getForeignSubtreeResolutionContextKey() {
-    return `__${this.name}_foreign_subtree_runtime__`;
-  }
-  createQueuedForeignSubtreeExecutionRuntime(options) {
-    return this.foreignSubtreeExecutionService.createQueuedRuntime({
-      renderInput: options.renderInput,
-      rendererCache: options.rendererCache,
-      runtimeContextKey: options.runtimeContextKey ?? this.getForeignSubtreeResolutionContextKey(),
-      tokenPrefix: options.tokenPrefix ?? this.getForeignSubtreeTokenPrefix(),
-      createRuntimeContext: options.createRuntimeContext
-    });
-  }
-  getQueuedForeignSubtreeResolutionContext(input) {
-    return this.foreignSubtreeExecutionService.getQueuedRuntimeContext(
-      input,
-      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.
@@ -399,9 +377,16 @@ class IntegrationRenderer {
       currentIntegrationName: this.name,
       renderInput: input,
       html: componentRender.html,
-      runtimeContextKey: this.getForeignSubtreeResolutionContextKey(),
+      runtimeContextKey: getForeignSubtreeResolutionContextKey(this.name),
       queueLabel: "String",
-      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
+      getOwningRenderer: (integrationName, rendererCache) => resolveOwningIntegrationRenderer({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        currentIntegrationName: this.name,
+        currentRenderer: this,
+        integrationName,
+        cache: rendererCache
+      }),
       applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes),
       dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets)
     });
@@ -435,23 +420,6 @@ class IntegrationRenderer {
       ownershipValidationService: new OwnershipValidationService(appConfig)
     });
   }
-  /**
-   * Returns the HTML path from the provided file path.
-   * It extracts the path relative to the pages directory and removes the 'index' part if present.
-   *
-   * @param file - The file path to extract the HTML path from.
-   * @returns The extracted HTML path.
-   */
-  getHtmlPath({ file }) {
-    const pagesDir = this.appConfig.absolutePaths.pagesDir;
-    const pagesIndex = file.indexOf(pagesDir);
-    if (pagesIndex === -1) return file;
-    const startIndex = file.indexOf(pagesDir) + pagesDir.length;
-    const endIndex = file.lastIndexOf("/");
-    const path = file.substring(startIndex, endIndex);
-    if (path === "/index") return "";
-    return path;
-  }
   /**
    * Returns the HTML template component.
    * It imports the HTML template from the specified path in the app configuration.
@@ -505,46 +473,6 @@ class IntegrationRenderer {
   resolveDependencyPath(componentDir, pathUrl) {
     return this.dependencyResolverService.resolveDependencyPath(componentDir, pathUrl);
   }
-  /**
-   * Extracts the dependencies from the provided component configuration.
-   * It resolves the paths for scripts and stylesheets based on the component directory.
-   *
-   * @param componentDir - The component directory path.
-   * @param scripts - The scripts to extract.
-   * @param stylesheets - The stylesheets to extract.
-   * @returns The extracted dependencies.
-   */
-  extractDependencies({
-    componentDir,
-    scripts,
-    stylesheets
-  }) {
-    const scriptsPaths = [
-      ...new Set(
-        (scripts ?? []).filter((script) => typeof script === "string" ? true : !script.lazy).map((script) => typeof script === "string" ? script : script.src).filter((script) => Boolean(script)).map((script) => this.resolveDependencyPath(componentDir, script))
-      )
-    ];
-    const stylesheetsPaths = [
-      ...new Set(
-        (stylesheets ?? []).map((style) => typeof style === "string" ? style : style.src).filter((style) => Boolean(style)).map((style) => this.resolveDependencyPath(componentDir, style))
-      )
-    ];
-    return {
-      scripts: scriptsPaths,
-      stylesheets: stylesheetsPaths
-    };
-  }
-  /**
-   * Resolves lazy script paths to public asset URLs.
-   * Converts source paths to their final bundled output paths.
-   *
-   * @param componentDir - The component directory path.
-   * @param scripts - The lazy script paths to resolve.
-   * @returns Comma-separated string of resolved public script paths.
-   */
-  resolveLazyScripts(componentDir, scripts) {
-    return this.dependencyResolverService.resolveLazyScripts(componentDir, scripts);
-  }
   /**
    * Collects the dependencies for the provided components.
    * Combines component-specific dependencies with global integration dependencies.
@@ -579,13 +507,19 @@ class IntegrationRenderer {
       resolveRouteDependencies: (input) => this.resolveRouteDependencies(input),
       importPageFile: (file) => this.importPageFile(file),
       collectPageBrowserGraphContribution: (context) => this.collectPageBrowserGraphContribution(context),
-      resolveRoutePageComponentRender: (input) => this.resolveRoutePageComponentRender(input),
       renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
       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)
+      transformRouteResponse: async (response, htmlContributions, pagePackage) => {
+        const resolvedPagePackage = this.htmlTransformer.getPagePackage() ?? pagePackage;
+        const transformedResponse = await this.htmlTransformer.transform(
+          response,
+          htmlContributions,
+          resolvedPagePackage
+        );
+        return transformedResponse.body ?? await transformedResponse.text();
+      }
     });
   }
   async resolveRouteRenderInputs(routeOptions) {
@@ -617,34 +551,9 @@ class IntegrationRenderer {
       resolvedDependencies: await this.resolveDependencies(input.components)
     };
   }
-  async resolveRoutePageComponentRender(input) {
-    if (!this.shouldRenderPageComponent({ Page: input.Page, Layout: input.Layout, options: input.routeOptions })) {
-      return void 0;
-    }
-    return this.renderComponentWithForeignChildren({
-      component: input.Page,
-      props: {
-        ...input.props,
-        params: input.routeOptions.params || {},
-        query: input.routeOptions.query || {}
-      },
-      integrationContext: {
-        componentInstanceId: "eco-page-root"
-      }
-    });
-  }
   async renderRouteBody(renderOptions) {
     return this.render(renderOptions);
   }
-  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();
-  }
   /**
    * Prepares the render options for the integration renderer.
    * It imports the page file, collects dependencies, and prepares the render options.
@@ -658,17 +567,6 @@ class IntegrationRenderer {
     this.htmlTransformer.setPagePackage(renderOptions.pagePackage);
     return renderOptions;
   }
-  /**
-   * Controls whether the page root should be rendered through `renderComponent()`
-   * during route option preparation in component-capable modes.
-   *
-   * Integrations that already own page-level hydration (for example router-driven
-   * React rendering) can override this and return `false` to avoid duplicate root
-   * mount assets and competing hydration entrypoints.
-   */
-  shouldRenderPageComponent(_input) {
-    return true;
-  }
   /**
    * Executes the integration renderer with the provided options.
    *
@@ -676,7 +574,7 @@ class IntegrationRenderer {
    * 1. Build normalized render options (`prepareRenderOptions`).
    * 2. Render the route body once.
    * 3. Reject unresolved route-level eco-marker artifacts.
-   * 4. Optionally apply root attributes for page/component root boundaries.
+   * 4. Optionally apply document attributes for integration-owned document boundaries.
    * 5. Run HTML transformer with final dependency set.
    *
    * Stream-safety note: the first render result is normalized to a string once,
@@ -694,42 +592,6 @@ class IntegrationRenderer {
       return this.routeRenderOrchestrator.executePrepared(renderOptions, adapter);
     });
   }
-  /**
-   * Finalizes already-resolved HTML for explicit renderer-owned paths.
-   *
-   * This keeps document and root-attribute stamping plus HTML transformation
-   * available after a renderer has completed nested foreign-subtree resolution without
-   * routing back through shared route execution.
-   */
-  async finalizeResolvedHtml(options) {
-    const rendererBootstrapDependencies = this.getRendererBootstrapDependencies(options.partial);
-    this.appendProcessedDependencies(rendererBootstrapDependencies);
-    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;
-    }
-    const htmlContributions = options.htmlContributions ?? this.getHtmlDocumentContributions({
-      partial: options.partial
-    });
-    const transformedResponse = await this.htmlTransformer.transform(
-      new Response(html, {
-        headers: { "Content-Type": "text/html" }
-      }),
-      htmlContributions
-    );
-    return await transformedResponse.text();
-  }
   /**
    * Returns document-level attributes to stamp onto the rendered `<html>` tag.
    *
@@ -757,34 +619,6 @@ class IntegrationRenderer {
   getHtmlDocumentContributions(_options) {
     return void 0;
   }
-  /**
-   * Returns a renderer instance for a given integration name.
-   *
-   * Uses a per-execution cache to avoid repeated renderer initialization.
-   *
-   * @param integrationName Target integration name.
-   * @param cache Render-pass renderer cache.
-   * @returns Renderer for the requested integration.
-   * @throws Error when no integration plugin matches `integrationName`.
-   */
-  getIntegrationRendererForName(integrationName, cache) {
-    if (cache.has(integrationName)) {
-      return cache.get(integrationName);
-    }
-    if (integrationName === this.name) {
-      cache.set(integrationName, this);
-      return this;
-    }
-    const integrationPlugin = this.appConfig.integrations.find(
-      (integration) => integration.name === integrationName
-    );
-    invariant(!!integrationPlugin, `[ecopages] Integration not found for foreign owner: ${integrationName}`);
-    const renderer = integrationPlugin.initializeRenderer({
-      rendererModules: this.appConfig.runtime?.rendererModuleContext
-    });
-    cache.set(integrationName, renderer);
-    return renderer;
-  }
   /**
    * Renders one component under this integration's foreign-child runtime and resolves
    * any nested foreign children captured during that render.
@@ -804,7 +638,14 @@ class IntegrationRenderer {
         renderInput,
         rendererCache
       }),
-      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache)
+      getOwningRenderer: (integrationName, rendererCache) => resolveOwningIntegrationRenderer({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        currentIntegrationName: this.name,
+        currentRenderer: this,
+        integrationName,
+        cache: rendererCache
+      })
     });
   }
   normalizeComponentRenderOutput(result) {
@@ -891,9 +732,11 @@ class IntegrationRenderer {
    * context or a different foreign-child execution strategy.
    */
   createForeignChildRuntime(options) {
-    return this.createQueuedForeignSubtreeExecutionRuntime({
+    return this.foreignSubtreeExecutionService.createQueuedRuntime({
       renderInput: options.renderInput,
-      rendererCache: options.rendererCache
+      rendererCache: options.rendererCache,
+      runtimeContextKey: getForeignSubtreeResolutionContextKey(this.name),
+      tokenPrefix: getForeignSubtreeTokenPrefix(this.name)
     });
   }
   /**