@ecopages/core 0.2.0-beta.27 → 0.2.0-beta.29

package/src/config/config-builder.js

@@ -53,6 +53,12 @@ class ConfigBuilder {
         "*": []
       }
     },
+    sitemap: {
+      enabled: false,
+      fileName: "sitemap.xml",
+      extraUrls: [],
+      exclude: []
+    },
     integrations: [],
     integrationsDependencies: [],
     distDir: DEFAULT_ECOPAGES_DIST_DIR,
@@ -74,7 +80,8 @@ class ConfigBuilder {
       publicDir: "",
       srcDir: "",
       htmlTemplatePath: "",
-      error404TemplatePath: ""
+      error404TemplatePath: "",
+      error500TemplatePath: ""
     },
     processors: /* @__PURE__ */ new Map(),
     loaders: /* @__PURE__ */ new Map(),
@@ -201,6 +208,31 @@ class ConfigBuilder {
     this.config.robotsTxt = robotsTxt;
     return this;
   }
+  /**
+   * Sets automatic sitemap.xml generation during static export.
+   *
+   * @remarks
+   * Merged over `{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }`.
+   * Existing apps stay unchanged until `enabled: true` is set. Page-level
+   * `metadata.robots.index: false` and metadata resolution failures are handled
+   * during static generation (not by this config merge).
+   */
+  setSitemap(sitemap) {
+    const defaults = {
+      enabled: false,
+      fileName: "sitemap.xml",
+      extraUrls: [],
+      exclude: []
+    };
+    this.config.sitemap = {
+      ...defaults,
+      ...this.config.sitemap,
+      ...sitemap,
+      extraUrls: sitemap.extraUrls ?? this.config.sitemap.extraUrls ?? defaults.extraUrls,
+      exclude: sitemap.exclude ?? this.config.sitemap.exclude ?? defaults.exclude
+    };
+    return this;
+  }
   /**
    * Sets the integration plugins to use.
    * These plugins provide additional functionality to the application.
@@ -381,11 +413,18 @@ class ConfigBuilder {
       error404TemplatePath: this.resolveSemanticTemplatePath({
         dirPath: absolutePagesDir,
         basename: "404"
+      }),
+      error500TemplatePath: this.resolveSemanticTemplatePath({
+        dirPath: absolutePagesDir,
+        basename: "500"
       })
     };
     return this;
   }
-  resolveSemanticTemplatePath({ dirPath, basename }) {
+  resolveSemanticTemplatePath({
+    dirPath,
+    basename
+  }) {
     const extensions = this.config.templatesExt.length > 0 ? this.config.templatesExt : [".ghtml.ts"];
     const matches = extensions.map((extension) => path.join(dirPath, `${basename}${extension}`)).filter((candidate) => fileSystem.exists(candidate));
     invariant(matches.length <= 1, CONFIG_BUILDER_ERRORS.duplicateSemanticTemplate(basename, matches));

package/src/config/constants.d.ts

@@ -7,6 +7,7 @@
  */
 export declare const STATUS_MESSAGE: {
     404: string;
+    500: string;
 };
 /**
  *Variables used to determine if the app is running on Bun

package/src/config/constants.js

@@ -1,5 +1,6 @@
 const STATUS_MESSAGE = {
-  404: "404 Not Found"
+  404: "404 Not Found",
+  500: "Internal Server Error"
 };
 const IS_BUN = typeof Bun !== "undefined";
 const RESOLVED_ASSETS_DIR = "assets";

package/src/eco/eco.js

@@ -2,8 +2,8 @@ import {
   finalizeComponentRender,
   getComponentRenderContext,
   interceptForeignChild
-} from "../route-renderer/orchestration/component-render-context.js";
-import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
+} from "../route-renderer/orchestration/foreign-child/component-render-context.js";
+import { isThenable } from "../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js";
 import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;

package/src/eco/eco.utils.d.ts

@@ -1 +1 @@
-export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js';

package/src/eco/eco.utils.js

@@ -2,7 +2,7 @@ import {
   addTriggerAttribute,
   isThenable,
   wrapWithScriptsInjector
-} from "../route-renderer/orchestration/render-output.utils.js";
+} from "../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js";
 export {
   addTriggerAttribute,
   isThenable,

package/src/hmr/client/hmr-runtime.js

@@ -88,7 +88,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     }
     await new Promise((resolve) => {
       const startedAt = performance.now();
-      const timeoutMs = 2e3;
+      const timeoutMs = 5e3;
       const poll = () => {
         if (!navigationRuntime.hasPendingNavigationTransaction()) {
           resolve();

package/src/hmr/hmr-file-change-prep.d.ts

@@ -1,5 +1,5 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import { type AffectedGraphIdentity } from '../route-renderer/orchestration/page-browser-graph-session.js';
+import { type AffectedGraphIdentity } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
 export type HmrFileChangePreparation = {
     affectedGraphIdentities: AffectedGraphIdentity[];
     invalidatedGraphCount: number;

package/src/hmr/hmr-file-change-prep.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import {
   getAffectedPageBrowserGraphIdentities,
   invalidatePageBrowserGraphSession
-} from "../route-renderer/orchestration/page-browser-graph-session.js";
+} from "../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js";
 function prepareHmrFileChange(appConfig, filePath) {
   const resolvedFilePath = path.resolve(filePath);
   const affectedGraphIdentities = getAffectedPageBrowserGraphIdentities(appConfig, resolvedFilePath);

package/src/plugins/processor.d.ts

@@ -19,6 +19,14 @@ export interface ProcessorWatchContext {
 }
 export interface ProcessorWatchConfig {
     paths: string[];
+    /**
+     * File extensions that trigger watch callbacks (`onCreate`, `onChange`, `onDelete`).
+     *
+     * @remarks
+     * Watch extensions drive notifications only. They do not declare asset ownership.
+     * Ownership requires {@link ProcessorConfig.capabilities} and controls whether dev
+     * invalidation skips server modules and HMR for processor-handled assets.
+     */
     extensions?: string[];
     onCreate?: (ctx: ProcessorWatchContext) => Promise<void>;
     onChange?: (ctx: ProcessorWatchContext) => Promise<void>;

package/src/route-renderer/GRAPH.md

@@ -85,7 +85,7 @@ flowchart TD
   B -- Yes --> C[return resolved renderer-owned output]
   B -- No --> D[queue foreign-subtree token]
   D --> E[finish current render pass]
-  E --> F[QueuedForeignSubtreeResolutionService resolveQueuedHtml]
+  E --> F[ForeignSubtreeExecutionService resolveQueuedHtml]
   F --> G[resolve nested queued tokens first]
   G --> H[dispatch foreign subtree to owning renderer]
   H --> I[merge emitted assets and root attributes]
@@ -115,12 +115,12 @@ flowchart TD
 The most useful reading order is:
 
 1. `route-renderer.ts`
-2. `orchestration/route-render-orchestrator.ts`
+2. `orchestration/route-pipeline/route-render-orchestrator.ts`
 3. `orchestration/integration-renderer.ts`
-4. `orchestration/ownership-validation.service.ts`
-5. `orchestration/component-graph.ts`
-6. `orchestration/component-render-context.ts`
-7. `orchestration/foreign-subtree-execution.service.ts`
+4. `orchestration/ownership-graph/ownership-validation.service.ts`
+5. `orchestration/ownership-graph/component-graph.ts`
+6. `orchestration/foreign-child/component-render-context.ts`
+7. `orchestration/foreign-child/foreign-subtree-execution.service.ts`
 8. `page-loading/page-module-loader.ts`
 9. `page-loading/dependency-resolver.ts`
 10. `eco/eco.ts`
@@ -128,12 +128,12 @@ The most useful reading order is:
 ## 7) Key Files
 
 - `packages/core/src/route-renderer/route-renderer.ts`
-- `packages/core/src/route-renderer/orchestration/route-render-orchestrator.ts`
+- `packages/core/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.ts`
 - `packages/core/src/route-renderer/orchestration/integration-renderer.ts`
-- `packages/core/src/route-renderer/orchestration/ownership-validation.service.ts`
-- `packages/core/src/route-renderer/orchestration/component-graph.ts`
-- `packages/core/src/route-renderer/orchestration/component-render-context.ts`
-- `packages/core/src/route-renderer/orchestration/foreign-subtree-execution.service.ts`
+- `packages/core/src/route-renderer/orchestration/ownership-graph/ownership-validation.service.ts`
+- `packages/core/src/route-renderer/orchestration/ownership-graph/component-graph.ts`
+- `packages/core/src/route-renderer/orchestration/foreign-child/component-render-context.ts`
+- `packages/core/src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.ts`
 - `packages/core/src/route-renderer/page-loading/page-module-loader.ts`
 - `packages/core/src/route-renderer/page-loading/dependency-resolver.ts`
 - `packages/core/src/eco/eco.ts`

package/src/route-renderer/README.md

@@ -50,13 +50,18 @@ See [`../build/README.md`](../build/README.md) for the JSX ownership helper spli
 
 ### `orchestration/`
 
-- `route-render-orchestrator.ts`: one route render from page-module loading through final HTML output
+Root renderer classes:
+
 - `integration-renderer.ts`: abstract base class for route rendering, explicit view rendering, and foreign-child delegation
-- `ownership-validation.service.ts`: up-front ownership validation for route roots and declared descendants
-- `foreign-subtree-execution.service.ts`: foreign-child execution policy, queue token resolution, and `toForeignSubtreeRenderPayload()`
-- `document-shell-render.service.ts`: shared page/layout/html shell composition and attribute stamping helpers
-- `component-render-context.ts`: active render context used by `eco.component()` to intercept foreign children
-- `render-output.utils.ts`: unresolved artifact normalization and marker inspection
+- `string-markup-renderer.ts`: shared base for string-markup integrations
+
+Domain folders:
+
+- `ownership-graph/`: component graph walk/collect and up-front ownership validation
+- `foreign-child/`: active render context, foreign-subtree execution, deferred template serialization
+- `document-shell/`: shared page/layout/html shell composition and attribute stamping helpers
+- `route-pipeline/`: route preparation, final HTML capture, marker-artifact enforcement
+- `page-browser-graph/`: browser asset graph build, session cache, and injector assets
 
 ### `page-loading/`
 

package/src/route-renderer/orchestration/{document-shell-render.service.d.ts → document-shell/document-shell-render.service.d.ts}

@@ -1,5 +1,6 @@
-import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../types/public-types.js';
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../../types/public-types.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import { HtmlTransformerService, type HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
 export type DocumentShellLayoutInput = {
     component: EcoComponent;
     props?: Record<string, unknown>;
@@ -88,3 +89,19 @@ export declare function applyDocumentShellAttributeStamping(html: string, stampi
  * Builds the final serialized document HTML for one route page render.
  */
 export declare function renderPageDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellPageRenderInput, docType: string): Promise<string>;
+/**
+ * Finalizes already-resolved HTML for explicit renderer-owned paths.
+ *
+ * @remarks
+ * Callers append renderer bootstrap dependencies before invoking this helper.
+ * Stamps document/root attributes and runs HTML transformation after nested
+ * foreign-subtree resolution without routing back through shared route execution.
+ */
+export declare function finalizeDocumentShellHtml(htmlTransformer: HtmlTransformerService, options: {
+    html: string;
+    partial?: boolean;
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+    transformHtml?: boolean;
+    htmlContributions?: HtmlDocumentContribution[];
+}): Promise<string>;

package/src/route-renderer/orchestration/{document-shell-render.service.js → document-shell/document-shell-render.service.js}

@@ -1,3 +1,6 @@
+import {
+  HtmlTransformerService
+} from "../../../services/html/html-transformer.service.js";
 function resolveDocumentShellLayouts(input) {
   if (input.layouts && input.layouts.length > 0) {
     return input.layouts;
@@ -112,9 +115,34 @@ async function renderPageDocumentShell(dependencies, input, docType) {
   const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(composedDocumentHtml) : composedDocumentHtml;
   return `${docType}${documentHtml}`;
 }
+async function finalizeDocumentShellHtml(htmlTransformer, options) {
+  const html = applyDocumentShellAttributeStamping(
+    options.html,
+    {
+      applyAttributesToFirstBodyElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToFirstBodyElement(nextHtml, attributes),
+      applyAttributesToHtmlElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToHtmlElement(nextHtml, attributes)
+    },
+    {
+      componentRootAttributes: options.componentRootAttributes,
+      documentAttributes: options.documentAttributes
+    }
+  );
+  const shouldTransform = options.transformHtml ?? !options.partial;
+  if (!shouldTransform) {
+    return html;
+  }
+  const transformedResponse = await htmlTransformer.transform(
+    new Response(html, {
+      headers: { "Content-Type": "text/html" }
+    }),
+    options.htmlContributions
+  );
+  return await transformedResponse.text();
+}
 export {
   applyDocumentShellAttributeStamping,
   composeDocumentShell,
   composeSequentialLayoutChildren,
+  finalizeDocumentShellHtml,
   renderPageDocumentShell
 };

package/src/route-renderer/orchestration/{layout-shell-props.service.d.ts → document-shell/layout-shell-props.service.d.ts}

@@ -1,4 +1,4 @@
-import type { EcoPageLayoutEntry, LayoutPropsContext } from '../../types/public-types.js';
+import type { EcoPageLayoutEntry, LayoutPropsContext } from '../../../types/public-types.js';
 export type LayoutShellPropsContext = LayoutPropsContext & {
     pageProps?: Record<string, unknown>;
 };

package/src/route-renderer/orchestration/{component-render-context.d.ts → foreign-child/component-render-context.d.ts}

@@ -1,4 +1,4 @@
-import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoComponent } from '../../../types/public-types.js';
 /**
  * Result returned by a renderer-owned foreign-child runtime.
  *

package/src/route-renderer/orchestration/{component-render-context.js → foreign-child/component-render-context.js}

@@ -1,4 +1,4 @@
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./render-output.utils.js";
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./foreign-child-output.utils.js";
 class ComponentRenderOutputRuntime {
   finalizeComponentRender(component, content) {
     const lazyTriggers = component.config?._resolvedLazyTriggers;

package/src/route-renderer/orchestration/{render-output.utils.d.ts → foreign-child/foreign-child-output.utils.d.ts}

@@ -1,4 +1,4 @@
-import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoComponent } from '../../../types/public-types.js';
 type ResolvedLazyScriptGroups = Readonly<NonNullable<EcoComponent['config']>['_resolvedLazyScripts']>;
 type TemplateContentShape = {
     strings: readonly string[];
@@ -73,10 +73,4 @@ export declare function wrapWithScriptsInjector(content: string, lazyGroups: Res
 export declare function wrapWithScriptsInjector<T extends TemplateContentShape>(content: T, lazyGroups: ResolvedLazyScriptGroups): T | string;
 export declare function wrapWithScriptsInjector<T extends MarkupNodeLikeShape>(content: T, lazyGroups: ResolvedLazyScriptGroups): T;
 export declare function wrapWithScriptsInjector(content: unknown, lazyGroups: ResolvedLazyScriptGroups): string | TemplateContentShape | MarkupNodeLikeShape;
-export declare function decodeHtmlEntities(value: string): string;
-export declare function normalizeUnresolvedMarkerArtifactHtml(html: string): string;
-export declare function inspectUnresolvedMarkerArtifactHtml(html: string): {
-    hasUnresolvedMarkerArtifacts: boolean;
-    normalizedHtml: string;
-};
 export {};

package/src/route-renderer/orchestration/{render-output.utils.js → foreign-child/foreign-child-output.utils.js}

@@ -1,4 +1,4 @@
-import { buildInjectorMapScript } from "../../eco/lazy-injector-map.js";
+import { buildInjectorMapScript } from "../../../eco/lazy-injector-map.js";
 function cloneTemplateStrings(strings, firstString) {
   const nextStrings = [...strings];
   nextStrings[0] = firstString;
@@ -170,36 +170,11 @@ function wrapWithScriptsInjector(content, lazyGroups) {
   }
   return wrapWithScriptsInjectorMarkup(String(content), injectorMapScript);
 }
-function decodeHtmlEntities(value) {
-  let decoded = value;
-  let previous;
-  do {
-    previous = decoded;
-    decoded = decoded.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&#x27;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
-  } while (decoded !== previous);
-  return decoded;
-}
-function normalizeUnresolvedMarkerArtifactHtml(html) {
-  return html.replace(
-    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
-    (marker) => decodeHtmlEntities(marker)
-  );
-}
-function inspectUnresolvedMarkerArtifactHtml(html) {
-  const normalizedHtml = normalizeUnresolvedMarkerArtifactHtml(html);
-  return {
-    normalizedHtml,
-    hasUnresolvedMarkerArtifacts: normalizedHtml.includes("<eco-marker")
-  };
-}
 export {
   addTriggerAttribute,
   assertForeignChildrenNotOpaque,
-  decodeHtmlEntities,
-  inspectUnresolvedMarkerArtifactHtml,
   isMarkupNodeLike,
   isOpaqueForeignChildValue,
   isThenable,
-  normalizeUnresolvedMarkerArtifactHtml,
   wrapWithScriptsInjector
 };

package/src/route-renderer/orchestration/{foreign-subtree-execution.service.d.ts → foreign-child/foreign-subtree-execution.service.d.ts}

@@ -1,5 +1,5 @@
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, ForeignSubtreeRenderPayload } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, ForeignSubtreeRenderPayload } from '../../../types/public-types.js';
 import { type ForeignChildRuntime } from './component-render-context.js';
 export type QueuedForeignChildDecisionInput = {
     currentIntegration: string;
@@ -46,7 +46,7 @@ export interface ForeignSubtreeExecutionRenderOptions {
         renderInput: ComponentRenderInput;
         rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>;
     }): ForeignChildRuntime;
-    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): Promise<ForeignSubtreeExecutionOwningRenderer>;
 }
 export interface ForeignSubtreeQueuedRuntimeOptions<TContext extends QueuedForeignSubtreeResolutionContext> {
     renderInput: ComponentRenderInput;
@@ -61,7 +61,7 @@ export interface ForeignSubtreeStringQueuedHtmlOptions {
     html: string;
     runtimeContextKey: string;
     queueLabel: string;
-    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): Promise<ForeignSubtreeExecutionOwningRenderer>;
     applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
 }
@@ -75,7 +75,7 @@ export interface ForeignSubtreeQueuedHtmlOptions<TContext extends QueuedForeignS
         children?: unknown;
         html?: string;
     }>;
-    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): ForeignSubtreeExecutionOwningRenderer;
+    getOwningRenderer(integrationName: string, rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>): Promise<ForeignSubtreeExecutionOwningRenderer>;
     applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
 }

package/src/route-renderer/orchestration/{foreign-subtree-execution.service.js → foreign-child/foreign-subtree-execution.service.js}

@@ -2,7 +2,7 @@ import {
   getComponentRenderContext,
   runWithComponentRenderContext
 } from "./component-render-context.js";
-import { assertForeignChildrenNotOpaque, isMarkupNodeLike } from "./render-output.utils.js";
+import { assertForeignChildrenNotOpaque, isMarkupNodeLike } from "./foreign-child-output.utils.js";
 function toForeignSubtreeRenderPayload(result) {
   return {
     html: result.html,
@@ -313,7 +313,7 @@ class ForeignSubtreeExecutionService {
     if (!foreignOwnerIntegrationName) {
       return void 0;
     }
-    const owningRenderer = options.getOwningRenderer(foreignOwnerIntegrationName, options.rendererCache);
+    const owningRenderer = await options.getOwningRenderer(foreignOwnerIntegrationName, options.rendererCache);
     if (owningRenderer.name === options.currentIntegrationName) {
       return void 0;
     }

package/src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.d.ts

@@ -0,0 +1,19 @@
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { ForeignSubtreeExecutionOwningRenderer } from './foreign-subtree-execution.service.js';
+export type OwningRendererResolutionInput = {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    currentIntegrationName: string;
+    currentRenderer: ForeignSubtreeExecutionOwningRenderer;
+    integrationName: string;
+    cache: Map<string, ForeignSubtreeExecutionOwningRenderer>;
+};
+export declare function getForeignSubtreeTokenPrefix(integrationName: string): string;
+export declare function getForeignSubtreeResolutionContextKey(integrationName: string): string;
+/**
+ * Resolves an owning integration renderer for a foreign-child handoff.
+ *
+ * Reuses the execution-scoped cache, activates the target runtime when needed,
+ * and initializes the plugin renderer once per integration name.
+ */
+export declare function resolveOwningIntegrationRenderer(input: OwningRendererResolutionInput): Promise<ForeignSubtreeExecutionOwningRenderer>;

package/src/route-renderer/orchestration/foreign-child/owning-renderer-resolution.js

@@ -0,0 +1,35 @@
+import { ensureIntegrationRuntimeReady } from "../../../build/app-build-manifest-runtime.js";
+import { invariant } from "../../../utils/invariant.js";
+function getForeignSubtreeTokenPrefix(integrationName) {
+  return `__${integrationName}_foreign_subtree__`;
+}
+function getForeignSubtreeResolutionContextKey(integrationName) {
+  return `__${integrationName}_foreign_subtree_runtime__`;
+}
+async function resolveOwningIntegrationRenderer(input) {
+  const { integrationName, cache } = input;
+  if (cache.has(integrationName)) {
+    return cache.get(integrationName);
+  }
+  if (integrationName === input.currentIntegrationName) {
+    cache.set(integrationName, input.currentRenderer);
+    return input.currentRenderer;
+  }
+  await ensureIntegrationRuntimeReady({
+    appConfig: input.appConfig,
+    integrationName,
+    runtimeOrigin: input.runtimeOrigin
+  });
+  const integrationPlugin = input.appConfig.integrations.find((integration) => integration.name === integrationName);
+  invariant(!!integrationPlugin, `[ecopages] Integration not found for foreign owner: ${integrationName}`);
+  const renderer = integrationPlugin.initializeRenderer({
+    rendererModules: input.appConfig.runtime?.rendererModuleContext
+  });
+  cache.set(integrationName, renderer);
+  return renderer;
+}
+export {
+  getForeignSubtreeResolutionContextKey,
+  getForeignSubtreeTokenPrefix,
+  resolveOwningIntegrationRenderer
+};

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

@@ -4,16 +4,16 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, PagePackageResult, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, 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 { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
-import type { ForeignChildRuntime } from './component-render-context.js';
-import { ForeignSubtreeExecutionService, type ForeignSubtreeExecutionOwningRenderer, type ForeignSubtreeQueuedHtmlOptions, type QueuedForeignSubtreeResolutionContext } from './foreign-subtree-execution.service.js';
+import { RouteRenderOrchestrator, type RouteRenderOrchestratorAdapter, type RouteRenderOrchestratorResolvedInputs } from './route-pipeline/route-render-orchestrator.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.
  *
@@ -118,7 +118,6 @@ 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;
     /**
      * Merges component-scoped assets into the active HTML transformer state.
      *
@@ -208,20 +207,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         transformDocumentHtml?: (html: string) => string;
     }): Promise<string>;
     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;
-    protected resolveQueuedForeignSubtreeHtml<TContext extends QueuedForeignSubtreeResolutionContext>(html: string, runtimeContext: TContext | undefined, renderQueuedChildren: ForeignSubtreeQueuedHtmlOptions<TContext>['renderQueuedChildren'], queueLabel?: string): Promise<{
-        assets: ProcessedAsset[];
-        html: string;
-    }>;
     /**
      * Renders a string-first component, then resolves any queued foreign
      * boundaries before returning final component HTML.
@@ -291,7 +276,6 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         resolvedDependencies: ProcessedAsset[];
     }>;
     protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
-    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.
@@ -318,21 +302,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.
      *
@@ -352,17 +321,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.