@nifrajs/web 2.13.0 → 3.1.0

package/src/router.ts

@@ -7,7 +7,9 @@
 import { decodeRouteParams } from "@nifrajs/core/pattern"
 import { Router as CoreRouter } from "@nifrajs/core/router"
 import type { StandardSchemaV1 } from "@nifrajs/core/server"
+import type { BoundaryDescriptor, BoundaryStates } from "./boundary.ts"
 import { parseNdjsonData } from "./deferred.ts"
+import type { ClientActionResult, ClientRequestBody, ClientRouteHooks } from "./manifest.ts"
 import { isClientOnlySearchChange } from "./search.ts"
 
 /**
@@ -89,6 +91,8 @@ export interface RouteDataEnvelope {
   /** Indices whose loader was SKIPPED because the layout's own params did not change. The client
    * keeps its existing value at each of these, so an unchanged layout is neither refetched nor lost. */
   readonly retained?: readonly number[]
+  /** Dynamic-boundary states returned alongside loader/layout data. */
+  readonly boundaries?: BoundaryStates
   /** Terminal status signalled by a loader. Added by the browser transport after reading
    * `X-Nifra-Status`; old servers and static data files simply omit it. */
   readonly status?: number
@@ -128,6 +132,8 @@ export interface RouterState {
   /** Per-layout loader data, aligned with the matched chain's leading layout prefix. Absent when no
    * layout in that chain has a loader. */
   readonly layoutData?: readonly unknown[] | undefined
+  /** Neutral named-boundary states for the active route. */
+  readonly boundaries?: BoundaryStates
   /** An action's data return after a client-side submit (cleared on navigation). */
   readonly actionData?: unknown
   /** True while a navigation or submit is in flight (drives loading UI). */
@@ -247,6 +253,8 @@ export interface ClientRouter {
     body: NonNullable<RequestInit["body"]>,
     opts?: SubmitOptions,
   ) => Promise<void>
+  /** Run the initial route's client loader after the adapter has hydrated the SSR markup. */
+  hydrate: () => Promise<void>
   /**
    * Mark cached route data stale and refresh the active view. With `paths`, target exactly those
    * (e.g. the routes a mutation changed); without, invalidate the whole cache. The active route
@@ -295,6 +303,8 @@ export interface ClientRouterOptions {
    * entry's `loadModule` (so a route's keys are present once it has been visited, which is exactly when a
    * same-route nav can consult them). Omit ⇒ every search change revalidates (the safe default). */
   readonly searchClientKeys?: Readonly<Record<string, readonly string[]>>
+  /** routeId → client-only loader/action hooks, populated by the generated route entry. */
+  readonly routeHooks?: Readonly<Record<string, ClientRouteHooks | undefined>>
 }
 
 /** Options for a per-adapter `mountRouter` (the Router binding that hydrates + re-renders). */
@@ -393,12 +403,58 @@ const rawSearchOf = (path: string): string => {
   return q === -1 ? "" : path.slice(q)
 }
 
+/** Validate the client-action envelope before reading it. Its `body` is deliberately not treated as
+ * trusted data: it is an opaque RequestInit body that the server action must parse and authorize. */
+const isClientActionResult = (value: unknown): value is ClientActionResult =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
 export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   const match = createMatcher(options.patterns)
   const fetchData = options.fetchData ?? defaultFetchData
   // routeId → the route's client-only search keys. Read by reference (the generated entry keeps writing
   // to it as routes load), so a same-route nav always sees the current route's keys.
   const searchClientKeys = options.searchClientKeys ?? {}
+  // routeId → client hooks. The generated entry mutates this object only while loading a route module;
+  // route navigation reads it after `loadModule` resolves, so an app without hooks pays only a map
+  // lookup and keeps the existing route-chunk split.
+  const routeHooks = options.routeHooks ?? {}
+  // Intercept patterns are compiled lazily from the already-loaded source route descriptor. Invalid
+  // client metadata is ignored (the server's register-time boundary validation remains authoritative),
+  // so a hand-built client manifest fails closed into an ordinary navigation.
+  const interceptMatchers = new Map<string, ReturnType<typeof createMatcher> | null>()
+  const interceptionFor = (
+    sourceRouteId: string,
+    path: string,
+    target: RouteMatch,
+  ): BoundaryDescriptor | undefined => {
+    const boundaries = routeHooks[sourceRouteId]?.boundaries ?? []
+    const pathname = pathnameOf(path)
+    for (const boundary of boundaries) {
+      if (typeof boundary.mode === "string") continue
+      const pattern = boundary.mode.intercept
+      if (
+        pattern.length === 0 ||
+        pattern.length > 2048 ||
+        !pattern.startsWith("/") ||
+        pattern.startsWith("//")
+      )
+        continue
+      let matcher = interceptMatchers.get(pattern)
+      if (matcher === undefined) {
+        try {
+          matcher = createMatcher([{ routeId: "__nifra_intercept__", pattern }])
+        } catch {
+          matcher = null
+        }
+        interceptMatchers.set(pattern, matcher)
+      }
+      if (matcher?.(pathname)?.routeId === "__nifra_intercept__") return boundary
+    }
+    // Keep `target` in the signature so the caller cannot accidentally install an interceptor for an
+    // unmatched route; the match is intentionally performed before this helper is called.
+    void target
+    return undefined
+  }
   /**
    * Fetch a route's data and normalise it.
    *
@@ -411,6 +467,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     readonly data: unknown
     readonly layoutData?: readonly unknown[] | undefined
     readonly terminalRouteId?: string | undefined
+    readonly boundaries?: BoundaryStates
   }
   const loadRouteData = async (
     path: string,
@@ -436,7 +493,11 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       return { data: null, terminalRouteId }
     }
     if (retainFrom === undefined || payload.retained === undefined) {
-      return { data: payload.data, layoutData: payload.layoutData }
+      return {
+        data: payload.data,
+        layoutData: payload.layoutData,
+        ...(payload.boundaries !== undefined ? { boundaries: payload.boundaries } : {}),
+      }
     }
     const retained = new Set(
       payload.retained.filter(
@@ -446,9 +507,110 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     const layoutData = payload.layoutData?.map((value, index) =>
       retained.has(index) ? retainFrom.layoutData[index] : value,
     )
-    return { data: payload.data, layoutData }
+    return {
+      data: payload.data,
+      layoutData,
+      ...(payload.boundaries !== undefined ? { boundaries: payload.boundaries } : {}),
+    }
+  }
+  /**
+   * Apply a client loader without making the server loader eager. The thunk is memoized per navigation
+   * (or per hydration), so a hook can call it repeatedly without duplicate requests. The returned
+   * client value is never sent back to the server.
+   */
+  const applyClientLoader = async (
+    path: string,
+    route: { routeId: string; params: Record<string, string> },
+    signal: AbortSignal | undefined,
+    serverLoad: () => Promise<LoadedRouteData>,
+    initial?: LoadedRouteData,
+  ): Promise<LoadedRouteData> => {
+    const hook = routeHooks[route.routeId]?.clientLoader
+    if (hook === undefined) return initial ?? serverLoad()
+    let serverResult: Promise<LoadedRouteData> | undefined =
+      initial === undefined ? undefined : Promise.resolve(initial)
+    const serverLoader = async (): Promise<unknown> => {
+      if (signal?.aborted === true)
+        throw new DOMException("The operation was aborted", "AbortError")
+      serverResult ??= serverLoad()
+      return (await serverResult).data
+    }
+    const clientData = await hook({
+      url: path,
+      params: route.params,
+      signal: signal ?? new AbortController().signal,
+      serverLoader,
+    })
+    const loaded = await serverResult
+    if (loaded === undefined) return { data: clientData }
+    // A server terminal status always wins over client-derived data. The client hook can enrich a
+    // normal response, but it cannot turn a server 404/410 into a rendered success route.
+    if (loaded.terminalRouteId !== undefined) return loaded
+    return { ...loaded, data: clientData }
   }
   const loadModule = options.loadModule
+  const prepareClientAction = async (
+    action: string,
+    body: ClientRequestBody,
+    signal: AbortSignal,
+  ): Promise<{ readonly body: ClientRequestBody; readonly optimisticData?: unknown }> => {
+    const target = match(action)
+    if (target === null) return { body }
+    await loadModule?.(target.routeId)
+    const hook = routeHooks[target.routeId]?.clientAction
+    if (hook === undefined) return { body }
+    const result = await hook({
+      url: action,
+      params: target.params,
+      signal,
+      body,
+      serverLoader: async () => state.data,
+    })
+    if (result === undefined) return { body }
+    if (!isClientActionResult(result)) {
+      throw new TypeError("[nifra/web] clientAction must return an object or undefined")
+    }
+    return {
+      body: result.body ?? body,
+      ...(Object.hasOwn(result, "optimisticData") ? { optimisticData: result.optimisticData } : {}),
+    }
+  }
+  let hydrated = false
+  const hydrate = async (): Promise<void> => {
+    if (hydrated) return
+    hydrated = true
+    const route = { routeId: state.routeId, params: state.params }
+    if (routeHooks[route.routeId]?.clientLoader === undefined) return
+    const mine = ++token
+    navAbort?.abort()
+    const ac = new AbortController()
+    navAbort = ac
+    const initial = {
+      data: state.data,
+      layoutData: state.layoutData,
+      ...(state.boundaries !== undefined ? { boundaries: state.boundaries } : {}),
+    }
+    const loaded = await applyClientLoader(
+      state.path,
+      route,
+      ac.signal,
+      () => Promise.resolve(initial),
+      initial,
+    )
+    if (mine !== token) return
+    if (loaded.terminalRouteId !== undefined) {
+      await loadModule?.(loaded.terminalRouteId)
+      state = { ...state, routeId: loaded.terminalRouteId, params: {}, data: null }
+    } else {
+      state = {
+        ...state,
+        data: loaded.data,
+        layoutData: loaded.layoutData,
+        ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
+      }
+    }
+    emit()
+  }
   let state = options.initial
   const listeners = new Set<() => void>()
   let token = 0
@@ -472,7 +634,12 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   const MAX_CACHE = 50
   const cache = new Map<
     string,
-    { data: unknown; layoutData?: readonly unknown[] | undefined; status: "fresh" | "stale" }
+    {
+      data: unknown
+      layoutData?: readonly unknown[] | undefined
+      boundaries?: BoundaryStates
+      status: "fresh" | "stale"
+    }
   >()
   const cachePut = (path: string, loaded: LoadedRouteData): void => {
     if (!cache.has(path) && cache.size >= MAX_CACHE) {
@@ -481,14 +648,26 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     }
     // The PAIR, not just the value: navigating back to a cached route must restore its layouts' data
     // too, or they would render empty on a hit and populated on a miss.
-    cache.set(path, { data: loaded.data, layoutData: loaded.layoutData, status: "fresh" })
+    cache.set(path, {
+      data: loaded.data,
+      layoutData: loaded.layoutData,
+      ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
+      status: "fresh",
+    })
   }
   // Flip cached entries to stale (a no-op for paths not in the cache). Shared by `invalidate` and the
   // `X-Nifra-Revalidate` handling in `submit`.
   const markStale = (paths: readonly string[]): void => {
     for (const p of paths) {
       const entry = cache.get(p)
-      if (entry !== undefined) cache.set(p, { data: entry.data, status: "stale" })
+      if (entry !== undefined) {
+        cache.set(p, {
+          data: entry.data,
+          layoutData: entry.layoutData,
+          ...(entry.boundaries !== undefined ? { boundaries: entry.boundaries } : {}),
+          status: "stale",
+        })
+      }
     }
   }
   // Parse the `X-Nifra-Revalidate` response header into validated paths. The header is response data
@@ -515,14 +694,19 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     state = { ...state, pending: true }
     emit()
     try {
-      const loaded = await loadRouteData(
-        state.path,
-        { routeId: state.routeId, params: state.params },
-        ac.signal,
+      const active = { routeId: state.routeId, params: state.params }
+      const loaded = await applyClientLoader(state.path, active, ac.signal, () =>
+        loadRouteData(state.path, active, ac.signal),
       )
       if (mine !== token) return // superseded - drop the stale result
       cachePut(state.path, loaded)
-      state = { ...state, data: loaded.data, layoutData: loaded.layoutData, pending: false }
+      state = {
+        ...state,
+        data: loaded.data,
+        layoutData: loaded.layoutData,
+        ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
+        pending: false,
+      }
       emit()
     } catch (err) {
       if (mine === token) {
@@ -690,7 +874,11 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       ) {
         ++token // supersede any in-flight navigation so its late result is dropped
         navAbort?.abort()
-        cachePut(path, { data: state.data, layoutData: state.layoutData })
+        cachePut(path, {
+          data: state.data,
+          layoutData: state.layoutData,
+          ...(state.boundaries !== undefined ? { boundaries: state.boundaries } : {}),
+        })
         state = { ...state, path, pending: false, pendingPath: undefined }
         emit()
         return
@@ -702,30 +890,68 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       state = { ...state, pending: true, pendingPath: path }
       emit()
       try {
-        // Use prefetched data when present (one-shot - drop it); else fetch. The chunk is loaded
-        // either way (cached + instant after a prefetch), so pending covers both.
+        // Load the route chunk before invoking a client loader. A route without a client loader still
+        // uses the same server-data path; a route with one gets a lazy `serverLoader()` thunk.
+        await loadModule?.(matched.routeId)
+        // Use prefetched server data when present (one-shot - drop it); clientLoader still runs over
+        // that cached result without causing another network request.
         const hit = prefetched.has(path)
-        const dataPromise = hit
-          ? Promise.resolve(prefetched.get(path) as LoadedRouteData)
-          : loadRouteData(
+        const prefetchedData = hit ? (prefetched.get(path) as LoadedRouteData) : undefined
+        if (hit) prefetched.delete(path)
+        const loaded = await applyClientLoader(
+          path,
+          matched,
+          ac.signal,
+          () =>
+            loadRouteData(
               path,
               matched,
               ac.signal,
               state.layoutData === undefined
                 ? undefined
                 : { path: state.path, layoutData: state.layoutData },
-            )
-        if (hit) prefetched.delete(path)
-        const [, loaded] = await Promise.all([loadModule?.(matched.routeId), dataPromise])
+            ),
+          prefetchedData,
+        )
         if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
         if (mine !== token) return // a newer navigation superseded this one - drop the stale result
         cachePut(path, loaded) // keep the keyed cache coherent with what we publish
+        const interception =
+          loaded.terminalRouteId === undefined
+            ? interceptionFor(state.routeId, path, matched)
+            : undefined
+        if (interception !== undefined) {
+          // The target's ordinary data request has already completed (including its server authz and
+          // optional client wrapper). Only the presentation route is retained; the current page stays
+          // mounted underneath the named slot. A target that returned a terminal status never reaches
+          // this branch, so an unauthorized/missing target cannot become a modal.
+          state = {
+            ...state,
+            path,
+            boundaries: {
+              ...(state.boundaries ?? {}),
+              [interception.name]: {
+                name: interception.name,
+                mode: interception.mode,
+                status: "ready",
+                data: loaded.data,
+                ...(interception.errorId === undefined ? {} : { errorId: interception.errorId }),
+              },
+            },
+            actionData: undefined,
+            pending: false,
+            pendingPath: undefined,
+          }
+          emit()
+          return
+        }
         state = {
           routeId: loaded.terminalRouteId ?? matched.routeId,
           params: loaded.terminalRouteId === undefined ? matched.params : {},
           path,
           data: loaded.data,
           layoutData: loaded.layoutData,
+          ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
           actionData: undefined, // a fresh navigation has no action result
           pending: false,
         }
@@ -742,6 +968,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     },
     submit: async (action, body, opts) => {
       const mine = ++token
+      const previousActionData = state.actionData
       // A superseding navigation/submit aborts this submit's FOLLOW-UP reads (revalidation / redirect
       // fetch + their NDJSON drains) - not the mutation POST itself, which should complete.
       // Wire into `navAbort` like `navigate`/`refetchActive`, so a later nav cancels the in-flight read.
@@ -757,7 +984,16 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       }
       emit()
       try {
-        const res = await fetch(action, { method: "POST", body, headers: { [DATA_HEADER]: "1" } })
+        const prepared = await prepareClientAction(action, body, ac.signal)
+        if (Object.hasOwn(prepared, "optimisticData")) {
+          state = { ...state, actionData: prepared.optimisticData }
+          emit()
+        }
+        const res = await fetch(action, {
+          method: "POST",
+          body: prepared.body,
+          headers: { [DATA_HEADER]: "1" },
+        })
         if (!res.ok) throw new Error(`[nifra/web] action failed (${res.status}): ${action}`)
         const redirectTo = res.headers.get(REDIRECT_HEADER)
         if (redirectTo !== null) {
@@ -765,8 +1001,8 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           const target = match(redirectTo)
           if (target === null)
             throw new Error(`[nifra/web] action redirect off-route: ${redirectTo}`)
-          const [, loaded] = await Promise.all([
-            loadModule?.(target.routeId),
+          await loadModule?.(target.routeId)
+          const loaded = await applyClientLoader(redirectTo, target, ac.signal, () =>
             loadRouteData(
               redirectTo,
               target,
@@ -775,7 +1011,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
                 ? undefined
                 : { path: state.path, layoutData: state.layoutData },
             ),
-          ])
+          )
           if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
           if (mine !== token) return
           cachePut(redirectTo, loaded)
@@ -785,6 +1021,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             path: redirectTo,
             data: loaded.data,
             layoutData: loaded.layoutData,
+            ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
             actionData: undefined,
             pending: false,
           }
@@ -802,12 +1039,15 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         // out (`revalidate: false`). A server-declared revalidate of the active path overrides the
         // opt-out (the server says it changed, so stale data would be wrong). Default is to revalidate.
         const skipActive = opts?.revalidate === false && !changed.includes(state.path)
+        const active = { routeId: state.routeId, params: state.params }
         const loaded = skipActive
-          ? { data: state.data, layoutData: state.layoutData }
-          : await loadRouteData(
-              state.path,
-              { routeId: state.routeId, params: state.params },
-              ac.signal,
+          ? {
+              data: state.data,
+              layoutData: state.layoutData,
+              ...(state.boundaries !== undefined ? { boundaries: state.boundaries } : {}),
+            }
+          : await applyClientLoader(state.path, active, ac.signal, () =>
+              loadRouteData(state.path, active, ac.signal),
             )
         if (mine !== token) return
         cachePut(state.path, loaded) // the revalidated (or kept) data is now the cache's truth
@@ -821,6 +1061,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           path: state.path,
           data: loaded.data,
           layoutData: loaded.layoutData,
+          ...(loaded.boundaries !== undefined ? { boundaries: loaded.boundaries } : {}),
           actionData,
           pending: false,
         }
@@ -837,7 +1078,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             params: state.params,
             path: state.path,
             data: state.data,
-            actionData: state.actionData,
+            actionData: previousActionData,
             pending: false,
           }
           emit()
@@ -845,6 +1086,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         throw err
       }
     },
+    hydrate,
     invalidate: async (paths) => {
       // Mark targeted cache entries stale (all entries when no `paths`) - unmounted ones refetch
       // lazily on next access.

package/src/vite.ts

@@ -21,7 +21,13 @@ import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { listenOrExplain } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry, setSsrModuleLoader } from "./index.ts"
-import { assertIdentityParity } from "./internal/parity.ts"
+import { viteDedupePackages } from "./internal/identity-policy.ts"
+import {
+  assertIdentityParity,
+  collectIdentityParity,
+  formatIdentityParityFindings,
+  identityParityHeadline,
+} from "./internal/parity.ts"
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
 import { importVite } from "./internal/vite-import.ts"
 import { scopedName } from "./plugins/css-modules.ts"
@@ -34,6 +40,18 @@ interface FetchApp {
   fetch(request: Request): Response | Promise<Response>
 }
 
+// A node in Vite's module graph. `importers` is the union of client and SSR importers - walking it
+// over-invalidates (a client-only importer gets re-evaluated on the SSR side too), which is safe:
+// re-evaluation is idempotent, and correctness of the served module beats sparing a dev re-eval.
+interface ViteModuleNode {
+  readonly importers: Set<ViteModuleNode>
+}
+// Structural slice of Vite's legacy unified module graph. Absent on a Vite that renamed it (the
+// invalidation degrades to Vite's own change handling, i.e. today's behavior) - never a hard failure.
+interface ViteModuleGraph {
+  getModulesByFile(file: string): Set<ViteModuleNode> | undefined
+  invalidateModule(mod: ViteModuleNode): void
+}
 // Structural slice of the Vite dev server this module drives (avoids a hard type dep on `vite`).
 interface ViteLike {
   /** Load a module through VITE's graph - the seam that makes the Vite pipeline own SSR too. */
@@ -41,6 +59,8 @@ interface ViteLike {
   readonly middlewares: (req: IncomingMessage, res: ServerResponse, next: () => void) => void
   transformIndexHtml(url: string, html: string): Promise<string>
   ssrFixStacktrace(err: Error): void
+  /** The module graph, used to invalidate a changed file AND its transitive importers before reload. */
+  readonly moduleGraph?: ViteModuleGraph
   readonly watcher: {
     on(event: "change" | "add" | "unlink", cb: (path: string) => void): void
   }
@@ -99,6 +119,14 @@ export interface ViteDevServerOptions {
   readonly publicDir?: string | false
   /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
   readonly publicEnvPrefix?: string
+  /**
+   * Downgrade the startup identity-parity check from a hard failure to a loud warning (dev only).
+   * The check catches two physical copies of an identity-sensitive package (e.g. React) resolving in
+   * one process, which reliably breaks hydration and framework context. When a duplicate comes from a
+   * linked sibling repo you cannot fix in the moment, set this to keep the dev server running while you
+   * resolve it; `nifra build` never honors it. Wired to `nifra dev --allow-duplicate-identity`.
+   */
+  readonly allowDuplicateIdentity?: boolean
 }
 
 export interface ViteDevServer {
@@ -297,7 +325,16 @@ function packageNameOf(specifier: string): string | undefined {
 export async function createViteDevServer(options: ViteDevServerOptions): Promise<ViteDevServer> {
   const root = resolvePath(options.root ?? process.cwd())
   const routesDir = resolvePath(options.routesDir)
-  await assertIdentityParity(root)
+  if (options.allowDuplicateIdentity === true) {
+    const parity = await collectIdentityParity(root)
+    if (parity.findings.length > 0)
+      console.warn(
+        `[nifra] identity parity bypassed via --allow-duplicate-identity (${identityParityHeadline(parity.findings.length)}):\n${formatIdentityParityFindings(parity.findings)}\n` +
+          "[nifra] dev is continuing, but duplicate module identity can break hydration and framework context - fix the resolution before you ship.",
+      )
+  } else {
+    await assertIdentityParity(root)
+  }
   const port = options.port ?? DEFAULT_DEV_PORT
 
   // Which files are the app's own components, for framework plugins that hot-patch at component
@@ -431,12 +468,13 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     plugins: [viteServerFnStub(), viteServerOnlyEmpty(), ...plugins],
     resolve: {
       conditions: resolveConditions,
-      // Dedupe React to ONE copy. In a multi-root workspace a shared package can pull react/react-dom
-      // from a SIBLING app's node_modules, so the dev server loads two React cores → a second hook
-      // dispatcher → `resolveDispatcher().useState` null on any hook-using route (the error points at the
-      // component, not the resolution - brutal to diagnose). Mirrors the build-time reactDedupePlugin so
-      // dev matches prod. No-op for non-React apps (the package simply isn't present to dedupe).
-      dedupe: ["react", "react-dom"],
+      // Dedupe each framework runtime to ONE copy. In a multi-root workspace a shared package can pull
+      // react/react-dom (or preact, or svelte) from a SIBLING app's node_modules, so the dev server
+      // loads two cores → a second hook dispatcher/options global → `resolveDispatcher().useState` null
+      // on any hook-using route (the error points at the component, not the resolution - brutal to
+      // diagnose). Same policy table the production builds read, so dev matches prod. No-op per
+      // framework the app does not use (the package simply isn't present to dedupe).
+      dedupe: [...viteDedupePackages()],
     },
     ssr: {
       // Explicit listing forces external even for workspace-LINKED packages (Vite's default keeps
@@ -474,12 +512,36 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   setSsrModuleLoader(ssrLoad)
   app = await options.createApp(entryUrl, ssrLoad)
 
+  // Evict a changed file from the SSR graph together with every module that (transitively) imports it,
+  // BEFORE re-creating the app. Vite re-evaluates a directly-changed module on its own, but a parent
+  // that merely imports the changed leaf keeps its cached SSR bindings - so the re-imported entry walks
+  // a graph that is fresh at the leaf and stale everywhere above it. That is what surfaces downstream as
+  // phantom hydration mismatches (SSR renders through an old module, the client through the new one) and
+  // stale i18n catalogs. Invalidating the importer closure makes the next `ssrLoadModule(entry)` re-walk
+  // the whole affected subtree. `importers` is the client+SSR union, so this over-invalidates slightly;
+  // in a dev server that only costs a re-evaluation, never correctness.
+  const invalidateImporterClosure = (path: string): void => {
+    const graph = vite.moduleGraph
+    if (graph === undefined) return
+    const roots = graph.getModulesByFile(path)
+    if (roots === undefined) return
+    const seen = new Set<ViteModuleNode>()
+    const stack = [...roots]
+    for (let mod = stack.pop(); mod !== undefined; mod = stack.pop()) {
+      if (seen.has(mod)) continue
+      seen.add(mod)
+      graph.invalidateModule(mod)
+      for (const importer of mod.importers) stack.push(importer)
+    }
+  }
+
   // Re-create the app on change so a hard reload picks up a route ADD/REMOVE (the manifest comes
-  // from a directory scan, which `ssrLoadModule` cannot invalidate). Module CONTENT no longer needs a
-  // version counter: Vite owns SSR resolution now and re-evaluates changed modules itself, which is
-  // the cache-busting the old `importQuery` was emulating against Bun's import cache.
+  // from a directory scan, which `ssrLoadModule` cannot invalidate). Module CONTENT is re-evaluated by
+  // Vite plus the importer-closure invalidation above; no version counter against Bun's import cache is
+  // needed anymore, the way the old `importQuery` cache-buster was.
   let refreshVersion = 0
-  const refreshApp = (): void => {
+  const refreshApp = (path?: string): void => {
+    if (path !== undefined) invalidateImporterClosure(path)
     const version = ++refreshVersion
     Promise.resolve(options.createApp(entryUrl, ssrLoad))
       .then((next) => {
@@ -491,7 +553,7 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   for (const event of ["add", "unlink"] as const) {
     vite.watcher.on(event, (path) => {
       if (path.startsWith(`${routesDir}/`) || path.startsWith(`${routesDir}\\`)) writeClientEntry()
-      refreshApp()
+      refreshApp(path)
     })
   }