@nifrajs/web 1.13.0 → 2.1.0

package/src/build.ts

@@ -5,7 +5,7 @@
  * are Bun-specific and never on the request path (own subpath, like `@nifrajs/web/fs`); the *output*
  * runs on any runtime.
  */
-import { mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, relative, resolve as resolvePath } from "node:path"
 import type { BunPlugin } from "bun"
 import { sanitizeOutputNames } from "./chunk-names.ts"
@@ -570,6 +570,69 @@ export function parseManifestClientEntry(source: string): string | undefined {
   return MANIFEST_CLIENT_ENTRY.exec(source)?.[1]
 }
 
+// The baked asset lines `generateServerManifest` emits: `export const styles = […]` then
+// `export const routeStyles = {…}`, each a JSON literal followed by the next `export const`. The capture
+// is `[\s\S]*?` (multi-line, non-greedy up to the following `export const`) NOT `.+` - a committed
+// manifest carries no format-ignore pragma, so a formatter can wrap a long `routeStyles` map across lines;
+// a single-line regex would then miss it and silently DROP every baked stylesheet on re-sync.
+const MANIFEST_STYLES = /export const styles = ([\s\S]*?)\nexport const /
+const MANIFEST_ROUTE_STYLES = /export const routeStyles = ([\s\S]*?)\nexport const /
+
+/** 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: string): unknown {
+  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: string): string[] {
+  const raw = MANIFEST_STYLES.exec(source)?.[1]
+  if (raw === undefined) return []
+  try {
+    const value = parseManifestLiteral(raw)
+    return Array.isArray(value) ? (value as string[]) : []
+  } catch {
+    return []
+  }
+}
+
+/** The baked per-route `routeStyles` map in a committed server-manifest (empty if absent/unparseable). Pure. */
+export function parseManifestRouteStyles(source: string): Record<string, string[]> {
+  const raw = MANIFEST_ROUTE_STYLES.exec(source)?.[1]
+  if (raw === undefined) return {}
+  try {
+    const value = parseManifestLiteral(raw)
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, string[]>)
+      : {}
+  } 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
+ * what makes `nifra sync-manifest` a route-table refresh (renamed / added / removed routes) that does NOT
+ * need a full build. It deliberately does NOT rebuild the client bundle: a brand-new HYDRATING route still
+ * needs a full build so its client chunk exists - this only re-syncs the server manifest's route table.
+ * Pure: `source` + the discovered `manifest` in, new source out.
+ */
+export function resyncServerManifestSource(
+  source: string,
+  manifest: Parameters<typeof generateServerManifest>[0],
+  routesPrefix: string,
+): string {
+  return generateServerManifest(manifest, {
+    resolve: (file) => `${routesPrefix}${file}`,
+    clientEntry: parseManifestClientEntry(source) ?? "",
+    styles: parseManifestStyles(source),
+    routeStyles: parseManifestRouteStyles(source),
+    lazy: source.includes("const loaders ="),
+  })
+}
+
 /**
  * Diff the route files a committed server-manifest imports against the files freshly discovered in
  * `routes/`. Returns the `missing` (in routes/, not in manifest — stale manifest) and `extra` (in
@@ -632,7 +695,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   mkdirSync(outDir, { recursive: true })
 
   const routeManifest = discoverRoutes(routesDir)
-  // The bootstrap's filename is `_velo`-namespaced (not `entry.ts`) so its `[name]` can't collide with
+  // The bootstrap's filename is `_nifra`-namespaced (not `entry.ts`) so its `[name]` can't collide with
   // a user route named `entry.tsx` when the CSS mapping below excludes the bootstrap's aggregate CSS.
   const mode = options.minify === false ? "development" : "production"
   // PUBLIC_*-prefixed env → client define (Vite/Next convention). Sourced from the build env (`Bun.env`,
@@ -641,7 +704,11 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // layered after these in the `define` object). `Bun` may be absent under non-Bun typecheck — guard it.
   const buildEnv = (typeof Bun !== "undefined" ? Bun.env : undefined) ?? process.env
   const publicDefines = publicEnvDefines(options.publicEnvPrefix ?? "PUBLIC_", buildEnv)
-  const entryFile = `${outDir}/_nifra-entry.ts`
+  // Keep the generated source beside the project, not inside `outDir`: module resolution starts at the
+  // importing file, so an absolute `--out /tmp/deploy` must still resolve the app's dependencies.
+  // A unique directory also avoids clobbering a user file or colliding with parallel builds.
+  const entryDir = mkdtempSync(resolvePath(dirname(routesDir), ".nifra-client-"))
+  const entryFile = `${entryDir}/_nifra-entry.ts`
   // A client bundle has no Node `process`; provide a minimal one so a stray bare `process` reference in
   // an app module doesn't crash hydration (`process.env.*` reads are handled at compile time by `define`).
   writeFileSync(
@@ -667,49 +734,50 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
   // same-basename collisions (`index.tsx` + `blog/index.tsx`) that a filename match can't. Not yet in
   // `@types/bun`'s `BuildConfig`, so spread it in (spread props skip the excess-property check).
   const buildExtras = { metafile: true }
-  const result = await Bun.build({
-    entrypoints: [entryFile, ...routeFiles.map(resolve)],
-    outdir: outDir,
-    target: "browser",
-    naming: "[name]-[hash].[ext]",
-    publicPath,
-    splitting: true, // one chunk per lazily-imported route; shared deps deduped into shared chunks
-    // `import "./x.css"` in a route/component → bundled, minified, content-hashed `.css` asset (Bun
-    // strips the import from the JS; CSS bundling is on by default since Bun 1.2). Mapped to routes
-    // below — both the aggregate and per-route — via the metafile, for `<link>` injection.
-    ...buildExtras,
-    minify: options.minify ?? true,
-    plugins: [
-      reactDedupePlugin(routesDir),
-      preactDedupePlugin(routesDir),
-      svelteDedupePlugin(routesDir),
-      serverOnlyEmptyPlugin(),
-      ...(options.plugins ?? []),
-    ],
-    ...(options.conditions ? { conditions: [...options.conditions] } : {}),
-    // Replace `process.env.*` at compile time so an app module reading config off `process.env` doesn't
-    // hit a `process is not defined` crash in the browser. Bun does longest-match: NODE_ENV resolves to
-    // the build mode (React's prod/dev branch); each PUBLIC_* var resolves to its baked VALUE; every
-    // other `process.env.X` becomes undefined (the bare `process.env` → `({})` fallback — so secrets
-    // never leak). Callers can override any of these via `options.define` (layered last).
-    define: {
-      "process.env": "({})",
-      "process.env.NODE_ENV": JSON.stringify(mode),
-      ...publicDefines,
-      ...options.define,
-    },
-  })
+  const result = await (async () => {
+    try {
+      return await Bun.build({
+        entrypoints: [entryFile, ...routeFiles.map(resolve)],
+        outdir: outDir,
+        target: "browser",
+        naming: "[name]-[hash].[ext]",
+        publicPath,
+        splitting: true, // one chunk per lazily-imported route; shared deps deduped into shared chunks
+        // `import "./x.css"` in a route/component → bundled, minified, content-hashed `.css` asset (Bun
+        // strips the import from the JS; CSS bundling is on by default since Bun 1.2). Mapped to routes
+        // below — both the aggregate and per-route — via the metafile, for `<link>` injection.
+        ...buildExtras,
+        minify: options.minify ?? true,
+        plugins: [
+          reactDedupePlugin(routesDir),
+          preactDedupePlugin(routesDir),
+          svelteDedupePlugin(routesDir),
+          serverOnlyEmptyPlugin(),
+          ...(options.plugins ?? []),
+        ],
+        ...(options.conditions ? { conditions: [...options.conditions] } : {}),
+        // Replace `process.env.*` at compile time so an app module reading config off `process.env` doesn't
+        // hit a `process is not defined` crash in the browser. Bun does longest-match: NODE_ENV resolves to
+        // the build mode (React's prod/dev branch); each PUBLIC_* var resolves to its baked VALUE; every
+        // other `process.env.X` becomes undefined (the bare `process.env` → `({})` fallback — so secrets
+        // never leak). Callers can override any of these via `options.define` (layered last).
+        define: {
+          "process.env": "({})",
+          "process.env.NODE_ENV": JSON.stringify(mode),
+          ...publicDefines,
+          ...options.define,
+        },
+      })
+    } finally {
+      rmSync(entryDir, { recursive: true, force: true })
+    }
+  })()
   if (!result.success) {
     throw new Error(
       `[nifra/web] client build failed:\n${result.logs.map((l) => String(l)).join("\n")}`,
     )
   }
 
-  // The generated client-entry SOURCE (`_nifra-entry.ts`) was written into outDir only to serve as a
-  // Bun.build entrypoint; the shipped artifact is the content-hashed `_nifra-entry-<hash>.js` the HTML
-  // references. Remove the leftover source so it never ships in a static deploy dir (nothing links it).
-  rmSync(entryFile, { force: true })
-
   // #4: a `node:` builtin (e.g. `node:crypto`) pulled into a CLIENT chunk builds fine (Bun substitutes
   // a browser polyfill) but breaks/leaks at runtime. Fail the build with a named, actionable error
   // instead — caught at build time, not by a confused user in the browser. Graph-based (the metafile's
@@ -1166,7 +1234,7 @@ export function generateServerEntry(options: {
   lines.push('import { clientEntry, manifest, styles, routeStyles } from "./server-manifest"')
   // cf-pages/vercel/deno need the fetch-handler shape; bun/node call app.fetch directly.
   const usesToFetch = target === "cf-pages" || target === "vercel" || target === "deno"
-  if (usesToFetch) lines.push('import { toFetchHandler } from "@nifrajs/core"')
+  if (usesToFetch) lines.push('import { toFetchHandler } from "@nifrajs/core/server"')
   if (target === "node") lines.push('import { serve } from "@nifrajs/node"')
   lines.push(
     "",

package/src/client.ts

@@ -44,16 +44,10 @@ export function installHistory(
       return raw
     }
   }
-  // Resolve a fragment id to its element — by `id`, then a legacy `<a name>` — or null if absent.
+  // Resolve a fragment id to its element by `id`, or null if absent.
   const findAnchor = (id: string): Element | null => {
     if (id === "") return null
-    const byId = document.getElementById(id)
-    if (byId !== null) return byId
-    try {
-      return document.querySelector(`a[name="${CSS.escape(id)}"]`)
-    } catch {
-      return null // CSS/CSS.escape unavailable or an exotic id → no named-anchor match
-    }
+    return document.getElementById(id)
   }
 
   // Wrap a navigation's render in a View Transition when the browser supports it — a graceful

package/src/deferred.ts

@@ -5,6 +5,7 @@
  * protocol — the marker, the resolved/deferred split, and the tiny client registry that streamed
  * resolution scripts settle. The per-adapter `<Await>` lives in `@nifrajs/web-{solid,react}/client`.
  */
+import { plainJsonCodec, type TransportCodec } from "@nifrajs/core/transport-codec"
 
 /**
  * A loader value marked to stream in after the shell. The component consumes it with the adapter's
@@ -28,6 +29,9 @@ export interface Deferred<T> {
  * component knows to `<Await>` it. The `id` is a placeholder until the server assigns the real one.
  */
 export function defer<T>(promise: Promise<T>): Deferred<T> {
+  // Claim the promise immediately: an eager rejection may otherwise be reported as unhandled before
+  // the SSR/NDJSON consumer attaches. Keep the original promise so consumers observe its rejection.
+  void promise.catch(() => {})
   return { __nifra_deferred: true, id: -1, promise }
 }
 
@@ -158,21 +162,22 @@ const NDJSON_ENCODER = new TextEncoder()
 export function ndjsonStream(
   forClient: unknown,
   deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
+  codec: TransportCodec = plainJsonCodec,
 ): ReadableStream<Uint8Array> {
   return new ReadableStream({
     async start(controller) {
-      controller.enqueue(NDJSON_ENCODER.encode(`${JSON.stringify(forClient)}\n`))
+      controller.enqueue(NDJSON_ENCODER.encode(`${codec.encode(forClient)}\n`))
       await Promise.all(
         deferred.map(async (d) => {
           try {
             const value = await d.promise
-            controller.enqueue(NDJSON_ENCODER.encode(`${JSON.stringify({ i: d.id, v: value })}\n`))
+            controller.enqueue(NDJSON_ENCODER.encode(`${codec.encode({ i: d.id, v: value })}\n`))
           } catch (err) {
             // Redact: stream a stable opaque code, never the raw error text; log the real reason
             // server-side. The client's <Await> errorFallback receives this code.
             console.error("[nifra/web] deferred value rejected:", err)
             controller.enqueue(
-              NDJSON_ENCODER.encode(`${JSON.stringify({ i: d.id, e: DEFERRED_ERROR_CODE })}\n`),
+              NDJSON_ENCODER.encode(`${codec.encode({ i: d.id, e: DEFERRED_ERROR_CODE })}\n`),
             )
           }
         }),
@@ -256,7 +261,11 @@ function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
       return marker
     }
     if (Array.isArray(value)) return value.map(walk)
-    if (value !== null && typeof value === "object") {
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+    ) {
       const out: Record<string, unknown> = {}
       for (const [key, v] of Object.entries(value)) out[key] = walk(v)
       return out
@@ -276,6 +285,7 @@ function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
 export async function parseNdjsonData(
   stream: ReadableStream<Uint8Array>,
   signal?: AbortSignal,
+  codec: TransportCodec = plainJsonCodec,
 ): Promise<unknown> {
   const reader = stream.getReader()
   const dec = new TextDecoder()
@@ -305,7 +315,7 @@ export async function parseNdjsonData(
 
   const pending: Pending = new Map()
   const first = await readLine()
-  const data = markersFromPlaceholders(first === null ? null : JSON.parse(first), pending)
+  const data = markersFromPlaceholders(first === null ? null : codec.decode(first), pending)
 
   void (async () => {
     try {
@@ -313,7 +323,7 @@ export async function parseNdjsonData(
         const line = await readLine()
         if (line === null) break
         if (line === "") continue
-        const msg = JSON.parse(line) as { i: number; v?: unknown; e?: string }
+        const msg = codec.decode(line) as { i: number; v?: unknown; e?: string }
         const entry = pending.get(msg.i)
         if (entry === undefined) continue
         pending.delete(msg.i)

package/src/draft.ts

@@ -14,7 +14,7 @@
  *   createWebApp({ ..., draftSecret: env.DRAFT_SECRET })   // → loaders get ctx.draft
  *   withISR(app, { ..., draftSecret: env.DRAFT_SECRET })   // → editors bypass the cache
  */
-import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core"
+import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core/server"
 
 /** The cookie name nifra uses for draft/preview mode. */
 export const DRAFT_COOKIE = "__nifra_draft"

package/src/forms.ts

@@ -18,7 +18,7 @@
  * runtime is a trivial pass-through — all the work is in the types. It checks the field KEY, never the
  * MEANING (a `field("email")` collecting a phone is still valid here); that stays an app/AI concern.
  */
-import type { RouteInfo, Server } from "@nifrajs/core"
+import type { RouteInfo, Server } from "@nifrajs/core/server"
 
 // Derived from `FormData` itself (not the `FormDataEntryValue` global) so this file stays DOM-lib-free:
 // `@nifrajs/web`'s server surface is typechecked by the root config, which has no DOM lib.

package/src/index.ts

@@ -7,12 +7,13 @@
  * the adapter interprets them. That keeps this package both framework-agnostic and free
  * of DOM types: it is pure server orchestration + string building.
  */
-import { server } from "@nifrajs/core"
+
 import {
   type BackendMount,
   type BackendMountHandler,
   NIFRA_BACKEND_MOUNT,
 } from "@nifrajs/core/mount"
+import { server } from "@nifrajs/core/server"
 import {
   DEFERRED_ERROR_CODE,
   DEFERRED_RUNTIME,
@@ -86,7 +87,6 @@ export {
 export {
   type Action,
   buildManifest,
-  enumeratePrerenderedPaths,
   enumerateStaticRoutes,
   filePathToPattern,
   filePathToPatterns,
@@ -201,6 +201,9 @@ export interface RenderProps {
   readonly actionData?: unknown
   /** True while a client navigation or submit is in flight (client-only; absent/false on SSR). */
   readonly pending?: boolean
+  /** The path a client navigation is transitioning TO while `pending` (client-only; absent on SSR and
+   * when idle). Lets an adapter tell a `NavLink` whether its own target is the one loading. */
+  readonly pendingPath?: string
   /** The in-flight client submit, for optimistic UI (client-only; absent on SSR + when idle). */
   readonly submission?: Submission
   /** The matched route's decoded path params (`/users/:id` → `{ id: "7" }`). Threaded identically on
@@ -687,21 +690,17 @@ function isSameOriginPath(location: string): boolean {
 /**
  * Build a redirect `Response` — return it from a route `action` for the Post/Redirect/Get
  * pattern (POST mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit).
- * Defaults to 303 (See Other); pass `307`/`308` (or `{ status }`) to preserve the method.
+ * Defaults to 303 (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
  *
  * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
  * off-origin/absolute destination throws unless you pass `{ external: true }` — this closes the
  * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
  * which returns the action's `Response` verbatim.
  *
- * @param statusOrOptions a status number (back-compat) or `{ status?, external? }`.
+ * @param options redirect status and whether an off-origin destination is intentional.
  */
-export function redirect(
-  location: string,
-  statusOrOptions: number | RedirectOptions = 303,
-): Response {
-  const opts = typeof statusOrOptions === "number" ? { status: statusOrOptions } : statusOrOptions
-  if (opts.external !== true && !isSameOriginPath(location)) {
+export function redirect(location: string, options: RedirectOptions = {}): Response {
+  if (options.external !== true && !isSameOriginPath(location)) {
     throw new Error(
       `[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//"), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`,
     )
@@ -715,7 +714,7 @@ export function redirect(
       `[nifra/web] redirect location contains a CR/LF character — refusing to emit a header-injecting redirect.`,
     )
   }
-  return new Response(null, { status: opts.status ?? 303, headers: { location } })
+  return new Response(null, { status: options.status ?? 303, headers: { location } })
 }
 
 /** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
@@ -967,15 +966,14 @@ export interface CreateWebAppOptions {
    * mount interface from `@nifrajs/core/mount`; `createWebApp` also serves that backend over HTTP at
    * {@link apiPrefix} (default `/api`): a request whose pathname starts with the prefix is dispatched
    * before page routing with the same `env`/`waitUntil` platform context, and the backend's `Response`
-   * is returned untouched. Legacy custom `.fetch(url, init)` bridges remain mountable but cannot
-   * receive platform context. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
+   * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
   readonly api?: unknown
   /** HTTP path prefix the {@link api} backend is auto-mounted at (default `"/api"`). A request whose
    * pathname is exactly the prefix or starts with `prefix + "/"` is dispatched to the backend before
    * page routing; the backend therefore defines its routes at the **full** path (`server().post("/api/
    * sync", …)`), matching the in-process `inProcessClient` call sites. Set to `""` to disable the
    * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
-   * is also a no-op when `api` has neither the symbol mount nor a legacy callable `.fetch`. */
+   * is also a no-op when `api` does not expose the symbol mount. */
   readonly apiPrefix?: string
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
@@ -994,7 +992,7 @@ export interface CreateWebAppOptions {
    * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
    * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
-  /** SSG: the prerendered-path set (e.g. from `enumeratePrerenderedPaths` or the build's
+  /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
    * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
    * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
   readonly prerenderedPaths?: readonly string[]
@@ -1027,24 +1025,15 @@ interface RouteContext {
   readonly env: unknown
 }
 
-/** Legacy pre-symbol mount bridge. Kept for custom integrations; it cannot receive platform context. */
-interface LegacyMountableApi {
-  readonly fetch: (url: string, init?: RequestInit) => Response | Promise<Response>
-}
-
 /**
- * Resolve the explicit backend mount interface, then fall back to the released `.fetch(url, init)`
- * convention. The symbol seam forwards platform context without making web depend on client.
+ * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
+ * context without making web depend on client.
  */
 function backendMountOf(api: unknown): BackendMountHandler | undefined {
   if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
   const explicit = (api as Partial<BackendMount>)[NIFRA_BACKEND_MOUNT]
-  if (typeof explicit === "function") {
-    return (request, platform) => explicit.call(api, request, platform)
-  }
-  const legacy = (api as Partial<LegacyMountableApi>).fetch
-  if (typeof legacy !== "function") return undefined
-  return (request) => legacy.call(api, request.url, request)
+  if (typeof explicit !== "function") return undefined
+  return (request, platform) => explicit.call(api, request, platform)
 }
 
 /**
@@ -1095,13 +1084,8 @@ export function createWebApp<Env = unknown>(
   // surfaces as the backend's own response, never the page 404. We dispatch the SAME `Request` object
   // (its body unread) so streamed/large bodies pass through untouched; the backend defines its routes
   // at the full prefixed path (`server().post("/api/sync", …)`), matching the `inProcessClient` call
-  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no `.fetch`) is left pages-only. The hook
+  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no symbol mount) is left pages-only. The hook
   // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
-  //
-  // Backward-compat: an app that still hand-dispatches `/api/*` in its server entry (the old
-  // `if (pathname.startsWith("/api/")) return backend.fetch(req)`) intercepts BEFORE `app.fetch` is
-  // ever called, so that branch returns first and this hook never sees the request — no double
-  // handling. Apps that drop the hand-dispatch now rely on this mount instead (dev + prod alike).
   const apiPrefix = options.apiPrefix ?? "/api"
   const mountedApi = backendMountOf(api)
   if (apiPrefix !== "" && mountedApi !== undefined) {

package/src/manifest.ts

@@ -108,7 +108,7 @@ export interface MetaArgs<Data = unknown> {
    * `og:url`/`canonical`/`og:image` built from it never drifts between the server-rendered `<head>` and
    * a soft-nav. Use it for absolute URLs (`origin + "/posts/" + slug`) instead of threading `siteUrl`
    * through loader data. Empty string (`""`) when the origin is unknown (e.g. a hand-built test render
-   * with no request URL) — back-compat-safe: a `meta()` that ignores `origin` is unchanged.
+   * with no request URL). A `meta()` that ignores `origin` is unchanged.
    */
   readonly origin: string
 }
@@ -381,7 +381,7 @@ const encodeRouteParam = (value: string): string => {
  * Substitute a route pattern's `:param` segments with concrete values: `/users/:id` + `{id:"7"}` →
  * `/users/7`. Returns the filled path plus any params that had no value (a `getStaticPaths` bug) so
  * the caller can skip rather than emit a path with a literal `:name`. Shared by the SSG driver and
- * {@link enumeratePrerenderedPaths}.
+ * {@link enumerateStaticRoutes}.
  */
 export function fillRoutePattern(
   pattern: string,
@@ -438,9 +438,3 @@ export async function enumerateStaticRoutes(routes: readonly RouteEntry[]): Prom
   }
   return { paths, fallbacks }
 }
-
-/** The prerendered-path subset of {@link enumerateStaticRoutes} — kept for callers that only need the
- * paths (e.g. injecting `window.__NIFRA_PRERENDERED__`). */
-export async function enumeratePrerenderedPaths(routes: readonly RouteEntry[]): Promise<string[]> {
-  return (await enumerateStaticRoutes(routes)).paths
-}

package/src/plugins/postcss.ts

@@ -0,0 +1,129 @@
+/**
+ * `@nifrajs/web/plugins/postcss` - a PostCSS (`*.css`, `*.pcss`, `*.postcss`) Bun plugin, in its OWN
+ * module so the SSR preload registers it BEFORE any CSS file loads. Mirrors `@nifrajs/web/plugins/scss`:
+ * pass `"dom"` for the client bundle (`buildClient({ plugins: [...] })`) and preload `"ssr"` for the
+ * server (`bun --preload`).
+ *
+ * PostCSS (`postcss`) is an **optional peer**, not a hard dependency: it's loaded on the first CSS file
+ * and fails loud with an install hint if absent. The plugin list comes from an explicit `plugins`
+ * option, or - when omitted - from the project's `postcss.config.js`, loaded via the optional
+ * `postcss-load-config` peer. This is the Tailwind v4 path: a config with `@tailwindcss/postcss` runs
+ * inside PostCSS, so `app.css` importing `tailwindcss` is compiled during `Bun.build` with no
+ * framework-specific code (v4 bundles its own Lightning CSS, so no separate autoprefixer step).
+ *
+ * Composes with CSS Modules: a `*.module.css` / `*.module.pcss` file is processed and then run through
+ * the same scoped-class transform as `@nifrajs/web/plugins/css-modules`, so `import styles` yields the
+ * `{ original: scoped }` map (SSR/dom class-map parity). A plain CSS file is a side-effect import - its
+ * CSS is bundled (dom) and it resolves to an empty module (ssr).
+ */
+import type { BunPlugin } from "bun"
+import { transformCssModule } from "./css-modules.ts"
+import { createStylesheetEmitter, reproduciblePath, requirePeer } from "./kit.ts"
+
+const STYLE_NS = "nifra-postcss"
+
+/** The subset of the `postcss` API this plugin uses (structural, so no hard dependency on its types). */
+export type PostcssProcessor = (plugins?: readonly unknown[]) => {
+  process(
+    css: string,
+    options: { readonly from?: string; readonly to?: string },
+  ): PromiseLike<{ readonly css: string }>
+}
+
+/** The subset of `postcss-load-config` this plugin uses when no explicit `plugins` are given. */
+export type PostcssConfigLoader = (
+  ctx?: Record<string, unknown>,
+  path?: string,
+) => Promise<{ readonly plugins?: readonly unknown[]; readonly options?: Record<string, unknown> }>
+
+export interface PostcssPluginOptions {
+  /** Inject the `postcss` function (default: the optional peer, loaded lazily). Pass a stub in tests. */
+  readonly postcss?: PostcssProcessor
+  /** PostCSS plugins to run. When omitted, the project's `postcss.config.js` is loaded instead. */
+  readonly plugins?: readonly unknown[]
+  /** Directory (or file) to load `postcss.config.js` from, when `plugins` is omitted. Default: cwd. */
+  readonly config?: string
+  /** Inject the config loader (default: the `postcss-load-config` optional peer). */
+  readonly loadConfig?: PostcssConfigLoader
+}
+
+const CSS_FILTER = /\.(css|pcss|postcss)(\?|$)/
+const isModuleRequest = (cleanPath: string): boolean =>
+  /\.module\.(css|pcss|postcss)$/.test(cleanPath)
+
+/**
+ * The PostCSS Bun plugin. `"dom"` → bundles the processed CSS (and, for `*.module.*`, exports the
+ * scoped class map); `"ssr"` → the class map only for `*.module.*`, an empty module for plain CSS.
+ * Tolerates a trailing `?query` (dev servers append one to bust Bun's import cache).
+ */
+export function postcssBunPlugin(
+  generate: "dom" | "ssr",
+  options: PostcssPluginOptions = {},
+): BunPlugin {
+  return {
+    name: `nifra-postcss-${generate}`,
+    setup(build) {
+      const stylesheet = createStylesheetEmitter(build, STYLE_NS)
+      let processor = options.postcss
+      let pluginList: readonly unknown[] | undefined = options.plugins
+
+      const getProcessor = async (): Promise<PostcssProcessor> => {
+        processor ??= (
+          await requirePeer<{ default: PostcssProcessor }>("postcss", {
+            feature: "PostCSS/Tailwind support",
+            install: "bun add -d postcss",
+          })
+        ).default
+        return processor
+      }
+
+      const getPlugins = async (): Promise<readonly unknown[]> => {
+        if (pluginList !== undefined) return pluginList
+        const load =
+          options.loadConfig ??
+          (
+            await requirePeer<{ default: PostcssConfigLoader }>("postcss-load-config", {
+              feature: "loading postcss.config.js (or pass `plugins` explicitly)",
+              install: "bun add -d postcss-load-config",
+            })
+          ).default
+        const loaded = await load({}, options.config)
+        pluginList = loaded.plugins ?? []
+        return pluginList
+      }
+
+      build.onLoad({ filter: CSS_FILTER }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        const source = await Bun.file(path).text()
+        const postcss = await getProcessor()
+        const plugins = await getPlugins()
+        let css: string
+        try {
+          css = (await postcss(plugins).process(source, { from: path })).css
+        } catch (err) {
+          throw new Error(
+            `[nifra/web] failed to process ${path}: ${(err as Error)?.message ?? err}`,
+            { cause: err },
+          )
+        }
+
+        if (isModuleRequest(path)) {
+          // *.module.css → process, then scope class names through the shared CSS-modules transform.
+          // Scope off the cwd-relative path so names are reproducible across machines/CI.
+          const { exports, css: scopedCss } = transformCssModule(css, reproduciblePath(path))
+          const js = `export default ${JSON.stringify(exports)}\n`
+          return {
+            contents: generate === "dom" ? js + stylesheet.emit(path, scopedCss) : js,
+            loader: "js",
+          }
+        }
+
+        // Plain CSS → side-effect import: bundle the CSS on dom, an empty module on ssr.
+        return {
+          contents: generate === "dom" ? stylesheet.emit(path, css) : "",
+          loader: "js",
+        }
+      })
+    },
+  }
+}