@nifrajs/web 2.0.0 → 2.2.0

package/dist/build.js

@@ -5,12 +5,15 @@
  * 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";
 // `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 +37,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). */
@@ -103,8 +256,8 @@ function shortestBuiltinChain(inputs, entryInputs, builtin) {
  * 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 ?? {};
+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)) {
@@ -119,7 +272,7 @@ export function detectNodeBuiltinsInClient(meta) {
     // 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 +288,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}`, {
@@ -252,8 +405,8 @@ function inputKeyResolver(inputs) {
  * (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 ?? {};
+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();
@@ -268,7 +421,7 @@ export function detectServerOnlyInClient(meta) {
     // 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 +437,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) });
@@ -301,6 +454,35 @@ 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. */
 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) => {
@@ -572,33 +754,19 @@ export async function buildClient(options) {
     // 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.
     const renamed = sanitizeOutputNames(result.outputs);
@@ -673,10 +841,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 } : {}),
     };
@@ -867,6 +1040,7 @@ export async function buildServer(options) {
             // 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.
             "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.
@@ -915,7 +1089,7 @@ export function isBuildTarget(value) {
  * 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,9 +1109,14 @@ 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") {
@@ -945,20 +1124,20 @@ export function generateServerEntry(options) {
         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.
         `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 +1163,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 +1204,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`)");
@@ -1055,9 +1262,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 +1273,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") {