@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/route-renderer/marker-graph-resolver.ts

@@ -1,153 +0,0 @@
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent } from '../public-types.ts';
-import type { ProcessedAsset } from '../services/asset-processing-service/index.ts';
-import type { MarkerNodeId } from './component-marker.ts';
-import { extractComponentGraph } from './component-graph.ts';
-import { resolveComponentGraph } from './component-graph-executor.ts';
-
-/**
- * Serializable graph-context payload used during post-render marker resolution.
- *
- * `propsByRef` stores serialized props captured during the first render pass,
- * while `slotChildrenByRef` preserves parent-child marker relationships for
- * slot-like composition.
- */
-export type MarkerGraphContext = {
-	propsByRef?: Record<string, Record<string, unknown>>;
-	slotChildrenByRef?: Record<string, MarkerNodeId[]>;
-};
-
-/**
- * Minimal renderer contract needed for deferred component resolution.
- *
- * The marker graph resolver intentionally depends only on component-level render
- * capabilities, not on the full integration renderer abstraction.
- */
-export interface MarkerGraphComponentRenderer {
-	renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-}
-
-export interface MarkerGraphResolverOptions {
-	html: string;
-	componentsToResolve: EcoComponent[];
-	graphContext: MarkerGraphContext;
-	resolveRenderer: (integrationName: string) => MarkerGraphComponentRenderer;
-	applyAttributesToFirstElement: (html: string, attributes: Record<string, string>) => string;
-}
-
-/**
- * Resolves deferred `eco-marker` tokens after the first render pass.
- *
- * This service owns the second-stage orchestration for cross-integration
- * component rendering. It builds a component reference registry, constructs a
- * deterministic marker DAG, resolves leaf nodes before parents, and collects any
- * component-level assets emitted during that process.
- *
- * Responsibility split:
- * - core resolves marker structure, refs, child ordering, and renderer dispatch
- * - the target integration renderer resolves the actual component render through
- *   `renderComponent()` once the marker has been decoded into component input
- */
-export class MarkerGraphResolver {
-	/**
-	 * Resolves every marker in the supplied HTML and returns the final HTML plus
-	 * any assets produced by nested component renders.
-	 *
-	 * The resolver is intentionally fail-fast: missing component refs or props refs
-	 * indicate a broken render graph and should surface immediately instead of
-	 * producing partial output.
-	 *
-	 * The resolver does not render integration-specific HTML itself. Instead, it
-	 * reconstructs `ComponentRenderInput` from the marker payload and then delegates
-	 * the actual rendering to the target integration renderer.
-	 *
-	 * @param options Marker graph resolution inputs for one render pass.
-	 * @returns Resolved HTML and collected component assets.
-	 */
-	async resolve(options: MarkerGraphResolverOptions): Promise<{ html: string; assets: ProcessedAsset[] }> {
-		const registry = this.buildComponentRefRegistry(options.componentsToResolve);
-		const graph = extractComponentGraph(options.html, options.graphContext.slotChildrenByRef ?? {});
-		const resolvedNodeHtml = new Map<MarkerNodeId, string>();
-		const assets: ProcessedAsset[] = [];
-
-		const resolvedHtml = await resolveComponentGraph(options.html, graph, async (marker) => {
-			const component = registry.get(marker.componentRef);
-			if (!component) {
-				throw new Error(`[ecopages] Missing component reference for marker: ${marker.componentRef}`);
-			}
-
-			const props = options.graphContext.propsByRef?.[marker.propsRef];
-			if (!props) {
-				throw new Error(`[ecopages] Missing props reference for marker: ${marker.propsRef}`);
-			}
-
-			let children: string | undefined;
-			if (marker.slotRef) {
-				const childNodeIds = options.graphContext.slotChildrenByRef?.[marker.slotRef] ?? [];
-				if (childNodeIds.length > 0) {
-					children = childNodeIds.map((childNodeId) => resolvedNodeHtml.get(childNodeId) ?? '').join('');
-				}
-			}
-
-			const renderer = options.resolveRenderer(marker.integration);
-			const componentRender = await renderer.renderComponent({
-				component,
-				props,
-				children,
-			});
-
-			if (componentRender.assets?.length) {
-				assets.push(...componentRender.assets);
-			}
-
-			const htmlWithAttributes =
-				componentRender.canAttachAttributes && componentRender.rootAttributes
-					? options.applyAttributesToFirstElement(componentRender.html, componentRender.rootAttributes)
-					: componentRender.html;
-
-			resolvedNodeHtml.set(marker.nodeId, htmlWithAttributes);
-			return { html: htmlWithAttributes };
-		});
-
-		return {
-			html: resolvedHtml,
-			assets,
-		};
-	}
-
-	/**
-	 * Builds a reference registry from the root component set and all nested
-	 * declared component dependencies.
-	 *
-	 * Component refs are keyed by `__eco.id` when available, falling back to
-	 * `__eco.file`. Traversal is depth-first and deduplicated by component
-	 * identity to remain stable in shared dependency graphs.
-	 *
-	 * @param components Root components participating in resolution.
-	 * @returns Lookup table from component ref to component definition.
-	 */
-	private buildComponentRefRegistry(components: EcoComponent[]): Map<string, EcoComponent> {
-		const registry = new Map<string, EcoComponent>();
-		const stack = [...components];
-		const seen = new Set<EcoComponent>();
-
-		while (stack.length > 0) {
-			const current = stack.pop();
-			if (!current || seen.has(current)) {
-				continue;
-			}
-			seen.add(current);
-
-			const ref = current.config?.__eco?.id ?? current.config?.__eco?.file;
-			if (ref) {
-				registry.set(ref, current);
-			}
-
-			const nested = current.config?.dependencies?.components ?? [];
-			for (const component of nested) {
-				stack.push(component);
-			}
-		}
-
-		return registry;
-	}
-}

package/src/route-renderer/page-module-loader.d.ts

@@ -1,61 +0,0 @@
-import type { EcoPageFile, GetMetadata, GetMetadataContext, GetStaticProps, PageMetadataProps, RouteRendererOptions, EcoPageComponent } from '../public-types.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
-/**
- * Handles page module loading plus static props/metadata resolution.
- */
-export declare class PageModuleLoaderService {
-    private appConfig;
-    private runtimeOrigin;
-    private pageModuleImportService;
-    constructor(appConfig: EcoPagesAppConfig, runtimeOrigin: string);
-    /**
-     * Imports a page module from source.
-     * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
-     */
-    importPageFile(file: string): Promise<EcoPageFile>;
-    /**
-     * Executes `getStaticProps` with Ecopages runtime context.
-     * Returns an empty props object when no static props function is defined.
-     */
-    getStaticPropsForPage(options: {
-        getStaticProps?: GetStaticProps<Record<string, unknown>>;
-        params?: RouteRendererOptions['params'];
-    }): Promise<{
-        props: Record<string, unknown>;
-        metadata?: PageMetadataProps;
-    }>;
-    /**
-     * Builds final page metadata using app-level defaults as a baseline.
-     * If `getMetadata` exists, its result overlays defaults so page-level fields take precedence.
-     */
-    getMetadataPropsForPage(options: {
-        getMetadata: GetMetadata | undefined;
-        context: GetMetadataContext;
-    }): Promise<PageMetadataProps>;
-    /**
-     * Loads a page module and normalizes integration-facing exports.
-     * When both component static methods and module exports exist, component statics win.
-     */
-    resolvePageModule(options: {
-        file: string;
-        importPageFileFn?: (file: string) => Promise<EcoPageFile>;
-    }): Promise<{
-        Page: EcoPageFile['default'] | EcoPageComponent<any>;
-        getStaticProps?: GetStaticProps<Record<string, unknown>>;
-        getMetadata?: GetMetadata;
-        integrationSpecificProps: Record<string, unknown>;
-    }>;
-    /**
-     * Resolves render-time page data in order: static props first, then metadata derived from those props.
-     */
-    resolvePageData(options: {
-        pageModule: {
-            getStaticProps?: GetStaticProps<Record<string, unknown>>;
-            getMetadata?: GetMetadata;
-        };
-        routeOptions: RouteRendererOptions;
-    }): Promise<{
-        props: Record<string, unknown>;
-        metadata: PageMetadataProps;
-    }>;
-}

package/src/route-renderer/page-module-loader.ts

@@ -1,153 +0,0 @@
-import { invariant } from '../utils/invariant.ts';
-import type {
-	EcoPageFile,
-	GetMetadata,
-	GetMetadataContext,
-	GetStaticProps,
-	PageMetadataProps,
-	RouteRendererOptions,
-	EcoPageComponent,
-} from '../public-types.ts';
-import type { EcoPagesAppConfig } from '../internal-types.ts';
-import { PageModuleImportService } from '../services/page-module-import.service.ts';
-
-/**
- * Handles page module loading plus static props/metadata resolution.
- */
-export class PageModuleLoaderService {
-	private pageModuleImportService: PageModuleImportService;
-
-	constructor(
-		private appConfig: EcoPagesAppConfig,
-		private runtimeOrigin: string,
-	) {
-		this.pageModuleImportService = new PageModuleImportService();
-	}
-
-	/**
-	 * Imports a page module from source.
-	 * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
-	 */
-	async importPageFile(file: string): Promise<EcoPageFile> {
-		try {
-			return await this.pageModuleImportService.importModule<EcoPageFile>({
-				filePath: file,
-				rootDir: this.appConfig.rootDir,
-				outdir: `${this.appConfig.absolutePaths.distDir}/.server-modules`,
-				transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
-				noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
-			});
-		} catch (error) {
-			invariant(false, `Error importing page file: ${error}`);
-		}
-	}
-
-	/**
-	 * Executes `getStaticProps` with Ecopages runtime context.
-	 * Returns an empty props object when no static props function is defined.
-	 */
-	async getStaticPropsForPage(options: {
-		getStaticProps?: GetStaticProps<Record<string, unknown>>;
-		params?: RouteRendererOptions['params'];
-	}): Promise<{
-		props: Record<string, unknown>;
-		metadata?: PageMetadataProps;
-	}> {
-		const { getStaticProps, params } = options;
-		return getStaticProps
-			? await getStaticProps({
-					pathname: { params: params ?? {} },
-					appConfig: this.appConfig,
-					runtimeOrigin: this.runtimeOrigin,
-				})
-					.then((data) => data)
-					.catch((err) => {
-						throw new Error(`Error fetching static props: ${err.message}`);
-					})
-			: {
-					props: {},
-					metadata: undefined,
-				};
-	}
-
-	/**
-	 * Builds final page metadata using app-level defaults as a baseline.
-	 * If `getMetadata` exists, its result overlays defaults so page-level fields take precedence.
-	 */
-	async getMetadataPropsForPage(options: {
-		getMetadata: GetMetadata | undefined;
-		context: GetMetadataContext;
-	}): Promise<PageMetadataProps> {
-		const { getMetadata, context } = options;
-		let metadata: PageMetadataProps = this.appConfig.defaultMetadata;
-		if (getMetadata) {
-			const dynamicMetadata = await getMetadata({
-				params: context.params,
-				query: context.query,
-				props: context.props,
-				appConfig: this.appConfig,
-			});
-			metadata = { ...metadata, ...dynamicMetadata };
-		}
-		return metadata;
-	}
-
-	/**
-	 * Loads a page module and normalizes integration-facing exports.
-	 * When both component static methods and module exports exist, component statics win.
-	 */
-	async resolvePageModule(options: {
-		file: string;
-		importPageFileFn?: (file: string) => Promise<EcoPageFile>;
-	}): Promise<{
-		Page: EcoPageFile['default'] | EcoPageComponent<any>;
-		getStaticProps?: GetStaticProps<Record<string, unknown>>;
-		getMetadata?: GetMetadata;
-		integrationSpecificProps: Record<string, unknown>;
-	}> {
-		const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
-		const {
-			default: Page,
-			getStaticProps: moduleGetStaticProps,
-			getMetadata: moduleGetMetadata,
-			...integrationSpecificProps
-		} = module;
-
-		return {
-			Page,
-			getStaticProps: Page.staticProps ?? moduleGetStaticProps,
-			getMetadata: Page.metadata ?? moduleGetMetadata,
-			integrationSpecificProps,
-		};
-	}
-
-	/**
-	 * Resolves render-time page data in order: static props first, then metadata derived from those props.
-	 */
-	async resolvePageData(options: {
-		pageModule: {
-			getStaticProps?: GetStaticProps<Record<string, unknown>>;
-			getMetadata?: GetMetadata;
-		};
-		routeOptions: RouteRendererOptions;
-	}): Promise<{
-		props: Record<string, unknown>;
-		metadata: PageMetadataProps;
-	}> {
-		const { props } = await this.getStaticPropsForPage({
-			getStaticProps: options.pageModule.getStaticProps,
-			params: options.routeOptions.params,
-		});
-
-		const metadata = await this.getMetadataPropsForPage({
-			getMetadata: options.pageModule.getMetadata,
-			context: {
-				props,
-				params: options.routeOptions.params ?? {},
-				query: options.routeOptions.query ?? {},
-			} as GetMetadataContext,
-		});
-
-		return { props, metadata };
-	}
-}

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

@@ -1,91 +0,0 @@
-import {
-  runWithComponentRenderContext
-} from "../eco/component-render-context.js";
-class RenderExecutionService {
-  /**
-   * 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 runWithComponentRenderContext(
-      {
-        currentIntegration: currentIntegrationName,
-        boundaryContext: callbacks.getComponentRenderBoundaryContext()
-      },
-      async () => callbacks.render(renderOptions)
-    );
-    let renderedHtml = await new Response(renderExecution.value).text();
-    const componentGraphContext = this.mergeGraphContext(
-      renderExecution.graphContext,
-      renderOptions.componentGraphContext
-    );
-    if (renderedHtml.includes("<eco-marker")) {
-      const markerResolution = await callbacks.resolveMarkerGraphHtml({
-        html: renderedHtml,
-        componentsToResolve: this.getComponentsToResolve(renderOptions),
-        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
-      );
-    }
-    const body = await callbacks.transformHtml(renderedHtml);
-    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 ?? {}
-      }
-    };
-  }
-  /**
-   * 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/render-execution.service.ts

@@ -1,158 +0,0 @@
-import {
-	runWithComponentRenderContext,
-	type ComponentRenderBoundaryContext,
-	type ComponentGraphContext as CapturedComponentGraphContext,
-} 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';
-
-/**
- * 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 RenderExecutionCallbacks<C> {
-	prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions<C>>;
-	render(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
-	getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
-	resolveMarkerGraphHtml(input: {
-		html: string;
-		componentsToResolve: EcoComponent[];
-		graphContext: RenderExecutionGraphContext;
-	}): Promise<{ html: string; assets: ProcessedAsset[] }>;
-	dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
-	getProcessedDependencies(): ProcessedAsset[];
-	setProcessedDependencies(dependencies: ProcessedAsset[]): void;
-	applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
-	transformHtml(html: string): Promise<RouteRendererBody>;
-}
-
-/**
- * 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 {
-	/**
-	 * 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 runWithComponentRenderContext(
-			{
-				currentIntegration: currentIntegrationName,
-				boundaryContext: callbacks.getComponentRenderBoundaryContext(),
-			},
-			async () => callbacks.render(renderOptions),
-		);
-
-		let renderedHtml = await new Response(renderExecution.value as BodyInit).text();
-		const componentGraphContext = this.mergeGraphContext(
-			renderExecution.graphContext,
-			(
-				renderOptions as IntegrationRendererRenderOptions<C> & {
-					componentGraphContext?: RenderExecutionGraphContext;
-				}
-			).componentGraphContext,
-		);
-
-		if (renderedHtml.includes('<eco-marker')) {
-			const markerResolution = await callbacks.resolveMarkerGraphHtml({
-				html: renderedHtml,
-				componentsToResolve: this.getComponentsToResolve(renderOptions),
-				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>,
-			);
-		}
-
-		const body = await callbacks.transformHtml(renderedHtml);
-
-		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.
-	 */
-	private mergeGraphContext(
-		capturedGraphContext: CapturedComponentGraphContext,
-		explicitGraphContext?: RenderExecutionGraphContext,
-	): RenderExecutionGraphContext {
-		return {
-			propsByRef: {
-				...(capturedGraphContext.propsByRef ?? {}),
-				...(explicitGraphContext?.propsByRef ?? {}),
-			},
-			slotChildrenByRef: {
-				...(capturedGraphContext.slotChildrenByRef ?? {}),
-				...(explicitGraphContext?.slotChildrenByRef ?? {}),
-			},
-		};
-	}
-
-	/**
-	 * 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];
-	}
-}