@nifrajs/web 2.1.0 → 2.3.0

package/src/router.ts

@@ -1,5 +1,5 @@
 /**
- * The agnostic client-side router core — pure logic, no `window`, no framework. A per-adapter
+ * The agnostic client-side router core - pure logic, no `window`, no framework. A per-adapter
  * Router binding subscribes via `subscribe`/`snapshot` and renders the matched chain; a
  * browser-only `installHistory` (history + link interception) wires on top. Kept DOM-free so it
  * unit-tests without a browser and is safe to import from the SSR core's main entry.
@@ -9,7 +9,9 @@ import {
   compileRoutePattern,
   matchRoutePattern,
 } from "@nifrajs/core/pattern"
+import type { StandardSchemaV1 } from "@nifrajs/core/server"
 import { parseNdjsonData } from "./deferred.ts"
+import { isClientOnlySearchChange } from "./search.ts"
 
 /**
  * Request header that asks a nifra route's GET to return just the loader data as JSON (instead of
@@ -20,32 +22,98 @@ export const DATA_HEADER = "x-nifra-data"
 /**
  * Global the server injects (`createWebApp({ prerenderedPaths })`) listing the SSG-prerendered paths.
  * The client's default data fetch reads it: a soft-nav INTO a prerendered route fetches its static
- * `<path>/_data.json` (a CDN file — no worker round-trip) instead of the dynamic header-GET.
+ * `<path>/_data.json` (a CDN file - no worker round-trip) instead of the dynamic header-GET.
  */
 export const PRERENDERED_GLOBAL = "__NIFRA_PRERENDERED__"
 
 /**
  * Response header a data-mode action POST uses to convey a redirect (`redirect(...)`) to the
- * client — fetch would otherwise silently follow a 3xx to its HTML, losing the target. The
+ * client - fetch would otherwise silently follow a 3xx to its HTML, losing the target. The
  * client reads this and performs a client-side navigation instead.
  */
 export const REDIRECT_HEADER = "x-nifra-redirect"
 
 /**
  * Response header an action sets (via the `revalidate(paths, data)` helper) to tell the client which
- * routes the mutation changed — a comma-separated list of paths. After the submit, the client marks
+ * routes the mutation changed - a comma-separated list of paths. After the submit, the client marks
  * those cached routes stale (refetching any that are mounted) so a mutation can refresh views beyond
  * the active one. The client validates each path against the manifest matcher before acting on it.
  */
 export const REVALIDATE_HEADER = "x-nifra-revalidate"
 
+/**
+ * Response header carrying a **terminal status** a loader signalled with `notFound()` / `gone()` /
+ * `statusPage(n)` during a client-side navigation's data fetch.
+ *
+ * A soft-nav fetches data, not a document, so the server cannot answer by rendering the `_404` page -
+ * it has only JSON to return. Without this channel the two halves disagree: a crawler doing a hard
+ * navigation gets a correct 404 page while a user who clicked a link gets an error or a blank screen.
+ * The client reads it and renders the same boundary the server would have.
+ *
+ * Carried in a header rather than the body so it survives the NDJSON deferred-data path unchanged,
+ * exactly like {@link REDIRECT_HEADER}.
+ */
+export const STATUS_HEADER = "x-nifra-status"
+
+/**
+ * Layout indices a client navigation is asking the server NOT to re-run, comma separated.
+ *
+ * The client owns the decision because it holds both the old and new match plus each layout's scoped
+ * params. The server treats it as a hint and refuses to skip a `gate` regardless - a guard that runs
+ * only when the client says so is not a guard.
+ */
+export const RETAIN_HEADER = "x-nifra-retain"
+
+/**
+ * The path a client navigation is coming FROM, sent on the data-mode GET.
+ *
+ * Lets the SERVER decide which layout loaders to skip: it already knows each layout's scoped params
+ * (derived at build time), so given both paths it can tell whether a layout's own prefix changed.
+ * Doing it server-side means the client never needs the scope table, and the decision lives next to
+ * the data it is about.
+ *
+ * Sent only when the client actually holds layout data to retain, so a request without it is simply
+ * the full-chain case.
+ */
+export const NAV_FROM_HEADER = "x-nifra-from"
+
+/**
+ * The data-mode payload once a chain can carry layout data.
+ *
+ * Versioned because a prerendered `_data.json` is a static file on a CDN and outlives the deploy that
+ * wrote it: a browser running new client code can be handed an envelope written by the previous
+ * build. The reader therefore accepts BOTH the bare pre-envelope value and this shape, and decides by
+ * structure rather than by assuming the deploy was atomic.
+ */
+export interface RouteDataEnvelope {
+  readonly v: 1
+  readonly data: unknown
+  readonly layoutData?: readonly unknown[]
+  /** Indices whose loader was SKIPPED because the layout's own params did not change. The client
+   * keeps its existing value at each of these, so an unchanged layout is neither refetched nor lost. */
+  readonly retained?: readonly number[]
+  /** Terminal status signalled by a loader. Added by the browser transport after reading
+   * `X-Nifra-Status`; old servers and static data files simply omit it. */
+  readonly status?: number
+}
+
+/** Recognise the envelope without mistaking a plain loader object that happens to have a `data` key. */
+export function isRouteDataEnvelope(value: unknown): value is RouteDataEnvelope {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { v?: unknown }).v === 1 &&
+    "data" in value
+  )
+}
+
 /** A URL matched against the manifest patterns: which route + its extracted params. */
 export interface RouteMatch {
   readonly routeId: string
   readonly params: Record<string, string>
 }
 
-/** An in-flight client submit — the action it targets + the `FormData` being sent. Set while the
+/** An in-flight client submit - the action it targets + the `FormData` being sent. Set while the
  * submit is pending, cleared when it settles. A component reads `submission.formData` to render an
  * **optimistic** view (the expected result) before the server responds. */
 export interface Submission {
@@ -60,6 +128,9 @@ export interface RouterState {
   /** The current URL path (used to revalidate the active loader after an action). */
   readonly path: string
   readonly data: unknown
+  /** Per-layout loader data, aligned with the matched chain's leading layout prefix. Absent when no
+   * layout in that chain has a loader. */
+  readonly layoutData?: readonly unknown[] | undefined
   /** An action's data return after a client-side submit (cleared on navigation). */
   readonly actionData?: unknown
   /** True while a navigation or submit is in flight (drives loading UI). */
@@ -67,11 +138,11 @@ export interface RouterState {
   /** The path a navigation is transitioning TO while `pending` (cleared when it settles). Lets a
    * `NavLink` know whether its own `to` is the one loading; `undefined` when idle. */
   readonly pendingPath?: string | undefined
-  /** The in-flight submit (set during a `submit`, cleared when it settles) — for optimistic UI. */
+  /** The in-flight submit (set during a `submit`, cleared when it settles) - for optimistic UI. */
   readonly submission?: Submission
 }
 
-/** A route id paired with its nifra pattern (e.g. `":id"` segments) — the matcher input. */
+/** A route id paired with its nifra pattern (e.g. `":id"` segments) - the matcher input. */
 export interface RoutePattern {
   readonly routeId: string
   readonly pattern: string
@@ -89,7 +160,7 @@ export function createMatcher(
     .map((pattern) => ({ routeId: pattern.routeId, pattern: compileRoutePattern(pattern.pattern) }))
     .sort((left, right) => compareRoutePatternSpecificity(left.pattern, right.pattern))
   return (path) => {
-    // Strip the query without allocating a `split("?")` array — matcher runs per match.
+    // Strip the query without allocating a `split("?")` array - matcher runs per match.
     const q = path.indexOf("?")
     const clean = q === -1 ? path : path.slice(0, q)
     for (const c of compiled) {
@@ -110,6 +181,10 @@ export type FetchRouteData = (
   path: string,
   match: RouteMatch,
   signal?: AbortSignal,
+  navigation?: {
+    readonly from: string
+    readonly retain: readonly number[]
+  },
 ) => Promise<unknown>
 
 /** Per-submit options. `revalidate: false` opts out of the post-action loader re-fetch. */
@@ -119,7 +194,7 @@ export interface SubmitOptions {
   readonly revalidate?: boolean
 }
 
-/** A fetcher's observable state — independent of the main router. `pending` covers its in-flight
+/** A fetcher's observable state - independent of the main router. `pending` covers its in-flight
  * load/submit; `data` is its last `load()` result; `actionData` its last `submit()` result;
  * `submission` the in-flight submit (for optimistic UI). Client-only (never SSR'd). */
 export interface FetcherState {
@@ -131,7 +206,7 @@ export interface FetcherState {
 
 /**
  * An independent load/submit state machine, retrieved by `router.fetcher(key)`. Runs **concurrently**
- * with the main router and with other fetchers — each is single-flight against *itself* (its own
+ * with the main router and with other fetchers - each is single-flight against *itself* (its own
  * monotonic token), so N row-level mutations / side-channel loads can be in flight at once without
  * disturbing the active view. Loads/submits write the shared cache and honor `X-Nifra-Revalidate`.
  */
@@ -145,7 +220,7 @@ export interface Fetcher {
   load: (path: string) => Promise<void>
   /** Submit an action into this fetcher's own state; honors `X-Nifra-Revalidate` by refreshing the
    * active route + any mounted fetcher showing a changed path. Rejects on failure (caller falls back).
-   * (No `revalidate` opt-out — a fetcher has no active loader of its own to skip.) */
+   * (No `revalidate` opt-out - a fetcher has no active loader of its own to skip.) */
   submit: (action: string, body: NonNullable<RequestInit["body"]>) => Promise<void>
 }
 
@@ -161,7 +236,7 @@ export interface ClientRouter {
    * Submit an action (POST `body` to `action` in data mode): a redirect becomes a client
    * navigation; otherwise the data return is published as `actionData` and the active route's
    * loader is revalidated so the mutation is reflected. Pass `{ revalidate: false }` to SKIP that
-   * revalidation — keep the current `data` and just publish the action's `actionData` (useful when
+   * revalidation - keep the current `data` and just publish the action's `actionData` (useful when
    * the action already returned everything that changed, saving the extra round-trip). A redirect
    * always loads its target regardless. Rejects on failure (caller falls back).
    */
@@ -173,28 +248,28 @@ export interface ClientRouter {
   /**
    * Mark cached route data stale and refresh the active view. With `paths`, target exactly those
    * (e.g. the routes a mutation changed); without, invalidate the whole cache. The active route
-   * refreshes immediately — refetched + republished — whenever it's in scope (an explicit list that
+   * refreshes immediately - refetched + republished - whenever it's in scope (an explicit list that
    * includes it, or an invalidate-all); other stale entries refetch lazily when next read (a
    * fetcher, or the next navigation/access). Rejects if the active refetch fails (like `navigate`).
    * The keyed substrate for targeted revalidation (the `X-Nifra-Revalidate` header) and fetchers.
    */
   invalidate: (paths?: readonly string[]) => Promise<void>
   /**
-   * Warm a path's chunk + loader data into a bounded one-shot cache without publishing state —
+   * Warm a path's chunk + loader data into a bounded one-shot cache without publishing state -
    * a later `navigate` to it transitions with no network round-trip. Best-effort: failures and
    * unmatched paths are no-ops. Wired to link hover/focus by `installHistory`.
    */
   prefetch: (path: string) => Promise<void>
   /**
-   * Get (lazily creating) the stable {@link Fetcher} for `key` — an independent, concurrent
+   * Get (lazily creating) the stable {@link Fetcher} for `key` - an independent, concurrent
    * load/submit state machine for row-level mutations or side-channel loads that must not disturb
    * the active view. The same `key` always returns the same fetcher (so a binding can subscribe to a
    * stable store). Keys are app-chosen and typically stable (e.g. a row id).
    */
   fetcher: (key: string) => Fetcher
-  /** All live fetchers — for a global busy view (e.g. a `useFetchers` binding). */
+  /** All live fetchers - for a global busy view (e.g. a `useFetchers` binding). */
   fetchers: () => readonly Fetcher[]
-  /** Subscribe to any-fetcher-changed (a transition on any fetcher, or a new one created) — backs a
+  /** Subscribe to any-fetcher-changed (a transition on any fetcher, or a new one created) - backs a
    * `useFetchers` binding; returns an unsubscribe fn. */
   subscribeFetchers: (listener: () => void) => () => void
   /** Match a path against the manifest patterns (exposed for history/link wiring). */
@@ -209,6 +284,15 @@ export interface ClientRouterOptions {
   /** Ensure a route's code chunk is loaded before rendering (code-splitting). Awaited in parallel
    * with the loader data, so `pending` covers both. Omit when the bundle isn't split. */
   readonly loadModule?: (routeId: string) => Promise<void>
+  /** Terminal status → client route id. Generated entries populate this from `_404` and
+   * `_<status>` files so soft navigation renders the same boundary as a hard request. */
+  readonly statusRoutes?: Readonly<Record<number, string>>
+  /** routeId → the route's client-only search keys (its `searchClientKeys` export). When a soft
+   * navigation stays on the same route + pathname and changes ONLY these keys, `navigate` publishes the
+   * new URL WITHOUT re-running the loader (re-render, not revalidate). Populated lazily by the generated
+   * entry's `loadModule` (so a route's keys are present once it has been visited, which is exactly when a
+   * same-route nav can consult them). Omit ⇒ every search change revalidates (the safe default). */
+  readonly searchClientKeys?: Readonly<Record<string, readonly string[]>>
 }
 
 /** Options for a per-adapter `mountRouter` (the Router binding that hydrates + re-renders). */
@@ -216,13 +300,20 @@ export interface MountRouterOptions {
   readonly router: ClientRouter
   /** routeId → layout chain (outermost layout → page); built by `generateClientEntry`. */
   readonly routes: Record<string, readonly unknown[]>
-  /** Hydration container (opaque — the adapter casts it to its DOM element type). */
+  /** routeId → the route's search-schema CHAIN (its layout chain's `searchSchema` exports, outermost
+   * first, then the page's; each entry `undefined` when that module declares none); built by
+   * `generateClientEntry`. The mount derives each route's typed `search` from this chain plus the URL via
+   * `searchOfChain` (layout keys merged with page keys, page-wins), matching the server's
+   * `ctx.search`/`RenderProps.search`. Omitted by callers with no typed search (tests, a hand-built mount)
+   * ⇒ every route sees the raw parsed query. */
+  readonly searchSchemas?: Readonly<Record<string, readonly (StandardSchemaV1 | undefined)[]>>
+  /** Hydration container (opaque - the adapter casts it to its DOM element type). */
   readonly container: unknown
 }
 
 /** Read a nifra data response: a deferred loader/action streams NDJSON (parse line 1 + settle
  * `<Await>` markers as resolution lines arrive); a non-deferred one returns a single JSON. Shared by
- * navigation fetches and action submits — both transports are identical. */
+ * navigation fetches and action submits - both transports are identical. */
 const readResponseData = (res: Response, signal?: AbortSignal): Promise<unknown> =>
   (res.headers.get("content-type") ?? "").includes("application/x-ndjson") && res.body !== null
     ? parseNdjsonData(res.body, signal)
@@ -233,8 +324,8 @@ const readResponseData = (res: Response, signal?: AbortSignal): Promise<unknown>
 const dataUrlFor = (pathname: string): string =>
   pathname === "/" ? "/_data.json" : `${pathname.replace(/\/+$/, "")}/_data.json`
 
-const defaultFetchData: FetchRouteData = async (path, _match, signal) => {
-  // SSG fast path: if this path was prerendered, its loader data is a static file — fetch that (no
+const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation) => {
+  // SSG fast path: if this path was prerendered, its loader data is a static file - fetch that (no
   // worker). Falls through to the dynamic header-GET on any miss (file absent, e.g. a deferred route,
   // or a stale set), so it's always safe. Non-SSG apps have no global → the dynamic path, unchanged.
   const prerendered = (globalThis as { [PRERENDERED_GLOBAL]?: unknown })[PRERENDERED_GLOBAL]
@@ -245,7 +336,16 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal) => {
       if (staticRes.ok) return readResponseData(staticRes, signal)
     }
   }
-  const res = await fetch(path, { headers: { [DATA_HEADER]: "1" }, signal: signal ?? null })
+  const headers = new Headers({ [DATA_HEADER]: "1" })
+  if (navigation !== undefined && navigation.retain.length > 0) {
+    headers.set(RETAIN_HEADER, navigation.retain.join(","))
+    headers.set(NAV_FROM_HEADER, navigation.from)
+  }
+  const res = await fetch(path, { headers, signal: signal ?? null })
+  const status = Number(res.headers.get(STATUS_HEADER))
+  if (Number.isInteger(status) && status >= 400 && status <= 599) {
+    return { v: 1, data: null, status } satisfies RouteDataEnvelope
+  }
   if (!res.ok) throw new Error(`[nifra/web] navigation data fetch failed (${res.status}): ${path}`)
   return readResponseData(res, signal)
 }
@@ -255,9 +355,72 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal) => {
  * navigations overlap, only the latest result is applied (rapid clicks don't flash stale data).
  * A failed fetch clears `pending` and rethrows so the caller can fall back to a full-page load.
  */
+// Split a `pathname + search` into its two parts. `rawSearchOf` keeps the leading `?` (what
+// `parseSearch` accepts); an empty query yields `""`.
+const pathnameOf = (path: string): string => {
+  const q = path.indexOf("?")
+  return q === -1 ? path : path.slice(0, q)
+}
+const rawSearchOf = (path: string): string => {
+  const q = path.indexOf("?")
+  return q === -1 ? "" : path.slice(q)
+}
+
 export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   const match = createMatcher(options.patterns)
   const fetchData = options.fetchData ?? defaultFetchData
+  // routeId → the route's client-only search keys. Read by reference (the generated entry keeps writing
+  // to it as routes load), so a same-route nav always sees the current route's keys.
+  const searchClientKeys = options.searchClientKeys ?? {}
+  /**
+   * Fetch a route's data and normalise it.
+   *
+   * The payload is either the versioned envelope (a chain with layout loaders) or the bare loader
+   * value (everything else, and every response written before layout loaders existed). Deciding by
+   * structure rather than by version-of-the-deploy is what lets a prerendered `_data.json` written by
+   * an older build be read by newer client code.
+   */
+  type LoadedRouteData = {
+    readonly data: unknown
+    readonly layoutData?: readonly unknown[] | undefined
+    readonly terminalRouteId?: string | undefined
+  }
+  const loadRouteData = async (
+    path: string,
+    match: { routeId: string; params: Record<string, string> },
+    signal?: AbortSignal,
+    retainFrom?: { readonly path: string; readonly layoutData: readonly unknown[] },
+  ): Promise<LoadedRouteData> => {
+    const retain = retainFrom?.layoutData.map((_, index) => index) ?? []
+    const payload = await fetchData(
+      path,
+      match,
+      signal,
+      retainFrom === undefined ? undefined : { from: retainFrom.path, retain },
+    )
+    if (!isRouteDataEnvelope(payload)) return { data: payload }
+    if (payload.status !== undefined) {
+      const terminalRouteId = options.statusRoutes?.[payload.status] ?? options.statusRoutes?.[404]
+      if (terminalRouteId === undefined) {
+        throw new Error(
+          `[nifra/web] no client status boundary is available for terminal status ${payload.status}`,
+        )
+      }
+      return { data: null, terminalRouteId }
+    }
+    if (retainFrom === undefined || payload.retained === undefined) {
+      return { data: payload.data, layoutData: payload.layoutData }
+    }
+    const retained = new Set(
+      payload.retained.filter(
+        (index) => Number.isInteger(index) && index >= 0 && index < retainFrom.layoutData.length,
+      ),
+    )
+    const layoutData = payload.layoutData?.map((value, index) =>
+      retained.has(index) ? retainFrom.layoutData[index] : value,
+    )
+    return { data: payload.data, layoutData }
+  }
   const loadModule = options.loadModule
   let state = options.initial
   const listeners = new Set<() => void>()
@@ -272,21 +435,26 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // Bounded one-shot prefetch cache (path → loader data) + an in-flight guard so hover spam
   // doesn't double-fetch. Consumed (and dropped) by the next navigate to that path.
   const MAX_PREFETCH = 10
-  const prefetched = new Map<string, unknown>()
+  const prefetched = new Map<string, LoadedRouteData>()
   const inflight = new Set<string>()
   // Keyed data cache (path → latest loader data + freshness). Written on every published data
   // (navigate/submit), read by `invalidate` (+ targeted revalidation and fetchers in later F16
-  // increments). Bounded — evict the oldest-inserted past the cap (route data is small; this just
+  // increments). Bounded - evict the oldest-inserted past the cap (route data is small; this just
   // caps memory). `status` is the staleness ledger: `invalidate` flips entries to `stale`; readers
-  // refetch stale ones. Client-only — never serialized/hydrated.
+  // refetch stale ones. Client-only - never serialized/hydrated.
   const MAX_CACHE = 50
-  const cache = new Map<string, { data: unknown; status: "fresh" | "stale" }>()
-  const cachePut = (path: string, data: unknown): void => {
+  const cache = new Map<
+    string,
+    { data: unknown; layoutData?: readonly unknown[] | undefined; status: "fresh" | "stale" }
+  >()
+  const cachePut = (path: string, loaded: LoadedRouteData): void => {
     if (!cache.has(path) && cache.size >= MAX_CACHE) {
       const oldest = cache.keys().next().value
       if (oldest !== undefined) cache.delete(oldest)
     }
-    cache.set(path, { data, status: "fresh" })
+    // The PAIR, not just the value: navigating back to a cached route must restore its layouts' data
+    // too, or they would render empty on a hit and populated on a miss.
+    cache.set(path, { data: loaded.data, layoutData: loaded.layoutData, status: "fresh" })
   }
   // Flip cached entries to stale (a no-op for paths not in the cache). Shared by `invalidate` and the
   // `X-Nifra-Revalidate` handling in `submit`.
@@ -297,7 +465,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     }
   }
   // Parse the `X-Nifra-Revalidate` response header into validated paths. The header is response data
-  // (a trust boundary), so each path must match a real manifest pattern — unknown/garbage is dropped
+  // (a trust boundary), so each path must match a real manifest pattern - unknown/garbage is dropped
   // and never triggers a fetch.
   const parseRevalidate = (header: string | null): string[] =>
     header === null
@@ -320,14 +488,14 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     state = { ...state, pending: true }
     emit()
     try {
-      const data = await fetchData(
+      const loaded = await loadRouteData(
         state.path,
         { routeId: state.routeId, params: state.params },
         ac.signal,
       )
-      if (mine !== token) return // superseded — drop the stale result
-      cachePut(state.path, data)
-      state = { ...state, data, pending: false }
+      if (mine !== token) return // superseded - drop the stale result
+      cachePut(state.path, loaded)
+      state = { ...state, data: loaded.data, layoutData: loaded.layoutData, pending: false }
       emit()
     } catch (err) {
       if (mine === token) {
@@ -359,7 +527,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
 
   // Best-effort refresh of every MOUNTED reader of `paths`: the active route (unless `skipActive`,
   // when the caller already refetched it) + any fetcher that loaded one of these paths. Errors are
-  // swallowed — a failed targeted refresh must not fail the mutation that triggered it.
+  // swallowed - a failed targeted refresh must not fail the mutation that triggered it.
   const refreshMounted = async (paths: readonly string[], skipActive: boolean): Promise<void> => {
     const jobs: Promise<void>[] = []
     if (!skipActive && paths.includes(state.path)) jobs.push(refetchActive().catch(() => {}))
@@ -387,17 +555,17 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       fState = { ...fState, pending: true }
       fEmit()
       try {
-        const [, data] = await Promise.all([
+        const [, loaded] = await Promise.all([
           loadModule?.(matched.routeId),
-          fetchData(path, matched, ac.signal),
+          loadRouteData(path, matched, ac.signal),
         ])
         if (mine !== fToken) return // a newer load/submit on THIS fetcher superseded us
-        // Record the loaded path only on SUCCESS — a thrown or superseded load must not
+        // Record the loaded path only on SUCCESS - a thrown or superseded load must not
         // leave `loadedPath` pointing at a path this fetcher never actually showed, or a later
         // `X-Nifra-Revalidate` for it would spuriously refetch onto unexpected data.
         loadedPath = path
-        cachePut(path, data)
-        fState = { ...fState, data, pending: false }
+        cachePut(path, loaded)
+        fState = { ...fState, data: loaded.data, pending: false }
         fEmit()
       } catch (err) {
         if (mine === fToken) {
@@ -418,7 +586,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       load: runLoad,
       submit: async (action, body) => {
         const mine = ++fToken
-        // Abort any prior in-flight load/submit on THIS fetcher (its fetch + NDJSON drain) — like
+        // Abort any prior in-flight load/submit on THIS fetcher (its fetch + NDJSON drain) - like
         // `runLoad` does for a superseding load. The mutation POST is left to complete; the
         // signal cancels the follow-up data drain if a newer op supersedes this one.
         fAbort?.abort()
@@ -442,7 +610,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           // Publish the fetcher's actionData; clear `submission` (the optimistic window is over).
           fState = { pending: false, data: fState.data, actionData }
           fEmit()
-          // A fetcher has no loader of its own — its mutation's freshness flows through the cache:
+          // A fetcher has no loader of its own - its mutation's freshness flows through the cache:
           // mark the changed routes stale + refresh every mounted reader (active route + fetchers).
           if (changed.length > 0) {
             markStale(changed)
@@ -479,6 +647,27 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     navigate: async (path) => {
       const matched = match(path)
       if (matched === null) return
+      // Client-only search fast path: same route + same pathname, and every changed search key is
+      // declared client-only. Publish the new URL (so `useSearch`/`useLocation` update) WITHOUT a data
+      // fetch - the loader's inputs did not change. Any loader-affecting key change falls through to the
+      // normal match → fetch → publish below, so data is never stale. Abort an in-flight fetch first: a
+      // rapid `?tab` after a real nav must not let the older fetch overwrite this synchronous update.
+      if (
+        matched.routeId === state.routeId &&
+        pathnameOf(path) === pathnameOf(state.path) &&
+        isClientOnlySearchChange(
+          rawSearchOf(state.path),
+          rawSearchOf(path),
+          searchClientKeys[state.routeId] ?? [],
+        )
+      ) {
+        ++token // supersede any in-flight navigation so its late result is dropped
+        navAbort?.abort()
+        cachePut(path, { data: state.data, layoutData: state.layoutData })
+        state = { ...state, path, pending: false, pendingPath: undefined }
+        emit()
+        return
+      }
       const mine = ++token
       navAbort?.abort() // abandon any in-flight navigation's stream
       const ac = new AbortController()
@@ -486,27 +675,36 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       state = { ...state, pending: true, pendingPath: path }
       emit()
       try {
-        // Use prefetched data when present (one-shot — drop it); else fetch. The chunk is loaded
+        // Use prefetched data when present (one-shot - drop it); else fetch. The chunk is loaded
         // either way (cached + instant after a prefetch), so pending covers both.
         const hit = prefetched.has(path)
         const dataPromise = hit
-          ? Promise.resolve(prefetched.get(path))
-          : fetchData(path, matched, ac.signal)
+          ? Promise.resolve(prefetched.get(path) as LoadedRouteData)
+          : loadRouteData(
+              path,
+              matched,
+              ac.signal,
+              state.layoutData === undefined
+                ? undefined
+                : { path: state.path, layoutData: state.layoutData },
+            )
         if (hit) prefetched.delete(path)
-        const [, data] = await Promise.all([loadModule?.(matched.routeId), dataPromise])
-        if (mine !== token) return // a newer navigation superseded this one — drop the stale result
-        cachePut(path, data) // keep the keyed cache coherent with what we publish
+        const [, loaded] = await Promise.all([loadModule?.(matched.routeId), dataPromise])
+        if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
+        if (mine !== token) return // a newer navigation superseded this one - drop the stale result
+        cachePut(path, loaded) // keep the keyed cache coherent with what we publish
         state = {
-          routeId: matched.routeId,
-          params: matched.params,
+          routeId: loaded.terminalRouteId ?? matched.routeId,
+          params: loaded.terminalRouteId === undefined ? matched.params : {},
           path,
-          data,
+          data: loaded.data,
+          layoutData: loaded.layoutData,
           actionData: undefined, // a fresh navigation has no action result
           pending: false,
         }
         emit()
       } catch (err) {
-        // Clear our pending flag + target (only if still current) and rethrow — the caller decides how
+        // Clear our pending flag + target (only if still current) and rethrow - the caller decides how
         // to recover (the history layer falls back to a full-page navigation).
         if (mine === token) {
           state = { ...state, pending: false, pendingPath: undefined }
@@ -518,7 +716,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     submit: async (action, body, opts) => {
       const mine = ++token
       // A superseding navigation/submit aborts this submit's FOLLOW-UP reads (revalidation / redirect
-      // fetch + their NDJSON drains) — not the mutation POST itself, which should complete.
+      // fetch + their NDJSON drains) - not the mutation POST itself, which should complete.
       // Wire into `navAbort` like `navigate`/`refetchActive`, so a later nav cancels the in-flight read.
       navAbort?.abort()
       const ac = new AbortController()
@@ -536,58 +734,72 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         if (!res.ok) throw new Error(`[nifra/web] action failed (${res.status}): ${action}`)
         const redirectTo = res.headers.get(REDIRECT_HEADER)
         if (redirectTo !== null) {
-          // The action redirected (Post/Redirect/Get) — treat it as a client navigation.
+          // The action redirected (Post/Redirect/Get) - treat it as a client navigation.
           const target = match(redirectTo)
           if (target === null)
             throw new Error(`[nifra/web] action redirect off-route: ${redirectTo}`)
-          const [, data] = await Promise.all([
+          const [, loaded] = await Promise.all([
             loadModule?.(target.routeId),
-            fetchData(redirectTo, target, ac.signal),
+            loadRouteData(
+              redirectTo,
+              target,
+              ac.signal,
+              state.layoutData === undefined
+                ? undefined
+                : { path: state.path, layoutData: state.layoutData },
+            ),
           ])
+          if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
           if (mine !== token) return
-          cachePut(redirectTo, data)
+          cachePut(redirectTo, loaded)
           state = {
-            routeId: target.routeId,
-            params: target.params,
+            routeId: loaded.terminalRouteId ?? target.routeId,
+            params: loaded.terminalRouteId === undefined ? target.params : {},
             path: redirectTo,
-            data,
+            data: loaded.data,
+            layoutData: loaded.layoutData,
             actionData: undefined,
             pending: false,
           }
           emit()
           return
         }
-        // The action's data — streamed NDJSON if it `defer()`'d slow parts (markers settle as lines
+        // The action's data - streamed NDJSON if it `defer()`'d slow parts (markers settle as lines
         // arrive, for `<Await actionData>`), else one JSON. Abortable so a superseding nav cancels the
         // drain.
         const actionData = res.status === 204 ? undefined : await readResponseData(res, ac.signal)
         // Routes the action declared changed (via the `revalidate()` helper → `X-Nifra-Revalidate`),
         // validated against the manifest.
         const changed = parseRevalidate(res.headers.get(REVALIDATE_HEADER))
-        // Revalidate the active route's loader so the mutation is reflected — unless the caller opted
+        // Revalidate the active route's loader so the mutation is reflected - unless the caller opted
         // out (`revalidate: false`). A server-declared revalidate of the active path overrides the
         // opt-out (the server says it changed, so stale data would be wrong). Default is to revalidate.
         const skipActive = opts?.revalidate === false && !changed.includes(state.path)
-        const data = skipActive
-          ? state.data
-          : await fetchData(state.path, { routeId: state.routeId, params: state.params }, ac.signal)
+        const loaded = skipActive
+          ? { data: state.data, layoutData: state.layoutData }
+          : await loadRouteData(
+              state.path,
+              { routeId: state.routeId, params: state.params },
+              ac.signal,
+            )
         if (mine !== token) return
-        cachePut(state.path, data) // the revalidated (or kept) data is now the cache's truth
+        cachePut(state.path, loaded) // the revalidated (or kept) data is now the cache's truth
         // Mark the OTHER changed routes stale so the next access refetches.
         markStale(changed.filter((p) => p !== state.path))
         // Reconcile: publish the revalidated data + actionData; omit `submission` (the optimistic
-        // window is over — the real data now drives the view).
+        // window is over - the real data now drives the view).
         state = {
           routeId: state.routeId,
           params: state.params,
           path: state.path,
-          data,
+          data: loaded.data,
+          layoutData: loaded.layoutData,
           actionData,
           pending: false,
         }
         emit()
         // Refresh any mounted fetcher showing one of the changed routes (the active route was just
-        // revalidated inline above, so skip it here). Best-effort — never rejects the submit.
+        // revalidated inline above, so skip it here). Best-effort - never rejects the submit.
         await refreshMounted(changed, true)
       } catch (err) {
         if (mine === token) {
@@ -607,11 +819,11 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       }
     },
     invalidate: async (paths) => {
-      // Mark targeted cache entries stale (all entries when no `paths`) — unmounted ones refetch
+      // Mark targeted cache entries stale (all entries when no `paths`) - unmounted ones refetch
       // lazily on next access.
       const targets = paths ?? [...cache.keys()]
       markStale(targets)
-      // Refresh mounted readers now: the active route (when in scope — an explicit list including it,
+      // Refresh mounted readers now: the active route (when in scope - an explicit list including it,
       // or an invalidate-all) + any fetcher showing a targeted path. The active refetch rejects on
       // failure (the caller asked to refresh); fetcher refreshes are best-effort (swallowed).
       const jobs: Promise<void>[] = []
@@ -625,15 +837,17 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       if (matched === null) return
       inflight.add(path)
       try {
-        const [, data] = await Promise.all([
+        // Unwrapped here, so a prefetched entry is the same shape `navigate` builds state from -
+        // otherwise a prefetch hit would publish an envelope where a miss publishes loader data.
+        const [, loaded] = await Promise.all([
           loadModule?.(matched.routeId),
-          fetchData(path, matched),
+          loadRouteData(path, matched),
         ])
         if (prefetched.size >= MAX_PREFETCH) {
           const oldest = prefetched.keys().next().value
           if (oldest !== undefined) prefetched.delete(oldest)
         }
-        prefetched.set(path, data)
+        prefetched.set(path, loaded)
       } catch {
         // Best-effort: a failed prefetch just means the eventual navigate fetches normally.
       } finally {
@@ -645,7 +859,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       if (existing !== undefined) return existing.fetcher
       const entry = createFetcher()
       fetchers.set(key, entry)
-      emitFetchers() // a new fetcher appeared — wake any `useFetchers` subscriber
+      emitFetchers() // a new fetcher appeared - wake any `useFetchers` subscriber
       return entry.fetcher
     },
     fetchers: () => fetchersArr,