@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.8

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -0,0 +1,372 @@
+/**
+ * This module contains the abstract class for the Integration Renderer
+ * Every integration renderer should extend this class
+ * @module
+ */
+import type { EcoPagesAppConfig, IHmrManager } from '../../internal-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentDependencies, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetMetadataContext, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../public-types.js';
+import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
+import { HttpError } from '../../errors/http-error.js';
+import { DependencyResolverService } from '../page-loading/dependency-resolver.js';
+import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
+import { MarkerGraphResolver } from '../component-graph/marker-graph-resolver.js';
+import { RenderExecutionService, type RenderExecutionGraphContext } from './render-execution.service.js';
+import { RenderPreparationService } from './render-preparation.service.js';
+import type { BoundaryRenderDecisionInput, ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
+export interface FinalizeCapturedHtmlRenderOptions {
+    html: string;
+    componentsToResolve: EcoComponent[];
+    graphContext: RenderExecutionGraphContext;
+    partial?: boolean;
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+    mergeAssets?: boolean;
+    transformHtml?: boolean;
+}
+/**
+ * Context for renderToResponse method.
+ */
+export interface RenderToResponseContext {
+    partial?: boolean;
+    status?: number;
+    headers?: HeadersInit;
+}
+/**
+ * The IntegrationRenderer class is an abstract class that provides a base for rendering integration-specific components in the EcoPages framework.
+ * It handles the import of page files, collection of dependencies, and preparation of render options.
+ * The class is designed to be extended by specific integration renderers.
+ */
+export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
+    abstract name: string;
+    protected appConfig: EcoPagesAppConfig;
+    protected assetProcessingService: AssetProcessingService;
+    protected htmlTransformer: HtmlTransformerService;
+    protected hmrManager?: IHmrManager;
+    protected resolvedIntegrationDependencies: ProcessedAsset[];
+    protected options: Required<IntegrationRendererRenderOptions>;
+    protected runtimeOrigin: string;
+    protected dependencyResolverService: DependencyResolverService;
+    protected pageModuleLoaderService: PageModuleLoaderService;
+    protected markerGraphResolver: MarkerGraphResolver;
+    protected renderPreparationService: RenderPreparationService;
+    protected renderExecutionService: RenderExecutionService;
+    protected DOC_TYPE: string;
+    setHmrManager(hmrManager: IHmrManager): void;
+    /**
+     * Build response headers with optional custom headers.
+     * @param contentType - The Content-Type header value
+     * @param customHeaders - Optional custom headers to merge
+     * @returns Headers object
+     */
+    protected buildHeaders(contentType: string, customHeaders?: HeadersInit): Headers;
+    /**
+     * Create an HTML Response.
+     * @param body - Response body (string or ReadableStream)
+     * @param ctx - Render context with status and headers
+     * @returns Response object
+     */
+    protected createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response;
+    /**
+     * Create an HttpError for render failures.
+     * @param message - Error message
+     * @param cause - Original error if available
+     * @returns HttpError with 500 status
+     */
+    protected createRenderError(message: string, cause?: unknown): HttpError;
+    /**
+     * Prepares dependencies for renderToResponse by resolving component dependencies
+     * and configuring the HTML transformer.
+     * @param view - The view component being rendered
+     * @param layout - Optional layout component
+     * @returns Resolved processed assets
+     */
+    protected prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
+    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, runtimeOrigin, }: {
+        appConfig: EcoPagesAppConfig;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies?: ProcessedAsset[];
+        runtimeOrigin: string;
+    });
+    /**
+     * Returns the HTML path from the provided file path.
+     * It extracts the path relative to the pages directory and removes the 'index' part if present.
+     *
+     * @param file - The file path to extract the HTML path from.
+     * @returns The extracted HTML path.
+     */
+    protected getHtmlPath({ file }: {
+        file: string;
+    }): string;
+    /**
+     * Returns the HTML template component.
+     * It imports the HTML template from the specified path in the app configuration.
+     *
+     * @returns The HTML template component.
+     */
+    protected getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+    /**
+     * Returns the static props for the page.
+     * It calls the provided getStaticProps function with the given options.
+     *
+     * @param getStaticProps - The function to get static props.
+     * @param options - The options to pass to the getStaticProps function.
+     * @returns The static props and metadata.
+     */
+    protected getStaticProps(getStaticProps?: GetStaticProps<Record<string, unknown>>, options?: Pick<RouteRendererOptions, 'params'>): Promise<{
+        props: Record<string, unknown>;
+        metadata?: PageMetadataProps;
+    }>;
+    /**
+     * Returns the metadata properties for the page.
+     * It calls the provided getMetadata function with the given context.
+     *
+     * @param getMetadata - The function to get metadata.
+     * @param context - The context to pass to the getMetadata function.
+     * @returns The metadata properties.
+     */
+    protected getMetadataProps(getMetadata: GetMetadata | undefined, { props, params, query }: GetMetadataContext): Promise<PageMetadataProps>;
+    /**
+     * Imports the page file from the specified path.
+     * It uses dynamic import to load the file and returns the imported module.
+     *
+     * @param file - The file path to import.
+     * @returns The imported module.
+     */
+    protected importPageFile(file: string): Promise<EcoPageFile>;
+    /**
+     * Resolves the dependency path based on the component directory.
+     * It combines the component directory with the provided path URL.
+     *
+     * @param componentDir - The component directory path.
+     * @param pathUrl - The path URL to resolve.
+     * @returns The resolved dependency path.
+     */
+    protected resolveDependencyPath(componentDir: string, pathUrl: string): string;
+    /**
+     * Extracts the dependencies from the provided component configuration.
+     * It resolves the paths for scripts and stylesheets based on the component directory.
+     *
+     * @param componentDir - The component directory path.
+     * @param scripts - The scripts to extract.
+     * @param stylesheets - The stylesheets to extract.
+     * @returns The extracted dependencies.
+     */
+    protected extractDependencies({ componentDir, scripts, stylesheets, }: {
+        componentDir: string;
+    } & EcoComponentDependencies): EcoComponentDependencies;
+    /**
+     * Resolves lazy script paths to public asset URLs.
+     * Converts source paths to their final bundled output paths.
+     *
+     * @param componentDir - The component directory path.
+     * @param scripts - The lazy script paths to resolve.
+     * @returns Comma-separated string of resolved public script paths.
+     */
+    protected resolveLazyScripts(componentDir: string, scripts: string[]): string;
+    /**
+     * Collects the dependencies for the provided components.
+     * Combines component-specific dependencies with global integration dependencies.
+     *
+     * @param components - The components to collect dependencies from.
+     */
+    protected resolveDependencies(components: (EcoComponent | Partial<EcoComponent>)[]): Promise<ProcessedAsset[]>;
+    /**
+     * Processes component-specific dependencies WITHOUT prepending global integration dependencies.
+     * Use this method when you need only the component's own assets.
+     *
+     * @param components - The components to collect dependencies from.
+     */
+    protected processComponentDependencies(components: (EcoComponent | Partial<EcoComponent>)[]): Promise<ProcessedAsset[]>;
+    /**
+     * Prepares the render options for the integration renderer.
+     * It imports the page file, collects dependencies, and prepares the render options.
+     *
+     * @param options - The route renderer options.
+     * @returns The prepared render options.
+     */
+    protected prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions>;
+    /**
+     * Controls whether the page root should be rendered through `renderComponent()`
+     * during route option preparation in component-capable modes.
+     *
+     * Integrations that already own page-level hydration (for example router-driven
+     * React rendering) can override this and return `false` to avoid duplicate root
+     * mount assets and competing hydration entrypoints.
+     */
+    protected shouldRenderPageComponent(_input: {
+        Page: EcoComponent;
+        Layout?: EcoComponent;
+        options: RouteRendererOptions;
+    }): boolean;
+    /**
+     * Resolves the page module and normalizes exports.
+     */
+    protected resolvePageModule(file: string): Promise<{
+        Page: EcoPageFile['default'] | EcoPageComponent<any>;
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        getMetadata?: GetMetadata;
+        integrationSpecificProps: Record<string, unknown>;
+    }>;
+    /**
+     * Resolves static props and metadata for the page.
+     */
+    protected resolvePageData(pageModule: {
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        getMetadata?: GetMetadata;
+    }, options: RouteRendererOptions): Promise<{
+        props: Record<string, unknown>;
+        metadata: PageMetadataProps;
+    }>;
+    /**
+     * Executes the integration renderer with the provided options.
+     *
+     * Execution flow:
+     * 1. Build normalized render options (`prepareRenderOptions`).
+     * 2. Render once inside component render context to capture marker graph refs.
+     * 3. Merge captured refs with optional explicit page-module graph context.
+     * 4. Resolve any `eco-marker` graph bottom-up and merge produced assets.
+     * 5. Optionally apply root attributes for page/component root boundaries.
+     * 6. Run HTML transformer with final dependency set.
+     *
+     * Stream-safety note: the first render result is normalized to a string once,
+     * then the pipeline continues with that immutable HTML value to avoid disturbed
+     * response-body errors.
+     *
+     * @param options Route renderer options.
+     * @returns Rendered route body plus effective cache strategy.
+     */
+    execute(options: RouteRendererOptions): Promise<RouteRenderResult>;
+    /**
+     * Captures a render pass as immutable HTML along with the graph context needed
+     * for deferred marker resolution.
+     *
+     * This is the shared entry point for direct `renderToResponse()` flows that
+     * need the same component graph capture semantics as route execution without
+     * going through `prepareRenderOptions()`.
+     */
+    protected captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<{
+        html: string;
+        graphContext: RenderExecutionGraphContext;
+    }>;
+    /**
+     * Finalizes previously captured HTML by resolving deferred markers, merging
+     * any emitted assets, stamping optional attributes, and optionally running the
+     * HTML transformer for full-document flows.
+     */
+    protected finalizeCapturedHtmlRender(options: FinalizeCapturedHtmlRenderOptions): Promise<string>;
+    /**
+     * Returns document-level attributes to stamp onto the rendered `<html>` tag.
+     *
+     * Integrations can override this to expose explicit document ownership or
+     * other runtime coordination markers without relying on script sniffing.
+     */
+    protected getDocumentAttributes(_renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    /**
+     * Resolves all `eco-marker` placeholders in rendered HTML using integration
+     * dispatch and bottom-up graph execution.
+     *
+     * Responsibility split:
+     * - core decodes markers into component refs, props, slot children, and target
+     *   integration dispatch
+     * - the selected integration renderer performs the actual component render via
+     *   `renderComponent()`
+     *
+     * Resolver callback behavior per marker:
+     * - resolve component definition by `componentRef`
+     * - resolve serialized props by `propsRef`
+     * - stitch resolved child HTML when `slotRef` is present
+     * - dispatch to target integration `renderComponent`
+     * - collect produced assets and apply root attributes when attachable
+     *
+     * @param options.html HTML that may still contain marker tokens.
+     * @param options.componentsToResolve Component set used to build component ref registry.
+     * @param options.graphContext Props/slot linkage captured during render.
+     * @returns Resolved HTML plus any component-scoped assets produced while resolving nodes.
+     * @throws Error when marker component refs or props refs cannot be resolved.
+     */
+    private resolveMarkerGraphHtml;
+    /**
+     * Returns a renderer instance for a given integration name.
+     *
+     * Uses a per-execution cache to avoid repeated renderer initialization.
+     *
+     * @param integrationName Target integration name.
+     * @param cache Render-pass renderer cache.
+     * @returns Renderer for the requested integration.
+     * @throws Error when no integration plugin matches `integrationName`.
+     */
+    private getIntegrationRendererForName;
+    /**
+     * Abstract method to render the integration-specific component.
+     * This method should be implemented by the specific integration renderer.
+     *
+     * @param options - The integration renderer render options.
+     * @returns The rendered body.
+     */
+    abstract render(options: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    /**
+     * Render a view directly to a Response object.
+     * Used for explicit routing where views are rendered from route handlers.
+     *
+     * @param view - The eco.page component to render
+     * @param props - Props to pass to the view
+     * @param ctx - Render context with partial flag and response options
+     * @returns A Response object with the rendered content
+     */
+    abstract renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+    /**
+     * Render a single component and return structured output for orchestration paths.
+     *
+     * Default behavior delegates to `renderToResponse` in partial mode and wraps
+     * the resulting HTML into the `ComponentRenderResult` contract.
+     *
+     * In marker resolution, this method is the integration-owned step that turns an
+     * already-resolved deferred boundary into concrete HTML, assets, and optional
+     * root attributes.
+     *
+     * Integrations can override this for richer behavior (asset emission,
+     * root attributes, integration-specific hydration metadata).
+     *
+     * @param input Component render request.
+     * @returns Structured render result used by marker/page orchestration.
+     */
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    /**
+     * Extracts the first root element tag name from HTML output.
+     *
+     * @param html HTML fragment.
+     * @returns Root tag name when present; otherwise `undefined`.
+     */
+    protected getRootTagName(html: string): string | undefined;
+    /**
+     * Method to build route render assets.
+     * This method can be optionally overridden by the specific integration renderer.
+     *
+     * @param file - The file path to build assets for.
+     * @returns The processed assets or undefined.
+     */
+    protected buildRouteRenderAssets(_file: string): Promise<ProcessedAsset[]> | undefined;
+    /**
+     * Builds the narrow boundary policy facade injected into component render
+     * context for this render pass.
+     *
+     * `eco.component()` consumes this facade without knowing about integration
+     * registries or plugin instances.
+     *
+     * @returns Boundary policy context for the active integration renderer.
+     */
+    protected getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
+    /**
+     * Resolves whether a component boundary should be deferred by consulting the
+     * target integration plugin.
+     *
+     * Boundaries targeting the current integration always render inline. Cross-
+     * integration boundaries delegate the decision to the target integration's
+     * `shouldDeferComponentBoundary()` policy.
+     *
+     * @param input Boundary metadata for the active render pass.
+     * @returns `true` when the boundary should emit a marker; otherwise `false`.
+     */
+    protected shouldDeferComponentBoundary(input: BoundaryRenderDecisionInput): boolean;
+}