@nifrajs/web 3.3.0 → 4.0.0

package/src/route-types.ts

@@ -0,0 +1,264 @@
+/**
+ * `@nifrajs/web/route-types` - the generated `./+types/<route>` modules.
+ *
+ * Every route file gets `.nifra/types/<routes>/<dir>/+types/<name>.d.ts`, declaring a `Route`
+ * namespace: the route's `Params`, the `LoaderData` and `ActionData` its output schemas let through,
+ * the `LoaderArgs` its backend half receives, and its component's props. With
+ * `"rootDirs": [".", "./.nifra/types"]` in tsconfig, both halves of a route import it as
+ * `./+types/<name>`:
+ *
+ *     // routes/blog/[slug].tsx
+ *     import type { Route } from "./+types/[slug]"
+ *     export default function Post({ data }: Route.ComponentProps) { ... }
+ *
+ *     // routes/blog/[slug].backend.ts
+ *     export async function loader({ api, params }: Route.LoaderArgs) { ... }
+ *
+ * `LoaderData` is the output type of `loaderOutput`, not the loader's return type: the data guard
+ * projects the loader's value through that schema, so the schema is what the component receives.
+ * `.nifra/types/register.d.ts` registers `backend/app.ts`'s `backend` with `@nifrajs/client`, so `api`
+ * is typed without a route importing the backend.
+ */
+import {
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, join, relative } from "node:path"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import {
+  buildManifest,
+  isMiddlewareFile,
+  isRouteBackendFile,
+  type LayoutEntry,
+  type Manifest,
+} from "./manifest.ts"
+
+/** Where the generated types live, relative to the app root. */
+export const ROUTE_TYPES_DIR = ".nifra/types"
+
+const BACKEND_APP = "backend/app"
+const SCRIPT_EXTS = [".ts", ".tsx", ".js", ".jsx"] as const
+
+export interface RouteTypesOptions {
+  /** The app root: where `.nifra/` and `backend/app.ts` live. */
+  readonly appRoot: string
+  /** The routes directory. Defaults to `<appRoot>/routes`. */
+  readonly routesDir?: string
+}
+
+type Kind = "page" | "layout"
+
+interface RouteFile {
+  readonly file: string
+  readonly backend: string | undefined
+  readonly kind: Kind
+}
+
+const posix = (path: string): string => path.replaceAll("\\", "/")
+
+/** Every route file the router serves, once each: pages, layouts and the special pages. */
+function routeFiles(manifest: Manifest): readonly RouteFile[] {
+  const files = new Map<string, RouteFile>()
+  const add = (entry: Pick<LayoutEntry, "file" | "backend">, kind: Kind): void => {
+    if (!files.has(entry.file))
+      files.set(entry.file, { file: entry.file, backend: entry.backend, kind })
+  }
+  for (const route of manifest.routes) add(route, "page")
+  for (const layout of Object.values(manifest.layouts)) add(layout, "layout")
+  for (const group of [
+    manifest.errors,
+    manifest.notFounds,
+    manifest.statusPages,
+    manifest.loadings,
+  ]) {
+    for (const entry of Object.values(group ?? {})) add(entry, "page")
+  }
+  if (manifest.notFound !== undefined) add(manifest.notFound, "page")
+  return [...files.values()].sort((a, b) => codeUnitOrder(a.file, b.file))
+}
+
+const PARAM = /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/
+const OPTIONAL = /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/
+const CATCH_ALL = /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/
+
+/** The params a route file's URL carries: its directories', plus its own name's for a page. */
+function paramsType(file: string, kind: Kind): string {
+  const segments = file.replace(/\.[^./]+$/, "").split("/")
+  const own =
+    kind === "page" && !segments.at(-1)?.startsWith("_") ? segments : segments.slice(0, -1)
+  const fields: string[] = []
+  for (const segment of own) {
+    const optional = OPTIONAL.exec(segment)
+    const name = optional?.[1] ?? PARAM.exec(segment)?.[1] ?? CATCH_ALL.exec(segment)?.[1]
+    if (name !== undefined) fields.push(`readonly ${name}${optional === null ? "" : "?"}: string`)
+  }
+  return fields.length === 0 ? "Record<string, never>" : `{ ${fields.join("; ")} }`
+}
+
+/** A module specifier for `target` from a file in `fromDir`, without a script extension. */
+function specifier(fromDir: string, target: string): string {
+  let path = posix(relative(fromDir, target))
+  for (const ext of SCRIPT_EXTS) if (path.endsWith(ext)) path = path.slice(0, -ext.length)
+  return path.startsWith(".") ? path : `./${path}`
+}
+
+const backendAppOf = (appRoot: string): string | undefined =>
+  SCRIPT_EXTS.map((ext) => join(appRoot, `${BACKEND_APP}${ext}`)).find((path) => existsSync(path))
+
+function routeTypesModule(
+  route: RouteFile,
+  out: string,
+  routesDir: string,
+  label: string,
+  register: string | undefined,
+): string {
+  const dir = dirname(out)
+  const backend = route.backend === undefined ? undefined : join(routesDir, route.backend)
+  // Only a script module's exports are visible to TypeScript; a .svelte/.vue/.mdx one is an ambient shim.
+  const frontend = /\.[jt]sx?$/.test(route.file) ? join(routesDir, route.file) : undefined
+  const lines = [`// Generated by nifra from ${label}. Do not edit: \`nifra types\` rewrites it.`]
+  if (register !== undefined)
+    lines.push(`/// <reference path="${posix(relative(dir, register))}" />`)
+  lines.push('import type { OutputOf, RouteLoaderArgs, SearchSchemaOf } from "@nifrajs/client"')
+  if (route.kind === "page") lines.push('import type { RenderProps } from "@nifrajs/web"')
+  lines.push("")
+  if (backend !== undefined)
+    lines.push(`type Backend = typeof import("${specifier(dir, backend)}")`)
+  if (frontend !== undefined)
+    lines.push(`type Frontend = typeof import("${specifier(dir, frontend)}")`)
+  if (backend !== undefined || frontend !== undefined) lines.push("")
+  const output = (name: string) => (backend === undefined ? "null" : `OutputOf<Backend, "${name}">`)
+  lines.push(
+    "export namespace Route {",
+    "  /** The URL params this route's path carries. */",
+    `  export type Params = ${paramsType(route.file, route.kind)}`,
+    "  /** What the loader sends to the browser: the output type of `loaderOutput`. */",
+    `  export type LoaderData = ${output("loaderOutput")}`,
+    "  /** What the action sends back: the output type of `actionOutput`. */",
+    `  export type ActionData = ${output("actionOutput")}`,
+    "  /** The context the backend half's loader receives. */",
+    `  export type LoaderArgs = RouteLoaderArgs<Params${frontend === undefined ? "" : ", SearchSchemaOf<Frontend>"}>`,
+    "  /** The context the backend half's action receives. */",
+    "  export type ActionArgs = LoaderArgs",
+  )
+  if (route.kind === "page") {
+    lines.push(
+      "  /** The page component's props. */",
+      '  export type ComponentProps = Omit<RenderProps, "data" | "actionData" | "params"> & {',
+      "    readonly data: LoaderData",
+      "    readonly actionData?: ActionData",
+      "    readonly params: Params",
+      "  }",
+    )
+  } else {
+    lines.push(
+      "  /** The layout component's props; `Children` is the adapter's children type. */",
+      "  export type ComponentProps<Children = unknown> = {",
+      "    readonly data: LoaderData",
+      "    readonly children?: Children",
+      "  }",
+    )
+  }
+  lines.push("}", "")
+  return lines.join("\n")
+}
+
+function registerModule(out: string, backendApp: string, label: string): string {
+  return [
+    `// Generated by nifra from ${label}. Do not edit: \`nifra types\` rewrites it.`,
+    `import type { backend } from "${specifier(dirname(out), backendApp)}"`,
+    "",
+    'declare module "@nifrajs/client" {',
+    "  interface Register {",
+    "    readonly backend: typeof backend",
+    "  }",
+    "}",
+    "",
+  ].join("\n")
+}
+
+/** Every generated types file for the app, by absolute path. */
+export function routeTypeFiles(options: RouteTypesOptions): ReadonlyMap<string, string> {
+  const appRoot = options.appRoot
+  const routesDir = options.routesDir ?? join(appRoot, "routes")
+  const typesRoot = join(appRoot, ROUTE_TYPES_DIR)
+  const files = new Map<string, string>()
+  const backendApp = backendAppOf(appRoot)
+  const register = backendApp === undefined ? undefined : join(typesRoot, "register.d.ts")
+  if (backendApp !== undefined && register !== undefined) {
+    files.set(register, registerModule(register, backendApp, posix(relative(appRoot, backendApp))))
+  }
+  if (!existsSync(routesDir)) return files
+  const listed = (readdirSync(routesDir, { recursive: true }) as string[])
+    .map(posix)
+    .filter(
+      (file) =>
+        /\.(?:tsx|jsx|svelte|vue|mdx)$/.test(file) ||
+        isRouteBackendFile(file) ||
+        isMiddlewareFile(file),
+    )
+  // Discovery only: the importer is never called.
+  const manifest = buildManifest(listed, () => () => Promise.reject(new Error("not loaded")))
+  const routesRel = posix(relative(appRoot, routesDir))
+  for (const route of routeFiles(manifest)) {
+    const dir = dirname(route.file)
+    const name = route.file.slice(dir === "." ? 0 : dir.length + 1).replace(/\.[^.]+$/, "")
+    const out = join(typesRoot, routesRel, dir === "." ? "" : dir, "+types", `${name}.d.ts`)
+    files.set(out, routeTypesModule(route, out, routesDir, `${routesRel}/${route.file}`, register))
+  }
+  return files
+}
+
+/** Generated files missing or different on disk, and files on disk the app no longer generates. */
+export function staleRouteTypes(options: RouteTypesOptions): readonly string[] {
+  const files = routeTypeFiles(options)
+  const stale: string[] = []
+  for (const [path, content] of files) {
+    if (!existsSync(path) || readFileSync(path, "utf8") !== content) stale.push(path)
+  }
+  for (const path of onDisk(join(options.appRoot, ROUTE_TYPES_DIR))) {
+    if (!files.has(path)) stale.push(path)
+  }
+  return stale.sort()
+}
+
+function onDisk(dir: string): readonly string[] {
+  if (!existsSync(dir)) return []
+  return (readdirSync(dir, { recursive: true, withFileTypes: true }) as Dirent[])
+    .filter((entry) => entry.isFile())
+    .map((entry) => join(entry.parentPath, entry.name))
+}
+
+export interface RouteTypesResult {
+  /** Files written because they were missing or out of date. */
+  readonly written: readonly string[]
+  /** Files removed because no route generates them any more. */
+  readonly removed: readonly string[]
+}
+
+/**
+ * Bring `.nifra/types` up to date with the app's routes. Unchanged files are left alone, so an
+ * editor watching them sees only real changes. Owns the directory: anything else in it is removed.
+ */
+export function writeRouteTypes(options: RouteTypesOptions): RouteTypesResult {
+  const files = routeTypeFiles(options)
+  const written: string[] = []
+  const removed: string[] = []
+  for (const [path, content] of files) {
+    if (existsSync(path) && readFileSync(path, "utf8") === content) continue
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, content)
+    written.push(path)
+  }
+  for (const path of onDisk(join(options.appRoot, ROUTE_TYPES_DIR))) {
+    if (files.has(path)) continue
+    rmSync(path)
+    removed.push(path)
+  }
+  return { written: written.sort(), removed: removed.sort() }
+}

package/src/router.ts

@@ -10,6 +10,7 @@ import type { StandardSchemaV1 } from "@nifrajs/core/server"
 import type { BoundaryDescriptor, BoundaryStates } from "./boundary.ts"
 import { parseNdjsonData } from "./deferred.ts"
 import type { ClientActionResult, ClientRequestBody, ClientRouteHooks } from "./manifest.ts"
+import type { MatchChain } from "./render-seam.ts"
 import { isClientOnlySearchChange } from "./search.ts"
 
 /**
@@ -25,6 +26,10 @@ export const DATA_HEADER = "x-nifra-data"
  */
 export const PRERENDERED_GLOBAL = "__NIFRA_PRERENDERED__"
 
+/** Where `createWebApp` serves a prerendered set too large to inline; the global then holds this URL
+ * plus a `?v=` content version, so the browser may cache it for good. */
+export const PRERENDERED_LIST_PATH = "/__nifra/prerendered.json"
+
 /**
  * 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
@@ -138,8 +143,9 @@ export interface RouterState {
   readonly actionData?: unknown
   /** True while a navigation or submit is in flight (drives loading UI). */
   readonly pending: boolean
-  /** 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. */
+  /** The path a navigation or a submit's redirect is loading while `pending`; a redirect the router
+   * follows moves it to the target. 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. */
   readonly submission?: Submission
@@ -197,8 +203,10 @@ export type FetchRouteData = (
 
 /** Per-submit options. `revalidate: false` opts out of the post-action loader re-fetch. */
 export interface SubmitOptions {
-  /** Re-run the active route's loader after the action settles (default `true`). Set `false` to
-   * keep the current `data` and rely on the action's `actionData` alone. */
+  /** Re-run the active route's loaders after the action settles (default `true`). Set `false` to
+   * keep the current `data` and rely on the action's `actionData` alone. When the action redirects,
+   * the target's layouts all re-run by default; with `false` it keeps the layout data an ordinary
+   * navigation would. */
   readonly revalidate?: boolean
 }
 
@@ -238,7 +246,11 @@ export interface ClientRouter {
   snapshot: () => RouterState
   /** Subscribe to transitions; returns an unsubscribe fn. */
   subscribe: (listener: () => void) => () => void
-  /** Navigate to a path: match → fetch loader data → publish. No-op for an unmatched path. */
+  /**
+   * Navigate to a path: match → fetch loader data → publish. No-op for an unmatched path. A loader
+   * redirect to another route is followed; one that leaves the app (another origin, a `#fragment`, no
+   * route) rejects with its target as `redirectTo`.
+   */
   navigate: (path: string) => Promise<void>
   /**
    * Submit an action (POST `body` to `action` in data mode): a redirect becomes a client
@@ -246,7 +258,8 @@ export interface ClientRouter {
    * 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
    * 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).
+   * always loads its target regardless. Rejects on failure (caller falls back); once the action has
+   * run, the rejection's `redirectTo` names the page to load instead of posting again.
    */
   submit: (
     action: string,
@@ -319,6 +332,10 @@ export interface MountRouterOptions {
    * `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)[]>>
+  /** routeId → the ids and `handle` exports `useMatches` reports for that chain; built by
+   * `generateClientEntry` as each route's modules load. The mount hands the current route's entry to
+   * the render as `RenderProps.matchChain`. Omitted ⇒ `useMatches` returns an empty list. */
+  readonly matchChains?: Readonly<Record<string, MatchChain>>
   /** Hydration container (opaque - the adapter casts it to its DOM element type). */
   readonly container: unknown
 }
@@ -356,11 +373,45 @@ const prerenderedSetOf = (paths: object): ReadonlySet<unknown> => {
   return set
 }
 
+// A handed-over URL is fetched once: the global then holds the pending list every navigation shares.
+// A failed fetch leaves navigations on the dynamic path, which is always correct.
+const prerenderedOf = (): unknown => {
+  const handed = Reflect.get(globalThis, PRERENDERED_GLOBAL)
+  if (typeof handed !== "string") return handed
+  const list = fetch(handed)
+    .then((res) => (res.ok ? res.json() : undefined))
+    .catch(() => undefined)
+  Reflect.set(globalThis, PRERENDERED_GLOBAL, list)
+  return list
+}
+
+/**
+ * The page to load as a document, when that is why a navigation or submit rejected. Only an `http:` or
+ * `https:` target: the caller hands it to `location`, which runs a `javascript:` URL in this page,
+ * where the same target in a real redirect's `Location` never runs.
+ */
+export const redirectOf = (error: unknown): string | undefined => {
+  const to = (error as { redirectTo?: unknown } | null | undefined)?.redirectTo
+  return typeof to === "string" && /^https?:$/.test(targetUrl(to)?.protocol ?? "") ? to : undefined
+}
+
+/** A redirect target resolved against a placeholder origin, or `undefined` when it does not parse. */
+const targetUrl = (to: string): URL | undefined => {
+  try {
+    return new URL(to, "http://n.invalid")
+  } catch {
+    return undefined
+  }
+}
+
+const redirected = (to: string): Error =>
+  Object.assign(new Error(`[nifra/web] redirected to ${to}`), { redirectTo: to })
+
 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]
+  const prerendered = await prerenderedOf()
   if (Array.isArray(prerendered)) {
     const query = path.indexOf("?")
     const hash = path.indexOf("#")
@@ -379,6 +430,8 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation
     headers.set(NAV_FROM_HEADER, navigation.from)
   }
   const res = await fetch(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
@@ -411,6 +464,8 @@ const isClientActionResult = (value: unknown): value is ClientActionResult =>
 export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   const match = createMatcher(options.patterns)
   const fetchData = options.fetchData ?? defaultFetchData
+  // Start a handed-over list's fetch now, so the first navigation rarely waits for it.
+  if (fetchData === defaultFetchData) 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 ?? {}
@@ -426,7 +481,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     sourceRouteId: string,
     path: string,
     target: RouteMatch,
-  ): BoundaryDescriptor | undefined => {
+  ): Omit<BoundaryDescriptor, "hasLoad"> | undefined => {
     const boundaries = routeHooks[sourceRouteId]?.boundaries ?? []
     const pathname = pathnameOf(path)
     for (const boundary of boundaries) {
@@ -473,8 +528,12 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     path: string,
     match: { routeId: string; params: Record<string, string> },
     signal?: AbortSignal,
-    retainFrom?: { readonly path: string; readonly layoutData: readonly unknown[] },
+    // Offer the server the layout data on screen: it re-runs whichever of those loaders it must.
+    keepLayouts?: boolean,
   ): Promise<LoadedRouteData> => {
+    const retainFrom = keepLayouts
+      ? state.layoutData && { path: state.path, layoutData: state.layoutData }
+      : undefined
     const retain = retainFrom?.layoutData.map((_, index) => index) ?? []
     const payload = await fetchData(
       path,
@@ -621,11 +680,17 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     if (listeners.size === 0) return
     for (const listener of [...listeners]) listener()
   }
-  // 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.
+  // Bounded one-shot prefetch cache (path → loader data, and when it arrived) + an in-flight guard so
+  // hover spam doesn't double-fetch. Consumed (and dropped) by the next navigate to that path - while
+  // fresh: a link warmed as it scrolled into view can be clicked minutes later.
   const MAX_PREFETCH = 10
-  const prefetched = new Map<string, LoadedRouteData>()
+  const PREFETCH_MAX_AGE_MS = 30_000
+  const prefetched = new Map<string, readonly [LoadedRouteData, number]>()
   const inflight = new Set<string>()
+  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
+  }
   // 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
@@ -684,6 +749,56 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // (so a superseded route's NDJSON stream stops reading instead of draining in the background).
   let navAbort: AbortController | undefined
 
+  // The route path an in-app redirect target leads to. Undefined when the browser has to load it: another
+  // origin, a `#fragment` to scroll to, or no route.
+  const appRedirect = (to: string | undefined): readonly [string, RouteMatch] | undefined => {
+    if (to === undefined || !to.startsWith("/") || to.includes("#")) return undefined
+    const url = targetUrl(to)
+    if (url?.host !== "n.invalid") return undefined // `//host`, `/\host`, unparseable
+    const path = url.pathname + url.search
+    const target = match(path)
+    return target === null ? undefined : [path, target]
+  }
+
+  // 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 (
+    mine: number,
+    path: string,
+    target: RouteMatch,
+    signal: AbortSignal,
+    keepLayouts: boolean,
+    usePrefetch: boolean,
+  ): Promise<readonly [string, RouteMatch, LoadedRouteData]> => {
+    let current: readonly [string, RouteMatch] = [path, target]
+    for (let hops = 0; ; hops++) {
+      const [at, route] = current
+      if (mine === generation && state.pendingPath !== at) {
+        state = { ...state, pendingPath: at }
+        emit()
+      }
+      await loadModule?.(route.routeId)
+      // Prefetched server data is one-shot; a clientLoader still runs over it without another request.
+      const prefetchedData = usePrefetch ? freshPrefetch(at) : undefined
+      if (usePrefetch) prefetched.delete(at)
+      try {
+        const loaded = await applyClientLoader(
+          at,
+          route,
+          signal,
+          () => loadRouteData(at, route, signal, keepLayouts),
+          prefetchedData,
+        )
+        if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
+        return [at, route, loaded]
+      } catch (error) {
+        const next = hops < 20 ? appRedirect(redirectOf(error)) : undefined
+        if (next === undefined) throw error
+        current = next
+      }
+    }
+  }
+
   // 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> => {
@@ -890,35 +1005,12 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       state = { ...state, pending: true, pendingPath: path }
       emit()
       try {
-        // Load the route chunk before invoking a client loader. A route without a client loader still
-        // uses the same server-data path; a route with one gets a lazy `serverLoader()` thunk.
-        await loadModule?.(matched.routeId)
-        // Use prefetched server data when present (one-shot - drop it); clientLoader still runs over
-        // that cached result without causing another network request.
-        const hit = prefetched.has(path)
-        const prefetchedData = hit ? (prefetched.get(path) as LoadedRouteData) : undefined
-        if (hit) prefetched.delete(path)
-        const loaded = await applyClientLoader(
-          path,
-          matched,
-          ac.signal,
-          () =>
-            loadRouteData(
-              path,
-              matched,
-              ac.signal,
-              state.layoutData === undefined
-                ? undefined
-                : { path: state.path, layoutData: state.layoutData },
-            ),
-          prefetchedData,
-        )
-        if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
+        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(path, loaded) // keep the keyed cache coherent with what we publish
+        cachePut(to, loaded) // keep the keyed cache coherent with what we publish
         const interception =
           loaded.terminalRouteId === undefined
-            ? interceptionFor(state.routeId, path, matched)
+            ? interceptionFor(state.routeId, to, target)
             : undefined
         if (interception !== undefined) {
           // The target's ordinary data request has already completed (including its server authz and
@@ -927,7 +1019,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           // this branch, so an unauthorized/missing target cannot become a modal.
           state = {
             ...state,
-            path,
+            path: to,
             boundaries: {
               ...(state.boundaries ?? {}),
               [interception.name]: {
@@ -946,9 +1038,9 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           return
         }
         state = {
-          routeId: loaded.terminalRouteId ?? matched.routeId,
-          params: loaded.terminalRouteId === undefined ? matched.params : {},
-          path,
+          routeId: loaded.terminalRouteId ?? target.routeId,
+          params: loaded.terminalRouteId === undefined ? target.params : {},
+          path: to,
           data: loaded.data,
           layoutData: loaded.layoutData,
           ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
@@ -983,6 +1075,9 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         ...(body instanceof FormData ? { submission: { action, formData: body } } : {}),
       }
       emit()
+      // Once the action has run, falling back to posting the form again would run it twice.
+      let posted = false
+      let landing: string | undefined
       try {
         const prepared = await prepareClientAction(action, body, ac.signal)
         if (Object.hasOwn(prepared, "optimisticData")) {
@@ -995,30 +1090,30 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           headers: { [DATA_HEADER]: "1" },
         })
         if (!res.ok) throw new Error(`[nifra/web] action failed (${res.status}): ${action}`)
+        posted = true
         const redirectTo = res.headers.get(REDIRECT_HEADER)
         if (redirectTo !== null) {
           // 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}`)
-          await loadModule?.(target.routeId)
-          const loaded = await applyClientLoader(redirectTo, target, ac.signal, () =>
-            loadRouteData(
-              redirectTo,
-              target,
-              ac.signal,
-              state.layoutData === undefined
-                ? undefined
-                : { path: state.path, layoutData: state.layoutData },
-            ),
+          const next = appRedirect(redirectTo)
+          if (next === undefined) throw redirected(redirectTo)
+          landing = next[0]
+          // The action may have changed what any layout shows, so the target loads its whole chain,
+          // the same as the non-redirect revalidation below. `revalidate: false` keeps layout data
+          // the server agrees is unchanged, like an ordinary navigation.
+          const [to, target, loaded] = await loadFollowing(
+            mine,
+            next[0],
+            next[1],
+            ac.signal,
+            opts?.revalidate === false,
+            false,
           )
-          if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
           if (mine !== generation) return
-          cachePut(redirectTo, loaded)
+          cachePut(to, loaded)
           state = {
             routeId: loaded.terminalRouteId ?? target.routeId,
             params: loaded.terminalRouteId === undefined ? target.params : {},
-            path: redirectTo,
+            path: to,
             data: loaded.data,
             layoutData: loaded.layoutData,
             ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
@@ -1071,19 +1166,23 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         await refreshMounted(changed, true)
       } catch (err) {
         if (mine === generation) {
-          // Revert: clear `submission` (the optimistic view vanishes) leaving `data` untouched, so the
-          // pre-submit data shows through.
+          // Revert: clear `submission` (the optimistic view vanishes) leaving the data untouched, so the
+          // pre-submit page shows through.
           state = {
             routeId: state.routeId,
             params: state.params,
             path: state.path,
             data: state.data,
+            layoutData: state.layoutData,
+            ...(state.boundaries !== undefined ? { boundaries: state.boundaries } : {}),
             actionData: previousActionData,
             pending: false,
           }
           emit()
         }
-        throw err
+        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
       }
     },
     hydrate,
@@ -1101,7 +1200,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       await Promise.all(jobs)
     },
     prefetch: async (path) => {
-      if (prefetched.has(path) || inflight.has(path)) return
+      if (inflight.has(path) || freshPrefetch(path) !== undefined) return
       const matched = match(path)
       if (matched === null) return
       inflight.add(path)
@@ -1112,11 +1211,12 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           loadModule?.(matched.routeId),
           loadRouteData(path, matched),
         ])
+        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)
         }
-        prefetched.set(path, loaded)
+        prefetched.set(path, [loaded, Date.now()])
       } catch {
         // Best-effort: a failed prefetch just means the eventual navigate fetches normally.
       } finally {