@nifrajs/web 2.1.0 → 2.3.0

package/dist/build.js

@@ -1,16 +1,20 @@
 /**
- * `@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 { 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 { Glob } from "bun";
 import { sanitizeOutputNames } from "./chunk-names.js";
 import { discoverRoutes } from "./fs.js";
 import { generateClientEntry, generateServerManifest } from "./index.js";
+import { generateServerFnStub, SERVER_FN_MODULE, SERVER_ONLY_MODULE, SERVER_ONLY_REPLACEMENT, serverFnNamespace, } from "./internal/server-boundary.js";
 // `buildTarget(static)` drives the SSG prerender engine directly (it's also re-exported below).
+import { fromBunMetafile } from "./module-graph.js";
 import { prerenderRoutes } from "./prerender.js";
 // Build-time SSG: prerender opted-in static + dynamic routes to `index.html` (+ static `_data.json`),
 // run after `buildClient`.
@@ -34,6 +38,156 @@ export function publicEnvDefines(prefix, env) {
     }
     return defines;
 }
+/**
+ * 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) {
+    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;
+function firstSegmentOf(pattern) {
+    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, routePatterns) {
+    const reserved = new Set();
+    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();
+    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, 
+/**
+ * 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) {
+    const include = ["/*"];
+    const exclude = ["/assets/*"];
+    const omitted = [];
+    // 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() : collapsibleDirs(publicFiles, routePatterns);
+    const emitted = new Set();
+    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, to) {
+    const source = resolvePath(from);
+    const sourceReal = await realpath(source);
+    const copied = [];
+    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();
+}
 /** The `node:` specifier of an import edge, or undefined if it isn't a Node built-in. Reads the
  * `original` (as-written) specifier first, falling back to the resolved `path` (an `external` node:
  * import keeps `node:` in its path). */
@@ -48,10 +202,10 @@ const nodeBuiltinOf = (im) => {
  * 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, entryInputs, builtin) {
     // Each queue item carries the resolved-path node + the display chain to reach it (entry + the
@@ -72,7 +226,7 @@ function shortestBuiltinChain(inputs, entryInputs, 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:") ||
                     inputs[target] === undefined ||
@@ -81,45 +235,45 @@ function shortestBuiltinChain(inputs, entryInputs, builtin) {
                 }
                 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) {
-    const inputs = meta?.inputs ?? {};
-    // (1) The builtins a user (non-polyfill) module imports directly — the ones the author controls.
+export function detectNodeBuiltinsInClient(graph) {
+    const inputs = graph.modules;
+    // (1) The builtins a user (non-polyfill) module imports directly - the ones the author controls.
     const userImported = new Set();
     for (const [inputKey, input] of Object.entries(inputs)) {
         if (inputKey.startsWith("node:"))
-            continue; // a polyfill importing another builtin — not the cause
+            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 ?? {})
+        ...new Set(Object.values(graph.chunks)
             .map((o) => o.entryPoint)
             .filter((e) => e !== undefined && !e.startsWith("node:"))),
     ];
@@ -135,8 +289,8 @@ export function detectNodeBuiltinsInClient(meta) {
     };
     // (2) Locate which emitted chunk each user-imported builtin reached, via the per-output `inputs`.
     const findings = new Map();
-    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}`, {
@@ -154,8 +308,8 @@ export function detectNodeBuiltinsInClient(meta) {
 // 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.
 // ---------------------------------------------------------------------------------------------------
 /** The marker specifier an author imports to opt a module into the client-leak guard. Matched on the
@@ -164,7 +318,7 @@ export function detectNodeBuiltinsInClient(meta) {
 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) => {
     if (im.original === SERVER_ONLY_MARKER)
         return true;
@@ -179,14 +333,14 @@ const isServerOnlyMarkerImport = (im) => {
  * "<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, entryInputs, markedModule, resolveTarget) {
     // 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) => `${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(entryInputs);
@@ -198,7 +352,7 @@ function shortestServerOnlyChain(inputs, entryInputs, markedModule, resolveTarge
         const next = [];
         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);
@@ -247,14 +401,14 @@ function inputKeyResolver(inputs) {
  * 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) {
-    const inputs = meta?.inputs ?? {};
-    // (1) The modules that import the marker — the ones the author opted into the guard. The marker
+export function detectServerOnlyInClient(graph) {
+    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();
     for (const [inputKey, input] of Object.entries(inputs)) {
@@ -265,10 +419,10 @@ export function detectServerOnlyInClient(meta) {
     }
     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 ?? {})
+        ...new Set(Object.values(graph.chunks)
             .map((o) => o.entryPoint)
             .filter((e) => e !== undefined && !e.startsWith("node:"))),
     ];
@@ -284,8 +438,8 @@ export function detectServerOnlyInClient(meta) {
     };
     // (2) Locate which emitted chunk each marked module reached, via the per-output `inputs`.
     const findings = new Map();
-    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) });
@@ -299,8 +453,37 @@ export function detectServerOnlyInClient(meta) {
     });
 }
 /** 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) => /(^|\/)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) {
+    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) {
+    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) => path.slice(path.lastIndexOf("/") + 1);
 /** `[name]` Bun derives for an entrypoint: basename without extension (`users/[id].tsx` → `[id]`). */
 const entryName = (file) => {
@@ -310,7 +493,7 @@ const entryName = (file) => {
 };
 /**
  * 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) {
@@ -332,7 +515,7 @@ export function formatBytes(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 /**
- * 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) {
@@ -367,7 +550,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, routesPrefix = "./routes/") {
     const files = new Set();
@@ -443,8 +626,8 @@ export function resyncServerManifestSource(source, manifest, routesPrefix) {
 }
 /**
  * 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.
  */
@@ -468,20 +651,20 @@ export function formatManifestDrift(drift, manifestPath = "server-manifest.ts")
     if (isManifestInSync(drift))
         return undefined;
     const lines = [
-        `[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(", ")}`);
+        lines.push(`  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(", ")}`);
+        lines.push(`  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.");
     return lines.join("\n");
 }
 /**
  * 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) {
@@ -496,7 +679,7 @@ export async function buildClient(options) {
     // 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
@@ -507,7 +690,7 @@ export async function buildClient(options) {
     // A client bundle has no Node `process`; provide a minimal one so a stray bare `process` reference in
     // an app module doesn't crash hydration (`process.env.*` reads are handled at compile time by `define`).
     writeFileSync(entryFile, `globalThis.process ??= { env: {} };\n${generateClientEntry(routeManifest, { clientModule, resolve })}`);
-    // 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).
@@ -518,7 +701,7 @@ export async function buildClient(options) {
             ...(routeManifest.notFound ? [routeManifest.notFound.file] : []),
         ]),
     ].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
@@ -535,7 +718,7 @@ export async function buildClient(options) {
                 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: [
@@ -543,13 +726,14 @@ export async function buildClient(options) {
                     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": "({})",
@@ -568,39 +752,25 @@ export async function buildClient(options) {
     }
     // #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.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) => `${publicPath}${renamed.get(basename(path)) ?? basename(path)}`;
     // Entry-point outputs come back in entrypoint order: [bootstrap, ...routeFiles]. Map each route file
@@ -615,7 +785,7 @@ export async function buildClient(options) {
     }
     const fileToChunk = new Map();
     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));
     });
@@ -629,9 +799,9 @@ export async function buildClient(options) {
     }
     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) => {
@@ -643,12 +813,12 @@ export async function buildClient(options) {
         .filter((o) => cssNameOf(o.path) === bootstrapName)
         .map((o) => toUrl(o.path));
     const css = 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();
     for (const out of Object.values(clientMeta?.outputs ?? {})) {
@@ -673,10 +843,15 @@ export async function buildClient(options) {
         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 = {
         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 } : {}),
     };
@@ -688,7 +863,7 @@ export async function buildClient(options) {
  * 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) => ({
     name: "nifra-react-dom-edge",
@@ -700,11 +875,11 @@ const reactDomEdgePlugin = (from) => ({
 });
 /**
  * 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.
@@ -719,7 +894,7 @@ export const reactDedupePlugin = (from) => ({
                 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 }));
@@ -727,14 +902,14 @@ export const reactDedupePlugin = (from) => ({
     },
 });
 /**
- * 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 = [
@@ -753,7 +928,7 @@ export const preactDedupePlugin = (from) => ({
                 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 }));
@@ -761,10 +936,10 @@ export const preactDedupePlugin = (from) => ({
     },
 });
 /**
- * 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.
@@ -783,26 +958,46 @@ export const svelteDedupePlugin = (from) => ({
                 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
             }
         });
     },
 });
 /**
  * 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 = () => ({
     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 = () => ({
+    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",
         }));
     },
@@ -831,7 +1026,7 @@ const solidWebServerPlugin = (from) => ({
  * (`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) {
@@ -847,7 +1042,7 @@ export async function buildServer(options) {
     // 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);
@@ -862,11 +1057,12 @@ export async function buildServer(options) {
             // 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.
@@ -888,12 +1084,12 @@ export async function buildServer(options) {
     return { worker: entryOutput.path, outputs: result.outputs.map((o) => o.path) };
 }
 // ===================================================================================================
-// `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). */
 export const BUILD_TARGETS = ["bun", "node", "deno", "cf-pages", "vercel", "static"];
@@ -910,12 +1106,12 @@ export function isBuildTarget(value) {
  *   - `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.
  */
 export function generateServerEntry(options) {
-    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)");
     }
@@ -935,30 +1131,35 @@ export function generateServerEntry(options) {
         lines.push('import { serve } from "@nifrajs/node"');
     lines.push("", "const app = createWebApp({", "  adapter,", "  manifest,", "  clientEntry,", "  styles,", "  routeStyles,", ...(backendImport !== undefined ? ["  api: inProcessClient(backend),"] : []), `  title: ${JSON.stringify(title)},`, "})", "");
     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.", 'export const config = { runtime: "edge" }', "export default (req: Request): Response | Promise<Response> => app.fetch(req)");
+        lines.push("// 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)");
         return `${lines.join("\n")}\n`;
     }
     // 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)', 'const TYPES = { js: "text/javascript", css: "text/css", map: "application/json" }');
+    lines.push("// 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") {
-        lines.push("const server = Bun.serve({", "  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))", '      if (!(await file.exists())) return new Response("not found", { status: 404 })', '      const ext = name.slice(name.lastIndexOf(".") + 1)', '      return new Response(file, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })', "    }", "    return app.fetch(req)", "  },", "})", 
+        lines.push("const server = Bun.serve({", "  port: Number(Bun.env.PORT ?? 3000),", "  async fetch(req) {", "    const { pathname } = new URL(req.url)", "    const filePath = staticPath(pathname)", "    if (filePath !== undefined) {", "      const file = Bun.file(new URL(filePath, STATIC_ROOT))", '      if (!(await file.exists())) return new Response("not found", { status: 404 })', '      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`;
     }
     if (target === "node") {
-        lines.push('import { readFile } from "node:fs/promises"', "await serve(", "  {", "    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 })', "        try {", "          const body = await readFile(new URL(name, ASSETS))", '          const ext = name.slice(name.lastIndexOf(".") + 1)', '          return new Response(body, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })', "        } catch {", '          return new Response("not found", { status: 404 })', "        }", "      }", "      return app.fetch(req)", "    },", "  },", "  { port: Number(process.env.PORT ?? 3000) },", ")");
+        lines.push('import { readFile } from "node:fs/promises"', "await serve(", "  {", "    async fetch(req) {", "      const { pathname } = new URL(req.url)", "      const filePath = staticPath(pathname)", "      if (filePath !== undefined) {", "        try {", "          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 })', "        }", "      }", "      return app.fetch(req)", "    },", "  },", "  { port: Number(process.env.PORT ?? 3000) },", ")");
         return `${lines.join("\n")}\n`;
     }
     // deno
-    lines.push("const handler = toFetchHandler(app)", "// @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 })', "    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)', '      return new Response(body, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })', "    } catch {", '      return new Response("not found", { status: 404 })', "    }", "  }", "  return handler.fetch(req)", "})");
+    lines.push("const handler = toFetchHandler(app)", "// @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)", "  const filePath = staticPath(pathname)", "  if (filePath !== undefined) {", "    try {", "      // @ts-ignore - Deno.readFile is present on the Deno runtime.", "      const body = await Deno.readFile(new URL(filePath, STATIC_ROOT))", '      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 })', "    }", "  }", "  return handler.fetch(req)", "})");
     return `${lines.join("\n")}\n`;
 }
 /** The Bun.build `target` each deploy target compiles its server with (mirrors `buildServer`'s docs). */
@@ -984,22 +1185,39 @@ async function measureOutputs(paths) {
     }
     return chunks;
 }
+/** The default (Bun) strategy - `buildClient`/`buildServer` from this module. */
+export const bunBundler = {
+    buildClient: (input) => buildClient({
+        routesDir: input.routesDir,
+        outDir: input.outDir,
+        clientModule: input.clientModule,
+        ...(input.plugins ? { plugins: input.plugins } : {}),
+        ...(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 } : {}),
+        ...(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, options) {
+    return buildTargetWith(target, options, bunBundler);
+}
 /**
- * Build a full deploy directory for `target` from a file-routed nifra app. Emits the client bundle to
- * `<outDir>/assets/*`, then per target:
- *   - `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
- *     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
- * only adapter/backend/routes. Returns the manifest + a size report. Throws on any build failure.
- *
- * 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.
+ * 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 buildTarget(target, options) {
+export async function buildTargetWith(target, options, bundler) {
     const { routesDir, outDir, workDir } = options;
     const { rmSync } = await import("node:fs");
     rmSync(outDir, { recursive: true, force: true });
@@ -1008,14 +1226,25 @@ export async function buildTarget(target, options) {
     mkdirSync(assetsDir, { recursive: true });
     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) {
             throw new Error("[nifra/web] buildTarget(static) requires `prerenderApp` (a factory `(client) => createWebApp`)");
@@ -1032,8 +1261,8 @@ export async function buildTarget(target, options) {
         });
         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.
-            throw new Error("[nifra/web] buildTarget(static): no routes were prerendered — opt routes in with " +
+            // 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 " +
                 "`export const prerender = true` (static) or `getStaticPaths` (dynamic).");
         }
         rmSync(workDir, { recursive: true, force: true });
@@ -1055,9 +1284,10 @@ export async function buildTarget(target, options) {
         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`,
@@ -1065,13 +1295,24 @@ export async function buildTarget(target, options) {
         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.
     const { cpSync } = await import("node:fs");
     let run;
     if (target === "cf-pages") {
         cpSync(worker, `${outDir}/_worker.js`);
-        writeFileSync(`${outDir}/_routes.json`, `${JSON.stringify({ version: 1, include: ["/*"], exclude: ["/assets/*"] }, null, 2)}\n`);
+        // 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: 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") {