@pyreon/router 0.13.1 → 0.15.0

package/lib/index.js

@@ -1,7 +1,9 @@
-import { ErrorBoundary, createContext, createRef, h, onUnmount, provide, useContext } from "@pyreon/core";
+import { ErrorBoundary, createContext, createRef, cx, h, nativeCompat, onUnmount, provide, useContext } from "@pyreon/core";
 import { computed, signal } from "@pyreon/reactivity";
 
 //#region src/loader.ts
+const __DEV__$1 = process.env.NODE_ENV !== "production";
+const _countSink$1 = globalThis;
 /**
 * Context frame that holds the loader data for the currently rendered route record.
 * Pushed by RouterView's withLoaderData wrapper before invoking the route component.
@@ -26,19 +28,27 @@ function useLoaderData() {
 * SSR helper: pre-run all loaders for the given path before rendering.
 * Call this before `renderToString` so route components can read data via `useLoaderData()`.
 *
+* The optional `request` is forwarded to each loader's `LoaderContext.request`,
+* letting server-side loaders read cookies / auth headers and `throw redirect()`
+* before the layout renders. A loader that throws `redirect()` propagates the
+* thrown error here — the SSR handler's `catch` converts it into a 302/307
+* `Location:` Response.
+*
 * @example
 * const router = createRouter({ routes, url: req.url })
-* await prefetchLoaderData(router, req.url)
+* await prefetchLoaderData(router, req.url, request)
 * const html = await renderToString(h(App, { router }))
 */
-async function prefetchLoaderData(router, path) {
+async function prefetchLoaderData(router, path, request) {
+	if (__DEV__$1) _countSink$1.__pyreon_count__?.("router.prefetch");
 	const route = router._resolve(path);
 	const ac = new AbortController();
 	await Promise.all(route.matched.filter((r) => r.loader).map(async (r) => {
 		const data = await r.loader?.({
 			params: route.params,
 			query: route.query,
-			signal: ac.signal
+			signal: ac.signal,
+			...request ? { request } : {}
 		});
 		router._loaderData.set(r, data);
 	}));
@@ -84,17 +94,21 @@ function hydrateLoaderData(router, serialized) {
 * Parse a query string into key-value pairs. Duplicate keys are overwritten
 * (last value wins). Use `parseQueryMulti` to preserve duplicates as arrays.
 */
+/** Decode a query component: `+` → space (per application/x-www-form-urlencoded), then URI-decode. */
+function decodeQueryComponent(raw) {
+	return decodeURIComponent(raw.replace(/\+/g, " "));
+}
 function parseQuery(qs) {
 	if (!qs) return {};
 	const result = {};
 	for (const part of qs.split("&")) {
 		const eqIdx = part.indexOf("=");
 		if (eqIdx < 0) {
-			const key = decodeURIComponent(part);
+			const key = decodeQueryComponent(part);
 			if (key) result[key] = "";
 		} else {
-			const key = decodeURIComponent(part.slice(0, eqIdx));
-			const val = decodeURIComponent(part.slice(eqIdx + 1));
+			const key = decodeQueryComponent(part.slice(0, eqIdx));
+			const val = decodeQueryComponent(part.slice(eqIdx + 1));
 			if (key) result[key] = val;
 		}
 	}
@@ -115,11 +129,11 @@ function parseQueryMulti(qs) {
 		let key;
 		let val;
 		if (eqIdx < 0) {
-			key = decodeURIComponent(part);
+			key = decodeQueryComponent(part);
 			val = "";
 		} else {
-			key = decodeURIComponent(part.slice(0, eqIdx));
-			val = decodeURIComponent(part.slice(eqIdx + 1));
+			key = decodeQueryComponent(part.slice(0, eqIdx));
+			val = decodeQueryComponent(part.slice(eqIdx + 1));
 		}
 		if (!key) continue;
 		const existing = result[key];
@@ -268,7 +282,8 @@ function flattenOne(result, c, parentSegments, chain, meta) {
 		if (c.children && c.children.length > 0) flattenWalk(result, c.children, parentSegments, chain, meta);
 		return;
 	}
-	const joined = [...parentSegments, ...c.segments];
+	const childPath = c.route.path;
+	const joined = typeof childPath === "string" && childPath.startsWith("/") ? c.segments : [...parentSegments, ...c.segments];
 	if (c.children && c.children.length > 0) flattenWalk(result, c.children, joined, chain, meta);
 	result.push(makeFlatEntry(joined, chain, meta, false));
 }
@@ -398,7 +413,8 @@ function resolveRoute(rawPath, routes) {
 		query,
 		hash,
 		matched: staticMatch.matchedChain,
-		meta: staticMatch.meta
+		meta: staticMatch.meta,
+		search: runValidateSearch(staticMatch.matchedChain, query)
 	};
 	const pathParts = splitPath(cleanPath);
 	const pathLen = pathParts.length;
@@ -413,7 +429,8 @@ function resolveRoute(rawPath, routes) {
 				query,
 				hash,
 				matched: match.matched,
-				meta: mergeMeta(match.matched)
+				meta: mergeMeta(match.matched),
+				search: runValidateSearch(match.matched, query)
 			};
 		}
 	}
@@ -424,7 +441,8 @@ function resolveRoute(rawPath, routes) {
 		query,
 		hash,
 		matched: dynMatch.matched,
-		meta: mergeMeta(dynMatch.matched)
+		meta: mergeMeta(dynMatch.matched),
+		search: runValidateSearch(dynMatch.matched, query)
 	};
 	const w = index.wildcards[0];
 	if (w) return {
@@ -433,7 +451,8 @@ function resolveRoute(rawPath, routes) {
 		query,
 		hash,
 		matched: w.matchedChain,
-		meta: w.meta
+		meta: w.meta,
+		search: runValidateSearch(w.matchedChain, query)
 	};
 	return {
 		path: cleanPath,
@@ -441,9 +460,22 @@ function resolveRoute(rawPath, routes) {
 		query,
 		hash,
 		matched: [],
-		meta: {}
+		meta: {},
+		search: {}
 	};
 }
+/** Run validateSearch from the deepest matched route that has one. */
+function runValidateSearch(matched, query) {
+	for (let i = matched.length - 1; i >= 0; i--) {
+		const validate = matched[i]?.validateSearch;
+		if (validate) try {
+			return validate(query);
+		} catch {
+			return { ...query };
+		}
+	}
+	return {};
+}
 /** Merge meta from matched routes (leaf takes precedence) */
 function mergeMeta(matched) {
 	const meta = {};
@@ -489,6 +521,58 @@ function buildNameIndex(routes) {
 	return index;
 }
 
+//#endregion
+//#region src/redirect.ts
+const REDIRECT = Symbol.for("pyreon.redirect");
+/**
+* Throw inside a route loader to redirect the navigation server-side
+* (during SSR returns a 302/307 `Location:` response) and client-side
+* (during CSR triggers `router.replace()` before the layout renders).
+*
+* The auth-gate use case: replaces the fragile `onMount + router.push()`
+* workaround. `onMount` doesn't fire reliably under nested-layout dev SSR +
+* hydration — so the layout renders briefly before the push happens, leaking
+* authenticated UI to unauthenticated users. `redirect()` runs in the loader
+* BEFORE the layout's component is invoked, so the unauthenticated UI never
+* mounts in the first place.
+*
+* @example
+* ```ts
+* // src/routes/app/_layout.tsx
+* export const loader = async ({ request }) => {
+*   const session = await getSession(request)
+*   if (!session) redirect('/login')
+*   return { user: session.user }
+* }
+* ```
+*
+* @param url - Target URL (typically a path like `/login` or absolute URL for cross-origin).
+* @param status - HTTP redirect status. Default `307` (Temporary Redirect, method-preserving).
+*   Use `301`/`308` for permanent moves, `302`/`303` to force GET on the target.
+*/
+function redirect(url, status = 307) {
+	const err = /* @__PURE__ */ new Error(`Redirect to ${url}`);
+	err[REDIRECT] = {
+		url,
+		status
+	};
+	throw err;
+}
+/** Check if an error is a RedirectError thrown by `redirect()`. */
+function isRedirectError(err) {
+	return typeof err === "object" && err !== null && typeof err[REDIRECT] === "object";
+}
+/**
+* Extract the redirect URL and status from a thrown RedirectError. Returns
+* `null` if `err` isn't a RedirectError. Used by the router's loader-runner
+* (CSR) and the SSR handler to convert the thrown error into the right kind
+* of response (a `router.replace()` call or a `302`/`307` Response).
+*/
+function getRedirectInfo(err) {
+	if (!isRedirectError(err)) return null;
+	return err[REDIRECT] ?? null;
+}
+
 //#endregion
 //#region src/scroll.ts
 /**
@@ -587,7 +671,8 @@ function isLazy(c) {
 //#endregion
 //#region src/router.ts
 const _isBrowser = typeof window !== "undefined";
-const __DEV__ = import.meta.env?.DEV === true;
+const __DEV__ = process.env.NODE_ENV !== "production";
+const _countSink = globalThis;
 const RouterContext = createContext(null);
 let _activeRouter = null;
 function setActiveRouter(router) {
@@ -806,8 +891,10 @@ function useTypedSearchParams(schema) {
 		const result = {};
 		for (const [key, type] of Object.entries(schema)) {
 			const raw = query[key];
-			if (type === "number") result[key] = raw !== void 0 ? Number(raw) : 0;
-			else if (type === "boolean") result[key] = raw === "true" || raw === "1";
+			if (type === "number") {
+				const n = raw !== void 0 ? Number(raw) : 0;
+				result[key] = Number.isNaN(n) ? 0 : n;
+			} else if (type === "boolean") result[key] = raw === "true" || raw === "1";
 			else result[key] = raw ?? "";
 		}
 		return result;
@@ -824,6 +911,44 @@ function useTypedSearchParams(schema) {
 	};
 	return [get, set];
 }
+/**
+* Read the validated search params from the current route's `validateSearch`.
+* Returns a reactive accessor that re-evaluates when the route changes.
+*
+* The generic `T` should match the return type of your `validateSearch` function.
+*
+* @example
+* ```tsx
+* // Route config:
+* { path: '/search', validateSearch: (raw) => ({
+*   page: Number(raw.page) || 1,
+*   q: raw.q ?? '',
+* }), component: SearchPage }
+*
+* // In SearchPage:
+* const search = useValidatedSearch<{ page: number; q: string }>()
+* // search().page — typed as number
+* // search().q — typed as string
+* ```
+*/
+function useValidatedSearch() {
+	const router = _getRouter();
+	let prev = null;
+	return () => {
+		const next = router.currentRoute().search;
+		if (prev && shallowEqual(prev, next)) return prev;
+		prev = next;
+		return next;
+	};
+}
+/** Shallow equality check for plain objects — keys + strict value comparison. */
+function shallowEqual(a, b) {
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) if (a[key] !== b[key]) return false;
+	return true;
+}
 function _getRouter() {
 	const router = useContext(RouterContext) ?? _activeRouter;
 	if (!router) throw new Error("[Pyreon] No router installed. Wrap your app in <RouterProvider router={router}>.");
@@ -927,14 +1052,19 @@ function createRouter(options) {
 	function processLoaderResult(result, record, ac, to) {
 		if (result.status === "fulfilled") {
 			router._loaderData.set(record, result.value);
-			return true;
+			return { action: "continue" };
 		}
-		if (ac.signal.aborted) return true;
+		if (ac.signal.aborted) return { action: "continue" };
+		const info = getRedirectInfo(result.reason);
+		if (info) return {
+			action: "redirect",
+			target: info.url
+		};
 		if (router._onError) {
-			if (router._onError(result.reason, to) === false) return false;
+			if (router._onError(result.reason, to) === false) return { action: "cancel" };
 		}
 		router._loaderData.set(record, void 0);
-		return true;
+		return { action: "continue" };
 	}
 	function syncBrowserUrl(path, replace) {
 		if (!_isBrowser) return;
@@ -954,21 +1084,89 @@ function createRouter(options) {
 		if (enterOutcome.action !== "continue") return enterOutcome;
 		return runGlobalGuards(guards, to, from, gen);
 	}
+	/** Default cache key: path + serialized params */
+	function defaultLoaderKey(record, ctx) {
+		return `${record.path}:${JSON.stringify(ctx.params)}`;
+	}
+	/** Get cache key for a route record + context. */
+	function getCacheKey(record, ctx) {
+		return record.loaderKey ? record.loaderKey(ctx) : defaultLoaderKey(record, ctx);
+	}
+	/** Check if a cached entry is still fresh (not expired by gcTime). */
+	function isCacheFresh(entry, record) {
+		const gcTime = record.gcTime ?? 3e5;
+		if (gcTime === 0) return false;
+		return Date.now() - entry.timestamp < gcTime;
+	}
+	/**
+	* Bounded set into `_loaderCache`: evicts the oldest entry (insertion-order
+	* FIFO) when the cap is exceeded. The `gcTime` TTL handles staleness, but
+	* without a size cap a long-running SPA navigating across many distinct
+	* loader keys (e.g. `/posts/:id` with hundreds of unique IDs) would
+	* accumulate cache entries indefinitely until manual `invalidateLoader()`
+	* — `_maxCacheSize` was wired through from `RouterOptions.maxCacheSize`
+	* (default 100) but the loader cache write paths never read it. Mirrors
+	* the same pattern used for `_componentCache` in `components.tsx`.
+	*/
+	function loaderCacheSet(key, data) {
+		router._loaderCache.set(key, {
+			data,
+			timestamp: Date.now()
+		});
+		if (router._loaderCache.size > router._maxCacheSize) {
+			const oldest = router._loaderCache.keys().next().value;
+			if (oldest !== void 0) router._loaderCache.delete(oldest);
+		}
+	}
+	/**
+	* Execute a loader with cache + dedup:
+	* 1. Cache hit + fresh → return cached data (skip loader entirely)
+	* 2. In-flight for same key → dedup (return existing promise)
+	* 3. Otherwise → run loader, cache result, clean up in-flight
+	*/
+	function executeLoader(record, loaderCtx) {
+		if (!record.loader) return Promise.resolve(void 0);
+		const key = getCacheKey(record, loaderCtx);
+		if (!record.staleWhileRevalidate) {
+			const cached = router._loaderCache.get(key);
+			if (cached && isCacheFresh(cached, record)) {
+				if (__DEV__) _countSink.__pyreon_count__?.("router.loaderCache.hit");
+				return Promise.resolve(cached.data);
+			}
+		}
+		const inflight = router._loaderInflight.get(key);
+		if (inflight && !inflight.signal.aborted) return inflight.promise;
+		if (__DEV__) _countSink.__pyreon_count__?.("router.loaderRun");
+		const promise = Promise.resolve().then(() => record.loader(loaderCtx)).then((data) => {
+			loaderCacheSet(key, data);
+			if (router._loaderInflight.get(key)?.promise === promise) router._loaderInflight.delete(key);
+			return data;
+		}).catch((err) => {
+			if (router._loaderInflight.get(key)?.promise === promise) router._loaderInflight.delete(key);
+			throw err;
+		});
+		router._loaderInflight.set(key, {
+			promise,
+			signal: loaderCtx.signal
+		});
+		return promise;
+	}
 	async function runBlockingLoaders(records, to, gen, ac) {
 		const loaderCtx = {
 			params: to.params,
 			query: to.query,
 			signal: ac.signal
 		};
-		const results = await Promise.allSettled(records.map((r) => r.loader ? r.loader(loaderCtx) : Promise.resolve(void 0)));
-		if (gen !== _navGen) return false;
+		const results = await Promise.allSettled(records.map((r) => executeLoader(r, loaderCtx)));
+		if (gen !== _navGen) return { action: "cancel" };
 		for (let i = 0; i < records.length; i++) {
 			const result = results[i];
 			const record = records[i];
 			if (!result || !record) continue;
-			if (!processLoaderResult(result, record, ac, to)) return false;
+			const outcome = processLoaderResult(result, record, ac, to);
+			if (outcome.action !== "continue") return outcome;
 		}
-		return true;
+		return { action: "continue" };
 	}
 	/** Fire-and-forget background revalidation for stale-while-revalidate routes. */
 	function revalidateSwrLoaders(records, to, ac) {
@@ -982,6 +1180,7 @@ function createRouter(options) {
 			r.loader(loaderCtx).then((data) => {
 				if (!ac.signal.aborted) {
 					router._loaderData.set(r, data);
+					loaderCacheSet(getCacheKey(r, loaderCtx), data);
 					loadingSignal.update((n) => n + 1);
 					loadingSignal.update((n) => n - 1);
 				}
@@ -990,16 +1189,17 @@ function createRouter(options) {
 	}
 	async function runLoaders(to, gen, ac) {
 		const loadableRecords = to.matched.filter((r) => r.loader);
-		if (loadableRecords.length === 0) return true;
+		if (loadableRecords.length === 0) return { action: "continue" };
 		const blocking = [];
 		const swr = [];
 		for (const r of loadableRecords) if (r.staleWhileRevalidate && router._loaderData.has(r)) swr.push(r);
 		else blocking.push(r);
 		if (blocking.length > 0) {
-			if (!await runBlockingLoaders(blocking, to, gen, ac)) return false;
+			const outcome = await runBlockingLoaders(blocking, to, gen, ac);
+			if (outcome.action !== "continue") return outcome;
 		}
 		if (swr.length > 0) revalidateSwrLoaders(swr, to, ac);
-		return true;
+		return { action: "continue" };
 	}
 	async function commitNavigation(path, replace, to, from) {
 		scrollManager.save(from.path);
@@ -1059,6 +1259,8 @@ function createRouter(options) {
 		return { action: "continue" };
 	}
 	async function navigate(rawPath, replace, redirectDepth = 0) {
+		if (__DEV__) _countSink.__pyreon_count__?.("router.navigate");
+		router._navigationStartTime = Date.now();
 		if (redirectDepth > 10) {
 			if (__DEV__) console.warn(`[Pyreon] Navigation to "${rawPath}" aborted: redirect depth exceeded 10 levels. This likely indicates a redirect loop in your route configuration.`);
 			return;
@@ -1092,8 +1294,10 @@ function createRouter(options) {
 		router._abortController?.abort();
 		const ac = new AbortController();
 		router._abortController = ac;
-		if (!await runLoaders(to, gen, ac)) {
+		const loaderOutcome = await runLoaders(to, gen, ac);
+		if (loaderOutcome.action !== "continue") {
 			loadingSignal.update((n) => n - 1);
+			if (loaderOutcome.action === "redirect") return navigate(sanitizePath(loaderOutcome.target), replace, redirectDepth + 1);
 			return;
 		}
 		await commitNavigation(path, replace, to, from);
@@ -1123,6 +1327,9 @@ function createRouter(options) {
 		_readyPromise,
 		_onError: onError,
 		_maxCacheSize: maxCacheSize,
+		_navigationStartTime: Date.now(),
+		_loaderCache: /* @__PURE__ */ new Map(),
+		_loaderInflight: /* @__PURE__ */ new Map(),
 		async push(location) {
 			if (typeof location === "string") return navigate(sanitizePath(resolveRelativePath(location, currentPath())), false);
 			return navigate(resolveNamedPath(location.name, location.params ?? {}, location.query ?? {}, nameIndex), false);
@@ -1158,7 +1365,7 @@ function createRouter(options) {
 		isReady() {
 			return router._readyPromise;
 		},
-		async preload(path) {
+		async preload(path, request) {
 			const resolved = resolveRoute(path, routes);
 			await Promise.all(resolved.matched.map(async (record) => {
 				if (componentCache.has(record)) return;
@@ -1173,14 +1380,31 @@ function createRouter(options) {
 			}));
 			const ac = new AbortController();
 			await Promise.all(resolved.matched.filter((r) => r.loader).map(async (r) => {
-				const data = await r.loader?.({
+				const data = await Promise.resolve().then(() => r.loader({
 					params: resolved.params,
 					query: resolved.query,
-					signal: ac.signal
-				});
+					signal: ac.signal,
+					...request ? { request } : {}
+				}));
 				router._loaderData.set(r, data);
 			}));
 		},
+		invalidateLoader(keyOrPredicate) {
+			if (!keyOrPredicate) {
+				router._loaderCache.clear();
+				router._loaderInflight.clear();
+				return;
+			}
+			if (typeof keyOrPredicate === "string") {
+				router._loaderCache.delete(keyOrPredicate);
+				router._loaderInflight.delete(keyOrPredicate);
+				return;
+			}
+			for (const key of [...router._loaderCache.keys()]) if (keyOrPredicate(key)) {
+				router._loaderCache.delete(key);
+				router._loaderInflight.delete(key);
+			}
+		},
 		destroy() {
 			if (_popstateHandler) window.removeEventListener("popstate", _popstateHandler);
 			if (_hashchangeHandler) window.removeEventListener("hashchange", _hashchangeHandler);
@@ -1190,6 +1414,8 @@ function createRouter(options) {
 			router._blockers.clear();
 			componentCache.clear();
 			router._loaderData.clear();
+			router._loaderCache.clear();
+			router._loaderInflight.clear();
 			router._abortController?.abort();
 			router._abortController = null;
 			if (_activeRouter === router) _activeRouter = null;
@@ -1214,7 +1440,10 @@ async function runGuard(guard, to, from) {
 }
 function resolveNamedPath(name, params, query, index) {
 	const record = index.get(name);
-	if (!record) return "/";
+	if (!record) {
+		if (__DEV__) console.warn(`[Pyreon Router] Unknown route name "${name}". Available names: ${[...index.keys()].join(", ") || "(none)"}. Falling back to "/".`);
+		return "/";
+	}
 	let path = buildPath(record.path, params);
 	const qs = Object.entries(query).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
 	if (qs) path += `?${qs}`;
@@ -1311,38 +1540,81 @@ const RouterView = (props) => {
 	onUnmount(() => {
 		router._viewDepth--;
 	});
-	const child = () => {
-		router._loadingSignal();
+	const depthEntry = computed(() => {
 		const route = router.currentRoute();
-		if (route.matched.length === 0) return null;
-		const record = route.matched[depth];
-		if (!record) return null;
-		const cached = router._componentCache.get(record);
-		if (cached) return renderWithLoader(router, record, cached, route);
-		const raw = record.component;
+		const rec = route.matched[depth] ?? null;
+		if (!rec) return {
+			rec: null,
+			comp: null,
+			errored: false,
+			route
+		};
+		router._loadingSignal();
+		if (router._erroredChunks.has(rec)) return {
+			rec,
+			comp: null,
+			errored: true,
+			route
+		};
+		const cached = router._componentCache.get(rec);
+		if (cached) return {
+			rec,
+			comp: cached,
+			errored: false,
+			route
+		};
+		const raw = rec.component;
 		if (!isLazy(raw)) {
-			cacheSet(router, record, raw);
-			return renderWithLoader(router, record, raw, route);
+			cacheSet(router, rec, raw);
+			return {
+				rec,
+				comp: raw,
+				errored: false,
+				route
+			};
 		}
-		return renderLazyRoute(router, record, raw);
+		return {
+			rec,
+			comp: null,
+			errored: false,
+			route
+		};
+	}, { equals: (a, b) => a.rec === b.rec && a.comp === b.comp && a.errored === b.errored && a.route === b.route });
+	const child = () => {
+		const { rec, comp, route } = depthEntry();
+		if (!rec) return null;
+		if (comp) return renderWithLoader(router, rec, comp, route);
+		return renderLazyRoute(router, rec, rec.component);
 	};
 	return h("div", { "data-pyreon-router-view": true }, child);
 };
 const RouterLink = (props) => {
 	const router = useContext(RouterContext);
-	const prefetchMode = props.prefetch ?? "hover";
+	const prefetchMode = props.prefetch ?? "intent";
 	const handleClick = (e) => {
 		e.preventDefault();
 		if (!router) return;
 		if (props.replace) router.replace(props.to);
 		else router.push(props.to);
 	};
-	const handleMouseEnter = () => {
-		if (prefetchMode !== "hover" || !router) return;
+	const triggerPrefetch = () => {
+		if (!router) return;
 		prefetchRoute(router, props.to);
 	};
+	const handleMouseEnter = () => {
+		if (prefetchMode === "hover" || prefetchMode === "intent") triggerPrefetch();
+	};
+	const handleFocus = () => {
+		if (prefetchMode === "intent") triggerPrefetch();
+	};
 	const inst = router;
-	const href = inst?.mode === "history" ? `${inst._base}${props.to}` : `#${props.to}`;
+	const href = () => inst?.mode === "history" ? `${inst._base}${props.to}` : `#${props.to}`;
+	const isExactMatch = () => {
+		if (!router) return false;
+		const target = props.to;
+		if (typeof target !== "string") return false;
+		return router.currentRoute().path === target;
+	};
 	const activeClass = () => {
 		if (!router) return "";
 		const current = router.currentRoute().path;
@@ -1355,6 +1627,7 @@ const RouterLink = (props) => {
 		if (isExact) classes.push(props.exactActiveClass ?? "router-link-exact-active");
 		return classes.join(" ").trim();
 	};
+	const ariaCurrent = () => isExactMatch() ? "page" : void 0;
 	const ref = createRef();
 	if (prefetchMode === "viewport" && router && typeof IntersectionObserver !== "undefined") {
 		const observer = new IntersectionObserver((entries) => {
@@ -1369,17 +1642,23 @@ const RouterLink = (props) => {
 		});
 		onUnmount(() => observer.disconnect());
 	}
-	const { to: _to, replace: _replace, activeClass: _ac, exactActiveClass: _eac, exact: _exact, prefetch: _prefetch, children, ...rest } = props;
+	const { to: _to, replace: _replace, activeClass: _ac, exactActiveClass: _eac, exact: _exact, prefetch: _prefetch, class: userClass, children, ...rest } = props;
+	const mergedClass = () => {
+		return cx([typeof userClass === "function" ? userClass() : userClass, activeClass()]);
+	};
 	return h("a", {
 		...rest,
 		ref,
 		href,
-		class: activeClass,
+		class: mergedClass,
+		"aria-current": ariaCurrent,
 		onClick: handleClick,
-		onMouseEnter: handleMouseEnter
+		onMouseEnter: handleMouseEnter,
+		onFocus: handleFocus
 	}, children ?? props.to);
 };
 /** Prefetch loader data for a route (only once per router + path). */
+const MAX_PREFETCH_CACHE = 50;
 function prefetchRoute(router, path) {
 	let set = _prefetched.get(router);
 	if (!set) {
@@ -1387,6 +1666,10 @@ function prefetchRoute(router, path) {
 		_prefetched.set(router, set);
 	}
 	if (set.has(path)) return;
+	if (set.size >= MAX_PREFETCH_CACHE) {
+		const first = set.values().next().value;
+		set.delete(first);
+	}
 	set.add(path);
 	prefetchLoaderData(router, path).catch(() => {
 		set?.delete(path);
@@ -1431,13 +1714,88 @@ function renderWithLoader(router, record, Comp, route) {
 }
 function renderLoaderContent(router, record, Comp, routeProps) {
 	const data = router._loaderData.get(record);
-	if (data === void 0 && record.errorComponent) return h(record.errorComponent, routeProps);
+	if (data !== void 0) return h(LoaderDataProvider, {
+		data,
+		children: h(Comp, routeProps)
+	});
+	if (record.pendingComponent) return h(PendingLoader, {
+		router,
+		record,
+		Comp,
+		routeProps
+	});
+	if (record.errorComponent) return h(record.errorComponent, routeProps);
 	return h(LoaderDataProvider, {
 		data,
 		children: h(Comp, routeProps)
 	});
 }
 /**
+* Signal-based pending component with timing control.
+*
+* State machine: hidden → pending → ready
+* - hidden: initial state, nothing shown (lasts pendingMs)
+* - pending: pendingComponent shown (lasts at least pendingMinMs)
+* - ready: real component shown (loader data arrived + minTime elapsed)
+*/
+function PendingLoader(props) {
+	const { router, record, Comp, routeProps } = props;
+	const pendingMs = record.pendingMs ?? 0;
+	const pendingMinMs = record.pendingMinMs ?? 200;
+	const phase = signal(pendingMs === 0 ? "pending" : "hidden");
+	let pendingTimer = null;
+	let minTimer = null;
+	let minTimeElapsed = pendingMs === 0 ? false : true;
+	let dataReady = false;
+	if (pendingMs === 0) {
+		minTimeElapsed = false;
+		minTimer = setTimeout(() => {
+			minTimeElapsed = true;
+			minTimer = null;
+			if (dataReady) phase.set("ready");
+		}, pendingMinMs);
+	} else pendingTimer = setTimeout(() => {
+		pendingTimer = null;
+		if (dataReady) phase.set("ready");
+		else {
+			phase.set("pending");
+			minTimeElapsed = false;
+			minTimer = setTimeout(() => {
+				minTimeElapsed = true;
+				minTimer = null;
+				if (dataReady) phase.set("ready");
+			}, pendingMinMs);
+		}
+	}, pendingMs);
+	const checkData = () => {
+		if (router._loaderData.get(record) !== void 0) {
+			dataReady = true;
+			if (phase.peek() === "hidden") {
+				if (pendingTimer) {
+					clearTimeout(pendingTimer);
+					pendingTimer = null;
+				}
+				phase.set("ready");
+			} else if (minTimeElapsed) phase.set("ready");
+		}
+	};
+	onUnmount(() => {
+		if (pendingTimer) clearTimeout(pendingTimer);
+		if (minTimer) clearTimeout(minTimer);
+	});
+	return (() => {
+		router._loadingSignal();
+		checkData();
+		const p = phase();
+		if (p === "hidden") return null;
+		if (p === "pending") return h(record.pendingComponent, routeProps);
+		return h(LoaderDataProvider, {
+			data: router._loaderData.get(record),
+			children: h(Comp, routeProps)
+		});
+	});
+}
+/**
 * Thin provider component that pushes LoaderDataContext before children mount.
 * Uses Pyreon's context stack so useLoaderData() reads it during child setup.
 */
@@ -1474,7 +1832,60 @@ function isStaleChunk(err) {
 	if (err instanceof SyntaxError) return true;
 	return false;
 }
+nativeCompat(RouterProvider);
+nativeCompat(RouterView);
+nativeCompat(RouterLink);
+
+//#endregion
+//#region src/not-found.ts
+const NOT_FOUND = Symbol.for("pyreon.notFound");
+/**
+* Throw inside a route loader or component to trigger the nearest
+* NotFoundBoundary. Inspired by Next.js's `notFound()`.
+*
+* @example
+* ```ts
+* // In a loader:
+* loader: async ({ params }) => {
+*   const user = await fetchUser(params.id)
+*   if (!user) notFound()
+*   return user
+* }
+* ```
+*/
+function notFound(message) {
+	const err = new Error(message ?? "Not Found");
+	err[NOT_FOUND] = true;
+	throw err;
+}
+/** Check if an error is a NotFoundError thrown by `notFound()`. */
+function isNotFoundError(err) {
+	return typeof err === "object" && err !== null && err[NOT_FOUND] === true;
+}
+/**
+* Catches `notFound()` errors from child route components or loaders
+* and renders the fallback. Wraps Pyreon's ErrorBoundary with notFound
+* detection — non-notFound errors propagate to parent error boundaries.
+*
+* @example
+* ```tsx
+* <NotFoundBoundary fallback={<NotFoundPage />}>
+*   <RouterView />
+* </NotFoundBoundary>
+* ```
+*/
+const NotFoundBoundary = (props) => {
+	return h(ErrorBoundary, { fallback: (err, reset) => {
+		if (!isNotFoundError(err)) throw err;
+		const fb = props.fallback;
+		if (typeof fb === "function" && fb.length <= 1) return h(fb, {
+			error: err,
+			reset
+		});
+		return fb;
+	} }, props.children);
+};
 
 //#endregion
-export { RouterContext, RouterLink, RouterProvider, RouterView, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams };
+export { NotFoundBoundary, RouterContext, RouterLink, RouterProvider, RouterView, buildPath, createRouter, findRouteByName, getRedirectInfo, hydrateLoaderData, isNotFoundError, isRedirectError, lazy, notFound, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, redirect, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams, useValidatedSearch };
 //# sourceMappingURL=index.js.map