@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/route-renderer/GRAPH.md

@@ -1,6 +1,6 @@
 # Rendering Logic Graph
 
-This document maps the end-to-end rendering logic in core, including request-time rendering, explicit route rendering, static generation, and marker graph orchestration.
+This document maps the end-to-end rendering logic in core, including request-time rendering, explicit route rendering, static generation, and deferred boundary orchestration.
 
 ## Design Principles
 
@@ -12,16 +12,14 @@ These diagrams are based on a few architectural assumptions that seem important
   Adapters and route matchers decide which renderer to use; once selected, the integration renderer owns the page render pipeline.
 - **Data resolution should happen before HTML transformation.**
   Static props, metadata, dependency processing, and route assets are all upstream of final HTML injection.
-- **Marker graph orchestration should be a post-render reconciliation step.**
-  The initial integration render may emit deferred component markers; those are resolved after the first HTML pass, not during route matching.
-- **Marker emission is integration-defined boundary behavior.**
-  Markers are emitted when the active render boundary policy decides a component boundary must be deferred. If no `eco-marker` tokens are emitted, the marker graph stage is skipped entirely.
-- **The marker pipeline remains generic after emission.**
-  Once markers exist, core resolves them generically through marker graph extraction, integration renderer dispatch, asset collection, and HTML replacement. The current built-in React integration is one concrete consumer of that mechanism.
+- **Deferred boundary orchestration should stay renderer-owned.**
+  The initial integration render is responsible for handing foreign boundaries back to their owning renderer before final route HTML is returned.
+- **Foreign boundary ownership is renderer-defined behavior.**
+  If a renderer cannot resolve a foreign boundary inside its own runtime, route execution now treats any leftover unresolved boundary artifact HTML as an error instead of attempting any route-level fallback.
 - **Caching policy is authoritative at the page layer.**
   Middleware, locals, and response reuse all depend on the effective page cache strategy.
 - **Asset emission should converge into one injection stage.**
-  Route-level assets, integration assets, page-root component assets, and marker-generated assets all end up in the HTML transformer.
+  Route-level assets, integration assets, page-root component assets, and renderer-owned boundary assets all end up in the HTML transformer.
 
 ## Entry Points
 
@@ -136,14 +134,14 @@ flowchart TD
   K -- Yes --> L[buildGlobalInjectorAssets]
   K -- No --> M[continue]
   L --> M
-  M --> N[HtmlPostProcessingService dedupeProcessedAssets]
+  M --> N[HtmlTransformerService dedupeProcessedAssets]
   N --> O[htmlTransformer setProcessedDependencies]
   O --> P[return normalized render options]
 ```
 
 ### 4.2 Main execute flow via `RenderExecutionService`
 
-Important nuance: this phase does not always run marker graph resolution. It only does that when the first render pass actually produced `eco-marker` placeholders. In practice today, that usually means a non-React renderer crossed into React component rendering and deferred those nodes for the second pass.
+Important nuance: this phase does not resolve mixed-integration boundaries itself anymore. Renderer-owned runtimes must finish that work before route finalization. If unresolved boundary artifact HTML survives to this phase, route execution fails fast.
 
 ```mermaid
 flowchart TD
@@ -151,19 +149,14 @@ flowchart TD
   B --> C[prepareRenderOptions]
   C --> D[runWithComponentRenderContext then render]
   D --> E[normalize response body to renderedHtml]
-  E --> F[merge captured and explicit componentGraphContext]
-  F --> G{contains eco marker token?}
-  G -- Yes --> H[resolveMarkerGraphHtml]
-  G -- No --> I[skip graph resolution]
-  H --> J[HtmlPostProcessingService dedupeProcessedAssets]
-  J --> K[merge marker assets into transformer deps]
-  I --> L{root attributes attachable?}
-  K --> L
-  L -- Yes --> M[HtmlPostProcessingService applyAttributesToFirstBodyElement]
-  L -- No --> N[leave html unchanged]
-  M --> O[htmlTransformer transform]
-  N --> O
-  O --> P[return body stream and cache strategy]
+  E --> F{contains unresolved boundary artifact html?}
+  F -- Yes --> G[throw unresolved boundary error]
+  F -- No --> H{root attributes attachable?}
+  H -- Yes --> I[HtmlTransformerService applyAttributesToFirstBodyElement]
+  H -- No --> J[leave html unchanged]
+  I --> K[htmlTransformer transform]
+  J --> K
+  K --> L[return body stream and cache strategy]
 ```
 
 ### 4.3 Render preparation responsibilities
@@ -189,42 +182,40 @@ flowchart LR
 flowchart LR
   A[IntegrationRenderer] --> B[RenderPreparationService]
   A --> C[RenderExecutionService]
-  A --> D[MarkerGraphResolver]
-  A --> E[HtmlPostProcessingService]
+  A --> D[QueuedBoundaryRuntimeService]
   A --> F[PageModuleLoaderService]
   A --> G[DependencyResolverService]
   A --> H[HtmlTransformerService]
 
   B --> F
   B --> G
-  B --> E
-  C --> D
-  C --> E
+  B --> H
   C --> H
+  D --> H
 ```
 
-## 5) Marker Emission + Graph Resolution
+## 5) Boundary Tokens And Renderer-Owned Resolution
 
-This part is architecturally interesting because it introduces a second render stage. The first pass captures boundaries; the second pass resolves them in dependency order.
+This part is architecturally interesting because boundaries can still emit temporary transport tokens, but renderer-owned runtimes are now responsible for resolving foreign descendants before final route HTML is returned.
 
 If this feels complex, the simplest mental model is:
 
 - first pass: render everything that can be rendered safely right now
-- when a boundary cannot be rendered safely in the current integration pass, emit a placeholder marker instead
-- second pass: revisit those placeholders and render them using the correct integration renderer
-- final pass: merge any emitted assets and perform the normal HTML transformation
+- when a renderer supports mixed boundaries, hand foreign descendants back to the owning renderer inside that renderer's runtime
+- if literal `<eco-marker>` boundary artifact HTML survives to route finalization, treat it as a failure instead of attempting any route-level fallback
+- final pass: merge emitted assets and perform the normal HTML transformation
 
-In the current implementation, this marker path exists to defer React subtrees that cannot be rendered inline during the active non-React integration pass.
+In the current implementation, renderer-owned runtimes use internal boundary tokens for queued nested handoff. Literal `<eco-marker>` markup remains only as a route-level failure signal when unresolved boundary artifacts escape renderer-owned resolution.
 
-Important clarification: not every integration automatically goes through this stage. The marker pipeline is conditional.
+Important clarification: not every integration automatically goes through this stage. Boundary queueing is conditional.
 
-- If the first render pass returns plain HTML with no `eco-marker` tokens, rendering continues directly to post-processing and HTML transformation.
-- If the first render pass emits `eco-marker` tokens, the marker graph is built and resolved before the final HTML rewrite.
-- In the current implementation, marker emission is triggered when the active render pass boundary policy decides that entering React should be deferred. The policy is injected through component render context, and the React integration currently opts into that deferred behavior.
+- If a render pass stays inside one integration, rendering continues directly to post-processing and HTML transformation.
+- If a renderer can resolve foreign descendants inline, the boundary runtime returns resolved HTML immediately.
+- If a renderer needs token-based nested handoff, it queues renderer-owned transport tokens and resolves them before returning final HTML.
 
 ### Why this exists
 
-The marker pipeline exists because some component boundaries cannot always be rendered eagerly inside the current integration pass.
+Renderer-owned boundary queueing exists because some component boundaries cannot always be rendered eagerly inside the current integration pass.
 
 Typical reasons include:
 
@@ -233,62 +224,45 @@ Typical reasons include:
 - the parent render needs to preserve ordering and slots before the child subtree is resolved
 - the child render may emit its own assets or root attributes that must be merged back into the final document
 
-So the first pass captures a stable placeholder plus serialized render context, and the second pass resolves those placeholders using the correct integration renderer.
-
-Responsibility split:
-
-- core resolves the deferred marker mechanically: graph shape, refs, slot relationships, and target renderer lookup
-- the selected integration renderer resolves the actual component render once it receives `component`, `props`, and optional `children`
+So the first pass either returns resolved renderer-owned output immediately or emits a renderer-local transport token that is resolved before the enclosing renderer returns its final HTML.
 
 Another way to say it:
 
-- a marker is a promise that says "this subtree will be rendered later by another renderer"
-- the marker stores just enough information to make that later render deterministic
-- the graph exists so nested deferred boundaries resolve from leaves to parents, preserving child insertion order and slot structure
+- a boundary token says "this subtree belongs to another renderer, but the current renderer still owns the overall render pass"
+- the token stores just enough information to make that later renderer-owned handoff deterministic
+- the queue exists so nested foreign boundaries resolve from leaves to parents while preserving child insertion order and emitted assets
 
-### 5.1 Marker emission in `eco.component` factory
+### 5.1 Boundary interception in `eco.component` factory
 
-The key rule here today is: markers are not a general-purpose placeholder for every component. During an active component render pass, `eco.component` asks the current render boundary context whether the next boundary should be deferred. When the answer is defer, it captures props/refs/slot links and returns an `eco-marker` token instead of rendering the component immediately.
+The key rule here today is: boundaries are resolved by the owning renderer, not by a shared core fallback. During an active component render pass, `eco.component` asks the current render boundary context whether the next boundary should render inline or be resolved by a foreign renderer runtime.
 
-For the current built-in integrations, this is how non-React renders defer React subtrees until the marker resolution pass.
+For the current built-in integrations, this is how non-owning renderers hand foreign subtrees back to the owning runtime without relying on a shared core fallback.
 
 ```mermaid
 flowchart TD
   A[eco component render] --> B[getComponentRenderContext]
-  B --> C[boundaryContext decideBoundaryRender]
-  C --> D{decision is defer?}
-  D -- No --> E[render component content immediately]
-  D -- Yes --> F[create nodeId + propsRef]
-  F --> G[store props in propsByRef]
-  G --> H{children include eco-marker tokens?}
-  H -- Yes --> I[create slotRef and slotChildrenByRef links]
-  H -- No --> J[no slot links]
-  I --> K[createComponentMarker]
-  J --> K
-  K --> L[return eco marker token]
+  B --> C[boundaryRuntime interceptBoundarySync]
+  C --> D{resolved foreign boundary?}
+  D -- No --> E[render component content inline]
+  D -- Yes --> F[return renderer-owned resolved html]
 ```
 
-### 5.2 Marker graph execution
+### 5.2 Queued boundary execution
 
-Once markers exist in the HTML, the second pass is integration-agnostic at execution time. Each marker carries its target integration name, so the resolver can ask the right renderer to render that specific node. Even though marker emission is currently React-focused, the resolution phase itself is generic and works off the marker payload plus renderer lookup.
+When string-first renderers queue foreign boundaries, the base renderer helper resolves queued boundary tokens directly against the shared queue service. That pass is intentionally narrow: it only resolves queued boundary tokens that the owning renderer emitted as transport artifacts for that string runtime.
 
-This means the marker itself is not interpreted by the integration renderer. Core interprets the marker and reconstructs render input; the integration renderer only performs the final component render.
+This means boundary tokens are no longer a general component-boundary contract. Core only resolves queued boundary payloads that already belong to a renderer-owned string boundary workflow.
 
 ```mermaid
 flowchart TD
-  A[resolveMarkerGraphHtml] --> B[buildComponentRefRegistry]
-  B --> C[extractComponentGraph from html and slot registry]
-  C --> D[resolveComponentGraph in reverse levels]
-  D --> E[for each marker node]
-  E --> F[resolve component by componentRef]
-  F --> G[resolve props by propsRef]
-  G --> H[stitch child html from slotRef node ids]
-  H --> I[getIntegrationRendererForName]
-  I --> J[renderer.renderComponent]
-  J --> K[collect component assets]
-  K --> L[apply root attributes to first element]
-  L --> M[replace marker token in HTML]
-  M --> N[resolved html and assets]
+  A[string boundary runtime html] --> B[find queued boundary tokens]
+  B --> C[resolve nested child tokens first]
+  C --> D[dispatch boundary to owning renderer]
+  D --> E[renderer.renderComponentBoundary]
+  E --> F[collect emitted assets]
+  F --> G[apply root attributes to first element]
+  G --> H[replace queued token in html]
+  H --> I[resolved html and merged assets]
 ```
 
 ## 6) Explicit Rendering Paths (outside FS page matching)
@@ -347,16 +321,12 @@ For someone new to the rendering system, this is probably the most useful order
 6. `integration-renderer.ts`
 7. `render-preparation.service.ts`
 8. `render-execution.service.ts`
-9. `marker-graph-resolver.ts`
-10. `html-post-processing.service.ts`
+9. `queued-boundary-runtime.service.ts`
+10. `html-transformer.service.ts`
 11. `page-module-loader.ts`
 12. `dependency-resolver.ts`
-13. `component-marker.ts`
-14. `component-graph.ts`
-15. `component-graph-executor.ts`
-16. `eco.ts`
-17. `component-render-context.ts`
-18. `html-transformer.service.ts`
+13. `eco.ts`
+14. `component-render-context.ts`
 
 ## 9) Key Files
 
@@ -368,18 +338,14 @@ For someone new to the rendering system, this is probably the most useful order
 - `packages/core/src/adapters/shared/explicit-static-route-matcher.ts`
 - `packages/core/src/adapters/shared/render-context.ts`
 - `packages/core/src/route-renderer/route-renderer.ts`
-- `packages/core/src/route-renderer/integration-renderer.ts`
-- `packages/core/src/route-renderer/render-preparation.service.ts`
-- `packages/core/src/route-renderer/render-execution.service.ts`
-- `packages/core/src/route-renderer/html-post-processing.service.ts`
-- `packages/core/src/route-renderer/marker-graph-resolver.ts`
-- `packages/core/src/route-renderer/component-marker.ts`
-- `packages/core/src/route-renderer/component-graph.ts`
-- `packages/core/src/route-renderer/component-graph-executor.ts`
-- `packages/core/src/route-renderer/page-module-loader.ts`
-- `packages/core/src/route-renderer/dependency-resolver.ts`
-- `packages/core/src/services/page-module-import.service.ts`
-- `packages/core/src/services/page-request-cache-coordinator.service.ts`
+- `packages/core/src/route-renderer/orchestration/integration-renderer.ts`
+- `packages/core/src/route-renderer/orchestration/render-preparation.service.ts`
+- `packages/core/src/route-renderer/orchestration/render-execution.service.ts`
+- `packages/core/src/route-renderer/orchestration/queued-boundary-runtime.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/services/module-loading/page-module-import.service.ts`
+- `packages/core/src/services/cache/page-request-cache-coordinator.service.ts`
 - `packages/core/src/eco/component-render-context.ts`
 - `packages/core/src/eco/eco.ts`
 - `packages/core/src/services/html-transformer.service.ts`

package/src/route-renderer/README.md

@@ -19,42 +19,27 @@ The route renderer layer is responsible for:
 - `RouteRendererFactory` chooses integration renderers based on route file extension.
 - `RouteRenderer` delegates route execution to the selected integration renderer.
 
-### `integration-renderer.ts`
+### `orchestration/`
 
-Abstract base class that coordinates end-to-end route rendering:
+Framework-owned orchestration services and renderer base class:
 
-1. Resolve page module and page data.
-2. Resolve and process component dependencies.
-3. Add route-level assets and orchestration assets.
-4. Render HTML via integration-specific `render()`.
-5. Inject processed assets into final HTML through `HtmlTransformerService`.
+- `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:
 
 - `renderToResponse()` contract for explicit-route rendering.
 - `renderComponent()` contract for component-level orchestration and artifact reporting.
-- marker graph resolution for nested cross-integration component boundaries.
+- deferred boundary resolution for nested cross-integration component boundaries.
 
-### `component-marker.ts`
+### Boundary Tokens
 
-Defines marker token contract for component-level orchestration:
+Renderer-owned runtimes may emit internal boundary tokens while they resolve foreign descendants before returning final HTML. If literal `<eco-marker ...></eco-marker>` markup survives to route finalization, it is treated as an unresolved boundary artifact rather than a normal transport mechanism.
 
-- `createComponentMarker()` for canonical `<eco-marker ...></eco-marker>` generation.
-- `parseComponentMarkers()` for marker extraction from rendered HTML.
-
-### `component-graph.ts`
-
-Builds a deterministic DAG from marker nodes:
-
-- node collection by marker id.
-- parent/child edges from slot reference registry.
-- topological levels for bottom-up execution.
-
-### `component-graph-executor.ts`
-
-Resolves graph levels in reverse order (leaf to root) and replaces markers with rendered HTML via integration `renderComponent()`.
-
-### `page-module-loader.ts`
+### `page-loading/`
 
 Service for loading page modules and deriving page data:
 
@@ -62,8 +47,6 @@ Service for loading page modules and deriving page data:
 - `resolvePageModule()` normalizes exports and statics.
 - `resolvePageData()` resolves static props then metadata.
 
-### `dependency-resolver.ts`
-
 Builds processed assets from component dependency declarations:
 
 - Scripts/styles/components/modules.
@@ -74,38 +57,73 @@ Builds processed assets from component dependency declarations:
 
 Default behavior:
 
-- marker-graph component orchestration + component render artifacts.
+- 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:
+
+- keep queued foreign-boundary resolution renderer-owned
+- apply root attributes only when `attachmentPolicy.kind === 'first-element'`
+- preserve asset bubbling through the normal dependency pipeline
 
-Current base orchestration behavior:
+The lower-level `ComponentRenderResult` currently includes:
 
-- Calls `renderComponent()` for the page root component.
-- Merges returned `assets` into processed dependencies.
-- Applies returned `rootAttributes` to the first element under `<body>`.
+- `html`
+- `canAttachAttributes`
+- `rootTag`
+- `integrationName`
+- optional `rootAttributes`
+- optional `assets`
 
-When rendered output contains `eco-marker` nodes:
+When rendered output still contains unresolved boundary artifact HTML:
 
-- builds marker graph using `componentGraphContext` (`propsByRef`, `slotChildrenByRef`) from integration-specific page module exports.
-- resolves markers bottom-up through integration-specific `renderComponent()` calls.
-- fails fast when marker component refs or props refs are missing.
-- merges marker-rendered assets back into the dependency pipeline with deduplication.
+- route execution now fails fast instead of attempting any route-level unresolved-boundary fallback.
+- renderer-owned boundary runtimes are responsible for resolving foreign nested components before final route HTML is returned.
 
 This enables island-style hydration assets (for example React/Lit/Kita integration outputs) to be emitted through the normal dependency injection pipeline.
 
@@ -128,8 +146,11 @@ This enables island-style hydration assets (for example React/Lit/Kita integrati
 6. HTML transformer injects head/body dependencies.
 7. Route result returns body + metadata + cache strategy.
 
-## Notes for Future Work
+## Current Limits And Near-Term Work
+
+If you are reading this file to understand today's contract, you can stop at the output pipeline above. The items below describe areas still evolving rather than required behavior.
 
-- Expand integration-side marker emission so more nested trees are resolved through graph mode by default.
-- Add broader fixtures/e2e for deep multi-level slot graphs.
-- Add optional batching by integration per graph level to reduce repeated renderer invocations.
+- 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
+};