@nifrajs/web 2.1.0 → 2.3.0

package/dist/plugins/kit.js

@@ -7,7 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 /**
- * `@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.
@@ -27,7 +27,7 @@ function packageRootOf(startDir) {
             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;
@@ -36,11 +36,11 @@ function packageRootOf(startDir) {
     return dir;
 }
 /**
- * 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.)
  */
@@ -49,7 +49,7 @@ export function reproduciblePath(absolutePath) {
     return relative(root, absolutePath).replaceAll("\\", "/");
 }
 /**
- * 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).
  */
@@ -62,7 +62,7 @@ export function hash8(input) {
 /**
  * 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, namespace) {
     const suffix = `?${namespace}`;
@@ -85,7 +85,7 @@ export function createStylesheetEmitter(build, namespace) {
 }
 /**
  * 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(specifier, hint) {
@@ -93,7 +93,7 @@ export async function requirePeer(specifier, hint) {
         return (await import(__rewriteRelativeImportExtension(specifier)));
     }
     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.code === "ERR_MODULE_NOT_FOUND") {

package/dist/plugins/scss.js

@@ -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/dist/plugins/vite-leak-guard.d.ts

@@ -0,0 +1,45 @@
+import { type RollupBundleLike } from "../module-graph.js";
+/**
+ * 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 declare function viteLeakGuard(): LeakGuardPlugin;
+export {};
+//# sourceMappingURL=vite-leak-guard.d.ts.map

package/dist/plugins/vite-leak-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-leak-guard.d.ts","sourceRoot":"","sources":["../../src/plugins/vite-leak-guard.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE5E;;;GAGG;AACH,UAAU,mBAAmB;IAC3B,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG;QACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QACxC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KACpD,GAAG,IAAI,CAAA;IACR;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAA;CAC3B;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAC5F;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,eAAe,CAyB/C"}

package/dist/plugins/vite-leak-guard.js

@@ -0,0 +1,67 @@
+/**
+ * `@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.js";
+import { fromRollupBundle } from "../module-graph.js";
+/**
+ * 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() {
+    const plugin = {
+        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) => {
+                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;
+}
+//# sourceMappingURL=vite-leak-guard.js.map

package/dist/plugins/vite-leak-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-leak-guard.js","sourceRoot":"","sources":["../../src/plugins/vite-leak-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,gBAAgB,EAAyB,MAAM,oBAAoB,CAAA;AAyC5E;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,MAAM,GAAoB;QAC9B,IAAI,EAAE,kBAAkB;QACxB,cAAc,CAAC,QAAQ,EAAE,MAAM;YAC7B,+FAA+F;YAC/F,qFAAqF;YACrF,MAAM,SAAS,GAAG,CAAC,EAAU,EAAqB,EAAE;gBAClD,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAA;gBACnC,IAAI,IAAI,KAAK,IAAI;oBAAE,OAAO,EAAE,CAAA;gBAC5B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,CAAA;YAC9E,CAAC,CAAA;YACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;YACjD,qGAAqG;YACrG,kEAAkE;YAClE,MAAM,IAAI,GACR,qBAAqB,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC;gBACxD,oBAAoB,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAA;YACvD,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAM;YAC9B,kGAAkG;YAClG,mGAAmG;YACnG,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;YAClB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;QAC7B,CAAC;KACF,CAAA;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/plugins/vite-server-fn.d.ts

@@ -0,0 +1,23 @@
+/** 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;
+}
+/**
+ * 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 declare function viteServerFnStub(): ServerFnStubPlugin;
+//# sourceMappingURL=vite-server-fn.d.ts.map

package/dist/plugins/vite-server-fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-server-fn.d.ts","sourceRoot":"","sources":["../../src/plugins/vite-server-fn.ts"],"names":[],"mappings":"AA2BA,oGAAoG;AACpG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,gFAAgF;IAChF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAA;IACjF,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,GACnC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;CACtC;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CAiBrD"}

package/dist/plugins/vite-server-fn.js

@@ -0,0 +1,51 @@
+/**
+ * `@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.js";
+/** Strips a Vite id's `?query` and `#hash` so the suffix test sees a plain path. */
+const bare = (id) => 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() {
+    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 };
+        },
+    };
+}
+//# sourceMappingURL=vite-server-fn.js.map

package/dist/plugins/vite-server-fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-server-fn.js","sourceRoot":"","sources":["../../src/plugins/vite-server-fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gCAAgC,CAAA;AAevC,oFAAoF;AACpF,MAAM,IAAI,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,KAAK;QACd,mGAAmG;QACnG,kEAAkE;QAClE,kBAAkB,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ;QAClE,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO;YACzB,mFAAmF;YACnF,IAAI,OAAO,EAAE,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAA;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAA;YACrB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC7C,2FAA2F;YAC3F,oDAAoD;YACpD,OAAO,EAAE,IAAI,EAAE,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;QACjF,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/plugins/vite-server-only.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `@nifrajs/web/plugins/vite-server-only` - the Vite half of the `.server` convention.
+ *
+ * A module named `*.server.ts(x)` is server-only: the Bun client build empties it so its import
+ * subtree - `node:` builtins, native modules, secrets - never reaches a browser. This does the same
+ * for Vite, in both the dev server and the production build.
+ *
+ * ## Why this exists separately
+ *
+ * The convention was implemented once, as a `Bun.build` plugin, which meant it held in exactly one of
+ * the four pipelines. `nifra build` emptied the module; `nifra dev` (Vite), a Vite production build,
+ * and `nifra dev --bun` all shipped it whole. A guard that holds in one pipeline and not the others is
+ * worse than none, because the file name reads as protection everywhere.
+ *
+ * `*.fn` already had this shape - a Bun plugin, a Vite plugin, and a refusal in the one pipeline that
+ * cannot transform. `.server` now matches it.
+ *
+ * ## 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 { SERVER_ONLY_MODULE, SERVER_ONLY_REPLACEMENT, viteServerOnlyReplacement } from "../internal/server-boundary.js";
+export { SERVER_ONLY_MODULE, SERVER_ONLY_REPLACEMENT, viteServerOnlyReplacement };
+/** The slice of a Vite/Rollup plugin this returns. Structural, so `vite` stays an optional peer. */
+export interface ServerOnlyEmptyPlugin {
+    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;
+}
+/**
+ * Empty every `*.server` module in the client build.
+ *
+ * Client-only by construction: nifra passes this to the client build and the dev server, never to the
+ * SSR build, where the real module is what runs.
+ */
+export declare function viteServerOnlyEmpty(): ServerOnlyEmptyPlugin;
+//# sourceMappingURL=vite-server-only.d.ts.map

package/dist/plugins/vite-server-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-server-only.d.ts","sourceRoot":"","sources":["../../src/plugins/vite-server-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,gCAAgC,CAAA;AAIvC,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,CAAA;AAEjF,oGAAoG;AACpG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,gFAAgF;IAChF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAA;IACjF,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,GACnC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;CACtC;AAKD;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,qBAAqB,CAiB3D"}

package/dist/plugins/vite-server-only.js

@@ -0,0 +1,57 @@
+/**
+ * `@nifrajs/web/plugins/vite-server-only` - the Vite half of the `.server` convention.
+ *
+ * A module named `*.server.ts(x)` is server-only: the Bun client build empties it so its import
+ * subtree - `node:` builtins, native modules, secrets - never reaches a browser. This does the same
+ * for Vite, in both the dev server and the production build.
+ *
+ * ## Why this exists separately
+ *
+ * The convention was implemented once, as a `Bun.build` plugin, which meant it held in exactly one of
+ * the four pipelines. `nifra build` emptied the module; `nifra dev` (Vite), a Vite production build,
+ * and `nifra dev --bun` all shipped it whole. A guard that holds in one pipeline and not the others is
+ * worse than none, because the file name reads as protection everywhere.
+ *
+ * `*.fn` already had this shape - a Bun plugin, a Vite plugin, and a refusal in the one pipeline that
+ * cannot transform. `.server` now matches it.
+ *
+ * ## 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 { SERVER_ONLY_MODULE, SERVER_ONLY_REPLACEMENT, viteServerOnlyReplacement, } from "../internal/server-boundary.js";
+// Re-exported so a caller wiring its own bundler gets the matcher from the same owner the pipelines
+// use, rather than writing a fifth copy of the regex.
+export { SERVER_ONLY_MODULE, SERVER_ONLY_REPLACEMENT, viteServerOnlyReplacement };
+/** Strips a Vite id's `?query` and `#hash` so the suffix test sees a plain path. */
+const bare = (id) => id.split("?")[0]?.split("#")[0] ?? id;
+/**
+ * Empty every `*.server` module in the client build.
+ *
+ * Client-only by construction: nifra passes this to the client build and the dev server, never to the
+ * SSR build, where the real module is what runs.
+ */
+export function viteServerOnlyEmpty() {
+    return {
+        name: "nifra:server-only-empty",
+        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_ONLY_MODULE.test(path))
+                return null;
+            // `map: null` is honest rather than lazy: the replacement shares no lines with the source, so any
+            // mapping would point a debugger at unrelated code.
+            return { code: viteServerOnlyReplacement(code), map: null };
+        },
+    };
+}
+//# sourceMappingURL=vite-server-only.js.map

package/dist/plugins/vite-server-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-server-only.js","sourceRoot":"","sources":["../../src/plugins/vite-server-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,gCAAgC,CAAA;AAEvC,oGAAoG;AACpG,sDAAsD;AACtD,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,CAAA;AAejF,oFAAoF;AACpF,MAAM,IAAI,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,KAAK;QACd,mGAAmG;QACnG,kEAAkE;QAClE,kBAAkB,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ;QAClE,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO;YACzB,mFAAmF;YACnF,IAAI,OAAO,EAAE,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAA;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAA;YACrB,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC/C,kGAAkG;YAClG,oDAAoD;YACpD,OAAO,EAAE,IAAI,EAAE,yBAAyB,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;QAC7D,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/prerender.d.ts

@@ -1,5 +1,5 @@
 import { type RouteEntry } from "./manifest.js";
-/** Minimal app surface the driver needs — just a fetch handler (a built `createWebApp`). */
+/** Minimal app surface the driver needs - just a fetch handler (a built `createWebApp`). */
 export interface PrerenderApp {
     fetch(req: Request): Response | Promise<Response>;
 }
@@ -33,7 +33,7 @@ export interface PrerenderResult {
         readonly path: string;
         readonly reason: string;
     }[];
-    /** Per dynamic route pattern, its `getStaticPaths` `fallback` (`"ssr"` default) — so the deploy
+    /** Per dynamic route pattern, its `getStaticPaths` `fallback` (`"ssr"` default) - so the deploy
      * layer knows whether unlisted paths should hit the worker (`"ssr"`) or 404 (`"404"`). */
     readonly fallbacks: Readonly<Record<string, "ssr" | "404">>;
 }
@@ -44,7 +44,7 @@ export declare function htmlFileFor(pattern: string): string;
 export declare function dataFileFor(pattern: string): string;
 /**
  * Render every opted-in static route to a static `index.html` under `outDir`. Run AFTER `buildClient`
- * (so the app references the hashed client entry). Returns a report of what was emitted vs skipped —
+ * (so the app references the hashed client entry). Returns a report of what was emitted vs skipped -
  * the caller can use `prerendered` to wire a hybrid deploy (e.g. exclude those paths from the SSR
  * worker so the CDN serves the static file). Never throws on a per-route miss: a non-OK response or a
  * non-opted/dynamic route is recorded in `skipped` and the build continues.
@@ -59,7 +59,7 @@ export interface CloudflarePagesRoutes {
 }
 export interface CloudflarePagesRoutesOptions {
     /** Prerendered request paths (e.g. `prerenderRoutes(...).prerendered.map(p => p.path)`, or the
-     * build's `prerendered.json`). Each is excluded from the worker — plus its static `_data.json`. */
+     * build's `prerendered.json`). Each is excluded from the worker - plus its static `_data.json`. */
     readonly prerendered: readonly string[];
     /** Extra globs to keep OFF the worker (CDN-served). Default `["/assets/*"]` (the hashed bundle). */
     readonly staticGlobs?: readonly string[];
@@ -71,7 +71,7 @@ export interface CloudflarePagesRoutesOptions {
  *
  * ⚠️ Cloudflare caps `_routes.json` at **100** include+exclude rules total, and each prerendered path
  * costs 2 (the doc + its `_data.json`). For a large SSG site, exclude by **prefix glob** (e.g.
- * `/blog/*`) instead of listing every path — pass those via `staticGlobs` and a smaller `prerendered`.
+ * `/blog/*`) instead of listing every path - pass those via `staticGlobs` and a smaller `prerendered`.
  */
 export declare function cloudflarePagesRoutes(options: CloudflarePagesRoutesOptions): CloudflarePagesRoutes;
 //# sourceMappingURL=prerender.d.ts.map

package/dist/prerender.js

@@ -2,7 +2,7 @@
  * Build-time SSG driver. Prerendering is framework-agnostic by construction: a nifra SSR page is
  * "just `app.fetch(GET)` returning a streamed `Response`", so prerendering = drive that same handler
  * at build with a synthetic request, drain the body to bytes, and write the HTML to disk. No adapter
- * (React/Solid/Vue/Preact/Svelte) is touched — this sits entirely above the render seam.
+ * (React/Solid/Vue/Preact/Svelte) is touched - this sits entirely above the render seam.
  *
  * Handles **static** routes (opt in via `export const prerender = true`) and **dynamic** `:param`
  * routes (enumerate concrete params via `export const getStaticPaths`). Catch-all/wildcard (`*`)
@@ -28,7 +28,7 @@ const outputPath = (root, file) => {
 };
 /**
  * Render every opted-in static route to a static `index.html` under `outDir`. Run AFTER `buildClient`
- * (so the app references the hashed client entry). Returns a report of what was emitted vs skipped —
+ * (so the app references the hashed client entry). Returns a report of what was emitted vs skipped -
  * the caller can use `prerendered` to wire a hybrid deploy (e.g. exclude those paths from the SSR
  * worker so the CDN serves the static file). Never throws on a per-route miss: a non-OK response or a
  * non-opted/dynamic route is recorded in `skipped` and the build continues.
@@ -44,7 +44,7 @@ export async function prerenderRoutes(options) {
     const renderPath = async (path) => {
         const res = await options.app.fetch(new Request(`${origin}${path}`));
         if (!res.ok) {
-            // A failed render is a per-route skip, not a build failure — surfaced for the caller to log.
+            // A failed render is a per-route skip, not a build failure - surfaced for the caller to log.
             skipped.push({ path, reason: `render returned HTTP ${res.status}` });
             return;
         }
@@ -59,7 +59,7 @@ export async function prerenderRoutes(options) {
         writeFileSync(abs, html);
         // Also emit the loader data as a static `_data.json` next to it, so a client soft-nav into this
         // route fetches a file instead of hitting the worker. Only when the data-mode response is plain
-        // JSON — a deferred loader answers with NDJSON, which the static fast-path doesn't cover (the
+        // JSON - a deferred loader answers with NDJSON, which the static fast-path doesn't cover (the
         // client falls back to the worker for those).
         let dataFile;
         const dataRes = await options.app.fetch(new Request(`${origin}${path}`, { headers: { [DATA_HEADER]: "1" } }));
@@ -76,13 +76,13 @@ export async function prerenderRoutes(options) {
             }
         }
         else {
-            await dataRes.body?.cancel(); // not emitting (non-OK or NDJSON) — release the stream
+            await dataRes.body?.cancel(); // not emitting (non-OK or NDJSON) - release the stream
         }
         prerendered.push({ path, file, bytes: html.length, ...(dataFile ? { dataFile } : {}) });
     };
     for (const route of options.routes) {
         if (route.pattern.includes("*")) {
-            skipped.push({ path: route.pattern, reason: "catch-all/wildcard route — not supported" });
+            skipped.push({ path: route.pattern, reason: "catch-all/wildcard route - not supported" });
             continue;
         }
         const mod = await route.load();
@@ -126,7 +126,7 @@ export async function prerenderRoutes(options) {
  *
  * ⚠️ Cloudflare caps `_routes.json` at **100** include+exclude rules total, and each prerendered path
  * costs 2 (the doc + its `_data.json`). For a large SSG site, exclude by **prefix glob** (e.g.
- * `/blog/*`) instead of listing every path — pass those via `staticGlobs` and a smaller `prerendered`.
+ * `/blog/*`) instead of listing every path - pass those via `staticGlobs` and a smaller `prerendered`.
  */
 export function cloudflarePagesRoutes(options) {
     const exclude = [...(options.staticGlobs ?? ["/assets/*"])];

package/dist/public-dir.d.ts

@@ -0,0 +1,36 @@
+/** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
+ * user-authored file keeps its name across deploys, so it gets a day and a revalidation. */
+export interface PublicDirCache {
+    /** `cache-control` for content-hashed assets (default immutable, one year). */
+    readonly hashed?: string;
+    /** `cache-control` for everything else under `public/` (default one day). */
+    readonly assets?: string;
+}
+export interface ServePublicDirOptions {
+    /** Absolute path of the directory to serve. */
+    readonly dir: string;
+    /** URL prefix whose files are content-hashed and may be cached immutably (default `"/assets/"`). */
+    readonly hashedPrefix?: string;
+    readonly cache?: PublicDirCache;
+    /** Optional encoded URL-path allowlist. When present, route misses avoid a filesystem probe. */
+    readonly files?: ReadonlySet<string>;
+}
+/**
+ * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
+ *
+ * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security
+ * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still
+ * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,
+ * because a blocklist over encodings is exactly the kind of check that gets bypassed.
+ */
+export declare function resolvePublicPath(root: string, pathname: string): string | undefined;
+/**
+ * Build a static-file handler for `dir`.
+ *
+ * Returns `undefined` on any miss so the caller **falls through to routing** - a static probe must
+ * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
+ * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
+ * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ */
+export declare function servePublicDir(options: ServePublicDirOptions): (request: Request) => Promise<Response | undefined>;
+//# sourceMappingURL=public-dir.d.ts.map

package/dist/public-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-dir.d.ts","sourceRoot":"","sources":["../src/public-dir.ts"],"names":[],"mappings":"AAiBA;4FAC4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oGAAoG;IACpG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAA;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACrC;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAapF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAmCrD"}