@nifrajs/cli 2.1.0 → 2.2.0

package/dist/pipeline-guard.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pipeline separation guard — one bundler owns a phase, never two.
+ *
+ * nifra supports both Vite and Bun, and the config keeps them in separate slots: `vitePlugins` for
+ * the Vite pipeline, `clientPlugins`/`serverPlugins` for the Bun one. Nothing enforces the split, so
+ * a plugin lands in the wrong slot and is silently ignored - a Vite plugin in `clientPlugins` is
+ * handed to `Bun.build`, which has no `transform` hook to call, so the transform simply never runs
+ * and the build succeeds.
+ *
+ * That failure mode is the whole reason for this file. nifra's expensive bugs are not caused by Vite
+ * or by Bun; they are caused by two toolchains disagreeing about one module. Dual-React is that, the
+ * dedupe plugins are patches for that, and a `resolve.alias` that never reaches SSR is that. Mixing
+ * is the defect - choice is not - so the separation has to be checked rather than documented.
+ *
+ * Detection is by hook shape, which is what each bundler actually dispatches on:
+ *   - a Bun plugin has `setup(build)`
+ *   - a Rollup/Vite plugin has `resolveId` / `load` / `transform` / `config` / `configResolved` /
+ *     `transformIndexHtml` and no `setup`
+ *
+ * Deliberately conservative: a plugin that matches neither shape is left alone rather than guessed
+ * at. A guard that fires on correct config is a guard people turn off.
+ */
+/** Which pipeline a slot belongs to. */
+export type PipelineSlot = "vitePlugins" | "clientPlugins" | "serverPlugins";
+export interface PipelineMismatch {
+    readonly slot: PipelineSlot;
+    /** The plugin's `name`, or a positional label when it has none. */
+    readonly plugin: string;
+    /** The pipeline the slot feeds. */
+    readonly expected: "vite" | "bun";
+    /** The pipeline the plugin's hooks say it belongs to. */
+    readonly actual: "vite" | "bun";
+    readonly fix: string;
+}
+/**
+ * Check one slot's resolved plugin list. Pure: takes the already-resolved array so a thunk-valued
+ * field is awaited by the caller, and so this stays testable without loading a project.
+ */
+export declare function checkPipelineSlot(slot: PipelineSlot, plugins: readonly unknown[]): PipelineMismatch[];
+/** Check every slot of a resolved framework config. */
+export declare function checkPipelineSeparation(slots: {
+    readonly vitePlugins?: readonly unknown[];
+    readonly clientPlugins?: readonly unknown[];
+    readonly serverPlugins?: readonly unknown[];
+}): PipelineMismatch[];
+/** Which bundler a build runs on. */
+export type BuildPipeline = "bun" | "vite";
+export interface PipelineDecision {
+    readonly pipeline: BuildPipeline;
+    /**
+     * Why this pipeline, for the `nifra build` log line - so an auto-selected Vite build never looks
+     * like the user got the default. `undefined` when the choice was the plain default or was forced.
+     */
+    readonly reason?: string;
+}
+/** The plugin slots a decision reads, already resolved. */
+export interface PipelineSlots {
+    readonly vitePlugins?: readonly unknown[];
+    readonly clientPlugins?: readonly unknown[];
+    readonly serverPlugins?: readonly unknown[];
+}
+/**
+ * Pick the bundler for `nifra build`, per app rather than per global default.
+ *
+ * The phase defaults are deliberately asymmetric - `nifra dev` is Vite (for the plugin ecosystem, and
+ * because Bun's DEV-server bundler cannot compile CSS Modules), `nifra build` is Bun (faster and
+ * Bun-native). For an app with no transforms that asymmetry is free: there is nothing to disagree about.
+ * For an app whose ONLY transforms are Vite plugins it is not. Those plugins run in dev and are then
+ * dropped by the Bun build - `buildForTarget` reads `clientPlugins`/`serverPlugins`, never `vitePlugins`
+ * - so the build succeeds, the output looks plausible, and the transform simply did not happen. That is
+ * the same failure {@link checkPipelineSeparation} exists to prevent, reached by crossing PHASES instead
+ * of slots, and the slot check cannot see it because the plugins are correctly placed.
+ *
+ * So the default follows the app: Vite plugins with no Bun counterpart means the app has exactly one
+ * pipeline that can build it, and that is the one used. An app declaring BOTH has supplied the Bun
+ * equivalent on purpose - nothing is dropped - so the fast Bun default stands.
+ *
+ * `forced` is `--vite` / `--bun` and always wins, except for the one combination that silently discards
+ * work, which throws instead. Refusing rather than warning matches the slot guard: a build that succeeds
+ * and omits the transform is worse than one that stops and says so.
+ */
+export declare function chooseBuildPipeline(slots: PipelineSlots, forced?: BuildPipeline): PipelineDecision;
+//# sourceMappingURL=pipeline-guard.d.ts.map

package/dist/pipeline-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-guard.d.ts","sourceRoot":"","sources":["../src/pipeline-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,CAAA;AAE5E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAA;IACjC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAmCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,SAAS,OAAO,EAAE,GAC1B,gBAAgB,EAAE,CAqBpB;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAC5C,GAAG,gBAAgB,EAAE,CAMrB;AAED,qCAAqC;AACrC,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAA;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAC5C;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,MAAM,CAAC,EAAE,aAAa,GACrB,gBAAgB,CAsBlB"}

package/dist/pipeline-guard.js

@@ -0,0 +1,136 @@
+/**
+ * Pipeline separation guard — one bundler owns a phase, never two.
+ *
+ * nifra supports both Vite and Bun, and the config keeps them in separate slots: `vitePlugins` for
+ * the Vite pipeline, `clientPlugins`/`serverPlugins` for the Bun one. Nothing enforces the split, so
+ * a plugin lands in the wrong slot and is silently ignored - a Vite plugin in `clientPlugins` is
+ * handed to `Bun.build`, which has no `transform` hook to call, so the transform simply never runs
+ * and the build succeeds.
+ *
+ * That failure mode is the whole reason for this file. nifra's expensive bugs are not caused by Vite
+ * or by Bun; they are caused by two toolchains disagreeing about one module. Dual-React is that, the
+ * dedupe plugins are patches for that, and a `resolve.alias` that never reaches SSR is that. Mixing
+ * is the defect - choice is not - so the separation has to be checked rather than documented.
+ *
+ * Detection is by hook shape, which is what each bundler actually dispatches on:
+ *   - a Bun plugin has `setup(build)`
+ *   - a Rollup/Vite plugin has `resolveId` / `load` / `transform` / `config` / `configResolved` /
+ *     `transformIndexHtml` and no `setup`
+ *
+ * Deliberately conservative: a plugin that matches neither shape is left alone rather than guessed
+ * at. A guard that fires on correct config is a guard people turn off.
+ */
+const ROLLUP_HOOKS = [
+    "resolveId",
+    "load",
+    "transform",
+    "config",
+    "configResolved",
+    "configureServer",
+    "transformIndexHtml",
+    "generateBundle",
+    "renderChunk",
+];
+/** Classify a plugin by the hooks it exposes, or `undefined` when its shape says nothing. */
+function classify(plugin) {
+    if (typeof plugin !== "object" || plugin === null)
+        return undefined;
+    const record = plugin;
+    // `setup` is Bun's only entry point, so its presence is decisive even alongside other keys.
+    if (typeof record.setup === "function")
+        return "bun";
+    if (ROLLUP_HOOKS.some((hook) => typeof record[hook] === "function"))
+        return "vite";
+    return undefined;
+}
+const SLOT_PIPELINE = {
+    vitePlugins: "vite",
+    clientPlugins: "bun",
+    serverPlugins: "bun",
+};
+const MOVE_TO = {
+    vite: "`vitePlugins`",
+    bun: "`clientPlugins` (client bundle) or `serverPlugins` (SSR)",
+};
+/**
+ * Check one slot's resolved plugin list. Pure: takes the already-resolved array so a thunk-valued
+ * field is awaited by the caller, and so this stays testable without loading a project.
+ */
+export function checkPipelineSlot(slot, plugins) {
+    const expected = SLOT_PIPELINE[slot];
+    const out = [];
+    for (let i = 0; i < plugins.length; i++) {
+        const plugin = plugins[i];
+        const actual = classify(plugin);
+        if (actual === undefined || actual === expected)
+            continue;
+        const named = plugin.name;
+        const label = typeof named === "string" && named !== "" ? named : `${slot}[${i}]`;
+        out.push({
+            slot,
+            plugin: label,
+            expected,
+            actual,
+            fix: actual === "vite"
+                ? `"${label}" is a Vite/Rollup plugin (it defines Rollup hooks, not \`setup\`) but sits in \`${slot}\`, which feeds Bun.build. Bun never calls those hooks, so the transform silently does not run. Move it to ${MOVE_TO.vite}.`
+                : `"${label}" is a Bun plugin (it defines \`setup\`) but sits in \`${slot}\`, which feeds Vite. Vite never calls \`setup\`, so the transform silently does not run. Move it to ${MOVE_TO.bun}.`,
+        });
+    }
+    return out;
+}
+/** Check every slot of a resolved framework config. */
+export function checkPipelineSeparation(slots) {
+    return [
+        ...checkPipelineSlot("vitePlugins", slots.vitePlugins ?? []),
+        ...checkPipelineSlot("clientPlugins", slots.clientPlugins ?? []),
+        ...checkPipelineSlot("serverPlugins", slots.serverPlugins ?? []),
+    ];
+}
+const pluginNames = (plugins) => plugins
+    .map((plugin, i) => {
+    const named = plugin.name;
+    return typeof named === "string" && named !== "" ? named : `vitePlugins[${i}]`;
+})
+    .join(", ");
+/**
+ * Pick the bundler for `nifra build`, per app rather than per global default.
+ *
+ * The phase defaults are deliberately asymmetric - `nifra dev` is Vite (for the plugin ecosystem, and
+ * because Bun's DEV-server bundler cannot compile CSS Modules), `nifra build` is Bun (faster and
+ * Bun-native). For an app with no transforms that asymmetry is free: there is nothing to disagree about.
+ * For an app whose ONLY transforms are Vite plugins it is not. Those plugins run in dev and are then
+ * dropped by the Bun build - `buildForTarget` reads `clientPlugins`/`serverPlugins`, never `vitePlugins`
+ * - so the build succeeds, the output looks plausible, and the transform simply did not happen. That is
+ * the same failure {@link checkPipelineSeparation} exists to prevent, reached by crossing PHASES instead
+ * of slots, and the slot check cannot see it because the plugins are correctly placed.
+ *
+ * So the default follows the app: Vite plugins with no Bun counterpart means the app has exactly one
+ * pipeline that can build it, and that is the one used. An app declaring BOTH has supplied the Bun
+ * equivalent on purpose - nothing is dropped - so the fast Bun default stands.
+ *
+ * `forced` is `--vite` / `--bun` and always wins, except for the one combination that silently discards
+ * work, which throws instead. Refusing rather than warning matches the slot guard: a build that succeeds
+ * and omits the transform is worse than one that stops and says so.
+ */
+export function chooseBuildPipeline(slots, forced) {
+    const vitePlugins = slots.vitePlugins ?? [];
+    const bunPlugins = [...(slots.clientPlugins ?? []), ...(slots.serverPlugins ?? [])];
+    const viteOnly = vitePlugins.length > 0 && bunPlugins.length === 0;
+    if (forced === "bun" && viteOnly) {
+        throw new Error("[nifra] `nifra build --bun` would silently drop this app's only transforms. `vitePlugins` are " +
+            "read by the Vite build; the Bun build reads `clientPlugins`/`serverPlugins`, so these would " +
+            "never run and the output would look plausible without them.\n" +
+            `  Would be dropped: ${pluginNames(vitePlugins)}\n` +
+            "  Drop the flag to build with Vite, or add the Bun equivalents to `clientPlugins`/`serverPlugins`.");
+    }
+    if (forced !== undefined)
+        return { pipeline: forced };
+    if (viteOnly) {
+        return {
+            pipeline: "vite",
+            reason: `auto: this app's only transforms are \`vitePlugins\` (${pluginNames(vitePlugins)}), which the Bun build cannot run`,
+        };
+    }
+    return { pipeline: "bun" };
+}
+//# sourceMappingURL=pipeline-guard.js.map

package/dist/pipeline-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-guard.js","sourceRoot":"","sources":["../src/pipeline-guard.ts"],"names":[],"mappings":"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"}

package/dist/types-search.d.ts

@@ -30,7 +30,7 @@ export declare function searchTypes(types: readonly TypeEntry[], query: string,
  * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
  * so this is the complete answer — there is no need to read a `.d.ts` file.
  */
-export declare function renderTypesResult(types: readonly TypeEntry[], name: string | undefined, query: string | undefined, limit: number): string;
+export declare function renderTypesResult(types: readonly TypeEntry[], name: string | undefined, query: string | undefined, limit: number, full?: boolean): string;
 /** Load the bundled type corpus (`docs/types.json`), resolved relative to this module so it works from
  * `src/` (dev) and `dist/` (published) alike. */
 export declare function loadTypesCorpus(): Promise<TypeEntry[] | undefined>;

package/dist/types-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types-search.d.ts","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;6BAC6B;AAC7B,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAGjF;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,UAAU,EAAE,CAed;AAQD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,GACZ,MAAM,CA0BR;AAED;iDACiD;AACjD,wBAAsB,eAAe,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAUxE"}
+{"version":3,"file":"types-search.d.ts","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;6BAC6B;AAC7B,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAGjF;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,UAAU,EAAE,CAed;AAuDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,UAAQ,GACX,MAAM,CA2BR;AAED;iDACiD;AACjD,wBAAsB,eAAe,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAUxE"}

package/dist/types-search.js

@@ -40,12 +40,56 @@ function renderEntry(t) {
     const doc = t.doc ? `${t.doc}\n` : "";
     return `${head}\n\n\`\`\`ts\n${doc}${t.signature}\n\`\`\``;
 }
+/**
+ * Longest signature rendered whole in a SEARCH result.
+ *
+ * Search is "which symbol did I mean?", not "show me everything about it" - and the corpus is wildly
+ * uneven: the median declaration is small, while `Server` alone is ~32,000 characters, five times the
+ * next largest. One broad query that happened to match it returned the entire class for near-zero
+ * value. Above this, a search result shows the head plus a member count and says how to get the rest;
+ * an exact `name` lookup is never collapsed, because there the caller asked for that symbol.
+ */
+const SEARCH_SIGNATURE_MAX = 600;
+/** First sentence of the doc block, flattened to one line - enough to pick between candidates. */
+function summarize(doc) {
+    if (doc === undefined)
+        return "";
+    const text = doc
+        .replace(/\/\*\*|\*\/|^\s*\*/gm, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (text === "")
+        return "";
+    const end = text.search(/\.\s|\.$/);
+    const sentence = end === -1 ? text : text.slice(0, end + 1);
+    return sentence.length > 200 ? `${sentence.slice(0, 197)}...` : sentence;
+}
+/** Keep the declaration head; replace a long body with a member count. */
+function collapseSignature(signature) {
+    const open = signature.indexOf("{");
+    if (open === -1)
+        return `${signature.slice(0, SEARCH_SIGNATURE_MAX)}…`;
+    const body = signature.slice(open);
+    // Rough but honest: count top-level-looking member lines rather than parsing TypeScript here.
+    const members = body.split("\n").filter((line) => /^\s{2,4}\S/.test(line)).length;
+    return `${signature.slice(0, open).trim()} { … ${members} members … }`;
+}
+/** A search hit: enough to choose, not the whole declaration. */
+function renderSearchHit(t) {
+    const head = `## ${t.name} — ${t.kind}, \`${t.package}\``;
+    const summary = summarize(t.doc);
+    const signature = t.signature.length <= SEARCH_SIGNATURE_MAX ? t.signature : collapseSignature(t.signature);
+    const note = t.signature.length <= SEARCH_SIGNATURE_MAX
+        ? ""
+        : `\n_Collapsed (${t.signature.length} chars). Call \`nifra_types({ name: "${t.name}" })\` for the full declaration._`;
+    return `${head}\n${summary ? `\n${summary}\n` : ""}\n\`\`\`ts\n${signature}\n\`\`\`${note}`;
+}
 /**
  * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a
  * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
  * so this is the complete answer — there is no need to read a `.d.ts` file.
  */
-export function renderTypesResult(types, name, query, limit) {
+export function renderTypesResult(types, name, query, limit, full = false) {
     if (name !== undefined && name.trim() !== "") {
         const hits = lookupType(types, name);
         if (hits.length === 0) {
@@ -58,7 +102,8 @@ export function renderTypesResult(types, name, query, limit) {
         if (matches.length === 0) {
             return `No types matched ${JSON.stringify(query)}. Try a broader term, pass an exact \`name\`, or call with no args for the index.`;
         }
-        return matches.map(renderEntry).join("\n\n---\n\n");
+        // Search results are collapsed by default; `full` opts back into whole declarations.
+        return matches.map(full ? renderEntry : renderSearchHit).join("\n\n---\n\n");
     }
     const byPkg = new Map();
     for (const t of types) {

package/dist/types-search.js.map

@@ -1 +1 @@
-{"version":3,"file":"types-search.js","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types-search.js","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"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"}

package/docs/examples.json

@@ -125,6 +125,12 @@
     "slug": "deployment",
     "code": "// _worker.ts — the edge SSR entry\nimport { toFetchHandler } from \"@nifrajs/core/server\"\nimport { createWebApp } from \"@nifrajs/web\"\nimport { reactAdapter } from \"@nifrajs/web-react\"\nimport { clientEntry, manifest } from \"./server-manifest\"  // generated by buildServer\n\nconst app = createWebApp({ adapter: reactAdapter, manifest, clientEntry })\nexport default toFetchHandler(app)   // a Workers/Pages fetch handler\n\n// build.ts — buildClient (→ /assets) + buildServer (edge conditions → _worker.js)\nimport { buildClient, buildServer } from \"@nifrajs/web/build\""
   },
+  {
+    "name": "VITE_PROD",
+    "topic": "Nifra — Dev & HMR",
+    "slug": "dev",
+    "code": "// vite.config.ts — a Vite/Rollup PRODUCTION client build (the escape hatch, not the default).\n// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; nifra's default\n// production bundler stays Bun (buildClient), which is faster and Bun-native.\nimport { viteLeakGuard } from \"@nifrajs/web/plugins/vite-leak-guard\"\n\nexport default {\n  build: {\n    // The SAME two client-leak guards nifra's Bun build runs — server-only code or a node: builtin\n    // reaching the browser fails the build, with the identical error message. A second production\n    // pipeline must not ship without them.\n    rollupOptions: { plugins: [viteLeakGuard()] },\n  },\n}"
+  },
   {
     "name": "LAB",
     "topic": "Nifra - Failure laboratory",

package/docs/llms-full.txt

@@ -780,15 +780,15 @@ cache. Pass the same `draftSecret` to `createWebApp` and
 
 ```ts
 // doc-check: skip — fragment spanning three files: your `app`, `env`, `redirect`, and route `slug`.
-// 1. A route you gate yourself flips draft mode on for the editor.
-import { enableDraft, disableDraft } from "@nifrajs/web"
+// 1. Mount the preview entry point your CMS links to. It checks the token in CONSTANT TIME,
+//    sets the signed HttpOnly cookie, and refuses an off-site ?to= (an open redirect otherwise).
+import { previewEndpoint, disableDraft } from "@nifrajs/web"
 
-app.get("/api/preview", async (c) => {
-  if (c.query.token !== env.PREVIEW_TOKEN) return new Response("nope", { status: 401 })
-  await enableDraft(c, env.DRAFT_SECRET) // signed, HttpOnly cookie
-  return redirect(String(c.query.to ?? "/"))
-})
+const preview = previewEndpoint({ secret: env.PREVIEW_TOKEN, draftSecret: env.DRAFT_SECRET })
+app.get("/api/preview", (c) => preview(c.req)) // ?token=…&to=/posts/hello
 app.get("/api/preview/exit", (c) => (disableDraft(c), redirect("/")))
+// Gating it yourself instead? Use enableDraft(c, env.DRAFT_SECRET) AFTER your own check — and
+// compare the token in constant time, since === leaks it one character at a time.
 
 // 2. Loaders branch on ctx.draft to load unpublished content.
 export async function loader({ api, draft }: LoaderArgs<typeof app>) {
@@ -2817,11 +2817,13 @@ the command printed by the build.
 
 ## Nifra — Dev & HMR
 
-> Use `nifra dev` for a Vite-backed state-preserving HMR loop, or `@nifrajs/web/dev` for a Bun-native live-reload loop. Production builds use Bun.
+> Use `nifra dev` for a Vite-backed state-preserving HMR loop, or `@nifrajs/web/dev` for a Bun-native HMR loop with no Vite dependency. Production builds use Bun.
 
-Nifra gives you two local development loops. Use `nifra dev` for
-state-preserving UI edits, or use `@nifrajs/web/dev` when you want a Bun-only
-live-reload server. Both serve your real SSR app locally.
+Nifra gives you two local development loops, and the rule between them is that one
+toolchain owns a whole phase. **Both** give you React Fast Refresh with state
+preserved. Use `nifra dev` (Vite) for the plugin ecosystem, or
+`nifra dev --bun` for one bundler across dev and prod with no Vite dependency.
+Both serve your real SSR app locally, and neither mixes the two bundlers in one process.
 
 ### Two loops, same app
 
@@ -2832,9 +2834,9 @@ use when
 
 `@nifrajs/web/dev`
 
-rebuild + full-page live-reload
+Bun HMR + Fast Refresh (native)
 none (Bun only)
-default; zero extra deps
+one bundler dev+prod; no Vite dep (no CSS Modules)
 
 `@nifrajs/web/vite`
 
@@ -2882,50 +2884,44 @@ can edit routes, components, loaders, actions, and styles in one local loop.
 
 ### Framework coverage
 
-All five adapters have a dev setup. Pass the framework's official Vite plugin, and for Vue,
-Svelte, and Solid, preload the matching Nifra compiler plugin for server rendering.
+All five adapters have a dev setup. Pass the framework's official Vite plugin and you are
+done: under `nifra dev` the Vite pipeline compiles both halves, so the same plugin
+that transforms your components for the browser also transforms them for SSR. No separate
+server-side compiler plugin to preload, and no way for the two halves to disagree about a
+specifier.
 
 framework
-client (Vite plugin)
-SSR compile
+Vite plugin (client + SSR)
 local state on edit
 
 React
 
 `@vitejs/plugin-react`
 
-Bun-native
 preserved (Fast Refresh)
 
 Preact
 
 `@preact/preset-vite`
 
-Bun-native
 preserved (prefresh)
 
 Vue
 
 `@vitejs/plugin-vue`
 
-`vueBunPlugin` preload
-
 preserved (rerender)
 
 Solid
 
 `vite-plugin-solid` (`{ ssr: true }`)
 
-`solidBunPlugin` preload
-
 resets (solid-refresh)
 
 Svelte
 
 `@sveltejs/vite-plugin-svelte`
 
-`svelteBunPlugin` preload
-
 resets (svelte HMR)
 
 For **React, Preact, and Vue**, an edit hot-swaps with component state preserved.
@@ -2968,17 +2964,72 @@ instead.
 
 ### The zero-dep alternative
 
-`@nifrajs/web/dev` is a self-contained server: it builds the client on boot,
-serves SSR, watches the routes, and does a full-page reload on change.
+`nifra dev --bun` (library: `@nifrajs/web/dev`) is self-contained —
+no Vite anywhere. `Bun.serve`'s native HMR bundles and hot-reloads the client while
+Bun's runtime resolves SSR, and it applies **React Fast Refresh natively**: editing
+a component-only module swaps its markup with `useState` state intact, no reload. The
+boundary rule is the same as Vite's (see below). The real prize is that dev and production use
+the _same bundler_, so the dev/prod seam disappears.
+
+One gap: **CSS Modules**. Bun's dev-server bundler has no
+`*.module.css` transform (its production `Bun.build` does), so the CLI
+refuses `--bun` for a CSS-Modules app rather than serving a broken client. Plain CSS
+and Tailwind work normally.
 
 ```ts
 // doc-check: skip — fragment: routesDir/outDir/clientModule/createApp are your app's dev config.
-// dev.ts — Bun-native live reload
+// dev.ts — Bun-native HMR, no Vite in the process
 import { createDevServer } from "@nifrajs/web/dev"
-// builds the client on boot, serves SSR, watches routes, full-page live-reload on change.
+// Bun.serve bundles + hot-reloads the client; Bun's runtime resolves SSR. An edit reloads the
+// changed module graph — with React Fast Refresh (state preserved) applied natively by Bun, no plugin.
+// CSS + the entry URL come from Bun. Plain CSS/Tailwind work; *.module.css does not (Bun's dev bundler).
 const server = await createDevServer({ routesDir, outDir, clientModule, createApp })
 ```
 
+### Production is Bun — with a Vite escape hatch
+
+Production builds default to **Bun** (`buildClient` /
+`nifra build`): faster, Bun-native, and the profile Nifra is tuned for. If an app
+genuinely needs a **Vite-only transform** with no Bun equivalent, you can run a
+Vite/Rollup production client build instead — but it must carry the same client-leak guards the
+Bun build enforces, or a second pipeline becomes a way for server-only code to reach the
+browser unnoticed. Add `viteLeakGuard()`: it runs the _same_ detection and
+emits the _same_ error as the Bun build (one implementation, adapted to Rollup's graph),
+so `node:` builtins and `server-only` modules fail the build either way.
+
+```ts
+// vite.config.ts — a Vite/Rollup PRODUCTION client build (the escape hatch, not the default).
+// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; nifra's default
+// production bundler stays Bun (buildClient), which is faster and Bun-native.
+import { viteLeakGuard } from "@nifrajs/web/plugins/vite-leak-guard"
+
+export default {
+  build: {
+    // The SAME two client-leak guards nifra's Bun build runs — server-only code or a node: builtin
+    // reaching the browser fails the build, with the identical error message. A second production
+    // pipeline must not ship without them.
+    rollupOptions: { plugins: [viteLeakGuard()] },
+  },
+}
+```
+
+For the full deploy, `nifra build --vite --target <t>` builds
+_both_ halves — client and SSR worker — with Vite and assembles the identical per-target
+deploy dir the Bun build produces (same `_worker.js` / `server.js`, same
+`_routes.json`, same prerender + size report). Only the bundler differs: both go
+through one orchestrator, so the deploy shape can't drift between pipelines. The leak guards run
+automatically.
+
+You usually don't need the flag. `nifra build` picks the bundler from your config:
+Bun by default, but Vite when your _only_ transforms are `vitePlugins`, and it
+prints the reason. That case is the one where the phase defaults would otherwise bite — dev runs
+Vite, so your plugins run; the Bun build reads `clientPlugins`/
+`serverPlugins` and never `vitePlugins`, so it would drop them and still
+succeed. An app declaring both slots has supplied the Bun equivalent on purpose, so it keeps the
+faster Bun default. `--vite` and `--bun` force the choice; `--bun`
+is refused for a `vitePlugins`-only app rather than silently building without your
+transforms.
+
 ### Styling (CSS)
 
 Import a stylesheet anywhere — `import "./app.css"` in a route, layout, or component.
@@ -7486,7 +7537,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NavigateOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateOptions`, `notFound`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `resolvePublicPath`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `servePublicDir`, `ServePublicDirOptions`, `ServerOnly`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `withISR`
 
 ## @nifrajs/web-preact