@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

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

@@ -1,11 +1,23 @@
 import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   AssetFactory
-} from "../services/asset-processing-service/index.js";
-import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../eco/global-injector-map.js";
-import { runWithComponentRenderContext } from "../eco/component-render-context.js";
-const coreRequire = createRequire(import.meta.url);
+} from "../../services/assets/asset-processing-service/index.js";
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../../eco/global-injector-map.js";
+import {
+  runWithComponentRenderContext
+} from "../../eco/component-render-context.js";
 class RenderPreparationService {
+  appConfig;
+  assetProcessingService;
+  /**
+   * Creates the render-preparation orchestrator for one app instance.
+   *
+   * @remarks
+   * 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) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
@@ -56,6 +68,10 @@ class RenderPreparationService {
       const globalAssets = await this.buildGlobalInjectorAssets(triggers, currentIntegrationName);
       allDependencies.push(...globalAssets);
     }
+    const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, currentIntegrationName);
+    if (eagerSsrLazyAssets.length > 0) {
+      allDependencies.push(...eagerSsrLazyAssets);
+    }
     callbacks.setProcessedDependencies(callbacks.dedupeProcessedAssets(allDependencies));
     const pageProps = {
       ...props,
@@ -203,7 +219,7 @@ class RenderPreparationService {
    * @returns Processed assets that should be merged into the final dependency set.
    */
   async buildGlobalInjectorAssets(triggers, currentIntegrationName) {
-    const globalInjectorImportPath = coreRequire.resolve("@ecopages/scripts-injector/global");
+    const globalInjectorImportPath = createRequire(import.meta.url).resolve("@ecopages/scripts-injector/global");
     const globalInjectorRuntimeAsset = AssetFactory.createNodeModuleScript({
       position: "head",
       name: "ecopages-scripts-injector-global",
@@ -237,6 +253,80 @@ class RenderPreparationService {
       currentIntegrationName
     );
   }
+  async buildEagerSsrLazyAssets(components, currentIntegrationName) {
+    const dependencies = this.collectEagerSsrLazyDependencies(components);
+    if (dependencies.length === 0) {
+      return [];
+    }
+    return this.assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
+  }
+  collectEagerSsrLazyDependencies(components) {
+    const dependencies = [];
+    const visitedConfigs = /* @__PURE__ */ new Set();
+    const seenKeys = /* @__PURE__ */ new Set();
+    const normalizeAttributes = (attributes) => ({
+      type: "module",
+      defer: "",
+      ...attributes ?? {}
+    });
+    const collect = (config) => {
+      if (!config || visitedConfigs.has(config)) {
+        return;
+      }
+      visitedConfigs.add(config);
+      const componentFile = config.__eco?.file;
+      if (componentFile) {
+        const componentDir = path.dirname(componentFile);
+        for (const script of config.dependencies?.scripts ?? []) {
+          if (typeof script === "string" || !script.lazy || script.ssr !== true) {
+            continue;
+          }
+          const attributes = normalizeAttributes(script.attributes);
+          if (script.content) {
+            const key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
+            if (seenKeys.has(key2)) {
+              continue;
+            }
+            seenKeys.add(key2);
+            dependencies.push(
+              AssetFactory.createContentScript({
+                position: "head",
+                content: script.content,
+                attributes
+              })
+            );
+            continue;
+          }
+          if (!script.src) {
+            continue;
+          }
+          const resolvedPath = path.resolve(componentDir, script.src);
+          const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
+          if (seenKeys.has(key)) {
+            continue;
+          }
+          seenKeys.add(key);
+          dependencies.push(
+            AssetFactory.createFileScript({
+              filepath: resolvedPath,
+              position: "head",
+              attributes
+            })
+          );
+        }
+      }
+      if (config.layout?.config) {
+        collect(config.layout.config);
+      }
+      for (const nestedComponent of config.dependencies?.components ?? []) {
+        collect(nestedComponent?.config);
+      }
+    };
+    for (const component of components) {
+      collect(component.config);
+    }
+    return dependencies;
+  }
 }
 export {
   RenderPreparationService

package/src/route-renderer/{dependency-resolver.d.ts → page-loading/dependency-resolver.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoComponent } from '../public-types.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { AssetProcessingService, ProcessedAsset } from '../services/asset-processing-service/index.js';
+import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 export declare const DEPENDENCY_ERRORS: {
     readonly INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content";
     readonly INVALID_SCRIPT_ENTRY: "Invalid script dependency entry: expected src or content";
@@ -9,7 +9,18 @@ export declare const DEPENDENCY_ERRORS: {
 export declare class DependencyResolverService {
     private appConfig;
     private assetProcessingService;
+    /**
+     * Creates the dependency resolver used by route and component rendering.
+     *
+     * @remarks
+     * The resolver stays intentionally separate from HTML rendering so component
+     * dependency collection, lazy trigger grouping, and processed-asset generation
+     * can evolve without changing renderer implementations.
+     */
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    /**
+     * Resolves one dependency path relative to the component that declared it.
+     */
     resolveDependencyPath(componentDir: string, pathUrl: string): string;
     /**
      * Maps lazy script source entries to deterministic fallback public URLs
@@ -20,5 +31,5 @@ export declare class DependencyResolverService {
      * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
      * Lazy dependencies are always resolved into global-injector trigger maps.
      */
-    processComponentDependencies(components: (EcoComponent | Partial<EcoComponent>)[], integrationName: string): Promise<ProcessedAsset[]>;
+    processComponentDependencies(components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>, integrationName: string): Promise<ProcessedAsset[]>;
 }

package/src/route-renderer/{dependency-resolver.js → page-loading/dependency-resolver.js}

@@ -1,8 +1,8 @@
 import path from "node:path";
 import { readFileSync } from "node:fs";
-import { rapidhash } from "../utils/hash.js";
-import { AssetFactory } from "../services/asset-processing-service/index.js";
-import { normalizeModuleDeclarations } from "../eco/module-dependencies.js";
+import { rapidhash } from "../../utils/hash.js";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
 import { parseSync } from "oxc-parser";
 const DEPENDENCY_ERRORS = {
   INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content",
@@ -139,10 +139,23 @@ function buildResolvedLazyTriggers(config, groups) {
   return [{ triggerId, rules }];
 }
 class DependencyResolverService {
+  appConfig;
+  assetProcessingService;
+  /**
+   * Creates the dependency resolver used by route and component rendering.
+   *
+   * @remarks
+   * The resolver stays intentionally separate from HTML rendering so component
+   * dependency collection, lazy trigger grouping, and processed-asset generation
+   * can evolve without changing renderer implementations.
+   */
   constructor(appConfig, assetProcessingService) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
   }
+  /**
+   * Resolves one dependency path relative to the component that declared it.
+   */
   resolveDependencyPath(componentDir, pathUrl) {
     return resolveDependencyPath(componentDir, pathUrl);
   }
@@ -163,6 +176,7 @@ class DependencyResolverService {
     const lazyScriptsByConfig = /* @__PURE__ */ new Map();
     const lazyDependencyKeys = /* @__PURE__ */ new Set();
     for (const component of components) {
+      if (!component) continue;
       const componentFile = component.config?.__eco?.file;
       if (!componentFile) continue;
       const stylesheetDependencyKeys = /* @__PURE__ */ new Set();
@@ -357,7 +371,7 @@ class DependencyResolverService {
         }
         if (dependenciesConfig?.components) {
           for (const nestedComponent of dependenciesConfig.components) {
-            if (nestedComponent.config) {
+            if (nestedComponent?.config) {
               collect(nestedComponent.config);
             }
           }

package/src/route-renderer/page-loading/page-module-loader.d.ts

@@ -0,0 +1,89 @@
+import type { EcoPageFile, GetMetadata, GetMetadataContext, GetStaticProps, PageMetadataProps, RouteRendererOptions, EcoPageComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Loads route page modules and normalizes their data hooks for rendering.
+ *
+ * @remarks
+ * This service keeps the render pipeline from depending directly on raw module
+ * imports. It owns the shared server-module transpiler setup, the precedence
+ * rules between component statics and module exports, and the normalization of
+ * page props and metadata into one renderer-facing shape.
+ */
+export declare class PageModuleLoaderService {
+    private appModuleLoader;
+    private appConfig;
+    private runtimeOrigin;
+    /**
+     * Creates the page-module loader for one app/runtime instance.
+     *
+     * @param appConfig Finalized app config that owns build and invalidation state.
+     * @param runtimeOrigin Runtime origin exposed to page data hooks.
+     */
+    constructor(appConfig: EcoPagesAppConfig, runtimeOrigin: string);
+    /**
+     * Imports one page module through the shared server-side module loading path.
+     *
+     * @remarks
+     * The underlying transpiler keeps Bun and Node aligned on one framework-owned
+     * loading contract even though the runtime-specific execution transport differs.
+     */
+    importPageFile(file: string, options?: {
+        bypassCache?: boolean;
+    }): Promise<EcoPageFile>;
+    /**
+     * Executes the page's static-props hook with Ecopages runtime context.
+     *
+     * @remarks
+     * Pages without a static-props hook still return a normalized empty props
+     * object so downstream render preparation does not branch on hook presence.
+     */
+    getStaticPropsForPage(options: {
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        params?: RouteRendererOptions['params'];
+    }): Promise<{
+        props: Record<string, unknown>;
+        metadata?: PageMetadataProps;
+    }>;
+    /**
+     * Builds the final page metadata object for one render request.
+     *
+     * @remarks
+     * App-level default metadata forms the baseline, then page-level metadata is
+     * overlaid so route-specific fields win without dropping global defaults.
+     */
+    getMetadataPropsForPage(options: {
+        getMetadata: GetMetadata | undefined;
+        context: GetMetadataContext;
+    }): Promise<PageMetadataProps>;
+    /**
+     * Loads a page module and normalizes integration-facing exports.
+     * When both component static methods and module exports exist, component statics win.
+     */
+    resolvePageModule(options: {
+        file: string;
+        importPageFileFn?: (file: string) => Promise<EcoPageFile>;
+    }): Promise<{
+        Page: EcoPageFile['default'] | EcoPageComponent<any>;
+        getStaticProps?: GetStaticProps<Record<string, unknown>>;
+        getMetadata?: GetMetadata;
+        integrationSpecificProps: Record<string, unknown>;
+    }>;
+    /**
+     * Resolves the page data needed by the render pipeline.
+     *
+     * @remarks
+     * Static props are resolved first because page metadata may depend on those
+     * props. This preserves the same ordering whether data hooks are declared as
+     * component statics or module exports.
+     */
+    resolvePageData(options: {
+        pageModule: {
+            getStaticProps?: GetStaticProps<Record<string, unknown>>;
+            getMetadata?: GetMetadata;
+        };
+        routeOptions: RouteRendererOptions;
+    }): Promise<{
+        props: Record<string, unknown>;
+        metadata: PageMetadataProps;
+    }>;
+}

package/src/route-renderer/{page-module-loader.js → page-loading/page-module-loader.js}

@@ -1,22 +1,35 @@
-import { invariant } from "../utils/invariant.js";
-import { PageModuleImportService } from "../services/page-module-import.service.js";
+import { invariant } from "../../utils/invariant.js";
+import { getAppModuleLoader } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
 class PageModuleLoaderService {
+  appModuleLoader;
+  appConfig;
+  runtimeOrigin;
+  /**
+   * Creates the page-module loader for one app/runtime instance.
+   *
+   * @param appConfig Finalized app config that owns build and invalidation state.
+   * @param runtimeOrigin Runtime origin exposed to page data hooks.
+   */
   constructor(appConfig, runtimeOrigin) {
     this.appConfig = appConfig;
     this.runtimeOrigin = runtimeOrigin;
-    this.pageModuleImportService = new PageModuleImportService();
+    this.appModuleLoader = getAppModuleLoader(appConfig);
   }
-  pageModuleImportService;
   /**
-   * Imports a page module from source.
-   * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
+   * Imports one page module through the shared server-side module loading path.
+   *
+   * @remarks
+   * The underlying transpiler keeps Bun and Node aligned on one framework-owned
+   * loading contract even though the runtime-specific execution transport differs.
    */
-  async importPageFile(file) {
+  async importPageFile(file, options) {
     try {
-      return await this.pageModuleImportService.importModule({
+      return await this.appModuleLoader.importModule({
         filePath: file,
         rootDir: this.appConfig.rootDir,
-        outdir: `${this.appConfig.absolutePaths.distDir}/.server-modules`,
+        outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
+        bypassCache: options?.bypassCache,
         transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
         noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`
       });
@@ -25,8 +38,11 @@ class PageModuleLoaderService {
     }
   }
   /**
-   * Executes `getStaticProps` with Ecopages runtime context.
-   * Returns an empty props object when no static props function is defined.
+   * Executes the page's static-props hook with Ecopages runtime context.
+   *
+   * @remarks
+   * Pages without a static-props hook still return a normalized empty props
+   * object so downstream render preparation does not branch on hook presence.
    */
   async getStaticPropsForPage(options) {
     const { getStaticProps, params } = options;
@@ -42,8 +58,11 @@ class PageModuleLoaderService {
     };
   }
   /**
-   * Builds final page metadata using app-level defaults as a baseline.
-   * If `getMetadata` exists, its result overlays defaults so page-level fields take precedence.
+   * Builds the final page metadata object for one render request.
+   *
+   * @remarks
+   * App-level default metadata forms the baseline, then page-level metadata is
+   * overlaid so route-specific fields win without dropping global defaults.
    */
   async getMetadataPropsForPage(options) {
     const { getMetadata, context } = options;
@@ -79,7 +98,12 @@ class PageModuleLoaderService {
     };
   }
   /**
-   * Resolves render-time page data in order: static props first, then metadata derived from those props.
+   * Resolves the page data needed by the render pipeline.
+   *
+   * @remarks
+   * Static props are resolved first because page metadata may depend on those
+   * props. This preserves the same ordering whether data hooks are declared as
+   * component statics or module exports.
    */
   async resolvePageData(options) {
     const { props } = await this.getStaticPropsForPage({

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

@@ -1,26 +1,63 @@
-import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
-import type { RouteRenderResult, RouteRendererOptions } from '../public-types.js';
-import type { IntegrationRenderer } from './integration-renderer.js';
+import type { RouteRenderResult, RouteRendererOptions } from '../types/public-types.js';
+import type { IntegrationRenderer } from './orchestration/integration-renderer.js';
+/**
+ * Thin wrapper around one initialized integration renderer.
+ *
+ * @remarks
+ * This type exists so higher-level routing code can ask for a route renderer
+ * without depending on the full integration plugin lifecycle. It delegates all
+ * real work to the integration-specific renderer selected by the factory.
+ */
 export declare class RouteRenderer {
     private renderer;
+    /**
+     * Creates a route renderer bound to one integration renderer instance.
+     */
     constructor(renderer: IntegrationRenderer);
+    /**
+     * Executes the render pipeline for one matched route.
+     */
     createRoute(options: RouteRendererOptions): Promise<RouteRenderResult>;
 }
+/**
+ * Selects and caches integration renderers for route files and explicit views.
+ *
+ * @remarks
+ * The factory owns the policy that maps a route file or explicit integration
+ * name to one initialized integration renderer. Renderer instances are cached by
+ * integration name so repeated requests do not rebuild renderer state.
+ */
 export declare class RouteRendererFactory {
     private appConfig;
     runtimeOrigin: string;
+    private rendererModules?;
     private rendererCache;
-    constructor({ appConfig, runtimeOrigin }: {
+    /**
+     * Creates the route-renderer factory for one app/runtime instance.
+     */
+    constructor({ appConfig, rendererModules, runtimeOrigin, }: {
         appConfig: EcoPagesAppConfig;
+        rendererModules?: unknown;
         runtimeOrigin: string;
     });
+    /**
+     * Returns a route renderer for the supplied route file.
+     */
     createRenderer(filePath: string): RouteRenderer;
     /**
      * Get an integration renderer by its name.
      * Used for explicit routing where views specify their integration via __eco.integration.
      */
     getRendererByIntegration(integrationName: string): IntegrationRenderer | null;
+    /**
+     * Resolves the integration plugin that owns a given route file.
+     */
     getIntegrationPlugin(filePath: string): IntegrationPlugin;
+    /**
+     * Returns the cached renderer engine for the file's owning integration,
+     * creating it on first use.
+     */
     private getRouteRendererEngine;
 }

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

@@ -2,9 +2,15 @@ import { invariant } from "../utils/invariant.js";
 import { PathUtils } from "../utils/path-utils.module.js";
 class RouteRenderer {
   renderer;
+  /**
+   * Creates a route renderer bound to one integration renderer instance.
+   */
   constructor(renderer) {
     this.renderer = renderer;
   }
+  /**
+   * Executes the render pipeline for one matched route.
+   */
   async createRoute(options) {
     return this.renderer.execute(options);
   }
@@ -12,11 +18,23 @@ class RouteRenderer {
 class RouteRendererFactory {
   appConfig;
   runtimeOrigin;
+  rendererModules;
   rendererCache = /* @__PURE__ */ new Map();
-  constructor({ appConfig, runtimeOrigin }) {
+  /**
+   * Creates the route-renderer factory for one app/runtime instance.
+   */
+  constructor({
+    appConfig,
+    rendererModules,
+    runtimeOrigin
+  }) {
     this.appConfig = appConfig;
+    this.rendererModules = rendererModules;
     this.runtimeOrigin = runtimeOrigin;
   }
+  /**
+   * Returns a route renderer for the supplied route file.
+   */
   createRenderer(filePath) {
     const integrationRenderer = this.getRouteRendererEngine(filePath);
     invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
@@ -35,10 +53,15 @@ class RouteRendererFactory {
     if (cached) {
       return cached;
     }
-    const renderer = integrationPlugin.initializeRenderer();
+    const renderer = integrationPlugin.initializeRenderer({
+      rendererModules: this.rendererModules
+    });
     this.rendererCache.set(integrationName, renderer);
     return renderer;
   }
+  /**
+   * Resolves the integration plugin that owns a given route file.
+   */
   getIntegrationPlugin(filePath) {
     const templateExtension = PathUtils.getEcoTemplateExtension(filePath);
     const isIntegrationPlugin = (plugin) => {
@@ -51,13 +74,19 @@ class RouteRendererFactory {
     );
     return integrationPlugin;
   }
+  /**
+   * Returns the cached renderer engine for the file's owning integration,
+   * creating it on first use.
+   */
   getRouteRendererEngine(filePath) {
     const integrationPlugin = this.getIntegrationPlugin(filePath);
     const cached = this.rendererCache.get(integrationPlugin.name);
     if (cached) {
       return cached;
     }
-    const renderer = integrationPlugin.initializeRenderer();
+    const renderer = integrationPlugin.initializeRenderer({
+      rendererModules: this.rendererModules
+    });
     this.rendererCache.set(integrationPlugin.name, renderer);
     return renderer;
   }

package/src/router/README.md

@@ -0,0 +1,97 @@
+# Router Layer
+
+This directory contains route discovery, matching, and browser-side navigation infrastructure.
+
+## Purpose
+
+The router layer determines what route is being handled and how the client runtime coordinates navigation.
+
+It is responsible for:
+
+- filesystem route scanning and classification (`exact`, `dynamic`, `catch-all`)
+- matching incoming request URLs to discovered routes
+- server-side static-path expansion for dynamic routes
+- client-side navigation ownership and cross-runtime handoff
+- keeping route discovery separate from rendering execution
+
+## Directory Structure
+
+```
+router/
+├── server/                      # Server-side route scanning and matching
+│   ├── fs-router-scanner.ts     # Scans the filesystem and classifies routes
+│   └── fs-router.ts             # Matches request URLs to discovered routes
+└── client/                      # Browser-side navigation coordination
+    ├── navigation-coordinator.ts # Singleton runtime coordinator
+    └── link-intent.ts           # Shared anchor detection and intent recovery helpers
+```
+
+## `server/`
+
+### `FSRouterScanner`
+
+Walks the pages directory and builds a `Routes` map keyed by route pathname.
+
+File patterns determine route kind:
+
+| Pattern         | Kind        | Example           |
+| --------------- | ----------- | ----------------- |
+| `page.tsx`      | `exact`     | `/about`          |
+| `[slug].tsx`    | `dynamic`   | `/blog/[slug]`    |
+| `[...slug].tsx` | `catch-all` | `/docs/[...slug]` |
+
+For `dynamic` routes, the scanner checks whether the page module exports `getStaticPaths`. If present, every returned path is expanded into a concrete `exact`-style route at scan time. In build mode, both `getStaticPaths` and `getStaticProps` are required or an invariant is thrown.
+
+Catch-all routes are registered but skipped during static generation with a warning.
+
+### `FSRouter`
+
+Holds the scanned `Routes` map and exposes a `match(requestUrl)` method used by adapters.
+
+Match priority:
+
+1. `exact` — the pathname must equal the route pathname exactly.
+2. `dynamic` — the clean (bracket-stripped) prefix must appear in the pathname, and the segment counts must match.
+3. `catch-all` — the clean prefix must appear in the pathname.
+
+Additional helpers:
+
+- `getDynamicParams(route, pathname)` — extracts named and spread parameters from a matched dynamic or catch-all route.
+- `getSearchParams(url)` — converts `URLSearchParams` to a plain object.
+- `setOnReload(cb)` / `reload()` — re-scans routes and fires an optional callback, used during development HMR.
+
+## `client/`
+
+### Navigation Coordinator (`navigation-coordinator.ts`)
+
+A singleton browser-side runtime stored on `window.__ECO_PAGES__.navigation`.
+
+Access it with:
+
+```ts
+import { getEcoNavigationRuntime } from '@ecopages/core/router/client/navigation-coordinator';
+const runtime = getEcoNavigationRuntime();
+```
+
+The coordinator is framework-agnostic. Browser runtimes (e.g. `browser-router`, `react-router`) register themselves and the coordinator arbitrates:
+
+- **Ownership** — which runtime currently drives SPA navigation (`claimOwnership`, `releaseOwnership`, `setOwner`).
+- **Document owner marker** — an HTML attribute (`data-eco-document-owner`) written into rendered markup so the coordinator can `adoptDocumentOwner` on the incoming page.
+- **Navigation transactions** — each navigation begins a transaction with an `AbortSignal`; superseded navigations are automatically cancelled.
+- **Cross-runtime handoff** — `requestHandoff` passes a pre-fetched `Document` to the target runtime without tearing down the current page prematurely.
+- **Reload** — `reloadCurrentPage` delegates to whichever runtime currently owns the document.
+- **Events** — `subscribe` lets runtimes react to `owner-change` and `registration-change` events.
+
+### Link Intent (`link-intent.ts`)
+
+Shared helpers for locating anchors and recovering stale navigation intent.
+
+- `getAnchorFromNavigationEvent(event, linkSelector)` — finds the nearest matching anchor in the event's composed path, including across Shadow DOM boundaries.
+- `recoverPendingNavigationHref(intent, hasInFlightNavigation, now, maxAgeMs?)` — resolves a previously captured pointer or hover target when the DOM changes before the click lands. Intents expire after `maxAgeMs` (default 1000 ms).
+
+## Relationship To Rendering
+
+The router layer answers **which route should run**.
+The route-renderer layer answers **how that route gets rendered**.
+
+Keeping those seams separate avoids mixing route ownership, module loading, and component orchestration into one service.