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

package/src/route-renderer/orchestration/render-execution.service.d.ts

@@ -1,103 +0,0 @@
-import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
-import type { EcoComponent, IntegrationRendererRenderOptions, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../public-types.js';
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { MarkerGraphContext } from '../component-graph/marker-graph-resolver.js';
-/**
- * Serializable graph context merged from render-time captured references and
- * optional explicit page-module graph metadata.
- */
-export type RenderExecutionGraphContext = {
-    propsByRef?: Record<string, Record<string, unknown>>;
-    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[];
-        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;
-    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.
- *
- * This service owns the orchestration that happens after normalized render
- * options have been prepared: the first render pass, graph-context capture,
- * deferred marker resolution, root-attribute application, and final HTML
- * transformation into a response body stream.
- */
-export declare class RenderExecutionService {
-    captureHtmlRender(currentIntegrationName: string, boundaryContext: ComponentRenderBoundaryContext, render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult>;
-    /**
-     * Executes one integration render pass and returns the final route render
-     * result.
-     *
-     * @typeParam C Integration render output element type.
-     * @param options Route-level render options.
-     * @param currentIntegrationName Active integration name for this render pass.
-     * @param callbacks Renderer-specific hooks required during execution.
-     * @returns Final route render output with body and cache strategy.
-     */
-    execute<C = unknown>(options: RouteRendererOptions, currentIntegrationName: string, callbacks: RenderExecutionCallbacks<C>): Promise<RouteRenderResult>;
-    /**
-     * Merges captured render-time graph references with any explicit graph context
-     * provided by the page module.
-     *
-     * @param capturedGraphContext Graph context captured from the first render pass.
-     * @param explicitGraphContext Optional page-module graph metadata.
-     * @returns Merged graph context used during marker resolution.
-     */
-    mergeGraphContext(capturedGraphContext: RenderExecutionGraphContext, explicitGraphContext?: RenderExecutionGraphContext): RenderExecutionGraphContext;
-    finalizeHtmlRender(options: FinalizeHtmlRenderOptions, callbacks: FinalizeHtmlRenderCallbacks): Promise<{
-        html: string;
-        assets: ProcessedAsset[];
-    }>;
-    /**
-     * Returns the component set that participates in marker graph resolution for a
-     * render pass.
-     *
-     * @typeParam C Integration render output element type.
-     * @param renderOptions Normalized render options for the pass.
-     * @returns Ordered component list for graph registry construction.
-     */
-    private getComponentsToResolve;
-}

package/src/route-renderer/orchestration/render-execution.service.js

@@ -1,121 +0,0 @@
-import {
-  runWithComponentRenderContext
-} from "../../eco/component-render-context.js";
-class RenderExecutionService {
-  async captureHtmlRender(currentIntegrationName, boundaryContext, render) {
-    const renderExecution = await runWithComponentRenderContext(
-      {
-        currentIntegration: currentIntegrationName,
-        boundaryContext
-      },
-      render
-    );
-    return {
-      html: await new Response(renderExecution.value).text(),
-      graphContext: renderExecution.graphContext
-    };
-  }
-  /**
-   * Executes one integration render pass and returns the final route render
-   * result.
-   *
-   * @typeParam C Integration render output element type.
-   * @param options Route-level render options.
-   * @param currentIntegrationName Active integration name for this render pass.
-   * @param callbacks Renderer-specific hooks required during execution.
-   * @returns Final route render output with body and cache strategy.
-   */
-  async execute(options, currentIntegrationName, callbacks) {
-    const renderOptions = await callbacks.prepareRenderOptions(options);
-    const shouldApplyComponentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0;
-    const renderExecution = await this.captureHtmlRender(
-      currentIntegrationName,
-      callbacks.getComponentRenderBoundaryContext(),
-      async () => callbacks.render(renderOptions)
-    );
-    const componentGraphContext = this.mergeGraphContext(
-      renderExecution.graphContext,
-      renderOptions.componentGraphContext
-    );
-    const finalization = await this.finalizeHtmlRender(
-      {
-        html: renderExecution.html,
-        graphContext: componentGraphContext,
-        componentsToResolve: this.getComponentsToResolve(renderOptions),
-        componentRootAttributes: shouldApplyComponentRootAttributes ? renderOptions.componentRender?.rootAttributes : void 0,
-        documentAttributes: callbacks.getDocumentAttributes(renderOptions),
-        mergeAssets: true
-      },
-      callbacks
-    );
-    const body = await callbacks.transformHtml(finalization.html);
-    return {
-      body,
-      cacheStrategy: renderOptions.cacheStrategy
-    };
-  }
-  /**
-   * Merges captured render-time graph references with any explicit graph context
-   * provided by the page module.
-   *
-   * @param capturedGraphContext Graph context captured from the first render pass.
-   * @param explicitGraphContext Optional page-module graph metadata.
-   * @returns Merged graph context used during marker resolution.
-   */
-  mergeGraphContext(capturedGraphContext, explicitGraphContext) {
-    return {
-      propsByRef: {
-        ...capturedGraphContext.propsByRef ?? {},
-        ...explicitGraphContext?.propsByRef ?? {}
-      },
-      slotChildrenByRef: {
-        ...capturedGraphContext.slotChildrenByRef ?? {},
-        ...explicitGraphContext?.slotChildrenByRef ?? {}
-      }
-    };
-  }
-  async finalizeHtmlRender(options, callbacks) {
-    let renderedHtml = options.html;
-    let markerAssets = [];
-    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.
-   *
-   * @typeParam C Integration render output element type.
-   * @param renderOptions Normalized render options for the pass.
-   * @returns Ordered component list for graph registry construction.
-   */
-  getComponentsToResolve(renderOptions) {
-    return renderOptions.Layout ? [renderOptions.HtmlTemplate, renderOptions.Layout, renderOptions.Page] : [renderOptions.HtmlTemplate, renderOptions.Page];
-  }
-}
-export {
-  RenderExecutionService
-};

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

@@ -1,230 +0,0 @@
-import {
-	runWithComponentRenderContext,
-	type ComponentRenderBoundaryContext,
-} from '../../eco/component-render-context.ts';
-import type {
-	EcoComponent,
-	IntegrationRendererRenderOptions,
-	RouteRendererBody,
-	RouteRendererOptions,
-	RouteRenderResult,
-} 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
- * optional explicit page-module graph metadata.
- */
-export type RenderExecutionGraphContext = {
-	propsByRef?: Record<string, Record<string, unknown>>;
-	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[];
-		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;
-	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.
- *
- * This service owns the orchestration that happens after normalized render
- * options have been prepared: the first render pass, graph-context capture,
- * deferred marker resolution, root-attribute application, and final HTML
- * 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.
-	 *
-	 * @typeParam C Integration render output element type.
-	 * @param options Route-level render options.
-	 * @param currentIntegrationName Active integration name for this render pass.
-	 * @param callbacks Renderer-specific hooks required during execution.
-	 * @returns Final route render output with body and cache strategy.
-	 */
-	async execute<C = unknown>(
-		options: RouteRendererOptions,
-		currentIntegrationName: string,
-		callbacks: RenderExecutionCallbacks<C>,
-	): Promise<RouteRenderResult> {
-		const renderOptions = await callbacks.prepareRenderOptions(options);
-		const shouldApplyComponentRootAttributes =
-			renderOptions.componentRender?.canAttachAttributes &&
-			renderOptions.componentRender.rootAttributes &&
-			Object.keys(renderOptions.componentRender.rootAttributes).length > 0;
-
-		const renderExecution = await this.captureHtmlRender(
-			currentIntegrationName,
-			callbacks.getComponentRenderBoundaryContext(),
-			async () => callbacks.render(renderOptions),
-		);
-
-		const componentGraphContext = this.mergeGraphContext(
-			renderExecution.graphContext,
-			(
-				renderOptions as IntegrationRendererRenderOptions<C> & {
-					componentGraphContext?: RenderExecutionGraphContext;
-				}
-			).componentGraphContext,
-		);
-		const finalization = await this.finalizeHtmlRender(
-			{
-				html: renderExecution.html,
-				graphContext: componentGraphContext,
-				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(finalization.html);
-
-		return {
-			body,
-			cacheStrategy: renderOptions.cacheStrategy,
-		};
-	}
-
-	/**
-	 * Merges captured render-time graph references with any explicit graph context
-	 * provided by the page module.
-	 *
-	 * @param capturedGraphContext Graph context captured from the first render pass.
-	 * @param explicitGraphContext Optional page-module graph metadata.
-	 * @returns Merged graph context used during marker resolution.
-	 */
-	mergeGraphContext(
-		capturedGraphContext: RenderExecutionGraphContext,
-		explicitGraphContext?: RenderExecutionGraphContext,
-	): RenderExecutionGraphContext {
-		return {
-			propsByRef: {
-				...(capturedGraphContext.propsByRef ?? {}),
-				...(explicitGraphContext?.propsByRef ?? {}),
-			},
-			slotChildrenByRef: {
-				...(capturedGraphContext.slotChildrenByRef ?? {}),
-				...(explicitGraphContext?.slotChildrenByRef ?? {}),
-			},
-		};
-	}
-
-	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.
-	 *
-	 * @typeParam C Integration render output element type.
-	 * @param renderOptions Normalized render options for the pass.
-	 * @returns Ordered component list for graph registry construction.
-	 */
-	private getComponentsToResolve<C>(renderOptions: IntegrationRendererRenderOptions<C>): EcoComponent[] {
-		return renderOptions.Layout
-			? [renderOptions.HtmlTemplate as EcoComponent, renderOptions.Layout as EcoComponent, renderOptions.Page]
-			: [renderOptions.HtmlTemplate as EcoComponent, renderOptions.Page];
-	}
-}

package/src/route-renderer/orchestration/render-preparation.service.d.ts

@@ -1,121 +0,0 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
-import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererOptions } from '../../public-types.js';
-import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
-type ResolvedPageModule = {
-    Page: EcoPageFile['default'] | EcoPageComponent<any>;
-    getStaticProps?: GetStaticProps<Record<string, unknown>>;
-    getMetadata?: GetMetadata;
-    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>;
-    /**
-     * Returns the boundary policy context that should be active while rendering
-     * page-root component output during preparation.
-     */
-    getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
-    setProcessedDependencies(dependencies: ProcessedAsset[]): void;
-    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
-    createPageLocalsProxy(filePath: string): RouteRendererOptions['locals'];
-}
-/**
- * Prepares the normalized render inputs consumed by `IntegrationRenderer.execute()`.
- *
- * 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.
- */
-export declare class RenderPreparationService {
-    private appConfig;
-    private assetProcessingService;
-    /**
-     * 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);
-    /**
-     * Builds the final render options object used by the integration-specific
-     * renderer.
-     *
-     * 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.
-     */
-    prepare<C = EcoPagesElement>(routeOptions: RouteRendererOptions, currentIntegrationName: string, callbacks: RenderPreparationCallbacks): Promise<IntegrationRendererRenderOptions<C>>;
-    /**
-     * 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.
-     */
-    private collectResolvedTriggers;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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 renderPageRoot;
-    /**
-     * 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 buildGlobalInjectorAssets;
-    private buildEagerSsrLazyAssets;
-    private collectEagerSsrLazyDependencies;
-}
-export {};