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

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

@@ -0,0 +1,133 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+import type { IntegrationPlugin } from '../plugins/integration-plugin.ts';
+import { invariant } from '../utils/invariant.ts';
+import { PathUtils } from '../utils/path-utils.module.ts';
+import type { IntegrationRenderer } from './orchestration/integration-renderer.ts';
+
+/**
+ * Narrow route-render contract exposed to higher-level routing code.
+ *
+ * @remarks
+ * 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 type PageRouteRenderer = Pick<IntegrationRenderer, 'execute' | 'loadPageModule'>;
+
+/**
+ * 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'>;
+
+export interface PageRendererResolver {
+	getPageRenderer(filePath: string): PageRouteRenderer;
+}
+
+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.
+ *
+ * @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 class RouteRendererFactory {
+	private appConfig: EcoPagesAppConfig;
+	runtimeOrigin: string;
+	private rendererModules?: unknown;
+	private rendererCache = new Map<string, IntegrationRenderer>();
+
+	/**
+	 * Creates the route-renderer factory for one app/runtime instance.
+	 */
+	constructor({
+		appConfig,
+		rendererModules,
+		runtimeOrigin,
+	}: {
+		appConfig: EcoPagesAppConfig;
+		rendererModules?: unknown;
+		runtimeOrigin: string;
+	}) {
+		this.appConfig = appConfig;
+		this.rendererModules = rendererModules;
+		this.runtimeOrigin = runtimeOrigin;
+	}
+
+	/**
+	 * Returns a route renderer for the supplied route file.
+	 */
+	getPageRenderer(filePath: string): PageRouteRenderer {
+		const integrationRenderer = this.getRouteRendererEngine(filePath);
+		invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
+		return integrationRenderer;
+	}
+
+	/**
+	 * Returns a renderer for an explicit view integration.
+	 */
+	getExplicitViewRenderer(integrationName: string): ExplicitViewRenderer | null {
+		const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
+		if (!integrationPlugin) {
+			return null;
+		}
+
+		const cached = this.rendererCache.get(integrationName);
+		if (cached) {
+			return cached;
+		}
+
+		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: string): IntegrationPlugin {
+		const templateExtension = PathUtils.getEcoTemplateExtension(filePath);
+		const isIntegrationPlugin = (plugin: IntegrationPlugin): boolean => {
+			return plugin.extensions.some((extension) => templateExtension === extension);
+		};
+		const integrationPlugin = this.appConfig.integrations.find(isIntegrationPlugin);
+		invariant(
+			!!integrationPlugin,
+			`No integration plugin found for template extension: ${templateExtension}, file: ${filePath}`,
+		);
+		return integrationPlugin as IntegrationPlugin;
+	}
+
+	/**
+	 * Returns the cached renderer engine for the file's owning integration,
+	 * creating it on first use.
+	 */
+	private getRouteRendererEngine(filePath: string): IntegrationRenderer {
+		const integrationPlugin = this.getIntegrationPlugin(filePath);
+		const cached = this.rendererCache.get(integrationPlugin.name);
+		if (cached) {
+			return cached;
+		}
+
+		const renderer = integrationPlugin.initializeRenderer({
+			rendererModules: this.rendererModules,
+		});
+		this.rendererCache.set(integrationPlugin.name, renderer);
+		return renderer;
+	}
+}

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();
 ```
 

package/src/router/client/link-intent.test.browser.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { getAnchorFromNavigationEvent, recoverPendingNavigationHref } from './link-intent.ts';
+
+describe('getAnchorFromNavigationEvent', () => {
+	it('returns the anchor when the event target is a text node inside it', () => {
+		const anchor = document.createElement('a');
+		anchor.href = '/fast';
+		anchor.setAttribute('data-eco-link', 'true');
+		const textNode = document.createTextNode('fast-link');
+		anchor.append(textNode);
+		document.body.append(anchor);
+
+		const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
+		Object.defineProperty(event, 'target', {
+			configurable: true,
+			value: textNode,
+		});
+
+		expect(getAnchorFromNavigationEvent(event, 'a[data-eco-link]')).toBe(anchor);
+	});
+
+	it('returns the closest matching anchor for nested element targets', () => {
+		const anchor = document.createElement('a');
+		anchor.href = '/fast';
+		anchor.setAttribute('data-eco-link', 'true');
+		const span = document.createElement('span');
+		span.textContent = 'fast-link';
+		anchor.append(span);
+		document.body.append(anchor);
+
+		const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
+		Object.defineProperty(event, 'target', {
+			configurable: true,
+			value: span,
+		});
+
+		expect(getAnchorFromNavigationEvent(event, 'a[data-eco-link]')).toBe(anchor);
+	});
+});
+
+describe('recoverPendingNavigationHref', () => {
+	it('returns null for stale or missing pending intent state', () => {
+		expect(recoverPendingNavigationHref(null, true, 10)).toBeNull();
+		expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 0 }, false, 10)).toBeNull();
+		expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 0 }, true, 2000, 1000)).toBeNull();
+	});
+
+	it('returns the captured href while a navigation is still in flight', () => {
+		expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 10 }, true, 20, 1000)).toBe('/fast');
+	});
+});

package/src/router/client/link-intent.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared client-side navigation intent helpers.
+ *
+ * Browser runtimes use the same low-level mechanics to:
+ * - locate the anchor associated with a click, pointer, or hover event,
+ * - persist the last valid pointer or hover target while a navigation is in flight,
+ * - recover the final intended href when the DOM changes before the click lands.
+ *
+ * Keeping those mechanics here lets browser-router and react-router share one
+ * implementation while preserving their router-specific interception rules.
+ *
+ * @module
+ */
+
+/**
+ * Timestamped navigation intent captured from pointer or hover activity.
+ */
+export type EcoPendingNavigationIntent = {
+	href: string;
+	timestamp: number;
+};
+
+/**
+ * Finds the nearest matching anchor within an event's composed path.
+ *
+ * This works across Shadow DOM boundaries, which is required for delegated
+ * navigation handling when links are rendered inside custom elements.
+ *
+ * @param event - Pointer or mouse event being inspected.
+ * @param linkSelector - Selector that identifies navigable anchors.
+ * @returns The matched anchor element, or `null` when no matching anchor exists.
+ */
+export function getAnchorFromNavigationEvent(
+	event: MouseEvent | PointerEvent,
+	linkSelector: string,
+): HTMLAnchorElement | null {
+	const eventTarget = event.target;
+
+	if (eventTarget instanceof HTMLAnchorElement && eventTarget.matches(linkSelector)) {
+		return eventTarget;
+	}
+
+	if (eventTarget instanceof Element) {
+		const closestAnchor = eventTarget.closest(linkSelector);
+		if (closestAnchor instanceof HTMLAnchorElement) {
+			return closestAnchor;
+		}
+	}
+
+	if (eventTarget instanceof Text) {
+		const parentAnchor = eventTarget.parentElement?.closest(linkSelector);
+		if (parentAnchor instanceof HTMLAnchorElement) {
+			return parentAnchor;
+		}
+	}
+
+	return event
+		.composedPath()
+		.find(
+			(target) => target instanceof HTMLAnchorElement && target.matches(linkSelector),
+		) as HTMLAnchorElement | null;
+}
+
+/**
+ * Resolves a previously captured intent while a navigation is still in flight.
+ *
+ * Pending intents expire quickly because they are only meant to bridge the gap
+ * between pointer or hover capture and the later click event when the DOM or
+ * active runtime changes during a rapid navigation sequence.
+ *
+ * @param intent - Previously captured pointer or hover intent.
+ * @param hasInFlightNavigation - Whether a router navigation is still active.
+ * @param now - Current monotonic timestamp, usually from `performance.now()`.
+ * @param maxAgeMs - Maximum allowed age for the recovered intent.
+ * @returns The intended href when still valid, otherwise `null`.
+ */
+export function recoverPendingNavigationHref(
+	intent: EcoPendingNavigationIntent | null,
+	hasInFlightNavigation: boolean,
+	now: number,
+	maxAgeMs = 1000,
+): string | null {
+	if (!intent || !hasInFlightNavigation) {
+		return null;
+	}
+
+	if (now - intent.timestamp > maxAgeMs) {
+		return null;
+	}
+
+	return intent.href;
+}

package/src/router/client/navigation-coordinator.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getEcoNavigationRuntime } from './navigation-coordinator.ts';
+
+function createWindowLike() {
+	return {} as Window &
+		typeof globalThis & {
+			__ECO_PAGES__?: { navigation?: ReturnType<typeof getEcoNavigationRuntime> };
+		};
+}
+
+describe('getEcoNavigationRuntime', () => {
+	it('returns the same coordinator instance for the same window', () => {
+		const windowLike = createWindowLike();
+		const first = getEcoNavigationRuntime(windowLike);
+		const second = getEcoNavigationRuntime(windowLike);
+
+		expect(first).toBe(second);
+	});
+
+	it('tracks explicit ownership claims', () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+
+		runtime.claimOwnership('react-router');
+
+		expect(runtime.getOwnerState()).toEqual({
+			owner: 'react-router',
+			canHandleSpaNavigation: false,
+		});
+	});
+
+	it('shares one navigation transaction sequence across runtimes', () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+
+		const first = runtime.beginNavigationTransaction();
+		expect(runtime.hasPendingNavigationTransaction()).toBe(true);
+		expect(first.isCurrent()).toBe(true);
+		expect(first.signal.aborted).toBe(false);
+
+		const second = runtime.beginNavigationTransaction();
+
+		expect(first.isCurrent()).toBe(false);
+		expect(first.signal.aborted).toBe(true);
+		expect(second.isCurrent()).toBe(true);
+		expect(second.signal.aborted).toBe(false);
+		second.complete();
+		expect(runtime.hasPendingNavigationTransaction()).toBe(false);
+	});
+
+	it('cancels only the current navigation transaction', () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+
+		const first = runtime.beginNavigationTransaction();
+		const second = runtime.beginNavigationTransaction();
+
+		first.cancel();
+		expect(second.isCurrent()).toBe(true);
+		expect(second.signal.aborted).toBe(false);
+
+		second.cancel();
+		expect(second.isCurrent()).toBe(false);
+		expect(second.signal.aborted).toBe(true);
+		expect(runtime.hasPendingNavigationTransaction()).toBe(false);
+	});
+
+	it('adopts ownership from the rendered document marker', () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const documentLike = {
+			documentElement: {
+				getAttribute: vi.fn(() => 'custom-router'),
+			},
+		} as unknown as Document;
+
+		expect(runtime.adoptDocumentOwner(documentLike, 'browser-router')).toBe('custom-router');
+		expect(runtime.getOwnerState().owner).toBe('custom-router');
+	});
+
+	it('delegates navigation to another registered runtime when the source cannot handle it', async () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const navigateSpy = vi.fn(async () => true);
+
+		runtime.register({ owner: 'browser-router', navigate: navigateSpy });
+		runtime.register({ owner: 'react-router', navigate: vi.fn(async () => true) });
+		runtime.claimOwnership('react-router');
+
+		const handled = await runtime.requestNavigation({
+			href: '/docs',
+			direction: 'forward',
+			source: 'react-router',
+		});
+
+		expect(handled).toBe(true);
+		expect(navigateSpy).toHaveBeenCalledWith({
+			href: '/docs',
+			direction: 'forward',
+			source: 'react-router',
+		});
+	});
+
+	it('delegates a fetched document handoff to the targeted runtime without forcing source cleanup first', async () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const cleanupSpy = vi.fn(async () => undefined);
+		const handoffSpy = vi.fn(async () => true);
+		const documentLike = {
+			documentElement: {
+				getAttribute: vi.fn(() => null),
+			},
+		} as unknown as Document;
+
+		runtime.register({ owner: 'react-router', cleanupBeforeHandoff: cleanupSpy });
+		runtime.register({ owner: 'browser-router', handoffNavigation: handoffSpy });
+		runtime.claimOwnership('react-router');
+
+		const handled = await runtime.requestHandoff({
+			href: '/docs',
+			finalHref: '/docs',
+			direction: 'forward',
+			source: 'react-router',
+			targetOwner: 'browser-router',
+			document: documentLike,
+		});
+
+		expect(handled).toBe(true);
+		expect(cleanupSpy).not.toHaveBeenCalled();
+		expect(handoffSpy).toHaveBeenCalledWith({
+			href: '/docs',
+			finalHref: '/docs',
+			direction: 'forward',
+			source: 'react-router',
+			targetOwner: 'browser-router',
+			document: documentLike,
+		});
+	});
+
+	it('ignores stale handoff requests before cleaning up the active owner', async () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const cleanupSpy = vi.fn(async () => undefined);
+		const handoffSpy = vi.fn(async () => true);
+		const documentLike = {
+			documentElement: {
+				getAttribute: vi.fn(() => null),
+			},
+		} as unknown as Document;
+
+		runtime.register({ owner: 'react-router', cleanupBeforeHandoff: cleanupSpy });
+		runtime.register({ owner: 'browser-router', handoffNavigation: handoffSpy });
+		runtime.claimOwnership('react-router');
+
+		const handled = await runtime.requestHandoff({
+			href: '/docs',
+			finalHref: '/docs',
+			direction: 'forward',
+			source: 'react-router',
+			targetOwner: 'browser-router',
+			document: documentLike,
+			isStaleSourceNavigation: () => true,
+		});
+
+		expect(handled).toBe(true);
+		expect(cleanupSpy).not.toHaveBeenCalled();
+		expect(handoffSpy).not.toHaveBeenCalled();
+		expect(runtime.getOwnerState().owner).toBe('react-router');
+	});
+
+	it('reloads the current owner through its registration', async () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const reloadSpy = vi.fn(async () => undefined);
+
+		runtime.register({ owner: 'react-router', reloadCurrentPage: reloadSpy });
+		runtime.claimOwnership('react-router');
+
+		const handled = await runtime.reloadCurrentPage({ clearCache: true, source: 'browser-router' });
+
+		expect(handled).toBe(true);
+		expect(reloadSpy).toHaveBeenCalledWith({ clearCache: true, source: 'browser-router' });
+	});
+
+	it('reloads the current owner even when the request source matches that owner', async () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const reloadSpy = vi.fn(async () => undefined);
+
+		runtime.register({ owner: 'react-router', reloadCurrentPage: reloadSpy });
+		runtime.claimOwnership('react-router');
+
+		const handled = await runtime.reloadCurrentPage({ clearCache: false, source: 'react-router' });
+
+		expect(handled).toBe(true);
+		expect(reloadSpy).toHaveBeenCalledWith({ clearCache: false, source: 'react-router' });
+	});
+
+	it('cleans up an explicit owner via its registration', async () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const cleanupSpy = vi.fn();
+
+		runtime.register({ owner: 'react-router', cleanupBeforeHandoff: cleanupSpy });
+		runtime.claimOwnership('react-router');
+
+		await runtime.cleanupOwner('react-router');
+
+		expect(cleanupSpy).toHaveBeenCalledTimes(1);
+		expect(runtime.getOwnerState().owner).toBe('none');
+	});
+
+	it('emits events for registrations and ownership changes', () => {
+		const windowLike = createWindowLike();
+		const runtime = getEcoNavigationRuntime(windowLike);
+		const listener = vi.fn();
+		const unsubscribe = runtime.subscribe(listener);
+
+		const unregister = runtime.register({ owner: 'custom-router' });
+		runtime.claimOwnership('custom-router');
+		runtime.releaseOwnership('custom-router');
+		unregister();
+		unsubscribe();
+
+		expect(listener).toHaveBeenCalledWith({
+			type: 'registration-change',
+			owner: 'custom-router',
+			status: 'registered',
+		});
+		expect(listener).toHaveBeenCalledWith({
+			type: 'owner-change',
+			owner: 'custom-router',
+			previousOwner: 'none',
+			reason: 'claim',
+		});
+	});
+});