@nifrajs/web 3.3.0 → 4.0.0

package/src/dev-sourcemap.ts

@@ -0,0 +1,281 @@
+/**
+ * Maps a browser stack trace back to source files, using the source maps the dev server itself
+ * serves (Bun links `/_bun/client/<gen>.js.map`; Vite inlines a data URL per module).
+ *
+ * Every fetch goes to the dev server's own origin, whatever host a frame names, so a crafted frame
+ * cannot make the server request anything else. Browser stacks in any engine's format come out as
+ * V8 `at` frames, which is what {@link parseFrames} reads.
+ */
+
+import { isAbsolute, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import {
+  decodeMappings,
+  inlineSourceMap,
+  lookupPosition,
+  type MappingLine,
+  originalPosition,
+  type RawSourceMap,
+} from "./internal/source-map.ts"
+
+export interface SourceMapperOptions {
+  readonly root: string
+  /** The dev server's own origin (`http://127.0.0.1:<port>`), or undefined before it listens. */
+  readonly origin: () => string | undefined
+  readonly fetch?: (url: string, init: { signal: AbortSignal }) => Promise<Response>
+  /** Decoded maps kept, most recently used first. */
+  readonly maxMaps?: number
+}
+
+export interface SourceMapper {
+  /** `stack` with each frame of a script this server served pointed at its source file. */
+  mapStack(stack: string): Promise<string>
+  /** Forget every map: the code they describe changed. */
+  clear(): void
+}
+
+interface Frame {
+  readonly name: string | undefined
+  readonly url: string
+  readonly line: number
+  readonly column: number
+}
+
+// V8: `    at fn (url:1:2)` / `    at url:1:2` / `    at async fn (url:1:2)`.
+const V8_FRAME = /^\s*at\s+(?:(.*?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/
+// SpiderMonkey / JavaScriptCore: `fn@url:1:2` / `@url:1:2`.
+const AT_FRAME = /^\s*(.*?)@(.+?):(\d+):(\d+)\s*$/
+const MAX_FRAMES = 50
+const SCRIPT_PATH = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|mdx)$/i
+const MAX_SCRIPT_BYTES = 64 * 1024 * 1024
+const FETCH_TIMEOUT_MS = 5_000
+
+function parseFrame(line: string): Frame | undefined {
+  const match = V8_FRAME.exec(line) ?? AT_FRAME.exec(line)
+  if (match === null) return undefined
+  const [, name, url = "", lineText = "", columnText = ""] = match
+  return {
+    name: name === undefined || name === "" ? undefined : name.replace(/^async\s+/, ""),
+    url,
+    line: Number(lineText),
+    column: Number(columnText),
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------------------------------
+
+export { decodeMappings } from "./internal/source-map.ts"
+
+interface DecodedMap {
+  readonly sources: readonly string[]
+  readonly lines: readonly (MappingLine | undefined)[]
+  readonly sourcesContent: readonly unknown[]
+  /** Per source, the map its content carries inline (a plugin's compile map), read on first use. */
+  readonly inner: Map<number, RawSourceMap | undefined>
+}
+
+/**
+ * The source position for a 0-based generated line/column. When the source is a plugin's output that
+ * carries its own map inline (a compiled `.svelte` or `.vue` file), that map is followed too: Bun's
+ * bundler keeps the plugin's output as the source, not the file it compiled.
+ */
+function lookup(
+  map: DecodedMap,
+  line: number,
+  column: number,
+): { source: string; line: number; column: number } | undefined {
+  const found = lookupPosition(map.lines, line, column)
+  if (found === undefined) return undefined
+  const source = map.sources[found.source]
+  if (source === undefined) return undefined
+  if (!map.inner.has(found.source)) {
+    const content = map.sourcesContent[found.source]
+    map.inner.set(found.source, typeof content === "string" ? inlineSourceMap(content) : undefined)
+  }
+  const inner = map.inner.get(found.source)
+  const original =
+    inner === undefined ? undefined : originalPosition(inner, found.line, found.column)
+  return original === undefined
+    ? { source, line: found.line, column: found.column }
+    : { source, line: original.line, column: original.column }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Fetching
+// ---------------------------------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+const SOURCE_MAPPING_URL = /[#@]\s*sourceMappingURL=([^\s'"]+)\s*$/
+
+function sourceMappingUrl(script: string): string | undefined {
+  // The comment is the last one in the file; a data URL can be megabytes, so look from the end.
+  const at = script.lastIndexOf("sourceMappingURL=")
+  if (at === -1) return undefined
+  const lineStart = script.lastIndexOf("\n", at) + 1
+  return SOURCE_MAPPING_URL.exec(script.slice(lineStart))?.[1]
+}
+
+function decodeDataUrl(url: string): string | undefined {
+  const comma = url.indexOf(",")
+  if (comma === -1) return undefined
+  const meta = url.slice(5, comma)
+  const payload = url.slice(comma + 1)
+  return meta.endsWith(";base64")
+    ? Buffer.from(payload, "base64").toString("utf8")
+    : decodeURIComponent(payload)
+}
+
+/**
+ * The directory a served script lives in on disk. Vite serves files outside the root as
+ * `/@fs/<absolute path>`; everything else maps onto the project root.
+ */
+function scriptDirectory(scriptPath: string, root: string): string {
+  const dir = decodeURIComponent(scriptPath.replace(/[^/]*$/, ""))
+  // `/@fs/C:/x/` names `C:/x/` on Windows: the slash before a drive letter is URL syntax only.
+  return dir.startsWith("/@fs/")
+    ? dir.slice("/@fs".length).replace(/^\/([a-zA-Z]:)/, "$1")
+    : resolve(root, `.${dir}`)
+}
+
+/** The filesystem path a map's source names, when it is a file. */
+function sourcePath(source: string, sourceRoot: string, scriptPath: string, root: string): string {
+  const joined = sourceRoot === "" ? source : `${sourceRoot.replace(/\/?$/, "/")}${source}`
+  if (joined.startsWith("file://")) {
+    try {
+      return fileURLToPath(joined)
+    } catch {
+      return joined
+    }
+  }
+  if (/^[a-z][a-z\d+.-]*:/i.test(joined)) return joined
+  if (isAbsolute(joined)) return joined
+  // Relative to the script's own location, as a map's sources always are.
+  return resolve(scriptDirectory(scriptPath, root), joined)
+}
+
+export function createSourceMapper(options: SourceMapperOptions): SourceMapper {
+  const root = resolve(options.root)
+  const fetchImpl = options.fetch ?? ((url, init) => fetch(url, init))
+  const maxMaps = options.maxMaps ?? 8
+  const maps = new Map<string, Promise<DecodedMap | undefined>>()
+
+  const fetchText = async (url: string): Promise<string | undefined> => {
+    const response = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+    if (!response.ok) return undefined
+    const length = Number(response.headers.get("content-length") ?? "0")
+    if (length > MAX_SCRIPT_BYTES) return undefined
+    const text = await response.text()
+    return text.length > MAX_SCRIPT_BYTES ? undefined : text
+  }
+
+  const load = async (origin: string, pathAndQuery: string): Promise<DecodedMap | undefined> => {
+    const scriptUrl = new URL(pathAndQuery, origin)
+    const script = await fetchText(scriptUrl.href)
+    if (script === undefined) return undefined
+    const reference = sourceMappingUrl(script)
+    if (reference === undefined) return undefined
+    let text: string | undefined
+    if (reference.startsWith("data:")) text = decodeDataUrl(reference)
+    else {
+      const mapUrl = new URL(reference, scriptUrl)
+      // Same server only: the map's URL comes from a script body, and a body is data.
+      if (mapUrl.origin !== scriptUrl.origin) return undefined
+      text = await fetchText(mapUrl.href)
+    }
+    if (text === undefined) return undefined
+    const raw: unknown = JSON.parse(text)
+    if (!isRecord(raw) || typeof raw.mappings !== "string" || !Array.isArray(raw.sources))
+      return undefined
+    const sourceRoot = typeof raw.sourceRoot === "string" ? raw.sourceRoot : ""
+    return {
+      sources: raw.sources.map((source) =>
+        typeof source === "string" ? sourcePath(source, sourceRoot, scriptUrl.pathname, root) : "",
+      ),
+      lines: decodeMappings(raw.mappings),
+      sourcesContent: Array.isArray(raw.sourcesContent) ? raw.sourcesContent : [],
+      inner: new Map(),
+    }
+  }
+
+  const mapFor = (origin: string, pathAndQuery: string): Promise<DecodedMap | undefined> => {
+    const cached = maps.get(pathAndQuery)
+    if (cached !== undefined) {
+      maps.delete(pathAndQuery)
+      maps.set(pathAndQuery, cached)
+      return cached
+    }
+    const loading = load(origin, pathAndQuery).catch(() => undefined)
+    maps.set(pathAndQuery, loading)
+    while (maps.size > maxMaps) {
+      const oldest = maps.keys().next().value
+      if (oldest === undefined) break
+      maps.delete(oldest)
+    }
+    return loading
+  }
+
+  /** The script's path on this server, when a frame names this server at all. */
+  const ownPath = (url: string, origin: string): string | undefined => {
+    let parsed: URL
+    try {
+      parsed = new URL(url)
+    } catch {
+      return undefined
+    }
+    const own = new URL(origin)
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return undefined
+    // `localhost:<port>` and `127.0.0.1:<port>` both reach this server; another port is another server.
+    if (parsed.port !== own.port) return undefined
+    const host = parsed.hostname
+    if (
+      host !== "localhost" &&
+      host !== "127.0.0.1" &&
+      host !== "[::1]" &&
+      !host.endsWith(".localhost")
+    )
+      return undefined
+    // Scripts only: fetching a page URL (an inline script's frame) would render it, loaders and all.
+    if (!SCRIPT_PATH.test(parsed.pathname)) return undefined
+    return `${parsed.pathname}${parsed.search}`
+  }
+
+  return {
+    async mapStack(stack) {
+      const origin = options.origin()
+      const lines = stack.split("\n")
+      const out: string[] = []
+      let frames = 0
+      for (const line of lines) {
+        const frame = parseFrame(line)
+        if (frame === undefined) {
+          // The message block (and engine noise between frames) stays as it was.
+          if (frames === 0) out.push(line)
+          continue
+        }
+        if (frames >= MAX_FRAMES) break
+        frames += 1
+        let location = `${frame.url}:${frame.line}:${frame.column}`
+        const path = origin === undefined ? undefined : ownPath(frame.url, origin)
+        if (origin !== undefined && path !== undefined) {
+          const map = await mapFor(origin, path)
+          const position =
+            map === undefined ? undefined : lookup(map, frame.line - 1, frame.column - 1)
+          if (position !== undefined && position.source !== "")
+            location = `${position.source}:${position.line}:${position.column}`
+        }
+        out.push(
+          frame.name === undefined ? `    at ${location}` : `    at ${frame.name} (${location})`,
+        )
+      }
+      return out.join("\n")
+    },
+    clear() {
+      maps.clear()
+    },
+  }
+}

package/src/dev-ssr-graph.ts

@@ -4,7 +4,7 @@
  * Bun's runtime caches every module it has evaluated, and nothing invalidates that cache on a file
  * change. The dev server's answer used to stop at the route module: `discoverRoutes({ importQuery })`
  * appends a changing query to each route's own dynamic import, so the route re-evaluates. Its imports
- * do not - a component, a helper, a `*.server` module all keep resolving to the same cached specifier,
+ * do not - a component, a helper, a backend module all keep resolving to the same cached specifier,
  * so SSR kept rendering the code that was on disk when the server started while the client, which Bun
  * rebuilds properly, rendered the edit. Every framework on this pipeline had it; the Vite pipeline does
  * not, because Vite owns its own SSR module graph.
@@ -46,8 +46,9 @@
  *
  * So the version is applied one level earlier, in the importer's own source: on load, each app-owned
  * module has its relative specifiers rewritten to absolute paths carrying the current version of the
- * file they point at. `onResolve` stays as well, because it is the only hook that sees modules loaded by
- * a third-party plugin this one does not wrap.
+ * file they point at - an alias such as `@/components/Button` too, resolved the way Bun resolves it.
+ * `onResolve` stays as well, because it is the only hook that sees modules loaded by a third-party plugin
+ * this one does not wrap.
  *
  * Old versions stay in Bun's registry - a bounded dev-only leak, one entry per edit, which is what the
  * route-level query already did.
@@ -104,6 +105,14 @@ const appSourceFilter = (root: string): RegExp => {
  */
 const SPECIFIER = /\b(from|import|require)((?:\s*\()?\s*)(["'])([^"'\n]+)\3/g
 
+/**
+ * A specifier that can name an app file: relative, absolute, or an alias an npm package name cannot be
+ * (`@/x`, `~/x`, `#x`, `$lib/x`). A bare package name is left alone - resolving one here would pin it
+ * for the life of the dev server, and a package is never app source anyway. An alias shaped like a
+ * package (`@app/x`, `src/x`) is not recognized.
+ */
+const APP_SPECIFIER = /^(?:[^a-z0-9@]|@[^a-z0-9])/i
+
 export interface SsrGraphOptions {
   /** The app root. Only files under it (and outside `node_modules`) are tracked. */
   readonly root: string
@@ -262,7 +271,9 @@ export function createSsrGraph(options: SsrGraphOptions): SsrGraph {
       // through untouched rather than adding a second, worse one.
       return contents
     }
-    const candidates = new Set(scanned.map((entry) => entry.path).filter((p) => p.startsWith(".")))
+    const candidates = new Set(
+      scanned.map((entry) => entry.path).filter((path) => APP_SPECIFIER.test(path)),
+    )
     if (candidates.size === 0) return contents
     const keys = new Map<string, string>()
     for (const specifier of candidates) {
@@ -289,7 +300,7 @@ export function createSsrGraph(options: SsrGraphOptions): SsrGraph {
       })
       // The resolver half covers what the loader half cannot see: a module compiled by a plugin that
       // does not call `rewriteSsrImports`. Extension-bearing specifiers only, which is all Bun offers.
-      build.onResolve({ filter: /^[./]/ }, (args) => {
+      build.onResolve({ filter: APP_SPECIFIER }, (args) => {
         if (resolving) return undefined
         // A specifier that already carries a query is either this module's own rewrite or a plugin's
         // virtual sub-request (`?vue-css` and friends) - both are already keyed.

package/src/dev.ts

@@ -14,7 +14,7 @@
  * 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.
  *
- * CSS Modules, server functions, and `*.server` modules use the same production transforms through the
+ * CSS Modules, server functions, and the zone guard use the same production transforms through the
  * generated Bun config. The CLI owns that config because Bun's HTML dev server accepts plugins only from
  * `[serve.static] plugins`; direct callers should pass the equivalent plugin through their Bun config.
  *
@@ -39,7 +39,7 @@
  *
  * SSR invalidation is Bun's import cache rather than Vite's module graph, so route modules are re-imported
  * under a changing query on each change - which is what `discoverRoutes({ importQuery })` exists for. That
- * query stops at the route file, so everything BELOW it - components, helpers, `*.server` modules - is
+ * query stops at the route file, so everything BELOW it - components, helpers, backend modules - is
  * tracked and re-keyed per module by `./dev-ssr-graph.ts`, or SSR would render the code that was on disk
  * when the server started.
  *
@@ -57,14 +57,16 @@ 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 { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { explainBindFailure } from "./dev-port.ts"
+import { createDevSession, type DevAppHooks, type DevSession } from "./dev-session.ts"
 import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEV_ENTRY_FILE } from "./internal/dev-reserved.ts"
 import { DEV_HMR_ENV, DEV_ROOT_ENV, DEV_ROUTES_ENV } from "./plugins/kit.ts"
 import { servePublicDir } from "./public-dir.ts"
 
+export type { DevAppHooks } from "./dev-session.ts"
 export { LAST_ERROR_PATH } from "./diagnostic.ts"
 
 /** Minimal app surface the dev server needs - `createWebApp(...)` satisfies it. */
@@ -76,9 +78,14 @@ export interface DevServerOptions extends Omit<BuildClientOptions, "minify"> {
   /**
    * 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.
+   * cached copies. Pass `dev.onLoaderError` to `createWebApp` so failures an `_error` boundary renders
+   * still reach the dev feed (`nifra errors`).
    */
-  readonly createApp: (clientEntry: string, importQuery: string) => FetchApp | Promise<FetchApp>
+  readonly createApp: (
+    clientEntry: string,
+    importQuery: string,
+    dev: DevAppHooks,
+  ) => FetchApp | Promise<FetchApp>
   /** Directories to watch (default: `[routesDir]`). */
   readonly watch?: readonly string[]
   /** Port to listen on (default {@link DEFAULT_DEV_PORT}). */
@@ -95,6 +102,16 @@ export interface DevServerOptions extends Omit<BuildClientOptions, "minify"> {
    * pass runs in the background off the hot path, so HMR is never waiting on it, and only reports.
    */
   readonly guardLeaks?: boolean
+  /**
+   * Write `.nifra/dev-server.json` (how `nifra errors`/`nifra logs` and the MCP tools find this server)
+   * and the persisted dev log beside it (default `true`).
+   */
+  readonly record?: boolean
+  /**
+   * Show the browser errors a dev page reports in a badge on that page, with a Copy prompt button per
+   * fix (default `true`). Off, the errors still reach the feed.
+   */
+  readonly indicator?: boolean
 }
 
 export interface DevServer {
@@ -293,10 +310,17 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   // (`devHotComponent`). Announced here rather than passed, for the same reason the flag above is.
   process.env[DEV_ROOT_ENV] = root
   process.env[DEV_ROUTES_ENV] = 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)
+  // Everything this server sees, for the agent driving it: failures (with the overlay's Diagnostic and
+  // LAST_ERROR_PATH riding on the same capture), console output, request traces and the discovery
+  // record. Shared with the Vite adapter so the two servers report identically.
+  const session = createDevSession({
+    root,
+    pipeline: "bun",
+    publicEnvPrefix: options.publicEnvPrefix,
+    record: options.record,
+    indicator: options.indicator,
+  })
+  const devHooks: DevAppHooks = { onLoaderError: session.onLoaderError }
   // SSR freshness BELOW the route module. The route-level `importQuery` only ever reloaded the route
   // itself; everything it imports is tracked here and re-keyed when it changes. Registered now because a
   // Bun runtime plugin only affects modules loaded after it, and the first route import is `appFor`
@@ -307,7 +331,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   const ssrGraph = createSsrGraph({ root })
   ;(await import("bun")).plugin(ssrGraph.plugin)
   const devDir = resolve(root, DEV_DIR)
-  const entryPath = resolve(devDir, "entry.tsx")
+  const entryPath = resolve(devDir, DEV_ENTRY_FILE)
   const htmlPath = resolve(devDir, "entry.html")
   const publicDir = options.publicDir === false ? undefined : (options.publicDir ?? "public")
   // Route dev's `public/` through the SAME handler production uses. Dev previously inherited this
@@ -378,15 +402,17 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
    * client leaks. It is no longer what keeps SSR correct.
    *
    * The entry hash is not the whole marker, though, because it only covers the CLIENT graph. A module
-   * the browser never receives - a `*.server` file, a loader's helper - can change without moving it, so
+   * the browser never receives - a backend module, a loader's helper - can change without moving it, so
    * the key also carries {@link SsrGraph} generation, which counts changes on the SERVER side. Either
    * one moving rebuilds the app, which is what re-imports the route modules under a fresh query.
    */
   const appFor = (key: string): Promise<FetchApp> => {
     if (built?.key === key) return Promise.resolve(built.app)
     if (building?.key === key) return building.promise
+    // A new key means the code moved since the last build: what the feed recorded before is stale.
+    if (version > 0) session.markChange()
     version += 1
-    const promise = Promise.resolve(createApp(CLIENT_ENTRY_PATH, `v=${version}`))
+    const promise = Promise.resolve(createApp(CLIENT_ENTRY_PATH, `v=${version}`, devHooks))
     building = { key, promise }
     void promise
       .then((next) => {
@@ -408,6 +434,37 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
     return appFor(`${entrySrc}#${ssrGraph.generation()}`)
   }
 
+  const renderApp = async (req: Request, url: URL): Promise<Response> => {
+    try {
+      // One fresh probe per request: it is both the freshness check for SSR and the stylesheet list,
+      // so the page cannot be rendered against a build the browser is not about to load.
+      const entry = await currentEntry(true)
+      const res = await (await appForRequest(entry.src)).fetch(req)
+      if (!(res.headers.get("content-type") ?? "").includes("text/html")) return res
+      if (entry.styles.length === 0) return session.decoratePage(req, res)
+      const headers = new Headers(res.headers)
+      headers.delete("content-length") // the body grows with the injected stylesheet links
+      return session.decoratePage(
+        req,
+        new Response(injectStyles(await res.text(), entry.styles), {
+          status: res.status,
+          headers,
+        }),
+      )
+    } catch (err) {
+      // One Diagnostic drives every surface: the overlay returned here, the JSON at LAST_ERROR_PATH and
+      // the feed's `ssr` entry.
+      const html = session.failure(err, {
+        method: req.method,
+        url: `${url.pathname}${url.search}`,
+      })
+      return new Response(html, {
+        status: 500,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      })
+    }
+  }
+
   try {
     server = serve({
       port,
@@ -427,11 +484,9 @@ 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 })
-        }
+        // The agent endpoints (errors, logs, requests, identity, last-error): shared surface.
+        const agent = await session.handle(req)
+        if (agent !== undefined) return agent
         // Static probe before routing; a miss returns undefined and falls through, so no route is
         // shadowed. Every GET/HEAD pays the probe, including page renders and API routes: the handler
         // serves extension-less files too (an ACME challenge token is the reason), so there is no
@@ -439,33 +494,11 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
         // mounting this handler itself can pass `files` to answer a miss without touching the disk.
         const staticFile = await servePublic(req)
         if (staticFile !== undefined) return staticFile
-        try {
-          // One fresh probe per request: it is both the freshness check for SSR and the stylesheet list,
-          // so the page cannot be rendered against a build the browser is not about to load.
-          const entry = await currentEntry(true)
-          const res = await (await appForRequest(entry.src)).fetch(req)
-          if (!(res.headers.get("content-type") ?? "").includes("text/html")) return res
-          if (entry.styles.length === 0) return res
-          const headers = new Headers(res.headers)
-          headers.delete("content-length") // the body grows with the injected stylesheet links
-          return new Response(injectStyles(await res.text(), entry.styles), {
-            status: res.status,
-            headers,
-          })
-        } catch (err) {
-          // 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" },
-          })
-        }
+        return session.track(req, () => renderApp(req, url))
       },
     })
   } catch (err) {
+    session.stop()
     // `Bun.serve` throws synchronously on a bind failure; the Vite path's equivalent arrives as an async
     // `error` event. Same explanation either way - see ./dev-port.ts for why it is worth spelling out.
     throw explainBindFailure(err, port)
@@ -479,10 +512,12 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
     // Leaving the server up would answer 500s forever, which presents as a running server rather than as
     // the startup failure it is.
     server.stop(true)
+    session.stop()
     throw err
   }
+  session.listening(server.port ?? port)
 
-  const guard = options.guardLeaks !== false ? leakGuard(options) : undefined
+  const guard = options.guardLeaks !== false ? leakGuard(options, session) : undefined
   guard?.()
 
   // What is left for the watcher, now that request ordering keeps SSR fresh: regenerate the client entry
@@ -494,11 +529,16 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   const onChange = (): void => {
     if (timer) clearTimeout(timer)
     timer = setTimeout(() => {
+      // A deletion its own watcher reported is unwatched now, or the next topology poll reports it
+      // again as a second change: another regeneration and another leak-guard build.
+      syncWatchedFiles(false)
+      session.markChange()
       try {
         writeDevFiles({ routesDir, clientModule, entryPath, htmlPath })
       } catch (err) {
         // A half-saved file can fail the scan mid-edit; the next change re-runs this.
         console.error("[nifra/web/dev] client entry regeneration failed:", err)
+        session.buildFailed(err, "client entry regeneration failed")
       }
       guard?.()
     }, 60)
@@ -552,6 +592,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       for (const file of watched) unwatchFile(file)
       ssrGraph.dispose()
       server.stop(true)
+      session.stop()
       rmSync(devDir, { recursive: true, force: true })
       // Put the dev-phase env flags back the way this server found them (see `priorDevEnv`).
       for (const [key, prior] of Object.entries(priorDevEnv)) {
@@ -585,7 +626,7 @@ export function buildFailureDetail(err: unknown): string {
     : `  ${err instanceof Error ? err.message : String(err)}`
 }
 
-function leakGuard(options: DevServerOptions): () => void {
+function leakGuard(options: DevServerOptions, session: DevSession): () => void {
   let running = false
   let queued = false
   const run = (): void => {
@@ -595,11 +636,13 @@ function leakGuard(options: DevServerOptions): () => void {
     }
     running = true
     buildClient({ ...options, minify: false })
+      .then(() => session.buildPassed())
       .catch((err: unknown) => {
         console.error(
           `\n[nifra/web/dev] client-leak guard failed:\n${buildFailureDetail(err)}\n` +
             "  The dev server is still running. This will fail `nifra build`.\n",
         )
+        session.buildFailed(err, "client build failed (this will fail `nifra build`)")
       })
       .finally(() => {
         running = false