@ecopages/core 0.2.0-alpha.11 → 0.2.0-alpha.13

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

@@ -10,20 +10,14 @@ import { HtmlTransformerService } from '../../services/html/html-transformer.ser
 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 { RenderExecutionService } 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;
-}
+import type { ComponentBoundaryRuntime } from './component-render-context.js';
+import { QueuedBoundaryRuntimeService, type QueuedBoundaryResolution, type QueuedBoundaryRuntimeContext } from './queued-boundary-runtime.service.js';
+type BoundaryRenderDecisionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+};
 /**
  * Context for renderToResponse method.
  */
@@ -49,10 +43,38 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected runtimeOrigin: string;
     protected dependencyResolverService: DependencyResolverService;
     protected pageModuleLoaderService: PageModuleLoaderService;
-    protected markerGraphResolver: MarkerGraphResolver;
     protected renderPreparationService: RenderPreparationService;
     protected renderExecutionService: RenderExecutionService;
+    protected readonly queuedBoundaryRuntimeService: QueuedBoundaryRuntimeService;
     protected DOC_TYPE: string;
+    /**
+     * Reads the execution-scoped foreign renderer cache from one boundary 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 boundary context carried with one render input.
+     * @returns The current execution cache when present.
+     */
+    private getBoundaryRendererCache;
+    private getRegisteredBoundaryOwner;
+    /**
+     * Attaches an execution-scoped foreign renderer cache to one boundary 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 boundary input contract.
+     * Existing integration-specific context is preserved and augmented.
+     *
+     * @param input - Original boundary render input.
+     * @param rendererCache - Execution-scoped renderer cache to propagate.
+     * @returns Boundary input augmented with the shared renderer cache.
+     */
+    private withBoundaryRendererCache;
     protected getRendererModuleValue(key: string): unknown;
     protected getRendererModuleString(key: string): string | undefined;
     protected getRendererBootstrapDependencies(partial?: boolean): ProcessedAsset[];
@@ -86,6 +108,139 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @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 boundary. 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 `renderComponentBoundary()` 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 boundary-owned
+     * shell composition model. This helper composes page, layout, and html template
+     * boundaries while threading one execution-scoped renderer cache through every
+     * delegated boundary 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>;
+    /**
+     * Renders one string-first component boundary and collects its assets.
+     *
+     * String-oriented integrations frequently share the same boundary 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
+     * boundary boilerplate.
+     *
+     * @param input - Boundary render input.
+     * @param component - String-oriented component implementation to execute.
+     * @returns Structured component render result for orchestration paths.
+     */
+    protected renderStringComponentBoundary(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
+    protected getBoundaryTokenPrefix(): string;
+    protected getBoundaryRuntimeContextKey(): string;
+    protected getQueuedBoundaryRuntime<TContext extends QueuedBoundaryRuntimeContext>(input: ComponentRenderInput, runtimeContextKey?: string): TContext | undefined;
+    protected resolveQueuedBoundaryTokens(html: string, queuedResolutionsByToken: Map<string, QueuedBoundaryResolution>, resolveToken: (token: string) => Promise<string>): Promise<string>;
+    protected createQueuedBoundaryRuntime<TContext extends QueuedBoundaryRuntimeContext>(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+        runtimeContextKey?: string;
+        tokenPrefix?: string;
+        createRuntimeContext?: (integrationContext: {
+            rendererCache?: Map<string, unknown>;
+            componentInstanceId?: string;
+            [key: string]: unknown;
+        }, rendererCache: Map<string, unknown>) => TContext;
+    }): ComponentBoundaryRuntime;
+    protected resolveRendererOwnedQueuedBoundaryHtml<TContext extends QueuedBoundaryRuntimeContext>(options: {
+        html: string;
+        runtimeContext?: TContext;
+        queueLabel: string;
+        renderQueuedChildren: (children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedBoundaryResolution>, resolveToken: (token: string) => Promise<string>) => Promise<{
+            assets: ProcessedAsset[];
+            html?: string;
+        }>;
+    }): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
+    /**
+     * Renders a string-first component, then resolves any queued foreign
+     * boundaries before returning final component HTML.
+     */
+    protected renderStringComponentBoundaryWithQueuedForeignBoundaries(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
     constructor({ appConfig, assetProcessingService, resolvedIntegrationDependencies, rendererModules, runtimeOrigin, }: {
         appConfig: EcoPagesAppConfig;
         assetProcessingService: AssetProcessingService;
@@ -231,11 +386,10 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      *
      * 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.
+     * 2. Render the route body once.
+     * 3. Reject unresolved route-level boundary 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
@@ -246,23 +400,19 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     execute(options: RouteRendererOptions): Promise<RouteRenderResult>;
     /**
-     * Captures a render pass as immutable HTML along with the graph context needed
-     * for deferred marker resolution.
+     * Finalizes already-resolved HTML for explicit renderer-owned paths.
      *
-     * 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()`.
+     * This keeps document and root-attribute stamping plus HTML transformation
+     * available after a renderer has completed nested boundary resolution without
+     * routing back through shared route execution.
      */
-    protected captureHtmlRender(render: () => Promise<RouteRendererBody>): Promise<{
+    protected finalizeResolvedHtml(options: {
         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>;
+        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.
      *
@@ -270,30 +420,6 @@ 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;
-    /**
-     * 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.
      *
@@ -313,17 +439,26 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns The rendered body.
      */
     abstract render(options: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    protected resolveBoundaryInOwningRenderer(input: ComponentRenderInput, rendererCache: Map<string, IntegrationRenderer<any>>): Promise<ComponentRenderResult | undefined>;
+    /**
+     * Renders one component under this integration's boundary runtime and resolves
+     * any nested foreign boundaries captured during that render.
+     *
+     * Without this wrapper, a component tree with foreign-owned descendants would
+     * render them with no active boundary runtime, which bypasses the owning
+     * renderer's nested-boundary handoff.
+     */
+    renderComponentBoundary(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    private normalizeComponentBoundaryRender;
+    protected normalizeBoundaryArtifactHtml(html: string): string;
     /**
-     * Renders one deferred marker-graph node under this integration's boundary
-     * context so nested cross-integration children can continue to defer while the
-     * graph is being resolved bottom-up.
+     * Returns whether the component dependency tree crosses into another
+     * integration.
      *
-     * Without this wrapper, resolving a deferred React or Kita node would render
-     * any nested foreign components with no active render context, causing them to
-     * fall back to inline escaped HTML instead of emitting the next marker layer.
+     * This keeps boundary-runtime setup narrow: same-integration trees can render
+     * directly without paying the queue orchestration cost.
      */
-    renderComponentForMarkerGraph(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    protected shouldWrapMarkerGraphComponent(component: EcoComponent): boolean;
+    protected hasForeignBoundaryDescendants(component: EcoComponent): boolean;
     /**
      * Render a view directly to a Response object.
      * Used for explicit routing where views are rendered from route handlers.
@@ -340,7 +475,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * 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
+     * In boundary resolution, this method is the integration-owned step that turns an
      * already-resolved deferred boundary into concrete HTML, assets, and optional
      * root attributes.
      *
@@ -348,7 +483,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * root attributes, integration-specific hydration metadata).
      *
      * @param input Component render request.
-     * @returns Structured render result used by marker/page orchestration.
+     * @returns Structured render result used by component/page orchestration.
      */
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
     /**
@@ -367,25 +502,28 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     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.
+     * Creates the per-render boundary runtime adopted by the shared component
+     * render context.
      *
-     * @returns Boundary policy context for the active integration renderer.
+     * Real mixed-integration renderers should override this and keep foreign
+     * boundary resolution inside their own renderer-owned queue. The base runtime
+     * fails fast when a renderer crosses into a foreign owner without providing its
+     * own handoff mechanism.
      */
-    protected getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
+    protected createComponentBoundaryRuntime(_options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): ComponentBoundaryRuntime;
     /**
-     * Resolves whether a component boundary should be deferred by consulting the
-     * target integration plugin.
+     * Resolves whether a boundary should leave the current render pass and be
+     * resolved by its owning renderer.
      *
-     * Boundaries targeting the current integration always render inline. Cross-
-     * integration boundaries delegate the decision to the target integration's
-     * `shouldDeferComponentBoundary()` policy.
+     * Boundaries owned by the current integration always render inline. Foreign-
+     * owned boundaries must be handed off by a renderer-owned runtime.
      *
      * @param input Boundary metadata for the active render pass.
-     * @returns `true` when the boundary should emit a marker; otherwise `false`.
+     * @returns `true` when the boundary should leave the current pass; otherwise `false`.
      */
-    protected shouldDeferComponentBoundary(input: BoundaryRenderDecisionInput): boolean;
+    protected shouldResolveBoundaryInOwningRenderer(input: BoundaryRenderDecisionInput): boolean;
 }
+export {};