@nifrajs/web 5.2.0 → 5.3.0

package/src/internal/render-document.ts

@@ -1,6 +1,12 @@
 import { isSameOriginPath, type ResponseResult, status as statusResult } from "@nifrajs/core/server"
 import type { BoundaryRegistration, BoundaryStates } from "../boundary.ts"
-import { type CspPolicy, cspDocumentNonce, cspHeaderValue, prepareCspPolicy } from "../csp.ts"
+import {
+  type CspPolicy,
+  cspCandidateNonce,
+  cspDocumentNonce,
+  cspHeaderValue,
+  prepareCspPolicy,
+} from "../csp.ts"
 import { type CssLoadingMode, DEFAULT_CSS_LOADING, normalizeCssLoading } from "../css-contract.ts"
 import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../deferred.ts"
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.ts"
@@ -54,6 +60,13 @@ const SCRIPT_ESCAPE_MAP: Readonly<Record<string, string>> = {
   [LINE_SEP]: "\\u2028",
   [PARA_SEP]: "\\u2029",
 }
+// Pages (the chain's last entry) whose string render suspended, with how many more requests go
+// straight to the stream instead of rendering the whole tree twice. The count runs out so a page
+// that suspended only once (a cold `lazy`) gets its buffered render back.
+const SUSPENDING_PAGES = new WeakMap<object, number>()
+const SUSPENDED_STREAMS = 32
+const isWeakKey = (value: unknown): value is object =>
+  (typeof value === "object" && value !== null) || typeof value === "function"
 const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
 const RESPONSE_RESULT = Symbol.for("nifra.response.result")
 
@@ -544,43 +557,77 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // streaming renderer are pure overhead vs a single sync render + concat. A buffered string body also
   // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
   // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
+  const streamed = (streamNonce: string | undefined): Promise<RenderedPage> =>
+    renderStreamedPage(
+      adapter,
+      chain,
+      renderProps,
+      shellOf,
+      parts,
+      closeRootHtml,
+      allDeferred,
+      tailHtml,
+      status,
+      headers,
+      streamNonce,
+      streamNonce === nonce ? nonceAttr : ` nonce="${escapeAttr(streamNonce ?? "")}"`,
+    ).then((response) => new ResponseRenderedPage(response))
+  const last = chain[chain.length - 1]
+  const leaf = isWeakKey(last) ? last : undefined
   if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
+    // Under a CSP a render can still write a script for this request alone (Solid's serialized
+    // error boundary, React's streamed Suspense reveal): it is handed a nonce, which the document
+    // keeps only when the render used it, so every other document stays nonce-free and cacheable.
+    const renderNonce =
+      nonce ?? (csp === undefined ? undefined : cspCandidateNonce(csp, requestedNonce))
+    const adoptNonce = (): void => {
+      if (renderNonce === nonce || csp === undefined || renderNonce === undefined) return
+      headers["cache-control"] = "private, no-store"
+      const policy = cspHeaderValue(csp, adapter, renderNonce)
+      if (policy !== undefined) headers["content-security-policy"] = policy
+    }
+    // A page whose string render suspended before goes straight to the stream: the string pass
+    // would render the whole tree only to be thrown away again.
+    const skips = leaf === undefined ? undefined : SUSPENDING_PAGES.get(leaf)
+    if (leaf !== undefined && skips !== undefined) {
+      if (skips > 1) SUSPENDING_PAGES.set(leaf, skips - 1)
+      else SUSPENDING_PAGES.delete(leaf)
+      adoptNonce()
+      return streamed(renderNonce)
+    }
     const out =
       parts !== undefined
         ? adapter.renderToString(
             chain,
             renderProps,
-            nonce === undefined ? { parts } : { nonce, parts },
+            renderNonce === undefined ? { parts } : { nonce: renderNonce, parts },
           )
-        : nonce === undefined
+        : renderNonce === undefined
           ? adapter.renderToString(chain, renderProps)
-          : adapter.renderToString(chain, renderProps, { nonce })
-    return typeof out === "string"
-      ? new BufferedRenderedPage(shellOf() + out + closeRootHtml + tailHtml, status, headers)
-      : out.then(
-          (bodyHtml) =>
-            new BufferedRenderedPage(
-              shellOf() + bodyHtml + closeRootHtml + tailHtml,
-              status,
-              headers,
-            ),
-        )
+          : adapter.renderToString(chain, renderProps, { nonce: renderNonce })
+    const page = (bodyHtml: string | undefined): MaybePromise<RenderedPage> => {
+      if (bodyHtml === undefined) {
+        // The render suspended on something only the streaming renderer waits for (React's `use`
+        // in a `<Suspense>`): stream the page, so the boundary resolves on the server.
+        if (leaf !== undefined) SUSPENDING_PAGES.set(leaf, SUSPENDED_STREAMS)
+        if (parts !== undefined) {
+          parts.head = ""
+          parts.body = ""
+        }
+        adoptNonce()
+        return streamed(renderNonce)
+      }
+      if (renderNonce !== undefined && bodyHtml.includes(`nonce="${renderNonce}"`)) adoptNonce()
+      return new BufferedRenderedPage(
+        shellOf() + bodyHtml + closeRootHtml + tailHtml,
+        status,
+        headers,
+      )
+    }
+    return out instanceof Promise ? out.then(page) : page(out)
   }
 
-  return renderStreamedPage(
-    adapter,
-    chain,
-    renderProps,
-    shellOf,
-    parts,
-    closeRootHtml,
-    allDeferred,
-    tailHtml,
-    status,
-    headers,
-    nonce,
-    nonceAttr,
-  ).then((response) => new ResponseRenderedPage(response))
+  return streamed(nonce)
 }
 
 async function renderStreamedPage(
@@ -673,6 +720,9 @@ function htmlResponse(body: string, init: ResponseInit): Response {
  * script per deferred value (emitted once its promise settles - by now the app stream has awaited
  * the same Suspense boundaries - and placed OUTSIDE `#root`) → `tail`. A mid-stream app error errors
  * the result (the body breaks) rather than silently truncating a 200.
+ *
+ * The app stream is read one chunk per pull, so a client that stops reading stops the renderer
+ * too: a stalled connection holds a chunk, not the whole rendered body.
  */
 function streamDocument(
   shell: Uint8Array,
@@ -687,45 +737,59 @@ function streamDocument(
   // A client that goes away cancels the body: the renderer stops, and nothing more is written.
   let cancelled = false
   let released = false
+  const release = (): void => {
+    if (released) return
+    released = true
+    reader.releaseLock()
+  }
+  // Settled into scripts now, not when the app stream ends: a rejection a stalled client never
+  // reads up to is still handled (and logged) rather than left unhandled.
+  const scripts = deferred.map((d) =>
+    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
+      )
+      .catch((err: unknown) => {
+        // A rejected (or unserializable) deferred streams __nifraReject (the client `<Await>`
+        // surfaces it) - it must not break the whole body. Redact: stream a stable opaque code,
+        // never the raw error text; log the real reason server-side.
+        console.error("[nifra/web] deferred value rejected:", err)
+        return `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
+      }),
+  )
   return new ReadableStream({
-    async start(controller) {
+    start(controller) {
+      controller.enqueue(shell)
+    },
+    async pull(controller) {
       try {
-        controller.enqueue(shell)
-        for (;;) {
+        if (!released) {
           const { done, value } = await reader.read()
           if (cancelled) return
-          if (done) break
-          controller.enqueue(value)
+          if (!done) {
+            controller.enqueue(value)
+            return
+          }
+          release()
+          controller.enqueue(closeRoot)
         }
-        controller.enqueue(closeRoot)
         // Stream each resolution as ITS OWN promise settles - NOT in array order. A slow
         // defer() must not block a faster one; each script self-addresses by id, so order is irrelevant.
         await Promise.all(
-          deferred.map(async (d) => {
-            let script: string
-            try {
-              const value = serializeData(await d.promise)
-              // `serializeData` JSON-serializes the value and escapes `<`, `>`, and Unicode line
-              // separators before this framework-owned script is emitted.
-              script = `<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>` // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
-            } catch (err) {
-              // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) - it must
-              // not break the whole body. Redact: stream a stable opaque code, never the raw error
-              // text; log the real reason server-side.
-              console.error("[nifra/web] deferred value rejected:", err)
-              script = `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
-            }
-            if (!cancelled) controller.enqueue(enc.encode(script))
+          scripts.map(async (script) => {
+            const html = await script
+            if (!cancelled) controller.enqueue(enc.encode(html))
           }),
         )
         if (cancelled) return
         controller.enqueue(tail)
         controller.close()
       } catch (err) {
+        release()
         if (!cancelled) controller.error(err)
-      } finally {
-        released = true
-        reader.releaseLock()
       }
     },
     cancel(reason) {

package/src/internal/request-url.ts

@@ -12,3 +12,27 @@ export function urlPartsFor(request: Request): UrlParts {
   REQUEST_URL_PARTS.set(request, parts)
   return parts
 }
+
+// The origin depends only on the text before the path, which repeats across requests, so each
+// distinct prefix is parsed once instead of every request's whole URL. Cleared when full: a client
+// can vary the Host header without bound.
+const ORIGINS = new Map<string, string>()
+
+/** `new URL(request.url).origin`, or `""` for a URL that does not parse. */
+export function originFor(request: { readonly url: string }): string {
+  const url = request.url
+  const schemeEnd = url.indexOf("://")
+  const pathStart = schemeEnd === -1 ? -1 : url.indexOf("/", schemeEnd + 3)
+  const prefix = pathStart === -1 ? url : url.slice(0, pathStart)
+  let origin = ORIGINS.get(prefix)
+  if (origin === undefined) {
+    try {
+      origin = new URL(prefix).origin
+    } catch {
+      origin = ""
+    }
+    if (ORIGINS.size >= 64) ORIGINS.clear()
+    ORIGINS.set(prefix, origin)
+  }
+  return origin
+}

package/src/internal/secret-scan.ts

@@ -694,10 +694,18 @@ export function createRedactor(
 export const buildEnvironment = (): Readonly<Record<string, string | undefined>> =>
   (typeof Bun !== "undefined" ? Bun.env : undefined) ?? process.env
 
+/** A build artifact holds a secret. Its own class so a step that tolerates other failures still stops. */
+export class SecretScanError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "SecretScanError"
+  }
+}
+
 /** Scan and throw the build-failing message on any finding. */
 export function assertNoSecrets(input: SecretScanInput): void {
   const message = formatSecretFindings(scanForSecrets(input))
-  if (message !== undefined) throw new Error(message)
+  if (message !== undefined) throw new SecretScanError(message)
 }
 
 /** The build-failing message for secret findings, or `undefined` when there are none. */

package/src/internal/web-app.ts

@@ -22,6 +22,7 @@ import { createMatcher, PRERENDERED_LIST_PATH } from "../router.ts"
 import type { EvidenceAncestry } from "./evidence-traversal.ts"
 import { formatShadowedPages, shadowedPages } from "./mount-shadow.ts"
 import { createPageRequestExecutor, type NonceResolver, type PageI18n } from "./page-execution.ts"
+import { type PrerenderedPages, servePrerenderedPages } from "./prerendered-pages.ts"
 import { requestPattern } from "./route-path.ts"
 
 export type { NonceResolver } from "./page-execution.ts"
@@ -73,6 +74,8 @@ export interface CreateWebAppOptions<Env = unknown> {
   readonly serverComponents?: import("../server-components/types.ts").ServerComponentRuntime
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
+  /** Cache production module imports and layout preparation, never request data. Defaults to NODE_ENV === "production"; disable for a mutable manifest. */
+  readonly cacheRouteModules?: boolean
   /** URL of the built client entry (module script) injected into every page. */
   readonly clientEntry: string
   /** Default document title for all pages. */
@@ -252,6 +255,14 @@ export interface CreateWebAppOptions<Env = unknown> {
    * 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[]
+  /**
+   * Pages a self-hosted build prerendered, answered from their file instead of rendered. `nifra build
+   * --target bun|node` wires this from its prerender pass. The page is served from the page route,
+   * so `use` middleware and every request hook run first; a request with a query string, a navigation
+   * data or component request, or a draft-mode visitor renders on demand as before. Ignored with
+   * {@link nonce}, whose documents need a nonce minted for their request.
+   */
+  readonly prerenderedPages?: PrerenderedPages
   /** 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
@@ -475,6 +486,9 @@ export function createWebApp<Env = unknown>(
     ? undefined
     : servedPrerenderedList(options.prerenderedPaths)
   const pageExecutor = createPageRequestExecutor<Env>({
+    ...(options.cacheRouteModules === undefined
+      ? {}
+      : { cacheRouteModules: options.cacheRouteModules }),
     ...(options.serverComponents === undefined
       ? {}
       : { serverComponents: options.serverComponents }),
@@ -520,17 +534,23 @@ export function createWebApp<Env = unknown>(
     cacheChannel,
   })
 
+  // A nonce app's documents authorize their scripts per request, which a file rendered once cannot.
+  const prerendered =
+    options.prerenderedPages === undefined || options.nonce !== undefined
+      ? undefined
+      : servePrerenderedPages(options.prerenderedPages, options.draftSecret)
   let ownsRootCatchAll = false
   for (const route of manifest.routes) {
     const pattern = requestPattern(route.pattern)
     if (pattern.startsWith("/*")) ownsRootCatchAll = true
+    const render = pageExecutor.get(route)
     app.register(
       "GET",
       pattern,
       options.serverComponents?.owns(route.id)
         ? { capabilities: options.serverComponents.capabilities(route.id) }
         : undefined,
-      pageExecutor.get(route),
+      prerendered === undefined ? render : prerendered(render),
     )
     app.register("POST", pattern, undefined, pageExecutor.post(route))
   }

package/src/isr.ts

@@ -161,6 +161,8 @@ export class MemoryCacheStore implements CacheStore {
   private order = 0
   private readonly purgedKeys = new Map<string, number>()
   private readonly purgedTags = new Map<string, number>()
+  // The newest purge order whose mark was evicted. A render fenced before it may predate that purge.
+  private purgeFloor = 0
 
   constructor(options: MemoryCacheStoreOptions = {}) {
     const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production"
@@ -246,8 +248,8 @@ export class MemoryCacheStore implements CacheStore {
   }
 
   private purgedAfter(key: string, tags: readonly string[], fence: number): boolean {
-    if ((this.purgedKeys.get(key) ?? 0) > fence) return true
-    return tags.some((tag) => (this.purgedTags.get(tag) ?? 0) > fence)
+    if ((this.purgedKeys.get(key) ?? this.purgeFloor) > fence) return true
+    return tags.some((tag) => (this.purgedTags.get(tag) ?? this.purgeFloor) > fence)
   }
 
   private markPurged(marks: Map<string, number>, name: string): void {
@@ -255,9 +257,10 @@ export class MemoryCacheStore implements CacheStore {
     marks.set(name, ++this.order)
     // Bounded like the entries: a mark matters only to a render still in flight.
     while (marks.size > this.max) {
-      const oldest = marks.keys().next().value
+      const oldest = marks.entries().next().value
       if (oldest === undefined) break
-      marks.delete(oldest)
+      marks.delete(oldest[0])
+      this.purgeFloor = Math.max(this.purgeFloor, oldest[1])
     }
   }
 

package/src/prerender.ts

@@ -10,6 +10,7 @@
  */
 import { mkdirSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve, sep } from "node:path"
+import { prerenderedDocumentHeaders } from "./internal/prerendered-pages.ts"
 import { assertNoSecrets, buildEnvironment, type SecretExemption } from "./internal/secret-scan.ts"
 import { fillRoutePattern, type RouteEntry } from "./manifest.ts"
 import { DATA_HEADER, PRERENDERED_GLOBAL, PRERENDERED_LIST_PATH } from "./router.ts"
@@ -52,6 +53,10 @@ export interface PrerenderEntry {
   /** The loader-data file written alongside (`<path>/_data.json`) so a client soft-nav INTO this
    * route skips the worker. Absent when the data-mode response is NDJSON (a deferred loader). */
   readonly dataFile?: string
+  /** The document headers a self-hosted server sends with this file (its `content-language` and CSP).
+   * Absent when the render was specific to its request - it set a cookie, was private or no-store, or
+   * varied on a request header - so a server keeps rendering this path on demand. */
+  readonly serveHeaders?: Readonly<Record<string, string>>
 }
 
 export interface PrerenderResult {
@@ -184,7 +189,14 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
       await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) - release the stream
     }
 
-    prerendered.push({ path, file, bytes: html.length, ...(dataFile ? { dataFile } : {}) })
+    const serveHeaders = prerenderedDocumentHeaders(res.status, res.headers)
+    prerendered.push({
+      path,
+      file,
+      bytes: html.length,
+      ...(dataFile ? { dataFile } : {}),
+      ...(serveHeaders ? { serveHeaders } : {}),
+    })
   }
 
   for (const route of options.routes) {

package/src/public-dir.ts

@@ -12,11 +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 { realpath } from "node:fs/promises"
+import { type FileHandle, 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 { isHiddenPublicPath } from "./internal/public-url.ts"
 import { openResolved } from "./open-resolved.ts"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
@@ -96,15 +97,33 @@ export const CONTENT_TYPES: Readonly<Record<string, string>> = {
 }
 
 /**
- * Whether a confined path crosses a dot-segment other than `.well-known`. The build copies `public/`
- * with dotfiles included, so an editor or VCS artifact (`.env`, `.git/`, `.DS_Store`) dropped there
- * would otherwise be downloadable. Checked on the resolved path, so `%2e` encodings are covered.
+ * Whether a confined path crosses a hidden segment ({@link isHiddenPublicPath}). Checked on the
+ * resolved path, so `%2e` encodings are covered, and again on the real target, so a visible name
+ * linking to `.env` is refused too.
  */
 function isHiddenPath(root: string, abs: string): boolean {
-  for (const segment of abs.slice(root.length + 1).split(sep)) {
-    if (segment.startsWith(".") && segment !== ".well-known") return true
+  return abs !== root && isHiddenPublicPath(abs.slice(root.length + 1))
+}
+
+// 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 64 KiB per request rather than the file.
+const BUFFERED_BODY_MAX = 256 * 1024
+
+/** `length` bytes of `handle` from `start`; fewer when the file shrank since its stat. */
+async function readPinned(
+  handle: FileHandle,
+  start: number,
+  length: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const bytes = new Uint8Array(length)
+  let offset = 0
+  while (offset < length) {
+    const { bytesRead } = await handle.read(bytes, offset, length - offset, start + offset)
+    if (bytesRead === 0) break
+    offset += bytesRead
   }
-  return false
+  return offset === length ? bytes : bytes.subarray(0, offset)
 }
 
 /** HTTP dates carry second precision; comparing raw milliseconds makes every file look stale. */
@@ -194,7 +213,8 @@ export function servePublicDir(
     if (
       resolvedRoot === undefined ||
       resolvedFile === undefined ||
-      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep))
+      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep)) ||
+      isHiddenPath(resolvedRoot, resolvedFile)
     ) {
       return undefined
     }
@@ -243,7 +263,8 @@ export function servePublicDir(
         return new Response(null, { status: 304, headers })
       }
 
-      const rangeHeader = request.headers.get("range")
+      // Range applies to GET only (RFC 9110 section 14.2); HEAD reports the whole representation.
+      const rangeHeader = head ? null : request.headers.get("range")
       const range =
         rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
           ? parseByteRange(rangeHeader, size)
@@ -255,7 +276,16 @@ export function servePublicDir(
         return new Response(null, { status: 416, headers })
       }
 
-      const body = (start?: number, end?: number): ReadableStream<Uint8Array> => {
+      const body = async (
+        start: number,
+        end: number,
+      ): Promise<Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>> => {
+        const length = end - start + 1
+        if (length <= BUFFERED_BODY_MAX) {
+          const bytes = await readPinned(handle!, start, length)
+          headers.set("content-length", String(bytes.byteLength))
+          return bytes
+        }
         const stream = handle!.createReadStream({ start, end })
         // FileHandle.createReadStream owns closing the descriptor after EOF/abort.
         handle = undefined
@@ -266,14 +296,14 @@ export function servePublicDir(
         const { start, end } = range.ranges[0]!
         headers.set("content-range", `bytes ${start}-${end}/${size}`)
         headers.set("content-length", String(end - start + 1))
-        return new Response(head ? null : body(start, end), { status: 206, headers })
+        return new Response(head ? null : await body(start, end), { status: 206, headers })
       }
 
       // Multiple ranges would require assembling `multipart/byteranges`, and doing that for a file on
       // disk means buffering the whole representation to serve a request that asked for less of it.
       // RFC 9110 lets a server ignore Range entirely, so the full body is the conformant answer here.
       headers.set("content-length", String(size))
-      return new Response(head ? null : body(), { headers })
+      return new Response(head || size === 0 ? null : await body(0, size - 1), { headers })
     } finally {
       if (handle !== undefined) {
         try {
@@ -285,3 +315,68 @@ export function servePublicDir(
     }
   }
 }
+
+export interface PrerenderedPageReaderOptions {
+  /** Absolute path of the directory the build wrote the prerendered pages into. */
+  readonly dir: string
+  /** Each page path mapped to its file, relative to `dir`. */
+  readonly files: Readonly<Record<string, string>>
+  /** Bytes of HTML kept in memory once read (default 32 MiB); a page past the budget is read per request. */
+  readonly cacheBytes?: number
+}
+
+/**
+ * Read a self-hosted build's prerendered pages for `createWebApp`'s `prerenderedPages`. Only the build's
+ * own files are reachable, each opened only once its real path is inside `dir`, so a link planted in the
+ * deployed tree cannot point a page elsewhere. A deploy's files do not change while it runs, so a page
+ * is kept after its first read; `undefined` (a missing or refused file) renders the page on demand.
+ */
+export function prerenderedPageReader(
+  options: PrerenderedPageReaderOptions,
+): (pathname: string) => Promise<string | undefined> {
+  const root = resolve(options.dir)
+  const rootReal = realpath(root).catch(() => undefined)
+  const files = new Map(Object.entries(options.files))
+  const budget = options.cacheBytes ?? 32 * 1024 * 1024
+  const cache = new Map<string, string>()
+  let cachedBytes = 0
+  return async (pathname) => {
+    const cached = cache.get(pathname)
+    if (cached !== undefined) return cached
+    const rel = files.get(pathname)
+    if (rel === undefined) return undefined
+    const abs = resolve(root, rel)
+    if (!abs.startsWith(root + sep) || isHiddenPath(root, abs)) return undefined
+    const [resolvedRoot, resolvedFile] = await Promise.all([
+      rootReal,
+      realpath(abs).catch(() => undefined),
+    ])
+    if (
+      resolvedRoot === undefined ||
+      resolvedFile === undefined ||
+      !resolvedFile.startsWith(resolvedRoot + sep)
+    ) {
+      return undefined
+    }
+    let handle: FileHandle
+    try {
+      handle = await openResolved(resolvedFile)
+    } catch {
+      return undefined
+    }
+    try {
+      if (!(await handle.stat()).isFile()) return undefined
+      const bytes = await handle.readFile()
+      const html = bytes.toString("utf8")
+      if (!cache.has(pathname) && cachedBytes + bytes.byteLength <= budget) {
+        cache.set(pathname, html)
+        cachedBytes += bytes.byteLength
+      }
+      return html
+    } catch {
+      return undefined
+    } finally {
+      await handle.close().catch(() => undefined)
+    }
+  }
+}

package/src/render-seam.ts

@@ -155,13 +155,16 @@ export interface RenderAdapter {
   ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
   /**
    * Render the chain to a complete HTML string when no content is deferred. `options.nonce` is the
-   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data).
+   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data); a
+   * document that sends a policy keeps the nonce only when the returned HTML carries it. Return
+   * `undefined` when the render suspended on something only `renderToStream` waits for (React's
+   * `use` or `lazy` inside `<Suspense>`): the page is then streamed instead.
    */
   renderToString?(
     chain: readonly unknown[],
     props: RenderProps,
     options?: RenderStreamOptions,
-  ): string | Promise<string>
+  ): string | undefined | Promise<string | undefined>
   /** Per-document bootstrap markup injected into `<head>` for client hydration. */
   hydrationHead(nonce?: string): string
   /**

package/src/search.ts

@@ -107,6 +107,7 @@ function encodeValue(value: unknown): string {
 /** The default JSON-first codec. Repeated keys (`?t=a&t=b`) decode to an array; single keys to a value. */
 const jsonCodec: SearchCodec = {
   parse(raw, limits) {
+    if (raw === "" || raw === "?") return {}
     const usp = new URLSearchParams(raw.startsWith("?") ? raw.slice(1) : raw)
     // Two passes instead of the old `Set(keys) + getAll(key)` shape, which rescanned the complete
     // URLSearchParams list once per distinct key (O(keys²)). Admission must be decided BEFORE any