@nifrajs/web 5.2.0 → 5.4.0

package/src/build.ts

@@ -25,6 +25,7 @@ import {
   singleCopyPlugin as declaredSingleCopyPlugin,
   readSingleCopyDeclaration,
 } from "@nifrajs/core/single-copy"
+import { isHiddenPath } from "@nifrajs/core/static-file"
 import { type BunPlugin, Glob } from "bun"
 import {
   aggregateSizeReport,
@@ -55,11 +56,16 @@ import { loadCopySplit } from "./internal/copy-split.ts"
 import { assertDisposableDir } from "./internal/disposable-dir.ts"
 import { entryChunks } from "./internal/entry-chunks.ts"
 import { dedupePolicyFor } from "./internal/identity-policy.ts"
+import { nodeAdapterRefusal } from "./internal/node-adapter.ts"
 import {
   assertDevelopmentProductionParity,
   assertIdentityParity,
   collectDevelopmentParityInput,
 } from "./internal/parity.ts"
+import {
+  type ServerPrerenderedPage,
+  servablePrerenderedPages,
+} from "./internal/prerendered-pages.ts"
 import { privateEnvCheck } from "./internal/private-env.ts"
 import { publicUrlPath } from "./internal/public-url.ts"
 import {
@@ -71,6 +77,7 @@ import {
   originName,
   publicScanFiles,
   type SecretExemption,
+  SecretScanError,
   scanForSecrets,
   textOf,
 } from "./internal/secret-scan.ts"
@@ -94,8 +101,8 @@ import { type ClientModuleGraph, fromBunMetafile } from "./module-graph.ts"
 import { assertNoImportGlob, importGlobPlugin } from "./plugins/import-glob.ts"
 import { zoneGuardPlugin } from "./plugins/zone-guard.ts"
 // `buildTarget(static)` drives the SSG prerender engine directly (it's also re-exported below).
-import { prerenderRoutes } from "./prerender.ts"
-import { CONTENT_TYPES, IMMUTABLE, ONE_DAY } from "./public-dir.ts"
+import { type PrerenderOptions, prerenderRoutes } from "./prerender.ts"
+import { IMMUTABLE, ONE_DAY } from "./public-dir.ts"
 import { createZoneClassifier } from "./zones.ts"
 
 export * from "./build-plan.ts"
@@ -128,6 +135,8 @@ interface BunMetafile {
   >
 }
 
+// A page a bun or node build answers from its file (`generateServerEntry`'s `prerenderedPages`).
+export type { ServerPrerenderedPage } from "./internal/prerendered-pages.ts"
 // The secret scan every client build, `public/` copy and prerender runs.
 export type { SecretExemption, SecretRule } from "./internal/secret-scan.ts"
 // Build-time SSG: prerender opted-in static + dynamic routes to `index.html` (+ static `_data.json`),
@@ -340,7 +349,9 @@ export function cloudflareRouteRules(
 
 /** The built asset map - the server reads `entry` for the client script + serves `assets`. */
 /**
- * Copy `from` into `to`, returning the URL paths copied (sorted).
+ * Copy `from` into `to`, returning the URL paths copied (sorted). Hidden entries other than
+ * `.well-known` are skipped, as development never serves them: every target ships this list, and a
+ * CDN-hosted one serves whatever was copied.
  *
  * Lives here, not beside `servePublicDir`, because it is BUILD-time: it reaches for `Bun.Glob` and
  * `node:fs`, and `public-dir.ts` is reachable from the client bundle graph through the package
@@ -351,6 +362,7 @@ export async function copyPublicDir(from: string, to: string): Promise<string[]>
   const sourceReal = await realpath(source)
   const copied: string[] = []
   for await (const rel of new Glob("**/*").scan({ cwd: source, dot: true, onlyFiles: false })) {
+    if (isHiddenPath(rel)) continue
     const candidate = join(source, rel)
     const candidateStat = await lstat(candidate)
     if (candidateStat.isSymbolicLink()) {
@@ -1296,6 +1308,9 @@ const PLATFORM_CLIENT_IP_HEADERS: Readonly<Partial<Record<BuildTarget, string>>>
   vercel: "x-real-ip",
 }
 
+/** Where a self-hosting build writes its prerendered pages, beside `server.js`. */
+const PRERENDERED_DIR = "_prerendered"
+
 /**
  * Codegen the per-target **server entry** module (source text) for `buildServer` to bundle. It imports
  * the app's `adapter` (from `framework.ts`), the optional `backend` (from `backend.ts`), and the
@@ -1332,6 +1347,9 @@ export function generateServerEntry(options: {
   readonly clientIp?: ServerEntryClientIp
   /** The server manifest exports `copyChunks` (the client build split copy tables by locale). */
   readonly copyChunks?: boolean
+  /** `bun` / `node` only: the pages the build prerendered into `_prerendered/`, by request path, which
+   * the app answers from their file (see `createWebApp`'s `prerenderedPages`). */
+  readonly prerenderedPages?: Readonly<Record<string, ServerPrerenderedPage>>
 }): string {
   const {
     target,
@@ -1363,7 +1381,20 @@ export function generateServerEntry(options: {
   if (target === "static") {
     throw new Error("[nifra/web] generateServerEntry: `static` has no server entry (SSG only)")
   }
-  const lines: string[] = ['import { createWebApp } from "@nifrajs/web"']
+  // Bun serves the client bundle through `servePublicDir` and Node through @nifrajs/node's own reader,
+  // both on core's static-file policy. Deno bundles for the browser condition, where `node:fs` is a
+  // stub, so its entry runs the same checks on Deno's own file API.
+  const nodeFs = target === "bun" || target === "node"
+  const prerendered = Object.entries(options.prerenderedPages ?? {})
+  if (prerendered.length > 0 && !nodeFs) {
+    throw new Error(
+      `[nifra/web] generateServerEntry: prerendered pages are served by the bun and node targets, not ${target}`,
+    )
+  }
+  const webImports = ["createWebApp"]
+  if (prerendered.length > 0) webImports.push("prerenderedPageReader")
+  if (target === "bun") webImports.push("servePublicDir")
+  const lines: string[] = [`import { ${webImports.join(", ")} } from "@nifrajs/web"`]
   if (backendImport !== undefined) lines.push('import { inProcessClient } from "@nifrajs/client"')
   lines.push(`import { adapter } from ${JSON.stringify(adapterImport)}`)
   if (useImport !== undefined) lines.push(`import { use } from ${JSON.stringify(useImport)}`)
@@ -1381,11 +1412,35 @@ export function generateServerEntry(options: {
   // Cloudflare needs the fetch-handler shape; the others call app.fetch directly.
   if (target === "cloudflare") lines.push('import { toFetchHandler } from "@nifrajs/core/server"')
   if (target === "node") lines.push('import { serve } from "@nifrajs/node"')
+  if (nodeFs) lines.push('import { fileURLToPath } from "node:url"')
+  if (target === "deno") {
+    lines.push(
+      'import { parseByteRange } from "@nifrajs/core/range"',
+      'import { contentTags, contentTypeOf, ifRangeAllowsPartial, isHiddenPath, isNotModified, lastModifiedOf } from "@nifrajs/core/static-file"',
+      'import { createHash } from "node:crypto"',
+    )
+  }
+  if (prerendered.length > 0) {
+    const headers = Object.fromEntries(prerendered.map(([path, page]) => [path, page.headers]))
+    const files = Object.fromEntries(prerendered.map(([path, page]) => [path, page.file]))
+    lines.push(
+      "",
+      `// The pages the build prerendered into ${PRERENDERED_DIR}/, answered from their file after \`use\`.`,
+      "const prerenderedPages = {",
+      `  pages: ${JSON.stringify(headers)},`,
+      "  read: prerenderedPageReader({",
+      `    dir: fileURLToPath(new URL(${JSON.stringify(`./${PRERENDERED_DIR}/`)}, import.meta.url)),`,
+      `    files: ${JSON.stringify(files)},`,
+      "  }),",
+      "}",
+    )
+  }
   lines.push(
     "",
     "const app = createWebApp({",
     "  adapter,",
     ...(useImport !== undefined ? ["  use,"] : []),
+    ...(prerendered.length > 0 ? ["  prerenderedPages,"] : []),
     ...importedOptions.map((name) => `  ${name},`),
     "  manifest,",
     "  clientEntry,",
@@ -1445,6 +1500,34 @@ export function generateServerEntry(options: {
     ...(hashedFiles !== undefined
       ? [`const HASHED_FILES = new Set(${JSON.stringify(hashedFiles)})`]
       : []),
+  )
+  if (target === "node") {
+    // The app itself with the adapter's own reader, not a `{ fetch }` wrapper around app.fetch: the
+    // wrapper hid the node-direct lane, so every page built an undici Request and drained a Response,
+    // and every file went through one too. The root mount serves only the files the build listed.
+    lines.push(
+      "await serve(app, {",
+      "  port: Number(process.env.PORT ?? 3000),",
+      "  static: [",
+      "    {",
+      '      dir: fileURLToPath(new URL("./assets/", import.meta.url)),',
+      '      prefix: "/assets",',
+      ...(hashedFiles !== undefined ? ["      hashedFiles: HASHED_FILES,"] : []),
+      `      cacheControl: ${JSON.stringify(ONE_DAY)},`,
+      "    },",
+      "    {",
+      "      dir: fileURLToPath(STATIC_ROOT),",
+      '      prefix: "/",',
+      "      files: PUBLIC_FILES,",
+      "      immutable: false,",
+      `      cacheControl: ${JSON.stringify(ONE_DAY)},`,
+      "    },",
+      "  ],",
+      "})",
+    )
+    return `${lines.join("\n")}\n`
+  }
+  lines.push(
     "const staticPath = (pathname: string): string | undefined => {",
     "  if (PUBLIC_FILES.has(pathname)) return '.' + pathname",
     '  if (!pathname.startsWith("/assets/")) return undefined',
@@ -1456,14 +1539,19 @@ export function generateServerEntry(options: {
     '    segment !== "." && segment !== ".." && /^[A-Za-z0-9._-]+$/.test(segment)',
     "  return segments.every(safe) ? '.' + pathname : undefined",
     "}",
-    // The type table and cache policy `servePublicDir` uses. Without a known type, Bun answers a file
-    // as an `application/octet-stream` attachment, which a browser downloads instead of showing.
-    `const TYPES: Record<string, string> = ${JSON.stringify(CONTENT_TYPES)}`,
-    "const staticHeaders = (pathname: string): Record<string, string> => ({",
-    '  "content-type": TYPES[pathname.slice(pathname.lastIndexOf(".")).toLowerCase()] ?? "application/octet-stream",',
-    `  "cache-control": ${hashedFiles !== undefined ? "HASHED_FILES.has(pathname)" : 'pathname.startsWith("/assets/")'} ? ${JSON.stringify(IMMUTABLE)} : ${JSON.stringify(ONE_DAY)},`,
-    '  "x-content-type-options": "nosniff",',
-    "})",
+    // The handler `nifra dev` serves public/ with: its type table, nosniff and cache policy, content
+    // tags, byte ranges and conditional requests, and a descriptor opened only once the real path is
+    // inside the root, so a link planted in the deployed tree cannot reach a file outside it.
+    ...(target === "bun"
+      ? [
+          "const serveStatic = servePublicDir({",
+          "  dir: fileURLToPath(STATIC_ROOT),",
+          ...(hashedFiles !== undefined ? ["  hashedFiles: HASHED_FILES,"] : []),
+          "})",
+          "const staticResponse = async (req: Request): Promise<Response> =>",
+          '  (await serveStatic(req)) ?? new Response("not found", { status: 404 })',
+        ]
+      : denoStaticResponse(hashedFiles !== undefined)),
   )
   // Bun.serve and Deno.serve delimit the body themselves, so its declared length is the transport
   // frame - the guarantee core's own listen() and the Deno adapter mark (see markTrustedBodyFraming).
@@ -1475,11 +1563,9 @@ export function generateServerEntry(options: {
       "  port: Number(Bun.env.PORT ?? 3000),",
       "  async fetch(req, server) {",
       "    const { pathname } = new URL(req.url)",
-      "    const filePath = staticPath(pathname)",
-      "    if (filePath !== undefined) {",
-      "      const file = Bun.file(new URL(filePath, STATIC_ROOT))",
-      '      if (!(await file.exists())) return new Response("not found", { status: 404 })',
-      "      return new Response(file, { headers: staticHeaders(pathname) })",
+      // Braced: the next emitted line opens with `(`, which would otherwise call the returned value.
+      "    if (staticPath(pathname) !== undefined) {",
+      "      return staticResponse(req)",
       "    }",
       `    ${markFramed}`,
       "    // The socket peer, looked up only when something reads it (as core's own listen() does).",
@@ -1492,30 +1578,6 @@ export function generateServerEntry(options: {
     )
     return `${lines.join("\n")}\n`
   }
-  if (target === "node") {
-    lines.push(
-      'import { readFile } from "node:fs/promises"',
-      "await serve(",
-      "  {",
-      "    async fetch(req, platform) {",
-      "      const { pathname } = new URL(req.url)",
-      "      const filePath = staticPath(pathname)",
-      "      if (filePath !== undefined) {",
-      "        try {",
-      "          const body = await readFile(new URL(filePath, STATIC_ROOT))",
-      "          return new Response(body, { headers: staticHeaders(pathname) })",
-      "        } catch {",
-      '          return new Response("not found", { status: 404 })',
-      "        }",
-      "      }",
-      "      return app.fetch(req, platform)",
-      "    },",
-      "  },",
-      "  { port: Number(process.env.PORT ?? 3000) },",
-      ")",
-    )
-    return `${lines.join("\n")}\n`
-  }
   // deno
   lines.push(
     "// @ts-ignore - Deno global is present on the Deno runtime this output targets.",
@@ -1523,13 +1585,7 @@ export function generateServerEntry(options: {
     "  const { pathname } = new URL(req.url)",
     "  const filePath = staticPath(pathname)",
     "  if (filePath !== undefined) {",
-    "    try {",
-    "      // @ts-ignore - Deno.readFile is present on the Deno runtime.",
-    "      const body = await Deno.readFile(new URL(filePath, STATIC_ROOT))",
-    "      return new Response(body, { headers: staticHeaders(pathname) })",
-    "    } catch {",
-    '      return new Response("not found", { status: 404 })',
-    "    }",
+    "    return staticResponse(req, filePath, pathname)",
     "  }",
     `  ${markFramed}`,
     "  return app.fetch(req, { clientIp: info.remoteAddr.hostname })",
@@ -1538,6 +1594,166 @@ export function generateServerEntry(options: {
   return `${lines.join("\n")}\n`
 }
 
+/**
+ * The Deno entry's static handler: `servePublicDir`'s checks and answers on Deno's file API. The real
+ * path must sit inside the root and cross no hidden segment, and the opened file must still be the one
+ * that path names, so a link planted in the deployed tree cannot reach a file outside it or a `.env`
+ * inside it. The file is typed by its real path, tagged by its content and dated only by an mtime its
+ * own last write set, through the same policy as servePublicDir: a current cached copy is a 304, and a
+ * range survives only an `If-Range` naming that tag. A file is read once to tag it, and one small
+ * enough is then served from those bytes; otherwise one byte range is served from a seek, several as
+ * the whole file.
+ */
+function denoStaticResponse(hashed: boolean): string[] {
+  return [
+    "const staticHeaders = (pathname: string, file: string): Record<string, string> => ({",
+    '  "content-type": contentTypeOf(file),',
+    `  "cache-control": ${hashed ? "HASHED_FILES.has(pathname)" : 'pathname.startsWith("/assets/")'} ? ${JSON.stringify(IMMUTABLE)} : ${JSON.stringify(ONE_DAY)},`,
+    '  "x-content-type-options": "nosniff",',
+    '  "accept-ranges": "bytes",',
+    "})",
+    "// @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "const STATIC_REAL: string = await Deno.realPath(STATIC_ROOT)",
+    "// One per process: the tag of a file is remembered by its real path.",
+    "const STATIC_TAGS = contentTags(createHash)",
+    "// Up to this many bytes are read whole to tag a file, and the response is then served from them.",
+    "const STATIC_INLINE_MAX = 256 * 1024",
+    "const staticResponse = async (req: Request, filePath: string, pathname: string): Promise<Response> => {",
+    '  const missing = () => new Response("not found", { status: 404 })',
+    '  if (req.method !== "GET" && req.method !== "HEAD") return missing()',
+    "  let file, info",
+    '  let real = ""',
+    "  try {",
+    "    // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "    real = await Deno.realPath(new URL(filePath, STATIC_ROOT))",
+    '    if (!real.startsWith(STATIC_REAL + (STATIC_REAL.includes("\\\\") ? "\\\\" : "/"))) return missing()',
+    "    if (isHiddenPath(real.slice(STATIC_REAL.length + 1))) return missing()",
+    "    // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "    file = await Deno.open(real)",
+    "    // Deno.open follows links, so a directory swapped for one after the check above redirects it.",
+    "    // The opened file must be the one at `real`, which must still resolve to itself.",
+    "    const opened = await file.stat()",
+    "    // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "    const named = await Deno.stat(real)",
+    "    // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "    if (opened.dev !== named.dev || opened.ino !== named.ino || (await Deno.realPath(real)) !== real) {",
+    "      file.close()",
+    "      return missing()",
+    "    }",
+    "    info = opened",
+    "  } catch {",
+    "    file?.close()",
+    "    return missing()",
+    "  }",
+    "  if (!info.isFile) {",
+    "    file.close()",
+    "    return missing()",
+    "  }",
+    "  const size: number = info.size",
+    "  const headers = new Headers(staticHeaders(pathname, real))",
+    "  // Deno reports a field the platform does not keep as null; NaN never matches a remembered version.",
+    "  const version = {",
+    "    dev: info.dev,",
+    "    ino: info.ino ?? Number.NaN,",
+    "    size,",
+    "    mtimeMs: info.mtime?.getTime() ?? Number.NaN,",
+    "    ctimeMs: info.ctime?.getTime() ?? Number.NaN,",
+    "  }",
+    "  let whole: Uint8Array<ArrayBuffer> | undefined",
+    "  let moved = false",
+    "  let etag: string | undefined",
+    "  try {",
+    "    etag = STATIC_TAGS.cached(real, version)",
+    "    if (etag === undefined && size <= STATIC_INLINE_MAX) {",
+    "      whole = new Uint8Array(size)",
+    "      let filled = 0",
+    "      while (filled < size) {",
+    "        const read: number | null = await file.read(whole.subarray(filled))",
+    "        if (read === null || read === 0) break",
+    "        filled += read",
+    "      }",
+    "      if (filled < size) whole = whole.subarray(0, filled)",
+    "      etag = STATIC_TAGS.ofBytes(real, version, whole)",
+    "    }",
+    "    etag ??= await STATIC_TAGS.ofFile(real, version, async (bytes: Uint8Array, position: number) => {",
+    "      moved = true",
+    "      // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "      await file.seek(position, Deno.SeekMode.Start)",
+    "      return (await file.read(bytes)) ?? 0",
+    "    })",
+    "  } catch {",
+    "    file.close()",
+    "    return missing()",
+    "  }",
+    '  if (etag !== undefined) headers.set("etag", etag)',
+    "  const lastModified = lastModifiedOf(version)",
+    '  if (lastModified !== undefined) headers.set("last-modified", new Date(lastModified).toUTCString())',
+    '  if (isNotModified(req.headers.get("if-none-match"), req.headers.get("if-modified-since"), etag, lastModified)) {',
+    "    file.close()",
+    '    headers.delete("content-type")',
+    "    return new Response(null, { status: 304, headers })",
+    "  }",
+    '  const rangeHeader = req.method === "GET" ? req.headers.get("range") : null',
+    "  const range =",
+    '    rangeHeader !== null && ifRangeAllowsPartial(req.headers.get("if-range"), etag, lastModified)',
+    "      ? parseByteRange(rangeHeader, size)",
+    '      : { kind: "none" as const }',
+    '  if (req.method === "HEAD" || range.kind === "unsatisfiable") {',
+    "    file.close()",
+    '    if (range.kind !== "unsatisfiable") {',
+    '      headers.set("content-length", String(size))',
+    "      return new Response(null, { headers })",
+    "    }",
+    '    headers.delete("content-type")',
+    '    headers.set("content-range", "bytes */" + size)',
+    "    return new Response(null, { status: 416, headers })",
+    "  }",
+    '  if (range.kind === "satisfiable" && range.ranges.length === 1) {',
+    "    const { start, end } = range.ranges[0]!",
+    '    headers.set("content-range", "bytes " + start + "-" + end + "/" + size)',
+    "    if (whole !== undefined) {",
+    "      file.close()",
+    "      const part = whole.subarray(start, end + 1)",
+    '      headers.set("content-length", String(part.byteLength))',
+    "      return new Response(part, { status: 206, headers })",
+    "    }",
+    "    // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "    await file.seek(start, Deno.SeekMode.Start)",
+    "    let left = end - start + 1",
+    '    headers.set("content-length", String(left))',
+    "    const body = new ReadableStream<Uint8Array>({",
+    "      async pull(controller) {",
+    "        const chunk = new Uint8Array(Math.min(left, 65_536))",
+    "        const read: number | null = await file.read(chunk)",
+    "        if (read === null || read === 0) {",
+    "          file.close()",
+    "          controller.close()",
+    "          return",
+    "        }",
+    "        controller.enqueue(chunk.subarray(0, read))",
+    "        left -= read",
+    "        if (left <= 0) {",
+    "          file.close()",
+    "          controller.close()",
+    "        }",
+    "      },",
+    "      cancel: () => file.close(),",
+    "    })",
+    "    return new Response(body, { status: 206, headers })",
+    "  }",
+    "  if (whole !== undefined) {",
+    "    file.close()",
+    '    headers.set("content-length", String(whole.byteLength))',
+    "    return new Response(whole, { headers })",
+    "  }",
+    "  // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "  if (moved) await file.seek(0, Deno.SeekMode.Start)",
+    '  headers.set("content-length", String(size))',
+    "  return new Response(file.readable, { headers })",
+    "}",
+  ]
+}
+
 /** Measure each emitted output file's raw + gzip size. Reads the file off disk and gzips it with
  * `Bun.gzipSync` (the over-the-wire weight). Async only because it reads files; the aggregation is the
  * pure {@link aggregateSizeReport}. */
@@ -1581,7 +1797,9 @@ export interface BuildTargetOptions {
    * emitted hydration `<script src>` uses the REAL content-hashed entry (`client.entry`) plus the same
    * styles/route-preload the server targets use. A pre-built instance can't work here: the hash isn't known
    * until `buildClient` runs inside `buildTarget`, so a hardcoded entry 404s → pages render but never
-   * hydrate. Required for `target: "static"` (SSG drives `app.fetch`); ignored otherwise. */
+   * hydrate. Required for `target: "static"` (SSG drives `app.fetch`). For `bun` and `node` it is
+   * optional: given, the opted-in routes are prerendered into `_prerendered/` and the server answers
+   * them from their file; the other targets ignore it. */
   readonly prerenderApp?: (client: BuildManifest) => PrerenderAppLike | Promise<PrerenderAppLike>
   /** Client-build plugins (e.g. the MDX/Vue/Solid Bun plugins). */
   readonly clientPlugins?: readonly BunPlugin[]
@@ -1710,6 +1928,48 @@ function assertNoPublicCollision(
   }
 }
 
+/** Prerender a self-hosting build's opted-in routes into `dir` and return the pages its server may
+ * answer from their file: those whose render was not specific to its request. */
+async function prerenderForServer(
+  prerenderApp: NonNullable<BuildTargetOptions["prerenderApp"]>,
+  client: BuildManifest,
+  routesDir: string,
+  dir: string,
+  publicFiles: readonly string[],
+  secrets: NonNullable<PrerenderOptions["secrets"]>,
+): Promise<Record<string, ServerPrerenderedPage>> {
+  const owned = `/${PRERENDERED_DIR}/`
+  const clashes = publicFiles.filter((file) => file.toLowerCase().startsWith(owned))
+  if (clashes.length > 0) {
+    throw new Error(
+      `[nifra/web] public file(s) ${clashes.join(", ")} sit under ${owned}, where the build writes its ` +
+        "prerendered pages. Rename or move them out of the public directory.",
+    )
+  }
+  let result: Awaited<ReturnType<typeof prerenderRoutes>>
+  try {
+    result = await prerenderRoutes({
+      app: await prerenderApp(client),
+      routes: discoverRoutes(routesDir).routes,
+      outDir: dir,
+      secrets,
+    })
+  } catch (error) {
+    // Prerendering loads every route module at build time, which a server build never needed before:
+    // one that cannot load there (a connection opened on import, an env var only production sets) costs
+    // the speedup, not the build. A secret in a page still fails it.
+    if (error instanceof SecretScanError) throw error
+    rmSync(dir, { recursive: true, force: true })
+    console.warn(
+      `[nifra/web] prerendering failed, so the server renders every page on demand: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+    return {}
+  }
+  return servablePrerenderedPages(result.prerendered)
+}
+
 /** Build a full deploy dir for `target` using the default Bun bundler. See {@link buildTargetWith}. */
 export async function buildTarget(
   target: BuildTarget,
@@ -1749,6 +2009,11 @@ export async function buildTargetWith(
   ]
   assertDisposableDir("outDir", outDir, sources)
   assertDisposableDir("workDir", workDir, sources)
+  // Before anything is cleared, so a refused build leaves the last deploy dir in place.
+  if (targetPlan.target === "node") {
+    const refusal = nodeAdapterRefusal(workDir)
+    if (refusal !== undefined) throw new Error(refusal)
+  }
   const { rmSync } = await import("node:fs")
   rmSync(outDir, { recursive: true, force: true })
   rmSync(workDir, { recursive: true, force: true })
@@ -1810,6 +2075,21 @@ export async function buildTargetWith(
     writeFileSync(`${assetsDir}/manifest.json`, JSON.stringify(client, null, 2))
   }
 
+  // A self-hosting server answers its prerendered pages from their file. The static target is all
+  // prerendered pages; the edge targets keep rendering them on demand.
+  const prerenderedPages =
+    options.prerenderApp !== undefined &&
+    (targetPlan.target === "bun" || targetPlan.target === "node")
+      ? await prerenderForServer(
+          options.prerenderApp,
+          client,
+          routesDir,
+          `${staticRoot}/${PRERENDERED_DIR}`,
+          publicFiles,
+          secretScan,
+        )
+      : undefined
+
   if (targetPlan.kind === "static") {
     if (options.prerenderApp === undefined) {
       throw new Error(
@@ -1865,6 +2145,7 @@ export async function buildTargetWith(
       hashedFiles: client.assets,
       ...(options.clientIp !== undefined ? { clientIp: options.clientIp } : {}),
       ...(client.copyChunks !== undefined ? { copyChunks: true } : {}),
+      ...(prerenderedPages !== undefined ? { prerenderedPages } : {}),
     }),
   )
   const { worker } = await bundler.buildServer({

package/src/csp.ts

@@ -175,6 +175,10 @@ export function cspDocumentNonce(
   return requested ?? policy[CSP_POLICY].generate()
 }
 
+/** A nonce for a render that may write a script of its own; the document carries it only if used. */
+export const cspCandidateNonce = (policy: CspPolicy, requested: string | undefined): string =>
+  requested ?? policy[CSP_POLICY].generate()
+
 /** The Content-Security-Policy value for one document, or `undefined` when the policy sends none. */
 export function cspHeaderValue(
   policy: CspPolicy,

package/src/deferred.ts

@@ -6,6 +6,7 @@
  * resolution scripts settle. The per-adapter `<Await>` lives in `@nifrajs/web-{solid,react}/client`.
  */
 import { plainJsonCodec, type TransportCodec } from "@nifrajs/core/transport-codec"
+import { isDeferredFree } from "./internal/deferred-free.ts"
 import { parsePageData } from "./internal/revive-dates.ts"
 
 /**
@@ -65,6 +66,7 @@ export function prepareDeferred(
   readonly deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>
 } {
   const deferred: Array<{ id: number; promise: Promise<unknown> }> = []
+  if (isDeferredFree(data)) return { forComponent: data, forClient: data, deferred }
   // Structural sharing: a subtree with no deferred value returns the ORIGINAL node for
   // both sides (`fc`/`cl` identical to the input), so a deferred-free result - the common case - is
   // returned by reference with no persisted clone, no downstream copy, and no throwaway clone
@@ -321,6 +323,14 @@ export async function parseNdjsonData(
   // accumulate listeners across navigations (a per-nav signal would be GC'd, but don't rely on it).
   const onAbort = (): void => void reader.cancel()
   if (signal) signal.addEventListener("abort", onAbort, { once: true })
+  let ended = false
+  // Every way out, a malformed line included, detaches from the signal and the body: a source left
+  // streaming into a reader nobody reads, or still locked to it, would hold its response open.
+  const release = (): void => {
+    signal?.removeEventListener("abort", onAbort) // no-op if it already fired ({ once: true })
+    if (!ended) reader.cancel().catch(() => {})
+    reader.releaseLock()
+  }
 
   const readLine = async (): Promise<string | null> => {
     for (;;) {
@@ -332,6 +342,7 @@ export async function parseNdjsonData(
       }
       const { done, value } = await reader.read()
       if (done) {
+        ended = true
         const rest = buffer
         buffer = ""
         return rest === "" ? null : rest
@@ -344,8 +355,14 @@ export async function parseNdjsonData(
   // Only plain JSON carries t.date() tags; a richer codec decodes its own dates.
   const decode = (line: string): unknown =>
     codec === plainJsonCodec ? parsePageData(line) : codec.decode(line)
-  const first = await readLine()
-  const data = markersFromPlaceholders(first === null ? null : decode(first), pending)
+  let data: unknown
+  try {
+    const first = await readLine()
+    data = markersFromPlaceholders(first === null ? null : decode(first), pending)
+  } catch (error) {
+    release()
+    throw error
+  }
 
   void (async () => {
     try {
@@ -363,7 +380,7 @@ export async function parseNdjsonData(
     } catch {
       // stream errored - leftovers are rejected below (unless this was an abort)
     } finally {
-      signal?.removeEventListener("abort", onAbort) // no-op if it already fired ({ once: true })
+      release()
       // A natural stream end with markers unsettled = truncation → reject (so `<Await>` shows its
       // error). An `abort` = a superseded navigation → leave them pending: the markers are detached
       // (their data was never applied), so rejecting would only risk an error flash mid-transition.

package/src/index.ts

@@ -87,6 +87,7 @@ export {
 // Generated client entries intentionally import the browser router from the client subpath:
 // `import { createClientRouter, createMatcher, mergeHeads, resolveChainMeta } from "@nifrajs/web/client"`.
 export { mergeHeads, resolveChainMeta, resolveMeta } from "./internal/head-merge.ts"
+export type { PrerenderedPages } from "./internal/prerendered-pages.ts"
 export {
   gone,
   notFound,
@@ -224,7 +225,9 @@ export {
 } from "./nonce.ts"
 // public/ - user-authored static files, served identically in dev and production by one handler.
 export {
+  type PrerenderedPageReaderOptions,
   type PublicDirCache,
+  prerenderedPageReader,
   resolvePublicPath,
   type ServePublicDirOptions,
   servePublicDir,

package/src/internal/deferred-free.ts

@@ -0,0 +1,15 @@
+/**
+ * Values an output guard settled under a schema that cannot let a `defer()` marker through: no
+ * `t.deferred`, and no open or untyped node. `prepareDeferred` returns them without walking them.
+ * A marker the schema does declare is projected into a new object, so the value that holds it is
+ * a fresh copy, never one marked here.
+ */
+const deferredFree = new WeakSet<object>()
+
+export function markDeferredFree(value: unknown): void {
+  if (typeof value === "object" && value !== null) deferredFree.add(value)
+}
+
+export function isDeferredFree(value: unknown): boolean {
+  return typeof value === "object" && value !== null && deferredFree.has(value)
+}