@ecopages/core 0.2.0-alpha.16 → 0.2.0-alpha.17

package/CHANGELOG.md

@@ -9,12 +9,15 @@ All notable changes to `@ecopages/core` are documented here.
 ### Features
 
 - Added app-owned runtime and build ownership around `createApp()`, host module loading, the browser-safe `eco` export, `eco.html()`, `eco.layout()`, and the published `EcoPagesAppConfig` surface.
+- Added boundary-plan metadata and a compatibility `renderBoundary()` payload contract for mixed-renderer orchestration.
 
 ### Refactoring
 
 - Consolidated runtime state around shared module-loading services, app-owned build execution, and the universal `createApp()` boundary.
 - Simplified route-renderer orchestration around renderer-owned boundary runtimes, shared string-boundary queue helpers, and a smaller component render context.
 - Centralized shared integration renderer bootstrapping so package integrations only append renderer-specific config instead of duplicating core lifecycle wiring.
+- Moved shared queued boundary resolution to attachment-policy payloads and constructor-injectable planning services.
+- Extracted shared page, layout, and document-shell composition into a narrow `RouteShellComposer` while keeping renderer-owned boundary handoff in `IntegrationRenderer`.
 - Removed marker-era compatibility capture, the shared route-level fallback resolver, deprecated `@ecopages/core/node*` escape hatches, and other dead route-renderer internals.
 
 ### Bug Fixes
@@ -34,6 +37,7 @@ All notable changes to `@ecopages/core` are documented here.
 
 - Added regression coverage for app-owned runtime services, Node fallback paths, and cross-runtime invalidation behavior.
 - Strengthened the core ghtml integration tests so route and explicit render paths await real outcomes and cover `renderToResponse` behavior.
+- Added core regression coverage for boundary plans, payload contracts, and typed mixed-boundary context flow.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.16",
+  "version": "0.2.0-alpha.17",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.16",
+    "@ecopages/file-system": "0.2.0-alpha.17",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.3",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",

package/src/config/config-builder.d.ts

@@ -27,15 +27,6 @@ type RuntimeKind = 'node' | 'bun';
  * Provides a fluent interface for setting various configuration options and managing
  * application settings.
  *
- * @example
- * ```typescript
- * const config = new ConfigBuilder()
- *   .setBaseUrl('https://example.com')
- *   .setRootDir('./myproject')
- *   .setSrcDir('source')
- *   .build();
- * ```
- *
  * @remarks
  * The ConfigBuilder follows the builder pattern and allows for:
  * - Setting directory paths for various components (pages, includes, layouts, etc.)

package/src/config/config-builder.js

@@ -14,7 +14,8 @@ import {
   updateAppBuildManifest
 } from "../build/build-adapter.js";
 import { createAppBuildExecutor } from "../build/dev-build-coordinator.js";
-import { GHTML_PLUGIN_NAME, ghtmlPlugin } from "../integrations/ghtml/ghtml.plugin.js";
+import { GHTML_PLUGIN_NAME } from "../integrations/ghtml/ghtml.constants.js";
+import { ghtmlPlugin } from "../integrations/ghtml/ghtml.plugin.js";
 import { createEcoComponentMetaPlugin } from "../plugins/eco-component-meta-plugin.js";
 import { createEcoComponentMetaTransform } from "../plugins/eco-component-meta-plugin.js";
 import {

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

@@ -1,7 +1,7 @@
 import {
   IntegrationRenderer
 } from "../../route-renderer/orchestration/integration-renderer.js";
-import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;
   async renderComponent(input) {

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

@@ -0,0 +1 @@
+export declare const GHTML_PLUGIN_NAME = "ghtml";

package/src/integrations/ghtml/ghtml.constants.js

@@ -0,0 +1,4 @@
+const GHTML_PLUGIN_NAME = "ghtml";
+export {
+  GHTML_PLUGIN_NAME
+};

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

@@ -1,9 +1,5 @@
 import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
 import { GhtmlRenderer } from './ghtml-renderer.js';
-/**
- * The name of the ghtml plugin
- */
-export declare const GHTML_PLUGIN_NAME = "ghtml";
 /**
  * The Ghtml plugin class
  * This plugin provides support for ghtml components in Ecopages

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

@@ -1,6 +1,6 @@
 import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
 import { GhtmlRenderer } from "./ghtml-renderer.js";
-const GHTML_PLUGIN_NAME = "ghtml";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlPlugin extends IntegrationPlugin {
   renderer = GhtmlRenderer;
   constructor(options) {
@@ -15,7 +15,6 @@ function ghtmlPlugin(options) {
   return new GhtmlPlugin(options);
 }
 export {
-  GHTML_PLUGIN_NAME,
   GhtmlPlugin,
   ghtmlPlugin
 };

package/src/route-renderer/README.md

@@ -26,6 +26,7 @@ Framework-owned orchestration services and renderer base class:
 - `integration-renderer.ts`: abstract base class that coordinates end-to-end route rendering.
 - `render-preparation.service.ts`: page module/data/dependency preparation before render.
 - `render-execution.service.ts`: render capture, unresolved boundary artifact enforcement, and finalization.
+- `route-shell-composer.service.ts`: shared page/view/layout/html-template shell composition used by multiple integrations.
 - `queued-boundary-runtime.service.ts`: shared queued foreign-boundary runtime used directly by renderer-owned helpers, including string-first renderers.
 
 It also provides:
@@ -59,28 +60,65 @@ Default behavior:
 - renderer-owned component-boundary orchestration + component render artifacts.
 - global lazy trigger map + global injector bootstrap.
 
+## Mixed Renderer Mental Model
+
+The current mixed-renderer contract has four phases:
+
+1. `render-preparation.service.ts` builds the route inputs and a conservative `boundaryPlan` from declared component dependencies.
+2. The selected integration renderer owns page, layout, document-shell, and explicit-view composition for that route.
+3. `route-shell-composer.service.ts` applies the shared page/view/layout/html-template composition flow while calling back into the owning renderer for each boundary render.
+4. Renderer-owned boundary runtimes resolve foreign nested components through the owning renderer and exchange a compatibility `renderBoundary()` payload with explicit attachment-policy semantics.
+5. `render-execution.service.ts` finalizes the response and fails if unresolved boundary artifact HTML survives the renderer-owned resolution pass.
+
+Important:
+
+- Renderer-owned deferral is intentional. Ecopages does not run a route-level fallback resolver after render completion.
+- Boundary ownership is planned from declared component dependency metadata, not inferred purely from rendered HTML.
+- Same-integration children do not have to pass through one universal string-only transport. Each renderer keeps its own child transport rules for same-integration trees.
+
+## Declared Foreign Child Contract
+
+Mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`. The planning pass uses those declarations to describe ownership transitions and surface invalid or unknown foreign owners before render execution.
+
+Current behavior:
+
+- Missing or unknown ownership is recorded on the route `boundaryPlan` as validation errors.
+- Renderer-owned runtime discovery still resolves actual foreign descendants during render.
+- If unresolved boundary artifact HTML reaches route finalization, Ecopages throws instead of attempting a route-level recovery pass.
+
 Global injector lifecycle notes:
 
 - The bootstrap remains active across client-side navigations.
 - On `eco:after-swap`, it prunes stale `ecopages/global-injector-map` scripts and calls `refresh()` so newly swapped `data-eco-trigger` elements can bind their lazy rules.
 - It must not call injector `cleanup()` on every swap, because that permanently disables future refresh work for the current runtime instance.
 
-## Current Component Artifact Contract
+## Boundary Payload Contract
 
-Integration `renderComponent()` returns `ComponentRenderResult` with:
+The compatibility boundary API is `renderBoundary()`. Today it wraps the existing `renderComponentBoundary()` behavior and returns a narrower payload:
 
 - `html`
-- `canAttachAttributes`
+- `assets`
 - `rootTag`
 - `integrationName`
 - optional `rootAttributes`
-- optional `assets`
+- `attachmentPolicy`
+
+`renderComponent()` still returns `ComponentRenderResult` internally, including `canAttachAttributes`, because renderer-local implementations have not been collapsed into one universal boundary primitive.
+
+Base orchestration uses the compatibility payload to:
 
-Current base orchestration behavior:
+- keep queued foreign-boundary resolution renderer-owned
+- apply root attributes only when `attachmentPolicy.kind === 'first-element'`
+- preserve asset bubbling through the normal dependency pipeline
 
-- Calls `renderComponent()` for the page root component.
-- Merges returned `assets` into processed dependencies.
-- Applies returned `rootAttributes` to the first element under `<body>`.
+The lower-level `ComponentRenderResult` currently includes:
+
+- `html`
+- `canAttachAttributes`
+- `rootTag`
+- `integrationName`
+- optional `rootAttributes`
+- optional `assets`
 
 When rendered output still contains unresolved boundary artifact HTML:
 
@@ -114,3 +152,5 @@ If you are reading this file to understand today's contract, you can stop at the
 
 - Deep multi-level mixed-integration trees now rely on renderer-owned boundary runtimes rather than a shared post-render graph resolver.
 - Each renderer still decides how to hand off foreign boundaries, so specialized runtimes remain appropriate where child serialization or hydration contracts differ.
+- `boundaryPlan` is currently preparation-time metadata and diagnostics. It does not yet drive a full route-composer execution model.
+- A narrow `RouteShellComposer` now owns shared shell composition, but a broader route composer that absorbs boundary ownership or execution flow is still deferred.

package/src/route-renderer/orchestration/boundary-planning.service.d.ts

@@ -0,0 +1,25 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { BoundaryPlan, EcoComponent } from '../../types/public-types.js';
+type BoundaryPlanBuildInput = {
+    routeFile: string;
+    currentIntegrationName: string;
+    HtmlTemplate: EcoComponent;
+    Layout?: EcoComponent;
+    Page: EcoComponent;
+};
+/**
+ * Builds a declared ownership plan from the component dependency graph.
+ *
+ * The plan is intentionally conservative: it reflects declared component
+ * dependencies available during render preparation and records diagnostics for
+ * foreign ownership edges that cannot be validated against registered
+ * integrations or stable component metadata.
+ */
+export declare class BoundaryPlanningService {
+    private readonly appConfig;
+    private nextSyntheticId;
+    constructor(appConfig: EcoPagesAppConfig);
+    buildPlan(input: BoundaryPlanBuildInput): BoundaryPlan;
+    private isRegisteredIntegration;
+}
+export {};

package/src/route-renderer/orchestration/boundary-planning.service.js

@@ -0,0 +1,97 @@
+class BoundaryPlanningService {
+  appConfig;
+  nextSyntheticId = 0;
+  constructor(appConfig) {
+    this.appConfig = appConfig;
+  }
+  buildPlan(input) {
+    this.nextSyntheticId = 0;
+    const validationErrors = [];
+    const rendererNames = /* @__PURE__ */ new Set([input.currentIntegrationName]);
+    let foreignEdgeCount = 0;
+    const buildNode = (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}:${this.nextSyntheticId += 1}`;
+      rendererNames.add(integrationName);
+      if (isForeignToParent) {
+        foreignEdgeCount += 1;
+        if (!componentMeta) {
+          validationErrors.push({
+            code: "MISSING_COMPONENT_METADATA",
+            message: `[ecopages] Foreign boundary "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
+            componentId,
+            integrationName
+          });
+        }
+        if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
+          validationErrors.push({
+            code: "UNKNOWN_INTEGRATION_OWNER",
+            message: `[ecopages] Foreign boundary "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
+            componentId,
+            componentFile: componentMeta?.file,
+            integrationName
+          });
+        }
+      }
+      const nextLineage = new Set(lineage);
+      nextLineage.add(component);
+      const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {
+        if (!child || nextLineage.has(child)) {
+          return [];
+        }
+        return [buildNode(child, "dependency", integrationName, nextLineage)];
+      });
+      return {
+        id: componentId,
+        source,
+        ownership: {
+          integrationName,
+          componentId,
+          componentFile: componentMeta?.file,
+          isPageEntry: source === "page",
+          isForeignToParent
+        },
+        children,
+        declaredDependenciesValid: true
+      };
+    };
+    const roots = [
+      { component: input.HtmlTemplate, source: "html-template" },
+      ...input.Layout ? [{ component: input.Layout, source: "layout" }] : [],
+      { component: input.Page, source: "page" }
+    ];
+    const root = {
+      id: `route:${input.routeFile}`,
+      source: "route",
+      ownership: {
+        integrationName: input.currentIntegrationName,
+        componentId: `route:${input.routeFile}`,
+        componentFile: input.routeFile,
+        isPageEntry: false,
+        isForeignToParent: false
+      },
+      children: roots.map(
+        ({ component, source }) => buildNode(component, source, input.currentIntegrationName, /* @__PURE__ */ new Set())
+      ),
+      declaredDependenciesValid: validationErrors.length === 0
+    };
+    return {
+      root,
+      rendererNames: Array.from(rendererNames),
+      foreignEdgeCount,
+      hasValidationErrors: validationErrors.length > 0,
+      validationErrors
+    };
+  }
+  isRegisteredIntegration(integrationName, currentIntegrationName) {
+    if (integrationName === currentIntegrationName) {
+      return true;
+    }
+    return this.appConfig.integrations.some((integration) => integration.name === integrationName);
+  }
+}
+export {
+  BoundaryPlanningService
+};

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

@@ -4,7 +4,7 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentDependencies, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetMetadataContext, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, BoundaryRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetMetadataContext, GetStaticProps, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, 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 { HttpError } from '../../errors/http-error.js';
@@ -12,6 +12,7 @@ import { DependencyResolverService } from '../page-loading/dependency-resolver.j
 import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
 import { RenderExecutionService } from './render-execution.service.js';
 import { RenderPreparationService } from './render-preparation.service.js';
+import { RouteShellComposer } from './route-shell-composer.service.js';
 import type { ComponentBoundaryRuntime } from './component-render-context.js';
 import { QueuedBoundaryRuntimeService, type QueuedBoundaryResolution, type QueuedBoundaryRuntimeContext } from './queued-boundary-runtime.service.js';
 type BoundaryRenderDecisionInput = {
@@ -56,6 +57,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     protected pageModuleLoaderService: PageModuleLoaderService;
     protected renderPreparationService: RenderPreparationService;
     protected renderExecutionService: RenderExecutionService;
+    protected readonly routeShellComposer: RouteShellComposer;
     protected readonly queuedBoundaryRuntimeService: QueuedBoundaryRuntimeService;
     protected DOC_TYPE: string;
     /**
@@ -238,11 +240,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         rendererCache: Map<string, IntegrationRenderer<any>>;
         runtimeContextKey?: string;
         tokenPrefix?: string;
-        createRuntimeContext?: (integrationContext: {
-            rendererCache?: Map<string, unknown>;
-            componentInstanceId?: string;
-            [key: string]: unknown;
-        }, rendererCache: Map<string, unknown>) => TContext;
+        createRuntimeContext?: (integrationContext: BaseIntegrationContext & Record<string, unknown>, rendererCache: Map<string, unknown>) => TContext;
     }): ComponentBoundaryRuntime;
     protected resolveRendererOwnedQueuedBoundaryHtml<TContext extends QueuedBoundaryRuntimeContext>(options: {
         html: string;
@@ -460,6 +458,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     abstract render(options: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
     protected resolveBoundaryInOwningRenderer(input: ComponentRenderInput, rendererCache: Map<string, IntegrationRenderer<any>>): Promise<ComponentRenderResult | undefined>;
+    protected resolveBoundaryPayloadInOwningRenderer(input: ComponentRenderInput, rendererCache: Map<string, IntegrationRenderer<any>>): Promise<BoundaryRenderPayload | undefined>;
     /**
      * Renders one component under this integration's boundary runtime and resolves
      * any nested foreign boundaries captured during that render.
@@ -469,6 +468,12 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * renderer's nested-boundary handoff.
      */
     renderComponentBoundary(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    /**
+     * Compatibility boundary contract that exposes a narrower payload shape for
+     * future route-composition work while preserving the current
+     * `renderComponentBoundary()` runtime semantics.
+     */
+    renderBoundary(input: ComponentRenderInput): Promise<BoundaryRenderPayload>;
     private normalizeComponentBoundaryRender;
     protected normalizeBoundaryArtifactHtml(html: string): string;
     /**

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

@@ -8,6 +8,7 @@ import { DependencyResolverService } from "../page-loading/dependency-resolver.j
 import { PageModuleLoaderService } from "../page-loading/page-module-loader.js";
 import { RenderExecutionService } from "./render-execution.service.js";
 import { RenderPreparationService } from "./render-preparation.service.js";
+import { RouteShellComposer } from "./route-shell-composer.service.js";
 import { normalizeBoundaryArtifactHtml } from "./render-output.utils.js";
 import { getComponentRenderContext, runWithComponentRenderContext } from "./component-render-context.js";
 import {
@@ -54,6 +55,7 @@ class IntegrationRenderer {
   pageModuleLoaderService;
   renderPreparationService;
   renderExecutionService;
+  routeShellComposer = new RouteShellComposer();
   queuedBoundaryRuntimeService = new QueuedBoundaryRuntimeService();
   DOC_TYPE = "<!DOCTYPE html>";
   /**
@@ -81,7 +83,7 @@ class IntegrationRenderer {
    * @returns The current execution cache when present.
    */
   getBoundaryRendererCache(integrationContext) {
-    if (typeof integrationContext === "object" && integrationContext !== null && "rendererCache" in integrationContext && integrationContext.rendererCache instanceof Map) {
+    if (integrationContext?.rendererCache instanceof Map) {
       return integrationContext.rendererCache;
     }
     return void 0;
@@ -107,9 +109,10 @@ class IntegrationRenderer {
    */
   withBoundaryRendererCache(input, rendererCache) {
     const integrationContext = input.integrationContext;
+    const sharedRendererCache = rendererCache;
     return {
       ...input,
-      integrationContext: typeof integrationContext === "object" && integrationContext !== null ? { ...integrationContext, rendererCache } : { rendererCache }
+      integrationContext: integrationContext ? { ...integrationContext, rendererCache: sharedRendererCache } : { rendererCache: sharedRendererCache }
     };
   }
   getRendererModuleValue(key) {
@@ -259,17 +262,17 @@ class IntegrationRenderer {
    * @returns HTML response for the partial render.
    */
   async renderPartialViewResponse(input) {
-    if (input.renderInline && !this.hasForeignBoundaryDescendants(input.view)) {
-      return this.createHtmlResponse(await input.renderInline(), input.ctx);
-    }
-    const rendererCache = /* @__PURE__ */ new Map();
-    const viewRender = await this.renderComponentBoundary({
-      component: input.view,
-      props: input.props ?? {},
-      integrationContext: { rendererCache }
+    return this.routeShellComposer.renderPartialViewResponse(input, {
+      hasForeignBoundaryDescendants: (component) => this.hasForeignBoundaryDescendants(component),
+      createHtmlResponse: (body, ctx) => this.createHtmlResponse(body, ctx),
+      renderComponentBoundary: (boundaryInput) => this.renderComponentBoundary(boundaryInput),
+      prepareViewDependencies: (view, layout) => this.prepareViewDependencies(view, layout),
+      getHtmlTemplate: () => this.getHtmlTemplate(),
+      resolveViewMetadata: (view, props) => this.resolveViewMetadata(view, props),
+      appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
+      finalizeResolvedHtml: (options) => this.finalizeResolvedHtml(options),
+      docType: this.DOC_TYPE
     });
-    const html = input.transformHtml ? input.transformHtml(viewRender.html) : viewRender.html;
-    return this.createHtmlResponse(html, input.ctx);
   }
   /**
    * Renders an explicit view through optional layout and document shells.
@@ -284,44 +287,17 @@ class IntegrationRenderer {
    * @returns HTML response for the explicit view render.
    */
   async renderViewWithDocumentShell(input) {
-    const normalizedProps = input.props ?? {};
-    if (input.ctx.partial) {
-      return this.renderPartialViewResponse({
-        view: input.view,
-        props: input.props,
-        ctx: input.ctx
-      });
-    }
-    await this.prepareViewDependencies(input.view, input.layout);
-    const HtmlTemplate = await this.getHtmlTemplate();
-    const metadata = await this.resolveViewMetadata(input.view, input.props);
-    const rendererCache = /* @__PURE__ */ new Map();
-    const viewRender = await this.renderComponentBoundary({
-      component: input.view,
-      props: normalizedProps,
-      integrationContext: { rendererCache }
-    });
-    const layoutRender = input.layout ? await this.renderComponentBoundary({
-      component: input.layout,
-      props: {},
-      children: viewRender.html,
-      integrationContext: { rendererCache }
-    }) : void 0;
-    const documentRender = await this.renderComponentBoundary({
-      component: HtmlTemplate,
-      props: {
-        metadata,
-        pageProps: normalizedProps
-      },
-      children: layoutRender?.html ?? viewRender.html,
-      integrationContext: { rendererCache }
-    });
-    this.appendProcessedDependencies(viewRender.assets, layoutRender?.assets, documentRender.assets);
-    const html = await this.finalizeResolvedHtml({
-      html: `${this.DOC_TYPE}${documentRender.html}`,
-      partial: false
+    return this.routeShellComposer.renderViewWithDocumentShell(input, {
+      hasForeignBoundaryDescendants: (component) => this.hasForeignBoundaryDescendants(component),
+      createHtmlResponse: (body, ctx) => this.createHtmlResponse(body, ctx),
+      renderComponentBoundary: (boundaryInput) => this.renderComponentBoundary(boundaryInput),
+      prepareViewDependencies: (view, layout) => this.prepareViewDependencies(view, layout),
+      getHtmlTemplate: () => this.getHtmlTemplate(),
+      resolveViewMetadata: (view, props) => this.resolveViewMetadata(view, props),
+      appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
+      finalizeResolvedHtml: (options) => this.finalizeResolvedHtml(options),
+      docType: this.DOC_TYPE
     });
-    return this.createHtmlResponse(html, input.ctx);
   }
   /**
    * Renders a route page through optional layout and document shells.
@@ -336,31 +312,17 @@ class IntegrationRenderer {
    * @returns Final serialized document HTML including the doctype prefix.
    */
   async renderPageWithDocumentShell(input) {
-    const rendererCache = /* @__PURE__ */ new Map();
-    const pageRender = await this.renderComponentBoundary({
-      component: input.page.component,
-      props: input.page.props,
-      integrationContext: { rendererCache }
-    });
-    const layoutRender = input.layout ? await this.renderComponentBoundary({
-      component: input.layout.component,
-      props: input.layout.props ?? {},
-      children: pageRender.html,
-      integrationContext: { rendererCache }
-    }) : void 0;
-    const documentRender = await this.renderComponentBoundary({
-      component: input.htmlTemplate,
-      props: {
-        metadata: input.metadata,
-        pageProps: input.pageProps,
-        ...input.documentProps ?? {}
-      },
-      children: layoutRender?.html ?? pageRender.html,
-      integrationContext: { rendererCache }
+    return this.routeShellComposer.renderPageWithDocumentShell(input, {
+      hasForeignBoundaryDescendants: (component) => this.hasForeignBoundaryDescendants(component),
+      createHtmlResponse: (body, ctx) => this.createHtmlResponse(body, ctx),
+      renderComponentBoundary: (boundaryInput) => this.renderComponentBoundary(boundaryInput),
+      prepareViewDependencies: (view, layout) => this.prepareViewDependencies(view, layout),
+      getHtmlTemplate: () => this.getHtmlTemplate(),
+      resolveViewMetadata: (view, props) => this.resolveViewMetadata(view, props),
+      appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
+      finalizeResolvedHtml: (options) => this.finalizeResolvedHtml(options),
+      docType: this.DOC_TYPE
     });
-    this.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
-    const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(documentRender.html) : documentRender.html;
-    return `${this.DOC_TYPE}${documentHtml}`;
   }
   /**
    * Renders one string-first component boundary and collects its assets.
@@ -423,7 +385,10 @@ class IntegrationRenderer {
       runtimeContext: options.runtimeContext,
       queueLabel: options.queueLabel,
       renderQueuedChildren: options.renderQueuedChildren,
-      resolveBoundary: (input, rendererCache) => this.resolveBoundaryInOwningRenderer(input, rendererCache),
+      resolveBoundary: (input, rendererCache) => this.resolveBoundaryPayloadInOwningRenderer(
+        input,
+        rendererCache
+      ),
       applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes),
       dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets)
     });
@@ -798,6 +763,17 @@ class IntegrationRenderer {
     }
     return await owningRenderer.renderComponentBoundary(this.withBoundaryRendererCache(input, rendererCache));
   }
+  async resolveBoundaryPayloadInOwningRenderer(input, rendererCache) {
+    const boundaryOwner = this.getRegisteredBoundaryOwner(input.component);
+    if (!boundaryOwner) {
+      return void 0;
+    }
+    const owningRenderer = this.getIntegrationRendererForName(boundaryOwner, rendererCache);
+    if (owningRenderer === this || owningRenderer.name === this.name) {
+      return void 0;
+    }
+    return await owningRenderer.renderBoundary(this.withBoundaryRendererCache(input, rendererCache));
+  }
   /**
    * Renders one component under this integration's boundary runtime and resolves
    * any nested foreign boundaries captured during that render.
@@ -838,6 +814,22 @@ class IntegrationRenderer {
     );
     return this.normalizeComponentBoundaryRender(execution.value);
   }
+  /**
+   * Compatibility boundary contract that exposes a narrower payload shape for
+   * future route-composition work while preserving the current
+   * `renderComponentBoundary()` runtime semantics.
+   */
+  async renderBoundary(input) {
+    const result = await this.renderComponentBoundary(input);
+    return {
+      html: result.html,
+      assets: result.assets ?? [],
+      rootTag: result.rootTag,
+      rootAttributes: result.rootAttributes,
+      attachmentPolicy: result.canAttachAttributes ? { kind: "first-element" } : { kind: "none" },
+      integrationName: result.integrationName
+    };
+  }
   normalizeComponentBoundaryRender(result) {
     const normalizedHtml = this.normalizeBoundaryArtifactHtml(result.html);
     return normalizedHtml === result.html ? result : {

package/src/route-renderer/orchestration/queued-boundary-runtime.service.d.ts

@@ -1,5 +1,5 @@
 import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent } from '../../types/public-types.js';
+import type { BaseIntegrationContext, BoundaryRenderPayload, ComponentRenderInput, EcoComponent } from '../../types/public-types.js';
 import type { ComponentBoundaryRuntime } from './component-render-context.js';
 export type QueuedBoundaryDecisionInput = {
     currentIntegration: string;
@@ -26,11 +26,7 @@ export type QueuedBoundaryRuntimeContext = {
     nextBoundaryId: number;
     queuedResolutions: QueuedBoundaryResolution[];
 };
-type QueuedBoundaryIntegrationContext = {
-    rendererCache?: Map<string, unknown>;
-    componentInstanceId?: string;
-    [key: string]: unknown;
-};
+type QueuedBoundaryIntegrationContext = BaseIntegrationContext & Record<string, unknown>;
 type QueuedBoundaryChildRenderResult = {
     assets: ProcessedAsset[];
     html?: string;
@@ -80,7 +76,7 @@ export declare class QueuedBoundaryRuntimeService {
         runtimeContext?: TContext;
         queueLabel: string;
         renderQueuedChildren: (children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedBoundaryResolution>, resolveToken: (token: string) => Promise<string>) => Promise<QueuedBoundaryChildRenderResult>;
-        resolveBoundary: (input: ComponentRenderInput, rendererCache: Map<string, unknown>) => Promise<ComponentRenderResult | undefined>;
+        resolveBoundary: (input: ComponentRenderInput, rendererCache: Map<string, unknown>) => Promise<BoundaryRenderPayload | undefined>;
         applyAttributesToFirstElement: (html: string, attributes: Record<string, string>) => string;
         dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
     }): Promise<{

package/src/route-renderer/orchestration/queued-boundary-runtime.service.js

@@ -105,7 +105,7 @@ class QueuedBoundaryRuntimeService {
         if ((boundaryRender.assets?.length ?? 0) > 0) {
           collectedAssets.push(...boundaryRender.assets ?? []);
         }
-        const resolvedHtml2 = boundaryRender.canAttachAttributes && boundaryRender.rootAttributes ? options.applyAttributesToFirstElement(boundaryRender.html, boundaryRender.rootAttributes) : boundaryRender.html;
+        const resolvedHtml2 = boundaryRender.attachmentPolicy.kind === "first-element" && boundaryRender.rootAttributes ? options.applyAttributesToFirstElement(boundaryRender.html, boundaryRender.rootAttributes) : boundaryRender.html;
         resolvedHtmlByToken.set(token, resolvedHtml2);
         return resolvedHtml2;
       } finally {

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

@@ -1,6 +1,7 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererOptions } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import { BoundaryPlanningService } from './boundary-planning.service.js';
 type ResolvedPageModule = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
     getStaticProps?: GetStaticProps<Record<string, unknown>>;
@@ -32,6 +33,9 @@ export interface RenderPreparationCallbacks {
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
     createPageLocalsProxy(filePath: string): RouteRendererOptions['locals'];
 }
+export interface RenderPreparationServiceDependencies {
+    boundaryPlanningService?: BoundaryPlanningService;
+}
 /**
  * Prepares the normalized render inputs consumed by `IntegrationRenderer.execute()`.
  *
@@ -43,6 +47,7 @@ export interface RenderPreparationCallbacks {
 export declare class RenderPreparationService {
     private appConfig;
     private assetProcessingService;
+    private readonly boundaryPlanningService;
     /**
      * Creates the render-preparation orchestrator for one app instance.
      *
@@ -50,7 +55,7 @@ export declare class RenderPreparationService {
      * The service is app-scoped because it depends on finalized config defaults and
      * the app-owned asset-processing pipeline while remaining renderer-agnostic.
      */
-    constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService, dependencies?: RenderPreparationServiceDependencies);
     /**
      * Builds the final render options object used by the integration-specific
      * renderer.

package/src/route-renderer/orchestration/render-preparation.service.js

@@ -1,13 +1,14 @@
 import { createRequire } from "node:module";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import {
   AssetFactory
 } from "../../services/assets/asset-processing-service/index.js";
 import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../../eco/global-injector-map.js";
+import { BoundaryPlanningService } from "./boundary-planning.service.js";
 class RenderPreparationService {
   appConfig;
   assetProcessingService;
+  boundaryPlanningService;
   /**
    * Creates the render-preparation orchestrator for one app instance.
    *
@@ -15,9 +16,10 @@ class RenderPreparationService {
    * The service is app-scoped because it depends on finalized config defaults and
    * the app-owned asset-processing pipeline while remaining renderer-agnostic.
    */
-  constructor(appConfig, assetProcessingService) {
+  constructor(appConfig, assetProcessingService, dependencies = {}) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
+    this.boundaryPlanningService = dependencies.boundaryPlanningService ?? new BoundaryPlanningService(appConfig);
   }
   /**
    * Builds the final render options object used by the integration-specific
@@ -39,6 +41,13 @@ class RenderPreparationService {
     const HtmlTemplate = await callbacks.getHtmlTemplate();
     const { props, metadata } = await callbacks.resolvePageData(pageModule, routeOptions);
     const Layout = Page.config?.layout;
+    const boundaryPlan = this.boundaryPlanningService.buildPlan({
+      routeFile: routeOptions.file,
+      currentIntegrationName,
+      HtmlTemplate,
+      Layout,
+      Page
+    });
     const componentsToResolve = Layout ? [HtmlTemplate, Layout, Page] : [HtmlTemplate, Page];
     const resolvedDependencies = await callbacks.resolveDependencies(componentsToResolve);
     const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(
@@ -95,7 +104,8 @@ class RenderPreparationService {
       pageProps,
       locals,
       pageLocals,
-      cacheStrategy
+      cacheStrategy,
+      boundaryPlan
     };
     return {
       ...integrationSpecificProps,

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

@@ -0,0 +1,50 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, HtmlTemplateProps, PageMetadataProps } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { RenderToResponseContext } from './integration-renderer.js';
+export interface RouteShellComposerCallbacks {
+    hasForeignBoundaryDescendants(component: EcoComponent): boolean;
+    createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response;
+    renderComponentBoundary(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
+    getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+    resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps>;
+    appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+    finalizeResolvedHtml(options: {
+        html: string;
+        partial?: boolean;
+        componentRootAttributes?: Record<string, string>;
+        documentAttributes?: Record<string, string>;
+        transformHtml?: boolean;
+    }): Promise<string>;
+    docType: string;
+}
+export declare class RouteShellComposer {
+    renderPartialViewResponse<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        renderInline?: () => Promise<BodyInit>;
+        transformHtml?: (html: string) => string;
+    }, callbacks: RouteShellComposerCallbacks): Promise<Response>;
+    renderViewWithDocumentShell<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        layout?: EcoComponent;
+    }, callbacks: RouteShellComposerCallbacks): Promise<Response>;
+    renderPageWithDocumentShell(input: {
+        page: {
+            component: EcoComponent;
+            props: Record<string, unknown>;
+        };
+        layout?: {
+            component: EcoComponent;
+            props?: Record<string, unknown>;
+        };
+        htmlTemplate: EcoComponent;
+        metadata: PageMetadataProps;
+        pageProps: Record<string, unknown>;
+        documentProps?: Record<string, unknown>;
+        transformDocumentHtml?: (html: string) => string;
+    }, callbacks: RouteShellComposerCallbacks): Promise<string>;
+}

package/src/route-renderer/orchestration/route-shell-composer.service.js

@@ -0,0 +1,81 @@
+class RouteShellComposer {
+  async renderPartialViewResponse(input, callbacks) {
+    if (input.renderInline && !callbacks.hasForeignBoundaryDescendants(input.view)) {
+      return callbacks.createHtmlResponse(await input.renderInline(), input.ctx);
+    }
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await callbacks.renderComponentBoundary({
+      component: input.view,
+      props: input.props ?? {},
+      integrationContext: { rendererCache }
+    });
+    const html = input.transformHtml ? input.transformHtml(viewRender.html) : viewRender.html;
+    return callbacks.createHtmlResponse(html, input.ctx);
+  }
+  async renderViewWithDocumentShell(input, callbacks) {
+    const normalizedProps = input.props ?? {};
+    if (input.ctx.partial) {
+      return this.renderPartialViewResponse(input, callbacks);
+    }
+    await callbacks.prepareViewDependencies(input.view, input.layout);
+    const HtmlTemplate = await callbacks.getHtmlTemplate();
+    const metadata = await callbacks.resolveViewMetadata(input.view, input.props);
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await callbacks.renderComponentBoundary({
+      component: input.view,
+      props: normalizedProps,
+      integrationContext: { rendererCache }
+    });
+    const layoutRender = input.layout ? await callbacks.renderComponentBoundary({
+      component: input.layout,
+      props: {},
+      children: viewRender.html,
+      integrationContext: { rendererCache }
+    }) : void 0;
+    const documentRender = await callbacks.renderComponentBoundary({
+      component: HtmlTemplate,
+      props: {
+        metadata,
+        pageProps: normalizedProps
+      },
+      children: layoutRender?.html ?? viewRender.html,
+      integrationContext: { rendererCache }
+    });
+    callbacks.appendProcessedDependencies(viewRender.assets, layoutRender?.assets, documentRender.assets);
+    const html = await callbacks.finalizeResolvedHtml({
+      html: `${callbacks.docType}${documentRender.html}`,
+      partial: false
+    });
+    return callbacks.createHtmlResponse(html, input.ctx);
+  }
+  async renderPageWithDocumentShell(input, callbacks) {
+    const rendererCache = /* @__PURE__ */ new Map();
+    const pageRender = await callbacks.renderComponentBoundary({
+      component: input.page.component,
+      props: input.page.props,
+      integrationContext: { rendererCache }
+    });
+    const layoutRender = input.layout ? await callbacks.renderComponentBoundary({
+      component: input.layout.component,
+      props: input.layout.props ?? {},
+      children: pageRender.html,
+      integrationContext: { rendererCache }
+    }) : void 0;
+    const documentRender = await callbacks.renderComponentBoundary({
+      component: input.htmlTemplate,
+      props: {
+        metadata: input.metadata,
+        pageProps: input.pageProps,
+        ...input.documentProps ?? {}
+      },
+      children: layoutRender?.html ?? pageRender.html,
+      integrationContext: { rendererCache }
+    });
+    callbacks.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
+    const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(documentRender.html) : documentRender.html;
+    return `${callbacks.docType}${documentHtml}`;
+  }
+}
+export {
+  RouteShellComposer
+};

package/src/services/module-loading/node-bootstrap-plugin.js

@@ -165,8 +165,9 @@ function createNodeBootstrapPlugin(options) {
       });
       build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
         const absolutePath = path.resolve(args.path);
-        const shouldPreserveImportMeta = importMetaRewritePaths.has(absolutePath);
-        const shouldRewriteReexports = shouldRewriteBootstrapSource(absolutePath, projectDir);
+        const isProjectSource = shouldRewriteBootstrapSource(absolutePath, projectDir);
+        const shouldPreserveImportMeta = isProjectSource || importMetaRewritePaths.has(absolutePath);
+        const shouldRewriteReexports = isProjectSource;
         if (!shouldPreserveImportMeta && !shouldRewriteReexports) {
           return void 0;
         }

package/src/types/public-types.d.ts

@@ -678,12 +678,66 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
+    boundaryPlan?: BoundaryPlan;
 };
-export interface ComponentRenderInput {
+export type BoundaryValidationErrorCode = 'UNKNOWN_INTEGRATION_OWNER' | 'MISSING_COMPONENT_METADATA';
+export interface BoundaryValidationError {
+    code: BoundaryValidationErrorCode;
+    message: string;
+    componentId?: string;
+    componentFile?: string;
+    integrationName?: string;
+}
+export type BoundaryPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
+export interface BoundaryOwnership {
+    integrationName: string;
+    componentId: string;
+    componentFile?: string;
+    isPageEntry: boolean;
+    isForeignToParent: boolean;
+}
+export interface BoundaryPlanNode {
+    id: string;
+    source: BoundaryPlanNodeSource;
+    ownership: BoundaryOwnership;
+    children: BoundaryPlanNode[];
+    declaredDependenciesValid: boolean;
+}
+export interface BoundaryPlan {
+    root: BoundaryPlanNode;
+    rendererNames: string[];
+    foreignEdgeCount: number;
+    hasValidationErrors: boolean;
+    validationErrors: BoundaryValidationError[];
+}
+export type BoundaryAttachmentPolicy = {
+    kind: 'none';
+} | {
+    kind: 'first-element';
+};
+export interface BoundaryRenderPayload {
+    html: string;
+    assets: ProcessedAsset[];
+    rootTag?: string;
+    rootAttributes?: Record<string, string>;
+    attachmentPolicy: BoundaryAttachmentPolicy;
+    integrationName: string;
+}
+/**
+ * Shared execution-scoped context threaded through component boundary renders.
+ *
+ * Integrations can extend this with renderer-local runtime keys, but the cache
+ * and optional component instance identity are shared across all renderers.
+ */
+export interface BaseIntegrationContext {
+    rendererCache?: Map<string, unknown>;
+    componentInstanceId?: string;
+}
+export interface ComponentRenderInput<TIntegrationContext extends BaseIntegrationContext = BaseIntegrationContext> {
     component: EcoComponent;
     props: Record<string, unknown>;
     children?: unknown;
-    integrationContext?: unknown;
+    integrationContext?: TIntegrationContext;
 }
 export interface ComponentRenderResult {
     html: string;