@pyreon/router 0.13.1 → 0.15.0

package/src/not-found.ts

@@ -0,0 +1,75 @@
+import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
+import { ErrorBoundary, h } from '@pyreon/core'
+
+// ─── NotFound symbol + throw ────────────────────────────────────────────────
+
+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
+ * }
+ * ```
+ */
+export function notFound(message?: string): never {
+  const err = new Error(message ?? 'Not Found')
+  ;(err as unknown as Record<symbol, unknown>)[NOT_FOUND] = true
+  throw err
+}
+
+/** Check if an error is a NotFoundError thrown by `notFound()`. */
+export function isNotFoundError(err: unknown): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    (err as Record<string | symbol, unknown>)[NOT_FOUND] === true
+  )
+}
+
+// ─── NotFoundBoundary ──────────────────────────────────────────────────────
+
+export 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>
+ * ```
+ */
+export const NotFoundBoundary: ComponentFn<NotFoundBoundaryProps> = (props) => {
+  return h(
+    ErrorBoundary,
+    {
+      fallback: (err: unknown, reset: () => void) => {
+        if (!isNotFoundError(err)) {
+          // Re-throw non-notFound errors so they propagate
+          throw err
+        }
+        const fb = props.fallback
+        if (typeof fb === 'function' && fb.length <= 1) {
+          return h(fb as ComponentFn, { error: err, reset })
+        }
+        return fb as VNodeChild
+      },
+    },
+    props.children,
+  )
+}

package/src/redirect.ts

@@ -0,0 +1,63 @@
+// ─── Redirect symbol + throw ────────────────────────────────────────────────
+
+const REDIRECT = Symbol.for('pyreon.redirect')
+
+/** Standard redirect status codes. 307/308 preserve the request method, 302/303 don't. */
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308
+
+interface RedirectInfo {
+  url: string
+  status: RedirectStatus
+}
+
+/**
+ * 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.
+ */
+export function redirect(url: string, status: RedirectStatus = 307): never {
+  const err = new Error(`Redirect to ${url}`)
+  ;(err as unknown as Record<symbol, RedirectInfo>)[REDIRECT] = { url, status }
+  throw err
+}
+
+/** Check if an error is a RedirectError thrown by `redirect()`. */
+export function isRedirectError(err: unknown): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    typeof (err as Record<symbol, unknown>)[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).
+ */
+export function getRedirectInfo(err: unknown): RedirectInfo | null {
+  if (!isRedirectError(err)) return null
+  return (err as Record<symbol, RedirectInfo>)[REDIRECT] ?? null
+}

package/src/router.ts

@@ -1,6 +1,7 @@
 import { createContext, onUnmount, useContext } from '@pyreon/core'
 import { computed, signal } from '@pyreon/reactivity'
 import { buildNameIndex, buildPath, resolveRoute, stringifyQuery } from './match'
+import { getRedirectInfo } from './redirect'
 import { ScrollManager } from './scroll'
 import {
   type AfterEachHook,
@@ -26,8 +27,10 @@ import {
 const _isBrowser = typeof window !== 'undefined'
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
+
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
 
 // ─── Router context ───────────────────────────────────────────────────────────
 // Context-based access: isolated per request in SSR (ALS-backed via
@@ -253,9 +256,7 @@ export type SearchParamSchema = {
 
 /** Infer the typed result from a search param schema. */
 type InferSearchParams<T extends SearchParamSchema> = {
-  [K in keyof T]: T[K] extends 'number' ? number
-    : T[K] extends 'boolean' ? boolean
-    : string
+  [K in keyof T]: T[K] extends 'number' ? number : T[K] extends 'boolean' ? boolean : string
 }
 
 /**
@@ -316,15 +317,20 @@ export function useSearchParams<T extends Record<string, string>>(
  */
 export function useTypedSearchParams<T extends SearchParamSchema>(
   schema: T,
-): [get: () => InferSearchParams<T>, set: (updates: Partial<InferSearchParams<T>>) => Promise<void>] {
+): [
+  get: () => InferSearchParams<T>,
+  set: (updates: Partial<InferSearchParams<T>>) => Promise<void>,
+] {
   const router = _getRouter()
   const get = (): InferSearchParams<T> => {
     const query = router.currentRoute().query
     const result: Record<string, unknown> = {}
     for (const [key, type] of Object.entries(schema)) {
       const raw = query[key]
-      if (type === 'number') result[key] = raw !== undefined ? Number(raw) : 0
-      else if (type === 'boolean') result[key] = raw === 'true' || raw === '1'
+      if (type === 'number') {
+        const n = raw !== undefined ? 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 as InferSearchParams<T>
@@ -341,6 +347,53 @@ export function useTypedSearchParams<T extends SearchParamSchema>(
   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
+ * ```
+ */
+export function useValidatedSearch<
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(): () => T {
+  const router = _getRouter()
+  // Structural sharing: cache the previous result and return it if
+  // shallow-equal to the new one. Prevents downstream re-renders when
+  // unrelated query params change but the validated subset didn't.
+  let prev: T | null = null
+  return () => {
+    const next = router.currentRoute().search as T
+    if (prev && shallowEqual(prev, next)) return prev
+    prev = next
+    return next
+  }
+}
+
+/** Shallow equality check for plain objects — keys + strict value comparison. */
+function shallowEqual<T extends Record<string, unknown>>(a: T, b: T): boolean {
+  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(): RouterInstance {
   const router = (useContext(RouterContext) ?? _activeRouter) as RouterInstance | null
   if (!router)
@@ -385,12 +438,14 @@ export function useTransition(): () => boolean {
  */
 export function useMiddlewareData(): () => Record<string, unknown> {
   const router = _getRouter()
-  return () => (router.currentRoute() as any)._middlewareData ?? {}
+  return () => router.currentRoute()._middlewareData ?? {}
 }
 
 // ─── Factory ──────────────────────────────────────────────────────────────────
 
-export function createRouter(options: RouterOptions | RouteRecord[]): Router {
+export function createRouter<TNames extends string = string>(
+  options: RouterOptions | RouteRecord[],
+): Router<TNames> {
   const opts: RouterOptions = Array.isArray(options) ? { routes: options } : options
   const {
     routes,
@@ -514,18 +569,24 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     record: RouteRecord,
     ac: AbortController,
     to: ResolvedRoute,
-  ): boolean {
+  ): GuardOutcome {
     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' }
+    // `redirect()` from a loader: propagate as a router-level redirect so the
+    // navigate flow re-runs against the target path BEFORE the matched route's
+    // layout / page mounts. Bypasses the user-supplied `_onError` hook — a
+    // redirect is intentional flow control, not an error.
+    const info = getRedirectInfo(result.reason)
+    if (info) return { action: 'redirect', target: info.url }
     if (router._onError) {
       const cancel = router._onError(result.reason, to)
-      if (cancel === false) return false
+      if (cancel === false) return { action: 'cancel' }
     }
     router._loaderData.set(record, undefined)
-    return true
+    return { action: 'continue' }
   }
 
   function syncBrowserUrl(path: string, replace: boolean): void {
@@ -558,24 +619,122 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     return runGlobalGuards(guards, to, from, gen)
   }
 
+  /** Default cache key: path + serialized params */
+  function defaultLoaderKey(
+    record: RouteRecord,
+    ctx: Pick<LoaderContext, 'params' | 'query'>,
+  ): string {
+    return `${record.path}:${JSON.stringify(ctx.params)}`
+  }
+
+  /** Get cache key for a route record + context. */
+  function getCacheKey(record: RouteRecord, ctx: Pick<LoaderContext, 'params' | 'query'>): string {
+    return record.loaderKey ? record.loaderKey(ctx) : defaultLoaderKey(record, ctx)
+  }
+
+  /** Check if a cached entry is still fresh (not expired by gcTime). */
+  function isCacheFresh(entry: { timestamp: number }, record: RouteRecord): boolean {
+    const gcTime = record.gcTime ?? 300_000 // 5 min default
+    if (gcTime === 0) return false // caching disabled
+    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: string, data: unknown): void {
+    router._loaderCache.set(key, { data, timestamp: Date.now() })
+    if (router._loaderCache.size > router._maxCacheSize) {
+      // Map iterates in insertion order — first key is oldest
+      const oldest = router._loaderCache.keys().next().value as string | undefined
+      if (oldest !== undefined) 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: RouteRecord, loaderCtx: LoaderContext): Promise<unknown> {
+    if (!record.loader) return Promise.resolve(undefined)
+
+    const key = getCacheKey(record, loaderCtx)
+
+    // 1. Cache hit — skip for SWR routes (they always revalidate via the SWR path)
+    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)
+      }
+    }
+
+    // 2. Dedup in-flight — but only if the in-flight signal is still live.
+    // Pre-fix: nav-1 starts loader (signal=ac1.signal). User navigates again
+    // to the same path → nav-2's `router.push` first calls `_abortController?.abort()`
+    // (aborting ac1), then calls executeLoader. The Map still holds nav-1's
+    // promise (the .catch hasn't run yet); deduping returns it, but its
+    // signal is already aborted → nav-2 ends up with a rejected promise
+    // even though it has its own fresh ac2.signal. Now we check liveness.
+    const inflight = router._loaderInflight.get(key)
+    if (inflight && !inflight.signal.aborted) return inflight.promise
+
+    // 3. Execute. Wrap with `Promise.resolve().then(...)` so a SYNCHRONOUS
+    // throw from the loader (`redirect('/login')` / `notFound()` / a plain
+    // `throw new Error(...)`) becomes a rejected promise the `.catch` can
+    // handle — instead of escaping past the promise chain and surfacing as
+    // an unhandled exception in `runBlockingLoaders`'s `Promise.allSettled`.
+    if (__DEV__) _countSink.__pyreon_count__?.('router.loaderRun')
+    const promise = Promise.resolve()
+      .then(() => record.loader!(loaderCtx))
+      .then((data) => {
+        loaderCacheSet(key, data)
+        // Only delete if WE'RE still the registered in-flight (a later nav
+        // may have replaced the entry with a fresh promise).
+        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: RouteRecord[],
     to: ResolvedRoute,
     gen: number,
     ac: AbortController,
-  ): Promise<boolean> {
+  ): Promise<GuardOutcome> {
     const loaderCtx: LoaderContext = { params: to.params, query: to.query, signal: ac.signal }
-    const results = await Promise.allSettled(
-      records.map((r) => (r.loader ? r.loader(loaderCtx) : Promise.resolve(undefined))),
-    )
-    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)
+      // Short-circuit on first redirect or cancel — later loaders' results
+      // are irrelevant once we know the navigation isn't committing here.
+      if (outcome.action !== 'continue') return outcome
     }
-    return true
+    return { action: 'continue' }
   }
 
   /** Fire-and-forget background revalidation for stale-while-revalidate routes. */
@@ -583,10 +742,14 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     const loaderCtx: LoaderContext = { params: to.params, query: to.query, signal: ac.signal }
     for (const r of records) {
       if (!r.loader) continue
+      // Bypass cache for revalidation — always fetch fresh
       r.loader(loaderCtx)
         .then((data) => {
           if (!ac.signal.aborted) {
             router._loaderData.set(r, data)
+            // Update cache with fresh data
+            const key = getCacheKey(r, loaderCtx)
+            loaderCacheSet(key, data)
             // Bump loadingSignal to trigger reactive re-render with fresh data
             loadingSignal.update((n) => n + 1)
             loadingSignal.update((n) => n - 1)
@@ -598,9 +761,13 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     }
   }
 
-  async function runLoaders(to: ResolvedRoute, gen: number, ac: AbortController): Promise<boolean> {
+  async function runLoaders(
+    to: ResolvedRoute,
+    gen: number,
+    ac: AbortController,
+  ): Promise<GuardOutcome> {
     const loadableRecords = to.matched.filter((r) => r.loader)
-    if (loadableRecords.length === 0) return true
+    if (loadableRecords.length === 0) return { action: 'continue' }
 
     const blocking: RouteRecord[] = []
     const swr: RouteRecord[] = []
@@ -613,11 +780,11 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     }
 
     if (blocking.length > 0) {
-      const ok = await runBlockingLoaders(blocking, to, gen, ac)
-      if (!ok) 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(
@@ -645,9 +812,10 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
 
     // Use View Transitions API when available and not explicitly disabled.
     // Route meta can opt out: meta: { viewTransition: false }
-    const useVT = _isBrowser
-      && to.meta.viewTransition !== false
-      && typeof (document as any).startViewTransition === 'function'
+    const useVT =
+      _isBrowser &&
+      to.meta.viewTransition !== false &&
+      typeof (document as any).startViewTransition === 'function'
 
     if (useVT) {
       // `startViewTransition(cb)` runs `cb` inside an async transition. Its
@@ -670,10 +838,11 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
         ready?: Promise<void>
         finished?: Promise<void>
       }
-      const vt = (document as { startViewTransition?: (cb: () => void) => ViewTransitionLike | undefined })
-        .startViewTransition!(() => {
-          doCommit()
-        })
+      const vt = (
+        document as { startViewTransition?: (cb: () => void) => ViewTransitionLike | undefined }
+      ).startViewTransition!(() => {
+        doCommit()
+      })
       // `startViewTransition` may return `undefined` in test doubles
       // that shim it with a bare `(cb) => cb()`. Guard accordingly.
       if (vt) {
@@ -734,7 +903,9 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     to: ResolvedRoute,
     from: ResolvedRoute,
     gen: number,
-  ): Promise<{ action: 'continue' } | { action: 'cancel' } | { action: 'redirect'; target: string }> {
+  ): Promise<
+    { action: 'continue' } | { action: 'cancel' } | { action: 'redirect'; target: string }
+  > {
     const ctx: RouteMiddlewareContext = { to, from, data: {} }
 
     for (const record of to.matched) {
@@ -749,11 +920,13 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     }
 
     // Store middleware data on the resolved route for component access
-    ;(to as any)._middlewareData = ctx.data
+    to._middlewareData = ctx.data
     return { action: 'continue' }
   }
 
   async function navigate(rawPath: string, replace: boolean, redirectDepth = 0): Promise<void> {
+    if (__DEV__) _countSink.__pyreon_count__?.('router.navigate')
+    router._navigationStartTime = Date.now()
     if (redirectDepth > 10) {
       if (__DEV__) {
         // oxlint-disable-next-line no-console
@@ -807,9 +980,12 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     const ac = new AbortController()
     router._abortController = ac
 
-    const loadersOk = await runLoaders(to, gen, ac)
-    if (!loadersOk) {
+    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
     }
 
@@ -847,6 +1023,9 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     _readyPromise,
     _onError: onError,
     _maxCacheSize: maxCacheSize,
+    _navigationStartTime: Date.now(),
+    _loaderCache: new Map(),
+    _loaderInflight: new Map(),
 
     async push(
       location:
@@ -918,7 +1097,7 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
       return router._readyPromise
     },
 
-    async preload(path: string) {
+    async preload(path: string, request?: Request) {
       const resolved = resolveRoute(path, routes)
       // Load lazy components in parallel and populate the component cache so
       // the synchronous render pass finds ready components instead of kicking
@@ -948,16 +1127,46 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
         resolved.matched
           .filter((r) => r.loader)
           .map(async (r) => {
-            const data = await r.loader?.({
-              params: resolved.params,
-              query: resolved.query,
-              signal: ac.signal,
-            })
+            // Wrap with `Promise.resolve().then(...)` so a SYNCHRONOUS
+            // throw — `redirect('/login')` from a sync loader, `notFound()`,
+            // a plain `throw new Error(...)` — becomes a rejected promise
+            // the surrounding Promise.all surfaces. Bare `await r.loader(...)`
+            // would let synchronous throws escape past the `await` and
+            // surface as an uncaught exception in the Vite dev SSR pipeline.
+            const data = await Promise.resolve().then(() =>
+              r.loader!({
+                params: resolved.params,
+                query: resolved.query,
+                signal: ac.signal,
+                ...(request ? { request } : {}),
+              }),
+            )
             router._loaderData.set(r, data)
           }),
       )
     },
 
+    invalidateLoader(keyOrPredicate?: string | ((key: string) => boolean)) {
+      if (!keyOrPredicate) {
+        // Invalidate all
+        router._loaderCache.clear()
+        router._loaderInflight.clear()
+        return
+      }
+      if (typeof keyOrPredicate === 'string') {
+        router._loaderCache.delete(keyOrPredicate)
+        router._loaderInflight.delete(keyOrPredicate)
+        return
+      }
+      // Predicate
+      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)
@@ -968,6 +1177,8 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
       router._blockers.clear()
       componentCache.clear()
       router._loaderData.clear()
+      router._loaderCache.clear()
+      router._loaderInflight.clear()
       router._abortController?.abort()
       router._abortController = null
       // Clear global ref so stale router doesn't survive in SSR or re-creation
@@ -986,7 +1197,7 @@ export function createRouter(options: RouterOptions | RouteRecord[]): Router {
     }
   })
 
-  return router
+  return router as unknown as Router<TNames>
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -1014,6 +1225,13 @@ function resolveNamedPath(
 ): string {
   const record = index.get(name)
   if (!record) {
+    if (__DEV__) {
+      // oxlint-disable-next-line no-console
+      console.warn(
+        `[Pyreon Router] Unknown route name "${name}". ` +
+          `Available names: ${[...index.keys()].join(', ') || '(none)'}. Falling back to "/".`,
+      )
+    }
     return '/'
   }
   let path = buildPath(record.path, params)