@nifrajs/web 2.1.0 → 2.3.0

package/src/build.ts

@@ -1,17 +1,26 @@
 /**
- * `@nifrajs/web/build` — the production build (Bun-only, build-time). `buildClient` codegens + bundles
+ * `@nifrajs/web/build` - the production build (Bun-only, build-time). `buildClient` codegens + bundles
  * the client entry (content-hashed, code-split); `buildServer` codegens the static-import server
  * manifest + bundles a self-contained **worker** for the disk-less edge (Cloudflare Workers). Both
  * are Bun-specific and never on the request path (own subpath, like `@nifrajs/web/fs`); the *output*
  * runs on any runtime.
  */
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
-import { dirname, relative, resolve as resolvePath } from "node:path"
-import type { BunPlugin } from "bun"
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { cp, lstat, mkdir, realpath } from "node:fs/promises"
+import { dirname, join, relative, resolve as resolvePath, sep } from "node:path"
+import { type BunPlugin, Glob } from "bun"
 import { sanitizeOutputNames } from "./chunk-names.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
+import {
+  generateServerFnStub,
+  SERVER_FN_MODULE,
+  SERVER_ONLY_MODULE,
+  SERVER_ONLY_REPLACEMENT,
+  serverFnNamespace,
+} from "./internal/server-boundary.ts"
 // `buildTarget(static)` drives the SSG prerender engine directly (it's also re-exported below).
+import { type ClientModuleGraph, fromBunMetafile } from "./module-graph.ts"
 import { prerenderRoutes } from "./prerender.ts"
 
 // Build-time SSG: prerender opted-in static + dynamic routes to `index.html` (+ static `_data.json`),
@@ -48,11 +57,20 @@ export interface BuildClientOptions {
   readonly minify?: boolean
   /** URL prefix the assets are served under (default `"/assets/"`); also Bun's chunk `publicPath`. */
   readonly publicPath?: string
+  /**
+   * Directory of user-authored static files copied into the build and served at the root (default
+   * `"public"`). Absent directory ⇒ nothing copied, no error.
+   *
+   * NOT the same thing as {@link publicPath}, despite the names: that is the URL prefix for
+   * content-hashed bundle chunks and never covers files an author put on disk. The collision is a
+   * real source of confusion, which is why both are spelled out here.
+   */
+  readonly publicDir?: string | false
   /**
    * Prefix that opts an environment variable into the **client** bundle (Vite/Next convention; default
    * `"PUBLIC_"`). Every var in the build environment whose name starts with this prefix is baked into
    * the client `define` as `"process.env.NAME": JSON.stringify(value)`, so `process.env.PUBLIC_API_URL`
-   * compiles to its literal value in the browser. Vars WITHOUT the prefix are never exposed — the bare
+   * compiles to its literal value in the browser. Vars WITHOUT the prefix are never exposed - the bare
    * `process.env` define resolves them to `undefined`, so server secrets can't leak into the client
    * bundle. Set to `""` to disable auto-exposure entirely (no var is baked in). `options.define` still
    * wins over an auto-exposed var (it's layered last). Sourced from `Bun.env` (falls back to
@@ -82,26 +100,209 @@ export function publicEnvDefines(
   return defines
 }
 
-/** The built asset map — the server reads `entry` for the client script + serves `assets`. */
+/**
+ * Percent-encode one path segment exactly the way a browser encodes it into a request URL.
+ *
+ * NOT `encodeURIComponent`. That escapes the sub-delimiters `, @ + = & ; $`, which a browser sends raw -
+ * so a file named `report,2026.csv` would be recorded as `/report%2C2026.csv` while the request arrives
+ * as `/report,2026.csv`, the allowlist lookup misses, and the file 404s in production only. `encodeURI`
+ * agrees with `URL.pathname` on every character except `?` and `#`, which terminate a path and so must
+ * be escaped explicitly here.
+ */
+function encodePathSegment(segment: string): string {
+  return encodeURI(segment).replace(
+    /[?#]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  )
+}
+
+/**
+ * Cloudflare Pages rejects a `_routes.json` with more than 100 include+exclude rules combined, or any
+ * single rule longer than 100 characters.
+ */
+const CF_MAX_ROUTE_RULES = 100
+const CF_MAX_RULE_LENGTH = 100
+
+export interface CloudflareRouteRules {
+  readonly include: readonly string[]
+  readonly exclude: readonly string[]
+  /** Public files the budget could not name, so the build can say so instead of capping silently. */
+  readonly omitted: readonly string[]
+}
+
+/**
+ * What a route pattern's first URL segment says about the paths it can reach.
+ *
+ * The three cases are genuinely different and collapsing them is a fail-open bug: `/` reaches only the
+ * root and can never match below a directory, while `/:locale/about` can match below ANY directory, and
+ * both would otherwise read as "no literal first segment". `dynamic` is also where unrecognised syntax
+ * lands, deliberately - a pattern form this does not understand must never be taken as proof that
+ * nothing matches.
+ */
+type FirstSegment =
+  | { readonly kind: "root" }
+  | { readonly kind: "literal"; readonly value: string }
+  | { readonly kind: "dynamic" }
+
+function firstSegmentOf(pattern: string): FirstSegment {
+  const first = pattern.split("/").find((segment) => segment !== "")
+  if (first === undefined) return { kind: "root" }
+  return /^[A-Za-z0-9._-]+$/.test(first) ? { kind: "literal", value: first } : { kind: "dynamic" }
+}
+
+/**
+ * Directories under `public/` whose every file can be replaced by one `/<dir>/*` rule.
+ *
+ * Safe only when no route can ever be served beneath that directory, because the glob does not merely
+ * describe today's files - it hands Pages every future path under the prefix, and the worker never sees
+ * them. A `public/blog/hero.png` next to a `/blog/:slug` route is the ordinary case that breaks: the
+ * glob would send `/blog/my-post` to the CDN, which has no such file, and the page 404s in production
+ * only. So a directory collapses only when every route pattern starts with a literal segment that is
+ * something else. One dynamic first segment anywhere (`/:locale/…`) disables collapsing entirely, which
+ * is correct - such a route can match under any directory name.
+ *
+ * A collapsed directory also gives up the app's own 404 page for a missing file beneath it, since the
+ * request never reaches the worker. That is the right trade for a directory that holds only static
+ * files: a missing image should fail as a fast CDN 404, not as an HTML error page.
+ */
+function collapsibleDirs(
+  publicFiles: readonly string[],
+  routePatterns: readonly string[],
+): ReadonlySet<string> {
+  const reserved = new Set<string>()
+  for (const pattern of routePatterns) {
+    const first = firstSegmentOf(pattern)
+    // A dynamic first segment can match anywhere, so nothing is collapsible at all.
+    if (first.kind === "dynamic") return new Set()
+    // `root` reserves nothing: `/` cannot match a path below a directory.
+    if (first.kind === "literal") reserved.add(first.value)
+  }
+  const dirs = new Set<string>()
+  for (const file of publicFiles) {
+    const slash = file.indexOf("/", 1)
+    if (slash === -1) continue // a root-level file has no directory to collapse into
+    const dir = file.slice(1, slash)
+    if (!reserved.has(dir)) dirs.add(dir)
+  }
+  return dirs
+}
+
+/**
+ * Build the cf-pages `_routes.json` rules for a set of copied public files, within Cloudflare's budget.
+ *
+ * `exclude` is what Pages serves straight from the CDN instead of invoking the worker, so naming every
+ * public file is ideal - and impossible past ~99 of them. A `public/` of icons, fonts and share images
+ * clears 100 easily, and the rejection lands at `wrangler pages deploy`, long after the build reported
+ * success.
+ *
+ * A glob is emitted only where it cannot be wrong. `/assets/*` always is: the build owns that prefix
+ * outright, since it is where the hashed bundle is written. A `public/` subdirectory is different - the
+ * name is the author's, and a `/blog/*` rule would hand Pages every future path under `/blog/`, so a
+ * `/blog/:slug` route would 404 from the CDN in production only. {@link collapsibleDirs} therefore
+ * collapses a directory only after checking it against the app's real route patterns, which is what
+ * makes the compaction safe rather than merely smaller. Everything else stays an exact path, and a name
+ * containing `*` is dropped rather than escaped, since the rule would become a wildcard.
+ *
+ * What still does not fit is dropped, which is safe because the list is only an optimization: the
+ * generated worker serves any allowlisted path it receives through the ASSETS binding, so an omitted
+ * file costs one worker invocation, not a 404.
+ */
+export function cloudflareRouteRules(
+  publicFiles: readonly string[],
+  /**
+   * Every route pattern the app serves. Required, not defaulted: an empty list means "this app serves
+   * no routes", which makes every directory collapsible - a defensible answer to state deliberately and
+   * a dangerous one to arrive at by forgetting the argument.
+   */
+  routePatterns: readonly string[],
+): CloudflareRouteRules {
+  const include = ["/*"]
+  const exclude = ["/assets/*"]
+  const omitted: string[] = []
+
+  // Collapse only where the route table proves nothing can be served beneath the directory, and only
+  // when the per-file list would not have fit anyway - a smaller `_routes.json` is worth nothing on its
+  // own, and exact paths keep the app's own 404 for a missing file under that directory.
+  const perFileFits = publicFiles.length + include.length + exclude.length <= CF_MAX_ROUTE_RULES
+  const collapsible = perFileFits ? new Set<string>() : collapsibleDirs(publicFiles, routePatterns)
+  const emitted = new Set<string>()
+
+  for (const file of publicFiles) {
+    const slash = file.indexOf("/", 1)
+    const dir = slash === -1 ? undefined : file.slice(1, slash)
+    const collapsed = dir !== undefined && collapsible.has(dir)
+    const rule = collapsed ? `/${dir}/*` : file
+    if (emitted.has(rule)) continue // already covered by a rule emitted for an earlier file
+    // A `*` in a FILE name would turn that file's own rule into a wildcard. A collapsed rule's `*` is
+    // ours and deliberate, and the file's name never appears in it, so the check applies to one case.
+    if (!collapsed && file.includes("*")) {
+      omitted.push(file)
+      continue
+    }
+    if (include.length + exclude.length >= CF_MAX_ROUTE_RULES || rule.length > CF_MAX_RULE_LENGTH) {
+      omitted.push(file)
+      continue
+    }
+    exclude.push(rule)
+    emitted.add(rule)
+  }
+  return { include, exclude, omitted }
+}
+
+/** The built asset map - the server reads `entry` for the client script + serves `assets`. */
+/**
+ * Copy `from` into `to`, returning the URL paths copied (sorted).
+ *
+ * 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
+ * entry - a dynamic `import("bun")` there fails the browser build outright.
+ */
+export async function copyPublicDir(from: string, to: string): Promise<string[]> {
+  const source = resolvePath(from)
+  const sourceReal = await realpath(source)
+  const copied: string[] = []
+  for await (const rel of new Glob("**/*").scan({ cwd: source, dot: true, onlyFiles: false })) {
+    const candidate = join(source, rel)
+    const candidateStat = await lstat(candidate)
+    if (candidateStat.isSymbolicLink()) {
+      throw new Error(`[nifra/web] publicDir entry escapes its root through a symlink: ${rel}`)
+    }
+    if (!candidateStat.isFile()) continue
+    const candidateReal = await realpath(candidate)
+    if (candidateReal !== sourceReal && !candidateReal.startsWith(sourceReal + sep)) {
+      throw new Error(`[nifra/web] publicDir entry escapes its root through a symlink: ${rel}`)
+    }
+    const target = join(to, rel)
+    await mkdir(join(target, ".."), { recursive: true })
+    await cp(candidateReal, target)
+    copied.push(`/${rel.split(sep).map(encodePathSegment).join("/")}`)
+  }
+  return copied.sort()
+}
+
 export interface BuildManifest {
   /** URL of the client entry module (content-hashed). */
   readonly entry: string
-  /** URLs of every emitted asset (entry + chunks) — for serving + preloading. */
+  /** URLs of every emitted asset (entry + chunks) - for serving + preloading. */
   readonly assets: readonly string[]
-  /** `routeId → [layout chunk URLs…, own chunk URL]` — the chunks a route needs, for `createWebApp`'s
+  /** `routeId → [layout chunk URLs…, own chunk URL]` - the chunks a route needs, for `createWebApp`'s
    * `routePreload` (`<link rel="modulepreload">` the matched route alongside the entry). Each route +
    * layout is also a build entrypoint, so it gets a named chunk the bootstrap's lazy import dedupes to. */
   readonly routes: Readonly<Record<string, readonly string[]>>
-  /** The app's bundled, content-hashed stylesheet(s) — the bootstrap's **aggregate** CSS (every
+  /** URL paths copied from `publicDir`, sorted. Lets the server entry serve them without scanning a
+   * directory per request, and lets an adapter that needs a file list (CDN upload, platform static
+   * assets) consume one. Omitted when there is no `public/`. */
+  readonly publicFiles?: readonly string[]
+  /** The app's bundled, content-hashed stylesheet(s) - the bootstrap's **aggregate** CSS (every
    * `import './x.css'` reachable from the app). The complete stylesheet regardless of which file
    * 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[]
-  /** `routeId → [chain CSS URLs]` — only the stylesheets the matched route's layout chain + own file
+  /** `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
    * only its own CSS. A route is omitted (→ aggregate fallback) when its `[name]` collides with another
-   * route's basename (ambiguous CSS↔route) or the build emitted orphan shared-chunk CSS — correctness
+   * route's basename (ambiguous CSS↔route) or the build emitted orphan shared-chunk CSS - correctness
    * over minimality. Absent entirely when the app imports no CSS. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
 }
@@ -154,10 +355,10 @@ export interface NodeBuiltinFinding {
  * BFS the metafile import graph for the SHORTEST user-module path that pulls `builtin` into the
  * bundle, returning it as display labels `[entryFile, …as-written specifiers…, builtin]`. The frontier
  * starts at every `entryInput` (the route/user entrypoints) so the reported chain begins where the dev
- * actually wrote `import` — the actionable root, not an arbitrary internal module. Traversal crosses
+ * actually wrote `import` - the actionable root, not an arbitrary internal module. Traversal crosses
  * only NON-`node:` edges (so Bun's polyfill chain never extends the path) and stops at the first edge
  * whose target is the builtin. Returns `[builtin]` if no entry reaches it (defensive; a flagged builtin
- * is reachable by construction). Pure — operates on the graph, never the emitted text.
+ * is reachable by construction). Pure - operates on the graph, never the emitted text.
  */
 function shortestBuiltinChain(
   inputs: Readonly<Record<string, { readonly imports?: readonly BunMetafileImport[] }>>,
@@ -181,7 +382,7 @@ function shortestBuiltinChain(
         if (nodeBuiltinOf(im) === builtin) return [...chain, builtin]
         const target = im.path
         // Only follow edges into user (non-`node:`) modules that exist in the input graph and haven't
-        // been visited — so the polyfill subtree can't lengthen the path and there are no cycles.
+        // been visited - so the polyfill subtree can't lengthen the path and there are no cycles.
         if (
           target === undefined ||
           target.startsWith("node:") ||
@@ -192,47 +393,47 @@ function shortestBuiltinChain(
         }
         seen.add(target)
         // Display the hop by its as-written specifier (`../db/client.ts`, `postgres`), falling back to
-        // the resolved path — that's what the dev recognizes in their source, not the resolved path.
+        // the resolved path - that's what the dev recognizes in their source, not the resolved path.
         next.push({ node: target, chain: [...chain, im.original ?? target] })
       }
     }
     frontier = next
   }
-  return [builtin] // unreachable from any entry — degrade to just the builtin (shouldn't happen)
+  return [builtin] // unreachable from any entry - degrade to just the builtin (shouldn't happen)
 }
 
 /**
  * Scan a build's metafile for any `node:` builtin that a USER module pulled into a CLIENT output
  * chunk, returning a sorted, deduped list of {@link NodeBuiltinFinding}s. Three graph facts combine so
  * the report is precise AND actionable:
- *  1. **What the user wrote** — only builtins imported by a NON-`node:` input count, so Bun's own
+ *  1. **What the user wrote** - only builtins imported by a NON-`node:` input count, so Bun's own
  *     polyfill chain (`node:crypto` → `node:buffer`/`node:stream`/…) doesn't bury the real cause.
- *  2. **Where it landed** — the chunk is read from the per-output `inputs`, so the error names the
+ *  2. **Where it landed** - the chunk is read from the per-output `inputs`, so the error names the
  *     emitted file to look at.
- *  3. **How it got there** — the shortest import chain from a user entry to the builtin
+ *  3. **How it got there** - the shortest import chain from a user entry to the builtin
  *     (`shortestBuiltinChain`), so the error points straight at the offending `import` line instead of
  *     leaving the dev to grep the dependency tree (the DX gap this closes).
  * Graph-based (never the emitted text), so it survives minification and can't be fooled by a string
  * literal that merely contains `"node:crypto"`. Pure + exported for unit testing. Empty ⇒ clean.
  */
 export function detectNodeBuiltinsInClient(
-  meta: BunMetafile | undefined,
+  graph: ClientModuleGraph,
 ): ReadonlyArray<NodeBuiltinFinding> {
-  const inputs = meta?.inputs ?? {}
-  // (1) The builtins a user (non-polyfill) module imports directly — the ones the author controls.
+  const inputs = graph.modules
+  // (1) The builtins a user (non-polyfill) module imports directly - the ones the author controls.
   const userImported = new Set<string>()
   for (const [inputKey, input] of Object.entries(inputs)) {
-    if (inputKey.startsWith("node:")) continue // a polyfill importing another builtin — not the cause
+    if (inputKey.startsWith("node:")) continue // a polyfill importing another builtin - not the cause
     for (const im of input.imports ?? []) {
       const builtin = nodeBuiltinOf(im)
       if (builtin !== undefined) userImported.add(builtin)
     }
   }
-  // The entry inputs (route/user entrypoints) — the chain BFS starts here so the reported path begins
+  // The entry inputs (route/user entrypoints) - the chain BFS starts here so the reported path begins
   // at the file the dev wrote an `import` in. Each output's `entryPoint` is one such input.
   const entryInputs = [
     ...new Set(
-      Object.values(meta?.outputs ?? {})
+      Object.values(graph.chunks)
         .map((o) => o.entryPoint)
         .filter((e): e is string => e !== undefined && !e.startsWith("node:")),
     ),
@@ -248,8 +449,8 @@ export function detectNodeBuiltinsInClient(
   }
   // (2) Locate which emitted chunk each user-imported builtin reached, via the per-output `inputs`.
   const findings = new Map<string, NodeBuiltinFinding>()
-  for (const [outPath, out] of Object.entries(meta?.outputs ?? {})) {
-    for (const inputKey of Object.keys(out.inputs ?? {})) {
+  for (const [outPath, out] of Object.entries(graph.chunks)) {
+    for (const inputKey of out.modules) {
       if (userImported.has(inputKey)) {
         const chunk = basename(outPath)
         findings.set(`${inputKey}\0${chunk}`, {
@@ -270,8 +471,8 @@ export function detectNodeBuiltinsInClient(
 // 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
-// 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 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.
 // ---------------------------------------------------------------------------------------------------
 
@@ -282,7 +483,7 @@ export const SERVER_ONLY_MARKER = "@nifrajs/web/server-only"
 
 /** True when an import edge is the `server-only` marker import. Reads the as-written `original` (the
  * specifier the author typed); falls back to the resolved `path`'s basename so a pre-resolved edge
- * (no `original`) — or a workspace-relative resolution — is still recognised. */
+ * (no `original`) - or a workspace-relative resolution - is still recognised. */
 const isServerOnlyMarkerImport = (im: BunMetafileImport): boolean => {
   if (im.original === SERVER_ONLY_MARKER) return true
   // Defensive fallback: an edge that lost its `original` but resolved to the marker module file. The
@@ -310,8 +511,8 @@ export interface ServerOnlyFinding {
  * "<module> (marked server-only)"]`. Mirrors {@link shortestBuiltinChain}: the frontier starts at
  * every `entryInput` so the chain begins at the file the dev wrote an `import` in; traversal crosses
  * only NON-`node:` user edges (no cycles via `seen`); it stops at the first node whose import set
- * contains the marker (the marked module — the actionable tail), labelling that node by the as-written
- * specifier the previous hop used to reach it. Pure — operates on the graph, never the emitted text.
+ * contains the marker (the marked module - the actionable tail), labelling that node by the as-written
+ * specifier the previous hop used to reach it. Pure - operates on the graph, never the emitted text.
  */
 function shortestServerOnlyChain(
   inputs: Readonly<Record<string, { readonly imports?: readonly BunMetafileImport[] }>>,
@@ -322,7 +523,7 @@ function shortestServerOnlyChain(
   // 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)`
-  // An entry that is ITSELF the marked module — the chain is just that one node.
+  // 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<string>(entryInputs)
   let frontier: Array<{ node: string; chain: string[] }> = entryInputs.map((node) => ({
@@ -333,7 +534,7 @@ function shortestServerOnlyChain(
     const next: Array<{ node: string; chain: string[] }> = []
     for (const { node, chain } of frontier) {
       for (const im of inputs[node]?.imports ?? []) {
-        // Resolve the edge's `path` to the matching INPUT-GRAPH KEY — in a real build the edge `path`
+        // Resolve the edge's `path` to the matching INPUT-GRAPH KEY - in a real build the edge `path`
         // is absolute while the input keys are cwd-relative, so a raw equality/lookup would miss every
         // multi-hop user edge (and the chain would degrade to just the tail). The resolver maps both.
         const target = resolveTarget(im)
@@ -380,16 +581,16 @@ function inputKeyResolver(
  * 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
  * 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
+ * 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
- * (which imports nothing) is excluded — only the modules that *opt in* are flagged. Pure + exported for
+ * (which imports nothing) is excluded - only the modules that *opt in* are flagged. Pure + exported for
  * unit testing. Empty ⇒ clean.
  */
 export function detectServerOnlyInClient(
-  meta: BunMetafile | undefined,
+  graph: ClientModuleGraph,
 ): ReadonlyArray<ServerOnlyFinding> {
-  const inputs = meta?.inputs ?? {}
-  // (1) The modules that import the marker — the ones the author opted into the guard. The marker
+  const inputs = graph.modules
+  // (1) The modules that import the marker - the ones the author opted into the guard. The marker
   // module itself is skipped: it's the import TARGET, not an opt-in (it imports nothing of its own).
   const marked = new Set<string>()
   for (const [inputKey, input] of Object.entries(inputs)) {
@@ -397,11 +598,11 @@ export function detectServerOnlyInClient(
     if ((input.imports ?? []).some(isServerOnlyMarkerImport)) marked.add(inputKey)
   }
   if (marked.size === 0) return []
-  // The entry inputs — the chain BFS starts here, so the reported path begins at the file the dev
+  // The entry inputs - the chain BFS starts here, so the reported path begins at the file the dev
   // wrote an `import` in. Same derivation as the node-builtin guard.
   const entryInputs = [
     ...new Set(
-      Object.values(meta?.outputs ?? {})
+      Object.values(graph.chunks)
         .map((o) => o.entryPoint)
         .filter((e): e is string => e !== undefined && !e.startsWith("node:")),
     ),
@@ -417,8 +618,8 @@ export function detectServerOnlyInClient(
   }
   // (2) Locate which emitted chunk each marked module reached, via the per-output `inputs`.
   const findings = new Map<string, ServerOnlyFinding>()
-  for (const [outPath, out] of Object.entries(meta?.outputs ?? {})) {
-    for (const inputKey of Object.keys(out.inputs ?? {})) {
+  for (const [outPath, out] of Object.entries(graph.chunks)) {
+    for (const inputKey of out.modules) {
       if (marked.has(inputKey)) {
         const chunk = basename(outPath)
         findings.set(`${inputKey}\0${chunk}`, { chunk, chain: chainFor(inputKey) })
@@ -433,10 +634,52 @@ export function detectServerOnlyInClient(
 }
 
 /** True when an INPUT graph key is the marker module file itself (`…/server-only.{ts,js}` under web).
- * Excluded from the "marked" set — the marker is the import target, not an opt-in module. */
+ * 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)
 
+// ---------------------------------------------------------------------------------------------------
+// Guard MESSAGES - one owner for both production pipelines. The Bun build (below) and the Vite/Rollup
+// leak-guard plugin (plugins/vite-leak-guard.ts) both call these, so a leak reads IDENTICALLY whichever
+// bundler produced it. A second bundler must not grow a second, subtly-different wording of a security
+// error; that is exactly the "mostly ported" outcome the neutral graph seam exists to prevent.
+// ---------------------------------------------------------------------------------------------------
+
+/** The build-failing message for `node:` builtins that reached the client bundle. `undefined` ⇒ clean. */
+export function formatNodeBuiltinLeak(
+  findings: ReadonlyArray<NodeBuiltinFinding>,
+): string | undefined {
+  if (findings.length === 0) return undefined
+  const lines = findings.map((f) =>
+    f.chain.length > 1
+      ? `  - ${f.builtin} reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
+      : `  - ${f.builtin} reached the client bundle via ${f.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")}`
+  )
+}
+
+/** The build-failing message for `server-only`-marked modules that reached the client. `undefined` ⇒ clean. */
+export function formatServerOnlyLeak(
+  findings: ReadonlyArray<ServerOnlyFinding>,
+): string | undefined {
+  if (findings.length === 0) return undefined
+  const lines = findings.map((f) =>
+    f.chain.length > 1
+      ? `  - server-only module reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
+      : `  - server-only module reached the client bundle via ${f.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")}`
+  )
+}
+
 const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1)
 /** `[name]` Bun derives for an entrypoint: basename without extension (`users/[id].tsx` → `[id]`). */
 const entryName = (file: string): string => {
@@ -461,7 +704,7 @@ export interface ChunkSize {
   readonly gzip: number
 }
 
-/** A whole build's size report — every chunk (largest first) + the totals. */
+/** A whole build's size report - every chunk (largest first) + the totals. */
 export interface SizeReport {
   /** Per-chunk sizes, sorted biggest gzip first (the regression you want to see at the top). */
   readonly chunks: readonly ChunkSize[]
@@ -473,7 +716,7 @@ export interface SizeReport {
 
 /**
  * Aggregate a list of measured chunks into a {@link SizeReport}: sort biggest-gzip-first (ties broken
- * by raw bytes, then name for stable output) and sum the totals. Pure — the measurement (reading the
+ * by raw bytes, then name for stable output) and sum the totals. Pure - the measurement (reading the
  * file + `Bun.gzipSync`) happens in the orchestrator; this is the deterministic, unit-testable core.
  */
 export function aggregateSizeReport(chunks: readonly ChunkSize[]): SizeReport {
@@ -497,7 +740,7 @@ export function formatBytes(bytes: number): string {
 }
 
 /**
- * Render a {@link SizeReport} as a terse aligned table (biggest first) with a totals row — the text
+ * Render a {@link SizeReport} as a terse aligned table (biggest first) with a totals row - the text
  * `nifra build --report` prints. Pure (string in, string out) so the formatting is unit-testable.
  */
 export function renderSizeReport(report: SizeReport): string {
@@ -526,18 +769,18 @@ export function renderSizeReport(report: SizeReport): string {
 // ---------------------------------------------------------------------------------------------------
 // Server-manifest drift detection (#7). `server-manifest.ts` is a committed generated file: it bakes
 // the route list + the client-entry hash for a disk-less worker (`generateServerManifest`). If `routes/`
-// changes but the manifest isn't regenerated, the worker serves a stale route table — a silent edge
+// changes but the manifest isn't regenerated, the worker serves a stale route table - a silent edge
 // break. These pure helpers diff the COMMITTED manifest source against the freshly-discovered routes so
 // `nifra check` (and `buildServer`) can fail with a named, actionable error before the drift ships.
 // ---------------------------------------------------------------------------------------------------
 
 /** A drift finding between a committed server-manifest and the live `routes/` tree. */
 export interface ManifestDrift {
-  /** Route files present in `routes/` but ABSENT from the committed manifest (the manifest is stale —
+  /** Route files present in `routes/` but ABSENT from the committed manifest (the manifest is stale -
    * the new route won't be served by the worker). */
   readonly missing: readonly string[]
   /** Route files the committed manifest imports that no longer exist in `routes/` (a deleted/renamed
-   * route still wired into the worker — a build/runtime break). */
+   * route still wired into the worker - a build/runtime break). */
   readonly extra: readonly string[]
 }
 
@@ -553,7 +796,7 @@ const MANIFEST_CLIENT_ENTRY = /export\s+const\s+clientEntry\s*=\s*["']([^"']+)["
  * `routes/`-relative keys `discoverRoutes` produces (e.g. `docs/index.tsx`). `routesPrefix` is the
  * specifier prefix the manifest used for the routes dir (default `./routes/`, what `buildServer`'s
  * default `resolve` emits). Only import specifiers under that prefix are route files; the
- * `@nifrajs/web` import (and any other bare specifier) is ignored. Pure — operates on source text.
+ * `@nifrajs/web` import (and any other bare specifier) is ignored. Pure - operates on source text.
  */
 export function parseManifestRouteFiles(source: string, routesPrefix = "./routes/"): string[] {
   const files = new Set<string>()
@@ -635,8 +878,8 @@ export function resyncServerManifestSource(
 
 /**
  * Diff the route files a committed server-manifest imports against the files freshly discovered in
- * `routes/`. Returns the `missing` (in routes/, not in manifest — stale manifest) and `extra` (in
- * manifest, gone from routes/ — dangling import) sets. Empty arrays ⇒ in sync. Pure — the caller
+ * `routes/`. Returns the `missing` (in routes/, not in manifest - stale manifest) and `extra` (in
+ * manifest, gone from routes/ - dangling import) sets. Empty arrays ⇒ in sync. Pure - the caller
  * supplies both file lists (the committed source is parsed via {@link parseManifestRouteFiles}; the
  * fresh list comes from `discoverRoutes`). Lists need not be pre-sorted; the result is sorted.
  */
@@ -667,16 +910,16 @@ export function formatManifestDrift(
 ): string | undefined {
   if (isManifestInSync(drift)) return undefined
   const lines: string[] = [
-    `[nifra/web] server-manifest drift — \`${manifestPath}\` is out of sync with routes/.`,
+    `[nifra/web] server-manifest drift - \`${manifestPath}\` is out of sync with routes/.`,
   ]
   if (drift.missing.length > 0) {
     lines.push(
-      `  Missing (in routes/, not in the manifest — these routes won't be served): ${drift.missing.join(", ")}`,
+      `  Missing (in routes/, not in the manifest - these routes won't be served): ${drift.missing.join(", ")}`,
     )
   }
   if (drift.extra.length > 0) {
     lines.push(
-      `  Extra (imported by the manifest, gone from routes/ — a dangling import): ${drift.extra.join(", ")}`,
+      `  Extra (imported by the manifest, gone from routes/ - a dangling import): ${drift.extra.join(", ")}`,
     )
   }
   lines.push("  Fix: re-run the build to regenerate the server manifest, then commit it.")
@@ -685,7 +928,7 @@ export function formatManifestDrift(
 
 /**
  * Build the client bundle for a file-routed app. Writes the hashed assets + `manifest.json` to
- * `outDir` and returns the manifest. Throws (with the bundler logs) on build failure — never
+ * `outDir` and returns the manifest. Throws (with the bundler logs) on build failure - never
  * silently ships a broken bundle.
  */
 export async function buildClient(options: BuildClientOptions): Promise<BuildManifest> {
@@ -701,7 +944,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // 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
-  // layered after these in the `define` object). `Bun` may be absent under non-Bun typecheck — guard it.
+  // layered after these in the `define` object). `Bun` may be absent under non-Bun typecheck - guard it.
   const buildEnv = (typeof Bun !== "undefined" ? Bun.env : undefined) ?? process.env
   const publicDefines = publicEnvDefines(options.publicEnvPrefix ?? "PUBLIC_", buildEnv)
   // Keep the generated source beside the project, not inside `outDir`: module resolution starts at the
@@ -716,7 +959,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
     `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, { clientModule, resolve })}`,
   )
 
-  // Every unique route/layout/`_404` file (sorted, stable), as ADDITIONAL entrypoints — Bun emits a
+  // Every unique route/layout/`_404` file (sorted, stable), as ADDITIONAL entrypoints - Bun emits a
   // named chunk per file that the bootstrap's lazy `import()` dedupes to (verified), so the manifest
   // can map each route to its chunk URLs for matched-route preload. `resolve(file)` is the same
   // specifier the bootstrap imports, so the entrypoint + lazy import are the same module (dedup).
@@ -728,7 +971,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
     ]),
   ].sort()
 
-  // `metafile: true` asks Bun for the input/output graph — specifically `outputs[js].entryPoint`
+  // `metafile: true` asks Bun for the input/output graph - specifically `outputs[js].entryPoint`
   // (the source file) + `outputs[js].cssBundle` (that entry's emitted stylesheet). It's the robust
   // entry→CSS link for per-route splitting: keyed by the unique source path, so it survives
   // same-basename collisions (`index.tsx` + `blog/index.tsx`) that a filename match can't. Not yet in
@@ -745,7 +988,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
         splitting: true, // one chunk per lazily-imported route; shared deps deduped into shared chunks
         // `import "./x.css"` in a route/component → bundled, minified, content-hashed `.css` asset (Bun
         // strips the import from the JS; CSS bundling is on by default since Bun 1.2). Mapped to routes
-        // below — both the aggregate and per-route — via the metafile, for `<link>` injection.
+        // below - both the aggregate and per-route - via the metafile, for `<link>` injection.
         ...buildExtras,
         minify: options.minify ?? true,
         plugins: [
@@ -753,13 +996,14 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
           preactDedupePlugin(routesDir),
           svelteDedupePlugin(routesDir),
           serverOnlyEmptyPlugin(),
+          serverFnStubPlugin(),
           ...(options.plugins ?? []),
         ],
         ...(options.conditions ? { conditions: [...options.conditions] } : {}),
         // Replace `process.env.*` at compile time so an app module reading config off `process.env` doesn't
         // hit a `process is not defined` crash in the browser. Bun does longest-match: NODE_ENV resolves to
         // the build mode (React's prod/dev branch); each PUBLIC_* var resolves to its baked VALUE; every
-        // other `process.env.X` becomes undefined (the bare `process.env` → `({})` fallback — so secrets
+        // other `process.env.X` becomes undefined (the bare `process.env` → `({})` fallback - so secrets
         // never leak). Callers can override any of these via `options.define` (layered last).
         define: {
           "process.env": "({})",
@@ -780,49 +1024,25 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
 
   // #4: a `node:` builtin (e.g. `node:crypto`) pulled into a CLIENT chunk builds fine (Bun substitutes
   // a browser polyfill) but breaks/leaks at runtime. Fail the build with a named, actionable error
-  // instead — caught at build time, not by a confused user in the browser. Graph-based (the metafile's
+  // instead - caught at build time, not by a confused user in the browser. Graph-based (the metafile's
   // per-output `inputs`), so it can't false-positive on a `"node:..."` string literal and survives
   // minification. Only the client build runs this; the server build's `node:` imports are legitimate.
   const clientMeta = (result as unknown as { metafile?: BunMetafile }).metafile
-  const nodeBuiltins = detectNodeBuiltinsInClient(clientMeta)
-  if (nodeBuiltins.length > 0) {
-    // Name the offending builtin AND the import chain that pulled it in (entry → … → builtin), so the
-    // dev sees the exact path from a route file to the leak instead of just the emitted chunk name.
-    // The chain always starts at a user entry; fall back to the chunk name if it somehow came back empty.
-    const lines = nodeBuiltins.map((f) =>
-      f.chain.length > 1
-        ? `  - ${f.builtin} reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
-        : `  - ${f.builtin} reached the client bundle via ${f.chunk}`,
-    )
-    throw new Error(
-      `[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")}`,
-    )
-  }
-
-  // §3.3/§5.1: a module that opted into the `server-only` marker (`import "@nifrajs/web/server-only"`)
-  // yet reached a CLIENT chunk — fail the build with the same chain-bearing, "reached the client bundle
-  // via" message shape as the node-builtin guard above. This catches pure-server logic (a secret, a
-  // server-only API call) that carries no `node:` import and isn't named `*.server`, so neither of the
-  // other two guards fires. Graph-based (the same metafile), so it survives minification.
-  const serverOnly = detectServerOnlyInClient(clientMeta)
-  if (serverOnly.length > 0) {
-    const lines = serverOnly.map((f) =>
-      f.chain.length > 1
-        ? `  - server-only module reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
-        : `  - server-only module reached the client bundle via ${f.chunk}`,
-    )
-    throw new Error(
-      `[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")}`,
-    )
-  }
+  const clientGraph = fromBunMetafile(clientMeta)
+  // #4: a `node:` builtin (e.g. `node:crypto`) pulled into a CLIENT chunk builds fine (Bun substitutes a
+  // browser polyfill) but breaks/leaks at runtime. Fail with the chain (entry → … → builtin), through the
+  // SHARED formatter so the Vite pipeline's identical guard reads byte-for-byte the same.
+  const nodeBuiltinLeak = formatNodeBuiltinLeak(detectNodeBuiltinsInClient(clientGraph))
+  if (nodeBuiltinLeak !== undefined) throw new Error(nodeBuiltinLeak)
+
+  // §3.3/§5.1: a module that opted into the `server-only` marker yet reached a CLIENT chunk - catches
+  // pure-server logic (a secret, a server-only API call) carrying no `node:` import and not named
+  // `*.server`, so neither other guard fires. Same shared formatter as above.
+  const serverOnlyLeak = formatServerOnlyLeak(detectServerOnlyInClient(clientGraph))
+  if (serverOnlyLeak !== undefined) throw new Error(serverOnlyLeak)
 
   // 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.
+  // rewrite the references - otherwise the lazy import 404s and the route silently never hydrates.
   const renamed = sanitizeOutputNames(result.outputs)
   const toUrl = (path: string): string =>
     `${publicPath}${renamed.get(basename(path)) ?? basename(path)}`
@@ -839,7 +1059,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   }
   const fileToChunk = new Map<string, string>()
   routeFiles.forEach((file, i) => {
-    const out = entryPoints[i + 1] // in range — length checked above
+    const out = entryPoints[i + 1] // in range - length checked above
     if (out !== undefined) fileToChunk.set(file, toUrl(out.path))
   })
   const chunksFor = (chainFiles: readonly string[]): string[] =>
@@ -853,9 +1073,9 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   }
   if (routeManifest.notFound) routes._404 = chunksFor([routeManifest.notFound.file])
 
-  // CSS — aggregate: an `import "./x.css"` anywhere → a content-hashed `.css` asset (Bun strips the
+  // CSS - aggregate: an `import "./x.css"` anywhere → a content-hashed `.css` asset (Bun strips the
   // import from the JS). The bootstrap lazily imports every route, so its **aggregate** stylesheet is
-  // the whole app's CSS — the always-safe fallback `createWebApp` links when a route has no per-route
+  // the whole app's CSS - the always-safe fallback `createWebApp` links when a route has no per-route
   // entry below. Fallback to all CSS assets if Bun emitted no distinct aggregate.
   const bootstrapName = entryName(entryFile) // `_nifra-entry`
   const cssNameOf = (path: string): string => {
@@ -869,12 +1089,12 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   const css: readonly string[] =
     aggregate.length > 0 ? aggregate : cssAssets.map((o) => toUrl(o.path))
 
-  // CSS — per-route: each route/layout file is its own entrypoint, so the build metafile records its
-  // `cssBundle` — exactly the CSS that file's subtree uses (shared-component CSS is inlined into each
+  // CSS - per-route: each route/layout file is its own entrypoint, so the build metafile records its
+  // `cssBundle` - exactly the CSS that file's subtree uses (shared-component CSS is inlined into each
   // consumer; verified). Keyed by the metafile's unique source `entryPoint`, so it survives
   // same-basename collisions (`index.tsx` + `blog/index.tsx`) that a filename match can't. A page then
   // links only its layout chain + own CSS (deduped); an empty array means the page needs no CSS at all.
-  // Absent (→ aggregate fallback) only if Bun emits no metafile/cssBundle — never silently incomplete.
+  // Absent (→ aggregate fallback) only if Bun emits no metafile/cssBundle - never silently incomplete.
   const cwd = process.cwd()
   const cssByEntry = new Map<string, string>()
   for (const out of Object.values(clientMeta?.outputs ?? {})) {
@@ -899,10 +1119,17 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
     if (routeManifest.notFound) routeStyles._404 = stylesFor([routeManifest.notFound.file])
   }
 
+  // Copy `public/` into the output next to the hashed assets. A missing directory is normal (most
+  // apps have none) and must not fail the build.
+  const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
+  const publicFiles =
+    publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
+
   const manifest: BuildManifest = {
     entry: toUrl(bootstrap.path),
     assets: result.outputs.map((o) => toUrl(o.path)),
     routes,
+    ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
   }
@@ -913,30 +1140,30 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
 export interface BuildServerOptions {
   /** The `routes/` directory to discover (absolute path). */
   readonly routesDir: string
-  /** The worker entry module (absolute path) — your `worker.ts`. It imports `{ manifest, clientEntry }`
+  /** The worker entry module (absolute path) - your `worker.ts`. It imports `{ manifest, clientEntry }`
    * from the generated `./server-manifest`, builds `createWebApp`, and `export default toFetchHandler(app)`. */
   readonly serverEntry: string
   /** Output directory for the bundled worker (absolute path). */
   readonly outDir: string
-  /** The content-hashed client entry URL (from `buildClient`'s manifest) — **baked** into the generated
+  /** The content-hashed client entry URL (from `buildClient`'s manifest) - **baked** into the generated
    * server manifest, since a disk-less worker can't read `manifest.json` at runtime. */
   readonly clientEntry: string
-  /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) — baked into the generated
+  /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) - baked into the generated
    * manifest so the server entry hands them to `createWebApp` (→ `<link rel="stylesheet">`). Omit ⇒ no CSS
    * link (the built SSR page would otherwise render unstyled). */
   readonly styles?: readonly string[] | undefined
-  /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) — baked alongside `styles`. */
+  /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - baked alongside `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
   /** Route/layout file → import specifier in the generated manifest (default: a relative path from the
-   * manifest's location — written next to `serverEntry` — to `routesDir`). */
+   * manifest's location - written next to `serverEntry` - to `routesDir`). */
   readonly resolve?: (file: string) => string
   /** Filename for the generated server-manifest module, written next to `serverEntry` (default
    * `"server-manifest.ts"`); your `serverEntry` imports it as `./server-manifest`. */
   readonly manifestFile?: string
-  /** Adapter build plugins (e.g. `solidBunPlugin("ssr")` — Solid routes need their SSR transform at
+  /** Adapter build plugins (e.g. `solidBunPlugin("ssr")` - Solid routes need their SSR transform at
    * build time; React's JSX is Bun-native and needs none). */
   readonly plugins?: readonly BunPlugin[]
-  /** `Bun.build` resolution conditions (default `["workerd", "edge-light", "browser"]`) — selects each
+  /** `Bun.build` resolution conditions (default `["workerd", "edge-light", "browser"]`) - selects each
    * dependency's edge build. */
   readonly conditions?: readonly string[]
   /** Compile-time replacements (default `{ "process.env.NODE_ENV": '"production"' }` → production
@@ -944,7 +1171,7 @@ export interface BuildServerOptions {
   readonly define?: Readonly<Record<string, string>>
   /** Minify the output (default `true`). */
   readonly minify?: boolean
-  /** `Bun.build` target (default `"browser"` — the right shape for edge runtimes: Cloudflare Workers,
+  /** `Bun.build` target (default `"browser"` - the right shape for edge runtimes: Cloudflare Workers,
    * Vercel Edge, Deno, Deno Deploy). Use `"node"` for a `@nifrajs/node` server (so `node:*` built-ins
    * stay external), or `"bun"` for a Bun server. The default `conditions` + the edge resolve shims
    * only apply to the `"browser"` target; `"node"`/`"bun"` resolve their own renderer builds via the
@@ -953,16 +1180,16 @@ export interface BuildServerOptions {
   /** **Lazy/code-split routes** (default `false`): emit `() => import(route)` loaders + bundle with
    * `splitting`, so each route is its own chunk loaded on first request (smaller cold-start parse)
    * instead of all parsed at boot. The output becomes the worker entry **+ chunk files** in `outDir`
-   * — on Cloudflare, ship them with wrangler's `no_bundle` + `find_additional_modules` + an ESModule
+   * - on Cloudflare, ship them with wrangler's `no_bundle` + `find_additional_modules` + an ESModule
    * `rule` (Node/Deno import the chunks natively). Eager (one self-contained file) stays the default. */
   readonly lazy?: boolean
 }
 
-/** The built worker bundle — point your `wrangler.toml`'s `main` at `worker`. */
+/** The built worker bundle - point your `wrangler.toml`'s `main` at `worker`. */
 export interface ServerBuild {
   /** Path to the bundled, self-contained worker entry. */
   readonly worker: string
-  /** Paths of every emitted output (entry + any code-split chunks) — what to ship to the platform. */
+  /** Paths of every emitted output (entry + any code-split chunks) - what to ship to the platform. */
   readonly outputs: readonly string[]
 }
 
@@ -971,7 +1198,7 @@ export interface ServerBuild {
  * on workerd, and `Bun.build` always applies the `bun` condition (it wins over `workerd`/`edge-light`),
  * so conditions alone can't select the edge build. This shim pins `react-dom/server` to its edge build
  * (`server.edge.js`, which exports `renderToReadableStream`). A no-op when nothing imports react-dom
- * (e.g. a Solid worker) — the resolver only runs on a match.
+ * (e.g. a Solid worker) - the resolver only runs on a match.
  */
 const reactDomEdgePlugin = (from: string): BunPlugin => ({
   name: "nifra-react-dom-edge",
@@ -984,11 +1211,11 @@ const reactDomEdgePlugin = (from: string): BunPlugin => ({
 
 /**
  * Dedupe React to a single copy. A `file:`-linked package can ship its OWN `react` under its own
- * node_modules, so the bundle ends up with two React cores — each with its own hook dispatcher — and SSR
+ * node_modules, so the bundle ends up with two React cores - each with its own hook dispatcher - and SSR
  * throws the cryptic `null is not an object (evaluating '…H.useState')` (the second renderer's dispatcher
  * is null). This was the #1 time-sink in app builds. Pinning `react` + its JSX runtimes to ONE resolved
  * copy (the app's, from `from`) guarantees a single dispatcher; `react-dom`, which imports `react`, then
- * shares it — so the class can't occur rather than needing a named error. No-op when React isn't used
+ * shares it - so the class can't occur rather than needing a named error. No-op when React isn't used
  * (an unresolvable spec is skipped; the resolver only fires on an exact match). React core is
  * condition-agnostic, so pinning it doesn't disturb the edge/browser/server conditions that select
  * react-dom's build.
@@ -1002,7 +1229,7 @@ export const reactDedupePlugin = (from: string): BunPlugin => ({
       try {
         resolved = Bun.resolveSync(spec, from)
       } catch {
-        continue // React (or this subpath) isn't resolvable here — nothing to dedupe
+        continue // React (or this subpath) isn't resolvable here - nothing to dedupe
       }
       const escaped = spec.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")
       build.onResolve({ filter: new RegExp(`^${escaped}$`) }, () => ({ path: resolved }))
@@ -1011,14 +1238,14 @@ export const reactDedupePlugin = (from: string): BunPlugin => ({
 })
 
 /**
- * Dedupe Preact to a single copy — the Preact analogue of `reactDedupePlugin`, closing the same class of
+ * Dedupe Preact to a single copy - the Preact analogue of `reactDedupePlugin`, closing the same class of
  * bug for the Preact framework (which had NO build-time dedup before). A `file:`-linked package can ship
  * its OWN `preact`, so the bundle ends up with two Preact cores; since `preact-render-to-string` mutates
  * `preact`'s shared `options` global and `preact/hooks` writes the SAME global, two copies → two `options`
  * → SSR throws `undefined is not an object (… __H)` (the vnode's hook state was set up on the other copy).
  * Pinning `preact` + its hooks/compat/jsx subpaths to ONE resolved copy (the app's, from `from`) makes the
  * renderer and the components share one core. No-op when Preact isn't used (an unresolvable spec is
- * skipped). Preact core is condition-agnostic, so pinning it doesn't disturb any condition selection — and
+ * skipped). Preact core is condition-agnostic, so pinning it doesn't disturb any condition selection - and
  * unlike react-dom there is no edge-vs-server build to preserve, so pinning the subpaths is safe.
  */
 const PREACT_DEDUPE_SPECS = [
@@ -1036,7 +1263,7 @@ export const preactDedupePlugin = (from: string): BunPlugin => ({
       try {
         resolved = Bun.resolveSync(spec, from)
       } catch {
-        continue // Preact (or this subpath) isn't resolvable here — nothing to dedupe
+        continue // Preact (or this subpath) isn't resolvable here - nothing to dedupe
       }
       const escaped = spec.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")
       build.onResolve({ filter: new RegExp(`^${escaped}$`) }, () => ({ path: resolved }))
@@ -1045,10 +1272,10 @@ export const preactDedupePlugin = (from: string): BunPlugin => ({
 })
 
 /**
- * Dedupe Svelte to a single copy — the Svelte analogue of `reactDedupePlugin`/`preactDedupePlugin`, closing
+ * Dedupe Svelte to a single copy - the Svelte analogue of `reactDedupePlugin`/`preactDedupePlugin`, closing
  * the same class of bug for Svelte (which had NO build-time dedup before). A workspace- or file-linked
  * `@nifrajs/web-svelte` can resolve its OWN `svelte` (e.g. a sibling repo's install store) while the app's
- * components resolve another — SAME version, two physical copies. Svelte 5's client runtime
+ * components resolve another - SAME version, two physical copies. Svelte 5's client runtime
  * (`svelte/internal/client`) holds module-level component-context state, so two copies means the compiled
  * components register on one runtime while `hydrate` runs on the other → hydration throws
  * `Cannot read properties of undefined (reading 'call')` and the server-rendered markup is wiped.
@@ -1066,7 +1293,7 @@ export const svelteDedupePlugin = (from: string): BunPlugin => ({
       try {
         return { path: Bun.resolveSync(args.path, from) }
       } catch {
-        return undefined // not resolvable from the app root — leave Bun's default resolution
+        return undefined // not resolvable from the app root - leave Bun's default resolution
       }
     })
   },
@@ -1074,19 +1301,43 @@ export const svelteDedupePlugin = (from: string): BunPlugin => ({
 
 /**
  * Remix-style `.server` convention for the CLIENT build. A module named `*.server.ts(x)` (`db.server.ts`,
- * `auth.server.ts`, …) is server-only — empty it in the browser bundle so its (possibly `node:` / native /
+ * `auth.server.ts`, …) is server-only - empty it in the browser bundle so its (possibly `node:` / native /
  * Capacitor) import subtree never reaches the client. The body is CJS-with-a-Proxy so any named OR default
  * import resolves to `undefined` rather than a "missing export" bundle error (verified), and the real
  * import subtree is gone. The complement to the node-builtin guard: when a server-only import is co-located
  * in a route file (so it can't be tree-shaken out and the guard fails loud), moving it into a `*.server`
- * module is the fix. CLIENT-only — buildServer keeps the real module, which runs server-side.
+ * module is the fix. CLIENT-only - buildServer keeps the real module, which runs server-side.
  */
-const SERVER_ONLY_MODULE = /\.server(\.[cm]?[jt]sx?)?$/
 export const serverOnlyEmptyPlugin = (): BunPlugin => ({
   name: "nifra-server-only-empty",
   setup(build) {
     build.onLoad({ filter: SERVER_ONLY_MODULE }, () => ({
-      contents: "module.exports = new Proxy({}, { get: () => undefined })",
+      contents: SERVER_ONLY_REPLACEMENT,
+      loader: "js",
+    }))
+  },
+})
+
+/**
+ * Server functions in the CLIENT build: replace each `*.fn.ts` module with stubs that call the routes
+ * the server mounted, so the function bodies - and everything they import - never reach a browser.
+ *
+ * The sibling of {@link serverOnlyEmptyPlugin}, and a deliberate contrast: a `*.server` module is
+ * EMPTIED because nothing may call it from the client, while a `*.fn` module is REPLACED because the
+ * client is supposed to call it, just over HTTP. The generation itself is in
+ * `internal/server-boundary.ts` so the Vite pipeline emits identical stubs from the same code; two
+ * hand-written copies would be a client that works in dev and 404s in production.
+ *
+ * CLIENT-only. The server build keeps the real module, which is what `serverFunctions()` mounts.
+ */
+export const serverFnStubPlugin = (): BunPlugin => ({
+  name: "nifra-server-fn-stub",
+  setup(build) {
+    build.onLoad({ filter: SERVER_FN_MODULE }, async (args) => ({
+      contents: generateServerFnStub(
+        await Bun.file(args.path).text(),
+        serverFnNamespace(args.path),
+      ),
       loader: "js",
     }))
   },
@@ -1117,7 +1368,7 @@ const solidWebServerPlugin = (from: string): BunPlugin => ({
  * (`generateServerManifest`, written next to `serverEntry`), then bundles `serverEntry` with
  * `Bun.build` using **edge conditions** + the adapter's SSR plugins. The output imports no `node:fs`
  * and does no dynamic-path import, so it runs on workerd: point `wrangler.toml`'s `main` at it and
- * serve the client assets via Workers Assets. Throws (with the bundler logs) on failure — never
+ * serve the client assets via Workers Assets. Throws (with the bundler logs) on failure - never
  * silently ships a broken worker.
  */
 export async function buildServer(options: BuildServerOptions): Promise<ServerBuild> {
@@ -1134,7 +1385,7 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
   // Edge (browser) target: Bun's `bun` condition contaminates react-dom's server build + the `worker`
   // condition segfaults Bun.build on solid, so force the edge/server builds via shims. The `node`/`bun`
   // targets resolve those correctly via their own condition, so the shims (and edge conditions) don't
-  // apply — defaults become `[target]` (e.g. react-dom → server.node.js under `node`).
+  // apply - defaults become `[target]` (e.g. react-dom → server.node.js under `node`).
   const edge = target === "browser"
   const conditions = options.conditions ?? (edge ? ["workerd", "edge-light", "browser"] : [target])
   const manifest = discoverRoutes(routesDir)
@@ -1153,11 +1404,12 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       // Tag every BUNDLED SSR output so @nifrajs/web-react's react-dom adapter takes the static
       // (bundled, deduped) react-dom instead of re-rooting react-dom/server to a DISK copy at runtime.
       // A `target:"bun"` bundle still has `Bun.resolveSync` under the Bun runtime, so without this tag the
-      // adapter re-imports a SECOND react-dom from node_modules — a second React core whose hook dispatcher
+      // adapter re-imports a SECOND react-dom from node_modules - a second React core whose hook dispatcher
       // is null for the bundled components → SSR throws `…H.useRef of null`. Always set (a structural fact
       // of bundling, layered after any caller `define` so it can't be overridden). Unbundled Bun runtimes
-      // (nifra dev/start, nifra_render) never define it, so they still re-root — the dev dual-install fix.
+      // (nifra dev/start, nifra_render) never define it, so they still re-root - the dev dual-install fix.
       "process.env.NIFRA_SSR_BUNDLED": '"1"',
+      "globalThis.__NIFRA_EDGE_RUNTIME__": edge ? "true" : "false",
     },
     minify: options.minify ?? true,
     // Lazy → one chunk per route (loaded on first request); eager → a single self-contained file.
@@ -1182,12 +1434,12 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
 }
 
 // ===================================================================================================
-// `nifra build --target` — package the engine above into one command that emits a full deploy dir.
+// `nifra build --target` - package the engine above into one command that emits a full deploy dir.
 //
 // An app already declares everything the build needs through nifra's conventions: `adapter` +
 // `clientModule` (nifra.config.ts / framework.ts), an optional `backend` (backend.ts), and `routes/`.
 // The ONLY thing apps used to hand-write per target was the server entry (`_worker.ts`, `server-bun.ts`,
-// …) — so we GENERATE it here (per target) instead of asking each app to ship five near-identical files.
+// …) - so we GENERATE it here (per target) instead of asking each app to ship five near-identical files.
 // ===================================================================================================
 
 /** A deploy target `nifra build --target <t>` can emit. `static` is pure SSG (no server). */
@@ -1208,7 +1460,7 @@ export function isBuildTarget(value: string): value is BuildTarget {
  *   - `deno`: same fetch-handler default, plus `Deno.serve` self-host when run directly.
  *   - `bun` / `node`: a self-hosting server that ALSO serves the client bundle from disk (those
  *     runtimes have a filesystem; the static `/assets/*` sit next to the entry).
- * `adapterImport`/`backendImport` are the specifiers the entry uses (relative to where it's written) —
+ * `adapterImport`/`backendImport` are the specifiers the entry uses (relative to where it's written) -
  * `buildServer` writes the entry next to `serverEntry`, so they're resolved from there. Pure (string in,
  * string out) so the generation is unit-testable without a real build.
  */
@@ -1220,8 +1472,10 @@ export function generateServerEntry(options: {
   readonly backendImport?: string
   /** Document `<title>` passed to `createWebApp`. */
   readonly title?: string
+  /** Encoded root-relative public file paths copied into the deploy directory. */
+  readonly publicFiles?: readonly string[]
 }): string {
-  const { target, adapterImport, backendImport, title = "nifra" } = options
+  const { target, adapterImport, backendImport, title = "nifra", publicFiles = [] } = options
   if (target === "static") {
     throw new Error("[nifra/web] generateServerEntry: `static` has no server entry (SSG only)")
   }
@@ -1251,14 +1505,33 @@ export function generateServerEntry(options: {
   )
 
   if (target === "cf-pages") {
-    // Cloudflare Pages advanced mode: `_routes.json` serves /assets/* from the CDN; everything else
-    // falls through to this fetch handler (SSR). The default export is the handler object.
-    lines.push("export default toFetchHandler(app)")
+    // Cloudflare Pages advanced mode: `_routes.json` keeps static paths off the worker entirely, and
+    // everything else falls through to this handler (SSR).
+    //
+    // That exclude list cannot always name every public file - Cloudflare caps `_routes.json` at 100
+    // rules - so a static request CAN arrive here. Serve it from the ASSETS binding instead of letting
+    // the router 404 it, which makes correctness independent of how much of the list fit: the exclude
+    // list decides only how many static requests skip the worker, never which files exist.
+    lines.push(
+      `const PUBLIC_FILES = new Set(${JSON.stringify(publicFiles)})`,
+      "const handler = toFetchHandler(app)",
+      "type Assets = { readonly ASSETS?: { fetch(request: Request): Promise<Response> } }",
+      "export default {",
+      "  fetch(request: Request, env: Assets, ctx: ExecutionContext) {",
+      "    const { pathname } = new URL(request.url)",
+      "    // Only the build's own outputs: the hashed bundle prefix and the files it copied.",
+      '    if (env?.ASSETS !== undefined && (pathname.startsWith("/assets/") || PUBLIC_FILES.has(pathname))) {',
+      "      return env.ASSETS.fetch(request)",
+      "    }",
+      "    return handler.fetch(request, env as never, ctx)",
+      "  },",
+      "}",
+    )
     return `${lines.join("\n")}\n`
   }
   if (target === "vercel") {
     lines.push(
-      "// Vercel Edge Function — Vercel serves /assets/* from its CDN; this only SSRs page routes.",
+      "// Vercel Edge Function - Vercel serves /assets/* from its CDN; this only SSRs page routes.",
       'export const config = { runtime: "edge" }',
       "export default (req: Request): Response | Promise<Response> => app.fetch(req)",
     )
@@ -1267,8 +1540,20 @@ export function generateServerEntry(options: {
 
   // bun / node / deno self-host AND serve the client bundle from disk (it sits next to this entry).
   lines.push(
-    "// The client bundle lives next to this entry; serve /assets/* from disk, SSR everything else.",
-    'const ASSETS = new URL("./assets/", import.meta.url)',
+    "// The client bundle and public files live next to this entry; serve only manifest-approved paths.",
+    'const STATIC_ROOT = new URL("./", import.meta.url)',
+    `const PUBLIC_FILES = new Set(${JSON.stringify(publicFiles)})`,
+    "const staticPath = (pathname: string): string | undefined => {",
+    "  if (PUBLIC_FILES.has(pathname)) return '.' + pathname",
+    '  if (!pathname.startsWith("/assets/")) return undefined',
+    '  const segments = pathname.slice(1).split("/")',
+    "  // `.` and `..` match the character class, and the path is joined onto a base URL that resolves",
+    "  // dot segments - so they are rejected explicitly rather than relying on the request URL having",
+    "  // been normalized upstream.",
+    "  const safe = (segment: string): boolean =>",
+    '    segment !== "." && segment !== ".." && /^[A-Za-z0-9._-]+$/.test(segment)',
+    "  return segments.every(safe) ? '.' + pathname : undefined",
+    "}",
     'const TYPES = { js: "text/javascript", css: "text/css", map: "application/json" }',
   )
   if (target === "bun") {
@@ -1277,19 +1562,18 @@ export function generateServerEntry(options: {
       "  port: Number(Bun.env.PORT ?? 3000),",
       "  async fetch(req) {",
       "    const { pathname } = new URL(req.url)",
-      '    if (pathname.startsWith("/assets/")) {',
-      '      const name = pathname.slice("/assets/".length)',
-      '      if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })',
-      "      const file = Bun.file(new URL(name, ASSETS))",
+      "    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 })',
-      '      const ext = name.slice(name.lastIndexOf(".") + 1)',
+      '      const ext = pathname.slice(pathname.lastIndexOf(".") + 1)',
       '      return new Response(file, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })',
       "    }",
       "    return app.fetch(req)",
       "  },",
       "})",
       // The `${...}` here is literal OUTPUT (a template in the GENERATED file), not a template in this
-      // source — split so biome's noTemplateCurlyInString doesn't flag it; the emitted line is unchanged.
+      // source - split so biome's noTemplateCurlyInString doesn't flag it; the emitted line is unchanged.
       `console.log(\`nifra (Bun) → http://localhost:$${"{server.port}"}\`)`,
     )
     return `${lines.join("\n")}\n`
@@ -1301,12 +1585,11 @@ export function generateServerEntry(options: {
       "  {",
       "    async fetch(req) {",
       "      const { pathname } = new URL(req.url)",
-      '      if (pathname.startsWith("/assets/")) {',
-      '        const name = pathname.slice("/assets/".length)',
-      '        if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })',
+      "      const filePath = staticPath(pathname)",
+      "      if (filePath !== undefined) {",
       "        try {",
-      "          const body = await readFile(new URL(name, ASSETS))",
-      '          const ext = name.slice(name.lastIndexOf(".") + 1)',
+      "          const body = await readFile(new URL(filePath, STATIC_ROOT))",
+      '          const ext = pathname.slice(pathname.lastIndexOf(".") + 1)',
       '          return new Response(body, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })',
       "        } catch {",
       '          return new Response("not found", { status: 404 })',
@@ -1323,16 +1606,15 @@ export function generateServerEntry(options: {
   // deno
   lines.push(
     "const handler = toFetchHandler(app)",
-    "// @ts-ignore — Deno global is present on the Deno runtime this output targets.",
+    "// @ts-ignore - Deno global is present on the Deno runtime this output targets.",
     'Deno.serve({ port: Number(Deno.env.get("PORT") ?? "3000") }, async (req) => {',
     "  const { pathname } = new URL(req.url)",
-    '  if (pathname.startsWith("/assets/")) {',
-    '    const name = pathname.slice("/assets/".length)',
-    '    if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })',
+    "  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(name, ASSETS))",
-    '      const ext = name.slice(name.lastIndexOf(".") + 1)',
+    "      // @ts-ignore - Deno.readFile is present on the Deno runtime.",
+    "      const body = await Deno.readFile(new URL(filePath, STATIC_ROOT))",
+    '      const ext = pathname.slice(pathname.lastIndexOf(".") + 1)',
     '      return new Response(body, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })',
     "    } catch {",
     '      return new Response("not found", { status: 404 })',
@@ -1383,7 +1665,7 @@ export interface BuildTargetOptions {
   readonly adapterImport: string
   /** Import specifier (resolvable from `workDir`) of the module exporting `backend`, or `undefined`. */
   readonly backendImport?: string
-  /** Factory that builds the app for `static` prerendering, GIVEN the client build's manifest — so the
+  /** Factory that builds the app for `static` prerendering, GIVEN the client build's manifest - so the
    * 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
@@ -1397,16 +1679,20 @@ export interface BuildTargetOptions {
   readonly conditions?: readonly string[]
   /** Compile-time `define` replacements layered onto both builds. */
   readonly define?: Readonly<Record<string, string>>
+  /** Project-root static directory copied to deploy root. `false` disables it. */
+  readonly publicDir?: string | false
+  /** Prefix of environment variables allowed into the client bundle (default `"PUBLIC_"`). */
+  readonly publicEnvPrefix?: string
   /** Document `<title>` for the generated server entry. */
   readonly title?: string
 }
 
-/** Minimal app surface `buildTarget`'s static path needs — a fetch handler (a built `createWebApp`). */
+/** Minimal app surface `buildTarget`'s static path needs - a fetch handler (a built `createWebApp`). */
 export interface PrerenderAppLike {
   fetch(req: Request): Response | Promise<Response>
 }
 
-/** The result of a target build — the deploy dir + the client manifest + an optional size report. */
+/** The result of a target build - the deploy dir + the client manifest + an optional size report. */
 export interface BuildTargetResult {
   /** The deploy target that was built. */
   readonly target: BuildTarget
@@ -1427,7 +1713,7 @@ export interface BuildTargetResult {
  *   - `static`: prerenders opted-in routes (`prerenderRoutes`) to `<outDir>/<path>/index.html` (+
  *     `_data.json`); needs `prerenderApp`. No server.
  *   - `cf-pages`: a `_worker.js` (edge bundle) + a `_routes.json` excluding /assets/* from the worker.
- *   - `vercel`: a `.vercel/output`-shaped function isn't emitted here — `vercel` emits the bundled edge
+ *   - `vercel`: a `.vercel/output`-shaped function isn't emitted here - `vercel` emits the bundled edge
  *     entry as `<outDir>/index.js` (the CLI's docs point at `vercel`'s Build Output wrapper). [see note]
  *   - `deno`/`node`/`bun`: the self-hosting server bundle (`server.js`) next to the assets.
  * The server entry is GENERATED (`generateServerEntry`) and bundled (`buildServer`); the app supplies
@@ -1436,9 +1722,84 @@ export interface BuildTargetResult {
  * Note: the heavier platform wrappers (`.vercel/output` v3 layout, wrangler ISR `find_additional_modules`)
  * remain app-owned scripts; this command targets the common single-bundle deploys. See the CLI docs.
  */
+/**
+ * A build-tool STRATEGY for {@link buildTargetWith} - the two bundling steps, and nothing else. Everything
+ * around them (server-entry codegen, deploy assembly, prerender, size report) is bundler-agnostic and
+ * lives in `buildTargetWith`, so a second bundler (Vite) is this interface, not a second orchestrator.
+ *
+ * Plugin lists are `readonly unknown[]` because a Bun plugin and a Vite plugin are different types; each
+ * strategy casts to its own. `buildTargetWith` only forwards them.
+ */
+export interface Bundler {
+  /** Build the client bundle → the shared {@link BuildManifest}. */
+  buildClient(input: {
+    readonly routesDir: string
+    readonly outDir: string
+    readonly clientModule: string
+    readonly plugins?: readonly unknown[]
+    readonly conditions?: readonly string[]
+    readonly define?: Readonly<Record<string, string>>
+    readonly publicDir?: string | false
+    readonly publicEnvPrefix?: string
+    /** Project root (Vite needs it; the Bun strategy ignores it). */
+    readonly root?: string
+  }): Promise<BuildManifest>
+  /** Build the server worker → the shared {@link ServerBuild}. */
+  buildServer(input: {
+    readonly routesDir: string
+    readonly serverEntry: string
+    readonly outDir: string
+    readonly clientEntry: string
+    readonly target: "browser" | "node" | "bun"
+    readonly plugins?: readonly unknown[]
+    readonly define?: Readonly<Record<string, string>>
+    readonly root?: string
+  }): Promise<ServerBuild>
+}
+
+/** The default (Bun) strategy - `buildClient`/`buildServer` from this module. */
+export const bunBundler: Bundler = {
+  buildClient: (input) =>
+    buildClient({
+      routesDir: input.routesDir,
+      outDir: input.outDir,
+      clientModule: input.clientModule,
+      ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
+      ...(input.conditions ? { conditions: input.conditions } : {}),
+      ...(input.define ? { define: input.define } : {}),
+      ...(input.publicDir !== undefined ? { publicDir: input.publicDir } : {}),
+      ...(input.publicEnvPrefix !== undefined ? { publicEnvPrefix: input.publicEnvPrefix } : {}),
+    }),
+  buildServer: (input) =>
+    buildServer({
+      routesDir: input.routesDir,
+      serverEntry: input.serverEntry,
+      outDir: input.outDir,
+      clientEntry: input.clientEntry,
+      target: input.target,
+      ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
+      ...(input.define ? { define: input.define } : {}),
+    }),
+}
+
+/** Build a full deploy dir for `target` using the default Bun bundler. See {@link buildTargetWith}. */
 export async function buildTarget(
   target: BuildTarget,
   options: BuildTargetOptions,
+): Promise<BuildTargetResult> {
+  return buildTargetWith(target, options, bunBundler)
+}
+
+/**
+ * The bundler-agnostic deploy orchestrator: everything `buildTarget` does EXCEPT the two bundling steps,
+ * which come from `bundler`. `buildTarget` passes {@link bunBundler}; `buildTargetVite`
+ * (`@nifrajs/web/build-vite`) passes the Vite strategy. One orchestrator, so the deploy-dir shape,
+ * server-entry codegen, prerender and size report are identical across pipelines.
+ */
+export async function buildTargetWith(
+  target: BuildTarget,
+  options: BuildTargetOptions,
+  bundler: Bundler,
 ): Promise<BuildTargetResult> {
   const { routesDir, outDir, workDir } = options
   const { rmSync } = await import("node:fs")
@@ -1449,14 +1810,27 @@ export async function buildTarget(
   mkdirSync(workDir, { recursive: true })
 
   // (1) Client bundle → <outDir>/assets/* (every target ships the same hashed client bundle).
-  const client = await buildClient({
+  let client = await bundler.buildClient({
     routesDir,
     outDir: assetsDir,
     clientModule: options.clientModule,
     ...(options.clientPlugins ? { plugins: options.clientPlugins } : {}),
     ...(options.conditions ? { conditions: options.conditions } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
+    publicDir: false,
+    ...(options.publicEnvPrefix !== undefined ? { publicEnvPrefix: options.publicEnvPrefix } : {}),
+    root: resolvePath(dirname(routesDir)),
   })
+  const publicDir =
+    options.publicDir === false
+      ? undefined
+      : resolvePath(options.publicDir ?? join(dirname(routesDir), "public"))
+  const publicFiles =
+    publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
+  if (publicFiles.length > 0) {
+    client = { ...client, publicFiles }
+    writeFileSync(`${assetsDir}/manifest.json`, JSON.stringify(client, null, 2))
+  }
 
   if (target === "static") {
     if (options.prerenderApp === undefined) {
@@ -1476,9 +1850,9 @@ export async function buildTarget(
     })
     if (result.prerendered.length === 0) {
       // A static build that renders nothing is almost always a misconfig (no `prerender = true` / no
-      // getStaticPaths) — fail loudly rather than ship an empty dir the dev thinks is their site.
+      // getStaticPaths) - fail loudly rather than ship an empty dir the dev thinks is their site.
       throw new Error(
-        "[nifra/web] buildTarget(static): no routes were prerendered — opt routes in with " +
+        "[nifra/web] buildTarget(static): no routes were prerendered - opt routes in with " +
           "`export const prerender = true` (static) or `getStaticPaths` (dynamic).",
       )
     }
@@ -1506,10 +1880,11 @@ export async function buildTarget(
       adapterImport: options.adapterImport,
       ...(options.backendImport !== undefined ? { backendImport: options.backendImport } : {}),
       ...(options.title !== undefined ? { title: options.title } : {}),
+      ...(publicFiles.length > 0 ? { publicFiles } : {}),
     }),
   )
   const serverTarget = SERVER_BUILD_TARGET[target]
-  const { worker } = await buildServer({
+  const { worker } = await bundler.buildServer({
     routesDir,
     serverEntry: serverEntryPath,
     outDir: `${workDir}/server`,
@@ -1517,6 +1892,7 @@ export async function buildTarget(
     target: serverTarget,
     ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
+    root: resolvePath(dirname(routesDir)),
   })
 
   // (3) Assemble the deploy dir for the target.
@@ -1524,10 +1900,25 @@ export async function buildTarget(
   let run: string
   if (target === "cf-pages") {
     cpSync(worker, `${outDir}/_worker.js`)
+    // The app's real patterns, so a directory is only collapsed into a glob once the route table
+    // proves nothing can be served beneath it.
+    const rules = cloudflareRouteRules(
+      publicFiles,
+      discoverRoutes(routesDir).routes.map((route) => route.pattern),
+    )
     writeFileSync(
       `${outDir}/_routes.json`,
-      `${JSON.stringify({ version: 1, include: ["/*"], exclude: ["/assets/*"] }, null, 2)}\n`,
+      `${JSON.stringify({ version: 1, include: rules.include, exclude: rules.exclude }, null, 2)}\n`,
     )
+    // Never cap silently: an omitted file still serves (the worker's ASSETS fallback), but it costs a
+    // worker invocation, and that trade should be visible rather than inferred from a latency graph.
+    if (rules.omitted.length > 0) {
+      console.log(
+        `[nifra/web] _routes.json holds ${rules.exclude.length} of ${publicFiles.length + 1} static rules ` +
+          `(Cloudflare allows ${CF_MAX_ROUTE_RULES}). The other ${rules.omitted.length} file(s) are served by the ` +
+          "worker via ASSETS instead of the CDN directly - correct, just one invocation each.",
+      )
+    }
     run = `Cloudflare Pages → ${outDir} (deploy: wrangler pages deploy ${basename(outDir)})`
   } else if (target === "vercel") {
     cpSync(worker, `${outDir}/index.js`)