@nifrajs/web 3.5.0 → 4.0.2

package/src/csp.ts

@@ -0,0 +1,194 @@
+import { PRE_HYDRATION_GUARD } from "./internal/runtime-contract.ts"
+import { createNonceResolver, type NonceResolver } from "./nonce.ts"
+import type { RenderAdapter } from "./render-seam.ts"
+
+/** What {@link CreateCspPolicyOptions.header} receives for one document. */
+export interface CspHeaderContext {
+  /**
+   * The `script-src` sources this document needs, space-separated: a `'sha256-…'` hash for each
+   * constant inline script nifra writes, plus `'nonce-…'` when the document carries a script that is
+   * specific to this request. External scripts (the client entry, route chunks, islands) are not
+   * listed: allow their origin, usually `'self'`.
+   */
+  readonly sources: string
+  /** The nonce, when this document carries one. Such a document is `private, no-store`. */
+  readonly nonce?: string
+}
+
+export interface CreateCspPolicyOptions {
+  /**
+   * Build the complete Content-Security-Policy value for one document, or `undefined` to send none:
+   *
+   * ```ts
+   * header: ({ sources }) => `default-src 'self'; script-src 'self' ${sources}; object-src 'none'`
+   * ```
+   */
+  readonly header: (context: CspHeaderContext) => string | undefined
+  /** Generate the nonce for a document that needs one. Default: 122 random bits, CSP base64-safe. */
+  readonly generate?: () => string
+}
+
+const CSP_POLICY: unique symbol = Symbol.for("nifra.web.cspPolicy")
+
+/** How a `createWebApp` app's documents meet a CSP: `"nonce"` (every document carries one, so none is
+ * cacheable) or `"hash"` (a {@link CspPolicy}). Read by wrappers that cache documents. */
+export const DOCUMENT_POLICY: unique symbol = Symbol.for("nifra.web.documentPolicy")
+
+/** The hash sources for one adapter, and the hydration head they were computed from. */
+interface AdapterSources {
+  readonly head: string
+  readonly sources: string
+}
+
+interface CspPolicyState {
+  readonly header: (context: CspHeaderContext) => string | undefined
+  readonly generate: () => string
+  readonly adapters: WeakMap<RenderAdapter, AdapterSources | Promise<AdapterSources>>
+}
+
+/**
+ * A hash-based Content-Security-Policy for nifra documents - see {@link createCspPolicy}. Opaque: pass
+ * it to `createWebApp({ csp })` or `renderPage({ csp })`.
+ */
+export interface CspPolicy {
+  readonly [CSP_POLICY]: CspPolicyState
+}
+
+/**
+ * Create a hash-based Content-Security-Policy for nifra documents, so a page can carry a strict CSP
+ * and still be cached.
+ *
+ * A per-request nonce makes every document unique: nifra marks a nonce-bearing document
+ * `private, no-store`, so no shared cache (ISR, a CDN) may store it. Under this policy a document
+ * gets a nonce only when it carries a script specific to this request: a page that `defer()`s streams
+ * one per settled value, and `unsafeInlineScript` names the nonce. Every other document is nonce-free.
+ * Its inline scripts are the constant ones nifra writes, listed by hash, so the CSP header is the
+ * same on every request and the page stays cacheable. Page data rides in an inert JSON script, which
+ * a CSP does not govern.
+ *
+ * ```ts
+ * const csp = createCspPolicy({
+ *   header: ({ sources }) => `default-src 'self'; script-src 'self' ${sources}; object-src 'none'`,
+ * })
+ * const app = createWebApp({ adapter, manifest, clientEntry, csp })
+ * ```
+ */
+export function createCspPolicy(options: CreateCspPolicyOptions): CspPolicy {
+  if (typeof options?.header !== "function") {
+    throw new TypeError("[nifra/web] createCspPolicy requires a header function")
+  }
+  return {
+    [CSP_POLICY]: {
+      header: options.header,
+      // A UUID's hyphens are outside the CSP base64-value grammar; the remaining 122 random bits are
+      // plenty for a per-response nonce, on every fetch runtime.
+      generate: options.generate ?? (() => crypto.randomUUID().replaceAll("-", "")),
+      adapters: new WeakMap(),
+    },
+  }
+}
+
+/** True for a value made by {@link createCspPolicy}. */
+export const isCspPolicy = (value: unknown): value is CspPolicy =>
+  typeof value === "object" && value !== null && CSP_POLICY in value
+
+// A closing tag ends at any space, slash or `>` after its name, as a browser reads it.
+const INLINE_SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script(?=[\s/>])[^>]*>/gi
+
+/** The bodies of the executable inline scripts in a fragment of markup (no `src`, no inert type). */
+const inlineScriptBodies = (html: string): string[] => {
+  const bodies: string[] = []
+  for (const match of html.matchAll(INLINE_SCRIPT)) {
+    const attrs = match[1] ?? ""
+    if (/\bsrc\s*=/i.test(attrs) || /\btype\s*=\s*["']?application\/(ld\+)?json/i.test(attrs))
+      continue
+    bodies.push(match[2] ?? "")
+  }
+  return bodies
+}
+
+const ENCODER = new TextEncoder()
+
+/** A CSP hash source for one inline script body: `'sha256-<base64 of the UTF-8 bytes>'`. */
+async function hashSource(body: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", ENCODER.encode(body)))
+  let binary = ""
+  for (const byte of digest) binary += String.fromCharCode(byte)
+  return `'sha256-${btoa(binary)}'`
+}
+
+/**
+ * The `'sha256-…'` sources for the constant inline scripts nifra writes into a document rendered
+ * with `adapter`: the pre-hydration form guard and the adapter's hydration head. For a CSP set outside
+ * the app (a proxy, a CDN rule); {@link createCspPolicy} computes the same list itself.
+ */
+export async function nifraScriptHashes(adapter: RenderAdapter): Promise<readonly string[]> {
+  const bodies = [PRE_HYDRATION_GUARD, ...inlineScriptBodies(adapter.hydrationHead())]
+  return Promise.all([...new Set(bodies)].map(hashSource))
+}
+
+/**
+ * Compute (once per adapter) the policy's hash sources. Returns `undefined` once they are ready, so
+ * the renderer stays synchronous after the first document.
+ */
+export function prepareCspPolicy(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+): Promise<void> | undefined {
+  const state = policy[CSP_POLICY]
+  const known = state.adapters.get(adapter)
+  if (known !== undefined) return known instanceof Promise ? known.then(() => undefined) : undefined
+  const head = adapter.hydrationHead()
+  const pending = nifraScriptHashes(adapter).then((hashes) => {
+    const sources = { head, sources: hashes.join(" ") }
+    state.adapters.set(adapter, sources)
+    return sources
+  })
+  state.adapters.set(adapter, pending)
+  // A failed digest must not pin a rejected promise: the next document retries.
+  pending.catch(() => state.adapters.delete(adapter))
+  return pending.then(() => undefined)
+}
+
+const preparedSources = (policy: CspPolicy, adapter: RenderAdapter): AdapterSources => {
+  const known = policy[CSP_POLICY].adapters.get(adapter)
+  if (known === undefined || known instanceof Promise) {
+    throw new Error("[nifra/web] CSP policy used before prepareCspPolicy resolved")
+  }
+  return known
+}
+
+/**
+ * The nonce one document carries under `policy`: `undefined` unless the document needs one -
+ * `needsNonce` (a deferred value or a head tag naming the nonce), or an adapter whose hydration head
+ * no longer matches the one the policy hashed. A needed nonce reuses the caller's, else is generated.
+ */
+export function cspDocumentNonce(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+  hydrate: boolean,
+  needsNonce: boolean,
+  requested: string | undefined,
+): string | undefined {
+  const varies = hydrate && adapter.hydrationHead() !== preparedSources(policy, adapter).head
+  if (!needsNonce && !varies) return undefined
+  return requested ?? policy[CSP_POLICY].generate()
+}
+
+/** The Content-Security-Policy value for one document, or `undefined` when the policy sends none. */
+export function cspHeaderValue(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+  nonce: string | undefined,
+): string | undefined {
+  const { sources } = preparedSources(policy, adapter)
+  const state = policy[CSP_POLICY]
+  return nonce === undefined
+    ? state.header({ sources })
+    : state.header({ sources: `${sources} 'nonce-${nonce}'`, nonce })
+}
+
+/** The per-request nonce source for a page executor under `policy`: generated eagerly so `meta` can
+ * name it in `unsafeInlineScript`, and dropped by the renderer from documents that do not need it. */
+export const cspNonceResolver = (policy: CspPolicy): NonceResolver =>
+  createNonceResolver({ generate: () => policy[CSP_POLICY].generate() })

package/src/dev-client.ts

@@ -0,0 +1,349 @@
+/**
+ * The browser half of the dev feed: a small inline script a dev server puts first in each page's
+ * `<head>`, so the agent sees what the page did after it left the server - uncaught errors, unhandled
+ * rejections, failed script/stylesheet loads, hydration mismatches and console output.
+ *
+ * Inline and first, rather than a module, so it is listening before any module (the framework, the
+ * HMR client, the app) runs. Dev only: nothing here is reachable from a production build.
+ */
+
+import { createHash } from "node:crypto"
+import { type DevLogLevel, isDevLogLevel } from "./dev-feed.ts"
+import { admitInlineScript } from "./internal/dev-csp.ts"
+
+export interface DevClientConfig {
+  /** Where the batches go (same origin). */
+  readonly ingestPath: string
+  /** Proves a batch came from a page this server served. */
+  readonly pageToken: string
+  /** The request that rendered this document: browser entries from it carry the same id. */
+  readonly requestId?: string | undefined
+  /** The document's path + search, so a client-side navigation away stops claiming that request. */
+  readonly documentPath?: string | undefined
+  /** The issues indicator module, loaded on the first error the server answers for; none when off. */
+  readonly indicatorPath?: string | undefined
+}
+
+// ES2017, no dependencies, one global: `__nifraDevClient`, the idempotence flag that also queues issues
+// for the indicator module. Keep it small: it ships in every dev page, and its hash goes into every CSP
+// that needs one.
+const CLIENT_SOURCE = String.raw`(function(C){
+if(window.__nifraDevClient)return;var S=window.__nifraDevClient={issues:[]};
+var nonce=document.currentScript&&document.currentScript.nonce,loading=0;
+var q=[],timer=0,inside=0,MSG=8000,STACK=16000;
+function cap(s,n){s=String(s);return s.length>n?s.slice(0,n)+"...":s}
+function where(){return location.pathname+location.search}
+function ser(v,d){
+if(typeof v==="string")return v;
+if(v instanceof Error)return v.stack||v.name+": "+v.message;
+if(typeof v==="function")return"[Function "+(v.name||"anonymous")+"]";
+if(typeof v!=="object"||v===null)return String(v);
+if(typeof Element!=="undefined"&&v instanceof Element)return"<"+v.tagName.toLowerCase()+(v.id?"#"+v.id:"")+">";
+if(d>2)return Array.isArray(v)?"[Array]":"[Object]";
+var seen=[];
+try{return JSON.stringify(v,function(k,x){
+if(typeof x==="object"&&x!==null){if(seen.indexOf(x)!==-1)return"[Circular]";seen.push(x)}
+if(typeof x==="bigint")return x+"n";
+if(x instanceof Error)return x.name+": "+x.message;
+return x})}catch(e){return Object.prototype.toString.call(v)}}
+function fmt(a){
+var args=Array.prototype.slice.call(a),out=[];
+if(typeof args[0]==="string"&&args[0].indexOf("%")!==-1){
+var rest=args.slice(1);
+out.push(args[0].replace(/%([sdifoOjc%])/g,function(m,k){
+if(k==="%")return"%";
+if(!rest.length)return m;
+var v=rest.shift();
+if(k==="c")return"";
+if(k==="d"||k==="i")return String(parseInt(v,10));
+if(k==="f")return String(parseFloat(v));
+return ser(v,0)}));
+args=rest}
+for(var i=0;i<args.length;i++)out.push(ser(args[i],0));
+return out.join(" ")}
+function send(keep){
+clearTimeout(timer);timer=0;
+while(q.length){
+var body=JSON.stringify({token:C.t,events:q.splice(0,50)});
+try{fetch(C.u,{method:"POST",body:body,keepalive:!!keep&&body.length<60000,headers:{"content-type":"application/json"},credentials:"same-origin"}).then(function(r){if(r.status===200&&C.i)return r.json().then(issues)}).catch(function(){})}catch(e){}}}
+function issues(j){
+var list=j&&j.issues;if(!list||!list.length)return;
+if(S.indicator){S.indicator.add(list);return}
+S.issues=S.issues.concat(list);if(loading)return;loading=1;
+var s=document.createElement("script");s.type="module";s.src=C.i;if(nonce)s.nonce=nonce;
+(document.head||document.documentElement).appendChild(s)}
+function push(e){
+e.page=cap(where(),2000);
+if(C.r&&e.page===C.p)e.requestId=C.r;
+q.push(e);
+if(q.length>=50)send(false);else if(!timer)timer=setTimeout(send,100)}
+["debug","info","log","warn","error"].forEach(function(level){
+var orig=console[level];if(typeof orig!=="function")return;
+console[level]=function(){
+if(!inside){inside=1;try{
+var ev={kind:"console",level:level,message:cap(fmt(arguments),MSG)};
+if(level==="error")for(var i=0;i<arguments.length;i++){var x=arguments[i];
+if(x instanceof Error){ev.error={name:cap(x.name,200),message:cap(x.message,MSG),stack:cap(x.stack||"",STACK)};break}}
+push(ev)}catch(e){}inside=0}
+return orig.apply(this,arguments)}});
+addEventListener("error",function(ev){
+var t=ev.target;
+if(t&&t!==window&&t.tagName){
+var tag=t.tagName.toLowerCase(),rel=(t.rel||"").toLowerCase();
+if(tag==="script"||(tag==="link"&&/stylesheet|modulepreload|preload/.test(rel)))push({kind:"resource",tag:tag,url:cap(t.src||t.href||"",2000)});
+return}
+var e=ev.error;
+if(!e&&ev.message==="Script error.")return;
+push({kind:"error",name:cap(e&&e.name?e.name:"Error",200),message:cap(e&&e.message!=null?e.message:ev.message,MSG),
+stack:cap(e&&e.stack?e.stack:(ev.filename?"    at "+ev.filename+":"+ev.lineno+":"+ev.colno:""),STACK)})},true);
+addEventListener("unhandledrejection",function(ev){
+var r=ev.reason;
+if(r instanceof Error)push({kind:"rejection",name:cap(r.name,200),message:cap(r.message,MSG),stack:cap(r.stack||"",STACK)});
+else push({kind:"rejection",name:"UnhandledRejection",message:cap(ser(r,0),MSG)})});
+addEventListener("pagehide",function(){send(true)});
+document.addEventListener("visibilitychange",function(){if(document.visibilityState==="hidden")send(true)});
+})`
+
+// `</script` inside a JSON value would end the element early; `<!--` can start a script-data escape.
+const scriptSafe = (json: string): string =>
+  json
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029")
+
+/** The script's text (without the `<script>` element). */
+export function devClientSource(config: DevClientConfig): string {
+  const settings: Record<string, string> = { u: config.ingestPath, t: config.pageToken }
+  if (config.indicatorPath !== undefined) settings.i = config.indicatorPath
+  if (config.requestId !== undefined && config.documentPath !== undefined) {
+    settings.r = config.requestId
+    settings.p = config.documentPath
+  }
+  return `${CLIENT_SOURCE}(${scriptSafe(JSON.stringify(settings))})`
+}
+
+/** The CSP source that admits exactly `source`. */
+export function scriptHash(source: string): string {
+  return `'sha256-${createHash("sha256").update(source).digest("base64")}'`
+}
+
+/** Whether a response is a page the script belongs in: HTML, with a body nobody has encoded yet. */
+export function isInjectablePage(response: Response, method: string): boolean {
+  if (method === "HEAD" || response.body === null) return false
+  if (response.status === 204 || response.status === 304) return false
+  if (response.headers.has("content-encoding")) return false
+  return (response.headers.get("content-type") ?? "").toLowerCase().includes("text/html")
+}
+
+/**
+ * Prepare `headers` for the script: admit it in the page's CSP, by hash unless `nonced` (the caller
+ * puts a nonce on every script afterwards). Returns the `<script>` element to insert, or undefined
+ * when the page's CSP forbids scripts and nothing should be inserted.
+ */
+export function devClientTag(
+  config: DevClientConfig,
+  headers: Headers,
+  origin: string,
+  nonced = false,
+): string | undefined {
+  const source = devClientSource(config)
+  const hash = nonced ? undefined : scriptHash(source)
+  // A nonced client hands its nonce to the module it loads, so only a hashed one needs the URL admitted.
+  const indicator =
+    nonced || config.indicatorPath === undefined ? undefined : new URL(config.indicatorPath, origin)
+  if (!admitInlineScript(headers, hash, new URL(config.ingestPath, origin), indicator))
+    return undefined
+  return `<script data-nifra-dev>${source}</script>`
+}
+
+// Latin-1 views keep string offsets equal to byte offsets, so a match position is a splice point.
+const latin1 = new TextDecoder("latin1")
+const HEAD_OPEN = /<head(?:\s[^>]*)?>/i
+const META_CHARSET = /^\s*<meta\s[^>]*charset\s*=[^>]*>/i
+// Past this, a page without `<head>` is a fragment: stop looking and stream it as it is.
+const HEAD_SEARCH_LIMIT = 64 * 1024
+// Enough to see a `<meta charset>` that immediately follows `<head>`.
+const META_LOOKAHEAD = 256
+
+/** Where the script goes in `text`: after `<head>`, and after a `<meta charset>` that leads it. */
+function insertionPoint(text: string, final: boolean): number | "wait" | "none" {
+  const head = HEAD_OPEN.exec(text)
+  if (head === null) {
+    const body = /<body[\s>]/i.test(text)
+    return final || body || text.length > HEAD_SEARCH_LIMIT ? "none" : "wait"
+  }
+  const afterHead = head.index + head[0].length
+  const rest = text.slice(afterHead)
+  const meta = META_CHARSET.exec(rest)
+  if (meta !== null) return afterHead + meta[0].length
+  if (!final && rest.length < META_LOOKAHEAD && !/<(?!meta)/i.test(rest.replace(/^\s+/, "")))
+    return "wait"
+  return afterHead
+}
+
+/** `html` with `tag` inserted into its head; unchanged when there is no `<head>`. */
+export function injectIntoHtml(html: string, tag: string): string {
+  const at = insertionPoint(html, true)
+  return typeof at === "number" ? html.slice(0, at) + tag + html.slice(at) : html
+}
+
+function concat(chunks: readonly Uint8Array[], length: number): Uint8Array {
+  const out = new Uint8Array(length)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+/**
+ * Stream `body` with `tag` inserted into its head. Only the prefix up to the insertion point is held
+ * back; the rest streams through untouched, so a streamed SSR page keeps its first-byte time.
+ */
+export function injectIntoStream(
+  body: ReadableStream<Uint8Array>,
+  tag: string,
+): ReadableStream<Uint8Array> {
+  const insert = new TextEncoder().encode(tag)
+  const held: Uint8Array[] = []
+  let heldBytes = 0
+  let done = false
+  const release = (
+    controller: TransformStreamDefaultController<Uint8Array>,
+    final: boolean,
+  ): void => {
+    const bytes = concat(held, heldBytes)
+    const at = insertionPoint(latin1.decode(bytes), final)
+    if (at === "wait") return
+    held.length = 0
+    heldBytes = 0
+    done = true
+    if (at === "none") {
+      controller.enqueue(bytes)
+      return
+    }
+    controller.enqueue(bytes.subarray(0, at))
+    controller.enqueue(insert)
+    controller.enqueue(bytes.subarray(at))
+  }
+  return body.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        if (done) {
+          controller.enqueue(chunk)
+          return
+        }
+        held.push(chunk)
+        heldBytes += chunk.byteLength
+        release(controller, false)
+      },
+      flush(controller) {
+        if (!done && heldBytes > 0) release(controller, true)
+      },
+    }),
+  )
+}
+
+// ---------------------------------------------------------------------------------------------------
+// What the script sends
+// ---------------------------------------------------------------------------------------------------
+
+/** One batch is bounded by what `fetch(keepalive)` may carry. */
+export const CLIENT_BATCH_MAX_BYTES = 64 * 1024
+export const CLIENT_BATCH_MAX_EVENTS = 50
+
+interface EventContext {
+  readonly page: string
+  readonly requestId?: string | undefined
+}
+
+export interface BrowserError {
+  readonly name: string
+  readonly message: string
+  readonly stack: string
+}
+
+export type ClientEvent = EventContext &
+  (
+    | {
+        readonly kind: "error" | "rejection"
+        readonly name: string
+        readonly message: string
+        readonly stack: string
+      }
+    | { readonly kind: "resource"; readonly tag: string; readonly url: string }
+    | {
+        readonly kind: "console"
+        readonly level: DevLogLevel
+        readonly message: string
+        /** The first Error a `console.error` call was given: frameworks report caught errors so. */
+        readonly error?: BrowserError | undefined
+      }
+  )
+
+export interface ClientBatch {
+  readonly token: string
+  readonly events: readonly ClientEvent[]
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const text = (value: unknown, max: number): string | undefined =>
+  typeof value === "string" ? value.slice(0, max) : undefined
+
+// The script only ever tags an event with the id the server put in it; anything else is dropped.
+const REQUEST_ID = /^r\d{1,12}$/
+
+function parseBrowserError(value: unknown): BrowserError | undefined {
+  if (!isRecord(value)) return undefined
+  const message = text(value.message, 8 * 1024)
+  if (message === undefined) return undefined
+  return {
+    name: text(value.name, 200) || "Error",
+    message,
+    stack: text(value.stack, 16 * 1024) ?? "",
+  }
+}
+
+function parseEvent(value: unknown): ClientEvent | undefined {
+  if (!isRecord(value)) return undefined
+  const page = text(value.page, 2048)
+  if (page === undefined || !page.startsWith("/")) return undefined
+  const requestId =
+    typeof value.requestId === "string" && REQUEST_ID.test(value.requestId)
+      ? value.requestId
+      : undefined
+  if (value.kind === "error" || value.kind === "rejection") {
+    const error = parseBrowserError(value)
+    return error === undefined ? undefined : { kind: value.kind, ...error, page, requestId }
+  }
+  if (value.kind === "resource") {
+    const tag = text(value.tag, 20)
+    const url = text(value.url, 2048)
+    if (tag === undefined || url === undefined) return undefined
+    return { kind: "resource", tag, url, page, requestId }
+  }
+  if (value.kind === "console") {
+    const message = text(value.message, 8 * 1024)
+    if (message === undefined || !isDevLogLevel(value.level)) return undefined
+    const error = parseBrowserError(value.error)
+    return { kind: "console", level: value.level, message, error, page, requestId }
+  }
+  return undefined
+}
+
+/** A batch the script could have sent, or undefined. Malformed events are dropped, not fatal. */
+export function parseClientBatch(value: unknown): ClientBatch | undefined {
+  if (!isRecord(value) || typeof value.token !== "string" || !Array.isArray(value.events))
+    return undefined
+  if (value.events.length > CLIENT_BATCH_MAX_EVENTS) return undefined
+  const events: ClientEvent[] = []
+  for (const raw of value.events) {
+    const event = parseEvent(raw)
+    if (event !== undefined) events.push(event)
+  }
+  return { token: value.token, events }
+}

package/src/dev-diagnostics.ts

@@ -8,8 +8,34 @@
  *
  * Vite once shipped without the `/__nifra/last-error` endpoint at all - the drift this module prevents.
  */
+import { relative } from "node:path"
 import { renderDiagnosticOverlay } from "./dev-error.ts"
-import { buildDiagnostic, type Diagnostic, LAST_ERROR_PATH } from "./diagnostic.ts"
+import { buildDiagnostic, type Diagnostic, fixPrompts, LAST_ERROR_PATH } from "./diagnostic.ts"
+import { browserDenial, createZoneClassifier } from "./zones.ts"
+
+const CODEFRAME_SOURCE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|mdx)$/i
+
+/**
+ * Whether a codeframe may show `file` (the canonical path it would read) to a browser: source in a
+ * browser zone. A page reports its own stack frames, so it can name any path: data files and the dev
+ * server's own `.nifra/` files (the discovery record holds the agent token) never qualify.
+ */
+export function createSourceGate(root: string): (file: string) => boolean {
+  const zones = createZoneClassifier({ appRoot: root })
+  return (file) => {
+    if (!CODEFRAME_SOURCE.test(file)) return false
+    if ((relative(zones.appRoot, file).split(/[\\/]/)[0] ?? "").startsWith(".nifra")) return false
+    return browserDenial(zones.classify(file)) === undefined
+  }
+}
+
+/** A failure as the dev feed recorded it: the entry and request let its agent prompt name a check. */
+export interface CapturedFailure {
+  readonly diagnostic: Diagnostic
+  readonly entry?: { readonly id: string; readonly seq: number } | undefined
+  readonly requestId?: string | undefined
+  readonly category?: string | undefined
+}
 
 export interface DevDiagnostics {
   /** True when a request path targets the structured last-error endpoint. */
@@ -20,12 +46,36 @@ export interface DevDiagnostics {
   /** 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
+  /** The overlay HTML for a failure the feed already recorded, which also becomes the last error. */
+  show(captured: CapturedFailure): 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 {
+ * to the project (see buildDiagnostic). Both dev servers resolve a concrete root before calling this.
+ * `build` replaces the default Diagnostic builder: the dev session passes one that also records the
+ * failure in its feed (redacted), so the overlay, this endpoint and the feed show the same object. */
+export function createDevDiagnostics(
+  root: string,
+  build?: (
+    err: unknown,
+    request: { readonly method: string; readonly url: string },
+  ) => CapturedFailure,
+): DevDiagnostics {
   let last: Diagnostic | undefined
+  const showSource = createSourceGate(root)
+  const show = (captured: CapturedFailure): string => {
+    last = captured.diagnostic
+    return renderDiagnosticOverlay(
+      last,
+      fixPrompts(last, {
+        surface: "overlay",
+        root,
+        entry: captured.entry,
+        requestId: captured.requestId,
+        category: captured.category ?? "ssr",
+      }),
+    )
+  }
   return {
     isLastErrorPath: (pathname) => pathname === LAST_ERROR_PATH,
     lastError: () => ({
@@ -39,9 +89,12 @@ export function createDevDiagnostics(root: string): DevDiagnostics {
         "x-nifra-diagnostic": "true",
       },
     }),
-    capture: (err, request) => {
-      last = buildDiagnostic(err, { root, request })
-      return renderDiagnosticOverlay(last)
-    },
+    capture: (err, request) =>
+      show(
+        build?.(err, request) ?? {
+          diagnostic: buildDiagnostic(err, { root, request, showSource }),
+        },
+      ),
+    show,
   }
 }