@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

package/src/integrations/ghtml/ghtml-renderer.js

@@ -1,56 +1,7 @@
-import {
-  IntegrationRenderer
-} from "../../route-renderer/orchestration/integration-renderer.js";
+import { StringMarkupRenderer } from "../../route-renderer/orchestration/string-markup-renderer.js";
 import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-class GhtmlRenderer extends IntegrationRenderer {
+class GhtmlRenderer extends StringMarkupRenderer {
   name = GHTML_PLUGIN_NAME;
-  async renderComponent(input) {
-    return this.renderStringComponentWithQueuedForeignSubtrees(
-      input,
-      input.component
-    );
-  }
-  async render({
-    params,
-    query,
-    props,
-    locals,
-    pageLocals,
-    metadata,
-    Page,
-    Layout,
-    HtmlTemplate
-  }) {
-    try {
-      return await this.renderPageWithDocumentShell({
-        page: {
-          component: Page,
-          props: { params, query, ...props, locals: pageLocals }
-        },
-        layout: Layout ? {
-          component: Layout,
-          props: locals ? { locals } : {}
-        } : void 0,
-        htmlTemplate: HtmlTemplate,
-        metadata,
-        pageProps: props ?? {}
-      });
-    } catch (error) {
-      throw this.createRenderError("Error rendering page", error);
-    }
-  }
-  async renderToResponse(view, props, ctx) {
-    try {
-      return await this.renderViewWithDocumentShell({
-        view,
-        props,
-        ctx,
-        layout: view.config?.layout
-      });
-    } catch (error) {
-      throw this.createRenderError("Error rendering view", error);
-    }
-  }
 }
 export {
   GhtmlRenderer

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -1,16 +1,3 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
-import { GhtmlRenderer } from './ghtml-renderer.js';
-/**
- * The Ghtml plugin class
- * This plugin provides support for ghtml components in Ecopages
- */
-export declare class GhtmlPlugin extends IntegrationPlugin {
-    renderer: typeof GhtmlRenderer;
-    constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
-}
-/**
- * Factory function to create a Ghtml plugin instance
- * @param options Configuration options for the Ghtml plugin
- * @returns A new GhtmlPlugin instance
- */
-export declare function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin;
+export declare const ghtmlPlugin: import("../../plugins/define-integration.js").DefinedIntegration<import("../../index.browser.js").EcoPagesElement>;
+/** @deprecated Use {@link ghtmlPlugin.Plugin} or {@link ghtmlPlugin} instead. */
+export declare const GhtmlPlugin: new (options?: Omit<import("../../plugins/integration-plugin.js").IntegrationPluginConfig, "name">) => import("../../plugins/integration-plugin.js").IntegrationPlugin<import("../../index.browser.js").EcoPagesElement>;

package/src/integrations/ghtml/ghtml.plugin.js

@@ -1,19 +1,12 @@
-import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
+import { defineIntegration } from "../../plugins/define-integration.js";
 import { GhtmlRenderer } from "./ghtml-renderer.js";
 import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
-class GhtmlPlugin extends IntegrationPlugin {
-  renderer = GhtmlRenderer;
-  constructor(options) {
-    super({
-      name: GHTML_PLUGIN_NAME,
-      extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
-      ...options
-    });
-  }
-}
-function ghtmlPlugin(options) {
-  return new GhtmlPlugin(options);
-}
+const ghtmlPlugin = defineIntegration({
+  name: GHTML_PLUGIN_NAME,
+  extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
+  renderer: GhtmlRenderer
+});
+const GhtmlPlugin = ghtmlPlugin.Plugin;
 export {
   GhtmlPlugin,
   ghtmlPlugin

package/src/plugins/define-integration.d.ts

@@ -0,0 +1,26 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
+import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { EcoPagesElement } from '../types/public-types.js';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
+import { IntegrationPlugin, type IntegrationPluginConfig } from './integration-plugin.js';
+type RendererClass<C> = new (options: {
+    appConfig: EcoPagesAppConfig;
+    assetProcessingService: AssetProcessingService;
+    resolvedIntegrationDependencies: ProcessedAsset[];
+    rendererModules?: unknown;
+    runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+export interface DefineIntegrationDefinition<C = EcoPagesElement> extends IntegrationPluginConfig {
+    renderer: RendererClass<C>;
+}
+export interface DefinedIntegration<C = EcoPagesElement> {
+    (options?: Omit<IntegrationPluginConfig, 'name'>): IntegrationPlugin<C>;
+    Plugin: new (options?: Omit<IntegrationPluginConfig, 'name'>) => IntegrationPlugin<C>;
+}
+/**
+ * Creates a typed integration plugin factory for integrations that only need
+ * declarative config and a renderer class.
+ */
+export declare function defineIntegration<C = EcoPagesElement>(definition: DefineIntegrationDefinition<C>): DefinedIntegration<C>;
+export {};

package/src/plugins/define-integration.js

@@ -0,0 +1,19 @@
+import { IntegrationPlugin } from "./integration-plugin.js";
+function defineIntegration(definition) {
+  const { renderer, ...defaultConfig } = definition;
+  class DefinedIntegrationPlugin extends IntegrationPlugin {
+    renderer = renderer;
+    constructor(options) {
+      super({
+        ...defaultConfig,
+        ...options
+      });
+    }
+  }
+  const factory = ((options) => new DefinedIntegrationPlugin(options));
+  factory.Plugin = DefinedIntegrationPlugin;
+  return factory;
+}
+export {
+  defineIntegration
+};

package/src/plugins/eco-component-meta-plugin.js

@@ -1,4 +1,5 @@
 import { cachedParseSync } from "../cache/module-parse-cache.js";
+import { prependJsxImportSourceIfMissing } from "./jsx-import-source.utils.js";
 import { rapidhash } from "../utils/hash.js";
 import {
   createEcoBuildPluginFromSourceTransform,
@@ -38,13 +39,6 @@ function detectIntegration(filePath, extensionToIntegration) {
   }
   return { name: "ghtml" };
 }
-function prependJsxImportSource(code, jsxImportSource) {
-  if (!jsxImportSource || code.includes("@jsxImportSource")) {
-    return code;
-  }
-  return `/** @jsxImportSource ${jsxImportSource} */
-${code}`;
-}
 function createExtensionPattern(extensions) {
   if (extensions.length === 0) {
     throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
@@ -67,7 +61,10 @@ function createEcoComponentMetaTransform(options) {
     transform(code, id) {
       const integration = detectIntegration(id, extensionToIntegration);
       return {
-        code: prependJsxImportSource(injectEcoMeta(code, id, integration.name), integration.jsxImportSource)
+        code: prependJsxImportSourceIfMissing(
+          injectEcoMeta(code, id, integration.name),
+          integration.jsxImportSource
+        )
       };
     }
   };

package/src/plugins/foreign-jsx-override-plugin.js

@@ -1,10 +1,9 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { createJsxImportSourcePragma, filterJsxSourceExtensions } from "./jsx-import-source.utils.js";
 function createForeignJsxOverridePlugin(options) {
-  const extensions = options.foreignExtensions.filter((ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx"));
-  const excludedExtensions = (options.excludeExtensions ?? []).filter(
-    (ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx")
-  );
+  const extensions = filterJsxSourceExtensions(options.foreignExtensions);
+  const excludedExtensions = filterJsxSourceExtensions(options.excludeExtensions ?? []);
   if (extensions.length === 0) {
     return {
       name: options.name ?? "foreign-jsx-override",
@@ -12,8 +11,7 @@ function createForeignJsxOverridePlugin(options) {
       }
     };
   }
-  const pragma = `/** @jsxImportSource ${options.hostJsxImportSource} */
-`;
+  const pragma = createJsxImportSourcePragma(options.hostJsxImportSource);
   const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
   return {
     name: options.name ?? "foreign-jsx-override",

package/src/plugins/integration-plugin.d.ts

@@ -6,10 +6,12 @@ import type { EcoPagesElement } from '../types/public-types.js';
 import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
 import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
 export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
 /**
  * Type-erased integration plugin stored in app-level registries.
@@ -47,13 +49,6 @@ export interface IntegrationPluginConfig {
      * They are not specific to any particular page or component.
      */
     integrationDependencies?: AssetDefinition[];
-    /**
-     * The strategy to use for static building.
-     * - 'render': Execute component function directly (faster, efficient).
-     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
-     * @default 'render'
-     */
-    staticBuildStep?: 'render' | 'fetch';
     /**
      * Declares runtime-specific requirements that must be satisfied before the
      * app can start with this integration enabled.
@@ -96,7 +91,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly name: string;
     readonly extensions: string[];
     abstract renderer: RendererClass<C>;
-    readonly staticBuildStep: 'render' | 'fetch';
     readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     readonly jsxImportSource?: string;
     protected integrationDependencies: AssetDefinition[];
@@ -199,7 +193,6 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * Renderers are cheap runtime objects. They receive the finalized app config,
      * a fresh asset-processing service, integration-global processed assets, and
      * any renderer module context supplied by the active runtime.
-            renderer.name ||= this.name;
      */
     initializeRenderer(options?: {
         rendererModules?: unknown;
@@ -213,6 +206,23 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this integration's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
+    /**
+     * Runs integration-specific setup before static page generation begins.
+     *
+     * @remarks
+     * Integrations that need build-scoped SSR preload or worker sessions should
+     * start them here rather than per-page inside the renderer.
+     */
+    beforeStaticExport?(_context: StaticExportContext): Promise<void>;
+    /**
+     * Releases resources started in {@link beforeStaticExport}.
+     */
+    afterStaticExport?(_context: StaticExportContext): Promise<void>;
     /**
      * Performs runtime-only integration setup after config build has already
      * sealed manifest contributions.

package/src/plugins/integration-plugin.js

@@ -15,7 +15,6 @@ function assertIntegrationInvariant(condition, message) {
 class IntegrationPlugin {
   name;
   extensions;
-  staticBuildStep;
   runtimeCapability;
   jsxImportSource;
   integrationDependencies;
@@ -60,7 +59,6 @@ class IntegrationPlugin {
     this.name = config.name;
     this.extensions = config.extensions;
     this.integrationDependencies = config.integrationDependencies || [];
-    this.staticBuildStep = config.staticBuildStep || "render";
     this.runtimeCapability = config.runtimeCapability;
     this.jsxImportSource = config.jsxImportSource;
   }
@@ -152,7 +150,6 @@ class IntegrationPlugin {
    * Renderers are cheap runtime objects. They receive the finalized app config,
    * a fresh asset-processing service, integration-global processed assets, and
    * any renderer module context supplied by the active runtime.
-  		renderer.name ||= this.name;
    */
   initializeRenderer(options) {
     const renderer = new this.renderer(this.createRendererOptions(options));
@@ -169,6 +166,13 @@ class IntegrationPlugin {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this integration's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   /**
    * Performs runtime-only integration setup after config build has already
    * sealed manifest contributions.
@@ -180,7 +184,6 @@ class IntegrationPlugin {
       this.integrationDependencies,
       this.name
     );
-    this.initializeRenderer();
   }
   /**
    * Releases runtime resources owned by the integration.

package/src/plugins/jsx-import-source.utils.d.ts

@@ -0,0 +1,8 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export declare function createJsxImportSourcePragma(jsxImportSource: string): string;
+export declare function prependJsxImportSourceIfMissing(code: string, jsxImportSource: string | undefined): string;
+export declare function isJsxSourceExtension(extension: string): boolean;
+export declare function filterJsxSourceExtensions(extensions: string[]): string[];
+export declare function collectJsxExtensions(integrations: NonNullable<EcoPagesAppConfig['integrations']>, options?: {
+    excludeIntegrationName?: string;
+}): string[];

package/src/plugins/jsx-import-source.utils.js

@@ -0,0 +1,26 @@
+function createJsxImportSourcePragma(jsxImportSource) {
+  return `/** @jsxImportSource ${jsxImportSource} */
+`;
+}
+function prependJsxImportSourceIfMissing(code, jsxImportSource) {
+  if (!jsxImportSource || code.includes("@jsxImportSource")) {
+    return code;
+  }
+  return createJsxImportSourcePragma(jsxImportSource) + code;
+}
+function isJsxSourceExtension(extension) {
+  return extension.endsWith(".tsx") || extension.endsWith(".jsx");
+}
+function filterJsxSourceExtensions(extensions) {
+  return extensions.filter(isJsxSourceExtension);
+}
+function collectJsxExtensions(integrations, options) {
+  return integrations.filter((integration) => integration.jsxImportSource).filter((integration) => integration.name !== options?.excludeIntegrationName).flatMap((integration) => filterJsxSourceExtensions(integration.extensions));
+}
+export {
+  collectJsxExtensions,
+  createJsxImportSourcePragma,
+  filterJsxSourceExtensions,
+  isJsxSourceExtension,
+  prependJsxImportSourceIfMissing
+};

package/src/plugins/processor.d.ts

@@ -1,6 +1,5 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.js';
-import type { AssetDefinition } from '../services/assets/asset-processing-service/assets.types.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
@@ -59,7 +58,6 @@ export interface ProcessorContext {
  */
 export declare abstract class Processor<TOptions = Record<string, unknown>> {
     readonly name: string;
-    protected dependencies: AssetDefinition[];
     protected context?: ProcessorContext;
     protected options?: TOptions;
     protected watchConfig?: ProcessorWatchConfig;
@@ -80,14 +78,31 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
      * warming or watcher registration should stay in `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this processor's build inputs changed since the last
+     * incremental static build.
+     *
+     * @remarks
+     * No shipped processor overrides this today. Integrations and processors can
+     * opt in when they own build inputs that should invalidate incremental static
+     * exports without a full rebuild.
+     */
+    didChange(): boolean;
     abstract setup(): Promise<void>;
-    abstract teardown(): Promise<void>;
     abstract process(input: unknown, filePath?: string): Promise<unknown>;
+    /**
+     * Releases runtime resources owned by the processor.
+     *
+     * @remarks
+     * Core does not call this hook today. Override only when a processor owns
+     * watchers, compiler handles, or other resources that outlive individual
+     * requests.
+     */
+    teardown(): Promise<void>;
     protected getCachePath(key: string): string;
     protected readCache<T>(key: string): Promise<T | null>;
     protected writeCache<T>(key: string, data: T): Promise<void>;
     getWatchConfig(): ProcessorWatchConfig | undefined;
-    getDependencies(): AssetDefinition[];
     getName(): string;
     getAssetCapabilities(): ProcessorAssetCapability[];
     matchesFileFilter(_filepath: string): boolean;

package/src/plugins/processor.js

@@ -16,7 +16,6 @@ function resolveGeneratedPath(type, options) {
 }
 class Processor {
   name;
-  dependencies = [];
   context;
   options;
   watchConfig;
@@ -54,6 +53,28 @@ class Processor {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this processor's build inputs changed since the last
+   * incremental static build.
+   *
+   * @remarks
+   * No shipped processor overrides this today. Integrations and processors can
+   * opt in when they own build inputs that should invalidate incremental static
+   * exports without a full rebuild.
+   */
+  didChange() {
+    return false;
+  }
+  /**
+   * Releases runtime resources owned by the processor.
+   *
+   * @remarks
+   * Core does not call this hook today. Override only when a processor owns
+   * watchers, compiler handles, or other resources that outlive individual
+   * requests.
+   */
+  async teardown() {
+  }
   getCachePath(key) {
     return `${this.context?.cache}/${key}`;
   }
@@ -76,9 +97,6 @@ class Processor {
   getWatchConfig() {
     return this.watchConfig;
   }
-  getDependencies() {
-    return this.dependencies;
-  }
   getName() {
     return this.name;
   }

package/src/plugins/source-transform.d.ts

@@ -4,9 +4,21 @@ export interface EcoSourceTransformResult {
     code: string;
     map?: unknown;
 }
+/**
+ * Bundler-neutral source transform registered on {@link EcoPagesAppConfig.sourceTransforms}.
+ *
+ * @remarks
+ * Prefer this shape over a competing {@link EcoBuildPlugin} `onLoad` handler when
+ * the transform only rewrites module source. Browser/HMR builds run source
+ * transforms after first-wins `onLoad` plugins, so metadata injection and similar
+ * passes still run on rewritten output from boundary/runtime plugins.
+ */
 export interface EcoSourceTransform {
+    /** Stable transform name. Also used to dedupe loader plugins in browser builds. */
     name: string;
+    /** File-path filter tested against {@link normalizeTransformId | normalized ids}. */
     filter: RegExp;
+    /** Runs before default transforms, or after them when set to `post`. */
     enforce?: 'pre' | 'post';
     transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
 }
@@ -24,8 +36,27 @@ export declare function normalizeTransformId(id: string): string;
  * Applies one source transform if the normalized id matches its filter.
  */
 export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * Applies app-owned source transforms in deterministic `pre` → default → `post` order.
+ *
+ * @remarks
+ * Used by the Rolldown plugin bridge after `onLoad` plugins produce final module
+ * contents. Transforms that do not match `filter` are skipped; matching transforms
+ * are chained left-to-right on the current source string.
+ *
+ * @param transforms - App-owned transforms, usually from {@link getAppSourceTransforms}.
+ * @param code - Current module source.
+ * @param id - Module id forwarded to each transform after query/hash normalization.
+ * @returns The transformed source, or the original `code` when no transform matches.
+ */
+export declare function applySourceTransforms(transforms: readonly EcoSourceTransform[], code: string, id: string): string;
 /**
  * Adapts a source transform into the existing Ecopages build-plugin contract.
+ *
+ * @remarks
+ * Server-oriented builds and loader registration still use this adapter.
+ * Browser/HMR builds should register the transform in `appConfig.sourceTransforms`
+ * instead so the Rolldown bridge can run it after competing `onLoad` plugins.
  */
 export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
 /**

package/src/plugins/source-transform.js

@@ -13,6 +13,27 @@ function applySourceTransform(transform, code, id) {
   }
   return transform.transform(code, normalizedId);
 }
+const SOURCE_TRANSFORM_ENFORCE_ORDER = {
+  pre: 0,
+  default: 1,
+  post: 2
+};
+function getSourceTransformEnforceOrder(transform) {
+  return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? "default"];
+}
+function applySourceTransforms(transforms, code, id) {
+  let current = code;
+  for (const transform of [...transforms].sort(
+    (left, right) => getSourceTransformEnforceOrder(left) - getSourceTransformEnforceOrder(right)
+  )) {
+    const result = applySourceTransform(transform, current, id);
+    if (!result) {
+      continue;
+    }
+    current = typeof result === "string" ? result : result.code;
+  }
+  return current;
+}
 function inferLoaderFromPath(filePath) {
   const extension = path.extname(filePath).toLowerCase();
   switch (extension) {
@@ -56,13 +77,14 @@ function createVitePluginFromSourceTransform(transform) {
   };
 }
 function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
+  return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
 }
 function createVitePluginsFromAppSourceTransforms(appConfig) {
   return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
 }
 export {
   applySourceTransform,
+  applySourceTransforms,
   createEcoBuildPluginFromSourceTransform,
   createVitePluginFromSourceTransform,
   createVitePluginsFromAppSourceTransforms,

package/src/route-renderer/GRAPH.md

@@ -33,15 +33,15 @@ flowchart TD
 
 ## 2) Route Render Flow
 
-`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderFlow`.
+`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderOrchestrator`.
 
 ```mermaid
 flowchart TD
-  A[IntegrationRenderer.execute] --> B[RouteRenderFlow.prepareRenderOptions]
+  A[IntegrationRenderer.execute] --> B[RouteRenderOrchestrator.prepareRenderOptions]
   B --> C[resolvePageModule]
   C --> D[ownershipValidationService.validate]
   D --> E[resolvePageData]
-  E --> F[ownershipPlanningService.buildPlan]
+  E --> F[ownershipValidationService.validate + throwIfOwnershipInvalid]
   F --> G[resolveDependencies]
   G --> H[buildPageBrowserGraph]
   H --> I{shouldRenderPageComponent?}
@@ -77,7 +77,7 @@ flowchart TD
   D -- Yes --> E[render inline]
   D -- No --> F[delegate to owning renderer]
   F --> G[owning renderer renderComponentWithForeignChildren]
-  G --> H[owning renderer renderForeignSubtree when payload form is needed]
+  G --> H[owning renderer renderComponentWithForeignChildren mapped via toForeignSubtreeRenderPayload]
   H --> I[resolved html plus assets and attachment policy]
 ```
 
@@ -121,12 +121,12 @@ flowchart TD
 The most useful reading order is:
 
 1. `route-renderer.ts`
-2. `orchestration/route-render-flow.ts`
+2. `orchestration/route-render-orchestrator.ts`
 3. `orchestration/integration-renderer.ts`
 4. `orchestration/ownership-validation.service.ts`
 5. `orchestration/ownership-planning.service.ts`
 6. `orchestration/component-render-context.ts`
-7. `orchestration/queued-foreign-subtree-resolution.service.ts`
+7. `orchestration/foreign-subtree-execution.service.ts`
 8. `page-loading/page-module-loader.ts`
 9. `page-loading/dependency-resolver.ts`
 10. `eco/eco.ts`
@@ -134,12 +134,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-flow.ts`
+- `packages/core/src/route-renderer/orchestration/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/ownership-planning.service.ts`
 - `packages/core/src/route-renderer/orchestration/component-render-context.ts`
-- `packages/core/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.ts`
+- `packages/core/src/route-renderer/orchestration/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`