@nifrajs/web 5.4.0 → 5.5.0

package/src/internal/output-guard.ts

@@ -12,6 +12,12 @@
  * Projection reads the schema's JSON Schema: a nifra schema's `jsonSchema`, or a Standard JSON Schema
  * (`~standard.jsonSchema.output`). A schema that exposes neither is trusted to strip unknown keys in
  * its own `validate` output, as zod and valibot objects do by default.
+ *
+ * Validation then runs on the projected value. A `@nifrajs/schema` schema validates it without the
+ * undeclared-key check of each closed object projection reached, which projection already did. A
+ * non-enumerable property is no key to either: JSON and `structuredClone` skip it and server
+ * component props refuse it, so it never reaches the browser. The one such property `JSON.stringify`
+ * does read, an own `toJSON` (or an array subclass's), never survives projection.
  */
 import type { StandardResult, StandardSchemaV1 } from "@nifrajs/core/server"
 import { markDeferredFree } from "./deferred-free.ts"
@@ -22,6 +28,8 @@ const RESPONSE_RESULT = Symbol.for("nifra.response.result")
 const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
 /** Set by `t.deferred(inner)` on its schema node: `inner`'s own validate. */
 const DEFERRED_VALIDATE = Symbol.for("nifra.schema.deferredValidate")
+/** On a `@nifrajs/schema` validate: its variant for a value projected by its own JSON Schema. */
+const VALIDATE_PROJECTED = Symbol.for("nifra.schema.validateProjected")
 
 export const DECLASSIFIED_KEY = "x-nifra-declassified"
 const DEFERRED_KEY = "x-nifra-deferred"
@@ -168,7 +176,7 @@ const DATE: Project = (value) =>
       : value
 
 /** An array whose items are all scalars, passed through whole. */
-const LEAF_ARRAY: Project = (value) => value
+const LEAF_ARRAY: Project = (value) => (Array.isArray(value) ? plainArray(value) : value)
 
 const typesOf = (node: Node): readonly unknown[] | undefined =>
   Array.isArray(node.type) ? node.type : node.type === undefined ? undefined : [node.type]
@@ -317,7 +325,7 @@ class Compiler {
     // A closed object drops a deferred marker's keys unless it declares them, so only an open one, or
     // one declaring the marker key, could pass a marker on.
     const checksMarker = open || declared.__nifra_deferred !== undefined
-    const project: Project = (value, state) => {
+    const closure: Project = (value, state) => {
       if (typeof value !== "object" || value === null || Array.isArray(value)) return value
       if (checksMarker && isDeferred(value)) {
         state.issues.push("")
@@ -325,13 +333,7 @@ class Compiler {
       }
       const proto = Object.getPrototypeOf(value)
       if (proto !== Object.prototype && proto !== null) {
-        if (value instanceof Date) return value.toJSON()
-        // A class instance: its own fields as a plain object, so no prototype `toJSON` or getter
-        // decides what is serialized.
-        const snapshot: Record<string, unknown> = {}
-        for (const key of Object.keys(value))
-          assign(snapshot, key, (value as Record<string, unknown>)[key])
-        return project(snapshot, state)
+        return value instanceof Date ? value.toJSON() : closure(snapshotOf(value), state)
       }
       const input = value as Record<string, unknown>
       // Copy-on-write: a value that already holds only declared keys is returned as it is.
@@ -345,7 +347,11 @@ class Compiler {
           continue
         }
         const before = input[key]
-        if (projector === LEAF_ARRAY || (projector === LEAF && !(before instanceof Date))) {
+        if (
+          projector === LEAF_ARRAY
+            ? !hasJsonHook(before)
+            : projector === LEAF && !(before instanceof Date)
+        ) {
           if (out !== undefined) assign(out, key, before)
           continue
         }
@@ -358,8 +364,10 @@ class Compiler {
           assign(out, key, after)
         }
       }
-      return out ?? value
+      return out ?? (input.toJSON === undefined ? value : snapshotOf(input))
     }
+    const project =
+      generatedObject(declared, open ? undeclared : undefined, checksMarker) ?? closure
     if (!checksMarker && Object.values(declared).every((child) => this.issueFree.has(child)))
       this.issueFree.add(project)
     return project
@@ -393,7 +401,7 @@ class Compiler {
             out[i] = after
           }
         }
-        return out ?? value
+        return plainArray(out ?? value)
       }
       this.issueFree.add(project)
       return project
@@ -417,7 +425,7 @@ class Compiler {
           out[i] = after
         }
       }
-      return out ?? value
+      return plainArray(out ?? value)
     }
   }
 
@@ -507,7 +515,7 @@ class Compiler {
     }
     const inner: CompiledGuard = {
       project: this.compile(node.inner, where),
-      validate: validate as CompiledGuard["validate"],
+      validate: validatorFor(validate as CompiledGuard["validate"], node.inner),
       warnDropped: inDevelopment(),
       deferredFree: false,
     }
@@ -522,6 +530,133 @@ class Compiler {
   }
 }
 
+/**
+ * A class instance as a plain object of its own fields, so no prototype `toJSON` or getter decides
+ * what is serialized.
+ */
+function snapshotOf(value: object): Record<string, unknown> {
+  const snapshot: Record<string, unknown> = {}
+  for (const key of Object.keys(value))
+    assign(snapshot, key, (value as Record<string, unknown>)[key])
+  return snapshot
+}
+
+/** Whether `JSON.stringify` would call a `toJSON` of `value`'s own or of its prototype chain. */
+const hasJsonHook = (value: unknown): boolean =>
+  typeof value === "object" &&
+  value !== null &&
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: reads one optional property of a value already narrowed to a non-null object.
+  (value as { readonly toJSON?: unknown }).toJSON !== undefined
+
+/**
+ * `value`, or a plain copy of its items when `JSON.stringify` would serialize it by a hook instead:
+ * an own `toJSON`, enumerable or not, or one on a subclass prototype (which `slice` also keeps).
+ */
+function plainArray(value: unknown[]): unknown[] {
+  if (!hasJsonHook(value)) return value
+  const copy = new Array<unknown>(value.length)
+  for (let i = 0; i < value.length; i++) copy[i] = value[i]
+  return copy
+}
+
+// Inside `for-in`, V8 folds `hasOwnProperty.call` into the loop but calls `Object.hasOwn` per key.
+// Bun runs both alike.
+const ownKey = Object.prototype.hasOwnProperty
+// Bun's string `switch` stops beating the dictionary lookup near 128 declared keys; V8's does not.
+const MAX_GENERATED_KEYS = 64
+
+/**
+ * The object projector as code generated for its declared keys: a `switch` on each key, with every
+ * key's projector a call site of its own. It reads, keeps and drops exactly what the closure in
+ * `Compiler.object` does, which serves where code generation is off: an edge bundle (the build
+ * defines `__NIFRA_EDGE_RUNTIME__`), a browser page (where even a caught attempt is a reported CSP
+ * violation), or a runtime that refuses it. Only `JSON.stringify`d key names reach the source.
+ */
+function generatedObject(
+  declared: Record<string, Project>,
+  undeclared: ((key: string) => Project | undefined) | undefined,
+  checksMarker: boolean,
+): Project | undefined {
+  const keys = Object.keys(declared)
+  // The edge build defines this global as `true`, so that bundle drops the generator.
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only nifra's build defines this global, as a boolean literal.
+  const edge = (globalThis as { readonly __NIFRA_EDGE_RUNTIME__?: boolean }).__NIFRA_EDGE_RUNTIME__
+  if (keys.length > MAX_GENERATED_KEYS || edge === true || "document" in globalThis)
+    return undefined
+  const tail = (store: (value: string) => string, call: string): string =>
+    `const from = state.issues.length; const after = ${call}(before, state);` +
+    "if (state.issues.length > from) prefix(state, from, key);" +
+    `if (out !== undefined) ${store("after")};` +
+    `else if (after !== before) { out = copyBefore(value, key); ${store("after")}; }` +
+    "continue;"
+  let cases = ""
+  for (const [i, key] of keys.entries()) {
+    const projector = declared[key]
+    const store = (value: string): string =>
+      key === "__proto__" ? `assign(out, key, ${value})` : `out[${JSON.stringify(key)}] = ${value}`
+    cases += `case ${JSON.stringify(key)}: { const before = value[key];`
+    if (projector === LEAF_ARRAY) {
+      cases += `if (!hasJsonHook(before)) { if (out !== undefined) ${store("before")}; continue; }`
+    } else if (projector === LEAF) {
+      cases += `if (!(before instanceof Date)) { if (out !== undefined) ${store("before")}; continue; }`
+    }
+    cases += `${tail(store, `p[${i}]`)} }`
+  }
+  const generic = (value: string): string => `assign(out, key, ${value})`
+  const rest =
+    undeclared === undefined
+      ? "out ??= copyBefore(value, key); continue;"
+      : "const projector = undeclared(key);" +
+        "if (projector === undefined) { out ??= copyBefore(value, key); continue; }" +
+        "const before = value[key];" +
+        "if (projector === LEAF_ARRAY ? !hasJsonHook(before) : projector === LEAF && !(before instanceof Date)) {" +
+        `if (out !== undefined) ${generic("before")}; continue; }` +
+        tail(generic, "projector")
+  const source =
+    '"use strict"; return function project(value, state) {' +
+    'if (typeof value !== "object" || value === null || Array.isArray(value)) return value;' +
+    (checksMarker ? 'if (isDeferred(value)) { state.issues.push(""); return value; }' : "") +
+    "const proto = Object.getPrototypeOf(value);" +
+    "if (proto !== Object.prototype && proto !== null)" +
+    "return value instanceof Date ? value.toJSON() : project(snapshotOf(value), state);" +
+    "let out;" +
+    "for (const key in value) {" +
+    "if (!ownKey.call(value, key)) continue;" +
+    `switch (key) { ${cases} default: { ${rest} } }` +
+    "}" +
+    "return out ?? (value.toJSON === undefined ? value : snapshotOf(value)); }"
+  try {
+    return new Function(
+      "p",
+      "undeclared",
+      "isDeferred",
+      "snapshotOf",
+      "copyBefore",
+      "assign",
+      "prefix",
+      "ownKey",
+      "hasJsonHook",
+      "LEAF",
+      "LEAF_ARRAY",
+      source,
+    )(
+      keys.map((key) => declared[key]),
+      undeclared,
+      isDeferred,
+      snapshotOf,
+      copyBefore,
+      assign,
+      prefix,
+      ownKey,
+      hasJsonHook,
+      LEAF,
+      LEAF_ARRAY,
+    )
+  } catch {
+    return undefined
+  }
+}
+
 /** The keys of a plain object before `stop`, every one of them kept as it is. */
 function copyBefore(input: Record<string, unknown>, stop: string): Record<string, unknown> {
   const out: Record<string, unknown> = {}
@@ -609,6 +744,19 @@ export function jsonSchemaOf(schema: StandardSchemaV1): Node | undefined {
   }
 }
 
+/**
+ * `validate`, or the variant its schema offers for a value projected by `json`: one that skips the
+ * undeclared-key check of each closed object the projection already kept to its declared keys.
+ */
+function validatorFor(validate: CompiledGuard["validate"], json: Node): CompiledGuard["validate"] {
+  const variant: unknown = Reflect.get(validate, VALIDATE_PROJECTED)
+  const projected: unknown = typeof variant === "function" ? variant(json) : undefined
+  return isValidate(projected) ? projected : validate
+}
+
+const isValidate = (value: unknown): value is CompiledGuard["validate"] =>
+  typeof value === "function"
+
 const compiled = new WeakMap<object, CompiledGuard>()
 
 /**
@@ -642,7 +790,10 @@ export function outputGuard(schema: unknown, owner: string, exportName: string):
   }
   const guard: CompiledGuard = {
     project,
-    validate: standard["~standard"].validate,
+    validate:
+      json === undefined
+        ? standard["~standard"].validate
+        : validatorFor(standard["~standard"].validate, json),
     warnDropped: inDevelopment(),
     deferredFree,
   }

package/src/internal/page-execution.ts

@@ -96,6 +96,13 @@ export interface PageRouteContext<Env = unknown> {
   /** The visitor's IP as the serving app derived it; forwarded to a request-bound `ctx.api`. */
   readonly clientIp?: string | undefined
   readonly waitUntil?: (promise: Promise<unknown>) => void
+  /** One request header, read off the serving app's source without building `req.headers`. */
+  readonly header?: (name: string) => string | null
+}
+
+/** Whether `c` is a client navigation's data request. On Node, `req.headers` builds every header. */
+function isDataRequest(c: PageRouteContext<unknown>): boolean {
+  return (c.header !== undefined ? c.header(DATA_HEADER) : c.req.headers.get(DATA_HEADER)) !== null
 }
 
 /** The page slot of an `ssr = false` route with no `HydrateFallback`: a component that renders nothing. */
@@ -139,11 +146,15 @@ class LoaderPlatform {
  * `x-nifra-redirect` on a 204 that keeps the redirect's own headers. `undefined` for any other outcome
  * or request.
  */
-function dataRedirect(req: Request, outcome: unknown): Response | ResponseResult | undefined {
-  if (req.headers.get(DATA_HEADER) === null) return undefined
+function dataRedirect(
+  req: Request,
+  isData: boolean,
+  outcome: unknown,
+): Response | ResponseResult | undefined {
+  if (!isData) return undefined
   if (isResponseResult(outcome)) {
     const plain = outcome.plain
-    if (plain === undefined) return dataRedirect(req, outcome.toResponse())
+    if (plain === undefined) return dataRedirect(req, isData, outcome.toResponse())
     if (plain.status < 300 || plain.status >= 400) return undefined
     const { location, ...own } = plain.headers ?? {}
     if (location === undefined) return undefined
@@ -676,8 +687,9 @@ export function createPageRequestExecutor<Env = unknown>(
    * The browser's side of a client navigation: the page it is leaving and the layout slots it asked
    * to keep. Undefined unless this is a data request whose `from` is same-origin and routable.
    */
-  const retainContextOf = (req: Request): RetainContext | undefined => {
-    if (req.headers.get(DATA_HEADER) === null) return undefined
+  const retainContextOf = (c: PageRouteContext<Env>): RetainContext | undefined => {
+    if (!isDataRequest(c)) return undefined
+    const req = c.req
     const requested = retainedIndices(req.headers.get(RETAIN_HEADER))
     const from = req.headers.get(NAV_FROM_HEADER)
     if (requested.size === 0 || from === null) return undefined
@@ -1065,6 +1077,7 @@ export function createPageRequestExecutor<Env = unknown>(
 
   const handleDataOrDocument = async (
     req: Request,
+    isData: boolean,
     env: Env,
     route: RouteEntry,
     params: Readonly<Record<string, string>>,
@@ -1084,7 +1097,7 @@ export function createPageRequestExecutor<Env = unknown>(
       settledLayouts(layoutModules, layoutData, count)
     if (isStatusSignal(data)) return renderStatusSignal(req, env, data, personalized, settled)
     if (isControlFlow(data)) return data
-    if (req.headers.get(DATA_HEADER) !== null) {
+    if (isData) {
       const pageSplit = prepareDeferred(data)
       const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
       let offset = pageSplit.deferred.length
@@ -1354,11 +1367,11 @@ export function createPageRequestExecutor<Env = unknown>(
       const controls = new PageResponseControls(c)
       try {
         const outcome = await run(c, controls)
-        const answer = dataRedirect(c.req, outcome) ?? outcome
+        const answer = dataRedirect(c.req, isDataRequest(c), outcome) ?? outcome
         return controls.personalized ? (privateOutcome(answer) as PageResponse) : answer
       } catch (err) {
         if (!isControlFlow(err)) throw err
-        const answer = dataRedirect(c.req, err)
+        const answer = dataRedirect(c.req, isDataRequest(c), err)
         // Returned rather than rethrown: the serving app sends a thrown `Response` exactly as it is,
         // without the cookies the request queued.
         if (controls.personalized) return privateOutcome(answer ?? err) as PageResponse
@@ -1448,7 +1461,7 @@ export function createPageRequestExecutor<Env = unknown>(
             route,
             ctx,
             controls,
-            componentOwner ? undefined : retainContextOf(c.req),
+            componentOwner ? undefined : retainContextOf(c),
           )
           layoutModules = run.modules
           layoutRetained = run.retained
@@ -1580,6 +1593,7 @@ export function createPageRequestExecutor<Env = unknown>(
         }
         return handleDataOrDocument(
           c.req,
+          isDataRequest(c),
           c.env,
           route,
           c.params,

package/src/internal/render-document.ts

@@ -748,9 +748,9 @@ function streamDocument(
     d.promise
       .then(
         (value) =>
-          // `serializeData` JSON-serializes the value and escapes `<`, `>`, and Unicode line
-          // separators before this framework-owned script is emitted.
-          `<script${nonceAttr}>window.__nifraResolve(${d.id},${serializeData(value)})</script>`, // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
+          // `serializeData` escapes `<`, `>`, and Unicode line separators. The JSON goes through
+          // `JSON.parse`, never read as an object literal, where a `"__proto__"` key sets the prototype.
+          `<script${nonceAttr}>window.__nifraResolve(${d.id},JSON.parse(${jsStringLiteral(serializeData(value))}))</script>`, // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
       )
       .catch((err: unknown) => {
         // A rejected (or unserializable) deferred streams __nifraReject (the client `<Await>`
@@ -1088,7 +1088,9 @@ export function revalidate<T>(paths: readonly string[], data: T): RevalidateResu
  * Serialize loader data for embedding inside an inline `<script>`. `JSON.stringify` alone
  * is NOT safe there: a string containing `</script>` or `<!--` would break out of the
  * script element (an XSS vector). Escape `<`/`>` to `\uXXXX`, plus the U+2028/U+2029
- * separators.
+ * separators. The result is JSON text: read it with `JSON.parse` (or from a
+ * `type="application/json"` script), never as a JavaScript object literal, where a `"__proto__"`
+ * key sets the object's prototype instead of becoming a property.
  */
 export function serializeData(data: unknown): string {
   const serialized = JSON.stringify(data ?? null)
@@ -1109,6 +1111,11 @@ export function serializeData(data: unknown): string {
     : serialized
 }
 
+/** Single-quoted JS string literal for script-safe JSON text, which has no raw line terminators. */
+function jsStringLiteral(json: string): string {
+  return `'${json.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`
+}
+
 function escapeHtml(value: string): string {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
 }

package/src/internal/web-app.ts

@@ -14,6 +14,12 @@ import type { MountableApp, MountOptions } from "@nifrajs/core/server"
 import { type ServerOptions, server } from "@nifrajs/core/server"
 import { type CspPolicy, cspNonceResolver, DOCUMENT_POLICY, isCspPolicy } from "../csp.ts"
 import type { CssLoadingMode } from "../css-contract.ts"
+import {
+  type BuildAssetSet,
+  type HostPolicy,
+  hostPolicyGate,
+  isHostPolicy,
+} from "../host-policy.ts"
 import { CACHE_CHANNEL } from "../isr.ts"
 import { generateLlmsTxt } from "../llms-txt.ts"
 import type { Manifest } from "../manifest.ts"
@@ -251,7 +257,8 @@ export interface CreateWebAppOptions<Env = unknown> {
   readonly cssLoading?: CssLoadingMode
   /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
    * `prerendered.json`). Handed over as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
-   * into a prerendered route fetches its static `_data.json` instead of hitting the worker. A set over
+   * into a prerendered route fetches its static `_data.json` instead of hitting the worker, unless the
+   * target carries a query string, which renders on demand as a hard request does. A set over
    * 4 KB of JSON is served once from `/__nifra/prerendered.json?v=<version>`, cacheable for good, and
    * pages hand over only that URL; `prerenderRoutes` writes the file into a static output. */
   readonly prerenderedPaths?: readonly string[]
@@ -263,6 +270,18 @@ export interface CreateWebAppOptions<Env = unknown> {
    * {@link nonce}, whose documents need a nonce minted for their request.
    */
   readonly prerenderedPages?: PrerenderedPages
+  /**
+   * Which pages and files each host serves, from `createHostPolicy()`. Evaluated before everything
+   * else the app answers (prerendered pages, mounts, the API, every page) and, in a `nifra build`
+   * server entry, before its static files too. A refused path answers the policy's refusal.
+   */
+  readonly hostPolicy?: HostPolicy
+  /**
+   * The files the build emitted, by request path: `buildAssets` from the generated server manifest.
+   * A {@link hostPolicy} rule's `buildAssets` token matches exactly these. `nifra dev` serves the
+   * client bundle and `public/` ahead of the app, so the app's own check never sees them there.
+   */
+  readonly buildAssets?: BuildAssetSet
   /** Publish the project's `AGENTS.md` inside `/llms.txt` and `/llms-full.txt`. **Off by default**:
    * those endpoints are public and unauthenticated, while `AGENTS.md` is a repo file written for the
    * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
@@ -395,6 +414,13 @@ export function createWebApp<Env = unknown>(
   // the platform bindings (see the `createWebApp` doc). The runtime `env` still arrives per-request via
   // `app.fetch(req, { env })`; this is a compile-time-only seed (`server<Env>()` casts, doesn't store).
   const app = server<Env>(options.server)
+  // First of all: a host's refused path must not reach a rate limiter, a mount or a page.
+  if (options.hostPolicy !== undefined) {
+    if (!isHostPolicy(options.hostPolicy)) {
+      throw new TypeError("[nifra/web] createWebApp `hostPolicy` must come from createHostPolicy()")
+    }
+    app.use(hostPolicyGate(options.hostPolicy, options.buildAssets))
+  }
   // Before the mount hooks and before every page route, so the order-scoped hooks (`derive`,
   // `beforeHandle`, assurance evidence) actually bind to them - see the `use` option. A caller
   // cannot do this after the fact: by the time this function returns, the routes are declared.

package/src/public-dir.ts

@@ -19,12 +19,14 @@ import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
 import {
+  CONTENT_SNAPSHOT_MAX,
   contentTags,
   contentTypeOf,
   ifRangeAllowsPartial,
   isHiddenPath,
   isNotModified,
   lastModifiedOf,
+  streamedLastModifiedOf,
 } from "@nifrajs/core/static-file"
 import { openResolved } from "./open-resolved.ts"
 
@@ -69,7 +71,7 @@ function hiddenUnder(root: string, abs: string): boolean {
 // Up to this many bytes are read whole through the pinned descriptor, which then closes before the
 // response leaves: on Bun a 200 KB asset is served in 0.17 ms against 0.28 ms through a node:fs
 // stream. A larger body streams, so a video holds a stream's buffer per request rather than the file.
-const BUFFERED_BODY_MAX = 256 * 1024
+const BUFFERED_BODY_MAX = CONTENT_SNAPSHOT_MAX
 // Bun.serve drops the declared length of any stream body and sends it chunked, and a Bun.file body
 // would need this descriptor open for a send nothing reports the end of. So on Bun a body up to 1 MiB
 // is read whole as well: a slow client then holds ~1 MB, against ~0.6 MB through Bun's stream sink.
@@ -125,9 +127,10 @@ export function resolvePublicPath(root: string, pathname: string): string | unde
  * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
  * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
  *
- * A file is sent with a strong `ETag` from its bytes, the tag `@nifrajs/node`'s `static` reader and
- * the Deno entry send, and with `Last-Modified` only while its mtime is that of its own last change,
- * so a replacement that keeps a file's size and timestamps is never judged current or resumed into.
+ * Files up to 256 KiB carry a strong `ETag` from the exact snapshot served, matching the Node and
+ * Deno readers. Those snapshots carry `Last-Modified` only while mtime reflects their own last change.
+ * Larger files stream without an `ETag`: an open inode can change after a separate hash pass. They
+ * are dated once settled, but an `If-Range` request gets the whole file rather than spliced versions.
  */
 export function servePublicDir(
   options: ServePublicDirOptions,
@@ -196,40 +199,44 @@ export function servePublicDir(
         // Set explicitly rather than inferred from the body, so HEAD (a null body) carries it too.
         "content-type": contentTypeOf(resolvedFile),
       })
-      // The whole file, when tagging it had to read it: the response is then served from these bytes.
-      let whole: Uint8Array<ArrayBuffer> | undefined
-      let etag = TAGS.cached(resolvedFile, stat)
-      if (etag === undefined && size <= bufferedMax) {
-        whole = await readPinned(file, 0, size)
-        etag = TAGS.ofBytes(resolvedFile, stat, whole)
-      }
-      etag ??= await TAGS.ofFile(resolvedFile, stat, async (bytes, position) => {
-        return (await file.read(bytes, 0, bytes.byteLength, position)).bytesRead
-      })
-      if (etag !== undefined) headers.set("etag", etag)
-      const lastModified = lastModifiedOf(stat)
+      const snapshot = size <= CONTENT_SNAPSHOT_MAX
+      const lastModified = snapshot ? lastModifiedOf(stat) : streamedLastModifiedOf(stat)
       if (lastModified !== undefined) {
         headers.set("last-modified", new Date(lastModified).toUTCString())
       }
       const head = request.method === "HEAD"
-
+      const ifNoneMatch = request.headers.get("if-none-match")
+      const ifModifiedSince = request.headers.get("if-modified-since")
+      // The whole file, when tagging it had to read it: the response is then served from these bytes.
+      let whole: Uint8Array<ArrayBuffer> | undefined
+      // A HEAD or a 304 sends none of the file, so the tag remembered for this settled version
+      // answers it from the stat alone: a write since that tag would show in the stat.
+      let etag = snapshot ? TAGS.cached(resolvedFile, stat) : undefined
       if (
-        isNotModified(
-          request.headers.get("if-none-match"),
-          request.headers.get("if-modified-since"),
-          etag,
-          lastModified,
-        )
+        snapshot &&
+        (etag === undefined ||
+          !(head || isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified)))
       ) {
+        whole = await readPinned(file, 0, size)
+        etag = await TAGS.ofSnapshot(resolvedFile, stat, whole, () => file.stat())
+      }
+      if (etag !== undefined) headers.set("etag", etag)
+
+      if (isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified)) {
         headers.delete("content-type")
         return new Response(null, { status: 304, headers })
       }
 
       // Range applies to GET only (RFC 9110 section 14.2); HEAD reports the whole representation.
       const rangeHeader = head ? null : request.headers.get("range")
+      // A streamed body's date is weak: a write during the stream must never splice two versions.
       const range =
         rangeHeader !== null &&
-        ifRangeAllowsPartial(request.headers.get("if-range"), etag, lastModified)
+        ifRangeAllowsPartial(
+          request.headers.get("if-range"),
+          etag,
+          snapshot ? lastModified : undefined,
+        )
           ? parseByteRange(rangeHeader, size)
           : ({ kind: "none" } as const)
 

package/src/router.ts

@@ -24,7 +24,8 @@ export const DATA_HEADER = "x-nifra-data"
 /**
  * Global the server injects (`createWebApp({ prerenderedPaths })`) listing the SSG-prerendered paths.
  * The client's default data fetch reads it: a soft-nav INTO a prerendered route fetches its static
- * `<path>/_data.json` (a CDN file - no worker round-trip) instead of the dynamic header-GET.
+ * `<path>/_data.json` (a CDN file - no worker round-trip) instead of the dynamic header-GET, unless
+ * the target carries a query string.
  */
 export const PRERENDERED_GLOBAL = "__NIFRA_PRERENDERED__"
 
@@ -422,13 +423,13 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation
   // 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 = await prerenderedOf()
-  if (Array.isArray(prerendered)) {
-    const query = path.indexOf("?")
-    const hash = path.indexOf("#")
-    // `indexOf` rather than `replace(/[?#].*$/)`: no regex allocation or backtracking on a
-    // caller-controlled navigation path.
-    const cut = query === -1 ? hash : hash === -1 ? query : Math.min(query, hash)
-    const pathname = cut === -1 ? path : path.slice(0, cut)
+  // `indexOf` rather than a regex: no allocation or backtracking on a caller-controlled path.
+  const query = path.indexOf("?")
+  const hash = path.indexOf("#")
+  // The file was rendered without a query, so a query-bearing path renders on demand, exactly as
+  // `servePrerenderedPages` answers the same URL on a hard request.
+  if (Array.isArray(prerendered) && (query === -1 || (hash !== -1 && hash < query))) {
+    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)

package/src/server-components/vite.ts

@@ -3,6 +3,10 @@ import { createRequire } from "node:module"
 import { resolve } from "node:path"
 import type * as TS from "typescript"
 import { type Plugin, version as viteVersion } from "vite"
+import {
+  CERTIFIED_COMPONENT_REACT,
+  CERTIFIED_COMPONENT_VITE,
+} from "../internal/certified-components.ts"
 import {
   compileComponentModule,
   componentReference,
@@ -102,25 +106,26 @@ export function serverComponentsPlugin(
     name: "nifra:server-components",
     enforce: "pre",
     configResolved(config) {
-      if (viteVersion !== "8.2.1")
+      if (viteVersion !== CERTIFIED_COMPONENT_VITE)
         throw new Error(
-          "[nifra/components] Use the certified Vite 8.2.1 component pipeline; Bun remains a supported server runtime",
+          `[nifra/components] Use the certified Vite ${CERTIFIED_COMPONENT_VITE} component pipeline, not ${viteVersion}; Bun remains a supported server runtime`,
         )
       if (options.adapter === "react") {
         const require = createRequire(resolve(config.root, "package.json"))
-        const versions = ["react", "react-dom", "react-server-dom-webpack"].map((name) => {
+        const packages = ["react", "react-dom", "react-server-dom-webpack"]
+        const versions = packages.map((name) => {
           try {
             // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The compiler inspects trusted AST/package metadata and its own populated stub map; application data never supplies these values.
             return (require(`${name}/package.json`) as { version: string }).version
           } catch {
             throw new Error(
-              `[nifra/components] Install ${name}@19.2.8 for the React component pipeline`,
+              `[nifra/components] Install ${name}@${CERTIFIED_COMPONENT_REACT} for the React component pipeline`,
             )
           }
         })
-        if (versions.some((version) => version !== "19.2.8"))
+        if (versions.some((version) => version !== CERTIFIED_COMPONENT_REACT))
           throw new Error(
-            "[nifra/components] React, React DOM, and Flight must all use the matching 19.2.8 version",
+            `[nifra/components] React, React DOM, and Flight must all use the matching ${CERTIFIED_COMPONENT_REACT} version, not ${packages.map((name, index) => `${name}@${versions[index]}`).join(", ")}`,
           )
       }
     },