npm - @ecopages/core - Versions diffs - 0.2.0-alpha.7 → 0.2.0-alpha.8 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (354) hide show

package/src/route-renderer/orchestration/integration-renderer.js ADDED Viewed

@@ -0,0 +1,589 @@
+import {
+} from "../../services/assets/asset-processing-service/index.js";
+import { HtmlTransformerService } from "../../services/html/html-transformer.service.js";
+import { invariant } from "../../utils/invariant.js";
+import { HttpError } from "../../errors/http-error.js";
+import { LocalsAccessError } from "../../errors/locals-access-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 } from "./render-execution.service.js";
+import { RenderPreparationService } from "./render-preparation.service.js";
+function createLocalsProxy(filePath) {
+  const errorMessage = `[ecopages] Request locals are only available during request-time rendering with cache: 'dynamic'. Page: ${filePath}. If you meant to use locals here, set cache: 'dynamic' and provide locals from route middleware/handlers.`;
+  return new Proxy(
+    {},
+    {
+      get: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      set: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      has: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      ownKeys: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      deleteProperty: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      defineProperty: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      getOwnPropertyDescriptor: () => {
+        throw new LocalsAccessError(errorMessage);
+      }
+    }
+  );
+}
+class IntegrationRenderer {
+  appConfig;
+  assetProcessingService;
+  htmlTransformer;
+  hmrManager;
+  resolvedIntegrationDependencies = [];
+  runtimeOrigin;
+  dependencyResolverService;
+  pageModuleLoaderService;
+  markerGraphResolver;
+  renderPreparationService;
+  renderExecutionService;
+  DOC_TYPE = "<!DOCTYPE html>";
+  setHmrManager(hmrManager) {
+    this.hmrManager = hmrManager;
+    if (this.assetProcessingService) {
+      this.assetProcessingService.setHmrManager(hmrManager);
+    }
+  }
+  /**
+   * Build response headers with optional custom headers.
+   * @param contentType - The Content-Type header value
+   * @param customHeaders - Optional custom headers to merge
+   * @returns Headers object
+   */
+  buildHeaders(contentType, customHeaders) {
+    const headers = new Headers({ "Content-Type": contentType });
+    if (customHeaders) {
+      const incoming = new Headers(customHeaders);
+      incoming.forEach((value, key) => headers.set(key, value));
+    }
+    return headers;
+  }
+  /**
+   * Create an HTML Response.
+   * @param body - Response body (string or ReadableStream)
+   * @param ctx - Render context with status and headers
+   * @returns Response object
+   */
+  createHtmlResponse(body, ctx) {
+    return new Response(body, {
+      status: ctx.status ?? 200,
+      headers: this.buildHeaders("text/html; charset=utf-8", ctx.headers)
+    });
+  }
+  /**
+   * Create an HttpError for render failures.
+   * @param message - Error message
+   * @param cause - Original error if available
+   * @returns HttpError with 500 status
+   */
+  createRenderError(message, cause) {
+    const errorMessage = cause instanceof Error ? `${message}: ${cause.message}` : message;
+    return HttpError.InternalServerError(errorMessage);
+  }
+  /**
+   * 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
+   */
+  async prepareViewDependencies(view, layout) {
+    const HtmlTemplate = await this.getHtmlTemplate();
+    const componentsToResolve = layout ? [HtmlTemplate, layout, view] : [HtmlTemplate, view];
+    const resolvedDependencies = this.htmlTransformer.dedupeProcessedAssets(
+      await this.resolveDependencies(componentsToResolve)
+    );
+    this.htmlTransformer.setProcessedDependencies(resolvedDependencies);
+    return resolvedDependencies;
+  }
+  constructor({
+    appConfig,
+    assetProcessingService,
+    resolvedIntegrationDependencies,
+    runtimeOrigin
+  }) {
+    this.appConfig = appConfig;
+    this.assetProcessingService = assetProcessingService;
+    this.htmlTransformer = new HtmlTransformerService();
+    this.resolvedIntegrationDependencies = resolvedIntegrationDependencies || [];
+    this.runtimeOrigin = runtimeOrigin;
+    this.dependencyResolverService = new DependencyResolverService(appConfig, assetProcessingService);
+    this.pageModuleLoaderService = new PageModuleLoaderService(appConfig, runtimeOrigin);
+    this.markerGraphResolver = new MarkerGraphResolver();
+    this.renderPreparationService = new RenderPreparationService(appConfig, assetProcessingService);
+    this.renderExecutionService = new RenderExecutionService();
+  }
+  /**
+   * 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.
+   */
+  getHtmlPath({ file }) {
+    const pagesDir = this.appConfig.absolutePaths.pagesDir;
+    const pagesIndex = file.indexOf(pagesDir);
+    if (pagesIndex === -1) return file;
+    const startIndex = file.indexOf(pagesDir) + pagesDir.length;
+    const endIndex = file.lastIndexOf("/");
+    const path = file.substring(startIndex, endIndex);
+    if (path === "/index") return "";
+    return path;
+  }
+  /**
+   * Returns the HTML template component.
+   * It imports the HTML template from the specified path in the app configuration.
+   *
+   * @returns The HTML template component.
+   */
+  async getHtmlTemplate() {
+    const { absolutePaths } = this.appConfig;
+    try {
+      const { default: HtmlTemplate } = await this.importPageFile(absolutePaths.htmlTemplatePath);
+      return HtmlTemplate;
+    } catch (error) {
+      invariant(false, `Error importing HtmlTemplate: ${error}`);
+    }
+  }
+  /**
+   * 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.
+   */
+  async getStaticProps(getStaticProps, options) {
+    return this.pageModuleLoaderService.getStaticPropsForPage({
+      getStaticProps,
+      params: options?.params
+    });
+  }
+  /**
+   * 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.
+   */
+  async getMetadataProps(getMetadata, { props, params, query }) {
+    return this.pageModuleLoaderService.getMetadataPropsForPage({
+      getMetadata,
+      context: { props, params, query }
+    });
+  }
+  /**
+   * 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.
+   */
+  async importPageFile(file) {
+    return this.pageModuleLoaderService.importPageFile(file);
+  }
+  /**
+   * 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.
+   */
+  resolveDependencyPath(componentDir, pathUrl) {
+    return this.dependencyResolverService.resolveDependencyPath(componentDir, pathUrl);
+  }
+  /**
+   * 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.
+   */
+  extractDependencies({
+    componentDir,
+    scripts,
+    stylesheets
+  }) {
+    const scriptsPaths = [
+      ...new Set(
+        (scripts ?? []).filter((script) => typeof script === "string" ? true : !script.lazy).map((script) => typeof script === "string" ? script : script.src).filter((script) => Boolean(script)).map((script) => this.resolveDependencyPath(componentDir, script))
+      )
+    ];
+    const stylesheetsPaths = [
+      ...new Set(
+        (stylesheets ?? []).map((style) => typeof style === "string" ? style : style.src).filter((style) => Boolean(style)).map((style) => this.resolveDependencyPath(componentDir, style))
+      )
+    ];
+    return {
+      scripts: scriptsPaths,
+      stylesheets: stylesheetsPaths
+    };
+  }
+  /**
+   * 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.
+   */
+  resolveLazyScripts(componentDir, scripts) {
+    return this.dependencyResolverService.resolveLazyScripts(componentDir, scripts);
+  }
+  /**
+   * Collects the dependencies for the provided components.
+   * Combines component-specific dependencies with global integration dependencies.
+   *
+   * @param components - The components to collect dependencies from.
+   */
+  async resolveDependencies(components) {
+    const componentDeps = await this.processComponentDependencies(components);
+    return this.resolvedIntegrationDependencies.concat(componentDeps);
+  }
+  /**
+   * 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.
+   */
+  async processComponentDependencies(components) {
+    return this.dependencyResolverService.processComponentDependencies(components, this.name);
+  }
+  /**
+   * 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.
+   */
+  async prepareRenderOptions(options) {
+    return this.renderPreparationService.prepare(options, this.name, {
+      resolvePageModule: (file) => this.resolvePageModule(file),
+      getHtmlTemplate: () => this.getHtmlTemplate(),
+      resolvePageData: (pageModule, routeOptions) => this.resolvePageData(pageModule, routeOptions),
+      resolveDependencies: (components) => this.resolveDependencies(components),
+      buildRouteRenderAssets: (file) => this.buildRouteRenderAssets(file),
+      shouldRenderPageComponent: (input) => this.shouldRenderPageComponent(input),
+      renderPageComponent: ({ component, props }) => this.renderComponent({
+        component,
+        props,
+        integrationContext: {
+          componentInstanceId: "eco-page-root"
+        }
+      }),
+      getComponentRenderBoundaryContext: () => this.getComponentRenderBoundaryContext(),
+      setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+      createPageLocalsProxy: (filePath) => createLocalsProxy(filePath)
+    });
+  }
+  /**
+   * 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.
+   */
+  shouldRenderPageComponent(_input) {
+    return true;
+  }
+  /**
+   * Resolves the page module and normalizes exports.
+   */
+  async resolvePageModule(file) {
+    return this.pageModuleLoaderService.resolvePageModule({
+      file,
+      importPageFileFn: (targetFile) => this.importPageFile(targetFile)
+    });
+  }
+  /**
+   * Resolves static props and metadata for the page.
+   */
+  async resolvePageData(pageModule, options) {
+    return this.pageModuleLoaderService.resolvePageData({
+      pageModule,
+      routeOptions: options
+    });
+  }
+  /**
+   * 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.
+   */
+  async execute(options) {
+    return this.renderExecutionService.execute(options, this.name, {
+      prepareRenderOptions: (routeOptions) => this.prepareRenderOptions(routeOptions),
+      render: (renderOptions) => this.render(renderOptions),
+      getComponentRenderBoundaryContext: () => this.getComponentRenderBoundaryContext(),
+      resolveMarkerGraphHtml: (input) => this.resolveMarkerGraphHtml({
+        html: input.html,
+        componentsToResolve: input.componentsToResolve,
+        graphContext: input.graphContext
+      }),
+      getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+      getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
+      setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
+      applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
+      applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes),
+      transformHtml: async (html) => {
+        const response = await this.htmlTransformer.transform(
+          new Response(html, {
+            headers: {
+              "Content-Type": "text/html"
+            }
+          })
+        );
+        return response.body;
+      }
+    });
+  }
+  /**
+   * 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()`.
+   */
+  async captureHtmlRender(render) {
+    return this.renderExecutionService.captureHtmlRender(
+      this.name,
+      this.getComponentRenderBoundaryContext(),
+      render
+    );
+  }
+  /**
+   * 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.
+   */
+  async finalizeCapturedHtmlRender(options) {
+    const finalization = await this.renderExecutionService.finalizeHtmlRender(
+      {
+        html: options.html,
+        graphContext: options.graphContext,
+        componentsToResolve: options.componentsToResolve,
+        componentRootAttributes: options.componentRootAttributes,
+        documentAttributes: options.documentAttributes,
+        mergeAssets: options.mergeAssets ?? !options.partial
+      },
+      {
+        resolveMarkerGraphHtml: (input) => this.resolveMarkerGraphHtml({
+          html: input.html,
+          componentsToResolve: input.componentsToResolve,
+          graphContext: input.graphContext
+        }),
+        dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+        getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
+        setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
+        applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
+        applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes)
+      }
+    );
+    const shouldTransform = options.transformHtml ?? !options.partial;
+    if (!shouldTransform) {
+      return finalization.html;
+    }
+    const transformedResponse = await this.htmlTransformer.transform(
+      new Response(finalization.html, {
+        headers: { "Content-Type": "text/html" }
+      })
+    );
+    return await transformedResponse.text();
+  }
+  /**
+   * 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.
+   */
+  getDocumentAttributes(_renderOptions) {
+    return void 0;
+  }
+  /**
+   * 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.
+   */
+  async resolveMarkerGraphHtml(options) {
+    const integrationRendererCache = /* @__PURE__ */ new Map();
+    return this.markerGraphResolver.resolve({
+      html: options.html,
+      componentsToResolve: options.componentsToResolve,
+      graphContext: options.graphContext,
+      resolveRenderer: (integrationName) => this.getIntegrationRendererForName(integrationName, integrationRendererCache),
+      applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes)
+    });
+  }
+  /**
+   * 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`.
+   */
+  getIntegrationRendererForName(integrationName, cache) {
+    if (cache.has(integrationName)) {
+      return cache.get(integrationName);
+    }
+    if (integrationName === this.name) {
+      cache.set(integrationName, this);
+      return this;
+    }
+    const integrationPlugin = this.appConfig.integrations.find(
+      (integration) => integration.name === integrationName
+    );
+    invariant(!!integrationPlugin, `[ecopages] Integration not found for marker: ${integrationName}`);
+    const renderer = integrationPlugin.initializeRenderer();
+    cache.set(integrationName, renderer);
+    return renderer;
+  }
+  /**
+   * 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.
+   */
+  async renderComponent(input) {
+    const response = await this.renderToResponse(
+      input.component,
+      input.props,
+      { partial: true }
+    );
+    const html = await response.text();
+    return {
+      html,
+      canAttachAttributes: true,
+      rootTag: this.getRootTagName(html),
+      integrationName: this.name
+    };
+  }
+  /**
+   * Extracts the first root element tag name from HTML output.
+   *
+   * @param html HTML fragment.
+   * @returns Root tag name when present; otherwise `undefined`.
+   */
+  getRootTagName(html) {
+    const rootTag = html.match(/^\s*<([a-zA-Z][a-zA-Z0-9:-]*)\b/);
+    return rootTag?.[1];
+  }
+  /**
+   * 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.
+   */
+  buildRouteRenderAssets(_file) {
+    return void 0;
+  }
+  /**
+   * 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.
+   */
+  getComponentRenderBoundaryContext() {
+    return {
+      decideBoundaryRender: (input) => this.shouldDeferComponentBoundary(input) ? "defer" : "inline"
+    };
+  }
+  /**
+   * 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`.
+   */
+  shouldDeferComponentBoundary(input) {
+    if (!input.targetIntegration || input.targetIntegration === input.currentIntegration) {
+      return false;
+    }
+    const targetIntegration = this.appConfig.integrations.find(
+      (integration) => integration.name === input.targetIntegration
+    );
+    invariant(
+      !!targetIntegration,
+      `[ecopages] Integration not found for component boundary: ${input.targetIntegration}`
+    );
+    return targetIntegration.shouldDeferComponentBoundary({
+      currentIntegration: input.currentIntegration,
+      targetIntegration: input.targetIntegration,
+      component: input.component
+    });
+  }
+}
+export {
+  IntegrationRenderer
+};

package/src/route-renderer/orchestration/render-execution.service.d.ts ADDED Viewed

@@ -0,0 +1,103 @@
+import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
+import type { EcoComponent, IntegrationRendererRenderOptions, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { MarkerGraphContext } from '../component-graph/marker-graph-resolver.js';
+/**
+ * Serializable graph context merged from render-time captured references and
+ * optional explicit page-module graph metadata.
+ */
+export type RenderExecutionGraphContext = {
+    propsByRef?: Record<string, Record<string, unknown>>;
+    slotChildrenByRef?: MarkerGraphContext['slotChildrenByRef'];
+};
+export interface CapturedHtmlRenderResult {
+    html: string;
+    graphContext: RenderExecutionGraphContext;
+}
+export interface FinalizeHtmlRenderOptions {
+    html: string;
+    graphContext: RenderExecutionGraphContext;
+    componentsToResolve: EcoComponent[];
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+    mergeAssets?: boolean;
+}
+export interface RenderExecutionCallbacks<C> {
+    prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions<C>>;
+    render(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
+    getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
+    getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    resolveMarkerGraphHtml(input: {
+        html: string;
+        componentsToResolve: EcoComponent[];
+        graphContext: RenderExecutionGraphContext;
+    }): Promise<{
+        html: string;
+        assets: ProcessedAsset[];
+    }>;
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+    getProcessedDependencies(): ProcessedAsset[];
+    setProcessedDependencies(dependencies: ProcessedAsset[]): void;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    transformHtml(html: string): Promise<RouteRendererBody>;
+}
+export interface FinalizeHtmlRenderCallbacks {
+    resolveMarkerGraphHtml(input: {
+        html: string;
+        componentsToResolve: EcoComponent[];
+        graphContext: RenderExecutionGraphContext;
+    }): Promise<{
+        html: string;
+        assets: ProcessedAsset[];
+    }>;
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+    getProcessedDependencies(): ProcessedAsset[];
+    setProcessedDependencies(dependencies: ProcessedAsset[]): void;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+}
+/**
+ * Executes the main post-preparation rendering flow for integration renderers.
+ *
+ * This service owns the orchestration that happens after normalized render
+ * options have been prepared: the first render pass, graph-context capture,
+ * deferred marker resolution, root-attribute application, and final HTML
+ * transformation into a response body stream.
+ */
+export declare class RenderExecutionService {
+    captureHtmlRender(currentIntegrationName: string, boundaryContext: ComponentRenderBoundaryContext, render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult>;
+    /**
+     * Executes one integration render pass and returns the final route render
+     * result.
+     *
+     * @typeParam C Integration render output element type.
+     * @param options Route-level render options.
+     * @param currentIntegrationName Active integration name for this render pass.
+     * @param callbacks Renderer-specific hooks required during execution.
+     * @returns Final route render output with body and cache strategy.
+     */
+    execute<C = unknown>(options: RouteRendererOptions, currentIntegrationName: string, callbacks: RenderExecutionCallbacks<C>): Promise<RouteRenderResult>;
+    /**
+     * Merges captured render-time graph references with any explicit graph context
+     * provided by the page module.
+     *
+     * @param capturedGraphContext Graph context captured from the first render pass.
+     * @param explicitGraphContext Optional page-module graph metadata.
+     * @returns Merged graph context used during marker resolution.
+     */
+    mergeGraphContext(capturedGraphContext: RenderExecutionGraphContext, explicitGraphContext?: RenderExecutionGraphContext): RenderExecutionGraphContext;
+    finalizeHtmlRender(options: FinalizeHtmlRenderOptions, callbacks: FinalizeHtmlRenderCallbacks): Promise<{
+        html: string;
+        assets: ProcessedAsset[];
+    }>;
+    /**
+     * Returns the component set that participates in marker graph resolution for a
+     * render pass.
+     *
+     * @typeParam C Integration render output element type.
+     * @param renderOptions Normalized render options for the pass.
+     * @returns Ordered component list for graph registry construction.
+     */
+    private getComponentsToResolve;
+}