@nifrajs/web 2.0.0 → 2.2.0

package/src/router.ts

@@ -39,6 +39,72 @@ export const REDIRECT_HEADER = "x-nifra-redirect"
  */
 export const REVALIDATE_HEADER = "x-nifra-revalidate"
 
+/**
+ * Response header carrying a **terminal status** a loader signalled with `notFound()` / `gone()` /
+ * `statusPage(n)` during a client-side navigation's data fetch.
+ *
+ * A soft-nav fetches data, not a document, so the server cannot answer by rendering the `_404` page -
+ * it has only JSON to return. Without this channel the two halves disagree: a crawler doing a hard
+ * navigation gets a correct 404 page while a user who clicked a link gets an error or a blank screen.
+ * The client reads it and renders the same boundary the server would have.
+ *
+ * Carried in a header rather than the body so it survives the NDJSON deferred-data path unchanged,
+ * exactly like {@link REDIRECT_HEADER}.
+ */
+export const STATUS_HEADER = "x-nifra-status"
+
+/**
+ * Layout indices a client navigation is asking the server NOT to re-run, comma separated.
+ *
+ * The client owns the decision because it holds both the old and new match plus each layout's scoped
+ * params. The server treats it as a hint and refuses to skip a `gate` regardless - a guard that runs
+ * only when the client says so is not a guard.
+ */
+export const RETAIN_HEADER = "x-nifra-retain"
+
+/**
+ * The path a client navigation is coming FROM, sent on the data-mode GET.
+ *
+ * Lets the SERVER decide which layout loaders to skip: it already knows each layout's scoped params
+ * (derived at build time), so given both paths it can tell whether a layout's own prefix changed.
+ * Doing it server-side means the client never needs the scope table, and the decision lives next to
+ * the data it is about.
+ *
+ * Sent only when the client actually holds layout data to retain, so a request without it is simply
+ * the full-chain case.
+ */
+export const NAV_FROM_HEADER = "x-nifra-from"
+
+/**
+ * The data-mode payload once a chain can carry layout data.
+ *
+ * Versioned because a prerendered `_data.json` is a static file on a CDN and outlives the deploy that
+ * wrote it: a browser running new client code can be handed an envelope written by the previous
+ * build. The reader therefore accepts BOTH the bare pre-envelope value and this shape, and decides by
+ * structure rather than by assuming the deploy was atomic.
+ */
+export interface RouteDataEnvelope {
+  readonly v: 1
+  readonly data: unknown
+  readonly layoutData?: readonly unknown[]
+  /** 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[]
+  /** 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
+}
+
+/** Recognise the envelope without mistaking a plain loader object that happens to have a `data` key. */
+export function isRouteDataEnvelope(value: unknown): value is RouteDataEnvelope {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { v?: unknown }).v === 1 &&
+    "data" in value
+  )
+}
+
 /** A URL matched against the manifest patterns: which route + its extracted params. */
 export interface RouteMatch {
   readonly routeId: string
@@ -60,6 +126,9 @@ export interface RouterState {
   /** The current URL path (used to revalidate the active loader after an action). */
   readonly path: string
   readonly data: unknown
+  /** 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
   /** 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). */
@@ -110,6 +179,10 @@ export type FetchRouteData = (
   path: string,
   match: RouteMatch,
   signal?: AbortSignal,
+  navigation?: {
+    readonly from: string
+    readonly retain: readonly number[]
+  },
 ) => Promise<unknown>
 
 /** Per-submit options. `revalidate: false` opts out of the post-action loader re-fetch. */
@@ -209,6 +282,9 @@ export interface ClientRouterOptions {
   /** Ensure a route's code chunk is loaded before rendering (code-splitting). Awaited in parallel
    * with the loader data, so `pending` covers both. Omit when the bundle isn't split. */
   readonly loadModule?: (routeId: string) => Promise<void>
+  /** Terminal status → client route id. Generated entries populate this from `_404` and
+   * `_<status>` files so soft navigation renders the same boundary as a hard request. */
+  readonly statusRoutes?: Readonly<Record<number, string>>
 }
 
 /** Options for a per-adapter `mountRouter` (the Router binding that hydrates + re-renders). */
@@ -233,7 +309,7 @@ const readResponseData = (res: Response, signal?: AbortSignal): Promise<unknown>
 const dataUrlFor = (pathname: string): string =>
   pathname === "/" ? "/_data.json" : `${pathname.replace(/\/+$/, "")}/_data.json`
 
-const defaultFetchData: FetchRouteData = async (path, _match, signal) => {
+const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation) => {
   // SSG fast path: if this path was prerendered, its loader data is a static file — fetch that (no
   // worker). Falls through to the dynamic header-GET on any miss (file absent, e.g. a deferred route,
   // or a stale set), so it's always safe. Non-SSG apps have no global → the dynamic path, unchanged.
@@ -245,7 +321,16 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal) => {
       if (staticRes.ok) return readResponseData(staticRes, signal)
     }
   }
-  const res = await fetch(path, { headers: { [DATA_HEADER]: "1" }, signal: signal ?? null })
+  const headers = new Headers({ [DATA_HEADER]: "1" })
+  if (navigation !== undefined && navigation.retain.length > 0) {
+    headers.set(RETAIN_HEADER, navigation.retain.join(","))
+    headers.set(NAV_FROM_HEADER, navigation.from)
+  }
+  const res = await fetch(path, { headers, signal: signal ?? null })
+  const status = Number(res.headers.get(STATUS_HEADER))
+  if (Number.isInteger(status) && status >= 400 && status <= 599) {
+    return { v: 1, data: null, status } satisfies RouteDataEnvelope
+  }
   if (!res.ok) throw new Error(`[nifra/web] navigation data fetch failed (${res.status}): ${path}`)
   return readResponseData(res, signal)
 }
@@ -258,6 +343,55 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal) => {
 export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   const match = createMatcher(options.patterns)
   const fetchData = options.fetchData ?? defaultFetchData
+  /**
+   * Fetch a route's data and normalise it.
+   *
+   * The payload is either the versioned envelope (a chain with layout loaders) or the bare loader
+   * value (everything else, and every response written before layout loaders existed). Deciding by
+   * structure rather than by version-of-the-deploy is what lets a prerendered `_data.json` written by
+   * an older build be read by newer client code.
+   */
+  type LoadedRouteData = {
+    readonly data: unknown
+    readonly layoutData?: readonly unknown[] | undefined
+    readonly terminalRouteId?: string | undefined
+  }
+  const loadRouteData = async (
+    path: string,
+    match: { routeId: string; params: Record<string, string> },
+    signal?: AbortSignal,
+    retainFrom?: { readonly path: string; readonly layoutData: readonly unknown[] },
+  ): Promise<LoadedRouteData> => {
+    const retain = retainFrom?.layoutData.map((_, index) => index) ?? []
+    const payload = await fetchData(
+      path,
+      match,
+      signal,
+      retainFrom === undefined ? undefined : { from: retainFrom.path, retain },
+    )
+    if (!isRouteDataEnvelope(payload)) return { data: payload }
+    if (payload.status !== undefined) {
+      const terminalRouteId = options.statusRoutes?.[payload.status] ?? options.statusRoutes?.[404]
+      if (terminalRouteId === undefined) {
+        throw new Error(
+          `[nifra/web] no client status boundary is available for terminal status ${payload.status}`,
+        )
+      }
+      return { data: null, terminalRouteId }
+    }
+    if (retainFrom === undefined || payload.retained === undefined) {
+      return { data: payload.data, layoutData: payload.layoutData }
+    }
+    const retained = new Set(
+      payload.retained.filter(
+        (index) => Number.isInteger(index) && index >= 0 && index < retainFrom.layoutData.length,
+      ),
+    )
+    const layoutData = payload.layoutData?.map((value, index) =>
+      retained.has(index) ? retainFrom.layoutData[index] : value,
+    )
+    return { data: payload.data, layoutData }
+  }
   const loadModule = options.loadModule
   let state = options.initial
   const listeners = new Set<() => void>()
@@ -272,7 +406,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // Bounded one-shot prefetch cache (path → loader data) + an in-flight guard so hover spam
   // doesn't double-fetch. Consumed (and dropped) by the next navigate to that path.
   const MAX_PREFETCH = 10
-  const prefetched = new Map<string, unknown>()
+  const prefetched = new Map<string, LoadedRouteData>()
   const inflight = new Set<string>()
   // Keyed data cache (path → latest loader data + freshness). Written on every published data
   // (navigate/submit), read by `invalidate` (+ targeted revalidation and fetchers in later F16
@@ -280,13 +414,18 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // caps memory). `status` is the staleness ledger: `invalidate` flips entries to `stale`; readers
   // refetch stale ones. Client-only — never serialized/hydrated.
   const MAX_CACHE = 50
-  const cache = new Map<string, { data: unknown; status: "fresh" | "stale" }>()
-  const cachePut = (path: string, data: unknown): void => {
+  const cache = new Map<
+    string,
+    { data: unknown; layoutData?: readonly unknown[] | undefined; status: "fresh" | "stale" }
+  >()
+  const cachePut = (path: string, loaded: LoadedRouteData): void => {
     if (!cache.has(path) && cache.size >= MAX_CACHE) {
       const oldest = cache.keys().next().value
       if (oldest !== undefined) cache.delete(oldest)
     }
-    cache.set(path, { data, status: "fresh" })
+    // 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" })
   }
   // 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`.
@@ -320,14 +459,14 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     state = { ...state, pending: true }
     emit()
     try {
-      const data = await fetchData(
+      const loaded = await loadRouteData(
         state.path,
         { routeId: state.routeId, params: state.params },
         ac.signal,
       )
       if (mine !== token) return // superseded — drop the stale result
-      cachePut(state.path, data)
-      state = { ...state, data, pending: false }
+      cachePut(state.path, loaded)
+      state = { ...state, data: loaded.data, layoutData: loaded.layoutData, pending: false }
       emit()
     } catch (err) {
       if (mine === token) {
@@ -387,17 +526,17 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       fState = { ...fState, pending: true }
       fEmit()
       try {
-        const [, data] = await Promise.all([
+        const [, loaded] = await Promise.all([
           loadModule?.(matched.routeId),
-          fetchData(path, matched, ac.signal),
+          loadRouteData(path, matched, ac.signal),
         ])
         if (mine !== fToken) return // a newer load/submit on THIS fetcher superseded us
         // Record the loaded path only on SUCCESS — a thrown or superseded load must not
         // leave `loadedPath` pointing at a path this fetcher never actually showed, or a later
         // `X-Nifra-Revalidate` for it would spuriously refetch onto unexpected data.
         loadedPath = path
-        cachePut(path, data)
-        fState = { ...fState, data, pending: false }
+        cachePut(path, loaded)
+        fState = { ...fState, data: loaded.data, pending: false }
         fEmit()
       } catch (err) {
         if (mine === fToken) {
@@ -490,17 +629,26 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         // either way (cached + instant after a prefetch), so pending covers both.
         const hit = prefetched.has(path)
         const dataPromise = hit
-          ? Promise.resolve(prefetched.get(path))
-          : fetchData(path, matched, ac.signal)
+          ? Promise.resolve(prefetched.get(path) as LoadedRouteData)
+          : loadRouteData(
+              path,
+              matched,
+              ac.signal,
+              state.layoutData === undefined
+                ? undefined
+                : { path: state.path, layoutData: state.layoutData },
+            )
         if (hit) prefetched.delete(path)
-        const [, data] = await Promise.all([loadModule?.(matched.routeId), dataPromise])
+        const [, loaded] = await Promise.all([loadModule?.(matched.routeId), dataPromise])
+        if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
         if (mine !== token) return // a newer navigation superseded this one — drop the stale result
-        cachePut(path, data) // keep the keyed cache coherent with what we publish
+        cachePut(path, loaded) // keep the keyed cache coherent with what we publish
         state = {
-          routeId: matched.routeId,
-          params: matched.params,
+          routeId: loaded.terminalRouteId ?? matched.routeId,
+          params: loaded.terminalRouteId === undefined ? matched.params : {},
           path,
-          data,
+          data: loaded.data,
+          layoutData: loaded.layoutData,
           actionData: undefined, // a fresh navigation has no action result
           pending: false,
         }
@@ -540,17 +688,26 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           const target = match(redirectTo)
           if (target === null)
             throw new Error(`[nifra/web] action redirect off-route: ${redirectTo}`)
-          const [, data] = await Promise.all([
+          const [, loaded] = await Promise.all([
             loadModule?.(target.routeId),
-            fetchData(redirectTo, target, ac.signal),
+            loadRouteData(
+              redirectTo,
+              target,
+              ac.signal,
+              state.layoutData === undefined
+                ? undefined
+                : { path: state.path, layoutData: state.layoutData },
+            ),
           ])
+          if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
           if (mine !== token) return
-          cachePut(redirectTo, data)
+          cachePut(redirectTo, loaded)
           state = {
-            routeId: target.routeId,
-            params: target.params,
+            routeId: loaded.terminalRouteId ?? target.routeId,
+            params: loaded.terminalRouteId === undefined ? target.params : {},
             path: redirectTo,
-            data,
+            data: loaded.data,
+            layoutData: loaded.layoutData,
             actionData: undefined,
             pending: false,
           }
@@ -568,11 +725,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 data = skipActive
-          ? state.data
-          : await fetchData(state.path, { routeId: state.routeId, params: state.params }, ac.signal)
+        const loaded = skipActive
+          ? { data: state.data, layoutData: state.layoutData }
+          : await loadRouteData(
+              state.path,
+              { routeId: state.routeId, params: state.params },
+              ac.signal,
+            )
         if (mine !== token) return
-        cachePut(state.path, data) // the revalidated (or kept) data is now the cache's truth
+        cachePut(state.path, loaded) // the revalidated (or kept) data is now the cache's truth
         // Mark the OTHER changed routes stale so the next access refetches.
         markStale(changed.filter((p) => p !== state.path))
         // Reconcile: publish the revalidated data + actionData; omit `submission` (the optimistic
@@ -581,7 +742,8 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           routeId: state.routeId,
           params: state.params,
           path: state.path,
-          data,
+          data: loaded.data,
+          layoutData: loaded.layoutData,
           actionData,
           pending: false,
         }
@@ -625,15 +787,17 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       if (matched === null) return
       inflight.add(path)
       try {
-        const [, data] = await Promise.all([
+        // Unwrapped here, so a prefetched entry is the same shape `navigate` builds state from —
+        // otherwise a prefetch hit would publish an envelope where a miss publishes loader data.
+        const [, loaded] = await Promise.all([
           loadModule?.(matched.routeId),
-          fetchData(path, matched),
+          loadRouteData(path, matched),
         ])
         if (prefetched.size >= MAX_PREFETCH) {
           const oldest = prefetched.keys().next().value
           if (oldest !== undefined) prefetched.delete(oldest)
         }
-        prefetched.set(path, data)
+        prefetched.set(path, loaded)
       } catch {
         // Best-effort: a failed prefetch just means the eventual navigate fetches normally.
       } finally {

package/src/vite.ts

@@ -18,6 +18,7 @@ import {
 } from "node:http"
 import { relative, resolve as resolvePath } from "node:path"
 import { renderDevErrorOverlay } from "./dev-error.ts"
+import { listenOrExplain } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
 
@@ -28,10 +29,14 @@ interface FetchApp {
 
 // 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. */
+  ssrLoadModule(url: string): Promise<Record<string, unknown>>
   readonly middlewares: (req: IncomingMessage, res: ServerResponse, next: () => void) => void
   transformIndexHtml(url: string, html: string): Promise<string>
   ssrFixStacktrace(err: Error): void
-  readonly watcher: { on(event: "change", cb: (path: string) => void): void }
+  readonly watcher: {
+    on(event: "change" | "add" | "unlink", cb: (path: string) => void): void
+  }
   close(): Promise<void>
 }
 interface ViteModule {
@@ -49,11 +54,18 @@ export interface ViteDevServerOptions {
   /** Client runtime module providing `mountRouter` (e.g. `"@nifrajs/web-react/client"`). */
   readonly clientModule: string
   /**
-   * Build the nifra app for the given dev client-entry URL. `importQuery` changes when a route file
-   * changes — thread it into `discoverRoutes(routesDir, { importQuery })` so a hard reload SSRs edited
-   * modules (HMR handles the live client update; this keeps server-render fresh).
+   * Build the nifra app for the given dev client-entry URL.
+   *
+   * `load` resolves a route module through **Vite's** graph (`ssrLoadModule`). Pass it to
+   * `discoverRoutes(routesDir, { load })` so SSR and the client are resolved by the SAME toolchain.
+   * Without it SSR resolves through Bun while the client resolves through Vite - two resolvers, one
+   * process - which is what makes `resolve.dedupe` fail to reach SSR and produces the dual-React
+   * crash. Vite re-evaluates on change, so no `importQuery` cache-buster is needed alongside it.
    */
-  readonly createApp: (clientEntry: string, importQuery: string) => FetchApp | Promise<FetchApp>
+  readonly createApp: (
+    clientEntry: string,
+    load: (absolutePath: string) => Promise<unknown>,
+  ) => FetchApp | Promise<FetchApp>
   /** Vite plugins — inject your framework's official plugin, e.g. `[react()]`. */
   readonly plugins?: readonly unknown[]
   /**
@@ -76,6 +88,8 @@ export interface ViteDevServerOptions {
    * `true` (or the env var `CHOKIDAR_USEPOLLING=1`) to poll instead. Default: off (native events).
    */
   readonly poll?: boolean
+  /** Vite public directory. Defaults to `<root>/public`; `false` disables it. */
+  readonly publicDir?: string | false
 }
 
 export interface ViteDevServer {
@@ -259,12 +273,15 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   const port = options.port ?? DEFAULT_DEV_PORT
 
   // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
-  const manifest = discoverRoutes(routesDir)
   const toUrl = (file: string): string => `/${relative(root, `${routesDir}/${file}`)}`
-  writeFileSync(
-    resolvePath(root, DEV_ENTRY),
-    generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
-  )
+  const writeClientEntry = (): void => {
+    const manifest = discoverRoutes(routesDir)
+    writeFileSync(
+      resolvePath(root, DEV_ENTRY),
+      generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
+    )
+  }
+  writeClientEntry()
   const entryUrl = `/${DEV_ENTRY}`
 
   // Create our HTTP server FIRST, then hand it to Vite as the HMR WebSocket host (`hmr.server`). In
@@ -273,7 +290,6 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   // port means HMR rides the same origin as the app, robust across restarts. The handler closes over
   // `vite`, which is assigned just below before the server starts listening.
   let vite!: ViteLike
-  let version = 0
   let app: FetchApp
 
   const server: NodeHttpServer = createHttpServer((req, res) => {
@@ -321,6 +337,7 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   )
   vite = await createServer({
     root,
+    ...(options.publicDir !== undefined ? { publicDir: options.publicDir } : {}),
     appType: "custom",
     server: {
       middlewareMode: true,
@@ -341,21 +358,46 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     ...(options.define ? { define: options.define } : {}),
   })
 
-  app = await options.createApp(entryUrl, `v=${version}`)
+  const ssrLoad = (absolutePath: string): Promise<unknown> => vite.ssrLoadModule(absolutePath)
+  app = await options.createApp(entryUrl, ssrLoad)
 
-  // Keep server-render fresh on edits (Vite already HMRs the client live; this is for a hard reload).
-  vite.watcher.on("change", () => {
-    version += 1
-    Promise.resolve(options.createApp(entryUrl, `v=${version}`))
+  // 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.
+  let refreshVersion = 0
+  const refreshApp = (): void => {
+    const version = ++refreshVersion
+    Promise.resolve(options.createApp(entryUrl, ssrLoad))
       .then((next) => {
-        app = next
+        if (version === refreshVersion) app = next
       })
       .catch((err) => console.error("[nifra/web/vite] app re-create failed:", err))
-  })
+  }
+  vite.watcher.on("change", refreshApp)
+  for (const event of ["add", "unlink"] as const) {
+    vite.watcher.on(event, (path) => {
+      if (path.startsWith(`${routesDir}/`) || path.startsWith(`${routesDir}\\`)) writeClientEntry()
+      refreshApp()
+    })
+  }
 
-  await new Promise<void>((done) => server.listen(port, done))
+  try {
+    await listenOrExplain(server, port)
+  } catch (err) {
+    // Nothing is listening, but Vite is fully up by now - watchers, the dep optimizer, its own sockets -
+    // and every one of those keeps the event loop alive. Left open, the process prints the diagnosis and
+    // then HANGS on it, which is worse than the raw crash this guard replaced: the user sees a dev server
+    // that appears to be starting. Tear Vite down so the failure is terminal.
+    await vite.close().catch(() => {})
+    throw err
+  }
+  // Report the port actually BOUND, not the one requested. They differ for `port: 0`, which is how you
+  // ask the OS for a free one - the correct thing to do in a test or when running several apps at once.
+  // Echoing the request back would return a literal 0, which connects to nothing.
+  const address = server.address()
   return {
-    port,
+    port: typeof address === "object" && address !== null ? address.port : port,
     stop: async () => {
       server.close()
       await vite.close()