@nifrajs/web 2.2.0 → 2.3.0

package/dist/internal/server-boundary.js

@@ -0,0 +1,174 @@
+/**
+ * The server/client boundary, owned in one place.
+ *
+ * The client build must never ship server-only code, or server-only config, to a browser. Three
+ * conventions enforce that, and each has to mean the SAME thing in every pipeline that builds the client
+ * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`'s refusal
+ * (which cannot transform, so it refuses to start instead):
+ *
+ *   - `*.server` modules - emptied, so a secret / `node:` / native import subtree never reaches the client.
+ *   - `*.fn` modules     - replaced with HTTP stubs, so the function bodies (and their imports) stay server-side.
+ *   - public-env prefix  - which environment variables the client bundle is allowed to inline.
+ *
+ * When each pipeline re-encoded one of these rules, they drifted. A hand-written glob
+ * `**\/*.server.{ts,tsx,js,jsx}` missed the extensionless `db.server` and the `.mts`/`.cts`/`.mjs`/`.cjs`
+ * forms the regex matches, waving a module the build empties straight into the browser. So the matchers,
+ * the replacement bodies, and the env mapping get exactly one definition here; every pipeline imports it,
+ * and parity tests assert the Bun and Vite halves emit identical bytes. A matcher that decides whether a
+ * secret can reach a browser gets one owner, not four.
+ */
+// Both module conventions match a filename SUFFIX with the identical optional source-extension tail -
+// `.ts`, `.tsx`, `.mts`, `.cts`, `.mjs`, `.cjs`, `.js`, `.jsx`, or none (the extensionless `db.server` /
+// `todos.fn`). Kept adjacent so the shared shape is visible, and a parity test pins that the two never
+// diverge on which extensions count - a copied-then-edited second tail is exactly how the old glob drifted.
+/** Matches `db.server.ts`, `auth.server.tsx`, `x.server.mjs`, and the extensionless `foo.server`. */
+export const SERVER_ONLY_MODULE = /\.server(\.[cm]?[jt]sx?)?$/;
+/** Modules whose exports become client stubs. Mirrors the `.server` convention's shape. */
+export const SERVER_FN_MODULE = /\.fn(\.[cm]?[jt]sx?)?$/;
+// ---------------------------------------------------------------------------------------------------
+// `.server` - empty a server-only module in the client build.
+// ---------------------------------------------------------------------------------------------------
+/**
+ * The replacement body for an emptied module. A Proxy rather than `export {}` so any named OR default
+ * import resolves to `undefined` instead of failing the bundle with a missing-export error - the client
+ * degrades at the call site it wrote, not at link time in a file it never named.
+ *
+ * Shared so the Bun and Vite pipelines emit the same bytes; a parity test asserts it.
+ */
+export const SERVER_ONLY_REPLACEMENT = "module.exports = new Proxy({}, { get: () => undefined })";
+const EXPORTED_DECLARATION = /\bexport\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function|class|enum)\s+([A-Za-z_$][\w$]*)/g;
+const EXPORTED_LIST = /\bexport\s*\{([^}]*)\}(?:\s*from\s*["'][^"']+["'])?/g;
+/**
+ * Vite dev serves native ESM, so the Bun/CommonJS proxy above is invalid there. Emit inert ESM
+ * bindings derived from the source's public names while discarding the implementation and imports.
+ * An unsupported exotic export fails closed at ESM link time; server code is never served as fallback.
+ */
+export function viteServerOnlyReplacement(source) {
+    const names = new Set();
+    let hasDefault = /\bexport\s+default\b/.test(source);
+    for (const match of source.matchAll(EXPORTED_DECLARATION))
+        names.add(match[1]);
+    for (const match of source.matchAll(EXPORTED_LIST)) {
+        for (const raw of (match[1] ?? "").split(",")) {
+            const item = raw.trim().replace(/^type\s+/, "");
+            if (item === "")
+                continue;
+            const parts = item.split(/\s+as\s+/);
+            const exported = (parts[1] ?? parts[0] ?? "").trim();
+            if (exported === "default")
+                hasDefault = true;
+            else if (/^[A-Za-z_$][\w$]*$/.test(exported))
+                names.add(exported);
+        }
+    }
+    const bindings = [...names].sort().map((name) => `export const ${name} = undefined`);
+    if (hasDefault)
+        bindings.push("export default undefined");
+    return `// Generated by @nifrajs/web: server-only implementation removed from the browser.\n${bindings.join("\n")}\n`;
+}
+// ---------------------------------------------------------------------------------------------------
+// `.fn` - turn a server-function module into the client stubs that call it.
+// ---------------------------------------------------------------------------------------------------
+/**
+ * The server half of a server function must never reach a browser: it closes over database handles,
+ * secrets and everything else the module imports. So the CLIENT build does not bundle these modules at
+ * all - it replaces each one with a stub per export that POSTs to the route the server mounted.
+ *
+ * The generation is pure on purpose. The Bun and Vite pipelines both need this transform and must
+ * produce byte-identical stubs, so it lives here and each bundler contributes only its own plugin shell.
+ * A divergence between the two would be a client that works in dev and 404s in production.
+ *
+ * The exports are found by scanning the SOURCE rather than importing it - importing would execute the
+ * module, which is precisely what must not happen in a client build - and the declaration form is fixed:
+ *
+ *     export const addTodo = serverFn({ … }, async (input, c) => { … })
+ *
+ * Anything else is refused rather than skipped: a server function the scanner cannot see would be absent
+ * from the client and fail as `addTodo is not a function` at runtime, far from the cause.
+ */
+/** `export const NAME = serverFn(` at the start of a line - the one declaration form. */
+const DECLARATION = /^[\t ]*export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*serverFn\s*\(/gm;
+/** Any mention of `serverFn(` as a call, used to prove nothing was missed. */
+const ANY_CALL = /\bserverFn\s*\(/g;
+/** Line comments and block comments, stripped before scanning so prose cannot register as code. */
+const COMMENTS = /\/\*[\s\S]*?\*\/|(^|[^:])\/\/.*$/gm;
+/**
+ * The namespace a `*.fn.ts` module is mounted under: its filename without the `.fn` suffix.
+ *
+ * Deriving it from the filename rather than the full path keeps the build machine's directory layout
+ * out of a public URL, and keeps the route readable in logs. It also means the mount on the server -
+ * `serverFunctions("todos", …)` - has to use the same word, which is the one thing a reader must check
+ * by eye today; {@link SERVER_FN_MODULE} files are named for it precisely to make that obvious.
+ */
+export function serverFnNamespace(filePath) {
+    const base = filePath.replaceAll("\\", "/").split("/").pop() ?? "";
+    return base.replace(SERVER_FN_MODULE, "");
+}
+/** The server functions a module declares, in source order. */
+export function scanServerFnExports(source) {
+    const code = source.replaceAll(COMMENTS, "$1");
+    const names = [...code.matchAll(DECLARATION)].map((m) => m[1]);
+    const calls = [...code.matchAll(ANY_CALL)].length;
+    if (calls > names.length) {
+        throw new Error("[nifra/fn] a server function is declared in a form the client transform cannot read. Use " +
+            "`export const name = serverFn(…)` at the top level: the client build scans the source rather " +
+            "than importing it (importing would run your server code during a browser build), so a " +
+            "declaration it cannot see would be missing from the client and fail as `name is not a function`.");
+    }
+    return names;
+}
+/**
+ * The client replacement for a `*.fn.ts` module: one stub per export, and none of the original code.
+ *
+ * `credentials: "same-origin"` is explicit rather than relied upon - the server refuses a cross-origin
+ * call, and stating it here means the browser never sends cookies somewhere that would reject them.
+ * The content type is not decoration either: it is what makes a cross-origin form unable to forge one
+ * of these calls, so the stub and the server guard have to agree on it.
+ */
+export function generateServerFnStub(source, namespace) {
+    const names = scanServerFnExports(source);
+    const calls = names
+        .map((name) => `export const ${name} = (input) => __nifraCall(${JSON.stringify(name)}, input)`)
+        .join("\n");
+    return `// Generated by @nifrajs/web: the server half of this module never reaches the browser.
+const __nifraBase = ${JSON.stringify(`/_nifra/fn/${namespace}`)}
+
+async function __nifraCall(name, input) {
+  const response = await fetch(\`\${__nifraBase}/\${name}\`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(input === undefined ? {} : input),
+    credentials: "same-origin",
+  })
+  if (response.status === 404) {
+    throw new Error(
+      \`[nifra/fn] \${name} is not mounted at \${__nifraBase}. The client derives that path from this \` +
+        \`file's name, so the server's serverFunctions(...) namespace has to match it.\`,
+    )
+  }
+  if (!response.ok) {
+    let detail = ""
+    try {
+      detail = JSON.stringify(await response.json())
+    } catch {
+      // A non-JSON error body is not worth a second failure; the status carries enough.
+    }
+    throw new Error(\`[nifra/fn] \${name} failed: \${response.status}\${detail ? \` \${detail}\` : ""}\`)
+  }
+  return response.status === 204 ? undefined : await response.json()
+}
+
+${calls}
+`;
+}
+// ---------------------------------------------------------------------------------------------------
+// public-env - which environment variables the client bundle may inline.
+// ---------------------------------------------------------------------------------------------------
+/** Translate Nifra's public-env contract to Vite's `envPrefix` option. */
+export function vitePublicEnvPrefix(prefix) {
+    const configured = prefix ?? "PUBLIC_";
+    // Vite rejects an empty prefix. Environment-variable names cannot contain NUL, so this sentinel
+    // cannot match an ambient key and faithfully represents Nifra's "expose nothing" setting.
+    return configured === "" ? "\0nifra-public-env-disabled" : configured;
+}
+//# sourceMappingURL=server-boundary.js.map

package/dist/internal/server-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-boundary.js","sourceRoot":"","sources":["../../src/internal/server-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sGAAsG;AACtG,yGAAyG;AACzG,uGAAuG;AACvG,4GAA4G;AAE5G,qGAAqG;AACrG,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAA;AAC9D,2FAA2F;AAC3F,MAAM,CAAC,MAAM,gBAAgB,GAAG,wBAAwB,CAAA;AAExD,sGAAsG;AACtG,8DAA8D;AAC9D,sGAAsG;AAEtG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,0DAA0D,CAAA;AAEjG,MAAM,oBAAoB,GACxB,oGAAoG,CAAA;AACtG,MAAM,aAAa,GAAG,sDAAsD,CAAA;AAE5E;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAc;IACtD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAA;IAC/B,IAAI,UAAU,GAAG,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAEpD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC,CAAA;IACxF,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACnD,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;YAC/C,IAAI,IAAI,KAAK,EAAE;gBAAE,SAAQ;YACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;YACpC,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;YACpD,IAAI,QAAQ,KAAK,SAAS;gBAAE,UAAU,GAAG,IAAI,CAAA;iBACxC,IAAI,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QACnE,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,IAAI,cAAc,CAAC,CAAA;IACpF,IAAI,UAAU;QAAE,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;IACzD,OAAO,uFAAuF,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AACvH,CAAC;AAED,sGAAsG;AACtG,4EAA4E;AAC5E,sGAAsG;AAEtG;;;;;;;;;;;;;;;;GAgBG;AAEH,yFAAyF;AACzF,MAAM,WAAW,GAAG,kEAAkE,CAAA;AACtF,8EAA8E;AAC9E,MAAM,QAAQ,GAAG,kBAAkB,CAAA;AACnC,mGAAmG;AACnG,MAAM,QAAQ,GAAG,oCAAoC,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAA;IAClE,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAA;AAC3C,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;IAC9C,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAW,CAAC,CAAA;IACxE,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAA;IACjD,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,2FAA2F;YACzF,+FAA+F;YAC/F,wFAAwF;YACxF,kGAAkG,CACrG,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,SAAiB;IACpE,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAA;IACzC,MAAM,KAAK,GAAG,KAAK;SAChB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,IAAI,6BAA6B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC;SAC9F,IAAI,CAAC,IAAI,CAAC,CAAA;IACb,OAAO;sBACa,IAAI,CAAC,SAAS,CAAC,cAAc,SAAS,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2B7D,KAAK;CACN,CAAA;AACD,CAAC;AAED,sGAAsG;AACtG,yEAAyE;AACzE,sGAAsG;AAEtG,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAAC,MAA0B;IAC5D,MAAM,UAAU,GAAG,MAAM,IAAI,SAAS,CAAA;IACtC,gGAAgG;IAChG,0FAA0F;IAC1F,OAAO,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,UAAU,CAAA;AACvE,CAAC"}

package/dist/internal/timing-safe-equal.d.ts

@@ -2,7 +2,7 @@
  * 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
+ * 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.
  */

package/dist/internal/timing-safe-equal.js

@@ -2,7 +2,7 @@
  * 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
+ * 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.
  */

package/dist/internal/vite-import.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The one place nifra imports Vite from.
+ *
+ * ## Why this is a module and not two `await import("vite")` calls
+ *
+ * Vite must not be imported before {@link relaxCaptureStackTrace} has run, and that requirement is
+ * invisible at the call site. It was invisible in exactly the way that matters: the production build
+ * relaxed first, the dev server did not, and the dev server's import ran earlier in the test process.
+ * ESM caches a module that throws while EVALUATING, so once vite failed there it kept failing - every
+ * later `loadVite` re-threw the cached error, with its shim correctly installed and no longer able to
+ * help. One unguarded import poisons vite for the whole process.
+ *
+ * So the import lives here and the guard is not optional. A caller cannot get the module without it.
+ */
+/**
+ * Restore V8's `Error.captureStackTrace` contract on a runtime that is stricter than it.
+ *
+ * `captureStackTrace` is a V8 API and V8 decorates ANY object handed to it. Some runtimes require a
+ * real Error - one with the internal slot - and throw "First argument must be an Error object".
+ *
+ * That breaks importing vite outright. Vite bundles `follow-redirects`, which builds its error types
+ * the pre-class way:
+ *
+ *   function CustomError(props) { Error.captureStackTrace(this, this.constructor); … }
+ *   CustomError.prototype = new (baseClass || Error)()
+ *
+ * The last line CONSTRUCTS `baseClass` while defining the subclass, so `this` inherits from Error but
+ * was never built by it - and the throw lands during module evaluation, before vite exports anything.
+ *
+ * Decorating a stack is best-effort by definition, so swallowing the refusal loses nothing: the shim
+ * delegates and suppresses only that. Installed once and deliberately not restored, since the strict
+ * behaviour is the deviation and a library evaluated later meets the same wall.
+ *
+ * ## Why it does not probe first
+ *
+ * It used to construct an object like follow-redirects' and install the shim only if the runtime
+ * refused it. That shipped and CI still failed, because the probe was not the same shape as the real
+ * call: it passed `Object.create(Error.prototype)` and no `constructorOpt`, while follow-redirects
+ * passes an object whose prototype is an Error INSTANCE plus `this.constructor`. One Bun build accepts
+ * the former and rejects the latter, so the probe reported "permissive" and installed nothing.
+ *
+ * A probe has to predict every caller's construction pattern to be right, and is silently wrong when
+ * it guesses short. Installing unconditionally cannot fail that way.
+ */
+export declare function relaxCaptureStackTrace(): void;
+/**
+ * Import the project's Vite, with the stack-trace contract restored first.
+ *
+ * Callers keep their own error message - the dev server and the production build fail for the same
+ * reasons but need to say different things - so this deliberately lets the cause through untouched.
+ * Use {@link isViteUnresolved} to tell "vite is not installed" from "vite failed to load".
+ */
+export declare function importVite<T>(): Promise<T>;
+/**
+ * Whether a failed {@link importVite} means vite is absent rather than broken.
+ *
+ * `vite` is an OPTIONAL peer, so a project without it fails to RESOLVE - the common case, and the one
+ * worth naming. But vite can also resolve and fail while EVALUATING, which is not a missing dependency
+ * at all: vite 8 loads rolldown's native binding on import, and a binding that will not load surfaces
+ * the same way. Telling that user to install what they already installed sends them the wrong way.
+ */
+export declare function isViteUnresolved(cause: unknown): boolean;
+//# sourceMappingURL=vite-import.d.ts.map

package/dist/internal/vite-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-import.d.ts","sourceRoot":"","sources":["../../src/internal/vite-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAkB7C;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAGhD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGxD"}

package/dist/internal/vite-import.js

@@ -0,0 +1,94 @@
+/**
+ * The one place nifra imports Vite from.
+ *
+ * ## Why this is a module and not two `await import("vite")` calls
+ *
+ * Vite must not be imported before {@link relaxCaptureStackTrace} has run, and that requirement is
+ * invisible at the call site. It was invisible in exactly the way that matters: the production build
+ * relaxed first, the dev server did not, and the dev server's import ran earlier in the test process.
+ * ESM caches a module that throws while EVALUATING, so once vite failed there it kept failing - every
+ * later `loadVite` re-threw the cached error, with its shim correctly installed and no longer able to
+ * help. One unguarded import poisons vite for the whole process.
+ *
+ * So the import lives here and the guard is not optional. A caller cannot get the module without it.
+ */
+/** Marks the shim as installed, so repeated imports do not wrap a wrapper. */
+const RELAXED = Symbol.for("@nifrajs/web/relaxed-capture-stack-trace");
+/**
+ * Restore V8's `Error.captureStackTrace` contract on a runtime that is stricter than it.
+ *
+ * `captureStackTrace` is a V8 API and V8 decorates ANY object handed to it. Some runtimes require a
+ * real Error - one with the internal slot - and throw "First argument must be an Error object".
+ *
+ * That breaks importing vite outright. Vite bundles `follow-redirects`, which builds its error types
+ * the pre-class way:
+ *
+ *   function CustomError(props) { Error.captureStackTrace(this, this.constructor); … }
+ *   CustomError.prototype = new (baseClass || Error)()
+ *
+ * The last line CONSTRUCTS `baseClass` while defining the subclass, so `this` inherits from Error but
+ * was never built by it - and the throw lands during module evaluation, before vite exports anything.
+ *
+ * Decorating a stack is best-effort by definition, so swallowing the refusal loses nothing: the shim
+ * delegates and suppresses only that. Installed once and deliberately not restored, since the strict
+ * behaviour is the deviation and a library evaluated later meets the same wall.
+ *
+ * ## Why it does not probe first
+ *
+ * It used to construct an object like follow-redirects' and install the shim only if the runtime
+ * refused it. That shipped and CI still failed, because the probe was not the same shape as the real
+ * call: it passed `Object.create(Error.prototype)` and no `constructorOpt`, while follow-redirects
+ * passes an object whose prototype is an Error INSTANCE plus `this.constructor`. One Bun build accepts
+ * the former and rejects the latter, so the probe reported "permissive" and installed nothing.
+ *
+ * A probe has to predict every caller's construction pattern to be right, and is silently wrong when
+ * it guesses short. Installing unconditionally cannot fail that way.
+ */
+export function relaxCaptureStackTrace() {
+    const strict = Error.captureStackTrace;
+    if (typeof strict !== "function")
+        return;
+    if (Error[RELAXED] === true)
+        return;
+    try {
+        Error.captureStackTrace = ((target, constructorOpt) => {
+            try {
+                ;
+                strict.call(Error, target, constructorOpt);
+            }
+            catch {
+                // The runtime refused to decorate this object. A missing `.stack` is not worth failing over.
+            }
+        });
+        Object.defineProperty(Error, RELAXED, { value: true, configurable: true });
+    }
+    catch {
+        // The property is frozen or non-writable. Nothing can be done about the import that follows, but
+        // failing HERE would replace vite's own error with an assignment error - strictly less
+        // informative than letting the import fail and be reported by the caller.
+    }
+}
+/**
+ * Import the project's Vite, with the stack-trace contract restored first.
+ *
+ * Callers keep their own error message - the dev server and the production build fail for the same
+ * reasons but need to say different things - so this deliberately lets the cause through untouched.
+ * Use {@link isViteUnresolved} to tell "vite is not installed" from "vite failed to load".
+ */
+export async function importVite() {
+    relaxCaptureStackTrace();
+    return (await import("vite"));
+}
+/**
+ * Whether a failed {@link importVite} means vite is absent rather than broken.
+ *
+ * `vite` is an OPTIONAL peer, so a project without it fails to RESOLVE - the common case, and the one
+ * worth naming. But vite can also resolve and fail while EVALUATING, which is not a missing dependency
+ * at all: vite 8 loads rolldown's native binding on import, and a binding that will not load surfaces
+ * the same way. Telling that user to install what they already installed sends them the wrong way.
+ */
+export function isViteUnresolved(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return /cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message);
+}
+//# sourceMappingURL=vite-import.js.map

package/dist/internal/vite-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-import.js","sourceRoot":"","sources":["../../src/internal/vite-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8EAA8E;AAC9E,MAAM,OAAO,GAAkB,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAA;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB,CAAA;IACtC,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAM;IACxC,IAAK,KAAiD,CAAC,OAAO,CAAC,KAAK,IAAI;QAAE,OAAM;IAChF,IAAI,CAAC;QACH,KAAK,CAAC,iBAAiB,GAAG,CAAC,CAAC,MAAc,EAAE,cAAwB,EAAE,EAAE;YACtE,IAAI,CAAC;gBACH,CAAC;gBAAC,MAA2C,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,CAAA;YACnF,CAAC;YAAC,MAAM,CAAC;gBACP,6FAA6F;YAC/F,CAAC;QACH,CAAC,CAAmC,CAAA;QACpC,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,iGAAiG;QACjG,uFAAuF;QACvF,0EAA0E;IAC5E,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,sBAAsB,EAAE,CAAA;IACxB,OAAO,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,CAAiB,CAAA;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACtE,OAAO,sDAAsD,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAC7E,CAAC"}

package/dist/islands.d.ts

@@ -1,16 +1,16 @@
 /**
- * @nifrajs/web/islands — the framework-agnostic islands client runtime.
+ * @nifrajs/web/islands - the framework-agnostic islands client runtime.
  *
  * An "island" is a server-rendered `<nifra-island>` element whose interactivity is mounted by a small
  * **plain-DOM** enhancer instead of a framework runtime. On a route that opts out of full-document
  * hydration (`export const hydrate = false`), the page ships **zero** framework JS; only the island
  * bundle (this runtime + your enhancers) loads. This variant ships ~99% less client JS than full
- * React hydration on a mostly-static page — the framework runtime is the cost, and islands skip it
+ * React hydration on a mostly-static page - the framework runtime is the cost, and islands skip it
  * entirely here.
  *
  * Server side: render the marker with `@nifrajs/web-react`'s `<Island>` (or any framework's host element
  * `<nifra-island data-id data-strategy data-props>`). Props are JSON-encoded inline in `data-props`
- * (attribute-escaped by the framework) — no central registry, so concurrent SSR renders never share
+ * (attribute-escaped by the framework) - no central registry, so concurrent SSR renders never share
  * state. Client side: bundle one entry that calls `mountIslands({ <id>: enhancer })` and load it via
  * the route's `islandScripts`.
  */
@@ -20,14 +20,14 @@ export type IslandStrategy = "load" | "idle" | "visible";
 export type IslandCleanup = () => void;
 /**
  * Enhances one island element with its (typed) props. Return a cleanup function to tear down on
- * `dispose()` (listeners, observers) — optional; an enhancer with nothing to clean up returns nothing.
+ * `dispose()` (listeners, observers) - optional; an enhancer with nothing to clean up returns nothing.
  * The `void` member is the no-cleanup case, the same shape as React's `EffectCallback`.
  */
 export type IslandEnhancer<P = unknown> = (el: HTMLElement, props: P) => IslandCleanup | void;
 /**
  * Find every `<nifra-island data-id>` under `root` (default `document`) and enhance each with the
  * matching enhancer, honoring its `data-strategy`. An island whose `id` has no enhancer is left as
- * inert SSR HTML (forward-compatible). An enhancer that throws is isolated — it never blocks the
+ * inert SSR HTML (forward-compatible). An enhancer that throws is isolated - it never blocks the
  * others (each island is independent). Returns a disposer that cancels pending triggers and runs every
  * enhancer's cleanup (call it on soft-nav teardown; harmless if your app never navigates).
  */

package/dist/islands.js

@@ -1,16 +1,16 @@
 /**
- * @nifrajs/web/islands — the framework-agnostic islands client runtime.
+ * @nifrajs/web/islands - the framework-agnostic islands client runtime.
  *
  * An "island" is a server-rendered `<nifra-island>` element whose interactivity is mounted by a small
  * **plain-DOM** enhancer instead of a framework runtime. On a route that opts out of full-document
  * hydration (`export const hydrate = false`), the page ships **zero** framework JS; only the island
  * bundle (this runtime + your enhancers) loads. This variant ships ~99% less client JS than full
- * React hydration on a mostly-static page — the framework runtime is the cost, and islands skip it
+ * React hydration on a mostly-static page - the framework runtime is the cost, and islands skip it
  * entirely here.
  *
  * Server side: render the marker with `@nifrajs/web-react`'s `<Island>` (or any framework's host element
  * `<nifra-island data-id data-strategy data-props>`). Props are JSON-encoded inline in `data-props`
- * (attribute-escaped by the framework) — no central registry, so concurrent SSR renders never share
+ * (attribute-escaped by the framework) - no central registry, so concurrent SSR renders never share
  * state. Client side: bundle one entry that calls `mountIslands({ <id>: enhancer })` and load it via
  * the route's `islandScripts`.
  */
@@ -63,7 +63,7 @@ function whenStrategy(el, strategy, run) {
 /**
  * Find every `<nifra-island data-id>` under `root` (default `document`) and enhance each with the
  * matching enhancer, honoring its `data-strategy`. An island whose `id` has no enhancer is left as
- * inert SSR HTML (forward-compatible). An enhancer that throws is isolated — it never blocks the
+ * inert SSR HTML (forward-compatible). An enhancer that throws is isolated - it never blocks the
  * others (each island is independent). Returns a disposer that cancels pending triggers and runs every
  * enhancer's cleanup (call it on soft-nav teardown; harmless if your app never navigates).
  */
@@ -99,7 +99,7 @@ export function mountIslands(enhancers, options = {}) {
                 dispose();
             }
             catch {
-                // best-effort teardown — a failing cleanup must not block the rest
+                // best-effort teardown - a failing cleanup must not block the rest
             }
         }
     };

package/dist/isr.d.ts

@@ -1,4 +1,4 @@
-/** A cached SSR response — the bytes + metadata a {@link CacheStore} persists. */
+/** A cached SSR response - the bytes + metadata a {@link CacheStore} persists. */
 export interface CachedResponse {
     /** The rendered document (UTF-8 HTML, fully buffered). */
     readonly body: string;
@@ -25,7 +25,7 @@ export interface CacheStore {
     delete(key: string): Promise<void>;
 }
 export interface MemoryCacheStoreOptions {
-    /** Allow the in-memory store in production. Off by default — per-instance caching means revalidation
+    /** Allow the in-memory store in production. Off by default - per-instance caching means revalidation
      * won't propagate across instances and each instance caches separately. */
     readonly allowInProduction?: boolean;
     /** Hard cap on entries; the least-recently-used is evicted past it (default 500). */
@@ -33,7 +33,7 @@ export interface MemoryCacheStoreOptions {
 }
 /**
  * In-process ISR cache. Refuses to run in production unless explicitly allowed (mirrors the
- * rate-limit `MemoryStore` — a per-instance cache is unsafe across instances). Bounded **LRU**: a
+ * rate-limit `MemoryStore` - a per-instance cache is unsafe across instances). Bounded **LRU**: a
  * read or write bumps the entry, so the least-recently-used evicts past `max` (a hot, frequently-read
  * page survives a burst of new pages).
  */
@@ -46,7 +46,7 @@ export declare class MemoryCacheStore implements CacheStore {
     delete(key: string): Promise<void>;
 }
 /**
- * Minimal structural shape of a Cloudflare Workers **KV namespace** binding — just the three methods
+ * Minimal structural shape of a Cloudflare Workers **KV namespace** binding - just the three methods
  * {@link KVCacheStore} uses. Structural (not a dependency on `@cloudflare/workers-types`) so any
  * KV-like binding satisfies it and tests can pass an in-memory double.
  */
@@ -63,16 +63,16 @@ export interface KVNamespaceLike {
 export interface KVCacheStoreOptions {
     /**
      * GC backstop (**seconds**) written as the KV entry's `expirationTtl`, so abandoned entries
-     * eventually evict. MUST exceed your longest `revalidate` window — otherwise KV expiry turns a
+     * eventually evict. MUST exceed your longest `revalidate` window - otherwise KV expiry turns a
      * stale-while-revalidate into a *blocking* miss (the entry vanishes instead of being served stale
-     * while it regenerates) — and be ≥ 60 (Cloudflare KV's minimum). Omit ⇒ entries persist until
+     * while it regenerates) - and be ≥ 60 (Cloudflare KV's minimum). Omit ⇒ entries persist until
      * overwritten on regeneration or purged via `revalidateEndpoint`.
      */
     readonly expirationTtl?: number;
 }
 /**
  * A {@link CacheStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike}
- * binding) — the production-grade shared/durable store ISR wants: cached pages and on-demand purges
+ * binding) - the production-grade shared/durable store ISR wants: cached pages and on-demand purges
  * hold *across* worker instances (unlike the per-instance {@link MemoryCacheStore}). Entries serialize
  * to JSON; every read is validated before it's trusted (a malformed/version-skewed entry is treated as
  * a miss). Construct it in your Workers `fetch` from the binding: `new KVCacheStore(env.ISR_CACHE)`.
@@ -85,12 +85,12 @@ export declare class KVCacheStore implements CacheStore {
     set(key: string, value: CachedResponse): Promise<void>;
     delete(key: string): Promise<void>;
 }
-/** Minimal platform shape `withISR` needs — just `waitUntil` (edge runtimes extend the response
+/** Minimal platform shape `withISR` needs - just `waitUntil` (edge runtimes extend the response
  * lifetime so background regeneration finishes). Off-edge it's absent and regen runs fire-and-forget. */
 export interface ISRPlatform {
     readonly waitUntil?: (promise: Promise<unknown>) => void;
 }
-/** The app `withISR` wraps — anything with a `fetch(req, platform?)` (a `createWebApp` result). */
+/** The app `withISR` wraps - anything with a `fetch(req, platform?)` (a `createWebApp` result). */
 export interface ISRApp {
     fetch(req: Request, platform?: ISRPlatform): Response | Promise<Response>;
 }
@@ -99,7 +99,7 @@ export interface ISRApp {
 export declare const ISR_STATUS_HEADER = "x-nifra-isr";
 /**
  * Response header a route uses to advertise its ISR freshness (**seconds**) to a {@link withISR}
- * wrapper — `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
+ * wrapper - `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
  * from the action-revalidation `x-nifra-revalidate` header (a CSV path list the *client* parses to
  * refetch): this one is an integer TTL the *wrapper* reads, so the two channels never alias.
  */
@@ -110,14 +110,14 @@ export interface ISROptions {
      * behind). A route overrides it per-page via `export const revalidate` (surfaced as the
      * `x-nifra-isr-revalidate` response header). */
     readonly revalidate: number;
-    /** Monotonic clock (ms) — injected for testability; production passes `() => Date.now()`. */
+    /** Monotonic clock (ms) - injected for testability; production passes `() => Date.now()`. */
     readonly now: () => number;
     /** Cache key for a request. Default: `origin + pathname + search` so host-routed apps do not share
      * entries across tenants. Return `null` to bypass the cache for this request (it goes straight to the
      * app, uncached). */
     readonly key?: (req: Request) => string | null;
     /** Draft/preview secret (the same one given to `createWebApp({ draftSecret })` + `enableDraft`). When
-     * set, a request carrying a valid signed draft cookie **bypasses the cache** — editors always render
+     * set, a request carrying a valid signed draft cookie **bypasses the cache** - editors always render
      * fresh, and a draft render is never written to the store (it can't poison the public cache). */
     readonly draftSecret?: string;
 }
@@ -125,7 +125,7 @@ export interface ISROptions {
  * Wrap a nifra app with **Incremental Static Regeneration**: a cacheable page is served from
  * {@link CacheStore} when fresh, served **stale while a fresh copy regenerates in the background**
  * (`platform.waitUntil` on edge), or rendered + stored on a miss. Framework-agnostic (it caches the
- * rendered bytes). Returns a `fetch(req, platform?)` handler — hand it to `Bun.serve`/the Workers
+ * rendered bytes). Returns a `fetch(req, platform?)` handler - hand it to `Bun.serve`/the Workers
  * `export default`, etc. Regeneration is single-flight per key (no stampede on a hot stale page).
  *
  * Each route's freshness comes from the `revalidate` header the app sets (per-route
@@ -139,12 +139,12 @@ export interface RevalidateEndpointOptions {
     readonly secret: string;
     /** Header carrying the secret. Default `x-nifra-revalidate-token`. */
     readonly tokenHeader?: string;
-    /** Map a to-purge path → its cache key — MUST match the `withISR` `key` fn. The default uses the
+    /** Map a to-purge path → its cache key - MUST match the `withISR` `key` fn. The default uses the
      * revalidation request's origin plus the purged path, matching `withISR`'s default host-aware key. */
     readonly key?: (path: string, req: Request) => string;
 }
 /**
- * An **on-demand revalidation** (purge) endpoint — a `fetch` handler that drops a path's cached entry
+ * An **on-demand revalidation** (purge) endpoint - a `fetch` handler that drops a path's cached entry
  * so the next request re-renders. `POST` with the secret in the token header and the path as `?path=`
  * or a JSON `{ "path": "/blog/x" }` body. The token is checked in **constant time** (wrong/missing →
  * `401`); a missing/relative path → `400`; non-POST → `405`. Mount it on a nifra route, e.g.

package/dist/isr.js

@@ -10,7 +10,7 @@ import { isDraftEnabled } from "./draft.js";
 import { timingSafeEqual } from "./internal/timing-safe-equal.js";
 /**
  * In-process ISR cache. Refuses to run in production unless explicitly allowed (mirrors the
- * rate-limit `MemoryStore` — a per-instance cache is unsafe across instances). Bounded **LRU**: a
+ * rate-limit `MemoryStore` - a per-instance cache is unsafe across instances). Bounded **LRU**: a
  * read or write bumps the entry, so the least-recently-used evicts past `max` (a hot, frequently-read
  * page survives a burst of new pages).
  */
@@ -29,7 +29,7 @@ export class MemoryCacheStore {
     get(key) {
         const value = this.cache.get(key);
         // LRU: a read bumps the entry to the tail so the bounded evict drops the LEAST-RECENTLY-USED,
-        // not the oldest-written — otherwise a burst of new pages would evict a hot, frequently-read one.
+        // not the oldest-written - otherwise a burst of new pages would evict a hot, frequently-read one.
         if (value !== undefined) {
             this.cache.delete(key);
             this.cache.set(key, value);
@@ -77,7 +77,7 @@ const isCachedResponse = (value) => {
 };
 /**
  * A {@link CacheStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike}
- * binding) — the production-grade shared/durable store ISR wants: cached pages and on-demand purges
+ * binding) - the production-grade shared/durable store ISR wants: cached pages and on-demand purges
  * hold *across* worker instances (unlike the per-instance {@link MemoryCacheStore}). Entries serialize
  * to JSON; every read is validated before it's trusted (a malformed/version-skewed entry is treated as
  * a miss). Construct it in your Workers `fetch` from the binding: `new KVCacheStore(env.ISR_CACHE)`.
@@ -122,7 +122,7 @@ export class KVCacheStore {
 export const ISR_STATUS_HEADER = "x-nifra-isr";
 /**
  * Response header a route uses to advertise its ISR freshness (**seconds**) to a {@link withISR}
- * wrapper — `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
+ * wrapper - `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
  * from the action-revalidation `x-nifra-revalidate` header (a CSV path list the *client* parses to
  * refetch): this one is an integer TTL the *wrapper* reads, so the two channels never alias.
  */
@@ -198,7 +198,7 @@ function sanitizeCachedHeaders(headers) {
  * Wrap a nifra app with **Incremental Static Regeneration**: a cacheable page is served from
  * {@link CacheStore} when fresh, served **stale while a fresh copy regenerates in the background**
  * (`platform.waitUntil` on edge), or rendered + stored on a miss. Framework-agnostic (it caches the
- * rendered bytes). Returns a `fetch(req, platform?)` handler — hand it to `Bun.serve`/the Workers
+ * rendered bytes). Returns a `fetch(req, platform?)` handler - hand it to `Bun.serve`/the Workers
  * `export default`, etc. Regeneration is single-flight per key (no stampede on a hot stale page).
  *
  * Each route's freshness comes from the `revalidate` header the app sets (per-route
@@ -234,7 +234,7 @@ export function withISR(app, options) {
             headers: { ...entry.headers, [ISR_STATUS_HEADER]: "miss" },
         });
     };
-    // Background regeneration (single-flight per key) — a failed regen keeps the stale entry; the next
+    // Background regeneration (single-flight per key) - a failed regen keeps the stale entry; the next
     // stale hit retries. Never throws (it runs detached / under waitUntil).
     const regenerate = async (req, platform, key) => {
         if (regenerating.has(key))
@@ -288,7 +288,7 @@ export function withISR(app, options) {
 }
 const jsonError = (status, error) => Response.json({ ok: false, error }, { status });
 /**
- * An **on-demand revalidation** (purge) endpoint — a `fetch` handler that drops a path's cached entry
+ * An **on-demand revalidation** (purge) endpoint - a `fetch` handler that drops a path's cached entry
  * so the next request re-renders. `POST` with the secret in the token header and the path as `?path=`
  * or a JSON `{ "path": "/blog/x" }` body. The token is checked in **constant time** (wrong/missing →
  * `401`); a missing/relative path → `400`; non-POST → `405`. Mount it on a nifra route, e.g.