@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

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

@@ -0,0 +1,516 @@
+/**
+ * This module contains the abstract class for the Integration Renderer
+ * Every integration renderer should extend this class
+ * @module
+ */
+import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/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 { type RouteHtmlFinalization, RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
+import type { ForeignChildRuntime } from './component-render-context.js';
+import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer } from './foreign-subtree-execution.service.js';
+import { type QueuedForeignSubtreeResolutionContext } from './queued-foreign-subtree-resolution.service.js';
+/**
+ * Controls how one route module is loaded outside the normal render path.
+ *
+ * Request-time metadata inspection and static-generation probes use these
+ * options to isolate their module identity from the main render cache while
+ * still going through the owning integration's import setup.
+ */
+export type RouteModuleLoadOptions = {
+    bypassCache?: boolean;
+    cacheScope?: string;
+};
+/**
+ * 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 rendererModules?: unknown;
+    protected options: Required<IntegrationRendererRenderOptions>;
+    protected runtimeOrigin: string;
+    protected dependencyResolverService: DependencyResolverService;
+    protected pageModuleLoaderService: PageModuleLoaderService;
+    protected routeRenderOrchestrator: RouteRenderOrchestrator;
+    protected readonly foreignSubtreeExecutionService: ForeignSubtreeExecutionService;
+    protected DOC_TYPE: string;
+    /**
+     * Loads one route module through the owning renderer's import path.
+     *
+     * Request-time infrastructure may need page metadata such as cache strategy or
+     * middleware before full rendering starts. Exposing this narrow entrypoint lets
+     * those callers reuse integration-specific import setup instead of bypassing it
+     * with raw transpiler access.
+     */
+    loadPageModule(file: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
+    /**
+     * Reads the execution-scoped owning-renderer cache from one render input.
+     *
+     * Shared page/layout/document shell helpers pass one cache through
+     * `integrationContext` so repeated delegation to the same foreign integration
+     * can reuse a single initialized renderer instance during one render flow.
+     * The cache is deliberately scoped to the current render execution rather than
+     * stored on the renderer, which avoids leaking mutable integration state across
+     * requests while still preventing redundant renderer initialization.
+     *
+     * @param integrationContext - Optional render context carried with one render input.
+     * @returns The current execution cache when present.
+     */
+    private getOwningRendererCache;
+    private getForeignOwnerIntegrationName;
+    /**
+     * Attaches an execution-scoped owning-renderer cache to one render input.
+     *
+     * Foreign-owned page, layout, or document shells may delegate several times in
+     * the same render flow. Threading the cache through `integrationContext`
+     * preserves renderer reuse without changing the public render input contract.
+     * Existing integration-specific context is preserved and augmented.
+     *
+     * @param input - Original render input.
+     * @param rendererCache - Execution-scoped renderer cache to propagate.
+     * @returns Render input augmented with the shared renderer cache.
+     */
+    private withOwningRendererCache;
+    protected getRendererModuleValue(key: string): unknown;
+    protected getRendererModuleString(key: string): string | undefined;
+    protected getRendererBootstrapDependencies(partial?: boolean): ProcessedAsset[];
+    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[]>;
+    /**
+     * Merges component-scoped assets into the active HTML transformer state.
+     *
+     * Explicit page, layout, and document shell composition can produce assets at
+     * each foreign subtree. This helper deduplicates those groups and folds them back into
+     * the transformer so downstream HTML finalization sees one canonical asset set.
+     *
+     * @param assetGroups - Optional groups of processed assets to merge.
+     * @returns The deduplicated asset subset contributed by this merge operation.
+     */
+    protected appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+    /**
+     * Resolves metadata for explicit view rendering.
+     *
+     * When a view declares a `metadata()` function, that contract owns the final
+     * metadata for the explicit render. Otherwise the app-level default metadata is
+     * reused so explicit routes and page-module routes share the same fallback.
+     *
+     * @param view - View component being rendered.
+     * @param props - Props passed to the view.
+     * @returns Resolved metadata for the final document shell.
+     */
+    protected resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps>;
+    /**
+     * Renders one explicit view response in partial mode.
+     *
+     * Same-integration views can optionally stream or render inline via the caller's
+     * `renderInline()` hook. Once a view may cross integration boundaries, this
+     * helper routes the render through `renderComponentWithForeignChildren()` instead so mixed
+     * shells can reuse the execution-scoped renderer cache and resolve nested
+     * foreign ownership before the partial response is returned.
+     *
+     * @param input - View render options for the partial response.
+     * @returns HTML response for the partial render.
+     */
+    protected renderPartialViewResponse<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        renderInline?: () => Promise<BodyInit>;
+        transformHtml?: (html: string) => string;
+    }): Promise<Response>;
+    /**
+     * Renders an explicit view through optional layout and document shells.
+     *
+     * This helper is the shared explicit-route path for string-oriented and mixed
+     * integrations. It prepares view dependencies, resolves metadata, and composes
+     * view, layout, and html template boundaries with one execution-scoped renderer
+     * cache so repeated foreign shell delegation can reuse initialized renderers
+     * during the same render flow.
+     *
+     * @param input - View, props, and optional layout metadata for the render.
+     * @returns HTML response for the explicit view render.
+     */
+    protected renderViewWithDocumentShell<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        layout?: EcoComponent;
+    }): Promise<Response>;
+    /**
+     * Renders a route page through optional layout and document shells.
+     *
+     * Route rendering and explicit view rendering now share the same renderer-owned
+     * shell composition model. This helper composes page, layout, and html template
+     * renders while threading one execution-scoped renderer cache through every
+     * delegated foreign subtree so foreign shell ownership remains stable and renderer
+     * initialization is reused inside the current request.
+     *
+     * @param input - Page, layout, document, and metadata inputs for the route render.
+     * @returns Final serialized document HTML including the doctype prefix.
+     */
+    protected renderPageWithDocumentShell(input: {
+        page: {
+            component: EcoComponent;
+            props: Record<string, unknown>;
+        };
+        layout?: {
+            component: EcoComponent;
+            props?: Record<string, unknown>;
+        };
+        htmlTemplate: EcoComponent;
+        metadata: PageMetadataProps;
+        pageProps: Record<string, unknown>;
+        documentProps?: Record<string, unknown>;
+        transformDocumentHtml?: (html: string) => string;
+    }): Promise<string>;
+    private composeDocumentShell;
+    /**
+     * Renders one string-first component with serialized children and collects its assets.
+     *
+     * String-oriented integrations frequently share the same component contract:
+     * pass serialized children through props, coerce the render result to HTML, and
+     * attach any component-scoped dependencies. This helper centralizes that flow
+     * so integrations can opt into shared orchestration without repeating the same
+     * string-render boilerplate.
+     *
+     * @param input - Component render input.
+     * @param component - String-oriented component implementation to execute.
+     * @returns Structured component render result for orchestration paths.
+     */
+    protected renderStringComponentWithSerializedChildren(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
+    protected getForeignSubtreeTokenPrefix(): string;
+    protected getForeignSubtreeResolutionContextKey(): string;
+    protected createQueuedForeignSubtreeExecutionRuntime<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+        runtimeContextKey?: string;
+        tokenPrefix?: string;
+        createRuntimeContext?: (integrationContext: BaseIntegrationContext & Record<string, unknown>, rendererCache: Map<string, unknown>) => TContext;
+    }): ForeignChildRuntime;
+    protected getQueuedForeignSubtreeResolutionContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput): TContext | undefined;
+    /**
+     * Renders a string-first component, then resolves any queued foreign
+     * boundaries before returning final component HTML.
+     */
+    protected renderStringComponentWithQueuedForeignSubtrees(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
+    constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, rendererModules, runtimeOrigin, }: {
+        appConfig: EcoPagesAppConfig;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies?: ProcessedAsset[];
+        rendererModules?: unknown;
+        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>>;
+    protected usesIntegrationPageImporter(_file: string): boolean;
+    protected importIntegrationPageFile(_file: string, _options?: RouteModuleLoadOptions): Promise<EcoPageFile>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(_file: string, pageModule: TPageModule): TPageModule;
+    /**
+     * 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, options?: RouteModuleLoadOptions): 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[]>;
+    /**
+     * Builds the internal route-render adapter consumed by `RouteRenderOrchestrator`.
+     *
+     * The route orchestrator needs a narrow orchestration contract, but those hooks should
+     * not become public API on the renderer base class. Keeping the adapter object
+     * local to the execution path lets the orchestrator depend on one explicit seam while
+     * subclasses continue to override protected renderer behavior directly.
+     */
+    protected createRouteRenderOrchestratorAdapter(): RouteRenderOrchestratorAdapter<C>;
+    protected resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    protected resolveRouteAssets(input: {
+        routeOptions: RouteRendererOptions;
+        components: (EcoComponent | Partial<EcoComponent>)[];
+    }): Promise<{
+        resolvedDependencies: ProcessedAsset[];
+        pageBrowserGraph?: {
+            assets: ProcessedAsset[];
+        };
+    }>;
+    protected resolveRoutePageComponentRender(input: {
+        Page: EcoComponent;
+        Layout?: EcoComponent;
+        props: Record<string, unknown>;
+        routeOptions: RouteRendererOptions;
+    }): Promise<ComponentRenderResult | undefined>;
+    protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
+    protected transformRouteResponse(response: Response): Promise<RouteRendererBody>;
+    /**
+     * 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, adapter?: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
+    /**
+     * 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;
+    /**
+     * Executes the integration renderer with the provided options.
+     *
+     * Execution flow:
+     * 1. Build normalized render options (`prepareRenderOptions`).
+     * 2. Render the route body once.
+     * 3. Reject unresolved route-level eco-marker artifacts.
+     * 4. Optionally apply root attributes for page/component root boundaries.
+     * 5. 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>;
+    /**
+     * Finalizes already-resolved HTML for explicit renderer-owned paths.
+     *
+     * This keeps document and root-attribute stamping plus HTML transformation
+     * available after a renderer has completed nested foreign-subtree resolution without
+     * routing back through shared route execution.
+     */
+    protected finalizeResolvedHtml(options: {
+        html: string;
+        partial?: boolean;
+        componentRootAttributes?: Record<string, string>;
+        documentAttributes?: Record<string, string>;
+        transformHtml?: boolean;
+    }): 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;
+    /**
+     * 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`.
+     */
+    protected getIntegrationRendererForName(integrationName: string, cache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    /**
+     * 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>;
+    /**
+     * Renders one component under this integration's foreign-child runtime and resolves
+     * any nested foreign children captured during that render.
+     *
+     * Without this wrapper, a component tree with foreign-owned descendants would
+     * render them with no active foreign-child runtime, which bypasses the owning
+     * renderer's nested foreign-child handoff.
+     */
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    /**
+     * Compatibility foreign-subtree contract that exposes a narrower payload shape for
+     * future route-composition work while preserving the current
+     * `renderComponentWithForeignChildren()` runtime semantics.
+     */
+    renderForeignSubtree(input: ComponentRenderInput): Promise<ForeignSubtreeRenderPayload>;
+    private normalizeComponentRenderOutput;
+    protected normalizeUnresolvedMarkerArtifactHtml(html: string): string;
+    /**
+     * Returns whether the component dependency tree crosses into another
+     * integration.
+     *
+     * This keeps foreign-child runtime setup narrow: same-integration trees can render
+     * directly without paying the queue orchestration cost.
+     */
+    protected hasForeignChildDescendants(component: EcoComponent): boolean;
+    /**
+     * 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 foreign-subtree resolution, this method is the integration-owned step that turns an
+     * already-resolved deferred foreign subtree 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 component/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;
+    /**
+     * Builds the Page Browser Graph owned by this integration for one Page.
+     * This method can be optionally overridden by the specific integration renderer.
+     *
+     * @param file - The file path to build assets for.
+     * @returns The structured Page Browser Graph or undefined.
+     */
+    protected buildPageBrowserGraph(_file: string): Promise<{
+        assets: ProcessedAsset[];
+    } | undefined>;
+    /**
+     * Creates the per-render foreign-child runtime adopted by the shared component
+     * render context.
+     *
+     * The default runtime queues delegated foreign subtrees inside the owning
+     * renderer so string and markup renderers do not need to re-declare the same
+     * handoff boilerplate. Override only when a renderer needs custom runtime
+     * context or a different foreign-child execution strategy.
+     */
+    protected createForeignChildRuntime(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): ForeignChildRuntime;
+    /**
+     * Creates an explicit fail-fast runtime for tests or renderers that do not
+     * support cross-integration foreign-child execution.
+     */
+    protected createFailFastForeignChildRuntime(): ForeignChildRuntime;
+}