@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

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

@@ -4,27 +4,23 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, PagePackageResult, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, 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 type { HtmlDocumentContribution } 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';
+import { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-pipeline/route-render-orchestrator.js';
+import { type ResolvedPageDependencies } from '../page-loading/resolved-page-dependencies.js';
+import { type GroupedGraphBuildPlan } from './page-browser-graph/grouped-graph-build-plan.js';
+import type { ForeignChildRuntime } from './foreign-child/component-render-context.js';
+import { ForeignSubtreeExecutionService } from './foreign-child/foreign-subtree-execution.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.
@@ -68,6 +64,24 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     private renderExclusiveChain;
     protected DOC_TYPE: string;
     private runRenderExclusive;
+    /**
+     * Activates the owning integration runtime on first render or graph use.
+     */
+    protected ensureIntegrationRuntimeActivated(): Promise<void>;
+    /**
+     * Prebuilds the production Page Browser Graph for one route file and optional params.
+     */
+    prebuildProductionPageBrowserGraph(routeFile: string, options?: Pick<RouteRendererOptions, 'params' | 'query'> & {
+        groupedBuildPlan?: GroupedGraphBuildPlan;
+    }): Promise<void>;
+    /**
+     * Builds one production grouped graph plan for the supplied static route instances.
+     */
+    buildGroupedGraphBuildPlan(instances: ReadonlyArray<{
+        routeFile: string;
+        params?: RouteRendererOptions['params'];
+        query?: RouteRendererOptions['query'];
+    }>): Promise<GroupedGraphBuildPlan>;
     /**
      * Loads one route module through the owning renderer's import path.
      *
@@ -77,34 +91,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * 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[];
@@ -124,10 +110,12 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response;
     /**
-     * Create an HttpError for render failures.
+     * Create an HttpError for unexpected render failures.
      * @param message - Error message
      * @param cause - Original error if available
-     * @returns HttpError with 500 status
+     * @returns The original HttpError when the cause is already one, otherwise a 500 HttpError
+     * @remarks HttpError from pages (for example NotFound from content lookup) must keep its
+     * status so the request matcher can serve a 404 instead of a 500.
      */
     protected createRenderError(message: string, cause?: unknown): HttpError;
     /**
@@ -139,7 +127,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
     protected resolvePageBrowserGraphForFile(filePath: string): Promise<PageBrowserGraphResult | undefined>;
-    protected mergePageBrowserGraphIntoPagePackage(pageBrowserGraph?: PageBrowserGraphResult): PageBrowserGraphResult | undefined;
+    protected resolvePageBrowserGraphForRoute(filePath: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>, groupedBuildPlan?: GroupedGraphBuildPlan): Promise<PageBrowserGraphResult | undefined>;
     /**
      * Merges component-scoped assets into the active HTML transformer state.
      *
@@ -199,6 +187,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         props: P;
         ctx: RenderToResponseContext;
         layout?: EcoComponent;
+        transformDocumentHtml?: (html: string) => string;
     }): Promise<Response>;
     /**
      * Renders a route page through optional layout and document shells.
@@ -227,31 +216,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         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.
@@ -264,16 +229,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         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.
@@ -281,12 +236,9 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @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.
@@ -301,27 +253,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @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.
@@ -346,20 +277,15 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected createRouteRenderOrchestratorAdapter(): RouteRenderOrchestratorAdapter<C>;
     protected resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
+    protected buildPageBrowserGraphContributionContext(routeFile: string, routeOptions?: Pick<RouteRendererOptions, 'params' | 'query'>): Promise<PageBrowserGraphContributionContext>;
+    protected resolvePageDependencies(context: PageBrowserGraphContributionContext): Promise<ResolvedPageDependencies | undefined>;
+    protected resolvePageBrowserGraphContributionFromDependencies(dependencies: EcoComponentDependencies, ownerFile: string): Promise<PageBrowserGraphContribution | undefined>;
     protected resolveRouteDependencies(input: {
         components: (EcoComponent | Partial<EcoComponent>)[];
     }): Promise<{
         resolvedDependencies: 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, htmlContributions?: HtmlDocumentContribution[], pagePackage?: PagePackageResult): Promise<RouteRendererBody>;
     /**
      * Prepares the render options for the integration renderer.
      * It imports the page file, collects dependencies, and prepares the render options.
@@ -368,19 +294,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @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.
      *
@@ -388,7 +301,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * 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.
+     * 4. Optionally apply document attributes for integration-owned document boundaries.
      * 5. Run HTML transformer with final dependency set.
      *
      * Stream-safety note: the first render result is normalized to a string once,
@@ -399,21 +312,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @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;
-        htmlContributions?: HtmlDocumentContribution[];
-    }): Promise<string>;
     /**
      * Returns document-level attributes to stamp onto the rendered `<html>` tag.
      *
@@ -421,6 +319,8 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * other runtime coordination markers without relying on script sniffing.
      */
     protected getDocumentAttributes(_renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    protected applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    protected applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
     /**
      * Returns declarative HTML fragments that core should inject into the final document.
      *
@@ -431,17 +331,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * response finalization logic.
      */
     protected getHtmlDocumentContributions(_options: HtmlDocumentContributionContext<C>): HtmlDocumentContribution[] | 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.
@@ -459,12 +348,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * 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>;
+    protected finalizeIslandComponentRender(input: ComponentRenderInput, result: ComponentRenderResult): ComponentRenderResult;
     private normalizeComponentRenderOutput;
     protected normalizeUnresolvedMarkerArtifactHtml(html: string): string;
     /**