@nifrajs/web 3.1.0 → 3.2.0

package/dist/build.js

@@ -7,9 +7,10 @@
  */
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { cp, lstat, mkdir, realpath } from "node:fs/promises";
-import { dirname, join, relative, resolve as resolvePath, sep } from "node:path";
+import { dirname, join, basename as pathBasename, relative, resolve as resolvePath, sep, } from "node:path";
 import { singleCopyPlugin as declaredSingleCopyPlugin, readSingleCopyDeclaration, } from "@nifrajs/core/single-copy";
 import { Glob } from "bun";
+import { aggregateSizeReport, detectNodeBuiltinsInClient, detectServerOnlyInClient, formatNodeBuiltinLeak, formatServerOnlyLeak, parseManifestClientEntry, parseManifestRouteStyles, parseManifestStyles, planBuildTarget, } from "./build-plan.js";
 import { sanitizeOutputNames } from "./chunk-names.js";
 import { discoverRoutes } from "./fs.js";
 import { generateClientEntry, generateServerManifest } from "./index.js";
@@ -19,6 +20,18 @@ import { generateServerFnStub, SERVER_FN_MODULE, SERVER_ONLY_MODULE, SERVER_ONLY
 // `buildTarget(static)` drives the SSG prerender engine directly (it's also re-exported below).
 import { fromBunMetafile } from "./module-graph.js";
 import { prerenderRoutes } from "./prerender.js";
+export * from "./build-plan.js";
+const basename = (path) => pathBasename(path);
+// The lazy shape declares `const loaders`, the eager shape `const modules`. Anchored at a line start,
+// NOT `.includes("const loaders =")`: the real emit is `const loaders: Record<...> = {`, whose `:` type
+// annotation sits between the name and the `=`, so the ` =` substring never matched and every lazy
+// manifest was re-synced as eager (silently converting `import()` splitting into a single eager bundle).
+const MANIFEST_IS_LAZY = /^const loaders\b/m;
+const entryName = (file) => {
+    const base = basename(file);
+    const dot = base.lastIndexOf(".");
+    return dot === -1 ? base : base.slice(0, dot);
+};
 // Build-time SSG: prerender opted-in static + dynamic routes to `index.html` (+ static `_data.json`),
 // run after `buildClient`.
 export { cloudflarePagesRoutes, dataFileFor, htmlFileFor, prerenderRoutes, } from "./prerender.js";
@@ -191,442 +204,6 @@ export async function copyPublicDir(from, to) {
     }
     return copied.sort();
 }
-/** The `node:` specifier of an import edge, or undefined if it isn't a Node built-in. Reads the
- * `original` (as-written) specifier first, falling back to the resolved `path` (an `external` node:
- * import keeps `node:` in its path). */
-const nodeBuiltinOf = (im) => {
-    if (im.original?.startsWith("node:"))
-        return im.original;
-    if (im.path?.startsWith("node:"))
-        return im.path;
-    return undefined;
-};
-/**
- * BFS the metafile import graph for the SHORTEST user-module path that pulls `builtin` into the
- * bundle, returning it as display labels `[entryFile, …as-written specifiers…, builtin]`. The frontier
- * starts at every `entryInput` (the route/user entrypoints) so the reported chain begins where the dev
- * actually wrote `import` - the actionable root, not an arbitrary internal module. Traversal crosses
- * only NON-`node:` edges (so Bun's polyfill chain never extends the path) and stops at the first edge
- * whose target is the builtin. Returns `[builtin]` if no entry reaches it (defensive; a flagged builtin
- * is reachable by construction). Pure - operates on the graph, never the emitted text.
- */
-function shortestBuiltinChain(inputs, entryInputs, builtin) {
-    // Each queue item carries the resolved-path node + the display chain to reach it (entry + the
-    // as-written specifier of every hop crossed so far). `seen` dedupes nodes so the BFS is linear and
-    // the first time we touch the builtin's importer is via a shortest path.
-    const seen = new Set(entryInputs);
-    let frontier = entryInputs.map((node) => ({
-        node,
-        chain: [node],
-    }));
-    while (frontier.length > 0) {
-        const next = [];
-        for (const { node, chain } of frontier) {
-            for (const im of inputs[node]?.imports ?? []) {
-                // The builtin reached via THIS edge → the chain ends here (append the builtin label). Match on
-                // the same `node:` detection the finding used (`original` first, then resolved `path`).
-                if (nodeBuiltinOf(im) === builtin)
-                    return [...chain, builtin];
-                const target = im.path;
-                // Only follow edges into user (non-`node:`) modules that exist in the input graph and haven't
-                // been visited - so the polyfill subtree can't lengthen the path and there are no cycles.
-                if (target === undefined ||
-                    target.startsWith("node:") ||
-                    inputs[target] === undefined ||
-                    seen.has(target)) {
-                    continue;
-                }
-                seen.add(target);
-                // Display the hop by its as-written specifier (`../db/client.ts`, `postgres`), falling back to
-                // the resolved path - that's what the dev recognizes in their source, not the resolved path.
-                next.push({ node: target, chain: [...chain, im.original ?? target] });
-            }
-        }
-        frontier = next;
-    }
-    return [builtin]; // unreachable from any entry - degrade to just the builtin (shouldn't happen)
-}
-/**
- * Scan a build's metafile for any `node:` builtin that a USER module pulled into a CLIENT output
- * chunk, returning a sorted, deduped list of {@link NodeBuiltinFinding}s. Three graph facts combine so
- * the report is precise AND actionable:
- *  1. **What the user wrote** - only builtins imported by a NON-`node:` input count, so Bun's own
- *     polyfill chain (`node:crypto` → `node:buffer`/`node:stream`/…) doesn't bury the real cause.
- *  2. **Where it landed** - the chunk is read from the per-output `inputs`, so the error names the
- *     emitted file to look at.
- *  3. **How it got there** - the shortest import chain from a user entry to the builtin
- *     (`shortestBuiltinChain`), so the error points straight at the offending `import` line instead of
- *     leaving the dev to grep the dependency tree (the DX gap this closes).
- * Graph-based (never the emitted text), so it survives minification and can't be fooled by a string
- * literal that merely contains `"node:crypto"`. Pure + exported for unit testing. Empty ⇒ clean.
- */
-export function detectNodeBuiltinsInClient(graph) {
-    const inputs = graph.modules;
-    // (1) The builtins a user (non-polyfill) module imports directly - the ones the author controls.
-    const userImported = new Set();
-    for (const [inputKey, input] of Object.entries(inputs)) {
-        if (inputKey.startsWith("node:"))
-            continue; // a polyfill importing another builtin - not the cause
-        for (const im of input.imports ?? []) {
-            const builtin = nodeBuiltinOf(im);
-            if (builtin !== undefined)
-                userImported.add(builtin);
-        }
-    }
-    // The entry inputs (route/user entrypoints) - the chain BFS starts here so the reported path begins
-    // at the file the dev wrote an `import` in. Each output's `entryPoint` is one such input.
-    const entryInputs = [
-        ...new Set(Object.values(graph.chunks)
-            .map((o) => o.entryPoint)
-            .filter((e) => e !== undefined && !e.startsWith("node:"))),
-    ];
-    // The chain per builtin is independent of the chunk, so compute it once per builtin (memoized).
-    const chainCache = new Map();
-    const chainFor = (builtin) => {
-        const cached = chainCache.get(builtin);
-        if (cached !== undefined)
-            return cached;
-        const chain = shortestBuiltinChain(inputs, entryInputs, builtin);
-        chainCache.set(builtin, chain);
-        return chain;
-    };
-    // (2) Locate which emitted chunk each user-imported builtin reached, via the per-output `inputs`.
-    const findings = new Map();
-    for (const [outPath, out] of Object.entries(graph.chunks)) {
-        for (const inputKey of out.modules) {
-            if (userImported.has(inputKey)) {
-                const chunk = basename(outPath);
-                findings.set(`${inputKey}\0${chunk}`, {
-                    builtin: inputKey,
-                    chunk,
-                    chain: chainFor(inputKey),
-                });
-            }
-        }
-    }
-    return [...findings.values()].sort((a, b) => a.builtin === b.builtin ? a.chunk.localeCompare(b.chunk) : a.builtin.localeCompare(b.builtin));
-}
-// ---------------------------------------------------------------------------------------------------
-// `server-only` poison-import guard (§3.3/§5.1). The complement to the `.server` convention + the
-// node-builtin guard: a module of PURE server logic with NO `node:` import (a secret-bearing constant,
-// a server-only API call) that an author wants to FAIL LOUD if it reaches the client opts in with a
-// side-effect `import "@nifrajs/web/server-only"` (Next's `import "server-only"`). On the SERVER build
-// the marker is an empty no-op; the CLIENT build detects - via the SAME Bun metafile graph the
-// node-builtin guard walks - any module that imports the marker AND lands in a client chunk, and fails
-// the build with the import chain. Graph-based (never the emitted text), so it survives minification.
-// ---------------------------------------------------------------------------------------------------
-/** The marker specifier an author imports to opt a module into the client-leak guard. Matched on the
- * import edge's *as-written* `original` first (the robust signal: it's exactly what the author typed,
- * before Bun resolves it to `src/server-only.ts` / `dist/server-only.js`). */
-export const SERVER_ONLY_MARKER = "@nifrajs/web/server-only";
-/** True when an import edge is the `server-only` marker import. Reads the as-written `original` (the
- * specifier the author typed); falls back to the resolved `path`'s basename so a pre-resolved edge
- * (no `original`) - or a workspace-relative resolution - is still recognised. */
-const isServerOnlyMarkerImport = (im) => {
-    if (im.original === SERVER_ONLY_MARKER)
-        return true;
-    // Defensive fallback: an edge that lost its `original` but resolved to the marker module file. The
-    // marker is the only `server-only.{ts,js}` under `@nifrajs/web`, so the basename is unambiguous.
-    const path = im.path;
-    return path !== undefined && /(^|\/)server-only\.[cm]?[jt]s$/.test(path);
-};
-/**
- * BFS the metafile import graph for the SHORTEST user-module path that reaches a module which imports
- * the `server-only` marker, returning it as display labels `[entryFile, …as-written specifiers…,
- * "<module> (marked server-only)"]`. Mirrors {@link shortestBuiltinChain}: the frontier starts at
- * every `entryInput` so the chain begins at the file the dev wrote an `import` in; traversal crosses
- * only NON-`node:` user edges (no cycles via `seen`); it stops at the first node whose import set
- * contains the marker (the marked module - the actionable tail), labelling that node by the as-written
- * specifier the previous hop used to reach it. Pure - operates on the graph, never the emitted text.
- */
-function shortestServerOnlyChain(inputs, entryInputs, markedModule, resolveTarget) {
-    // The label for the marked module's tail: its as-written specifier (filled when we cross the edge
-    // that reaches it) suffixed with `(marked server-only)`; the entry case uses the entry key itself.
-    const tail = (label) => `${label} (marked server-only)`;
-    // An entry that is ITSELF the marked module - the chain is just that one node.
-    if (entryInputs.includes(markedModule))
-        return [tail(markedModule)];
-    const seen = new Set(entryInputs);
-    let frontier = entryInputs.map((node) => ({
-        node,
-        chain: [node],
-    }));
-    while (frontier.length > 0) {
-        const next = [];
-        for (const { node, chain } of frontier) {
-            for (const im of inputs[node]?.imports ?? []) {
-                // Resolve the edge's `path` to the matching INPUT-GRAPH KEY - in a real build the edge `path`
-                // is absolute while the input keys are cwd-relative, so a raw equality/lookup would miss every
-                // multi-hop user edge (and the chain would degrade to just the tail). The resolver maps both.
-                const target = resolveTarget(im);
-                if (target === undefined || target.startsWith("node:"))
-                    continue;
-                // The marked module reached via THIS edge → the chain ends here (label it as the marked tail
-                // using the as-written specifier the author wrote, falling back to the resolved key).
-                if (target === markedModule)
-                    return [...chain, tail(im.original ?? target)];
-                if (seen.has(target))
-                    continue;
-                seen.add(target);
-                next.push({ node: target, chain: [...chain, im.original ?? target] });
-            }
-        }
-        frontier = next;
-    }
-    return [tail(markedModule)]; // unreachable from any entry (defensive; a flagged module is reachable)
-}
-/**
- * Build a resolver from an import EDGE to its INPUT-GRAPH KEY. Bun's metafile records edge `path`s as
- * ABSOLUTE paths but keys `inputs` by CWD-RELATIVE paths, so a raw `inputs[im.path]` lookup misses
- * every user edge in a real build. The resolver: (1) an exact key match (the synthetic-metafile / unit
- * case); else (2) the input key the absolute path ends with (`…/secrets.ts` → `packages/web/.../secrets.ts`).
- * The longest-suffix match is taken so a shorter key can't shadow a more specific one. Pure.
- */
-function inputKeyResolver(inputs) {
-    const keys = Object.keys(inputs);
-    return (im) => {
-        const path = im.path;
-        if (path === undefined)
-            return undefined;
-        if (inputs[path] !== undefined)
-            return path; // exact (synthetic keys, or already-relative paths)
-        let best;
-        for (const key of keys) {
-            // `/<key>` so a suffix match aligns on a path boundary (never a partial segment), and the longest
-            // such key wins (the most specific file).
-            if (path.endsWith(`/${key}`) && (best === undefined || key.length > best.length))
-                best = key;
-        }
-        return best;
-    };
-}
-/**
- * Scan a build's metafile for any module that opts into the `server-only` marker (a side-effect
- * `import "@nifrajs/web/server-only"`) yet landed in a CLIENT output chunk, returning a sorted, deduped
- * list of {@link ServerOnlyFinding}s. Mirrors {@link detectNodeBuiltinsInClient}: it reads the SAME
- * graph facts - which inputs import the marker (the "marked" modules), which chunk each landed in (the
- * per-output `inputs`), and the shortest import chain from a user entry to it. The marker module ITSELF
- * (which imports nothing) is excluded - only the modules that *opt in* are flagged. Pure + exported for
- * unit testing. Empty ⇒ clean.
- */
-export function detectServerOnlyInClient(graph) {
-    const inputs = graph.modules;
-    // (1) The modules that import the marker - the ones the author opted into the guard. The marker
-    // module itself is skipped: it's the import TARGET, not an opt-in (it imports nothing of its own).
-    const marked = new Set();
-    for (const [inputKey, input] of Object.entries(inputs)) {
-        if (isServerOnlyMarkerModule(inputKey))
-            continue;
-        if ((input.imports ?? []).some(isServerOnlyMarkerImport))
-            marked.add(inputKey);
-    }
-    if (marked.size === 0)
-        return [];
-    // The entry inputs - the chain BFS starts here, so the reported path begins at the file the dev
-    // wrote an `import` in. Same derivation as the node-builtin guard.
-    const entryInputs = [
-        ...new Set(Object.values(graph.chunks)
-            .map((o) => o.entryPoint)
-            .filter((e) => e !== undefined && !e.startsWith("node:"))),
-    ];
-    const resolveTarget = inputKeyResolver(inputs);
-    const chainCache = new Map();
-    const chainFor = (markedModule) => {
-        const cached = chainCache.get(markedModule);
-        if (cached !== undefined)
-            return cached;
-        const chain = shortestServerOnlyChain(inputs, entryInputs, markedModule, resolveTarget);
-        chainCache.set(markedModule, chain);
-        return chain;
-    };
-    // (2) Locate which emitted chunk each marked module reached, via the per-output `inputs`.
-    const findings = new Map();
-    for (const [outPath, out] of Object.entries(graph.chunks)) {
-        for (const inputKey of out.modules) {
-            if (marked.has(inputKey)) {
-                const chunk = basename(outPath);
-                findings.set(`${inputKey}\0${chunk}`, { chunk, chain: chainFor(inputKey) });
-            }
-        }
-    }
-    return [...findings.values()].sort((a, b) => {
-        const am = a.chain[a.chain.length - 1] ?? "";
-        const bm = b.chain[b.chain.length - 1] ?? "";
-        return am === bm ? a.chunk.localeCompare(b.chunk) : am.localeCompare(bm);
-    });
-}
-/** True when an INPUT graph key is the marker module file itself (`…/server-only.{ts,js}` under web).
- * Excluded from the "marked" set - the marker is the import target, not an opt-in module. */
-const isServerOnlyMarkerModule = (inputKey) => /(^|\/)server-only\.[cm]?[jt]s$/.test(inputKey);
-// ---------------------------------------------------------------------------------------------------
-// Guard MESSAGES - one owner for both production pipelines. The Bun build (below) and the Vite/Rollup
-// leak-guard plugin (plugins/vite-leak-guard.ts) both call these, so a leak reads IDENTICALLY whichever
-// bundler produced it. A second bundler must not grow a second, subtly-different wording of a security
-// error; that is exactly the "mostly ported" outcome the neutral graph seam exists to prevent.
-// ---------------------------------------------------------------------------------------------------
-/** The build-failing message for `node:` builtins that reached the client bundle. `undefined` ⇒ clean. */
-export function formatNodeBuiltinLeak(findings) {
-    if (findings.length === 0)
-        return undefined;
-    const lines = findings.map((f) => f.chain.length > 1
-        ? `  - ${f.builtin} reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
-        : `  - ${f.builtin} reached the client bundle via ${f.chunk}`);
-    return (`[nifra/web] Node built-in(s) in the client bundle - move them behind a server-only path ` +
-        `(a loader/action runs on the server; import the \`node:\` module there, not at a route's ` +
-        `top level):\n${lines.join("\n")}`);
-}
-/** The build-failing message for `server-only`-marked modules that reached the client. `undefined` ⇒ clean. */
-export function formatServerOnlyLeak(findings) {
-    if (findings.length === 0)
-        return undefined;
-    const lines = findings.map((f) => f.chain.length > 1
-        ? `  - server-only module reached the client bundle via ${f.chain.join(" → ")} (chunk: ${f.chunk})`
-        : `  - server-only module reached the client bundle via ${f.chunk}`);
-    return (`[nifra/web] server-only module(s) in the client bundle - a module marked ` +
-        `\`import "${SERVER_ONLY_MARKER}"\` reached the browser. Move it behind a server-only path ` +
-        `(reach it via a loader/action, or rename it \`*.server.ts\`), so its server logic never ships ` +
-        `to the client:\n${lines.join("\n")}`);
-}
-const basename = (path) => path.slice(path.lastIndexOf("/") + 1);
-/** `[name]` Bun derives for an entrypoint: basename without extension (`users/[id].tsx` → `[id]`). */
-const entryName = (file) => {
-    const base = basename(file);
-    const dot = base.lastIndexOf(".");
-    return dot === -1 ? base : base.slice(0, dot);
-};
-/**
- * Aggregate a list of measured chunks into a {@link SizeReport}: sort biggest-gzip-first (ties broken
- * by raw bytes, then name for stable output) and sum the totals. Pure - the measurement (reading the
- * file + `Bun.gzipSync`) happens in the orchestrator; this is the deterministic, unit-testable core.
- */
-export function aggregateSizeReport(chunks) {
-    const sorted = [...chunks].sort((a, b) => b.gzip - a.gzip || b.bytes - a.bytes || a.name.localeCompare(b.name));
-    let totalBytes = 0;
-    let totalGzip = 0;
-    for (const c of sorted) {
-        totalBytes += c.bytes;
-        totalGzip += c.gzip;
-    }
-    return { chunks: sorted, totalBytes, totalGzip };
-}
-/** Human-readable byte count: `B`/`KB`/`MB` with one decimal above 1 KB (e.g. `12.3 KB`). Pure. */
-export function formatBytes(bytes) {
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-/**
- * Render a {@link SizeReport} as a terse aligned table (biggest first) with a totals row - the text
- * `nifra build --report` prints. Pure (string in, string out) so the formatting is unit-testable.
- */
-export function renderSizeReport(report) {
-    const rows = report.chunks.map((c) => ({
-        name: c.name,
-        raw: formatBytes(c.bytes),
-        gz: formatBytes(c.gzip),
-    }));
-    // Column widths from the header + every row + the totals label, so the table never clips a value.
-    const nameW = Math.max(5, ...rows.map((r) => r.name.length), "Total".length);
-    const rawW = Math.max(3, ...rows.map((r) => r.raw.length), formatBytes(report.totalBytes).length);
-    const gzW = Math.max(4, ...rows.map((r) => r.gz.length), formatBytes(report.totalGzip).length);
-    const padEnd = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
-    const padStart = (s, w) => " ".repeat(Math.max(0, w - s.length)) + s;
-    const line = (name, raw, gz) => `  ${padEnd(name, nameW)}  ${padStart(raw, rawW)}  ${padStart(gz, gzW)}`;
-    const out = [
-        line("Chunk", "Raw", "Gzip"),
-        line("-".repeat(nameW), "-".repeat(rawW), "-".repeat(gzW)),
-        ...rows.map((r) => line(r.name, r.raw, r.gz)),
-        line("Total", formatBytes(report.totalBytes), formatBytes(report.totalGzip)),
-    ];
-    return out.join("\n");
-}
-// The route-relative file keys the generated manifest's route map declares. Both shapes are matched by
-// their VALUE: eager `  "routes/x.tsx": m0,` and lazy `  "routes/x.tsx": () => import("./routes/x"),`.
-// The KEY (not the import specifier) is the route identity `discoverRoutes` produces, extension and all;
-// the import specifier is emitted extensionless (so a bare `tsc` compiles the manifest) and could not be
-// mapped back to the exact `.tsx`/`.ts` key. The baked `routeStyles` JSON is a single line, so its keys
-// are never at an indented line start and never match. `[ \t]+` (not `\s+`) so the `m` anchor stays on
-// the same line and one route-map entry cannot span two lines of source.
-const MANIFEST_ROUTE_ENTRY = /^[ \t]+(["'])([^"'\n]+)\1\s*:\s*(?:m\d+\b|\(\s*\)\s*=>\s*import\b)/gm;
-// The lazy shape declares `const loaders`, the eager shape `const modules`. Anchored at a line start,
-// NOT `.includes("const loaders =")`: the real emit is `const loaders: Record<...> = {`, whose `:` type
-// annotation sits between the name and the `=`, so the ` =` substring never matched and every lazy
-// manifest was re-synced as eager (silently converting `import()` splitting into a single eager bundle).
-const MANIFEST_IS_LAZY = /^const loaders\b/m;
-// The baked client-entry line: `export const clientEntry = "…"`.
-const MANIFEST_CLIENT_ENTRY = /export\s+const\s+clientEntry\s*=\s*["']([^"']+)["']/;
-/**
- * Extract the route-relative file list a committed server-manifest declares, as the same
- * `routes/`-relative keys `discoverRoutes` produces (e.g. `docs/index.tsx`). Reads the route map's KEYS,
- * which carry the file extension and no directory prefix - exactly discovery's shape - so the result is
- * independent of the specifier prefix the manifest happened to import with. The `@nifrajs/web` import and
- * the baked `clientEntry`/`styles`/`routeStyles` lines carry no route-map entry and are ignored.
- *
- * `_routesPrefix` is accepted for call-site compatibility but no longer needed: the keys are already
- * prefix-free. Pure - operates on source text.
- */
-export function parseManifestRouteFiles(source, _routesPrefix) {
-    const files = new Set();
-    for (const match of source.matchAll(MANIFEST_ROUTE_ENTRY)) {
-        if (match[2] !== undefined)
-            files.add(match[2]);
-    }
-    return [...files].sort();
-}
-/** The baked `clientEntry` URL in a committed server-manifest, or `undefined` if absent. Pure. */
-export function parseManifestClientEntry(source) {
-    return MANIFEST_CLIENT_ENTRY.exec(source)?.[1];
-}
-// The baked asset lines `generateServerManifest` emits: `export const styles = […]` then
-// `export const routeStyles = {…}`, each a JSON literal running to the next `export const`. Extracted
-// with `indexOf` slicing rather than a lazy `[\s\S]*?` regex: the slice is multi-line by nature (a
-// formatter can wrap a long `routeStyles` map, and missing it would silently DROP every baked
-// stylesheet on re-sync), and a lazy scan re-walks the file per unterminated opener - quadratic.
-function bakedManifestLiteral(source, name) {
-    const opener = `export const ${name} = `;
-    const start = source.indexOf(opener);
-    if (start === -1)
-        return undefined;
-    const from = start + opener.length;
-    const end = source.indexOf("\nexport const ", from);
-    return end === -1 ? undefined : source.slice(from, end);
-}
-/** Parse a baked JSON literal captured from a committed manifest, tolerating a formatter's TRAILING COMMAS
- * (biome/prettier add one when wrapping a multi-line array/object; strict `JSON.parse` would reject it).
- * Only a comma immediately before a closing `]`/`}` is stripped, so commas inside string values are safe. */
-function parseManifestLiteral(raw) {
-    return JSON.parse(raw.replace(/,(\s*[\]}])/g, "$1"));
-}
-/** The baked top-level `styles` array in a committed server-manifest (empty if absent/unparseable). Pure. */
-export function parseManifestStyles(source) {
-    const raw = bakedManifestLiteral(source, "styles");
-    if (raw === undefined)
-        return [];
-    try {
-        const value = parseManifestLiteral(raw);
-        return Array.isArray(value) ? value : [];
-    }
-    catch {
-        return [];
-    }
-}
-/** The baked per-route `routeStyles` map in a committed server-manifest (empty if absent/unparseable). Pure. */
-export function parseManifestRouteStyles(source) {
-    const raw = bakedManifestLiteral(source, "routeStyles");
-    if (raw === undefined)
-        return {};
-    try {
-        const value = parseManifestLiteral(raw);
-        return value !== null && typeof value === "object" && !Array.isArray(value)
-            ? value
-            : {};
-    }
-    catch {
-        return {};
-    }
-}
 /**
  * Re-emit a committed server-manifest from a freshly-discovered route tree, PRESERVING its baked
  * client-asset references (`clientEntry` / `styles` / `routeStyles`) and its eager-vs-lazy shape. This is
@@ -651,37 +228,6 @@ export function resyncServerManifestSource(source, manifest, routesPrefix) {
  * supplies both file lists (the committed source is parsed via {@link parseManifestRouteFiles}; the
  * fresh list comes from `discoverRoutes`). Lists need not be pre-sorted; the result is sorted.
  */
-export function diffManifestRoutes(manifestFiles, discoveredFiles) {
-    const inManifest = new Set(manifestFiles);
-    const inRoutes = new Set(discoveredFiles);
-    const missing = discoveredFiles.filter((f) => !inManifest.has(f)).sort();
-    const extra = manifestFiles.filter((f) => !inRoutes.has(f)).sort();
-    return { missing, extra };
-}
-/** True when a drift report is clean (no missing + no extra routes). */
-export function isManifestInSync(drift) {
-    return drift.missing.length === 0 && drift.extra.length === 0;
-}
-/**
- * Format a {@link ManifestDrift} as a named, actionable error message, or `undefined` when in sync.
- * Names the exact missing/extra routes + the one fix (regenerate the manifest by re-running the build).
- * `manifestPath` is shown for the dev to locate the stale file. Pure.
- */
-export function formatManifestDrift(drift, manifestPath = "server-manifest.ts") {
-    if (isManifestInSync(drift))
-        return undefined;
-    const lines = [
-        `[nifra/web] server-manifest drift - \`${manifestPath}\` is out of sync with routes/.`,
-    ];
-    if (drift.missing.length > 0) {
-        lines.push(`  Missing (in routes/, not in the manifest - these routes won't be served): ${drift.missing.join(", ")}`);
-    }
-    if (drift.extra.length > 0) {
-        lines.push(`  Extra (imported by the manifest, gone from routes/ - a dangling import): ${drift.extra.join(", ")}`);
-    }
-    lines.push("  Fix: re-run the build to regenerate the server manifest, then commit it.");
-    return lines.join("\n");
-}
 /**
  * Build the client bundle for a file-routed app. Writes the hashed assets + `manifest.json` to
  * `outDir` and returns the manifest. Throws (with the bundler logs) on build failure - never
@@ -693,6 +239,20 @@ export async function buildClient(options) {
     await assertIdentityParity(root);
     const resolve = options.resolve ?? ((file) => `${routesDir}/${file}`);
     const publicPath = options.publicPath ?? "/assets/";
+    // outDir inside publicDir folds the build output back into the public copy on the next run (the
+    // bundle lands at public/assets/assets/*), and the dev/prod parity assert then throws on paths no
+    // one authored. Reject the overlap up front - no copy behavior is correct for this layout, and the
+    // parity symptom names neither option so the cause is unrecoverable from the message.
+    const publicRoot = options.publicDir === false ? undefined : (options.publicDir ?? "public");
+    if (publicRoot !== undefined) {
+        const publicResolved = resolvePath(publicRoot);
+        const outResolved = resolvePath(outDir);
+        if (outResolved === publicResolved || outResolved.startsWith(publicResolved + sep)) {
+            throw new Error(`[nifra/web] outDir (${outResolved}) is inside publicDir (${publicResolved}). The public ` +
+                `copy would fold the build output back into itself. Move outDir outside publicDir, or ` +
+                `pass publicDir: false if the app has no hand-authored static files.`);
+        }
+    }
     mkdirSync(outDir, { recursive: true });
     const routeManifest = discoverRoutes(routesDir);
     // The bootstrap's filename is `_nifra`-namespaced (not `entry.ts`) so its `[name]` can't collide with
@@ -862,7 +422,12 @@ export async function buildClient(options) {
         return [...new Set(urls)];
     };
     const routeStyles = {};
-    if (css.length > 0 && cssByEntry.size > 0) {
+    // A compiler plugin may attach a global stylesheet to the generated bootstrap rather than to a
+    // route entry (StyleX's atomic CSS is one example). In that shape there is no useful per-route map:
+    // emitting `routeId: []` would suppress the aggregate `styles` fallback in `createWebApp` and render
+    // SSR pages unstyled. Keep routeStyles absent until at least one authored route entry owns CSS.
+    const routeCssEntries = [...cssByEntry.keys()].filter((entry) => entry !== resolvePath(entryFile));
+    if (css.length > 0 && routeCssEntries.length > 0) {
         for (const route of routeManifest.routes) {
             routeStyles[route.id] = stylesFor([
                 ...route.layoutIds.map((id) => routeManifest.layouts[id]?.file ?? ""),
@@ -888,6 +453,7 @@ export async function buildClient(options) {
     writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2));
     return manifest;
 }
+/** The built worker bundle - point your `wrangler.toml`'s `main` at `worker`. */
 /**
  * react-dom's `exports["./server"]` maps the `bun` condition to a Bun-API server build that crashes
  * on workerd, and `Bun.build` always applies the `bun` condition (it wins over `workerd`/`edge-light`),
@@ -1130,12 +696,6 @@ export async function buildServer(options) {
 // The ONLY thing apps used to hand-write per target was the server entry (`_worker.ts`, `server-bun.ts`,
 // …) - so we GENERATE it here (per target) instead of asking each app to ship five near-identical files.
 // ===================================================================================================
-/** A deploy target `nifra build --target <t>` can emit. `static` is pure SSG (no server). */
-export const BUILD_TARGETS = ["bun", "node", "deno", "cf-pages", "vercel", "static"];
-/** A type guard narrowing an arbitrary string to a {@link BuildTarget}. */
-export function isBuildTarget(value) {
-    return BUILD_TARGETS.includes(value);
-}
 /**
  * Codegen the per-target **server entry** module (source text) for `buildServer` to bundle. It imports
  * the app's `adapter` (from `framework.ts`), the optional `backend` (from `backend.ts`), and the
@@ -1203,14 +763,6 @@ export function generateServerEntry(options) {
     lines.push("const handler = toFetchHandler(app)", "// @ts-ignore - Deno global is present on the Deno runtime this output targets.", 'Deno.serve({ port: Number(Deno.env.get("PORT") ?? "3000") }, async (req) => {', "  const { pathname } = new URL(req.url)", "  const filePath = staticPath(pathname)", "  if (filePath !== undefined) {", "    try {", "      // @ts-ignore - Deno.readFile is present on the Deno runtime.", "      const body = await Deno.readFile(new URL(filePath, STATIC_ROOT))", '      const ext = pathname.slice(pathname.lastIndexOf(".") + 1)', '      return new Response(body, { headers: { "content-type": TYPES[ext] ?? "application/octet-stream" } })', "    } catch {", '      return new Response("not found", { status: 404 })', "    }", "  }", "  return handler.fetch(req)", "})");
     return `${lines.join("\n")}\n`;
 }
-/** The Bun.build `target` each deploy target compiles its server with (mirrors `buildServer`'s docs). */
-const SERVER_BUILD_TARGET = {
-    "cf-pages": "browser", // edge conditions (workerd/edge-light)
-    vercel: "browser", // Vercel Edge runtime
-    deno: "browser", // Deno's Web-standard runtime runs the edge bundle
-    node: "node", // node:* external; react-dom → its Node SSR build
-    bun: "bun", // Bun's flagship runtime
-};
 /** Measure each emitted output file's raw + gzip size. Reads the file off disk and gzips it with
  * `Bun.gzipSync` (the over-the-wire weight). Async only because it reads files; the aggregation is the
  * pure {@link aggregateSizeReport}. */
@@ -1226,6 +778,21 @@ async function measureOutputs(paths) {
     }
     return chunks;
 }
+/**
+ * Build a full deploy directory for `target` from a file-routed nifra app. Emits the client bundle to
+ * `<outDir>/assets/*`, then per target:
+ *   - `static`: prerenders opted-in routes (`prerenderRoutes`) to `<outDir>/<path>/index.html` (+
+ *     `_data.json`); needs `prerenderApp`. No server.
+ *   - `cf-pages`: a `_worker.js` (edge bundle) + a `_routes.json` excluding /assets/* from the worker.
+ *   - `vercel`: a `.vercel/output`-shaped function isn't emitted here - `vercel` emits the bundled edge
+ *     entry as `<outDir>/index.js` (the CLI's docs point at `vercel`'s Build Output wrapper). [see note]
+ *   - `deno`/`node`/`bun`: the self-hosting server bundle (`server.js`) next to the assets.
+ * The server entry is GENERATED (`generateServerEntry`) and bundled (`buildServer`); the app supplies
+ * only adapter/backend/routes. Returns the manifest + a size report. Throws on any build failure.
+ *
+ * Note: the heavier platform wrappers (`.vercel/output` v3 layout, wrangler ISR `find_additional_modules`)
+ * remain app-owned scripts; this command targets the common single-bundle deploys. See the CLI docs.
+ */
 /** The default (Bun) strategy - `buildClient`/`buildServer` from this module. */
 export const bunBundler = {
     buildClient: (input) => buildClient({
@@ -1260,6 +827,7 @@ export async function buildTarget(target, options) {
  */
 export async function buildTargetWith(target, options, bundler) {
     const { routesDir, outDir, workDir } = options;
+    const targetPlan = planBuildTarget(target, outDir);
     const { rmSync } = await import("node:fs");
     rmSync(outDir, { recursive: true, force: true });
     rmSync(workDir, { recursive: true, force: true });
@@ -1286,7 +854,7 @@ export async function buildTargetWith(target, options, bundler) {
         client = { ...client, publicFiles };
         writeFileSync(`${assetsDir}/manifest.json`, JSON.stringify(client, null, 2));
     }
-    if (target === "static") {
+    if (targetPlan.kind === "static") {
         if (options.prerenderApp === undefined) {
             throw new Error("[nifra/web] buildTarget(static) requires `prerenderApp` (a factory `(client) => createWebApp`)");
         }
@@ -1312,7 +880,7 @@ export async function buildTargetWith(target, options, bundler) {
             target,
             outDir,
             client,
-            run: `static site → ${outDir} (serve the directory with any static host)`,
+            run: targetPlan.run,
             size,
         };
     }
@@ -1328,22 +896,20 @@ export async function buildTargetWith(target, options, bundler) {
         ...(options.title !== undefined ? { title: options.title } : {}),
         ...(publicFiles.length > 0 ? { publicFiles } : {}),
     }));
-    const serverTarget = SERVER_BUILD_TARGET[target];
     const { worker } = await bundler.buildServer({
         routesDir,
         serverEntry: serverEntryPath,
         outDir: `${workDir}/server`,
         clientEntry: client.entry,
-        target: serverTarget,
+        target: targetPlan.serverTarget,
         ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
         define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
         root: resolvePath(dirname(routesDir)),
     });
     // (3) Assemble the deploy dir for the target.
     const { cpSync } = await import("node:fs");
-    let run;
-    if (target === "cf-pages") {
-        cpSync(worker, `${outDir}/_worker.js`);
+    if (targetPlan.target === "cf-pages") {
+        cpSync(worker, `${outDir}/${targetPlan.outputFile}`);
         // The app's real patterns, so a directory is only collapsed into a glob once the route table
         // proves nothing can be served beneath it.
         const rules = cloudflareRouteRules(publicFiles, discoverRoutes(routesDir).routes.map((route) => route.pattern));
@@ -1355,26 +921,19 @@ export async function buildTargetWith(target, options, bundler) {
                 `(Cloudflare allows ${CF_MAX_ROUTE_RULES}). The other ${rules.omitted.length} file(s) are served by the ` +
                 "worker via ASSETS instead of the CDN directly - correct, just one invocation each.");
         }
-        run = `Cloudflare Pages → ${outDir} (deploy: wrangler pages deploy ${basename(outDir)})`;
     }
-    else if (target === "vercel") {
-        cpSync(worker, `${outDir}/index.js`);
-        run = `Vercel edge function → ${outDir}/index.js (wrap with your vercel.json or Build Output API)`;
+    else if (targetPlan.target === "vercel") {
+        cpSync(worker, `${outDir}/${targetPlan.outputFile}`);
     }
     else {
-        // bun / node / deno: the runnable server bundle next to its /assets.
-        cpSync(worker, `${outDir}/server.js`);
-        const cmd = target === "node"
-            ? `node ${basename(outDir)}/server.js`
-            : `${target} ${basename(outDir)}/server.js`;
-        run = `${target} server → ${outDir} (run: ${cmd})`;
+        cpSync(worker, `${outDir}/${targetPlan.outputFile}`);
     }
     rmSync(workDir, { recursive: true, force: true });
     // Size report over the client assets + the server bundle (its parse cost matters on the edge).
     const clientPaths = client.assets.map((u) => assetUrlToPath(u, assetsDir));
-    const serverPath = `${outDir}/${target === "cf-pages" ? "_worker.js" : target === "vercel" ? "index.js" : "server.js"}`;
+    const serverPath = `${outDir}/${targetPlan.outputFile}`;
     const size = aggregateSizeReport(await measureOutputs([...clientPaths, serverPath]));
-    return { target, outDir, client, run, size };
+    return { target, outDir, client, run: targetPlan.run, size };
 }
 /** Map a client asset URL (`/assets/x-hash.js`) back to its on-disk path under `assetsDir`. The
  * `publicPath` prefix is always `/assets/` for these builds, so strip it and rejoin. */