@nifrajs/web 2.0.0 → 2.2.0

package/src/internal/timing-safe-equal.ts

@@ -0,0 +1,24 @@
+/**
+ * Constant-time string equality, shared by every secret check in `@nifrajs/web`. Internal: no
+ * `exports` entry points here, so it never becomes public API.
+ *
+ * One owner per package rather than a copy per call site — this is the primitive whose whole value
+ * lies in a detail (no early exit) that a well-meaning "simplification" silently removes, and a bug
+ * in it is invisible in review and in tests, since a timing-unsafe compare returns the same answers.
+ */
+
+/**
+ * Compare two strings without leaking, via timing, where they first differ. A length mismatch returns
+ * `false` up front: the length isn't the secret, and different-length buffers can't be compared in
+ * constant time anyway. Encodes to bytes first so multi-byte characters compare by content, not by
+ * UTF-16 code unit.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  const enc = new TextEncoder()
+  const ba = enc.encode(a)
+  const bb = enc.encode(b)
+  if (ba.length !== bb.length) return false
+  let diff = 0
+  for (let i = 0; i < ba.length; i++) diff |= (ba[i] as number) ^ (bb[i] as number)
+  return diff === 0
+}

package/src/isr.ts

@@ -7,6 +7,7 @@
  * This module is the store primitive; the SWR wrapper (`withISR`) builds on it next.
  */
 import { isDraftEnabled } from "./draft.ts"
+import { timingSafeEqual } from "./internal/timing-safe-equal.ts"
 
 /** A cached SSR response — the bytes + metadata a {@link CacheStore} persists. */
 export interface CachedResponse {
@@ -406,19 +407,6 @@ export function withISR(
 const jsonError = (status: number, error: string): Response =>
   Response.json({ ok: false, error }, { status })
 
-/** Constant-time string equality (XOR-accumulate, no early exit). A length mismatch returns `false`
- * up front — the length isn't the secret, and different-length buffers can't be compared in constant
- * time anyway. Used to check the on-demand revalidation token without leaking it via timing. */
-function timingSafeEqual(a: string, b: string): boolean {
-  const enc = new TextEncoder()
-  const ba = enc.encode(a)
-  const bb = enc.encode(b)
-  if (ba.length !== bb.length) return false
-  let diff = 0
-  for (let i = 0; i < ba.length; i++) diff |= (ba[i] as number) ^ (bb[i] as number)
-  return diff === 0
-}
-
 export interface RevalidateEndpointOptions {
   readonly store: CacheStore
   /** Shared secret; the request's token must match it (constant-time). */

package/src/llms-txt.ts

@@ -91,11 +91,19 @@ export async function generateLlmsTxt(
   // 1. Project Guidelines
   let agentsMd = ""
   try {
-    if (typeof Bun !== "undefined") {
-      agentsMd = await Bun.file("AGENTS.md").text()
-    } else {
-      const fs = await import("node:fs/promises")
-      agentsMd = await fs.readFile("AGENTS.md", "utf-8")
+    // Edge bundles define this flag and dead-code-eliminate the filesystem branch. Keeping the import
+    // behind a runtime-only `typeof Bun` check is insufficient: Rollup must still emit an unresolved
+    // `node:` dependency, which workerd cannot load.
+    const edgeRuntime = (
+      globalThis as typeof globalThis & { readonly __NIFRA_EDGE_RUNTIME__?: boolean }
+    ).__NIFRA_EDGE_RUNTIME__
+    if (edgeRuntime !== true) {
+      if (typeof Bun !== "undefined") {
+        agentsMd = await Bun.file("AGENTS.md").text()
+      } else {
+        const fs = await import("node:fs/promises")
+        agentsMd = await fs.readFile("AGENTS.md", "utf-8")
+      }
     }
   } catch {
     // ignore

package/src/manifest.ts

@@ -89,6 +89,23 @@ export interface Meta {
   readonly link?: readonly LinkDescriptor[]
   /** Inert head `<script>`s (JSON-LD structured data, etc.). See {@link ScriptDescriptor}. */
   readonly script?: readonly ScriptDescriptor[]
+  /**
+   * The document language — `<html lang="...">`. Nearest-wins like `title`, so a localized route can
+   * override a layout's default. Defaults to `"en"` when no head in the chain sets it.
+   *
+   * This is the ONLY way to set it: the shell's `<html>` is framework-owned, so a multilingual app
+   * otherwise serves every URL as `lang="en"` — which tells a screen reader to pronounce every locale
+   * with an English voice, and suppresses the browser's translation offer.
+   */
+  readonly lang?: string
+  /**
+   * The document writing direction — `<html dir="...">`. Nearest-wins like `title`. Omitted from the
+   * shell when unset, which is HTML's `ltr` default, so an LTR app's output is byte-identical.
+   *
+   * Required for Arabic/Hebrew/Urdu/Persian: without it the browser lays the page out left-to-right
+   * and mis-orders trailing punctuation, so the text renders wrong rather than merely unstyled.
+   */
+  readonly dir?: "ltr" | "rtl" | "auto"
 }
 
 /**
@@ -195,6 +212,16 @@ export interface RouteEntry {
   readonly id: string
   readonly pattern: string
   readonly layoutIds: readonly string[]
+  /**
+   * Param names each layout in {@link layoutIds} owns, aligned by index.
+   *
+   * A layout wraps a URL prefix, so these are the params it may read and the ones whose change should
+   * re-run its loader - everything deeper belongs to routes beneath it. Derived per (route, layout)
+   * pair rather than per layout, because one layout can own different params on different expanded
+   * patterns: `[[lang]]/docs/_layout` owns nothing on `/docs/:slug` and `{lang}` on `/:lang/docs/:slug`.
+   * Optional only so hand-built test manifests may omit it.
+   */
+  readonly layoutParams?: ReadonlyArray<readonly string[]>
   /** `_error` boundary ids in this route's ancestor chain (outermost → innermost). The last is the
    * **nearest** boundary, rendered when the route's loader throws. Always set by `buildManifest`
    * (optional only so hand-built test manifests may omit it); absent/empty ⇒ no boundary (error 500s). */
@@ -211,6 +238,11 @@ export interface Manifest {
    * `buildManifest` (optional only so hand-built test manifests may omit it). */
   readonly errors?: Readonly<Record<string, LayoutEntry>>
   readonly notFound?: LayoutEntry
+  /** Per-status terminal pages from `_<status>.tsx` at the routes root (`_410`, `_451`, …), keyed by
+   * the status as a string. Rendered by a loader's `gone()` / `statusPage(n)`; a status with no page
+   * falls back to `_404`, and then to plain text. `_404` itself stays on {@link notFound} - it is
+   * reached by unmatched paths too, which these are not. */
+  readonly statusPages?: Readonly<Record<string, LayoutEntry>>
 }
 
 // `.svelte` and `.vue` routes are supported too: their `default` export is the component and
@@ -226,6 +258,10 @@ const OPTIONAL = /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/
 // A route group: a `(name)` folder organizes routes (and can hold its own `_layout`) without
 // contributing a URL segment — mirrors Next/Remix. Requires content between the parens.
 const GROUP = /^\(.+\)$/
+// A terminal status page: `_410.tsx`, `_451.tsx`. `_404` is matched before this and stays its own
+// thing. Restricted to 3 digits so `_401k` or `_4` is treated as an ordinary underscore-prefixed
+// file (ignored) rather than silently becoming a status page.
+const STATUS_PAGE = /^_[1-5][0-9][0-9]$/
 
 const stripExt = (file: string): string => file.replace(ROUTE_EXT, "")
 const baseName = (file: string): string => file.slice(file.lastIndexOf("/") + 1)
@@ -242,14 +278,112 @@ const errorIdFor = (dir: string): string => (dir === "" ? "_error" : `${dir}/_er
  * with no optionals yields exactly one pattern. Throws on an invalid param or a catch-all that isn't
  * the last segment.
  */
+/** Every `[…]` marker in a file segment, so a part-literal segment can be spliced into a pattern. */
+const FILE_MARKER = /\[([^\]]*)\]/g
+const FILE_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * Translate a part-literal-part-`[param]` file segment into its route pattern, or `undefined` when
+ * the segment is wholly literal or wholly a marker (both already handled by the caller).
+ *
+ * `[inKey].txt` becomes `:inKey.txt`. Needed because IndexNow-style verification files, per-locale
+ * sitemaps, and static-site URL parity (`post-[id].html`) all put a variable INSIDE a filename, and
+ * `stripExt` already reduces `[inKey].txt.tsx` to `[inKey].txt` - `robots.txt.tsx` proves literal
+ * dots survive into a segment, so this was only ever a parser gap.
+ *
+ * `[[optional]]` and `[...catchAll]` are **rejected** inside a mixed segment rather than given a
+ * meaning. There is no sensible absent form for `/[[locale]]-feed.xml` - `/-feed.xml` and dropping
+ * the segment are both surprising - and a catch-all captures the remaining path verbatim, which
+ * conflicts with a trailing literal. A clear rejection beats semantics nobody can predict.
+ */
+function mixedFileSegment(seg: string, file: string): string | undefined {
+  // A segment that is ENTIRELY one of the existing whole-segment forms belongs to the caller, not
+  // here. Checked against the real patterns rather than by comparing the first marker to the
+  // segment: `[[lang]]` does not equal its own first `[…]` match, so a naive comparison sends every
+  // optional segment down the mixed path and rejects it.
+  if (PARAM.test(seg) || OPTIONAL.test(seg) || CATCH_ALL.test(seg)) return undefined
+  const markers = [...seg.matchAll(FILE_MARKER)]
+  if (markers.length === 0) return undefined
+
+  let pattern = ""
+  let cursor = 0
+  for (const marker of markers) {
+    const inner = marker[1] ?? ""
+    if (inner.startsWith("...")) {
+      throw new Error(
+        `[nifra/web] catch-all "[${inner}]" cannot be combined with literal text in "${file}" (segment "${seg}") — a catch-all captures the rest of the path, so a trailing literal can never match. Give it its own segment.`,
+      )
+    }
+    if (inner.startsWith("[")) {
+      throw new Error(
+        `[nifra/web] optional "[${inner}]]" cannot be combined with literal text in "${file}" (segment "${seg}") — there is no sensible form for the segment when it is absent. Use a required [name], or give the optional its own segment.`,
+      )
+    }
+    if (!FILE_PARAM_NAME.test(inner)) {
+      throw new Error(
+        `[nifra/web] invalid route param in "${file}": "[${inner}]" must be [name], [[name]], [...name], or a (group) folder`,
+      )
+    }
+    pattern += `${seg.slice(cursor, marker.index)}:${inner}`
+    cursor = (marker.index ?? 0) + marker[0].length
+  }
+  return pattern + seg.slice(cursor)
+}
+
 export function filePathToPatterns(file: string): string[] {
-  // Each combo is a list of URL segments built so far; an optional segment doubles the set.
-  let combos: string[][] = [[]]
+  return filePathToRoutes(file).map((route) => route.pattern)
+}
+
+/** One URL pattern a route file expands to, plus the scope information layouts need. */
+export interface FileRoutePattern {
+  readonly pattern: string
+  /**
+   * URL segments contributed by the first *k* path parts of the file, indexed by *k*.
+   *
+   * This is what makes a layout's scope derivable without turning layouts into router nodes. A layout
+   * lives at a directory; the segments that directory contributes are exactly the prefix of the URL it
+   * wraps, so `depths[partsIn(layoutDir)]` is how many leading pattern segments it owns - and the
+   * params inside that prefix are the ones it may read.
+   *
+   * Per EXPANDED pattern, not per file, because the two diverge: `[[lang]]/docs/_layout` owns nothing
+   * on `/docs/:slug` and `{lang}` on `/:lang/docs/:slug`. A route group contributes no segment, so
+   * `(marketing)/_layout` owns nothing at all.
+   */
+  readonly depths: readonly number[]
+}
+
+/** Expand a route file into its URL patterns, each carrying per-directory segment counts. */
+export function filePathToRoutes(file: string): FileRoutePattern[] {
+  // Each combo is the URL segments built so far, plus the running per-path-part segment count.
+  let combos: Array<{ segs: string[]; depths: number[] }> = [{ segs: [], depths: [0] }]
   const segments = stripExt(file).split("/")
+  // Record the running segment count after each path part, on every combo. Called once per part so
+  // `depths` stays index-aligned with the file's path parts even for parts that emit nothing.
+  const mark = (): void => {
+    for (const combo of combos) combo.depths.push(combo.segs.length)
+  }
+  const push = (segment: string): void => {
+    for (const combo of combos) combo.segs.push(segment)
+  }
   for (let i = 0; i < segments.length; i++) {
     const seg = segments[i]!
-    if (seg === "index") continue
-    if (GROUP.test(seg)) continue // route group — no URL segment (its `_layout` still applies, keyed by dir)
+    if (seg === "index") {
+      mark()
+      continue
+    }
+    if (GROUP.test(seg)) {
+      // Route group — no URL segment (its `_layout` still applies, keyed by dir).
+      mark()
+      continue
+    }
+    // A segment that is part literal, part `[param]` — `[inKey].txt`, `post-[id].html`. Checked
+    // before the whole-segment forms below, which only handle a marker spanning the entire segment.
+    const mixed = mixedFileSegment(seg, file)
+    if (mixed !== undefined) {
+      push(mixed)
+      mark()
+      continue
+    }
     if (seg.startsWith("[")) {
       const catchAll = CATCH_ALL.exec(seg)
       if (catchAll !== null) {
@@ -261,13 +395,18 @@ export function filePathToPatterns(file: string): string[] {
             `[nifra/web] catch-all "${seg}" must be the last segment in "${file}" (found "${after.join("/")}" after it)`,
           )
         }
-        combos = combos.map((c) => [...c, `*${catchAll[1]}`])
+        push(`*${catchAll[1]}`)
+        mark()
         continue
       }
       const optional = OPTIONAL.exec(seg)
       if (optional !== null) {
         // Optional segment: keep each existing combo (absent) AND a copy with `:name` appended (present).
-        combos = combos.flatMap((c) => [c, [...c, `:${optional[1]}`]])
+        combos = combos.flatMap((c) => [
+          { segs: c.segs, depths: c.depths },
+          { segs: [...c.segs, `:${optional[1]}`], depths: [...c.depths] },
+        ])
+        mark()
         continue
       }
       const match = PARAM.exec(seg)
@@ -276,12 +415,13 @@ export function filePathToPatterns(file: string): string[] {
           `[nifra/web] invalid route param in "${file}": "${seg}" must be [name], [[name]], [...name], or a (group) folder`,
         )
       }
-      combos = combos.map((c) => [...c, `:${match[1]}`])
+      push(`:${match[1]}`)
     } else {
-      combos = combos.map((c) => [...c, seg])
+      push(seg)
     }
+    mark()
   }
-  return combos.map((c) => `/${c.join("/")}`)
+  return combos.map((c) => ({ pattern: `/${c.segs.join("/")}`, depths: c.depths }))
 }
 
 /**
@@ -295,6 +435,26 @@ export function filePathToPattern(file: string): string {
 }
 
 /** The dir chain from root → the file's own dir, e.g. "a/b/p.tsx" → ["", "a", "a/b"]. */
+/**
+ * Param names in the first `count` segments of a pattern - the params a layout at that depth owns.
+ *
+ * This is the whole scoping mechanism: a layout wraps a URL prefix, so the params inside that prefix
+ * are the ones it may read, and the ones whose change should re-run its loader. Everything deeper
+ * belongs to routes below it and must not invalidate it.
+ */
+function paramsInPrefix(pattern: string, count: number): string[] {
+  if (count === 0) return []
+  const names: string[] = []
+  const segments = pattern === "/" ? [] : pattern.slice(1).split("/")
+  for (const segment of segments.slice(0, count)) {
+    // Mirrors the router's own grammar: `:name`, `*name`, and a mixed segment's embedded `:name`s.
+    for (const match of segment.matchAll(/[:*]([A-Za-z_][A-Za-z0-9_]*)/g)) {
+      names.push(match[1] as string)
+    }
+  }
+  return names
+}
+
 const ancestorDirs = (file: string): string[] => {
   const dirs = [""]
   const dir = dirOf(file)
@@ -322,6 +482,7 @@ export function buildManifest(
   const errorDirs = new Set<string>()
   const errors: Record<string, LayoutEntry> = {}
   let notFound: LayoutEntry | undefined
+  const statusPages: Record<string, LayoutEntry> = {}
   const routeFiles: string[] = []
 
   for (const file of files) {
@@ -336,6 +497,11 @@ export function buildManifest(
       errors[errorIdFor(dir)] = { file, load: importer(file) }
     } else if (stem === "_404") {
       notFound = { file, load: importer(file) }
+    } else if (STATUS_PAGE.test(stem) && dirOf(file) === "") {
+      // `_410.tsx`, `_451.tsx`, … at the routes root. Root-only: unlike `_error`, these are not
+      // resolved per segment - a terminal status is a property of the outcome, not of where in the
+      // tree the route lives, and a per-segment variant would need a precedence rule nobody asked for.
+      statusPages[stem.slice(1)] = { file, load: importer(file) }
     } else if (!stem.startsWith("_")) {
       routeFiles.push(file)
     }
@@ -345,13 +511,14 @@ export function buildManifest(
   const routes: RouteEntry[] = []
   for (const file of routeFiles) {
     const dirs = ancestorDirs(file)
-    const layoutIds = dirs.filter((dir) => layoutDirs.has(dir)).map(layoutIdFor)
+    const layoutDirsForFile = dirs.filter((dir) => layoutDirs.has(dir))
+    const layoutIds = layoutDirsForFile.map(layoutIdFor)
     const errorIds = dirs.filter((dir) => errorDirs.has(dir)).map(errorIdFor)
     const id = stripExt(file)
     const load = importer(file) // one lazy loader per file, shared by its (possibly expanded) patterns
     // An optional `[[x]]` segment expands a file into multiple patterns, all pointing at the same
     // module (same id/load/layout chain). Distinct patterns ⇒ no match ambiguity (different lengths).
-    for (const pattern of filePathToPatterns(file)) {
+    for (const { pattern, depths } of filePathToRoutes(file)) {
       const existing = byPattern.get(pattern)
       if (existing !== undefined) {
         throw new Error(
@@ -359,11 +526,19 @@ export function buildManifest(
         )
       }
       byPattern.set(pattern, file)
-      routes.push({ id, pattern, layoutIds, errorIds, file, load })
+      const layoutParams = layoutDirsForFile.map((dir) =>
+        paramsInPrefix(pattern, depths[dir === "" ? 0 : dir.split("/").length] ?? 0),
+      )
+      routes.push({ id, pattern, layoutIds, layoutParams, errorIds, file, load })
     }
   }
 
-  const base: Manifest = { routes, layouts, errors }
+  const base: Manifest = {
+    routes,
+    layouts,
+    errors,
+    ...(Object.keys(statusPages).length > 0 ? { statusPages } : {}),
+  }
   return notFound === undefined ? base : { ...base, notFound }
 }
 

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/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
+}