@pyreon/router 0.13.1 → 0.14.0

package/lib/types/index.d.ts

@@ -47,6 +47,15 @@ interface ResolvedRoute<P extends Record<string, string | undefined> = Record<st
   /** All matched records from root to leaf (one per nesting level) */
   matched: RouteRecord[];
   meta: RouteMeta;
+  /**
+   * Validated search params — populated when the matched route has `validateSearch`.
+   * Contains the typed result of `validateSearch(query)`. Use `useValidatedSearch()`
+   * to access this in components with full type inference.
+   * Empty object `{}` when no `validateSearch` is configured.
+   */
+  search?: Record<string, unknown> | undefined;
+  /** Middleware data attached during navigation (populated by middleware chain) */
+  _middlewareData?: Record<string, unknown> | undefined;
 }
 declare const LAZY_SYMBOL: unique symbol;
 interface LazyComponent {
@@ -144,8 +153,58 @@ interface RouteRecord<TPath extends string = string> {
    * Only applies when navigating to a route that already has cached loader data.
    */
   staleWhileRevalidate?: boolean;
+  /**
+   * Cache key function for loader data. Returns a string key derived from
+   * route params/query. When the key matches cached data, the loader is
+   * skipped (cache hit). Default: `path + JSON.stringify(params)`.
+   *
+   * @example
+   * ```ts
+   * loaderKey: ({ params }) => `user-${params.id}`
+   * ```
+   */
+  loaderKey?: (ctx: Pick<LoaderContext, 'params' | 'query'>) => string;
+  /**
+   * Time in ms to keep cached loader data before garbage collection.
+   * Default: 300000 (5 minutes). Set to 0 to disable caching.
+   * Stale data is still served immediately if `staleWhileRevalidate` is true.
+   */
+  gcTime?: number;
   /** Component rendered when this route's loader throws an error */
   errorComponent?: ComponentFn$1;
+  /**
+   * Component rendered while this route's loader is running.
+   * Only shown after `pendingMs` (default: 0) to avoid flash on fast loads.
+   * Once shown, displayed for at least `pendingMinMs` (default: 200) to avoid flicker.
+   */
+  pendingComponent?: ComponentFn$1;
+  /** Delay in ms before showing pendingComponent (default: 0). Prevents flash on fast loaders. */
+  pendingMs?: number;
+  /** Minimum display time in ms for pendingComponent once shown (default: 200). Prevents flicker. */
+  pendingMinMs?: number;
+  /**
+   * Validate and transform raw query string parameters into typed values.
+   * Receives the raw `Record<string, string>` from the URL and returns
+   * a typed object. The validated result is available via `useValidatedSearch()`.
+   *
+   * Accepts any function — use Zod `.parse`, Valibot, or a plain function:
+   *
+   * @example
+   * ```ts
+   * // Plain function:
+   * validateSearch: (raw) => ({
+   *   page: Number(raw.page) || 1,
+   *   q: raw.q ?? '',
+   * })
+   *
+   * // With Zod:
+   * validateSearch: z.object({
+   *   page: z.coerce.number().default(1),
+   *   q: z.string().default(''),
+   * }).parse
+   * ```
+   */
+  validateSearch?: (raw: Record<string, string>) => Record<string, unknown>;
   /** Per-route middleware — runs before guards, can accumulate context data. */
   middleware?: RouteMiddleware | RouteMiddleware[];
 }
@@ -255,6 +314,13 @@ interface Router<TNames extends string = string> {
    * call this for the same `url` you initialised the router with.
    */
   preload(path: string): Promise<void>;
+  /**
+   * Invalidate cached loader data. Forces loaders to re-run on next navigation.
+   * - No args: invalidate ALL cached loader data
+   * - String: invalidate by cache key (as returned by `loaderKey`)
+   * - Function: invalidate entries where the predicate returns true
+   */
+  invalidateLoader(keyOrPredicate?: string | ((key: string) => boolean)): void;
   /** Remove all event listeners, clear caches, and abort in-flight navigations. */
   destroy(): void;
 }
@@ -290,6 +356,15 @@ interface RouterInstance extends Router {
   _readyResolve: (() => void) | null;
   /** The isReady() promise instance */
   _readyPromise: Promise<void>;
+  /** Timestamp when the current navigation started — used for pendingMs timing */
+  _navigationStartTime: number;
+  /** Key-based loader cache: cacheKey → { data, timestamp } */
+  _loaderCache: Map<string, {
+    data: unknown;
+    timestamp: number;
+  }>;
+  /** In-flight loader dedup: cacheKey → Promise */
+  _loaderInflight: Map<string, Promise<unknown>>;
 }
 //#endregion
 //#region src/components.d.ts
@@ -338,15 +413,53 @@ interface RouterLinkProps extends Props {
   exact?: boolean;
   /**
    * Prefetch strategy for loader data:
-   *   - "hover" (default) — prefetch when the user hovers over the link
+   *   - "intent" (default) — prefetch on hover AND focus (covers mouse + keyboard)
+   *   - "hover" — prefetch on hover only
    *   - "viewport" — prefetch when the link scrolls into the viewport
    *   - "none" — no prefetching
    */
-  prefetch?: 'hover' | 'viewport' | 'none';
+  prefetch?: 'intent' | 'hover' | 'viewport' | 'none';
   children?: VNodeChild | null;
 }
 declare const RouterLink: ComponentFn<RouterLinkProps>;
 //#endregion
+//#region src/not-found.d.ts
+/**
+ * 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
+ * }
+ * ```
+ */
+declare function notFound(message?: string): never;
+/** Check if an error is a NotFoundError thrown by `notFound()`. */
+declare function isNotFoundError(err: unknown): boolean;
+interface NotFoundBoundaryProps extends Props {
+  /** Component or VNode to render when notFound() is thrown */
+  fallback: ComponentFn | VNodeChild;
+  children?: VNodeChild;
+}
+/**
+ * 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>
+ * ```
+ */
+declare const NotFoundBoundary: ComponentFn<NotFoundBoundaryProps>;
+//#endregion
 //#region src/loader.d.ts
 /**
  * Returns the data resolved by the current route's `loader` function.
@@ -399,10 +512,6 @@ declare function serializeLoaderData(router: RouterInstance): Record<string, unk
 declare function hydrateLoaderData(router: RouterInstance, serialized: Record<string, unknown>): void;
 //#endregion
 //#region src/match.d.ts
-/**
- * Parse a query string into key-value pairs. Duplicate keys are overwritten
- * (last value wins). Use `parseQueryMulti` to preserve duplicates as arrays.
- */
 declare function parseQuery(qs: string): Record<string, string>;
 /**
  * Parse a query string preserving duplicate keys as arrays.
@@ -526,6 +635,27 @@ declare function useSearchParams<T extends Record<string, string>>(defaults?: T)
  * ```
  */
 declare function useTypedSearchParams<T extends SearchParamSchema>(schema: T): [get: () => InferSearchParams<T>, set: (updates: Partial<InferSearchParams<T>>) => Promise<void>];
+/**
+ * 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
+ * ```
+ */
+declare function useValidatedSearch<T extends Record<string, unknown> = Record<string, unknown>>(): () => T;
 /**
  * Returns true while a navigation is in progress (guards + loaders running).
  * Use this to show loading indicators during route transitions.
@@ -556,7 +686,7 @@ declare function useTransition(): () => boolean;
  * ```
  */
 declare function useMiddlewareData(): () => Record<string, unknown>;
-declare function createRouter(options: RouterOptions | RouteRecord[]): Router;
+declare function createRouter<TNames extends string = string>(options: RouterOptions | RouteRecord[]): Router<TNames>;
 //#endregion
-export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteMiddleware, type RouteMiddlewareContext, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, hydrateLoaderData, lazy, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams };
+export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, NotFoundBoundary, type NotFoundBoundaryProps, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteMiddleware, type RouteMiddlewareContext, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, 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=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/components.tsx","../../../src/loader.ts","../../../src/match.ts","../../../src/router.ts"],"mappings":"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"}
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/components.tsx","../../../src/not-found.ts","../../../src/loader.ts","../../../src/match.ts","../../../src/router.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/router",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Official router for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/router#readme",
   "bugs": {
@@ -43,14 +43,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.13.1",
-    "@pyreon/reactivity": "^0.13.1",
-    "@pyreon/runtime-dom": "^0.13.1"
+    "@pyreon/core": "^0.14.0",
+    "@pyreon/reactivity": "^0.14.0",
+    "@pyreon/runtime-dom": "^0.14.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/test-utils": "^0.13.1",
+    "@pyreon/test-utils": "^0.13.2",
     "@vitest/browser-playwright": "^4.1.4",
     "happy-dom": "^20.8.3"
   }

package/src/components.tsx

@@ -1,5 +1,6 @@
 import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
 import { createRef, ErrorBoundary, h, onUnmount, provide, useContext } from '@pyreon/core'
+import { signal } from '@pyreon/reactivity'
 import { LoaderDataContext, prefetchLoaderData } from './loader'
 import { isLazy, RouterContext, setActiveRouter } from './router'
 import type { LazyComponent, ResolvedRoute, RouteRecord, Router, RouterInstance } from './types'
@@ -117,17 +118,18 @@ export interface RouterLinkProps extends Props {
   exact?: boolean
   /**
    * Prefetch strategy for loader data:
-   *   - "hover" (default) — prefetch when the user hovers over the link
+   *   - "intent" (default) — prefetch on hover AND focus (covers mouse + keyboard)
+   *   - "hover" — prefetch on hover only
    *   - "viewport" — prefetch when the link scrolls into the viewport
    *   - "none" — no prefetching
    */
-  prefetch?: 'hover' | 'viewport' | 'none'
+  prefetch?: 'intent' | 'hover' | 'viewport' | 'none'
   children?: VNodeChild | null
 }
 
 export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
   const router = useContext(RouterContext)
-  const prefetchMode = props.prefetch ?? 'hover'
+  const prefetchMode = props.prefetch ?? 'intent'
 
   const handleClick = (e: MouseEvent) => {
     e.preventDefault()
@@ -139,14 +141,29 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
     }
   }
 
-  const handleMouseEnter = () => {
-    if (prefetchMode !== 'hover' || !router) return
+  const triggerPrefetch = () => {
+    if (!router) return
     prefetchRoute(router as RouterInstance, props.to)
   }
 
+  const handleMouseEnter = () => {
+    if (prefetchMode === 'hover' || prefetchMode === 'intent') triggerPrefetch()
+  }
+
+  const handleFocus = () => {
+    if (prefetchMode === 'intent') triggerPrefetch()
+  }
+
   const inst = router as RouterInstance | null
   const href = inst?.mode === 'history' ? `${inst._base}${props.to}` : `#${props.to}`
 
+  const isExactMatch = (): boolean => {
+    if (!router) return false
+    const target = props.to
+    if (typeof target !== 'string') return false
+    return router.currentRoute().path === target
+  }
+
   const activeClass = (): string => {
     if (!router) return ''
     const current = router.currentRoute().path
@@ -161,6 +178,8 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
     return classes.join(' ').trim()
   }
 
+  const ariaCurrent = (): string | undefined => isExactMatch() ? 'page' : undefined
+
   // Viewport prefetching — observe link visibility with IntersectionObserver
   const ref = createRef<Element>()
   if (prefetchMode === 'viewport' && router && typeof IntersectionObserver !== 'undefined') {
@@ -185,12 +204,14 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
 
   return h(
     'a',
-    { ...rest, ref, href, class: activeClass, onClick: handleClick, onMouseEnter: handleMouseEnter },
+    { ...rest, ref, href, class: activeClass, 'aria-current': ariaCurrent, onClick: handleClick, 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: RouterInstance, path: string): void {
   let set = _prefetched.get(router)
   if (!set) {
@@ -198,6 +219,11 @@ function prefetchRoute(router: RouterInstance, path: string): void {
     _prefetched.set(router, set)
   }
   if (set.has(path)) return
+  // Evict oldest entries when cache is full to prevent unbounded growth
+  if (set.size >= MAX_PREFETCH_CACHE) {
+    const first = set.values().next().value as string
+    set.delete(first)
+  }
   set.add(path)
   prefetchLoaderData(router, path).catch(() => {
     // Silently ignore — prefetch is best-effort
@@ -276,12 +302,118 @@ function renderLoaderContent(
   routeProps: Record<string, unknown>,
 ): VNodeChild {
   const data = router._loaderData.get(record)
-  if (data === undefined && record.errorComponent) {
+
+  if (data !== undefined) {
+    return h(LoaderDataProvider, { data, children: h(Comp, routeProps) })
+  }
+
+  // Data not yet available — show pending component if configured
+  if (record.pendingComponent) {
+    return h(PendingLoader as unknown as ComponentFn, {
+      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: {
+  router: RouterInstance
+  record: RouteRecord
+  Comp: ComponentFn
+  routeProps: Record<string, unknown>
+}): VNodeChild {
+  const { router, record, Comp, routeProps } = props
+  const pendingMs = record.pendingMs ?? 0
+  const pendingMinMs = record.pendingMinMs ?? 200
+
+  type Phase = 'hidden' | 'pending' | 'ready'
+  const phase = signal<Phase>(pendingMs === 0 ? 'pending' : 'hidden')
+
+  let pendingTimer: ReturnType<typeof setTimeout> | null = null
+  let minTimer: ReturnType<typeof setTimeout> | null = null
+  let minTimeElapsed = pendingMs === 0 ? false : true // if no delay, minTime matters
+  let dataReady = false
+
+  if (pendingMs === 0) {
+    // Show pending immediately, start minTime countdown
+    minTimeElapsed = false
+    minTimer = setTimeout(() => {
+      minTimeElapsed = true
+      minTimer = null
+      if (dataReady) phase.set('ready')
+    }, pendingMinMs)
+  } else {
+    // Delay before showing pending
+    pendingTimer = setTimeout(() => {
+      pendingTimer = null
+      if (dataReady) {
+        // Data arrived during delay — skip pending entirely
+        phase.set('ready')
+      } else {
+        phase.set('pending')
+        minTimeElapsed = false
+        minTimer = setTimeout(() => {
+          minTimeElapsed = true
+          minTimer = null
+          if (dataReady) phase.set('ready')
+        }, pendingMinMs)
+      }
+    }, pendingMs)
+  }
+
+  // Watch for loader data arrival
+  const checkData = () => {
+    const data = router._loaderData.get(record)
+    if (data !== undefined) {
+      dataReady = true
+      if (phase.peek() === 'hidden') {
+        // Data arrived before pendingMs — skip pending, go straight to ready
+        if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null }
+        phase.set('ready')
+      } else if (minTimeElapsed) {
+        phase.set('ready')
+      }
+      // else: pending is showing but minTime hasn't elapsed — wait for minTimer
+    }
+  }
+
+  // Poll via loadingSignal reactivity — re-checks when navigation completes
+  // This runs inside the reactive accessor below
+
+  onUnmount(() => {
+    if (pendingTimer) clearTimeout(pendingTimer)
+    if (minTimer) clearTimeout(minTimer)
+  })
+
+  return (() => {
+    // Track router's loading signal to re-run when loader completes
+    router._loadingSignal()
+    checkData()
+
+    const p = phase()
+    if (p === 'hidden') return null
+    if (p === 'pending') return h(record.pendingComponent!, routeProps)
+    // ready
+    const data = router._loaderData.get(record)
+    return h(LoaderDataProvider, { data, children: h(Comp, routeProps) })
+  }) as unknown as VNodeChild
+}
+
 /**
  * Thin provider component that pushes LoaderDataContext before children mount.
  * Uses Pyreon's context stack so useLoaderData() reads it during child setup.

package/src/index.ts

@@ -44,6 +44,8 @@
 export type { RouterLinkProps, RouterProviderProps, RouterViewProps } from './components'
 // Components
 export { RouterLink, RouterProvider, RouterView } from './components'
+export type { NotFoundBoundaryProps } from './not-found'
+export { isNotFoundError, NotFoundBoundary, notFound } from './not-found'
 export { hydrateLoaderData, prefetchLoaderData, serializeLoaderData, useLoaderData } from './loader'
 // Match utilities (useful for SSR route pre-fetching)
 export {
@@ -68,6 +70,7 @@ export {
   useSearchParams,
   useTransition,
   useTypedSearchParams,
+  useValidatedSearch,
 } from './router'
 // Types
 // Data loaders

package/src/loader.ts

@@ -2,6 +2,11 @@ import type { Context } from '@pyreon/core'
 import { createContext, useContext } from '@pyreon/core'
 import type { RouterInstance } from './types'
 
+// Dev-mode gate + counter sink. See packages/internals/perf-harness for contract.
+// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
+const __DEV__ = import.meta.env?.DEV === true
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
+
 /**
  * Context frame that holds the loader data for the currently rendered route record.
  * Pushed by RouterView's withLoaderData wrapper before invoking the route component.
@@ -34,6 +39,7 @@ export function useLoaderData<T = unknown>(): T {
  * const html = await renderToString(h(App, { router }))
  */
 export async function prefetchLoaderData(router: RouterInstance, path: string): Promise<void> {
+  if (__DEV__) _countSink.__pyreon_count__?.('router.prefetch')
   const route = router._resolve(path)
   // Use a local AbortController — prefetch is best-effort and must NOT
   // clobber `router._abortController`, which belongs to the active

package/src/match.ts

@@ -6,17 +6,22 @@ import type { ResolvedRoute, RouteMeta, RouteRecord } from './types'
  * 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: string): string {
+  return decodeURIComponent(raw.replace(/\+/g, ' '))
+}
+
 export function parseQuery(qs: string): Record<string, string> {
   if (!qs) return {}
   const result: Record<string, string> = {}
   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
     }
   }
@@ -38,11 +43,11 @@ export function parseQueryMulti(qs: string): Record<string, string | string[]> {
     let key: string
     let val: string
     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]
@@ -558,6 +563,7 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
       hash,
       matched: staticMatch.matchedChain,
       meta: staticMatch.meta,
+      search: runValidateSearch(staticMatch.matchedChain, query),
     }
   }
 
@@ -579,6 +585,7 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
           hash,
           matched: match.matched,
           meta: mergeMeta(match.matched),
+          search: runValidateSearch(match.matched, query),
         }
       }
     }
@@ -594,6 +601,7 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
       hash,
       matched: dynMatch.matched,
       meta: mergeMeta(dynMatch.matched),
+      search: runValidateSearch(dynMatch.matched, query),
     }
   }
 
@@ -607,10 +615,31 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
       hash,
       matched: w.matchedChain,
       meta: w.meta,
+      search: runValidateSearch(w.matchedChain, query),
     }
   }
 
-  return { path: cleanPath, params: {}, query, hash, matched: [], meta: {} }
+  return { path: cleanPath, params: {}, query, hash, matched: [], meta: {}, search: {} }
+}
+
+/** Run validateSearch from the deepest matched route that has one. */
+function runValidateSearch(
+  matched: RouteRecord[],
+  query: Record<string, string>,
+): Record<string, unknown> {
+  // Walk from leaf to root — first validateSearch wins (most specific route)
+  for (let i = matched.length - 1; i >= 0; i--) {
+    const validate = matched[i]?.validateSearch
+    if (validate) {
+      try {
+        return validate(query)
+      } catch {
+        // Validation failed — return raw query as-is
+        return { ...query }
+      }
+    }
+  }
+  return {}
 }
 
 /** Merge meta from matched routes (leaf takes precedence) */