@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.27

package/src/route-renderer/GRAPH.md

@@ -1,38 +1,16 @@
 # Rendering Logic Graph
 
-This document maps the end-to-end rendering logic in core, including request-time rendering, explicit route rendering, static generation, and deferred boundary orchestration.
+This document maps the rendering logic in core using the ownership, foreign-child, and foreign-subtree model.
 
 ## Design Principles
 
-These diagrams are based on a few architectural assumptions that seem important to preserve:
+- Rendering entry points stay separate, but they converge on the same integration renderer contracts.
+- Integration selection happens outside the renderer. Once selected, the integration renderer owns the render pipeline.
+- Ownership is preparation-time metadata. Runtime handoff still happens inside renderer-owned foreign-child interception.
+- Route-level fallback resolution is gone. Unresolved `<eco-marker>` artifacts are now a failure signal.
+- Asset emission converges into one final HTML transformation step.
 
-- **Rendering entry points are separate, but should converge on shared renderer contracts.**
-  Request-time page rendering, explicit view rendering, and static generation all eventually depend on the same integration renderer behavior.
-- **Integration choice should remain a boundary concern.**
-  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.
-- **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 renderer-owned boundary assets all end up in the HTML transformer.
-
-## Entry Points
-
-There are three main rendering entry points:
-
-1. **Runtime request rendering**
-    - handled through the server adapters and file-system route matching
-2. **Explicit rendering APIs**
-    - handled through `renderToResponse()` and route-handler render context helpers
-3. **Static site generation**
-    - handled through explicit route generation and route renderer reuse at build time
-
-## 1) Runtime Request Flow (Bun and Node)
+## 1) Runtime Request Flow
 
 ```mermaid
 flowchart TD
@@ -51,303 +29,117 @@ flowchart TD
   K --> L[RouteRenderer createRoute]
   L --> M[IntegrationRenderer execute]
   M --> N[response body and cache strategy]
-
-  J --> O{Static asset request?}
-  O -- Yes --> P[FileSystemServerResponseFactory createFileResponse]
-  O -- No --> Q[FileSystemServerResponseFactory createCustomNotFoundResponse]
-  Q --> R[routeRendererFactory createRenderer for 404 template]
-  R --> S[RouteRenderer createRoute]
-```
-
-## 2) FS Route Rendering + Middleware + Cache
-
-This is the most operationally important runtime path because it is where middleware, locals, and cache behavior are coordinated.
-
-```mermaid
-flowchart TD
-  A[FileSystemResponseMatcher handleMatch] --> B[PageModuleImportService importModule]
-  B --> C[read Page cache and Page middleware]
-  C --> D[FileRouteMiddlewarePipeline assertValidConfiguration]
-  D --> E{Middleware exists?}
-
-  E -- Yes --> F{cache dynamic?}
-  F -- No --> G[throw LocalsAccessError]
-  F -- Yes --> H[FileRouteMiddlewarePipeline createContext]
-  H --> I[FileRouteMiddlewarePipeline run]
-
-  E -- No --> J[renderResponse]
-  I --> J
-
-  J --> K[PageRequestCacheCoordinator render]
-  K --> L{cache disabled OR dynamic page?}
-  L -- Yes --> M[renderFn directly]
-  L -- No --> N[PageCacheService getOrCreate]
-
-  M --> O[routeRenderer createRoute]
-  N --> O
-  O --> P[PageRequestCacheCoordinator bodyToString]
-  P --> Q[html and strategy]
-  Q --> R[createCachedResponse with cache headers]
-```
-
-## 3) RouteRendererFactory Selection Logic
-
-This is a small but important boundary. It centralizes integration selection and renderer reuse, which helps keep adapter code thin.
-
-```mermaid
-flowchart TD
-  A[createRenderer filePath] --> B[getRouteRendererEngine filePath]
-  B --> C[getIntegrationPlugin by template extension]
-  C --> D{renderer cached by integration name?}
-  D -- Yes --> E[Reuse renderer]
-  D -- No --> F[integrationPlugin.initializeRenderer]
-  F --> G[Cache renderer]
-  E --> H[RouteRenderer]
-  G --> H
-
-  I[getRendererByIntegration integrationName] --> J{plugin exists?}
-  J -- No --> K[return null]
-  J -- Yes --> L{renderer cached?}
-  L -- Yes --> M[Reuse renderer]
-  L -- No --> N[initializeRenderer + cache]
 ```
 
-## 4) IntegrationRenderer Pipeline
+## 2) Route Render Flow
 
-The original single graph was accurate but a bit dense. Splitting it into preparation and execution phases makes the orchestration easier to reason about.
-
-### 4.1 Render preparation via `RenderPreparationService`
+`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderFlow`.
 
 ```mermaid
 flowchart TD
-  A[IntegrationRenderer prepareRenderOptions] --> B[RenderPreparationService prepare]
+  A[IntegrationRenderer.execute] --> B[RouteRenderFlow.prepareRenderOptions]
   B --> C[resolvePageModule]
-  C --> D[resolvePageData staticProps to metadata]
-  D --> E[resolveDependencies and used integration deps and route assets]
-  E --> F{shouldRenderPageComponent?}
-  F -- Yes --> G[renderPageRoot via renderComponent]
-  F -- No --> H[skip page root component render]
-  G --> I[merge component assets]
-  H --> I
-  I --> J[collect lazy triggers]
-  J --> K{triggers found?}
-  K -- Yes --> L[buildGlobalInjectorAssets]
-  K -- No --> M[continue]
-  L --> M
-  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 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
-  A[IntegrationRenderer execute] --> B[RenderExecutionService execute]
-  B --> C[prepareRenderOptions]
-  C --> D[runWithComponentRenderContext then render]
-  D --> E[normalize response body to renderedHtml]
-  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
-
-```mermaid
-flowchart LR
-  A[Page module loader] --> B[static props]
-  B --> C[metadata]
-  C --> D[page props and locals]
-
-  E[dependency resolver] --> F[component assets]
-  F --> G[integration assets]
-  G --> H[route assets]
-  H --> I[global injector assets]
-
-  D --> J[prepared render options]
-  I --> J
-```
-
-### 4.4 Service boundary map
-
-```mermaid
-flowchart LR
-  A[IntegrationRenderer] --> B[RenderPreparationService]
-  A --> C[RenderExecutionService]
-  A --> D[QueuedBoundaryRuntimeService]
-  A --> F[PageModuleLoaderService]
-  A --> G[DependencyResolverService]
-  A --> H[HtmlTransformerService]
-
-  B --> F
-  B --> G
-  B --> H
-  C --> H
-  D --> H
+  C --> D[ownershipValidationService.validate]
+  D --> E[resolvePageData]
+  E --> F[ownershipPlanningService.buildPlan]
+  F --> G[resolveDependencies]
+  G --> H[buildPageBrowserGraph]
+  H --> I{shouldRenderPageComponent?}
+  I -- Yes --> J[renderPageComponent]
+  I -- No --> K[skip page-root render]
+  J --> L[merge component assets]
+  K --> L
+  L --> M[collect injector and eager SSR lazy assets]
+  M --> N[build pagePackage and prepared render options]
+  N --> O[callbacks.render]
+  O --> P[capture rendered body as html]
+  P --> Q[inspect unresolved marker artifacts]
+  Q --> R{unresolved eco-marker remains?}
+  R -- Yes --> S[throw unresolved artifact error]
+  R -- No --> T[stamp root or document attributes when needed]
+  T --> U[htmlTransformer transform]
+  U --> V[final body and cache strategy]
 ```
 
-## 5) Boundary Tokens And Renderer-Owned Resolution
-
-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 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, 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. Boundary queueing is conditional.
-
-- 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
-
-Renderer-owned boundary queueing exists because some component boundaries cannot always be rendered eagerly inside the current integration pass.
+## 3) Mixed-Integration Render Model
 
-Typical reasons include:
+The renderer-level mental model is:
 
-- the child component belongs to a different integration/runtime
-- the child integration needs its own renderer entry point
-- 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 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 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 Boundary interception in `eco.component` factory
-
-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-owning renderers hand foreign subtrees back to the owning runtime without relying on a shared core fallback.
+1. declared dependencies describe ownership
+2. active render context intercepts foreign children
+3. the owning renderer returns a foreign subtree
 
 ```mermaid
 flowchart TD
-  A[eco component render] --> B[getComponentRenderContext]
-  B --> C[boundaryRuntime interceptBoundarySync]
-  C --> D{resolved foreign boundary?}
-  D -- No --> E[render component content inline]
-  D -- Yes --> F[return renderer-owned resolved html]
+  A[eco.component render] --> B[getComponentRenderContext]
+  B --> C[foreignChildRuntime interceptForeignChildSync]
+  C --> D{same integration?}
+  D -- Yes --> E[render inline]
+  D -- No --> F[delegate to owning renderer]
+  F --> G[owning renderer renderComponentWithForeignChildren]
+  G --> H[owning renderer renderForeignSubtree when payload form is needed]
+  H --> I[resolved html plus assets and attachment policy]
 ```
 
-### 5.2 Queued boundary execution
+## 4) Queued Foreign-Subtree Resolution
 
-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 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.
+Some renderers cannot hand off foreign children inline. Those renderers can use the queue service during one render pass.
 
 ```mermaid
 flowchart TD
-  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]
+  A[current renderer encounters foreign child] --> B{can resolve inline?}
+  B -- Yes --> C[return resolved renderer-owned output]
+  B -- No --> D[queue foreign-subtree token]
+  D --> E[finish current render pass]
+  E --> F[QueuedForeignSubtreeResolutionService resolveQueuedHtml]
+  F --> G[resolve nested queued tokens first]
+  G --> H[dispatch foreign subtree to owning renderer]
+  H --> I[merge emitted assets and root attributes]
+  I --> J[replace token in html]
 ```
 
-## 6) Explicit Rendering Paths (outside FS page matching)
+## 5) Explicit Rendering Paths
 
-These paths are simpler than request-time file-system rendering because they bypass most router and cache orchestration.
+These paths bypass most filesystem routing, but they still converge on the same renderer contracts.
 
 ```mermaid
 flowchart TD
   A[ExplicitStaticRouteMatcher handleMatch] --> B[route loader returns view]
-  B --> C[read view integration metadata]
-  C --> D[routeRendererFactory getRendererByIntegration]
-  D --> E[optional view.staticProps]
-  E --> F[renderer renderToResponse]
-
-  G[createRenderContext render or renderPartial] --> H[get renderer from integrations list]
-  H --> I[merge props + locals]
-  I --> J[renderer renderToResponse]
-
-  K[StaticSiteGenerator explicit routes] --> L[getRendererByIntegration]
-  L --> M[optional staticPaths and staticProps]
-  M --> N[renderer renderToResponse]
-  N --> O[write html to dist]
-```
-
-## 7) Current Concrete Integration in core
+  B --> C[get renderer by integration]
+  C --> D[renderer renderToResponse]
 
-Today the concrete in-core renderer is `GhtmlRenderer`. That makes it a useful reference implementation for the abstract integration renderer contract.
+  E[render context render or renderPartial] --> F[get renderer from integrations list]
+  F --> G[renderer renderToResponse]
 
-```mermaid
-flowchart TD
-  A[GhtmlRenderer.render] --> B[Page params/query/props/locals]
-  B --> C{Layout exists?}
-  C -- Yes --> D[Layout wraps page content]
-  C -- No --> E[use page content]
-  D --> F[HtmlTemplate metadata + children + pageProps]
-  E --> F
-  F --> G[prepend DOCTYPE]
-
-  H[GhtmlRenderer renderToResponse] --> I{partial?}
-  I -- Yes --> J[return component html only]
-  I -- No --> K[resolve Layout and HtmlTemplate and metadata]
-  K --> L[prepend DOCTYPE]
-  J --> M[createHtmlResponse]
-  L --> M
+  H[StaticSiteGenerator explicit routes] --> I[get renderer by integration]
+  I --> J[renderer renderToResponse]
+  J --> K[write html to dist]
 ```
 
-## 8) Reading Order
+## 6) Reading Order
 
-For someone new to the rendering system, this is probably the most useful order to read the code:
+The most useful reading order is:
 
-1. `server-route-handler.ts`
-2. `fs-server-response-matcher.ts`
-3. `file-route-middleware-pipeline.ts`
-4. `page-request-cache-coordinator.service.ts`
-5. `route-renderer.ts`
-6. `integration-renderer.ts`
-7. `render-preparation.service.ts`
-8. `render-execution.service.ts`
-9. `queued-boundary-runtime.service.ts`
-10. `html-transformer.service.ts`
-11. `page-module-loader.ts`
-12. `dependency-resolver.ts`
-13. `eco.ts`
-14. `component-render-context.ts`
+1. `route-renderer.ts`
+2. `orchestration/route-render-flow.ts`
+3. `orchestration/integration-renderer.ts`
+4. `orchestration/ownership-validation.service.ts`
+5. `orchestration/ownership-planning.service.ts`
+6. `orchestration/component-render-context.ts`
+7. `orchestration/queued-foreign-subtree-resolution.service.ts`
+8. `page-loading/page-module-loader.ts`
+9. `page-loading/dependency-resolver.ts`
+10. `eco/eco.ts`
 
-## 9) Key Files
+## 7) Key Files
 
-- `packages/core/src/adapters/shared/server-adapter.ts`
-- `packages/core/src/adapters/shared/server-route-handler.ts`
-- `packages/core/src/adapters/shared/fs-server-response-matcher.ts`
-- `packages/core/src/adapters/shared/file-route-middleware-pipeline.ts`
-- `packages/core/src/adapters/shared/fs-server-response-factory.ts`
-- `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/orchestration/route-render-flow.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/orchestration/ownership-validation.service.ts`
+- `packages/core/src/route-renderer/orchestration/ownership-planning.service.ts`
+- `packages/core/src/route-renderer/orchestration/component-render-context.ts`
+- `packages/core/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.ts`
 - `packages/core/src/route-renderer/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`
-- `packages/core/src/services/cache/page-cache-service.ts`
-- `packages/core/src/integrations/ghtml/ghtml-renderer.ts`