@nifrajs/web 5.5.0 → 5.6.0

package/src/client.ts

@@ -35,6 +35,7 @@ export function currentDocumentNonce(): string | undefined {
   return script.getAttribute("nonce") ?? undefined
 }
 
+export { identityChanged } from "./identity.ts"
 /**
  * Everything the generated client entry needs, re-exported here so that entry imports ONE module and
  * that module is DOM-only. It used to take these from `@nifrajs/web`, whose graph includes `renderPage`
@@ -44,6 +45,7 @@ export function currentDocumentNonce(): string | undefined {
  */
 export { mergeHeads, resolveChainMeta, resolveMeta } from "./internal/head-merge.ts"
 export {
+  closeBoundary,
   getBrowserNavigate,
   IDLE_BLOCKER,
   registerBlocker,
@@ -255,6 +257,48 @@ export function installHistory(
   let reversing = false
   // The path the router was last seen loading, so a redirect it follows shows up as a change.
   let expected: string | undefined
+  // The entry holding the page last shown without an intercept boundary, so closing a boundary opened
+  // over it can go back there. Cleared once that entry is replaced or cut off by a push.
+  let pageEntry: number | undefined = index
+  // Before writing the entry at `index` (replace) or pushing past it, which drops every later entry.
+  const writingEntry = (mode: "push" | "replace"): void => {
+    if (mode === "replace" ? pageEntry === index : pageEntry !== undefined && pageEntry > index)
+      pageEntry = undefined
+  }
+  // Every entry this document owns carries its index, the first one included, so an entry without one
+  // is one the browser pushed itself: a same-page fragment link, which this router leaves native.
+  // Number it as the push it was, or index deltas (a guard's reversal, closeBoundary) count wrong.
+  const numbered = (): boolean => {
+    const current: unknown = history.state
+    return (
+      typeof current === "object" &&
+      current !== null &&
+      "nifraIndex" in current &&
+      typeof current.nifraIndex === "number"
+    )
+  }
+  const stampEntry = (): void => {
+    const current: unknown = history.state
+    history.replaceState(
+      Object.assign({}, typeof current === "object" ? current : null, { nifraIndex: index }),
+      "",
+    )
+  }
+  const adoptNativeEntry = (): boolean => {
+    if (numbered()) return false
+    writingEntry("push")
+    index += 1
+    stampEntry()
+    here = location.pathname + location.search + (location.hash ?? "")
+    return true
+  }
+  // An opaque or file: document routes nothing, so its history is left alone. A refused write (a
+  // browser's rate limit) only leaves fragment entries uncounted, as before.
+  if (location.origin !== "null" && location.protocol !== "file:" && !numbered()) {
+    try {
+      stampEntry()
+    } catch {}
+  }
   type Registration = {
     readonly shouldBlock: BlockerFunction
     readonly emit: (blocker: Blocker) => void
@@ -292,6 +336,23 @@ export function installHistory(
   type ViewTransitionDocument = Document & {
     startViewTransition?: (cb: () => unknown) => ViewTransition
   }
+  // A navigation that loads takes the page from a partially prerendered first document, which then
+  // stops filling its holes and cancels the ones still loading on the server. `navigate` publishes
+  // its `pendingPath` before its first await; a client-only search change, or a boundary already
+  // showing its target, loads nothing, so the holes still pending keep filling.
+  const navigateFrom = (routePath: string, from: string): Promise<void> => {
+    const run = router.navigate(routePath).catch((error) => leave(error, from))
+    const ppr: unknown = Reflect.get(globalThis, "__nifraPpr")
+    if (
+      router.snapshot().pendingPath === routePath &&
+      typeof ppr === "function" &&
+      "leave" in ppr &&
+      typeof ppr.leave === "function"
+    )
+      ppr.leave()
+    return run
+  }
+
   const transition = (run: () => Promise<void>): void => {
     const doc = document as ViewTransitionDocument
     if (typeof doc.startViewTransition !== "function") {
@@ -364,6 +425,7 @@ export function installHistory(
     // whole object on back/forward for free.
     const entryState =
       state !== undefined ? { nifraIndex: index, nifraState: state } : { nifraIndex: index }
+    writingEntry(mode)
     if (mode === "replace") {
       // Replace the current entry (same index) with the new URL. The entry we're leaving is discarded, so
       // its scroll isn't worth saving; the new route scrolls to its fragment target, else the top.
@@ -381,7 +443,7 @@ export function installHistory(
     here = url.pathname + url.search + url.hash
     expected = routePath
     // The data layer fetches by path+search; the #hash is client-only (never sent to the server).
-    transition(() => router.navigate(routePath).catch((error) => leave(error, path)))
+    transition(() => navigateFrom(routePath, path))
     settle()
   }
 
@@ -417,7 +479,15 @@ export function installHistory(
     }
     go(to, navOptions?.replace === true ? "replace" : "push", navOptions?.state)
   }
-  setBrowserNavigate(navigate, router)
+  // Back through the entries the boundary added to the page underneath; without that entry, replace
+  // the boundary's URL with the page's.
+  const closeBoundary = (name: string): void => {
+    const intercepted = router.snapshot().intercepted
+    if (intercepted === undefined || intercepted.boundary !== name) return
+    if (pageEntry !== undefined && pageEntry < index) history.go(pageEntry - index)
+    else go(intercepted.pagePath, "replace")
+  }
+  setBrowserNavigate(navigate, router, closeBoundary)
 
   // Publish the guard registry through the DOM-free bridge (`@nifrajs/web`'s `registerBlocker`, which an
   // adapter's `useBlocker` calls). One slot, latest registration wins; the unregister clears it only if
@@ -515,10 +585,12 @@ export function installHistory(
       reversing = false
       return
     }
+    adoptNativeEntry()
     const newIndex = (history.state as { nifraIndex?: number } | null)?.nifraIndex ?? 0
     const dest = location.pathname + location.search + (location.hash ?? "")
     const delta = newIndex - index
-    if (guard(dest, () => history.go(delta))) {
+    // A fragment entry the browser just pushed is not a move between entries to reverse.
+    if (delta !== 0 && guard(dest, () => history.go(delta))) {
       reversing = true
       history.go(-delta)
       return
@@ -528,7 +600,7 @@ export function installHistory(
     pendingScroll = { pos: scrollOf(history.state) }
     const routePath = location.pathname + location.search
     expected = routePath
-    transition(() => router.navigate(routePath).catch((error) => leave(error, dest)))
+    transition(() => navigateFrom(routePath, dest))
     settle()
   }
 
@@ -555,6 +627,7 @@ export function installHistory(
   // form post back to the page it was on adds nothing.
   const follow = (path: string): void => {
     if (path !== location.pathname + location.search) {
+      writingEntry(expected === undefined ? "push" : "replace")
       if (expected === undefined) {
         history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
         index += 1
@@ -573,13 +646,15 @@ export function installHistory(
   // A settle with no navigation (a submit's revalidation) scrolls nothing. Either way the rendered
   // page is then scanned for links to warm.
   const settled = (): void => {
-    const { pending, pendingPath } = router.snapshot()
+    const { pending, pendingPath, intercepted } = router.snapshot()
     if (pending) {
       if (pendingPath !== undefined && pendingPath !== expected) follow(pendingPath)
       return
     }
     expected = undefined
-    const target = pendingScroll
+    if (intercepted === undefined) pageEntry = index
+    // A boundary opened over the page leaves the page where it was scrolled.
+    const target = intercepted === undefined ? pendingScroll : null
     pendingScroll = null
     requestAnimationFrame(() => {
       if (target !== null && "hash" in target) {
@@ -599,6 +674,8 @@ export function installHistory(
   document.addEventListener("pointerover", onPrefetch)
   document.addEventListener("focusin", onPrefetch)
   window.addEventListener("popstate", onPopState)
+  // Where a fragment link fires no popstate, its entry is still numbered here.
+  window.addEventListener("hashchange", adoptNativeEntry)
   window.addEventListener("beforeunload", onBeforeUnload)
   return () => {
     unsubscribe()
@@ -609,6 +686,7 @@ export function installHistory(
     document.removeEventListener("pointerover", onPrefetch)
     document.removeEventListener("focusin", onPrefetch)
     window.removeEventListener("popstate", onPopState)
+    window.removeEventListener("hashchange", adoptNativeEntry)
     window.removeEventListener("beforeunload", onBeforeUnload)
   }
 }
@@ -693,6 +771,47 @@ export function applyHead(head: Meta, path?: string): void {
   }
 }
 
+/**
+ * The route path a form with no action posts to while an intercept boundary holds a target. The
+ * document URL is then the target's, but the form belongs to whichever route rendered it: the target
+ * when it sits inside the boundary's `data-nifra-boundary="<name>"` element, otherwise the page
+ * underneath. `undefined` when the form names its action, or no boundary holds a target.
+ */
+function implicitActionOwner(
+  router: ClientRouter,
+  form: HTMLFormElement,
+  actionFrom: Element,
+): string | undefined {
+  const { intercepted, path } = router.snapshot()
+  if (intercepted === undefined) return undefined
+  const named = Element.prototype.getAttribute.call(actionFrom, actionAttribute(actionFrom, form))
+  if (named !== null && named.trim() !== "") return undefined
+  // Any ancestor marking the open boundary owns it, so a marker nested inside the modal (another
+  // boundary's) does not hand the form to the page. Boundary names are validated identifiers; the
+  // check keeps the selector literal regardless.
+  const inside =
+    BOUNDARY_NAME.test(intercepted.boundary) &&
+    Element.prototype.closest.call(form, `[data-nifra-boundary="${intercepted.boundary}"]`) !== null
+  return inside ? path : intercepted.pagePath
+}
+
+const BOUNDARY_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/
+
+const actionAttribute = (actionFrom: Element, form: HTMLFormElement): string =>
+  actionFrom === form ? "action" : "formaction"
+
+// Point the implicit action at `href` for one native submission; the returned function puts the
+// attribute back, so a form that outlives the boundary (one in a layout) keeps posting to its page.
+function pointAction(actionFrom: Element, form: HTMLFormElement, href: string): () => void {
+  const name = actionAttribute(actionFrom, form)
+  const previous = Element.prototype.getAttribute.call(actionFrom, name)
+  Element.prototype.setAttribute.call(actionFrom, name, href)
+  return () => {
+    if (previous === null) Element.prototype.removeAttribute.call(actionFrom, name)
+    else Element.prototype.setAttribute.call(actionFrom, name, previous)
+  }
+}
+
 // A control named like a form property shadows it (`<input name="target">` makes `form.target` that
 // input), so the form's own state is read through the prototype accessors.
 function formProperty(form: HTMLFormElement, name: "action" | "method" | "target"): string {
@@ -720,14 +839,26 @@ export function installForms(router: ClientRouter): () => void {
     const method = submitter?.hasAttribute("formmethod")
       ? submitter.formMethod
       : formProperty(form, "method")
-    if (method.toLowerCase() !== "post") return // GET forms submit natively
+    const actionFrom = submitter?.hasAttribute("formaction") ? submitter : form
+    const owner = implicitActionOwner(router, form, actionFrom)
+    if (method.toLowerCase() !== "post") {
+      // GET forms submit natively. The browser reads the action after this event, so one the page
+      // rendered under a boundary is pointed at the page for this submission, then restored.
+      if (owner !== undefined)
+        setTimeout(pointAction(actionFrom, form, new URL(appUrl(owner), location.href).href), 0)
+      return
+    }
     const target = submitter?.hasAttribute("formtarget")
       ? submitter.formTarget
       : formProperty(form, "target")
     if (target !== "" && target !== "_self") return // it loads in another browsing context
     // Resolved (or the current document URL if unset).
     const url = sameDocumentUrl(
-      submitter?.hasAttribute("formaction") ? submitter.formAction : formProperty(form, "action"),
+      owner !== undefined
+        ? appUrl(owner)
+        : actionFrom === submitter
+          ? submitter.formAction
+          : formProperty(form, "action"),
     )
     if (url === null) return
     if (router.match(url.pathname) === null) return // not an app route → native submit
@@ -742,9 +873,15 @@ export function installForms(router: ClientRouter): () => void {
       // The server answered: load the page that shows the result rather than run the action again.
       if (to !== undefined) location.assign(to)
       else {
-        // Nothing reached the server - post natively, through the same button.
+        // Nothing reached the server - post natively, through the same button, to the same route.
         native.add(form)
-        HTMLFormElement.prototype.requestSubmit.call(form, submitter)
+        // requestSubmit reads the action synchronously, so the attribute is restored right after.
+        const restore = owner === undefined ? undefined : pointAction(actionFrom, form, url.href)
+        try {
+          HTMLFormElement.prototype.requestSubmit.call(form, submitter)
+        } finally {
+          restore?.()
+        }
       }
     })
   }

package/src/csp.ts

@@ -109,8 +109,9 @@ const inlineScriptBodies = (html: string): string[] => {
 
 const ENCODER = new TextEncoder()
 
-/** A CSP hash source for one inline script body: `'sha256-<base64 of the UTF-8 bytes>'`. */
-async function hashSource(body: string): Promise<string> {
+/** A CSP hash source for one inline script body: `'sha256-<base64 of the UTF-8 bytes>'`. Shared with
+ * the PPR runtime; `index.ts` does not re-export it. */
+export async function hashSource(body: string): Promise<string> {
   const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", ENCODER.encode(body)))
   let binary = ""
   for (const byte of digest) binary += String.fromCharCode(byte)
@@ -158,6 +159,19 @@ const preparedSources = (policy: CspPolicy, adapter: RenderAdapter): AdapterSour
   return known
 }
 
+/**
+ * The policy value for a partially prerendered document: the adapter's hash sources plus `extra`
+ * (the PPR runtime and invoker hashes), with no nonce. Prepare the policy for `adapter` first.
+ */
+export function cspHeaderWithSources(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+  extra: string,
+): string | undefined {
+  const { sources } = preparedSources(policy, adapter)
+  return policy[CSP_POLICY].header({ sources: sources === "" ? extra : `${sources} ${extra}` })
+}
+
 /**
  * The nonce one document carries under `policy`: `undefined` unless the document needs one -
  * `needsNonce` (a deferred value or a head tag naming the nonce), or an adapter whose hydration head

package/src/deferred.ts

@@ -7,6 +7,7 @@
  */
 import { plainJsonCodec, type TransportCodec } from "@nifrajs/core/transport-codec"
 import { isDeferredFree } from "./internal/deferred-free.ts"
+import { reportDeferredRejection } from "./internal/request-abort.ts"
 import { parsePageData } from "./internal/revive-dates.ts"
 
 /**
@@ -171,15 +172,19 @@ const NDJSON_ENCODER = new TextEncoder()
  * `{__nifra_deferred: id}` placeholders (`forClient`), then one line per deferred as its promise
  * settles - `{"i": id, "v": value}` on resolve, `{"i": id, "e": "deferred_error"}` on reject (a
  * rejection is data, not a stream error; the opaque code never leaks the raw reason). Closes when all
- * settle. The client (`defaultFetchData`) returns the
+ * settle. The client (`fetchRouteData`) returns the
  * data after line 1 and settles `<Await>`'s markers as the resolution lines arrive. `JSON.stringify`
  * escapes newlines in values, so each line is NDJSON-safe; no HTML escaping (this is a fetch body,
- * parsed with `JSON.parse`, never injected into markup).
+ * parsed with `JSON.parse`, never injected into markup). A rejection is logged to `logError`, the
+ * app's error log (the console without one), unless the request `signal` aborting caused it: that is
+ * the client leaving, not a failure.
  */
 export function ndjsonStream(
   forClient: unknown,
   deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
   codec: TransportCodec = plainJsonCodec,
+  signal?: AbortSignal,
+  logError?: (error: unknown) => void,
 ): ReadableStream<Uint8Array> {
   // A client that goes away cancels the body; a value settling after that has nowhere to go.
   let cancelled = false
@@ -194,7 +199,7 @@ export function ndjsonStream(
           } catch (err) {
             // Redact: stream a stable opaque code, never the raw error text; log the real reason
             // server-side. The client's <Await> errorFallback receives this code.
-            console.error("[nifra/web] deferred value rejected:", err)
+            reportDeferredRejection(signal, err, logError)
             line = codec.encode({ i: d.id, e: DEFERRED_ERROR_CODE })
           }
           if (!cancelled) controller.enqueue(NDJSON_ENCODER.encode(`${line}\n`))
@@ -319,7 +324,7 @@ function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
 }
 
 /**
- * Client side of {@link ndjsonStream} (used by the router's `defaultFetchData` on a soft nav): read
+ * Client side of {@link ndjsonStream} (used by the router's `fetchRouteData` on a soft nav): read
  * the NDJSON body into a data object whose deferred markers settle as resolution lines arrive.
  * Returns after **line 1** so the router can apply the critical data + render immediately; the
  * markers' promises settle/reject in the background. If the stream ends (or `signal` aborts) with
@@ -335,7 +340,8 @@ export async function parseNdjsonData(
   let buffer = ""
   // `{ once: true }` + explicit removal in the drain's `finally` so a reused long-lived signal doesn't
   // accumulate listeners across navigations (a per-nav signal would be GC'd, but don't rely on it).
-  const onAbort = (): void => void reader.cancel()
+  // A body the abort has already errored (WebKit errors it first) rejects the cancel.
+  const onAbort = (): void => void reader.cancel().catch(() => {})
   if (signal) signal.addEventListener("abort", onAbort, { once: true })
   let ended = false
   // Every way out, a malformed line included, detaches from the signal and the body: a source left

package/src/dev-feed.ts

@@ -36,6 +36,7 @@ import {
   buildDiagnostic,
   type Diagnostic,
   type DiagnosticFrame,
+  isConsoleDiagnostic,
 } from "./diagnostic.ts"
 import { createRedactor } from "./internal/secret-scan.ts"
 import { originalPosition, ssrSourceMaps } from "./internal/source-map.ts"
@@ -1140,8 +1141,16 @@ const ssrRemap = (
 export function captureInto(feed: DevFeed): () => void {
   return installCapture({
     feedId: feed.id,
-    line: (level, message, request) =>
-      feed.recordLog(level, message, { requestId: request?.requestId }),
+    line: (level, message, request) => {
+      feed.recordLog(level, message, { requestId: request?.requestId })
+      // A diagnostic the server only logs (no throw reaches the feed) still becomes an entry.
+      if ((level === "warn" || level === "error") && isConsoleDiagnostic(message)) {
+        const warning = new Error(message)
+        warning.name = "Warning"
+        warning.stack = `Warning: ${message}`
+        feed.recordError(warning, { category: "ssr", requestId: request?.requestId })
+      }
+    },
     structured: (entry, request) => {
       const level = isDevLogLevel(entry.level) ? entry.level : "log"
       feed.recordLog(level, structuredText(entry), { requestId: request?.requestId })

package/src/dev-session.ts

@@ -44,7 +44,13 @@ import {
 } from "./dev-feed.ts"
 import { DEV_INDICATOR_MAX_ISSUES, DEV_INDICATOR_SOURCE, type DevIssue } from "./dev-indicator.ts"
 import { createSourceMapper } from "./dev-sourcemap.ts"
-import { fixPrompts, isHydrationMismatch, LAST_ERROR_PATH, promptPath } from "./diagnostic.ts"
+import {
+  fixPrompts,
+  isConsoleDiagnostic,
+  isHydrationMismatch,
+  LAST_ERROR_PATH,
+  promptPath,
+} from "./diagnostic.ts"
 import { diagnosticHeadline } from "./diagnostic-prompt.ts"
 import { timingSafeEqual } from "./internal/timing-safe-equal.ts"
 import { ISR_STATUS_HEADER } from "./isr.ts"
@@ -439,16 +445,21 @@ export function createDevSession(options: DevSessionOptions): DevSession {
     if (event.kind === "console") {
       feed.recordLog(event.level, event.message, meta)
       if (event.error !== undefined) return (await recordBrowserError(event.error, meta)).entry
-      // React 18, Vue and Svelte report a mismatch through the console rather than by throwing.
-      if (
-        (event.level === "error" || event.level === "warn") &&
-        isHydrationMismatch(event.message)
-      ) {
-        const recorded = await recordBrowserError(
-          { name: "HydrationMismatch", message: event.message, stack: "" },
-          meta,
-        )
-        return recorded.entry
+      // React 18, Vue and Svelte report a mismatch through the console rather than by throwing, as
+      // nifra's own browser diagnostics do.
+      if (event.level === "error" || event.level === "warn") {
+        const name = isHydrationMismatch(event.message)
+          ? "HydrationMismatch"
+          : isConsoleDiagnostic(event.message)
+            ? "Warning"
+            : undefined
+        if (name !== undefined) {
+          const recorded = await recordBrowserError(
+            { name, message: event.message, stack: "" },
+            meta,
+          )
+          return recorded.entry
+        }
       }
       return undefined
     }

package/src/dev.ts

@@ -67,8 +67,15 @@ import {
 import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
 import { formatBuildLog } from "./diagnostic.ts"
 import { discoverRoutes } from "./fs.ts"
-import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEFAULT_DEV_PORT, generateClientEntry, type LiveClientEntry } from "./index.ts"
 import { DEV_ENTRY_FILE } from "./internal/dev-reserved.ts"
+import {
+  type BunUpgradeServer,
+  bunDevWebSocket,
+  isWebSocketUpgrade,
+  type UpgradableApp,
+  upgradeOnBun,
+} from "./internal/dev-websocket.ts"
 import { DEV_HMR_ENV, DEV_ROOT_ENV, DEV_ROUTES_ENV } from "./plugins/kit.ts"
 import { servePublicDir } from "./public-dir.ts"
 
@@ -76,7 +83,7 @@ export type { DevAppHooks } from "./dev-session.ts"
 export { LAST_ERROR_PATH } from "./diagnostic.ts"
 
 /** Minimal app surface the dev server needs - `createWebApp(...)` satisfies it. */
-interface FetchApp {
+interface FetchApp extends UpgradableApp {
   fetch(request: Request): Response | Promise<Response>
 }
 
@@ -169,7 +176,8 @@ interface BunServeOptions {
   readonly hostname: "127.0.0.1"
   readonly development: { readonly hmr: boolean }
   readonly routes: Record<string, HtmlBundle>
-  fetch(request: Request): Promise<Response>
+  fetch(request: Request, server: BunUpgradeServer): Promise<Response | undefined>
+  readonly websocket: typeof bunDevWebSocket
 }
 interface BunServerHandle {
   readonly port: number
@@ -214,6 +222,7 @@ export function devHtml(entryHref: string): string {
 interface WriteDevFilesOptions {
   readonly routesDir: string
   readonly clientModule: string
+  readonly live?: LiveClientEntry | undefined
   readonly entryPath: string
   readonly htmlPath: string
 }
@@ -226,7 +235,7 @@ interface WriteDevFilesOptions {
  * the way the runtime does, so a leading slash there would mean the filesystem root.
  */
 export function writeDevFiles(options: WriteDevFilesOptions): void {
-  const { routesDir, clientModule, entryPath, htmlPath } = options
+  const { routesDir, clientModule, entryPath, htmlPath, live } = options
   mkdirSync(dirname(entryPath), { recursive: true })
   const manifest = discoverRoutes(routesDir)
   const entryDir = dirname(entryPath)
@@ -244,7 +253,10 @@ export function writeDevFiles(options: WriteDevFilesOptions): void {
   // already been passed to createRoot()") and only then does the callback get to reload - trading an
   // accurate warning for a real error. Editing a component-only module never reaches this path: Bun
   // applies React Fast Refresh there and state is preserved.
-  writeIfChanged(entryPath, generateClientEntry(manifest, { clientModule, resolve: toSpecifier }))
+  writeIfChanged(
+    entryPath,
+    generateClientEntry(manifest, { clientModule, resolve: toSpecifier, live }),
+  )
   const entryHref = `./${relative(dirname(htmlPath), entryPath).replaceAll("\\", "/")}`
   writeIfChanged(htmlPath, devHtml(entryHref))
 }
@@ -355,7 +367,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       ? async (): Promise<undefined> => undefined
       : servePublicDir({ dir: resolve(publicDir) })
 
-  writeDevFiles({ routesDir, clientModule, entryPath, htmlPath })
+  writeDevFiles({ routesDir, clientModule, entryPath, htmlPath, live: options.live })
   // Importing the generated HTML is what hands it to Bun's bundler. A runtime-computed path is fine:
   // Bun resolves and bundles the HTML, and everything it references, at import time.
   const htmlModule = (await import(htmlPath)) as { default: HtmlBundle }
@@ -486,7 +498,8 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       development: { hmr: true },
       // The probe route is the ONLY path Bun owns; everything else falls through to nifra's SSR.
       routes: { [PROBE_PATH]: htmlModule.default },
-      fetch: async (req: Request): Promise<Response> => {
+      websocket: bunDevWebSocket,
+      fetch: async (req: Request, bun: BunUpgradeServer): Promise<Response | undefined> => {
         const url = new URL(req.url)
         const host = req.headers.get("host") ?? url.host
         if (!isLoopbackHost(host) && !allowedHosts.has(hostName(host)))
@@ -494,6 +507,14 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
             `[nifra/web/dev] ${hostName(host)} is not a loopback host; add it to allowedHosts if this server should answer it.\n`,
             { status: 403, headers: { "content-type": "text/plain; charset=utf-8" } },
           )
+        if (isWebSocketUpgrade(req)) {
+          const answer = await upgradeOnBun(
+            await appForRequest((await currentEntry()).src),
+            req,
+            bun,
+          )
+          if (answer !== "pass") return answer
+        }
         // The stable client-entry URL. Pages reference THIS; it redirects to whichever hashed chunk Bun
         // is serving at the moment the browser asks. A redirect rather than a proxy so the module's final
         // URL is Bun's own - its HMR client derives its socket and module identity from `import.meta.url`,
@@ -554,7 +575,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       syncWatchedFiles(false)
       session.markChange()
       try {
-        writeDevFiles({ routesDir, clientModule, entryPath, htmlPath })
+        writeDevFiles({ routesDir, clientModule, entryPath, htmlPath, live: options.live })
       } catch (err) {
         // A half-saved file can fail the scan mid-edit; the next change re-runs this.
         console.error("[nifra/web/dev] client entry regeneration failed:", err)

package/src/diagnostic-catalog.ts

@@ -17,6 +17,8 @@ interface CatalogEntry {
   readonly fix: string
   readonly docsAnchor: string
   readonly options?: readonly FixOption[]
+  /** Reported by a console warning, not thrown: the dev feed records the warning as an entry. */
+  readonly console?: true
 }
 
 /**
@@ -191,6 +193,52 @@ export const DIAGNOSTIC_CATALOG: readonly CatalogEntry[] = [
     fix: "Read the reason in the line: a 401 or 403 means the token lacks purge permission for this zone, project or service; a 5xx or network_error is retried on its own.",
     docsAnchor: "errors#cdn-purge-failed",
   },
+  {
+    code: "NIFRA_KEEPALIVE_IDENTITY_COOKIE",
+    match: (_n, m) => m.includes("NIFRA_KEEPALIVE_IDENTITY_COOKIE"),
+    console: true,
+    cause:
+      "The app keeps pages alive, and a response changed an HttpOnly cookie nifra does not know as a sign-in cookie. If that cookie says who is signed in, a sign-in or sign-out through it leaves the previous visitor's kept pages in every tab, and back shows them.",
+    fix: "Name the cookie in createWebApp({ keepAlive: { identityCookies } }) if it carries the session, or in keepAlive.ignoreCookies if it does not.",
+    docsAnchor: "errors#keepalive-identity-cookie",
+    options: [
+      {
+        label: "It is the session cookie",
+        fix: 'Add it to createWebApp({ keepAlive: { identityCookies: ["<name>"] } }): a response that changes or deletes it rotates the identity epoch, and every tab drops its kept pages.',
+      },
+      {
+        label: "It says nothing about the visitor",
+        fix: 'Add it to createWebApp({ keepAlive: { ignoreCookies: ["<name>"] } }) so development stops reporting it.',
+      },
+      {
+        label: "Identity lives in a token",
+        fix: "When the session is a bearer token in client storage, call identityChanged() from @nifrajs/web/client at sign-in and sign-out; it drops kept pages in every tab.",
+      },
+    ],
+  },
+  {
+    code: "NIFRA_KEEPALIVE_DIRECT_CHILD_CSS",
+    match: (_n, m) => m.includes("NIFRA_KEEPALIVE_DIRECT_CHILD_CSS"),
+    console: true,
+    cause:
+      "A keepAlive page renders inside two display:contents wrappers, so a selector that reached its top-level element as a direct child (or by its position among siblings) no longer matches it.",
+    fix: "Rewrite the selector the message names: a descendant combinator, the wrapper as the parent, or a class on the page's root element.",
+    docsAnchor: "errors#keepalive-direct-child-css",
+    options: [
+      {
+        label: "Use a descendant combinator",
+        fix: "Write `main section` instead of `main > section`: the wrappers sit between the two.",
+      },
+      {
+        label: "Target the wrapper",
+        fix: "Write `[data-nifra-page] > section`: the inner wrapper is the page's parent while it is shown.",
+      },
+      {
+        label: "Put a class on the page root",
+        fix: "Give the page's root element a class and select it directly, instead of by its parent or its position.",
+      },
+    ],
+  },
   {
     code: "NIFRA_SCHEMA_PARSE",
     match: (n, m) =>
@@ -215,6 +263,11 @@ const HYDRATION_MESSAGES: readonly RegExp[] = [
   /Minified React error #(?:418|423|425)\b/,
 ]
 
+/** True when a console `message` reports a catalog failure that is only ever logged, never thrown. */
+export function isConsoleDiagnostic(message: string): boolean {
+  return DIAGNOSTIC_CATALOG.some((entry) => entry.console === true && entry.match("", message))
+}
+
 /** True when `message` is a framework's report of a server/browser render mismatch. */
 export function isHydrationMismatch(message: string): boolean {
   return HYDRATION_MESSAGES.some((pattern) => pattern.test(message))

package/src/diagnostic.ts

@@ -20,6 +20,7 @@ export {
   classify,
   DIAGNOSTIC_CATALOG,
   type FixOption,
+  isConsoleDiagnostic,
   isHydrationMismatch,
 } from "./diagnostic-catalog.ts"
 export {