@nifrajs/web 2.3.0 → 2.5.0

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)
+    },
+  }
+}

package/src/dev-error.ts

@@ -1,39 +1,55 @@
 /**
  * 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).
+ * renders a readable full-page overlay from a structured [Diagnostic] - the code, the message, a source
+ * codeframe around the offending line, the recognised cause/fix when nifra has one, and the stack -
+ * instead of a bare `err.stack` text dump. Dev-only by construction: it's called solely from the dev
+ * server's catch, never in production (production maps errors to the `_error` route boundary).
+ *
+ * The overlay and the agent surfaces (`/__nifra/last-error`, `nifra_explain`) render from the SAME
+ * `Diagnostic`, so a person and an agent see the identical failure, one as HTML and one as JSON.
  */
+import type { Diagnostic } from "./diagnostic.ts"
 
 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()),
-  }
+/** The source codeframe block: numbered lines with the offending one highlighted. */
+function codeframeHtml(diagnostic: Diagnostic): string {
+  const cf = diagnostic.codeframe
+  if (cf === undefined) return ""
+  const loc = `${esc(cf.file)}:${cf.line}${cf.column !== undefined ? `:${cf.column}` : ""}`
+  const rows = cf.lines
+    .map(
+      (l) =>
+        `<div class="cf-row${l.caret ? " caret" : ""}"><span class="cf-ln">${l.number}</span><span class="cf-src">${esc(l.text) || " "}</span></div>`,
+    )
+    .join("")
+  return `<h1>Source</h1><div class="cf-loc">${loc}</div><div class="codeframe">${rows}</div>`
 }
 
-/**
- * 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")
+/** The recognised-failure callout: cause + fix + docs anchor, shown only when nifra classified the error. */
+function fixHtml(diagnostic: Diagnostic): string {
+  if (diagnostic.fix === undefined) return ""
+  const anchor =
+    diagnostic.docsAnchor !== undefined
+      ? `<div class="fix-docs">docs: <code>${esc(diagnostic.docsAnchor)}</code></div>`
+      : ""
+  const cause =
+    diagnostic.cause !== undefined ? `<p class="fix-cause">${esc(diagnostic.cause)}</p>` : ""
+  return `<div class="fix"><div class="fix-tag">likely fix</div>${cause}<p class="fix-do">${esc(diagnostic.fix)}</p>${anchor}</div>`
+}
+
+/** Render the overlay HTML from a prebuilt Diagnostic (the same object the agent surfaces serve). */
+export function renderDiagnosticOverlay(diagnostic: Diagnostic): string {
+  const name = esc(diagnostic.name || "Error")
+  const code = esc(diagnostic.code)
+  const reqLine =
+    diagnostic.request !== undefined
+      ? `<span class="req">${esc(diagnostic.request.method)} ${esc(diagnostic.request.url)}</span>`
+      : ""
   const framesHtml =
-    frames.length > 0
-      ? `<ol class="frames">${frames.map((f) => `<li>${esc(f)}</li>`).join("")}</ol>`
+    diagnostic.frames.length > 0
+      ? `<ol class="frames">${diagnostic.frames.map((f) => `<li>${esc(f.raw)}</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>
@@ -41,22 +57,37 @@ export function renderDevErrorOverlay(err: unknown, req: { method: string; url:
   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 .code { font-size: 11px; font-weight: 600; color: #ffd9a0; background: #3a2a12; padding: 2px 8px; border-radius: 99px; letter-spacing: .04em; }
   .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; }
+  h1 { font-size: 13px; color: #9aa; font-weight: 600; margin: 24px 0 6px; text-transform: uppercase; letter-spacing: .05em; }
+  h1:first-of-type { margin-top: 0; }
+  .message { font-size: 18px; color: #ff9b9b; white-space: pre-wrap; margin: 0 0 4px; font-weight: 600; }
+  .fix { background: #10241a; border: 1px solid #1f4d38; border-radius: 8px; padding: 12px 16px; margin: 20px 0; }
+  .fix-tag { font-size: 11px; font-weight: 700; color: #7fe0af; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 6px; }
+  .fix-cause { margin: 0 0 8px; color: #b9c9c1; }
+  .fix-do { margin: 0; color: #d6f2e4; }
+  .fix-docs { margin-top: 8px; font-size: 12px; color: #6a8; }
+  .cf-loc { color: #c98; font-size: 12px; margin-bottom: 8px; }
+  .codeframe { background: #0f1319; border: 1px solid #222; border-radius: 8px; overflow: auto; }
+  .cf-row { display: flex; white-space: pre; }
+  .cf-row.caret { background: #2a1414; }
+  .cf-ln { color: #556; text-align: right; width: 48px; padding: 1px 12px 1px 0; user-select: none; flex: none; border-right: 1px solid #222; }
+  .cf-row.caret .cf-ln { color: #ff8a8a; }
+  .cf-src { padding: 1px 0 1px 12px; color: #cdd6e0; }
   .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>
+<div class="bar"><span class="tag">nifra dev</span><span class="code">${code}</span><span>${name}</span>${reqLine}</div>
 <main>
-  <h1>Unhandled error during SSR</h1>
-  <p class="message">${esc(message)}</p>
+  <p class="message">${esc(diagnostic.message)}</p>
+  ${fixHtml(diagnostic)}
+  ${codeframeHtml(diagnostic)}
   <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>
+  <footer>This overlay is shown only by the dev server. Its structured form is at <code>/__nifra/last-error</code> and via <code>nifra_explain</code>. In production this error maps to your <code>_error</code> route boundary.</footer>
 </main></body></html>`
 }

package/src/dev-port.ts

@@ -49,15 +49,27 @@ export interface ListenTarget {
  * Without an `error` listener attached, Node throws from deep inside `node:events`, the new process dies
  * in the background, and nothing connects that death to the stale page in front of you.
  */
-export function listenOrExplain(server: ListenTarget, port: number): Promise<void> {
+export function listenOrExplain(
+  server: ListenTarget,
+  port: number,
+  hostname?: string,
+): Promise<void> {
   return new Promise<void>((resolve, reject) => {
     const onError = (err: unknown): void => reject(explainBindFailure(err, port))
     server.once("error", onError)
-    server.listen(port, () => {
+    const onListening = (): void => {
       // Drop the guard once we're listening: leaving it attached would funnel a LATER server error into
       // an already-settled promise, silently swallowing it instead of surfacing it.
       server.removeListener("error", onError)
       resolve()
-    })
+    }
+    if (hostname === undefined) server.listen(port, onListening)
+    else {
+      ;(
+        server as ListenTarget & {
+          listen(port: number, hostname: string, cb: () => void): void
+        }
+      ).listen(port, hostname, onListening)
+    }
   })
 }

package/src/dev.ts

@@ -54,12 +54,14 @@ import {
 import { dirname, relative, resolve } from "node:path"
 import { type BuildClientOptions, buildClient } from "./build.ts"
 import { type DevEntryMatch, resolveDevEntry } from "./bun-dev-entry.ts"
-import { renderDevErrorOverlay } from "./dev-error.ts"
+import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { explainBindFailure } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
 import { servePublicDir } from "./public-dir.ts"
 
+export { LAST_ERROR_PATH } from "./diagnostic.ts"
+
 /** Minimal app surface the dev server needs - `createWebApp(...)` satisfies it. */
 interface FetchApp {
   fetch(request: Request): Response | Promise<Response>
@@ -128,6 +130,8 @@ type HtmlBundle = unknown
 /** The `Bun.serve` surface this uses, typed structurally so the file builds without Bun's ambient types. */
 interface BunServeOptions {
   readonly port: number
+  /** Diagnostics contain source paths; keep the dev server private by default. */
+  readonly hostname: "127.0.0.1"
   readonly development: { readonly hmr: boolean }
   readonly routes: Record<string, HtmlBundle>
   fetch(request: Request): Promise<Response>
@@ -243,6 +247,10 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   // The app root. `routesDir` is `<app>/routes` by convention, so its parent is the project - the one
   // place a generated entry can sit and still resolve the app's imports.
   const root = resolve(routesDir, "..")
+  // The most recent SSR failure as a structured Diagnostic, scoped to THIS server. Served at
+  // LAST_ERROR_PATH so an agent driving the dev server reads the exact failure (code, codeframe, fix) as
+  // JSON instead of scraping the overlay. Shared with the Vite adapter so the endpoint can't drift.
+  const devDiagnostics = createDevDiagnostics(root)
   const devDir = resolve(root, DEV_DIR)
   const entryPath = resolve(devDir, "entry.tsx")
   const htmlPath = resolve(devDir, "entry.html")
@@ -337,6 +345,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   try {
     server = serve({
       port,
+      hostname: "127.0.0.1",
       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 },
@@ -352,6 +361,11 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
           const entry = await currentEntry()
           return new Response(null, { status: 307, headers: { location: entry.src } })
         }
+        if (devDiagnostics.isLastErrorPath(url.pathname)) {
+          // The structured form of the overlay, for an agent driving the dev server (shared surface).
+          const { body, headers } = devDiagnostics.lastError()
+          return new Response(body, { headers })
+        }
         // Static probe before routing; a miss returns undefined and falls through, so no route is
         // shadowed and a page render never pays a filesystem stat (extension-less paths skip it).
         const staticFile = await servePublic(req)
@@ -370,13 +384,15 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
             headers,
           })
         } catch (err) {
-          return new Response(
-            renderDevErrorOverlay(err, {
-              method: req.method,
-              url: `${url.pathname}${url.search}`,
-            }),
-            { status: 500, headers: { "content-type": "text/html; charset=utf-8" } },
-          )
+          // One Diagnostic drives both surfaces: the overlay returned here and the JSON at LAST_ERROR_PATH.
+          const html = devDiagnostics.capture(err, {
+            method: req.method,
+            url: `${url.pathname}${url.search}`,
+          })
+          return new Response(html, {
+            status: 500,
+            headers: { "content-type": "text/html; charset=utf-8" },
+          })
         }
       },
     })

package/src/diagnostic.ts

@@ -0,0 +1,284 @@
+/**
+ * The structured diagnostic that every nifra failure resolves to - the single source both the human
+ * dev overlay ([dev-error.ts]) and the agent-facing surfaces (`/__nifra/last-error`, `nifra_explain`)
+ * render from. A stack trace is a wall of text; a `Diagnostic` is queryable: a stable `code`, the top
+ * USER frame (file/line/column), a source codeframe around it, and - when the failure is one nifra
+ * recognises - a plain-language `cause` + `fix` + docs anchor.
+ *
+ * This is the "AI-native" half of error reporting: the same object a person reads in the overlay is the
+ * JSON an agent reads to apply the fix, so neither has to scrape the other's format.
+ *
+ * Pure + DOM-free by construction (it only parses strings and reads source text through an injected
+ * reader), so it lives in the root typecheck program and is unit-testable without a dev server or disk.
+ */
+import { readFileSync, realpathSync } from "node:fs"
+import { isAbsolute, relative, resolve } from "node:path"
+
+/** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */
+export const LAST_ERROR_PATH = "/__nifra/last-error"
+
+/** One parsed stack frame. `file`/`line`/`column` are present only when the frame could be located. */
+export interface DiagnosticFrame {
+  readonly raw: string
+  readonly file?: string
+  readonly line?: number
+  readonly column?: number
+}
+
+/** A source window around the offending line. `caret` marks the exact line the top frame points at. */
+export interface Codeframe {
+  readonly file: string
+  readonly line: number
+  readonly column?: number | undefined
+  readonly lines: ReadonlyArray<{
+    readonly number: number
+    readonly text: string
+    readonly caret: boolean
+  }>
+}
+
+/** The structured failure. Serialisable as-is to JSON for the agent surfaces. */
+export interface Diagnostic {
+  /** Stable, greppable identifier, e.g. `NIFRA_SERVER_ONLY_IN_CLIENT`. `NIFRA_UNHANDLED` when unrecognised. */
+  readonly code: string
+  readonly name: string
+  readonly message: string
+  readonly request?: { readonly method: string; readonly url: string } | undefined
+  readonly frames: readonly DiagnosticFrame[]
+  readonly codeframe?: Codeframe | undefined
+  /** Plain-language "why this happened", when the failure is recognised. */
+  readonly cause?: string | undefined
+  /** Plain-language "do this", when the failure is recognised. */
+  readonly fix?: string | undefined
+  /** Docs section anchor for the code, e.g. `errors#server-only-in-client`. */
+  readonly docsAnchor?: string | undefined
+}
+
+/** Reads a source file's text, or returns undefined if it cannot (missing, binary, permission). */
+export type SourceReader = (file: string) => string | undefined
+
+const defaultReader: SourceReader = (file) => {
+  try {
+    return readFileSync(file, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
+// Turns a raw frame path into an absolute filesystem path, or undefined if it isn't one. Handles the
+// `file://` URL form Vite/Node emit and strips the `?v=hash` / `#` suffixes a bundler appends.
+function cleanFramePath(path: string): string | undefined {
+  let p = path.trim()
+  if (p.startsWith("file://")) {
+    try {
+      p = decodeURIComponent(new URL(p).pathname)
+    } catch {
+      return undefined
+    }
+  }
+  // Strip the `?v=hash` / `#` suffix without a `.*` regex (ReDoS-safe): cut at the first `?` or `#`.
+  const cut = p.search(/[?#]/)
+  if (cut !== -1) p = p.slice(0, cut)
+  const isAbsolute = p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p)
+  return isAbsolute ? p : undefined
+}
+
+/**
+ * Parse a V8/Node stack into structured frames. Handles the `at fn (path:line:col)`, bare
+ * `at path:line:col`, and `at async fn (...)` shapes; a frame that doesn't match keeps its raw text
+ * with no location (so nothing is silently dropped).
+ */
+export function parseFrames(stack: string): DiagnosticFrame[] {
+  const frames: DiagnosticFrame[] = []
+  for (const line of stack.split("\n")) {
+    const raw = line.trim()
+    if (!/^at\s/.test(raw)) continue
+    // Prefer the parenthesised location; fall back to a trailing `path:line:col`.
+    const paren = raw.match(/\(([^()]+):(\d+):(\d+)\)\s*$/)
+    const bare = raw.match(/^at\s+(?:async\s+)?(\S.*):(\d+):(\d+)\s*$/)
+    const m = paren ?? bare
+    if (!m) {
+      frames.push({ raw })
+      continue
+    }
+    const file = cleanFramePath(m[1] as string)
+    frames.push(
+      file === undefined ? { raw } : { raw, file, line: Number(m[2]), column: Number(m[3]) },
+    )
+  }
+  return frames
+}
+
+/** Frames inside dependencies or the runtime are noise for a first look; the user's own code is the signal. */
+function isUserFrame(file: string, root: string | undefined): boolean {
+  if (file.includes("/node_modules/") || file.includes("\\node_modules\\")) return false
+  if (file.startsWith("node:")) return false
+  if (root !== undefined) {
+    // A string prefix is not a path boundary (`/app-evil` starts with `/app`) and leaves `..` and
+    // symlink escapes unresolved. Resolve lexically first, then realpath existing paths so a codeframe
+    // can never read a source file outside the project root merely because a stack frame was crafted.
+    const rootPath = canonicalPath(root)
+    const framePath = canonicalPath(file)
+    const rel = relative(rootPath, framePath)
+    if (rel === ".." || rel.startsWith(`..${sepForPath(rel)}`) || isAbsolute(rel)) return false
+  }
+  return true
+}
+
+function sepForPath(path: string): string {
+  return path.includes("\\") ? "\\" : "/"
+}
+
+function canonicalPath(path: string): string {
+  const lexical = resolve(path)
+  try {
+    return realpathSync.native(lexical)
+  } catch {
+    return lexical
+  }
+}
+
+/** The first frame that points at the user's own source - what the codeframe should show. */
+export function topUserFrame(
+  frames: readonly DiagnosticFrame[],
+  root: string | undefined,
+): DiagnosticFrame | undefined {
+  return frames.find((f) => f.file !== undefined && isUserFrame(f.file, root))
+}
+
+/**
+ * Build a source codeframe: `radius` lines either side of `line`, each tagged with its 1-based number
+ * and whether it is the offending line. Returns undefined if the source can't be read or the line is
+ * out of range - a diagnostic without a codeframe is still useful, so this never throws.
+ */
+export function buildCodeframe(
+  file: string,
+  line: number,
+  column: number | undefined,
+  read: SourceReader = defaultReader,
+  radius = 3,
+): Codeframe | undefined {
+  const source = read(file)
+  if (source === undefined) return undefined
+  const all = source.split("\n")
+  if (line < 1 || line > all.length) return undefined
+  const start = Math.max(1, line - radius)
+  const end = Math.min(all.length, line + radius)
+  const lines: Array<{ number: number; text: string; caret: boolean }> = []
+  for (let n = start; n <= end; n++) {
+    lines.push({ number: n, text: all[n - 1] ?? "", caret: n === line })
+  }
+  return { file, line, column, lines }
+}
+
+/** A recognised failure shape: a stable code plus the plain-language cause/fix/anchor to attach. */
+interface CatalogEntry {
+  readonly code: string
+  readonly match: (name: string, message: string) => boolean
+  readonly cause: string
+  readonly fix: string
+  readonly docsAnchor: string
+}
+
+/**
+ * The recognised-failure catalog. Seeded with the highest-signal nifra failures; extend it as new
+ * classes of error earn a stable code. Order matters only in that the first match wins.
+ */
+export const DIAGNOSTIC_CATALOG: readonly CatalogEntry[] = [
+  {
+    code: "NIFRA_SERVER_ONLY_IN_CLIENT",
+    match: (_n, m) => m.includes("server-only module(s) in the client bundle"),
+    cause:
+      "A module marked server-only was reachable from a client entry, so it would ship to the browser.",
+    fix: "Follow the import chain in the message and move the server-only use behind a loader/action or a `*.server.ts` boundary, so it never enters a client component.",
+    docsAnchor: "errors#server-only-in-client",
+  },
+  {
+    code: "NIFRA_NODE_BUILTIN_IN_CLIENT",
+    match: (_n, m) => m.includes("Node built-in(s) in the client bundle"),
+    cause: "A `node:` built-in was reached from a client entry; it has no browser implementation.",
+    fix: "Move the code using the built-in to the server (loader/action or `*.server.ts`); the message lists the import chain that pulled it in.",
+    docsAnchor: "errors#node-builtin-in-client",
+  },
+  {
+    code: "NIFRA_SCHEMA_PARSE",
+    match: (n, m) =>
+      n === "SchemaError" ||
+      /failed to (parse|validate)|invalid_type|expected .* received/i.test(m),
+    cause: "Data crossing a boundary did not match its declared schema.",
+    fix: "Check the value against the schema at the failing boundary (loader input, search params, or request body); parse-don't-cast means the shape must match exactly.",
+    docsAnchor: "errors#schema-parse",
+  },
+]
+
+/** Classify an error name+message against the catalog; falls back to the generic unhandled code. */
+export function classify(
+  name: string,
+  message: string,
+): {
+  code: string
+  cause?: string
+  fix?: string
+  docsAnchor?: string
+} {
+  const hit = DIAGNOSTIC_CATALOG.find((e) => e.match(name, message))
+  if (hit === undefined) return { code: "NIFRA_UNHANDLED" }
+  return { code: hit.code, cause: hit.cause, fix: hit.fix, docsAnchor: hit.docsAnchor }
+}
+
+/** Split an Error's `stack` into its leading message block and its frame lines. */
+function messageAndStack(err: Error): { message: string; stack: string } {
+  const stack = err.stack ?? `${err.name}: ${err.message}`
+  const lines = stack.split("\n")
+  const firstFrame = lines.findIndex((l) => /^\s*at\s/.test(l))
+  if (firstFrame === -1) return { message: err.message || stack.trim(), stack: "" }
+  return {
+    message: lines.slice(0, firstFrame).join("\n").trim(),
+    stack: lines.slice(firstFrame).join("\n"),
+  }
+}
+
+export interface BuildDiagnosticOptions {
+  readonly request?: { readonly method: string; readonly url: string }
+  /** Project root; frames outside it are treated as non-user. Defaults to `process.cwd()`. */
+  readonly root?: string
+  /** Injectable source reader (tests pass a fake; production reads the filesystem). */
+  readonly read?: SourceReader
+}
+
+/**
+ * Resolve any thrown value into a `Diagnostic`: parse the (already source-mapped) stack, locate the top
+ * user frame, attach a codeframe, and classify the failure for a cause/fix. The caller is responsible
+ * for running Vite's `ssrFixStacktrace` first so the frames point at real source.
+ */
+export function buildDiagnostic(err: unknown, options: BuildDiagnosticOptions = {}): Diagnostic {
+  const error = err instanceof Error ? err : new Error(String(err))
+  const root = options.root ?? safeCwd()
+  const { message } = messageAndStack(error)
+  const frames = parseFrames(error.stack ?? "")
+  const top = topUserFrame(frames, root)
+  const codeframe =
+    top?.file !== undefined && top.line !== undefined
+      ? buildCodeframe(canonicalPath(top.file), top.line, top.column, options.read)
+      : undefined
+  const { code, cause, fix, docsAnchor } = classify(error.name || "Error", message)
+  return {
+    code,
+    name: error.name || "Error",
+    message,
+    request: options.request,
+    frames,
+    codeframe,
+    cause,
+    fix,
+    docsAnchor,
+  }
+}
+
+function safeCwd(): string | undefined {
+  try {
+    return process.cwd()
+  } catch {
+    return undefined
+  }
+}

package/src/router.ts

@@ -5,9 +5,9 @@
  * unit-tests without a browser and is safe to import from the SSR core's main entry.
  */
 import {
-  compareRoutePatternSpecificity,
   compileRoutePattern,
   matchRoutePattern,
+  sortRoutesBySpecificity,
 } from "@nifrajs/core/pattern"
 import type { StandardSchemaV1 } from "@nifrajs/core/server"
 import { parseNdjsonData } from "./deferred.ts"
@@ -156,9 +156,12 @@ export interface RoutePattern {
 export function createMatcher(
   patterns: readonly RoutePattern[],
 ): (path: string) => RouteMatch | null {
-  const compiled = patterns
-    .map((pattern) => ({ routeId: pattern.routeId, pattern: compileRoutePattern(pattern.pattern) }))
-    .sort((left, right) => compareRoutePatternSpecificity(left.pattern, right.pattern))
+  const compiled = sortRoutesBySpecificity(
+    patterns.map((pattern) => ({
+      routeId: pattern.routeId,
+      pattern: compileRoutePattern(pattern.pattern),
+    })),
+  )
   return (path) => {
     // Strip the query without allocating a `split("?")` array - matcher runs per match.
     const q = path.indexOf("?")