@nifrajs/cli 2.10.0 → 2.11.0

package/docs/llms-full.txt

@@ -3545,23 +3545,35 @@ Deploy: `wrangler pages deploy dist` (Pages) or `wrangler deploy`
 `server.ts` to hand-write. (`create-nifra` scaffolds the conventions.)
 
 ```ts
-nifra dev      # true-HMR dev server (Vite middleware + Nifra SSR) - http://localhost:4321
+nifra dev      # true-HMR dev server (Bun native HMR + Nifra SSR) - http://localhost:4321
+nifra dev --vite   # the Vite middleware pipeline instead (automatic when vitePlugins are your ONLY transforms)
 nifra build    # full Bun deploy → dist/server.js + content-hashed dist/assets/ (default target: bun)
 nifra start    # run dist/server.js on Bun
 nifra build --target cf-pages  # also: node | deno | vercel | static; add --report for chunk sizes
 
 # dev + start share the default port 4321. Override per run: --port <n> (alias -p) or the PORT env var.
 # flags: --port <n> (dev/start) · --out <dir> (build/start) · --target <t> (build) · --poll (dev)
+#        --vite | --bun (dev/build) force the pipeline
 ```
 
 ### The conventions
 
-Four conventions at the project root. `nifra dev` runs the Vite-backed
+Four conventions at the project root. `nifra dev` runs the Bun-native
 [HMR dev server](/docs/dev); `nifra build` runs the Bun-native production
 build (content-hashed client assets plus a target-specific server); `nifra start`
 runs the default Bun output. The generated server serves assets and SSR with matched-route
 chunks preloaded and route CSS linked in each `<head>`.
 
+**One rule picks the bundler, and it is the same rule in both phases** - so a
+project can never be bundled by one toolchain in dev and the other in production. Bun runs
+everything, except an app whose _only_ transforms are `vitePlugins`: the Bun
+pipeline cannot run those, so that app gets Vite for dev and build alike, and says so.
+`--vite` / `--bun` force the choice; `--bun` is refused on a
+Vite-only app rather than dropping its transforms silently. Every `dev` and
+`build` run prints which bundler it picked and why, and `nifra check`
+answers the same question without starting a server - see
+[which pipeline runs, when](/docs/dev) for the full table.
+
 ```ts
 my-app/
   routes/            # file-based routes (index.tsx, _layout.tsx, [id].tsx, …)
@@ -3844,9 +3856,9 @@ distinct.
 
 Nifra gives you two local development loops, and the rule between them is that one
 toolchain owns a whole phase. **Both** give you React Fast Refresh with state
-preserved. Use `nifra dev` (Vite) for the plugin ecosystem, or
-`nifra dev --bun` for one bundler across dev and prod with no Vite dependency.
-Both serve your real SSR app locally, and neither mixes the two bundlers in one process.
+preserved. Bun is the default; Vite takes over automatically when your config's only
+transforms are `vitePlugins`. Both serve your real SSR app locally, and neither
+mixes the two bundlers in one process.
 
 ### Two loops, same app
 
@@ -3859,7 +3871,7 @@ use when
 
 Bun HMR + Fast Refresh (native)
 none (Bun only)
-one bundler dev+prod; no Vite dep (no CSS Modules)
+one bundler dev+prod, no Vite dep; CSS Modules included
 
 `@nifrajs/web/vite`
 
@@ -3869,6 +3881,79 @@ true HMR (Fast Refresh / framework HMR)
 
 state-preserving UI iteration
 
+### Which pipeline runs, when
+
+One rule decides the bundler, and it decides it the same way for `nifra dev` and
+`nifra build` - your dev loop and your production build are never on different
+toolchains.
+
+your config
+command
+pipeline
+why
+
+no plugins at all
+
+`nifra dev` / `nifra build`
+
+Bun
+the default: no Vite dependency, one bundler across dev and prod
+
+`clientPlugins` and/or `serverPlugins`
+
+`nifra dev` / `nifra build`
+
+Bun
+those slots are Bun.build plugins; Vite would never call them
+
+`vitePlugins` only
+
+`nifra dev` / `nifra build`
+
+Vite (automatic)
+the Bun build cannot run them, so staying on Bun would silently drop your transforms
+
+`vitePlugins` only
+
+`--bun`
+
+error
+nifra refuses rather than build an app with its compiler switched off
+
+any
+
+`--vite`
+
+Vite (forced)
+
+exact dev/prod client resolution for `conditions`, or a Vite-only plugin
+
+any
+
+`--bun`
+
+Bun (forced)
+allowed whenever no transform would be lost
+
+You never have to work this out from the table. Every `nifra dev` and
+`nifra build` run prints the answer under its banner, and
+`nifra check` and `nifra doctor` report it - with the config hazards
+below - without starting a server:
+
+```ts
+# doc-check: skip - fragment: terminal output, not source.
+$ nifra dev
+nifra dev (bun) → http://localhost:3000
+  bundler: bun (default; --vite to switch)
+
+$ nifra build
+nifra build (node, vite) → dist/server/server.js
+  bundler: vite (auto: this app's only transforms are `vitePlugins` (svelte), which the Bun build cannot run)
+
+$ nifra check
+• bundler: vite (auto: this app's only transforms are `vitePlugins` (svelte), which the Bun build cannot run)
+```
+
 ### State-preserving HMR
 
 Use `createViteDevServer` when you want component edits to update the browser
@@ -4012,10 +4097,12 @@ a component-only module swaps its markup with `useState` state intact, no reload
 boundary rule is the same as Vite's (see below). The real prize is that dev and production use
 the _same bundler_, so the dev/prod seam disappears.
 
-One gap: **CSS Modules**. Bun's dev-server bundler has no
-`*.module.css` transform (its production `Bun.build` does), so the CLI
-refuses `--bun` for a CSS-Modules app rather than serving a broken client. Plain CSS
-and Tailwind work normally.
+**CSS Modules included.** Bun's dev-server bundler has no
+`*.module.css` transform of its own, so the CLI hands it the same one the
+production `Bun.build` uses - and a class hashes to the same scoped name on every
+pipeline. Calling `createDevServer` as a library instead of through the CLI, you
+supply that plugin yourself through your own `bunfig.toml`; plain CSS and Tailwind
+need nothing either way.
 
 **
 Server functions and `*.server` modules work under `--bun`
@@ -4044,7 +4131,8 @@ source. A divergence between the loops is treated as a bug, not a caveat.
 import { createDevServer } from "@nifrajs/web/dev"
 // Bun.serve bundles + hot-reloads the client; Bun's runtime resolves SSR. An edit reloads the
 // changed module graph - with React Fast Refresh (state preserved) applied natively by Bun, no plugin.
-// CSS + the entry URL come from Bun. Plain CSS/Tailwind work; *.module.css does not (Bun's dev bundler).
+// CSS + the entry URL come from Bun. Plain CSS/Tailwind work as-is; for *.module.css as a library
+// caller, pass the production CSS Modules plugin through your own bunfig (nifra dev --bun does it for you).
 const server = await createDevServer({ routesDir, outDir, clientModule, createApp })
 ```
 
@@ -4161,6 +4249,105 @@ own stylesheet. Pass `manifest.routeStyles` to `createWebApp` alongside
 `styles`, and Nifra links the matched route's CSS during SSR. In
 **dev**, Vite injects per-module CSS.
 
+### Gotchas
+
+The rule "one toolchain owns a whole phase" is what keeps the two loops honest, and most of
+what follows is a consequence of it. None of these are things you have to memorise before you
+start - they are the edges you can hit later, collected in one place.
+
+#### Keep the adapter out of your config file
+
+Split `framework.ts` (the adapter, imported by your server and edge entries) from
+`nifra.config.ts` (the CLI's config, where the Vite plugins and SFC compilers live).
+If your server entry reaches the adapter _through_ the config, everything the config
+imports is bundled into your production server - the Vite plugin, the framework compiler, and
+their native bindings. It builds without complaint and then fails at startup with a missing
+native binding, which reads like a broken install rather than a config-shape problem.
+
+```ts
+// doc-check: skip - fragment: two files from one app, shown together.
+// framework.ts - imported by your SERVER and edge entries. Adapter only, nothing else.
+import { svelteAdapter } from "@nifrajs/web-svelte"
+export const adapter = svelteAdapter
+
+// nifra.config.ts - imported ONLY by the CLI, which runs on Bun. Compilers and Vite plugins
+// belong here. Re-export the adapter; never define it here, or the dev toolchain it pulls in
+// (Vite, the SFC compiler, their native bindings) is bundled into your production server.
+import { svelte } from "@sveltejs/vite-plugin-svelte"
+export { adapter } from "./framework"
+export const clientModule = "@nifrajs/web-svelte/client"
+export const vitePlugins = [svelte()]
+```
+
+#### Plugins go in the slot that matches the pipeline
+
+`vitePlugins` run on the Vite pipeline; `clientPlugins` and
+`serverPlugins` run on the Bun one. A plugin in the wrong slot is not an error, it
+is a _no-op_ - your transform silently does not run. Nifra classifies each plugin by its
+hook shape and refuses a mismatch rather than letting the build succeed without it. The same
+check is why `--bun` throws for an app whose only transforms are
+`vitePlugins`, instead of building without them.
+
+#### `conditions` does not reach the Bun dev client bundle
+
+On the Bun pipeline, `conditions` governs SSR - `nifra dev` passes them
+to the runtime when it re-execs - and it governs the production client bundle. It cannot govern
+the client bundle the dev server serves: Bun's dev-server bundler accepts no resolve
+conditions, and there is no `bunfig.toml` key for them either (a top-level
+`conditions`, or one under `[run]`, `[serve.static]` or
+`[bundle]`, parses and is ignored). So a package with an `exports` map
+can resolve to one file in dev and another in `nifra build`. Nifra says so once at
+startup rather than letting you find out in production. If your app depends on exact dev/prod
+client resolution, run `nifra dev --vite`.
+
+Related, if you ever pass the flag to `bun` yourself: it takes
+**one condition per flag**. The comma form is accepted and matches nothing,
+because Bun reads the whole string as a single condition name.
+
+```ts
+# Resolve conditions on the Bun dev pipeline.
+# SSR honours `conditions` - nifra passes them to the runtime when it re-execs.
+# The CLIENT bundle does not: Bun's dev-server bundler takes no resolve conditions,
+# from bunfig.toml or anywhere else. nifra warns once at startup when it matters.
+nifra dev --vite            # exact dev/prod client resolution, if your app needs it
+
+# If you invoke bun yourself: ONE FLAG PER CONDITION.
+bun --conditions=browser --conditions=development ./app.ts   # correct
+bun --conditions=browser,development ./app.ts                # ONE condition named "browser,development"
+```
+
+#### Editing a non-route file updates SSR too
+
+On the Bun pipeline the dev server tracks the module graph your routes import, so editing a
+component, a helper, or a server module several levels down is reflected in the next SSR
+render - not just in the browser bundle. Modules you did _not_ touch keep their
+identity, so a module-level singleton stays single across the reload. Two limits are
+deliberate: files under `node_modules` are not tracked (they are dependencies, not
+your source), and a specifier only participates if it is relative and written literally - a
+computed or aliased specifier is invisible to a static graph. A third-party Bun plugin that
+rewrites imports needs to call `rewriteSsrImports` for its output to stay tracked.
+
+#### An adapter with a compiled asset needs the dev server's loader
+
+This one matters only if you are writing a render adapter. On the Vite pipeline Vite owns SSR
+resolution, which is what lets `resolve.dedupe` reach the server and keeps your app
+on one copy of the framework. Adapter packages themselves stay external to that graph, because
+the adapter's context object has to be the one instance your app imported. If such an adapter
+must load a _compiled_ asset on the server - Svelte's chain component is one - a plain
+`import` reaches a runtime with no compiler for it, and registering a second
+compiler in the runtime is worse: the tree then holds two copies of the framework runtime, and
+context written by one half is invisible to the other. Load it through
+`ssrModuleLoader()` instead, and take the framework's _server renderer_ from
+there as well - a component compiled by one toolchain has to render through the renderer that
+toolchain resolved.
+
+#### Scoped class names are identical across pipelines
+
+A CSS Modules class hashes to the same scoped name whichever pipeline produced it, and across
+machines - the hash is keyed on the class name plus the module's _package-relative_
+path, never an absolute one. A selector written against a generated name behaves the same under
+`nifra dev`, `nifra dev --bun`, and `nifra build`.
+
 ## Nifra - Troubleshooting
 
 > Fixes keyed on the literal error strings Nifra prints: `reached the client bundle` (a node:/native import in the browser bundle), `server-only module reached the client bundle` (the server-only marker), and `resolveDispatcher` / `Invalid hook call` (duplicate React).
@@ -6877,7 +7064,7 @@ The `nifra` CLI - zero-config dev/build/start for a nifra app, plus the agent su
 `routes/`).
 
 ```
-nifra dev     [--port <n>] [--poll]       True-HMR dev server (Vite + nifra SSR).
+nifra dev     [--port <n>] [--poll]       True-HMR dev server (Bun + nifra SSR; Vite for a Vite-only app).
 nifra build   [--out <dir>] [--target <t>]  Complete deploy directory; target defaults to Bun.
 nifra start   [--port <n>] [--out <dir>]   Run the generated Bun server at <out>/server.js.
 nifra context                             Print this project's API + page routes + conventions.
@@ -8955,7 +9142,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateRouteSearchTypes`, `GenerateRouteSearchTypesOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `IDLE_BLOCKER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `notFound`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `registerBlocker`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderedPage`, `renderPage`, `RenderPageInput`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `RouteSearch`, `routeStyles`, `ScriptDescriptor`, `searchOf`, `SearchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `ServePublicDirOptions`, `SERVER_FN_MODULE`, `SERVER_ONLY_MODULE`, `ServerOnly`, `setBlockerController`, `setBrowserNavigate`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `unsafeInlineScript`, `UnsafeScriptDescriptor`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `assertRenderAdapterConformance`, `Blocker`, `BlockerController`, `BlockerFunction`, `BlockerLocation`, `BlockerState`, `BrowserNavigate`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createMutation`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `DehydratedState`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `gate`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateRouteSearchTypes`, `GenerateRouteSearchTypesOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `getBrowserNavigate`, `GetStaticPaths`, `gone`, `hashQueryKey`, `IDLE_BLOCKER`, `InertScriptType`, `InfiniteData`, `InfiniteQueryHandle`, `InfiniteQueryOptions`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_REVALIDATE_TAGS_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LAYOUT_DATA_GLOBAL`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `MutationCallbacks`, `MutationHandle`, `MutationState`, `MutationStatus`, `NAV_FROM_HEADER`, `NavigateFunction`, `NavigateOptions`, `NavigateSearchOf`, `NavigateTargetInput`, `notFound`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `previewEndpoint`, `PreviewEndpointOptions`, `PublicDirCache`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryOptions`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `registerBlocker`, `RenderAdapter`, `RenderAdapterConformanceError`, `RenderAdapterConformanceFixture`, `RenderAssemblyCache`, `RenderedPage`, `renderPage`, `RenderPageInput`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `resolveNavigate`, `resolvePublicPath`, `RETAIN_HEADER`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROOT_ATTRIBUTE`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `RouteSearch`, `routeStyles`, `ScriptDescriptor`, `searchOf`, `SearchOf`, `searchOfChain`, `serializeData`, `serializeSearch`, `servePublicDir`, `ServePublicDirOptions`, `SERVER_FN_MODULE`, `SERVER_ONLY_MODULE`, `ServerOnly`, `setBlockerController`, `setBrowserNavigate`, `setSsrModuleLoader`, `ssrModuleLoader`, `SsrModuleLoader`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `STATUS_HEADER`, `statusPage`, `StatusPageOptions`, `styles`, `Submission`, `SubmitOptions`, `unsafeInlineScript`, `UnsafeScriptDescriptor`, `withISR`
 
 ## @nifrajs/web-preact
 

package/docs/types.json

@@ -3229,6 +3229,33 @@
     "signature": "export declare function detectServerOnlyInClient(graph: ClientModuleGraph): ReadonlyArray<ServerOnlyFinding>;",
     "doc": "/**\n * Scan a build's metafile for any module that opts into the `server-only` marker (a side-effect\n * `import \"@nifrajs/web/server-only\"`) yet landed in a CLIENT output chunk, returning a sorted, deduped\n * list of {@link ServerOnlyFinding}s. Mirrors {@link detectNodeBuiltinsInClient}: it reads the SAME\n * graph facts - which inputs import the marker (the \"marked\" modules), which chunk each landed in (the\n * per-output `inputs`), and the shortest import chain from a user entry to it. The marker module ITSELF\n * (which imports nothing) is excluded - only the modules that *opt in* are flagged. Pure + exported for\n * unit testing. Empty ⇒ clean.\n */"
   },
+  {
+    "name": "DEV_HMR_ENV",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const DEV_HMR_ENV = \"NIFRA_DEV_HMR\";",
+    "doc": "/**\n * Env flag a nifra dev server sets for its own lifetime, so a framework compiler plugin can tell a dev\n * compile from a `nifra build` one. Exported for the dev server that sets it; plugins ask\n * {@link devServerCompile} instead of reading it.\n */"
+  },
+  {
+    "name": "DEV_ROOT_ENV",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const DEV_ROOT_ENV = \"NIFRA_DEV_ROOT\";",
+    "doc": "/**\n * The app root and the routes directory of the running dev server, for plugins that need to tell one of\n * the app's own components from a dependency or a route module. Set alongside {@link DEV_HMR_ENV}; read\n * through {@link devHotComponent}.\n */"
+  },
+  {
+    "name": "DEV_ROUTES_ENV",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const DEV_ROUTES_ENV = \"NIFRA_DEV_ROUTES\";"
+  },
+  {
+    "name": "devHotComponent",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function devHotComponent(path: string): boolean;",
+    "doc": "/**\n * Whether a dev compile of `path` may wrap the module in component-level hot-patching - i.e. whether it\n * is one of the app's OWN components rather than a dependency or a route module.\n *\n * The exclusions are not caution, they are two things such a wrapper cannot survive:\n *\n *   - a **dependency**, whose components are the framework's own composition machinery. An adapter folds\n *     a layout chain through them, so they are entered from a snippet or as a dynamic component - and a\n *     wrapper there sits between the SSR markup and the component that is supposed to claim it.\n *   - a **route module**, for the same reason one level down: a route or layout IS a chain member, so it\n *     is always the dynamic child. It is also the wrong boundary to patch - a route module carries the\n *     loader and meta the server ran, and re-running those is a navigation, not a patch. Editing one\n *     finds no accepting module and reloads the page, which is the correct outcome.\n *\n * Both cost nothing in practice: the components an edit loop actually touches are the views, and a view\n * that wants to hot-patch lives outside the routes directory. Where the split is unknown (no dev server,\n * or a root that was never announced), the answer is `false` - a full reload is always correct, a\n * mispatched tree is not.\n */"
+  },
   {
     "name": "devHtml",
     "kind": "function",
@@ -3242,6 +3269,13 @@
     "package": "@nifrajs/web",
     "signature": "export interface DevServer {\n    readonly port: number;\n    /**\n     * The URL pages point their client entry at - always {@link CLIENT_ENTRY_PATH}, never Bun's hashed\n     * chunk. Deliberately not the underlying chunk URL: that one moves on every rebuild, and anything\n     * holding onto it is holding onto a URL that will stop working.\n     */\n    readonly clientEntry: string;\n    stop(): void;\n}"
   },
+  {
+    "name": "devServerCompile",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function devServerCompile(): boolean;",
+    "doc": "/**\n * True while a nifra dev server is running, i.e. the compile may emit HMR wiring (and, where the\n * framework couples the two, dev-mode runtime output).\n *\n * The phase cannot be a plugin constructor argument: an app builds its `clientPlugins` once in\n * `nifra.config.ts` and the same plugin objects serve both `nifra dev` and `nifra build`. Guarding the\n * emitted code with `if (import.meta.hot)` is not sufficient either - `Bun.build` keeps the branch, so\n * the HMR calls were measured shipping in production client chunks. The dev server announces itself in\n * the environment instead, and `nifra build` never sets it. Read per compile (not captured at\n * registration) so the flag is honoured however late the server sets it.\n */"
+  },
   {
     "name": "DevServerOptions",
     "kind": "interface",
@@ -4520,6 +4554,13 @@
     "signature": "export declare class Histogram {\n    readonly name: string;\n    readonly help: string;\n    private readonly series;\n    private readonly buckets;\n    constructor(name: string, help: string, buckets: readonly number[]);\n    observe(value: number, labels?: Labels): void;\n    render(): string;\n}",
     "doc": "/** Latency-style distribution over fixed buckets (seconds). Renders Prometheus cumulative buckets. */"
   },
+  {
+    "name": "hotUpdateNeedsReload",
+    "kind": "const",
+    "package": "@nifrajs/web-preact",
+    "signature": "export declare const hotUpdateNeedsReload = true;",
+    "doc": "/**\n * Preact cannot apply Bun's hot updates, so the generated client entry reloads instead.\n *\n * Bun's dev server runs React Fast Refresh over JSX modules. A Preact component compiles to JSX that\n * looks the same, so the update is ACCEPTED - and then dropped, because Preact's refresh runtime\n * (prefresh) is not the one Bun installs. Measured: `bun:beforeUpdate` and `bun:afterUpdate` both fire,\n * the server logs the rebuild, the browser keeps rendering the old component and never reloads. The\n * edit simply appears not to happen.\n *\n * Reloading loses component state, which React keeps here. That is the honest trade until Bun's dev\n * server can install prefresh: a visible reload beats an edit that silently does nothing.\n */"
+  },
   {
     "name": "html",
     "kind": "function",
@@ -6186,7 +6227,7 @@
     "kind": "function",
     "package": "@nifrajs/web",
     "signature": "export declare function mergeHeads(heads: readonly Meta[]): Meta;",
-    "doc": "/**\n * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.\n *\n * The head contract (see {@link CreateWebAppOptions} and `LayoutEntry`): a `_layout.tsx` may export\n * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below\n * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the\n * render chain), and merges:\n *  - **`title`** - *nearest-wins*: the last defined value across the list, so the page overrides an\n *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined\n *    page `title` keeps it.\n *  - **`meta` / `link`** - *concatenated* in list order (outermost first, page last). Duplicate-tag\n *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout\n *    can ship N `<link rel=\"alternate\" hreflang>` tags and a page can add its own canonical.\n *\n * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a\n * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is\n * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its\n * content can vary with loader data anyway).\n */"
+    "doc": "/**\n * Merge a layout chain's heads, outermost first: `title`/`lang`/`dir` are nearest-wins, and\n * `meta`/`link`/`script` concatenate in chain order.\n *\n * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a\n * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is\n * fine: `headTags`'s memo is keyed on identity, so a per-request merge simply recomputes (its\n * content can vary with loader data anyway).\n */"
   },
   {
     "name": "Messages",
@@ -8352,7 +8393,7 @@
     "kind": "function",
     "package": "@nifrajs/web",
     "signature": "export declare function resolveMeta(meta: MetaInput | undefined, args: MetaArgs): Meta;",
-    "doc": "/** Resolve a route's `meta` (static or a function of the loader data + params) to a {@link Meta}. */"
+    "doc": "/** Resolve a route's `meta` export - a static object, or a function of the route's data/params. */"
   },
   {
     "name": "resolveNavigate",
@@ -8614,6 +8655,13 @@
     "signature": "export interface RevalidateResult<T> {\n    readonly __nifraRevalidate: readonly string[];\n    readonly data: T;\n}",
     "doc": "/** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged\n * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing\n * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and\n * the paths via the `X-Nifra-Revalidate` header. */"
   },
+  {
+    "name": "rewriteSsrImports",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function rewriteSsrImports(contents: string, path: string, generate: \"dom\" | \"ssr\"): string;",
+    "doc": "/**\n * Re-key the app-owned imports of a module a **server-side** plugin just compiled. A plugin that claims a\n * file extension is the only code that sees that file's source, so it is the only place its imports can\n * be versioned; without this call every component in that language stays on the code it had at startup.\n *\n * A no-op outside a Bun dev server, and on the client half of a plugin - the client is bundled, and a\n * bundle has no import cache to bust.\n */"
+  },
   {
     "name": "richWireCodec",
     "kind": "function",
@@ -9206,6 +9254,13 @@
     "signature": "export interface SchemaSnapshot {\n    readonly jsonSchema?: JsonSchema;\n    readonly fields?: readonly ReflectedSchemaField[];\n}",
     "doc": "/** One schema position in a snapshot: JSON Schema metadata only, no validator. */"
   },
+  {
+    "name": "scopedName",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function scopedName(filePath: string, className: string): string;",
+    "doc": "/**\n * The scoped name for a class. Keyed by `filePath` + `className` (NUL-separated so `\"a\"+\"bc\"` can't\n * collide with `\"ab\"+\"c\"`), so the same class name in two different files gets two different scoped\n * names - cross-file collision resistance - while staying stable across builds.\n *\n * Exported because it is the definition of the name, and the OTHER pipeline has to be able to produce\n * it: Vite ships its own CSS-Modules naming, so without handing Vite this function a class is called\n * one thing under `nifra dev --vite` and another after `nifra build`. `filePath` must be the\n * package-relative form from `reproduciblePath`, never an absolute path, or the name stops being\n * reproducible across machines.\n */"
+  },
   {
     "name": "ScriptDescriptor",
     "kind": "interface",
@@ -9798,6 +9853,13 @@
     "signature": "export type SetSearchParams = (next: SearchParamsInit | ((prev: URLSearchParams) => SearchParamsInit), options?: NavigateOptions) => void;",
     "doc": "/** Set the query string. Accepts a `URLSearchParams`, a record, a raw string, or an updater of the\n * current params; navigates to the same pathname with the new query (push, or replace via options). */"
   },
+  {
+    "name": "setSsrModuleLoader",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function setSsrModuleLoader(load: SsrModuleLoader | undefined): void;",
+    "doc": "/**\n * Publishes the dev server's SSR module loader. Called by a dev server that owns SSR resolution\n * itself; pass `undefined` to clear it on shutdown.\n */"
+  },
   {
     "name": "shapeOf",
     "kind": "function",
@@ -9981,7 +10043,7 @@
     "kind": "function",
     "package": "@nifrajs/web-solid",
     "signature": "export declare function solidBunPlugin(generate: \"dom\" | \"ssr\"): BunPlugin;",
-    "doc": "/**\n * Bun build/runtime plugin that compiles Solid components with Babel - `generate: \"ssr\"`\n * for the server, `\"dom\"` for the client, `hydratable` so SSR and hydrate align. Solid's\n * reactive-JSX compiler ships only as a Babel plugin (no swc/native port); this runs at\n * build time, on `.tsx` files only.\n */"
+    "doc": "/**\n * Bun build/runtime plugin that compiles Solid components with Babel - `generate: \"ssr\"`\n * for the server, `\"dom\"` for the client, `hydratable` so SSR and hydrate align. Solid's\n * reactive-JSX compiler ships only as a Babel plugin (no swc/native port); this runs at\n * build time, on `.tsx` files only.\n *\n * Under a dev server the client half additionally runs `solid-refresh`, which is what makes an edit\n * patch the running component tree instead of reloading the page - see {@link setupSolidRefresh}.\n */"
   },
   {
     "name": "solidMdxBunPlugin",
@@ -10115,6 +10177,20 @@
     "signature": "export interface SSEStream {\n    /** Enqueue an event frame. No-op once the stream is closed. */\n    send(message: SSEMessage): void;\n    /** End the stream now. */\n    close(): void;\n    /** Aborts when the client disconnects - use it to tear down subscriptions/loops. */\n    readonly signal: AbortSignal;\n}",
     "doc": "/** The stream handed to the `run` callback. */"
   },
+  {
+    "name": "ssrModuleLoader",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function ssrModuleLoader(): SsrModuleLoader | undefined;",
+    "doc": "/**\n * The dev server's SSR module loader, or `undefined` when nothing owns SSR resolution but the runtime\n * - the Bun dev pipeline, and every production build, where the adapter's assets are compiled ahead\n * of time and a plain `import` is already the right thing.\n *\n * An adapter that must load a COMPILED asset at runtime (a `.svelte` component, say) has to prefer\n * this over a bare `import`, and has to take the framework's SERVER RENDERER from it as well, not\n * just the component. A component compiled by the dev server renders through the renderer the dev\n * server resolved; mixing the two puts two copies of the framework runtime in one component tree,\n * where context written by one half is invisible to the other.\n */"
+  },
+  {
+    "name": "SsrModuleLoader",
+    "kind": "type",
+    "package": "@nifrajs/web",
+    "signature": "export type SsrModuleLoader = (id: string) => Promise<unknown>;",
+    "doc": "/**\n * Loads a module through the DEV SERVER'S module graph rather than the runtime's. Takes an absolute\n * file path or a bare specifier; resolution, compilation and caching are the dev server's.\n */"
+  },
   {
     "name": "StandardFailure",
     "kind": "interface",
@@ -10541,6 +10617,13 @@
     "signature": "export declare const svelteDedupePlugin: (from: string) => BunPlugin;",
     "doc": "/**\n * Dedupe Svelte to a single copy - the Svelte analogue of `reactDedupePlugin`/`preactDedupePlugin`, closing\n * the same class of bug for Svelte (which had NO build-time dedup before). A workspace- or file-linked\n * `@nifrajs/web-svelte` can resolve its OWN `svelte` (e.g. a sibling repo's install store) while the app's\n * components resolve another - SAME version, two physical copies. Svelte 5's client runtime\n * (`svelte/internal/client`) holds module-level component-context state, so two copies means the compiled\n * components register on one runtime while `hydrate` runs on the other → hydration throws\n * `Cannot read properties of undefined (reading 'call')` and the server-rendered markup is wiped.\n *\n * Pin every `svelte` + `svelte/internal/*` import to the ONE copy resolvable from `from` (the app root) so\n * the renderer (`hydrate`/`mount`) and the compiled components share one runtime. Unlike react/preact (a\n * fixed subpath list), Svelte has many internal subpaths, so each matched import is resolved dynamically.\n * `svelte/compiler` (build-time only, not in the bundle) doesn't match the filter and is left alone. No-op\n * when Svelte isn't used / isn't resolvable from `from`.\n */"
   },
+  {
+    "name": "svelteHmrBoundary",
+    "kind": "function",
+    "package": "@nifrajs/web-svelte",
+    "signature": "export declare function svelteHmrBoundary({ filename }: {\n    filename: string;\n}): {\n    hmr: boolean;\n};",
+    "doc": "/**\n * The same hot-patch boundary as the Bun pipeline's, in the shape `@sveltejs/vite-plugin-svelte` takes:\n *\n * ```ts\n * svelte({ dynamicCompileOptions: svelteHmrBoundary })\n * ```\n *\n * Svelte's HMR wrapper resolves the component through a signal, which survives hydration only where\n * the component is a plain child in a template. A layout or a page is not: the adapter's `Chain` enters\n * chain members as dynamic components and through snippets, so a wrapper on one leaves the hydration\n * cursor pointing at markup the wrapped component never claims. Svelte then throws the server's tree\n * away and re-renders on the client - `hydration_mismatch` in the console, on first load, before any\n * edit. Left on, the dev server quietly stops exercising hydration at all.\n *\n * Views keep hot-patching; route modules fall back to a full reload, which is what they want anyway\n * (a route module carries the loader and meta the server ran, and re-running those is a navigation).\n * Outside a nifra dev server nothing is announced and the answer is \"no boundary\" - a full reload is\n * always correct, a mispatched tree is not.\n */"
+  },
   {
     "name": "svelteMdxBunPlugin",
     "kind": "function",
@@ -11609,14 +11692,14 @@
     "name": "VERSION",
     "kind": "const",
     "package": "@nifrajs/core",
-    "signature": "export declare const VERSION: \"2.10.0\";",
+    "signature": "export declare const VERSION: \"2.11.0\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {
     "name": "VERSION",
     "kind": "const",
     "package": "nifra",
-    "signature": "export declare const VERSION: \"2.10.0\";",
+    "signature": "export declare const VERSION: \"2.11.0\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -41,14 +41,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "2.10.0",
-    "@nifrajs/core": "2.10.0",
-    "@nifrajs/mcp": "2.10.0",
-    "@nifrajs/runner": "2.10.0",
-    "@nifrajs/schema": "2.10.0",
-    "@nifrajs/testing": "2.10.0",
-    "@nifrajs/web": "2.10.0",
-    "create-nifra": "2.10.0"
+    "@nifrajs/client": "2.11.0",
+    "@nifrajs/core": "2.11.0",
+    "@nifrajs/mcp": "2.11.0",
+    "@nifrajs/runner": "2.11.0",
+    "@nifrajs/schema": "2.11.0",
+    "@nifrajs/testing": "2.11.0",
+    "@nifrajs/web": "2.11.0",
+    "create-nifra": "2.11.0"
   },
   "repository": {
     "type": "git",