@pyreon/router 0.13.1 → 0.14.0

package/README.md

@@ -13,9 +13,10 @@ bun add @pyreon/router
 ```tsx
 import { createRouter, RouterProvider, RouterView, RouterLink } from '@pyreon/router'
 
-const router = createRouter({
+// Type-safe named navigation — route names are checked at compile time
+const router = createRouter<'home' | 'user'>({
   routes: [
-    { path: '/', component: Home },
+    { path: '/', component: Home, name: 'home' },
     { path: '/user/:id', component: UserPage, name: 'user' },
     {
       path: '/admin',
@@ -112,3 +113,73 @@ Route changes are wrapped in `document.startViewTransition()` automatically when
 | `finished` | Full animation completed | no -- `.catch()` only |
 
 `afterEach` hooks and scroll restoration fire after the VT callback completes, so they observe the new route state when invoked.
+
+## notFound()
+
+Throw `notFound()` in a loader or component to render a 404 boundary:
+
+```tsx
+import { notFound, NotFoundBoundary, RouterView } from '@pyreon/router'
+
+// Route loader:
+{ path: '/user/:id', component: UserPage, loader: async ({ params }) => {
+  const user = await fetchUser(params.id)
+  if (!user) notFound()
+  return user
+}}
+
+// App layout:
+<NotFoundBoundary fallback={<NotFoundPage />}>
+  <RouterView />
+</NotFoundBoundary>
+```
+
+## Pending Components
+
+Show a skeleton while route loaders run:
+
+```ts
+{
+  path: '/dashboard',
+  component: Dashboard,
+  loader: fetchDashboardData,
+  pendingComponent: DashboardSkeleton,
+  pendingMs: 200,     // delay before showing skeleton (avoid flash)
+  pendingMinMs: 500,  // minimum display time (avoid flicker)
+}
+```
+
+## Validated Search Params
+
+Type-safe query string validation per route — works with Zod, Valibot, or plain functions:
+
+```ts
+import { useValidatedSearch } from '@pyreon/router'
+
+// Route config:
+{
+  path: '/search',
+  component: SearchPage,
+  validateSearch: (raw) => ({
+    page: Number(raw.page) || 1,
+    q: raw.q ?? '',
+  }),
+}
+
+// With Zod:
+{
+  path: '/search',
+  component: SearchPage,
+  validateSearch: z.object({
+    page: z.coerce.number().default(1),
+    q: z.string().default(''),
+  }).parse,
+}
+
+// In component:
+const search = useValidatedSearch<{ page: number; q: string }>()
+search().page // number — typed + validated
+search().q    // string — typed + validated
+```
+
+Structural sharing: `useValidatedSearch()` returns the same object reference when the validated values haven't changed, preventing unnecessary downstream re-renders.

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"aa1c31e3-1","name":"loader.ts"},{"uid":"aa1c31e3-3","name":"match.ts"},{"uid":"aa1c31e3-5","name":"scroll.ts"},{"uid":"aa1c31e3-7","name":"types.ts"},{"uid":"aa1c31e3-9","name":"router.ts"},{"uid":"aa1c31e3-11","name":"components.tsx"},{"uid":"aa1c31e3-13","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"aa1c31e3-1":{"renderedLength":2824,"gzipLength":1233,"brotliLength":0,"metaUid":"aa1c31e3-0"},"aa1c31e3-3":{"renderedLength":12203,"gzipLength":3691,"brotliLength":0,"metaUid":"aa1c31e3-2"},"aa1c31e3-5":{"renderedLength":2194,"gzipLength":899,"brotliLength":0,"metaUid":"aa1c31e3-4"},"aa1c31e3-7":{"renderedLength":385,"gzipLength":246,"brotliLength":0,"metaUid":"aa1c31e3-6"},"aa1c31e3-9":{"renderedLength":23568,"gzipLength":6469,"brotliLength":0,"metaUid":"aa1c31e3-8"},"aa1c31e3-11":{"renderedLength":7151,"gzipLength":2635,"brotliLength":0,"metaUid":"aa1c31e3-10"},"aa1c31e3-13":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"aa1c31e3-12"}},"nodeMetas":{"aa1c31e3-0":{"id":"/src/loader.ts","moduleParts":{"index.js":"aa1c31e3-1"},"imported":[{"uid":"aa1c31e3-14"}],"importedBy":[{"uid":"aa1c31e3-12"},{"uid":"aa1c31e3-10"}]},"aa1c31e3-2":{"id":"/src/match.ts","moduleParts":{"index.js":"aa1c31e3-3"},"imported":[],"importedBy":[{"uid":"aa1c31e3-12"},{"uid":"aa1c31e3-8"}]},"aa1c31e3-4":{"id":"/src/scroll.ts","moduleParts":{"index.js":"aa1c31e3-5"},"imported":[],"importedBy":[{"uid":"aa1c31e3-8"}]},"aa1c31e3-6":{"id":"/src/types.ts","moduleParts":{"index.js":"aa1c31e3-7"},"imported":[],"importedBy":[{"uid":"aa1c31e3-12"},{"uid":"aa1c31e3-8"}]},"aa1c31e3-8":{"id":"/src/router.ts","moduleParts":{"index.js":"aa1c31e3-9"},"imported":[{"uid":"aa1c31e3-14"},{"uid":"aa1c31e3-15"},{"uid":"aa1c31e3-2"},{"uid":"aa1c31e3-4"},{"uid":"aa1c31e3-6"}],"importedBy":[{"uid":"aa1c31e3-12"},{"uid":"aa1c31e3-10"}]},"aa1c31e3-10":{"id":"/src/components.tsx","moduleParts":{"index.js":"aa1c31e3-11"},"imported":[{"uid":"aa1c31e3-14"},{"uid":"aa1c31e3-0"},{"uid":"aa1c31e3-8"}],"importedBy":[{"uid":"aa1c31e3-12"}]},"aa1c31e3-12":{"id":"/src/index.ts","moduleParts":{"index.js":"aa1c31e3-13"},"imported":[{"uid":"aa1c31e3-10"},{"uid":"aa1c31e3-0"},{"uid":"aa1c31e3-2"},{"uid":"aa1c31e3-8"},{"uid":"aa1c31e3-6"}],"importedBy":[],"isEntry":true},"aa1c31e3-14":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"aa1c31e3-10"},{"uid":"aa1c31e3-0"},{"uid":"aa1c31e3-8"}]},"aa1c31e3-15":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"aa1c31e3-8"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"007eb862-1","name":"loader.ts"},{"uid":"007eb862-3","name":"match.ts"},{"uid":"007eb862-5","name":"scroll.ts"},{"uid":"007eb862-7","name":"types.ts"},{"uid":"007eb862-9","name":"router.ts"},{"uid":"007eb862-11","name":"components.tsx"},{"uid":"007eb862-13","name":"not-found.ts"},{"uid":"007eb862-15","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"007eb862-1":{"renderedLength":2974,"gzipLength":1310,"brotliLength":0,"metaUid":"007eb862-0"},"007eb862-3":{"renderedLength":12965,"gzipLength":3914,"brotliLength":0,"metaUid":"007eb862-2"},"007eb862-5":{"renderedLength":2194,"gzipLength":899,"brotliLength":0,"metaUid":"007eb862-4"},"007eb862-7":{"renderedLength":385,"gzipLength":246,"brotliLength":0,"metaUid":"007eb862-6"},"007eb862-9":{"renderedLength":27519,"gzipLength":7633,"brotliLength":0,"metaUid":"007eb862-8"},"007eb862-11":{"renderedLength":9851,"gzipLength":3302,"brotliLength":0,"metaUid":"007eb862-10"},"007eb862-13":{"renderedLength":1315,"gzipLength":682,"brotliLength":0,"metaUid":"007eb862-12"},"007eb862-15":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"007eb862-14"}},"nodeMetas":{"007eb862-0":{"id":"/src/loader.ts","moduleParts":{"index.js":"007eb862-1"},"imported":[{"uid":"007eb862-16"}],"importedBy":[{"uid":"007eb862-14"},{"uid":"007eb862-10"}]},"007eb862-2":{"id":"/src/match.ts","moduleParts":{"index.js":"007eb862-3"},"imported":[],"importedBy":[{"uid":"007eb862-14"},{"uid":"007eb862-8"}]},"007eb862-4":{"id":"/src/scroll.ts","moduleParts":{"index.js":"007eb862-5"},"imported":[],"importedBy":[{"uid":"007eb862-8"}]},"007eb862-6":{"id":"/src/types.ts","moduleParts":{"index.js":"007eb862-7"},"imported":[],"importedBy":[{"uid":"007eb862-14"},{"uid":"007eb862-8"}]},"007eb862-8":{"id":"/src/router.ts","moduleParts":{"index.js":"007eb862-9"},"imported":[{"uid":"007eb862-16"},{"uid":"007eb862-17"},{"uid":"007eb862-2"},{"uid":"007eb862-4"},{"uid":"007eb862-6"}],"importedBy":[{"uid":"007eb862-14"},{"uid":"007eb862-10"}]},"007eb862-10":{"id":"/src/components.tsx","moduleParts":{"index.js":"007eb862-11"},"imported":[{"uid":"007eb862-16"},{"uid":"007eb862-17"},{"uid":"007eb862-0"},{"uid":"007eb862-8"}],"importedBy":[{"uid":"007eb862-14"}]},"007eb862-12":{"id":"/src/not-found.ts","moduleParts":{"index.js":"007eb862-13"},"imported":[{"uid":"007eb862-16"}],"importedBy":[{"uid":"007eb862-14"}]},"007eb862-14":{"id":"/src/index.ts","moduleParts":{"index.js":"007eb862-15"},"imported":[{"uid":"007eb862-10"},{"uid":"007eb862-12"},{"uid":"007eb862-0"},{"uid":"007eb862-2"},{"uid":"007eb862-8"},{"uid":"007eb862-6"}],"importedBy":[],"isEntry":true},"007eb862-16":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"007eb862-10"},{"uid":"007eb862-12"},{"uid":"007eb862-0"},{"uid":"007eb862-8"}]},"007eb862-17":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"007eb862-10"},{"uid":"007eb862-8"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -2,6 +2,8 @@ import { ErrorBoundary, createContext, createRef, h, onUnmount, provide, useCont
 import { computed, signal } from "@pyreon/reactivity";
 
 //#region src/loader.ts
+const __DEV__$1 = import.meta.env?.DEV === true;
+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.
@@ -32,6 +34,7 @@ function useLoaderData() {
 * const html = await renderToString(h(App, { router }))
 */
 async function prefetchLoaderData(router, path) {
+	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) => {
@@ -84,17 +87,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 +122,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];
@@ -398,7 +405,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 +421,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 +433,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 +443,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 +452,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 = {};
@@ -588,6 +612,7 @@ function isLazy(c) {
 //#region src/router.ts
 const _isBrowser = typeof window !== "undefined";
 const __DEV__ = import.meta.env?.DEV === true;
+const _countSink = globalThis;
 const RouterContext = createContext(null);
 let _activeRouter = null;
 function setActiveRouter(router) {
@@ -806,8 +831,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 +851,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}>.");
@@ -954,13 +1019,60 @@ 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;
+	}
+	/**
+	* 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) return inflight;
+		if (__DEV__) _countSink.__pyreon_count__?.("router.loaderRun");
+		const promise = record.loader(loaderCtx).then((data) => {
+			router._loaderCache.set(key, {
+				data,
+				timestamp: Date.now()
+			});
+			router._loaderInflight.delete(key);
+			return data;
+		}).catch((err) => {
+			router._loaderInflight.delete(key);
+			throw err;
+		});
+		router._loaderInflight.set(key, promise);
+		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)));
+		const results = await Promise.allSettled(records.map((r) => executeLoader(r, loaderCtx)));
 		if (gen !== _navGen) return false;
 		for (let i = 0; i < records.length; i++) {
 			const result = results[i];
@@ -982,6 +1094,11 @@ function createRouter(options) {
 			r.loader(loaderCtx).then((data) => {
 				if (!ac.signal.aborted) {
 					router._loaderData.set(r, data);
+					const key = getCacheKey(r, loaderCtx);
+					router._loaderCache.set(key, {
+						data,
+						timestamp: Date.now()
+					});
 					loadingSignal.update((n) => n + 1);
 					loadingSignal.update((n) => n - 1);
 				}
@@ -1059,6 +1176,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;
@@ -1123,6 +1242,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);
@@ -1181,6 +1303,22 @@ function createRouter(options) {
 				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 +1328,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 +1354,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}`;
@@ -1330,19 +1473,31 @@ const RouterView = (props) => {
 };
 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 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 +1510,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) => {
@@ -1375,11 +1531,14 @@ const RouterLink = (props) => {
 		ref,
 		href,
 		class: activeClass,
+		"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 +1546,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 +1594,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.
 */
@@ -1476,5 +1714,55 @@ function isStaleChunk(err) {
 }
 
 //#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 };
+//#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 { NotFoundBoundary, RouterContext, RouterLink, RouterProvider, RouterView, buildPath, createRouter, findRouteByName, hydrateLoaderData, isNotFoundError, lazy, notFound, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams, useValidatedSearch };
 //# sourceMappingURL=index.js.map