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

package/src/route-renderer/page-loading/dependency-resolver.test.ts

@@ -203,28 +203,38 @@ describe('DependencyResolverService', () => {
 				file: componentFile,
 			},
 			dependencies: {
-				scripts: ['./widget.script.ts', './other.ts', { src: './lazy.ts', lazy: { 'on:interaction': 'click' } }],
+				scripts: [
+					'./widget.script.ts',
+					'./other.ts',
+					{ src: './lazy.ts', lazy: { 'on:interaction': 'click' } },
+				],
 			},
 		};
 
 		try {
 			await service.processComponentDependencies([component], 'ecopages-jsx');
 
+			const fileScripts = capturedDeps.filter(
+				(dep): dep is Extract<AssetDefinition, { kind: 'script'; source: 'file' }> =>
+					dep.kind === 'script' && dep.source === 'file',
+			);
 			const contentScripts = capturedDeps.filter(
 				(dep): dep is Extract<AssetDefinition, { kind: 'script'; source: 'content' }> =>
 					dep.kind === 'script' && dep.source === 'content',
 			);
 
-			expect(contentScripts).toHaveLength(2);
-
-			const pageScript = contentScripts.find((dep) => dep.packageRole === 'page-script');
-			const lazyEntry = contentScripts.find((dep) => dep.excludeFromHtml === true);
-
-			expect(pageScript).toEqual(
+			expect(fileScripts).toEqual([
 				expect.objectContaining({
-					content: `import ${JSON.stringify(widgetScript)};\nimport ${JSON.stringify(siblingScript)};`,
+					filepath: widgetScript,
 				}),
-			);
+				expect.objectContaining({
+					filepath: siblingScript,
+				}),
+			]);
+
+			expect(contentScripts).toHaveLength(1);
+
+			const lazyEntry = contentScripts.find((dep) => dep.excludeFromHtml === true);
 
 			expect(lazyEntry).toEqual(
 				expect.objectContaining({
@@ -236,7 +246,6 @@ describe('DependencyResolverService', () => {
 				}),
 			);
 
-			expect(pageScript?.groupedBundle).toBeUndefined();
 			expect(lazyEntry?.groupedBundle).toBeUndefined();
 		} finally {
 			rmSync(tempDir, { recursive: true, force: true });
@@ -248,7 +257,11 @@ describe('DependencyResolverService', () => {
 		const componentFile = join(tempDir, 'component.tsx');
 		const lazyScript = join(tempDir, 'theme-toggle.script.ts');
 
-		writeFileSync(componentFile, "import './theme-toggle.script';\nexport const Component = () => null;\n", 'utf-8');
+		writeFileSync(
+			componentFile,
+			"import './theme-toggle.script';\nexport const Component = () => null;\n",
+			'utf-8',
+		);
 		writeFileSync(lazyScript, 'export const themeToggle = true;\n', 'utf-8');
 
 		let capturedDeps: AssetDefinition[] = [];
@@ -420,6 +433,8 @@ describe('DependencyResolverService', () => {
 	});
 
 	it('should collapse bundleable page stylesheets and scripts into page-owned assets', async () => {
+		const previousNodeEnv = process.env.NODE_ENV;
+		process.env.NODE_ENV = 'production';
 		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-bundle-'));
 		const componentFile = join(tempDir, 'component.tsx');
 		const stylesheetA = join(tempDir, 'first.css');
@@ -473,15 +488,96 @@ describe('DependencyResolverService', () => {
 					source: 'content',
 					packageRole: 'page-style',
 					content: '.first { color: red; }\n.second { color: blue; }',
+					bundledSourceFilepaths: [stylesheetA, stylesheetB],
 				}),
 				expect.objectContaining({
 					kind: 'script',
 					source: 'content',
 					packageRole: 'page-script',
 					content: `import ${JSON.stringify(scriptA)};\nimport ${JSON.stringify(scriptB)};`,
+					bundledSourceFilepaths: [scriptA, scriptB],
+				}),
+			]);
+		} finally {
+			process.env.NODE_ENV = previousNodeEnv;
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should keep bundleable page stylesheets and scripts as file assets during development', async () => {
+		const previousNodeEnv = process.env.NODE_ENV;
+		process.env.NODE_ENV = 'development';
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-style-dev-'));
+		const componentFile = join(tempDir, 'component.tsx');
+		const stylesheetA = join(tempDir, 'first.css');
+		const stylesheetB = join(tempDir, 'second.css');
+		const scriptA = join(tempDir, 'first.ts');
+		const scriptB = join(tempDir, 'second.ts');
+
+		writeFileSync(componentFile, 'export const Component = () => null;', 'utf-8');
+		writeFileSync(stylesheetA, '.first { color: red; }', 'utf-8');
+		writeFileSync(stylesheetB, '.second { color: blue; }', 'utf-8');
+		writeFileSync(scriptA, 'export const first = true;', 'utf-8');
+		writeFileSync(scriptB, 'export const second = true;', 'utf-8');
+
+		let capturedDeps: AssetDefinition[] = [];
+		const assetProcessingService = {
+			processDependencies: vi.fn(async (deps: AssetDefinition[]) => {
+				capturedDeps = deps;
+				return [] as ProcessedAsset[];
+			}),
+		} as unknown as AssetProcessingService;
+
+		const bundleAppConfig = {
+			...appConfig,
+			rootDir: tempDir,
+			absolutePaths: {
+				srcDir: tempDir,
+				distDir: join(tempDir, '.eco/public'),
+			},
+		} as EcoPagesAppConfig;
+
+		const service = new DependencyResolverService(bundleAppConfig, assetProcessingService);
+		const component = ((_) => '<div></div>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'page-style-dev',
+				integration: 'react',
+				file: componentFile,
+			},
+			dependencies: {
+				stylesheets: ['./first.css', './second.css'],
+				scripts: ['./first.ts', './second.ts'],
+			},
+		};
+
+		try {
+			await service.processComponentDependencies([component], 'react');
+
+			expect(capturedDeps).toEqual([
+				expect.objectContaining({
+					kind: 'stylesheet',
+					source: 'file',
+					filepath: stylesheetA,
+				}),
+				expect.objectContaining({
+					kind: 'stylesheet',
+					source: 'file',
+					filepath: stylesheetB,
+				}),
+				expect.objectContaining({
+					kind: 'script',
+					source: 'file',
+					filepath: scriptA,
+				}),
+				expect.objectContaining({
+					kind: 'script',
+					source: 'file',
+					filepath: scriptB,
 				}),
 			]);
 		} finally {
+			process.env.NODE_ENV = previousNodeEnv;
 			rmSync(tempDir, { recursive: true, force: true });
 		}
 	});

package/src/route-renderer/page-loading/dependency-resolver.ts

@@ -1,18 +1,12 @@
 import path from 'node:path';
 import type { EcoComponent } from '../../types/public-types.ts';
 import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import type {
-	AssetProcessingService,
-	ProcessedAsset,
-} from '../../services/assets/asset-processing-service/index.ts';
+import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
 import { rapidhash } from '../../utils/hash.ts';
 import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
-import {
-	buildResolvedLazyTriggers,
-	type ResolvedLazyGroup,
-} from './lazy-trigger-planning.ts';
+import { buildResolvedLazyTriggers, type ResolvedLazyGroup } from './lazy-trigger-planning.ts';
 import { collectComponentDependencies } from './component-dependency-collection.ts';
-import { createUnifiedPageDependencies } from './page-dependency-bundling.ts';
+import { packagePageDependencies } from './page-dependency-bundling.ts';
 
 export const DEPENDENCY_ERRORS = {
 	INVALID_STYLESHEET_ENTRY: 'Invalid stylesheet dependency entry: expected src or content',
@@ -104,13 +98,13 @@ export class DependencyResolverService {
 			},
 		});
 
-		const unifiedDependencies = createUnifiedPageDependencies(dependencies, integrationName);
-		const hasLazyDependencies = unifiedDependencies.some(
+		const packagedDependencies = packagePageDependencies(dependencies, integrationName);
+		const hasLazyDependencies = packagedDependencies.some(
 			(dep) => dep.kind === 'script' && dep.excludeFromHtml === true,
 		);
 
 		const processedDependencies = await this.assetProcessingService.processDependencies(
-			unifiedDependencies,
+			packagedDependencies,
 			integrationName,
 		);
 		const lazyKeyToOutputUrl = new Map<string, string>();

package/src/route-renderer/page-loading/ecopages-virtual-imports.ts

@@ -72,4 +72,4 @@ export function extractEcopagesVirtualImports(file: string): EcopagesVirtualImpo
 		from,
 		imports: importsSet ? Array.from(importsSet) : undefined,
 	}));
-}
+}

package/src/route-renderer/page-loading/lazy-entry-collection.ts

@@ -164,4 +164,4 @@ export function collectLazyScriptEntries(options: CollectLazyEntriesOptions): vo
 			fallbackUrl,
 		});
 	}
-}
+}

package/src/route-renderer/page-loading/lazy-trigger-planning.ts

@@ -71,4 +71,4 @@ export function buildResolvedLazyTriggers(
 	});
 
 	return [{ triggerId, rules }];
-}
+}

package/src/route-renderer/page-loading/module-declaration-aggregation.ts

@@ -57,4 +57,4 @@ export function collectModuleDeclarations(
 	for (const declaration of autoVirtualImports) {
 		mergeModuleDeclaration(modulesMap, declaration);
 	}
-}
+}

package/src/route-renderer/page-loading/module-declaration-scripts.ts

@@ -13,4 +13,4 @@ export function createNamedImportModuleSource(from: string, imports: string[]):
 
 export function createNamespaceImportModuleSource(from: string): string {
 	return `export * from '${from}';`;
-}
+}

package/src/route-renderer/page-loading/page-dependency-bundling.ts

@@ -47,7 +47,7 @@ function normalizeCssReferenceToken(token: string): string {
  * working once multiple files are collapsed into one page-owned bundle.
  */
 function isSafeBundledStylesheetContent(content: string): boolean {
-	for (const match of content.matchAll(/@import\s+(?:url\()?['"]?([^'"\)\s]+)['"]?\)?/g)) {
+	for (const match of content.matchAll(/@import\s+(?:url\()?['"]?([^'")\s]+)['"]?\)?/g)) {
 		const reference = normalizeCssReferenceToken(match[1] ?? '');
 		if (reference && !isSafeBundledStylesheetReference(reference)) {
 			return false;
@@ -72,6 +72,13 @@ function isBundleableFileScriptAsset(dependency: AssetDefinition): dependency is
 	return dependency.kind === 'script' && dependency.source === 'file';
 }
 
+type PageDependencyPackagingPlan = {
+	bundledStylesheet?: AssetDefinition;
+	bundledScript?: AssetDefinition;
+	bundleableStyleFilepaths: Set<string>;
+	bundleableScriptFilepaths: Set<string>;
+};
+
 /**
  * Returns whether the current integration should collapse eligible page assets into
  * page-owned bundle entries.
@@ -80,53 +87,57 @@ export function shouldBundlePageDependencies(integrationName: string): boolean {
 	return integrationName === 'react' || integrationName === 'ecopages-jsx';
 }
 
-/**
- * Rewrites eligible flat dependency declarations into page-owned stylesheet and script bundles.
- *
- * Only assets with the default attribute shape and without explicit packaging roles are
- * collapsed so integration-specific or lazy behavior keeps its existing ownership model.
- */
-export function createUnifiedPageDependencies(
+function createPageDependencyPackagingPlan(
 	dependencies: AssetDefinition[],
 	integrationName: string,
-): AssetDefinition[] {
-	if (!shouldBundlePageDependencies(integrationName)) {
-		return dependencies;
-	}
+): PageDependencyPackagingPlan | undefined {
+	const shouldBundleDependencies = process.env.NODE_ENV === 'production';
 
-	const bundleableStyles = dependencies.filter((dependency) => {
-		if (dependency.kind !== 'stylesheet' || dependency.inline || dependency.position === 'body') {
-			return false;
-		}
+	const bundleableStyles = dependencies
+		.filter((dependency) => {
+			if (!shouldBundleDependencies) {
+				return false;
+			}
 
-		if (dependency.packageRole || !hasOnlyExpectedAttributes(dependency.attributes, { rel: 'stylesheet' })) {
-			return false;
-		}
+			if (dependency.kind !== 'stylesheet' || dependency.inline || dependency.position === 'body') {
+				return false;
+			}
 
-		if (dependency.source === 'content') {
-			return isSafeBundledStylesheetContent(dependency.content);
-		}
+			if (dependency.packageRole || !hasOnlyExpectedAttributes(dependency.attributes, { rel: 'stylesheet' })) {
+				return false;
+			}
 
-		if (!existsSync(dependency.filepath)) {
-			return false;
-		}
+			if (dependency.source === 'content') {
+				return isSafeBundledStylesheetContent(dependency.content);
+			}
 
-		return isSafeBundledStylesheetContent(readFileSync(dependency.filepath, 'utf8'));
-	}).filter(isBundleableFileStylesheetAsset);
+			if (!existsSync(dependency.filepath)) {
+				return false;
+			}
 
-	const bundleableScripts = dependencies.filter((dependency) => {
-		return (
-			dependency.kind === 'script' &&
-			dependency.source === 'file' &&
-			!dependency.inline &&
-			!dependency.excludeFromHtml &&
-			dependency.position !== 'body' &&
-			!dependency.packageRole &&
-			dependency.bundle !== false &&
-			hasOnlyExpectedAttributes(dependency.attributes, { type: 'module', defer: '' }) &&
-			existsSync(dependency.filepath)
-		);
-	}).filter(isBundleableFileScriptAsset);
+			return isSafeBundledStylesheetContent(readFileSync(dependency.filepath, 'utf8'));
+		})
+		.filter(isBundleableFileStylesheetAsset);
+
+	const bundleableScripts = dependencies
+		.filter((dependency) => {
+			if (!shouldBundleDependencies) {
+				return false;
+			}
+
+			return (
+				dependency.kind === 'script' &&
+				dependency.source === 'file' &&
+				!dependency.inline &&
+				!dependency.excludeFromHtml &&
+				dependency.position !== 'body' &&
+				!dependency.packageRole &&
+				dependency.bundle !== false &&
+				hasOnlyExpectedAttributes(dependency.attributes, { type: 'module', defer: '' }) &&
+				existsSync(dependency.filepath)
+			);
+		})
+		.filter(isBundleableFileScriptAsset);
 
 	const bundledStylesheet =
 		bundleableStyles.length > 1
@@ -135,56 +146,65 @@ export function createUnifiedPageDependencies(
 					position: 'head',
 					attributes: { rel: 'stylesheet' },
 					packageRole: 'page-style',
+					bundledSourceFilepaths: bundleableStyles.map((dependency) => dependency.filepath),
 				})
 			: undefined;
 
-	const bundleableStyleFilepaths = new Set(bundleableStyles.map((dependency) => dependency.filepath));
 	const pageScriptImports = [...new Set(bundleableScripts.map((dependency) => dependency.filepath))];
-	const bundleableScriptFilepaths = new Set(pageScriptImports);
-
 	const shouldBundlePageScript = pageScriptImports.length > 0 && bundleableScripts.length > 1;
-
-	const bundledScript =
-		shouldBundlePageScript
-			? AssetFactory.createContentScript({
-					name: `${integrationName}-page-${rapidhash(pageScriptImports.join('|')).toString(16)}`,
-					content: pageScriptImports.map((filepath) => `import ${JSON.stringify(filepath)};`).join('\n'),
-					position: 'head',
-					attributes: { type: 'module', defer: '' },
-					packageRole: 'page-script',
-				})
-			: undefined;
+	const bundledScript = shouldBundlePageScript
+		? AssetFactory.createContentScript({
+				name: `${integrationName}-page-${rapidhash(pageScriptImports.join('|')).toString(16)}`,
+				content: pageScriptImports.map((filepath) => `import ${JSON.stringify(filepath)};`).join('\n'),
+				position: 'head',
+				attributes: { type: 'module', defer: '' },
+				packageRole: 'page-script',
+				bundledSourceFilepaths: pageScriptImports,
+			})
+		: undefined;
 
 	if (!bundledStylesheet && !bundledScript) {
-		return dependencies;
+		return undefined;
 	}
 
+	return {
+		bundledStylesheet,
+		bundledScript,
+		bundleableStyleFilepaths: new Set(bundleableStyles.map((dependency) => dependency.filepath)),
+		bundleableScriptFilepaths: new Set(pageScriptImports),
+	};
+}
+
+function applyPageDependencyPackagingPlan(
+	dependencies: AssetDefinition[],
+	plan: PageDependencyPackagingPlan,
+): AssetDefinition[] {
 	const unifiedDependencies: AssetDefinition[] = [];
 	let insertedStylesheet = false;
 	let insertedScript = false;
 
 	for (const dependency of dependencies) {
 		if (
-			bundledStylesheet &&
+			plan.bundledStylesheet &&
 			dependency.kind === 'stylesheet' &&
 			dependency.source === 'file' &&
-			bundleableStyleFilepaths.has(dependency.filepath)
+			plan.bundleableStyleFilepaths.has(dependency.filepath)
 		) {
 			if (!insertedStylesheet) {
-				unifiedDependencies.push(bundledStylesheet);
+				unifiedDependencies.push(plan.bundledStylesheet);
 				insertedStylesheet = true;
 			}
 			continue;
 		}
 
 		if (
-			bundledScript &&
+			plan.bundledScript &&
 			dependency.kind === 'script' &&
 			dependency.source === 'file' &&
-			bundleableScriptFilepaths.has(dependency.filepath)
+			plan.bundleableScriptFilepaths.has(dependency.filepath)
 		) {
 			if (!insertedScript) {
-				unifiedDependencies.push(bundledScript);
+				unifiedDependencies.push(plan.bundledScript);
 				insertedScript = true;
 			}
 			continue;
@@ -193,13 +213,32 @@ export function createUnifiedPageDependencies(
 		unifiedDependencies.push(dependency);
 	}
 
-	if (bundledScript && !insertedScript) {
-		unifiedDependencies.push(bundledScript);
+	if (plan.bundledScript && !insertedScript) {
+		unifiedDependencies.push(plan.bundledScript);
 	}
 
-	if (bundledStylesheet && !insertedStylesheet) {
-		unifiedDependencies.push(bundledStylesheet);
+	if (plan.bundledStylesheet && !insertedStylesheet) {
+		unifiedDependencies.push(plan.bundledStylesheet);
 	}
 
 	return unifiedDependencies;
-}
+}
+
+/**
+ * Rewrites eligible flat dependency declarations into page-owned stylesheet and script bundles.
+ *
+ * Only assets with the default attribute shape and without explicit packaging roles are
+ * collapsed so integration-specific or lazy behavior keeps its existing ownership model.
+ */
+export function packagePageDependencies(dependencies: AssetDefinition[], integrationName: string): AssetDefinition[] {
+	if (!shouldBundlePageDependencies(integrationName)) {
+		return dependencies;
+	}
+
+	const plan = createPageDependencyPackagingPlan(dependencies, integrationName);
+	if (!plan) {
+		return dependencies;
+	}
+
+	return applyPageDependencyPackagingPlan(dependencies, plan);
+}

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

@@ -1,43 +1,41 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.ts';
 import type { IntegrationPlugin } from '../plugins/integration-plugin.ts';
-import type { EcoPageFile, RouteRenderResult, RouteRendererOptions } from '../types/public-types.ts';
 import { invariant } from '../utils/invariant.ts';
 import { PathUtils } from '../utils/path-utils.module.ts';
-import type { IntegrationRenderer, RouteModuleLoadOptions } from './orchestration/integration-renderer.ts';
+import type { IntegrationRenderer } from './orchestration/integration-renderer.ts';
 
 /**
- * Thin wrapper around one initialized integration renderer.
+ * Narrow route-render contract exposed to higher-level routing code.
  *
  * @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.
+ * Higher-level routing code only needs request execution and page-module
+ * loading. Returning this narrowed shape avoids a dedicated wrapper class while
+ * still keeping callers off the full integration renderer surface.
  */
-export class RouteRenderer {
-	private renderer: IntegrationRenderer;
+export type PageRouteRenderer = Pick<IntegrationRenderer, 'execute' | 'loadPageModule'>;
 
-	/**
-	 * Creates a route renderer bound to one integration renderer instance.
-	 */
-	constructor(renderer: IntegrationRenderer) {
-		this.renderer = renderer;
-	}
+/**
+ * Narrow explicit-view render contract exposed to static route handling.
+ *
+ * @remarks
+ * Explicit static routes only need `renderToResponse()`, so the factory can
+ * hide the broader integration renderer surface there as well.
+ */
+export type ExplicitViewRenderer = Pick<IntegrationRenderer, 'renderToResponse'>;
 
-	/**
-	 * Executes the render pipeline for one matched route.
-	 */
-	async createRoute(options: RouteRendererOptions): Promise<RouteRenderResult> {
-		return this.renderer.execute(options);
-	}
+export interface PageRendererResolver {
+	getPageRenderer(filePath: string): PageRouteRenderer;
+}
 
-	/**
-	 * Loads the route module through the owning integration renderer.
-	 */
-	async loadPageModule(filePath: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile> {
-		return this.renderer.loadPageModule(filePath, options);
-	}
+export interface ExplicitViewRendererResolver {
+	getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null;
 }
 
+/**
+ * Combined renderer-factory contract used by static generation.
+ */
+export type StaticGenerationRendererResolver = PageRendererResolver & ExplicitViewRendererResolver;
+
 /**
  * Selects and caches integration renderers for route files and explicit views.
  *
@@ -72,17 +70,16 @@ export class RouteRendererFactory {
 	/**
 	 * Returns a route renderer for the supplied route file.
 	 */
-	createRenderer(filePath: string): RouteRenderer {
+	getPageRenderer(filePath: string): PageRouteRenderer {
 		const integrationRenderer = this.getRouteRendererEngine(filePath);
 		invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
-		return new RouteRenderer(integrationRenderer);
+		return integrationRenderer;
 	}
 
 	/**
-	 * Get an integration renderer by its name.
-	 * Used for explicit routing where views specify their integration via __eco.integration.
+	 * Returns a renderer for an explicit view integration.
 	 */
-	getRendererByIntegration(integrationName: string): IntegrationRenderer | null {
+	getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null {
 		const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
 		if (!integrationPlugin) {
 			return null;

package/src/router/README.md

@@ -8,9 +8,9 @@ The router layer determines what route is being handled and how the client runti
 
 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
+- filesystem route discovery and classification (`exact`, `dynamic`, `catch-all`)
+- matching incoming request URLs to canonical template routes
+- server-side static-path expansion for dynamic template routes
 - client-side navigation ownership and cross-runtime handoff
 - keeping route discovery separate from rendering execution
 
@@ -18,9 +18,8 @@ It is responsible for:
 
 ```
 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
+├── server/                      # Server-side route discovery and matching
+│   └── route-registry.ts        # Owns template routes, request matching, static expansion, and reload
 └── client/                      # Browser-side navigation coordination
     ├── navigation-coordinator.ts # Singleton runtime coordinator
     └── link-intent.ts           # Shared anchor detection and intent recovery helpers
@@ -28,9 +27,9 @@ router/
 
 ## `server/`
 
-### `FSRouterScanner`
+### `RouteRegistry`
 
-Walks the pages directory and builds a `Routes` map keyed by route pathname.
+Owns the canonical set of filesystem-discovered template routes for one application.
 
 File patterns determine route kind:
 
@@ -40,13 +39,17 @@ File patterns determine route kind:
 | `[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.
+The registry stores canonical template routes only. It compiles request-time matching metadata during `init()` and `reload()`, but it does not execute `staticPaths()` during discovery.
 
-Catch-all routes are registered but skipped during static generation with a warning.
+Build-time static expansion is a separate operation. The registry invokes `staticPaths()` lazily through an injected page-module adapter and returns concrete static path expansions for the static generator.
 
-### `FSRouter`
+The public interface is intentionally small:
 
-Holds the scanned `Routes` map and exposes a `match(requestUrl)` method used by adapters.
+- `templateRoutes` — ordered readonly template routes
+- `init()` / `reload()` — rebuild discovery state and match metadata
+- `matchRequest(requestUrl)` — request-time matching result with requested pathname, matched template route, params, and query
+- `listStaticPathExpansions()` — build-time expansion for dynamic routes
+- `listStaticGenerationRoutes()` — build-time route planning for static generation across exact and expanded routes
 
 Match priority:
 
@@ -54,12 +57,6 @@ Match priority:
 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`)
@@ -69,7 +66,7 @@ A singleton browser-side runtime stored on `window.__ECO_PAGES__.navigation`.
 Access it with:
 
 ```ts
-import { getEcoNavigationRuntime } from '@ecopages/core/router/client/navigation-coordinator';
+import { getEcoNavigationRuntime } from '@ecopages/core/router/navigation-coordinator';
 const runtime = getEcoNavigationRuntime();
 ```