npm - @ecopages/core - Versions diffs - 0.2.0-alpha.4 → 0.2.0-alpha.6 - Mend

@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (418) hide show

package/src/route-renderer/{integration-renderer.ts → orchestration/integration-renderer.ts} RENAMED Viewed

@@ -4,7 +4,7 @@
  * @module
  */
-import type { EcoPagesAppConfig, IHmrManager } from '../internal-types.ts';
+import type { EcoPagesAppConfig, IHmrManager } from '../../internal-types.ts';
 import type {
 	ComponentRenderInput,
 	ComponentRenderResult,
@@ -23,19 +23,35 @@ import type {
 	RouteRendererBody,
 	RouteRendererOptions,
 	RouteRenderResult,
-} from '../public-types.ts';
-import { type AssetProcessingService, type ProcessedAsset } from '../services/asset-processing-service/index.ts';
-import { HtmlTransformerService } from '../services/html-transformer.service.ts';
-import { invariant } from '../utils/invariant.ts';
-import { HttpError } from '../errors/http-error.ts';
-import { LocalsAccessError } from '../errors/locals-access-error.ts';
-import { DependencyResolverService } from './dependency-resolver.ts';
-import { HtmlPostProcessingService } from './html-post-processing.service.ts';
-import { PageModuleLoaderService } from './page-module-loader.ts';
-import { MarkerGraphResolver } from './marker-graph-resolver.ts';
+} from '../../public-types.ts';
+import {
+	type AssetProcessingService,
+	type ProcessedAsset,
+} from '../../services/assets/asset-processing-service/index.ts';
+import { HtmlTransformerService } from '../../services/html/html-transformer.service.ts';
+import { invariant } from '../../utils/invariant.ts';
+import { HttpError } from '../../errors/http-error.ts';
+import { LocalsAccessError } from '../../errors/locals-access-error.ts';
+import { DependencyResolverService } from '../page-loading/dependency-resolver.ts';
+import { PageModuleLoaderService } from '../page-loading/page-module-loader.ts';
+import { MarkerGraphResolver } from '../component-graph/marker-graph-resolver.ts';
 import { RenderExecutionService, type RenderExecutionGraphContext } from './render-execution.service.ts';
 import { RenderPreparationService } from './render-preparation.service.ts';
-import type { BoundaryRenderDecisionInput, ComponentRenderBoundaryContext } from '../eco/component-render-context.ts';
+import type {
+	BoundaryRenderDecisionInput,
+	ComponentRenderBoundaryContext,
+} from '../../eco/component-render-context.ts';
+export interface FinalizeCapturedHtmlRenderOptions {
+	html: string;
+	componentsToResolve: EcoComponent[];
+	graphContext: RenderExecutionGraphContext;
+	partial?: boolean;
+	componentRootAttributes?: Record<string, string>;
+	documentAttributes?: Record<string, string>;
+	mergeAssets?: boolean;
+	transformHtml?: boolean;
+}
 /**
  * Creates a Proxy that throws LocalsAccessError on any property access.
@@ -103,7 +119,6 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 	protected pageModuleLoaderService: PageModuleLoaderService;
 	protected markerGraphResolver: MarkerGraphResolver;
 	protected renderPreparationService: RenderPreparationService;
-	protected htmlPostProcessingService: HtmlPostProcessingService;
 	protected renderExecutionService: RenderExecutionService;
 	protected DOC_TYPE = '<!DOCTYPE html>';
@@ -164,7 +179,7 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 	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.htmlPostProcessingService.dedupeProcessedAssets(
+		const resolvedDependencies = this.htmlTransformer.dedupeProcessedAssets(
 			await this.resolveDependencies(componentsToResolve),
 		);
 		this.htmlTransformer.setProcessedDependencies(resolvedDependencies);
@@ -191,7 +206,6 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 		this.pageModuleLoaderService = new PageModuleLoaderService(appConfig, runtimeOrigin);
 		this.markerGraphResolver = new MarkerGraphResolver();
 		this.renderPreparationService = new RenderPreparationService(appConfig, assetProcessingService);
-		this.htmlPostProcessingService = new HtmlPostProcessingService();
 		this.renderExecutionService = new RenderExecutionService();
 	}
@@ -394,7 +408,7 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 				}),
 			getComponentRenderBoundaryContext: () => this.getComponentRenderBoundaryContext(),
 			setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
-			dedupeProcessedAssets: (assets) => this.htmlPostProcessingService.dedupeProcessedAssets(assets),
+			dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
 			createPageLocalsProxy: (filePath) =>
 				createLocalsProxy(filePath) as unknown as RouteRendererOptions['locals'],
 		});
@@ -480,11 +494,14 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 					componentsToResolve: input.componentsToResolve,
 					graphContext: input.graphContext,
 				}),
-			dedupeProcessedAssets: (assets) => this.htmlPostProcessingService.dedupeProcessedAssets(assets),
+			getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
+			dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
 			getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
 			setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
+			applyAttributesToHtmlElement: (html, attributes) =>
+				this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
 			applyAttributesToFirstBodyElement: (html, attributes) =>
-				this.htmlPostProcessingService.applyAttributesToFirstBodyElement(html, attributes),
+				this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes),
 			transformHtml: async (html) => {
 				const response = await this.htmlTransformer.transform(
 					new Response(html, {
@@ -498,6 +515,83 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 		});
 	}
+	/**
+	 * Captures a render pass as immutable HTML along with the graph context needed
+	 * for deferred marker resolution.
+	 *
+	 * 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()`.
+	 */
+	protected async captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<{
+		html: string;
+		graphContext: RenderExecutionGraphContext;
+	}> {
+		return this.renderExecutionService.captureHtmlRender(
+			this.name,
+			this.getComponentRenderBoundaryContext(),
+			render,
+		);
+	}
+	/**
+	 * Finalizes previously captured HTML by resolving deferred markers, merging
+	 * any emitted assets, stamping optional attributes, and optionally running the
+	 * HTML transformer for full-document flows.
+	 */
+	protected async finalizeCapturedHtmlRender(options: FinalizeCapturedHtmlRenderOptions): Promise<string> {
+		const finalization = await this.renderExecutionService.finalizeHtmlRender(
+			{
+				html: options.html,
+				graphContext: options.graphContext,
+				componentsToResolve: options.componentsToResolve,
+				componentRootAttributes: options.componentRootAttributes,
+				documentAttributes: options.documentAttributes,
+				mergeAssets: options.mergeAssets ?? !options.partial,
+			},
+			{
+				resolveMarkerGraphHtml: (input) =>
+					this.resolveMarkerGraphHtml({
+						html: input.html,
+						componentsToResolve: input.componentsToResolve,
+						graphContext: input.graphContext,
+					}),
+				dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+				getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
+				setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
+				applyAttributesToHtmlElement: (html, attributes) =>
+					this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
+				applyAttributesToFirstBodyElement: (html, attributes) =>
+					this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes),
+			},
+		);
+		const shouldTransform = options.transformHtml ?? !options.partial;
+		if (!shouldTransform) {
+			return finalization.html;
+		}
+		const transformedResponse = await this.htmlTransformer.transform(
+			new Response(finalization.html, {
+				headers: { 'Content-Type': 'text/html' },
+			}),
+		);
+		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;
+	}
 	/**
 	 * Resolves all `eco-marker` placeholders in rendered HTML using integration
 	 * dispatch and bottom-up graph execution.
@@ -534,7 +628,7 @@ export abstract class IntegrationRenderer<C = EcoPagesElement> {
 			resolveRenderer: (integrationName) =>
 				this.getIntegrationRendererForName(integrationName, integrationRendererCache),
 			applyAttributesToFirstElement: (html, attributes) =>
-				this.htmlPostProcessingService.applyAttributesToFirstElement(html, attributes),
+				this.htmlTransformer.applyAttributesToFirstElement(html, attributes),
 		});
 	}

package/src/route-renderer/orchestration/render-execution.service.test.ts ADDED Viewed

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getComponentRenderContext } from '../../eco/component-render-context.ts';
+import type { EcoComponent, IntegrationRendererRenderOptions, RouteRendererOptions } from '../../public-types.ts';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import { createComponentMarker } from '../component-graph/component-marker.ts';
+import { RenderExecutionService } from './render-execution.service.ts';
+describe('RenderExecutionService', () => {
+	it('should execute render flow, merge graph context, resolve markers, and apply root attributes', async () => {
+		const service = new RenderExecutionService();
+		const HtmlTemplate = (() => '<html></html>') as EcoComponent<Record<string, unknown>>;
+		const Page = (() => '<main>Page</main>') as EcoComponent<Record<string, unknown>>;
+		const asset = { kind: 'script', srcUrl: '/assets/nested.js', position: 'head' } as ProcessedAsset;
+		const setProcessedDependencies = vi.fn();
+		const dedupeProcessedAssets = vi.fn((assets: ProcessedAsset[]) => {
+			const seen = new Set<string>();
+			return assets.filter((entry) => {
+				const key = `${entry.kind}:${entry.srcUrl ?? ''}:${entry.position ?? ''}`;
+				if (seen.has(key)) {
+					return false;
+				}
+				seen.add(key);
+				return true;
+			});
+		});
+		const resolveMarkerGraphHtml = vi.fn(async (input) => {
+			expect(input.componentsToResolve).toEqual([HtmlTemplate, Page]);
+			expect(input.graphContext.propsByRef).toEqual({
+				captured: { count: 1 },
+				explicit: { count: 2 },
+			});
+			return {
+				html: '<html><body><main>Resolved</main></body></html>',
+				assets: [asset, asset],
+			};
+		});
+		const result = await service.execute(
+			{
+				file: '/app/pages/index.tsx',
+				params: {},
+				query: {},
+			} as unknown as RouteRendererOptions,
+			'ghtml',
+			{
+				prepareRenderOptions: async () =>
+					({
+						HtmlTemplate,
+						Page,
+						cacheStrategy: { revalidate: 60 },
+						componentRender: {
+							canAttachAttributes: true,
+							rootAttributes: { 'data-eco-component-id': 'eco-page-root' },
+						},
+						componentGraphContext: {
+							propsByRef: {
+								explicit: { count: 2 },
+							},
+						},
+					}) as unknown as IntegrationRendererRenderOptions<unknown>,
+				render: async () => {
+					const context = getComponentRenderContext();
+					if (context) {
+						context.propsByRef.captured = { count: 1 };
+					}
+					return `<html><body>${createComponentMarker({
+						nodeId: 'n_1',
+						integration: 'react',
+						componentRef: 'nested-component',
+						propsRef: 'captured',
+					})}</body></html>`;
+				},
+				getComponentRenderBoundaryContext: () => ({
+					decideBoundaryRender: () => 'inline',
+				}),
+				getDocumentAttributes: () => ({ 'data-eco-document-owner': 'react-router' }),
+				resolveMarkerGraphHtml,
+				dedupeProcessedAssets,
+				getProcessedDependencies: () => [asset],
+				setProcessedDependencies,
+				applyAttributesToHtmlElement: (html, attributes) =>
+					html.replace('<html', `<html data-eco-document-owner="${attributes['data-eco-document-owner']}"`),
+				applyAttributesToFirstBodyElement: (html, attributes) =>
+					html.replace('<main', `<main data-eco-component-id="${attributes['data-eco-component-id']}"`),
+				transformHtml: async (html) => html,
+			},
+		);
+		expect(result.cacheStrategy).toEqual({ revalidate: 60 });
+		expect(result.body).toContain('<html data-eco-document-owner="react-router"><body>');
+		expect(result.body).toContain('<main data-eco-component-id="eco-page-root">Resolved</main>');
+		expect(setProcessedDependencies).toHaveBeenCalledWith([asset]);
+		expect(dedupeProcessedAssets).toHaveBeenCalled();
+		expect(resolveMarkerGraphHtml).toHaveBeenCalledTimes(1);
+	});
+});

package/src/route-renderer/{render-execution.service.ts → orchestration/render-execution.service.ts} RENAMED Viewed

@@ -1,17 +1,16 @@
 import {
 	runWithComponentRenderContext,
 	type ComponentRenderBoundaryContext,
-	type ComponentGraphContext as CapturedComponentGraphContext,
-} from '../eco/component-render-context.ts';
+} from '../../eco/component-render-context.ts';
 import type {
 	EcoComponent,
 	IntegrationRendererRenderOptions,
 	RouteRendererBody,
 	RouteRendererOptions,
 	RouteRenderResult,
-} from '../public-types.ts';
-import type { ProcessedAsset } from '../services/asset-processing-service/index.ts';
-import type { MarkerGraphContext } from './marker-graph-resolver.ts';
+} from '../../public-types.ts';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import type { MarkerGraphContext } from '../component-graph/marker-graph-resolver.ts';
 /**
  * Serializable graph context merged from render-time captured references and
@@ -22,10 +21,25 @@ export type RenderExecutionGraphContext = {
 	slotChildrenByRef?: MarkerGraphContext['slotChildrenByRef'];
 };
+export interface CapturedHtmlRenderResult {
+	html: string;
+	graphContext: RenderExecutionGraphContext;
+}
+export interface FinalizeHtmlRenderOptions {
+	html: string;
+	graphContext: RenderExecutionGraphContext;
+	componentsToResolve: EcoComponent[];
+	componentRootAttributes?: Record<string, string>;
+	documentAttributes?: Record<string, string>;
+	mergeAssets?: boolean;
+}
 export interface RenderExecutionCallbacks<C> {
 	prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions<C>>;
 	render(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
 	getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
+	getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
 	resolveMarkerGraphHtml(input: {
 		html: string;
 		componentsToResolve: EcoComponent[];
@@ -34,10 +48,24 @@ export interface RenderExecutionCallbacks<C> {
 	dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
 	getProcessedDependencies(): ProcessedAsset[];
 	setProcessedDependencies(dependencies: ProcessedAsset[]): void;
+	applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
 	applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
 	transformHtml(html: string): Promise<RouteRendererBody>;
 }
+export interface FinalizeHtmlRenderCallbacks {
+	resolveMarkerGraphHtml(input: {
+		html: string;
+		componentsToResolve: EcoComponent[];
+		graphContext: RenderExecutionGraphContext;
+	}): Promise<{ html: string; assets: ProcessedAsset[] }>;
+	dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+	getProcessedDependencies(): ProcessedAsset[];
+	setProcessedDependencies(dependencies: ProcessedAsset[]): void;
+	applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+	applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+}
 /**
  * Executes the main post-preparation rendering flow for integration renderers.
  *
@@ -47,6 +75,25 @@ export interface RenderExecutionCallbacks<C> {
  * transformation into a response body stream.
  */
 export class RenderExecutionService {
+	async captureHtmlRender(
+		currentIntegrationName: string,
+		boundaryContext: ComponentRenderBoundaryContext,
+		render: () => Promise<RouteRendererBody>,
+	): Promise<CapturedHtmlRenderResult> {
+		const renderExecution = await runWithComponentRenderContext(
+			{
+				currentIntegration: currentIntegrationName,
+				boundaryContext,
+			},
+			render,
+		);
+		return {
+			html: await new Response(renderExecution.value as BodyInit).text(),
+			graphContext: renderExecution.graphContext,
+		};
+	}
 	/**
 	 * Executes one integration render pass and returns the final route render
 	 * result.
@@ -68,15 +115,12 @@ export class RenderExecutionService {
 			renderOptions.componentRender.rootAttributes &&
 			Object.keys(renderOptions.componentRender.rootAttributes).length > 0;
-		const renderExecution = await runWithComponentRenderContext(
-			{
-				currentIntegration: currentIntegrationName,
-				boundaryContext: callbacks.getComponentRenderBoundaryContext(),
-			},
+		const renderExecution = await this.captureHtmlRender(
+			currentIntegrationName,
+			callbacks.getComponentRenderBoundaryContext(),
 			async () => callbacks.render(renderOptions),
 		);
-		let renderedHtml = await new Response(renderExecution.value as BodyInit).text();
 		const componentGraphContext = this.mergeGraphContext(
 			renderExecution.graphContext,
 			(
@@ -85,32 +129,21 @@ export class RenderExecutionService {
 				}
 			).componentGraphContext,
 		);
-		if (renderedHtml.includes('<eco-marker')) {
-			const markerResolution = await callbacks.resolveMarkerGraphHtml({
-				html: renderedHtml,
-				componentsToResolve: this.getComponentsToResolve(renderOptions),
+		const finalization = await this.finalizeHtmlRender(
+			{
+				html: renderExecution.html,
 				graphContext: componentGraphContext,
-			});
-			renderedHtml = markerResolution.html;
-			if (markerResolution.assets.length > 0) {
-				const mergedDependencies = callbacks.dedupeProcessedAssets([
-					...callbacks.getProcessedDependencies(),
-					...markerResolution.assets,
-				]);
-				callbacks.setProcessedDependencies(mergedDependencies);
-			}
-		}
-		if (shouldApplyComponentRootAttributes) {
-			renderedHtml = callbacks.applyAttributesToFirstBodyElement(
-				renderedHtml,
-				renderOptions.componentRender?.rootAttributes as Record<string, string>,
-			);
-		}
+				componentsToResolve: this.getComponentsToResolve(renderOptions),
+				componentRootAttributes: shouldApplyComponentRootAttributes
+					? (renderOptions.componentRender?.rootAttributes as Record<string, string>)
+					: undefined,
+				documentAttributes: callbacks.getDocumentAttributes(renderOptions),
+				mergeAssets: true,
+			},
+			callbacks,
+		);
-		const body = await callbacks.transformHtml(renderedHtml);
+		const body = await callbacks.transformHtml(finalization.html);
 		return {
 			body,
@@ -126,8 +159,8 @@ export class RenderExecutionService {
 	 * @param explicitGraphContext Optional page-module graph metadata.
 	 * @returns Merged graph context used during marker resolution.
 	 */
-	private mergeGraphContext(
-		capturedGraphContext: CapturedComponentGraphContext,
+	mergeGraphContext(
+		capturedGraphContext: RenderExecutionGraphContext,
 		explicitGraphContext?: RenderExecutionGraphContext,
 	): RenderExecutionGraphContext {
 		return {
@@ -142,6 +175,45 @@ export class RenderExecutionService {
 		};
 	}
+	async finalizeHtmlRender(
+		options: FinalizeHtmlRenderOptions,
+		callbacks: FinalizeHtmlRenderCallbacks,
+	): Promise<{ html: string; assets: ProcessedAsset[] }> {
+		let renderedHtml = options.html;
+		let markerAssets: ProcessedAsset[] = [];
+		if (renderedHtml.includes('<eco-marker')) {
+			const markerResolution = await callbacks.resolveMarkerGraphHtml({
+				html: renderedHtml,
+				componentsToResolve: options.componentsToResolve,
+				graphContext: options.graphContext,
+			});
+			renderedHtml = markerResolution.html;
+			markerAssets = markerResolution.assets;
+			if (options.mergeAssets !== false && markerResolution.assets.length > 0) {
+				const mergedDependencies = callbacks.dedupeProcessedAssets([
+					...callbacks.getProcessedDependencies(),
+					...markerResolution.assets,
+				]);
+				callbacks.setProcessedDependencies(mergedDependencies);
+			}
+		}
+		if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
+			renderedHtml = callbacks.applyAttributesToFirstBodyElement(renderedHtml, options.componentRootAttributes);
+		}
+		if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
+			renderedHtml = callbacks.applyAttributesToHtmlElement(renderedHtml, options.documentAttributes);
+		}
+		return {
+			html: renderedHtml,
+			assets: markerAssets,
+		};
+	}
 	/**
 	 * Returns the component set that participates in marker graph resolution for a
 	 * render pass.