@pyreon/router 0.14.0 → 0.16.0

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

@@ -1,4 +1,38 @@
-import type { ResolvedRoute, RouteMeta, RouteRecord } from './types'
+import type { ResolvedRoute, RouteComponent, RouteMeta, RouteRecord } from './types'
+
+// ─── Default chrome layout registration ──────────────────────────────────────
+//
+// Late-bound registration for the synthetic layout used by the
+// layout-less-app 404 fallback in `findNotFoundFallback` below. The
+// component itself lives in `./components.tsx` (it needs JSX + the
+// `RouterView` it imports), but `match.ts` is below `components.tsx` in
+// the dependency graph (router.ts imports match.ts; components.tsx
+// imports router.ts) — directly importing `components.tsx` from here
+// would create a cycle. Instead, `components.tsx` calls
+// `_setDefaultChromeLayout(DefaultChromeLayout)` at module load. As
+// long as the consumer's app imports anything from `@pyreon/router`
+// that touches `components.tsx` (which every app does via
+// `RouterProvider` / `RouterView` / `RouterLink`), the registration
+// runs before any `resolveRoute()` call.
+//
+// When the setter hasn't been called (e.g. unit tests that exercise
+// `resolveRoute` in isolation without ever importing `components.tsx`),
+// `findNotFoundFallback` returns `null` for the layout-less case — the
+// standalone-render path in the SSG plugin / runtime handler picks up
+// from there. So the fix degrades gracefully.
+let _defaultChromeLayout: RouteComponent | null = null
+
+/**
+ * Register the synthetic "default chrome" layout used when a page-level
+ * `notFoundComponent` is the closest fallback (layout-less single-page-
+ * app shape). Called once at module load from `./components.tsx`. Pyreon
+ * apps shouldn't need to call this themselves.
+ *
+ * @internal
+ */
+export function _setDefaultChromeLayout(component: RouteComponent): void {
+  _defaultChromeLayout = component
+}
 
 // ─── Query string ─────────────────────────────────────────────────────────────
 
@@ -293,7 +327,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)
   }
@@ -619,9 +664,189 @@ export function resolveRoute(rawPath: string, routes: RouteRecord[]): ResolvedRo
     }
   }
 
+  // Fallback: notFoundComponent walk. When the URL doesn't match any
+  // descendant route, look for the deepest parent `notFoundComponent`
+  // whose path is a prefix of this URL. Build a synthetic chain that
+  // renders the not-found component INSIDE its ancestor layouts so the
+  // 404 page carries the same chrome (headers, footers, navigation) as
+  // regular pages. Without this, SSG/SSR returns `matched: []` and the
+  // caller has to render the not-found component standalone, losing
+  // layout wrapping.
+  const nfb = findNotFoundFallback(routes, cleanPath)
+  if (nfb) {
+    return {
+      path: cleanPath,
+      params: {},
+      query,
+      hash,
+      matched: nfb,
+      meta: mergeMeta(nfb),
+      search: {},
+      isNotFound: true,
+    }
+  }
+
   return { path: cleanPath, params: {}, query, hash, matched: [], meta: {}, search: {} }
 }
 
+// ─── notFoundComponent walking ───────────────────────────────────────────────
+
+/** Synthetic leaf RouteRecord used by the 404 fallback. Carries no real
+ * path matching — the resolver inserts it at the end of the chain when
+ * a parent `notFoundComponent` is the closest fallback for the URL. */
+const SYNTHETIC_NOT_FOUND_PATH = '__pyreon_not_found_leaf__'
+
+/**
+ * Walk the route tree finding records with `notFoundComponent`. Return
+ * the chain `[...ancestors, parentWithNotFound, syntheticLeaf]` for the
+ * DEEPEST record whose URL path is a prefix of `urlPath`.
+ *
+ * The path-prefix check: a record at `'/de'` applies to `/de/unknown`
+ * and `/de` itself but NOT to `/about` or `/encyclopedia` (full-segment
+ * boundary required, not substring). A record at `'/'` (root layout)
+ * applies to every URL. Deeper matches win — `/de` layout takes
+ * precedence over root layout for URLs under `/de/...`.
+ *
+ * Returns `null` when no record has `notFoundComponent`.
+ */
+function findNotFoundFallback(routes: RouteRecord[], urlPath: string): RouteRecord[] | null {
+  let best: { chain: RouteRecord[]; record: RouteRecord; depth: number; specificity: number } | null = null
+  // Second-pass fallback: collect the BEST page-level notFoundComponent
+  // (no children) in case the layout pass finds nothing. Applies to the
+  // layout-less single-page-app case where `_404.tsx` is emitted without
+  // a parent `_layout.tsx`. The layout pass intentionally skips this
+  // shape (page records have no `<RouterView />` to wrap the leaf); the
+  // synthetic default-chrome layout fills that gap below.
+  let pageBest: {
+    record: RouteRecord
+    depth: number
+    specificity: number
+    fullPath: string
+  } | null = null
+
+  function walk(records: RouteRecord[], parentChain: RouteRecord[], parentPath: string): void {
+    for (const r of records) {
+      const rawPath = typeof r.path === 'string' ? r.path : ''
+      // fs-router emits absolute paths for nested routes (e.g. `/de/about`);
+      // relative paths inherit parent's path via concat. Mirror flattenOne's
+      // logic so synthesised paths track real URL prefixes.
+      const fullPath = rawPath.startsWith('/')
+        ? rawPath
+        : `${parentPath}/${rawPath}`.replace(/\/+/g, '/')
+      const chain = [...parentChain, r]
+
+      // Filter to LAYOUT records (records with non-empty `children`).
+      // fs-router attaches `notFoundComponent` to BOTH the parent layout
+      // AND every page record under that layout. Page records have no
+      // `<RouterView />` to render the synthetic leaf at the next depth,
+      // so picking a page as the fallback parent produces a chain
+      // `[Layout, Page, syntheticLeaf]` where `Page` swallows the leaf.
+      // Filtering to records with children ensures the synthetic leaf
+      // lands at a depth a `<RouterView />` will actually render.
+      const isLayout = Array.isArray(r.children) && r.children.length > 0
+
+      if (typeof r.notFoundComponent === 'function') {
+        const applies = pathPrefixApplies(fullPath, urlPath)
+        if (applies) {
+          // Prefer (a) the deepest record (longest chain), then (b) the
+          // most specific path-prefix when chains tie. Specificity =
+          // number of path segments in `fullPath`. `/` has 0; `/de` has 1.
+          const specificity = countSegments(fullPath)
+          if (isLayout) {
+            if (
+              !best ||
+              chain.length > best.depth ||
+              (chain.length === best.depth && specificity > best.specificity)
+            ) {
+              best = { chain, record: r, depth: chain.length, specificity }
+            }
+          } else if (
+            !pageBest ||
+            chain.length > pageBest.depth ||
+            (chain.length === pageBest.depth && specificity > pageBest.specificity)
+          ) {
+            pageBest = { record: r, depth: chain.length, specificity, fullPath }
+          }
+        }
+      }
+
+      if (Array.isArray(r.children)) {
+        walk(r.children, chain, fullPath)
+      }
+    }
+  }
+
+  walk(routes, [], '')
+
+  if (best) {
+    // TypeScript widening: `best` is inferred as `null` inside the closure
+    // when not narrowed, even though we asserted it's non-null above.
+    const found: { chain: RouteRecord[]; record: RouteRecord; depth: number; specificity: number } =
+      best
+
+    const syntheticLeaf: RouteRecord = {
+      path: SYNTHETIC_NOT_FOUND_PATH,
+      component: found.record.notFoundComponent as RouteComponent,
+    }
+
+    return [...found.chain, syntheticLeaf]
+  }
+
+  // Layout-less fallback. The user has a page-level `notFoundComponent`
+  // (e.g. `_404.tsx` at the route root with no `_layout.tsx`). Without
+  // a parent layout to wrap the leaf, we synthesize ONE: a minimal
+  // "default chrome" layout that renders `<main data-pyreon-default-chrome>
+  // <RouterView /></main>`. This provides a semantic-HTML landmark for
+  // accessibility + a hook for users to target the wrapper via CSS, while
+  // routing the render through the normal `<RouterView />` pipeline (so
+  // `isNotFound` propagation and runtime SSR status-404 still work).
+  //
+  // The DefaultChromeLayout component is registered by `components.tsx`
+  // at module load time via `_setDefaultChromeLayout()` (setter pattern
+  // to avoid the components.tsx → match.ts circular import). If the
+  // setter hasn't been called yet (consumer never imported anything
+  // from `@pyreon/router` that triggers components.tsx's side effects),
+  // we fall back to returning null — the standalone-render path in the
+  // SSG plugin / runtime handler picks up from there.
+  if (pageBest && _defaultChromeLayout) {
+    const found: {
+      record: RouteRecord
+      depth: number
+      specificity: number
+      fullPath: string
+    } = pageBest
+
+    const syntheticChromeLayout: RouteRecord = {
+      path: found.fullPath,
+      component: _defaultChromeLayout,
+    }
+    const syntheticLeaf: RouteRecord = {
+      path: SYNTHETIC_NOT_FOUND_PATH,
+      component: found.record.notFoundComponent as RouteComponent,
+    }
+    return [syntheticChromeLayout, syntheticLeaf]
+  }
+
+  return null
+}
+
+/** Check whether `prefixPath` is a path-prefix of `urlPath` at segment boundaries. */
+function pathPrefixApplies(prefixPath: string, urlPath: string): boolean {
+  if (prefixPath === '/' || prefixPath === '') return true
+  if (urlPath === prefixPath) return true
+  // Require a `/` boundary after the prefix to avoid `/de` matching `/encyclopedia`.
+  return urlPath.startsWith(`${prefixPath}/`)
+}
+
+/** Count `/`-separated path segments. `/` → 0; `/de` → 1; `/de/about` → 2. */
+function countSegments(path: string): number {
+  let count = 0
+  for (let i = 0; i < path.length; i++) {
+    if (path.charCodeAt(i) === 47 /* / */ && i + 1 < path.length) count++
+  }
+  return count
+}
+
 /** Run validateSearch from the deepest matched route that has one. */
 function runValidateSearch(
   matched: RouteRecord[],

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,
@@ -12,7 +13,6 @@ import {
   type NavigationGuard,
   type NavigationGuardResult,
   type ResolvedRoute,
-  type RouteMiddleware,
   type RouteMiddlewareContext,
   type RouteRecord,
   type Router,
@@ -26,8 +26,7 @@ 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 }
@@ -569,18 +568,24 @@ export function createRouter<TNames extends string = string>(
     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 {
@@ -633,6 +638,25 @@ export function createRouter<TNames extends string = string>(
     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)
@@ -653,25 +677,41 @@ export function createRouter<TNames extends string = string>(
       }
     }
 
-    // 2. Dedup in-flight
+    // 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) return inflight
+    if (inflight && !inflight.signal.aborted) return inflight.promise
 
-    // 3. Execute
+    // 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 = record
-      .loader(loaderCtx)
+    const promise = Promise.resolve()
+      .then(() => record.loader!(loaderCtx))
       .then((data) => {
-        router._loaderCache.set(key, { data, timestamp: Date.now() })
-        router._loaderInflight.delete(key)
+        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) => {
-        router._loaderInflight.delete(key)
+        if (router._loaderInflight.get(key)?.promise === promise) {
+          router._loaderInflight.delete(key)
+        }
         throw err
       })
 
-    router._loaderInflight.set(key, promise)
+    router._loaderInflight.set(key, { promise, signal: loaderCtx.signal })
     return promise
   }
 
@@ -680,17 +720,20 @@ export function createRouter<TNames extends string = string>(
     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) => executeLoader(r, loaderCtx)))
-    if (gen !== _navGen) return false
+    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. */
@@ -705,7 +748,7 @@ export function createRouter<TNames extends string = string>(
             router._loaderData.set(r, data)
             // Update cache with fresh data
             const key = getCacheKey(r, loaderCtx)
-            router._loaderCache.set(key, { data, timestamp: Date.now() })
+            loaderCacheSet(key, data)
             // Bump loadingSignal to trigger reactive re-render with fresh data
             loadingSignal.update((n) => n + 1)
             loadingSignal.update((n) => n - 1)
@@ -717,9 +760,13 @@ export function createRouter<TNames extends string = string>(
     }
   }
 
-  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[] = []
@@ -732,11 +779,11 @@ export function createRouter<TNames extends string = string>(
     }
 
     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(
@@ -932,9 +979,12 @@ export function createRouter<TNames extends string = string>(
     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
     }
 
@@ -1046,7 +1096,11 @@ export function createRouter<TNames extends string = string>(
       return router._readyPromise
     },
 
-    async preload(path: string) {
+    async preload(
+      path: string,
+      request?: Request,
+      options?: { skipLoaders?: boolean },
+    ) {
       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
@@ -1064,6 +1118,13 @@ export function createRouter<TNames extends string = string>(
           componentCache.set(record, comp)
         }),
       )
+      // Skip the loader-running step when the caller explicitly opts out
+      // (used by the SSG plugin's 404 build path — parent-layout loaders
+      // that hit auth resources or external APIs shouldn't fire when
+      // generating a static 404 page). Lazy components above DO still
+      // resolve so the synthetic chain renders cleanly; only the
+      // `r.loader()` invocations are skipped.
+      if (options?.skipLoaders) return
       // Run loaders for the matched path — uses the same code path SSR
       // already relied on, so loader data ends up in `_loaderData` under the
       // matched route records. Uses a LOCAL AbortController: `preload` is
@@ -1076,11 +1137,20 @@ export function createRouter<TNames extends string = string>(
         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)
           }),
       )