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

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

@@ -1,453 +0,0 @@
-/**
- * Shared browser-side navigation coordinator.
- *
- * This module is the client runtime contract used by browser-router,
- * react-router, and HMR code to coordinate ownership, cross-runtime handoff,
- * current-page reloads, and stale-navigation cancellation.
- *
- * The coordinator stays framework-agnostic: browser runtimes register their
- * capabilities here, and the coordinator arbitrates which runtime currently
- * owns the document and which navigation transaction is still current.
- *
- * @module
- */
-
-/** Logical owner name for a browser navigation runtime. */
-export type EcoNavigationOwner = 'none' | 'browser-router' | 'react-router' | (string & {});
-
-/** HTML attribute used to persist the rendered document owner across navigations. */
-export const ECO_DOCUMENT_OWNER_ATTRIBUTE = 'data-eco-document-owner';
-
-/** High-level navigation direction understood by browser runtimes. */
-export type EcoNavigationDirection = 'forward' | 'back' | 'replace';
-
-/** Navigation request sent between browser runtimes. */
-export type EcoNavigationRequest = {
-	href: string;
-	direction?: EcoNavigationDirection;
-	source?: EcoNavigationOwner;
-};
-
-/** Navigation handoff request that includes a pre-fetched document. */
-export type EcoNavigationHandoffRequest = EcoNavigationRequest & {
-	finalHref?: string;
-	targetOwner: EcoNavigationOwner;
-	document: Document;
-	html?: string;
-	/**
-	 * Reports whether the source runtime's original navigation has already been
-	 * superseded.
-	 *
-	 * Target runtimes use this to ignore handoff work that arrives after a newer
-	 * navigation has already claimed ownership.
-	 */
-	isStaleSourceNavigation?: () => boolean;
-};
-
-/** Request to reload the current page through the active runtime. */
-export type EcoReloadRequest = {
-	/**
-	 * Clears runtime-owned caches before reloading.
-	 *
-	 * Runtimes use this when a reload must discard persisted client state such as
-	 * cached layouts or route-local module instances.
-	 */
-	clearCache?: boolean;
-	/**
-	 * Explicit page module URL to load for the reload.
-	 *
-	 * This is primarily used by HMR-aware runtimes so a current-page reload can
-	 * reuse the active hot module entry instead of rediscovering the static page
-	 * bootstrap asset from the fetched HTML document.
-	 */
-	moduleUrl?: string;
-	source?: EcoNavigationOwner;
-};
-
-/** Snapshot of the coordinator's current runtime ownership state. */
-export type EcoNavigationOwnerState = {
-	owner: EcoNavigationOwner;
-	canHandleSpaNavigation: boolean;
-};
-
-/**
- * Coordinator-managed navigation transaction.
- *
- * Runtimes use this to determine whether async work has become stale and to
- * cancel or complete the active navigation sequence.
- */
-export type EcoNavigationTransaction = {
-	id: number;
-	signal: AbortSignal;
-	isCurrent: () => boolean;
-	cancel: () => void;
-	complete: () => void;
-};
-
-export type EcoNavigationRuntimeEvent =
-	| {
-			type: 'owner-change';
-			owner: EcoNavigationOwner;
-			previousOwner: EcoNavigationOwner;
-			reason: 'set' | 'claim' | 'release' | 'document' | 'unregister';
-	  }
-	| {
-			type: 'registration-change';
-			owner: EcoNavigationOwner;
-			status: 'registered' | 'unregistered';
-	  };
-
-export type EcoNavigationRuntimeListener = (event: EcoNavigationRuntimeEvent) => void;
-
-export type EcoNavigationRuntimeRegistration = {
-	owner: EcoNavigationOwner;
-	navigate?: (request: EcoNavigationRequest) => Promise<boolean | void>;
-	handoffNavigation?: (request: EcoNavigationHandoffRequest) => Promise<boolean | void>;
-	/**
-	 * Reloads the current page through the runtime's local navigation mechanism.
-	 *
-	 * Implementations may honor `request.moduleUrl` to force a specific page entry
-	 * and `request.clearCache` to discard persisted runtime state before reloading.
-	 */
-	reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<void>;
-	/**
-	 * Releases runtime-owned client state before another runtime commits a new
-	 * document.
-	 *
-	 * This hook intentionally does not run as part of `requestHandoff()`. The
-	 * accepting runtime decides when cleanup is safe so cross-runtime handoffs do
-	 * not blank the current page before the incoming document is ready.
-	 */
-	cleanupBeforeHandoff?: () => void | Promise<void>;
-};
-
-/** Public browser-side navigation coordinator interface. */
-export interface EcoNavigationRuntime {
-	/** Returns the currently active runtime owner and whether it can handle SPA navigation. */
-	getOwnerState(): EcoNavigationOwnerState;
-	/** Starts a new navigation transaction, invalidating the previously active one. */
-	beginNavigationTransaction(): EcoNavigationTransaction;
-	/** Reports whether a navigation transaction is still in flight. */
-	hasPendingNavigationTransaction(): boolean;
-	/** Cancels the active navigation transaction, if one exists. */
-	cancelCurrentNavigationTransaction(): void;
-	/** Forces the current owner value without checking registrations. */
-	setOwner(owner: EcoNavigationOwner): void;
-	/** Claims ownership for a runtime that is ready to drive SPA navigation. */
-	claimOwnership(owner: EcoNavigationOwner): void;
-	/** Releases ownership when the given runtime no longer controls the document. */
-	releaseOwnership(owner: EcoNavigationOwner): void;
-	/** Resolves document ownership from the rendered owner marker or fallback. */
-	resolveDocumentOwner(doc: Document, fallbackOwner?: EcoNavigationOwner): EcoNavigationOwner;
-	/** Reads and adopts the rendered document owner as the active runtime owner. */
-	adoptDocumentOwner(doc: Document, fallbackOwner?: EcoNavigationOwner): EcoNavigationOwner;
-	/** Returns whether the active owner is some runtime other than the given owner. */
-	isOwnedByAnotherRuntime(owner: EcoNavigationOwner): boolean;
-	/** Subscribes to ownership and registration change events. */
-	subscribe(listener: EcoNavigationRuntimeListener): () => void;
-	/** Registers a runtime implementation with the coordinator. */
-	register(runtime: EcoNavigationRuntimeRegistration): () => void;
-	/** Requests navigation through another eligible registered runtime. */
-	requestNavigation(request: EcoNavigationRequest): Promise<boolean>;
-	/**
-	 * Hands a pre-fetched document to the target runtime.
-	 *
-	 * The coordinator delegates the document but does not clean up the current
-	 * owner first. Cleanup timing belongs to the accepting runtime so a stale or
-	 * superseded handoff cannot tear down the current page prematurely.
-	 */
-	requestHandoff(request: EcoNavigationHandoffRequest): Promise<boolean>;
-	/** Requests the active runtime to reload the current page. */
-	reloadCurrentPage(request?: EcoReloadRequest): Promise<boolean>;
-	/** Runs a target runtime's cleanup hook before handoff. */
-	cleanupOwner(owner: EcoNavigationOwner): Promise<void>;
-	/** Runs cleanup for whichever runtime currently owns the document. */
-	cleanupCurrentOwner(): Promise<void>;
-}
-
-/**
- * Reads the explicit browser document owner marker from a rendered HTML document.
- *
- * Documents without a marker return `null`, allowing runtimes to fall back to
- * their local default behavior without scanning hydration scripts.
- */
-export function getEcoDocumentOwner(doc: Document): EcoNavigationOwner | null {
-	const owner = doc.documentElement.getAttribute(ECO_DOCUMENT_OWNER_ATTRIBUTE);
-	return owner && owner.length > 0 ? (owner as EcoNavigationOwner) : null;
-}
-
-type EcoNavigationWindow = Window &
-	typeof globalThis & {
-		__ECO_PAGES__?: {
-			navigation?: EcoNavigationRuntime;
-		};
-	};
-
-function getCandidateOwners(
-	currentOwner: EcoNavigationOwner,
-	registrations: Map<EcoNavigationOwner, EcoNavigationRuntimeRegistration>,
-	excludedOwner?: EcoNavigationOwner,
-): EcoNavigationOwner[] {
-	const owners: EcoNavigationOwner[] = [];
-
-	if (currentOwner !== 'none' && currentOwner !== excludedOwner) {
-		owners.push(currentOwner);
-	}
-
-	for (const owner of registrations.keys()) {
-		if (owner === currentOwner || owner === excludedOwner) {
-			continue;
-		}
-
-		owners.push(owner);
-	}
-
-	return owners;
-}
-
-function createEcoNavigationRuntime(): EcoNavigationRuntime {
-	const registrations = new Map<EcoNavigationOwner, EcoNavigationRuntimeRegistration>();
-	const listeners = new Set<EcoNavigationRuntimeListener>();
-	let owner: EcoNavigationOwner = 'none';
-	let navigationSequence = 0;
-	let navigationAbortController: AbortController | null = null;
-
-	const emit = (event: EcoNavigationRuntimeEvent) => {
-		for (const listener of listeners) {
-			listener(event);
-		}
-	};
-
-	const updateOwner = (
-		nextOwner: EcoNavigationOwner,
-		reason: Extract<EcoNavigationRuntimeEvent, { type: 'owner-change' }>['reason'],
-	) => {
-		if (owner === nextOwner) {
-			return;
-		}
-
-		const previousOwner = owner;
-		owner = nextOwner;
-		emit({
-			type: 'owner-change',
-			owner: nextOwner,
-			previousOwner,
-			reason,
-		});
-	};
-
-	const cancelNavigationTransaction = (navigationId: number, abortController: AbortController): void => {
-		if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
-			return;
-		}
-
-		navigationSequence += 1;
-		navigationAbortController = null;
-		abortController.abort();
-	};
-
-	const completeNavigationTransaction = (navigationId: number, abortController: AbortController): void => {
-		if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
-			return;
-		}
-
-		navigationAbortController = null;
-	};
-
-	const runtime: EcoNavigationRuntime = {
-		getOwnerState(): EcoNavigationOwnerState {
-			const activeRuntime = registrations.get(owner);
-			return {
-				owner,
-				canHandleSpaNavigation: typeof activeRuntime?.navigate === 'function',
-			};
-		},
-
-		hasPendingNavigationTransaction(): boolean {
-			return navigationAbortController !== null;
-		},
-
-		beginNavigationTransaction(): EcoNavigationTransaction {
-			navigationAbortController?.abort();
-			const abortController = new AbortController();
-			const navigationId = ++navigationSequence;
-			navigationAbortController = abortController;
-
-			return {
-				id: navigationId,
-				signal: abortController.signal,
-				isCurrent: () => navigationSequence === navigationId && navigationAbortController === abortController,
-				cancel: () => {
-					cancelNavigationTransaction(navigationId, abortController);
-				},
-				complete: () => {
-					completeNavigationTransaction(navigationId, abortController);
-				},
-			};
-		},
-
-		cancelCurrentNavigationTransaction(): void {
-			if (!navigationAbortController) {
-				return;
-			}
-
-			cancelNavigationTransaction(navigationSequence, navigationAbortController);
-		},
-
-		setOwner(nextOwner: EcoNavigationOwner): void {
-			updateOwner(nextOwner, 'set');
-		},
-
-		claimOwnership(nextOwner: EcoNavigationOwner): void {
-			updateOwner(nextOwner, 'claim');
-		},
-
-		releaseOwnership(currentOwner: EcoNavigationOwner): void {
-			if (owner !== currentOwner) {
-				return;
-			}
-
-			updateOwner('none', 'release');
-		},
-
-		resolveDocumentOwner(doc: Document, fallbackOwner: EcoNavigationOwner = 'none'): EcoNavigationOwner {
-			return getEcoDocumentOwner(doc) ?? fallbackOwner;
-		},
-
-		adoptDocumentOwner(doc: Document, fallbackOwner: EcoNavigationOwner = 'none'): EcoNavigationOwner {
-			const nextOwner = runtime.resolveDocumentOwner(doc, fallbackOwner);
-			updateOwner(nextOwner, 'document');
-			return nextOwner;
-		},
-
-		isOwnedByAnotherRuntime(candidateOwner: EcoNavigationOwner): boolean {
-			return owner !== 'none' && owner !== candidateOwner;
-		},
-
-		subscribe(listener: EcoNavigationRuntimeListener): () => void {
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
-		},
-
-		register(registration: EcoNavigationRuntimeRegistration): () => void {
-			registrations.set(registration.owner, registration);
-			emit({
-				type: 'registration-change',
-				owner: registration.owner,
-				status: 'registered',
-			});
-
-			return () => {
-				const currentRegistration = registrations.get(registration.owner);
-				if (currentRegistration !== registration) {
-					return;
-				}
-
-				registrations.delete(registration.owner);
-				emit({
-					type: 'registration-change',
-					owner: registration.owner,
-					status: 'unregistered',
-				});
-				if (owner === registration.owner) {
-					updateOwner('none', 'unregister');
-				}
-			};
-		},
-
-		async requestNavigation(request: EcoNavigationRequest): Promise<boolean> {
-			for (const candidateOwner of getCandidateOwners(owner, registrations, request.source)) {
-				const registration = registrations.get(candidateOwner);
-				if (!registration?.navigate) {
-					continue;
-				}
-
-				const handled = await registration.navigate(request);
-				if (handled !== false) {
-					return true;
-				}
-			}
-
-			return false;
-		},
-
-		async requestHandoff(request: EcoNavigationHandoffRequest): Promise<boolean> {
-			if (request.targetOwner === 'none') {
-				return false;
-			}
-
-			if (request.isStaleSourceNavigation?.()) {
-				return true;
-			}
-
-			const registration = registrations.get(request.targetOwner);
-			if (!registration?.handoffNavigation) {
-				return false;
-			}
-
-			if (request.isStaleSourceNavigation?.()) {
-				return true;
-			}
-
-			const handled = await registration.handoffNavigation(request);
-			return handled !== false;
-		},
-
-		async reloadCurrentPage(request?: EcoReloadRequest): Promise<boolean> {
-			for (const candidateOwner of getCandidateOwners(owner, registrations)) {
-				const registration = registrations.get(candidateOwner);
-				if (!registration?.reloadCurrentPage) {
-					continue;
-				}
-
-				await registration.reloadCurrentPage(request);
-				return true;
-			}
-
-			return false;
-		},
-
-		async cleanupOwner(targetOwner: EcoNavigationOwner): Promise<void> {
-			if (targetOwner === 'none') {
-				return;
-			}
-
-			const registration = registrations.get(targetOwner);
-			if (!registration?.cleanupBeforeHandoff) {
-				return;
-			}
-
-			await registration.cleanupBeforeHandoff();
-			if (owner === targetOwner) {
-				updateOwner('none', 'release');
-			}
-		},
-
-		async cleanupCurrentOwner(): Promise<void> {
-			await runtime.cleanupOwner(owner);
-		},
-	};
-
-	return runtime;
-}
-
-/**
- * Returns the singleton browser-side navigation coordinator.
- *
- * The coordinator centralizes ownership, handoff, and current-page reload
- * requests across browser runtimes through one internal protocol.
- *
- * @param windowObject - Window-like object that stores the singleton runtime.
- * @returns The shared browser navigation coordinator.
- */
-export function getEcoNavigationRuntime(windowObject: Window & typeof globalThis = window): EcoNavigationRuntime {
-	const runtimeWindow = windowObject as EcoNavigationWindow;
-	runtimeWindow.__ECO_PAGES__ = runtimeWindow.__ECO_PAGES__ || {};
-	if (!runtimeWindow.__ECO_PAGES__.navigation) {
-		runtimeWindow.__ECO_PAGES__.navigation = createEcoNavigationRuntime();
-	}
-
-	return runtimeWindow.__ECO_PAGES__.navigation;
-}

package/src/router/server/fs-router-scanner.test.ts

@@ -1,83 +0,0 @@
-import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { test } from 'vitest';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import { FSRouterScanner } from './fs-router-scanner.ts';
-
-test('FSRouterScanner scans dynamic routes in Node when module graph needs transpilation', async () => {
-	if (typeof Bun !== 'undefined') {
-		// This test expects Node's missing Bun global to trigger Esbuild transpilation. Skip in Bun runner.
-		return;
-	}
-
-	const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecopages-fs-router-scanner-node-'));
-	const pagesDir = path.join(rootDir, 'src', 'pages');
-	const dynamicDir = path.join(pagesDir, 'dynamic');
-	const distDir = path.join(rootDir, 'dist');
-	const workDir = path.join(rootDir, '.eco');
-
-	try {
-		fs.mkdirSync(dynamicDir, { recursive: true });
-		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
-
-		fs.writeFileSync(
-			path.join(rootDir, 'src', 'decorated.ts'),
-			[
-				'function sealed<T extends new (...args: never[]) => object>(target: T) {',
-				'\treturn target;',
-				'}',
-				'@sealed',
-				'export class DecoratedModule {}',
-			].join('\n'),
-		);
-
-		fs.writeFileSync(
-			path.join(dynamicDir, '[slug].kita.tsx'),
-			[
-				"import '../../decorated.ts';",
-				'',
-				'export const getStaticPaths = async () => ({',
-				"\tpaths: [{ params: { slug: 'hello-world' } }],",
-				'});',
-				'',
-				'export const getStaticProps = async () => ({ props: {} });',
-				'',
-				'export default async function Page() {',
-				"\treturn '<div>Hello</div>';",
-				'}',
-			].join('\n'),
-		);
-
-		const scanner = new FSRouterScanner({
-			dir: pagesDir,
-			origin: 'http://localhost:3000',
-			templatesExt: ['.kita.tsx'],
-			options: {
-				buildMode: false,
-			},
-			appConfig: {
-				rootDir,
-				workDir: '.eco',
-				absolutePaths: {
-					distDir,
-					workDir,
-				},
-			} as unknown as EcoPagesAppConfig,
-		});
-
-		const routes = await scanner.scan();
-
-		assert.equal(routes['http://localhost:3000/dynamic/hello-world']?.kind, 'dynamic');
-		assert.equal(routes['http://localhost:3000/dynamic/hello-world']?.pathname, '/dynamic/[slug]');
-
-		const transpiledModulesDir = path.join(workDir, '.server-route-modules');
-		assert.equal(fs.existsSync(transpiledModulesDir), true);
-
-		const transpiledFiles = fs.readdirSync(transpiledModulesDir).filter((file) => file.endsWith('.js'));
-		assert.ok(transpiledFiles.length > 0);
-	} finally {
-		fs.rmSync(rootDir, { recursive: true, force: true });
-	}
-});