@nifrajs/web 0.1.0-alpha.1

package/src/client.ts

@@ -0,0 +1,218 @@
+/**
+ * `@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.
+ */
+import type { Meta } from "./manifest.ts"
+import type { ClientRouter } from "./router.ts"
+
+export interface InstallHistoryOptions {
+  /** Full-page fallback when a client navigation can't proceed (default: `location.assign`). */
+  readonly fallback?: (path: string) => void
+}
+
+/**
+ * Attach history + link interception to a router. Returns a teardown function that removes the
+ * listeners. A data-fetch failure during a client navigation falls back to a full-page load, so
+ * navigation degrades gracefully rather than leaving the user stuck.
+ */
+export function installHistory(
+  router: ClientRouter,
+  options: InstallHistoryOptions = {},
+): () => void {
+  const fallback = options.fallback ?? ((path: string) => location.assign(path))
+
+  // We manage scroll ourselves (save per history entry, restore after the navigated content
+  // renders), so disable the browser's native restoration which would otherwise fight us.
+  history.scrollRestoration = "manual"
+  // A pending scroll is either a saved [x,y] (fresh push → top; back/forward → the stored position) or a
+  // 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
+  const scrollOf = (state: unknown): [number, number] => {
+    const saved = (state as { nifraScroll?: [number, number] } | null)?.nifraScroll
+    return Array.isArray(saved) ? saved : [0, 0]
+  }
+  // The fragment id from a `#hash` (percent-decoded; a malformed escape falls back to the raw value).
+  const hashId = (hash: string): string => {
+    const raw = hash.slice(1)
+    try {
+      return decodeURIComponent(raw)
+    } catch {
+      return raw
+    }
+  }
+  // Resolve a fragment id to its element — by `id`, then a legacy `<a name>` — or null if absent.
+  const findAnchor = (id: string): Element | null => {
+    if (id === "") return null
+    const byId = document.getElementById(id)
+    if (byId !== null) return byId
+    try {
+      return document.querySelector(`a[name="${CSS.escape(id)}"]`)
+    } catch {
+      return null // CSS/CSS.escape unavailable or an exotic id → no named-anchor match
+    }
+  }
+
+  // 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 = {
+    readonly ready: Promise<unknown>
+    readonly finished: Promise<unknown>
+    readonly updateCallbackDone: Promise<unknown>
+  }
+  type ViewTransitionDocument = Document & {
+    startViewTransition?: (cb: () => unknown) => ViewTransition
+  }
+  const transition = (run: () => Promise<void>): void => {
+    const doc = document as ViewTransitionDocument
+    if (typeof doc.startViewTransition !== "function") {
+      void run()
+      return
+    }
+    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
+    // 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, push: boolean): void => {
+    const url = new URL(path, location.origin)
+    if (push) {
+      // 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.
+      history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
+      history.pushState({}, "", path)
+      pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
+    }
+    // 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)))
+  }
+
+  // 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 => {
+    const anchor = target instanceof Element ? target.closest("a") : null
+    if (anchor === null) return null
+    if (anchor.target !== "" && anchor.target !== "_self") return null
+    if (anchor.hasAttribute("download")) return null
+    if (anchor.getAttribute("rel")?.split(/\s+/).includes("external")) return null
+    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
+    // 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
+    // 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
+    // Keep the hash: a cross-page link to `/docs#install` lands on that anchor once the page renders.
+    return url.pathname + url.search + url.hash
+  }
+
+  const onClick = (event: MouseEvent): void => {
+    // Let the browser handle anything that isn't a plain left-click (modifiers = new tab/window).
+    if (event.defaultPrevented || event.button !== 0) return
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+    const href = inAppHref(event.target)
+    if (href === null) return
+    event.preventDefault()
+    go(href, true)
+  }
+
+  // Hover/focus an in-app link → warm its chunk + data (the store dedupes the spam).
+  const onPrefetch = (event: Event): void => {
+    const href = inAppHref(event.target)
+    if (href === null) return
+    const url = new URL(href, location.origin)
+    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.
+  const onPopState = (): void => {
+    pendingScroll = { pos: scrollOf(history.state) }
+    transition(() =>
+      router.navigate(location.pathname + location.search).catch(() => fallback(location.pathname)),
+    )
+  }
+
+  // After a navigation settles (content rendered), apply the pending scroll target on the next frame:
+  // a fragment's element for a cross-page `#hash`, the saved position for back/forward, else the top.
+  // Skipped for submits (pending).
+  const restoreScroll = (): void => {
+    if (router.snapshot().pending || pendingScroll === null) return
+    const target = pendingScroll
+    pendingScroll = null
+    requestAnimationFrame(() => {
+      if ("hash" in target) {
+        const el = findAnchor(target.hash)
+        if (el !== null) el.scrollIntoView()
+        else window.scrollTo(0, 0) // fragment not found → top, like a fresh page load
+      } else {
+        window.scrollTo(target.pos[0], target.pos[1])
+      }
+    })
+  }
+  const unsubscribe = router.subscribe(restoreScroll)
+
+  document.addEventListener("click", onClick)
+  document.addEventListener("pointerover", onPrefetch)
+  document.addEventListener("focusin", onPrefetch)
+  window.addEventListener("popstate", onPopState)
+  return () => {
+    unsubscribe()
+    document.removeEventListener("click", onClick)
+    document.removeEventListener("pointerover", onPrefetch)
+    document.removeEventListener("focusin", onPrefetch)
+    window.removeEventListener("popstate", onPopState)
+  }
+}
+
+/**
+ * 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
+ * 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
+ * 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
+  for (const el of document.head.querySelectorAll("[data-nifra]")) el.remove()
+  const add = (tag: "meta" | "link", attrs: Record<string, string>): void => {
+    const el = document.createElement(tag)
+    for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value)
+    el.setAttribute("data-nifra", "")
+    document.head.appendChild(el)
+  }
+  for (const m of head.meta ?? []) add("meta", m)
+  for (const l of head.link ?? []) add("link", l)
+}
+
+export function installForms(router: ClientRouter): () => void {
+  const onSubmit = (event: SubmitEvent): void => {
+    if (event.defaultPrevented) return
+    const form = event.target
+    if (!(form instanceof HTMLFormElement)) return
+    if (form.method.toLowerCase() !== "post") return // GET forms submit natively
+    const url = new URL(form.action) // resolved (or the current document URL if unset)
+    if (url.origin !== location.origin) return
+    if (router.match(url.pathname) === null) return // not an app route → native submit
+    event.preventDefault()
+    // `data-nifra-revalidate="false"` opts out of the post-action loader revalidation (the action's
+    // 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
+    })
+  }
+  document.addEventListener("submit", onSubmit)
+  return () => document.removeEventListener("submit", onSubmit)
+}

package/src/deferred.ts

@@ -0,0 +1,339 @@
+/**
+ * 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
+ * resolution scripts settle. The per-adapter `<Await>` lives in `@nifrajs/web-{solid,react}/client`.
+ */
+
+/**
+ * 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.
+ */
+export interface Deferred<T> {
+  readonly __nifra_deferred: true
+  readonly id: number
+  readonly promise: Promise<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:
+ *
+ *   return { user: await api.user.get(), feed: defer(api.user.feed()),
+ *            panels: [{ chart: defer(api.metrics()) }] }
+ *
+ * `LoaderData<typeof loader>` surfaces each deferred value as `Deferred<…>` (not awaited), so the
+ * component knows to `<Await>` it. The `id` is a placeholder until the server assigns the real one.
+ */
+export function defer<T>(promise: Promise<T>): Deferred<T> {
+  return { __nifra_deferred: true, id: -1, promise }
+}
+
+/** A loader value is a deferred marker (vs. a serialized `{__nifra_deferred: <number>}` placeholder,
+ * whose field is a number, not `true`). */
+function isDeferred(value: unknown): value is Deferred<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __nifra_deferred?: unknown }).__nifra_deferred === true
+  )
+}
+
+/**
+ * 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
+ * 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
+ * be plain JSON-serializable values.
+ */
+export function prepareDeferred(
+  data: unknown,
+  idOffset = 0,
+): {
+  readonly forComponent: unknown
+  readonly forClient: unknown
+  readonly deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>
+} {
+  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
+  // 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.
+  const split = (value: unknown): { fc: unknown; cl: unknown } | undefined => {
+    if (isDeferred(value)) {
+      const id = idOffset + deferred.length
+      deferred.push({ id, promise: value.promise })
+      return {
+        fc: { __nifra_deferred: true, id, promise: value.promise },
+        cl: { __nifra_deferred: id },
+      }
+    }
+    if (Array.isArray(value)) {
+      let fc: unknown[] | undefined
+      let cl: unknown[] | undefined
+      for (let i = 0; i < value.length; i++) {
+        const v = value[i]
+        const r = split(v)
+        if (r === undefined) {
+          if (fc !== undefined && cl !== undefined) {
+            fc[i] = v
+            cl[i] = v
+          }
+          continue
+        }
+        if (fc === undefined || cl === undefined) {
+          fc = value.slice(0, i)
+          cl = value.slice(0, i)
+        }
+        fc[i] = r.fc
+        cl[i] = r.cl
+      }
+      return fc === undefined || cl === undefined ? undefined : { fc, cl }
+    }
+    if (value !== null && typeof value === "object") {
+      const input = value as Record<string, unknown>
+      let fc: Record<string, unknown> | undefined
+      let cl: Record<string, unknown> | undefined
+      for (const k in input) {
+        if (!Object.hasOwn(input, k)) continue
+        const v = input[k]
+        const r = split(v)
+        if (r === undefined) {
+          if (fc !== undefined && cl !== undefined) {
+            fc[k] = v
+            cl[k] = v
+          }
+          continue
+        }
+        if (fc === undefined || cl === undefined) {
+          fc = {}
+          cl = {}
+          for (const prev in input) {
+            if (!Object.hasOwn(input, prev)) continue
+            if (prev === k) break
+            const prevValue = input[prev]
+            fc[prev] = prevValue
+            cl[prev] = prevValue
+          }
+        }
+        fc[k] = r.fc
+        cl[k] = r.cl
+      }
+      return fc === undefined || cl === undefined ? undefined : { fc, cl }
+    }
+    return undefined
+  }
+  const result = split(data)
+  return result === undefined
+    ? { forComponent: data, forClient: data, deferred }
+    : { forComponent: result.fc, forClient: result.cl, deferred }
+}
+
+/**
+ * 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.
+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
+ * 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`
+ * 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).
+ */
+export function ndjsonStream(
+  forClient: unknown,
+  deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
+): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    async start(controller) {
+      controller.enqueue(NDJSON_ENCODER.encode(`${JSON.stringify(forClient)}\n`))
+      await Promise.all(
+        deferred.map(async (d) => {
+          try {
+            const value = await d.promise
+            controller.enqueue(NDJSON_ENCODER.encode(`${JSON.stringify({ i: d.id, v: value })}\n`))
+          } 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)
+            controller.enqueue(
+              NDJSON_ENCODER.encode(`${JSON.stringify({ i: d.id, e: DEFERRED_ERROR_CODE })}\n`),
+            )
+          }
+        }),
+      )
+      controller.close()
+    },
+  })
+}
+
+/**
+ * Inline client runtime injected into the shell `<head>` when a page has deferred data: a per-id
+ * promise registry that streamed `__nifraResolve(id, value)` / `__nifraReject(id, err)` scripts settle
+ * (created lazily, so a resolve script that arrives before the client maps the placeholder still
+ * works), plus `__nifraDeferred(id)` to read the promise. A plain inline script (not the deferred
+ * module entry), so it runs before any streamed resolve script.
+ */
+export const DEFERRED_RUNTIME = `(() => {
+  const reg = new Map();
+  const get = (id) => {
+    let e = reg.get(id);
+    if (!e) {
+      let r, j;
+      const p = new Promise((a, b) => { r = a; j = b; });
+      // <Await> reads the tagged status/reason synchronously (it never .then()s a rejected promise),
+      // so attach a no-op catch to keep a rejection from surfacing as an unhandled rejection.
+      p.catch(() => {});
+      e = { p, r, j };
+      reg.set(id, e);
+    }
+    return e;
+  };
+  window.__nifraDeferred = (id) => get(id).p;
+  // 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); };
+  window.__nifraReject = (id, x) => { const e = get(id); e.p.status = "rejected"; e.p.reason = x; e.j(x); };
+})();`
+
+/**
+ * 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
+ * promises to `<Await>`. A no-op for data without placeholders (so non-deferred pages are unchanged).
+ */
+export const MAP_DEFERRED_SOURCE = `const mapDeferred = (d) => {
+  if (!d || typeof d !== "object") return d
+  if (typeof d.__nifra_deferred === "number") return { __nifra_deferred: true, id: d.__nifra_deferred, promise: window.__nifraDeferred(d.__nifra_deferred) }
+  if (Array.isArray(d)) return d.map(mapDeferred)
+  const out = {}
+  for (const k in d) out[k] = mapDeferred(d[k])
+  return out
+}`
+
+type Pending = Map<number, { resolve: (v: unknown) => void; reject: (e: unknown) => void }>
+
+/** 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.
+  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
+      // permanently-pending promise that leaks on abort). One resolve line then settles both.
+      const seen = byId.get(id)
+      if (seen !== undefined) return seen
+      let resolve!: (v: unknown) => void
+      let reject!: (e: unknown) => void
+      const promise = new Promise<unknown>((res, rej) => {
+        resolve = res
+        reject = rej
+      })
+      promise.catch(() => {}) // no unhandled rejection (<Await> drives the actual handling)
+      pending.set(id, { resolve, reject })
+      const marker = { __nifra_deferred: true, id, promise } satisfies Deferred<unknown>
+      byId.set(id, marker)
+      return marker
+    }
+    if (Array.isArray(value)) return value.map(walk)
+    if (value !== null && typeof value === "object") {
+      const out: Record<string, unknown> = {}
+      for (const [key, v] of Object.entries(value)) out[key] = walk(v)
+      return out
+    }
+    return value
+  }
+  return walk(data)
+}
+
+/**
+ * Client side of {@link ndjsonStream} (used by the router's `defaultFetchData` 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
+ * markers unsettled, they reject — so `<Await>` never hangs.
+ */
+export async function parseNdjsonData(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const reader = stream.getReader()
+  const dec = new TextDecoder()
+  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()
+  if (signal) signal.addEventListener("abort", onAbort, { once: true })
+
+  const readLine = async (): Promise<string | null> => {
+    for (;;) {
+      const nl = buffer.indexOf("\n")
+      if (nl !== -1) {
+        const line = buffer.slice(0, nl)
+        buffer = buffer.slice(nl + 1)
+        return line
+      }
+      const { done, value } = await reader.read()
+      if (done) {
+        const rest = buffer
+        buffer = ""
+        return rest === "" ? null : rest
+      }
+      buffer += dec.decode(value, { stream: true })
+    }
+  }
+
+  const pending: Pending = new Map()
+  const first = await readLine()
+  const data = markersFromPlaceholders(first === null ? null : JSON.parse(first), pending)
+
+  void (async () => {
+    try {
+      for (;;) {
+        const line = await readLine()
+        if (line === null) break
+        if (line === "") continue
+        const msg = JSON.parse(line) as { i: number; v?: unknown; e?: string }
+        const entry = pending.get(msg.i)
+        if (entry === undefined) continue
+        pending.delete(msg.i)
+        if ("e" in msg) entry.reject(new Error(msg.e))
+        else entry.resolve(msg.v)
+      }
+    } catch {
+      // 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
+      // error). An `abort` = a superseded navigation → leave them pending: the markers are detached
+      // (their data was never applied), so rejecting would only risk an error flash mid-transition.
+      if (!signal?.aborted) {
+        for (const [, entry] of pending) {
+          entry.reject(new Error("[nifra/web] deferred stream ended before this value resolved"))
+        }
+      }
+    }
+  })()
+
+  return data
+}

package/src/dev-error.ts

@@ -0,0 +1,62 @@
+/**
+ * Dev-only error overlay. When a loader/action/render throws during `@nifrajs/web/vite` dev, this
+ * renders a readable full-page overlay — the message, the source-mapped stack (Vite's
+ * `ssrFixStacktrace` runs first), and the request line — instead of the bare `err.stack` text dump.
+ * Dev-only by construction: it's called solely from the Vite middleware's catch, never in
+ * production (production maps errors to the `_error` route boundary).
+ */
+
+const esc = (s: string): string =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+
+/** Split a stack into the message (first line) + the frame lines, for separate styling. */
+function parseStack(err: Error): { message: string; frames: string[] } {
+  const stack = err.stack ?? `${err.name}: ${err.message}`
+  const lines = stack.split("\n")
+  // The message can span multiple leading lines (some errors do); frames start at the first "    at ".
+  const firstFrame = lines.findIndex((l) => /^\s*at\s/.test(l))
+  if (firstFrame === -1) return { message: stack, frames: [] }
+  return {
+    message: lines.slice(0, firstFrame).join("\n").trim(),
+    frames: lines.slice(firstFrame).map((l) => l.trim()),
+  }
+}
+
+/**
+ * Render the dev error overlay HTML. `req` (method + url) is shown for context. The page is
+ * self-contained (inline CSS), dark, and labels itself a dev overlay so it's never mistaken for a
+ * production error page.
+ */
+export function renderDevErrorOverlay(err: unknown, req: { method: string; url: string }): string {
+  const error = err instanceof Error ? err : new Error(String(err))
+  const { message, frames } = parseStack(error)
+  const name = esc(error.name || "Error")
+  const framesHtml =
+    frames.length > 0
+      ? `<ol class="frames">${frames.map((f) => `<li>${esc(f)}</li>`).join("")}</ol>`
+      : `<p class="no-frames">No stack frames.</p>`
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${name} — nifra dev</title>
+<style>
+  :root { color-scheme: dark }
+  body { margin: 0; background: #0b0d10; color: #e6e6e6; font: 14px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; }
+  .bar { background: #2a0e0e; border-bottom: 1px solid #5a1d1d; padding: 10px 20px; font-weight: 700; color: #ff8a8a; display: flex; gap: 12px; align-items: baseline; }
+  .bar .tag { font-size: 11px; font-weight: 600; color: #ffb4b4; background: #401616; padding: 2px 8px; border-radius: 99px; letter-spacing: .04em; text-transform: uppercase; }
+  .bar .req { margin-left: auto; color: #c98; font-weight: 500; font-size: 12px; }
+  main { padding: 24px 28px; max-width: 1000px; }
+  h1 { font-size: 13px; color: #9aa; font-weight: 600; margin: 0 0 6px; text-transform: uppercase; letter-spacing: .05em; }
+  .message { font-size: 18px; color: #ff9b9b; white-space: pre-wrap; margin: 0 0 28px; font-weight: 600; }
+  .frames { list-style: none; margin: 0; padding: 0; border-left: 2px solid #333; }
+  .frames li { padding: 3px 0 3px 16px; color: #9fb0c0; white-space: pre-wrap; word-break: break-all; }
+  .frames li:first-child { color: #d6e2ee; }
+  .no-frames { color: #778; }
+  footer { margin-top: 28px; color: #667; font-size: 12px; }
+</style></head><body>
+<div class="bar"><span class="tag">nifra dev</span><span>${name}</span><span class="req">${esc(req.method)} ${esc(req.url)}</span></div>
+<main>
+  <h1>Unhandled error during SSR</h1>
+  <p class="message">${esc(message)}</p>
+  <h1>Stack</h1>
+  ${framesHtml}
+  <footer>This overlay is shown only by the dev server. In production this error maps to your <code>_error</code> route boundary.</footer>
+</main></body></html>`
+}