@nifrajs/web 2.0.0 → 2.2.0

package/src/build.ts

@@ -5,13 +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 type { BunPlugin } from "bun"
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { cp, lstat, mkdir, realpath } from "node:fs/promises"
+import { dirname, join, relative, resolve as resolvePath, sep } from "node:path"
+import { type BunPlugin, Glob } from "bun"
 import { sanitizeOutputNames } from "./chunk-names.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
 // `buildTarget(static)` drives the SSG prerender engine directly (it's also re-exported below).
+import { type ClientModuleGraph, fromBunMetafile } from "./module-graph.ts"
 import { prerenderRoutes } from "./prerender.ts"
 
 // Build-time SSG: prerender opted-in static + dynamic routes to `index.html` (+ static `_data.json`),
@@ -48,6 +50,15 @@ export interface BuildClientOptions {
   readonly minify?: boolean
   /** URL prefix the assets are served under (default `"/assets/"`); also Bun's chunk `publicPath`. */
   readonly publicPath?: string
+  /**
+   * Directory of user-authored static files copied into the build and served at the root (default
+   * `"public"`). Absent directory ⇒ nothing copied, no error.
+   *
+   * NOT the same thing as {@link publicPath}, despite the names: that is the URL prefix for
+   * content-hashed bundle chunks and never covers files an author put on disk. The collision is a
+   * real source of confusion, which is why both are spelled out here.
+   */
+  readonly publicDir?: string | false
   /**
    * Prefix that opts an environment variable into the **client** bundle (Vite/Next convention; default
    * `"PUBLIC_"`). Every var in the build environment whose name starts with this prefix is baked into
@@ -82,7 +93,186 @@ export function publicEnvDefines(
   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: string): string {
+  return encodeURI(segment).replace(
+    /[?#]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  )
+}
+
+/**
+ * Cloudflare Pages rejects a `_routes.json` with more than 100 include+exclude rules combined, or any
+ * single rule longer than 100 characters.
+ */
+const CF_MAX_ROUTE_RULES = 100
+const CF_MAX_RULE_LENGTH = 100
+
+export interface CloudflareRouteRules {
+  readonly include: readonly string[]
+  readonly exclude: readonly string[]
+  /** Public files the budget could not name, so the build can say so instead of capping silently. */
+  readonly omitted: readonly string[]
+}
+
+/**
+ * What a route pattern's first URL segment says about the paths it can reach.
+ *
+ * The three cases are genuinely different and collapsing them is a fail-open bug: `/` reaches only the
+ * root and can never match below a directory, while `/:locale/about` can match below ANY directory, and
+ * both would otherwise read as "no literal first segment". `dynamic` is also where unrecognised syntax
+ * lands, deliberately - a pattern form this does not understand must never be taken as proof that
+ * nothing matches.
+ */
+type FirstSegment =
+  | { readonly kind: "root" }
+  | { readonly kind: "literal"; readonly value: string }
+  | { readonly kind: "dynamic" }
+
+function firstSegmentOf(pattern: string): FirstSegment {
+  const first = pattern.split("/").find((segment) => segment !== "")
+  if (first === undefined) return { kind: "root" }
+  return /^[A-Za-z0-9._-]+$/.test(first) ? { kind: "literal", value: first } : { kind: "dynamic" }
+}
+
+/**
+ * Directories under `public/` whose every file can be replaced by one `/<dir>/*` rule.
+ *
+ * Safe only when no route can ever be served beneath that directory, because the glob does not merely
+ * describe today's files - it hands Pages every future path under the prefix, and the worker never sees
+ * them. A `public/blog/hero.png` next to a `/blog/:slug` route is the ordinary case that breaks: the
+ * glob would send `/blog/my-post` to the CDN, which has no such file, and the page 404s in production
+ * only. So a directory collapses only when every route pattern starts with a literal segment that is
+ * something else. One dynamic first segment anywhere (`/:locale/…`) disables collapsing entirely, which
+ * is correct - such a route can match under any directory name.
+ *
+ * A collapsed directory also gives up the app's own 404 page for a missing file beneath it, since the
+ * request never reaches the worker. That is the right trade for a directory that holds only static
+ * files: a missing image should fail as a fast CDN 404, not as an HTML error page.
+ */
+function collapsibleDirs(
+  publicFiles: readonly string[],
+  routePatterns: readonly string[],
+): ReadonlySet<string> {
+  const reserved = new Set<string>()
+  for (const pattern of routePatterns) {
+    const first = firstSegmentOf(pattern)
+    // A dynamic first segment can match anywhere, so nothing is collapsible at all.
+    if (first.kind === "dynamic") return new Set()
+    // `root` reserves nothing: `/` cannot match a path below a directory.
+    if (first.kind === "literal") reserved.add(first.value)
+  }
+  const dirs = new Set<string>()
+  for (const file of publicFiles) {
+    const slash = file.indexOf("/", 1)
+    if (slash === -1) continue // a root-level file has no directory to collapse into
+    const dir = file.slice(1, slash)
+    if (!reserved.has(dir)) dirs.add(dir)
+  }
+  return dirs
+}
+
+/**
+ * Build the cf-pages `_routes.json` rules for a set of copied public files, within Cloudflare's budget.
+ *
+ * `exclude` is what Pages serves straight from the CDN instead of invoking the worker, so naming every
+ * public file is ideal - and impossible past ~99 of them. A `public/` of icons, fonts and share images
+ * clears 100 easily, and the rejection lands at `wrangler pages deploy`, long after the build reported
+ * success.
+ *
+ * A glob is emitted only where it cannot be wrong. `/assets/*` always is: the build owns that prefix
+ * outright, since it is where the hashed bundle is written. A `public/` subdirectory is different - the
+ * name is the author's, and a `/blog/*` rule would hand Pages every future path under `/blog/`, so a
+ * `/blog/:slug` route would 404 from the CDN in production only. {@link collapsibleDirs} therefore
+ * collapses a directory only after checking it against the app's real route patterns, which is what
+ * makes the compaction safe rather than merely smaller. Everything else stays an exact path, and a name
+ * containing `*` is dropped rather than escaped, since the rule would become a wildcard.
+ *
+ * What still does not fit is dropped, which is safe because the list is only an optimization: the
+ * generated worker serves any allowlisted path it receives through the ASSETS binding, so an omitted
+ * file costs one worker invocation, not a 404.
+ */
+export function cloudflareRouteRules(
+  publicFiles: readonly string[],
+  /**
+   * Every route pattern the app serves. Required, not defaulted: an empty list means "this app serves
+   * no routes", which makes every directory collapsible - a defensible answer to state deliberately and
+   * a dangerous one to arrive at by forgetting the argument.
+   */
+  routePatterns: readonly string[],
+): CloudflareRouteRules {
+  const include = ["/*"]
+  const exclude = ["/assets/*"]
+  const omitted: string[] = []
+
+  // Collapse only where the route table proves nothing can be served beneath the directory, and only
+  // when the per-file list would not have fit anyway - a smaller `_routes.json` is worth nothing on its
+  // own, and exact paths keep the app's own 404 for a missing file under that directory.
+  const perFileFits = publicFiles.length + include.length + exclude.length <= CF_MAX_ROUTE_RULES
+  const collapsible = perFileFits ? new Set<string>() : collapsibleDirs(publicFiles, routePatterns)
+  const emitted = new Set<string>()
+
+  for (const file of publicFiles) {
+    const slash = file.indexOf("/", 1)
+    const dir = slash === -1 ? undefined : file.slice(1, slash)
+    const collapsed = dir !== undefined && collapsible.has(dir)
+    const rule = collapsed ? `/${dir}/*` : file
+    if (emitted.has(rule)) continue // already covered by a rule emitted for an earlier file
+    // A `*` in a FILE name would turn that file's own rule into a wildcard. A collapsed rule's `*` is
+    // ours and deliberate, and the file's name never appears in it, so the check applies to one case.
+    if (!collapsed && file.includes("*")) {
+      omitted.push(file)
+      continue
+    }
+    if (include.length + exclude.length >= CF_MAX_ROUTE_RULES || rule.length > CF_MAX_RULE_LENGTH) {
+      omitted.push(file)
+      continue
+    }
+    exclude.push(rule)
+    emitted.add(rule)
+  }
+  return { include, exclude, omitted }
+}
+
 /** The built asset map — the server reads `entry` for the client script + serves `assets`. */
+/**
+ * Copy `from` into `to`, returning the URL paths copied (sorted).
+ *
+ * Lives here, not beside `servePublicDir`, because it is BUILD-time: it reaches for `Bun.Glob` and
+ * `node:fs`, and `public-dir.ts` is reachable from the client bundle graph through the package
+ * entry - a dynamic `import("bun")` there fails the browser build outright.
+ */
+export async function copyPublicDir(from: string, to: string): Promise<string[]> {
+  const source = resolvePath(from)
+  const sourceReal = await realpath(source)
+  const copied: string[] = []
+  for await (const rel of new Glob("**/*").scan({ cwd: source, dot: true, onlyFiles: false })) {
+    const candidate = join(source, rel)
+    const candidateStat = await lstat(candidate)
+    if (candidateStat.isSymbolicLink()) {
+      throw new Error(`[nifra/web] publicDir entry escapes its root through a symlink: ${rel}`)
+    }
+    if (!candidateStat.isFile()) continue
+    const candidateReal = await realpath(candidate)
+    if (candidateReal !== sourceReal && !candidateReal.startsWith(sourceReal + sep)) {
+      throw new Error(`[nifra/web] publicDir entry escapes its root through a symlink: ${rel}`)
+    }
+    const target = join(to, rel)
+    await mkdir(join(target, ".."), { recursive: true })
+    await cp(candidateReal, target)
+    copied.push(`/${rel.split(sep).map(encodePathSegment).join("/")}`)
+  }
+  return copied.sort()
+}
+
 export interface BuildManifest {
   /** URL of the client entry module (content-hashed). */
   readonly entry: string
@@ -92,6 +282,10 @@ export interface BuildManifest {
    * `routePreload` (`<link rel="modulepreload">` the matched route alongside the entry). Each route +
    * layout is also a build entrypoint, so it gets a named chunk the bootstrap's lazy import dedupes to. */
   readonly routes: Readonly<Record<string, readonly string[]>>
+  /** URL paths copied from `publicDir`, sorted. Lets the server entry serve them without scanning a
+   * directory per request, and lets an adapter that needs a file list (CDN upload, platform static
+   * assets) consume one. Omitted when there is no `public/`. */
+  readonly publicFiles?: readonly string[]
   /** The app's bundled, content-hashed stylesheet(s) — the bootstrap's **aggregate** CSS (every
    * `import './x.css'` reachable from the app). The complete stylesheet regardless of which file
    * imported the CSS; the always-safe fallback `createWebApp` links when a route has no per-route entry
@@ -216,9 +410,9 @@ function shortestBuiltinChain(
  * literal that merely contains `"node:crypto"`. Pure + exported for unit testing. Empty ⇒ clean.
  */
 export function detectNodeBuiltinsInClient(
-  meta: BunMetafile | undefined,
+  graph: ClientModuleGraph,
 ): ReadonlyArray<NodeBuiltinFinding> {
-  const inputs = meta?.inputs ?? {}
+  const inputs = graph.modules
   // (1) The builtins a user (non-polyfill) module imports directly — the ones the author controls.
   const userImported = new Set<string>()
   for (const [inputKey, input] of Object.entries(inputs)) {
@@ -232,7 +426,7 @@ export function detectNodeBuiltinsInClient(
   // at the file the dev wrote an `import` in. Each output's `entryPoint` is one such input.
   const entryInputs = [
     ...new Set(
-      Object.values(meta?.outputs ?? {})
+      Object.values(graph.chunks)
         .map((o) => o.entryPoint)
         .filter((e): e is string => e !== undefined && !e.startsWith("node:")),
     ),
@@ -248,8 +442,8 @@ export function detectNodeBuiltinsInClient(
   }
   // (2) Locate which emitted chunk each user-imported builtin reached, via the per-output `inputs`.
   const findings = new Map<string, NodeBuiltinFinding>()
-  for (const [outPath, out] of Object.entries(meta?.outputs ?? {})) {
-    for (const inputKey of Object.keys(out.inputs ?? {})) {
+  for (const [outPath, out] of Object.entries(graph.chunks)) {
+    for (const inputKey of out.modules) {
       if (userImported.has(inputKey)) {
         const chunk = basename(outPath)
         findings.set(`${inputKey}\0${chunk}`, {
@@ -386,9 +580,9 @@ function inputKeyResolver(
  * unit testing. Empty ⇒ clean.
  */
 export function detectServerOnlyInClient(
-  meta: BunMetafile | undefined,
+  graph: ClientModuleGraph,
 ): ReadonlyArray<ServerOnlyFinding> {
-  const inputs = meta?.inputs ?? {}
+  const inputs = graph.modules
   // (1) The modules that import the marker — the ones the author opted into the guard. The marker
   // module itself is skipped: it's the import TARGET, not an opt-in (it imports nothing of its own).
   const marked = new Set<string>()
@@ -401,7 +595,7 @@ export function detectServerOnlyInClient(
   // wrote an `import` in. Same derivation as the node-builtin guard.
   const entryInputs = [
     ...new Set(
-      Object.values(meta?.outputs ?? {})
+      Object.values(graph.chunks)
         .map((o) => o.entryPoint)
         .filter((e): e is string => e !== undefined && !e.startsWith("node:")),
     ),
@@ -417,8 +611,8 @@ export function detectServerOnlyInClient(
   }
   // (2) Locate which emitted chunk each marked module reached, via the per-output `inputs`.
   const findings = new Map<string, ServerOnlyFinding>()
-  for (const [outPath, out] of Object.entries(meta?.outputs ?? {})) {
-    for (const inputKey of Object.keys(out.inputs ?? {})) {
+  for (const [outPath, out] of Object.entries(graph.chunks)) {
+    for (const inputKey of out.modules) {
       if (marked.has(inputKey)) {
         const chunk = basename(outPath)
         findings.set(`${inputKey}\0${chunk}`, { chunk, chain: chainFor(inputKey) })
@@ -437,6 +631,48 @@ export function detectServerOnlyInClient(
 const isServerOnlyMarkerModule = (inputKey: string): boolean =>
   /(^|\/)server-only\.[cm]?[jt]s$/.test(inputKey)
 
+// ---------------------------------------------------------------------------------------------------
+// Guard MESSAGES — one owner for both production pipelines. The Bun build (below) and the Vite/Rollup
+// leak-guard plugin (plugins/vite-leak-guard.ts) both call these, so a leak reads IDENTICALLY whichever
+// bundler produced it. A second bundler must not grow a second, subtly-different wording of a security
+// error; that is exactly the "mostly ported" outcome the neutral graph seam exists to prevent.
+// ---------------------------------------------------------------------------------------------------
+
+/** The build-failing message for `node:` builtins that reached the client bundle. `undefined` ⇒ clean. */
+export function formatNodeBuiltinLeak(
+  findings: ReadonlyArray<NodeBuiltinFinding>,
+): string | undefined {
+  if (findings.length === 0) return undefined
+  const lines = findings.map((f) =>
+    f.chain.length > 1
+      ? `  - ${f.builtin} reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
+      : `  - ${f.builtin} reached the client bundle via ${f.chunk}`,
+  )
+  return (
+    `[nifra/web] Node built-in(s) in the client bundle — move them behind a server-only path ` +
+    `(a loader/action runs on the server; import the \`node:\` module there, not at a route's ` +
+    `top level):\n${lines.join("\n")}`
+  )
+}
+
+/** The build-failing message for `server-only`-marked modules that reached the client. `undefined` ⇒ clean. */
+export function formatServerOnlyLeak(
+  findings: ReadonlyArray<ServerOnlyFinding>,
+): string | undefined {
+  if (findings.length === 0) return undefined
+  const lines = findings.map((f) =>
+    f.chain.length > 1
+      ? `  - server-only module reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
+      : `  - server-only module reached the client bundle via ${f.chunk}`,
+  )
+  return (
+    `[nifra/web] server-only module(s) in the client bundle — a module marked ` +
+    `\`import "${SERVER_ONLY_MARKER}"\` reached the browser. Move it behind a server-only path ` +
+    `(reach it via a loader/action, or rename it \`*.server.ts\`), so its server logic never ships ` +
+    `to the client:\n${lines.join("\n")}`
+  )
+}
+
 const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1)
 /** `[name]` Bun derives for an entrypoint: basename without extension (`users/[id].tsx` → `[id]`). */
 const entryName = (file: string): string => {
@@ -784,42 +1020,18 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // per-output `inputs`), so it can't false-positive on a `"node:..."` string literal and survives
   // minification. Only the client build runs this; the server build's `node:` imports are legitimate.
   const clientMeta = (result as unknown as { metafile?: BunMetafile }).metafile
-  const nodeBuiltins = detectNodeBuiltinsInClient(clientMeta)
-  if (nodeBuiltins.length > 0) {
-    // Name the offending builtin AND the import chain that pulled it in (entry → … → builtin), so the
-    // dev sees the exact path from a route file to the leak instead of just the emitted chunk name.
-    // The chain always starts at a user entry; fall back to the chunk name if it somehow came back empty.
-    const lines = nodeBuiltins.map((f) =>
-      f.chain.length > 1
-        ? `  - ${f.builtin} reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
-        : `  - ${f.builtin} reached the client bundle via ${f.chunk}`,
-    )
-    throw new Error(
-      `[nifra/web] Node built-in(s) in the client bundle — move them behind a server-only path ` +
-        `(a loader/action runs on the server; import the \`node:\` module there, not at a route's ` +
-        `top level):\n${lines.join("\n")}`,
-    )
-  }
-
-  // §3.3/§5.1: a module that opted into the `server-only` marker (`import "@nifrajs/web/server-only"`)
-  // yet reached a CLIENT chunk — fail the build with the same chain-bearing, "reached the client bundle
-  // via" message shape as the node-builtin guard above. This catches pure-server logic (a secret, a
-  // server-only API call) that carries no `node:` import and isn't named `*.server`, so neither of the
-  // other two guards fires. Graph-based (the same metafile), so it survives minification.
-  const serverOnly = detectServerOnlyInClient(clientMeta)
-  if (serverOnly.length > 0) {
-    const lines = serverOnly.map((f) =>
-      f.chain.length > 1
-        ? `  - server-only module reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
-        : `  - server-only module reached the client bundle via ${f.chunk}`,
-    )
-    throw new Error(
-      `[nifra/web] server-only module(s) in the client bundle — a module marked ` +
-        `\`import "${SERVER_ONLY_MARKER}"\` reached the browser. Move it behind a server-only path ` +
-        `(reach it via a loader/action, or rename it \`*.server.ts\`), so its server logic never ships ` +
-        `to the client:\n${lines.join("\n")}`,
-    )
-  }
+  const clientGraph = fromBunMetafile(clientMeta)
+  // #4: a `node:` builtin (e.g. `node:crypto`) pulled into a CLIENT chunk builds fine (Bun substitutes a
+  // browser polyfill) but breaks/leaks at runtime. Fail with the chain (entry → … → builtin), through the
+  // SHARED formatter so the Vite pipeline's identical guard reads byte-for-byte the same.
+  const nodeBuiltinLeak = formatNodeBuiltinLeak(detectNodeBuiltinsInClient(clientGraph))
+  if (nodeBuiltinLeak !== undefined) throw new Error(nodeBuiltinLeak)
+
+  // §3.3/§5.1: a module that opted into the `server-only` marker yet reached a CLIENT chunk — catches
+  // pure-server logic (a secret, a server-only API call) carrying no `node:` import and not named
+  // `*.server`, so neither other guard fires. Same shared formatter as above.
+  const serverOnlyLeak = formatServerOnlyLeak(detectServerOnlyInClient(clientGraph))
+  if (serverOnlyLeak !== undefined) throw new Error(serverOnlyLeak)
 
   // Rename any chunk whose basename isn't URL-safe (dynamic-route files become `[slug]-hash.js`) and
   // rewrite the references — otherwise the lazy import 404s and the route silently never hydrates.
@@ -899,10 +1111,17 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
     if (routeManifest.notFound) routeStyles._404 = stylesFor([routeManifest.notFound.file])
   }
 
+  // Copy `public/` into the output next to the hashed assets. A missing directory is normal (most
+  // apps have none) and must not fail the build.
+  const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
+  const publicFiles =
+    publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
+
   const manifest: BuildManifest = {
     entry: toUrl(bootstrap.path),
     assets: result.outputs.map((o) => toUrl(o.path)),
     routes,
+    ...(publicFiles.length > 0 ? { publicFiles } : {}),
     ...(css.length > 0 ? { css } : {}),
     ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
   }
@@ -1158,6 +1377,7 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       // 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.
@@ -1220,8 +1440,10 @@ export function generateServerEntry(options: {
   readonly backendImport?: string
   /** Document `<title>` passed to `createWebApp`. */
   readonly title?: string
+  /** Encoded root-relative public file paths copied into the deploy directory. */
+  readonly publicFiles?: readonly string[]
 }): string {
-  const { target, adapterImport, backendImport, title = "nifra" } = options
+  const { target, adapterImport, backendImport, title = "nifra", publicFiles = [] } = options
   if (target === "static") {
     throw new Error("[nifra/web] generateServerEntry: `static` has no server entry (SSG only)")
   }
@@ -1251,9 +1473,28 @@ export function generateServerEntry(options: {
   )
 
   if (target === "cf-pages") {
-    // Cloudflare Pages advanced mode: `_routes.json` serves /assets/* from the CDN; everything else
-    // falls through to this fetch handler (SSR). The default export is the handler object.
-    lines.push("export default toFetchHandler(app)")
+    // Cloudflare Pages advanced mode: `_routes.json` keeps static paths off the worker entirely, and
+    // everything else falls through to this handler (SSR).
+    //
+    // That exclude list cannot always name every public file - Cloudflare caps `_routes.json` at 100
+    // rules - so a static request CAN arrive here. Serve it from the ASSETS binding instead of letting
+    // the router 404 it, which makes correctness independent of how much of the list fit: the exclude
+    // list decides only how many static requests skip the worker, never which files exist.
+    lines.push(
+      `const PUBLIC_FILES = new Set(${JSON.stringify(publicFiles)})`,
+      "const handler = toFetchHandler(app)",
+      "type Assets = { readonly ASSETS?: { fetch(request: Request): Promise<Response> } }",
+      "export default {",
+      "  fetch(request: Request, env: Assets, ctx: ExecutionContext) {",
+      "    const { pathname } = new URL(request.url)",
+      "    // Only the build's own outputs: the hashed bundle prefix and the files it copied.",
+      '    if (env?.ASSETS !== undefined && (pathname.startsWith("/assets/") || PUBLIC_FILES.has(pathname))) {',
+      "      return env.ASSETS.fetch(request)",
+      "    }",
+      "    return handler.fetch(request, env as never, ctx)",
+      "  },",
+      "}",
+    )
     return `${lines.join("\n")}\n`
   }
   if (target === "vercel") {
@@ -1267,8 +1508,20 @@ export function generateServerEntry(options: {
 
   // bun / node / deno self-host AND serve the client bundle from disk (it sits next to this entry).
   lines.push(
-    "// The client bundle lives next to this entry; serve /assets/* from disk, SSR everything else.",
-    'const ASSETS = new URL("./assets/", import.meta.url)',
+    "// The client bundle and public files live next to this entry; serve only manifest-approved paths.",
+    'const STATIC_ROOT = new URL("./", import.meta.url)',
+    `const PUBLIC_FILES = new Set(${JSON.stringify(publicFiles)})`,
+    "const staticPath = (pathname: string): string | undefined => {",
+    "  if (PUBLIC_FILES.has(pathname)) return '.' + pathname",
+    '  if (!pathname.startsWith("/assets/")) return undefined',
+    '  const segments = pathname.slice(1).split("/")',
+    "  // `.` and `..` match the character class, and the path is joined onto a base URL that resolves",
+    "  // dot segments - so they are rejected explicitly rather than relying on the request URL having",
+    "  // been normalized upstream.",
+    "  const safe = (segment: string): boolean =>",
+    '    segment !== "." && segment !== ".." && /^[A-Za-z0-9._-]+$/.test(segment)',
+    "  return segments.every(safe) ? '.' + pathname : undefined",
+    "}",
     'const TYPES = { js: "text/javascript", css: "text/css", map: "application/json" }',
   )
   if (target === "bun") {
@@ -1277,12 +1530,11 @@ export function generateServerEntry(options: {
       "  port: Number(Bun.env.PORT ?? 3000),",
       "  async fetch(req) {",
       "    const { pathname } = new URL(req.url)",
-      '    if (pathname.startsWith("/assets/")) {',
-      '      const name = pathname.slice("/assets/".length)',
-      '      if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })',
-      "      const file = Bun.file(new URL(name, ASSETS))",
+      "    const filePath = staticPath(pathname)",
+      "    if (filePath !== undefined) {",
+      "      const file = Bun.file(new URL(filePath, STATIC_ROOT))",
       '      if (!(await file.exists())) return new Response("not found", { status: 404 })',
-      '      const ext = name.slice(name.lastIndexOf(".") + 1)',
+      '      const ext = pathname.slice(pathname.lastIndexOf(".") + 1)',
       '      return new Response(file, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })',
       "    }",
       "    return app.fetch(req)",
@@ -1301,12 +1553,11 @@ export function generateServerEntry(options: {
       "  {",
       "    async fetch(req) {",
       "      const { pathname } = new URL(req.url)",
-      '      if (pathname.startsWith("/assets/")) {',
-      '        const name = pathname.slice("/assets/".length)',
-      '        if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })',
+      "      const filePath = staticPath(pathname)",
+      "      if (filePath !== undefined) {",
       "        try {",
-      "          const body = await readFile(new URL(name, ASSETS))",
-      '          const ext = name.slice(name.lastIndexOf(".") + 1)',
+      "          const body = await readFile(new URL(filePath, STATIC_ROOT))",
+      '          const ext = pathname.slice(pathname.lastIndexOf(".") + 1)',
       '          return new Response(body, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })',
       "        } catch {",
       '          return new Response("not found", { status: 404 })',
@@ -1326,13 +1577,12 @@ export function generateServerEntry(options: {
     "// @ts-ignore — Deno global is present on the Deno runtime this output targets.",
     'Deno.serve({ port: Number(Deno.env.get("PORT") ?? "3000") }, async (req) => {',
     "  const { pathname } = new URL(req.url)",
-    '  if (pathname.startsWith("/assets/")) {',
-    '    const name = pathname.slice("/assets/".length)',
-    '    if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })',
+    "  const filePath = staticPath(pathname)",
+    "  if (filePath !== undefined) {",
     "    try {",
     "      // @ts-ignore — Deno.readFile is present on the Deno runtime.",
-    "      const body = await Deno.readFile(new URL(name, ASSETS))",
-    '      const ext = name.slice(name.lastIndexOf(".") + 1)',
+    "      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 })',
@@ -1397,6 +1647,10 @@ export interface BuildTargetOptions {
   readonly conditions?: readonly string[]
   /** Compile-time `define` replacements layered onto both builds. */
   readonly define?: Readonly<Record<string, string>>
+  /** Project-root static directory copied to deploy root. `false` disables it. */
+  readonly publicDir?: string | false
+  /** Prefix of environment variables allowed into the client bundle (default `"PUBLIC_"`). */
+  readonly publicEnvPrefix?: string
   /** Document `<title>` for the generated server entry. */
   readonly title?: string
 }
@@ -1436,9 +1690,84 @@ export interface BuildTargetResult {
  * Note: the heavier platform wrappers (`.vercel/output` v3 layout, wrangler ISR `find_additional_modules`)
  * remain app-owned scripts; this command targets the common single-bundle deploys. See the CLI docs.
  */
+/**
+ * A build-tool STRATEGY for {@link buildTargetWith} — the two bundling steps, and nothing else. Everything
+ * around them (server-entry codegen, deploy assembly, prerender, size report) is bundler-agnostic and
+ * lives in `buildTargetWith`, so a second bundler (Vite) is this interface, not a second orchestrator.
+ *
+ * Plugin lists are `readonly unknown[]` because a Bun plugin and a Vite plugin are different types; each
+ * strategy casts to its own. `buildTargetWith` only forwards them.
+ */
+export interface Bundler {
+  /** Build the client bundle → the shared {@link BuildManifest}. */
+  buildClient(input: {
+    readonly routesDir: string
+    readonly outDir: string
+    readonly clientModule: string
+    readonly plugins?: readonly unknown[]
+    readonly conditions?: readonly string[]
+    readonly define?: Readonly<Record<string, string>>
+    readonly publicDir?: string | false
+    readonly publicEnvPrefix?: string
+    /** Project root (Vite needs it; the Bun strategy ignores it). */
+    readonly root?: string
+  }): Promise<BuildManifest>
+  /** Build the server worker → the shared {@link ServerBuild}. */
+  buildServer(input: {
+    readonly routesDir: string
+    readonly serverEntry: string
+    readonly outDir: string
+    readonly clientEntry: string
+    readonly target: "browser" | "node" | "bun"
+    readonly plugins?: readonly unknown[]
+    readonly define?: Readonly<Record<string, string>>
+    readonly root?: string
+  }): Promise<ServerBuild>
+}
+
+/** The default (Bun) strategy — `buildClient`/`buildServer` from this module. */
+export const bunBundler: Bundler = {
+  buildClient: (input) =>
+    buildClient({
+      routesDir: input.routesDir,
+      outDir: input.outDir,
+      clientModule: input.clientModule,
+      ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
+      ...(input.conditions ? { conditions: input.conditions } : {}),
+      ...(input.define ? { define: input.define } : {}),
+      ...(input.publicDir !== undefined ? { publicDir: input.publicDir } : {}),
+      ...(input.publicEnvPrefix !== undefined ? { publicEnvPrefix: input.publicEnvPrefix } : {}),
+    }),
+  buildServer: (input) =>
+    buildServer({
+      routesDir: input.routesDir,
+      serverEntry: input.serverEntry,
+      outDir: input.outDir,
+      clientEntry: input.clientEntry,
+      target: input.target,
+      ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
+      ...(input.define ? { define: input.define } : {}),
+    }),
+}
+
+/** Build a full deploy dir for `target` using the default Bun bundler. See {@link buildTargetWith}. */
 export async function buildTarget(
   target: BuildTarget,
   options: BuildTargetOptions,
+): Promise<BuildTargetResult> {
+  return buildTargetWith(target, options, bunBundler)
+}
+
+/**
+ * The bundler-agnostic deploy orchestrator: everything `buildTarget` does EXCEPT the two bundling steps,
+ * which come from `bundler`. `buildTarget` passes {@link bunBundler}; `buildTargetVite`
+ * (`@nifrajs/web/build-vite`) passes the Vite strategy. One orchestrator, so the deploy-dir shape,
+ * server-entry codegen, prerender and size report are identical across pipelines.
+ */
+export async function buildTargetWith(
+  target: BuildTarget,
+  options: BuildTargetOptions,
+  bundler: Bundler,
 ): Promise<BuildTargetResult> {
   const { routesDir, outDir, workDir } = options
   const { rmSync } = await import("node:fs")
@@ -1449,14 +1778,27 @@ export async function buildTarget(
   mkdirSync(workDir, { recursive: true })
 
   // (1) Client bundle → <outDir>/assets/* (every target ships the same hashed client bundle).
-  const client = await buildClient({
+  let client = await bundler.buildClient({
     routesDir,
     outDir: assetsDir,
     clientModule: options.clientModule,
     ...(options.clientPlugins ? { plugins: options.clientPlugins } : {}),
     ...(options.conditions ? { conditions: options.conditions } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
+    publicDir: false,
+    ...(options.publicEnvPrefix !== undefined ? { publicEnvPrefix: options.publicEnvPrefix } : {}),
+    root: resolvePath(dirname(routesDir)),
   })
+  const publicDir =
+    options.publicDir === false
+      ? undefined
+      : resolvePath(options.publicDir ?? join(dirname(routesDir), "public"))
+  const publicFiles =
+    publicDir !== undefined && existsSync(publicDir) ? await copyPublicDir(publicDir, outDir) : []
+  if (publicFiles.length > 0) {
+    client = { ...client, publicFiles }
+    writeFileSync(`${assetsDir}/manifest.json`, JSON.stringify(client, null, 2))
+  }
 
   if (target === "static") {
     if (options.prerenderApp === undefined) {
@@ -1506,10 +1848,11 @@ export async function buildTarget(
       adapterImport: options.adapterImport,
       ...(options.backendImport !== undefined ? { backendImport: options.backendImport } : {}),
       ...(options.title !== undefined ? { title: options.title } : {}),
+      ...(publicFiles.length > 0 ? { publicFiles } : {}),
     }),
   )
   const serverTarget = SERVER_BUILD_TARGET[target]
-  const { worker } = await buildServer({
+  const { worker } = await bundler.buildServer({
     routesDir,
     serverEntry: serverEntryPath,
     outDir: `${workDir}/server`,
@@ -1517,6 +1860,7 @@ export async function buildTarget(
     target: serverTarget,
     ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
+    root: resolvePath(dirname(routesDir)),
   })
 
   // (3) Assemble the deploy dir for the target.
@@ -1524,10 +1868,25 @@ export async function buildTarget(
   let run: string
   if (target === "cf-pages") {
     cpSync(worker, `${outDir}/_worker.js`)
+    // The app's real patterns, so a directory is only collapsed into a glob once the route table
+    // proves nothing can be served beneath it.
+    const rules = cloudflareRouteRules(
+      publicFiles,
+      discoverRoutes(routesDir).routes.map((route) => route.pattern),
+    )
     writeFileSync(
       `${outDir}/_routes.json`,
-      `${JSON.stringify({ version: 1, include: ["/*"], exclude: ["/assets/*"] }, null, 2)}\n`,
+      `${JSON.stringify({ version: 1, include: rules.include, exclude: rules.exclude }, null, 2)}\n`,
     )
+    // Never cap silently: an omitted file still serves (the worker's ASSETS fallback), but it costs a
+    // worker invocation, and that trade should be visible rather than inferred from a latency graph.
+    if (rules.omitted.length > 0) {
+      console.log(
+        `[nifra/web] _routes.json holds ${rules.exclude.length} of ${publicFiles.length + 1} static rules ` +
+          `(Cloudflare allows ${CF_MAX_ROUTE_RULES}). The other ${rules.omitted.length} file(s) are served by the ` +
+          "worker via ASSETS instead of the CDN directly - correct, just one invocation each.",
+      )
+    }
     run = `Cloudflare Pages → ${outDir} (deploy: wrangler pages deploy ${basename(outDir)})`
   } else if (target === "vercel") {
     cpSync(worker, `${outDir}/index.js`)