@webjsdev/server 0.8.27 → 0.8.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.27",
+  "version": "0.8.28",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
@@ -51,5 +51,8 @@
   ],
   "engines": {
     "node": ">=24.0.0"
+  },
+  "optionalDependencies": {
+    "amaro": "^1.1.10"
   }
 }

package/src/action-seed.js

@@ -258,6 +258,18 @@ function seedLoadHook(url, context, nextLoad) {
  * second call.
  */
 export function registerSeedHooks() {
+  // The seed facade rides Node's synchronous `module.registerHooks` (#472).
+  // Bun (and any runtime without that API, #508) cannot install the hook, so
+  // seeding simply stays OFF there: `seedingEnabled()` returns false, ssr.js
+  // emits no seed block, and the client RPC stub falls back to a normal fetch.
+  // This is the same fail-open posture as a key miss, never wrong data.
+  if (typeof nodeModule.registerHooks !== 'function') {
+    if (!_registered) {
+      _registered = true;
+      console.warn('[webjs] SSR action-result seeding (#472) is disabled: module.registerHooks is unavailable on this runtime (e.g. Bun). Async-render components will re-fetch on hydration; no correctness impact.');
+    }
+    return;
+  }
   _enabled = true;
   if (_registered) return;
   _registered = true;

package/src/dev.js

@@ -1,50 +1,15 @@
 import { createServer as createHttp1Server } from 'node:http';
 import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
 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';
-// Namespace import, NOT `import { stripTypeScriptTypes }`. On Node < 22.13 the
-// `stripTypeScriptTypes` named export does not exist, and a NAMED import of a
-// missing builtin export is a LINK-TIME SyntaxError that fires before any
-// module body runs, which would defeat the Node-version preflight (issue #238)
-// by crashing the import of @webjsdev/server itself. A namespace import links
-// on every Node (the property is just `undefined` at runtime on old Node), so
-// importing @webjsdev/server succeeds and `assertNodeVersion()` at the top of
-// createRequestHandler throws the clean "you need Node 24+" message instead.
-import * as nodeModule from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Server-side `.ts` imports are handled natively by Node 24+'s default
-// type-stripping (`process.features.typescript === 'strip'`). No loader
-// hook required. The browser-bound TypeScript request handler uses
-// `module.stripTypeScriptTypes` for the same transform, so SSR and
-// hydration produce identical JS.
-//
-// Runtime backing: Node ships `stripTypeScriptTypes` via the `amaro`
-// package internally (wraps SWC's WASM TypeScript transform in a
-// position-preserving strip-only mode). If the framework ever needs
-// to run on Bun, Deno, or another runtime that does NOT expose the
-// equivalent built-in, we will need to install `amaro` directly (or
-// an equivalent: Sucrase preserves lines but not columns; SWC's
-// strip-only also works). The fast-path `stripTs` helper would
-// change one import line.
-//
-// Suppress the one-shot ExperimentalWarning that Node prints the
-// first time `stripTypeScriptTypes` is called. The API is committed
-// per Node 24's release notes; the warning is a holdover. We keep
-// every other warning intact.
-const _origEmitWarning = process.emitWarning.bind(process);
-process.emitWarning = function (warning, type, code, ctor) {
-  const msg = warning && warning.message ? warning.message : String(warning);
-  if (
-    (type === 'ExperimentalWarning' || (warning && warning.name === 'ExperimentalWarning')) &&
-    msg.includes('stripTypeScriptTypes')
-  ) {
-    return;
-  }
-  return _origEmitWarning(warning, type, code, ctor);
-};
+// type-stripping (`process.features.typescript === 'strip'`) or by Bun. The
+// BROWSER-bound `.ts` request handler erases types via the pluggable stripper in
+// `./ts-strip.js` (Node's built-in `module.stripTypeScriptTypes`, or `amaro` on
+// Bun), so SSR and hydration produce identical JS on either runtime (#508).
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
@@ -61,6 +26,7 @@ import {
   hashFile,
 } from './actions.js';
 import { registerSeedHooks } from './action-seed.js';
+import { stripTypeScript, ensureStripper } from './ts-strip.js';
 import { defaultLogger } from './logger.js';
 import { assertNodeVersion } from './node-version.js';
 import { applyEnvValidation } from './env-schema.js';
@@ -68,6 +34,16 @@ import { withRequest, setCspNonce, setBodyLimits, setRequestId, requestId as get
 import { buildInfoResponse } from './build-info.js';
 import { readCspConfig, mintNonce, buildCspHeader, cspHeaderName } from './csp.js';
 import { attachWebSocket } from './websocket.js';
+import {
+  SseHub,
+  serverRuntime,
+  isCompressible,
+  installProcessHandlers,
+  makeShutdown,
+  negotiateEncoding,
+  createCompressor,
+  varyWithAcceptEncoding,
+} from './listener-core.js';
 import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from './vendor.js';
 import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport } from './module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from './component-scanner.js';
@@ -441,6 +417,10 @@ export async function createRequestHandler(opts) {
   // Throw a clear Error here so an embedded host (Express/Fastify/Bun/Deno)
   // gets the actionable message at boot, not a cryptic API failure mid-request.
   assertNodeVersion({ onFail: 'throw' });
+  // Resolve the TS stripper backend at boot (#508): the Node built-in, or amaro
+  // on Bun. Doing it here pays the (one-time) amaro import up front and surfaces
+  // a missing-amaro error at boot rather than on the first `.ts` request.
+  await ensureStripper();
   const appDir = resolve(opts.appDir);
   // Load <appDir>/.env into process.env BEFORE anything else.
   // buildActionIndex below imports server-only files (lib/*.server.ts,
@@ -1402,26 +1382,28 @@ export async function startServer(opts) {
   const compress = opts.compress ?? !dev;
   const logger = opts.logger || defaultLogger({ dev });
 
-  /** @type {Set<import('node:http').ServerResponse>} */
-  const sseClients = new Set();
-  const app = await createRequestHandler({
-    ...opts,
-    logger,
-    onReload: () => {
-      for (const res of sseClients) {
-        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 {}
-      }
-    },
-  });
+  // Runtime-neutral SSE registry + fanout (shared by the node:http and Bun.serve
+  // shells via listener-core.js, so live-reload + the dev error overlay behave
+  // identically on both). Built before the handler so its onReload / onDevError
+  // callbacks can fan out through it.
+  const hub = new SseHub();
+  let app;
+  try {
+    app = await createRequestHandler({
+      ...opts,
+      logger,
+      onReload: () => hub.reload(),
+      // 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) => hub.devError(frame),
+    });
+  } catch (e) {
+    // The hub starts its keepalive interval in its constructor (before this
+    // await), so a boot failure must clear it rather than leak a live timer.
+    hub.closeAll();
+    throw e;
+  }
 
   /** @type {AbortController | null} */
   let watcherAbort = null;
@@ -1451,14 +1433,42 @@ export async function startServer(opts) {
     })();
   }
 
-  // SSE keepalive: send a comment frame every 25s to defeat proxy idle timeouts.
-  // Cheap (no event listeners on the client side) and safe: comments are ignored.
-  const keepalive = setInterval(() => {
-    for (const res of sseClients) {
-      try { res.write(`: ka\n\n`); } catch {}
-    }
-  }, 25_000);
-  keepalive.unref();
+  // Inbound server timeouts (issue #237). On node these are the node:http
+  // built-ins; on Bun the node `requestTimeout` maps to Bun's single
+  // `idleTimeout`. Defends against slowloris and hung connections. Overridable
+  // via `webjs.requestTimeoutMs` / `headersTimeoutMs` / `keepAliveTimeoutMs` in
+  // package.json or the matching WEBJS_*_MS env vars; `0` disables that timeout.
+  const timeouts = await readServerTimeoutsFromApp(app.appDir);
+
+  // The shared context both listener shells consume. The transport-specific glue
+  // (node:http `res.write`, Bun.serve streaming Response) lives in each shell;
+  // the SSE registry, the live-reload path predicate, the WS module loader, and
+  // the lifecycle wiring are shared via listener-core.js so the shells can't drift.
+  /** @type {import('./listener-types.js').ListenerContext} */
+  const ctx = { app, dev, compress, logger, hub, port, basePathStr: basePath(), timeouts, watcherAbort };
+
+  // Pick the adapter by runtime. Bun is Request/Response-native, so its shell
+  // skips the node:http bridge (toWebRequest/sendWebResponse) for ~1.9x more
+  // req/s on the listening path (#511); the Bun shell is dynamically imported so
+  // the `Bun.*` global is never referenced on Node.
+  if (serverRuntime() === 'bun') {
+    const { startBunListener } = await import('./listener-bun.js');
+    return startBunListener(ctx);
+  }
+  return startNodeListener(ctx);
+}
+
+/**
+ * The node:http listener shell: the original `startServer` socket path, now
+ * reading the shared `ListenerContext`. Bridges node `IncomingMessage` ->
+ * `Request` (`toWebRequest`) and `Response` -> `ServerResponse`
+ * (`sendWebResponse`), emits 103 Early Hints, and drives SSE + WS over node
+ * primitives, sharing the SSE registry + lifecycle wiring with the Bun shell.
+ * @param {import('./listener-types.js').ListenerContext} ctx
+ * @returns {{ server: import('node:http').Server, close: () => Promise<void> }}
+ */
+function startNodeListener(ctx) {
+  const { app, dev, compress, logger, hub, port, basePathStr, timeouts, watcherAbort } = ctx;
 
   const server = makeHttpServer(async (req, res) => {
     try {
@@ -1468,7 +1478,7 @@ export async function startServer(opts) {
       // base-path-stripped pathname so the reload stream answers at
       // `<basePath>/__webjs/events` under a sub-path deploy (#256). With no
       // basePath this is a pure pass-through (the bare path still matches).
-      if (stripBasePath(url.pathname, basePath()) === '/__webjs/events') {
+      if (stripBasePath(url.pathname, basePathStr) === '/__webjs/events') {
         if (!dev) { res.writeHead(404); res.end(); return; }
         res.writeHead(200, {
           'content-type': 'text/event-stream',
@@ -1476,7 +1486,13 @@ export async function startServer(opts) {
           connection: 'keep-alive',
         });
         res.write(`event: hello\ndata: webjs\n\n`);
-        sseClients.add(res);
+        // Register a node client wrapper in the shared hub: the fanout + keepalive
+        // live in SseHub; only the transport write (res.write / res.end) is local.
+        const client = {
+          send: (s) => { try { res.write(s); } catch {} },
+          close: () => { try { res.end(); } catch {} },
+        };
+        hub.add(client);
         // 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.
@@ -1484,7 +1500,7 @@ export async function startServer(opts) {
         if (pending) {
           try { res.write(`event: webjs-error\ndata: ${JSON.stringify(pending)}\n\n`); } catch {}
         }
-        res.socket?.on('close', () => sseClients.delete(res));
+        res.socket?.on('close', () => hub.remove(client));
         return;
       }
 
@@ -1519,16 +1535,10 @@ export async function startServer(opts) {
     }
   });
 
-  // Inbound server timeouts (issue #237), node:http built-ins. Defends against
-  // slowloris and hung connections: `requestTimeout` bounds the time to receive
-  // the WHOLE request, `headersTimeout` the time to receive just the headers
-  // (node measures both from the same request start, so it is kept strictly
-  // under requestTimeout to actually fire), and `keepAliveTimeout` the idle
-  // window before a kept-alive socket is closed. Secure production defaults,
-  // overridable via `webjs.requestTimeoutMs` / `headersTimeoutMs` /
-  // `keepAliveTimeoutMs` in package.json or the matching WEBJS_*_MS env vars.
-  // A value of 0 disables that timeout (node's own no-limit sentinel).
-  const timeouts = await readServerTimeoutsFromApp(app.appDir);
+  // node:http built-in timeouts: `requestTimeout` bounds the time to receive the
+  // WHOLE request, `headersTimeout` just the headers (kept strictly under
+  // requestTimeout so it actually fires), `keepAliveTimeout` the idle window
+  // before a kept-alive socket is closed.
   server.requestTimeout = timeouts.requestTimeout;
   server.headersTimeout = timeouts.headersTimeout;
   server.keepAliveTimeout = timeouts.keepAliveTimeout;
@@ -1546,7 +1556,10 @@ export async function startServer(opts) {
     app.warmup();
   });
 
-  const shutdown = gracefulShutdown(server, sseClients, logger);
+  const closeServer = () => new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve(undefined)));
+  });
+  const shutdown = makeShutdown({ closeServer, hub, logger });
   process.once('SIGINT', () => shutdown('SIGINT'));
   process.once('SIGTERM', () => shutdown('SIGTERM'));
 
@@ -1559,6 +1572,9 @@ export async function startServer(opts) {
     server,
     close: () => new Promise((r) => {
       if (watcherAbort) watcherAbort.abort();
+      // Clear the shared SSE keepalive timer so repeated startServer/close cycles
+      // (e.g. across a test run) don't accumulate live intervals.
+      hub.closeAll();
       server.close(() => r());
     }),
   };
@@ -1963,54 +1979,6 @@ function makeHttpServer(handler) {
   return createHttp1Server(handler);
 }
 
-/**
- * Install once-only process error handlers. Idempotent across multiple
- * `startServer` calls in the same process.
- *
- * @param {import('./logger.js').Logger} logger
- * @param {() => void} onFatal
- */
-function installProcessHandlers(logger, onFatal) {
-  if (/** @type any */ (globalThis).__webjsProcHandlers) return;
-  /** @type any */ (globalThis).__webjsProcHandlers = true;
-  process.on('unhandledRejection', (reason) => {
-    logger.error('unhandledRejection', {
-      err: reason instanceof Error ? reason.stack || reason.message : String(reason),
-    });
-  });
-  process.on('uncaughtException', (err) => {
-    logger.error('uncaughtException', { err: err.stack || err.message });
-    // Begin orderly shutdown; process state may be corrupt.
-    try { onFatal(); } catch {}
-  });
-}
-
-function gracefulShutdown(server, sseClients, logger) {
-  let shuttingDown = false;
-  return (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    logger.info(`received ${signal}, shutting down`);
-    for (const res of sseClients) {
-      try { res.end(); } catch {}
-    }
-    sseClients.clear();
-    server.close((err) => {
-      if (err) {
-        logger.error('server close error', { err: String(err) });
-        process.exit(1);
-      }
-      logger.info('bye');
-      process.exit(0);
-    });
-    // Hard-fail after 10s if we can't drain.
-    setTimeout(() => {
-      logger.warn('shutdown timed out, forcing exit');
-      process.exit(1);
-    }, 10_000).unref();
-  };
-}
-
 /* ------------ helpers ------------ */
 
 /** @param {import('node:http').IncomingMessage} req @param {URL} url */
@@ -2068,21 +2036,18 @@ async function sendWebResponse(res, webRes, req, opts) {
     headers[k] = v;
   });
 
-  // Negotiate compression.
+  // Negotiate compression via the SHARED seam (listener-core.js), so the node and
+  // Bun shells negotiate + compress identically (brotli > gzip > deflate, node:zlib
+  // both sides). Skip a body that is already content-encoded (a route.ts returning
+  // pre-compressed bytes), and merge into any pre-existing `Vary` rather than
+  // clobbering it (`isCompressible` already excludes `text/event-stream`).
   let compressor = null;
-  if (opts?.compress && req && webRes.body && isCompressible(headers['content-type'])) {
-    const accept = String(req.headers['accept-encoding'] || '');
-    if (/(?:^|,\s*)br(?:;|,|$)/.test(accept)) {
-      compressor = createBrotliCompress({
-        params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 },
-      });
-      headers['content-encoding'] = 'br';
-    } else if (/(?:^|,\s*)gzip(?:;|,|$)/.test(accept)) {
-      compressor = createGzip({ level: 6 });
-      headers['content-encoding'] = 'gzip';
-    }
+  if (opts?.compress && req && webRes.body && !headers['content-encoding'] && isCompressible(headers['content-type'])) {
+    const encoding = negotiateEncoding(req.headers['accept-encoding']);
+    compressor = createCompressor(encoding);
     if (compressor) {
-      headers['vary'] = 'Accept-Encoding';
+      headers['content-encoding'] = encoding;
+      headers['vary'] = varyWithAcceptEncoding(typeof headers['vary'] === 'string' ? headers['vary'] : '');
       delete headers['content-length'];
     }
   }
@@ -2114,13 +2079,6 @@ async function sendWebResponse(res, webRes, req, opts) {
   res.end();
 }
 
-/** @param {string | string[] | undefined} contentType */
-function isCompressible(contentType) {
-  if (!contentType) return false;
-  const ct = Array.isArray(contentType) ? contentType[0] : contentType;
-  return /^(?:text\/|application\/(?:javascript|json|xml|wasm|manifest)|image\/svg\+xml)/i.test(ct);
-}
-
 /**
  * Read a file and return a Response with appropriate caching.
  * Dev: no-cache (always revalidate).
@@ -2201,12 +2159,16 @@ async function exists(p) {
  * rules catch these at edit time. There is no bundler fallback;
  * webjs is buildless end-to-end.
  *
+ * The backend is the runtime-appropriate stripper (#508): Node 24+'s built-in
+ * `module.stripTypeScriptTypes`, or `amaro` on Bun (byte-identical, equally
+ * position-preserving), resolved once via `./ts-strip.js`.
+ *
  * @param {string} source
  * @param {string} _abs  (unused; preserved for symmetry with prior signature)
  * @returns {Promise<string>}
  */
 async function stripTs(source, _abs) {
-  return nodeModule.stripTypeScriptTypes(source);
+  return stripTypeScript(source);
 }
 
 /**

package/src/file-storage.js

@@ -19,8 +19,10 @@
  * Design notes:
  *
  *   - **Streaming write.** `put` never buffers the whole file. It pipes
- *     `file.stream()` -> `Readable.fromWeb` -> `createWriteStream` via
- *     `node:stream/promises.pipeline`, so a large upload uses constant memory.
+ *     `file.stream()` -> a reader-loop async generator (`webStreamChunks`) ->
+ *     `createWriteStream` via `node:stream/promises.pipeline`, so a large upload
+ *     uses constant memory (the reader loop instead of `Readable.fromWeb` so a
+ *     mid-stream source error propagates through `pipeline` on Bun too, #509).
  *     The upstream body-size cap (#237, `maxMultipartBytes`) bounds the size
  *     BEFORE the bytes ever reach the store, so the store does not re-implement
  *     a limit; it only stays streaming.
@@ -44,6 +46,7 @@ import { dirname, join, resolve, sep, extname } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { randomUUID, createHmac, timingSafeEqual } from 'node:crypto';
+import { webStreamChunks } from './listener-core.js';
 
 /**
  * @typedef {Object} StoredObjectHandle
@@ -181,15 +184,19 @@ export function assertSafeKey(dir, key) {
  * @returns {{ stream: import('node:stream').Readable, contentType: string | null }}
  */
 function toNodeStream(file) {
-  // A Blob / File exposes a web ReadableStream via `.stream()`; converting it
-  // with Readable.fromWeb keeps it streaming (no `.arrayBuffer()`).
+  // A Blob / File exposes a web ReadableStream via `.stream()`; consuming it
+  // through a reader-loop async generator (NOT `Readable.fromWeb`) keeps it
+  // streaming AND propagates a mid-stream source error reliably on both Node and
+  // Bun. `Readable.fromWeb` does NOT forward a web-stream error through
+  // `stream/promises.pipeline` on Bun (the `pipeline` promise never settles, so
+  // `put` would hang instead of rejecting + cleaning up the partial file, #509).
   if (file && typeof file.stream === 'function' && typeof file.size === 'number') {
     const contentType = typeof file.type === 'string' && file.type ? file.type : null;
-    return { stream: Readable.fromWeb(file.stream()), contentType };
+    return { stream: Readable.from(webStreamChunks(file.stream())), contentType };
   }
   // A web ReadableStream directly.
   if (file && typeof file.getReader === 'function') {
-    return { stream: Readable.fromWeb(/** @type {ReadableStream} */ (file)), contentType: null };
+    return { stream: Readable.from(webStreamChunks(/** @type {ReadableStream} */ (file))), contentType: null };
   }
   // A Uint8Array / Buffer: wrap as a single-chunk readable. This DOES hold the
   // bytes the caller already has in memory, but it does not COPY-buffer them

package/src/listener-bun.js

@@ -0,0 +1,359 @@
+/**
+ * Bun.serve listener adapter (#511): the `Bun.serve` shell for `startServer`,
+ * 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.
+ *
+ * Feature parity with the node shell, routed through the shared
+ * `listener-core.js` so the two cannot drift:
+ *   - **SSE live-reload** (#264): a streaming `text/event-stream` `Response` whose
+ *     `ReadableStream` controller is registered in the shared `SseHub`; the
+ *     request `AbortSignal` (and the stream `cancel`) deregister it on disconnect.
+ *   - **WebSocket upgrade**: a `route.ts` `WS` export. Bun's native WS dispatches
+ *     through server-level `websocket` handlers (not the node `ws`-library
+ *     EventEmitter contract the `WS(ws, …)` export expects), so a small
+ *     `BunWsAdapter` re-exposes `.on('message')` / `.on('close')` / `.send()` /
+ *     `.readyState` over Bun's `ServerWebSocket`, keeping the handler contract and
+ *     the `broadcast()` registry identical across runtimes.
+ *   - **Compression**: brotli / gzip / deflate via `node:zlib` (which runs
+ *     natively on Bun), the SAME negotiation + compressor factory the node shell
+ *     uses (shared in `listener-core.js`), so the Bun path gets brotli too (#517).
+ *   - **Timeouts** (#237): the node `requestTimeout` maps to Bun's single
+ *     `idleTimeout` (seconds), clamped above the 25s SSE keepalive so a dev
+ *     live-reload stream is never reaped.
+ *   - **Proxy IP**: `server.requestIP(req).address` stamps the framework-trusted
+ *     `x-webjs-remote-ip` (the node socket-address equivalent), after stripping
+ *     any spoofed inbound value.
+ *
+ * Not supported on Bun (documented, node-only): **103 Early Hints**. `Bun.serve`
+ * exposes no API to write an informational response before the body.
+ *
+ * This module is imported DYNAMICALLY by `dev.js` only when `serverRuntime()` is
+ * `'bun'`, so the `Bun.*` global is never referenced on Node. It still LINKS on
+ * Node (the global is only read inside functions), but it is never loaded there.
+ */
+import { EventEmitter } from 'node:events';
+import { Readable, pipeline } from 'node:stream';
+import { matchApi } from './router.js';
+import { registerClient } from './broadcast.js';
+import {
+  isCompressible,
+  isEventsPath,
+  loadWsModule,
+  installProcessHandlers,
+  makeShutdown,
+  negotiateEncoding,
+  createCompressor,
+  varyWithAcceptEncoding,
+  webStreamChunks,
+} from './listener-core.js';
+
+/* global Bun */
+
+/**
+ * Start the Bun.serve listener.
+ * @param {import('./listener-types.js').ListenerContext} ctx
+ * @returns {{ server: any, close: () => Promise<void> }}
+ */
+export function startBunListener(ctx) {
+  const { app, dev, compress, logger, hub, port, basePathStr, timeouts, watcherAbort } = ctx;
+
+  const server = Bun.serve({
+    port,
+    idleTimeout: bunIdleTimeout(timeouts),
+    // webjs owns its dev error overlay (over SSE) and handles thrown errors in
+    // `fetch`, so Bun's own development error page must never interfere; keep it
+    // deterministic (off) rather than tied to NODE_ENV.
+    development: false,
+    /**
+     * @param {Request} req
+     * @param {any} srv  the Bun server (requestIP / upgrade)
+     */
+    async fetch(req, srv) {
+      try {
+        const url = new URL(req.url);
+
+        // SSE live-reload stream (dev only); does not fit the req->Response model
+        // on node, but on Bun it is a perfectly ordinary streaming Response.
+        if (isEventsPath(url.pathname, basePathStr)) {
+          if (!dev) return new Response(null, { status: 404 });
+          return bunSseResponse(req, hub, app);
+        }
+
+        // WebSocket upgrade: a route.ts exporting WS.
+        if ((req.headers.get('upgrade') || '').toLowerCase() === 'websocket') {
+          return await bunUpgrade(req, srv, ctx);
+        }
+
+        // 103 Early Hints are intentionally skipped: Bun.serve has no API to
+        // write an informational response before the body. The modulepreload
+        // 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;
+      } catch (e) {
+        logger.error('request pipeline threw', { err: e instanceof Error ? e.stack : String(e) });
+        return new Response(
+          dev && e instanceof Error ? `webjs error: ${e.stack}` : 'Internal server error',
+          { status: 500, headers: { 'content-type': 'text/plain' } },
+        );
+      }
+    },
+    websocket: {
+      /** @param {any} ws */
+      open(ws) {
+        const d = ws.data;
+        try {
+          d.wrapper._bind(ws);
+          registerClient(d.pathname, d.wrapper);
+          d.mod.WS(d.wrapper, d.req, { params: d.params });
+        } catch (e) {
+          logger.error('WebSocket handler threw', {
+            err: e instanceof Error ? e.stack || e.message : String(e),
+          });
+          try { ws.close(1011, 'Internal error'); } catch {}
+        }
+      },
+      /** @param {any} ws @param {string | Buffer} message */
+      message(ws, message) {
+        try { ws.data.wrapper.emit('message', message); } catch {}
+      },
+      /** @param {any} ws @param {number} code @param {string} reason */
+      close(ws, code, reason) {
+        const w = ws.data.wrapper;
+        w.readyState = 3;
+        try { w.emit('close', code, reason); } catch {}
+      },
+    },
+  });
+
+  logger.info(
+    `webjs ${dev ? 'dev' : 'prod'} server ready on http://localhost:${server.port} (Bun ${process.versions.bun})`,
+  );
+  // Warm the first-request analysis in the background; listening does not wait
+  // on it, matching the node shell.
+  app.warmup();
+
+  const closeServer = () => Promise.resolve(server.stop(true));
+  const shutdown = makeShutdown({ closeServer, hub, logger });
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+  installProcessHandlers(logger, () => shutdown('uncaughtException'));
+
+  return {
+    server,
+    close: () => {
+      if (watcherAbort) watcherAbort.abort();
+      hub.closeAll();
+      return Promise.resolve(server.stop(true)).then(() => undefined);
+    },
+  };
+}
+
+/**
+ * The node `ws`-library WebSocket contract (`.on('message')` / `.on('close')` /
+ * `.send()` / `.readyState` / `.close()`) re-exposed over a Bun `ServerWebSocket`,
+ * which otherwise dispatches messages through server-level handlers rather than
+ * per-socket events. Constructed at upgrade time and bound to the real socket in
+ * the `open` handler; messages/close are forwarded to its emitter from the
+ * `websocket.message` / `websocket.close` handlers.
+ *
+ * Only `'message'` and `'close'` are forwarded (the events webjs WS handlers and
+ * `broadcast()` use). Bun exposes no per-socket `'error'` / `'ping'` / `'pong'`
+ * handler to bridge; a socket failure on Bun surfaces as a `'close'`, so
+ * `'close'`-keyed cleanup still runs. Documented in the WebSockets doc.
+ */
+class BunWsAdapter extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {any} */
+    this._ws = null;
+    // WebSocket.readyState constants: 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED.
+    this.readyState = 0;
+  }
+
+  /** @param {any} ws  the Bun ServerWebSocket, available once `open` fires */
+  _bind(ws) {
+    this._ws = ws;
+    this.readyState = 1;
+  }
+
+  /** @param {string | ArrayBufferView | ArrayBuffer} data */
+  send(data) {
+    try { if (this._ws) this._ws.send(data); } catch {}
+  }
+
+  /** @param {number} [code] @param {string} [reason] */
+  close(code, reason) {
+    try { if (this._ws) this._ws.close(code, reason); } catch {}
+  }
+
+  get bufferedAmount() {
+    try { return this._ws ? this._ws.getBufferedAmount() : 0; } catch { return 0; }
+  }
+}
+
+/**
+ * Resolve a `route.ts` `WS` export and upgrade the connection. Mirrors the node
+ * `attachWebSocket` path (match the route, load the module, require a `WS`
+ * function) but drives Bun's `server.upgrade`. Returns `undefined` on a
+ * successful upgrade (Bun's contract: the fetch handler must not return a
+ * Response once the socket is taken over).
+ * @param {Request} req
+ * @param {any} srv
+ * @param {import('./listener-types.js').ListenerContext} ctx
+ */
+async function bunUpgrade(req, srv, ctx) {
+  const url = new URL(req.url);
+  // Matches the node WS path, which keys on the full pathname (no base-path
+  // stripping) and on `registerClient(url.pathname, …)`.
+  const match = matchApi(ctx.app.getRouteTable(), url.pathname);
+  if (!match) return new Response('Not Found', { status: 404 });
+
+  let mod;
+  try {
+    mod = await loadWsModule(match.route.file, ctx.dev);
+  } catch (e) {
+    ctx.logger.error('WebSocket module load failed', { err: String(e) });
+    return new Response('Upgrade failed', { status: 500 });
+  }
+  if (typeof mod.WS !== 'function') {
+    return new Response('Upgrade not supported at this route', { status: 426 });
+  }
+
+  const wrapper = new BunWsAdapter();
+  const handlerReq = upgradeRequest(req, url);
+  const ok = srv.upgrade(req, {
+    data: { wrapper, mod, req: handlerReq, params: match.params, pathname: url.pathname },
+  });
+  if (ok) return undefined;
+  return new Response('Upgrade failed', { status: 500 });
+}
+
+/**
+ * Best-effort `Request` for the WS handler: headers + GET + URL, no body (it is a
+ * handshake). Mirrors the node `buildRequestFromUpgrade` so the handler reads the
+ * same cookies/auth either side.
+ * @param {Request} req
+ * @param {URL} url
+ */
+function upgradeRequest(req, url) {
+  const headers = new Headers();
+  req.headers.forEach((v, k) => { if (!k.startsWith(':')) headers.set(k, v); });
+  return new Request(url, { method: 'GET', headers });
+}
+
+/**
+ * Build the dev live-reload SSE `Response`: a streaming `text/event-stream` whose
+ * controller is registered in the shared `SseHub`. The request `AbortSignal` and
+ * the stream `cancel` both deregister the client on disconnect.
+ * @param {Request} req
+ * @param {import('./listener-core.js').SseHub} hub
+ * @param {any} app
+ */
+function bunSseResponse(req, hub, app) {
+  const enc = new TextEncoder();
+  /** @type {{ send: (s: string) => void, close: () => void } | null} */
+  let client = null;
+  const stream = new ReadableStream({
+    start(controller) {
+      client = {
+        send: (s) => { try { controller.enqueue(enc.encode(s)); } catch {} },
+        close: () => { try { controller.close(); } catch {} },
+      };
+      controller.enqueue(enc.encode('event: hello\ndata: webjs\n\n'));
+      hub.add(client);
+      // Replay an unresolved dev error (#264) so a tab connecting AFTER the
+      // breaking edit still shows the overlay.
+      const pending = app.getLastDevError && app.getLastDevError();
+      if (pending) {
+        try { controller.enqueue(enc.encode(`event: webjs-error\ndata: ${JSON.stringify(pending)}\n\n`)); } catch {}
+      }
+    },
+    cancel() { if (client) hub.remove(client); },
+  });
+  if (req.signal) {
+    req.signal.addEventListener('abort', () => { if (client) hub.remove(client); });
+  }
+  return new Response(stream, {
+    status: 200,
+    headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' },
+  });
+}
+
+/**
+ * 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.
+ * @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 });
+}
+
+/**
+ * Compress a `Response` via `node:zlib` (brotli / gzip / deflate), the SAME
+ * 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`).
+ * @param {Response} resp
+ * @param {Request} req
+ */
+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;
+
+  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));
+  pipeline(source, compressor, () => {});
+  const body = Readable.toWeb(compressor);
+  return new Response(body, { status: resp.status, statusText: resp.statusText, headers });
+}
+
+/**
+ * Map the node `requestTimeout` (ms) to Bun's single `idleTimeout` (seconds). Bun
+ * caps it at 255s; we clamp it above the 25s SSE keepalive so a dev live-reload
+ * stream is never reaped as idle. `0` (the node "disable" sentinel) disables it
+ * on Bun too.
+ * @param {{ requestTimeout?: number } | undefined} timeouts
+ */
+function bunIdleTimeout(timeouts) {
+  const reqMs = timeouts && timeouts.requestTimeout;
+  if (reqMs === 0) return 0;
+  let secs = Math.ceil((reqMs || 30_000) / 1000);
+  if (secs < 30) secs = 30;
+  if (secs > 255) secs = 255;
+  return secs;
+}

package/src/listener-core.js

@@ -0,0 +1,245 @@
+/**
+ * Runtime-neutral listener core (#511): the pieces both the node:http shell and
+ * the `Bun.serve` shell share, so the two adapters cannot drift.
+ *
+ * `createRequestHandler` already returns a runtime-agnostic `handle(req): Response`.
+ * The remaining shell work (accept a socket, dispatch SSE live-reload, upgrade a
+ * WebSocket, apply timeouts + compression, run graceful shutdown) is split here
+ * into the genuinely-shared decision logic (this module) and the irreducibly
+ * transport-specific glue (the node `res.write` path in `dev.js`, the `Bun.serve`
+ * streaming-`Response` path in `listener-bun.js`). The SSE registry + fanout, the
+ * live-reload path predicate, the WS module loader, the runtime detector, and the
+ * lifecycle wiring all live here so a feature added to one shell is added to both.
+ *
+ * The seam also sets up future `Deno.serve` / embedded-host adapters: a new shell
+ * supplies its own client wrapper to `SseHub`, its own socket-to-`Request` bridge,
+ * 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 { stripBasePath } from './base-path.js';
+
+/** The dev live-reload SSE path (matched after base-path stripping). */
+export const EVENTS_PATH = '/__webjs/events';
+
+/**
+ * Detect the host runtime so `startServer` can pick an adapter. Bun sets
+ * `process.versions.bun` (and also reports a `node` version via its compat
+ * layer, so the Bun check must come first).
+ * @returns {'bun' | 'node'}
+ */
+export function serverRuntime() {
+  return (typeof process !== 'undefined' && process.versions && process.versions.bun)
+    ? 'bun'
+    : 'node';
+}
+
+/**
+ * Is this request the dev live-reload SSE stream? Base-path-aware so the stream
+ * answers at `<basePath>/__webjs/events` under a sub-path deploy (#256); a no-op
+ * pass-through when there is no base path.
+ * @param {string} pathname
+ * @param {string} basePathStr
+ */
+export function isEventsPath(pathname, basePathStr) {
+  return stripBasePath(pathname, basePathStr) === EVENTS_PATH;
+}
+
+/**
+ * Whether a response body of this content type is worth compressing. Shared by
+ * the node `sendWebResponse` and the Bun `maybeCompress` so both shells gzip the
+ * exact same set of media types.
+ * @param {string | string[] | null | undefined} contentType
+ */
+export function isCompressible(contentType) {
+  if (!contentType) return false;
+  const ct = Array.isArray(contentType) ? contentType[0] : contentType;
+  // Never compress an event stream: a compressor buffers/chunk-delays bytes that
+  // an SSE body (a user route.ts returning text/event-stream) is meant to flush
+  // incrementally, so it would stall the stream. The framework's own
+  // /__webjs/events stream is intercepted before compression; this guards a
+  // user-authored one on both shells.
+  if (/^text\/event-stream/i.test(ct)) return false;
+  return /^(?:text\/|application\/(?:javascript|json|xml|wasm|manifest)|image\/svg\+xml)/i.test(ct);
+}
+
+/**
+ * Negotiate a response content-encoding from a request's `Accept-Encoding`,
+ * preferring brotli (best ratio), then gzip, then deflate. Returns `''` when
+ * none is acceptable. Shared by BOTH listener shells so they negotiate
+ * identically; the matching uses the same `(?:^|,\s*)<enc>(?:;|,|$)` token test
+ * the node shell has always used.
+ * @param {string | string[] | undefined | null} acceptEncoding
+ * @returns {'br' | 'gzip' | 'deflate' | ''}
+ */
+export function negotiateEncoding(acceptEncoding) {
+  const accept = Array.isArray(acceptEncoding) ? acceptEncoding.join(',') : String(acceptEncoding || '');
+  if (/(?:^|,\s*)br(?:;|,|$)/.test(accept)) return 'br';
+  if (/(?:^|,\s*)gzip(?:;|,|$)/.test(accept)) return 'gzip';
+  if (/(?:^|,\s*)deflate(?:;|,|$)/.test(accept)) return 'deflate';
+  return '';
+}
+
+/**
+ * Create a `node:zlib` compressor Transform for a negotiated encoding, or null.
+ * `node:zlib` runs NATIVELY on Bun, so both shells get brotli through it (the web
+ * `CompressionStream` the Bun shell used before had gzip/deflate only, no brotli).
+ * Brotli quality 4 / gzip + deflate level 6 match the node shell's prior tuning
+ * (fast, good ratio for on-the-fly compression).
+ * @param {'br' | 'gzip' | 'deflate' | ''} encoding
+ * @returns {import('node:stream').Transform | null}
+ */
+export function createCompressor(encoding) {
+  if (encoding === 'br') return createBrotliCompress({ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 } });
+  if (encoding === 'gzip') return createGzip({ level: 6 });
+  if (encoding === 'deflate') return createDeflate({ 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
+ * `Origin`, etc.) does not clobber that. Shared so both shells behave identically.
+ * @param {string | null | undefined} existingVary
+ * @returns {string}
+ */
+export function varyWithAcceptEncoding(existingVary) {
+  const vary = existingVary || '';
+  return vary && !/accept-encoding/i.test(vary) ? `${vary}, Accept-Encoding` : (vary || 'Accept-Encoding');
+}
+
+/**
+ * Read a web `ReadableStream` chunk by chunk as an async iterable. A read error
+ * (a source body that errors mid-stream) throws OUT of the generator, which
+ * `Readable.from` surfaces as a node stream `error` that `pipeline` then
+ * propagates by destroying the whole chain. This is the cross-runtime-reliable
+ * way to feed a web body into a node stream: `Readable.fromWeb` does NOT
+ * propagate a web-stream error through `pipeline` on Bun (the #509 hang), so the
+ * Bun compression path must NOT use it. On early termination (the consumer
+ * aborted, e.g. a client disconnect destroyed the compressor) the source is
+ * cancelled so an upstream producer stops.
+ * @param {ReadableStream} web
+ */
+export async function* webStreamChunks(web) {
+  const reader = web.getReader();
+  let finished = false;
+  try {
+    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 {}
+  }
+}
+
+/**
+ * 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
+ * (`websocket.js`) and the Bun upgrade path so both resolve the handler identically.
+ * @param {string} file
+ * @param {boolean} dev
+ */
+export function loadWsModule(file, dev) {
+  const url = pathToFileURL(file).toString();
+  const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
+  return import(url + bust);
+}
+
+/**
+ * Runtime-neutral SSE registry + fanout for dev live-reload and the dev error
+ * overlay (#264). Owns the connected-client Set and the keepalive timer; the
+ * fanout writes plain SSE frames through each client's `send`. Each shell adds a
+ * thin client wrapper over its own transport (node `res.write`, a Bun
+ * `ReadableStreamDefaultController`), so this fanout logic is written once.
+ */
+export class SseHub {
+  /** @param {{ keepaliveMs?: number }} [opts] */
+  constructor(opts = {}) {
+    /** @type {Set<{ send: (s: string) => void, close: () => void }>} */
+    this.clients = new Set();
+    // Keepalive: a comment frame every 25s defeats proxy idle timeouts (and, on
+    // Bun, keeps the connection under the server idleTimeout). Cheap and safe:
+    // SSE comments are ignored by the client. Unref'd so it never holds the
+    // process open.
+    this._timer = setInterval(() => this._raw(': ka\n\n'), opts.keepaliveMs ?? 25_000);
+    if (typeof this._timer.unref === 'function') this._timer.unref();
+  }
+
+  /** @param {{ send: (s: string) => void, close: () => void }} client */
+  add(client) { this.clients.add(client); }
+  /** @param {{ send: (s: string) => void, close: () => void }} client */
+  remove(client) { this.clients.delete(client); }
+
+  /** @param {string} frame */
+  _raw(frame) {
+    for (const c of this.clients) {
+      try { c.send(frame); } catch { /* a dead client is dropped by its own close handler */ }
+    }
+  }
+
+  /** Push a live-reload event to every open tab. */
+  reload() { this._raw('event: reload\ndata: now\n\n'); }
+
+  /** Push a dev-error overlay frame (#264) to every open tab. @param {object} frame */
+  devError(frame) { this._raw(`event: webjs-error\ndata: ${JSON.stringify(frame)}\n\n`); }
+
+  /** Close every client and stop the keepalive (graceful shutdown). */
+  closeAll() {
+    for (const c of this.clients) { try { c.close(); } catch {} }
+    this.clients.clear();
+    clearInterval(this._timer);
+  }
+}
+
+/**
+ * Install once-only process error handlers. Idempotent across multiple
+ * `startServer` calls in the same process. Runtime-neutral (plain `process.on`).
+ * @param {import('./logger.js').Logger} logger
+ * @param {() => void} onFatal
+ */
+export function installProcessHandlers(logger, onFatal) {
+  if (/** @type any */ (globalThis).__webjsProcHandlers) return;
+  /** @type any */ (globalThis).__webjsProcHandlers = true;
+  process.on('unhandledRejection', (reason) => {
+    logger.error('unhandledRejection', {
+      err: reason instanceof Error ? reason.stack || reason.message : String(reason),
+    });
+  });
+  process.on('uncaughtException', (err) => {
+    logger.error('uncaughtException', { err: err.stack || err.message });
+    // Begin orderly shutdown; process state may be corrupt.
+    try { onFatal(); } catch {}
+  });
+}
+
+/**
+ * Build a graceful-shutdown signal handler. Runtime-neutral: the shell supplies a
+ * `closeServer()` thunk that resolves once the server has stopped accepting
+ * connections (node `server.close`, Bun `server.stop(true)`). Closes the SSE hub,
+ * then drains, then exits; hard-exits after 10s if the drain hangs.
+ * @param {{ closeServer: () => Promise<unknown>, hub: SseHub, logger: import('./logger.js').Logger }} opts
+ * @returns {(signal: string) => void}
+ */
+export function makeShutdown({ closeServer, hub, logger }) {
+  let shuttingDown = false;
+  return (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info(`received ${signal}, shutting down`);
+    try { hub.closeAll(); } catch {}
+    const hard = setTimeout(() => {
+      logger.warn('shutdown timed out, forcing exit');
+      process.exit(1);
+    }, 10_000);
+    if (typeof hard.unref === 'function') hard.unref();
+    Promise.resolve()
+      .then(closeServer)
+      .then(
+        () => { logger.info('bye'); process.exit(0); },
+        (err) => { logger.error('server close error', { err: String(err) }); process.exit(1); },
+      );
+  };
+}

package/src/listener-types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared shape passed from `startServer` to whichever listener shell it selects
+ * (the node:http path in `dev.js`, the `Bun.serve` path in `listener-bun.js`).
+ * Types only; no runtime exports.
+ *
+ * @typedef {object} ListenerContext
+ * @property {any} app  the `createRequestHandler` result (`handle`, `routeFor`,
+ *   `getRouteTable`, `getLastDevError`, `warmup`, `appDir`).
+ * @property {boolean} dev
+ * @property {boolean} compress
+ * @property {import('./logger.js').Logger} logger
+ * @property {import('./listener-core.js').SseHub} hub
+ * @property {number} port
+ * @property {string} basePathStr  the configured base path (`''` when unset).
+ * @property {{ requestTimeout: number, headersTimeout: number, keepAliveTimeout: number }} timeouts
+ * @property {AbortController | null} watcherAbort  the dev fs.watch controller, aborted on close.
+ */
+
+export {};

package/src/node-version.js

@@ -89,6 +89,15 @@ export function requiredNodeMajor() {
  * @returns {void}
  */
 export function assertNodeVersion(opts = {}) {
+  // Bun (#508) satisfies webjs's requirements through a different mechanism: the
+  // TS strip comes from `amaro` (resolved by ts-strip.js), and `fs.watch` /
+  // `node:crypto` are provided by its node-compat layer, even though Bun reports
+  // a Node version string. The Node-major gate is a proxy for "the Node built-ins
+  // exist", which does not hold on Bun, so skip it there. Only when no explicit
+  // `current` is passed (real runtime detection, not a unit test override).
+  if (opts.current === undefined && typeof process !== 'undefined' && process.versions && process.versions.bun) {
+    return;
+  }
   const current = opts.current ?? process.versions.node;
   const requiredMajor = opts.requiredMajor ?? requiredNodeMajor();
   const onFail = opts.onFail ?? 'throw';

package/src/ts-strip.js

@@ -0,0 +1,157 @@
+/**
+ * Pluggable TypeScript stripper (#508), the one seam that lets webjs run on both
+ * Node and Bun.
+ *
+ * webjs serves `.ts` / `.mts` source to the browser as JavaScript by ERASING the
+ * type syntax in place (position-preserving whitespace replacement, so no
+ * sourcemap is shipped and stack traces stay byte-exact). On Node 24+ that is the
+ * built-in `module.stripTypeScriptTypes`. Bun has no such built-in, so this
+ * module picks the backend at boot:
+ *
+ *   - **Node 24+**: the built-in `module.stripTypeScriptTypes` (zero deps, the
+ *     default; nothing about the Node path changes).
+ *   - **Bun (or any runtime lacking the built-in)**: `amaro`, lazily imported.
+ *     Node's built-in is itself a thin wrapper over `amaro`'s `strip-only` mode,
+ *     so the output is BYTE-IDENTICAL and equally position-preserving. `amaro` is
+ *     an `optionalDependency` of `@webjsdev/server`: a Node-only install that
+ *     prunes optionals still runs (it never loads amaro), while a Bun install
+ *     gets it.
+ *
+ * `WEBJS_TS_STRIPPER=builtin|amaro` forces a backend (used by the tests to
+ * exercise the amaro path under Node, and an escape hatch).
+ *
+ * Erasable TypeScript only, either way: non-erasable syntax (`enum`, value
+ * `namespace`, parameter properties, legacy decorators, `import = require`)
+ * throws at strip time, which the `erasable-typescript-only` /
+ * `no-non-erasable-typescript` lint rules catch at edit time.
+ */
+// Namespace import, NOT `import { stripTypeScriptTypes }`. On Node < 22.13 the
+// named export does not exist, and a NAMED import of a missing builtin export is
+// a LINK-TIME SyntaxError that fires before any module body runs, which would
+// defeat the Node-version preflight by crashing the import of @webjsdev/server
+// itself. A namespace import links on every runtime (the property is just
+// `undefined` where absent, e.g. Bun) and we branch on it at runtime instead.
+import * as nodeModule from 'node:module';
+
+// Suppress the one-shot ExperimentalWarning Node prints the first time
+// `stripTypeScriptTypes` is called (the API is committed per Node 24's release
+// notes; the warning is a holdover). Installed here, co-located with the strip
+// call, so it covers every consumer of this module (dev.js, the CLI, tests),
+// not just the dev server. Every other warning passes through untouched.
+const _origEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function (warning, type, code, ctor) {
+  const msg = warning && warning.message ? warning.message : String(warning);
+  if (
+    (type === 'ExperimentalWarning' || (warning && warning.name === 'ExperimentalWarning')) &&
+    msg.includes('stripTypeScriptTypes')
+  ) {
+    return;
+  }
+  return _origEmitWarning(warning, type, code, ctor);
+};
+
+/** @typedef {{ fn: (source: string) => string, name: 'builtin' | 'amaro' }} Stripper */
+
+/** @type {Stripper | null} */
+let _strip = null;
+/** @type {Promise<Stripper> | null} */
+let _resolving = null;
+
+/** Forced backend from the env, or '' for auto-detect. */
+function forcedBackend() {
+  const v = String(process.env.WEBJS_TS_STRIPPER || '').toLowerCase().trim();
+  return v === 'builtin' || v === 'amaro' ? v : '';
+}
+
+/**
+ * Resolve the active stripper backend once. Auto-detects (built-in when present,
+ * else amaro); honors a `WEBJS_TS_STRIPPER` override.
+ * @returns {Promise<Stripper>}
+ */
+async function resolve() {
+  const forced = forcedBackend();
+  const hasBuiltin = typeof nodeModule.stripTypeScriptTypes === 'function';
+  if (forced !== 'amaro' && (forced === 'builtin' || hasBuiltin)) {
+    if (forced === 'builtin' && !hasBuiltin) {
+      throw new Error('WEBJS_TS_STRIPPER=builtin but module.stripTypeScriptTypes is unavailable on this runtime.');
+    }
+    return { fn: (source) => nodeModule.stripTypeScriptTypes(source), name: 'builtin' };
+  }
+  // amaro backend (Bun, a Node without the built-in, or forced).
+  let amaro;
+  try {
+    amaro = await import('amaro');
+  } catch (e) {
+    const why = e && e.message ? e.message : String(e);
+    throw new Error(
+      "webjs needs a TypeScript stripper: this runtime has no built-in " +
+      "`module.stripTypeScriptTypes` (e.g. Bun) and the `amaro` fallback failed " +
+      "to load. Install `amaro` (it is an optionalDependency of @webjsdev/server) " +
+      "to run webjs here. Underlying: " + why,
+    );
+  }
+  const tx = amaro.transformSync || (amaro.default && amaro.default.transformSync);
+  if (typeof tx !== 'function') {
+    throw new Error('webjs: the resolved `amaro` module has no `transformSync` export.');
+  }
+  return {
+    fn: (source) => {
+      try {
+        return tx(source, { mode: 'strip-only' }).code;
+      } catch (e) {
+        // Normalize amaro's non-erasable-syntax error code to Node's, so a
+        // single downstream check (`err.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'`
+        // in dev.js's tsResponse) classifies the failure identically on both
+        // runtimes (amaro reports `code: 'UnsupportedSyntax'` for an enum /
+        // namespace-with-values / parameter-property / legacy-decorator). The
+        // strip-error contract is part of this seam, like the strip itself.
+        if (e && e.code === 'UnsupportedSyntax') {
+          try { e.code = 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'; } catch {}
+        }
+        throw e;
+      }
+    },
+    name: 'amaro',
+  };
+}
+
+/**
+ * Resolve (once, memoized) and return the active stripper. Call at boot so the
+ * backend is ready and a missing-amaro error surfaces early rather than on the
+ * first `.ts` request.
+ * @returns {Promise<Stripper>}
+ */
+export async function ensureStripper() {
+  if (_strip) return _strip;
+  // Clear `_resolving` on BOTH settle paths so a failed resolve (e.g. a missing
+  // amaro on a runtime lacking the built-in) re-detects on the next call instead
+  // of caching the rejection forever (self-healing, matching `__resetStripper`).
+  if (!_resolving) {
+    _resolving = resolve().then(
+      (s) => { _strip = s; _resolving = null; return s; },
+      (e) => { _resolving = null; throw e; },
+    );
+  }
+  return _resolving;
+}
+
+/**
+ * Strip TypeScript types from `source`, resolving the backend on first use.
+ * @param {string} source
+ * @returns {Promise<string>}
+ */
+export async function stripTypeScript(source) {
+  const s = _strip || await ensureStripper();
+  return s.fn(source);
+}
+
+/** The active backend name, or null before resolution (diagnostics / tests). */
+export function stripperName() {
+  return _strip ? _strip.name : null;
+}
+
+/** Test seam: forget the resolved backend so the next call re-detects. */
+export function __resetStripper() {
+  _strip = null;
+  _resolving = null;
+}

package/src/websocket.js

@@ -1,8 +1,8 @@
 import { WebSocketServer } from 'ws';
-import { pathToFileURL } from 'node:url';
 import { matchApi } from './router.js';
 import { urlFromRequest } from './forwarded.js';
 import { registerClient } from './broadcast.js';
+import { loadWsModule } from './listener-core.js';
 
 /**
  * WebSocket support.
@@ -48,7 +48,7 @@ export function attachWebSocket(server, getRouteTable, opts) {
         return reject(socket, 404, 'Not Found');
       }
 
-      const mod = await loadModule(match.route.file, opts.dev);
+      const mod = await loadWsModule(match.route.file, opts.dev);
       if (typeof mod.WS !== 'function') {
         return reject(socket, 426, 'Upgrade not supported at this route');
       }
@@ -109,13 +109,3 @@ function buildRequestFromUpgrade(req, url) {
   }
   return new Request(url, { method: 'GET', headers });
 }
-
-/**
- * @param {string} file
- * @param {boolean} dev
- */
-async function loadModule(file, dev) {
-  const url = pathToFileURL(file).toString();
-  const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
-  return import(url + bust);
-}