@webjsdev/server 0.8.16 → 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. */
@@ -640,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

@@ -49,6 +49,7 @@ 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.16",
+  "version": "0.8.17",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

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);
+});
 `;
 }

package/src/frame-render.js

@@ -0,0 +1,172 @@
+/**
+ * Server-side `<webjs-frame>` subtree extraction (#253).
+ *
+ * When a `<webjs-frame src loading>` self-loads (or a click drives a frame
+ * nav), the client sends an `x-webjs-frame: <id>` header and then, from the
+ * response, applies ONLY the matching `<webjs-frame id>` subtree (the rest of
+ * the page is discarded). Rendering the FULL page just to throw away all but
+ * one region wastes the full-page render + transfer cost.
+ *
+ * This module extracts the requested frame subtree from the already-rendered
+ * full-page HTML and returns ONLY that, so the response is BYTE-EQUIVALENT by
+ * construction to what the client would have extracted from the full page (a
+ * `src` self-load and a click-driven frame nav therefore produce identical DOM)
+ * while sending far fewer bytes. "Isolable" means the requested frame id is
+ * present in the rendered output; when it is not, the caller falls back to the
+ * full-page render (so an auth redirect / a route that dropped the frame is
+ * handled exactly as before).
+ *
+ * The extraction is a structural scan over the rendered HTML, balancing nested
+ * `<webjs-frame>` tags so a frame nested inside another frame is matched
+ * correctly. It only triggers when the `x-webjs-frame` header is present, so a
+ * normal full-page request is completely unaffected (byte-identical).
+ */
+
+const FRAME_TAG = 'webjs-frame';
+
+/**
+ * Read the requested frame id off a request's `x-webjs-frame` header.
+ * Returns the trimmed id, or `null` when the header is absent / empty (the
+ * normal full-page request path).
+ *
+ * @param {Request | undefined} req
+ * @returns {string | null}
+ */
+export function requestedFrameId(req) {
+  if (!req || !req.headers) return null;
+  const raw = req.headers.get('x-webjs-frame');
+  if (!raw) return null;
+  const id = raw.trim();
+  return id ? id : null;
+}
+
+/**
+ * Find the `<webjs-frame ... id="<frameId>" ...>...</webjs-frame>` subtree in
+ * `html` and return it verbatim (opening tag through matching close tag), so
+ * the slice is byte-equivalent to the same bytes inside the full page. Nested
+ * `<webjs-frame>` tags are balanced, so an outer frame's close is not mistaken
+ * for an inner frame's. Returns `null` when no frame with that id is present
+ * (the caller then renders / returns the full page).
+ *
+ * The id match is attribute-aware (it reads the `id` attribute of each opening
+ * `<webjs-frame>` tag rather than substring-matching), so a frame whose id is a
+ * prefix of another id is not mismatched. A self-closing `<webjs-frame/>` (no
+ * children) is matched as an empty subtree.
+ *
+ * @param {string} html  The rendered full-page HTML.
+ * @param {string} frameId  The requested frame id.
+ * @returns {string | null}  The frame subtree, or null when absent.
+ */
+export function extractFrameSubtree(html, frameId) {
+  if (typeof html !== 'string' || !frameId) return null;
+  const lower = html.toLowerCase();
+  const open = '<' + FRAME_TAG;
+  let cursor = 0;
+  while (cursor < lower.length) {
+    const start = lower.indexOf(open, cursor);
+    if (start === -1) return null;
+    // Confirm this is a real tag open (`<webjs-frame` followed by whitespace,
+    // `>`, or `/`), not a longer tag name that happens to share the prefix.
+    const after = lower[start + open.length];
+    if (after !== undefined && after !== ' ' && after !== '\t' && after !== '\n'
+        && after !== '\r' && after !== '>' && after !== '/') {
+      cursor = start + open.length;
+      continue;
+    }
+    // Locate the end of this opening tag.
+    const tagEnd = html.indexOf('>', start);
+    if (tagEnd === -1) return null;
+    const openTag = html.slice(start, tagEnd + 1);
+    const selfClosing = /\/\s*>$/.test(openTag);
+    const id = readIdAttr(openTag);
+    if (id === frameId) {
+      if (selfClosing) return openTag;
+      const end = findMatchingClose(html, lower, tagEnd + 1);
+      if (end === -1) return null;
+      return html.slice(start, end);
+    }
+    cursor = tagEnd + 1;
+  }
+  return null;
+}
+
+/**
+ * Read the `id` attribute value out of a single opening `<webjs-frame ...>`
+ * tag string. Handles double-quoted, single-quoted, and unquoted forms.
+ *
+ * @param {string} openTag  The opening tag including `<` and `>`.
+ * @returns {string | null}
+ */
+function readIdAttr(openTag) {
+  const m = /\sid\s*=\s*("([^"]*)"|'([^']*)'|([^\s>/]+))/i.exec(openTag);
+  if (!m) return null;
+  return m[2] ?? m[3] ?? m[4] ?? null;
+}
+
+/**
+ * Given the index just past a `<webjs-frame ...>` opening tag, return the index
+ * just past its matching `</webjs-frame>`, balancing nested `<webjs-frame>`
+ * opens. Returns -1 when unbalanced (no matching close).
+ *
+ * @param {string} html  Original-case HTML (returned-slice source).
+ * @param {string} lower  Lower-cased copy for case-insensitive scanning.
+ * @param {number} from  Index just past the opening tag's `>`.
+ * @returns {number}  Index just past the matching `</webjs-frame>`, or -1.
+ */
+/**
+ * Find the next `needle` (`<webjs-frame` or `</webjs-frame`) in `lower` from
+ * `start` that is a REAL tag, i.e. the char right after the tag name is a tag
+ * boundary (whitespace, `>`, or `/`). This skips a prefix-collision tag such as
+ * `<webjs-frame-nav>` / `</webjs-frame-nav>`, which `indexOf` alone would match
+ * and miscount (an unbalanced one would corrupt the depth scan). Returns -1
+ * when no real tag remains.
+ *
+ * @param {string} lower
+ * @param {string} needle
+ * @param {number} start
+ * @returns {number}
+ */
+function findRealTag(lower, needle, start) {
+  let at = start;
+  while (at < lower.length) {
+    const idx = lower.indexOf(needle, at);
+    if (idx === -1) return -1;
+    const after = lower[idx + needle.length];
+    if (after === undefined || after === ' ' || after === '\t' || after === '\n'
+      || after === '\r' || after === '>' || after === '/') {
+      return idx;
+    }
+    at = idx + needle.length; // a prefix-collision tag, keep scanning
+  }
+  return -1;
+}
+
+function findMatchingClose(html, lower, from) {
+  const open = '<' + FRAME_TAG;
+  const close = '</' + FRAME_TAG;
+  let depth = 1;
+  let i = from;
+  while (i < lower.length) {
+    const nextOpen = findRealTag(lower, open, i);
+    const nextClose = findRealTag(lower, close, i);
+    if (nextClose === -1) return -1;
+    if (nextOpen !== -1 && nextOpen < nextClose) {
+      // A nested frame open. Skip past its opening tag, and only increase
+      // depth when it is NOT self-closing (a self-closing nested frame opens
+      // and closes in one tag, so it does not need a matching close).
+      const tagEnd = html.indexOf('>', nextOpen);
+      if (tagEnd === -1) return -1;
+      const nestedOpenTag = html.slice(nextOpen, tagEnd + 1);
+      if (!/\/\s*>$/.test(nestedOpenTag)) depth++;
+      i = tagEnd + 1;
+      continue;
+    }
+    // A close tag. Consume through its `>`.
+    const closeEnd = html.indexOf('>', nextClose);
+    if (closeEnd === -1) return -1;
+    depth--;
+    i = closeEnd + 1;
+    if (depth === 0) return i;
+  }
+  return -1;
+}

package/src/html-cache.js

@@ -26,6 +26,7 @@
 
 import { getStore } from './cache.js';
 import { STREAM_MARKER } from './conditional-get.js';
+import { createHash } from 'node:crypto';
 import { publishedBuildId } from './importmap.js';
 import { dynamicAccessed } from './context.js';
 
@@ -53,6 +54,39 @@ export const HTML_CACHE_MARKER = 'x-webjs-html-cache';
  */
 let _generation = 0;
 
+/**
+ * A fingerprint of the served app source, folded into every cache key (#318).
+ * The published build id keys on the IMPORTMAP (core + vendor) only, so a deploy
+ * that changes ONLY an app module's bytes does not move it, and a Redis-cached
+ * `revalidate` page survives that deploy still serving its baked-in OLD `?v`
+ * boot URLs (under #243 immutable caching those then content-address to stale
+ * bytes). dev.js sets this to a deterministic, location-independent digest of
+ * the browser-bound file set's content hashes (PROD only; '' in dev, where
+ * fs.watch handles staleness), so an app-source-changing deploy re-keys (a fresh
+ * render) while a no-change redeploy keeps the key (a warm cache survives). The
+ * client-router build id deliberately stays importmap-only: a partial-swap
+ * fragment already carries the new `?v` boot URLs, so app updates propagate on
+ * the next navigation without a destructive hard reload.
+ *
+ * @type {string}
+ */
+let _appSourceFp = '';
+
+/**
+ * Set the app-source fingerprint folded into the HTML cache key (see
+ * `_appSourceFp`). Called by dev.js from `ensureReady` after the browser-bound
+ * file set + asset hashes are known, and again on each rebuild. The input is a
+ * deterministic, location-independent STRING (sorted `relpath:contentHash`
+ * lines); it is digested to a short hex so the key stays compact. An empty
+ * input clears the fingerprint (the key collapses to its prior shape).
+ *
+ * @param {string} raw
+ * @returns {void}
+ */
+export function setAppSourceFingerprint(raw) {
+  _appSourceFp = raw ? createHash('sha256').update(raw).digest('hex').slice(0, 16) : '';
+}
+
 /**
  * Read the revalidation window (seconds) a page module opted into via
  * `export const revalidate = N` (the Next idiom). Returns a positive finite
@@ -86,8 +120,13 @@ export function readRevalidate(pageModule) {
  *    naturally writes and reads under fresh keys. The cached HTML bakes the
  *    deploy's `data-webjs-build` importmap into its boot script, so a Redis
  *    store that survives a deploy must NOT let a v2 process serve a v1-body
- *    (resolving modules against stale vendor URLs). Folding the build id in
- *    means a deploy effectively invalidates all cached HTML for free.
+ *    (resolving modules against stale vendor URLs);
+ *  - the app-source fingerprint (#318), so a deploy that changes ONLY an app
+ *    module's bytes (which does not move the importmap build id) also re-keys,
+ *    instead of serving a cached body with stale `?v` boot URLs. Together the
+ *    build id (vendor) and the app-source fingerprint (app modules) mean ANY
+ *    deploy that changes the served output re-keys, while a no-change redeploy
+ *    keeps every key so a warm cache survives.
  *
  * @param {URL} url
  * @returns {string}
@@ -100,7 +139,11 @@ export function htmlCacheKey(url) {
     ? '?' + params.map(([k, v]) => `${k}=${v}`).join('&')
     : '';
   const build = publishedBuildId() || 'nobuild';
-  return `${KEY_PREFIX}${build}:${_generation}:${url.pathname}${search}`;
+  // The app-source fingerprint (#318) re-keys on an app-module-only deploy that
+  // the importmap-only build id misses. Empty (dev / no fingerprint) collapses
+  // to the prior key shape, so an unconfigured app is byte-identical.
+  const appfp = _appSourceFp ? `${_appSourceFp}:` : '';
+  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${url.pathname}${search}`;
 }
 
 /**

package/src/page-action.js

@@ -207,6 +207,13 @@ export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
     throw err;
   }
 
+  // A page action MAY return a `Response` directly (e.g. a content-negotiated
+  // `streamResponse`, #248). Honor it verbatim, so the action owns the status +
+  // content type and the router applies it (a stream body surgically). With JS
+  // off the same action returns a normal ActionResult instead, so the PRG /
+  // re-render paths below still drive the no-JS form.
+  if (result instanceof Response) return result;
+
   if (!isFailureResult(result)) {
     // SUCCESS: Post/Redirect/Get. A user-controlled `result.redirect` is only
     // honored when it is a same-site local path; otherwise fall back to the

package/src/ssr.js

@@ -13,6 +13,7 @@ import {
   readHtmlCache,
   HTML_CACHE_MARKER,
 } from './html-cache.js';
+import { requestedFrameId, extractFrameSubtree } from './frame-render.js';
 
 /**
  * SSR a matched page route to a Response.
@@ -94,6 +95,31 @@ export async function ssrPage(route, params, url, opts) {
       ? new Set(haveHeader.split(',').map((s) => s.trim()).filter(Boolean))
       : null;
     const body = await renderChain(route, ctx, opts.dev, suspenseCtx, have, opts.pageModule);
+
+    // Frame subtree render (#253). A `<webjs-frame src>` self-load (or a
+    // click-driven frame nav) sends `x-webjs-frame: <id>` and applies ONLY the
+    // matching `<webjs-frame id>` subtree from the response, discarding the rest
+    // of the page. So when that header is present AND the requested frame is in
+    // the rendered output (the "isolable" case), return JUST that subtree: the
+    // bytes are extracted verbatim from the same full render, so the result is
+    // BYTE-EQUIVALENT to what the client would slice from a full-page response,
+    // but the full document shell + all the other regions never go on the wire.
+    // The frame swap path (applySwap in router-client.js) parses this body and
+    // does `doc.querySelector('webjs-frame#<id>')`, which finds the lone
+    // subtree exactly as it would in the full page. A streamed (Suspense)
+    // render is skipped (its bytes are not yet final). When the frame id is NOT
+    // found (an auth redirect to a login page, a route that dropped the frame),
+    // we fall through to the normal full-page render, where the client's
+    // existing `webjs:frame-missing` fallback handles the absence. A request
+    // with NO `x-webjs-frame` header never reaches this branch, so a normal
+    // page request is byte-identical to before this feature.
+    const frameId = requestedFrameId(opts.req);
+    if (frameId && suspenseCtx.pending.length === 0) {
+      const subtree = extractFrameSubtree(body, frameId);
+      if (subtree !== null) {
+        return htmlResponse(subtree, opts.status || 200, opts.req, url);
+      }
+    }
     // Module URLs for the page + every layout in its chain. These ride
     // the importmap; the browser fetches each file as it walks the
     // import graph. Combined with the modulepreload hints below, this
@@ -187,6 +213,11 @@ export async function ssrPage(route, params, url, opts) {
     if (typeof opts.onError === 'function') {
       try { opts.onError(err); } catch { /* a throwing sink must not affect the response */ }
     }
+    // Dev error overlay (#264): push a rich frame to the open tab so the
+    // overlay appears live. Dev-only + best-effort; never affects the response.
+    if (typeof opts.onDevError === 'function') {
+      try { opts.onDevError(err); } catch { /* a throwing sink must not affect the response */ }
+    }
     // Error paths still need to honor the request's CSP nonce so the
     // error page's boot scripts (when moduleUrls is non-empty) and
     // the meta csp-nonce tag both pass strict-CSP enforcement.

package/src/stream.js

@@ -0,0 +1,95 @@
+/**
+ * Server-side stream-action helpers (#248) that build the `<webjs-stream>` HTML
+ * the client applier (`renderStream` / the `webjs-stream` element) applies
+ * surgically.
+ *
+ * The payload is plain HTML, a `<webjs-stream action target>` wrapping one
+ * `<template>`. These helpers compose that string for the two delivery paths,
+ * a content-negotiated HTTP form response and a `broadcast()` / WS message, so
+ * an app never hand-writes the markup. A page `action` or a `route` handler
+ * branches on `acceptsStream(request)`, returning `streamResponse(...)` when the
+ * router asked for a stream and a normal render otherwise (the JS-off degrade).
+ *
+ * The helpers do NOT escape the CONTENT (it is server-authored HTML, like a
+ * template result). Escape any user-supplied substring yourself, the same way
+ * you would inside an `html` template hole.
+ */
+
+/** The content type that negotiates and carries a stream-action response. */
+export const STREAM_MIME = 'text/vnd.webjs-stream.html';
+
+/**
+ * Report whether a request opted into a stream-action response. The client
+ * router adds the stream MIME to `Accept` on a form submission. With JS off the
+ * browser sends no such Accept, so this returns false and the app returns a
+ * normal render (the progressive-enhancement degrade).
+ *
+ * @param {Request | { headers?: Headers }} req
+ * @returns {boolean}
+ */
+export function acceptsStream(req) {
+  const accept = req && req.headers && req.headers.get ? (req.headers.get('accept') || '') : '';
+  return accept.toLowerCase().includes(STREAM_MIME);
+}
+
+/** Escape the target id for safe placement in a double-quoted attribute. */
+function escapeAttr(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Build one `<webjs-stream>` action element.
+ * @param {string} action  One of append, prepend, before, after, replace, update, remove.
+ * @param {string} target  The target element id.
+ * @param {string} [content]  Inner HTML for the insert actions (ignored by remove).
+ * @returns {string}
+ */
+function build(action, target, content) {
+  const t = escapeAttr(target);
+  if (action === 'remove') {
+    return `<webjs-stream action="remove" target="${t}"></webjs-stream>`;
+  }
+  const inner = content == null ? '' : String(content);
+  return `<webjs-stream action="${action}" target="${t}"><template>${inner}</template></webjs-stream>`;
+}
+
+/**
+ * The stream-action builder. Each method returns one `<webjs-stream>` HTML
+ * string. Concatenate several and pass them to `streamResponse` or a
+ * `broadcast()`.
+ */
+export const stream = {
+  /** @param {string} target @param {string} content @returns {string} */
+  append: (target, content) => build('append', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  prepend: (target, content) => build('prepend', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  before: (target, content) => build('before', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  after: (target, content) => build('after', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  replace: (target, content) => build('replace', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  update: (target, content) => build('update', target, content),
+  /** @param {string} target @returns {string} */
+  remove: (target) => build('remove', target),
+};
+
+/**
+ * Wrap one or more stream-action strings in a `Response` carrying the stream
+ * content type, so the client router applies it surgically. A non-200 status is
+ * fine (the router applies a stream body of any status).
+ *
+ * @param {...string} parts  `<webjs-stream>` HTML strings from `stream.*`.
+ * @returns {Response}
+ */
+export function streamResponse(...parts) {
+  return new Response(parts.join('\n'), {
+    status: 200,
+    headers: { 'content-type': STREAM_MIME + '; charset=utf-8' },
+  });
+}