@nifrajs/web 4.0.2 → 5.0.0

package/src/llms-txt.ts

@@ -3,9 +3,12 @@ import {
   reflectedRoutesFromEvidence,
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
+import { type BackendEvidenceProvider, NIFRA_BACKEND_EVIDENCE } from "@nifrajs/core/mount"
 import { compileRoutePattern, type RoutePatternSegment } from "@nifrajs/core/pattern"
 
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+const RESERVED_CLIENT_SEGMENT = /^(?:get|post|put|patch|delete|head|options)$/i
+const RESERVED_EXACT_SEGMENTS = new Set(["subscribe", "ws", "index", "then"])
 
 /** The subset of JSON Schema fields {@link tsTypeOf} reads to render a TypeScript type string. */
 interface JsonSchemaNode {
@@ -93,7 +96,13 @@ function clientCall(method: string, path: string, schema: unknown): string {
   if (segs.length === 0) chain += ".index"
   else
     for (const seg of segs) {
-      chain += paramCall(seg) ?? (IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`)
+      chain +=
+        paramCall(seg) ??
+        (RESERVED_CLIENT_SEGMENT.test(seg) || RESERVED_EXACT_SEGMENTS.has(seg)
+          ? `(${JSON.stringify(seg)})`
+          : IDENT.test(seg)
+            ? `.${seg}`
+            : `[${JSON.stringify(seg)}]`)
     }
   const isBodyVerb = verb === "post" || verb === "put" || verb === "patch"
   let call: string
@@ -101,12 +110,27 @@ function clientCall(method: string, path: string, schema: unknown): string {
     const bodyArg = s?.body ? "body" : s?.query ? "undefined" : ""
     const opts = s?.query ? (bodyArg ? ", { query }" : "{ query }") : ""
     call = `.${verb}(${bodyArg}${opts})`
+  } else if (verb === "delete") {
+    const fields = [...(s?.body ? ["body"] : []), ...(s?.query ? ["query"] : [])]
+    call = `.delete(${fields.length === 0 ? "" : `{ ${fields.join(", ")} }`})`
   } else {
     call = `.${verb}(${s?.query ? "{ query }" : ""})`
   }
   return `await ${chain}${call}`
 }
 
+async function backendEvidence(backend: unknown): Promise<ProjectEvidenceSnapshot> {
+  if (backend !== null && (typeof backend === "object" || typeof backend === "function")) {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object/function check allows reading the optional symbol-keyed provider without touching the client path proxy.
+    const provider = (backend as { readonly [NIFRA_BACKEND_EVIDENCE]?: unknown })[
+      NIFRA_BACKEND_EVIDENCE
+    ]
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: A callable at NIFRA_BACKEND_EVIDENCE implements the framework's trusted evidence-provider seam.
+    if (typeof provider === "function") return (provider as BackendEvidenceProvider).call(backend)
+  }
+  return snapshotProjectEvidence(backend)
+}
+
 /** Read the project's `AGENTS.md`, or `""` if there isn't one (or we're on an edge runtime with no
  * filesystem). Never throws - a missing file just means no guidelines section. */
 async function readAgentsMd(): Promise<string> {
@@ -134,6 +158,8 @@ export async function generateLlmsTxt(
     readonly includeLocalGuidelines?: boolean
     /** Reuse the project's canonical route-evidence pass when one is already available. */
     readonly evidence?: ProjectEvidenceSnapshot
+    /** The mount prefix a visitor's URL carries but the backend's own routes do not (`apiStrip`). */
+    readonly apiPathPrefix?: string
   } = {},
 ): Promise<string> {
   let output = ""
@@ -160,14 +186,17 @@ export async function generateLlmsTxt(
   // 3. API Routes
   output += `## API Routes\n\n`
   const apiRoutes = reflectedRoutesFromEvidence(
-    options.evidence ?? snapshotProjectEvidence(backend),
+    options.evidence ?? (await backendEvidence(backend)),
   )
 
   if (apiRoutes.length === 0) {
     output += `No API routes registered.\n`
   } else {
+    const prefix = options.apiPathPrefix ?? ""
     for (const route of apiRoutes) {
-      output += `- **${route.method}** \`${route.path}\`\n`
+      // The stripped backend's root is the bare prefix, as the mount matches it.
+      const path = prefix !== "" && route.path === "/" ? prefix : prefix + route.path
+      output += `- **${route.method}** \`${path}\`\n`
       if (full) {
         output += `  - Client Call: \`${clientCall(route.method, route.path, route.schema)}\`\n`
         const s = route.schema

package/src/manifest.ts

@@ -271,13 +271,24 @@ export interface Meta {
 }
 
 /**
- * Args for a route's `meta` function: the loader's `data` + the route `params` + the request `origin`.
- * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** -
- * `origin` is the only server-resolved fact it gets (so you needn't thread `siteUrl` through loader data
- * for absolute `og:url`/`canonical`/`og:image` URLs). See {@link origin}.
+ * Args for a route's or layout's `meta` function: its own loader's `data` + the page's `pageData` + the
+ * route `params` + the request `origin`. `meta()` runs in BOTH SSR and client navigation, so it has
+ * **no `request`/`process.env`/server access** - `origin` is the only server-resolved fact it gets (so you
+ * needn't thread `siteUrl` through loader data for absolute `og:url`/`canonical`/`og:image` URLs). See
+ * {@link origin}.
  */
 export interface MetaArgs<Data = unknown> {
+  /**
+   * The loader data of the module that exports this `meta`: the page's for a page, the layout's own for a
+   * layout (`null` when the layout has no loader), the same value its component receives. A layout that
+   * loads the locale sets `lang` from here, so a soft navigation keeps it.
+   */
   readonly data: Data
+  /**
+   * The page's loader data, for a layout's `meta` that builds on the page (a title template). In a page's
+   * own `meta` it is the same value as {@link data}. Always set by the framework.
+   */
+  readonly pageData?: unknown
   readonly params: Record<string, string>
   /** The resolved document CSP nonce, when this render uses per-request nonce protection. */
   readonly nonce?: string
@@ -323,6 +334,8 @@ export type GetStaticPaths = () => StaticPaths | Promise<StaticPaths>
 export interface RouteModule {
   readonly default: unknown
   readonly loader?: Loader
+  /** Layout loader that must run before actions and is not retained across the action's render. */
+  readonly gate?: boolean
   readonly action?: Action
   /**
    * Backend half only: the schema of what {@link loader} sends to the browser. Required whenever the
@@ -384,6 +397,14 @@ export interface RouteModule {
    * the module on the server and in the browser, so it must be the same value on both.
    */
   readonly handle?: unknown
+  /**
+   * On a root status page (`_404.tsx`, `_<status>.tsx`) or an `_error.tsx`. By default (`true`) the
+   * page renders inside the layouts above it with their loader data and `meta`, as a nested `_404`
+   * renders. When those layouts cannot render it - a loader throws, a gate or the middleware refuses -
+   * a root status page renders alone and an `_error` inside its layouts without their data, with the
+   * same status. `false` always renders them that way, and runs no layout loader for them.
+   */
+  readonly inLayouts?: boolean
   /**
    * Opt a **static** route (no `:param`/`*`) into build-time prerendering (SSG): `prerenderRoutes`
    * (from `@nifrajs/web/build`) renders it to a static `index.html` at build. The loader runs at build
@@ -998,6 +1019,9 @@ const ancestorDirs = (file: string): string[] => {
  * turns a path into a lazy module loader. Pure - no fs. Throws at boot (the loud-and-early
  * RouteConfigError ethos) on duplicate patterns. `_layout`/`_404`/`_error`/`_loading`/`_middleware`
  * files are special; other `_`-prefixed files are ignored (private/colocated, never routed).
+ * A page pairs with its `.backend.*` half only when both are in `files`, so a hand-written list that
+ * omits the half serves the page without its loader and guards; `discoverRoutes` from
+ * `@nifrajs/web/fs` scans a routes dir and never does.
  */
 export function buildManifest(
   files: readonly string[],

package/src/open-resolved.ts

@@ -0,0 +1,64 @@
+import { constants as FS } from "node:fs"
+import { type FileHandle, open, readlink, realpath, stat } from "node:fs/promises"
+
+// Darwin's open(2) flag refusing a symlink in ANY component; `O_NOFOLLOW` covers only the last one.
+const O_NOFOLLOW_ANY = 0x20000000
+// Deno's node:fs rejects flags it does not know with EINVAL; the first refusal turns the flag off.
+let noFollowAny: boolean | undefined
+
+/**
+ * Open a name `realpath` already resolved, refusing it when any component became a symlink since.
+ * A local writer inside the served tree can swap an intermediate directory for a link after the
+ * containment check; `O_NOFOLLOW` alone would follow it. Darwin refuses such a path in the kernel;
+ * Linux reads back the name the descriptor holds. Elsewhere, Windows included, no file API can open
+ * without following a middle link or name an open descriptor's path, so the check in
+ * {@link opensAt} is a platform limit: it narrows the race to repeated swaps but cannot close it.
+ */
+export async function openResolved(realFile: string): Promise<FileHandle> {
+  // Read per open, not at load: this module can sit in a client bundle graph, where `process` is
+  // undefined.
+  if (noFollowAny ?? process.platform === "darwin") {
+    try {
+      return await open(realFile, FS.O_RDONLY | O_NOFOLLOW_ANY)
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EINVAL")) throw error
+      noFollowAny = false
+    }
+  }
+  const handle = await open(realFile, FS.O_RDONLY | FS.O_NOFOLLOW)
+  try {
+    if (await opensAt(handle, realFile)) return handle
+  } catch {}
+  await handle.close()
+  throw Object.assign(new Error(`${realFile} moved while it was opened`), { code: "ELOOP" })
+}
+
+/** Whether `handle` is the file at `realFile` with no symlink in its path. */
+export async function opensAt(
+  handle: Pick<FileHandle, "fd" | "stat">,
+  realFile: string,
+): Promise<boolean> {
+  try {
+    return (await readlink(`/proc/self/fd/${handle.fd}`)) === realFile
+  } catch {
+    return sameFileAt(handle, realFile)
+  }
+}
+
+/**
+ * {@link opensAt} where no descriptor's path can be read. Exported for its test, which runs it on
+ * every host.
+ */
+export async function sameFileAt(
+  handle: Pick<FileHandle, "stat">,
+  realFile: string,
+): Promise<boolean> {
+  // One step after another, so passing takes a swap back and a swap again between steps: the name
+  // resolves to itself, then to the opened file, then to itself again. Identities are compared as
+  // bigints because a Windows file index can exceed 2^53.
+  if ((await realpath(realFile)) !== realFile) return false
+  const opened = await handle.stat({ bigint: true })
+  const named = await stat(realFile, { bigint: true })
+  if (opened.dev !== named.dev || opened.ino !== named.ino) return false
+  return (await realpath(realFile)) === realFile
+}

package/src/plugins/kit.ts

@@ -4,7 +4,7 @@
  * CSS→client-bundle wiring, the deterministic hash, or the optional-peer guard. Internal to
  * `@nifrajs/web` (imported by the sibling plugin modules); not a public subpath.
  */
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { dirname, join, relative } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import type { BunPlugin } from "bun"
@@ -23,7 +23,7 @@ export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
  */
 export { rewriteSsrImports } from "../dev-ssr-graph.ts"
 
-const packageRootCache = new Map<string, string>()
+const packageCache = new Map<string, PackageOf>()
 
 /**
  * Convert a plugin/runtime path into a path the host filesystem can open.
@@ -57,14 +57,31 @@ export function portablePath(path: string): string {
   return normalizeFilePath(path).replaceAll("\\", "/")
 }
 
-/** The nearest ancestor directory of `startDir` that holds a `package.json` (the file's package root),
- * cached. Falls back to `startDir` if none is found, so it never throws. */
-function packageRootOf(startDir: string): string {
-  const cached = packageRootCache.get(startDir)
+interface PackageOf {
+  readonly root: string
+  readonly name: string
+}
+
+/** The nearest ancestor directory of `startDir` that holds a `package.json` (the file's package root)
+ * and that package's `name` (`""` when it has none), cached. Falls back to `startDir` if none is found,
+ * so it never throws. */
+function packageOf(startDir: string): PackageOf {
+  const cached = packageCache.get(startDir)
   if (cached !== undefined) return cached
   let dir = startDir
+  let name = ""
   for (;;) {
-    if (existsSync(join(dir, "package.json"))) break
+    const manifest = join(dir, "package.json")
+    if (existsSync(manifest)) {
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(manifest, "utf8"))
+        if (typeof parsed === "object" && parsed !== null && "name" in parsed)
+          name = typeof parsed.name === "string" ? parsed.name : ""
+      } catch {
+        // An unreadable manifest still marks the package root; the name is only a disambiguator.
+      }
+      break
+    }
     const parent = dirname(dir)
     if (parent === dir) {
       dir = startDir // reached the filesystem root with no package.json - anchor on the file's own dir
@@ -72,8 +89,9 @@ function packageRootOf(startDir: string): string {
     }
     dir = parent
   }
-  packageRootCache.set(startDir, dir)
-  return dir
+  const found = { root: dir, name }
+  packageCache.set(startDir, found)
+  return found
 }
 
 /**
@@ -84,11 +102,13 @@ function packageRootOf(startDir: string): string {
  * different machines or from different cwds - derive the SAME relative path for a given file, so their
  * scoped class maps always agree. (Hashing the absolute path would differ across CI/host; a
  * cwd-relative path would silently desync if the SSR server started from a non-project-root cwd.)
+ * The package's `name` leads the path, so `src/Card.vue` in two workspace packages hashes apart.
  */
 export function reproduciblePath(absolutePath: string): string {
   const filePath = normalizeFilePath(absolutePath)
-  const root = packageRootOf(dirname(filePath))
-  return relative(root, filePath).replaceAll("\\", "/")
+  const { root, name } = packageOf(dirname(filePath))
+  const path = relative(root, filePath).replaceAll("\\", "/")
+  return name === "" ? path : `${name}/${path}`
 }
 
 /**

package/src/plugins/vite-leak-guard.ts

@@ -251,6 +251,7 @@ function secretLeak(
       artifacts,
       env: options.secrets?.env ?? process.env,
       publicEnvPrefix: options.publicEnvPrefix ?? "PUBLIC_",
+      // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: Explicitly configured secret-scan exemptions preserve their absence by default.
       ...(options.secrets?.exemptions ? { exemptions: options.secrets.exemptions } : {}),
     }),
   )
@@ -260,7 +261,7 @@ function secretLeak(
 export type ServerZoneGuardOptions = Pick<
   LeakGuardOptions,
   "appRoot" | "routesDir" | "generatedFiles" | "publicEnvPrefix"
->
+> & { readonly componentModules?: ReadonlySet<string> }
 
 /**
  * The server build's half of the zone rules, with the same checks and message as nifra's Bun server
@@ -285,6 +286,9 @@ export function viteServerZoneGuard(options: ServerZoneGuardOptions = {}): LeakG
           classifier,
           sourceOf: rollupModuleSource,
           privateEnv: privateEnvCheck(options.publicEnvPrefix ?? "PUBLIC_"),
+          ...(options.componentModules === undefined
+            ? {}
+            : { componentModules: options.componentModules }),
         }),
       )
       if (leak === undefined) return

package/src/public-dir.ts

@@ -12,12 +12,12 @@
  * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
  * The names collide and the concepts do not: `publicPath` never covers user-authored files.
  */
-import { constants as FS } from "node:fs"
-import { open, realpath } from "node:fs/promises"
+import { realpath } from "node:fs/promises"
 import { extname, normalize, resolve, sep } from "node:path"
 import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
+import { openResolved } from "./open-resolved.ts"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
  * user-authored file keeps its name across deploys, so it gets a day and a revalidation. */
@@ -31,8 +31,15 @@ export interface PublicDirCache {
 export interface ServePublicDirOptions {
   /** Absolute path of the directory to serve. */
   readonly dir: string
-  /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`). */
+  /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`).
+   * Ignored when `hashedFiles` is set. */
   readonly hashedPrefix?: string
+  /**
+   * Encoded URL paths of the content-hashed files, such as a build manifest's `assets`. When set, only
+   * these are cached immutably and every other file gets the `assets` policy, so a user-authored file
+   * that happens to sit under the hashed prefix still revalidates.
+   */
+  readonly hashedFiles?: ReadonlySet<string>
   readonly cache?: PublicDirCache
   /** Optional encoded URL-path allowlist. When present, route misses avoid a filesystem probe. */
   readonly files?: ReadonlySet<string>
@@ -166,6 +173,7 @@ export function servePublicDir(
   const root = resolve(options.dir)
   const rootReal = realpath(root).catch(() => undefined)
   const hashedPrefix = options.hashedPrefix ?? "/assets/"
+  const hashedFiles = options.hashedFiles
   const hashed = options.cache?.hashed ?? IMMUTABLE
   const assets = options.cache?.assets ?? ONE_DAY
 
@@ -192,16 +200,27 @@ export function servePublicDir(
     }
     // Open the canonical path once and stream from that descriptor. Reopening the pathname after
     // realpath containment checks would let a writable public tree swap a symlink between validation
-    // and the actual read. O_NOFOLLOW also rejects a final-component symlink if one appears before
-    // the open; the descriptor then pins the bytes for the lifetime of the response.
-    let handle: Awaited<ReturnType<typeof open>> | undefined
+    // and the actual read. openResolved also refuses the name once any component of it became a
+    // symlink; the descriptor then pins the bytes for the lifetime of the response.
+    let handle: Awaited<ReturnType<typeof openResolved>> | undefined
     try {
-      handle = await open(resolvedFile, FS.O_RDONLY | FS.O_NOFOLLOW)
+      try {
+        handle = await openResolved(resolvedFile)
+      } catch {
+        // A name refused or gone since realpath falls through, as a failed realpath does.
+        return undefined
+      }
       const stat = await handle.stat()
       if (!stat.isFile()) return undefined
       const size = stat.size
       const headers = new Headers({
-        "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+        "cache-control": (
+          hashedFiles === undefined
+            ? pathname.startsWith(hashedPrefix)
+            : hashedFiles.has(pathname)
+        )
+          ? hashed
+          : assets,
         // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
         // so a video or audio file under `public/` is scrubbable only once this header is present.
         "accept-ranges": "bytes",

package/src/query.ts

@@ -111,6 +111,12 @@ export interface DehydratedState {
     readonly data: unknown
     readonly updatedAt: number
   }>
+  /** The successful infinite queries, pages and page params. */
+  readonly infiniteQueries?: ReadonlyArray<{
+    readonly key: unknown
+    readonly data: InfiniteData<unknown, unknown>
+    readonly updatedAt: number
+  }>
 }
 
 /** The keyed query cache. One per app (a binding registers it like the router). */
@@ -125,8 +131,9 @@ export interface QueryClient {
     fn: (pageParam: P) => Promise<T>,
     options: InfiniteQueryOptions<T, P>,
   ) => InfiniteQueryHandle<T, P>
-  /** Mark matching cached queries stale and refetch the **mounted** ones (subscribers > 0). Array
-   * keys match by **prefix** (`["todo"]` ⇒ every `["todo", …]`); other keys match exactly. */
+  /** Mark matching cached queries, infinite ones included, stale and refetch the **mounted** ones
+   * (subscribers > 0). Array keys match by **prefix** (`["todo"]` ⇒ every `["todo", …]`); other keys
+   * match exactly. */
   invalidateQueries: (keyOrPrefix: unknown) => void
   /** Read a cached query's data (`undefined` if absent or not yet successful). Synchronous, no fetch. */
   getQueryData: <T>(key: unknown) => T | undefined
@@ -218,17 +225,24 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
 
   // Lazily evict entries whose GC timer has elapsed (no subscribers), then enforce the hard cap by
   // dropping the oldest-inserted unsubscribed entries. Called on every `query()` - no background timer.
-  const sweep = (): void => {
-    const t = now()
-    for (const [h, e] of cache) {
-      if (e.subscribers === 0 && e.gcAt !== undefined && t >= e.gcAt) cache.delete(h)
+  const sweepEntries = (
+    entries: Map<string, { readonly subscribers: number; readonly gcAt: number | undefined }>,
+    t: number,
+  ): void => {
+    for (const [h, e] of entries) {
+      if (e.subscribers === 0 && e.gcAt !== undefined && t >= e.gcAt) entries.delete(h)
     }
-    if (cache.size <= max) return
-    for (const [h, e] of cache) {
-      if (cache.size <= max) break
-      if (e.subscribers === 0) cache.delete(h) // oldest-inserted unsubscribed first (Map order)
+    if (entries.size <= max) return
+    for (const [h, e] of entries) {
+      if (entries.size <= max) break
+      if (e.subscribers === 0) entries.delete(h) // oldest-inserted unsubscribed first (Map order)
     }
   }
+  const sweep = (): void => {
+    const t = now()
+    sweepEntries(cache, t)
+    sweepEntries(infinite, t)
+  }
 
   // Build a cache entry + its handle. `fn`/`staleTime` are mutated in place on re-bind (closures change
   // between renders). All the fetch/dedup/generation machinery lives here so query(), prefetchQuery(),
@@ -348,6 +362,9 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       entry.generation++
       if (entry.subscribers > 0) void entry.handle.refetch().catch(() => {}) // refresh mounted now (best-effort)
     }
+    for (const entry of infinite.values()) {
+      if (keyMatchesPrefix(entry.key, keyOrPrefix)) entry.invalidate()
+    }
   }
 
   const getQueryData = <T>(key: unknown): T | undefined => {
@@ -392,7 +409,17 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       if (entry.state.status === "success")
         queries.push({ key: entry.key, data: entry.state.data, updatedAt: entry.state.updatedAt })
     }
-    return { queries }
+    const infiniteQueries: Array<{
+      key: unknown
+      data: InfiniteData<unknown, unknown>
+      updatedAt: number
+    }> = []
+    for (const entry of infinite.values()) {
+      const { status, data, updatedAt } = entry.handle.snapshot()
+      if (status === "success" && data !== undefined)
+        infiniteQueries.push({ key: entry.key, data, updatedAt })
+    }
+    return { queries, infiniteQueries }
   }
 
   const hydrate = (state: DehydratedState): void => {
@@ -409,6 +436,14 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       if (entry.state.status !== "success" || q.updatedAt > entry.state.updatedAt)
         entry.setState(successState(q.data, q.updatedAt))
     }
+    // An infinite entry needs its page options before it can exist, so a snapshot for a key not yet
+    // queried waits here until `infiniteQuery` creates it.
+    for (const q of state.infiniteQueries ?? []) {
+      const h = hashQueryKey(q.key)
+      const existing = infinite.get(h)
+      if (existing === undefined) seeded.set(h, q)
+      else existing.seed(q.data, q.updatedAt)
+    }
   }
 
   // --- Infinite (paged) queries -----------------------------------------------------------------
@@ -427,19 +462,33 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       )
       return existing.handle as InfiniteQueryHandle<T, P>
     }
-    const created = makeInfinite<T, P>(fn, opts)
+    const created = makeInfinite<T, P>(key, fn, opts)
     infinite.set(h, created as InfiniteEntry<unknown, unknown>)
+    const snapshot = seeded.get(h)
+    if (snapshot !== undefined) {
+      seeded.delete(h)
+      created.seed(snapshot.data, snapshot.updatedAt)
+    }
     return created.handle
   }
 
   // Infinite entries live in their own map (their data shape + fetch model differ from plain queries).
   interface InfiniteEntry<T, P> {
+    readonly key: unknown
     handle: InfiniteQueryHandle<T, P>
     rebind: (fn: (p: P) => Promise<T>, opts: InfiniteQueryOptions<T, P>) => void
+    /** Mark stale, drop an in-flight fetch's result, and refetch when mounted. */
+    invalidate: () => void
+    /** Take a dehydrated snapshot unless the entry already holds fresher data. */
+    seed: (data: InfiniteData<unknown, unknown>, updatedAt: number) => void
+    subscribers: number
+    gcAt: number | undefined
   }
   const infinite = new Map<string, InfiniteEntry<unknown, unknown>>()
+  const seeded = new Map<string, NonNullable<DehydratedState["infiniteQueries"]>[number]>()
 
   const makeInfinite = <T, P>(
+    key: unknown,
     fetchPage: (pageParam: P) => Promise<T>,
     initialOpts: InfiniteQueryOptions<T, P>,
   ): InfiniteEntry<T, P> => {
@@ -447,6 +496,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     let opts = initialOpts
     let state: QueryState<InfiniteData<T, P>> = PENDING as QueryState<InfiniteData<T, P>>
     let generation = 0
+    let invalidated = false
     let promise: Promise<InfiniteData<T, P>> | undefined
     const listeners = new Set<() => void>()
     const emit = (): void => {
@@ -475,7 +525,8 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         data.pageParams,
       )
     }
-    const isStale = (): boolean => now() - state.updatedAt >= (opts.staleTime ?? defaultStaleTime)
+    const isStale = (): boolean =>
+      invalidated || now() - state.updatedAt >= (opts.staleTime ?? defaultStaleTime)
 
     // Run a paged operation under a fresh generation, guarding against a superseding op (like `run`).
     const runPaged = (build: () => Promise<InfiniteData<T, P>>): Promise<InfiniteData<T, P>> => {
@@ -486,6 +537,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         try {
           const data = await build()
           if (gen !== generation) return data
+          invalidated = false
           setState(successState(data, now()))
           return data
         } catch (error) {
@@ -511,9 +563,13 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     const handle: InfiniteQueryHandle<T, P> = {
       snapshot: () => state,
       subscribe: (listener) => {
+        entry.subscribers++
+        entry.gcAt = undefined
         listeners.add(listener)
         return () => {
           listeners.delete(listener)
+          entry.subscribers--
+          if (entry.subscribers === 0) entry.gcAt = now() + gcTime
         }
       },
       fetch: () => fetchFirst(false),
@@ -558,13 +614,30 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         return p !== undefined && p !== null
       },
     }
-    return {
-      handle: handle as InfiniteQueryHandle<unknown, unknown>,
+    const entry: InfiniteEntry<T, P> = {
+      key,
+      handle,
       rebind: (nextFn, nextOpts) => {
         fn = nextFn
         opts = nextOpts
       },
-    } as InfiniteEntry<T, P>
+      invalidate: () => {
+        invalidated = true
+        // A fetch begun before this point read pre-mutation data: it may not publish, and a new fetch
+        // must not join it.
+        generation++
+        promise = undefined
+        if (entry.subscribers > 0) void handle.refetch().catch(() => {})
+      },
+      seed: (data, updatedAt) => {
+        if (state.status === "success" && state.updatedAt >= updatedAt) return
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the snapshot was dehydrated from an entry under this key, whose pages and params are T and P
+        setState(successState(data as InfiniteData<T, P>, updatedAt))
+      },
+      subscribers: 0,
+      gcAt: undefined,
+    }
+    return entry
   }
 
   return {
@@ -609,8 +682,10 @@ export interface MutationCallbacks<TData, TVariables> {
 export interface MutationHandle<TData, TVariables> {
   snapshot: () => MutationState<TData, TVariables>
   subscribe: (listener: () => void) => () => void
-  /** Run the mutation. Resolves to the data (and runs onSuccess/onSettled) or rejects (onError/onSettled).
-   * The latest concurrent call wins the published state (older results are dropped). */
+  /** Run the mutation. Resolves to the data (and runs onSuccess/onSettled) or rejects (onError/onSettled);
+   * a throwing `onMutate` fails it the same way. A throwing `onSuccess` or `onSettled` after the write
+   * rejects the call but leaves the state `success` and never calls `onError`. The latest concurrent
+   * call wins the published state (older results are dropped). */
   mutate: (variables: TVariables) => Promise<TData>
   /** Rebind the latest `fn`/callbacks (closures change between renders) without losing state. */
   rebind: (
@@ -667,21 +742,27 @@ export function createMutation<TData, TVariables>(
     mutate: async (variables) => {
       const mine = ++latest
       setState({ status: "pending", data: undefined, error: undefined, variables })
-      // Only await a callback when one is actually supplied - an `await undefined` would insert a
-      // needless microtask before the mutationFn runs (and complicates single-flight timing).
-      if (cbs.onMutate !== undefined) await cbs.onMutate(variables)
+      let data: TData
       try {
-        const data = await mutationFn(variables)
-        if (mine === latest) setState({ status: "success", data, error: undefined, variables })
-        if (cbs.onSuccess !== undefined) await cbs.onSuccess(data, variables)
-        if (cbs.onSettled !== undefined) await cbs.onSettled(data, undefined, variables)
-        return data
+        // Only await a callback when one is actually supplied - an `await undefined` would insert a
+        // needless microtask before the mutationFn runs (and complicates single-flight timing).
+        if (cbs.onMutate !== undefined) await cbs.onMutate(variables)
+        data = await mutationFn(variables)
       } catch (error) {
         if (mine === latest) setState({ status: "error", data: undefined, error, variables })
         if (cbs.onError !== undefined) await cbs.onError(error, variables)
         if (cbs.onSettled !== undefined) await cbs.onSettled(undefined, error, variables)
         throw error
       }
+      if (mine === latest) setState({ status: "success", data, error: undefined, variables })
+      // The write happened: a success callback that throws rejects the call, but is no failure of the
+      // write, so it never reaches onError (which would roll back what the server kept).
+      try {
+        if (cbs.onSuccess !== undefined) await cbs.onSuccess(data, variables)
+      } finally {
+        if (cbs.onSettled !== undefined) await cbs.onSettled(data, undefined, variables)
+      }
+      return data
     },
   }
 }