@nifrajs/web 2.2.0 → 2.3.0

package/dist/build.js

@@ -1,5 +1,5 @@
 /**
- * `@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*
@@ -12,6 +12,7 @@ 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";
@@ -156,7 +157,7 @@ routePatterns) {
     }
     return { include, exclude, omitted };
 }
-/** The built asset map — the server reads `entry` for the client script + serves `assets`. */
+/** The built asset map - the server reads `entry` for the client script + serves `assets`. */
 /**
  * Copy `from` into `to`, returning the URL paths copied (sorted).
  *
@@ -201,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
@@ -225,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 ||
@@ -234,23 +235,23 @@ 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
@@ -258,18 +259,18 @@ function shortestBuiltinChain(inputs, entryInputs, builtin) {
  */
 export function detectNodeBuiltinsInClient(graph) {
     const inputs = graph.modules;
-    // (1) The builtins a user (non-polyfill) module imports directly — the ones the author controls.
+    // (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(graph.chunks)
@@ -307,8 +308,8 @@ export function detectNodeBuiltinsInClient(graph) {
 // 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
@@ -317,7 +318,7 @@ export function detectNodeBuiltinsInClient(graph) {
 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;
@@ -332,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);
@@ -351,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);
@@ -400,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(graph) {
     const inputs = graph.modules;
-    // (1) The modules that import the marker — the ones the author opted into the guard. The marker
+    // (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)) {
@@ -418,7 +419,7 @@ export function detectServerOnlyInClient(graph) {
     }
     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(graph.chunks)
@@ -452,10 +453,10 @@ export function detectServerOnlyInClient(graph) {
     });
 }
 /** 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
+// 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.
@@ -467,7 +468,7 @@ export function formatNodeBuiltinLeak(findings) {
     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 ` +
+    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")}`);
 }
@@ -478,7 +479,7 @@ export function formatServerOnlyLeak(findings) {
     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 ` +
+    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")}`);
@@ -492,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) {
@@ -514,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) {
@@ -549,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();
@@ -625,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.
  */
@@ -650,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) {
@@ -678,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
@@ -689,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).
@@ -700,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
@@ -717,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: [
@@ -725,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": "({})",
@@ -750,7 +752,7 @@ 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;
@@ -761,14 +763,14 @@ export async function buildClient(options) {
     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
+    // §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
@@ -783,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));
     });
@@ -797,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) => {
@@ -811,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 ?? {})) {
@@ -861,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",
@@ -873,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.
@@ -892,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 }));
@@ -900,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 = [
@@ -926,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 }));
@@ -934,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.
@@ -956,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",
         }));
     },
@@ -1004,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) {
@@ -1020,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);
@@ -1035,10 +1057,10 @@ 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",
         },
@@ -1062,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"];
@@ -1084,7 +1106,7 @@ 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.
  */
@@ -1120,7 +1142,7 @@ export function generateServerEntry(options) {
         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).
@@ -1128,7 +1150,7 @@ export function generateServerEntry(options) {
     if (target === "bun") {
         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`;
     }
@@ -1137,7 +1159,7 @@ export function generateServerEntry(options) {
         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)", "  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)", "})");
+    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). */
@@ -1163,7 +1185,7 @@ async function measureOutputs(paths) {
     }
     return chunks;
 }
-/** The default (Bun) strategy — `buildClient`/`buildServer` from this module. */
+/** The default (Bun) strategy - `buildClient`/`buildServer` from this module. */
 export const bunBundler = {
     buildClient: (input) => buildClient({
         routesDir: input.routesDir,
@@ -1239,8 +1261,8 @@ export async function buildTargetWith(target, options, bundler) {
         });
         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 });