@nifrajs/web 2.2.0 → 2.4.0

package/src/bun-dev-entry.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web/bun-dev-entry` — discovering the client-entry URL Bun's dev server assigns.
+ * `@nifrajs/web/bun-dev-entry` - discovering the client-entry URL Bun's dev server assigns.
  *
  * ## Why this file exists at all
  *

package/src/chunk-names.ts

@@ -1,6 +1,6 @@
 /**
  * URL-safe output chunk naming. Bun names a code-split chunk after its source file's basename, so a
- * dynamic-route file like `[slug].tsx` emits `[slug]-<hash>.js` — the `[ ]` make a URL a static server
+ * dynamic-route file like `[slug].tsx` emits `[slug]-<hash>.js` - the `[ ]` make a URL a static server
  * (server-bun, CF Pages) reject with 400, so the lazy import fails and the route silently never
  * hydrates (SSR looks perfect; all interactivity is dead). `sanitizeOutputNames` renames every output
  * whose basename isn't URL-path-safe (`[slug]` → `_slug_`) and rewrites the references to it inside the

package/src/client.ts

@@ -1,11 +1,23 @@
 /**
- * `@nifrajs/web/client` — the agnostic browser layer for client-side navigation. It wires the pure
+ * `@nifrajs/web/client` - the agnostic browser layer for client-side navigation. It wires the pure
  * router store ({@link ClientRouter}) to the browser: `pushState` on navigate, `popstate` →
  * navigate, and delegated interception of same-origin `<a>` clicks (client transition instead of
- * a full page load). DOM-only — never imported on the server, so the store stays SSR-safe.
+ * a full page load). DOM-only - never imported on the server, so the store stays SSR-safe.
  */
+import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
 import type { Meta } from "./manifest.ts"
-import { type BrowserNavigate, setBrowserNavigate } from "./navigation.ts"
+import {
+  type Blocker,
+  type BlockerController,
+  type BlockerFunction,
+  type BlockerLocation,
+  type BlockerState,
+  type BrowserNavigate,
+  IDLE_BLOCKER,
+  setBlockerController,
+  setBrowserNavigate,
+} from "./navigation.ts"
 import type { ClientRouter } from "./router.ts"
 
 export interface InstallHistoryOptions {
@@ -31,6 +43,22 @@ export function installHistory(
   // fragment target (`#id`) to scroll to once the cross-page navigation's content renders.
   type PendingScroll = { readonly pos: readonly [number, number] } | { readonly hash: string }
   let pendingScroll: PendingScroll | null = null
+
+  // Navigation-guard state (useBlocker). `index` is our position in the history line, stored in
+  // `history.state.nifraIndex`; it exists solely to reverse a blocked back/forward (a popstate can't be
+  // cancelled, so we read the delta from the index and `history.go(-delta)` back). `here` is the location
+  // we're currently on - after a popstate `location` is already the destination, so "where we were" has
+  // to be tracked, not read. `reversing` swallows the popstate our own restoring `history.go` fires.
+  let index = (history.state as { nifraIndex?: number } | null)?.nifraIndex ?? 0
+  let here = location.pathname + location.search + (location.hash ?? "")
+  let reversing = false
+  type Registration = {
+    readonly shouldBlock: BlockerFunction
+    readonly emit: (blocker: Blocker) => void
+    state: BlockerState
+  }
+  // A single active guard (like react-router, one blocker at a time); the latest registration wins.
+  let registration: Registration | undefined
   const scrollOf = (state: unknown): [number, number] => {
     const saved = (state as { nifraScroll?: [number, number] } | null)?.nifraScroll
     return Array.isArray(saved) ? saved : [0, 0]
@@ -50,7 +78,7 @@ export function installHistory(
     return document.getElementById(id)
   }
 
-  // Wrap a navigation's render in a View Transition when the browser supports it — a graceful
+  // Wrap a navigation's render in a View Transition when the browser supports it - a graceful
   // enhancement (no-op elsewhere). The captured "before" is held across the data fetch, so pair
   // with link prefetch (hover/focus warms the cache) to keep most transitions instant.
   type ViewTransition = {
@@ -69,35 +97,112 @@ export function installHistory(
     }
     const vt = doc.startViewTransition(run)
     // Rapid in-app clicks supersede an in-flight transition; the browser skips it and rejects its
-    // promises. Reasons vary by engine — InvalidStateError "Transition was aborted because of
+    // promises. Reasons vary by engine - InvalidStateError "Transition was aborted because of
     // invalid state", or AbortError "Transition was skipped". The navigation still completes, so
     // we swallow these expected aborts rather than let them surface as unhandled rejections.
     for (const p of [vt.ready, vt.finished, vt.updateCallbackDone]) p.catch(() => {})
   }
 
-  const go = (path: string, mode: "push" | "replace"): void => {
+  // Parse a path into the `{ pathname, search, hash }` a `BlockerFunction` decides on.
+  const locationOf = (path: string): BlockerLocation => {
     const url = new URL(path, location.origin)
+    return { pathname: url.pathname, search: url.search, hash: url.hash }
+  }
+
+  // The single funnel every navigation asks before it commits. Returns true (navigation held) when a
+  // guard is armed and blocks; false when it may proceed. `retry` performs the navigation and is what
+  // `proceed` replays. While a prompt is already open (`blocked`) further navigations are swallowed; the
+  // replay from `proceed` (`proceeding`) is let straight through.
+  const guard = (nextPath: string, retry: () => void): boolean => {
+    const reg = registration
+    if (reg === undefined || reg.state === "proceeding") return false
+    if (reg.state === "blocked") return true
+    if (!reg.shouldBlock({ currentLocation: locationOf(here), nextLocation: locationOf(nextPath) }))
+      return false
+    reg.state = "blocked"
+    reg.emit({
+      state: "blocked",
+      proceed: () => {
+        if (reg.state !== "blocked") return
+        reg.state = "proceeding"
+        reg.emit({ state: "proceeding", proceed: undefined, reset: undefined })
+        retry()
+      },
+      reset: () => {
+        if (reg.state !== "blocked") return
+        reg.state = "unblocked"
+        reg.emit(IDLE_BLOCKER)
+      },
+    })
+    return true
+  }
+
+  // Once a proceeded navigation has committed, return the guard to idle so it can block the next one.
+  const settle = (): void => {
+    const reg = registration
+    if (reg !== undefined && reg.state === "proceeding") {
+      reg.state = "unblocked"
+      reg.emit(IDLE_BLOCKER)
+    }
+  }
+
+  // Commit a navigation only after its URL and origin are known-safe. An unmatched same-origin path
+  // becomes a hard load BEFORE history is mutated; otherwise the address bar could change while the
+  // router intentionally kept rendering the old route.
+  const parseNavigationUrl = (path: string): URL | null => {
+    try {
+      const url = new URL(path, location.origin)
+      if (url.protocol !== "http:" && url.protocol !== "https:") return null
+      if (url.origin !== location.origin) return null
+      return url
+    } catch {
+      return null
+    }
+  }
+
+  const commit = (path: string, url: URL, mode: "push" | "replace"): void => {
+    const routePath = url.pathname + url.search
+    if (router.match(routePath) === null) {
+      settle()
+      fallback(path)
+      return
+    }
     if (mode === "replace") {
-      // Replace the current entry 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.
-      history.replaceState({}, "", path)
+      // 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.
+      history.replaceState({ nifraIndex: index }, "", path)
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     } else {
-      // Save the leaving entry's scroll, push a fresh entry (URL incl. any #hash), then scroll the new
-      // route: to the fragment target if one was given, else to the top.
+      // Save the leaving entry's scroll (spread keeps its nifraIndex), push a fresh higher-indexed entry
+      // (URL incl. any #hash), then scroll the new route: to the fragment target if given, else the top.
       history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
-      history.pushState({}, "", path)
+      index += 1
+      history.pushState({ nifraIndex: index }, "", path)
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     }
+    here = url.pathname + url.search + url.hash
     // The data layer fetches by path+search; the #hash is client-only (never sent to the server).
-    transition(() => router.navigate(url.pathname + url.search).catch(() => fallback(path)))
+    transition(() => router.navigate(routePath).catch(() => fallback(path)))
+    settle()
+  }
+
+  const go = (path: string, mode: "push" | "replace"): void => {
+    // Validate before the blocker observes the target. A blocker receives parsed locations, so letting a
+    // malformed string reach `locationOf` would make an otherwise no-throw navigate unexpectedly throw.
+    const url = parseNavigationUrl(path)
+    if (url === null) {
+      settle()
+      return
+    }
+    if (guard(path, () => commit(path, url, mode))) return
+    commit(path, url, mode)
   }
 
   // Programmatic navigation for adapter `useNavigate` bindings, published through the DOM-free bridge
   // (`@nifrajs/web`'s `getBrowserNavigate`). A string path pushes (or replaces); a number is a history
-  // delta (`-1` back / `1` forward), matching `history.go`. An off-route / cross-origin push still goes
-  // through `go`, whose `router.navigate` no-ops an unmatched path and whose fetch-failure falls back to
-  // a full load — same graceful degradation as a link click.
+  // delta (`-1` back / `1` forward), matching `history.go`. Off-route same-origin destinations hard-load
+  // without first creating a stale in-document history entry. Cross-origin and active-scheme strings are
+  // rejected; callers that intentionally leave the app use a normal `<a>`.
   const navigate: BrowserNavigate = (to, navOptions) => {
     if (typeof to === "number") {
       history.go(to)
@@ -107,6 +212,20 @@ export function installHistory(
   }
   setBrowserNavigate(navigate)
 
+  // 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
+  // it's still the current one (so a stale unmount doesn't wipe a newer guard).
+  const controller: BlockerController = {
+    register(shouldBlock, onChange) {
+      const reg: Registration = { shouldBlock, emit: onChange, state: "unblocked" }
+      registration = reg
+      return () => {
+        if (registration === reg) registration = undefined
+      }
+    },
+  }
+  setBlockerController(controller)
+
   // Resolve an event target to an in-app route path, or null (cross-origin, unknown route, or an
   // anchor opting out via target/download/rel=external). Shared by click + hover/focus prefetch.
   const inAppHref = (target: EventTarget | null): string | null => {
@@ -118,9 +237,9 @@ export function installHistory(
     const url = new URL(anchor.href)
     if (url.origin !== location.origin) return null
     if (router.match(url.pathname) === null) return null
-    // A same-page fragment link (`#section`, `/here#section` — only the hash differs) → null: let the
+    // A same-page fragment link (`#section`, `/here#section` - only the hash differs) → null: let the
     // browser do its native in-page anchor jump. Intercepting it would drop the fragment from the URL
-    // and force a scroll-to-top (a fresh push restores [0,0]) — i.e. break every in-page anchor (AUDIT
+    // and force a scroll-to-top (a fresh push restores [0,0]) - i.e. break every in-page anchor (AUDIT
     // H2). (A same-page link with NO hash still soft-navigates, as before.)
     if (url.pathname === location.pathname && url.search === location.search && url.hash !== "")
       return null
@@ -146,12 +265,49 @@ export function installHistory(
     void router.prefetch(url.pathname + url.search) // warm by path+search; the #hash isn't data
   }
 
-  // Back/forward: the entry exists (no push); restore its saved scroll after it renders.
+  // Back/forward: the entry already exists (no push). The URL has ALSO already changed - a popstate can't
+  // be cancelled - so a guard here can only restore-then-prompt: read the delta from our index, and if the
+  // guard holds, `history.go(-delta)` back to where we were (ignoring the popstate that reversal fires via
+  // `reversing`) while `proceed` re-issues `history.go(delta)` to redo the move. Unguarded, it's the old
+  // path: restore the entry's saved scroll after it renders.
   const onPopState = (): void => {
+    if (reversing) {
+      reversing = false
+      return
+    }
+    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))) {
+      reversing = true
+      history.go(-delta)
+      return
+    }
+    index = newIndex
+    here = dest
     pendingScroll = { pos: scrollOf(history.state) }
     transition(() =>
       router.navigate(location.pathname + location.search).catch(() => fallback(location.pathname)),
     )
+    settle()
+  }
+
+  // Close / reload / hard navigation away: no in-app destination exists, so consult the guard with the
+  // current location as both sides. A dirtiness guard (a boolean, or one that checks its own state) then
+  // triggers the browser's native "Leave site?" prompt; a purely destination-based guard won't. Browsers
+  // ignore any custom message - the string is set only because legacy engines require `returnValue`.
+  const onBeforeUnload = (event: BeforeUnloadEvent): void => {
+    const reg = registration
+    if (reg === undefined || reg.state === "proceeding") return
+    // `blocked` already proves the guard found unsaved state. Re-check only while idle; suppressing the
+    // native prompt merely because an in-app confirmation is open creates a close/reload data-loss gap.
+    if (
+      reg.state === "unblocked" &&
+      !reg.shouldBlock({ currentLocation: locationOf(here), nextLocation: locationOf(here) })
+    )
+      return
+    event.preventDefault()
+    event.returnValue = ""
   }
 
   // After a navigation settles (content rendered), apply the pending scroll target on the next frame:
@@ -177,32 +333,35 @@ export function installHistory(
   document.addEventListener("pointerover", onPrefetch)
   document.addEventListener("focusin", onPrefetch)
   window.addEventListener("popstate", onPopState)
+  window.addEventListener("beforeunload", onBeforeUnload)
   return () => {
     unsubscribe()
     setBrowserNavigate(undefined) // stop routing `useNavigate` to a torn-down router
+    setBlockerController(undefined) // stop routing `useBlocker` to a torn-down registry
     document.removeEventListener("click", onClick)
     document.removeEventListener("pointerover", onPrefetch)
     document.removeEventListener("focusin", onPrefetch)
     window.removeEventListener("popstate", onPopState)
+    window.removeEventListener("beforeunload", onBeforeUnload)
   }
 }
 
 /**
  * Intercept submissions of same-origin `<form method="post">` whose action targets an app route:
- * submit via the router (no full reload — POST the action, then revalidate the active loader). On
+ * submit via the router (no full reload - POST the action, then revalidate the active loader). On
  * failure it falls back to a native submit, so the form still works. Returns a teardown function.
  */
 /**
  * Sync the document head to a route's resolved {@link Meta} on client navigation. Sets the title
- * (when provided) and replaces the **managed** (`data-nifra`) `<meta>`/`<link>` tags — static head
+ * (when provided) and replaces the **managed** (`data-nifra`) `<meta>`/`<link>` tags - static head
  * content (charset, hand-written tags) is never touched. SSR injects the same `data-nifra` tags, so
  * the first navigation cleanly takes over from the server-rendered head.
  */
 export function applyHead(head: Meta): void {
   if (head.title !== undefined) document.title = head.title
-  // `<html lang>`/`<html dir>` — applied AUTHORITATIVELY (unlike `title`, which is left alone when the
+  // `<html lang>`/`<html dir>` - applied AUTHORITATIVELY (unlike `title`, which is left alone when the
   // route omits it), mirroring the SSR shell's defaulting exactly: `lang` falls back to `"en"`, `dir` is
-  // removed when unset. Anything laxer drifts on a multilingual site — navigating /ur → /en would leave
+  // removed when unset. Anything laxer drifts on a multilingual site - navigating /ur → /en would leave
   // `dir="rtl"` behind and lay the English page out right-to-left, a bug a hard reload would not show.
   const root = document.documentElement
   root.setAttribute("lang", head.lang ?? "en")
@@ -210,12 +369,13 @@ export function applyHead(head: Meta): void {
   else root.setAttribute("dir", head.dir)
   for (const el of document.head.querySelectorAll("[data-nifra]")) el.remove()
   // Values follow the same HTML attribute conventions as the SSR `tagAttrs`: a string sets the value,
-  // `true` sets the bare boolean attribute, `false`/`undefined` skip it — so a soft-nav head matches
+  // `true` sets the bare boolean attribute, `false`/`undefined` skip it - so a soft-nav head matches
   // the server-rendered one exactly (no hydration drift on the managed tags).
-  const add = (tag: "meta" | "link", attrs: Record<string, string | boolean | undefined>): void => {
+  const add = (tag: "meta" | "link", attrs: Readonly<object>): void => {
+    const trusted = trustedHeadAttributes(tag, attrs)
+    if (trusted === null) return
     const el = document.createElement(tag)
-    for (const [name, value] of Object.entries(attrs)) {
-      if (value === undefined || value === false) continue
+    for (const [name, value] of trusted) {
       el.setAttribute(name, value === true ? "" : value)
     }
     el.setAttribute("data-nifra", "")
@@ -223,13 +383,36 @@ export function applyHead(head: Meta): void {
   }
   for (const m of head.meta ?? []) add("meta", m)
   for (const l of head.link ?? []) add("link", l)
-  // `<script>` slot (JSON-LD etc.) — soft-nav parity with the SSR `headTags` script render. Set the body
+  // `<script>` slot (JSON-LD etc.) - soft-nav parity with the SSR `headTags` script render. Set the body
   // via `textContent`, NOT `innerHTML`: `textContent` assigns the raw string without HTML re-parsing, so
-  // a `</script>` (or `<!--`/`]]>`) payload in the JSON-LD can't break out — the DOM-native equivalent of
+  // a `</script>` (or `<!--`/`]]>`) payload in the JSON-LD can't break out - the DOM-native equivalent of
   // the server's `escapeScriptContent`. `type` defaults to `application/ld+json` (matching the SSR side).
   for (const s of head.script ?? []) {
+    const type = s.type ?? "application/ld+json"
+    if (!INERT_SCRIPT_TYPES.has(type)) {
+      throw new TypeError("[nifra/web] refusing executable content in the inert head.script slot")
+    }
+    const el = document.createElement("script")
+    el.setAttribute("type", type)
+    el.textContent = s.content
+    el.setAttribute("data-nifra", "")
+    document.head.appendChild(el)
+  }
+  for (const s of head.unsafeScript ?? []) {
+    if (s.unsafe !== true || s.nonce.trim() === "") {
+      throw new TypeError("[nifra/web] executable inline scripts require a non-empty CSP nonce")
+    }
+    // Same allowlist the server applies. `setAttribute` cannot be broken out of the way the server's
+    // template literal could, so this is not about injection here - it is about the two halves
+    // accepting the same documents, so a head that renders cannot fail on the next soft-nav.
+    if (!EXECUTABLE_SCRIPT_TYPES.has(s.type)) {
+      throw new TypeError(
+        `[nifra/web] unsupported executable script type ${JSON.stringify(s.type)}`,
+      )
+    }
     const el = document.createElement("script")
-    el.setAttribute("type", s.type ?? "application/ld+json")
+    el.setAttribute("type", s.type)
+    el.setAttribute("nonce", s.nonce)
     el.textContent = s.content
     el.setAttribute("data-nifra", "")
     document.head.appendChild(el)
@@ -250,7 +433,7 @@ export function installForms(router: ClientRouter): () => void {
     // actionData drives the update); absent or any other value keeps the default revalidation.
     const revalidate = form.dataset.nifraRevalidate !== "false"
     router.submit(url.pathname + url.search, new FormData(form), { revalidate }).catch(() => {
-      form.submit() // data submit failed — fall back to a full-page POST
+      form.submit() // data submit failed - fall back to a full-page POST
     })
   }
   document.addEventListener("submit", onSubmit)
@@ -262,7 +445,7 @@ export function installForms(router: ClientRouter): () => void {
  * and fires a one-shot `nifra:hydrated` event. The generated client entry calls this on the next frame
  * after the adapter mounts (so every framework binding gets it), letting apps gate a custom JS-only
  * interaction that would otherwise fire before its handler is attached. Idempotent. nifra's own
- * progressive-enhancement forms/links don't need it — only hand-wired onClick/onSubmit handlers with no
+ * progressive-enhancement forms/links don't need it - only hand-wired onClick/onSubmit handlers with no
  * native fallback do. See the Hydration guide.
  */
 export function signalHydrated(): void {

package/src/conformance.ts

@@ -93,8 +93,8 @@ const readHtml = async (
  * and hydration-head output is a stable string. It rejects with
  * {@link RenderAdapterConformanceError} naming the first failed check.
  *
- * Framework semantics outside the interface—Suspense scheduling, compiler plugins, DOM hydration,
- * error boundaries, and framework-specific primitives—remain the adapter package's local tests.
+ * Framework semantics outside the interface-Suspense scheduling, compiler plugins, DOM hydration,
+ * error boundaries, and framework-specific primitives-remain the adapter package's local tests.
  */
 export async function assertRenderAdapterConformance(
   adapter: RenderAdapter,
@@ -135,7 +135,7 @@ export async function assertRenderAdapterConformance(
     if (typeof buffered !== "string") fail("buffered render", "renderToString must return a string")
     const bufferedHtml = buffered as string
     if (fixture.deferred) {
-      // Deferred content differs between streaming and buffered renders — only require every marker.
+      // Deferred content differs between streaming and buffered renders - only require every marker.
       for (const marker of [
         markers.outer,
         markers.inner,

package/src/deferred.ts

@@ -2,7 +2,7 @@
  * Deferred loader data (`defer()`). A loader may mark slow values as deferred: the critical data
  * renders in the shell, the deferred data streams in behind a `<Suspense>` (the adapter's `<Await>`
  * consumes it) and resolves on the client **without a re-fetch**. This module owns the agnostic
- * protocol — the marker, the resolved/deferred split, and the tiny client registry that streamed
+ * protocol - the marker, the resolved/deferred split, and the tiny client registry that streamed
  * resolution scripts settle. The per-adapter `<Await>` lives in `@nifrajs/web-{solid,react}/client`.
  */
 import { plainJsonCodec, type TransportCodec } from "@nifrajs/core/transport-codec"
@@ -10,7 +10,7 @@ import { plainJsonCodec, type TransportCodec } from "@nifrajs/core/transport-cod
 /**
  * A loader value marked to stream in after the shell. The component consumes it with the adapter's
  * `<Await resolve={...}>`; until the promise settles the shell shows the `<Suspense>` fallback.
- * `id` is assigned by the server at serialization time — the streamed resolve script keys off it.
+ * `id` is assigned by the server at serialization time - the streamed resolve script keys off it.
  */
 export interface Deferred<T> {
   readonly __nifra_deferred: true
@@ -19,8 +19,8 @@ export interface Deferred<T> {
 }
 
 /**
- * Mark a loader value as deferred — it streams in after the shell instead of blocking it. Works
- * **anywhere** in the loader's returned data — a top-level key, or nested in objects/arrays:
+ * Mark a loader value as deferred - it streams in after the shell instead of blocking it. Works
+ * **anywhere** in the loader's returned data - a top-level key, or nested in objects/arrays:
  *
  *   return { user: await api.user.get(), feed: defer(api.user.feed()),
  *            panels: [{ chart: defer(api.metrics()) }] }
@@ -48,8 +48,8 @@ function isDeferred(value: unknown): value is Deferred<unknown> {
 /**
  * Split a loader (or action) result into the **component-facing** data (deferred values carry their
  * assigned `id` + promise, for `<Await>`) and the **client-serializable** data (deferred values
- * replaced with a `{__nifra_deferred: id}` placeholder — promises don't serialize). Walks the tree
- * **recursively** — `defer()` works at any depth, inside nested objects and arrays — assigning ids in
+ * replaced with a `{__nifra_deferred: id}` placeholder - promises don't serialize). Walks the tree
+ * **recursively** - `defer()` works at any depth, inside nested objects and arrays - assigning ids in
  * walk order. `idOffset` continues the id space when a page splits two results (loader data **and**
  * action data) into one shared client registry, so their ids don't collide. `deferred` lists the
  * promises for callers that await them. Recurses plain objects + arrays only; the data is expected to
@@ -65,7 +65,7 @@ export function prepareDeferred(
 } {
   const deferred: Array<{ id: number; promise: Promise<unknown> }> = []
   // Structural sharing: a subtree with no deferred value returns the ORIGINAL node for
-  // both sides (`fc`/`cl` identical to the input), so a deferred-free result — the common case — is
+  // both sides (`fc`/`cl` identical to the input), so a deferred-free result - the common case - is
   // returned by reference with no persisted clone, no downstream copy, and no throwaway clone
   // allocations. Only the path to a `defer()` marker is rebuilt; unchanged siblings are shared by
   // reference.
@@ -140,19 +140,19 @@ export function prepareDeferred(
 }
 
 /**
- * Stable, non-leaking payload streamed to the client when a deferred value rejects — never the raw
+ * Stable, non-leaking payload streamed to the client when a deferred value rejects - never the raw
  * error text. The real reason is logged server-side; `<Await>`'s `errorFallback` receives
  * this code. (A future typed `DeferredError` could opt into a public, intentional message.) Shared by
  * the NDJSON soft-nav transport and the full-document SSR path (`renderPage`'s `streamDocument`).
  */
 export const DEFERRED_ERROR_CODE = "deferred_error"
-// Shared, stateless — allocated once at module load, not per stream.
+// Shared, stateless - allocated once at module load, not per stream.
 const NDJSON_ENCODER = new TextEncoder()
 
 /**
  * Stream a loader result as NDJSON for a client (soft) navigation: line 1 is the critical data with
  * `{__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
+ * 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
  * data after line 1 and settles `<Await>`'s markers as the resolution lines arrive. `JSON.stringify`
@@ -210,7 +210,7 @@ export const DEFERRED_RUNTIME = `(() => {
     return e;
   };
   window.__nifraDeferred = (id) => get(id).p;
-  // Tag the promise (status/value/reason) — React's use() reads them and returns SYNCHRONOUSLY at
+  // Tag the promise (status/value/reason) - React's use() reads them and returns SYNCHRONOUSLY at
   // hydration, so it renders the resolved content directly into the <Suspense> boundary the server
   // streamed (no re-suspend, no fallback flash). r/j also wake awaiters (Solid uses its own _$HY).
   window.__nifraResolve = (id, v) => { const e = get(id); e.p.status = "fulfilled"; e.p.value = v; e.r(v); };
@@ -219,7 +219,7 @@ export const DEFERRED_RUNTIME = `(() => {
 
 /**
  * Source emitted into the generated client entry: maps serialized `{__nifra_deferred: id}` placeholders
- * (at any depth — nested objects/arrays) to the registry's promises, so the component receives real
+ * (at any depth - nested objects/arrays) to the registry's promises, so the component receives real
  * promises to `<Await>`. A no-op for data without placeholders (so non-deferred pages are unchanged).
  */
 export const MAP_DEFERRED_SOURCE = `const mapDeferred = (d) => {
@@ -233,18 +233,18 @@ export const MAP_DEFERRED_SOURCE = `const mapDeferred = (d) => {
 
 type Pending = Map<number, { resolve: (v: unknown) => void; reject: (e: unknown) => void }>
 
-/** Replace `{__nifra_deferred: <number>}` placeholders (at any depth — nested objects/arrays) with
+/** Replace `{__nifra_deferred: <number>}` placeholders (at any depth - nested objects/arrays) with
  * `Deferred` markers whose promises are held open in `pending` (settled later by
  * {@link parseNdjsonData}'s drain). Mirrors `prepareDeferred`'s recursive walk. */
 function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
-  // Markers already created in THIS parse, keyed by id — so a repeated id aliases the first marker.
+  // Markers already created in THIS parse, keyed by id - so a repeated id aliases the first marker.
   const byId = new Map<number, Deferred<unknown>>()
   const walk = (value: unknown): unknown => {
     const id = (value as { __nifra_deferred?: unknown } | null)?.__nifra_deferred
     if (value !== null && typeof value === "object" && typeof id === "number") {
       // The NDJSON stream is a trust boundary; the server assigns unique ids, but a corrupt/crafted
       // line-1 could repeat one. Alias a duplicate id to the first marker (same promise) instead of
-      // overwriting its resolver in `pending` — otherwise the first marker would never settle (a
+      // overwriting its resolver in `pending` - otherwise the first marker would never settle (a
       // permanently-pending promise that leaks on abort). One resolve line then settles both.
       const seen = byId.get(id)
       if (seen !== undefined) return seen
@@ -280,7 +280,7 @@ function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
  * 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
- * markers unsettled, they reject — so `<Await>` never hangs.
+ * markers unsettled, they reject - so `<Await>` never hangs.
  */
 export async function parseNdjsonData(
   stream: ReadableStream<Uint8Array>,
@@ -331,7 +331,7 @@ export async function parseNdjsonData(
         else entry.resolve(msg.v)
       }
     } catch {
-      // stream errored — leftovers are rejected below (unless this was an abort)
+      // stream errored - leftovers are rejected below (unless this was an abort)
     } finally {
       signal?.removeEventListener("abort", onAbort) // no-op if it already fired ({ once: true })
       // A natural stream end with markers unsettled = truncation → reject (so `<Await>` shows its

package/src/dev-diagnostics.ts

@@ -0,0 +1,47 @@
+/**
+ * The dev server's diagnostics surface, shared by both dev-server adapters - Bun in `dev.ts`, Vite in
+ * `vite.ts`. It owns the one contract that must never drift between them: capture the most recent SSR
+ * failure, serve it as JSON at `LAST_ERROR_PATH` with the identity + no-store headers an agent relies on,
+ * and render that same failure as the developer overlay. Each adapter keeps only its bundler-specific
+ * transport (Bun.serve + HMR vs Vite middlewares + `ssrFixStacktrace`); the diagnostic behaviour lives
+ * here once, so a new header or a new capture rule is a single edit both servers pick up.
+ *
+ * Vite once shipped without the `/__nifra/last-error` endpoint at all - the drift this module prevents.
+ */
+import { renderDiagnosticOverlay } from "./dev-error.ts"
+import { buildDiagnostic, type Diagnostic, LAST_ERROR_PATH } from "./diagnostic.ts"
+
+export interface DevDiagnostics {
+  /** True when a request path targets the structured last-error endpoint. */
+  isLastErrorPath(pathname: string): boolean
+  /** The JSON body + headers for the last-error endpoint: the most recent failure, or a benign
+   * `NIFRA_NONE` shape when nothing has failed yet. `no-store` so a stale failure is never cached. */
+  lastError(): { readonly body: string; readonly headers: Readonly<Record<string, string>> }
+  /** Capture a thrown SSR failure: store it for the endpoint and return the overlay HTML. The overlay a
+   * person sees and the JSON an agent reads come from this one Diagnostic, so they can never disagree. */
+  capture(err: unknown, request: { readonly method: string; readonly url: string }): string
+}
+
+/** One diagnostics surface per dev server. `root` is the resolved project root; it scopes the codeframe
+ * to the project (see buildDiagnostic). Both dev servers resolve a concrete root before calling this. */
+export function createDevDiagnostics(root: string): DevDiagnostics {
+  let last: Diagnostic | undefined
+  return {
+    isLastErrorPath: (pathname) => pathname === LAST_ERROR_PATH,
+    lastError: () => ({
+      body: JSON.stringify(
+        last ?? { code: "NIFRA_NONE", message: "No error captured since the dev server started." },
+      ),
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        "x-nifra-diagnostic": "true",
+      },
+    }),
+    capture: (err, request) => {
+      last = buildDiagnostic(err, { root, request })
+      return renderDiagnosticOverlay(last)
+    },
+  }
+}