@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.27

package/src/route-renderer/orchestration/{render-preparation.service.ts → route-render-orchestrator.ts}

@@ -3,66 +3,57 @@ import path from 'node:path';
 import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
 import type {
 	ComponentRenderResult,
+	DependencyAttributes,
 	EcoComponent,
 	EcoComponentConfig,
-	DependencyAttributes,
 	EcoPageComponent,
 	EcoPageFile,
-	EcoPagesElement,
-	GetMetadata,
-	GetStaticProps,
 	HtmlTemplateProps,
 	IntegrationRendererRenderOptions,
-	PageProps,
+	PageBrowserGraphResult,
 	PageMetadataProps,
+	PageProps,
 	ResolvedLazyTrigger,
+	RouteRendererBody,
 	RouteRendererOptions,
+	RouteRenderResult,
 } from '../../types/public-types.ts';
 import {
 	type AssetProcessingService,
 	AssetFactory,
+	createPagePackage,
 	type ProcessedAsset,
 } from '../../services/assets/asset-processing-service/index.ts';
 import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from '../../eco/global-injector-map.ts';
 import { LocalsAccessError } from '../../errors/locals-access-error.ts';
-import { BoundaryPlanningService } from './boundary-planning.service.ts';
-import { PagePackagingService } from './page-packaging.service.ts';
+import { inspectUnresolvedMarkerArtifactHtml } from './render-output.utils.ts';
+import { OwnershipValidationService } from './ownership-validation.service.ts';
+import { OwnershipPlanningService } from './ownership-planning.service.ts';
 import { dedupeProcessedAssets } from './processed-asset-dedupe.ts';
 
-type ResolvedPageModule = {
+export type RouteRenderOrchestratorResolvedInputs = {
 	Page: EcoPageFile['default'] | EcoPageComponent<any>;
-	getStaticProps?: GetStaticProps<Record<string, unknown>>;
-	getMetadata?: GetMetadata;
+	HtmlTemplate: EcoComponent<HtmlTemplateProps>;
+	Layout?: EcoComponent;
+	props: Record<string, unknown>;
+	metadata: PageMetadataProps;
 	integrationSpecificProps: Record<string, unknown>;
 };
 
-export interface RenderPreparationCallbacks {
-	resolvePageModule(file: string): Promise<ResolvedPageModule>;
-	getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
-	resolvePageData(
-		pageModule: {
-			getStaticProps?: GetStaticProps<Record<string, unknown>>;
-			getMetadata?: GetMetadata;
-		},
-		routeOptions: RouteRendererOptions,
-	): Promise<{ props: Record<string, unknown>; metadata: PageMetadataProps }>;
-	resolveDependencies(components: (EcoComponent | Partial<EcoComponent>)[]): Promise<ProcessedAsset[]>;
-	buildRouteRenderAssets(file: string): Promise<ProcessedAsset[]> | undefined;
-	shouldRenderPageComponent(input: {
-		Page: EcoComponent;
-		Layout?: EcoComponent;
-		options: RouteRendererOptions;
-	}): boolean;
-	renderPageComponent(input: {
-		component: EcoComponent;
-		props: Record<string, unknown>;
-	}): Promise<ComponentRenderResult>;
-}
+export type RouteRenderOrchestratorResolvedAssets = {
+	resolvedDependencies: ProcessedAsset[];
+	pageBrowserGraph?: PageBrowserGraphResult;
+};
 
-export interface RenderPreparationServiceDependencies {
-	boundaryPlanningService?: BoundaryPlanningService;
-	pagePackagingService?: PagePackagingService;
-}
+/**
+ * Structural HTML work applied after the route body has been fully resolved.
+ *
+ * The shared route flow only needs to know whether a post-render HTML step
+ * exists. When `finalizeHtml` is absent, the captured body can be reused as-is.
+ */
+export type RouteHtmlFinalization = {
+	finalizeHtml?(html: string): string;
+};
 
 function createPageLocalsProxy(filePath: string): Record<string, never> {
 	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.`;
@@ -95,114 +86,158 @@ function createPageLocalsProxy(filePath: string): Record<string, never> {
 	);
 }
 
+export interface RouteRenderOrchestratorAdapter<C> {
+	/**
+	 * Name of the owning Integration for the current route render.
+	 */
+	readonly name: string;
+	/**
+	 * Loads the Integration-owned route inputs needed for one Page render.
+	 */
+	resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+	/**
+	 * Resolves route-owned assets needed before Integration rendering starts.
+	 */
+	resolveRouteAssets(input: {
+		routeOptions: RouteRendererOptions;
+		components: (EcoComponent | Partial<EcoComponent>)[];
+	}): Promise<RouteRenderOrchestratorResolvedAssets>;
+	/**
+	 * Resolves the optional page-root render through the foreign-child-aware component contract.
+	 */
+	resolveRoutePageComponentRender(input: {
+		Page: EcoComponent;
+		Layout?: EcoComponent;
+		props: Record<string, unknown>;
+		routeOptions: RouteRendererOptions;
+	}): Promise<ComponentRenderResult | undefined>;
+	/**
+	 * Executes the Integration-specific route render.
+	 */
+	renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+	/**
+	 * Returns the structural Html finalization plan for one prepared route render.
+	 */
+	getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
+	/**
+	 * Runs SSR-policy response transformation and returns the body value exposed to callers.
+	 */
+	transformRouteResponse(response: Response): Promise<RouteRendererBody>;
+}
+
+/**
+ * Captured route-render output in both replayable body and string HTML forms.
+ */
+export interface CapturedHtmlRenderResult {
+	body: RouteRendererBody;
+	html: string;
+}
+
+/**
+ * Optional app-scoped collaborators used by the route render orchestrator.
+ */
+export interface RouteRenderOrchestratorDependencies {
+	ownershipPlanningService?: OwnershipPlanningService;
+	ownershipValidationService?: OwnershipValidationService;
+}
+
 /**
- * Prepares the normalized render inputs consumed by `IntegrationRenderer.execute()`.
+ * Owns one route render from normalized module loading through final HTML output.
  *
- * This service owns the orchestration that happens before the main HTML render:
- * page module resolution, data loading, dependency aggregation, page-root
- * component artifact capture, lazy trigger bootstrap generation, and request
- * locals policy.
+ * This orchestrator keeps route rendering as one app-scoped unit while still
+ * delegating integration-specific behavior through the adapter seam. It owns
+ * route-root validation, dependency aggregation, page package creation, and the
+ * final HTML/body handling that happens after the integration render returns.
  */
-export class RenderPreparationService {
-	private appConfig: EcoPagesAppConfig;
-	private assetProcessingService: AssetProcessingService;
-	private readonly boundaryPlanningService: BoundaryPlanningService;
-	private readonly pagePackagingService: PagePackagingService;
+export class RouteRenderOrchestrator {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly assetProcessingService: AssetProcessingService;
+	private readonly ownershipPlanningService: OwnershipPlanningService;
+	private readonly ownershipValidationService: OwnershipValidationService;
 
-	/**
-	 * Creates the render-preparation orchestrator for one app instance.
-	 *
-	 * @remarks
-	 * The service is app-scoped because it depends on finalized config defaults and
-	 * the app-owned asset-processing pipeline while remaining renderer-agnostic.
-	 */
 	constructor(
 		appConfig: EcoPagesAppConfig,
 		assetProcessingService: AssetProcessingService,
-		dependencies: RenderPreparationServiceDependencies = {},
+		dependencies: RouteRenderOrchestratorDependencies = {},
 	) {
 		this.appConfig = appConfig;
 		this.assetProcessingService = assetProcessingService;
-		this.boundaryPlanningService = dependencies.boundaryPlanningService ?? new BoundaryPlanningService(appConfig);
-		this.pagePackagingService = dependencies.pagePackagingService ?? new PagePackagingService();
+		this.ownershipPlanningService = dependencies.ownershipPlanningService ?? new OwnershipPlanningService();
+		this.ownershipValidationService =
+			dependencies.ownershipValidationService ?? new OwnershipValidationService(appConfig);
 	}
 
 	/**
-	 * Builds the final render options object used by the integration-specific
-	 * renderer.
+	 * Builds normalized route render options before the integration render runs.
 	 *
-	 * The returned object contains normalized page data, processed dependency
-	 * state, component render artifacts, and the locals contract expected by the
-	 * rest of the pipeline.
-	 *
-	 * @typeParam C Integration render output element type.
-	 * @param routeOptions Route-level render inputs.
-	 * @param currentIntegrationName Active integration name for this preparation pass.
-	 * @param callbacks Renderer-specific hooks used during preparation.
-	 * @returns Normalized render options.
+	 * This preparation step validates route-root ownership, resolves page data,
+	 * collects processed assets, captures optional page-root render metadata, and
+	 * produces the page package consumed by downstream HTML transformation.
 	 */
-	async prepare<C = EcoPagesElement>(
+	async prepareRenderOptions<C = unknown>(
 		routeOptions: RouteRendererOptions,
-		currentIntegrationName: string,
-		callbacks: RenderPreparationCallbacks,
+		adapter: RouteRenderOrchestratorAdapter<C>,
 	): Promise<IntegrationRendererRenderOptions<C>> {
-		const pageModule = await callbacks.resolvePageModule(routeOptions.file);
-		const { Page, integrationSpecificProps } = pageModule;
-		const HtmlTemplate = await callbacks.getHtmlTemplate();
-		const { props, metadata } = await callbacks.resolvePageData(pageModule, routeOptions);
-		const Layout = Page.config?.layout;
-		const boundaryPlan = this.boundaryPlanningService.buildPlan({
+		const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
+		const { Page, HtmlTemplate, Layout, props, metadata, integrationSpecificProps } = resolvedInputs;
+		const validationErrors = this.ownershipValidationService.validate({
+			currentIntegrationName: adapter.name,
+			roots: [
+				{ component: HtmlTemplate as EcoComponent, source: 'html-template' },
+				...(Layout ? [{ component: Layout as EcoComponent, source: 'layout' as const }] : []),
+				{ component: Page as EcoComponent, source: 'page' },
+			],
+		});
+		const ownershipPlan = this.ownershipPlanningService.buildPlan({
 			routeFile: routeOptions.file,
-			currentIntegrationName,
-			HtmlTemplate,
+			currentIntegrationName: adapter.name,
+			HtmlTemplate: HtmlTemplate as EcoComponent,
 			Layout,
 			Page: Page as EcoComponent,
+			validationErrors,
 		});
 
 		const componentsToResolve = Layout ? [HtmlTemplate, Layout, Page] : [HtmlTemplate, Page];
-		const resolvedDependencies = await callbacks.resolveDependencies(componentsToResolve);
-		const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(
-			componentsToResolve,
-			currentIntegrationName,
-		);
-		const pageDeps = (await callbacks.buildRouteRenderAssets(routeOptions.file)) || [];
-		const allDependencies = [...resolvedDependencies, ...usedIntegrationDependencies, ...pageDeps];
-
-		let componentRender: ComponentRenderResult | undefined;
-		if (callbacks.shouldRenderPageComponent({ Page, Layout, options: routeOptions })) {
-			const pageRootRender = await this.renderPageRoot({
-				Page: Page as EcoComponent,
-				props,
-				routeOptions,
-				callbacks,
-			});
-			componentRender = pageRootRender.componentRender;
-
-			if (componentRender.assets?.length) {
-				allDependencies.push(...componentRender.assets);
-			}
+		const { resolvedDependencies, pageBrowserGraph } = await adapter.resolveRouteAssets({
+			routeOptions,
+			components: componentsToResolve,
+		});
+		const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(componentsToResolve, adapter.name);
+		const allDependencies = [
+			...resolvedDependencies,
+			...usedIntegrationDependencies,
+			...(pageBrowserGraph?.assets ?? []),
+		];
+
+		const componentRender = await adapter.resolveRoutePageComponentRender({
+			Page: Page as EcoComponent,
+			Layout,
+			props,
+			routeOptions,
+		});
+
+		if (componentRender?.assets?.length) {
+			allDependencies.push(...componentRender.assets);
 		}
 
 		const triggers = this.collectResolvedTriggers(componentsToResolve);
 		if (triggers.length > 0) {
-			const globalAssets = await this.buildGlobalInjectorAssets(triggers, currentIntegrationName);
+			const globalAssets = await this.buildGlobalInjectorAssets(triggers, adapter.name);
 			allDependencies.push(...globalAssets);
 		}
 
-		const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, currentIntegrationName);
+		const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, adapter.name);
 		if (eagerSsrLazyAssets.length > 0) {
 			allDependencies.push(...eagerSsrLazyAssets);
 		}
 
 		const dedupedDependencies = dedupeProcessedAssets(allDependencies);
-		const pagePackage = this.pagePackagingService.createPagePackage(dedupedDependencies);
-
+		const pagePackage = createPagePackage(dedupedDependencies);
 		const pageProps = {
 			...props,
 			params: routeOptions.params || {},
 			query: routeOptions.query || {},
 		};
-
 		const cacheStrategy = (Page as EcoPageComponent<any>).cache;
 		const defaultCacheStrategy = this.appConfig.cache?.defaultStrategy ?? 'static';
 		const effectiveCacheStrategy = cacheStrategy ?? defaultCacheStrategy;
@@ -229,7 +264,7 @@ export class RenderPreparationService {
 			locals,
 			pageLocals,
 			cacheStrategy,
-			boundaryPlan,
+			ownershipPlan,
 		};
 
 		return {
@@ -239,15 +274,107 @@ export class RenderPreparationService {
 	}
 
 	/**
-	 * Collects resolved lazy trigger metadata from the component tree.
-	 *
-	 * Traversal is depth-first and deduplicated by component identity so shared
-	 * component dependencies do not emit duplicate trigger sets.
-	 *
-	 * @param components Root component set.
-	 * @param seen Internal visited set for shared graphs.
-	 * @returns All resolved lazy triggers reachable from the root set.
+	 * Captures one route render body as HTML while preserving a replayable body value.
+	 */
+	async captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult> {
+		const renderedBody = await render();
+		const capturedRender = await this.captureRenderedBody(renderedBody);
+
+		return {
+			body: capturedRender.body,
+			html: capturedRender.html,
+		};
+	}
+
+	/**
+	 * Executes the full route-render flow and returns the final body plus cache strategy.
+	 */
+	async execute<C = unknown>(
+		options: RouteRendererOptions,
+		adapter: RouteRenderOrchestratorAdapter<C>,
+	): Promise<RouteRenderResult> {
+		const renderOptions = await this.prepareRenderOptions(options, adapter);
+		return this.executePrepared(renderOptions, adapter);
+	}
+
+	/**
+	 * Executes the route-render finalization path for already prepared render options.
 	 */
+	async executePrepared<C = unknown>(
+		renderOptions: IntegrationRendererRenderOptions<C>,
+		adapter: RouteRenderOrchestratorAdapter<C>,
+	): Promise<RouteRenderResult> {
+		const renderExecution = await this.captureHtmlRender(async () => adapter.renderRouteBody(renderOptions));
+		const unresolvedArtifactInspection = inspectUnresolvedMarkerArtifactHtml(renderExecution.html);
+		const htmlFinalization = adapter.getRouteHtmlFinalization(renderOptions);
+		const hasUnresolvedMarkerHtml = unresolvedArtifactInspection.hasUnresolvedMarkerArtifacts;
+
+		if (hasUnresolvedMarkerHtml) {
+			throw new Error(
+				'[ecopages] Route render returned unresolved eco-marker artifact HTML. Full-route unresolved-marker fallback has been removed; resolve mixed foreign children inside renderComponentWithForeignChildren().',
+			);
+		}
+
+		const canReuseCapturedBody = !hasUnresolvedMarkerHtml && htmlFinalization.finalizeHtml === undefined;
+
+		if (canReuseCapturedBody) {
+			const body = await adapter.transformRouteResponse(
+				new Response(renderExecution.body as BodyInit, {
+					headers: {
+						'Content-Type': 'text/html',
+					},
+				}),
+			);
+
+			return {
+				body,
+				cacheStrategy: renderOptions.cacheStrategy,
+			};
+		}
+
+		const finalization = htmlFinalization.finalizeHtml
+			? htmlFinalization.finalizeHtml(unresolvedArtifactInspection.normalizedHtml)
+			: unresolvedArtifactInspection.normalizedHtml;
+
+		const body = await adapter.transformRouteResponse(
+			new Response(finalization, {
+				headers: {
+					'Content-Type': 'text/html',
+				},
+			}),
+		);
+
+		return {
+			body,
+			cacheStrategy: renderOptions.cacheStrategy,
+		};
+	}
+
+	private async captureRenderedBody(body: RouteRendererBody): Promise<{ body: RouteRendererBody; html: string }> {
+		const response = new Response(body as BodyInit);
+
+		if (typeof body === 'string') {
+			return {
+				body,
+				html: await response.text(),
+			};
+		}
+
+		if (!response.body) {
+			return {
+				body,
+				html: await response.text(),
+			};
+		}
+
+		const [capturedBody, replayBody] = response.body.tee();
+
+		return {
+			body: replayBody,
+			html: await new Response(capturedBody).text(),
+		};
+	}
+
 	private collectResolvedTriggers(
 		components: (EcoComponent | Partial<EcoComponent>)[],
 		seen = new Set<object>(),
@@ -275,13 +402,6 @@ export class RenderPreparationService {
 		return triggers;
 	}
 
-	/**
-	 * Collects global integration dependencies used by nested components belonging
-	 * to integrations other than the current renderer.
-	 *
-	 * @param components Root component set.
-	 * @returns Processed integration dependencies contributed by nested integrations.
-	 */
 	private collectUsedIntegrationDependencies(
 		components: (EcoComponent | Partial<EcoComponent>)[],
 		currentIntegrationName: string,
@@ -307,13 +427,6 @@ export class RenderPreparationService {
 		return dependencies;
 	}
 
-	/**
-	 * Discovers integration names referenced by the component dependency graph.
-	 *
-	 * @param components Root component set.
-	 * @param seen Internal visited set for shared graphs.
-	 * @returns Set of integration names found in the graph.
-	 */
 	private collectIntegrationNames(
 		components: (EcoComponent | Partial<EcoComponent>)[],
 		seen = new Set<object>(),
@@ -348,38 +461,6 @@ export class RenderPreparationService {
 		return integrationNames;
 	}
 
-	/**
-	 * Renders the page root through the component-level render contract so any
-	 * integration-specific assets and root attributes are available before the main
-	 * document render.
-	 *
-	 * @param input Page root render inputs.
-	 * @returns Structured component render result.
-	 */
-	private async renderPageRoot(input: {
-		Page: EcoComponent;
-		props: Record<string, unknown>;
-		routeOptions: RouteRendererOptions;
-		callbacks: RenderPreparationCallbacks;
-	}): Promise<{ componentRender: ComponentRenderResult }> {
-		return {
-			componentRender: await input.callbacks.renderPageComponent({
-				component: input.Page,
-				props: {
-					...input.props,
-					params: input.routeOptions.params || {},
-					query: input.routeOptions.query || {},
-				},
-			}),
-		};
-	}
-
-	/**
-	 * Builds the runtime assets needed to bootstrap global lazy trigger execution.
-	 *
-	 * @param triggers Fully resolved lazy trigger definitions.
-	 * @returns Processed assets that should be merged into the final dependency set.
-	 */
 	private async buildGlobalInjectorAssets(
 		triggers: ResolvedLazyTrigger[],
 		currentIntegrationName: string,
@@ -403,7 +484,10 @@ export class RenderPreparationService {
 			bundle: true,
 		});
 
-		return this.assetProcessingService.processDependencies([mapScript, bootstrapInlineScript], currentIntegrationName);
+		return this.assetProcessingService.processDependencies(
+			[mapScript, bootstrapInlineScript],
+			currentIntegrationName,
+		);
 	}
 
 	private async buildEagerSsrLazyAssets(

package/src/route-renderer/page-loading/component-dependency-collection.ts

@@ -81,8 +81,14 @@ type CollectComponentDependenciesOptions = {
 export function collectComponentDependencies(
 	options: CollectComponentDependenciesOptions,
 ): CollectedComponentDependencies {
-	const { components, integrationName, resolveLazyScripts, createEcopagesJsxLazyEntryName, isEcopagesJsxIntegration, errors } =
-		options;
+	const {
+		components,
+		integrationName,
+		resolveLazyScripts,
+		createEcopagesJsxLazyEntryName,
+		isEcopagesJsxIntegration,
+		errors,
+	} = options;
 	const dependencies: AssetDefinition[] = [];
 	const lazyScriptsByConfig = new Map<NonNullable<EcoComponent['config']>, Map<string, LazyGroup>>();
 	const lazyDependencyKeys = new Set<string>();
@@ -193,4 +199,4 @@ export function collectComponentDependencies(
 		dependencies,
 		lazyScriptsByConfig,
 	};
-}
+}

package/src/route-renderer/page-loading/declared-asset-collection.ts

@@ -1,7 +1,4 @@
-import type {
-	EcoComponentScriptEntry,
-	EcoComponentStylesheetEntry,
-} from '../../types/public-types.ts';
+import type { EcoComponentScriptEntry, EcoComponentStylesheetEntry } from '../../types/public-types.ts';
 import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.ts';
 import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
 
@@ -153,4 +150,4 @@ export function collectDeclaredAssetEntries(options: CollectDeclaredAssetEntries
 			}),
 		);
 	}
-}
+}