@nifrajs/web 2.1.0 → 2.3.0

package/src/module-graph.ts

@@ -0,0 +1,146 @@
+/**
+ * A bundler-neutral view of a client build, for the guards that must run on every pipeline.
+ *
+ * nifra's two client-leak guards - server-only code reaching the browser, and `node:` builtins in
+ * client code - are the reason a pipeline choice is safe. They are security guards, not lints: one
+ * stops secrets and database access shipping to a browser. Today both read Bun's metafile directly,
+ * so a second production pipeline would either arrive without them or need them hastily ported, and
+ * "mostly ported" is the wrong outcome for a guard of that kind.
+ *
+ * This is the seam that prevents that. It is introduced while Bun is still the ONLY producer, so the
+ * adapter can be verified against the existing behaviour rather than written under pressure beside a
+ * new bundler. Adding Rollup later becomes one more `from…` function rather than a second copy of the
+ * detection logic.
+ *
+ * Deliberately minimal - exactly what the guards read, nothing more:
+ *   - which modules exist and what each imports (to walk the import chain to a sink)
+ *   - which output chunk each module landed in (to name the chunk a leak reached)
+ */
+
+/** One import edge, as the bundler recorded it. */
+export interface GraphImport {
+  /** The resolved path, when the bundler resolved it. */
+  readonly path?: string
+  /** The specifier as written in source - the only form that survives an unresolved import. */
+  readonly original?: string
+}
+
+export interface GraphModule {
+  readonly imports: readonly GraphImport[]
+}
+
+export interface GraphChunk {
+  /** Source module this chunk is the entry for, if it is one. */
+  readonly entryPoint?: string
+  /** Module ids that landed in this chunk. */
+  readonly modules: readonly string[]
+}
+
+/** What a client build looks like to the guards, whichever bundler produced it. */
+export interface ClientModuleGraph {
+  /** Module id → its imports. Ids are bundler-native (Bun graph keys, Rollup module ids). */
+  readonly modules: Readonly<Record<string, GraphModule>>
+  /** Output path → what it contains. */
+  readonly chunks: Readonly<Record<string, GraphChunk>>
+}
+
+/** The slice of Bun's metafile this seam consumes. Not yet in `@types/bun`; shape per the docs. */
+export interface BunMetafileLike {
+  readonly inputs?: Readonly<
+    Record<string, { readonly imports?: ReadonlyArray<{ path?: string; original?: string }> }>
+  >
+  readonly outputs?: Readonly<
+    Record<
+      string,
+      { readonly entryPoint?: string; readonly inputs?: Readonly<Record<string, unknown>> }
+    >
+  >
+}
+
+/**
+ * Adapt a `Bun.build` metafile to the neutral graph.
+ *
+ * A total function: an absent or partial metafile yields an empty graph rather than throwing, because
+ * a guard that crashes on an unexpected build shape fails the build for the wrong reason. An empty
+ * graph reports no findings, which matches the existing behaviour when the metafile is missing.
+ */
+export function fromBunMetafile(meta: BunMetafileLike | undefined): ClientModuleGraph {
+  const modules: Record<string, GraphModule> = {}
+  for (const [id, input] of Object.entries(meta?.inputs ?? {})) {
+    modules[id] = { imports: input.imports ?? [] }
+  }
+  const chunks: Record<string, GraphChunk> = {}
+  for (const [path, output] of Object.entries(meta?.outputs ?? {})) {
+    chunks[path] = {
+      ...(output.entryPoint !== undefined ? { entryPoint: output.entryPoint } : {}),
+      modules: Object.keys(output.inputs ?? {}),
+    }
+  }
+  return { modules, chunks }
+}
+
+/**
+ * The slice of a Rollup/Vite output bundle this seam consumes. `OutputBundle` is
+ * `Record<fileName, OutputChunk | OutputAsset>`; only chunks carry a module graph. Typed structurally
+ * (no `rollup`/`vite` type dependency) - the fields are stable Rollup output API.
+ */
+export interface RollupChunkLike {
+  /** `"chunk"` for JS output, `"asset"` for CSS/static - assets have no module graph. */
+  readonly type?: string
+  /** The entry module id this chunk was built for, if it is an entry. Rollup's `facadeModuleId`. */
+  readonly facadeModuleId?: string | null
+  /** Every module id that landed in this chunk. Rollup's `moduleIds`. */
+  readonly moduleIds?: readonly string[]
+}
+export type RollupBundleLike = Readonly<Record<string, RollupChunkLike>>
+
+/**
+ * Adapt a Rollup/Vite output bundle to the neutral graph - the second producer the seam was built for.
+ *
+ * The bundle records which modules landed in which chunk (`moduleIds`) but NOT each module's import
+ * edges, so those come from `importsOf`, which the caller backs with `this.getModuleInfo(id).importedIds`
+ * inside a plugin hook (a test backs it with a plain map). Edges carry only the RESOLVED id - Rollup does
+ * not keep the as-written specifier per edge - so `path` is set and `original` is left undefined. Both
+ * guards read the resolved `path` as their fallback (a `node:` prefix, the `server-only` basename), so
+ * detection is unaffected; only the human-readable chain shows resolved paths instead of as-written ones.
+ *
+ * Total, like {@link fromBunMetafile}: an empty bundle yields an empty graph (no findings), never a throw
+ * that would fail a build for the wrong reason.
+ */
+export function fromRollupBundle(
+  bundle: RollupBundleLike,
+  importsOf: (moduleId: string) => readonly string[],
+): ClientModuleGraph {
+  const modules: Record<string, GraphModule> = {}
+  const chunks: Record<string, GraphChunk> = {}
+  for (const [fileName, output] of Object.entries(bundle)) {
+    // Assets (CSS, copied files) have no module graph; `type` is absent only on hand-built test inputs,
+    // which are always chunks, so treat "not explicitly an asset" as a chunk.
+    if (output.type === "asset") continue
+    const moduleIds = output.moduleIds ?? []
+    // Start from the real modules; `node:` builtins get appended below.
+    const chunkModules: string[] = [...moduleIds]
+    for (const id of moduleIds) {
+      const imports = importsOf(id).map((path) => ({ path }))
+      if (modules[id] === undefined) modules[id] = { imports }
+      // The guards locate a leak by finding the builtin IN a chunk's module list - Bun BUNDLES the `node:`
+      // polyfill, so the builtin appears there as an input. Rollup EXTERNALIZES `node:`, so it never lands
+      // in `moduleIds` and the guard would see nothing. Synthesize the Bun shape: register each imported
+      // builtin as a member of THIS chunk (where the leak is) and as a leaf module, so the neutral graph
+      // is identical whichever bundler produced it. Only `node:` needs this; a server-only-marked module
+      // is a real user module and is already a chunk member.
+      for (const im of imports) {
+        if (!im.path.startsWith("node:")) continue
+        if (!chunkModules.includes(im.path)) chunkModules.push(im.path)
+        if (modules[im.path] === undefined) modules[im.path] = { imports: [] }
+      }
+    }
+    chunks[fileName] = {
+      // `facadeModuleId` is null for a shared/common chunk (no single entry) - omit it then, matching
+      // how a non-entry Bun output omits `entryPoint`, so the guards' entry set stays the real entries.
+      ...(output.facadeModuleId ? { entryPoint: output.facadeModuleId } : {}),
+      modules: chunkModules,
+    }
+  }
+  return { modules, chunks }
+}

package/src/navigation.ts

@@ -1,23 +1,94 @@
 /**
- * `@nifrajs/web` navigation bridge — a tiny, DOM-free seam that lets an adapter's `useNavigate`
- * (a route component, which must import only from the agnostic `@nifrajs/web` main entry — never the
+ * `@nifrajs/web` navigation bridge - a tiny, DOM-free seam that lets an adapter's `useNavigate`
+ * (a route component, which must import only from the agnostic `@nifrajs/web` main entry - never the
  * DOM-only `/client`) reach the browser's history-aware navigate, WITHOUT the route component pulling
  * `@nifrajs/web/client` (and its `document`/`history` access) into a bundle that also renders on the
  * server.
  *
  * The browser layer (`installHistory`, in `./client.ts`) populates this on setup and clears it on
- * teardown; a framework binding reads it via {@link getBrowserNavigate}. Module-level singleton — the
+ * teardown; a framework binding reads it via {@link getBrowserNavigate}. Module-level singleton - the
  * browser mounts exactly one app per page (the same convention the adapters' `setMountedRouter` uses).
  * On the server (and before hydration) the getter returns `undefined`, so a binding degrades to the
- * native `<a href>` full-page navigation — progressive enhancement, no throw.
+ * native `<a href>` full-page navigation - progressive enhancement, no throw.
  */
 
+import { serializeSearch } from "./search.ts"
+
 /** Options for a programmatic navigation. */
 export interface NavigateOptions {
   /** Replace the current history entry instead of pushing a new one (like `history.replaceState`). */
   readonly replace?: boolean
 }
 
+/**
+ * The augmentable route -> search-type map for typed cross-route navigation. Empty by default (so an
+ * object-form navigate to any path is allowed with a loose `search`). A build step (`nifra sync-routes`)
+ * OR the app declares one entry per route path against its `searchSchema` output:
+ *
+ * ```ts
+ * declare module "@nifrajs/web" {
+ *   interface RouteSearch {
+ *     "/reports": { page: number; q: string }
+ *   }
+ * }
+ * ```
+ *
+ * With that, `navigate({ to: "/reports", search: { page: 2 } })` type-checks `search` against
+ * `/reports`'s schema, and a wrong shape is a compile error. See {@link NavigateTarget}.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmentation target - empty by design, apps/codegen fill it.
+export interface RouteSearch {}
+
+/**
+ * The `search` type for a navigate to `To`: the route's schema output when `To` is a mapped
+ * {@link RouteSearch} key, otherwise the loose `Record<string, unknown>` (so a navigate to any path is
+ * always allowed). Keyed on `To` rather than a union, so a mapped route can't fall back to the loose form
+ * with a wrong shape - `navigate({ to: "/reports", search: { page: "x" } })` is a compile error.
+ */
+export type NavigateSearchOf<To extends string> = To extends keyof RouteSearch
+  ? RouteSearch[To]
+  : Record<string, unknown>
+
+/** The runtime shape of an object-form navigate target (loose - the typed narrowing lives in
+ * {@link NavigateFunction}'s generic call signature). `to` is a bare pathname; `search` is serialized
+ * onto it; `replace` folds into the options. */
+export interface NavigateTargetInput {
+  readonly to: string
+  readonly search?: Record<string, unknown>
+  readonly replace?: boolean
+}
+
+/**
+ * A programmatic navigate, shared by every adapter's `useNavigate`. Three forms: a string path (push, or
+ * replace via `{ replace: true }`), a history delta (`-1`/`1`), or an object target `{ to, search, replace }`
+ * whose `search` is typed against `to`'s route schema via {@link NavigateSearchOf} (a wrong shape for a
+ * mapped route is a compile error; an unmapped path takes a loose `search`). The object form's `search` is
+ * serialized onto `to`. A no-op on the server / before hydration.
+ */
+export interface NavigateFunction {
+  (to: string | number, options?: NavigateOptions): void
+  <To extends string>(target: {
+    readonly to: To
+    readonly search?: NavigateSearchOf<To>
+    readonly replace?: boolean
+  }): void
+}
+
+/**
+ * Normalize a navigate argument to the bridge's `(to, options)`: a string path or history-delta passes
+ * through; an object target has its `search` serialized onto `to` and its `replace` folded into the
+ * options. The one place the object form becomes a URL, so every adapter's `navigate` resolves it
+ * identically.
+ */
+export function resolveNavigate(
+  to: string | number | NavigateTargetInput,
+  options?: NavigateOptions,
+): { readonly to: string | number; readonly options: NavigateOptions | undefined } {
+  if (typeof to !== "object") return { to, options }
+  const query = to.search !== undefined ? serializeSearch(to.search) : ""
+  return { to: to.to + query, options: to.replace === true ? { replace: true } : options }
+}
+
 /**
  * A history-aware navigate. A **string** `to` is a same-origin path (`/users/7?tab=a`) navigated to
  * (push, or replace with `{ replace: true }`); a **number** is a history delta (`-1` back, `1`
@@ -29,7 +100,7 @@ export type BrowserNavigate = (to: string | number, options?: NavigateOptions) =
 // per page; absent on the server and before hydration.
 let browserNavigate: BrowserNavigate | undefined
 
-/** Register (or clear, with `undefined`) the browser navigate — called by `installHistory`. Not for
+/** Register (or clear, with `undefined`) the browser navigate - called by `installHistory`. Not for
  * app use. */
 export function setBrowserNavigate(navigate: BrowserNavigate | undefined): void {
   browserNavigate = navigate
@@ -40,3 +111,78 @@ export function setBrowserNavigate(navigate: BrowserNavigate | undefined): void
 export function getBrowserNavigate(): BrowserNavigate | undefined {
   return browserNavigate
 }
+
+/** A parsed navigation target the {@link BlockerFunction} decides on. `pathname`/`search`/`hash` match
+ * the DOM `Location` shape (search keeps its `?`, hash its `#`). */
+export interface BlockerLocation {
+  readonly pathname: string
+  readonly search: string
+  readonly hash: string
+}
+
+/**
+ * Decide whether a navigation should be halted. Receives where the app is (`currentLocation`) and where
+ * it's heading (`nextLocation`), so a guard can allow same-section moves and block only real exits. A
+ * boolean form (`useBlocker(isDirty)`) is sugar for `() => isDirty`. Runs synchronously at navigation
+ * time - return the current answer; the async "are you sure?" happens afterward via {@link Blocker}'s
+ * `proceed`/`reset`.
+ */
+export type BlockerFunction = (args: {
+  readonly currentLocation: BlockerLocation
+  readonly nextLocation: BlockerLocation
+}) => boolean
+
+/**
+ * The blocker's lifecycle. `unblocked` - idle, nothing intercepted. `blocked` - a navigation was halted
+ * and is awaiting the app's decision (`proceed`/`reset` are live). `proceeding` - the app called
+ * `proceed`; the held navigation is being replayed.
+ */
+export type BlockerState = "unblocked" | "blocked" | "proceeding"
+
+/**
+ * A navigation guard, mirroring react-router's shape. When `state` is `blocked`, `proceed()` lets the
+ * held navigation through and `reset()` cancels it (staying put); both are `undefined` otherwise. The
+ * pair is what a boolean `when` can't express - the app shows its OWN async confirmation UI, then calls
+ * one of them, instead of the browser's synchronous `confirm()`.
+ */
+export interface Blocker {
+  readonly state: BlockerState
+  readonly proceed: (() => void) | undefined
+  readonly reset: (() => void) | undefined
+}
+
+/** The idle blocker - a stable reference (no needless adapter re-renders while unblocked). */
+export const IDLE_BLOCKER: Blocker = { state: "unblocked", proceed: undefined, reset: undefined }
+
+/**
+ * The browser layer's blocker registry - installed by `installHistory` (which owns navigation and can
+ * therefore halt, restore, and replay it) and read by an adapter's `useBlocker` through
+ * {@link registerBlocker}. Kept here, DOM-free, for the same reason as {@link BrowserNavigate}: a route
+ * component's blocker hook must import only this agnostic entry.
+ */
+export interface BlockerController {
+  register(shouldBlock: BlockerFunction, onChange: (blocker: Blocker) => void): () => void
+}
+
+// The active controller (set by `installHistory`, cleared on teardown). Module-scoped: one app per page.
+let blockerController: BlockerController | undefined
+
+/** Register (or clear, with `undefined`) the blocker controller - called by `installHistory`. Not for
+ * app use. */
+export function setBlockerController(controller: BlockerController | undefined): void {
+  blockerController = controller
+}
+
+/**
+ * Register a navigation guard, returning an unregister function. `onChange` is called with the current
+ * {@link Blocker} whenever its state changes (so the adapter can re-render its confirmation UI). Before
+ * `installHistory` has run (SSR, pre-hydration), there's no controller: registration is a no-op and the
+ * caller stays on {@link IDLE_BLOCKER}, degrading to native navigation. Called by an adapter's
+ * `useBlocker`, not by app code directly.
+ */
+export function registerBlocker(
+  shouldBlock: BlockerFunction,
+  onChange: (blocker: Blocker) => void,
+): () => void {
+  return blockerController?.register(shouldBlock, onChange) ?? (() => {})
+}

package/src/plugins/kit.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web/plugins` shared kit — the small infrastructure every CSS-bearing asset plugin reuses, so
+ * `@nifrajs/web/plugins` shared kit - the small infrastructure every CSS-bearing asset plugin reuses, so
  * P1 (CSS Modules), P2 (SCSS), and any future P4 (LESS/Stylus/PostCSS) don't each re-implement the
  * CSS→client-bundle wiring, the deterministic hash, or the optional-peer guard. Internal to
  * `@nifrajs/web` (imported by the sibling plugin modules); not a public subpath.
@@ -8,7 +8,7 @@ import { existsSync } from "node:fs"
 import { dirname, relative } from "node:path"
 import type { BunPlugin } from "bun"
 
-/** The argument Bun passes to a plugin's `setup` — Bun doesn't export the type, so derive it. */
+/** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
 export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
 
 const packageRootCache = new Map<string, string>()
@@ -23,7 +23,7 @@ function packageRootOf(startDir: string): string {
     if (existsSync(`${dir}/package.json`)) break
     const parent = dirname(dir)
     if (parent === dir) {
-      dir = startDir // reached the filesystem root with no package.json — anchor on the file's own dir
+      dir = startDir // reached the filesystem root with no package.json - anchor on the file's own dir
       break
     }
     dir = parent
@@ -33,11 +33,11 @@ function packageRootOf(startDir: string): string {
 }
 
 /**
- * A **package-root-relative**, forward-slashed form of an absolute path — the input to {@link hash8} for
+ * A **package-root-relative**, forward-slashed form of an absolute path - the input to {@link hash8} for
  * any build-stable identifier (e.g. CSS-module scoped names). Anchoring on the file's nearest
  * `package.json` (not the absolute path, not `process.cwd()`) makes the result independent of BOTH the
- * machine's directory layout AND the working directory: the dom build and the ssr runtime — even on
- * different machines or from different cwds — derive the SAME relative path for a given file, so their
+ * machine's directory layout AND the working directory: the dom build and the ssr runtime - even on
+ * different machines or from different cwds - derive the SAME relative path for a given file, so their
  * scoped class maps always agree. (Hashing the absolute path would differ across CI/host; a
  * cwd-relative path would silently desync if the SSR server started from a non-project-root cwd.)
  */
@@ -47,7 +47,7 @@ export function reproduciblePath(absolutePath: string): string {
 }
 
 /**
- * Deterministic 8-hex hash (djb2/xor). Stable across builds — no `Date.now`/`Math.random` — so build
+ * Deterministic 8-hex hash (djb2/xor). Stable across builds - no `Date.now`/`Math.random` - so build
  * output is reproducible. The single hash implementation behind CSS-module scoped names (and a drop-in
  * for any SFC scope id).
  */
@@ -58,7 +58,7 @@ export function hash8(input: string): string {
 }
 
 /**
- * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module —
+ * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module -
  * the idiom the Vue plugin established (`?vue-css`). Register one per plugin `setup`; call `emit` per
  * file to stash its CSS and get back the `import` line to append to the JS module.
  */
@@ -70,7 +70,7 @@ export interface StylesheetEmitter {
 /**
  * Wire the virtual-CSS-module handlers onto `build` for `namespace`, returning an {@link StylesheetEmitter}.
  * The `namespace` must be a plain identifier (letters/`-`); it's used verbatim as the import suffix and
- * the Bun namespace. Only the `"dom"` build should emit CSS — the `"ssr"` build ships no stylesheet.
+ * the Bun namespace. Only the `"dom"` build should emit CSS - the `"ssr"` build ships no stylesheet.
  */
 export function createStylesheetEmitter(
   build: PluginBuilder,
@@ -97,7 +97,7 @@ export function createStylesheetEmitter(
 
 /**
  * Load an optional peer compiler at build time, throwing a consistent, actionable install-hint error if
- * it's absent — the `@vue/compiler-sfc` peer pattern, centralized. Build-time only, so the dynamic
+ * it's absent - the `@vue/compiler-sfc` peer pattern, centralized. Build-time only, so the dynamic
  * `import` (which keeps the peer out of the package's hard dependencies) is correct here.
  */
 export async function requirePeer<T>(
@@ -107,7 +107,7 @@ export async function requirePeer<T>(
   try {
     return (await import(specifier)) as T
   } catch (err) {
-    // Only a genuine resolution failure means "not installed" — surface anything else (a corrupt
+    // Only a genuine resolution failure means "not installed" - surface anything else (a corrupt
     // install, a native-binding error, a throw at module top-level) as the real error rather than
     // masking it behind a misleading "please install it" hint.
     if ((err as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND") {

package/src/plugins/scss.ts

@@ -1,17 +1,17 @@
 /**
- * `@nifrajs/web/plugins/scss` — a SASS/SCSS (`*.scss`, `*.sass`) Bun plugin, in its OWN module so the SSR
+ * `@nifrajs/web/plugins/scss` - a SASS/SCSS (`*.scss`, `*.sass`) Bun plugin, in its OWN module so the SSR
  * preload registers it BEFORE any Sass file loads. Mirrors the `@nifrajs/web-vue/plugin` seam: pass
  * `"dom"` for the client bundle (`buildClient({ plugins: [...] })`) and preload `"ssr"` for the server
  * (`bun --preload`).
  *
- * The Dart Sass compiler is an **optional peer** (`sass`, or the faster `sass-embedded` — same API), not
+ * The Dart Sass compiler is an **optional peer** (`sass`, or the faster `sass-embedded` - same API), not
  * a hard dependency: it's loaded on first Sass file and fails loud with an install hint if absent. Pass
  * your own `compiler` to override (e.g. `sass-embedded`, or a stub in tests).
  *
  * Composes with CSS Modules: a `*.module.scss` / `*.module.sass` file is compiled to CSS and then run
  * through the same scoped-class transform as `@nifrajs/web/plugins/css-modules`, so its `import styles`
  * yields the `{ original: scoped }` map (SSR/dom class-map parity included). A plain `*.scss` is a
- * side-effect import — its CSS is bundled (dom) and it resolves to an empty module (ssr).
+ * side-effect import - its CSS is bundled (dom) and it resolves to an empty module (ssr).
  */
 import { dirname } from "node:path"
 import { pathToFileURL } from "node:url"

package/src/plugins/vite-leak-guard.ts

@@ -0,0 +1,110 @@
+/**
+ * `@nifrajs/web/plugins/vite-leak-guard` - nifra's two client-leak guards, for a Vite/Rollup production
+ * build.
+ *
+ * ## Why this exists
+ *
+ * nifra's production default is Bun, and that is not changing: a Vite/Rollup production build inherits
+ * Rollup's build profile and gives up the Bun-native advantage nifra competes on. But some apps depend on
+ * a Vite-only transform that has no Bun equivalent, and for those a Vite production build is the escape
+ * hatch. The moment that hatch exists, the two client-leak guards have to come with it - they are security
+ * guards, not lints: one stops secrets and database access from shipping to a browser. A second production
+ * pipeline arriving WITHOUT them, or with a hastily re-implemented "mostly ported" copy, is the failure the
+ * neutral module-graph seam was built to prevent.
+ *
+ * So this is not a second implementation. The detection logic (`detectNodeBuiltinsInClient`,
+ * `detectServerOnlyInClient`) and the failure MESSAGES (`formatNodeBuiltinLeak`, `formatServerOnlyLeak`)
+ * are the exact same functions the Bun build calls. This plugin only adapts Rollup's bundle shape into the
+ * neutral `ClientModuleGraph` (`fromRollupBundle`) and runs them. A leak reads identically whichever
+ * bundler produced it, and there is one place to change if a guard changes.
+ *
+ * ## How
+ *
+ * In `generateBundle` the whole client graph is available: each output chunk lists its `moduleIds`, and
+ * `this.getModuleInfo(id)` gives each module's resolved import edges. That is exactly what
+ * `fromRollupBundle` needs. Findings fail the build through Rollup's `this.error`, so the message lands in
+ * the build output the same way a Bun-build throw does.
+ *
+ * Add it to the `plugins` of a Vite production build (the LAST plugin, so it sees the final graph):
+ *
+ *   // vite.config.ts (production client build)
+ *   import { viteLeakGuard } from "@nifrajs/web/plugins/vite-leak-guard"
+ *   export default { build: { rollupOptions: { plugins: [viteLeakGuard()] } } }
+ */
+import {
+  detectNodeBuiltinsInClient,
+  detectServerOnlyInClient,
+  formatNodeBuiltinLeak,
+  formatServerOnlyLeak,
+} from "../build.ts"
+import { fromRollupBundle, type RollupBundleLike } from "../module-graph.ts"
+
+/**
+ * The Rollup plugin-context slice this uses: `getModuleInfo` for a module's resolved imports, and `error`
+ * to fail the build. Typed structurally so the file needs no `rollup`/`vite` type dependency.
+ */
+interface RollupPluginContext {
+  getModuleInfo(id: string): {
+    readonly importedIds?: readonly string[]
+    readonly dynamicallyImportedIds?: readonly string[]
+  } | null
+  /**
+   * Takes an `Error`, never a string.
+   *
+   * Handed a string, rolldown synthesizes its own error type and calls `Error.captureStackTrace` on a
+   * plain object - which Bun rejects with "First argument must be an Error object", and THAT becomes the
+   * build failure. The guard still fires, but its message is replaced by an internal one naming nothing,
+   * so a real client leak reports as a stack-trace complaint. Passing an Error skips that construction
+   * entirely and the message survives.
+   */
+  error(error: Error): never
+}
+
+/** The minimal Rollup plugin shape this returns - `generateBundle` bound to the plugin context. */
+export interface LeakGuardPlugin {
+  readonly name: string
+  /**
+   * The finding that failed the build, or `undefined` when the bundle was clean.
+   *
+   * Recorded as well as thrown because the throw does not reliably survive. A plugin error is handed to
+   * the bundler, which builds its own error to report it, and on some Bun + rolldown combinations that
+   * construction itself fails (`Error.captureStackTrace` rejecting a non-Error) - so what surfaces is an
+   * internal complaint naming neither the leaked module nor its import chain. A caller that owns the
+   * build can read this afterwards and raise the real message from its own code, where nothing can
+   * rewrite it. A leak is the one failure that must stay legible: the whole point is naming what
+   * reached the browser.
+   */
+  leak?: string
+  generateBundle(this: RollupPluginContext, options: unknown, bundle: RollupBundleLike): void
+}
+
+/**
+ * A Vite/Rollup plugin that fails the build when server-only code or a `node:` builtin reaches the client
+ * bundle - the same two guards, and the same error messages, as nifra's Bun production build.
+ */
+export function viteLeakGuard(): LeakGuardPlugin {
+  const plugin: LeakGuardPlugin = {
+    name: "nifra:leak-guard",
+    generateBundle(_options, bundle) {
+      // Resolved import edges per module, straight from Rollup's graph. Dynamic imports count too: a
+      // `node:`/server-only module reached only via `import()` still ships to the browser.
+      const importsOf = (id: string): readonly string[] => {
+        const info = this.getModuleInfo(id)
+        if (info === null) return []
+        return [...(info.importedIds ?? []), ...(info.dynamicallyImportedIds ?? [])]
+      }
+      const graph = fromRollupBundle(bundle, importsOf)
+      // Node-builtin guard first, then server-only - the same order as the Bun build, so the first error a
+      // dev sees is the same across pipelines when a module trips both.
+      const leak =
+        formatNodeBuiltinLeak(detectNodeBuiltinsInClient(graph)) ??
+        formatServerOnlyLeak(detectServerOnlyInClient(graph))
+      if (leak === undefined) return
+      // Record before throwing: the throw is what fails the build for a standalone user of this plugin,
+      // and the record is what lets a caller that owns the build re-raise the real message (see `leak`).
+      plugin.leak = leak
+      this.error(new Error(leak))
+    },
+  }
+  return plugin
+}

package/src/plugins/vite-server-fn.ts

@@ -0,0 +1,67 @@
+/**
+ * `@nifrajs/web/plugins/vite-server-fn` - the Vite half of the server-function client transform.
+ *
+ * A `*.fn` module must never reach a browser: it holds the function bodies and everything they import.
+ * The Bun build replaces each one with client stubs, and this does the same for Vite, in both the dev
+ * server and the production build.
+ *
+ * ## Why the generation is not in here
+ *
+ * The stub text comes from `internal/server-boundary.ts`, shared verbatim with the Bun plugin. Two
+ * implementations of "what a stub looks like" would drift, and the drift would be invisible until a
+ * client that worked in dev 404'd in production - the exact shape of failure this codebase has already
+ * paid for once. A parity test asserts both pipelines emit the same bytes.
+ *
+ * ## Why `transform` and not `load`
+ *
+ * Vite resolves and reads the file itself; taking `load` would mean re-implementing its resolution.
+ * `transform` receives the source Vite already read, and returning replacement code discards the
+ * original along with its imports - so the server subtree is never followed. `enforce: "pre"` puts this
+ * ahead of framework transforms, which have no business seeing server code either.
+ */
+import {
+  generateServerFnStub,
+  SERVER_FN_MODULE,
+  serverFnNamespace,
+} from "../internal/server-boundary.ts"
+
+/** The slice of a Vite/Rollup plugin this returns. Structural, so `vite` stays an optional peer. */
+export interface ServerFnStubPlugin {
+  readonly name: string
+  readonly enforce: "pre"
+  /** Applied only to the CLIENT build; the server build keeps the real module. */
+  readonly applyToEnvironment?: (environment: { readonly name: string }) => boolean
+  transform(
+    code: string,
+    id: string,
+    options?: { readonly ssr?: boolean },
+  ): { code: string; map: null } | null
+}
+
+/** Strips a Vite id's `?query` and `#hash` so the suffix test sees a plain path. */
+const bare = (id: string): string => id.split("?")[0]?.split("#")[0] ?? id
+
+/**
+ * Replace every `*.fn` module with its client stubs.
+ *
+ * Client-only by construction: nifra passes this to the client build and the dev server, never to the
+ * SSR build, because the server is what actually runs these functions.
+ */
+export function viteServerFnStub(): ServerFnStubPlugin {
+  return {
+    name: "nifra:server-fn-stub",
+    enforce: "pre",
+    // Vite 6+ environments: the SSR environment must keep the real module. Older Vite ignores this and
+    // relies on nifra only registering the plugin on the client side.
+    applyToEnvironment: (environment) => environment.name === "client",
+    transform(code, id, options) {
+      // Vite 5 ignores `applyToEnvironment` but supplies this transform context for SSR.
+      if (options?.ssr === true) return null
+      const path = bare(id)
+      if (!SERVER_FN_MODULE.test(path)) return null
+      // `map: null` is honest rather than lazy: the stub shares no lines with the source, so any
+      // mapping would point a debugger at unrelated code.
+      return { code: generateServerFnStub(code, serverFnNamespace(path)), map: null }
+    },
+  }
+}