@pyreon/router 0.13.1 → 0.15.0

package/src/components.tsx

@@ -1,5 +1,15 @@
-import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
-import { createRef, ErrorBoundary, h, onUnmount, provide, useContext } from '@pyreon/core'
+import type { ClassValue, ComponentFn, Props, VNodeChild } from '@pyreon/core'
+import {
+  createRef,
+  cx,
+  ErrorBoundary,
+  h,
+  nativeCompat,
+  onUnmount,
+  provide,
+  useContext,
+} from '@pyreon/core'
+import { computed, signal } from '@pyreon/reactivity'
 import { LoaderDataContext, prefetchLoaderData } from './loader'
 import { isLazy, RouterContext, setActiveRouter } from './router'
 import type { LazyComponent, ResolvedRoute, RouteRecord, Router, RouterInstance } from './types'
@@ -74,30 +84,108 @@ export const RouterView: ComponentFn<RouterViewProps> = (props) => {
     router._viewDepth--
   })
 
-  const child = (): VNodeChild => {
-    router._loadingSignal() // reactive — re-renders after lazy load completes
-
-    const route = router.currentRoute()
-
-    if (route.matched.length === 0) return null
-
-    // Render the matched record at this view's depth level
-    const record = route.matched[depth]
-    if (!record) return null // no component at this nesting level
-
-    const cached = router._componentCache.get(record)
-    if (cached) {
-      return renderWithLoader(router, record, cached, route)
-    }
+  // ── Structure / data decoupling ───────────────────────────────────────────
+  //
+  // Pre-fix the reactive child accessor read `_loadingSignal` and the full
+  // `currentRoute` snapshot. The framework's `mountReactive` tears down and
+  // rebuilds the entire subtree on every accessor re-emission, so any
+  // unrelated route signal (loader writes, lazy resolution, navigation
+  // start/end counters, param changes that don't change the matched record)
+  // would tear down the layout, then the page, then everything below it.
+  // For a single page load with one cold-start `router.replace()`, that
+  // produced ~9 cascading remounts of the layout — confirmed empirically
+  // by instance counters.
+  //
+  // The fix decouples STRUCTURE (which RouteRecord is mounted at this depth
+  // + which component to render for it) from DATA (params / query / loader
+  // data flowing into the rendered component). One computed returns BOTH
+  // the record and its resolved component as an atomic pair — re-emits ONLY
+  // when either side changes (reference equality on both fields). Loader
+  // writes / param changes / navigation counters don't re-emit; the rendered
+  // component receives route data through reactive props + the
+  // `LoaderDataProvider` context, which subscribe per-component to the
+  // signals they actually care about, so a param change re-renders just the
+  // page leaf — not the layout chain above it.
+  //
+  // The structure is intentionally a SINGLE computed (not two layered ones):
+  // when `currentRoute` changes, the reactive child accessor must see a
+  // CONSISTENT (rec, comp) pair on its next re-run. With two layered
+  // computeds the child accessor subscribes to both, and the order in which
+  // those two notify the child is unspecified — if the child runs after rec
+  // is notified but before comp re-evaluates, it reads the new rec paired
+  // with the OLD comp. Empirically that produced rec=/button paired with
+  // comp=HomePage, leaving the previous page rendered after navigation.
+  // Combining them into one computed forces atomic emission.
+  interface DepthEntry {
+    rec: RouteRecord | null
+    comp: ComponentFn | null
+    /**
+     * True when lazy resolution exhausted retries and the chunk is in
+     * `_erroredChunks`. Tracked structurally so the entry re-emits when
+     * the error state flips on — otherwise `equals` would block the
+     * { rec, comp: null } → { rec, comp: null, errored: true } transition
+     * (`comp` and `rec` are unchanged) and the error component would
+     * never render.
+     */
+    errored: boolean
+    /**
+     * The full ResolvedRoute reference at the time this entry was emitted.
+     * `currentRoute` is a `computed` keyed on `currentPath` — same path
+     * returns the same memoized reference, different path returns a new
+     * one. Tracking the reference in `equals` makes the depth re-emit on
+     * any real navigation (params change, query change, hash change) even
+     * when the matched record at this depth stays the same — required so
+     * `/user/42 → /user/99` re-renders the User component with new params
+     * — while NOT re-emitting on navigate-flow noise (`_loadingSignal`
+     * start/end ticks, lazy resolution writes that complete without
+     * changing currentPath). One emit per real navigation, not per
+     * within-navigation signal tick.
+     */
+    route: ResolvedRoute
+  }
+  const depthEntry = computed<DepthEntry>(
+    () => {
+      const route = router.currentRoute()
+      const rec = route.matched[depth] ?? null
+      if (!rec) return { rec: null, comp: null, errored: false, route }
+      // Subscribe to `_loadingSignal` so lazy resolution wakes this
+      // computed up — when the cache fills, we re-emit with comp set.
+      router._loadingSignal()
+      const errored = router._erroredChunks.has(rec)
+      if (errored) 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, rec, raw)
+        return { rec, comp: raw, errored: false, route }
+      }
+      // Lazy and not yet cached — `child()` below renders the lazy
+      // fallback and triggers the load; once the load completes,
+      // `_loadingSignal` ticks and this computed re-emits with `comp` set.
+      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 raw = record.component
+  const child = (): VNodeChild => {
+    const { rec, comp, route } = depthEntry()
+    if (!rec) return null
 
-    if (!isLazy(raw)) {
-      cacheSet(router, record, raw)
-      return renderWithLoader(router, record, raw, route)
+    if (comp) {
+      return renderWithLoader(router, rec, comp, route)
     }
 
-    return renderLazyRoute(router, record, raw)
+    // Component not yet cached — kick off the lazy load. `renderLazyRoute`
+    // mutates `_loadingSignal` and `_componentCache` on completion, which
+    // re-emits `depthEntry` and re-runs this accessor with `comp` set.
+    return renderLazyRoute(router, rec, rec.component as LazyComponent)
   }
 
   return h('div', { 'data-pyreon-router-view': true }, child as unknown as VNodeChild)
@@ -117,17 +205,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,13 +228,35 @@ 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}`
+  // `href` MUST be an accessor, not a string captured at setup. `props.to`
+  // is a getter when the parent passes a reactive expression (the JSX
+  // compiler wraps `<RouterLink to={someExpr}>` as `_rp(() => someExpr)`).
+  // Capturing into a string at setup time freezes the URL — passing the
+  // accessor lets `applyProp` wrap it in `renderEffect` so href tracks the
+  // underlying signal.
+  const href = (): string =>
+    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 ''
@@ -161,6 +272,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') {
@@ -180,17 +293,51 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
     onUnmount(() => observer.disconnect())
   }
 
-  // Forward all non-RouterLink props (style, class, id, data-*, etc.) to the <a>.
-  const { to: _to, replace: _replace, activeClass: _ac, exactActiveClass: _eac, exact: _exact, prefetch: _prefetch, children, ...rest } = props
+  // Forward all non-RouterLink props (style, id, data-*, etc.) to the <a>.
+  // `class` is pulled out separately so it can be MERGED with the internal
+  // active-class accessor — overriding the user's class silently dropped any
+  // conditional class the consumer wanted (e.g. `class={() => cond ? 'on' : ''}`).
+  const {
+    to: _to,
+    replace: _replace,
+    activeClass: _ac,
+    exactActiveClass: _eac,
+    exact: _exact,
+    prefetch: _prefetch,
+    class: userClass,
+    children,
+    ...rest
+  } = props as RouterLinkProps & { class?: ClassValue | (() => ClassValue) }
+
+  // Compose the user-provided `class` (string / array / object / function) with
+  // the internal `activeClass` accessor. Returning a function lets `applyProp`
+  // wrap it in `renderEffect` once — so navigation re-evaluates BOTH sides on
+  // every route change without rebuilding the link.
+  const mergedClass = (): string => {
+    const userResolved =
+      typeof userClass === 'function' ? (userClass as () => ClassValue)() : userClass
+    return cx([userResolved, activeClass()] as ClassValue)
+  }
 
   return h(
     'a',
-    { ...rest, ref, href, class: activeClass, onClick: handleClick, onMouseEnter: handleMouseEnter },
+    {
+      ...rest,
+      ref,
+      href,
+      class: mergedClass,
+      '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 +345,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 +428,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.
@@ -323,3 +581,12 @@ function isStaleChunk(err: unknown): boolean {
   if (err instanceof SyntaxError) return true
   return false
 }
+
+// Mark router framework components as native — compat-mode jsx() runtimes
+// (react/preact/vue/solid-compat) skip wrapCompatComponent for these so their
+// provide() / useContext() / onUnmount() / effect() / IntersectionObserver
+// setup runs inside Pyreon's lifecycle frame instead of the compat wrapper's
+// runUntracked accessor.
+nativeCompat(RouterProvider)
+nativeCompat(RouterView)
+nativeCompat(RouterLink)

package/src/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal process type — just enough for `process.env.NODE_ENV` checks.
+ * Avoids requiring @types/node in consumers that import pyreon source
+ * via the `"bun"` export condition.
+ */
+declare var process: { env: { NODE_ENV?: string } }

package/src/index.ts

@@ -44,6 +44,10 @@
 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 type { RedirectStatus } from './redirect'
+export { getRedirectInfo, isRedirectError, redirect } from './redirect'
 export { hydrateLoaderData, prefetchLoaderData, serializeLoaderData, useLoaderData } from './loader'
 // Match utilities (useful for SSR route pre-fetching)
 export {
@@ -68,6 +72,7 @@ export {
   useSearchParams,
   useTransition,
   useTypedSearchParams,
+  useValidatedSearch,
 } from './router'
 // Types
 // Data loaders

package/src/loader.ts

@@ -2,6 +2,10 @@ 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.
+const __DEV__ = process.env.NODE_ENV !== 'production'
+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.
@@ -28,12 +32,23 @@ export function useLoaderData<T = unknown>(): T {
  * 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 }))
  */
-export async function prefetchLoaderData(router: RouterInstance, path: string): Promise<void> {
+export async function prefetchLoaderData(
+  router: RouterInstance,
+  path: string,
+  request?: Request,
+): 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
@@ -48,6 +63,7 @@ export async function prefetchLoaderData(router: RouterInstance, path: string):
           params: route.params,
           query: route.query,
           signal: ac.signal,
+          ...(request ? { request } : {}),
         })
         router._loaderData.set(r, data)
       }),

package/src/manifest.ts

@@ -254,6 +254,69 @@ const User = () => {
 }`,
       seeAlso: ['useMiddlewareData', 'useRoute'],
     },
+    {
+      name: 'redirect',
+      kind: 'function',
+      signature: 'redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): never',
+      summary:
+        "Throw inside a route loader to redirect the navigation BEFORE the layout renders. On SSR (initial nav), the thrown error is converted by `@pyreon/server`'s handler into a real HTTP `302`/`307` `Location:` response — no layout HTML leaves the server. On CSR (subsequent nav), the redirect propagates through the navigate flow and triggers `router.replace()` before any matched route's component mounts. Replaces the fragile `onMount + router.push()` workaround for auth-gates under nested-layout dev SSR + hydration. Default status is `307` (Temporary Redirect, method-preserving).",
+      example: `// src/routes/app/_layout.tsx
+import { redirect, type LoaderContext } from "@pyreon/router"
+
+export async function loader(ctx: LoaderContext) {
+  // SSR: read from request headers; CSR: read from document.cookie
+  const cookie = ctx.request?.headers.get("cookie")
+    ?? (typeof document !== "undefined" ? document.cookie : "")
+  const sid = /(?:^|;\\s*)sid=([^;]+)/.exec(cookie)?.[1]
+  if (!sid) redirect("/login")
+  const session = await getSession(sid)
+  if (!session) redirect("/login")
+  return { session }
+}`,
+      mistakes: [
+        'Calling `redirect()` outside a loader (in a component body, an event handler, etc.) — the helper expects to be caught by the loader-runner. For imperative redirects from event handlers, use `router.replace(target)` instead.',
+        "Forgetting to make `LoaderContext.request` access optional. It's populated only on SSR; CSR loaders see `request: undefined`. Read both: `ctx.request?.headers.get('cookie') ?? document.cookie`.",
+        'Using `redirect()` for control-flow that should be a `<Match>` / `<Show>` conditional — the helper is for redirecting the URL, not for branching the rendered output.',
+        'Returning `redirect()` instead of throwing it. The helper has return type `never` and throws — `return redirect(...)` is misleading and may suppress the throw under TS strict-null checks.',
+        'Picking the wrong status. Default `307` preserves the request method (POST stays POST after redirect). Use `302`/`303` to force GET on the target. Use `301`/`308` for PERMANENT moves (browsers cache them aggressively).',
+        'Assuming `redirect()` cancels every loader in a sibling chain. The first loader to throw wins; later loaders in the same `Promise.allSettled` batch may have already started executing before the redirect short-circuits. Treat them as best-effort.',
+      ],
+      seeAlso: ['notFound', 'useLoaderData', 'isRedirectError'],
+    },
+    {
+      name: 'isRedirectError',
+      kind: 'function',
+      signature: 'isRedirectError(err: unknown): boolean',
+      summary:
+        'Type guard for errors thrown by `redirect()`. Used internally by the router (CSR) and `@pyreon/server` (SSR) to distinguish redirect-control-flow errors from real failures. Useful in custom error boundaries that should let redirects pass through to the framework instead of catching them.',
+      example: `import { ErrorBoundary } from "@pyreon/core"
+import { isRedirectError } from "@pyreon/router"
+
+<ErrorBoundary fallback={(err, reset) => {
+  if (isRedirectError(err)) throw err  // let the framework handle it
+  return <ErrorPage error={err} onReset={reset} />
+}}>
+  <App />
+</ErrorBoundary>`,
+      seeAlso: ['redirect', 'isNotFoundError', 'getRedirectInfo'],
+    },
+    {
+      name: 'getRedirectInfo',
+      kind: 'function',
+      signature: 'getRedirectInfo(err: unknown): { url: string; status: 301 | 302 | 303 | 307 | 308 } | null',
+      summary:
+        "Extract the redirect URL and status from a thrown RedirectError. Returns `null` for non-redirect errors. Used by `@pyreon/server`'s SSR handler to convert the thrown error into a 302/307 `Response`.",
+      example: `import { getRedirectInfo } from "@pyreon/router"
+
+try {
+  await prefetchLoaderData(router, path, request)
+} catch (err) {
+  const info = getRedirectInfo(err)
+  if (info) return new Response(null, { status: info.status, headers: { Location: info.url } })
+  throw err
+}`,
+      seeAlso: ['redirect', 'isRedirectError'],
+    },
     {
       name: 'useSearchParams',
       kind: 'hook',

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]
@@ -288,7 +293,18 @@ function flattenOne(
     return
   }
 
-  const joined = [...parentSegments, ...c.segments]
+  // fs-router emits absolute paths for nested children (e.g. parent
+  // `/app` with child `/app/dashboard`, NOT child `dashboard`). Concating
+  // parent segments with the child's already-absolute segments would
+  // produce `/app/app/dashboard` — the staticMap then lookups the wrong
+  // key and resolveRoute returns `matched: []` for any such request.
+  // Detect "child path is absolute" (`path` starts with `/`) and skip the
+  // parent-segment prefix in that case — the child's own segments ARE
+  // the full intended path. Relative children (`dashboard`, `:id`)
+  // continue to inherit the parent's segments via concatenation.
+  const childPath = c.route.path
+  const isAbsoluteChild = typeof childPath === 'string' && childPath.startsWith('/')
+  const joined = isAbsoluteChild ? c.segments : [...parentSegments, ...c.segments]
   if (c.children && c.children.length > 0) {
     flattenWalk(result, c.children, joined, chain, meta)
   }
@@ -558,6 +574,7 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
       hash,
       matched: staticMatch.matchedChain,
       meta: staticMatch.meta,
+      search: runValidateSearch(staticMatch.matchedChain, query),
     }
   }
 
@@ -579,6 +596,7 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
           hash,
           matched: match.matched,
           meta: mergeMeta(match.matched),
+          search: runValidateSearch(match.matched, query),
         }
       }
     }
@@ -594,6 +612,7 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
       hash,
       matched: dynMatch.matched,
       meta: mergeMeta(dynMatch.matched),
+      search: runValidateSearch(dynMatch.matched, query),
     }
   }
 
@@ -607,10 +626,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) */