@webjsdev/server 0.8.38 → 0.8.40

package/src/check.js

@@ -1030,14 +1030,18 @@ export async function checkConventions(appDir) {
  * `middleware.ts` / `route.ts` (server-only, never page/layout/component
  * entries, so they are not in the candidate set to begin with).
  *
- * Known limitation: a DYNAMIC `import('./x.server.ts')` is invisible to this
- * rule. The framework's import scanner (`IMPORT_RE` in module-graph.js) matches
- * only static `import`/`export … from`, not the `import(` call form, so a
- * dynamic server import is not a graph edge here. This is deliberate and
- * consistent with the framework-wide graph: a dynamic import is also not elided
- * framework-wide, and its crash is deferred to call time (when the chunk is
- * fetched), not module load. Catching it would mean teaching the shared scanner
- * about `import(`, which is out of scope for this rule.
+ * Scope note for dynamic imports: a string-literal `import('./widget.ts')` IS
+ * tracked by the module graph now (#751), but only as a GATE edge (so the
+ * lazily-imported module is servable); this rule's server-import detection
+ * still runs over STATIC edges only (`transitiveDeps`), so a dynamic
+ * `import('./x.server.ts')` of a no-`'use server'` utility is not flagged here.
+ * That is deliberate: the throw-at-load crash is deferred to call time (when
+ * the module is actually fetched), not module load, and a dynamic import is
+ * also not elided framework-wide. A computed `import(expr)` cannot be resolved
+ * statically at all; rather than a false-positive-prone check rule (a computed
+ * import of an npm specifier or an otherwise-reachable app module is perfectly
+ * valid, so it fails the check-is-correctness-only dividing line), the dev
+ * server surfaces it with a 404 hint when the target 404s (see dev.js #751).
  *
  * @param {string} appDir
  * @param {Violation[]} violations  appended to in place

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';
@@ -268,32 +269,6 @@ export async function readSeedEnabled(appDir) {
   return true;
 }
 
-/**
- * Read the Bun zero-install version-pinning switch (#685). The `WEBJS_PIN` env
- * override wins (same grammar as `WEBJS_SEED`), otherwise
- * `{ "webjs": { "pin": false } }` disables it. Default ON (opt-out). Consulted
- * only on Bun: the rewrite injects inline-version specifiers that Bun's
- * auto-install honors so zero-install fetches the pinned version, not latest
- * (#684). Node zero-install pinning is #669's separate concern.
- * @param {string} appDir
- * @returns {Promise<boolean>}
- */
-export async function readPinEnabled(appDir) {
-  const raw = process.env.WEBJS_PIN;
-  if (raw != null && raw !== '') {
-    const v = String(raw).trim().toLowerCase();
-    if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
-    if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
-  }
-  try {
-    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
-    if (pkg && pkg.webjs && pkg.webjs.pin === false) return false;
-  } catch {
-    // No package.json, malformed JSON, or unreadable. Keep the default.
-  }
-  return true;
-}
-
 /**
  * Read the client-router switch (`webjs.clientRouter`) from the app's
  * package.json (#629). Default `true`: the client router auto-enables in the
@@ -594,11 +569,7 @@ export async function createRequestHandler(opts) {
   // Read once (not per-rebuild): the hook is global and cannot be cleanly
   // un-installed, so toggling needs a restart. Disabled -> no hook, no ambient
   // collector wrap in ssr.js, and module loading stays byte-identical.
-  // Pinning (#685) is Bun-only and independent of seeding, so install the hook
-  // when EITHER is on (on Bun they share one onLoad).
-  const seedEnabled = await readSeedEnabled(appDir);
-  const pinEnabled = serverRuntime() === 'bun' && await readPinEnabled(appDir);
-  if (seedEnabled || pinEnabled) await registerSeedHooks({ appDir, seedEnabled, pinEnabled });
+  if (await readSeedEnabled(appDir)) await registerSeedHooks();
 
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no
@@ -1251,18 +1222,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;
           }
         }
       }
@@ -1933,6 +1917,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