@nifrajs/web 5.1.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"
@@ -11,13 +17,23 @@ import type {
   RouteModule,
   UnsafeScriptDescriptor,
 } from "../manifest.ts"
-import type { DocumentParts, MatchChain, RenderAdapter, RenderProps } from "../render-seam.ts"
+import type {
+  DocumentParts,
+  MatchChain,
+  PageLocale,
+  PageLocales,
+  RenderAdapter,
+  RenderProps,
+} from "../render-seam.ts"
 import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
+  COPY_CHUNKS_GLOBAL,
+  COPY_REALM,
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
 } from "../render-seam.ts"
@@ -44,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")
 
@@ -111,6 +134,15 @@ export interface RenderPageOptions {
   /** SSG: the URL of a JSON array of the prerendered paths, handed over in place of
    * {@link prerenderedPaths} so a large set is fetched once instead of riding in every page. */
   readonly prerenderedListUrl?: string
+  /** Locale key -> copy chunk URL (`buildClient`'s `BuildManifest.copyChunks`), handed over to the
+   * client; the chunks this page reads its copy from are preloaded. Omit ⇒ none. */
+  readonly copyChunks?: Readonly<Record<string, string>>
+  /** The page's locale from the app's locale routing: `<html lang dir>` default to it unless `head`
+   * sets `lang`, the response carries `Content-Language`, and the adapter reads it as
+   * `RenderProps.locale`. Omit ⇒ none of these. */
+  readonly locale?: PageLocale
+  /** The served locales, handed to the client so it names each page's locale on navigation. */
+  readonly locales?: PageLocales
   /** ISR: route freshness in seconds, emitted as the `x-nifra-isr-revalidate` header for a `withISR`
    * wrapper to read. Omit ⇒ no header (the wrapper's default TTL applies). */
   readonly revalidate?: number
@@ -184,7 +216,7 @@ export interface RenderPageOptions {
    * prefix/suffix, tail statics) on the first render and reuses afterwards, skipping their re-assembly.
    *
    * Only pass a cache when every shell-shaping input is IDENTICAL across the requests sharing it:
-   * same `head` content (a static meta chain - never a `meta(data)` function), `title`, `styles`,
+   * same `head` content (a static meta chain - never a `meta(data)` function), `locale`, `title`, `styles`,
    * `cssLoading`, `preload`, `islandScripts`, `clientEntry`, `rootId`, `hydrate`, and `prerenderedPaths`.
    * Per-request
    * values (`data`, `params`, `search`, `actionData`, `layoutData`, deferred state) are always assembled
@@ -248,6 +280,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     cssLoading: requestedCssLoading,
     prerenderedPaths = [],
     prerenderedListUrl,
+    copyChunks,
+    locale,
     revalidate,
     revalidateTags = [],
     routeId,
@@ -276,6 +310,13 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       : prerenderedPaths.length === 0
         ? ""
         : `,"${PRERENDERED_GLOBAL}":${serializeData(prerenderedPaths)}`
+  const copyHandover =
+    copyChunks === undefined ? "" : `,"${COPY_CHUNKS_GLOBAL}":${serializeData(copyChunks)}`
+  const localesHandover =
+    options.locales === undefined ? "" : `,"${LOCALES_GLOBAL}":${serializeData(options.locales)}`
+  // A route's `lang` wins with its own `dir`; otherwise the page's registered locale names both.
+  const lang = head?.lang ?? locale?.lang ?? "en"
+  const dir = head?.dir ?? (head?.lang === undefined ? locale?.dir : undefined)
   // Split deferred values: the component sees markers (id + promise) to `<Await>`; the serialized
   // data carries `{__nifra_deferred: id}` placeholders (promises don't serialize). `actionData` may
   // also `defer()` - split it too, continuing the id space so a single registry settles both. The
@@ -405,7 +446,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     // `<html>` attributes. `lang` defaults to `"en"`; `dir` is omitted entirely when unset, which IS
     // HTML's `ltr` default. Both attribute-escaped. `client.ts`'s `applyHead` mirrors this exact
     // defaulting on soft-nav, so a hard load and a client navigation produce the same `<html>`.
-    const htmlAttrs = ` lang="${escapeAttr(head?.lang ?? "en")}"${head?.dir === undefined ? "" : ` dir="${escapeAttr(head.dir)}"`}`
+    const htmlAttrs = ` lang="${escapeAttr(lang)}"${dir === undefined ? "" : ` dir="${escapeAttr(dir)}"`}`
     // Marks the container for the client entry when the id is not the one the entry falls back to.
     const rootMarker = rootId === "root" ? "" : ` ${ROOT_ATTRIBUTE}`
     // A non-hydrated page omits the adapter's hydration bootstrap entirely (Solid's `_$HY` registry
@@ -432,7 +473,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     if (hydrate) {
       // Inert JSON, never executed: the page state needs no nonce and no hash under any CSP.
       slot.tailPre = `<script type="application/json" id="${HANDOVER_ID}">{"${DATA_GLOBAL}":`
-      slot.tailPost = `${route}${prerendered}}</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`
+      slot.tailPost = `${route}${prerendered}${copyHandover}${localesHandover}}</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`
     } else {
       slot.tailPre = ""
       slot.tailPost = `${islandTags}</body></html>`
@@ -441,13 +482,18 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
   // only when something actually deferred - matching the pre-cache emission exactly.
   const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : ""
-  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}${slot.rootOpen}`
+  // Per request, so outside the cached shell: one route serves every locale.
+  const copyPreloads =
+    hydrate && copyChunks !== undefined
+      ? copyPreloadLinks(copyChunks, options.path ?? "", lang)
+      : ""
+  const shellHtml = `${slot.shellPre}${copyPreloads}${runtimeSeam}${slot.shellPost}${slot.rootOpen}`
   const parts: DocumentParts | undefined =
     adapter.documentParts === true ? { head: "", body: "" } : undefined
   const shellOf = (): string =>
     parts === undefined || (parts.head === "" && parts.body === "")
       ? shellHtml
-      : `${slot.shellPre}${runtimeSeam}${parts.head}${slot.shellPost}${parts.body}${slot.rootOpen}`
+      : `${slot.shellPre}${copyPreloads}${runtimeSeam}${parts.head}${slot.shellPost}${parts.body}${slot.rootOpen}`
   // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
   // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
   const closeRootHtml = "</div>"
@@ -457,6 +503,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${slot.tailPost}`
     : (slot.tailPost as string)
   const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
+  if (locale !== undefined) headers["content-language"] = lang
   // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
   // framework's own below, so `content-type` and the ISR channel stay authoritative - a caller must
   // not be able to mislabel the document or forge the freshness header by passing them here.
@@ -501,6 +548,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       ? { boundaries: boundarySplit.forComponent as BoundaryStates }
       : {}),
     ...(options.matchChain !== undefined ? { matchChain: options.matchChain } : {}),
+    ...(locale === undefined ? {} : { locale }),
   }
 
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
@@ -509,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(
@@ -638,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,
@@ -652,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) {
@@ -1171,3 +1270,25 @@ export function unsafeInlineScript(
     content,
   }
 }
+
+/** The copy chunks a page loads first, as `@nifrajs/i18n/copy` picks them in the browser, so they
+ * download beside the route's code instead of after it. */
+function copyPreloadLinks(
+  chunks: Readonly<Record<string, string>>,
+  path: string,
+  lang: string,
+): string {
+  const realm: unknown = Reflect.get(globalThis, Symbol.for(COPY_REALM))
+  if (typeof realm !== "object" || realm === null) return ""
+  const pageLocales: unknown = Reflect.get(realm, "pageLocales")
+  if (typeof pageLocales !== "function") return ""
+  const locales: unknown = Reflect.apply(pageLocales, realm, [path, lang])
+  if (!Array.isArray(locales)) return ""
+  let links = ""
+  for (const locale of locales) {
+    const url =
+      typeof locale === "string" && Object.hasOwn(chunks, locale) ? chunks[locale] : undefined
+    if (url !== undefined) links += `<link rel="modulepreload" href="${escapeAttr(url)}">`
+  }
+  return links
+}

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/typescript-api.ts

@@ -0,0 +1,11 @@
+import type * as TS from "typescript"
+
+/** Whether a loaded `typescript` module carries the in-process compiler API (TypeScript 7's does not). */
+export function isTypeScriptCompiler(value: unknown): value is typeof TS {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "createSourceFile" in value &&
+    typeof value.createSourceFile === "function"
+  )
+}

package/src/internal/vite-plugin-compat.ts

@@ -0,0 +1,81 @@
+// A Vite `config` hook is a plain function or the object form `{ handler, order }` Vite accepts for hook
+// ordering; plugins are typed structurally (no `vite` type dep) and every other field is kept by spread.
+type ConfigFn = (config: unknown, env: unknown) => unknown
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+
+/**
+ * Move a plugin's `optimizeDeps.rollupOptions` to `optimizeDeps.rolldownOptions` under rolldown-vite and
+ * drop its `jsx` key, so Vite 8 warns about neither on `nifra dev` or a Vite build.
+ *
+ * Both are version-skew artifacts of plugins such as `@vitejs/plugin-react@4.x`, which still emit
+ * `optimizeDeps.rollupOptions.jsx`:
+ *
+ * - Vite 8 renamed the dep optimizer's options to `rolldownOptions` and moved jsx under `transform.jsx`,
+ *   so a stale `jsx` key prints `Invalid input options … "jsx" Invalid key`. The route JSX transform runs
+ *   through the plugin's own `transform` hook and pre-bundled deps almost never hold raw JSX, so the key
+ *   is dead and dropping it changes no behavior.
+ * - Vite 8 reads `rollupOptions` there only as a deprecated alias of `rolldownOptions` and warns on every
+ *   resolve, even for `{}`. The remaining keys move to `rolldownOptions`; when the same object already
+ *   sets `rolldownOptions`, Vite ignores the alias, so it is dropped. `ssr.optimizeDeps` gets the same.
+ *
+ * Only a plugin's `config` hook output is rewritten, never mutated, and only under rolldown-vite.
+ * Non-rolldown Vite is passed through verbatim.
+ *
+ * FLATTEN FIRST: a Vite plugin factory may return an ARRAY of plugins - `@vitejs/plugin-react`'s `react()`
+ * returns `[vite:react-babel, vite:react-refresh]`, and it's `react:react-babel`'s `config` hook that emits
+ * the offending `optimizeDeps.rollupOptions.jsx`. `nifra.config.ts` writes `vitePlugins = [react()]`, so the
+ * plugin list arrives NESTED (`[[babel, refresh]]`). Without flattening, `.map` sees the inner array (which
+ * has no `config`), leaves it untouched, and Vite - which flattens plugin arrays itself before running them
+ * - then executes the un-stripped babel hook, so the warning survives. Flattening here (Vite accepts a flat
+ * list identically) is what lets the strip reach every real plugin.
+ */
+export function normalizeRolldownPlugins(
+  plugins: readonly unknown[],
+  isRolldown: boolean,
+): readonly unknown[] {
+  if (!isRolldown) return plugins
+  const migrateDepOptions = (deps: unknown): unknown => {
+    if (!isRecord(deps)) return deps
+    const { rollupOptions, ...rest } = deps
+    if (rollupOptions === undefined) return deps
+    // Vite skips the alias when the same object sets rolldownOptions (mergeConfigRecursively).
+    if (rest.rolldownOptions || rollupOptions === null) return rest
+    if (!isRecord(rollupOptions)) return { ...rest, rolldownOptions: rollupOptions }
+    const { jsx: _dropped, ...kept } = rollupOptions
+    return Object.keys(kept).length === 0 ? rest : { ...rest, rolldownOptions: kept }
+  }
+  const migrateConfig = (returned: unknown): unknown => {
+    if (!isRecord(returned)) return returned
+    const ssr = isRecord(returned.ssr) ? returned.ssr : undefined
+    const deps = migrateDepOptions(returned.optimizeDeps)
+    const ssrDeps = migrateDepOptions(ssr?.optimizeDeps)
+    if (deps === returned.optimizeDeps && ssrDeps === ssr?.optimizeDeps) return returned
+    const out = { ...returned }
+    if (deps !== returned.optimizeDeps) out.optimizeDeps = deps
+    if (ssr !== undefined && ssrDeps !== ssr.optimizeDeps)
+      out.ssr = { ...ssr, optimizeDeps: ssrDeps }
+    return out
+  }
+  return plugins.flat(Number.POSITIVE_INFINITY).map((plugin) => {
+    if (!isRecord(plugin)) return plugin
+    // `config` may be a plain function or the object form `{ handler, order }`. Wrap the handler either way.
+    const hook = plugin.config
+    const objectHook = isRecord(hook) ? hook : undefined
+    const handler = typeof hook === "function" ? hook : objectHook?.handler
+    if (typeof handler !== "function") return plugin
+    const wrappedHandler: ConfigFn = (config, env) => {
+      const returned: unknown = handler(config, env)
+      // The hook may return a promise - normalize both shapes.
+      return returned instanceof Promise ? returned.then(migrateConfig) : migrateConfig(returned)
+    }
+    // Preserve the ORIGINAL shape: a function stays a function; the object form keeps its `order`
+    // (collapsing `{ handler, order }` to a bare function would silently drop the hook ordering).
+    return {
+      ...plugin,
+      config:
+        objectHook === undefined ? wrappedHandler : { ...objectHook, handler: wrappedHandler },
+    }
+  })
+}

package/src/internal/web-app.ts

@@ -21,14 +21,61 @@ import type { RenderAdapter } from "../render-seam.ts"
 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 } from "./page-execution.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"
+
+/** An app's locale routing as `createWebApp` reads it: what `defineI18nRouting()` from
+ * `@nifrajs/i18n/routing` returns. */
+export interface WebAppI18n {
+  readonly locales: {
+    readonly default: string
+    /** Served locale keys, in registry order. */
+    readonly served: readonly string[]
+    documentMeta(key: string): { readonly lang: string; readonly dir: "ltr" | "rtl" }
+  }
+  localeOf(path: string): string
+  matchSegment(
+    value: string | undefined,
+    pathname: string,
+  ):
+    | { readonly kind: "ok" | "not-found" }
+    | { readonly kind: "redirect"; readonly location: string }
+}
+
+function pageI18n(routing: WebAppI18n): PageI18n {
+  const { locales } = routing
+  if (
+    typeof routing.localeOf !== "function" ||
+    typeof routing.matchSegment !== "function" ||
+    typeof locales?.documentMeta !== "function" ||
+    !Array.isArray(locales.served)
+  ) {
+    throw new TypeError(
+      "[nifra/web] createWebApp `i18n` must be the router defineI18nRouting() from @nifrajs/i18n/routing returns",
+    )
+  }
+  return {
+    locales: {
+      default: locales.default,
+      locales: locales.served.map((key) => {
+        const { lang, dir } = locales.documentMeta(key)
+        return { key, lang, dir }
+      }),
+    },
+    localeOf: (path) => routing.localeOf(path),
+    matchSegment: (value, pathname) => routing.matchSegment(value, pathname),
+  }
+}
+
 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. */
@@ -181,6 +228,20 @@ export interface CreateWebAppOptions<Env = unknown> {
    * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
    * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+  /** Locale key -> copy chunk URL (`buildClient`'s `BuildManifest.copyChunks`, the server manifest's
+   * `copyChunks`). A production client build moves copy tables (`@nifrajs/i18n/copy`) into one chunk per
+   * locale; each page lists them for the browser and preloads its own. Omit ⇒ tables keep their values. */
+  readonly copyChunks?: Readonly<Record<string, string>>
+  /**
+   * The app's locale routing, `defineI18nRouting()` from `@nifrajs/i18n/routing`, registered once:
+   * export it as `i18n` from `backend/framework.ts`. Every document then takes its locale from the
+   * URL: `<html lang dir>` from the registry unless the route's meta sets `lang`, a `Content-Language`
+   * header, and the locale each adapter's `useLocale()` and `<I18nProvider>` read. A route under a
+   * `[lang]` or `[[lang]]` directory is checked with its `matchSegment()` before any middleware: an
+   * unserved locale, or a page missing from it, is a 404, and a non-canonical prefix (`/en/x` when the
+   * default is unprefixed) redirects with a 308.
+   */
+  readonly i18n?: WebAppI18n
   /**
    * Activation policy for framework-owned stylesheet links (default `"blocking"`). `"deferred"`
    * emits `media="print"` links; the generated client waits for them and switches them to `all` before
@@ -194,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
@@ -417,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 }),
@@ -442,6 +514,8 @@ export function createWebApp<Env = unknown>(
     ...(options.routePreload === undefined ? {} : { routePreload: options.routePreload }),
     ...(options.styles === undefined ? {} : { styles: options.styles }),
     ...(options.routeStyles === undefined ? {} : { routeStyles: options.routeStyles }),
+    ...(options.copyChunks === undefined ? {} : { copyChunks: options.copyChunks }),
+    ...(options.i18n === undefined ? {} : { i18n: pageI18n(options.i18n) }),
     ...(options.cssLoading === undefined ? {} : { cssLoading: options.cssLoading }),
     ...(options.prerenderedPaths === undefined
       ? {}
@@ -460,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))
   }