npm - @ecopages/core - Versions diffs - 0.2.0-alpha.8 → 0.2.1-beta.0 - Mend

@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

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

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

@@ -1,42 +1,23 @@
 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 { LocalsAccessError } from "../../errors/locals-access-error.js";
 import { DependencyResolverService } from "../page-loading/dependency-resolver.js";
 import { PageModuleLoaderService } from "../page-loading/page-module-loader.js";
-import { MarkerGraphResolver } from "../component-graph/marker-graph-resolver.js";
-import { RenderExecutionService } from "./render-execution.service.js";
-import { RenderPreparationService } from "./render-preparation.service.js";
-function createLocalsProxy(filePath) {
-  const errorMessage = `[ecopages] Request locals are only available during request-time rendering with cache: 'dynamic'. Page: ${filePath}. If you meant to use locals here, set cache: 'dynamic' and provide locals from route middleware/handlers.`;
-  return new Proxy(
-    {},
-    {
-      get: () => {
-        throw new LocalsAccessError(errorMessage);
-      },
-      set: () => {
-        throw new LocalsAccessError(errorMessage);
-      },
-      has: () => {
-        throw new LocalsAccessError(errorMessage);
-      },
-      ownKeys: () => {
-        throw new LocalsAccessError(errorMessage);
-      },
-      deleteProperty: () => {
-        throw new LocalsAccessError(errorMessage);
-      },
-      defineProperty: () => {
-        throw new LocalsAccessError(errorMessage);
-      },
-      getOwnPropertyDescriptor: () => {
-        throw new LocalsAccessError(errorMessage);
-      }
-    }
-  );
+import { OwnershipValidationService } from "./ownership-validation.service.js";
+import {
+  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";
+import { buildProcessedAssetDedupeKey } from "./processed-asset-dedupe.js";
+function isMarkupNodeLike(value) {
+  return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && "outerHTML" in value && typeof value.outerHTML === "string";
 }
 class IntegrationRenderer {
   appConfig;
@@ -44,13 +25,103 @@ class IntegrationRenderer {
   htmlTransformer;
   hmrManager;
   resolvedIntegrationDependencies = [];
+  rendererModules;
   runtimeOrigin;
   dependencyResolverService;
   pageModuleLoaderService;
-  markerGraphResolver;
-  renderPreparationService;
-  renderExecutionService;
+  routeRenderOrchestrator;
+  foreignSubtreeExecutionService = new ForeignSubtreeExecutionService();
   DOC_TYPE = "<!DOCTYPE html>";
+  /**
+   * Loads one route module through the owning renderer's import path.
+   *
+   * 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.
+   */
+  async loadPageModule(file, options) {
+    return this.importPageFile(file, options);
+  }
+  /**
+   * Reads the execution-scoped owning-renderer cache from one render input.
+   *
+   * Shared page/layout/document shell helpers pass one cache through
+   * `integrationContext` so repeated delegation to the same foreign integration
+   * can reuse a single initialized renderer instance during one render flow.
+   * The cache is deliberately scoped to the current render execution rather than
+   * stored on the renderer, which avoids leaking mutable integration state across
+   * requests while still preventing redundant renderer initialization.
+   *
+   * @param integrationContext - Optional render context carried with one render input.
+   * @returns The current execution cache when present.
+   */
+  getOwningRendererCache(integrationContext) {
+    if (integrationContext?.rendererCache instanceof Map) {
+      return integrationContext.rendererCache;
+    }
+    return void 0;
+  }
+  getForeignOwnerIntegrationName(component) {
+    const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
+    if (!integrationName || integrationName === this.name) {
+      return void 0;
+    }
+    return this.appConfig.integrations.some((integration) => integration.name === integrationName) ? integrationName : void 0;
+  }
+  /**
+   * Attaches an execution-scoped owning-renderer cache to one render input.
+   *
+   * Foreign-owned page, layout, or document shells may delegate several times in
+   * the same render flow. Threading the cache through `integrationContext`
+   * preserves renderer reuse without changing the public render input contract.
+   * Existing integration-specific context is preserved and augmented.
+   *
+   * @param input - Original render input.
+   * @param rendererCache - Execution-scoped renderer cache to propagate.
+   * @returns Render input augmented with the shared renderer cache.
+   */
+  withOwningRendererCache(input, rendererCache) {
+    const integrationContext = input.integrationContext;
+    const sharedRendererCache = rendererCache;
+    return {
+      ...input,
+      integrationContext: integrationContext ? { ...integrationContext, rendererCache: sharedRendererCache } : { rendererCache: sharedRendererCache }
+    };
+  }
+  getRendererModuleValue(key) {
+    if (!this.rendererModules || typeof this.rendererModules !== "object") {
+      return void 0;
+    }
+    return this.rendererModules[key];
+  }
+  getRendererModuleString(key) {
+    const value = this.getRendererModuleValue(key);
+    return typeof value === "string" && value.length > 0 ? value : void 0;
+  }
+  getRendererBootstrapDependencies(partial = false) {
+    if (partial) {
+      return [];
+    }
+    const islandClientModuleId = this.getRendererModuleString("islandClientModuleId");
+    if (!islandClientModuleId) {
+      return [];
+    }
+    return [
+      {
+        attributes: {
+          crossorigin: "anonymous",
+          "data-ecopages-runtime": "islands",
+          type: "module"
+        },
+        content: `import ${JSON.stringify(islandClientModuleId)};`,
+        inline: true,
+        kind: "script",
+        packageRole: "keep-separate",
+        position: "body"
+      }
+    ];
+  }
   setHmrManager(hmrManager) {
     this.hmrManager = hmrManager;
     if (this.assetProcessingService) {
@@ -106,25 +177,312 @@ class IntegrationRenderer {
     const resolvedDependencies = this.htmlTransformer.dedupeProcessedAssets(
       await this.resolveDependencies(componentsToResolve)
     );
-    this.htmlTransformer.setProcessedDependencies(resolvedDependencies);
+    this.htmlTransformer.setPagePackage(createPagePackage(resolvedDependencies));
     return resolvedDependencies;
   }
+  async resolvePageBrowserGraphForFile(filePath) {
+    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)
+      )
+    );
+    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.
+   *
+   * Explicit page, layout, and document shell composition can produce assets at
+   * 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.
+   * @returns The deduplicated asset subset contributed by this merge operation.
+   */
+  appendProcessedDependencies(...assetGroups) {
+    const nextDependencies = this.htmlTransformer.dedupeProcessedAssets(
+      assetGroups.flatMap((assets) => assets ?? [])
+    );
+    if (nextDependencies.length === 0) {
+      return nextDependencies;
+    }
+    const mergedDependencies = this.htmlTransformer.dedupeProcessedAssets([
+      ...this.htmlTransformer.getProcessedDependencies(),
+      ...nextDependencies
+    ]);
+    const currentPageBrowserGraph = this.htmlTransformer.getPagePackage()?.pageBrowserGraph;
+    this.htmlTransformer.setPagePackage(
+      createPagePackage(mergedDependencies, {
+        pageBrowserGraph: currentPageBrowserGraph
+      })
+    );
+    return nextDependencies;
+  }
+  /**
+   * Resolves metadata for explicit view rendering.
+   *
+   * When a view declares a `metadata()` function, that contract owns the final
+   * metadata for the explicit render. Otherwise the app-level default metadata is
+   * reused so explicit routes and page-module routes share the same fallback.
+   *
+   * @param view - View component being rendered.
+   * @param props - Props passed to the view.
+   * @returns Resolved metadata for the final document shell.
+   */
+  async resolveViewMetadata(view, props) {
+    return view.metadata ? await view.metadata({
+      params: {},
+      query: {},
+      props,
+      appConfig: this.appConfig
+    }) : this.appConfig.defaultMetadata;
+  }
+  /**
+   * Renders one explicit view response in partial mode.
+   *
+   * 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 `renderComponentWithForeignChildren()` instead so mixed
+   * shells can reuse the execution-scoped renderer cache and resolve nested
+   * foreign ownership before the partial response is returned.
+   *
+   * @param input - View render options for the partial response.
+   * @returns HTML response for the partial render.
+   */
+  async renderPartialViewResponse(input) {
+    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.
+   *
+   * This helper is the shared explicit-route path for string-oriented and mixed
+   * integrations. It prepares view dependencies, resolves metadata, and composes
+   * view, layout, and html template boundaries with one execution-scoped renderer
+   * cache so repeated foreign shell delegation can reuse initialized renderers
+   * during the same render flow.
+   *
+   * @param input - View, props, and optional layout metadata for the render.
+   * @returns HTML response for the explicit view render.
+   */
+  async renderViewWithDocumentShell(input) {
+    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 renderer-owned
+   * shell composition model. This helper composes page, layout, and html template
+   * 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) {
+    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 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;
+    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);
+      throw new TypeError(
+        `[ecopages] ${this.name} renderer expected serialized children for ${componentFile}, received ${childTag}.`
+      );
+    }
+    const props = serializedChildren === void 0 ? input.props : { ...input.props, children: serializedChildren };
+    const content = await component(props);
+    const html = String(content);
+    const assets = input.component.config?.dependencies && typeof this.assetProcessingService?.processDependencies === "function" ? await this.processComponentDependencies([input.component]) : void 0;
+    return {
+      html,
+      canAttachAttributes: true,
+      rootTag: this.getRootTagName(html),
+      integrationName: this.name,
+      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.
+   */
+  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,
+      runtimeContextKey: this.getForeignSubtreeResolutionContextKey(),
+      queueLabel: "String",
+      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 ?? [],
+      ...queuedForeignSubtreeResolution.assets
+    ]);
+    return {
+      ...componentRender,
+      html: queuedForeignSubtreeResolution.html,
+      rootTag: this.getRootTagName(queuedForeignSubtreeResolution.html),
+      assets: mergedAssets.length > 0 ? mergedAssets : void 0
+    };
+  }
   constructor({
     appConfig,
     assetProcessingService,
     resolvedIntegrationDependencies,
+    rendererModules,
     runtimeOrigin
   }) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
     this.htmlTransformer = new HtmlTransformerService();
     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.markerGraphResolver = new MarkerGraphResolver();
-    this.renderPreparationService = new RenderPreparationService(appConfig, assetProcessingService);
-    this.renderExecutionService = new RenderExecutionService();
+    this.routeRenderOrchestrator = new RouteRenderOrchestrator(appConfig, assetProcessingService, {
+      ownershipValidationService: new OwnershipValidationService(appConfig)
+    });
   }
   /**
    * Returns the HTML path from the provided file path.
@@ -150,41 +508,22 @@ class IntegrationRenderer {
    * @returns The HTML template component.
    */
   async getHtmlTemplate() {
-    const { absolutePaths } = this.appConfig;
+    const htmlTemplatePath = this.getRendererModuleString("htmlTemplateModulePath") ?? this.appConfig.absolutePaths.htmlTemplatePath;
     try {
-      const { default: HtmlTemplate } = await this.importPageFile(absolutePaths.htmlTemplatePath);
+      const { default: HtmlTemplate } = await this.importPageFile(htmlTemplatePath);
       return HtmlTemplate;
     } catch (error) {
       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
-    });
+  usesIntegrationPageImporter(_file) {
+    return false;
   }
-  /**
-   * 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 }
-    });
+  async importIntegrationPageFile(_file, _options) {
+    invariant(false, "Integration page importer must be implemented when enabled");
+  }
+  normalizeImportedPageFile(_file, pageModule) {
+    return pageModule;
   }
   /**
    * Imports the page file from the specified path.
@@ -193,8 +532,16 @@ class IntegrationRenderer {
    * @param file - The file path to import.
    * @returns The imported module.
    */
-  async importPageFile(file) {
-    return this.pageModuleLoaderService.importPageFile(file);
+  async importPageFile(file, options) {
+    const bypassCache = options?.bypassCache ?? (typeof Bun !== "undefined" && process.env.NODE_ENV === "development");
+    const pageModule = this.usesIntegrationPageImporter(file) ? await this.importIntegrationPageFile(file, {
+      bypassCache,
+      cacheScope: options?.cacheScope
+    }) : await this.pageModuleLoaderService.importPageFile(file, {
+      bypassCache,
+      cacheScope: options?.cacheScope
+    });
+    return this.normalizeImportedPageFile(file, pageModule);
   }
   /**
    * Resolves the dependency path based on the component directory.
@@ -266,6 +613,103 @@ 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),
+      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),
+      renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
+      getRouteHtmlFinalization: (renderOptions) => this.getRouteHtmlFinalization(renderOptions),
+      transformRouteResponse: (response, htmlContributions) => this.transformRouteResponse(response, htmlContributions)
+    };
+  }
+  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 resolveRouteDependencies(input) {
+    return {
+      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.
@@ -273,26 +717,11 @@ class IntegrationRenderer {
    * @param options - The route renderer options.
    * @returns The prepared render options.
    */
-  async prepareRenderOptions(options) {
-    return 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.renderComponent({
-        component,
-        props,
-        integrationContext: {
-          componentInstanceId: "eco-page-root"
-        }
-      }),
-      getComponentRenderBoundaryContext: () => this.getComponentRenderBoundaryContext(),
-      setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
-      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-      createPageLocalsProxy: (filePath) => createLocalsProxy(filePath)
-    });
+  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()`
@@ -305,34 +734,15 @@ 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 once inside component render context to capture marker graph refs.
-   * 3. Merge captured refs with optional explicit page-module graph context.
-   * 4. Resolve any `eco-marker` graph bottom-up and merge produced assets.
-   * 5. Optionally apply root attributes for page/component root boundaries.
-   * 6. Run HTML transformer with final dependency set.
+   * 2. Render the route body once.
+   * 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.
    *
    * Stream-safety note: the first render result is normalized to a string once,
    * then the pipeline continues with that immutable HTML value to avoid disturbed
@@ -342,84 +752,39 @@ class IntegrationRenderer {
    * @returns Rendered route body plus effective cache strategy.
    */
   async execute(options) {
-    return this.renderExecutionService.execute(options, this.name, {
-      prepareRenderOptions: (routeOptions) => this.prepareRenderOptions(routeOptions),
-      render: (renderOptions) => this.render(renderOptions),
-      getComponentRenderBoundaryContext: () => this.getComponentRenderBoundaryContext(),
-      resolveMarkerGraphHtml: (input) => this.resolveMarkerGraphHtml({
-        html: input.html,
-        componentsToResolve: input.componentsToResolve,
-        graphContext: input.graphContext
-      }),
-      getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
-      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-      getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
-      setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
-      applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
-      applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes),
-      transformHtml: async (html) => {
-        const response = await this.htmlTransformer.transform(
-          new Response(html, {
-            headers: {
-              "Content-Type": "text/html"
-            }
-          })
-        );
-        return response.body;
-      }
-    });
+    const adapter = this.createRouteRenderOrchestratorAdapter();
+    const renderOptions = await this.prepareRenderOptions(options, adapter);
+    return this.routeRenderOrchestrator.executePrepared(renderOptions, adapter);
   }
   /**
-   * Captures a render pass as immutable HTML along with the graph context needed
-   * for deferred marker resolution.
+   * Finalizes already-resolved HTML for explicit renderer-owned paths.
    *
-   * This is the shared entry point for direct `renderToResponse()` flows that
-   * need the same component graph capture semantics as route execution without
-   * going through `prepareRenderOptions()`.
-   */
-  async captureHtmlRender(render) {
-    return this.renderExecutionService.captureHtmlRender(
-      this.name,
-      this.getComponentRenderBoundaryContext(),
-      render
-    );
-  }
-  /**
-   * Finalizes previously captured HTML by resolving deferred markers, merging
-   * any emitted assets, stamping optional attributes, and optionally running the
-   * HTML transformer for full-document flows.
+   * 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 finalizeCapturedHtmlRender(options) {
-    const finalization = await this.renderExecutionService.finalizeHtmlRender(
-      {
-        html: options.html,
-        graphContext: options.graphContext,
-        componentsToResolve: options.componentsToResolve,
-        componentRootAttributes: options.componentRootAttributes,
-        documentAttributes: options.documentAttributes,
-        mergeAssets: options.mergeAssets ?? !options.partial
-      },
-      {
-        resolveMarkerGraphHtml: (input) => this.resolveMarkerGraphHtml({
-          html: input.html,
-          componentsToResolve: input.componentsToResolve,
-          graphContext: input.graphContext
-        }),
-        dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-        getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
-        setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
-        applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
-        applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes)
-      }
-    );
+  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 finalization.html;
+      return html;
     }
+    const htmlContributions = options.htmlContributions ?? this.getHtmlDocumentContributions({
+      partial: options.partial
+    });
     const transformedResponse = await this.htmlTransformer.transform(
-      new Response(finalization.html, {
+      new Response(html, {
         headers: { "Content-Type": "text/html" }
-      })
+      }),
+      htmlContributions
     );
     return await transformedResponse.text();
   }
@@ -433,37 +798,16 @@ class IntegrationRenderer {
     return void 0;
   }
   /**
-   * Resolves all `eco-marker` placeholders in rendered HTML using integration
-   * dispatch and bottom-up graph execution.
-   *
-   * Responsibility split:
-   * - core decodes markers into component refs, props, slot children, and target
-   *   integration dispatch
-   * - the selected integration renderer performs the actual component render via
-   *   `renderComponent()`
-   *
-   * Resolver callback behavior per marker:
-   * - resolve component definition by `componentRef`
-   * - resolve serialized props by `propsRef`
-   * - stitch resolved child HTML when `slotRef` is present
-   * - dispatch to target integration `renderComponent`
-   * - collect produced assets and apply root attributes when attachable
-   *
-   * @param options.html HTML that may still contain marker tokens.
-   * @param options.componentsToResolve Component set used to build component ref registry.
-   * @param options.graphContext Props/slot linkage captured during render.
-   * @returns Resolved HTML plus any component-scoped assets produced while resolving nodes.
-   * @throws Error when marker component refs or props refs cannot be resolved.
-   */
-  async resolveMarkerGraphHtml(options) {
-    const integrationRendererCache = /* @__PURE__ */ new Map();
-    return this.markerGraphResolver.resolve({
-      html: options.html,
-      componentsToResolve: options.componentsToResolve,
-      graphContext: options.graphContext,
-      resolveRenderer: (integrationName) => this.getIntegrationRendererForName(integrationName, integrationRendererCache),
-      applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes)
-    });
+   * Returns declarative HTML fragments that core should inject into the final document.
+   *
+   * @remarks
+   * Integrations may contribute document markup here, but core retains ownership
+   * of the final HTML rewrite pipeline and placement semantics. This is the
+   * supported document-markup extension point for integrations instead of custom
+   * response finalization logic.
+   */
+  getHtmlDocumentContributions(_options) {
+    return void 0;
   }
   /**
    * Returns a renderer instance for a given integration name.
@@ -486,26 +830,100 @@ class IntegrationRenderer {
     const integrationPlugin = this.appConfig.integrations.find(
       (integration) => integration.name === integrationName
     );
-    invariant(!!integrationPlugin, `[ecopages] Integration not found for marker: ${integrationName}`);
-    const renderer = integrationPlugin.initializeRenderer();
+    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.
+   *
+   * Without this wrapper, a component tree with foreign-owned descendants would
+   * 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 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 : {
+      ...result,
+      html: normalizedHtml
+    };
+  }
+  normalizeUnresolvedMarkerArtifactHtml(html) {
+    return normalizeUnresolvedMarkerArtifactHtml(html);
+  }
+  /**
+   * Returns whether the component dependency tree crosses into another
+   * integration.
+   *
+   * This keeps foreign-child runtime setup narrow: same-integration trees can render
+   * 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;
+  }
   /**
    * Render a single component and return structured output for orchestration paths.
    *
    * Default behavior delegates to `renderToResponse` in partial mode and wraps
    * the resulting HTML into the `ComponentRenderResult` contract.
    *
-   * In marker 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,
    * root attributes, integration-specific hydration metadata).
    *
    * @param input Component render request.
-   * @returns Structured render result used by marker/page orchestration.
+   * @returns Structured render result used by component/page orchestration.
    */
   async renderComponent(input) {
     const response = await this.renderToResponse(
@@ -528,60 +946,44 @@ class IntegrationRenderer {
    * @returns Root tag name when present; otherwise `undefined`.
    */
   getRootTagName(html) {
-    const rootTag = html.match(/^\s*<([a-zA-Z][a-zA-Z0-9:-]*)\b/);
+    const rootTag = html.match(/^(?:\s|<!--[\s\S]*?-->)*<([a-zA-Z][a-zA-Z0-9:-]*)\b/);
     return rootTag?.[1];
   }
   /**
-   * Method to build route render assets.
-   * This method can be optionally overridden by the specific integration renderer.
+   * Collects declarative Page Browser Graph contributions for one Page.
+   *
+   * @remarks
+   * Integrations may describe page-scoped browser requirements here, while core
+   * retains ownership of dependency processing and final graph assembly. This is
+   * the supported page-browser extension point for integrations.
    *
-   * @param file - The file path to build assets for.
-   * @returns The processed assets or undefined.
+   * @param context - The route file path and already imported page module.
+   * @returns Declarative dependencies or pre-resolved assets for the Page.
    */
-  buildRouteRenderAssets(_file) {
+  async collectPageBrowserGraphContribution(_context) {
     return void 0;
   }
   /**
-   * Builds the narrow boundary policy facade injected into component render
-   * context for this render pass.
+   * Creates the per-render foreign-child runtime adopted by the shared component
+   * render context.
    *
-   * `eco.component()` consumes this facade without knowing about integration
-   * registries or plugin instances.
-   *
-   * @returns Boundary policy context for the active integration renderer.
+   * 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.
    */
-  getComponentRenderBoundaryContext() {
-    return {
-      decideBoundaryRender: (input) => this.shouldDeferComponentBoundary(input) ? "defer" : "inline"
-    };
+  createForeignChildRuntime(options) {
+    return this.createQueuedForeignSubtreeExecutionRuntime({
+      renderInput: options.renderInput,
+      rendererCache: options.rendererCache
+    });
   }
   /**
-   * Resolves whether a component boundary should be deferred by consulting the
-   * target integration plugin.
-   *
-   * Boundaries targeting the current integration always render inline. Cross-
-   * integration boundaries delegate the decision to the target integration's
-   * `shouldDeferComponentBoundary()` policy.
-   *
-   * @param input Boundary metadata for the active render pass.
-   * @returns `true` when the boundary should emit a marker; otherwise `false`.
+   * Creates an explicit fail-fast runtime for tests or renderers that do not
+   * support cross-integration foreign-child execution.
    */
-  shouldDeferComponentBoundary(input) {
-    if (!input.targetIntegration || input.targetIntegration === input.currentIntegration) {
-      return false;
-    }
-    const targetIntegration = this.appConfig.integrations.find(
-      (integration) => integration.name === input.targetIntegration
-    );
-    invariant(
-      !!targetIntegration,
-      `[ecopages] Integration not found for component boundary: ${input.targetIntegration}`
-    );
-    return targetIntegration.shouldDeferComponentBoundary({
-      currentIntegration: input.currentIntegration,
-      targetIntegration: input.targetIntegration,
-      component: input.component
-    });
+  createFailFastForeignChildRuntime() {
+    return this.foreignSubtreeExecutionService.createFailFastRuntime(this.name);
   }
 }
 export {