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

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

@@ -3,27 +3,29 @@
  * Every integration renderer should extend this class
  * @module
  */
-import type { EcoPagesAppConfig, IHmrManager } from '../../internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentDependencies, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetMetadataContext, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../public-types.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
+import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 import { HttpError } from '../../errors/http-error.js';
 import { DependencyResolverService } from '../page-loading/dependency-resolver.js';
 import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
-import { MarkerGraphResolver } from '../component-graph/marker-graph-resolver.js';
-import { RenderExecutionService, type RenderExecutionGraphContext } from './render-execution.service.js';
-import { RenderPreparationService } from './render-preparation.service.js';
-import type { BoundaryRenderDecisionInput, ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
-export interface FinalizeCapturedHtmlRenderOptions {
-    html: string;
-    componentsToResolve: EcoComponent[];
-    graphContext: RenderExecutionGraphContext;
-    partial?: boolean;
-    componentRootAttributes?: Record<string, string>;
-    documentAttributes?: Record<string, string>;
-    mergeAssets?: boolean;
-    transformHtml?: boolean;
-}
+import { type RouteHtmlFinalization, RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
+import type { ForeignChildRuntime } from './component-render-context.js';
+import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer } from './foreign-subtree-execution.service.js';
+import { type QueuedForeignSubtreeResolutionContext } from './queued-foreign-subtree-resolution.service.js';
+/**
+ * Controls how one route module is loaded outside the normal render path.
+ *
+ * Request-time metadata inspection and static-generation probes use these
+ * options to isolate their module identity from the main render cache while
+ * still going through the owning integration's import setup.
+ */
+export type RouteModuleLoadOptions = {
+    bypassCache?: boolean;
+    cacheScope?: string;
+};
 /**
  * Context for renderToResponse method.
  */
@@ -32,6 +34,12 @@ export interface RenderToResponseContext {
     status?: number;
     headers?: HeadersInit;
 }
+export type HtmlDocumentContributionContext<C = EcoPagesElement> = {
+    renderOptions?: IntegrationRendererRenderOptions<C>;
+    partial?: boolean;
+};
+export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../../types/public-types.js';
+export type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 /**
  * The IntegrationRenderer class is an abstract class that provides a base for rendering integration-specific components in the EcoPages framework.
  * It handles the import of page files, collection of dependencies, and preparation of render options.
@@ -44,14 +52,54 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected htmlTransformer: HtmlTransformerService;
     protected hmrManager?: IHmrManager;
     protected resolvedIntegrationDependencies: ProcessedAsset[];
+    protected rendererModules?: unknown;
     protected options: Required<IntegrationRendererRenderOptions>;
     protected runtimeOrigin: string;
     protected dependencyResolverService: DependencyResolverService;
     protected pageModuleLoaderService: PageModuleLoaderService;
-    protected markerGraphResolver: MarkerGraphResolver;
-    protected renderPreparationService: RenderPreparationService;
-    protected renderExecutionService: RenderExecutionService;
+    protected routeRenderOrchestrator: RouteRenderOrchestrator;
+    protected readonly foreignSubtreeExecutionService: ForeignSubtreeExecutionService;
     protected DOC_TYPE: string;
+    /**
+     * 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.
+     */
+    loadPageModule(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
+    /**
+     * Reads the execution-scoped owning-renderer cache from one render input.
+     *
+     * Shared page/layout/document shell helpers pass one cache through
+     * `integrationContext` so repeated delegation to the same foreign integration
+     * can reuse a single initialized renderer instance during one render flow.
+     * The cache is deliberately scoped to the current render execution rather than
+     * stored on the renderer, which avoids leaking mutable integration state across
+     * requests while still preventing redundant renderer initialization.
+     *
+     * @param integrationContext - Optional render context carried with one render input.
+     * @returns The current execution cache when present.
+     */
+    private getOwningRendererCache;
+    private getForeignOwnerIntegrationName;
+    /**
+     * Attaches an execution-scoped owning-renderer cache to one render input.
+     *
+     * Foreign-owned page, layout, or document shells may delegate several times in
+     * the same render flow. Threading the cache through `integrationContext`
+     * preserves renderer reuse without changing the public render input contract.
+     * Existing integration-specific context is preserved and augmented.
+     *
+     * @param input - Original render input.
+     * @param rendererCache - Execution-scoped renderer cache to propagate.
+     * @returns Render input augmented with the shared renderer cache.
+     */
+    private withOwningRendererCache;
+    protected getRendererModuleValue(key: string): unknown;
+    protected getRendererModuleString(key: string): string | undefined;
+    protected getRendererBootstrapDependencies(partial?: boolean): ProcessedAsset[];
     setHmrManager(hmrManager: IHmrManager): void;
     /**
      * Build response headers with optional custom headers.
@@ -82,10 +130,130 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns Resolved processed assets
      */
     protected prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
-    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, runtimeOrigin, }: {
+    protected resolvePageBrowserGraphForFile(filePath: string): Promise<PageBrowserGraphResult | undefined>;
+    protected mergePageBrowserGraphIntoPagePackage(pageBrowserGraph?: PageBrowserGraphResult): PageBrowserGraphResult | undefined;
+    /**
+     * 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.
+     */
+    protected appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+    /**
+     * 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.
+     */
+    protected resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps>;
+    /**
+     * 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.
+     */
+    protected renderPartialViewResponse<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        renderInline?: () => Promise<BodyInit>;
+        transformHtml?: (html: string) => string;
+    }): Promise<Response>;
+    /**
+     * 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.
+     */
+    protected renderViewWithDocumentShell<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        layout?: EcoComponent;
+    }): Promise<Response>;
+    /**
+     * 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.
+     */
+    protected renderPageWithDocumentShell(input: {
+        page: {
+            component: EcoComponent;
+            props: Record<string, unknown>;
+        };
+        layout?: {
+            component: EcoComponent;
+            props?: Record<string, unknown>;
+        };
+        htmlTemplate: EcoComponent;
+        metadata: PageMetadataProps;
+        pageProps: Record<string, unknown>;
+        documentProps?: Record<string, unknown>;
+        transformDocumentHtml?: (html: string) => string;
+    }): Promise<string>;
+    private composeDocumentShell;
+    /**
+     * Renders one string-first component with serialized children and collects its assets.
+     *
+     * String-oriented integrations frequently share the same component contract:
+     * pass serialized children through props, coerce the render result to HTML, and
+     * attach any component-scoped dependencies. This helper centralizes that flow
+     * so integrations can opt into shared orchestration without repeating the same
+     * string-render boilerplate.
+     *
+     * @param input - Component render input.
+     * @param component - String-oriented component implementation to execute.
+     * @returns Structured component render result for orchestration paths.
+     */
+    protected renderStringComponentWithSerializedChildren(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
+    protected getForeignSubtreeTokenPrefix(): string;
+    protected getForeignSubtreeResolutionContextKey(): string;
+    protected createQueuedForeignSubtreeExecutionRuntime<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+        runtimeContextKey?: string;
+        tokenPrefix?: string;
+        createRuntimeContext?: (integrationContext: BaseIntegrationContext & Record<string, unknown>, rendererCache: Map<string, unknown>) => TContext;
+    }): ForeignChildRuntime;
+    protected getQueuedForeignSubtreeResolutionContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput): TContext | undefined;
+    /**
+     * Renders a string-first component, then resolves any queued foreign
+     * boundaries before returning final component HTML.
+     */
+    protected renderStringComponentWithQueuedForeignSubtrees(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
+    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, rendererModules, runtimeOrigin, }: {
         appConfig: EcoPagesAppConfig;
         assetProcessingService: AssetProcessingService;
         resolvedIntegrationDependencies?: ProcessedAsset[];
+        rendererModules?: unknown;
         runtimeOrigin: string;
     });
     /**
@@ -105,27 +273,9 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns The HTML template component.
      */
     protected getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
-    /**
-     * 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.
-     */
-    protected getStaticProps(getStaticProps?: GetStaticProps<Record<string, unknown>>, options?: Pick<RouteRendererOptions, 'params'>): Promise<{
-        props: Record<string, unknown>;
-        metadata?: PageMetadataProps;
-    }>;
-    /**
-     * 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.
-     */
-    protected getMetadataProps(getMetadata: GetMetadata | undefined, { props, params, query }: GetMetadataContext): Promise<PageMetadataProps>;
+    protected usesIntegrationPageImporter(_file: string): boolean;
+    protected importIntegrationPageFile(_file: string, _options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(_file: string, pageModule: TPageModule): TPageModule;
     /**
      * Imports the page file from the specified path.
      * It uses dynamic import to load the file and returns the imported module.
@@ -133,7 +283,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @param file - The file path to import.
      * @returns The imported module.
      */
-    protected importPageFile(file: string): Promise<EcoPageFile>;
+    protected importPageFile(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
     /**
      * Resolves the dependency path based on the component directory.
      * It combines the component directory with the provided path URL.
@@ -178,6 +328,30 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @param components - The components to collect dependencies from.
      */
     protected processComponentDependencies(components: (EcoComponent | Partial<EcoComponent>)[]): Promise<ProcessedAsset[]>;
+    /**
+     * 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.
+     */
+    protected createRouteRenderOrchestratorAdapter(): RouteRenderOrchestratorAdapter<C>;
+    protected resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    protected resolveRouteDependencies(input: {
+        components: (EcoComponent | Partial<EcoComponent>)[];
+    }): Promise<{
+        resolvedDependencies: ProcessedAsset[];
+    }>;
+    protected resolveRoutePageComponentRender(input: {
+        Page: EcoComponent;
+        Layout?: EcoComponent;
+        props: Record<string, unknown>;
+        routeOptions: RouteRendererOptions;
+    }): Promise<ComponentRenderResult | undefined>;
+    protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
+    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
     /**
      * Prepares the render options for the integration renderer.
      * It imports the page file, collects dependencies, and prepares the render options.
@@ -185,7 +359,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @param options - The route renderer options.
      * @returns The prepared render options.
      */
-    protected prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions>;
+    protected prepareRenderOptions(options: RouteRendererOptions, adapter?: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
     /**
      * Controls whether the page root should be rendered through `renderComponent()`
      * during route option preparation in component-capable modes.
@@ -199,35 +373,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         Layout?: EcoComponent;
         options: RouteRendererOptions;
     }): boolean;
-    /**
-     * Resolves the page module and normalizes exports.
-     */
-    protected resolvePageModule(file: string): Promise<{
-        Page: EcoPageFile['default'] | EcoPageComponent<any>;
-        getStaticProps?: GetStaticProps<Record<string, unknown>>;
-        getMetadata?: GetMetadata;
-        integrationSpecificProps: Record<string, unknown>;
-    }>;
-    /**
-     * Resolves static props and metadata for the page.
-     */
-    protected resolvePageData(pageModule: {
-        getStaticProps?: GetStaticProps<Record<string, unknown>>;
-        getMetadata?: GetMetadata;
-    }, options: RouteRendererOptions): Promise<{
-        props: Record<string, unknown>;
-        metadata: PageMetadataProps;
-    }>;
     /**
      * 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
@@ -238,23 +392,20 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     execute(options: RouteRendererOptions): Promise<RouteRenderResult>;
     /**
-     * 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()`.
+     * This keeps document and root-attribute stamping plus HTML transformation
+     * available after a renderer has completed nested foreign-subtree resolution without
+     * routing back through shared route execution.
      */
-    protected captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<{
+    protected finalizeResolvedHtml(options: {
         html: string;
-        graphContext: RenderExecutionGraphContext;
-    }>;
-    /**
-     * 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.
-     */
-    protected finalizeCapturedHtmlRender(options: FinalizeCapturedHtmlRenderOptions): Promise<string>;
+        partial?: boolean;
+        componentRootAttributes?: Record<string, string>;
+        documentAttributes?: Record<string, string>;
+        transformHtml?: boolean;
+        htmlContributions?: HtmlDocumentContribution[];
+    }): Promise<string>;
     /**
      * Returns document-level attributes to stamp onto the rendered `<html>` tag.
      *
@@ -263,29 +414,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected getDocumentAttributes(_renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
     /**
-     * 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
+     * Returns declarative HTML fragments that core should inject into the final document.
      *
-     * @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.
+     * @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.
      */
-    private resolveMarkerGraphHtml;
+    protected getHtmlDocumentContributions(_options: HtmlDocumentContributionContext<C>): HtmlDocumentContribution[] | undefined;
     /**
      * Returns a renderer instance for a given integration name.
      *
@@ -296,7 +433,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns Renderer for the requested integration.
      * @throws Error when no integration plugin matches `integrationName`.
      */
-    private getIntegrationRendererForName;
+    protected getIntegrationRendererForName(integrationName: string, cache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
     /**
      * Abstract method to render the integration-specific component.
      * This method should be implemented by the specific integration renderer.
@@ -305,6 +442,31 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns The rendered body.
      */
     abstract render(options: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    /**
+     * 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.
+     */
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    /**
+     * Compatibility foreign-subtree contract that exposes a narrower payload shape for
+     * future route-composition work while preserving the current
+     * `renderComponentWithForeignChildren()` runtime semantics.
+     */
+    renderForeignSubtree(input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload>;
+    private normalizeComponentRenderOutput;
+    protected normalizeUnresolvedMarkerArtifactHtml(html: string): string;
+    /**
+     * 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.
+     */
+    protected hasForeignChildDescendants(component: EcoComponent): boolean;
     /**
      * Render a view directly to a Response object.
      * Used for explicit routing where views are rendered from route handlers.
@@ -321,15 +483,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * 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.
      */
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
     /**
@@ -340,33 +502,33 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected getRootTagName(html: string): string | undefined;
     /**
-     * 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.
      */
-    protected buildRouteRenderAssets(_file: string): Promise<ProcessedAsset[]> | undefined;
+    protected collectPageBrowserGraphContribution(_context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
     /**
-     * Builds the narrow boundary policy facade injected into component render
-     * context for this render pass.
-     *
-     * `eco.component()` consumes this facade without knowing about integration
-     * registries or plugin instances.
+     * Creates the per-render foreign-child runtime adopted by the shared component
+     * render context.
      *
-     * @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.
      */
-    protected getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
+    protected createForeignChildRuntime(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): ForeignChildRuntime;
     /**
-     * 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.
      */
-    protected shouldDeferComponentBoundary(input: BoundaryRenderDecisionInput): boolean;
+    protected createFailFastForeignChildRuntime(): ForeignChildRuntime;
 }