npm - @ecopages/core - Versions diffs - 0.2.0-alpha.26 → 0.2.0-alpha.28 - Mend

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

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 (106) hide show

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

@@ -1,19 +1,20 @@
 import {
+  createPagePackage
 } from "../../services/assets/asset-processing-service/index.js";
 import { HtmlTransformerService } from "../../services/html/html-transformer.service.js";
 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 { PagePackagingService } from "./page-packaging.service.js";
-import { RenderExecutionService } from "./render-execution.service.js";
-import { RenderPreparationService } from "./render-preparation.service.js";
-import { RouteShellComposer } from "./route-shell-composer.service.js";
-import { normalizeBoundaryArtifactHtml } from "./render-output.utils.js";
-import { getComponentRenderContext, runWithComponentRenderContext } from "./component-render-context.js";
+import { OwnershipValidationService } from "./ownership-validation.service.js";
 import {
-  QueuedBoundaryRuntimeService
-} from "./queued-boundary-runtime.service.js";
+  RouteRenderOrchestrator
+} from "./route-render-orchestrator.js";
+import { normalizeUnresolvedMarkerArtifactHtml } from "./render-output.utils.js";
+import {
+  ForeignSubtreeExecutionService
+} from "./foreign-subtree-execution.service.js";
+import {} from "./queued-foreign-subtree-resolution.service.js";
 class IntegrationRenderer {
   appConfig;
   assetProcessingService;
@@ -24,11 +25,8 @@ class IntegrationRenderer {
   runtimeOrigin;
   dependencyResolverService;
   pageModuleLoaderService;
-  renderPreparationService;
-  renderExecutionService;
-  pagePackagingService;
-  routeShellComposer = new RouteShellComposer();
-  queuedBoundaryRuntimeService = new QueuedBoundaryRuntimeService();
+  routeRenderOrchestrator;
+  foreignSubtreeExecutionService = new ForeignSubtreeExecutionService();
   DOC_TYPE = "<!DOCTYPE html>";
   /**
    * Loads one route module through the owning renderer's import path.
@@ -42,7 +40,7 @@ class IntegrationRenderer {
     return this.importPageFile(file, options);
   }
   /**
-   * Reads the execution-scoped foreign renderer cache from one boundary input.
+   * 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
@@ -51,16 +49,16 @@ class IntegrationRenderer {
    * stored on the renderer, which avoids leaking mutable integration state across
    * requests while still preventing redundant renderer initialization.
    *
-   * @param integrationContext - Optional boundary context carried with one render input.
+   * @param integrationContext - Optional render context carried with one render input.
    * @returns The current execution cache when present.
    */
-  getBoundaryRendererCache(integrationContext) {
+  getOwningRendererCache(integrationContext) {
     if (integrationContext?.rendererCache instanceof Map) {
       return integrationContext.rendererCache;
     }
     return void 0;
   }
-  getRegisteredBoundaryOwner(component) {
+  getForeignOwnerIntegrationName(component) {
     const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
     if (!integrationName || integrationName === this.name) {
       return void 0;
@@ -68,18 +66,18 @@ class IntegrationRenderer {
     return this.appConfig.integrations.some((integration) => integration.name === integrationName) ? integrationName : void 0;
   }
   /**
-   * Attaches an execution-scoped foreign renderer cache to one boundary input.
+   * 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 boundary input contract.
+   * preserves renderer reuse without changing the public render input contract.
    * Existing integration-specific context is preserved and augmented.
    *
-   * @param input - Original boundary render input.
+   * @param input - Original render input.
    * @param rendererCache - Execution-scoped renderer cache to propagate.
-   * @returns Boundary input augmented with the shared renderer cache.
+   * @returns Render input augmented with the shared renderer cache.
    */
-  withBoundaryRendererCache(input, rendererCache) {
+  withOwningRendererCache(input, rendererCache) {
     const integrationContext = input.integrationContext;
     const sharedRendererCache = rendererCache;
     return {
@@ -175,14 +173,14 @@ class IntegrationRenderer {
     const resolvedDependencies = this.htmlTransformer.dedupeProcessedAssets(
       await this.resolveDependencies(componentsToResolve)
     );
-    this.htmlTransformer.setPagePackage(this.pagePackagingService.createPagePackage(resolvedDependencies));
+    this.htmlTransformer.setPagePackage(createPagePackage(resolvedDependencies));
     return resolvedDependencies;
   }
   /**
    * Merges component-scoped assets into the active HTML transformer state.
    *
    * Explicit page, layout, and document shell composition can produce assets at
-   * each boundary. This helper deduplicates those groups and folds them back into
+   * each foreign subtree. This helper deduplicates those groups and folds them back into
    * the transformer so downstream HTML finalization sees one canonical asset set.
    *
    * @param assetGroups - Optional groups of processed assets to merge.
@@ -199,7 +197,7 @@ class IntegrationRenderer {
       ...this.htmlTransformer.getProcessedDependencies(),
       ...nextDependencies
     ]);
-    this.htmlTransformer.setPagePackage(this.pagePackagingService.createPagePackage(mergedDependencies));
+    this.htmlTransformer.setPagePackage(createPagePackage(mergedDependencies));
     return nextDependencies;
   }
   /**
@@ -226,7 +224,7 @@ class IntegrationRenderer {
    *
    * Same-integration views can optionally stream or render inline via the caller's
    * `renderInline()` hook. Once a view may cross integration boundaries, this
-   * helper routes the render through `renderComponentBoundary()` instead so mixed
+   * helper routes the render through `renderComponentWithForeignChildren()` instead so mixed
    * shells can reuse the execution-scoped renderer cache and resolve nested
    * foreign ownership before the partial response is returned.
    *
@@ -234,17 +232,17 @@ class IntegrationRenderer {
    * @returns HTML response for the partial render.
    */
   async renderPartialViewResponse(input) {
-    return this.routeShellComposer.renderPartialViewResponse(input, {
-      hasForeignBoundaryDescendants: (component) => this.hasForeignBoundaryDescendants(component),
-      createHtmlResponse: (body, ctx) => this.createHtmlResponse(body, ctx),
-      renderComponentBoundary: (boundaryInput) => this.renderComponentBoundary(boundaryInput),
-      prepareViewDependencies: (view, layout) => this.prepareViewDependencies(view, layout),
-      getHtmlTemplate: () => this.getHtmlTemplate(),
-      resolveViewMetadata: (view, props) => this.resolveViewMetadata(view, props),
-      appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
-      finalizeResolvedHtml: (options) => this.finalizeResolvedHtml(options),
-      docType: this.DOC_TYPE
+    if (input.renderInline && !this.hasForeignChildDescendants(input.view)) {
+      return this.createHtmlResponse(await input.renderInline(), input.ctx);
+    }
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await this.renderComponentWithForeignChildren({
+      component: input.view,
+      props: input.props ?? {},
+      integrationContext: { rendererCache }
     });
+    const html = input.transformHtml ? input.transformHtml(viewRender.html) : viewRender.html;
+    return this.createHtmlResponse(html, input.ctx);
   }
   /**
    * Renders an explicit view through optional layout and document shells.
@@ -259,57 +257,97 @@ class IntegrationRenderer {
    * @returns HTML response for the explicit view render.
    */
   async renderViewWithDocumentShell(input) {
-    return this.routeShellComposer.renderViewWithDocumentShell(input, {
-      hasForeignBoundaryDescendants: (component) => this.hasForeignBoundaryDescendants(component),
-      createHtmlResponse: (body, ctx) => this.createHtmlResponse(body, ctx),
-      renderComponentBoundary: (boundaryInput) => this.renderComponentBoundary(boundaryInput),
-      prepareViewDependencies: (view, layout) => this.prepareViewDependencies(view, layout),
-      getHtmlTemplate: () => this.getHtmlTemplate(),
-      resolveViewMetadata: (view, props) => this.resolveViewMetadata(view, props),
-      appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
-      finalizeResolvedHtml: (options) => this.finalizeResolvedHtml(options),
-      docType: this.DOC_TYPE
+    const normalizedProps = input.props ?? {};
+    if (input.ctx.partial) {
+      return this.renderPartialViewResponse(input);
+    }
+    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 html = await this.finalizeResolvedHtml({
+      html: `${this.DOC_TYPE}${documentHtml}`,
+      partial: false
     });
+    return this.createHtmlResponse(html, input.ctx);
   }
   /**
    * Renders a route page through optional layout and document shells.
    *
-   * Route rendering and explicit view rendering now share the same boundary-owned
+   * Route rendering and explicit view rendering now share the same renderer-owned
    * shell composition model. This helper composes page, layout, and html template
-   * boundaries while threading one execution-scoped renderer cache through every
-   * delegated boundary so foreign shell ownership remains stable and renderer
+   * renders while threading one execution-scoped renderer cache through every
+   * delegated foreign subtree so foreign shell ownership remains stable and renderer
    * initialization is reused inside the current request.
    *
    * @param input - Page, layout, document, and metadata inputs for the route render.
    * @returns Final serialized document HTML including the doctype prefix.
    */
   async renderPageWithDocumentShell(input) {
-    return this.routeShellComposer.renderPageWithDocumentShell(input, {
-      hasForeignBoundaryDescendants: (component) => this.hasForeignBoundaryDescendants(component),
-      createHtmlResponse: (body, ctx) => this.createHtmlResponse(body, ctx),
-      renderComponentBoundary: (boundaryInput) => this.renderComponentBoundary(boundaryInput),
-      prepareViewDependencies: (view, layout) => this.prepareViewDependencies(view, layout),
-      getHtmlTemplate: () => this.getHtmlTemplate(),
-      resolveViewMetadata: (view, props) => this.resolveViewMetadata(view, props),
-      appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
-      finalizeResolvedHtml: (options) => this.finalizeResolvedHtml(options),
-      docType: this.DOC_TYPE
+    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
+    };
   }
   /**
-   * Renders one string-first component boundary and collects its assets.
+   * Renders one string-first component with serialized children and collects its assets.
    *
-   * String-oriented integrations frequently share the same boundary contract:
+   * 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
-   * boundary boilerplate.
+   * string-render boilerplate.
    *
-   * @param input - Boundary render input.
+   * @param input - Component render input.
    * @param component - String-oriented component implementation to execute.
    * @returns Structured component render result for orchestration paths.
    */
-  async renderStringComponentBoundary(input, component) {
+  async renderStringComponentWithSerializedChildren(input, component) {
     const props = input.children === void 0 ? input.props : { ...input.props, children: input.children };
     const content = await component(props);
     const html = String(content);
@@ -322,79 +360,51 @@ class IntegrationRenderer {
       assets
     };
   }
-  getBoundaryTokenPrefix() {
-    return `__${this.name}_boundary__`;
+  getForeignSubtreeTokenPrefix() {
+    return `__${this.name}_foreign_subtree__`;
   }
-  getBoundaryRuntimeContextKey() {
-    return `__${this.name}_boundary_runtime__`;
+  getForeignSubtreeResolutionContextKey() {
+    return `__${this.name}_foreign_subtree_runtime__`;
   }
-  getQueuedBoundaryRuntime(input, runtimeContextKey = this.getBoundaryRuntimeContextKey()) {
-    return this.queuedBoundaryRuntimeService.getRuntimeContext(input, runtimeContextKey);
-  }
-  async resolveQueuedBoundaryTokens(html, queuedResolutionsByToken, resolveToken) {
-    let resolvedHtml = html;
-    for (const token of queuedResolutionsByToken.keys()) {
-      if (!resolvedHtml.includes(token)) {
-        continue;
-      }
-      resolvedHtml = resolvedHtml.split(token).join(await resolveToken(token));
-    }
-    return resolvedHtml;
-  }
-  createQueuedBoundaryRuntime(options) {
-    return this.queuedBoundaryRuntimeService.createRuntime({
-      boundaryInput: options.boundaryInput,
+  createQueuedForeignSubtreeExecutionRuntime(options) {
+    return this.foreignSubtreeExecutionService.createQueuedRuntime({
+      renderInput: options.renderInput,
       rendererCache: options.rendererCache,
-      runtimeContextKey: options.runtimeContextKey ?? this.getBoundaryRuntimeContextKey(),
-      tokenPrefix: options.tokenPrefix ?? this.getBoundaryTokenPrefix(),
-      shouldQueueBoundary: (input) => this.shouldResolveBoundaryInOwningRenderer(input),
+      runtimeContextKey: options.runtimeContextKey ?? this.getForeignSubtreeResolutionContextKey(),
+      tokenPrefix: options.tokenPrefix ?? this.getForeignSubtreeTokenPrefix(),
       createRuntimeContext: options.createRuntimeContext
     });
   }
-  async resolveRendererOwnedQueuedBoundaryHtml(options) {
-    return this.queuedBoundaryRuntimeService.resolveQueuedHtml({
-      html: options.html,
-      runtimeContext: options.runtimeContext,
-      queueLabel: options.queueLabel,
-      renderQueuedChildren: options.renderQueuedChildren,
-      resolveBoundary: (input, rendererCache) => this.resolveBoundaryPayloadInOwningRenderer(
-        input,
-        rendererCache
-      ),
-      applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes),
-      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets)
-    });
+  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.
    */
-  async renderStringComponentBoundaryWithQueuedForeignBoundaries(input, component) {
-    const componentRender = await this.renderStringComponentBoundary(input, component);
-    const queuedBoundaryResolution = await this.resolveRendererOwnedQueuedBoundaryHtml({
+  async renderStringComponentWithQueuedForeignSubtrees(input, component) {
+    const componentRender = await this.renderStringComponentWithSerializedChildren(input, component);
+    const queuedForeignSubtreeResolution = await this.foreignSubtreeExecutionService.resolveStringQueuedHtml({
+      currentIntegrationName: this.name,
+      renderInput: input,
       html: componentRender.html,
-      runtimeContext: this.getQueuedBoundaryRuntime(input),
+      runtimeContextKey: this.getForeignSubtreeResolutionContextKey(),
       queueLabel: "String",
-      renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => {
-        if (children === void 0) {
-          return { assets: [], html: void 0 };
-        }
-        const html = await this.resolveQueuedBoundaryTokens(
-          typeof children === "string" ? children : String(children ?? ""),
-          queuedResolutionsByToken,
-          resolveToken
-        );
-        return { assets: [], html };
-      }
+      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
+      applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets)
     });
     const mergedAssets = this.htmlTransformer.dedupeProcessedAssets([
       ...componentRender.assets ?? [],
-      ...queuedBoundaryResolution.assets
+      ...queuedForeignSubtreeResolution.assets
     ]);
     return {
       ...componentRender,
-      html: queuedBoundaryResolution.html,
-      rootTag: this.getRootTagName(queuedBoundaryResolution.html),
+      html: queuedForeignSubtreeResolution.html,
+      rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
       assets: mergedAssets.length > 0 ? mergedAssets : void 0
     };
   }
@@ -408,16 +418,14 @@ class IntegrationRenderer {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
     this.htmlTransformer = new HtmlTransformerService();
-    this.pagePackagingService = new PagePackagingService();
     this.resolvedIntegrationDependencies = resolvedIntegrationDependencies || [];
     this.rendererModules = rendererModules ?? appConfig.runtime?.rendererModuleContext;
     this.runtimeOrigin = runtimeOrigin;
     this.dependencyResolverService = new DependencyResolverService(appConfig, assetProcessingService);
     this.pageModuleLoaderService = new PageModuleLoaderService(appConfig, runtimeOrigin);
-    this.renderPreparationService = new RenderPreparationService(appConfig, assetProcessingService, {
-      pagePackagingService: this.pagePackagingService
+    this.routeRenderOrchestrator = new RouteRenderOrchestrator(appConfig, assetProcessingService, {
+      ownershipValidationService: new OwnershipValidationService(appConfig)
     });
-    this.renderExecutionService = new RenderExecutionService();
   }
   /**
    * Returns the HTML path from the provided file path.
@@ -451,34 +459,6 @@ class IntegrationRenderer {
       invariant(false, `Error importing HtmlTemplate: ${error}`);
     }
   }
-  /**
-   * Returns the static props for the page.
-   * It calls the provided getStaticProps function with the given options.
-   *
-   * @param getStaticProps - The function to get static props.
-   * @param options - The options to pass to the getStaticProps function.
-   * @returns The static props and metadata.
-   */
-  async getStaticProps(getStaticProps, options) {
-    return this.pageModuleLoaderService.getStaticPropsForPage({
-      getStaticProps,
-      params: options?.params
-    });
-  }
-  /**
-   * Returns the metadata properties for the page.
-   * It calls the provided getMetadata function with the given context.
-   *
-   * @param getMetadata - The function to get metadata.
-   * @param context - The context to pass to the getMetadata function.
-   * @returns The metadata properties.
-   */
-  async getMetadataProps(getMetadata, { props, params, query }) {
-    return this.pageModuleLoaderService.getMetadataPropsForPage({
-      getMetadata,
-      context: { props, params, query }
-    });
-  }
   usesIntegrationPageImporter(_file) {
     return false;
   }
@@ -576,6 +556,98 @@ class IntegrationRenderer {
   async processComponentDependencies(components) {
     return this.dependencyResolverService.processComponentDependencies(components, this.name);
   }
+  /**
+   * Builds the internal route-render adapter consumed by `RouteRenderOrchestrator`.
+   *
+   * The route orchestrator needs a narrow orchestration contract, but those hooks should
+   * not become public API on the renderer base class. Keeping the adapter object
+   * local to the execution path lets the orchestrator depend on one explicit seam while
+   * subclasses continue to override protected renderer behavior directly.
+   */
+  createRouteRenderOrchestratorAdapter() {
+    return {
+      name: this.name,
+      resolveRouteRenderInputs: (routeOptions) => this.resolveRouteRenderInputs(routeOptions),
+      resolveRouteAssets: (input) => this.resolveRouteAssets(input),
+      resolveRoutePageComponentRender: (input) => this.resolveRoutePageComponentRender(input),
+      renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
+      getRouteHtmlFinalization: (renderOptions) => this.getRouteHtmlFinalization(renderOptions),
+      transformRouteResponse: (response) => this.transformRouteResponse(response)
+    };
+  }
+  async resolveRouteRenderInputs(routeOptions) {
+    const pageModule = await this.pageModuleLoaderService.resolvePageModule({
+      file: routeOptions.file,
+      importPageFileFn: (targetFile) => this.importPageFile(targetFile)
+    });
+    const { Page, integrationSpecificProps } = pageModule;
+    const HtmlTemplate = await this.getHtmlTemplate();
+    const Layout = Page.config?.layout;
+    const { props, metadata } = await this.pageModuleLoaderService.resolvePageData({
+      pageModule,
+      routeOptions
+    });
+    return {
+      Page,
+      HtmlTemplate,
+      Layout,
+      props,
+      metadata,
+      integrationSpecificProps
+    };
+  }
+  async resolveRouteAssets(input) {
+    return {
+      resolvedDependencies: await this.resolveDependencies(input.components),
+      pageBrowserGraph: await this.buildPageBrowserGraph(input.routeOptions.file)
+    };
+  }
+  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 hasStructuralFinalization = componentRootAttributes && Object.keys(componentRootAttributes).length > 0 || documentAttributes && Object.keys(documentAttributes).length > 0;
+    if (!hasStructuralFinalization) {
+      return {};
+    }
+    return {
+      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) {
+    const transformedResponse = await this.htmlTransformer.transform(response);
+    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.
@@ -583,25 +655,11 @@ class IntegrationRenderer {
    * @param options - The route renderer options.
    * @returns The prepared render options.
    */
-  async prepareRenderOptions(options) {
-    const preparedOptions = await this.renderPreparationService.prepare(options, this.name, {
-      resolvePageModule: (file) => this.resolvePageModule(file),
-      getHtmlTemplate: () => this.getHtmlTemplate(),
-      resolvePageData: (pageModule, routeOptions) => this.resolvePageData(pageModule, routeOptions),
-      resolveDependencies: (components) => this.resolveDependencies(components),
-      buildRouteRenderAssets: (file) => this.buildRouteRenderAssets(file),
-      shouldRenderPageComponent: (input) => this.shouldRenderPageComponent(input),
-      renderPageComponent: ({ component, props }) => this.renderComponentBoundary({
-        component,
-        props,
-        integrationContext: {
-          componentInstanceId: "eco-page-root"
-        }
-      })
-    });
-    invariant(preparedOptions.pagePackage !== void 0, "Expected render preparation to produce a page package");
-    this.htmlTransformer.setPagePackage(preparedOptions.pagePackage);
-    return preparedOptions;
+  async prepareRenderOptions(options, adapter = this.createRouteRenderOrchestratorAdapter()) {
+    const renderOptions = await this.routeRenderOrchestrator.prepareRenderOptions(options, adapter);
+    invariant(renderOptions.pagePackage !== void 0, "Expected render preparation to produce a page package");
+    this.htmlTransformer.setPagePackage(renderOptions.pagePackage);
+    return renderOptions;
   }
   /**
    * Controls whether the page root should be rendered through `renderComponent()`
@@ -614,31 +672,13 @@ class IntegrationRenderer {
   shouldRenderPageComponent(_input) {
     return true;
   }
-  /**
-   * Resolves the page module and normalizes exports.
-   */
-  async resolvePageModule(file) {
-    return this.pageModuleLoaderService.resolvePageModule({
-      file,
-      importPageFileFn: (targetFile) => this.importPageFile(targetFile)
-    });
-  }
-  /**
-   * Resolves static props and metadata for the page.
-   */
-  async resolvePageData(pageModule, options) {
-    return this.pageModuleLoaderService.resolvePageData({
-      pageModule,
-      routeOptions: options
-    });
-  }
   /**
    * Executes the integration renderer with the provided options.
    *
    * Execution flow:
    * 1. Build normalized render options (`prepareRenderOptions`).
    * 2. Render the route body once.
-   * 3. Reject unresolved route-level boundary artifacts.
+   * 3. Reject unresolved route-level eco-marker artifacts.
    * 4. Optionally apply root attributes for page/component root boundaries.
    * 5. Run HTML transformer with final dependency set.
    *
@@ -650,23 +690,15 @@ class IntegrationRenderer {
    * @returns Rendered route body plus effective cache strategy.
    */
   async execute(options) {
-    return this.renderExecutionService.execute(options, {
-      prepareRenderOptions: (routeOptions) => this.prepareRenderOptions(routeOptions),
-      render: (renderOptions) => this.render(renderOptions),
-      getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
-      applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
-      applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes),
-      transformResponse: async (response) => {
-        const transformedResponse = await this.htmlTransformer.transform(response);
-        return transformedResponse.body ?? await transformedResponse.text();
-      }
-    });
+    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 boundary resolution without
+   * available after a renderer has completed nested foreign-subtree resolution without
    * routing back through shared route execution.
    */
   async finalizeResolvedHtml(options) {
@@ -720,82 +752,42 @@ class IntegrationRenderer {
     const integrationPlugin = this.appConfig.integrations.find(
       (integration) => integration.name === integrationName
     );
-    invariant(!!integrationPlugin, `[ecopages] Integration not found for boundary owner: ${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;
   }
-  async resolveBoundaryInOwningRenderer(input, rendererCache) {
-    const boundaryOwner = this.getRegisteredBoundaryOwner(input.component);
-    if (!boundaryOwner) {
-      return void 0;
-    }
-    const owningRenderer = this.getIntegrationRendererForName(boundaryOwner, rendererCache);
-    if (owningRenderer === this || owningRenderer.name === this.name) {
-      return void 0;
-    }
-    return await owningRenderer.renderComponentBoundary(this.withBoundaryRendererCache(input, rendererCache));
-  }
-  async resolveBoundaryPayloadInOwningRenderer(input, rendererCache) {
-    const boundaryOwner = this.getRegisteredBoundaryOwner(input.component);
-    if (!boundaryOwner) {
-      return void 0;
-    }
-    const owningRenderer = this.getIntegrationRendererForName(boundaryOwner, rendererCache);
-    if (owningRenderer === this || owningRenderer.name === this.name) {
-      return void 0;
-    }
-    return await owningRenderer.renderBoundary(this.withBoundaryRendererCache(input, rendererCache));
-  }
   /**
-   * Renders one component under this integration's boundary runtime and resolves
-   * any nested foreign boundaries captured during that render.
+   * Renders one component under this integration's foreign-child runtime and resolves
+   * any nested foreign children captured during that render.
    *
    * Without this wrapper, a component tree with foreign-owned descendants would
-   * render them with no active boundary runtime, which bypasses the owning
-   * renderer's nested-boundary handoff.
-   */
-  async renderComponentBoundary(input) {
-    const rendererCache = this.getBoundaryRendererCache(input.integrationContext) ?? /* @__PURE__ */ new Map();
-    const delegatedBoundaryRender = await this.resolveBoundaryInOwningRenderer(input, rendererCache);
-    if (delegatedBoundaryRender) {
-      return delegatedBoundaryRender;
-    }
-    const hasForeignBoundaries = this.hasForeignBoundaryDescendants(input.component);
-    const activeRenderContext = getComponentRenderContext();
-    if (!hasForeignBoundaries) {
-      if (!activeRenderContext || activeRenderContext.currentIntegration === this.name) {
-        return this.normalizeComponentBoundaryRender(await this.renderComponent(input));
-      }
-      const sameIntegrationExecution = await runWithComponentRenderContext(
-        {
-          currentIntegration: this.name
-        },
-        async () => this.renderComponent(input)
-      );
-      return this.normalizeComponentBoundaryRender(sameIntegrationExecution.value);
-    }
-    const execution = await runWithComponentRenderContext(
-      {
-        currentIntegration: this.name,
-        boundaryRuntime: this.createComponentBoundaryRuntime({
-          boundaryInput: input,
-          rendererCache
-        })
-      },
-      async () => this.renderComponent(input)
-    );
-    return this.normalizeComponentBoundaryRender(execution.value);
+   * render them with no active foreign-child runtime, which bypasses the owning
+   * renderer's nested foreign-child handoff.
+   */
+  async renderComponentWithForeignChildren(input) {
+    return await this.foreignSubtreeExecutionService.executeComponentRender({
+      currentIntegrationName: this.name,
+      input,
+      renderComponent: (renderInput) => this.renderComponent(renderInput),
+      normalizeComponentRenderOutput: (result) => this.normalizeComponentRenderOutput(result),
+      hasForeignChildDescendants: (component) => this.hasForeignChildDescendants(component),
+      createForeignChildRuntime: ({ renderInput, rendererCache }) => this.createForeignChildRuntime({
+        renderInput,
+        rendererCache
+      }),
+      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache)
+    });
   }
   /**
-   * Compatibility boundary contract that exposes a narrower payload shape for
+   * Compatibility foreign-subtree contract that exposes a narrower payload shape for
    * future route-composition work while preserving the current
-   * `renderComponentBoundary()` runtime semantics.
+   * `renderComponentWithForeignChildren()` runtime semantics.
    */
-  async renderBoundary(input) {
-    const result = await this.renderComponentBoundary(input);
+  async renderForeignSubtree(input) {
+    const result = await this.renderComponentWithForeignChildren(input);
     return {
       html: result.html,
       assets: result.assets ?? [],
@@ -805,24 +797,24 @@ class IntegrationRenderer {
       integrationName: result.integrationName
     };
   }
-  normalizeComponentBoundaryRender(result) {
-    const normalizedHtml = this.normalizeBoundaryArtifactHtml(result.html);
+  normalizeComponentRenderOutput(result) {
+    const normalizedHtml = this.normalizeUnresolvedMarkerArtifactHtml(result.html);
     return normalizedHtml === result.html ? result : {
       ...result,
       html: normalizedHtml
     };
   }
-  normalizeBoundaryArtifactHtml(html) {
-    return normalizeBoundaryArtifactHtml(html);
+  normalizeUnresolvedMarkerArtifactHtml(html) {
+    return normalizeUnresolvedMarkerArtifactHtml(html);
   }
   /**
    * Returns whether the component dependency tree crosses into another
    * integration.
    *
-   * This keeps boundary-runtime setup narrow: same-integration trees can render
+   * This keeps foreign-child runtime setup narrow: same-integration trees can render
    * directly without paying the queue orchestration cost.
    */
-  hasForeignBoundaryDescendants(component) {
+  hasForeignChildDescendants(component) {
     const stack = [component];
     const seen = /* @__PURE__ */ new Set();
     while (stack.length > 0) {
@@ -845,8 +837,8 @@ class IntegrationRenderer {
    * Default behavior delegates to `renderToResponse` in partial mode and wraps
    * the resulting HTML into the `ComponentRenderResult` contract.
    *
-   * In boundary resolution, this method is the integration-owned step that turns an
-   * already-resolved deferred boundary into concrete HTML, assets, and optional
+   * In foreign-subtree resolution, this method is the integration-owned step that turns an
+   * already-resolved deferred foreign subtree into concrete HTML, assets, and optional
    * root attributes.
    *
    * Integrations can override this for richer behavior (asset emission,
@@ -880,51 +872,36 @@ class IntegrationRenderer {
     return rootTag?.[1];
   }
   /**
-   * Method to build route render assets.
+   * Builds the Page Browser Graph owned by this integration for one Page.
    * This method can be optionally overridden by the specific integration renderer.
    *
    * @param file - The file path to build assets for.
-   * @returns The processed assets or undefined.
+   * @returns The structured Page Browser Graph or undefined.
    */
-  buildRouteRenderAssets(_file) {
+  async buildPageBrowserGraph(_file) {
     return void 0;
   }
   /**
-   * Creates the per-render boundary runtime adopted by the shared component
+   * Creates the per-render foreign-child runtime adopted by the shared component
    * render context.
    *
-   * Real mixed-integration renderers should override this and keep foreign
-   * boundary resolution inside their own renderer-owned queue. The base runtime
-   * fails fast when a renderer crosses into a foreign owner without providing its
-   * own handoff mechanism.
+   * The default runtime queues delegated foreign subtrees inside the owning
+   * renderer so string and markup renderers do not need to re-declare the same
+   * handoff boilerplate. Override only when a renderer needs custom runtime
+   * context or a different foreign-child execution strategy.
    */
-  createComponentBoundaryRuntime(_options) {
-    const decideBoundaryInterception = (input) => {
-      if (!this.shouldResolveBoundaryInOwningRenderer(input)) {
-        return { kind: "inline" };
-      }
-      throw new Error(
-        `[ecopages] ${this.name} renderer crossed into ${input.targetIntegration} without a renderer-owned boundary runtime. Override createComponentBoundaryRuntime() to resolve foreign boundaries inside the owning renderer.`
-      );
-    };
-    const runtime = {
-      interceptBoundary: decideBoundaryInterception,
-      interceptBoundarySync: decideBoundaryInterception
-    };
-    return runtime;
+  createForeignChildRuntime(options) {
+    return this.createQueuedForeignSubtreeExecutionRuntime({
+      renderInput: options.renderInput,
+      rendererCache: options.rendererCache
+    });
   }
   /**
-   * Resolves whether a boundary should leave the current render pass and be
-   * resolved by its owning renderer.
-   *
-   * Boundaries owned by the current integration always render inline. Foreign-
-   * owned boundaries must be handed off by a renderer-owned runtime.
-   *
-   * @param input Boundary metadata for the active render pass.
-   * @returns `true` when the boundary should leave the current pass; otherwise `false`.
+   * Creates an explicit fail-fast runtime for tests or renderers that do not
+   * support cross-integration foreign-child execution.
    */
-  shouldResolveBoundaryInOwningRenderer(input) {
-    return !!input.targetIntegration && input.targetIntegration !== input.currentIntegration;
+  createFailFastForeignChildRuntime() {
+    return this.foreignSubtreeExecutionService.createFailFastRuntime(this.name);
   }
 }
 export {