@nifrajs/web 2.2.0 → 2.4.0

package/src/dev-error.ts

@@ -1,62 +1,93 @@
 /**
  * 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>
+  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 .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

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web/dev-port` — what a dev server says when it cannot bind.
+ * `@nifrajs/web/dev-port` - what a dev server says when it cannot bind.
  *
  * Both pipelines need this and neither should own it: the Vite server binds through Node's `http`
  * (asynchronous `error` event), the Bun server binds through `Bun.serve` (synchronous throw). Two very
@@ -36,7 +36,7 @@ const asError = (err: unknown): Error => (err instanceof Error ? err : new Error
 export const explainBindFailure = (err: unknown, port: number): Error =>
   isAddressInUse(err) ? new Error(portInUseMessage(port)) : asError(err)
 
-/** The bits of a Node server {@link listenOrExplain} touches — structural, so a test can fake it. */
+/** The bits of a Node server {@link listenOrExplain} touches - structural, so a test can fake it. */
 export interface ListenTarget {
   listen(port: number, cb: () => void): void
   once(event: "error", cb: (err: unknown) => void): void
@@ -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

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web/dev` — the **Bun pipeline's** dev server: one toolchain, no Vite in the process.
+ * `@nifrajs/web/dev` - the **Bun pipeline's** dev server: one toolchain, no Vite in the process.
  *
  * nifra ships two dev pipelines and the rule between them is that a pipeline owns a whole phase. The
  * Vite server (`@nifrajs/web/vite`) is the default - mature framework plugins, and it resolves SSR as
@@ -7,12 +7,12 @@
  * and hot-reloads the client while Bun's runtime resolves SSR. Only one toolchain is present, so the two
  * cannot disagree.
  *
- * What you get: React Fast Refresh WITH state preserved — Bun's dev server applies it natively, no plugin
+ * What you get: React Fast Refresh WITH state preserved - Bun's dev server applies it natively, no plugin
  * (verified: editing a component-only module swaps its markup while a `useState` counter keeps its value,
  * no reload). The usual boundary rule still applies, and it is the same rule Vite has: a module whose
  * exports are all components is a refresh boundary, so a ROUTE file that also exports `loader`/`meta` is
  * not, and saving it does a clean full reload. Plus no Vite dependency and ONE bundler across dev and
- * production, which is the real prize — the dev/prod seam disappears.
+ * production, which is the real prize - the dev/prod seam disappears.
  *
  * What you give up: `*.module.css`. Bun's DEV-server bundler has no CSS-Modules transform (its production
  * `Bun.build` does), so the import compiles to a dangling reference. Plain CSS and Tailwind are fine. The
@@ -54,20 +54,22 @@ 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"
 
-/** Minimal app surface the dev server needs — `createWebApp(...)` satisfies it. */
+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>
 }
 
 export interface DevServerOptions extends Omit<BuildClientOptions, "minify"> {
   /**
-   * Build the nifra app for the current client entry. `importQuery` changes on every reload — pass it to
+   * Build the nifra app for the current client entry. `importQuery` changes on every reload - pass it to
    * `discoverRoutes(routesDir, { importQuery })` so SSR re-imports edited route modules instead of Bun's
    * cached copies.
    */
@@ -93,7 +95,7 @@ export interface DevServerOptions extends Omit<BuildClientOptions, "minify"> {
 export interface DevServer {
   readonly port: number
   /**
-   * The URL pages point their client entry at — always {@link CLIENT_ENTRY_PATH}, never Bun's hashed
+   * The URL pages point their client entry at - always {@link CLIENT_ENTRY_PATH}, never Bun's hashed
    * chunk. Deliberately not the underlying chunk URL: that one moves on every rebuild, and anything
    * holding onto it is holding onto a URL that will stop working.
    */
@@ -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>
@@ -154,7 +158,7 @@ function writeIfChanged(path: string, content: string): void {
   try {
     if (readFileSync(path, "utf8") === content) return
   } catch {
-    // missing or unreadable — fall through and write
+    // missing or unreadable - fall through and write
   }
   writeFileSync(path, content)
 }
@@ -196,13 +200,13 @@ export function writeDevFiles(options: WriteDevFilesOptions): void {
     // A bare relative path reads as a PACKAGE specifier to a bundler; `./` is what makes it a file.
     return rel.startsWith(".") ? rel : `./${rel}`
   }
-  // No `import.meta.hot.accept` here, deliberately. When an edit lands OUTSIDE a Fast Refresh boundary —
-  // a route file, which also exports `loader`/`meta` — Bun walks up to this generated entry, finds no
+  // No `import.meta.hot.accept` here, deliberately. When an edit lands OUTSIDE a Fast Refresh boundary -
+  // a route file, which also exports `loader`/`meta` - Bun walks up to this generated entry, finds no
   // `accept`, logs "hot update was not accepted" and does a full reload. That reload is correct: the route
   // module's non-component exports changed, so patching it into the live tree would be wrong. Accepting
   // here is worse than the warning: Bun re-evaluates the module BEFORE the accept callback runs, so the
   // entry re-executes against a container React already mounted ("createRoot() on a container that has
-  // already been passed to createRoot()") and only then does the callback get to reload — trading an
+  // already been passed to createRoot()") and only then does the callback get to reload - trading an
   // accurate warning for a real error. Editing a component-only module never reaches this path: Bun
   // applies React Fast Refresh there and state is preserved.
   writeIfChanged(entryPath, generateClientEntry(manifest, { clientModule, resolve: toSpecifier }))
@@ -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")
@@ -261,9 +269,9 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   const htmlModule = (await import(htmlPath)) as { default: HtmlBundle }
 
   let server: BunServerHandle
-  // The last resolved entry, with the time it was resolved. Deliberately short-lived — see `currentEntry`.
+  // The last resolved entry, with the time it was resolved. Deliberately short-lived - see `currentEntry`.
   let cache: { readonly entry: DevEntryMatch; readonly at: number } | undefined
-  // The app, tagged with the entry hash it was built against — see `appFor`.
+  // The app, tagged with the entry hash it was built against - see `appFor`.
   let built: { readonly entry: string; readonly app: FetchApp } | undefined
   let building: { readonly entry: string; readonly promise: Promise<FetchApp> } | undefined
   let version = 0
@@ -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
+  }
+}