@ecopages/core 0.2.0-alpha.54 → 0.2.0-alpha.55

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

@@ -1,1384 +0,0 @@
-/**
- * This module contains the abstract class for the Integration Renderer
- * Every integration renderer should extend this class
- * @module
- */
-
-import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.ts';
-import type {
-	ComponentRenderInput,
-	ComponentRenderResult,
-	ForeignSubtreeRenderPayload,
-	EcoComponent,
-	EcoComponentDependencies,
-	EcoFunctionComponent,
-	EcoPageFile,
-	EcoPagesElement,
-	BaseIntegrationContext,
-	HtmlTemplateProps,
-	IntegrationRendererRenderOptions,
-	PageBrowserGraphContribution,
-	PageBrowserGraphContributionContext,
-	PageBrowserGraphResult,
-	PageMetadataProps,
-	RouteRendererBody,
-	RouteRendererOptions,
-	RouteRenderResult,
-} from '../../types/public-types.ts';
-import {
-	type AssetProcessingService,
-	createPagePackage,
-	type ProcessedAsset,
-} from '../../services/assets/asset-processing-service/index.ts';
-import { HtmlTransformerService } from '../../services/html/html-transformer.service.ts';
-import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.ts';
-import { invariant } from '../../utils/invariant.ts';
-import { HttpError } from '../../errors/http-error.ts';
-import { DependencyResolverService } from '../page-loading/dependency-resolver.ts';
-import { PageModuleLoaderService } from '../page-loading/page-module-loader.ts';
-import { OwnershipValidationService } from './ownership-validation.service.ts';
-import {
-	type RouteHtmlFinalization,
-	RouteRenderOrchestrator,
-	type RouteRenderOrchestratorAdapter,
-	type RouteRenderOrchestratorResolvedInputs,
-} from './route-render-orchestrator.ts';
-import type { ForeignChildRuntime } from './component-render-context.ts';
-import { normalizeUnresolvedMarkerArtifactHtml } from './render-output.utils.ts';
-import {
-	ForeignSubtreeExecutionService,
-	type ForeignSubtreeExecutionOwningRenderer,
-} from './foreign-subtree-execution.service.ts';
-import { type QueuedForeignSubtreeResolutionContext } from './queued-foreign-subtree-resolution.service.ts';
-import { buildProcessedAssetDedupeKey } from './processed-asset-dedupe.ts';
-
-/**
- * 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.
- */
-export interface RenderToResponseContext {
-	partial?: boolean;
-	status?: number;
-	headers?: HeadersInit;
-}
-
-export type HtmlDocumentContributionContext<C = EcoPagesElement> = {
-	renderOptions?: IntegrationRendererRenderOptions<C>;
-	partial?: boolean;
-};
-
-export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../../types/public-types.ts';
-export type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.ts';
-
-type MarkupNodeLike = {
-	nodeType: number;
-	outerHTML: string;
-};
-
-function isMarkupNodeLike(value: unknown): value is MarkupNodeLike {
-	return (
-		typeof value === 'object' &&
-		value !== null &&
-		'nodeType' in value &&
-		typeof value.nodeType === 'number' &&
-		'outerHTML' in value &&
-		typeof value.outerHTML === 'string'
-	);
-}
-
-/**
- * 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.
- * The class is designed to be extended by specific integration renderers.
- */
-export abstract class IntegrationRenderer<C = EcoPagesElement> {
-	abstract name: string;
-	protected appConfig: EcoPagesAppConfig;
-	protected assetProcessingService: AssetProcessingService;
-	protected htmlTransformer: HtmlTransformerService;
-	protected hmrManager?: IHmrManager;
-	protected resolvedIntegrationDependencies: ProcessedAsset[] = [];
-	protected rendererModules?: unknown;
-	declare protected options: Required<IntegrationRendererRenderOptions>;
-	protected runtimeOrigin: string;
-	protected dependencyResolverService: DependencyResolverService;
-	protected pageModuleLoaderService: PageModuleLoaderService;
-	protected routeRenderOrchestrator: RouteRenderOrchestrator;
-	protected readonly foreignSubtreeExecutionService = new ForeignSubtreeExecutionService();
-
-	protected 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.
-	 */
-	public async loadPageModule(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile> {
-		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.
-	 */
-	private getOwningRendererCache(
-		integrationContext?: BaseIntegrationContext,
-	): Map<string, IntegrationRenderer<any>> | undefined {
-		if (integrationContext?.rendererCache instanceof Map) {
-			return integrationContext.rendererCache as Map<string, IntegrationRenderer<any>>;
-		}
-
-		return undefined;
-	}
-
-	private getForeignOwnerIntegrationName(component: EcoComponent): string | undefined {
-		const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
-		if (!integrationName || integrationName === this.name) {
-			return undefined;
-		}
-
-		return this.appConfig.integrations.some((integration) => integration.name === integrationName)
-			? integrationName
-			: undefined;
-	}
-
-	/**
-	 * 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(
-		input: ComponentRenderInput,
-		rendererCache: Map<string, IntegrationRenderer<any>>,
-	): ComponentRenderInput {
-		const integrationContext = input.integrationContext;
-		const sharedRendererCache = rendererCache as BaseIntegrationContext['rendererCache'];
-
-		return {
-			...input,
-			integrationContext: integrationContext
-				? { ...integrationContext, rendererCache: sharedRendererCache }
-				: { rendererCache: sharedRendererCache },
-		};
-	}
-
-	protected getRendererModuleValue(key: string): unknown {
-		if (!this.rendererModules || typeof this.rendererModules !== 'object') {
-			return undefined;
-		}
-
-		return (this.rendererModules as Record<string, unknown>)[key];
-	}
-
-	protected getRendererModuleString(key: string): string | undefined {
-		const value = this.getRendererModuleValue(key);
-		return typeof value === 'string' && value.length > 0 ? value : undefined;
-	}
-
-	protected getRendererBootstrapDependencies(partial = false): ProcessedAsset[] {
-		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',
-			},
-		];
-	}
-
-	public setHmrManager(hmrManager: IHmrManager) {
-		this.hmrManager = hmrManager;
-		if (this.assetProcessingService) {
-			this.assetProcessingService.setHmrManager(hmrManager);
-		}
-	}
-
-	/**
-	 * Build response headers with optional custom headers.
-	 * @param contentType - The Content-Type header value
-	 * @param customHeaders - Optional custom headers to merge
-	 * @returns Headers object
-	 */
-	protected buildHeaders(contentType: string, customHeaders?: HeadersInit): Headers {
-		const headers = new Headers({ 'Content-Type': contentType });
-		if (customHeaders) {
-			const incoming = new Headers(customHeaders);
-			incoming.forEach((value, key) => headers.set(key, value));
-		}
-		return headers;
-	}
-
-	/**
-	 * Create an HTML Response.
-	 * @param body - Response body (string or ReadableStream)
-	 * @param ctx - Render context with status and headers
-	 * @returns Response object
-	 */
-	protected createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response {
-		return new Response(body, {
-			status: ctx.status ?? 200,
-			headers: this.buildHeaders('text/html; charset=utf-8', ctx.headers),
-		});
-	}
-
-	/**
-	 * Create an HttpError for render failures.
-	 * @param message - Error message
-	 * @param cause - Original error if available
-	 * @returns HttpError with 500 status
-	 */
-	protected createRenderError(message: string, cause?: unknown): HttpError {
-		const errorMessage = cause instanceof Error ? `${message}: ${cause.message}` : message;
-		return HttpError.InternalServerError(errorMessage);
-	}
-
-	/**
-	 * Prepares dependencies for renderToResponse by resolving component dependencies
-	 * and configuring the HTML transformer.
-	 * @param view - The view component being rendered
-	 * @param layout - Optional layout component
-	 * @returns Resolved processed assets
-	 */
-	protected async prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]> {
-		const HtmlTemplate = await this.getHtmlTemplate();
-		const componentsToResolve = layout ? [HtmlTemplate, layout, view] : [HtmlTemplate, view];
-		const resolvedDependencies = this.htmlTransformer.dedupeProcessedAssets(
-			await this.resolveDependencies(componentsToResolve),
-		);
-		this.htmlTransformer.setPagePackage(createPagePackage(resolvedDependencies));
-		return resolvedDependencies;
-	}
-
-	protected async resolvePageBrowserGraphForFile(filePath: string): Promise<PageBrowserGraphResult | undefined> {
-		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 });
-			},
-		});
-	}
-
-	protected mergePageBrowserGraphIntoPagePackage(
-		pageBrowserGraph?: PageBrowserGraphResult,
-	): PageBrowserGraphResult | undefined {
-		if (!pageBrowserGraph) {
-			return undefined;
-		}
-
-		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.
-	 */
-	protected appendProcessedDependencies(
-		...assetGroups: Array<readonly ProcessedAsset[] | undefined>
-	): ProcessedAsset[] {
-		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.
-	 */
-	protected async resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps> {
-		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.
-	 */
-	protected async renderPartialViewResponse<P>(input: {
-		view: EcoComponent<P>;
-		props: P;
-		ctx: RenderToResponseContext;
-		renderInline?: () => Promise<BodyInit>;
-		transformHtml?: (html: string) => string;
-	}): Promise<Response> {
-		if (input.renderInline && !this.hasForeignChildDescendants(input.view as EcoComponent)) {
-			return this.createHtmlResponse(await input.renderInline(), input.ctx);
-		}
-
-		const rendererCache = new Map<string, unknown>() as BaseIntegrationContext['rendererCache'];
-		const viewRender = await this.renderComponentWithForeignChildren({
-			component: input.view as EcoComponent,
-			props: (input.props ?? {}) as Record<string, unknown>,
-			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.
-	 */
-	protected async renderViewWithDocumentShell<P>(input: {
-		view: EcoComponent<P>;
-		props: P;
-		ctx: RenderToResponseContext;
-		layout?: EcoComponent;
-	}): Promise<Response> {
-		const normalizedProps = (input.props ?? {}) as Record<string, unknown>;
-
-		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 as EcoComponent,
-			primaryProps: normalizedProps,
-			layout: input.layout
-				? {
-						component: input.layout,
-						props: {},
-					}
-				: undefined,
-			htmlTemplate: HtmlTemplate as EcoComponent,
-			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.
-	 */
-	protected async 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> {
-		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}`;
-	}
-
-	private async composeDocumentShell(input: {
-		primaryComponent: EcoComponent;
-		primaryProps: Record<string, unknown>;
-		layout?: {
-			component: EcoComponent;
-			props?: Record<string, unknown>;
-		};
-		htmlTemplate: EcoComponent;
-		documentProps: Record<string, unknown>;
-	}): Promise<{ documentHtml: string }> {
-		const rendererCache = new Map<string, unknown>() as BaseIntegrationContext['rendererCache'];
-		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 },
-				})
-			: undefined;
-		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.
-	 */
-	protected async renderStringComponentWithSerializedChildren(
-		input: ComponentRenderInput,
-		component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement,
-	): Promise<ComponentRenderResult> {
-		const serializedChildren =
-			input.children === undefined
-				? undefined
-				: typeof input.children === 'string'
-					? input.children
-					: isMarkupNodeLike(input.children)
-						? input.children.outerHTML
-						: undefined;
-
-		if (input.children !== undefined && serializedChildren === undefined) {
-			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 === undefined ? 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])
-				: undefined;
-
-		return {
-			html,
-			canAttachAttributes: true,
-			rootTag: this.getRootTagName(html),
-			integrationName: this.name,
-			assets,
-		};
-	}
-
-	protected getForeignSubtreeTokenPrefix(): string {
-		return `__${this.name}_foreign_subtree__`;
-	}
-
-	protected getForeignSubtreeResolutionContextKey(): string {
-		return `__${this.name}_foreign_subtree_runtime__`;
-	}
-
-	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 {
-		return this.foreignSubtreeExecutionService.createQueuedRuntime<TContext>({
-			renderInput: options.renderInput,
-			rendererCache: options.rendererCache,
-			runtimeContextKey: options.runtimeContextKey ?? this.getForeignSubtreeResolutionContextKey(),
-			tokenPrefix: options.tokenPrefix ?? this.getForeignSubtreeTokenPrefix(),
-			createRuntimeContext: options.createRuntimeContext,
-		});
-	}
-
-	protected getQueuedForeignSubtreeResolutionContext<TContext extends QueuedForeignSubtreeResolutionContext>(
-		input: ComponentRenderInput,
-	): TContext | undefined {
-		return this.foreignSubtreeExecutionService.getQueuedRuntimeContext<TContext>(
-			input,
-			this.getForeignSubtreeResolutionContextKey(),
-		);
-	}
-
-	/**
-	 * Renders a string-first component, then resolves any queued foreign
-	 * boundaries before returning final component HTML.
-	 */
-	protected async renderStringComponentWithQueuedForeignSubtrees(
-		input: ComponentRenderInput,
-		component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement,
-	): Promise<ComponentRenderResult> {
-		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 : undefined,
-		};
-	}
-
-	constructor({
-		appConfig,
-		assetProcessingService,
-		resolvedIntegrationDependencies,
-		rendererModules,
-		runtimeOrigin,
-	}: {
-		appConfig: EcoPagesAppConfig;
-		assetProcessingService: AssetProcessingService;
-		resolvedIntegrationDependencies?: ProcessedAsset[];
-		rendererModules?: unknown;
-		runtimeOrigin: string;
-	}) {
-		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.routeRenderOrchestrator = new RouteRenderOrchestrator(appConfig, assetProcessingService, {
-			ownershipValidationService: new OwnershipValidationService(appConfig),
-		});
-	}
-
-	/**
-	 * Returns the HTML path from the provided file path.
-	 * It extracts the path relative to the pages directory and removes the 'index' part if present.
-	 *
-	 * @param file - The file path to extract the HTML path from.
-	 * @returns The extracted HTML path.
-	 */
-	protected getHtmlPath({ file }: { file: string }): string {
-		const pagesDir = this.appConfig.absolutePaths.pagesDir;
-		const pagesIndex = file.indexOf(pagesDir);
-		if (pagesIndex === -1) return file;
-		const startIndex = file.indexOf(pagesDir) + pagesDir.length;
-		const endIndex = file.lastIndexOf('/');
-		const path = file.substring(startIndex, endIndex);
-		if (path === '/index') return '';
-		return path;
-	}
-
-	/**
-	 * Returns the HTML template component.
-	 * It imports the HTML template from the specified path in the app configuration.
-	 *
-	 * @returns The HTML template component.
-	 */
-	protected async getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>> {
-		const htmlTemplatePath =
-			this.getRendererModuleString('htmlTemplateModulePath') ?? this.appConfig.absolutePaths.htmlTemplatePath;
-		try {
-			const { default: HtmlTemplate } = await this.importPageFile(htmlTemplatePath);
-			return HtmlTemplate as EcoComponent<HtmlTemplateProps>;
-		} catch (error) {
-			invariant(false, `Error importing HtmlTemplate: ${error}`);
-		}
-	}
-
-	protected usesIntegrationPageImporter(_file: string): boolean {
-		return false;
-	}
-
-	protected async importIntegrationPageFile(_file: string, _options?: RouteModuleLoadOptions): Promise<EcoPageFile> {
-		invariant(false, 'Integration page importer must be implemented when enabled');
-	}
-
-	protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(
-		_file: string,
-		pageModule: TPageModule,
-	): TPageModule {
-		return pageModule;
-	}
-
-	/**
-	 * Imports the page file from the specified path.
-	 * It uses dynamic import to load the file and returns the imported module.
-	 *
-	 * @param file - The file path to import.
-	 * @returns The imported module.
-	 */
-	protected async importPageFile(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile> {
-		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.
-	 * It combines the component directory with the provided path URL.
-	 *
-	 * @param componentDir - The component directory path.
-	 * @param pathUrl - The path URL to resolve.
-	 * @returns The resolved dependency path.
-	 */
-	protected resolveDependencyPath(componentDir: string, pathUrl: string): string {
-		return this.dependencyResolverService.resolveDependencyPath(componentDir, pathUrl);
-	}
-
-	/**
-	 * Extracts the dependencies from the provided component configuration.
-	 * It resolves the paths for scripts and stylesheets based on the component directory.
-	 *
-	 * @param componentDir - The component directory path.
-	 * @param scripts - The scripts to extract.
-	 * @param stylesheets - The stylesheets to extract.
-	 * @returns The extracted dependencies.
-	 */
-	protected extractDependencies({
-		componentDir,
-		scripts,
-		stylesheets,
-	}: {
-		componentDir: string;
-	} & EcoComponentDependencies): EcoComponentDependencies {
-		const scriptsPaths = [
-			...new Set(
-				(scripts ?? [])
-					.filter((script) => (typeof script === 'string' ? true : !script.lazy))
-					.map((script) => (typeof script === 'string' ? script : script.src))
-					.filter((script): script is string => Boolean(script))
-					.map((script) => this.resolveDependencyPath(componentDir, script)),
-			),
-		];
-
-		const stylesheetsPaths = [
-			...new Set(
-				(stylesheets ?? [])
-					.map((style) => (typeof style === 'string' ? style : style.src))
-					.filter((style): style is string => Boolean(style))
-					.map((style) => this.resolveDependencyPath(componentDir, style)),
-			),
-		];
-
-		return {
-			scripts: scriptsPaths,
-			stylesheets: stylesheetsPaths,
-		};
-	}
-
-	/**
-	 * Resolves lazy script paths to public asset URLs.
-	 * Converts source paths to their final bundled output paths.
-	 *
-	 * @param componentDir - The component directory path.
-	 * @param scripts - The lazy script paths to resolve.
-	 * @returns Comma-separated string of resolved public script paths.
-	 */
-	protected resolveLazyScripts(componentDir: string, scripts: string[]): string {
-		return this.dependencyResolverService.resolveLazyScripts(componentDir, scripts);
-	}
-
-	/**
-	 * Collects the dependencies for the provided components.
-	 * Combines component-specific dependencies with global integration dependencies.
-	 *
-	 * @param components - The components to collect dependencies from.
-	 */
-	protected async resolveDependencies(
-		components: (EcoComponent | Partial<EcoComponent>)[],
-	): Promise<ProcessedAsset[]> {
-		const componentDeps = await this.processComponentDependencies(components);
-		return this.resolvedIntegrationDependencies.concat(componentDeps);
-	}
-
-	/**
-	 * Processes component-specific dependencies WITHOUT prepending global integration dependencies.
-	 * Use this method when you need only the component's own assets.
-	 *
-	 * @param components - The components to collect dependencies from.
-	 */
-	protected async processComponentDependencies(
-		components: (EcoComponent | Partial<EcoComponent>)[],
-	): Promise<ProcessedAsset[]> {
-		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.
-	 */
-	protected createRouteRenderOrchestratorAdapter(): RouteRenderOrchestratorAdapter<C> {
-		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),
-		};
-	}
-
-	protected async resolveRouteRenderInputs(
-		routeOptions: RouteRendererOptions,
-	): Promise<RouteRenderOrchestratorResolvedInputs> {
-		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: HtmlTemplate as EcoComponent<HtmlTemplateProps>,
-			Layout,
-			props,
-			metadata,
-			integrationSpecificProps,
-		};
-	}
-
-	protected async resolveRouteDependencies(input: {
-		components: (EcoComponent | Partial<EcoComponent>)[];
-	}): Promise<{ resolvedDependencies: ProcessedAsset[] }> {
-		return {
-			resolvedDependencies: await this.resolveDependencies(input.components),
-		};
-	}
-
-	protected async resolveRoutePageComponentRender(input: {
-		Page: EcoComponent;
-		Layout?: EcoComponent;
-		props: Record<string, unknown>;
-		routeOptions: RouteRendererOptions;
-	}): Promise<ComponentRenderResult | undefined> {
-		if (!this.shouldRenderPageComponent({ Page: input.Page, Layout: input.Layout, options: input.routeOptions })) {
-			return undefined;
-		}
-
-		return this.renderComponentWithForeignChildren({
-			component: input.Page,
-			props: {
-				...input.props,
-				params: input.routeOptions.params || {},
-				query: input.routeOptions.query || {},
-			},
-			integrationContext: {
-				componentInstanceId: 'eco-page-root',
-			},
-		});
-	}
-
-	protected async renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody> {
-		return this.render(renderOptions);
-	}
-
-	protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization {
-		const componentRootAttributes =
-			renderOptions.componentRender?.canAttachAttributes &&
-			renderOptions.componentRender.rootAttributes &&
-			Object.keys(renderOptions.componentRender.rootAttributes).length > 0
-				? (renderOptions.componentRender.rootAttributes as Record<string, string>)
-				: undefined;
-		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;
-			},
-		};
-	}
-
-	protected async transformRouteResponse(
-		response: Response,
-		htmlContributions?: HtmlDocumentContribution[],
-	): Promise<RouteRendererBody> {
-		const transformedResponse = await this.htmlTransformer.transform(response, htmlContributions);
-		return (transformedResponse.body ?? (await transformedResponse.text())) as RouteRendererBody;
-	}
-
-	/**
-	 * Prepares the render options for the integration renderer.
-	 * It imports the page file, collects dependencies, and prepares the render options.
-	 *
-	 * @param options - The route renderer options.
-	 * @returns The prepared render options.
-	 */
-	protected async prepareRenderOptions(
-		options: RouteRendererOptions,
-		adapter = this.createRouteRenderOrchestratorAdapter(),
-	): Promise<IntegrationRendererRenderOptions<C>> {
-		const renderOptions = await this.routeRenderOrchestrator.prepareRenderOptions(options, adapter);
-		invariant(renderOptions.pagePackage !== undefined, '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()`
-	 * during route option preparation in component-capable modes.
-	 *
-	 * Integrations that already own page-level hydration (for example router-driven
-	 * React rendering) can override this and return `false` to avoid duplicate root
-	 * mount assets and competing hydration entrypoints.
-	 */
-	protected shouldRenderPageComponent(_input: {
-		Page: EcoComponent;
-		Layout?: EcoComponent;
-		options: RouteRendererOptions;
-	}): boolean {
-		return true;
-	}
-
-	/**
-	 * 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 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
-	 * response-body errors.
-	 *
-	 * @param options Route renderer options.
-	 * @returns Rendered route body plus effective cache strategy.
-	 */
-	public async execute(options: RouteRendererOptions): Promise<RouteRenderResult> {
-		const adapter = this.createRouteRenderOrchestratorAdapter();
-		const renderOptions = await this.prepareRenderOptions(options, adapter);
-		return this.routeRenderOrchestrator.executePrepared(renderOptions, adapter);
-	}
-
-	/**
-	 * Finalizes already-resolved HTML for explicit renderer-owned paths.
-	 *
-	 * This keeps document and root-attribute stamping plus HTML transformation
-	 * available after a renderer has completed nested foreign-subtree resolution without
-	 * routing back through shared route execution.
-	 */
-	protected async finalizeResolvedHtml(options: {
-		html: string;
-		partial?: boolean;
-		componentRootAttributes?: Record<string, string>;
-		documentAttributes?: Record<string, string>;
-		transformHtml?: boolean;
-		htmlContributions?: HtmlDocumentContribution[];
-	}): Promise<string> {
-		const rendererBootstrapDependencies = this.getRendererBootstrapDependencies(options.partial);
-		this.appendProcessedDependencies(rendererBootstrapDependencies);
-
-		let html = options.html;
-
-		if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
-			html = this.htmlTransformer.applyAttributesToFirstBodyElement(html, options.componentRootAttributes);
-		}
-
-		if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
-			html = this.htmlTransformer.applyAttributesToHtmlElement(html, options.documentAttributes);
-		}
-
-		const shouldTransform = options.transformHtml ?? !options.partial;
-		if (!shouldTransform) {
-			return html;
-		}
-
-		const htmlContributions =
-			options.htmlContributions ??
-			this.getHtmlDocumentContributions({
-				partial: options.partial,
-			});
-
-		const transformedResponse = await this.htmlTransformer.transform(
-			new Response(html, {
-				headers: { 'Content-Type': 'text/html' },
-			}),
-			htmlContributions,
-		);
-
-		return await transformedResponse.text();
-	}
-
-	/**
-	 * Returns document-level attributes to stamp onto the rendered `<html>` tag.
-	 *
-	 * Integrations can override this to expose explicit document ownership or
-	 * other runtime coordination markers without relying on script sniffing.
-	 */
-	protected getDocumentAttributes(
-		_renderOptions: IntegrationRendererRenderOptions<C>,
-	): Record<string, string> | undefined {
-		return undefined;
-	}
-
-	/**
-	 * 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.
-	 */
-	protected getHtmlDocumentContributions(
-		_options: HtmlDocumentContributionContext<C>,
-	): HtmlDocumentContribution[] | undefined {
-		return undefined;
-	}
-
-	/**
-	 * Returns a renderer instance for a given integration name.
-	 *
-	 * Uses a per-execution cache to avoid repeated renderer initialization.
-	 *
-	 * @param integrationName Target integration name.
-	 * @param cache Render-pass renderer cache.
-	 * @returns Renderer for the requested integration.
-	 * @throws Error when no integration plugin matches `integrationName`.
-	 */
-	protected getIntegrationRendererForName(
-		integrationName: string,
-		cache: Map<string, ForeignSubtreeExecutionOwningRenderer>,
-	): ForeignSubtreeExecutionOwningRenderer {
-		if (cache.has(integrationName)) {
-			return cache.get(integrationName) as ForeignSubtreeExecutionOwningRenderer;
-		}
-
-		if (integrationName === this.name) {
-			cache.set(integrationName, this);
-			return this;
-		}
-
-		const integrationPlugin = this.appConfig.integrations.find(
-			(integration) => integration.name === integrationName,
-		);
-		invariant(!!integrationPlugin, `[ecopages] Integration not found for foreign owner: ${integrationName}`);
-		const renderer = integrationPlugin.initializeRenderer({
-			rendererModules: this.appConfig.runtime?.rendererModuleContext,
-		});
-		cache.set(integrationName, renderer);
-		return renderer;
-	}
-
-	/**
-	 * Abstract method to render the integration-specific component.
-	 * This method should be implemented by the specific integration renderer.
-	 *
-	 * @param options - The integration renderer render options.
-	 * @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.
-	 */
-	async renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult> {
-		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: rendererCache as Map<string, IntegrationRenderer<any>>,
-				}),
-			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: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload> {
-		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,
-		};
-	}
-
-	private normalizeComponentRenderOutput(result: ComponentRenderResult): ComponentRenderResult {
-		const normalizedHtml = this.normalizeUnresolvedMarkerArtifactHtml(result.html);
-
-		return normalizedHtml === result.html
-			? result
-			: {
-					...result,
-					html: normalizedHtml,
-				};
-	}
-
-	protected normalizeUnresolvedMarkerArtifactHtml(html: string): string {
-		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.
-	 */
-	protected hasForeignChildDescendants(component: EcoComponent): boolean {
-		const stack = [component];
-		const seen = new Set<EcoComponent>();
-
-		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 view directly to a Response object.
-	 * Used for explicit routing where views are rendered from route handlers.
-	 *
-	 * @param view - The eco.page component to render
-	 * @param props - Props to pass to the view
-	 * @param ctx - Render context with partial flag and response options
-	 * @returns A Response object with the rendered content
-	 */
-	abstract renderToResponse<P = Record<string, unknown>>(
-		view: EcoComponent<P>,
-		props: P,
-		ctx: RenderToResponseContext,
-	): Promise<Response>;
-
-	/**
-	 * 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 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 component/page orchestration.
-	 */
-	async renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult> {
-		const response = await this.renderToResponse(
-			input.component as EcoFunctionComponent<Record<string, unknown>, EcoPagesElement>,
-			input.props,
-			{ partial: true },
-		);
-		const html = await response.text();
-
-		return {
-			html,
-			canAttachAttributes: true,
-			rootTag: this.getRootTagName(html),
-			integrationName: this.name,
-		};
-	}
-
-	/**
-	 * Extracts the first root element tag name from HTML output.
-	 *
-	 * @param html HTML fragment.
-	 * @returns Root tag name when present; otherwise `undefined`.
-	 */
-	protected getRootTagName(html: string): string | undefined {
-		const rootTag = html.match(/^(?:\s|<!--[\s\S]*?-->)*<([a-zA-Z][a-zA-Z0-9:-]*)\b/);
-		return rootTag?.[1];
-	}
-
-	/**
-	 * 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 context - The route file path and already imported page module.
-	 * @returns Declarative dependencies or pre-resolved assets for the Page.
-	 */
-	protected async collectPageBrowserGraphContribution(
-		_context: PageBrowserGraphContributionContext,
-	): Promise<PageBrowserGraphContribution | undefined> {
-		return undefined;
-	}
-
-	/**
-	 * Creates the per-render foreign-child runtime adopted by the shared component
-	 * render context.
-	 *
-	 * 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 createForeignChildRuntime(options: {
-		renderInput: ComponentRenderInput;
-		rendererCache: Map<string, IntegrationRenderer<any>>;
-	}): ForeignChildRuntime {
-		return this.createQueuedForeignSubtreeExecutionRuntime({
-			renderInput: options.renderInput,
-			rendererCache: options.rendererCache,
-		});
-	}
-
-	/**
-	 * Creates an explicit fail-fast runtime for tests or renderers that do not
-	 * support cross-integration foreign-child execution.
-	 */
-	protected createFailFastForeignChildRuntime(): ForeignChildRuntime {
-		return this.foreignSubtreeExecutionService.createFailFastRuntime(this.name);
-	}
-}