npm - @ecopages/core - Versions diffs - 0.2.0-beta.3 → 0.2.0-beta.31 - Mend

@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (433) hide show

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

@@ -6,19 +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 { 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 { normalizeUnresolvedMarkerArtifactHtml } 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 {} 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";
-}
+  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 {
+  composeDocumentShell,
+  finalizeDocumentShellHtml,
+  renderPageDocumentShell
+} from "./document-shell/document-shell-render.service.js";
+import {
+  resolveInnermostPageLayout,
+  resolvePageLayoutComponents
+} from "./document-shell/layout-shell-props.service.js";
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -31,63 +43,52 @@ class IntegrationRenderer {
   pageModuleLoaderService;
   routeRenderOrchestrator;
   foreignSubtreeExecutionService = new ForeignSubtreeExecutionService();
-  DOC_TYPE = "<!DOCTYPE html>";
   /**
-   * Loads one route module through the owning renderer's import path.
+   * Serializes route and view renders that mutate `htmlTransformer` state.
    *
-   * Request-time infrastructure may need page metadata such as cache strategy or
-   * middleware before full rendering starts. Exposing this narrow entrypoint lets
-   * those callers reuse integration-specific import setup instead of bypassing it
-   * with raw transpiler access.
+   * Integration renderers are cached per integration, so concurrent static builds
+   * and overlapping SSR requests must not share one transformer page package.
    */
-  async loadPageModule(file, options) {
-    return this.importPageFile(file, options);
+  renderExclusiveChain = Promise.resolve();
+  DOC_TYPE = "<!DOCTYPE html>";
+  runRenderExclusive(operation) {
+    const run = this.renderExclusiveChain.then(async () => {
+      await this.ensureIntegrationRuntimeActivated();
+      return operation();
+    });
+    this.renderExclusiveChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
   }
   /**
-   * 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.
+   * Activates the owning integration runtime on first render or graph use.
    */
-  getOwningRendererCache(integrationContext) {
-    if (integrationContext?.rendererCache instanceof Map) {
-      return integrationContext.rendererCache;
-    }
-    return void 0;
+  async ensureIntegrationRuntimeActivated() {
+    await ensureIntegrationRuntimeReady({
+      appConfig: this.appConfig,
+      integrationName: this.name,
+      runtimeOrigin: this.runtimeOrigin
+    });
   }
-  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;
+  /**
+   * Prebuilds the production Page Browser Graph for one route file.
+   */
+  async prebuildProductionPageBrowserGraph(routeFile) {
+    await this.ensureIntegrationRuntimeActivated();
+    await this.resolvePageBrowserGraphForFile(routeFile);
   }
   /**
-   * 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.
+   * Loads one route module through the owning renderer's import path.
    *
-   * @param input - Original render input.
-   * @param rendererCache - Execution-scoped renderer cache to propagate.
-   * @returns Render input augmented with the shared renderer cache.
+   * Request-time infrastructure may need page metadata such as cache strategy or
+   * middleware before full rendering starts. Exposing this narrow entrypoint lets
+   * those callers reuse integration-specific import setup instead of bypassing it
+   * with raw transpiler access.
    */
-  withOwningRendererCache(input, rendererCache) {
-    const integrationContext = input.integrationContext;
-    const sharedRendererCache = rendererCache;
-    return {
-      ...input,
-      integrationContext: integrationContext ? { ...integrationContext, rendererCache: sharedRendererCache } : { rendererCache: sharedRendererCache }
-    };
+  async loadPageModule(file, options) {
+    return this.importPageFile(file, options);
   }
   getRendererModuleValue(key) {
     if (!this.rendererModules || typeof this.rendererModules !== "object") {
@@ -184,41 +185,12 @@ 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 });
-      }
-    });
-  }
-  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)
+      collectContribution: (routeFile) => loadPageBrowserGraphContribution(
+        routeFile,
+        (targetFile) => this.importPageFile(targetFile),
+        (context) => this.collectPageBrowserGraphContribution(context)
       )
-    );
-    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.
@@ -306,29 +278,42 @@ 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();
     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
+    );
+    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);
   }
@@ -345,59 +330,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);
@@ -407,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,
@@ -417,27 +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()
-    );
-  }
   /**
    * Renders a string-first component, then resolves any queued foreign
    * boundaries before returning final component HTML.
@@ -448,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)
     });
@@ -484,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.
@@ -533,7 +452,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
@@ -554,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.
@@ -622,19 +501,26 @@ 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 });
-      },
-      resolveRoutePageComponentRender: (input) => this.resolveRoutePageComponentRender(input),
+      importPageFile: (file) => this.importPageFile(file),
+      collectPageBrowserGraphContribution: (context) => this.collectPageBrowserGraphContribution(context),
       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),
+      applyAttributesToHtmlElement: (html, attributes) => this.applyAttributesToHtmlElement(html, attributes),
+      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) {
     const pageModule = await this.pageModuleLoaderService.resolvePageModule({
@@ -643,7 +529,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 +538,9 @@ class IntegrationRenderer {
     return {
       Page,
       HtmlTemplate,
+      Layouts,
       Layout,
+      layoutEntries: Page.config?.layoutEntries,
       props,
       metadata,
       integrationSpecificProps
@@ -662,54 +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);
   }
-  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 {
-      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);
-    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.
@@ -723,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.
    *
@@ -741,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,
@@ -752,41 +585,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);
-  }
-  /**
-   * 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 = 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);
-    }
-    const shouldTransform = options.transformHtml ?? !options.partial;
-    if (!shouldTransform) {
-      return html;
-    }
-    const htmlContributions = options.htmlContributions ?? this.getHtmlDocumentContributions({
-      partial: options.partial
+    return this.runRenderExclusive(async () => {
+      this.htmlTransformer.setProcessedDependencies([]);
+      const adapter = this.createRouteRenderOrchestratorAdapter();
+      const renderOptions = await this.prepareRenderOptions(options, adapter);
+      return this.routeRenderOrchestrator.executePrepared(renderOptions, adapter);
     });
-    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.
@@ -797,6 +601,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.
    *
@@ -809,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.
@@ -856,25 +638,16 @@ 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
+      })
     });
   }
-  /**
-   * 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 +666,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.
@@ -973,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)
     });
   }
   /**