@webjsdev/server 0.8.39 → 0.8.41

package/src/component-elision.js

@@ -126,6 +126,35 @@ export const CLIENT_LIFECYCLE_HOOKS = [
  */
 export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'requestUpdate'];
 
+/**
+ * Static class fields whose declaration (to a non-`false` value) marks a
+ * component interactive (must ship). Kept as ONE registry so a new
+ * interactivity-relevant static convention is added in a single place; the
+ * per-class analysis loops over it. Unlike prototype methods (guarded by
+ * `lifecycle-coverage.test.js` via prototype introspection), there is no
+ * enumerable runtime source of "all static conventions", so the contract is
+ * a documented one: a new interactivity static field MUST be added here AND
+ * to the lifecycle table in agent-docs/components.md. `sigil-coverage.test.js`
+ * asserts each entry is honoured as a ship signal.
+ *
+ *   - `shadow`: Declarative Shadow DOM attaches ONLY during HTML parsing, so a
+ *     component that arrives via a client DOM insertion (a soft-nav swap, a
+ *     streamed <webjs-suspense> boundary's replaceWith) would never re-attach
+ *     its shadow root if elided. Context-free, so any shadow component ships.
+ *   - `refresh`: `static refresh = true` is the explicit opt-in to ship a bare
+ *     async component so its stale-while-revalidate refresh runs after SSR;
+ *     eliding drops that on-load re-fetch (moot for request-stable data).
+ *
+ * @type {readonly string[]}
+ */
+export const INTERACTIVITY_STATIC_FIELDS = ['shadow', 'refresh'];
+
+/** Why each INTERACTIVITY_STATIC_FIELDS entry forces a ship (analyser reason). */
+const STATIC_FIELD_REASONS = {
+  shadow: 'declares static shadow (DSD must re-attach on a client swap)',
+  refresh: 'declares static refresh = true (keeps the on-load re-fetch)',
+};
+
 /**
  * A bare `async render()` is NOT a standalone ship signal (#474). Its SSR
  * pass bakes the resolved data into the first paint, so a light-DOM async
@@ -144,8 +173,37 @@ export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'reques
  * re-fetch that eliding would drop).
  */
 
-/** Match a `@event=${...}` binding inside a template (unquoted per invariant 4). */
-const EVENT_BINDING_RE = /@[A-Za-z][\w-]*\s*=\s*\$\{/;
+/**
+ * Template binding-prefix classification, the anchor for the elision drift
+ * guard. Every prefix core's renderers recognise (core's `BINDING_PREFIXES`)
+ * is one of two kinds:
+ *   - SSR_DROPPED_PREFIXES: a CLIENT-BEHAVIOUR ship signal. The binding drops
+ *     at SSR and is wired only after hydration (`@event`), so a component whose
+ *     only interactivity is such a binding MUST ship.
+ *   - ROUND_TRIP_PREFIXES: an SSR-SAFE binding that survives into the served
+ *     HTML (`.prop` via `data-webjs-prop-*`, `?bool` as a boolean attribute),
+ *     so it is NOT a ship signal on its own and stays elidable.
+ * `sigil-coverage.test.js` asserts these two lists PARTITION `BINDING_PREFIXES`
+ * exactly (union equal, disjoint), so a new sigil cannot be added to the
+ * renderers without being classified here. That closes the one interactivity
+ * surface the prototype-introspection guard (`lifecycle-coverage.test.js`)
+ * cannot see, because a sigil is template syntax, not a method or an export.
+ */
+export const SSR_DROPPED_PREFIXES = ['@'];
+export const ROUND_TRIP_PREFIXES = ['.', '?'];
+
+/** Escape a single char for safe inclusion in a regex character class. */
+const escapeForCharClass = (c) => c.replace(/[\\\]^-]/g, '\\$&');
+
+/**
+ * Match a client-behaviour binding (`@event=${...}`), a ship signal. The
+ * prefix set is DERIVED from SSR_DROPPED_PREFIXES (not hardcoded), so a new
+ * client-behaviour sigil added to core is detected here automatically once it
+ * is classified above. (unquoted per invariant 4)
+ */
+const EVENT_BINDING_RE = new RegExp(
+  `[${SSR_DROPPED_PREFIXES.map(escapeForCharClass).join('')}][A-Za-z][\\w-]*\\s*=\\s*\\$\\{`,
+);
 
 /** Match a `.onclick=${...}` (native event-handler property) binding. */
 const EVENT_PROP_RE = /\.on[a-z]+\s*=\s*\$\{/;
@@ -505,22 +563,13 @@ export function analyzeComponentSource(src) {
   }
 
   for (const { body, factoryArg } of bodies) {
-    // Shadow DOM always ships (#474). Declarative Shadow DOM attaches ONLY
-    // during HTML parsing; an elided component that arrives via a client DOM
-    // insertion (a soft-nav swap, a streamed <webjs-suspense> boundary's
-    // replaceWith) would never re-attach its shadow root, because eliding
-    // drops the module that runs `attachShadow`. The analyser is context-free
-    // (it cannot tell whether a given component will be streamed or
-    // navigated to), so any shadow component is shipped.
-    if (declaresStaticTrue(body, 'shadow')) {
-      return { interactive: true, reason: 'declares static shadow (DSD must re-attach on a client swap)' };
-    }
-    // `static refresh = true` is the explicit opt-in to ship a bare async
-    // component so its stale-while-revalidate refresh runs ~after SSR; eliding
-    // a bare async component drops that on-load re-fetch (moot for request-
-    // stable data, the default), so an author who wants fresh-on-load opts in.
-    if (declaresStaticTrue(body, 'refresh')) {
-      return { interactive: true, reason: 'declares static refresh = true (keeps the on-load re-fetch)' };
+    // Interactivity-signal static conventions (`static shadow` / `static
+    // refresh = true`), driven by the INTERACTIVITY_STATIC_FIELDS registry so a
+    // new convention is added in one place (see its doc for why each ships).
+    for (const field of INTERACTIVITY_STATIC_FIELDS) {
+      if (declaresStaticTrue(body, field)) {
+        return { interactive: true, reason: STATIC_FIELD_REASONS[field] };
+      }
     }
     for (const hook of CLIENT_LIFECYCLE_HOOKS) {
       // A client lifecycle hook as a method (`hook(`) OR as an arrow class

package/src/dev.js

@@ -87,6 +87,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
+import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
@@ -685,6 +686,14 @@ export async function createRequestHandler(opts) {
     middleware: null,
     bodyLimits,
     logger,
+    // Test-mode serve gate (#806). Set ONLY by the browser-test harness
+    // (`@webjsdev/server/testing`'s `createBrowserTestHandler`), NEVER by
+    // `webjs dev` / `webjs start`. When true the source-serve gate is relaxed
+    // so ANY app file under appDir is servable (a component a browser test
+    // imports is not route-reachable, so it is absent from `browserBoundFiles`
+    // and would 404). The `.server.*` guardrail (source -> RPC/throw stub) and
+    // the core / vendor serving are unchanged, so no server source is exposed.
+    testMode: opts.testMode === true,
     moduleGraph: null,
     elidableComponents: new Set(),
     inertRouteModules: new Set(),
@@ -1221,18 +1230,31 @@ export async function createRequestHandler(opts) {
             // Rewrite the Request with the stripped URL, preserving method,
             // headers, and body. `duplex: 'half'` is required by the spec when
             // a body stream is present on a non-GET/HEAD request.
+            //
+            // SECURITY (#756): this is a fresh Request object, so it is NOT in
+            // the listener's out-of-band trusted-IP WeakMap (the Bun shell
+            // stamps the IP there instead of cloning the Request to set the
+            // header). Without carrying it forward, `clientIp` would fall back
+            // to the inbound `x-webjs-remote-ip` header that the copied
+            // `req.headers` still carries, which a client can spoof. So strip
+            // that header on the rebuild and propagate the framework-trusted IP
+            // across the new object, the same pattern page-action.js uses.
+            const headers = new Headers(req.headers);
+            headers.delete('x-webjs-remote-ip');
             const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
-            req = new Request(
+            const next = new Request(
               reqUrl.toString(),
               /** @type {any} */ ({
                 method: req.method,
-                headers: req.headers,
+                headers,
                 body: hasBody ? req.body : undefined,
                 duplex: hasBody ? 'half' : undefined,
                 redirect: req.redirect,
                 signal: req.signal,
               }),
             );
+            propagateTrustedRemoteIp(req, next);
+            req = next;
           }
         }
       }
@@ -1850,8 +1872,16 @@ async function handleCore(req, ctx) {
     // files (.server.{js,ts}) get a stub via the guardrail below; they
     // ARE included in browserBoundFiles because client code imports
     // them by path (the import rewrites to an RPC stub at request time).
-    const inGraph = state.browserBoundFiles && state.browserBoundFiles.has(abs);
-    if (abs.startsWith(appDir) && inGraph && (await exists(abs))) {
+    // In test mode any app file is servable (see the `state.testMode` note
+    // above); otherwise the file must be in the browser-bound module graph.
+    const inGraph = state.testMode || (state.browserBoundFiles && state.browserBoundFiles.has(abs));
+    // Containment: `abs` must be appDir itself or genuinely UNDER it. The
+    // trailing `sep` (matching the public-asset branch) stops a `..` path that
+    // resolves to a sibling sharing the appDir name-prefix (`/x/app` ->
+    // `/x/app-secrets/...`) from passing in test mode, where graph membership
+    // is not the gate.
+    const underAppDir = abs === appDir || abs.startsWith(appDir + sep);
+    if (underAppDir && inGraph && (await exists(abs))) {
       // Server-file guardrail: a file matching `.server.{js,ts,mjs,mts}`
       // MUST NEVER be served as source to the browser. The extension is
       // the path-level boundary; we re-verify it on every request (not
@@ -1903,6 +1933,20 @@ async function handleCore(req, ctx) {
       }
       return fileResponse(abs, { dev, immutable: versioned });
     }
+    // Dev hint (#751): the request is for a real app source module that EXISTS
+    // on disk but is NOT in the browser-bound graph, so the gate 404s it. The
+    // most common cause is a dynamic `import()` the static scanner cannot
+    // track: a string-literal `import('./x.ts')` IS tracked and servable, but a
+    // computed `import(expr)` / `import('./' + name)` cannot be resolved
+    // statically and falls through here. Surface the likely cause instead of a
+    // bare 404 so the author is not left guessing. Dev-only and diagnostic; it
+    // does not change the 404 status, only the body + a server log line.
+    if (dev && abs.startsWith(appDir) && /\.m?[jt]s$/.test(abs) && (await exists(abs))) {
+      const rel = relative(appDir, abs);
+      const hint = `[webjs] 404: ${rel} exists but is not reachable from any browser-bound entry, so it is not servable. If you load it via a dynamic import(), use a STRING-LITERAL specifier (e.g. import('./x.ts')) so the scanner can track it; a computed import(expr) cannot be resolved statically and will 404. Otherwise this module is simply unreferenced by client code.`;
+      console.warn(hint);
+      return new Response(hint, { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+    }
   }
 
   // Metadata routes: /sitemap.xml, /robots.txt, /icon, /opengraph-image, etc.

package/src/importmap.js

@@ -459,6 +459,42 @@ export function buildImportMap(opts = {}) {
   return out;
 }
 
+/**
+ * Resolve a set of bare vendor specifiers to `modulepreload` targets (#754), so
+ * SSR can flatten the vendor CDN waterfall: instead of discovering each vendor
+ * module level by level (fetch app module -> parse -> fetch vendor -> parse ...),
+ * the reached vendor URLs are hinted up front and fetched in parallel.
+ *
+ * The href is taken DIRECTLY from `buildImportMap().imports[spec]`, so it is
+ * BYTE-IDENTICAL to the importmap target (same base-path + `?v` rewrite): a
+ * differing href would make the browser treat the preload and the import as two
+ * resources and double-fetch. The matching `integrity` comes from the same map.
+ * A specifier NOT in the importmap (an unpinned / unreached / elided vendor)
+ * yields nothing, so this never over-fetches. Duplicate hrefs are collapsed.
+ *
+ * Framework runtime specifiers (`@webjsdev/core`...) are excluded: core is
+ * served same-origin and already on the boot path, not a CDN-waterfall vendor.
+ *
+ * @param {Iterable<string>} specifiers  bare specifiers reached by the page
+ * @returns {Array<{ href: string, integrity?: string }>}
+ */
+export function vendorPreloadTargets(specifiers) {
+  const specs = [...(specifiers || [])];
+  if (!specs.length) return [];
+  const map = buildImportMap();
+  /** @type {Array<{ href: string, integrity?: string }>} */
+  const out = [];
+  const seen = new Set();
+  for (const spec of specs) {
+    if (spec === '@webjsdev/core' || spec.startsWith('@webjsdev/core/')) continue;
+    const href = map.imports[spec];
+    if (!href || seen.has(href)) continue;
+    seen.add(href);
+    out.push({ href, integrity: map.integrity ? map.integrity[href] : undefined });
+  }
+  return out;
+}
+
 /**
  * Derive the cross-origin vendor CDN origins from the resolved vendor
  * importmap, most-common first (issue #243, auto vendor preconnect). For an

package/src/listener-bun.js

@@ -3,9 +3,15 @@
  * selected when the host runtime is Bun. Bun's server is `Request`/`Response`
  * native, so this path skips the node:http `toWebRequest` / `sendWebResponse`
  * bridge entirely and hands the app's `handle(req): Response` straight to
- * `Bun.serve({ fetch })`. A benchmark on the full listening path (node:http
- * compat on Bun vs `Bun.serve`) measured ~1.9x more req/s, which is what justifies
- * a second shell rather than running the node compat path on Bun.
+ * `Bun.serve({ fetch })`. A microbenchmark of the LISTENING PATH ONLY (a trivial
+ * handler: node:http compat on Bun vs `Bun.serve`) measured ~1.9x more req/s,
+ * which is what justifies a second shell rather than running the node compat path
+ * on Bun. That figure is the listening-path delta, NOT end-to-end throughput: for
+ * a real SSR page the render cost dominates and the listener delta is small (see
+ * the end-to-end benchmark in `scripts/bench-listener.mjs`, #756). The hot path
+ * is kept allocation-lean: the remote IP is stamped out of band (no per-request
+ * `Request` clone, #756) and a buffered response is compressed synchronously (no
+ * per-response stream bridge).
  *
  * Feature parity with the node shell, routed through the shared
  * `listener-core.js` so the two cannot drift:
@@ -39,6 +45,7 @@ import { EventEmitter } from 'node:events';
 import { Readable, pipeline } from 'node:stream';
 import { matchApi } from './router.js';
 import { registerClient } from './broadcast.js';
+import { setTrustedRemoteIp } from './rate-limit.js';
 import {
   isCompressible,
   isEventsPath,
@@ -47,8 +54,10 @@ import {
   makeShutdown,
   negotiateEncoding,
   createCompressor,
+  compressBufferSync,
+  MAX_SYNC_COMPRESS_BYTES,
   varyWithAcceptEncoding,
-  webStreamChunks,
+  readBufferedOrStream,
 } from './listener-core.js';
 
 /* global Bun */
@@ -93,9 +102,9 @@ export function startBunListener(ctx) {
         // hints still ship in the rendered <head>, so the only loss is the
         // head-start during SSR compute, not the preloads themselves.
 
-        const webReq = stampRemoteIp(req, srv);
-        const resp = await app.handle(webReq);
-        return compress ? maybeCompress(resp, req) : resp;
+        stampRemoteIp(req, srv);
+        const resp = await app.handle(req);
+        return compress ? await maybeCompress(resp, req) : resp;
       } catch (e) {
         logger.error('request pipeline threw', { err: e instanceof Error ? e.stack : String(e) });
         return new Response(
@@ -287,20 +296,21 @@ function bunSseResponse(req, hub, app) {
 }
 
 /**
- * Stamp the framework-trusted remote IP from Bun's `server.requestIP`, after
- * stripping any spoofed inbound `x-webjs-remote-ip` (the node `toWebRequest`
- * equivalent, which reads `req.socket.remoteAddress`). Re-wraps the request with
- * the adjusted headers, preserving method + body.
+ * Stamp the framework-trusted remote IP from Bun's `server.requestIP`,
+ * out-of-band via `setTrustedRemoteIp` (#756). The previous implementation
+ * cloned the whole `Request` (`new Request(req, { headers })`) on EVERY request
+ * just to set one header; the WeakMap channel avoids that hot-path reallocation.
+ * The stamp is authoritative (`clientIp` reads it and ignores the inbound
+ * `x-webjs-remote-ip` header), so a client cannot spoof it even though the
+ * unmodified request still carries any inbound copy. Always stamps (with `''`
+ * when no IP is available) so the inbound header is never trusted on Bun.
  * @param {Request} req
  * @param {any} srv
  */
 function stampRemoteIp(req, srv) {
-  const headers = new Headers(req.headers);
-  headers.delete('x-webjs-remote-ip');
   let ip;
   try { ip = srv.requestIP(req)?.address; } catch {}
-  if (ip) headers.set('x-webjs-remote-ip', ip);
-  return new Request(req, { headers });
+  setTrustedRemoteIp(req, ip || '');
 }
 
 /**
@@ -308,35 +318,70 @@ function stampRemoteIp(req, srv) {
  * negotiation + compressor factory the node shell uses (shared in
  * `listener-core.js`). `node:zlib` runs natively on Bun, so this gives **brotli
  * on Bun** (the web `CompressionStream` used before had no brotli) and full
- * compression parity with the node shell. The body is bridged web -> node ->
- * web (`Readable.from(webStreamChunks(...))` -> `compressor` -> `Readable.toWeb`,
- * driven by `pipeline`; NOT `Readable.fromWeb`, which does not propagate a
- * mid-stream source error through `pipeline` on Bun, the #509 hang). Skips an
- * already-encoded body and a non-compressible media type (`isCompressible`
- * already excludes `text/event-stream`).
+ * compression parity with the node shell.
+ *
+ * A BUFFERED body (the common SSR page / JSON / file response, detected by
+ * `readBufferedOrStream` peeking a single bounded chunk) is compressed
+ * SYNCHRONOUSLY (`compressBufferSync`), skipping the per-response
+ * web -> node -> web stream bridge entirely (#756). A genuinely STREAMED body
+ * (Suspense, an action / route stream) or an oversized one keeps the bridge
+ * (`Readable.from(peeked.stream)` -> `compressor` -> `Readable.toWeb`, driven by
+ * `pipeline`; NOT `Readable.fromWeb`, which does not propagate a mid-stream
+ * source error through `pipeline` on Bun, the #509 hang). The sync and streamed
+ * paths use the SAME algo + params, so WITHIN a runtime the buffered fast path
+ * and the streaming bridge produce identical bytes (a buffered body is not
+ * served differently from a streamed one). Across runtimes the exact bytes can
+ * differ for gzip / deflate (Bun's bundled zlib is not the same build as Node's,
+ * so the compressed output is not guaranteed identical, byte-for-byte; brotli
+ * does match), which is fine since each response is self-describing via
+ * `content-encoding` and a client just decodes it. Skips an already-encoded body
+ * and a non-compressible media type (`isCompressible` already excludes
+ * `text/event-stream`).
  * @param {Response} resp
  * @param {Request} req
  */
-function maybeCompress(resp, req) {
+async function maybeCompress(resp, req) {
   if (!resp.body) return resp;
   if (resp.headers.has('content-encoding')) return resp;
   if (!isCompressible(resp.headers.get('content-type'))) return resp;
   const encoding = negotiateEncoding(req.headers.get('accept-encoding'));
-  const compressor = createCompressor(encoding);
-  if (!compressor) return resp;
+  if (!encoding) return resp;
 
   const headers = new Headers(resp.headers);
   headers.set('content-encoding', encoding);
-  headers.delete('content-length');
   headers.set('vary', varyWithAcceptEncoding(headers.get('vary')));
-  // Feed the web body into the compressor through the reader-loop generator (NOT
-  // Readable.fromWeb, which does not propagate a mid-stream source error through
-  // `pipeline` on Bun, the #509 hang) and drive it with `pipeline` so a source
-  // error (or a client disconnect destroying the output) tears down the whole
-  // chain instead of leaking/hanging the compressor. Backpressure is preserved:
-  // a slow client stalls `toWeb`, which stalls the compressor, which pauses the
-  // source.
-  const source = Readable.from(webStreamChunks(resp.body));
+
+  // Buffered-body fast path (#756): peek the body to tell a single bounded
+  // buffered chunk (the common SSR page / JSON / file response) from a genuinely
+  // streamed body (Suspense, an action / route stream) WITHOUT buffering a real
+  // stream. A buffered body cannot error mid-stream, so compress it synchronously
+  // and skip the per-response web -> node -> web stream bridge entirely. The sync
+  // path and the streaming bridge share the SAME algo + params, so within this
+  // runtime a buffered body and a streamed one compress identically (the wire is
+  // self-describing via content-encoding either way). A streamed / oversized body
+  // falls through to the bridge below.
+  const peeked = await readBufferedOrStream(resp.body, MAX_SYNC_COMPRESS_BYTES);
+  if (peeked.buffered !== undefined) {
+    const out = compressBufferSync(encoding, peeked.buffered);
+    headers.set('content-length', String(out.length));
+    return new Response(out, { status: resp.status, statusText: resp.statusText, headers });
+  }
+
+  headers.delete('content-length');
+  // Allocate the streaming compressor ONLY on the streamed path: the buffered
+  // fast path above used `compressBufferSync` and never needs a Transform, so
+  // hoisting this would waste a native zlib/brotli handle on the common case.
+  // `encoding` is guaranteed br/gzip/deflate (negotiateEncoding), so
+  // `createCompressor` never returns null here.
+  const compressor = createCompressor(encoding);
+  // Feed the (peeked + drained) web body into the compressor through the reader
+  // loop (NOT Readable.fromWeb, which does not propagate a mid-stream source
+  // error through `pipeline` on Bun, the #509 hang) and drive it with `pipeline`
+  // so a source error (or a client disconnect destroying the output) tears down
+  // the whole chain instead of leaking/hanging the compressor. Backpressure is
+  // preserved: a slow client stalls `toWeb`, which stalls the compressor, which
+  // pauses the source.
+  const source = Readable.from(peeked.stream);
   pipeline(source, compressor, () => {});
   const body = Readable.toWeb(compressor);
   return new Response(body, { status: resp.status, statusText: resp.statusText, headers });

package/src/listener-core.js

@@ -16,7 +16,11 @@
  * and its own `closeServer` thunk, and reuses everything else verbatim.
  */
 import { pathToFileURL } from 'node:url';
-import { createBrotliCompress, createGzip, createDeflate, constants as zlibConstants } from 'node:zlib';
+import {
+  createBrotliCompress, createGzip, createDeflate,
+  brotliCompressSync, gzipSync, deflateSync,
+  constants as zlibConstants,
+} from 'node:zlib';
 import { stripBasePath } from './base-path.js';
 
 /** The dev live-reload SSE path (matched after base-path stripping). */
@@ -96,6 +100,37 @@ export function createCompressor(encoding) {
   return null;
 }
 
+/**
+ * The largest buffered body that takes the SYNCHRONOUS compression fast path
+ * (#756). Sync `node:zlib` blocks the event loop, whereas the streaming
+ * compressor offloads to the libuv threadpool, so the sync path is a win ONLY
+ * for small bodies (a typical SSR HTML page) where the per-response stream
+ * bridge dominates; a larger buffered body keeps the non-blocking stream path.
+ */
+export const MAX_SYNC_COMPRESS_BYTES = 256 * 1024;
+
+/**
+ * Compress an already-buffered body synchronously, byte-for-byte identical to
+ * the streaming `createCompressor` ON THE SAME RUNTIME (same algorithm + params:
+ * brotli quality 4, gzip / deflate level 6, over the same `node:zlib`), so a
+ * buffered fast path and a streamed slow path produce the same wire bytes within
+ * a runtime (#756). Across runtimes the exact gzip / deflate bytes can differ
+ * (Bun's bundled zlib is not Node's build; brotli matches), which is fine since
+ * each response is self-describing via `content-encoding`. For a buffered body
+ * (one that cannot error mid-stream) this skips the per-response
+ * web -> node -> web stream bridge entirely. Returns null for an unknown / empty
+ * encoding so the caller leaves the body uncompressed.
+ * @param {'br' | 'gzip' | 'deflate' | ''} encoding
+ * @param {Uint8Array} buf
+ * @returns {Buffer | null}
+ */
+export function compressBufferSync(encoding, buf) {
+  if (encoding === 'br') return brotliCompressSync(buf, { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 } });
+  if (encoding === 'gzip') return gzipSync(buf, { level: 6 });
+  if (encoding === 'deflate') return deflateSync(buf, { level: 6 });
+  return null;
+}
+
 /**
  * Merge `Accept-Encoding` into an existing `Vary` header (or create it) without
  * duplicating, so compressing a response that already varies (on `Cookie`, an
@@ -135,6 +170,145 @@ export async function* webStreamChunks(web) {
   }
 }
 
+/** An async generator that throws on first pull (a source that errored before
+ * any output), so the caller's `pipeline` tears down exactly as it would for a
+ * mid-stream error. @param {unknown} err */
+async function* failingStream(err) { throw err; }
+
+/** Yield a fixed set of already-read chunks with no further reads (the source is
+ * already exhausted). @param {Uint8Array[]} chunks */
+async function* justChunks(chunks) { for (const c of chunks) yield c; }
+
+/**
+ * Drain a reader after replaying already-peeked `prefix` chunks, mirroring
+ * `webStreamChunks`' error + early-cancel semantics (so the #509 hang fix is
+ * preserved for the reconstructed stream). If `pendingError` is set (the peek's
+ * second read rejected, a mid-stream source error), the prefix is replayed and
+ * then the error is rethrown.
+ * @param {Uint8Array[]} prefix
+ * @param {ReadableStreamDefaultReader} reader
+ * @param {unknown} pendingError
+ */
+async function* drainAfter(prefix, reader, pendingError) {
+  let finished = false;
+  try {
+    for (const c of prefix) yield c;
+    if (pendingError) { finished = true; throw pendingError; }
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) { finished = true; return; }
+      yield value;
+    }
+  } finally {
+    if (!finished) { try { await reader.cancel(); } catch {} }
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+/** Sentinel: the classifying second read has not settled within a macrotask, so
+ * the body is genuinely streaming and must not be withheld (#756). */
+const STREAM_PENDING = Symbol('webjs.stream-pending');
+
+/**
+ * Drain a reader for a STREAMED body whose classifying second read is still
+ * in flight (`secondP`, a settled-shape promise `{ r }` | `{ e }`). Yields the
+ * already-peeked `firstChunk`, then CONSUMES the in-flight second read (never
+ * issuing a duplicate `reader.read()`), then drains the rest. Same error +
+ * early-cancel teardown as `drainAfter` / `webStreamChunks` (the #509 fix).
+ * @param {Uint8Array} firstChunk
+ * @param {ReadableStreamDefaultReader} reader
+ * @param {Promise<{ r?: ReadableStreamReadResult<Uint8Array>, e?: unknown }>} secondP
+ */
+async function* drainAfterPending(firstChunk, reader, secondP) {
+  let finished = false;
+  try {
+    yield firstChunk;
+    const settled = await secondP;
+    if (settled.e !== undefined) { finished = true; throw settled.e; }
+    if (settled.r.done) { finished = true; return; }
+    yield settled.r.value;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) { finished = true; return; }
+      yield value;
+    }
+  } finally {
+    if (!finished) { try { await reader.cancel(); } catch {} }
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+/**
+ * Decide whether a web body is a single bounded buffered chunk (the common SSR
+ * page / JSON / file response) or a genuinely streamed body (Suspense, an action
+ * / route `ReadableStream`), WITHOUT buffering a real stream and WITHOUT
+ * withholding a streamed body's first byte (#756). It peeks the first chunk, then
+ * classifies on the SECOND read, but does NOT block on it: a buffered Response
+ * (built from a string / Uint8Array) has an already-closed underlying stream, so
+ * its second read settles on the next microtask; a streamed body's second chunk
+ * may be arbitrarily far in the future (a Suspense boundary resolving), and
+ * awaiting it would stall the status line + first byte until then. So the second
+ * read is RACED against a macrotask sentinel: if it settles first AND is `done`
+ * (single chunk) within `maxBytes`, the body is buffered and returned as bytes so
+ * the caller can sync-compress and skip the stream bridge; otherwise (still
+ * pending = streaming, or multi-chunk, oversized, empty, or a mid-stream error)
+ * it returns an async iterable that replays the peeked chunk(s) then drains the
+ * rest, with the same error + cancel semantics as `webStreamChunks`.
+ *
+ * @param {ReadableStream} web
+ * @param {number} maxBytes
+ * @returns {Promise<{ buffered: Uint8Array } | { stream: AsyncIterable<Uint8Array> }>}
+ */
+export async function readBufferedOrStream(web, maxBytes) {
+  const reader = web.getReader();
+  let first;
+  try {
+    first = await reader.read();
+  } catch (e) {
+    // Source errored before any output: hand back a stream that rethrows it.
+    try { reader.releaseLock(); } catch {}
+    return { stream: failingStream(e) };
+  }
+  if (first.done) {
+    try { reader.releaseLock(); } catch {}
+    return { buffered: new Uint8Array(0) };
+  }
+  const firstChunk = first.value;
+
+  // Issue the classifying second read but DO NOT await it directly: race it
+  // against a macrotask sentinel so a streamed body (whose second chunk is far
+  // off) is handed back immediately as a stream instead of stalling first paint.
+  const secondP = reader.read().then((r) => ({ r }), (e) => ({ e }));
+  const settled = await Promise.race([
+    secondP,
+    new Promise((res) => { setImmediate(() => res(STREAM_PENDING)); }),
+  ]);
+  if (settled === STREAM_PENDING) {
+    // Still in flight after a macrotask: a genuinely streamed body. Emit the
+    // first chunk now and continue from the in-flight second read (consumed by
+    // the generator, never re-issued).
+    return { stream: drainAfterPending(firstChunk, reader, secondP) };
+  }
+  if (settled.e !== undefined) {
+    // The second read errored on a short body (a mid-stream source error):
+    // replay the first chunk then rethrow, matching webStreamChunks teardown.
+    return { stream: drainAfter([firstChunk], reader, settled.e) };
+  }
+  const second = settled.r;
+  if (second.done) {
+    try { reader.releaseLock(); } catch {}
+    if (firstChunk.byteLength <= maxBytes) return { buffered: firstChunk };
+    // One chunk but too large to block the event loop on a sync compress: stream
+    // it. The source is already exhausted (second read was `done`), so just
+    // replay the single chunk with no further reads.
+    return { stream: justChunks([firstChunk]) };
+  }
+  // Two quick chunks (a small multi-chunk buffered body): not a single buffer,
+  // so stream it (replay both, then drain the rest). The second read is already
+  // consumed, so drainAfter continues from the third chunk.
+  return { stream: drainAfter([firstChunk, second.value], reader, null) };
+}
+
 /**
  * Load a `route.{js,ts}` module for its `WS` export, cache-busting in dev so a
  * code edit is picked up per connection. Shared by the node WebSocket subsystem