@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.20

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

@@ -1,76 +0,0 @@
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent } from '../public-types.js';
-import type { ProcessedAsset } from '../services/asset-processing-service/index.js';
-import type { MarkerNodeId } from './component-marker.js';
-/**
- * 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 declare 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.
-     */
-    resolve(options: MarkerGraphResolverOptions): Promise<{
-        html: string;
-        assets: ProcessedAsset[];
-    }>;
-    /**
-     * 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;
-}

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

@@ -1,93 +0,0 @@
-import { extractComponentGraph } from "./component-graph.js";
-import { resolveComponentGraph } from "./component-graph-executor.js";
-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) {
-    const registry = this.buildComponentRefRegistry(options.componentsToResolve);
-    const graph = extractComponentGraph(options.html, options.graphContext.slotChildrenByRef ?? {});
-    const resolvedNodeHtml = /* @__PURE__ */ new Map();
-    const assets = [];
-    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;
-      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.
-   */
-  buildComponentRefRegistry(components) {
-    const registry = /* @__PURE__ */ new Map();
-    const stack = [...components];
-    const seen = /* @__PURE__ */ new Set();
-    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;
-  }
-}
-export {
-  MarkerGraphResolver
-};

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.d.ts

@@ -1,69 +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/asset-processing-service/index.js';
-import type { MarkerGraphContext } from './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 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 declare 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.
-     */
-    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.
-     */
-    private mergeGraphContext;
-    /**
-     * 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;
-}