@nifrajs/web 5.1.0 → 5.3.0

package/src/build.ts

@@ -39,6 +39,7 @@ import {
   formatServerOnlyLeak,
   parseBuildTarget,
   parseManifestClientEntry,
+  parseManifestCopyChunks,
   parseManifestCssLoading,
   parseManifestRouteStyles,
   parseManifestStyles,
@@ -50,6 +51,7 @@ import { sanitizeOutputNames } from "./chunk-names.ts"
 import { type CssLoadingMode, normalizeCssCodeSplit, normalizeCssLoading } from "./css-contract.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
+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"
@@ -58,8 +60,12 @@ import {
   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 { isHiddenPublicPath, publicUrlPath } from "./internal/public-url.ts"
 import {
   assertNoSecrets,
   buildEnvironment,
@@ -69,6 +75,7 @@ import {
   originName,
   publicScanFiles,
   type SecretExemption,
+  SecretScanError,
   scanForSecrets,
   textOf,
 } from "./internal/secret-scan.ts"
@@ -89,9 +96,10 @@ import {
   verifyServerGraph,
 } from "./internal/zone-graph.ts"
 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 { type PrerenderOptions, prerenderRoutes } from "./prerender.ts"
 import { CONTENT_TYPES, IMMUTABLE, ONE_DAY } from "./public-dir.ts"
 import { createZoneClassifier } from "./zones.ts"
 
@@ -125,6 +133,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`),
@@ -186,6 +196,12 @@ export interface BuildClientOptions {
    * variable. Each names its rule, its file (or, for an environment value, its variable) and a reason.
    */
   readonly secretExemptions?: readonly SecretExemption[]
+  /**
+   * Move copy tables (`@nifrajs/i18n/copy`) into one chunk per locale, so a page's JavaScript carries
+   * only the copy of the locale it renders in (default: on when minifying). The server bundle keeps
+   * every table whole; the server entry passes the manifest's `copyChunks` to `createWebApp`.
+   */
+  readonly copySplit?: boolean
 }
 
 /**
@@ -331,7 +347,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
@@ -342,6 +360,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 (isHiddenPublicPath(rel)) continue
     const candidate = join(source, rel)
     const candidateStat = await lstat(candidate)
     if (candidateStat.isSymbolicLink()) {
@@ -374,12 +393,14 @@ export function resyncServerManifestSource(
   routesPrefix: string,
 ): string {
   const cssLoading = parseManifestCssLoading(source)
+  const copyChunks = parseManifestCopyChunks(source)
   return generateServerManifest(manifest, {
     resolve: (file) => `${routesPrefix}${file}`,
     clientEntry: parseManifestClientEntry(source) ?? "",
     styles: parseManifestStyles(source),
     routeStyles: parseManifestRouteStyles(source),
     ...(cssLoading !== undefined ? { cssLoading } : {}),
+    ...(copyChunks !== undefined ? { copyChunks } : {}),
     lazy: MANIFEST_IS_LAZY.test(source),
   })
 }
@@ -426,6 +447,10 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // The bootstrap's filename is `_nifra`-namespaced (not `entry.ts`) so its `[name]` can't collide with
   // a user route named `entry.tsx` when the CSS mapping below excludes the bootstrap's aggregate CSS.
   const mode = options.minify === false ? "development" : "production"
+  const copySplit =
+    (options.copySplit ?? mode === "production")
+      ? await loadCopySplit(root, { skip: [outDir] })
+      : undefined
   // PUBLIC_*-prefixed env → client define (Vite/Next convention). Sourced from the build env (`Bun.env`,
   // falling back to `process.env`). Only prefixed vars are baked in; unprefixed secrets stay undefined
   // in the client via the bare `process.env` → `({})` define below. Caller's `options.define` wins (it's
@@ -442,7 +467,11 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // an app module doesn't crash hydration (`process.env.*` reads are handled at compile time by `define`).
   writeFileSync(
     entryFile,
-    `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, { clientModule, resolve })}`,
+    `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, {
+      clientModule,
+      resolve,
+      copyChunks: copySplit !== undefined,
+    })}`,
   )
 
   // Every unique route/layout/`_404` file (sorted, stable), as ADDITIONAL entrypoints - Bun emits a
@@ -496,6 +525,10 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
           svelteDedupePlugin(routesDir),
           serverFnStubPlugin(),
           ...(options.plugins ?? []),
+          // Before the copy split: it claims a module that calls the glob and reads it through the split.
+          importGlobPlugin({ root }),
+          // Last: it rewrites a module no other plugin claims, and the ones that do read through it.
+          ...(copySplit === undefined ? [] : [copySplit.plugin]),
         ],
         ...(options.conditions ? { conditions: [...options.conditions] } : {}),
         // Replace `process.env.*` at compile time so an app module reading config off `process.env` doesn't
@@ -550,6 +583,11 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
       return { name: out.path, kind: "code", text: await out.text() }
     }),
   )
+  assertNoImportGlob(
+    emitted.flatMap((file) =>
+      file.kind === "code" ? [[relative(cwd, file.name), file.text ?? ""] as const] : [],
+    ),
+  )
   const clientGraph = withEmittedImports(fromBunMetafile(clientMeta), emitted, publicPath)
   const verdict = verifyClientGraph(clientGraph, {
     classifier,
@@ -596,6 +634,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   if (unaccounted !== undefined) throw new Error(unaccounted)
 
   const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
+  const copy = copySplit?.chunks(publicPath)
   const { sources, originsOf } = graphScanInput(clientGraph, bunModuleSource(cwd), classifier)
   const secrets = formatSecretFindings(
     scanForSecrets({
@@ -606,6 +645,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
           const name = file.name.replace(/^\.\//, "")
           return emittedScanFiles(name, file.text, originsOf(name))
         }),
+        ...(copy?.files ?? []).flatMap((file) => emittedScanFiles(file.name, file.text)),
         ...(publicDir !== undefined && existsSync(publicDir)
           ? publicScanFiles(publicDir, originName(root, resolvePath(publicDir)))
           : []),
@@ -624,6 +664,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
       return { kind: out.kind, path }
     }),
   )
+  for (const file of copy?.files ?? []) writeFileSync(join(outDir, file.name), file.text)
 
   // Rename any chunk whose basename isn't URL-safe (dynamic-route files become `[slug]-hash.js`) and
   // rewrite the references - otherwise the lazy import 404s and the route silently never hydrates.
@@ -750,13 +791,15 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   const publicFiles =
     publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
 
+  const copyChunks = copy?.urls ?? {}
   const manifest: BuildManifest = {
     entry: entryUrl,
-    assets: outputs.map((o) => toUrl(o.path)),
+    assets: [...outputs.map((o) => toUrl(o.path)), ...Object.values(copyChunks)],
     routes,
     ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
+    ...(Object.keys(copyChunks).length > 0 ? { copyChunks } : {}),
   }
   assertDevelopmentProductionParity(collectDevelopmentParityInput(routesDir, publicDir), manifest)
   writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2))
@@ -780,6 +823,8 @@ export interface BuildServerOptions {
   readonly styles?: readonly string[] | undefined
   /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - baked alongside `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
+  /** Copy chunk URLs by locale (`buildClient`'s `BuildManifest.copyChunks`) - baked as `copyChunks`. */
+  readonly copyChunks?: Readonly<Record<string, string>> | undefined
   /** How framework-owned stylesheet links should activate before hydration (default `"blocking"`). */
   readonly cssLoading?: CssLoadingMode
   /** Route/layout file → import specifier in the generated manifest (default: a relative path from the
@@ -1051,6 +1096,7 @@ function formatRefusedFiles(refused: ReadonlyMap<string, string>, root: string):
   return `[nifra/web] the browser build reached code that may not ship to a browser:\n${lines.join("\n")}`
 }
 
+export { importGlobPlugin } from "./plugins/import-glob.ts"
 export { zoneGuardPlugin } from "./plugins/zone-guard.ts"
 
 /**
@@ -1130,6 +1176,7 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       styles,
       routeStyles,
       ...(cssLoading !== undefined ? { cssLoading } : {}),
+      ...(options.copyChunks !== undefined ? { copyChunks: options.copyChunks } : {}),
       lazy,
     }),
   )
@@ -1161,6 +1208,7 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       reactDedupePlugin(entryDir),
       preactDedupePlugin(entryDir),
       ...(options.plugins ?? []),
+      importGlobPlugin({ root: resolvePath(options.root ?? dirname(routesDir)) }),
     ],
   })
   if (!result.success) {
@@ -1227,7 +1275,14 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
 // ===================================================================================================
 
 /** The `createWebApp` options a generated server entry can import from the app's framework module. */
-export const SERVER_ENTRY_OPTIONS = ["apiPrefix", "apiStrip", "mounts", "csp", "nonce"] as const
+export const SERVER_ENTRY_OPTIONS = [
+  "apiPrefix",
+  "apiStrip",
+  "mounts",
+  "csp",
+  "nonce",
+  "i18n",
+] as const
 export type ServerEntryOption = (typeof SERVER_ENTRY_OPTIONS)[number]
 /** Each importable option mapped to the specifier of the module that exports it. */
 export type ServerEntryOptionImports = Readonly<Partial<Record<ServerEntryOption, string>>>
@@ -1251,6 +1306,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
@@ -1285,6 +1343,11 @@ export function generateServerEntry(options: {
   readonly hashedFiles?: readonly string[]
   /** Trust the edge platform's client-address header for `c.clientIp`. See {@link ServerEntryClientIp}. */
   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,
@@ -1316,7 +1379,22 @@ 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 and Node serve the client bundle through `servePublicDir`. 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 lines: string[] = [
+    !nodeFs
+      ? 'import { createWebApp } from "@nifrajs/web"'
+      : prerendered.length > 0
+        ? 'import { createWebApp, prerenderedPageReader, servePublicDir } from "@nifrajs/web"'
+        : 'import { createWebApp, servePublicDir } 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)}`)
@@ -1327,22 +1405,43 @@ export function generateServerEntry(options: {
     lines.push(`import { backend } from ${JSON.stringify(backendImport)}`)
   }
   lines.push(
-    'import { clientEntry, cssLoading, manifest, styles, routeStyles } from "./server-manifest"',
+    options.copyChunks === true
+      ? 'import { clientEntry, copyChunks, cssLoading, manifest, styles, routeStyles } from "./server-manifest"'
+      : 'import { clientEntry, cssLoading, manifest, styles, routeStyles } from "./server-manifest"',
   )
   // 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"')
+  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,",
     "  styles,",
     "  routeStyles,",
     "  cssLoading,",
+    ...(options.copyChunks === true ? ["  copyChunks,"] : []),
     ...(backendImport !== undefined ? ["  api: inProcessClient(backend),"] : []),
     `  title: ${JSON.stringify(title)},`,
     // Core's own `{ header }` trust, so the mounted backend and every loader see the derived caller.
@@ -1406,14 +1505,20 @@ 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, HEAD
+    // answered without reading the file, 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.
+    ...(nodeFs
+      ? [
+          "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).
@@ -1425,11 +1530,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).",
@@ -1444,20 +1547,11 @@ export function generateServerEntry(options: {
   }
   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 })',
-      "        }",
-      "      }",
+      "      if (staticPath(pathname) !== undefined) return staticResponse(req)",
       "      return app.fetch(req, platform)",
       "    },",
       "  },",
@@ -1473,13 +1567,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 })",
@@ -1488,6 +1576,99 @@ export function generateServerEntry(options: {
   return `${lines.join("\n")}\n`
 }
 
+/**
+ * The Deno entry's static handler: `servePublicDir`'s checks 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.
+ * HEAD answers from `stat` without reading; one byte range is served from a seek, several as the
+ * whole file.
+ */
+function denoStaticResponse(hashed: boolean): string[] {
+  return [
+    `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": ${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)",
+    "const hiddenSegment = (rel: string): boolean =>",
+    '  rel.split(/[\\\\/]/).some((segment) => segment.startsWith(".") && segment !== ".well-known")',
+    "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",
+    "  try {",
+    "    // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
+    "    const real: string = await Deno.realPath(new URL(filePath, STATIC_ROOT))",
+    '    if (!real.startsWith(STATIC_REAL + (STATIC_REAL.includes("\\\\") ? "\\\\" : "/"))) return missing()',
+    "    if (hiddenSegment(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()",
+    "  }",
+    "  const size: number = info.size",
+    "  const headers = new Headers(staticHeaders(pathname))",
+    '  const range = req.method === "GET" ? parseByteRange(req.headers.get("range"), size) : { kind: "none" as const }',
+    '  if (!info.isFile || req.method === "HEAD" || range.kind === "unsatisfiable") {',
+    "    file.close()",
+    "    if (!info.isFile) return missing()",
+    '    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]!",
+    "    // @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-range", "bytes " + start + "-" + end + "/" + size)',
+    '    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 })",
+    "  }",
+    '  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}. */
@@ -1531,7 +1712,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[]
@@ -1630,6 +1813,7 @@ export const bunBundler: Bundler = {
       target: input.target,
       ...(input.styles !== undefined ? { styles: input.styles } : {}),
       ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
+      ...(input.copyChunks !== undefined ? { copyChunks: input.copyChunks } : {}),
       ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
       ...(input.define ? { define: input.define } : {}),
       ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
@@ -1659,6 +1843,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,
@@ -1759,6 +1985,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(
@@ -1813,6 +2054,8 @@ export async function buildTargetWith(
       ...(publicFiles.length > 0 ? { publicFiles } : {}),
       hashedFiles: client.assets,
       ...(options.clientIp !== undefined ? { clientIp: options.clientIp } : {}),
+      ...(client.copyChunks !== undefined ? { copyChunks: true } : {}),
+      ...(prerenderedPages !== undefined ? { prerenderedPages } : {}),
     }),
   )
   const { worker } = await bundler.buildServer({
@@ -1823,6 +2066,7 @@ export async function buildTargetWith(
     target: targetPlan.serverTarget,
     ...(client.css !== undefined ? { styles: client.css } : {}),
     ...(client.routeStyles !== undefined ? { routeStyles: client.routeStyles } : {}),
+    ...(client.copyChunks !== undefined ? { copyChunks: client.copyChunks } : {}),
     ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
     ...(client.cssLoading !== undefined

package/src/client.ts

@@ -19,6 +19,7 @@ import {
   setBlockerController,
   setBrowserNavigate,
 } from "./navigation.ts"
+import { handoverLocale } from "./render-seam.ts"
 import { type ClientRouter, redirectOf } from "./router.ts"
 
 /** Read the nonce carried by the current server-rendered document, if any. */
@@ -49,6 +50,7 @@ export {
   resolveNavigate,
 } from "./navigation.ts"
 export { createMutation, createQueryClient } from "./query.ts"
+export { localeOfProps } from "./render-seam.ts"
 export { createClientRouter, createMatcher } from "./router.ts"
 // Same reason, for the ADAPTER packages (`@nifrajs/web-react` and friends). Every one of them reaches
 // for these from the root - `searchOfChain` in its `/client` entry, the navigation and query values in
@@ -617,17 +619,23 @@ export function installHistory(
  * content (charset, hand-written tags) is never touched. SSR injects the same `data-nifra` tags, so
  * the first navigation cleanly takes over from the server-rendered head.
  */
-export function applyHead(head: Meta): void {
+export function applyHead(head: Meta, path?: string): void {
   const documentNonce = currentDocumentNonce()
   if (head.title !== undefined) document.title = head.title
   // `<html lang>`/`<html dir>` - applied AUTHORITATIVELY (unlike `title`, which is left alone when the
-  // route omits it), mirroring the SSR shell's defaulting exactly: `lang` falls back to `"en"`, `dir` is
-  // removed when unset. Anything laxer drifts on a multilingual site - navigating /ur → /en would leave
-  // `dir="rtl"` behind and lay the English page out right-to-left, a bug a hard reload would not show.
+  // route omits it), mirroring the SSR shell's defaulting exactly: a meta `lang` wins, then the page's
+  // registered locale, then `"en"`; `dir` is removed when unset. Anything laxer drifts on a
+  // multilingual site - navigating /ur → /en would leave `dir="rtl"` behind and lay the English page
+  // out right-to-left, a bug a hard reload would not show.
+  const locale =
+    head.lang === undefined
+      ? handoverLocale(path ?? (typeof location === "undefined" ? "" : location.pathname))
+      : undefined
+  const dir = head.dir ?? locale?.dir
   const root = document.documentElement
-  root.setAttribute("lang", head.lang ?? "en")
-  if (head.dir === undefined) root.removeAttribute("dir")
-  else root.setAttribute("dir", head.dir)
+  root.setAttribute("lang", head.lang ?? locale?.lang ?? "en")
+  if (dir === undefined) root.removeAttribute("dir")
+  else root.setAttribute("dir", dir)
   for (const el of document.head.querySelectorAll("[data-nifra]")) el.remove()
   // Values follow the same HTML attribute conventions as the SSR `tagAttrs`: a string sets the value,
   // `true` sets the bare boolean attribute, `false`/`undefined` skip it - so a soft-nav head matches