@webjsdev/server 0.8.15 → 0.8.17

package/index.d.ts

@@ -91,6 +91,15 @@ export interface RequestHandlerOptions {
     error: unknown,
     ctx: { request: Request; requestId: string | null; phase: string },
   ) => void;
+  /** Called when a dev source change has been applied (the live-reload trigger). */
+  onReload?: () => void;
+  /**
+   * Dev error overlay sink (#264): called with a structured error frame when a
+   * dev render crash, a non-erasable-TS strip failure, or a failed rebuild
+   * occurs. `startServer` wires this to the SSE overlay channel. Dev-only and
+   * best-effort; never fires in prod.
+   */
+  onDevError?: (frame: object) => void;
 }
 
 /** A matched page route for a path, as returned by `routeFor`. */
@@ -110,6 +119,8 @@ export interface RequestHandler {
   warmup: () => Promise<void>;
   /** Current route table getter (used by the WebSocket subsystem). */
   getRouteTable: () => unknown;
+  /** Current unresolved dev error frame (#264), or null (always null in prod). */
+  getLastDevError: () => object | null;
   /** The resolved app root. */
   appDir: string;
   /** Whether the handler is in dev mode. */
@@ -247,7 +258,7 @@ export declare function handleApi(
 // ---------------------------------------------------------------------------
 
 /** Scan the app for `.server.{js,ts}` files and build the RPC + expose index. */
-export declare function buildActionIndex(appDir: string, dev: boolean): Promise<unknown>;
+export declare function buildActionIndex(appDir: string, dev: boolean, opts?: { skipExposeLoad?: boolean }): Promise<unknown>;
 /** Whether a file path is a `.server.{js,ts,mjs,mts}` server file. */
 export declare function isServerFile(file: string): boolean;
 /** SHA-256 hash of an action file's absolute path (the RPC endpoint addressing scheme). */
@@ -553,6 +564,63 @@ export declare function broadcast(
   opts?: { except?: unknown },
 ): void;
 
+// ---------------------------------------------------------------------------
+// file-storage.js (#247)
+// ---------------------------------------------------------------------------
+
+/** A streaming handle returned by `FileStore.get` (body is a stream, never buffered). */
+export interface StoredObjectHandle {
+  body: ReadableStream | import('node:stream').Readable;
+  size: number;
+  contentType: string;
+}
+
+/** The result of `FileStore.put`. */
+export interface PutResult {
+  key: string;
+  size: number;
+  contentType: string;
+}
+
+/**
+ * The pluggable file-storage interface. `diskStore` is the local-disk default;
+ * an S3-compatible adapter is a drop-in (same web-standard object shapes).
+ */
+export interface FileStore {
+  put(
+    key: string,
+    file: Blob | File | ReadableStream | Uint8Array,
+    opts?: { contentType?: string },
+  ): Promise<PutResult>;
+  get(key: string): Promise<StoredObjectHandle | null>;
+  delete(key: string): Promise<void>;
+  url(key: string): string;
+  has?(key: string): Promise<boolean>;
+}
+
+/** The default uploads directory (relative to cwd), gitignore-friendly. */
+export declare const DEFAULT_UPLOAD_DIR: string;
+/** Local-disk file store (the default adapter). Streams writes. */
+export declare function diskStore(opts?: { dir?: string; baseUrl?: string }): FileStore;
+/** Set the default file store (call at startup to use a custom dir or S3). */
+export declare function setFileStore(store: FileStore): void;
+/** Get the default file store (`diskStore` under `<cwd>/.webjs/uploads` unless set). */
+export declare function getFileStore(): FileStore;
+/** Generate a random, opaque, traversal-safe key, preserving a whitelisted extension. */
+export declare function generateKey(filename?: string): string;
+/** Validate a key and return the absolute path it resolves to (throws on traversal). */
+export declare function assertSafeKey(dir: string, key: string): string;
+/** Mint a signed, expiring URL for a stored object (HMAC-SHA256). */
+export declare function signedUrl(
+  key: string,
+  opts: { secret: string; expiresIn?: number; base?: string },
+): string;
+/** Verify a signed URL (or parsed params); constant-time, checks expiry + tamper. */
+export declare function verifySignedUrl(
+  input: string | URL | URLSearchParams | { key?: string; exp?: string | number; sig?: string },
+  secret: string,
+): { valid: boolean; key: string | null; reason?: string };
+
 // ---------------------------------------------------------------------------
 // json.js
 // ---------------------------------------------------------------------------
@@ -583,6 +651,28 @@ export declare function sitemap(entries: SitemapEntry[]): string;
 /** Serialize child sitemaps into a `<sitemapindex>` XML document. */
 export declare function sitemapIndex(sitemaps: SitemapIndexEntry[]): string;
 
+// ---------------------------------------------------------------------------
+// stream.js (#248): stream-action helpers (the `<webjs-stream>` HTML the
+// client `renderStream` / element applies surgically)
+// ---------------------------------------------------------------------------
+
+/** The content type that negotiates and carries a stream-action response. */
+export declare const STREAM_MIME: string;
+/** Report whether a request opted into a stream-action response (its `Accept` carries the stream MIME). */
+export declare function acceptsStream(req: Request | { headers?: Headers }): boolean;
+/** The stream-action builder; each method returns one `<webjs-stream>` HTML string. */
+export declare const stream: {
+  append(target: string, content: string): string;
+  prepend(target: string, content: string): string;
+  before(target: string, content: string): string;
+  after(target: string, content: string): string;
+  replace(target: string, content: string): string;
+  update(target: string, content: string): string;
+  remove(target: string): string;
+};
+/** Wrap one or more stream-action strings in a `Response` carrying the stream content type. */
+export declare function streamResponse(...parts: string[]): Response;
+
 // ---------------------------------------------------------------------------
 // websocket.js
 // ---------------------------------------------------------------------------

package/index.js

@@ -46,8 +46,10 @@ export { revalidateTag, revalidateTags } from './src/cache-tags.js';
 export { revalidatePath, revalidateAll } from './src/html-cache.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';
 export { broadcast } from './src/broadcast.js';
+export { diskStore, setFileStore, getFileStore, generateKey, signedUrl, verifySignedUrl, assertSafeKey, DEFAULT_UPLOAD_DIR } from './src/file-storage.js';
 export { json, readBody } from './src/json.js';
 export { sitemap, sitemapIndex } from './src/sitemap.js';
+export { stream, streamResponse, acceptsStream, STREAM_MIME } from './src/stream.js';
 export { attachWebSocket } from './src/websocket.js';
 export { getSerializer, setSerializer, defaultSerializer } from './src/serializer.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.15",
+  "version": "0.8.17",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/actions.js

@@ -151,9 +151,17 @@ async function rpcResponse(payload, init = {}) {
  *
  * @param {string} appDir
  * @param {boolean} dev
+ * @param {{ skipExposeLoad?: boolean }} [opts]
+ *   `skipExposeLoad: true` builds the (load-free) `fileToHash` / `hashToFile`
+ *   maps WITHOUT importing any `expose()`-referencing module, so `httpRoutes`
+ *   stays empty. A read-only introspection caller (the MCP `list_actions` tool,
+ *   #262) uses this to derive RPC endpoint hashes without running a server
+ *   module's top-level side effects (Prisma init, DB connect) or risking a
+ *   stray stdout write. The request pipeline keeps the default (loads expose
+ *   routes, which the router must know before a request can hit them).
  * @returns {Promise<ActionIndex>}
  */
-export async function buildActionIndex(appDir, dev) {
+export async function buildActionIndex(appDir, dev, opts = {}) {
   /** @type {Map<string,string>} */
   const hashToFile = new Map();
   /** @type {Map<string,string>} */
@@ -190,6 +198,9 @@ export async function buildActionIndex(appDir, dev) {
     // mention in a comment or string only over-matches, costing one harmless
     // extra module load; the common pure-RPC file never names `expose` and so
     // still defers entirely.
+    // A read-only caller (MCP introspection) only needs the file -> hash maps
+    // above, so skip the expose-load entirely (no module side effects).
+    if (opts.skipExposeLoad) continue;
     let src = '';
     try { src = await readFile(file, 'utf8'); } catch {}
     if (!/\bexpose\b/.test(src)) continue;

package/src/component-elision.js

@@ -59,6 +59,10 @@ export const REACTIVE_IMPORTS = new Set([
   'computed',
   'effect',
   'watch',
+  // `optimistic(signal, value, action)` mutates a signal (client work) and
+  // settles after a server round-trip, so a component importing it is not
+  // display-only and must ship.
+  'optimistic',
   'Task',
   'until',
   'asyncAppend',
@@ -66,6 +70,10 @@ export const REACTIVE_IMPORTS = new Set([
   'ContextProvider',
   'ContextConsumer',
   'connectWS',
+  // `renderStream(payload)` applies a server stream-action payload to the live
+  // DOM (append/replace/remove), so a component importing it does client work
+  // and must ship (#248).
+  'renderStream',
   // Client-only directives. `ref` / `createRef` fire a callback against the
   // live element (focus, measure, third-party mount); `live` syncs an input
   // value against the DOM. All produce identical SSR HTML but do real work

package/src/dev-error.js

@@ -0,0 +1,129 @@
+/**
+ * Dev error overlay frames (#264).
+ *
+ * The dev server pushes a structured error frame over the existing SSE reload
+ * channel so the open tab renders a rich overlay (message, parsed location, a
+ * source code frame) without a manual reload, the way Vite's HMR error overlay
+ * and Next's dev overlay work. This module is the PURE frame builder: it parses
+ * an error's stack for the offending file location and reads a source excerpt.
+ * It is DEV-ONLY by construction (the caller gates on `dev`), so no file path or
+ * source ever reaches a production response.
+ *
+ * `buildDevErrorFrame` returns a plain JSON-serializable object the reload
+ * client renders. The only side effect is a guarded `readFileSync` of the
+ * offending source file for the code frame (a read failure degrades to no
+ * frame, never throws).
+ */
+import { readFileSync } from 'node:fs';
+
+/**
+ * Pull the first useful `file:line:column` out of an error stack. Prefers a
+ * frame under `appDir` (the user's own code) over a framework / node_modules
+ * frame, so the overlay points at the edit that broke, not webjs internals.
+ *
+ * Handles the V8 stack forms `at fn (/abs/file.ts:12:5)`, `at /abs/file.ts:12:5`,
+ * and `at file:///abs/file.ts:12:5`.
+ *
+ * @param {string} stack
+ * @param {string} [appDir]
+ * @returns {{ file: string, line: number, column: number } | null}
+ */
+export function parseStackLocation(stack, appDir) {
+  if (typeof stack !== 'string') return null;
+  // Capture `/abs/path` (group 1) then an OPTIONAL `?query` (the dev module
+  // loader appends a `?t=<mtime>` cache-bust, which would otherwise be glued to
+  // the path and break the readFileSync that builds the code frame), then
+  // `:line:col`. The path class excludes `?` so the query is split off.
+  //
+  // POSIX-first: this anchors on a leading `/`, so a Windows `C:\...` bare-path
+  // frame yields no location and the overlay degrades to a message-only card
+  // (the `file:///` URL form, whose path uses forward slashes, still resolves).
+  // That matches the framework's POSIX-first dev posture; it degrades, never
+  // crashes.
+  const re = /(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+):(\d+)/g;
+  /** @type {{ file: string, line: number, column: number }[]} */
+  const frames = [];
+  let m;
+  while ((m = re.exec(stack)) !== null) {
+    frames.push({ file: m[1], line: Number(m[2]), column: Number(m[3]) });
+  }
+  if (!frames.length) return null;
+  // Prefer a frame in the app (not node_modules), then the first app frame,
+  // else the first frame overall.
+  const inApp = frames.filter(
+    (f) => (!appDir || f.file.startsWith(appDir)) && !f.file.includes('/node_modules/')
+  );
+  return (inApp[0] || frames.find((f) => !f.file.includes('/node_modules/')) || frames[0]);
+}
+
+/**
+ * Read a source excerpt around `line` (1-based), `context` lines on each side,
+ * formatted with line numbers and a `>` marker on the offending line plus a
+ * caret under `column`. Returns null when the file cannot be read.
+ *
+ * @param {string} file
+ * @param {number} line
+ * @param {number} [column]
+ * @param {number} [context]
+ * @returns {string | null}
+ */
+export function readCodeFrame(file, line, column, context = 3) {
+  let src;
+  try { src = readFileSync(file, 'utf8'); } catch { return null; }
+  const lines = src.split('\n');
+  if (line < 1 || line > lines.length) return null;
+  const start = Math.max(1, line - context);
+  const end = Math.min(lines.length, line + context);
+  const gutter = String(end).length;
+  /** @type {string[]} */
+  const out = [];
+  for (let n = start; n <= end; n++) {
+    const marker = n === line ? '>' : ' ';
+    out.push(`${marker} ${String(n).padStart(gutter)} | ${lines[n - 1]}`);
+    if (n === line && column && column > 0) {
+      // A caret line under the offending column (account for the gutter prefix).
+      out.push(`  ${' '.repeat(gutter)} | ${' '.repeat(column - 1)}^`);
+    }
+  }
+  return out.join('\n');
+}
+
+/**
+ * Build a dev error frame from an error. DEV-ONLY (the caller gates on `dev`).
+ *
+ * @param {unknown} error
+ * @param {{ kind?: 'render' | 'ts-strip' | 'rebuild', appDir?: string, file?: string, line?: number, column?: number, hint?: string }} [opts]
+ * @returns {{ kind: string, message: string, stack: string|null, file: string|null, line: number|null, column: number|null, codeFrame: string|null, hint: string|null }}
+ */
+export function buildDevErrorFrame(error, opts = {}) {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const kind = opts.kind || 'render';
+  const stack = typeof err.stack === 'string' ? err.stack : null;
+  // An explicit file (the ts-strip case, where the strip error names the .ts
+  // file + position) wins over stack parsing; otherwise parse the stack.
+  let file = opts.file || null;
+  let line = opts.line != null ? opts.line : null;
+  let column = opts.column != null ? opts.column : null;
+  if (!file && stack) {
+    const loc = parseStackLocation(stack, opts.appDir);
+    if (loc) { file = loc.file; line = loc.line; column = loc.column; }
+  }
+  // An explicit file (the ts-strip case) but no line: Node's strip error embeds
+  // the offending position as `file:line:col` in its MESSAGE, so mine the
+  // message (and stack) for a location pointing at that same file.
+  if (file && line == null) {
+    const loc = parseStackLocation(`${err.message}\n${stack || ''}`, opts.appDir);
+    if (loc && loc.file === file) { line = loc.line; column = loc.column; }
+  }
+  const codeFrame = file && line ? readCodeFrame(file, line, column || 0) : null;
+  return {
+    kind,
+    message: err.message || String(err),
+    stack,
+    file,
+    line,
+    column,
+    codeFrame,
+    hint: opts.hint || null,
+  };
+}

package/src/dev-overlay.js

@@ -0,0 +1,75 @@
+/**
+ * The dev error overlay renderer (#264), the BROWSER half of the dev error
+ * overlay. It is a browser-safe ES module (no node imports) so it can be both
+ * unit-tested in a real browser AND inlined verbatim into the served dev
+ * reload client (`reloadClientJs` reads this file's source, strips the `export`
+ * keywords, and embeds it). Sharing the one source means the test drives the
+ * exact code that ships, with no drift.
+ *
+ * Security: the overlay is built with `createElement` + `textContent` only,
+ * NEVER `innerHTML`, so a hostile error message / file path / code frame is
+ * rendered as inert text and can never inject markup or script.
+ */
+
+/** The single live overlay element, or null. */
+let __wjOverlay = null;
+
+/** Remove the overlay if one is showing. */
+export function dismissDevOverlay() {
+  if (__wjOverlay) { __wjOverlay.remove(); __wjOverlay = null; }
+}
+
+/** Append a styled text row to `parent`. */
+function __wjRow(parent, css, text) {
+  const d = document.createElement('div');
+  d.style.cssText = css;
+  d.textContent = text;
+  parent.appendChild(d);
+  return d;
+}
+
+/**
+ * Render the dev error overlay for a frame, replacing any prior one.
+ * @param {{ kind?: string, message?: string, file?: string|null, line?: number|null, column?: number|null, codeFrame?: string|null, hint?: string|null }} f
+ */
+export function renderDevOverlay(f) {
+  dismissDevOverlay();
+  if (!f) return;
+  const o = document.createElement('div');
+  o.setAttribute('data-webjs-error-overlay', '');
+  o.style.cssText = 'position:fixed;inset:0;z-index:2147483647;background:rgba(10,10,12,.92);color:#e6e6e6;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;padding:32px;overflow:auto';
+  const card = document.createElement('div');
+  card.style.cssText = 'max-width:920px;margin:0 auto;background:#1a1a1f;border:1px solid #5b2330;border-radius:8px;padding:24px';
+  const kind = f.kind === 'ts-strip' ? 'TypeScript error (hydration is dead until fixed)' : f.kind === 'rebuild' ? 'Rebuild failed' : 'Server render error';
+  __wjRow(card, 'color:#ff6b6b;font-weight:700;font-size:15px;margin-bottom:8px', kind);
+  __wjRow(card, 'white-space:pre-wrap;margin-bottom:12px', f.message || '');
+  if (f.file) __wjRow(card, 'color:#9aa3ad;margin-bottom:12px', f.file + (f.line ? ':' + f.line + (f.column ? ':' + f.column : '') : ''));
+  if (f.codeFrame) {
+    const pre = document.createElement('pre');
+    pre.style.cssText = 'background:#0d0d10;border-radius:6px;padding:12px;overflow:auto;margin:0 0 12px;white-space:pre';
+    pre.textContent = f.codeFrame;
+    card.appendChild(pre);
+  }
+  if (f.hint) __wjRow(card, 'color:#ffd479;border-top:1px solid #333;padding-top:12px;white-space:pre-wrap', f.hint);
+  if (f.stack) {
+    const det = document.createElement('details');
+    det.style.cssText = 'margin-top:12px;color:#9aa3ad';
+    const sum = document.createElement('summary');
+    sum.textContent = 'Stack trace';
+    sum.style.cssText = 'cursor:pointer';
+    det.appendChild(sum);
+    const pre = document.createElement('pre');
+    pre.style.cssText = 'background:#0d0d10;border-radius:6px;padding:12px;overflow:auto;margin:8px 0 0;white-space:pre;font-size:12px';
+    pre.textContent = f.stack;
+    det.appendChild(pre);
+    card.appendChild(det);
+  }
+  const btn = document.createElement('button');
+  btn.textContent = 'Dismiss';
+  btn.style.cssText = 'margin-top:16px;background:#333;color:#eee;border:0;border-radius:4px;padding:6px 12px;cursor:pointer';
+  btn.addEventListener('click', dismissDevOverlay);
+  card.appendChild(btn);
+  o.appendChild(card);
+  (document.body || document.documentElement).appendChild(o);
+  __wjOverlay = o;
+}

package/src/dev.js

@@ -1,6 +1,6 @@
 import { createServer as createHttp1Server } from 'node:http';
 import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createGzip, createBrotliCompress, constants as zlibConstants } from 'node:zlib';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
 import { createRequire } from 'node:module';
@@ -115,7 +115,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
-import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash } from './asset-hash.js';
+import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
 import {
@@ -126,7 +126,8 @@ import {
 } from './redirects.js';
 import { readBodyLimits, computeServerTimeouts } from './body-limit.js';
 import { applyConditionalGet, BUFFERED_MARKER } from './conditional-get.js';
-import { commitHtmlCache } from './html-cache.js';
+import { commitHtmlCache, setAppSourceFingerprint } from './html-cache.js';
+import { buildDevErrorFrame } from './dev-error.js';
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -394,6 +395,7 @@ export async function readServerTimeoutsFromApp(appDir) {
  *   logger?: import('./logger.js').Logger,
  *   onError?: (error: unknown, ctx: { request: Request, requestId: string|null, phase: string }) => void,
  *   onReload?: () => void,
+ *   onDevError?: (frame: object) => void,
  * }} opts
  */
 export async function createRequestHandler(opts) {
@@ -607,8 +609,30 @@ export async function createRequestHandler(opts) {
     // settings (a multi-tenant embedder, or the differential elision test)
     // must not share it, or the second would serve the first's elided source.
     tsCache: new Map(),
+    // The most recent unresolved dev error frame (#264), or null. Pushed to the
+    // SSE channel for the live overlay and replayed to a freshly-connected tab.
+    // Dev-only (never populated when !dev); cleared on a successful rebuild.
+    lastDevError: null,
   };
 
+  /**
+   * Report a dev error (#264): build a frame and push it to the open tab via
+   * the SSE overlay channel. DEV-ONLY and best-effort, so it can never affect a
+   * response or crash the server (a frame-build failure is swallowed). No file
+   * path or source is ever built in prod (the early return), so nothing leaks.
+   *
+   * @param {unknown} error
+   * @param {{ kind?: 'render'|'ts-strip'|'rebuild', file?: string, line?: number, column?: number, hint?: string }} [info]
+   */
+  function reportDevError(error, info = {}) {
+    if (!dev) return;
+    try {
+      const frame = buildDevErrorFrame(error, { ...info, appDir });
+      state.lastDevError = frame;
+      opts.onDevError?.(frame);
+    } catch { /* a frame-build failure must never affect the request path */ }
+  }
+
   // All whole-app analysis is built lazily on the first request, memoized so
   // boot does none of it. It runs in two stages. The deterministic analysis
   // (module graph, component scan + prime, browser-bound gate, action index,
@@ -707,6 +731,28 @@ export async function createRequestHandler(opts) {
               ].map(rel).sort();
               setElisionFingerprint(elidedPaths.length ? elidedPaths.join('\n') : '');
             }
+            // App-source fingerprint for the HTML cache key (#318): a
+            // deterministic, location-independent digest of the browser-bound
+            // file set's content hashes, so a deploy that changes ONLY an app
+            // module's bytes (which the importmap-only build id misses) re-keys
+            // the cache instead of serving a body with stale `?v` boot URLs.
+            // PROD only (asset-hash is enabled there); '' in dev, where fs.watch
+            // handles staleness. Computed AFTER the elision fingerprint, so each
+            // per-file hash already reflects the elision verdict (an elision
+            // flip changes the served output, so it moves this fingerprint too).
+            // This eagerly hashes the WHOLE browser-bound set once (not just the
+            // first route's files), but `assetHashFor` is memoized and already
+            // runs for `?v` emission in prod, so it stays a one-time bounded cost
+            // inside the lazy analysis (never at boot).
+            if (!dev && state.browserBoundFiles) {
+              const relApp = (p) => (p.startsWith(appDir + sep) ? p.slice(appDir.length) : p);
+              const lines = [...state.browserBoundFiles]
+                .map((abs) => `${relApp(abs)}:${assetHashFor(abs)}`)
+                .sort();
+              setAppSourceFingerprint(lines.join('\n'));
+            } else {
+              setAppSourceFingerprint('');
+            }
             t.elision = now() - m;
             if (dev) {
               for (const { className, file } of await findOrphanComponents(appDir)) {
@@ -850,6 +896,9 @@ export async function createRequestHandler(opts) {
   async function rebuild() {
     rebuildInFlight = rebuildInFlight.then(() => doRebuild()).catch((e) => {
       logger.error?.(`[webjs] rebuild failed:`, e);
+      // Push the failure to the open tab so the overlay appears live after a
+      // breaking edit, not only on the next manual navigation (#264).
+      reportDevError(e, { kind: 'rebuild' });
     });
     return rebuildInFlight;
   }
@@ -884,6 +933,15 @@ export async function createRequestHandler(opts) {
     readyDone = false;
     readyError = null;
     readinessFn = undefined; // reload readiness.{js,ts} after a rebuild
+    // Optimistically clear the dev error (#264): the rebuild itself only
+    // re-scans the route table and INVALIDATES the lazy analysis (the real
+    // re-parse / re-strip / re-render happens on the next request), so we do
+    // not yet know the edit fixed the error. Clearing it here means a tab that
+    // connects now is not replayed a possibly-stale overlay; `onReload` then
+    // reloads every open tab, and if the underlying error is still present the
+    // reloaded request re-pushes a fresh frame (a brief dismiss-then-reappear
+    // flicker on an unrelated edit, self-correcting to the right end state).
+    state.lastDevError = null;
     opts.onReload?.();
   }
 
@@ -1175,7 +1233,7 @@ export async function createRequestHandler(opts) {
       // Build all whole-app analysis on the first request (memoized), before
       // any SSR, module serve, gate check, action dispatch, or middleware runs.
       await ensureReady();
-      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, cspEnabled: cspConfig.enabled });
+      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled: cspConfig.enabled });
       if (state.middleware) {
         try {
           return await state.middleware(req, next);
@@ -1245,6 +1303,10 @@ export async function createRequestHandler(opts) {
     warmup: () => ensureReady().catch((e) => logger.error?.(`[webjs] background warm-up failed (will retry on the next request):`, e)),
     /** current route table getter: used by the WebSocket subsystem */
     getRouteTable: () => state.routeTable,
+    /** Current unresolved dev error frame (#264), or null. Replayed by
+     * startServer to a freshly-connected SSE client so the overlay shows even
+     * after a navigation, not only on the breaking edit. Always null in prod. */
+    getLastDevError: () => state.lastDevError,
     appDir,
     dev,
     logger,
@@ -1304,6 +1366,15 @@ export async function startServer(opts) {
         try { res.write(`event: reload\ndata: now\n\n`); } catch {}
       }
     },
+    // Dev error overlay (#264): push a frame to every open tab over the SAME
+    // SSE channel. A distinct `webjs-error` event name (NOT `error`, which is
+    // EventSource's native connection-error event) carries the JSON frame.
+    onDevError: (frame) => {
+      const data = JSON.stringify(frame);
+      for (const res of sseClients) {
+        try { res.write(`event: webjs-error\ndata: ${data}\n\n`); } catch {}
+      }
+    },
   });
 
   /** @type {AbortController | null} */
@@ -1360,6 +1431,13 @@ export async function startServer(opts) {
         });
         res.write(`event: hello\ndata: webjs\n\n`);
         sseClients.add(res);
+        // Replay an unresolved dev error (#264) so a tab that connects AFTER the
+        // breaking edit (e.g. opened via a fresh navigation) still shows the
+        // overlay, not only the tab that was open when the error fired.
+        const pending = app.getLastDevError?.();
+        if (pending) {
+          try { res.write(`event: webjs-error\ndata: ${JSON.stringify(pending)}\n\n`); } catch {}
+        }
         res.socket?.on('close', () => sseClients.delete(res));
         return;
       }
@@ -1537,7 +1615,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
 }
 
 async function handleCore(req, ctx) {
-  const { state, appDir, coreDir, dev, reportError, cspEnabled } = ctx;
+  const { state, appDir, coreDir, dev, reportError, reportDevError, cspEnabled } = ctx;
   const url = new URL(req.url);
   // Decode percent-encoded characters so filesystem lookups match real
   // filenames. Dynamic route segments like `[slug]` and route groups like
@@ -1694,7 +1772,7 @@ async function handleCore(req, ctx) {
       // A `?v=<hash>` app-module request is content-addressed -> immutable
       // (#243); an un-fingerprinted request keeps the 1h fallback.
       if (/\.m?ts$/.test(abs)) {
-        return tsResponse(abs, dev, elideOpts, state.tsCache, versioned);
+        return tsResponse(abs, dev, elideOpts, state.tsCache, versioned, reportDevError);
       }
       if (/\.m?js$/.test(abs)) {
         return jsModuleResponse(abs, dev, elideOpts, versioned);
@@ -1760,6 +1838,10 @@ async function handleCore(req, ctx) {
         // onError sink (issue #239): a page render error that becomes a 500 is
         // reported to the APM hook with the active request's correlation id.
         onError: reportError ? (e) => reportError(e, req, 'ssr') : undefined,
+        // Dev error overlay (#264): a render crash pushes a frame to the open
+        // tab. Dev-only (reportDevError early-returns in prod), so no source
+        // leaks. Distinct from onError (the APM sink), which always fires.
+        onDevError: dev ? (e) => reportDevError(e, { kind: 'render' }) : undefined,
       };
       if (method === 'GET' || method === 'HEAD') {
         const handler = () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
@@ -2117,7 +2199,7 @@ async function stripTs(source, _abs) {
  *   serve `immutable` (1 year) instead of the 1h fallback. The cached BODY is
  *   the same bytes regardless; only the cache header varies. Dev stays `no-cache`.
  */
-async function tsResponse(abs, dev, elideOpts, cache, immutable) {
+async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDevError) {
   // The body bytes are identical with or without `?v`; only the cache header
   // changes, so the per-mtime cache stays a single entry.
   const cacheControl = dev ? 'no-cache' : immutable ? 'public, max-age=31536000, immutable' : 'public, max-age=3600';
@@ -2148,6 +2230,15 @@ async function tsResponse(abs, dev, elideOpts, cache, immutable) {
       // see what went wrong in their logs.
       // eslint-disable-next-line no-console
       console.error(`[webjs] non-erasable TypeScript in ${abs}: ${err.message}`);
+      // Dev error overlay (#264): a TS strip failure breaks only the CLIENT
+      // module fetch (the page still SSRs, so hydration is silently dead and
+      // the hint below is buried in a JS comment). Push a frame so the open tab
+      // shows the overlay with the offending file + the no-non-erasable hint.
+      reportDevError?.(err, {
+        kind: 'ts-strip',
+        file: abs,
+        hint: 'webjs is buildless: only erasable TypeScript is supported. Replace enum / namespace-with-values / parameter-property / legacy-decorator / import = require with their erasable equivalents. Run `webjs check` (no-non-erasable-typescript rule).',
+      });
       const msg = dev
         // Dev: include the file path and Node's error message so the
         // developer's browser tooling can point them at the offending
@@ -2320,9 +2411,25 @@ function locatePackageDir(appDir, pkgName) {
  * @param {string} bp the normalized base path (`''` = no-op)
  * @returns {string}
  */
+// The overlay renderer source, read once + `export`-stripped so it inlines as
+// plain functions into the classic reload-client script. Sharing the one source
+// (`dev-overlay.js`, which the browser test imports directly) means the test
+// drives the EXACT code that ships, with no drift (#264).
+const DEV_OVERLAY_SRC = readFileSync(new URL('./dev-overlay.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
 function reloadClientJs(bp) {
+  // The overlay renderer uses textContent throughout (never innerHTML), so the
+  // error message / code frame can never inject markup (#264). Served only in
+  // dev (the /__webjs/reload.js branch 404s in prod), so it never reaches a
+  // production page.
   return `// webjs dev reload client
+${DEV_OVERLAY_SRC}
 const es = new EventSource(${JSON.stringify(withBasePath('/__webjs/events', bp))});
 es.addEventListener('reload', () => location.reload());
+es.addEventListener('webjs-error', (e) => {
+  let f; try { f = JSON.parse(e.data); } catch (_) { return; }
+  renderDevOverlay(f);
+});
 `;
 }