@nifrajs/web 2.10.0 → 2.11.0

package/src/dev.ts

@@ -2,9 +2,9 @@
  * `@nifrajs/web/dev` - the **Bun pipeline's** dev server: one toolchain, no Vite in the process.
  *
  * nifra ships two dev pipelines and the rule between them is that a pipeline owns a whole phase. The
- * Vite server (`@nifrajs/web/vite`) is the default - mature framework plugins, and it resolves SSR as
- * well as the client so both halves agree on every specifier. This is the other one: `Bun.serve` bundles
- * and hot-reloads the client while Bun's runtime resolves SSR. Only one toolchain is present, so the two
+ * Vite server (`@nifrajs/web/vite`) is the Vite-only escape hatch - mature framework plugins, and it
+ * resolves SSR as well as the client so both halves agree on every specifier. This is the other one:
+ * `Bun.serve` bundles and hot-reloads the client while Bun's runtime resolves SSR. Only one toolchain is present, so the two
  * cannot disagree.
  *
  * What you get: React Fast Refresh WITH state preserved - Bun's dev server applies it natively, no plugin
@@ -14,9 +14,9 @@
  * not, and saving it does a clean full reload. Plus no Vite dependency and ONE bundler across dev and
  * production, which is the real prize - the dev/prod seam disappears.
  *
- * What you give up: `*.module.css`. Bun's DEV-server bundler has no CSS-Modules transform (its production
- * `Bun.build` does), so the import compiles to a dangling reference. Plain CSS and Tailwind are fine. The
- * CLI refuses `nifra dev --bun` for a CSS-Modules app rather than serving a broken client.
+ * CSS Modules, server functions, and `*.server` modules use the same production transforms through the
+ * generated Bun config. The CLI owns that config because Bun's HTML dev server accepts plugins only from
+ * `[serve.static] plugins`; direct callers should pass the equivalent plugin through their Bun config.
  *
  * ## How the two halves meet
  *
@@ -38,7 +38,10 @@
  * production, which reads CSS from the build manifest, is perfectly fine.
  *
  * SSR invalidation is Bun's import cache rather than Vite's module graph, so route modules are re-imported
- * under a changing query on each change - which is what `discoverRoutes({ importQuery })` exists for.
+ * under a changing query on each change - which is what `discoverRoutes({ importQuery })` exists for. That
+ * query stops at the route file, so everything BELOW it - components, helpers, `*.server` modules - is
+ * tracked and re-keyed per module by `./dev-ssr-graph.ts`, or SSR would render the code that was on disk
+ * when the server started.
  *
  * Bun-only + build-time; never imported by the edge runtime.
  */
@@ -56,8 +59,10 @@ import { type BuildClientOptions, buildClient } from "./build.ts"
 import { type DevEntryMatch, resolveDevEntry } from "./bun-dev-entry.ts"
 import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { explainBindFailure } from "./dev-port.ts"
+import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEV_HMR_ENV, DEV_ROOT_ENV, DEV_ROUTES_ENV } from "./plugins/kit.ts"
 import { servePublicDir } from "./public-dir.ts"
 
 export { LAST_ERROR_PATH } from "./diagnostic.ts"
@@ -244,13 +249,54 @@ export function injectStyles(html: string, styles: readonly string[]): string {
 export async function createDevServer(options: DevServerOptions): Promise<DevServer> {
   const { createApp, port = DEFAULT_DEV_PORT, routesDir, clientModule } = options
   const serve = bunServe()
+  // Tell the framework compiler plugins they are compiling for a DEV SERVER, so they may emit HMR
+  // wiring. It cannot be a plugin constructor argument: an app builds its `clientPlugins` once in
+  // `nifra.config.ts` and the same objects serve dev and `nifra build`. Guarding the emitted code with
+  // `if (import.meta.hot)` is not sufficient either - `Bun.build` keeps the branch, so the HMR calls
+  // ship to production. This flag is the phase signal; `nifra build` never sets it.
+  process.env[DEV_HMR_ENV] = "1"
+  // Dev-shaped runtimes for SSR, matching what the client bundle gets: a library ships its dev build
+  // behind the `development` export condition with a `NODE_ENV` fallback for resolvers that set no
+  // conditions, and Bun's runtime (where SSR runs) is one of those. `nifra dev` sets this on the server
+  // process before it reads the app config, which is earlier than this and is the point that matters -
+  // a framework runtime imported through the config has already read the flag by the time this line
+  // runs. This is the floor for a dev server started programmatically. `??=`, so a pinned value stands.
+  process.env.NODE_ENV ??= "development"
+  // `conditions` governs the production client bundle but CANNOT govern the one served here: Bun's
+  // dev-server bundler takes no resolve conditions, from `bunfig.toml` or anywhere else, so a package
+  // with an `exports` map can resolve to a different file in dev than in `nifra build`. SSR is fine -
+  // `nifra dev` passes these to the runtime as `--conditions` when it re-execs - which is exactly why
+  // this is worth a line: the halves of the dev process no longer agree, and the drift is invisible
+  // until production picks the other file. Said once at startup rather than swallowed.
+  if (options.conditions !== undefined && options.conditions.length > 0) {
+    console.warn(
+      `\n[nifra/web/dev] \`conditions: [${options.conditions.map((c) => `"${c}"`).join(", ")}]\` ` +
+        "does not reach the client bundle on the Bun dev pipeline.\n" +
+        "  Bun's dev-server bundler accepts no resolve conditions, so a package with an `exports` map\n" +
+        "  may resolve differently here than in `nifra build`. SSR does honour them.\n" +
+        "  Run `nifra dev --vite` if this app needs exact dev/prod client resolution.\n",
+    )
+  }
   // The app root. `routesDir` is `<app>/routes` by convention, so its parent is the project - the one
   // place a generated entry can sit and still resolve the app's imports.
   const root = resolve(routesDir, "..")
+  // Which files are the app's own components, for the plugins that hot-patch at component granularity
+  // (`devHotComponent`). Announced here rather than passed, for the same reason the flag above is.
+  process.env[DEV_ROOT_ENV] = root
+  process.env[DEV_ROUTES_ENV] = resolve(routesDir)
   // The most recent SSR failure as a structured Diagnostic, scoped to THIS server. Served at
   // LAST_ERROR_PATH so an agent driving the dev server reads the exact failure (code, codeframe, fix) as
   // JSON instead of scraping the overlay. Shared with the Vite adapter so the endpoint can't drift.
   const devDiagnostics = createDevDiagnostics(root)
+  // SSR freshness BELOW the route module. The route-level `importQuery` only ever reloaded the route
+  // itself; everything it imports is tracked here and re-keyed when it changes. Registered now because a
+  // Bun runtime plugin only affects modules loaded after it, and the first route import is `appFor`
+  // below - the CLI's own plugins (CSS Modules, the app's `serverPlugins`) register earlier still, and
+  // being earlier is what gives them first refusal on the specifiers and file types they own. That
+  // ordering is deliberate: a framework plugin compiling `.vue`/`.svelte`/`.tsx` keeps its loader, and
+  // re-keys the imports of what it compiled by handing its output through `rewriteSsrImports`.
+  const ssrGraph = createSsrGraph({ root })
+  ;(await import("bun")).plugin(ssrGraph.plugin)
   const devDir = resolve(root, DEV_DIR)
   const entryPath = resolve(devDir, "entry.tsx")
   const htmlPath = resolve(devDir, "entry.html")
@@ -271,9 +317,9 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   let server: BunServerHandle
   // The last resolved entry, with the time it was resolved. Deliberately short-lived - see `currentEntry`.
   let cache: { readonly entry: DevEntryMatch; readonly at: number } | undefined
-  // The app, tagged with the entry hash it was built against - see `appFor`.
-  let built: { readonly entry: string; readonly app: FetchApp } | undefined
-  let building: { readonly entry: string; readonly promise: Promise<FetchApp> } | undefined
+  // The app, tagged with the build it was made for - see `appFor`.
+  let built: { readonly key: string; readonly app: FetchApp } | undefined
+  let building: { readonly key: string; readonly promise: Promise<FetchApp> } | undefined
   let version = 0
 
   /**
@@ -321,27 +367,38 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
    *
    * The watcher still runs: it regenerates the entry when routes are added or removed, and re-checks for
    * client leaks. It is no longer what keeps SSR correct.
+   *
+   * The entry hash is not the whole marker, though, because it only covers the CLIENT graph. A module
+   * the browser never receives - a `*.server` file, a loader's helper - can change without moving it, so
+   * the key also carries {@link SsrGraph} generation, which counts changes on the SERVER side. Either
+   * one moving rebuilds the app, which is what re-imports the route modules under a fresh query.
    */
-  const appFor = (entrySrc: string): Promise<FetchApp> => {
-    if (built?.entry === entrySrc) return Promise.resolve(built.app)
-    if (building?.entry === entrySrc) return building.promise
+  const appFor = (key: string): Promise<FetchApp> => {
+    if (built?.key === key) return Promise.resolve(built.app)
+    if (building?.key === key) return building.promise
     version += 1
     const promise = Promise.resolve(createApp(CLIENT_ENTRY_PATH, `v=${version}`))
-    building = { entry: entrySrc, promise }
+    building = { key, promise }
     void promise
       .then((next) => {
-        if (building?.entry === entrySrc) {
-          built = { entry: entrySrc, app: next }
+        if (building?.key === key) {
+          built = { key, app: next }
           building = undefined
         }
       })
       .catch(() => {
         // Clear the in-flight marker so the next request retries instead of re-awaiting a failed build.
-        if (building?.entry === entrySrc) building = undefined
+        if (building?.key === key) building = undefined
       })
     return promise
   }
 
+  /** Check the server-side graph for changes, then hand back the app for what is on disk right now. */
+  const appForRequest = (entrySrc: string): Promise<FetchApp> => {
+    ssrGraph.sweep()
+    return appFor(`${entrySrc}#${ssrGraph.generation()}`)
+  }
+
   try {
     server = serve({
       port,
@@ -377,7 +434,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
           // One fresh probe per request: it is both the freshness check for SSR and the stylesheet list,
           // so the page cannot be rendered against a build the browser is not about to load.
           const entry = await currentEntry(true)
-          const res = await (await appFor(entry.src)).fetch(req)
+          const res = await (await appForRequest(entry.src)).fetch(req)
           if (!(res.headers.get("content-type") ?? "").includes("text/html")) return res
           if (entry.styles.length === 0) return res
           const headers = new Headers(res.headers)
@@ -408,7 +465,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   try {
     // Build once up front so a dev server that cannot find the entry, or whose app fails to construct,
     // fails at startup with a real diagnosis instead of on the first page request.
-    await appFor((await currentEntry()).src)
+    await appForRequest((await currentEntry()).src)
   } catch (err) {
     // Leaving the server up would answer 500s forever, which presents as a running server rather than as
     // the startup failure it is.
@@ -484,6 +541,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       if (timer) clearTimeout(timer)
       clearInterval(topologyTimer)
       for (const file of watched) unwatchFile(file)
+      ssrGraph.dispose()
       server.stop(true)
       rmSync(devDir, { recursive: true, force: true })
     },

package/src/index.ts

@@ -25,6 +25,10 @@ import {
 } from "./deferred.ts"
 import { isDraftEnabled } from "./draft.ts"
 import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+// Head resolution/merging. Defined in an internal module so `@nifrajs/web/client` can export the same
+// two functions to the generated client entry without dragging THIS module (and its server code) into
+// the browser graph - see internal/head-merge.ts. Re-exported here so the public API is unchanged.
+import { mergeHeads, resolveMeta } from "./internal/head-merge.ts"
 import { jsStringLiteral } from "./internal/js-string.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "./isr.ts"
@@ -195,7 +199,7 @@ export {
   type SubmitOptions,
 } from "./router.ts"
 // Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
-export { type Deferred, defer }
+export { type Deferred, defer, mergeHeads, resolveMeta }
 
 /** Phantom brand key for {@link ServerOnly}. A unique symbol so the brand can't be forged by a plain
  * object literal; `unique symbol` keys never appear in the emitted JS, so the brand is purely
@@ -311,6 +315,43 @@ export interface RenderAdapter {
   hydrationHead(nonce?: string): string
 }
 
+/**
+ * Loads a module through the DEV SERVER'S module graph rather than the runtime's. Takes an absolute
+ * file path or a bare specifier; resolution, compilation and caching are the dev server's.
+ */
+export type SsrModuleLoader = (id: string) => Promise<unknown>
+
+/* A `globalThis` singleton for the same reason `@nifrajs/web-react`'s router context is one: in dev
+ * this module is evaluated twice in one process (the CLI's copy under Bun, and the app's copy), and a
+ * module-level `let` would leave the adapter reading a slot the dev server set on the other copy. */
+const SSR_MODULE_LOADER_SLOT = Symbol.for("nifra.web.ssr-module-loader")
+/* Explicitly `| undefined`: clearing the slot is part of the contract (a dev server clears it on
+ * stop), and under `exactOptionalPropertyTypes` "absent" and "set to undefined" are separate types. */
+const loaderSlot = globalThis as { [SSR_MODULE_LOADER_SLOT]?: SsrModuleLoader | undefined }
+
+/**
+ * Publishes the dev server's SSR module loader. Called by a dev server that owns SSR resolution
+ * itself; pass `undefined` to clear it on shutdown.
+ */
+export function setSsrModuleLoader(load: SsrModuleLoader | undefined): void {
+  loaderSlot[SSR_MODULE_LOADER_SLOT] = load
+}
+
+/**
+ * The dev server's SSR module loader, or `undefined` when nothing owns SSR resolution but the runtime
+ * - the Bun dev pipeline, and every production build, where the adapter's assets are compiled ahead
+ * of time and a plain `import` is already the right thing.
+ *
+ * An adapter that must load a COMPILED asset at runtime (a `.svelte` component, say) has to prefer
+ * this over a bare `import`, and has to take the framework's SERVER RENDERER from it as well, not
+ * just the component. A component compiled by the dev server renders through the renderer the dev
+ * server resolved; mixing the two puts two copies of the framework runtime in one component tree,
+ * where context written by one half is invisible to the other.
+ */
+export function ssrModuleLoader(): SsrModuleLoader | undefined {
+  return loaderSlot[SSR_MODULE_LOADER_SLOT]
+}
+
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export const DATA_GLOBAL = "__NIFRA_DATA__"
 /** Per-layout loader data for hydration. Emitted ONLY when some layout in the chain has a loader, so
@@ -1287,12 +1328,6 @@ function headTags(head: Meta | undefined): string {
   return out
 }
 
-/** Resolve a route's `meta` (static or a function of the loader data + params) to a {@link Meta}. */
-export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
-  if (meta === undefined) return {}
-  return typeof meta === "function" ? meta(args) : meta
-}
-
 /**
  * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
  * engines which URL is authoritative for a page (deduping query-string / tracking variants).
@@ -1379,68 +1414,6 @@ export function unsafeInlineScript(
   }
 }
 
-/**
- * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.
- *
- * The head contract (see {@link CreateWebAppOptions} and `LayoutEntry`): a `_layout.tsx` may export
- * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below
- * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the
- * render chain), and merges:
- *  - **`title`** - *nearest-wins*: the last defined value across the list, so the page overrides an
- *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined
- *    page `title` keeps it.
- *  - **`meta` / `link`** - *concatenated* in list order (outermost first, page last). Duplicate-tag
- *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout
- *    can ship N `<link rel="alternate" hreflang>` tags and a page can add its own canonical.
- *
- * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
- * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
- * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its
- * content can vary with loader data anyway).
- */
-export function mergeHeads(heads: readonly Meta[]): Meta {
-  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
-  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
-  if (heads.length === 1) return heads[0] as Meta
-  let title: string | undefined
-  let lang: string | undefined
-  let dir: Meta["dir"]
-  const meta: MetaDescriptor[] = []
-  const link: LinkDescriptor[] = []
-  const script: ScriptDescriptor[] = []
-  const unsafeScript: UnsafeScriptDescriptor[] = []
-  for (const h of heads) {
-    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
-    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
-    if (h.dir !== undefined) dir = h.dir
-    if (h.meta !== undefined) meta.push(...h.meta)
-    if (h.link !== undefined) link.push(...h.link)
-    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
-    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
-  }
-  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
-  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
-  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
-  // `undefined`).
-  const merged: {
-    title?: string
-    meta?: Meta["meta"]
-    link?: Meta["link"]
-    script?: Meta["script"]
-    unsafeScript?: Meta["unsafeScript"]
-    lang?: string
-    dir?: Meta["dir"]
-  } = {}
-  if (title !== undefined) merged.title = title
-  if (meta.length > 0) merged.meta = meta
-  if (link.length > 0) merged.link = link
-  if (script.length > 0) merged.script = script
-  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
-  if (lang !== undefined) merged.lang = lang
-  if (dir !== undefined) merged.dir = dir
-  return merged as Meta
-}
-
 export interface CreateWebAppOptions {
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
@@ -2447,7 +2420,9 @@ export function generateClientEntry(
   }
 
   return `${[
-    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web"',
+    // `/client`, never the root: the root's graph carries the server (renderPage, the static-file
+    // server), and Vite's dev server evaluates what it is given instead of tree-shaking it.
+    'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web/client"',
     'import { applyHead, installForms, installHistory, signalHydrated } from "@nifrajs/web/client"',
     // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
     // access yields `undefined` if absent - unlike a named import, which would be a link error.
@@ -2464,6 +2439,16 @@ export function generateClientEntry(
         '`/client` entry (e.g. "@nifrajs/web-react/client"), or re-export mountRouter from it.',
     )})`,
     "const errorBoundary = __adapter.errorBoundary",
+    // A hot update that the framework cannot actually apply must end in a reload, not in nothing.
+    //
+    // Bun's dev server applies React Fast Refresh to JSX modules. For React that patches the component
+    // and preserves state. For Preact it does not - the module still LOOKS Fast-Refresh-able, so the
+    // update is accepted and then swallowed: `bun:beforeUpdate`/`bun:afterUpdate` both fire, the server
+    // logs a rebuild, and the page silently keeps rendering the old code. An edit that appears to do
+    // nothing is the worst failure mode in a dev loop - worse than a reload, because there is no signal
+    // to act on. An adapter that knows its framework is in that position says so, and the entry turns
+    // the swallowed update into an honest full reload.
+    'if (import.meta.hot && __adapter.hotUpdateNeedsReload) import.meta.hot.on("bun:afterUpdate", () => location.reload())',
     `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
     // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
     // route, shared layouts/deps deduped into shared chunks, so a route's code loads only when

package/src/internal/head-merge.ts

@@ -0,0 +1,80 @@
+/**
+ * Head resolution + merging, in its own module so the CLIENT can have it without the server.
+ *
+ * These two are pure functions over `Meta`, but they used to live in `index.ts` - the module that also
+ * carries `renderPage`, `createWebApp` and the static-file server. The generated client entry imported
+ * them from `@nifrajs/web`, which under a bundler was harmless (server code tree-shakes away) and under
+ * Vite's dev server was fatal: it serves each module as-is, so pulling `index.ts` into the browser graph
+ * executed `public-dir.ts` and the page died on `Module "node:fs/promises" has been externalized`
+ * before hydrating. Splitting them out means the client entry never names the server module at all,
+ * rather than relying on a bundler to remove it afterwards.
+ *
+ * `index.ts` and `client.ts` both re-export from here, so the public API is unchanged in both places.
+ */
+import type {
+  LinkDescriptor,
+  Meta,
+  MetaArgs,
+  MetaDescriptor,
+  MetaInput,
+  ScriptDescriptor,
+  UnsafeScriptDescriptor,
+} from "../manifest.ts"
+
+/** Resolve a route's `meta` export - a static object, or a function of the route's data/params. */
+export function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta {
+  if (meta === undefined) return {}
+  return typeof meta === "function" ? meta(args) : meta
+}
+
+/**
+ * Merge a layout chain's heads, outermost first: `title`/`lang`/`dir` are nearest-wins, and
+ * `meta`/`link`/`script` concatenate in chain order.
+ *
+ * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
+ * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
+ * fine: `headTags`'s memo is keyed on identity, so a per-request merge simply recomputes (its
+ * content can vary with loader data anyway).
+ */
+export function mergeHeads(heads: readonly Meta[]): Meta {
+  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
+  // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
+  if (heads.length === 1) return heads[0] as Meta
+  let title: string | undefined
+  let lang: string | undefined
+  let dir: Meta["dir"]
+  const meta: MetaDescriptor[] = []
+  const link: LinkDescriptor[] = []
+  const script: ScriptDescriptor[] = []
+  const unsafeScript: UnsafeScriptDescriptor[] = []
+  for (const h of heads) {
+    if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
+    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
+    if (h.dir !== undefined) dir = h.dir
+    if (h.meta !== undefined) meta.push(...h.meta)
+    if (h.link !== undefined) link.push(...h.link)
+    if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
+    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
+  }
+  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
+  // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
+  // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
+  // `undefined`).
+  const merged: {
+    title?: string
+    meta?: Meta["meta"]
+    link?: Meta["link"]
+    script?: Meta["script"]
+    unsafeScript?: Meta["unsafeScript"]
+    lang?: string
+    dir?: Meta["dir"]
+  } = {}
+  if (title !== undefined) merged.title = title
+  if (meta.length > 0) merged.meta = meta
+  if (link.length > 0) merged.link = link
+  if (script.length > 0) merged.script = script
+  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
+  if (lang !== undefined) merged.lang = lang
+  if (dir !== undefined) merged.dir = dir
+  return merged as Meta
+}

package/src/internal/server-boundary.ts

@@ -3,8 +3,7 @@
  *
  * The client build must never ship server-only code, or server-only config, to a browser. Three
  * conventions enforce that, and each has to mean the SAME thing in every pipeline that builds the client
- * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`'s refusal
- * (which cannot transform, so it refuses to start instead):
+ * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`:
  *
  *   - `*.server` modules - emptied, so a secret / `node:` / native import subtree never reaches the client.
  *   - `*.fn` modules     - replaced with HTTP stubs, so the function bodies (and their imports) stay server-side.

package/src/plugins/kit.ts

@@ -11,6 +11,16 @@ import type { BunPlugin } from "bun"
 /** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
 export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
 
+/**
+ * Re-keys the app-owned imports of a module the SERVER half of a plugin just compiled, so an edit below
+ * a route reaches SSR instead of being served from Bun's import cache. A plugin that claims a file
+ * extension is the only code that ever sees that file's source, so it is the only place its imports can
+ * be versioned - every `generate: "ssr"` loader should return its output through this.
+ *
+ * A no-op on the client half and outside a dev server. See `../dev-ssr-graph.ts` for the whole design.
+ */
+export { rewriteSsrImports } from "../dev-ssr-graph.ts"
+
 const packageRootCache = new Map<string, string>()
 
 /** The nearest ancestor directory of `startDir` that holds a `package.json` (the file's package root),
@@ -57,6 +67,67 @@ export function hash8(input: string): string {
   return h.toString(16).padStart(8, "0")
 }
 
+/**
+ * Env flag a nifra dev server sets for its own lifetime, so a framework compiler plugin can tell a dev
+ * compile from a `nifra build` one. Exported for the dev server that sets it; plugins ask
+ * {@link devServerCompile} instead of reading it.
+ */
+export const DEV_HMR_ENV = "NIFRA_DEV_HMR"
+
+/**
+ * True while a nifra dev server is running, i.e. the compile may emit HMR wiring (and, where the
+ * framework couples the two, dev-mode runtime output).
+ *
+ * The phase cannot be a plugin constructor argument: an app builds its `clientPlugins` once in
+ * `nifra.config.ts` and the same plugin objects serve both `nifra dev` and `nifra build`. Guarding the
+ * emitted code with `if (import.meta.hot)` is not sufficient either - `Bun.build` keeps the branch, so
+ * the HMR calls were measured shipping in production client chunks. The dev server announces itself in
+ * the environment instead, and `nifra build` never sets it. Read per compile (not captured at
+ * registration) so the flag is honoured however late the server sets it.
+ */
+export function devServerCompile(): boolean {
+  return process.env[DEV_HMR_ENV] === "1"
+}
+
+/**
+ * The app root and the routes directory of the running dev server, for plugins that need to tell one of
+ * the app's own components from a dependency or a route module. Set alongside {@link DEV_HMR_ENV}; read
+ * through {@link devHotComponent}.
+ */
+export const DEV_ROOT_ENV = "NIFRA_DEV_ROOT"
+export const DEV_ROUTES_ENV = "NIFRA_DEV_ROUTES"
+
+const under = (path: string, dir: string | undefined): boolean =>
+  dir !== undefined &&
+  dir !== "" &&
+  (path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`))
+
+/**
+ * Whether a dev compile of `path` may wrap the module in component-level hot-patching - i.e. whether it
+ * is one of the app's OWN components rather than a dependency or a route module.
+ *
+ * The exclusions are not caution, they are two things such a wrapper cannot survive:
+ *
+ *   - a **dependency**, whose components are the framework's own composition machinery. An adapter folds
+ *     a layout chain through them, so they are entered from a snippet or as a dynamic component - and a
+ *     wrapper there sits between the SSR markup and the component that is supposed to claim it.
+ *   - a **route module**, for the same reason one level down: a route or layout IS a chain member, so it
+ *     is always the dynamic child. It is also the wrong boundary to patch - a route module carries the
+ *     loader and meta the server ran, and re-running those is a navigation, not a patch. Editing one
+ *     finds no accepting module and reloads the page, which is the correct outcome.
+ *
+ * Both cost nothing in practice: the components an edit loop actually touches are the views, and a view
+ * that wants to hot-patch lives outside the routes directory. Where the split is unknown (no dev server,
+ * or a root that was never announced), the answer is `false` - a full reload is always correct, a
+ * mispatched tree is not.
+ */
+export function devHotComponent(path: string): boolean {
+  const root = process.env[DEV_ROOT_ENV]
+  if (!under(path, root)) return false
+  if (path.includes("/node_modules/")) return false
+  return !under(path, process.env[DEV_ROUTES_ENV])
+}
+
 /**
  * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module -
  * the idiom the Vue plugin established (`?vue-css`). Register one per plugin `setup`; call `emit` per

package/src/vite.ts

@@ -20,9 +20,11 @@ import { relative, resolve as resolvePath } from "node:path"
 import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { listenOrExplain } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
-import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEFAULT_DEV_PORT, generateClientEntry, setSsrModuleLoader } from "./index.ts"
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
 import { importVite } from "./internal/vite-import.ts"
+import { scopedName } from "./plugins/css-modules.ts"
+import { DEV_ROOT_ENV, DEV_ROUTES_ENV, reproduciblePath } from "./plugins/kit.ts"
 import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
 import { viteServerOnlyEmpty } from "./plugins/vite-server-only.ts"
 
@@ -296,6 +298,12 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   const routesDir = resolvePath(options.routesDir)
   const port = options.port ?? DEFAULT_DEV_PORT
 
+  // Which files are the app's own components, for framework plugins that hot-patch at component
+  // granularity (`devHotComponent`). Announced in the environment rather than passed, because the
+  // plugin that reads it is constructed by the app, in its own config, before this server exists.
+  process.env[DEV_ROOT_ENV] = root
+  process.env[DEV_ROUTES_ENV] = routesDir
+
   // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
   const toUrl = (file: string): string => `/${relative(root, `${routesDir}/${file}`)}`
   const writeClientEntry = (): void => {
@@ -442,10 +450,26 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
         externalConditions: ssrConditions,
       },
     },
+    css: {
+      modules: {
+        // Vite ships its own CSS-Modules naming (`_name_<base64>`); the Bun pipeline and every
+        // `nifra build` use `scopedName`. Left alone, one class is called two different things
+        // depending on which pipeline served it, so a selector written against a generated name works
+        // in dev and vanishes in production - and the two dev pipelines disagree with each other. The
+        // name is defined once, in the plugin, and Vite is handed that definition.
+        generateScopedName: (name: string, filename: string): string =>
+          scopedName(reproduciblePath(filename), name),
+      },
+    },
     ...(options.define ? { define: options.define } : {}),
   })
 
   const ssrLoad = (absolutePath: string): Promise<unknown> => vite.ssrLoadModule(absolutePath)
+  // Published so an ADAPTER can reach this graph too. Route modules already load through it; an
+  // adapter that has to load a compiled asset of its own on the server (`@nifrajs/web-svelte` and its
+  // `Chain.svelte`) would otherwise take it from the runtime, which has no compiler for it and no
+  // reason to agree with Vite about which copy of the framework runtime it renders through.
+  setSsrModuleLoader(ssrLoad)
   app = await options.createApp(entryUrl, ssrLoad)
 
   // Re-create the app on change so a hard reload picks up a route ADD/REMOVE (the manifest comes
@@ -486,6 +510,10 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   return {
     port: typeof address === "object" && address !== null ? address.port : port,
     stop: async () => {
+      // Cleared with the server that owns it: the slot is process-global, so a stopped server leaving
+      // its loader behind would hand the next one's adapter a graph that is closed (tests start and
+      // stop several dev servers in one process).
+      setSsrModuleLoader(undefined)
       server.close()
       await vite.close()
     },