@nifrajs/web 3.3.0 → 4.0.0

package/src/build-plan.ts

@@ -1,4 +1,8 @@
 import { basename as pathBasename } from "node:path"
+import type { CssLoadingMode } from "./css-contract.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { isBareNodeBuiltin } from "./internal/node-builtins.ts"
+import type { SecretExemption } from "./internal/secret-scan.ts"
 import type { ClientModuleGraph } from "./module-graph.ts"
 
 export interface BuildManifest {
@@ -19,6 +23,10 @@ export interface BuildManifest {
    * imported the CSS; the always-safe fallback `createWebApp` links when a route has no per-route entry
    * in {@link routeStyles}. Omitted when the app imports no CSS. */
   readonly css?: readonly string[]
+  /** Whether the Vite client build kept CSS split by entry/chunk. Absent for the native Bun build. */
+  readonly cssCodeSplit?: boolean
+  /** How framework-owned SSR stylesheet links should become active. Defaults to `blocking`. */
+  readonly cssLoading?: CssLoadingMode
   /** `routeId → [chain CSS URLs]` - only the stylesheets the matched route's layout chain + own file
    * actually use (Bun emits a per-entrypoint CSS bundle per route/layout, with shared-component CSS
    * inlined into each consumer). `createWebApp` links these instead of the aggregate, so a page ships
@@ -46,7 +54,7 @@ export interface ServerBuild {
 // ===================================================================================================
 
 /** A deploy target `nifra build --target <t>` can emit. `static` is pure SSG (no server). */
-export const BUILD_TARGETS = ["bun", "node", "deno", "cf-pages", "vercel", "static"] as const
+export const BUILD_TARGETS = ["bun", "node", "deno", "cloudflare", "vercel", "static"] as const
 export type BuildTarget = (typeof BUILD_TARGETS)[number]
 
 /** A type guard narrowing an arbitrary string to a {@link BuildTarget}. */
@@ -54,6 +62,16 @@ export function isBuildTarget(value: string): value is BuildTarget {
   return (BUILD_TARGETS as readonly string[]).includes(value)
 }
 
+/** `value` as a {@link BuildTarget}, or throw naming the valid ones (and the renamed `cf-pages`). */
+export function parseBuildTarget(value: string, label = "target"): BuildTarget {
+  if (isBuildTarget(value)) return value
+  throw new Error(
+    value === "cf-pages"
+      ? `[nifra] the ${label} "cf-pages" is now "cloudflare"`
+      : `[nifra] unknown ${label} "${value}". Valid: ${BUILD_TARGETS.join(", ")}`,
+  )
+}
+
 export type ServerBuildTarget = "browser" | "node" | "bun"
 
 export interface StaticBuildTargetPlan {
@@ -61,6 +79,7 @@ export interface StaticBuildTargetPlan {
   readonly kind: "static"
   readonly serverTarget: undefined
   readonly outputFile: undefined
+  readonly staticDir: ""
   readonly run: string
 }
 
@@ -68,8 +87,10 @@ export interface ServerBuildTargetPlan {
   readonly target: Exclude<BuildTarget, "static">
   readonly kind: "server"
   readonly serverTarget: ServerBuildTarget
-  /** The worker's final filename inside the assembled deploy directory. */
-  readonly outputFile: "_worker.js" | "index.js" | "server.js"
+  /** The worker's final path inside the assembled deploy directory. */
+  readonly outputFile: "_worker.js" | "functions/index.func/index.js" | "server.js"
+  /** Where the host serves static files from, relative to the deploy directory (`""` = its root). */
+  readonly staticDir: "" | "static"
   readonly run: string
 }
 
@@ -101,15 +122,17 @@ export function planBuildTarget(target: BuildTarget, outDir: string): BuildTarge
       kind: "static",
       serverTarget: undefined,
       outputFile: undefined,
+      staticDir: "",
       run: `static site → ${outDir} (serve the directory with any static host)`,
     }
   }
-  if (target === "cf-pages") {
+  if (target === "cloudflare") {
     return {
       target,
       kind: "server",
       serverTarget: "browser",
       outputFile: "_worker.js",
+      staticDir: "",
       run: `Cloudflare Pages → ${outDir} (deploy: wrangler pages deploy ${finalPathSegment(outDir)})`,
     }
   }
@@ -118,8 +141,10 @@ export function planBuildTarget(target: BuildTarget, outDir: string): BuildTarge
       target,
       kind: "server",
       serverTarget: "browser",
-      outputFile: "index.js",
-      run: `Vercel edge function → ${outDir}/index.js (wrap with your vercel.json or Build Output API)`,
+      // Vercel's Build Output API: `vercel deploy --prebuilt` uploads this tree as it is.
+      outputFile: "functions/index.func/index.js",
+      staticDir: "static",
+      run: `Vercel (Build Output API) → ${outDir} (deploy: vercel deploy --prebuilt)`,
     }
   }
   return {
@@ -127,6 +152,7 @@ export function planBuildTarget(target: BuildTarget, outDir: string): BuildTarge
     kind: "server",
     serverTarget: target === "node" ? "node" : target === "bun" ? "bun" : "browser",
     outputFile: "server.js",
+    staticDir: "",
     run: `${target} server → ${outDir} (run: ${target === "node" ? "node" : target} ${finalPathSegment(outDir)}/server.js)`,
   }
 }
@@ -150,8 +176,14 @@ export interface Bundler {
     readonly define?: Readonly<Record<string, string>>
     readonly publicDir?: string | false
     readonly publicEnvPrefix?: string
+    /** Vite CSS splitting policy; the Bun strategy rejects `false` and otherwise preserves its native behavior. */
+    readonly cssCodeSplit?: boolean
+    /** Framework-owned stylesheet activation policy; supported by both server strategies. */
+    readonly cssLoading?: CssLoadingMode
     /** Project root (Vite needs it; the Bun strategy ignores it). */
     readonly root?: string
+    /** Reviewed false positives of the secret scan. */
+    readonly secretExemptions?: readonly SecretExemption[]
   }): Promise<BuildManifest>
   /** Build the server worker → the shared {@link ServerBuild}. */
   buildServer(input: {
@@ -160,15 +192,26 @@ export interface Bundler {
     readonly outDir: string
     readonly clientEntry: string
     readonly target: "browser" | "node" | "bun"
+    /** The client build's aggregate stylesheet URLs to bake into the server manifest. */
+    readonly styles?: readonly string[]
+    /** The client build's per-route stylesheet map to bake into the server manifest. */
+    readonly routeStyles?: Readonly<Record<string, readonly string[]>>
     readonly plugins?: readonly unknown[]
     readonly define?: Readonly<Record<string, string>>
+    /** CSS activation policy to bake into the generated server manifest. */
+    readonly cssLoading?: CssLoadingMode
     readonly root?: string
+    /** Modules the zone rules treat as generated: the adapter module the generated entry imports. */
+    readonly generatedFiles?: readonly string[]
+    /** The public-env prefix browser code may read (default `"PUBLIC_"`). */
+    readonly publicEnvPrefix?: string
   }): Promise<ServerBuild>
 }
 
 interface GraphImport {
   readonly path?: string
   readonly original?: string
+  readonly external?: boolean
 }
 
 interface GraphInput {
@@ -180,7 +223,11 @@ const basename = (path: string): string => pathBasename(path)
 const nodeBuiltinOf = (im: GraphImport): string | undefined => {
   if (im.original?.startsWith("node:")) return im.original
   if (im.path?.startsWith("node:")) return im.path
-  return undefined
+  // A bare built-in only counts when the bundler left it external: a bundled `fs` resolved to an
+  // installed package (or a polyfill keyed `node:fs`) is handled above or is not a built-in at all.
+  // Labeled with the prefix, so `fs/promises` reads the same from either bundler.
+  const spec = im.external === true ? (im.original ?? im.path) : undefined
+  return spec !== undefined && isBareNodeBuiltin(spec) ? `node:${spec}` : undefined
 }
 
 /** One `node:`-builtin-in-the-client finding: the offending builtin, the emitted chunk it landed in,
@@ -287,29 +334,43 @@ export function detectNodeBuiltinsInClient(
     chains.set(builtin, chain)
     return chain
   }
+  // (1b) Builtins the bundler left EXTERNAL: the import ships in the importer's chunk but the module
+  // is in no output, so (2) can't find it as a chunk member. Bun does this for a dynamic
+  // `import("node:fs")` in a browser build; the browser then fails to load it.
+  const externalsOf = new Map<string, string[]>()
+  for (const [inputKey, input] of Object.entries(inputs)) {
+    if (inputKey.startsWith("node:")) continue
+    for (const im of input.imports ?? []) {
+      if (im.external !== true) continue
+      const builtin = nodeBuiltinOf(im)
+      if (builtin === undefined) continue
+      const list = externalsOf.get(inputKey) ?? []
+      if (!list.includes(builtin)) list.push(builtin)
+      externalsOf.set(inputKey, list)
+    }
+  }
   // (2) Locate which emitted chunk each user-imported builtin reached, via the per-output `inputs`.
   const findings = new Map<string, NodeBuiltinFinding>()
+  const report = (builtin: string, outputPath: string): void => {
+    const chunk = basename(outputPath)
+    findings.set(`${builtin}\0${chunk}`, { builtin, chunk, chain: chainFor(builtin) })
+  }
   for (const [outputPath, output] of Object.entries(graph.chunks)) {
     for (const inputKey of output.modules) {
-      if (!userImported.has(inputKey)) continue
-      const chunk = basename(outputPath)
-      findings.set(`${inputKey}\0${chunk}`, {
-        builtin: inputKey,
-        chunk,
-        chain: chainFor(inputKey),
-      })
+      if (userImported.has(inputKey)) report(inputKey, outputPath)
+      for (const builtin of externalsOf.get(inputKey) ?? []) report(builtin, outputPath)
     }
   }
   return [...findings.values()].sort((a, b) =>
-    a.builtin === b.builtin ? a.chunk.localeCompare(b.chunk) : a.builtin.localeCompare(b.builtin),
+    a.builtin === b.builtin ? codeUnitOrder(a.chunk, b.chunk) : codeUnitOrder(a.builtin, b.builtin),
   )
 }
 
 // ---------------------------------------------------------------------------------------------------
-// `server-only` poison-import guard (§3.3/§5.1). The complement to the `.server` convention + the
+// `backend-only` poison-import guard (§3.3/§5.1). The complement to the zones + the
 // node-builtin guard: a module of PURE server logic with NO `node:` import (a secret-bearing constant,
 // a server-only API call) that an author wants to FAIL LOUD if it reaches the client opts in with a
-// side-effect `import "@nifrajs/web/server-only"` (Next's `import "server-only"`). On the SERVER build
+// side-effect `import "@nifrajs/web/backend-only"` (Next's `import "server-only"`). On the SERVER build
 // the marker is an empty no-op; the CLIENT build detects - via the SAME Bun metafile graph the
 // node-builtin guard walks - any module that imports the marker AND lands in a client chunk, and fails
 // the build with the import chain. Graph-based (never the emitted text), so it survives minification.
@@ -317,18 +378,18 @@ export function detectNodeBuiltinsInClient(
 
 /** The marker specifier an author imports to opt a module into the client-leak guard. Matched on the
  * import edge's *as-written* `original` first (the robust signal: it's exactly what the author typed,
- * before Bun resolves it to `src/server-only.ts` / `dist/server-only.js`). */
-export const SERVER_ONLY_MARKER = "@nifrajs/web/server-only"
+ * before Bun resolves it to `src/backend-only.ts` / `dist/backend-only.js`). */
+export const SERVER_ONLY_MARKER = "@nifrajs/web/backend-only"
 
 const isServerOnlyMarkerImport = (im: GraphImport): boolean => {
   if (im.original === SERVER_ONLY_MARKER) return true
-  return im.path !== undefined && /(^|\/)server-only\.[cm]?[jt]s$/.test(im.path)
+  return im.path !== undefined && /(^|\/)backend-only\.[cm]?[jt]s$/.test(im.path)
 }
 
-/** True when an INPUT graph key is the marker module file itself (`…/server-only.{ts,js}` under web).
+/** True when an INPUT graph key is the marker module file itself (`…/backend-only.{ts,js}` under web).
  * Excluded from the "marked" set - the marker is the import target, not an opt-in module. */
 const isServerOnlyMarkerModule = (inputKey: string): boolean =>
-  /(^|\/)server-only\.[cm]?[jt]s$/.test(inputKey)
+  /(^|\/)backend-only\.[cm]?[jt]s$/.test(inputKey)
 
 /** One `server-only`-module-in-the-client finding: the offending module (the as-written marker-import
  * chain's tail before the marker), the emitted chunk it landed in, and the shortest USER-module import
@@ -383,7 +444,7 @@ function shortestServerOnlyChain(
 ): string[] {
   // The label for the marked module's tail: its as-written specifier (filled when we cross the edge
   // that reaches it) suffixed with `(marked server-only)`; the entry case uses the entry key itself.
-  const tail = (label: string): string => `${label} (marked server-only)`
+  const tail = (label: string): string => `${label} (marked backend-only)`
   // An entry that is ITSELF the marked module - the chain is just that one node.
   if (entryInputs.includes(markedModule)) return [tail(markedModule)]
   const seen = new Set(entryInputs)
@@ -412,7 +473,7 @@ function shortestServerOnlyChain(
 
 /**
  * Scan a build's metafile for any module that opts into the `server-only` marker (a side-effect
- * `import "@nifrajs/web/server-only"`) yet landed in a CLIENT output chunk, returning a sorted, deduped
+ * `import "@nifrajs/web/backend-only"`) yet landed in a CLIENT output chunk, returning a sorted, deduped
  * list of {@link ServerOnlyFinding}s. Mirrors {@link detectNodeBuiltinsInClient}: it reads the SAME
  * graph facts - which inputs import the marker (the "marked" modules), which chunk each landed in (the
  * per-output `inputs`), and the shortest import chain from a user entry to it. The marker module ITSELF
@@ -451,17 +512,28 @@ export function detectServerOnlyInClient(
   }
   // (2) Locate which emitted chunk each marked module reached, via the per-output `inputs`.
   const findings = new Map<string, ServerOnlyFinding>()
+  const placed = new Set<string>()
   for (const [outputPath, output] of Object.entries(graph.chunks)) {
     for (const inputKey of output.modules) {
       if (!marked.has(inputKey)) continue
       const chunk = basename(outputPath)
+      placed.add(inputKey)
       findings.set(`${inputKey}\0${chunk}`, { chunk, chain: chainFor(inputKey) })
     }
   }
+  // A marked module the build loaded but no chunk lists: the bundler inlined what it exports (a
+  // constant ships without its module) or dropped it. The import crossed the boundary either way.
+  for (const inputKey of marked) {
+    if (placed.has(inputKey)) continue
+    findings.set(`${inputKey}\0`, {
+      chunk: "none, inlined or shaken out",
+      chain: chainFor(inputKey),
+    })
+  }
   return [...findings.values()].sort((a, b) => {
     const am = a.chain[a.chain.length - 1] ?? ""
     const bm = b.chain[b.chain.length - 1] ?? ""
-    return am === bm ? a.chunk.localeCompare(b.chunk) : am.localeCompare(bm)
+    return am === bm ? codeUnitOrder(a.chunk, b.chunk) : codeUnitOrder(am, bm)
   })
 }
 
@@ -483,9 +555,8 @@ export function formatNodeBuiltinLeak(
       : `  - ${finding.builtin} reached the client bundle via ${finding.chunk}`,
   )
   return (
-    `[nifra/web] Node built-in(s) in the client bundle - move them behind a server-only path ` +
-    `(a loader/action runs on the server; import the \`node:\` module there, not at a route's ` +
-    `top level):\n${lines.join("\n")}`
+    `[nifra/web] Node built-in(s) in the client bundle - built-ins run on the server only: import ` +
+    `them in a route's backend half (x.backend.ts) or under backend/, never in browser code:\n${lines.join("\n")}`
   )
 }
 
@@ -496,14 +567,13 @@ export function formatServerOnlyLeak(
   if (findings.length === 0) return undefined
   const lines = findings.map((finding) =>
     finding.chain.length > 1
-      ? `  - server-only module reached the client bundle via ${finding.chain.join(" → ")} (chunk: ${finding.chunk})`
-      : `  - server-only module reached the client bundle via ${finding.chunk}`,
+      ? `  - backend-only module reached the client bundle via ${finding.chain.join(" → ")} (chunk: ${finding.chunk})`
+      : `  - backend-only module reached the client bundle via ${finding.chunk}`,
   )
   return (
-    `[nifra/web] server-only module(s) in the client bundle - a module marked ` +
-    `\`import "${SERVER_ONLY_MARKER}"\` reached the browser. Move it behind a server-only path ` +
-    `(reach it via a loader/action, or rename it \`*.server.ts\`), so its server logic never ships ` +
-    `to the client:\n${lines.join("\n")}`
+    `[nifra/web] backend-only module(s) in the client bundle - a module marked ` +
+    `\`import "${SERVER_ONLY_MARKER}"\` reached the browser. Move it under backend/ and reach it ` +
+    `from a route's backend half (x.backend.ts) or a *.fn.ts server function:\n${lines.join("\n")}`
   )
 }
 
@@ -540,7 +610,7 @@ export interface SizeReport {
  */
 export function aggregateSizeReport(chunks: readonly ChunkSize[]): SizeReport {
   const sorted = [...chunks].sort(
-    (a, b) => b.gzip - a.gzip || b.bytes - a.bytes || a.name.localeCompare(b.name),
+    (a, b) => b.gzip - a.gzip || b.bytes - a.bytes || codeUnitOrder(a.name, b.name),
   )
   let totalBytes = 0
   let totalGzip = 0
@@ -618,6 +688,8 @@ export interface ManifestDrift {
 const MANIFEST_ROUTE_ENTRY = /^[ \t]+(["'])([^"'\n]+)\1\s*:\s*(?:m\d+\b|\(\s*\)\s*=>\s*import\b)/gm
 // The baked client-entry line: `export const clientEntry = "…"`.
 const MANIFEST_CLIENT_ENTRY = /export\s+const\s+clientEntry\s*=\s*["']([^"']+)["']/
+// The baked stylesheet activation line: `generateServerManifest` emits this after the style maps.
+const MANIFEST_CSS_LOADING = /export\s+const\s+cssLoading\s*=\s*["'](blocking|deferred)["']/
 
 /**
  * Extract the route-relative file list a committed server-manifest declares, as the same
@@ -642,6 +714,11 @@ export function parseManifestClientEntry(source: string): string | undefined {
   return MANIFEST_CLIENT_ENTRY.exec(source)?.[1]
 }
 
+/** The baked framework stylesheet activation mode, or `undefined` for an older manifest. Pure. */
+export function parseManifestCssLoading(source: string): CssLoadingMode | undefined {
+  return MANIFEST_CSS_LOADING.exec(source)?.[1] as CssLoadingMode | undefined
+}
+
 // The baked asset lines `generateServerManifest` emits: `export const styles = […]` then
 // `export const routeStyles = {…}`, each a JSON literal running to the next `export const`. Extracted
 // with `indexOf` slicing rather than a lazy `[\s\S]*?` regex: the slice is multi-line by nature (a
@@ -653,7 +730,7 @@ function bakedManifestLiteral(source: string, name: string): string | undefined
   if (start === -1) return undefined
   const from = start + opener.length
   const end = source.indexOf("\nexport const ", from)
-  return end === -1 ? undefined : source.slice(from, end)
+  return source.slice(from, end === -1 ? source.length : end).trim()
 }
 
 /** Parse a baked JSON literal captured from a committed manifest, tolerating a formatter's TRAILING COMMAS

package/src/build-vite.ts

@@ -28,6 +28,13 @@ import {
   publicEnvDefines,
 } from "./build.ts"
 import type { BuildManifest, BuildTarget, Bundler, ServerBuild } from "./build-plan.ts"
+import {
+  assertCssLoadingCompatible,
+  type CssLoadingMode,
+  DEFAULT_CSS_LOADING,
+  normalizeCssCodeSplit,
+  normalizeCssLoading,
+} from "./css-contract.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
 import { viteDedupePackages } from "./internal/identity-policy.ts"
@@ -37,12 +44,17 @@ import {
   collectDevelopmentParityInput,
 } from "./internal/parity.ts"
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
+import { unsupportedBuiltin } from "./internal/target-compat.ts"
 import { importVite, isViteUnresolved } from "./internal/vite-import.ts"
 import { scopedName } from "./plugins/css-modules.ts"
 import { reproduciblePath } from "./plugins/kit.ts"
-import { viteLeakGuard } from "./plugins/vite-leak-guard.ts"
+import {
+  viteAssetUrlGuard,
+  viteBareBuiltinExternal,
+  viteLeakGuard,
+  viteServerZoneGuard,
+} from "./plugins/vite-leak-guard.ts"
 import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
-import { viteServerOnlyEmpty } from "./plugins/vite-server-only.ts"
 
 // ---------------------------------------------------------------------------------------------------
 // Structural Vite typings - no hard `vite` dependency (mirrors vite.ts). Only the build API is used.
@@ -117,6 +129,17 @@ export interface BuildClientViteOptions extends Omit<BuildClientOptions, "plugin
   readonly vitePlugins?: readonly unknown[]
   /** Vite project root (default: the parent of `routesDir`). Manifest keys are relative to it. */
   readonly root?: string
+  /**
+   * Vite's CSS output strategy (default `true`). Set to `false` to emit one aggregate stylesheet for
+   * the whole client, preventing lazy-route prefetch from attaching additional stylesheets.
+   */
+  readonly cssCodeSplit?: boolean
+  /**
+   * Activation policy for framework-owned SSR stylesheet links (default `"blocking"`). `"deferred"`
+   * fetches with `media="print"` and the generated client promotes the links before mounting. It must
+   * be paired with `cssCodeSplit: false`; split lazy chunks can otherwise attach CSS during prefetch.
+   */
+  readonly cssLoading?: CssLoadingMode
 }
 
 /**
@@ -130,6 +153,9 @@ export interface BuildClientViteOptions extends Omit<BuildClientOptions, "plugin
  */
 export async function buildClientVite(options: BuildClientViteOptions): Promise<BuildManifest> {
   const { routesDir, outDir, clientModule } = options
+  const cssCodeSplit = normalizeCssCodeSplit(options.cssCodeSplit)
+  const cssLoading = normalizeCssLoading(options.cssLoading ?? DEFAULT_CSS_LOADING)
+  assertCssLoadingCompatible(cssCodeSplit, cssLoading)
   const root = resolvePath(options.root ?? dirname(routesDir))
   await assertIdentityParity(root)
   const resolve = options.resolve ?? ((file: string) => `${routesDir}/${file}`)
@@ -153,6 +179,8 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
       ...routeManifest.routes.map((r) => r.file),
       ...Object.values(routeManifest.layouts).map((l) => l.file),
       ...(routeManifest.notFound ? [routeManifest.notFound.file] : []),
+      // A nested `_404` is an entry only for its stylesheet: it renders on the server, unhydrated.
+      ...Object.values(routeManifest.notFounds ?? {}).map((page) => page.file),
     ]),
   ].sort()
 
@@ -180,7 +208,28 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
   const buildEnv = (typeof Bun !== "undefined" ? Bun.env : undefined) ?? process.env
   const publicDefines = publicEnvDefines(options.publicEnvPrefix ?? "PUBLIC_", buildEnv)
   const vite = await loadVite()
-  const leakGuard = viteLeakGuard()
+  // A worker is bundled by its own sub-build the main graph never sees, so it gets its own guard; the
+  // main guard then accepts the worker chunks that guard verified.
+  const verified = new Set<string>()
+  const exemptions = options.secretExemptions
+  const guardOptions = {
+    appRoot: dirname(routesDir),
+    routesDir,
+    root,
+    outDir: resolvePath(outDir),
+    generatedFiles: [entryFile],
+    verified,
+    ...(options.publicEnvPrefix !== undefined ? { publicEnvPrefix: options.publicEnvPrefix } : {}),
+    secrets: { env: buildEnv, ...(exemptions ? { exemptions } : {}) },
+  }
+  // nifra copies `public/` after the build; the main guard scans it with the bundle.
+  const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
+  const leakGuard = viteLeakGuard({
+    ...guardOptions,
+    secrets: { ...guardOptions.secrets, ...(publicDir !== undefined ? { publicDir } : {}) },
+  })
+  const assetUrlGuard = viteAssetUrlGuard(guardOptions)
+  const workerGuards: { readonly leak?: string | undefined }[] = []
   try {
     await withSerializedNodeEnv(mode, () =>
       vite.build({
@@ -214,11 +263,22 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
               scopedName(reproduciblePath(filename), name),
           },
         },
-        plugins: [...(options.vitePlugins ?? [])],
+        // First, so a bare built-in is named before Vite turns it into an anonymous stub.
+        // The asset URL guard last, so it reads each module after any framework plugin made it JavaScript.
+        plugins: [viteBareBuiltinExternal(), ...(options.vitePlugins ?? []), assetUrlGuard],
+        worker: {
+          plugins: () => {
+            const guard = viteLeakGuard(guardOptions)
+            const urlGuard = viteAssetUrlGuard(guardOptions)
+            workerGuards.push(guard, urlGuard)
+            return [viteBareBuiltinExternal(), viteServerFnStub(), guard, urlGuard]
+          },
+        },
         build: {
           outDir,
           emptyOutDir: false, // buildTargetWith owns outDir lifecycle; never let Vite wipe sibling files
           manifest: true,
+          cssCodeSplit,
           minify: options.minify !== false,
           rollupOptions: {
             // Keep `node:` builtins as external specifiers so the leak guard sees `node:crypto` and can
@@ -229,7 +289,7 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
             external: [/^node:/],
             input,
             // The leak guard is a Rollup plugin - last, so it sees the final graph.
-            plugins: [viteServerFnStub(), viteServerOnlyEmpty(), leakGuard],
+            plugins: [viteServerFnStub(), leakGuard],
             output: {
               entryFileNames: "[name]-[hash].js",
               chunkFileNames: "[name]-[hash].js",
@@ -245,7 +305,11 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     // that construction fails, replacing a precise "node:crypto reached the client bundle" with an
     // internal complaint naming nothing. Raising it here puts the message beyond anything that can
     // rewrite it; the bundler's error is kept as `cause` for the rest of the context.
-    if (leakGuard.leak !== undefined) throw new Error(leakGuard.leak, { cause: error })
+    const leak =
+      assetUrlGuard.leak ??
+      leakGuard.leak ??
+      workerGuards.find((guard) => guard.leak !== undefined)?.leak
+    if (leak !== undefined) throw new Error(leak, { cause: error })
     throw error
   } finally {
     rmSync(entryDir, { recursive: true, force: true })
@@ -298,16 +362,28 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     }
     return [...urls]
   }
-  // CSS aggregate - every stylesheet the app emits, the always-safe fallback.
+  // CSS aggregate - every stylesheet the app emits, the always-safe fallback. With native Vite
+  // `cssCodeSplit: false`, the aggregate is a standalone manifest asset and is not listed in any
+  // JavaScript entry's `css` array. Collect both shapes so the framework manifest never loses the only
+  // stylesheet in a single-file build.
   const allCss = new Set<string>()
   for (const entry of Object.values(viteManifest)) {
+    if (entry.file.endsWith(".css")) allCss.add(url(entry.file))
     for (const css of entry.css ?? []) allCss.add(url(css))
   }
   const css = [...allCss]
   const routeStyles: Record<string, readonly string[]> = {}
-  if (css.length > 0) {
+  // A single aggregate stylesheet is deliberately the route fallback. A per-route `[]` map would
+  // suppress it in `createWebApp` and produce unstyled SSR on every route.
+  if (css.length > 0 && cssCodeSplit) {
     for (const route of routeManifest.routes) routeStyles[route.id] = stylesFor(chainFiles(route))
     if (routeManifest.notFound) routeStyles._404 = stylesFor([routeManifest.notFound.file])
+    for (const [id, page] of Object.entries(routeManifest.notFounds ?? {})) {
+      routeStyles[id] = stylesFor([
+        ...page.layoutIds.map((layoutId) => routeManifest.layouts[layoutId]?.file ?? ""),
+        page.file,
+      ])
+    }
   }
 
   // assets - every emitted file + stylesheet across the manifest (chunks, entries, css).
@@ -318,7 +394,6 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     for (const asset of entry.assets ?? []) assets.add(url(asset))
   }
 
-  const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
   const publicFiles =
     publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
 
@@ -326,6 +401,8 @@ export async function buildClientVite(options: BuildClientViteOptions): Promise<
     entry: url(bootstrap.file),
     assets: [...assets],
     routes,
+    cssCodeSplit,
+    cssLoading,
     ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
@@ -343,6 +420,8 @@ export interface BuildServerViteOptions {
   readonly clientEntry: string
   readonly styles?: readonly string[] | undefined
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
+  /** How framework-owned stylesheet links should activate before hydration (default `"blocking"`). */
+  readonly cssLoading?: CssLoadingMode
   readonly resolve?: (file: string) => string
   readonly manifestFile?: string
   readonly vitePlugins?: readonly unknown[]
@@ -353,6 +432,10 @@ export interface BuildServerViteOptions {
   readonly target?: "browser" | "node" | "bun"
   /** Vite project root (default: the parent of `routesDir`). */
   readonly root?: string
+  /** Modules the build generated besides the entry and manifest (a target's adapter import). */
+  readonly generatedFiles?: readonly string[]
+  /** The public-env prefix browser code may read (default `"PUBLIC_"`). */
+  readonly publicEnvPrefix?: string
 }
 
 interface EdgeBundleChunk {
@@ -399,12 +482,13 @@ function edgeBuiltinGuard(): EdgeGuardPlugin {
       for (const output of Object.values(bundle)) {
         if (output.type !== "chunk") continue
         for (const specifier of [...(output.imports ?? []), ...(output.dynamicImports ?? [])]) {
-          if (specifier.startsWith("node:")) builtins.add(specifier)
+          if (unsupportedBuiltin(specifier, "browser")) builtins.add(specifier)
         }
         for (const id of output.moduleIds ?? []) {
           const info = this.getModuleInfo(id)
           const imports = [...(info?.importedIds ?? []), ...(info?.dynamicallyImportedIds ?? [])]
-          if (imports.some((specifier) => specifier.startsWith("node:"))) importers.add(id)
+          if (imports.some((specifier) => unsupportedBuiltin(specifier, "browser")))
+            importers.add(id)
         }
       }
       if (builtins.size === 0) return
@@ -434,7 +518,7 @@ function edgeBuiltinGuard(): EdgeGuardPlugin {
  * The client-leak guards are deliberately NOT run here: a server bundle's `node:` imports are legitimate.
  */
 export async function buildServerVite(options: BuildServerViteOptions): Promise<ServerBuild> {
-  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles } = options
+  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles, cssLoading } = options
   const root = resolvePath(options.root ?? dirname(routesDir))
   const entryDir = dirname(serverEntry)
   const manifestFile = options.manifestFile ?? "server-manifest.ts"
@@ -451,7 +535,13 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
   const routeManifest = discoverRoutes(routesDir)
   writeFileSync(
     `${entryDir}/${manifestFile}`,
-    generateServerManifest(routeManifest, { resolve, clientEntry, styles, routeStyles }),
+    generateServerManifest(routeManifest, {
+      resolve,
+      clientEntry,
+      styles,
+      routeStyles,
+      ...(cssLoading !== undefined ? { cssLoading } : {}),
+    }),
   )
 
   // Pin the mode to match NODE_ENV - the react plugin's JSX runtime (jsx vs jsxDEV) follows it, and a
@@ -459,6 +549,16 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
   const mode = options.minify === false ? "development" : "production"
   const vite = await loadVite()
   const edgeGuard = edgeBuiltinGuard()
+  const zoneGuard = viteServerZoneGuard({
+    appRoot: root,
+    routesDir: resolvePath(routesDir),
+    generatedFiles: [
+      serverEntry,
+      join(entryDir, manifestFile),
+      ...(options.generatedFiles ?? []),
+    ].map((file) => resolvePath(file)),
+    ...(options.publicEnvPrefix !== undefined ? { publicEnvPrefix: options.publicEnvPrefix } : {}),
+  })
   try {
     await withSerializedNodeEnv(mode, () =>
       vite.build({
@@ -487,7 +587,7 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
             // Keep builtins external so Node/Bun use their native implementations. Edge builds add a
             // generateBundle guard below, so an external specifier can never silently ship to workerd.
             external: [/^node:/],
-            ...(edge ? { plugins: [edgeGuard] } : {}),
+            plugins: [...(edge ? [edgeGuard] : []), zoneGuard],
             // ONE self-contained `server.js`. `inlineDynamicImports` forces the ENTRY chunk to absorb
             // every module - the app, the adapter, react/react-dom, @nifrajs/* - so no second chunk is
             // emitted. It is NOT redundant with `ssr.noExternal`: `noExternal` decides what gets bundled,
@@ -512,7 +612,8 @@ export async function buildServerVite(options: BuildServerViteOptions): Promise<
   } catch (error) {
     // Re-raise the guard's own message from here, where no bundler error-reporting path can rewrite it
     // (see the same handling in buildClientVite).
-    if (edgeGuard.leak !== undefined) throw new Error(edgeGuard.leak, { cause: error })
+    const leak = zoneGuard.leak ?? edgeGuard.leak
+    if (leak !== undefined) throw new Error(leak, { cause: error })
     throw error
   }
 
@@ -536,8 +637,11 @@ export const viteBundler: Bundler = {
       ...(input.plugins ? { vitePlugins: input.plugins } : {}),
       ...(input.conditions ? { conditions: input.conditions } : {}),
       ...(input.define ? { define: input.define } : {}),
+      ...(input.cssCodeSplit !== undefined ? { cssCodeSplit: input.cssCodeSplit } : {}),
+      ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
       ...(input.publicDir !== undefined ? { publicDir: input.publicDir } : {}),
       ...(input.publicEnvPrefix !== undefined ? { publicEnvPrefix: input.publicEnvPrefix } : {}),
+      ...(input.secretExemptions !== undefined ? { secretExemptions: input.secretExemptions } : {}),
       ...(input.root ? { root: input.root } : {}),
     }),
   buildServer: (input) =>
@@ -547,9 +651,14 @@ export const viteBundler: Bundler = {
       outDir: input.outDir,
       clientEntry: input.clientEntry,
       target: input.target,
+      ...(input.styles !== undefined ? { styles: input.styles } : {}),
+      ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
       ...(input.plugins ? { vitePlugins: input.plugins } : {}),
       ...(input.define ? { define: input.define } : {}),
+      ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
       ...(input.root ? { root: input.root } : {}),
+      ...(input.generatedFiles !== undefined ? { generatedFiles: input.generatedFiles } : {}),
+      ...(input.publicEnvPrefix !== undefined ? { publicEnvPrefix: input.publicEnvPrefix } : {}),
     }),
 }