@nifrajs/web 5.5.1 → 5.7.0

package/src/router.ts

@@ -7,10 +7,13 @@
 import { decodeRouteParams } from "@nifrajs/core/pattern"
 import { Router as CoreRouter } from "@nifrajs/core/router"
 import type { StandardSchemaV1 } from "@nifrajs/core/server"
-import type { BoundaryDescriptor, BoundaryStates } from "./boundary.ts"
+import type { BoundaryDescriptor, BoundaryState, BoundaryStates } from "./boundary.ts"
 import { parseNdjsonData } from "./deferred.ts"
+import { epochOf, IDENTITY_CHANNEL, onIdentityChange } from "./identity.ts"
+import { present } from "./internal/present.ts"
 import { parsePageData } from "./internal/revive-dates.ts"
 import { appUrl, requestPattern } from "./internal/route-path.ts"
+import { shareData } from "./internal/share-data.ts"
 import type { ClientActionResult, ClientRequestBody, ClientRouteHooks } from "./manifest.ts"
 import type { MatchChain } from "./render-seam.ts"
 import { isClientOnlySearchChange } from "./search.ts"
@@ -21,6 +24,12 @@ import { isClientOnlySearchChange } from "./search.ts"
  */
 export const DATA_HEADER = "x-nifra-data"
 
+/**
+ * Sent beside {@link DATA_HEADER} by a prefetch. A partially prerendered route answers it with its
+ * shell data and starts no hole: nothing could cancel that work if the link is never followed.
+ */
+export const PREFETCH_HEADER = "x-nifra-prefetch"
+
 /**
  * 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
@@ -84,6 +93,20 @@ export const RETAIN_HEADER = "x-nifra-retain"
  */
 export const NAV_FROM_HEADER = "x-nifra-from"
 
+/**
+ * Sent on a data request that reloads the route instance on screen: the holes, comma separated, whose
+ * hosts the partially prerendered page holds. Each one's state then carries its fill (server HTML,
+ * plus props when it hydrates) instead of its data, so the client updates the host in place.
+ */
+export const HOLE_FILL_HEADER = "x-nifra-hole-fill"
+
+/**
+ * Holes of a partially prerendered page the client keeps, comma separated: they are not loaded, and
+ * each state says so. Only the live load endpoint sets it, for holes whose keys did not change. A name
+ * the route does not declare is refused with a 400.
+ */
+export const KEEP_HOLES_HEADER = "x-nifra-keep-holes"
+
 /**
  * The data-mode payload once a chain can carry layout data.
  *
@@ -105,6 +128,8 @@ export interface RouteDataEnvelope {
   /** 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
+  /** A live load's handle, carried through to {@link RouterState.live} untouched. */
+  readonly live?: unknown
 }
 
 /** Recognise the envelope without mistaking a plain loader object that happens to have a `data` key. */
@@ -136,7 +161,8 @@ export interface RouterState {
   readonly serverComponents?: import("./server-components/types.ts").ComponentState | undefined
   readonly routeId: string
   readonly params: Record<string, string>
-  /** The current URL path (used to revalidate the active loader after an action). */
+  /** The current URL path (used to revalidate the active loader after an action). While
+   * {@link intercepted} is set it is the target shown in the boundary, not the page's own. */
   readonly path: string
   readonly data: unknown
   /** Per-layout loader data, aligned with the matched chain's leading layout prefix. Absent when no
@@ -154,6 +180,33 @@ export interface RouterState {
   readonly pendingPath?: string | undefined
   /** The in-flight submit (set during a `submit`, cleared when it settles) - for optimistic UI. */
   readonly submission?: Submission
+  /** Set while an intercept boundary shows a navigation's target over the page: the boundary holding
+   * it, and the path the page underneath was loaded from. The page revalidates under `pagePath`, the
+   * boundary under `path`. */
+  readonly intercepted?: Intercepted
+  /** Opaque: which live load the page data on screen came from (`@nifrajs/web/live-client`). */
+  readonly live?: unknown
+  /** The page instance on screen, when the app keeps pages alive (`@nifrajs/web/keep-alive`). */
+  readonly instance?: string | undefined
+  /** Pages kept mounted and hidden, least recently shown first. Absent when none is kept. */
+  readonly kept?: readonly KeptPage[] | undefined
+  /** This publish showed a kept page again. */
+  readonly restored?: boolean | undefined
+  /** A page shown again is reloading its data in place: not a navigation, so `pending` stays false. */
+  readonly revalidating?: boolean | undefined
+}
+
+/** A page kept mounted while its history entry is not the one on screen. */
+export interface KeptPage {
+  readonly instance: string
+  /** Its last settled state, which it renders from while hidden. */
+  readonly state: RouterState
+}
+
+/** Which intercept boundary is open, and the page underneath it. */
+export interface Intercepted {
+  readonly boundary: string
+  readonly pagePath: string
 }
 
 /** A route id paired with its nifra pattern (e.g. `":id"` segments) - the matcher input. */
@@ -194,8 +247,22 @@ export function createMatcher(
   }
 }
 
+/**
+ * What the router knows about the response text a path's data on screen was read from. The router's
+ * own transport resolves a reload answering that same text to this object itself, and the router keeps
+ * the data on screen without parsing it; for any other plain JSON response it records the text in
+ * `text`. A response with deferred parts sets neither, and a custom transport may ignore it.
+ */
+export interface DataText {
+  readonly previous: string | undefined
+  text?: string
+}
+
 /** How a router fetches a route's loader data on navigation. `signal` aborts a superseded fetch
- * (and its deferred stream). */
+ * (and its deferred stream). `purpose` is `"prefetch"` when no navigation is waiting on the result.
+ * `hosts` names the holes of the page on screen whose hosts reload in place
+ * ({@link HOLE_FILL_HEADER}). `read` is the {@link DataText} of the data on screen, which a custom
+ * transport may ignore. */
 export type FetchRouteData = (
   path: string,
   match: RouteMatch,
@@ -204,6 +271,9 @@ export type FetchRouteData = (
     readonly from: string
     readonly retain: readonly number[]
   },
+  purpose?: "prefetch",
+  hosts?: readonly string[],
+  read?: DataText,
 ) => Promise<unknown>
 
 /** Per-submit options. `revalidate: false` opts out of the post-action loader re-fetch. */
@@ -265,7 +335,8 @@ export interface ClientRouter {
    * 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); once the server has
    * answered, at any status, the rejection's `redirectTo` names the page to load instead of posting
-   * again.
+   * again. A revalidation answered with a terminal status renders that status route in the page's
+   * place.
    */
   submit: (
     action: string,
@@ -280,6 +351,8 @@ export interface ClientRouter {
    * 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`).
+   * A refetch answered with a terminal status renders that status route in the page's place; one
+   * whose status page renders inside layouts rejects, so the caller can load the page as a document.
    * The keyed substrate for targeted revalidation (the `X-Nifra-Revalidate` header) and fetchers.
    */
   invalidate: (paths?: readonly string[]) => Promise<void>
@@ -354,10 +427,19 @@ export interface MountRouterOptions {
 /** 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. */
-const readResponseData = (res: Response, signal?: AbortSignal): Promise<unknown> =>
+const readResponseData = (
+  res: Response,
+  signal?: AbortSignal,
+  read?: DataText,
+): Promise<unknown> =>
   (res.headers.get("content-type") ?? "").includes("application/x-ndjson") && res.body !== null
     ? parseNdjsonData(res.body, signal)
-    : res.text().then(parsePageData)
+    : res.text().then((text) => {
+        if (read === undefined) return parsePageData(text)
+        if (text === read.previous) return read
+        read.text = text
+        return parsePageData(text)
+      })
 
 // Index scan, not `/\/+$/` - the unanchored-start trailing-run replace backtracks quadratically and
 // the pathname is caller-controlled.
@@ -418,7 +500,36 @@ const targetUrl = (to: string): URL | undefined => {
 const redirected = (to: string, cause?: unknown): Error =>
   Object.assign(new Error(`[nifra/web] redirected to ${to}`, { cause }), { redirectTo: to })
 
-const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation) => {
+/**
+ * A route data response as `fetchData` resolves it: a loader's in-app redirect rejects with its
+ * target, a terminal status becomes an envelope carrying it, and any other failure rejects.
+ */
+export const routeDataOf = async (
+  res: Response,
+  path: string,
+  signal?: AbortSignal,
+  read?: DataText,
+): Promise<unknown> => {
+  const redirectTo = res.headers.get(REDIRECT_HEADER)
+  if (redirectTo !== null) throw redirected(redirectTo)
+  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, read)
+}
+
+/** The router's own transport, which a `fetchData` override may layer over. */
+export const fetchRouteData: FetchRouteData = async (
+  path,
+  _match,
+  signal,
+  navigation,
+  purpose,
+  hosts,
+  read,
+) => {
   // 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.
@@ -432,23 +543,22 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation
     const pathname = hash === -1 ? path : path.slice(0, hash)
     if (prerenderedSetOf(prerendered).has(pathname)) {
       const staticRes = await fetch(appUrl(dataUrlFor(pathname)), { signal: signal ?? null })
-      if (staticRes.ok) return readResponseData(staticRes, signal)
+      if (staticRes.ok) return readResponseData(staticRes, signal, read)
     }
   }
   const headers = new Headers({ [DATA_HEADER]: "1" })
+  if (purpose === "prefetch") headers.set(PREFETCH_HEADER, "1")
+  if (hosts !== undefined && hosts.length > 0) headers.set(HOLE_FILL_HEADER, hosts.join(","))
   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(appUrl(path), { headers, signal: signal ?? null })
-  const redirectTo = res.headers.get(REDIRECT_HEADER)
-  if (redirectTo !== null) throw redirected(redirectTo)
-  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)
+  return routeDataOf(
+    await fetch(appUrl(path), { headers, signal: signal ?? null }),
+    path,
+    signal,
+    read,
+  )
 }
 
 /**
@@ -474,9 +584,9 @@ const isClientActionResult = (value: unknown): value is ClientActionResult =>
 
 export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   const match = createMatcher(options.patterns)
-  const fetchData = options.fetchData ?? defaultFetchData
+  const fetchData = options.fetchData ?? fetchRouteData
   // Start a handed-over list's fetch now, so the first navigation rarely waits for it.
-  if (fetchData === defaultFetchData) prerenderedOf()
+  if (fetchData === fetchRouteData) prerenderedOf()
   // 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 ?? {}
@@ -535,31 +645,96 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     readonly layoutData?: readonly unknown[] | undefined
     readonly terminalRouteId?: string | undefined
     readonly boundaries?: BoundaryStates
+    readonly live?: unknown
+    /** The response text this was read from, when it was plain JSON. */
+    readonly text?: string | undefined
   }
   const dataFields = (value: LoadedRouteData) => ({
     data: value.data,
     layoutData: value.layoutData,
     serverComponents: value.serverComponents,
+    live: value.live,
     ...(value.boundaries === undefined ? {} : { boundaries: value.boundaries }),
   })
+  // The path the page on screen was loaded from. While a boundary holds an intercepted target, `path`
+  // is that target's URL, so anything that reloads or caches the page must read this instead.
+  const pagePathOf = (current: RouterState): string => current.intercepted?.pagePath ?? current.path
+  // `boundaries` with `name` holding a target's outcome. The URL names one target, so every other
+  // intercept boundary goes back to unresolved. A target that answered with a status, or failed, is
+  // an error state: its data never reaches the boundary.
+  const holdTarget = (
+    boundaries: BoundaryStates | undefined,
+    descriptor: Omit<BoundaryDescriptor, "hasLoad">,
+    outcome: LoadedRouteData | undefined,
+  ): BoundaryStates => {
+    const next: Record<string, BoundaryState> = {}
+    for (const [name, boundary] of Object.entries(boundaries ?? {})) {
+      next[name] =
+        typeof boundary.mode === "string" || name === descriptor.name
+          ? boundary
+          : {
+              name: boundary.name,
+              mode: boundary.mode,
+              status: "unresolved",
+              ...(boundary.errorId === undefined ? {} : { errorId: boundary.errorId }),
+            }
+    }
+    const base = {
+      name: descriptor.name,
+      mode: descriptor.mode,
+      ...(descriptor.errorId === undefined ? {} : { errorId: descriptor.errorId }),
+    }
+    next[descriptor.name] =
+      outcome === undefined || outcome.terminalRouteId !== undefined
+        ? { ...base, status: "error", error: { name: "Error", message: "Boundary failed" } }
+        : { ...base, status: "ready", data: outcome.data, live: outcome.live }
+    return next
+  }
+  // `boundaries` with `name`'s action result set (or cleared, for `undefined`). Only a boundary showing
+  // its target's data carries one.
+  const withActionData = (
+    boundaries: BoundaryStates | undefined,
+    name: string,
+    actionData: unknown,
+  ): BoundaryStates | undefined => {
+    const held = boundaries?.[name]
+    if (held === undefined || held.status !== "ready") return boundaries
+    const { actionData: _previous, ...rest } = held
+    return { ...boundaries, [name]: actionData === undefined ? rest : { ...rest, actionData } }
+  }
   const loadRouteData = async (
     path: string,
     match: { routeId: string; params: Record<string, string> },
     signal?: AbortSignal,
     // Offer the server the layout data on screen: it re-runs whichever of those loaders it must.
     keepLayouts?: boolean,
+    purpose?: "prefetch",
+    hosts?: readonly string[],
+    // What this path shows, when this is a reload of it: the same response text again is that, unparsed.
+    shown?: LoadedRouteData,
   ): Promise<LoadedRouteData> => {
     const retainFrom = keepLayouts
-      ? state.layoutData && { path: state.path, layoutData: state.layoutData }
+      ? state.layoutData && { path: pagePathOf(state), layoutData: state.layoutData }
       : undefined
     const retain = retainFrom?.layoutData.map((_, index) => index) ?? []
+    const hooks = routeHooks[match.routeId]
+    // A client loader's output is not what the text says, and an opted-out route takes fresh data.
+    const read: DataText = {
+      previous:
+        hooks?.clientLoader === undefined && hooks?.shareData !== false ? shown?.text : undefined,
+    }
     const payload = await fetchData(
       path,
       match,
       signal,
       retainFrom === undefined ? undefined : { from: retainFrom.path, retain },
+      purpose,
+      hosts,
+      read,
     )
-    if (!isRouteDataEnvelope(payload)) return { data: payload }
+    if (shown !== undefined && payload === read) return shown
+    const text = read.text
+    if (!isRouteDataEnvelope(payload)) return { data: payload, text }
     if (payload.status !== undefined) {
       const terminalRouteId = options.statusRoutes?.[payload.status] ?? options.statusRoutes?.[404]
       if (terminalRouteId === undefined) {
@@ -584,7 +759,31 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       data: payload.data,
       layoutData,
       serverComponents: payload.serverComponents,
+      live: payload.live,
       ...(payload.boundaries !== undefined ? { boundaries: payload.boundaries } : {}),
+      text,
+    }
+  }
+  // A reload with every part equal to what its path shows replaced by that part, so what the reload
+  // did not change keeps its identity on screen (`shareData`), unless the route exports
+  // `shareData = false`.
+  const shareShown = (
+    routeId: string,
+    shown: LoadedRouteData,
+    loaded: LoadedRouteData,
+  ): LoadedRouteData => {
+    if (loaded.terminalRouteId !== undefined || routeHooks[routeId]?.shareData === false)
+      return loaded
+    // Parsed JSON is a tree; a client loader/custom transport can return cyclic or aliased data.
+    const plainJson = loaded.text !== undefined && routeHooks[routeId]?.clientLoader === undefined
+    return {
+      ...loaded,
+      data: shareData(shown.data, loaded.data, plainJson),
+      layoutData: shareData(shown.layoutData, loaded.layoutData, plainJson),
+      serverComponents: shareData(shown.serverComponents, loaded.serverComponents, plainJson),
+      ...(loaded.boundaries === undefined
+        ? {}
+        : { boundaries: shareData(shown.boundaries, loaded.boundaries, plainJson) }),
     }
   }
   /**
@@ -638,7 +837,11 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       params: target.params,
       signal,
       body,
-      serverLoader: async () => state.data,
+      // An action posted to the target an intercept boundary holds belongs to that target.
+      serverLoader: async () =>
+        state.intercepted !== undefined && pathnameOf(action) === pathnameOf(state.path)
+          ? state.boundaries?.[state.intercepted.boundary]?.data
+          : state.data,
     })
     if (result === undefined) return { body }
     if (!isClientActionResult(result)) {
@@ -668,18 +871,15 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       initial,
     )
     if (mine !== generation) return
-    if (loaded.terminalRouteId !== undefined) {
-      await loadModule?.(loaded.terminalRouteId, state.path)
-      state = { ...state, routeId: loaded.terminalRouteId, params: {}, data: null }
-    } else {
-      state = {
-        ...state,
-        ...dataFields(loaded),
-      }
-    }
+    // No terminal status can arrive here: the server already rendered this route (a status page
+    // included) and its data is the only server result the client loader sees.
+    state = { ...state, ...dataFields(loaded) }
     emit()
   }
   let state = options.initial
+  // The page as last published from a load, with the response text it was read from. Every publish of
+  // page data replaces it, and a reload reuses it only for the same text, which says the same.
+  let shownPage: LoadedRouteData | undefined
   const listeners = new Set<() => void>()
   let generation = 0
   // Snapshot listeners to defend against accidental un/subscribe during notification. The adapters
@@ -694,12 +894,33 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // fresh: a link warmed as it scrolled into view can be clicked minutes later.
   const MAX_PREFETCH = 10
   const PREFETCH_MAX_AGE_MS = 30_000
-  const prefetched = new Map<string, readonly [LoadedRouteData, number]>()
-  const inflight = new Set<string>()
+  // path -> [data, when it arrived, the identity epoch it was loaded under]
+  const prefetched = new Map<string, readonly [LoadedRouteData, number, string]>()
+  // path -> the token of the prefetch loading it; a prefetch stores what it read only while its
+  // token is still there, so dropping the token discards a load that started before the drop.
+  const inflight = new Map<string, object>()
+  // Read without the DOM types: this module also builds in tsconfigs that leave the DOM lib out.
+  const readEpoch = (): string => {
+    const cookie: unknown = Reflect.get(Reflect.get(globalThis, "document") ?? {}, "cookie")
+    return typeof cookie === "string" ? epochOf(cookie) : ""
+  }
   const freshPrefetch = (path: string): LoadedRouteData | undefined => {
     const held = prefetched.get(path)
-    return held !== undefined && Date.now() - held[1] < PREFETCH_MAX_AGE_MS ? held[0] : undefined
+    return held !== undefined &&
+      Date.now() - held[1] < PREFETCH_MAX_AGE_MS &&
+      held[2] === readEpoch()
+      ? held[0]
+      : undefined
   }
+  // Warmed data was loaded before a mutation or for the previous visitor, so either one drops all of
+  // it, along with what a prefetch still in flight read.
+  const dropPrefetched = (): void => {
+    inflight.clear()
+    prefetched.clear()
+  }
+  onIdentityChange(dropPrefetched)
+  if (typeof BroadcastChannel !== "undefined")
+    new BroadcastChannel(IDENTITY_CHANNEL).addEventListener("message", dropPrefetched)
   // 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
@@ -737,6 +958,8 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // `X-Nifra-Revalidate` handling in `submit`.
   const markStale = (paths: readonly string[]): void => {
     for (const p of paths) {
+      prefetched.delete(p)
+      inflight.delete(p)
       const entry = cache.get(p)
       if (entry !== undefined) {
         cache.set(p, {
@@ -773,6 +996,15 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     return target === null ? undefined : [path, target]
   }
 
+  // Load the status route a terminal answer for `at` renders. One inside layouts needs those layouts'
+  // loaders, which only a document request runs, so the caller loads `at` as a document instead.
+  const loadTerminal = async (routeId: string, at: string): Promise<void> => {
+    await loadModule?.(routeId, at)
+    if (options.layoutStatusRoutes?.[routeId] === true) {
+      throw new Error(`[nifra/web] ${routeId} renders inside layouts; loading ${at} as a document`)
+    }
+  }
+
   // Load `path` for the navigation or submit `mine`, following the redirects its loaders answer with
   // while they stay in the app (20 at most, as a browser allows).
   const loadFollowing = async (
@@ -802,14 +1034,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           () => loadRouteData(at, route, signal, keepLayouts),
           prefetchedData,
         )
-        if (loaded.terminalRouteId !== undefined) {
-          await loadModule?.(loaded.terminalRouteId, at)
-          if (options.layoutStatusRoutes?.[loaded.terminalRouteId] === true) {
-            throw new Error(
-              `[nifra/web] ${loaded.terminalRouteId} renders inside layouts; loading ${at} as a document`,
-            )
-          }
-        }
+        if (loaded.terminalRouteId !== undefined) await loadTerminal(loaded.terminalRouteId, at)
         return [at, route, loaded]
       } catch (error) {
         const next = hops < 20 ? appRedirect(redirectOf(error)) : undefined
@@ -819,9 +1044,113 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     }
   }
 
-  // Refetch the active route + republish, single-flight via the shared `generation`. Shared by `invalidate`
-  // and targeted revalidation. Rejects if the fetch fails (clearing its own `pending` first).
-  const refetchActive = async (): Promise<void> => {
+  // Reload what is on screen: the page under its own path when `page`, and, while an intercept boundary
+  // holds a target, that target under its URL when `target`. The part not reloaded is kept as shown.
+  // Returns the fields to publish, both parts together. `route` is set when the page's reload names
+  // another route - the status route it answered with, or, on a status page, its URL's own route
+  // answering again - which then replaces the page and any boundary over it, so data is only ever
+  // rendered by the route it was loaded for. A target that fails becomes its
+  // boundary's error state rather than failing the page, as a dynamic boundary's load does. Nothing is
+  // cached once `mine` is superseded: a newer action's reload owns the cache.
+  const reloadActive = async (
+    signal: AbortSignal,
+    page: boolean,
+    target: boolean,
+    mine: number,
+  ): Promise<{
+    readonly fields: ReturnType<typeof dataFields>
+    readonly route?: { readonly routeId: string; readonly params: Record<string, string> }
+  }> => {
+    const pagePath = pagePathOf(state)
+    const intercepted = state.intercepted
+    const targetPath = state.path
+    // The route the page's URL matches: the one on screen, except on a status page.
+    const pageRoute = match(pagePath) ?? { routeId: state.routeId, params: state.params }
+    const rematched = pageRoute.routeId !== state.routeId
+    const targetRoute = intercepted !== undefined && target ? match(targetPath) : null
+    // The page's own route shares with what the page shows; a status page answered by its URL's route
+    // has nothing of that route on screen.
+    const shown = rematched ? undefined : (shownPage ?? state)
+    const shownTarget = { data: intercepted && state.boundaries?.[intercepted.boundary]?.data }
+    // A hole on screen that is a host stays one: it reloads as a fill.
+    const hosts = rematched
+      ? []
+      : Object.values(state.boundaries ?? {})
+          .filter((held) => held.ppr === true)
+          .map((held) => held.name)
+    const [reloaded, targetOutcome] = await Promise.all([
+      page
+        ? (async (): Promise<LoadedRouteData> => {
+            if (rematched) await loadModule?.(pageRoute.routeId, pagePath)
+            const loaded = await applyClientLoader(pagePath, pageRoute, signal, () =>
+              loadRouteData(
+                pagePath,
+                pageRoute,
+                signal,
+                false,
+                undefined,
+                hosts.length === 0 ? undefined : hosts,
+                shown,
+              ),
+            )
+            return shown === undefined ? loaded : shareShown(pageRoute.routeId, shown, loaded)
+          })()
+        : undefined,
+      targetRoute === null
+        ? undefined
+        : (async (): Promise<LoadedRouteData | undefined> => {
+            try {
+              await loadModule?.(targetRoute.routeId, targetPath)
+              const outcome = shareShown(
+                targetRoute.routeId,
+                shownTarget,
+                await applyClientLoader(targetPath, targetRoute, signal, () =>
+                  loadRouteData(targetPath, targetRoute, signal),
+                ),
+              )
+              if (mine === generation) cachePut(targetPath, outcome)
+              return outcome
+            } catch {
+              return undefined
+            }
+          })(),
+    ])
+    if (reloaded?.terminalRouteId !== undefined)
+      await loadTerminal(reloaded.terminalRouteId, pagePath)
+    if (reloaded !== undefined && mine === generation) {
+      cachePut(pagePath, reloaded)
+      shownPage = reloaded
+    }
+    const fields = dataFields(reloaded ?? state)
+    if (reloaded?.terminalRouteId !== undefined)
+      return { fields, route: { routeId: reloaded.terminalRouteId, params: {} } }
+    if (reloaded !== undefined && rematched) return { fields, route: pageRoute }
+    if (intercepted === undefined) return { fields }
+    const held = state.boundaries?.[intercepted.boundary]
+    if (held === undefined) return { fields }
+    if (targetRoute === null)
+      return {
+        fields: {
+          ...fields,
+          boundaries: { ...(fields.boundaries ?? {}), [intercepted.boundary]: held },
+        },
+      }
+    // A reload keeps the result of the last action posted to the target, as the page keeps its own.
+    const boundaries = withActionData(
+      holdTarget(fields.boundaries, held, targetOutcome),
+      intercepted.boundary,
+      held.actionData,
+    )
+    return { fields: { ...fields, ...(boundaries === undefined ? {} : { boundaries }) } }
+  }
+
+  // Refetch what is on screen + republish, single-flight via the shared `generation`. Shared by
+  // `invalidate` and targeted revalidation: `inScope` says which paths to refresh, and a page or held
+  // target outside it is kept. Rejects if the page's fetch fails (clearing its own `pending` first).
+  const refetchActive = async (inScope?: (path: string) => boolean): Promise<void> => {
+    const page = inScope === undefined || inScope(pagePathOf(state))
+    const target = state.intercepted !== undefined && (inScope === undefined || inScope(state.path))
+    if (!page && !target) return
     const mine = ++generation
     navAbort?.abort()
     const ac = new AbortController()
@@ -829,17 +1158,21 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     state = { ...state, pending: true }
     emit()
     try {
-      const active = { routeId: state.routeId, params: state.params }
-      const loaded = await applyClientLoader(state.path, active, ac.signal, () =>
-        loadRouteData(state.path, active, ac.signal),
-      )
+      const { fields, route } = await reloadActive(ac.signal, page, target, mine)
       if (mine !== generation) return // superseded - drop the stale result
-      cachePut(state.path, loaded)
-      state = {
-        ...state,
-        ...dataFields(loaded),
-        pending: false,
-      }
+      // A terminal answer for the page (the session expired, the record is gone) replaces it, and any
+      // boundary over it, with its status route, as a navigation to this URL would.
+      state =
+        route === undefined
+          ? { ...state, ...fields, pending: false }
+          : {
+              routeId: route.routeId,
+              params: route.params,
+              path: state.path,
+              ...fields,
+              actionData: undefined,
+              pending: false,
+            }
       emit()
     } catch (err) {
       if (mine === generation) {
@@ -874,7 +1207,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // 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(() => {}))
+    if (!skipActive) jobs.push(refetchActive((path) => paths.includes(path)).catch(() => {}))
     for (const entry of fetchers.values()) jobs.push(entry.refreshIfShowing(paths))
     await Promise.all(jobs)
   }
@@ -884,6 +1217,8 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     let fGeneration = 0
     let fAbort: AbortController | undefined
     let loadedPath: string | undefined
+    // `data` as loaded, with the response text it was read from.
+    let shown: LoadedRouteData | undefined
     const fListeners = new Set<() => void>()
     const fEmit = (): void => {
       if (fListeners.size > 0) for (const l of [...fListeners]) l() // snapshot for defensiveness
@@ -899,11 +1234,15 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       fState = { ...fState, pending: true }
       fEmit()
       try {
-        const [, loaded] = await Promise.all([
+        // Loading the path again is a reload of what this fetcher shows.
+        const before = path === loadedPath ? shown : undefined
+        const [, fresh] = await Promise.all([
           loadModule?.(matched.routeId),
-          loadRouteData(path, matched, ac.signal),
+          loadRouteData(path, matched, ac.signal, false, undefined, undefined, before),
         ])
         if (mine !== fGeneration) return // a newer load/submit on THIS fetcher superseded us
+        const loaded = before === undefined ? fresh : shareShown(matched.routeId, before, fresh)
+        shown = loaded
         // 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.
@@ -950,6 +1289,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             body,
             headers: { [DATA_HEADER]: "1" },
           })
+          dropPrefetched()
           if (!res.ok)
             throw new Error(`[nifra/web] fetcher action failed (${res.status}): ${action}`)
           const actionData = res.status === 204 ? undefined : await readResponseData(res, ac.signal)
@@ -995,12 +1335,25 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     navigate: async (path) => {
       const matched = match(path)
       if (matched === null) return
+      // The target an open boundary already shows (a `#fragment` entry inside it, a link to itself):
+      // reloading it would rebuild the boundary and drop its action result. One in its error state
+      // loads again, so a link can retry it.
+      if (
+        state.intercepted !== undefined &&
+        state.boundaries?.[state.intercepted.boundary]?.status === "ready" &&
+        !state.pending &&
+        path === state.path
+      ) {
+        emit()
+        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 (
+        state.intercepted === undefined &&
         matched.routeId === state.routeId &&
         pathnameOf(path) === pathnameOf(state.path) &&
         isClientOnlySearchChange(
@@ -1009,11 +1362,14 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           searchClientKeys[state.routeId] ?? [],
         )
       ) {
-        ++generation // supersede any in-flight navigation so its late result is dropped
+        const mine = ++generation // supersede any in-flight navigation so its late result is dropped
         navAbort?.abort()
-        cachePut(path, dataFields(state))
-        state = { ...state, path, pending: false, pendingPath: undefined }
-        emit()
+        await present(() => {
+          if (mine !== generation) return
+          cachePut(path, dataFields(state))
+          state = { ...state, path, pending: false, pendingPath: undefined }
+          emit()
+        })
         return
       }
       const mine = ++generation
@@ -1026,57 +1382,73 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         const [to, target, loaded] = await loadFollowing(mine, path, matched, ac.signal, true, true)
         if (mine !== generation) return // a newer navigation superseded this one - drop the stale result
         cachePut(to, loaded) // keep the keyed cache coherent with what we publish
-        const interception =
-          loaded.terminalRouteId === undefined
-            ? interceptionFor(state.routeId, to, target)
-            : undefined
-        if (interception !== undefined) {
-          // The target's ordinary data request has already completed (including its server authz and
-          // optional client wrapper). Only the presentation route is retained; the current page stays
-          // mounted underneath the named slot. A target that returned a terminal status never reaches
-          // this branch, so an unauthorized/missing target cannot become a modal.
+        // The swap can wait a frame for the presenter, and a newer navigation started meanwhile owns it.
+        await present(() => {
+          if (mine !== generation) return
+          // The page's own URL is never intercepted: navigating there (Back out of a boundary, a link
+          // to itself) shows the page, even when a boundary's pattern matches it.
+          const pagePath = pagePathOf(state)
+          const interception =
+            loaded.terminalRouteId === undefined && pathnameOf(to) !== pathnameOf(pagePath)
+              ? interceptionFor(state.routeId, to, target)
+              : undefined
+          if (interception !== undefined) {
+            // The target's ordinary data request has already completed (including its server authz and
+            // optional client wrapper). Only the presentation route is retained; the current page stays
+            // mounted underneath the named slot. A target that returned a terminal status never reaches
+            // this branch, so an unauthorized/missing target cannot become a modal.
+            state = {
+              ...state,
+              path: to,
+              boundaries: holdTarget(state.boundaries, interception, loaded),
+              intercepted: { boundary: interception.name, pagePath },
+              pending: false,
+              pendingPath: undefined,
+            }
+            emit()
+            return
+          }
           state = {
-            ...state,
+            routeId: loaded.terminalRouteId ?? target.routeId,
+            params: loaded.terminalRouteId === undefined ? target.params : {},
             path: to,
-            boundaries: {
-              ...(state.boundaries ?? {}),
-              [interception.name]: {
-                name: interception.name,
-                mode: interception.mode,
-                status: "ready",
-                data: loaded.data,
-                ...(interception.errorId === undefined ? {} : { errorId: interception.errorId }),
-              },
-            },
-            actionData: undefined,
+            ...dataFields(loaded),
+            actionData: undefined, // a fresh navigation has no action result
             pending: false,
-            pendingPath: undefined,
           }
+          shownPage = loaded
           emit()
-          return
-        }
-        state = {
-          routeId: loaded.terminalRouteId ?? target.routeId,
-          params: loaded.terminalRouteId === undefined ? target.params : {},
-          path: to,
-          ...dataFields(loaded),
-          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
-        // to recover (the history layer falls back to a full-page navigation).
-        if (mine === generation) {
-          state = { ...state, pending: false, pendingPath: undefined }
-          emit()
-        }
+        // A newer navigation or submit owns the page, and aborting this one's request is how it took
+        // over: as with a submit, the superseded navigation settles quietly.
+        if (mine !== generation) return
+        // Clear our pending flag + target and rethrow - the caller decides how to recover (the history
+        // layer falls back to a full-page navigation).
+        state = { ...state, pending: false, pendingPath: undefined }
+        emit()
         throw err
       }
     },
     submit: async (action, body, opts) => {
       const mine = ++generation
       const previousActionData = state.actionData
+      // An action posted to the target an intercept boundary holds answers that boundary, not the page.
+      const actionBoundary =
+        state.intercepted !== undefined && pathnameOf(action) === pathnameOf(state.path)
+          ? state.intercepted.boundary
+          : undefined
+      const previousBoundaryActionData =
+        actionBoundary === undefined ? undefined : state.boundaries?.[actionBoundary]?.actionData
+      // The state with `value` as the action's result, on whichever owns the action.
+      const answered = (
+        current: { readonly boundaries?: BoundaryStates | undefined },
+        value: unknown,
+      ): Partial<RouterState> => {
+        if (actionBoundary === undefined) return { actionData: value }
+        const boundaries = withActionData(current.boundaries, actionBoundary, value)
+        return boundaries === undefined ? {} : { boundaries }
+      }
       // 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.
       // Wire into `navAbort` like `navigate`/`refetchActive`, so a later nav cancels the in-flight read.
@@ -1097,7 +1469,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       try {
         const prepared = await prepareClientAction(action, body, ac.signal)
         if (Object.hasOwn(prepared, "optimisticData")) {
-          state = { ...state, actionData: prepared.optimisticData }
+          state = { ...state, ...answered(state, prepared.optimisticData) }
           emit()
         }
         const res = await fetch(appUrl(action), {
@@ -1107,6 +1479,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         })
         // Whatever the status, the server took the POST: the action may have run before it failed.
         posted = true
+        dropPrefetched()
         if (!res.ok) throw new Error(`[nifra/web] action failed (${res.status}): ${action}`)
         const redirectTo = res.headers.get(REDIRECT_HEADER)
         if (redirectTo !== null) {
@@ -1135,6 +1508,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             actionData: undefined,
             pending: false,
           }
+          shownPage = loaded
           emit()
           return
         }
@@ -1145,32 +1519,43 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         // 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
-        // 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 active = { routeId: state.routeId, params: state.params }
-        const loaded = skipActive
-          ? {
-              ...dataFields(state),
-            }
-          : await applyClientLoader(state.path, active, ac.signal, () =>
-              loadRouteData(state.path, active, ac.signal),
-            )
+        // Revalidate what is on screen so the mutation is reflected - the page, and a target an
+        // intercept boundary holds - unless the caller opted out (`revalidate: false`). A
+        // server-declared revalidate of a path on screen overrides the opt-out (the server says it
+        // changed, so stale data would be wrong). Default is to revalidate.
+        const pagePath = pagePathOf(state)
+        const reloadPage = opts?.revalidate !== false || changed.includes(pagePath)
+        const reloadTarget =
+          state.intercepted !== undefined &&
+          (opts?.revalidate !== false || changed.includes(state.path))
+        const { fields, route } = await reloadActive(ac.signal, reloadPage, reloadTarget, mine)
         if (mine !== generation) return
-        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))
+        markStale(changed.filter((p) => p !== pagePath && (!reloadTarget || p !== state.path)))
         // Reconcile: publish the revalidated data + actionData; omit `submission` (the optimistic
-        // window is over - the real data now drives the view).
-        state = {
-          routeId: state.routeId,
-          params: state.params,
-          path: state.path,
-          ...dataFields(loaded),
-          actionData,
-          pending: false,
-        }
+        // window is over - the real data now drives the view). A reload that names another route (a
+        // terminal answer for the page) renders it in the page's place, closing any boundary, and the
+        // action's result goes with the page.
+        state =
+          route === undefined
+            ? {
+                routeId: state.routeId,
+                params: state.params,
+                path: state.path,
+                ...fields,
+                actionData: previousActionData,
+                ...answered(fields, actionData),
+                pending: false,
+                ...(state.intercepted === undefined ? {} : { intercepted: state.intercepted }),
+              }
+            : {
+                routeId: route.routeId,
+                params: route.params,
+                path: state.path,
+                ...fields,
+                actionData: undefined,
+                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.
@@ -1185,26 +1570,33 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             path: state.path,
             ...dataFields(state),
             actionData: previousActionData,
+            ...(actionBoundary === undefined
+              ? {}
+              : answered(dataFields(state), previousBoundaryActionData)),
             pending: false,
+            ...(state.intercepted === undefined ? {} : { intercepted: state.intercepted }),
           }
           emit()
         }
         if (!posted) throw err
         if (mine !== generation) return // a newer navigation or submit owns the page
-        throw redirectOf(err) === undefined ? redirected(landing ?? state.path, err) : err
+        // Otherwise show the route that owns the action, as a native post to it would.
+        const owner = actionBoundary === undefined ? pagePathOf(state) : state.path
+        throw redirectOf(err) === undefined ? redirected(landing ?? owner, err) : err
       }
     },
     hydrate,
     invalidate: async (paths) => {
       // Mark targeted cache entries stale (all entries when no `paths`) - unmounted ones refetch
-      // lazily on next access.
+      // lazily on next access. A warmed prefetch of a target is dropped: it would show the old data.
       const targets = paths ?? [...cache.keys()]
       markStale(targets)
+      if (paths === undefined) dropPrefetched()
       // 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>[] = []
-      if (paths === undefined || paths.includes(state.path)) jobs.push(refetchActive())
+      jobs.push(refetchActive(paths === undefined ? undefined : (path) => paths.includes(path)))
       for (const entry of fetchers.values()) jobs.push(entry.refreshIfShowing(targets))
       await Promise.all(jobs)
     },
@@ -1212,24 +1604,34 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       if (inflight.has(path) || freshPrefetch(path) !== undefined) return
       const matched = match(path)
       if (matched === null) return
-      inflight.add(path)
+      const token = {}
+      inflight.set(path, token)
+      const epoch = readEpoch()
       try {
         // 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, path),
-          loadRouteData(path, matched),
+          loadRouteData(path, matched, undefined, false, "prefetch"),
         ])
         prefetched.delete(path) // a stale entry re-enters as the newest
         if (prefetched.size >= MAX_PREFETCH) {
           const oldest = prefetched.keys().next().value
           if (oldest !== undefined) prefetched.delete(oldest)
         }
-        if (loaded.serverComponents === undefined) prefetched.set(path, [loaded, Date.now()])
+        // A prefetched hole is an empty host nothing fills; the navigation fetches it, cancellably.
+        const holes = Object.values(loaded.boundaries ?? {}).some((state) => state.ppr === true)
+        if (
+          loaded.serverComponents === undefined &&
+          !holes &&
+          inflight.get(path) === token &&
+          epoch === readEpoch()
+        )
+          prefetched.set(path, [loaded, Date.now(), epoch])
       } catch {
         // Best-effort: a failed prefetch just means the eventual navigate fetches normally.
       } finally {
-        inflight.delete(path)
+        if (inflight.get(path) === token) inflight.delete(path)
       }
     },
     fetcher: (key) => {