@webjsdev/server 0.8.45 → 0.8.47

package/package.json

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

package/src/action-route.js

@@ -1,7 +1,7 @@
 /**
  * The optional `route(action, opts?)` convenience adapter (#488).
  *
- * REST endpoints in webjs go through `route.ts` (the framework's first-class
+ * REST endpoints in WebJs go through `route.ts` (the framework's first-class
  * HTTP handler). The ALWAYS-WORKS baseline is a hand-written `route.ts` that
  * imports a `'use server'` action and calls it:
  *
@@ -28,6 +28,22 @@
  * export const POST = route(createPost, { validate: createPostSchema });
  * ```
  *
+ * Passing the action's MODULE NAMESPACE instead of the function auto-applies the
+ * action's declared `export const middleware` and `export const validate`, so a
+ * guard declared once next to the action protects the REST boundary the same way
+ * it protects the RPC boundary (#876). This is the way to keep "declare once,
+ * protected on every entry point" true without re-listing the config:
+ *
+ * ```js
+ * // app/api/posts/route.ts
+ * import { route } from '@webjsdev/server';
+ * import * as postActions from '../../../modules/posts/actions/create-post.server.ts';
+ * export const POST = route(postActions);   // its declared middleware + validate apply
+ * ```
+ *
+ * The function form still takes explicit `opts`, and an explicit `opts.middleware`
+ * / `opts.validate` overrides the module's declared config when both are given.
+ *
  * Adapter rules when invoked over HTTP:
  *   - URL query params, route params (`ctx.params`), and the parsed JSON body
  *     (for a method with a body) are merged into a single object argument
@@ -51,6 +67,7 @@
 import { runValidate } from './actions.js';
 import { runWithActionSignal } from './action-signal.js';
 import { runActionChain } from './action-middleware.js';
+import { actionFunctionNames, actionMiddleware } from './action-config.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
 
@@ -69,16 +86,48 @@ function jsonBodyLimit() {
  * Expose a plain `'use server'` action over REST as a `route.ts`-style handler.
  *
  * @template A, R
- * @param {(input: A, ctx: { req: Request, params: Record<string,string> }) => R | Promise<R>} action
- *   the server action to call (its source is unchanged; this only wraps the
- *   HTTP-to-action adapter around it).
+ * @param {((input: A, ctx: { req: Request, params: Record<string,string> }) => R | Promise<R>) | Record<string, unknown>} actionOrModule
+ *   the server action to call, OR the action's module namespace (`import * as m`)
+ *   so its declared `middleware` / `validate` config is auto-applied (#876). Its
+ *   source is unchanged; this only wraps the HTTP-to-action adapter around it.
  * @param {{
  *   validate?: (input: any) => any,
  *   middleware?: Function[],
  * }} [opts]
  * @returns {(req: Request, ctx?: { params?: Record<string,string> }) => Promise<Response>}
  */
-export function route(action, opts = {}) {
+export function route(actionOrModule, opts = {}) {
+  // Resolve the callable action plus any config the caller did not pass
+  // explicitly. A function is used verbatim (the original form). A module
+  // namespace exposes the single action function and its declared config, so
+  // `route(mod)` inherits the same `middleware` / `validate` the RPC boundary
+  // reads (#876). An explicit `opts` value still wins over the declared one.
+  let action;
+  /** @type {{ middleware?: Function[], validate?: Function }} */
+  let declared = {};
+  if (typeof actionOrModule === 'function') {
+    action = actionOrModule;
+  } else if (actionOrModule && typeof actionOrModule === 'object') {
+    const names = actionFunctionNames(actionOrModule);
+    if (names.length !== 1) {
+      throw new Error(
+        `route(module) expects exactly one action function in the module, found ${names.length}` +
+          (names.length ? ` (${names.join(', ')})` : ''),
+      );
+    }
+    action = /** @type {Function} */ (actionOrModule[names[0]]);
+    declared = {
+      middleware: actionMiddleware(actionOrModule),
+      validate: typeof actionOrModule.validate === 'function'
+        ? /** @type {Function} */ (actionOrModule.validate)
+        : undefined,
+    };
+  } else {
+    throw new Error('route() expects an action function or a module namespace');
+  }
+  const validate = opts.validate ?? declared.validate;
+  const middlewareChain = opts.middleware ?? declared.middleware ?? [];
+
   return async function handler(req, ctx) {
     const params = (ctx && ctx.params) || {};
     const url = new URL(req.url);
@@ -102,13 +151,13 @@ export function route(action, opts = {}) {
     }
 
     let arg = { ...query, ...params, ...body };
-    if (typeof opts.validate === 'function') {
+    if (typeof validate === 'function') {
       // Run the validator through the SHARED contract (#245) so the REST adapter
       // and the RPC path interpret a `{ success, fieldErrors }` envelope, a
       // throw, and a transform-return identically. A structured failure becomes
       // a 422 JSON; a throw stays a 400 (keeping a schema lib's `issues`); a
       // transform-return replaces the input.
-      const v = runValidate(opts.validate, arg);
+      const v = runValidate(validate, arg);
       if (!v.ok) {
         if (v.thrown !== undefined) {
           const msg = v.result.error || 'Invalid input';
@@ -126,10 +175,9 @@ export function route(action, opts = {}) {
     // The action runs inside the request signal scope (#492) and the per-action
     // middleware chain (#490). `ranAction` distinguishes a real completion from
     // a middleware short-circuit (the action never ran).
-    const middleware = opts.middleware || [];
     let ranAction = false;
     const result = await runWithActionSignal(req.signal, () =>
-      runActionChain(middleware, { request: req, args: [arg], signal: req.signal }, () => {
+      runActionChain(middlewareChain, { request: req, args: [arg], signal: req.signal }, () => {
         ranAction = true;
         return action(/** @type any */ (arg), { req, params });
       }));

package/src/actions.js

@@ -33,12 +33,12 @@ function jsonBodyLimit() {
 }
 
 /**
- * Internal RPC wire-format content type. Distinguishes webjs action
+ * Internal RPC wire-format content type. Distinguishes WebJs action
  * responses from plain `application/json` so the stub can pick the right
  * parser and external JSON consumers aren't confused.
  *
  * Uses the content type from the active serializer (defaults to
- * `application/vnd.webjs+json` with the built-in webjs serializer).
+ * `application/vnd.webjs+json` with the built-in WebJs serializer).
  */
 export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
 

package/src/auth.js

@@ -1,5 +1,5 @@
 /**
- * NextAuth/Auth.js-style authentication for webjs.
+ * NextAuth/Auth.js-style authentication for WebJs.
  *
  * JWT or database sessions, Credentials + OAuth (Google, GitHub) providers.
  * Uses Web Crypto HMAC-SHA256: no external dependencies.

package/src/body-limit.js

@@ -252,7 +252,7 @@ export async function readBytesBounded(req, limit) {
 /**
  * Read a request body as text, bounded by `limit`. Used by the RPC endpoint,
  * `readBody`, and the exposed-action REST path, all of which then parse the
- * text (webjs wire or JSON).
+ * text (WebJs wire or JSON).
  *
  * @param {Request} req
  * @param {number} limit max bytes (0 / negative = unlimited)

package/src/check.js

@@ -14,7 +14,7 @@ import { analyzeElision } from './component-elision.js';
 import { RESERVED_CONFIG } from './action-config.js';
 
 /**
- * Convention validator for webjs apps.
+ * Convention validator for WebJs apps.
  *
  * Scans an app directory and reports correctness violations: things that
  * crash the app, leak a secret, or fail the build / type-strip. Designed to be
@@ -380,7 +380,7 @@ function findBrowserMemberUses(code) {
 }
 
 /**
- * Scan a webjs app directory and report convention violations.
+ * Scan a WebJs app directory and report convention violations.
  *
  * Every rule is a correctness check (a crash, a security leak, or a
  * build/type-strip failure), so they all run unconditionally. There is no
@@ -436,7 +436,7 @@ export async function checkConventions(appDir) {
       // redactor leaves them alone.
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
       // Accept either registration pattern:
-      //   Counter.register('tag')                    (webjs idiom)
+      //   Counter.register('tag')                    (WebJs idiom)
       //   customElements.define('tag', Counter)      (native)
       if (/\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*['"`]/.test(scan)) continue;
       if (/\bcustomElements\.define\s*\(/.test(scan)) continue;
@@ -1208,7 +1208,7 @@ function findImportChain(graph, from, to) {
  * @param {Violation[]} violations  appended to in place
  */
 async function checkServerImportInBrowserModule(appDir, violations) {
-  // No `app/` directory means this is not a routable webjs app (e.g. a bare
+  // No `app/` directory means this is not a routable WebJs app (e.g. a bare
   // component library, or a fixture with only `lib/`); nothing ships, so the
   // rule has nothing to police. Skip rather than do the heavy analysis.
   if (!(await pathExists(join(appDir, 'app')))) return;

package/src/component-elision.js

@@ -1,5 +1,5 @@
 /**
- * Static analyser deciding whether a webjs component module can be
+ * Static analyser deciding whether a WebJs component module can be
  * ELIDED from the browser, that is, never downloaded as JS because its
  * SSR'd HTML is the complete, final output and the component does no
  * client-side work.
@@ -34,7 +34,7 @@
  *      packages/core/AGENTS.md and the MAINTAINER NOTE on the
  *      WebComponent lifecycle in packages/core/src/component.js both
  *      direct anyone adding an interactivity surface to update these
- *      lists, since webjs development is largely AI-agent driven.
+ *      lists, since WebJs development is largely AI-agent driven.
  */
 
 import {
@@ -101,7 +101,7 @@ export const CLIENT_LIFECYCLE_HOOKS = [
   'connectedCallback',
   'disconnectedCallback',
   'attributeChangedCallback',
-  // Standard custom-element callback webjs does not itself define (so it
+  // Standard custom-element callback WebJs does not itself define (so it
   // is absent from the prototype guard's CLASSIFICATION), but an author
   // can still override it to do client work. Kept for conservatism.
   'adoptedCallback',

package/src/component-scanner.js

@@ -1,13 +1,13 @@
 /**
  * Server-side scanner that walks the app tree and records the
- * browser-visible URL for every webjs component module.
+ * browser-visible URL for every WebJs component module.
  *
  * Called once on the first request (lazily, via `ensureReady`), then memoized. Results are used to prime the core
  * registry (`primeModuleUrl`) BEFORE any SSR render: so when a page
  * renders a component tag, `lookupModuleUrl(tag)` already has the URL
  * ready for `<link rel="modulepreload">` hints.
  *
- * The convention webjs uses is the web-standard one:
+ * The convention WebJs uses is the web-standard one:
  *
  *     class Counter extends WebComponent { … }
  *     customElements.define('my-counter', Counter);

package/src/cors.js

@@ -1,7 +1,7 @@
 /**
- * Reusable CORS primitive for webjs.
+ * Reusable CORS primitive for WebJs.
  *
- * `cors(options)` returns a webjs MIDDLEWARE `(req, next) => Response`,
+ * `cors(options)` returns a WebJs MIDDLEWARE `(req, next) => Response`,
  * usable in `middleware.js` (root or per-segment) or wrapped around a
  * `route.js` handler. This is the public app-facing API. The shared
  * origin-resolution + header-building core (`resolveOrigin` /

package/src/csp.js

@@ -181,7 +181,7 @@ export function readCspConfig(pkg) {
 export function mintNonce() {
   const bytes = new Uint8Array(16);
   crypto.getRandomValues(bytes);
-  // Buffer is available in every webjs server runtime (Node 24+). Avoids a
+  // Buffer is available in every WebJs server runtime (Node 24+). Avoids a
   // hand-rolled base64 of a binary string.
   return Buffer.from(bytes).toString('base64');
 }

package/src/csrf.js

@@ -4,7 +4,7 @@
  * `cop-middleware` and Go 1.25's `http.CrossOriginProtection` use, and the
  * spiritual sibling of Next.js / Astro's Origin-vs-Host check.
  *
- * Why not a token cookie: webjs previously issued a per-request `webjs_csrf`
+ * Why not a token cookie: WebJs previously issued a per-request `webjs_csrf`
  * double-submit cookie on every SSR response. That made SSR HTML
  * un-cacheable at a CDN (a CDN skips a response with `Set-Cookie`, and a
  * cached one would share / poison the token across visitors). A header check

package/src/dev-error.js

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
 /**
  * Pull the first useful `file:line:column` out of an error stack. Prefers a
  * frame under `appDir` (the user's own code) over a framework / node_modules
- * frame, so the overlay points at the edit that broke, not webjs internals.
+ * frame, so the overlay points at the edit that broke, not WebJs internals.
  *
  * Handles the V8 stack forms `at fn (/abs/file.ts:12:5)`, `at /abs/file.ts:12:5`,
  * and `at file:///abs/file.ts:12:5`.

package/src/dev-reload-worker.js

@@ -0,0 +1,53 @@
+/**
+ * The dev live-reload SharedWorker relay (#887), the BROWSER half. Kept as a
+ * standalone browser-safe module (no node imports) so the served worker inlines
+ * the EXACT source a browser test drives, with no drift, the same pattern as
+ * `dev-overlay.js` (#264). `reloadWorkerJs` in dev.js reads this file, strips
+ * the `export` keyword, and appends a
+ * `startReloadWorker(self, EventSource, '<eventsUrl>')` call.
+ *
+ * One SharedWorker is shared across every tab of the origin (a SharedWorker is
+ * keyed by its script URL), so it holds the ONE `EventSource` to
+ * `/__webjs/events` and fans each `reload` / `webjs-error` out to every tab over
+ * its `MessagePort`. Tab count never touches the browser's per-host HTTP/1.1
+ * connection cap, which the per-tab `EventSource` it replaces used to exhaust.
+ *
+ * @param {{ onconnect: any }} scope  the worker global (`self`)
+ * @param {new (url: string) => any} EventSourceCtor  the `EventSource` constructor
+ * @param {string} eventsUrl  the base-path-aware `/__webjs/events` URL
+ */
+export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
+  /** @type {Set<any>} */
+  const ports = new Set();
+  /** @type {string | null} the last error frame, cached for late-joining tabs */
+  let lastError = null;
+
+  // A MessagePort has no reliable close event, so prune a port when a post to it
+  // throws (a closed tab). Some browsers silently no-op instead of throwing,
+  // leaving a dead port in the set, but that is a harmless dev-only no-op and
+  // the set is bounded by the tabs opened in one session.
+  function fanout(msg) {
+    for (const p of ports) {
+      try { p.postMessage(msg); } catch (_) { ports.delete(p); }
+    }
+  }
+
+  const es = new EventSourceCtor(eventsUrl);
+  es.addEventListener('reload', () => { lastError = null; fanout({ type: 'reload' }); });
+  es.addEventListener('webjs-error', (e) => { lastError = e.data; fanout({ type: 'webjs-error', data: e.data }); });
+
+  scope.onconnect = (e) => {
+    const port = e.ports[0];
+    ports.add(port);
+    port.start();
+    // A tab that connects AFTER a breaking edit still needs the current overlay.
+    // The single shared EventSource already consumed the server's replay (#264),
+    // so the worker caches the last error and hands it to each new tab itself.
+    if (lastError != null) {
+      try { port.postMessage({ type: 'webjs-error', data: lastError }); } catch (_) { ports.delete(port); }
+    }
+  };
+
+  // Returned for tests; the served worker ignores it.
+  return { ports, es };
+}

package/src/dev.js

@@ -136,7 +136,7 @@ const MIME = {
  * `namespace` with values, parameter properties, legacy decorators
  * with `emitDecoratorMetadata`, `import = require`) throws at strip
  * time. The `erasable-typescript-only` and `no-non-erasable-typescript`
- * lint rules catch these at edit time. webjs is buildless end-to-end:
+ * lint rules catch these at edit time. WebJs is buildless end-to-end:
  * there is no bundler fallback.
  *
  * The transformed bytes are cached per request handler in `state.tsCache`
@@ -441,7 +441,7 @@ export async function readServerTimeoutsFromApp(appDir) {
 }
 
 /**
- * Create a reusable, framework-agnostic request handler for a webjs app.
+ * Create a reusable, framework-agnostic request handler for a WebJs app.
  * The returned `handle(req)` takes a standard `Request` and resolves to a
  * standard `Response`: suitable for Node http, Deno, Bun, Cloudflare Workers,
  * or embedding inside an Express/Fastify app.
@@ -456,7 +456,7 @@ export async function readServerTimeoutsFromApp(appDir) {
  * }} opts
  */
 export async function createRequestHandler(opts) {
-  // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
+  // Preflight: WebJs needs Node 24+ (built-in TS strip + recursive fs.watch).
   // 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' });
@@ -1464,7 +1464,7 @@ export async function createRequestHandler(opts) {
 }
 
 /**
- * Start a webjs HTTP server. Thin wrapper around `createRequestHandler`.
+ * Start a WebJs HTTP server. Thin wrapper around `createRequestHandler`.
  *
  * Speaks plain HTTP/1.1. TLS termination + HTTP/2 to the browser is
  * expected to be handled by a reverse proxy (PaaS edge, nginx, Caddy,
@@ -1745,6 +1745,14 @@ async function tryServeFrameworkStatic(path, method, ctx) {
     });
   }
 
+  // Dev live-reload SharedWorker: one shared connection for all tabs (#887).
+  if (path === '/__webjs/reload-worker.js') {
+    if (!dev) return new Response('Not found', { status: 404 });
+    return new Response(reloadWorkerJs(basePath()), {
+      headers: { 'content-type': 'application/javascript; charset=utf-8' },
+    });
+  }
+
   // Core module: /__webjs/core/*
   //
   // ETag + ~1h max-age, NOT immutable. The URL path is un-versioned
@@ -1822,7 +1830,8 @@ async function handleCore(req, ctx) {
 
   // Health / readiness probes (`/__webjs/health`, `/__webjs/ready`) and the
   // framework-internal static assets (`/__webjs/core/*`, `/__webjs/reload.js`,
-  // downloaded `/__webjs/vendor/*`) are served in `handle()` BEFORE ensureReady,
+  // `/__webjs/reload-worker.js`, downloaded `/__webjs/vendor/*`) are served in
+  // `handle()` BEFORE ensureReady,
   // so they are not repeated here. This fallback covers the (currently
   // unreachable) case of handleCore being entered for one of those assets, so
   // the routing stays correct if a future caller bypasses the early path.
@@ -2138,7 +2147,7 @@ async function loadMiddleware(appDir, dev, logger) {
  * @param {import('./logger.js').Logger} logger
  */
 /**
- * Create a plain HTTP/1.1 server. webjs deploys are expected to sit
+ * Create a plain HTTP/1.1 server. WebJs deploys are expected to sit
  * behind a reverse proxy (PaaS edge, nginx, Caddy, etc.) that handles
  * TLS termination and speaks HTTP/2 to clients: Node's http2 module
  * doesn't need to be involved on the framework side.
@@ -2259,7 +2268,25 @@ async function sendWebResponse(res, webRes, req, opts) {
  */
 async function fileResponse(abs, opts) {
   try {
-    const data = await readFile(abs);
+    let data = await readFile(abs);
+    // In dev an external watcher (tailwindcss --watch, esbuild, ...) rewrites a
+    // public asset with truncate-then-write, so the file is 0 bytes for a short
+    // window during a rebuild. A hot reload that lands in that window would
+    // serve empty CSS / JS and the page paints unstyled (#891). Close that
+    // 0-byte window: when an empty read comes from a file that was JUST modified
+    // (the mid-rewrite signal), re-read a few times so the truncated read does
+    // not reach the browser. A genuinely empty, untouched asset is served
+    // immediately (no delay), and a non-zero-but-partial write is a smaller
+    // residual gap this does not cover. Prod has no such watcher and is
+    // left untouched.
+    if (opts.dev && data.length === 0) {
+      let midRewrite = false;
+      try { midRewrite = Date.now() - (await stat(abs)).mtimeMs < 500; } catch { /* gone */ }
+      for (let i = 0; midRewrite && i < 12 && data.length === 0; i++) {
+        await new Promise((r) => setTimeout(r, 20));
+        try { data = await readFile(abs); } catch { break; }
+      }
+    }
     const type = MIME[extname(abs).toLowerCase()] || 'application/octet-stream';
     // The body is fully buffered (read into `data`), so opt it into the
     // conditional-GET funnel, which is the single place that hashes the bytes
@@ -2327,7 +2354,7 @@ async function exists(p) {
  * dev server returns the error to the caller. The
  * `erasable-typescript-only` and `no-non-erasable-typescript` lint
  * rules catch these at edit time. There is no bundler fallback;
- * webjs is buildless end-to-end.
+ * 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
@@ -2609,18 +2636,74 @@ function locatePackageDir(appDir, pkgName) {
 const DEV_OVERLAY_SRC = readFileSync(new URL('./dev-overlay.js', import.meta.url), 'utf8')
   .replace(/^export /gm, '');
 
+// The reload SharedWorker relay source (#887), read once + `export`-stripped so
+// it inlines into the served worker script. Sharing the one source
+// (`dev-reload-worker.js`, which the browser test imports directly) means the
+// test drives the EXACT relay code that ships, with no drift (same as #264).
+const RELOAD_WORKER_SRC = readFileSync(new URL('./dev-reload-worker.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
 function reloadClientJs(bp) {
   // The overlay renderer uses textContent throughout (never innerHTML), so the
   // error message / code frame can never inject markup (#264). Served only in
   // dev (the /__webjs/reload.js branch 404s in prod), so it never reaches a
   // production page.
+  //
+  // Every tab shares ONE live-reload connection through a SharedWorker (#887).
+  // The old client opened an `EventSource` per tab, and because the dev server
+  // is HTTP/1.1 and browsers cap concurrent connections per host at ~6, a
+  // handful of open tabs would hold every connection slot with idle SSE streams
+  // and later tabs could not even fetch their HTML. The SharedWorker holds the
+  // single `EventSource` (see reloadWorkerJs) and relays each `reload` /
+  // `webjs-error` to every tab. The overlay still renders on the main thread
+  // (a worker has no DOM), so the worker forwards only the raw frame data.
+  //
+  // Fallback: where `SharedWorker` is missing (some mobile browsers) or its
+  // construction throws (a strict dev CSP without `worker-src`), each tab opens
+  // its own `EventSource`, the original behaviour. Correct, just not shared.
+  const eventsUrl = JSON.stringify(withBasePath('/__webjs/events', bp));
+  const workerUrl = JSON.stringify(withBasePath('/__webjs/reload-worker.js', bp));
   return `// webjs dev reload client
 ${DEV_OVERLAY_SRC}
-const es = new EventSource(${JSON.stringify(withBasePath('/__webjs/events', bp))});
-es.addEventListener('reload', () => location.reload());
-es.addEventListener('webjs-error', (e) => {
-  let f; try { f = JSON.parse(e.data); } catch (_) { return; }
+function __webjsApplyError(data) {
+  let f; try { f = JSON.parse(data); } catch (_) { return; }
   renderDevOverlay(f);
-});
+}
+function __webjsDirectEvents() {
+  const es = new EventSource(${eventsUrl});
+  es.addEventListener('reload', () => location.reload());
+  es.addEventListener('webjs-error', (e) => __webjsApplyError(e.data));
+}
+try {
+  if (typeof SharedWorker !== 'undefined') {
+    const w = new SharedWorker(${workerUrl});
+    w.port.onmessage = (e) => {
+      const m = e.data || {};
+      if (m.type === 'reload') location.reload();
+      else if (m.type === 'webjs-error') __webjsApplyError(m.data);
+    };
+    w.port.start();
+  } else {
+    __webjsDirectEvents();
+  }
+} catch (_) {
+  __webjsDirectEvents();
+}
+`;
+}
+
+/**
+ * The dev live-reload SharedWorker. One instance is shared across every tab of
+ * the same origin (a SharedWorker is keyed by its script URL), so it holds the
+ * ONE `EventSource` to `/__webjs/events` and fans each event out to all tabs
+ * over their `MessagePort`s (#887). The `EventSource` URL carries the base path
+ * the same way the client's does (#256). Served only in dev.
+ * @param {string} bp the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+function reloadWorkerJs(bp) {
+  return `// webjs dev reload worker (one shared connection for all tabs)
+${RELOAD_WORKER_SRC}
+startReloadWorker(self, EventSource, ${JSON.stringify(withBasePath('/__webjs/events', bp))});
 `;
 }

package/src/elision-report.js

@@ -2,7 +2,7 @@
  * App-level elision report (#646).
  *
  * A reporting layer over the `analyzeElision` verdict, NOT a second analysis
- * and NOT a build (webjs is no-build; elision is the server's analysis pass,
+ * and NOT a build (WebJs is no-build; elision is the server's analysis pass,
  * run at dev-server start and re-derived after each fs.watch rebuild). It
  * builds the module graph, runs `analyzeElision`, and returns the page / layout
  * route modules that SHIP WHOLE to the browser, each with the first

package/src/env-schema.js

@@ -1,7 +1,7 @@
 /**
  * Startup env-var validation with a typed schema hook (issue #236).
  *
- * webjs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
+ * WebJs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
  * validation, so a missing or misconfigured required var (DATABASE_URL,
  * AUTH_SECRET, ...) fails late and cryptically (a database connect error
  * mid-request, an undefined secret signing a token). This module adds an

package/src/file-storage.js

@@ -2,7 +2,7 @@
  * File storage primitive: a pluggable `FileStore` with a streaming local-disk
  * default adapter (issue #247).
  *
- * webjs already round-trips a native `File` / `Blob` / `FormData` over the RPC
+ * WebJs already round-trips a native `File` / `Blob` / `FormData` over the RPC
  * wire (the serializer), but nothing decided WHERE the bytes land. This module
  * is that answer. The model mirrors `cache.js` exactly: a documented interface,
  * a default adapter (`diskStore`), and a module singleton (`setFileStore` /
@@ -35,7 +35,7 @@
  *     (`File` / `Blob` / `ReadableStream` / `Uint8Array` in, a `{ body, size,
  *     contentType }` handle out), so an S3 / R2 / GCS adapter is a drop-in: it
  *     implements the same `put` / `get` / `delete` / `url` and the call sites do
- *     not change. webjs ships no S3 SDK; see the JSDoc on `FileStore` below.
+ *     not change. WebJs ships no S3 SDK; see the JSDoc on `FileStore` below.
  *
  * @module file-storage
  */

package/src/forwarded.js

@@ -2,7 +2,7 @@
  * Build a full URL from a Node IncomingMessage, respecting standard
  * reverse-proxy headers (`X-Forwarded-Proto`, `X-Forwarded-Host`).
  *
- * Why: webjs apps are almost always deployed behind a reverse proxy
+ * Why: WebJs apps are almost always deployed behind a reverse proxy
  * (Railway, Fly, Render, Vercel, Cloudflare, nginx, Caddy, Traefik -
  * see the no-build architecture docs). The proxy terminates TLS and
  * speaks plain HTTP/1.1 to the container, so `req.url` inside the

package/src/headers.js

@@ -2,7 +2,7 @@
  * Secure-by-default response headers plus a small declarative per-path
  * header config (issue #232).
  *
- * webjs sets a baseline of standard security headers on every document
+ * WebJs sets a baseline of standard security headers on every document
  * and asset response, so a scaffolded app is not clickjackable or
  * MIME-sniffable out of the box (no reverse proxy required for the
  * baseline). The defaults are LITERAL HTTP headers, no abstraction.

package/src/json.js

@@ -15,7 +15,7 @@ import { readTextBounded, BodyLimitError, DEFAULT_MAX_BODY_BYTES } from './body-
  * The helper reads the in-flight Request from the AsyncLocalStorage
  * request context. If the caller sent `Accept: application/vnd.webjs+json`
  * (e.g. via the `richFetch` client helper), the response body is
- * encoded with the webjs serializer so rich types (Date, Map, Set,
+ * encoded with the WebJs serializer so rich types (Date, Map, Set,
  * BigInt, TypedArrays, Blob, File, FormData, cycles) survive. Otherwise
  * the response is plain `application/json`, unchanged behaviour for
  * curl / external consumers.
@@ -47,7 +47,7 @@ export async function json(data, init = {}) {
 }
 
 /**
- * Parse a request body using the webjs serializer when the client sent
+ * Parse a request body using the WebJs serializer when the client sent
  * our content type, otherwise as plain JSON. Handy for route handlers
  * that accept rich bodies from the `richFetch` helper but plain JSON
  * from everyone else.

package/src/listener-bun.js

@@ -73,7 +73,7 @@ export function startBunListener(ctx) {
   const server = Bun.serve({
     port,
     idleTimeout: bunIdleTimeout(timeouts),
-    // webjs owns its dev error overlay (over SSE) and handles thrown errors in
+    // 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,
@@ -172,7 +172,7 @@ export function startBunListener(ctx) {
  * 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
+ * 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.

package/src/logger.js

@@ -1,7 +1,7 @@
 /**
  * Minimal pluggable logger.
  *
- * webjs doesn't pick pino/winston/bunyan for you. The default in prod emits
+ * WebJs doesn't pick pino/winston/bunyan for you. The default in prod emits
  * one JSON object per line to stdout: trivially ingestable by any log
  * aggregator. In dev, lines are plain text for readability.
  *

package/src/node-version.js

@@ -1,7 +1,7 @@
 /**
  * Node-version preflight guard (issue #238).
  *
- * webjs depends on Node 24+ built-ins: `module.stripTypeScriptTypes` (the
+ * WebJs depends on Node 24+ built-ins: `module.stripTypeScriptTypes` (the
  * no-build TypeScript strip) and recursive `fs.watch` (dev live-reload). On an
  * older Node the failure surfaces late and cryptically (a strip error or a
  * missing API deep inside a request), not as a clear "you need Node 24+". This

package/src/redirects.js

@@ -1,7 +1,7 @@
 /**
  * Declarative permanent / temporary redirects (issue #254).
  *
- * webjs already ships `redirect(url)` (a per-request throw sentinel) for
+ * WebJs already ships `redirect(url)` (a per-request throw sentinel) for
  * imperative, request-time redirects. This module adds the missing
  * DECLARATIVE surface: a config of old-path -> new-path rules an app
  * declares once and the framework applies at the very start of request

package/src/serializer.js

@@ -2,7 +2,7 @@ import { stringify, parse } from '@webjsdev/core';
 
 /**
  * @typedef {Object} Serializer
- * A pluggable serializer that controls how webjs server actions encode and
+ * A pluggable serializer that controls how WebJs server actions encode and
  * decode values on the RPC wire.
  *
  * **AI hint:** The default serializer uses webjs's built-in
@@ -50,7 +50,7 @@ let current = defaultSerializer;
  *
  * **AI hint:** Use this in server-side code that needs to encode or decode
  * RPC payloads. It returns whatever serializer was set via `setSerializer`,
- * or the default webjs serializer if none was set.
+ * or the default WebJs serializer if none was set.
  *
  * @returns {Serializer}
  */

package/src/testing.js

@@ -1,7 +1,7 @@
 /**
  * Server-side test harness helpers (issue #267).
  *
- * `createRequestHandler(...).handle(request)` drives the FULL webjs pipeline
+ * `createRequestHandler(...).handle(request)` drives the FULL WebJs pipeline
  * (middleware, routing, SSR, page actions, server-action RPC, auth + CSRF), and
  * the framework's own suite already drives it. These helpers are THIN builders
  * over the native `Request` / `Response` around that `handle()`, so an app test
@@ -350,7 +350,7 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
 }
 
 /**
- * Browser-test harness (#806): build a webjs handler that a `web-test-runner`
+ * Browser-test harness (#806): build a WebJs handler that a `web-test-runner`
  * config can proxy module requests to, so a `test/**​/browser/*.test.js` file
  * can import a real `.ts` component that imports a `'use server'` action and it
  * loads + hydrates in a real browser. Plain WTR serves raw TS with no webjs
@@ -369,7 +369,7 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
  * of `@webjsdev/server/testing` stays light (they pull the full server + the
  * `ws` WebSocket subsystem).
  *
- * @param {string} appDir  the webjs app root (usually `process.cwd()`)
+ * @param {string} appDir  the WebJs app root (usually `process.cwd()`)
  * @returns {Promise<{ handle: Handle, warmup: () => Promise<void>, importmapHtml: () => string }>}
  */
 export async function createBrowserTestHandler(appDir) {

package/src/ts-strip.js

@@ -1,8 +1,8 @@
 /**
- * Pluggable TypeScript stripper (#508), the one seam that lets webjs run on both
+ * 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
+ * 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

package/src/vendor.js

@@ -1,7 +1,7 @@
 /**
  * Resolve bare npm imports to browser-loadable URLs via jspm.io.
  *
- * webjs follows the Rails 7 + importmap-rails posture exactly. When user
+ * WebJs follows the Rails 7 + importmap-rails posture exactly. When user
  * code imports a bare specifier (e.g. `import dayjs from 'dayjs'`), the
  * browser can't resolve it natively. The framework's job is to emit an
  * importmap that translates each bare specifier to a real URL.
@@ -10,7 +10,7 @@
  *
  *   importmap: { "dayjs": "https://ga.jspm.io/npm:dayjs@1.11.13/index.js" }
  *
- * The browser fetches the bundle directly from jspm.io. The webjs server
+ * The browser fetches the bundle directly from jspm.io. The WebJs server
  * does not proxy, cache, or bundle anything. jspm.io has done the work
  * server-side (CJS-to-ESM conversion, transitive bundling, browser
  * polyfills).
@@ -85,7 +85,7 @@ const FRAMEWORK_SERVER_ONLY = new Set(['@webjsdev/cli', '@webjsdev/server', '@we
  * Excludes:
  *   - `node_modules`, `.webjs`, `public` directories
  *   - Any directory starting with `_` (webjs `_private/` convention)
- *   - `test/` and `tests/` (server-only by webjs convention)
+ *   - `test/` and `tests/` (server-only by WebJs convention)
  *   - Files whose name marks them as server-only:
  *       * `*.server.{js,ts,mjs,mts}` (path-level boundary)
  *       * `route.{js,ts,mjs,mts}` (file-router HTTP handler)
@@ -1030,7 +1030,7 @@ export async function readPinFile(appDir) {
  * When `integrity` is provided and non-empty, it's included alongside
  * `imports` as a sibling key (matching the browser importmap-integrity
  * spec: a flat `{url: 'sha384-...'}` map). Omitted entirely when empty
- * so older webjs versions read the file as before.
+ * so older WebJs versions read the file as before.
  *
  * `provider` is persisted alongside imports when non-default. It lets
  * `webjs vendor update` know which CDN to re-resolve against, and
@@ -1343,7 +1343,7 @@ export async function pinAll(appDir, opts = {}) {
   }
 
   // The app legitimately has zero bare-specifier imports (or the
-  // scanner is running outside a webjs project). Don't create an
+  // scanner is running outside a WebJs project). Don't create an
   // empty `.webjs/vendor/importmap.json`. Without this guard the file
   // gets written as `{ imports: {} }` in whatever cwd the CLI was
   // invoked from, then immediately rejected by readPinFile's empty