@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,76 @@
+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

@@ -0,0 +1,93 @@
+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

@@ -0,0 +1,153 @@
+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

@@ -0,0 +1,61 @@
+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.js

@@ -0,0 +1,102 @@
+import { invariant } from "../utils/invariant.js";
+import { PageModuleImportService } from "../services/page-module-import.service.js";
+class PageModuleLoaderService {
+  constructor(appConfig, runtimeOrigin) {
+    this.appConfig = appConfig;
+    this.runtimeOrigin = runtimeOrigin;
+    this.pageModuleImportService = new PageModuleImportService();
+  }
+  pageModuleImportService;
+  /**
+   * Imports a page module from source.
+   * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
+   */
+  async importPageFile(file) {
+    try {
+      return await this.pageModuleImportService.importModule({
+        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) {
+    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: void 0
+    };
+  }
+  /**
+   * 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) {
+    const { getMetadata, context } = options;
+    let metadata = 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) {
+    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) {
+    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 ?? {}
+      }
+    });
+    return { props, metadata };
+  }
+}
+export {
+  PageModuleLoaderService
+};

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

@@ -0,0 +1,153 @@
+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 };
+	}
+}