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

package/src/route-renderer/README.md

@@ -16,18 +16,30 @@ The route renderer layer is responsible for:
 
 The architecture is organized around three distinct concepts:
 
-- `ownership`: preparation-time metadata that describes which integration owns each declared component edge
+- `ownership`: declared component dependency metadata validated before render
 - `foreign child`: a component encountered during render whose owning integration differs from the current integration
 - `foreign subtree`: the resolved HTML, assets, and root-attachment metadata returned by the owning renderer for that foreign child
 
 These concepts intentionally live in different places:
 
-- `ownership-planning.service.ts` builds `ownershipPlan`
-- `ownership-validation.service.ts` validates declared foreign ownership up front
+- `ownership-validation.service.ts` validates declared foreign ownership up front and fails the render on misconfiguration
 - `component-render-context.ts` intercepts foreign children during active component render
-- `queued-foreign-subtree-resolution.service.ts` resolves queued foreign subtrees for renderers that cannot hand them off inline
-- `integration-renderer.ts` owns renderer-to-renderer delegation and shared shell composition
-- `route-render-flow.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+- `foreign-subtree-execution.service.ts` owns mixed-integration execution policy and queued token resolution
+- `document-shell-render.service.ts` composes page, layout, and html template shells with one execution-scoped renderer cache
+- `integration-renderer.ts` owns renderer-to-renderer delegation and integration-specific render hooks
+- `route-render-orchestrator.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+
+## Build-Time JSX vs Runtime Foreign Children
+
+Mixed-integration apps use two separate mechanisms:
+
+| Layer   | Mechanism                                                         | Purpose                                                                                  |
+| ------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Build   | `getJsxOwnershipPlugins()` / `getHostScopedJsxOwnershipPlugins()` | Prepend `@jsxImportSource` so bundled `.tsx` files compile with the correct JSX runtime  |
+| Build   | `eco-component-meta-plugin`                                       | Prepends the owning integration pragma when injecting `__eco` metadata into native files |
+| Runtime | `eco.component()` / `eco.embed()` + foreign-child runtime         | Hand off cross-integration children during SSR                                           |
+
+See [`../build/README.md`](../build/README.md) for the JSX ownership helper split.
 
 ## Main Files
 
@@ -38,12 +50,12 @@ These concepts intentionally live in different places:
 
 ### `orchestration/`
 
-- `route-render-flow.ts`: one route render from page-module loading through final HTML output
+- `route-render-orchestrator.ts`: one route render from page-module loading through final HTML output
 - `integration-renderer.ts`: abstract base class for route rendering, explicit view rendering, and foreign-child delegation
-- `ownership-planning.service.ts`: declared ownership graph construction
 - `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
-- `queued-foreign-subtree-resolution.service.ts`: queue resolution for renderers that need token-based foreign-subtree handoff
 - `render-output.utils.ts`: unresolved artifact normalization and marker inspection
 
 ### `page-loading/`
@@ -56,11 +68,11 @@ These concepts intentionally live in different places:
 The route-render contract is:
 
 1. `RouteRendererFactory` selects the owning integration renderer.
-2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderFlow`.
-3. `RouteRenderFlow.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
+2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderOrchestrator`.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership (fail-fast), resolves page data, resolves dependencies, and builds the page browser graph.
 4. The integration renderer performs page, layout, and document-shell rendering. When it encounters a foreign child, it delegates that child back to the owning renderer.
 5. If a renderer needs queued handoff, it emits internal foreign-subtree tokens and resolves them before returning final HTML.
-6. `RouteRenderFlow.execute()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
+6. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
 
 Important:
 
@@ -72,38 +84,28 @@ Important:
 
 Mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`.
 
-That declaration is used for two things:
-
-- `OwnershipValidationService` surfaces missing metadata or unknown integrations before render execution
-- `OwnershipPlanningService` records the expected ownership shape in `ownershipPlan`
+`OwnershipValidationService` surfaces missing metadata or unknown integrations during `prepareRenderOptions()` and throws before render execution starts.
 
 At runtime, renderers still discover actual foreign children through the active component render context.
 
 ## Foreign Subtree Contract
 
-`renderForeignSubtree()` is the compatibility contract for renderer-to-renderer handoff. It returns:
-
-- `html`
-- `assets`
-- `rootTag`
-- optional `rootAttributes`
-- `attachmentPolicy`
-- `integrationName`
-
-`renderComponentWithForeignChildren()` is the higher-level renderer entrypoint. It is responsible for:
+`renderComponentWithForeignChildren()` is the renderer entrypoint for mixed-integration trees. It is responsible for:
 
 - reusing the execution-scoped owning-renderer cache
 - deciding whether the current component can stay local
 - creating a foreign-child runtime when nested foreign ownership must be resolved
 - normalizing unresolved artifact HTML before the render leaves the renderer
 
+Queue resolution maps owning-renderer output into the foreign-subtree payload shape via `toForeignSubtreeRenderPayload()` inside `foreign-subtree-execution.service.ts`.
+
 ## Queue Model
 
 Not every integration needs queue-based handoff.
 
 - If a renderer can resolve a foreign child inline, it returns resolved output immediately.
 - If it cannot, it may emit internal foreign-subtree tokens and resolve them before returning final HTML.
-- The queue service is only for renderer-owned transport inside one render pass. It is not a general route-level fallback mechanism.
+- Queue mechanics live inside `ForeignSubtreeExecutionService`; they are renderer-owned transport inside one render pass, not a general route-level fallback mechanism.
 
 ## React Island Notes
 
@@ -114,5 +116,5 @@ Not every integration needs queue-based handoff.
 
 ## Current Limits
 
-- `ownershipPlan` is still diagnostic and preparatory metadata; it does not yet drive a full route-composer execution model.
 - Different integrations still own different foreign-child runtime strategies, which is intentional where child transport or hydration behavior differs.
+- `integration-renderer.ts` remains the largest integration hook surface even after document-shell extraction.

package/src/route-renderer/orchestration/component-graph-collectors.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoComponent, ResolvedLazyTrigger } from '../../types/public-types.js';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+export declare function collectIntegrationNamesFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Set<string>;
+export declare function collectResolvedLazyTriggersFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ResolvedLazyTrigger[];
+export declare function hasForeignChildDescendantsInGraph(component: EcoComponent, currentIntegrationName: string): boolean;
+export declare function collectEagerSsrLazyScriptDefinitions(components: (EcoComponent | Partial<EcoComponent>)[]): AssetDefinition[];
+export declare function collectUsedIntegrationDependenciesFromGraph(appConfig: EcoPagesAppConfig, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ProcessedAsset[];
+export declare function buildEagerSsrLazyAssetsFromGraph(assetProcessingService: AssetProcessingService, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Promise<ProcessedAsset[]>;

package/src/route-renderer/orchestration/component-graph-collectors.js

@@ -0,0 +1,143 @@
+import path from "node:path";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { walkComponentGraph } from "./component-graph.js";
+function toGraphRoots(components) {
+  return components.filter(Boolean).map((component) => ({ component }));
+}
+function collectIntegrationNamesFromGraph(components, currentIntegrationName) {
+  const integrationNames = /* @__PURE__ */ new Set();
+  walkComponentGraph({
+    roots: toGraphRoots(components),
+    currentIntegrationName,
+    onComponent: ({ component }) => {
+      const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
+      if (integrationName) {
+        integrationNames.add(integrationName);
+      }
+    }
+  });
+  return integrationNames;
+}
+function collectResolvedLazyTriggersFromGraph(components, currentIntegrationName) {
+  const triggers = [];
+  walkComponentGraph({
+    roots: toGraphRoots(components),
+    currentIntegrationName,
+    onComponent: ({ component }) => {
+      const ownTriggers = component.config?._resolvedLazyTriggers;
+      if (ownTriggers?.length) {
+        triggers.push(...ownTriggers);
+      }
+    }
+  });
+  return triggers;
+}
+function hasForeignChildDescendantsInGraph(component, currentIntegrationName) {
+  let foundForeign = false;
+  walkComponentGraph({
+    roots: [{ component }],
+    currentIntegrationName,
+    onComponent: ({ component: currentComponent }) => {
+      if (foundForeign) {
+        return false;
+      }
+      const integrationName = currentComponent.config?.integration ?? currentComponent.config?.__eco?.integration;
+      if (integrationName && integrationName !== currentIntegrationName) {
+        foundForeign = true;
+        return false;
+      }
+    }
+  });
+  return foundForeign;
+}
+function collectEagerSsrLazyScriptDefinitions(components) {
+  const dependencies = [];
+  const seenKeys = /* @__PURE__ */ new Set();
+  const normalizeAttributes = (attributes) => ({
+    type: "module",
+    defer: "",
+    ...attributes ?? {}
+  });
+  walkComponentGraph({
+    roots: toGraphRoots(components),
+    currentIntegrationName: "",
+    visitLayout: true,
+    onConfig: (config) => {
+      const componentFile = config?.__eco?.file;
+      if (!componentFile) {
+        return;
+      }
+      const componentDir = path.dirname(componentFile);
+      for (const script of config.dependencies?.scripts ?? []) {
+        if (typeof script === "string" || !script.lazy || script.ssr !== true) {
+          continue;
+        }
+        const attributes = normalizeAttributes(script.attributes);
+        if (script.content) {
+          const key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
+          if (seenKeys.has(key2)) {
+            continue;
+          }
+          seenKeys.add(key2);
+          dependencies.push(
+            AssetFactory.createContentScript({
+              position: "head",
+              content: script.content,
+              attributes,
+              packageRole: "dynamic-chunk"
+            })
+          );
+          continue;
+        }
+        if (!script.src) {
+          continue;
+        }
+        const resolvedPath = path.resolve(componentDir, script.src);
+        const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
+        if (seenKeys.has(key)) {
+          continue;
+        }
+        seenKeys.add(key);
+        dependencies.push(
+          AssetFactory.createFileScript({
+            filepath: resolvedPath,
+            position: "head",
+            attributes,
+            packageRole: "dynamic-chunk"
+          })
+        );
+      }
+    }
+  });
+  return dependencies;
+}
+function collectUsedIntegrationDependenciesFromGraph(appConfig, components, currentIntegrationName) {
+  const integrationNames = collectIntegrationNamesFromGraph(components, currentIntegrationName);
+  const dependencies = [];
+  for (const integrationName of integrationNames) {
+    if (integrationName === currentIntegrationName) {
+      continue;
+    }
+    const integrationPlugin = appConfig.integrations.find((integration) => integration.name === integrationName);
+    if (!integrationPlugin || typeof integrationPlugin.getResolvedIntegrationDependencies !== "function") {
+      continue;
+    }
+    dependencies.push(...integrationPlugin.getResolvedIntegrationDependencies());
+  }
+  return dependencies;
+}
+async function buildEagerSsrLazyAssetsFromGraph(assetProcessingService, components, currentIntegrationName) {
+  const dependencies = collectEagerSsrLazyScriptDefinitions(components);
+  if (dependencies.length === 0) {
+    return [];
+  }
+  return assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
+}
+export {
+  buildEagerSsrLazyAssetsFromGraph,
+  collectEagerSsrLazyScriptDefinitions,
+  collectIntegrationNamesFromGraph,
+  collectResolvedLazyTriggersFromGraph,
+  collectUsedIntegrationDependenciesFromGraph,
+  hasForeignChildDescendantsInGraph
+};

package/src/route-renderer/orchestration/component-graph.d.ts

@@ -0,0 +1,36 @@
+import type { EcoComponent, OwnershipPlanNodeSource } from '../../types/public-types.js';
+export type DeclaredOwnershipRoot = {
+    component: EcoComponent;
+    source: Extract<OwnershipPlanNodeSource, 'page' | 'layout' | 'html-template'>;
+};
+export type DeclaredOwnershipNodeInput = {
+    component: EcoComponent;
+    source: Exclude<OwnershipPlanNodeSource, 'route'>;
+    parentIntegrationName: string;
+    integrationName: string;
+    componentId: string;
+    isForeignToParent: boolean;
+};
+export type ComponentGraphRoot = {
+    component: EcoComponent | Partial<EcoComponent>;
+    source?: Exclude<OwnershipPlanNodeSource, 'route'>;
+};
+export type ComponentGraphWalkInput = {
+    component: EcoComponent;
+    parentIntegrationName: string;
+    source?: Exclude<OwnershipPlanNodeSource, 'route'>;
+};
+export declare function walkComponentGraph(input: {
+    roots: ComponentGraphRoot[];
+    currentIntegrationName: string;
+    visitLayout?: boolean;
+    onComponent?: (node: ComponentGraphWalkInput) => void | boolean;
+    onConfig?: (config: EcoComponent['config']) => void;
+}): void;
+export declare function mapComponentGraph<T>(input: {
+    roots: DeclaredOwnershipRoot[];
+    currentIntegrationName: string;
+    mapNode: (node: DeclaredOwnershipNodeInput, children: T[]) => T;
+}): T[];
+/** @deprecated Use `mapComponentGraph` from `component-graph.ts`. */
+export declare const mapDeclaredOwnershipGraph: typeof mapComponentGraph;

package/src/route-renderer/orchestration/component-graph.js

@@ -0,0 +1,98 @@
+function walkComponentGraph(input) {
+  const seenComponents = /* @__PURE__ */ new Set();
+  const seenConfigs = /* @__PURE__ */ new Set();
+  const visitComponent = (component, parentIntegrationName, source) => {
+    if (!component) {
+      return;
+    }
+    const ecoComponent = component;
+    if (seenComponents.has(ecoComponent)) {
+      return;
+    }
+    seenComponents.add(ecoComponent);
+    const integrationName = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration ?? parentIntegrationName;
+    if (input.onConfig && ecoComponent.config && !seenConfigs.has(ecoComponent.config)) {
+      seenConfigs.add(ecoComponent.config);
+      input.onConfig(ecoComponent.config);
+    }
+    if (input.onComponent) {
+      const shouldContinue = input.onComponent({
+        component: ecoComponent,
+        parentIntegrationName,
+        source
+      });
+      if (shouldContinue === false) {
+        return;
+      }
+    }
+    if (input.visitLayout) {
+      for (const layout of ecoComponent.config?.layouts ?? []) {
+        if (layout?.config) {
+          visitConfig(layout.config, integrationName);
+        }
+      }
+    }
+    for (const child of ecoComponent.config?.dependencies?.components ?? []) {
+      visitComponent(child, integrationName, "dependency");
+    }
+  };
+  const visitConfig = (config, parentIntegrationName) => {
+    if (!config || seenConfigs.has(config)) {
+      return;
+    }
+    seenConfigs.add(config);
+    if (input.onConfig) {
+      input.onConfig(config);
+    }
+    if (input.visitLayout) {
+      for (const layout of config.layouts ?? []) {
+        if (layout?.config) {
+          visitConfig(layout.config, parentIntegrationName);
+        }
+      }
+    }
+    for (const child of config.dependencies?.components ?? []) {
+      visitComponent(child, parentIntegrationName, "dependency");
+    }
+  };
+  for (const root of input.roots) {
+    visitComponent(root.component, input.currentIntegrationName, root.source);
+  }
+}
+function mapComponentGraph(input) {
+  let nextSyntheticId = 0;
+  const mapComponent = (component, source, parentIntegrationName, lineage) => {
+    const integrationName = component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
+    const componentMeta = component.config?.__eco;
+    const isForeignToParent = integrationName !== parentIntegrationName;
+    const componentId = componentMeta?.id ?? componentMeta?.file ?? `${source}:${nextSyntheticId += 1}`;
+    const nextLineage = new Set(lineage);
+    nextLineage.add(component);
+    const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {
+      if (!child || nextLineage.has(child)) {
+        return [];
+      }
+      return [mapComponent(child, "dependency", integrationName, nextLineage)];
+    });
+    return input.mapNode(
+      {
+        component,
+        source,
+        parentIntegrationName,
+        integrationName,
+        componentId,
+        isForeignToParent
+      },
+      children
+    );
+  };
+  return input.roots.map(
+    ({ component, source }) => mapComponent(component, source, input.currentIntegrationName, /* @__PURE__ */ new Set())
+  );
+}
+const mapDeclaredOwnershipGraph = mapComponentGraph;
+export {
+  mapComponentGraph,
+  mapDeclaredOwnershipGraph,
+  walkComponentGraph
+};

package/src/route-renderer/orchestration/component-render-context.d.ts

@@ -12,13 +12,6 @@ export type ForeignChildInterceptionResult = {
 } | {
     kind: 'resolved';
     value: unknown;
-};
-export type ForeignChildRenderInterception = {
-    kind: 'inline';
-    props?: Record<string, unknown>;
-} | {
-    kind: 'resolved';
-    value: unknown;
 } | undefined;
 /**
  * Foreign-child metadata passed into the active renderer-owned runtime.
@@ -44,7 +37,7 @@ export interface ForeignChildRuntime {
      * which decides whether the child stays inline or leaves the current renderer.
      */
     interceptForeignChild?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult | Promise<ForeignChildInterceptionResult>;
-    interceptForeignChildSync?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult;
+    interceptForeignChildSync?(input: ForeignChildInterceptionInput): Exclude<ForeignChildInterceptionResult, undefined>;
 }
 type ForeignChildRenderInput = {
     component: EcoComponent;
@@ -58,7 +51,7 @@ type ForeignChildRenderInput = {
 export type ComponentRenderContext = {
     currentIntegration: string;
     foreignChildRuntime?: ForeignChildRuntime;
-    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
+    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildInterceptionResult> | ForeignChildInterceptionResult;
     finalizeComponentRender<T>(component: EcoComponent, content: T): T;
 };
 /**
@@ -72,7 +65,7 @@ export declare function getComponentRenderContext(): ComponentRenderContext | un
  *
  * The active runtime may resolve the foreign child immediately or keep it inline.
  */
-export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
+export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildInterceptionResult> | ForeignChildInterceptionResult;
 /**
  * Applies lazy trigger or injector wrapping to completed component output.
  *

package/src/route-renderer/orchestration/component-render-context.js

@@ -51,7 +51,9 @@ class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
     const asyncInterception = this.context.foreignChildRuntime?.interceptForeignChild?.(foreignChildRuntimeInput);
     if (asyncInterception !== void 0) {
       if (isThenable(asyncInterception)) {
-        return asyncInterception.then((result) => this.applyForeignChildInterceptionResult(result));
+        return asyncInterception.then(
+          (result) => result === void 0 ? void 0 : this.applyForeignChildInterceptionResult(result)
+        );
       }
       return this.applyForeignChildInterceptionResult(asyncInterception);
     }

package/src/route-renderer/orchestration/declared-ownership-graph.d.ts

@@ -1,18 +1 @@
-import type { EcoComponent, OwnershipPlanNodeSource } from '../../types/public-types.js';
-export type DeclaredOwnershipRoot = {
-    component: EcoComponent;
-    source: Extract<OwnershipPlanNodeSource, 'page' | 'layout' | 'html-template'>;
-};
-export type DeclaredOwnershipNodeInput = {
-    component: EcoComponent;
-    source: Exclude<OwnershipPlanNodeSource, 'route'>;
-    parentIntegrationName: string;
-    integrationName: string;
-    componentId: string;
-    isForeignToParent: boolean;
-};
-export declare function mapDeclaredOwnershipGraph<T>(input: {
-    roots: DeclaredOwnershipRoot[];
-    currentIntegrationName: string;
-    mapNode: (node: DeclaredOwnershipNodeInput, children: T[]) => T;
-}): T[];
+export { mapComponentGraph, mapDeclaredOwnershipGraph, type ComponentGraphRoot, type ComponentGraphWalkInput, type DeclaredOwnershipNodeInput, type DeclaredOwnershipRoot, } from './component-graph.js';

package/src/route-renderer/orchestration/declared-ownership-graph.js

@@ -1,34 +1,8 @@
-function mapDeclaredOwnershipGraph(input) {
-  let nextSyntheticId = 0;
-  const mapComponent = (component, source, parentIntegrationName, lineage) => {
-    const integrationName = component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
-    const componentMeta = component.config?.__eco;
-    const isForeignToParent = integrationName !== parentIntegrationName;
-    const componentId = componentMeta?.id ?? componentMeta?.file ?? `${source}:${nextSyntheticId += 1}`;
-    const nextLineage = new Set(lineage);
-    nextLineage.add(component);
-    const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {
-      if (!child || nextLineage.has(child)) {
-        return [];
-      }
-      return [mapComponent(child, "dependency", integrationName, nextLineage)];
-    });
-    return input.mapNode(
-      {
-        component,
-        source,
-        parentIntegrationName,
-        integrationName,
-        componentId,
-        isForeignToParent
-      },
-      children
-    );
-  };
-  return input.roots.map(
-    ({ component, source }) => mapComponent(component, source, input.currentIntegrationName, /* @__PURE__ */ new Set())
-  );
-}
+import {
+  mapComponentGraph,
+  mapDeclaredOwnershipGraph
+} from "./component-graph.js";
 export {
+  mapComponentGraph,
   mapDeclaredOwnershipGraph
 };

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

@@ -0,0 +1,90 @@
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+export type DocumentShellLayoutInput = {
+    component: EcoComponent;
+    props?: Record<string, unknown>;
+};
+export type DocumentShellComposeChildrenContext = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    primaryRender?: ComponentRenderResult;
+    layouts: DocumentShellLayoutInput[];
+    rendererCache: BaseIntegrationContext['rendererCache'];
+    renderComponentWithForeignChildren: DocumentShellRenderDependencies['renderComponentWithForeignChildren'];
+};
+export type DocumentShellComposeChildrenResult = {
+    /** Serialized or element children passed to the HTML template shell. */
+    children: unknown;
+    layoutRenders: ComponentRenderResult[];
+    /**
+     * Primary/page render assets when the hook performs unified composition.
+     *
+     * @remarks
+     * Omit only when the default sequential string path runs (core renders primary first).
+     */
+    primaryRender?: ComponentRenderResult;
+};
+/**
+ * Optional hook that replaces default sequential string layout wrapping.
+ *
+ * @remarks
+ * When provided, core skips the initial primary render and expects the hook to return
+ * `children` for the HTML template. Supply `primaryRender` so dependency assets still merge.
+ */
+export type DocumentShellComposeChildrenHook = (context: DocumentShellComposeChildrenContext) => Promise<DocumentShellComposeChildrenResult>;
+export type DocumentShellComposeInput = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
+    htmlTemplate: EcoComponent;
+    documentProps: Record<string, unknown>;
+};
+export type DocumentShellPageRenderInput = {
+    page: {
+        component: EcoComponent;
+        props: Record<string, unknown>;
+    };
+    layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
+    htmlTemplate: EcoComponent;
+    metadata: PageMetadataProps;
+    pageProps: Record<string, unknown>;
+    documentProps?: Record<string, unknown>;
+    transformDocumentHtml?: (html: string) => string;
+};
+export type DocumentShellRenderDependencies = {
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+};
+export type DocumentShellAttributeStamping = {
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+};
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export declare function composeSequentialLayoutChildren(context: DocumentShellComposeChildrenContext): Promise<DocumentShellComposeChildrenResult>;
+/**
+ * Composes page or view content through optional layout and document shells.
+ *
+ * One execution-scoped renderer cache is threaded through every shell layer so
+ * repeated foreign delegation reuses initialized renderers within one render pass.
+ */
+export declare function composeDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellComposeInput): Promise<{
+    documentHtml: string;
+}>;
+/**
+ * Applies optional component-root and document-root attribute stamping before HTML
+ * transformation runs on explicit renderer-owned paths.
+ */
+export declare function applyDocumentShellAttributeStamping(html: string, stamping: DocumentShellAttributeStamping, options: {
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+}): string;
+/**
+ * Builds the final serialized document HTML for one route page render.
+ */
+export declare function renderPageDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellPageRenderInput, docType: string): Promise<string>;