fix: isolate the shim port from application throws, and close the doc drift

Review found five things.

The shim port the per-tab fallback hands the relay runs application code
synchronously in its postMessage, and the relay deletes a port whose
postMessage throws. That heuristic reads a throw as "the tab is gone",
which is right for a real MessagePort and wrong here: an overlay render
that threw would permanently unsubscribe the tab and silently kill its
live reload. The pre-#1397 fallback attached to the EventSource directly,
where a handler throw detached nothing, so the guard restores the old
behaviour rather than adding a new one.

The ?v= test claimed to cover the early path while building the handler
with dev: false, so it exercised the prod path instead. It cannot be
written the other way, since fileResponse hard-codes no-cache whenever dev
is true, so immutable is unobservable there. Retitled to what it actually
pins, plus a dev-mode assertion that a fingerprinted asset still serves on
the early path.

Correcting the middleware prose left two code-block comments two lines
below still saying "every request", and the same claim was still on the
agent-facing skill reference the scaffold ships, in the root AGENTS.md
layout table, and in the blog example's own middleware.

Inserting the two constants between the module header and the function
orphaned its @PARAM tags onto a constant, and the header no longer
mentioned that reloadClientJs inlines this source too.

Author: vivek7405

.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -202,7 +202,7 @@ Export `GET` / `POST` / etc. as named async functions `(request, { params }) =>
 
 ### `middleware.ts` is per-segment and chainable, not one matcher config
 
-The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every request, outermost to innermost.
+The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every app request, outermost to innermost. Two things are served ahead of it: the framework's own `/__webjs/*` assets and probes, in both modes, and in DEV only, `/public/*` plus the `/sw.js` / `/offline.html` root remaps and `/favicon.ico`, so a stylesheet is never queued behind the dev startup analysis. In production those static files go through root middleware normally, so a middleware that guards an asset still guards it where it counts.
 
 ### No `<Link>`, no `next/navigation`, no `next/*` libraries
 

AGENTS.md

@@ -185,7 +185,7 @@ app/                        ROUTING ONLY (thin adapters importing from modules/;
   <path>/route.js           HTTP handler at /<path>
   <segment>/middleware.js   per-segment middleware
   <segment>/loading.js      auto Suspense boundary
-middleware.js               root middleware (every request; .ts/.mts/.mjs too)
+middleware.js               root middleware (every app request; .ts/.mts/.mjs too)
 readiness.js                optional /__webjs/ready check (return false/throw = 503)
 env.js                      optional boot-time env validation (schema or validator fn; fails fast)
 instrumentation.js          optional boot-time hook (register(); wire APM via setOnError, #848)

examples/blog/middleware.ts

@@ -1,5 +1,5 @@
 /**
- * Global middleware. Runs on every request before webjs routes it.
+ * Global middleware. Runs on every app request before webjs routes it.
  * Return a Response to short-circuit; call next() to continue.
  *
  * To add framework sessions:

packages/server/src/dev-reload-worker.js

@@ -2,19 +2,19 @@
  * 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.
+ * `dev-overlay.js` (#264).
+ *
+ * BOTH served dev scripts inline this file, `export`-stripped. `reloadWorkerJs`
+ * appends a `startReloadWorker(self, EventSource, '<eventsUrl>')` call for the
+ * SharedWorker, and since #1397 `reloadClientJs` inlines it too, so the per-tab
+ * fallback runs this same relay over a shim port instead of a second copy of
+ * the boot-id rule and the reload debounce.
  *
  * 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
  */
 
 /**
@@ -42,6 +42,14 @@ export const RELOAD_QUIET_MS = 2000;
  */
 export const RELOAD_MAX_HOLD_MS = 5000;
 
+/**
+ * @param {{ onconnect: any, setTimeout?: any, clearTimeout?: any }} scope  the
+ *   worker global (`self`), or a plain shim object for the per-tab fallback.
+ *   Timers are read off it when it has them, which is what lets a browser test
+ *   drive the debounce on a fake clock.
+ * @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();

packages/server/src/dev.js

@@ -3084,8 +3084,19 @@ function __webjsDirectEvents() {
   const scope = {};
   startReloadWorker(scope, EventSource, ${eventsUrl});
   scope.onconnect({ ports: [{ start() {}, postMessage(m) {
-    if (m.type === 'reload') __webjsReloadWhenReady();
-    else if (m.type === 'webjs-error') __webjsApplyError(m.data);
+    // Nothing may throw out of here. The relay's fanout deletes a port whose
+    // postMessage throws, which is the right read for a REAL MessagePort (a
+    // throw there means the tab is gone) and the wrong one for this shim,
+    // whose postMessage runs application code synchronously: an overlay
+    // render that threw would permanently unsubscribe this tab and silently
+    // kill live reload for the rest of the page's life. The old fallback
+    // attached to the EventSource directly, where a handler throw detached
+    // nothing, so swallowing here restores that behaviour rather than adding
+    // a new one.
+    try {
+      if (m.type === 'reload') __webjsReloadWhenReady();
+      else if (m.type === 'webjs-error') __webjsApplyError(m.data);
+    } catch (_) { /* a bad frame must not cost this tab its live reload */ }
   } }] });
 }
 try {

packages/server/test/dev/public-before-analysis.test.js

@@ -160,11 +160,25 @@ test('a stale webjs.dev.regenerate output is rebuilt before serving on the early
   assert.equal(await res.text(), 'body{color:lime}', 'the stale output was regenerated, not served as-is');
 });
 
-// #243: the `?v=` fingerprint still decides the cache header on the early path.
-test('?v= still yields immutable on the early path, un-versioned keeps the 1h fallback', async () => {
+// #243: the `?v=` fingerprint still decides the cache header through the
+// extracted function. This is the PROD path deliberately, and it is the one
+// case in this file that is not about the dev hoist. `fileResponse` hard-codes
+// `cache-control: no-cache` whenever `opts.dev` is true, so `immutable` is
+// unobservable on the dev early path by construction; asserting it there would
+// be a test that cannot fail. What this pins is that the extraction did not
+// drop the fingerprint handling on the call site that still serves it.
+test('?v= still yields immutable through the extracted serve (prod), un-versioned keeps the 1h fallback', async () => {
   const app = await createRequestHandler({ appDir: makeApp(), dev: false });
   const versioned = await app.handle(new Request('http://x/public/a.css?v=abc123'));
   assert.match(versioned.headers.get('cache-control') || '', /immutable/, 'content-addressed is immutable');
   const plain = await app.handle(new Request('http://x/public/a.css'));
   assert.doesNotMatch(plain.headers.get('cache-control') || '', /immutable/, 'un-fingerprinted is not');
+
+  // The dev half of the same concern, which IS on the early path: a `?v=`
+  // request still resolves and serves rather than falling through, even though
+  // the header it earns in dev is `no-cache` either way.
+  const devApp = await createRequestHandler({ appDir: makeApp(), dev: true });
+  const devVersioned = await devApp.handle(new Request('http://x/public/a.css?v=abc123'));
+  assert.equal(devVersioned.status, 200, 'a fingerprinted asset still serves on the dev early path');
+  assert.equal(await devVersioned.text(), 'body{color:red}\n');
 });

packages/server/test/dev/reload-shared-connection.test.js

@@ -48,6 +48,30 @@ test('dev serves the reload SharedWorker, and the client uses it with a direct E
   assert.match(clientSrc, /function startReloadWorker/, 'the client inlines the relay module for the fallback');
   assert.match(clientSrc, /startReloadWorker\(scope, EventSource, "\/__webjs\/events"\)/, 'the fallback runs the relay against the real EventSource');
   assert.match(clientSrc, /scope\.onconnect\(\{ ports: \[\{/, 'and drives it over a shim port');
+  // The shim's postMessage runs application code synchronously, and the relay's
+  // fanout DELETES a port whose postMessage throws (correct for a real
+  // MessagePort, where a throw means the tab is gone). Unguarded, an overlay
+  // render that threw would permanently unsubscribe the tab and silently kill
+  // its live reload, which the pre-#1397 fallback could not do because it
+  // attached to the EventSource directly.
+  //
+  // Sliced to the fallback function's own body first. A regex over the whole
+  // client matches the SharedWorker bootstrap's `try { ... } catch` further
+  // down and passes with the guard removed, which is a test that observes
+  // nothing (found by running exactly that counterfactual).
+  const fallbackStart = clientSrc.indexOf('function __webjsDirectEvents()');
+  assert.notEqual(fallbackStart, -1, 'the fallback function is in the client');
+  const fallbackBody = clientSrc.slice(fallbackStart, clientSrc.indexOf('if (typeof SharedWorker', fallbackStart));
+  assert.match(
+    fallbackBody,
+    /postMessage\(m\)\s*\{[^]*?try\s*\{/,
+    'the shim port opens a try before running any application code',
+  );
+  assert.match(fallbackBody, /\}\s*catch\s*\(_\)/, 'and swallows the throw so the relay cannot drop the tab');
+  assert.ok(
+    fallbackBody.indexOf('try {') < fallbackBody.indexOf('__webjsReloadWhenReady()'),
+    'the guard opens BEFORE the reload call, not around something else',
+  );
   assert.match(clientSrc, /catch\s*\(_\)\s*\{\s*__webjsDirectEvents/, 'a worker failure falls back');
   // The debounce (#1397) is part of the relay, so it ships in BOTH scripts.
   assert.match(clientSrc, /const RELOAD_QUIET_MS/, 'the reload debounce ships in the client fallback');

website/app/docs/middleware/page.ts

@@ -11,7 +11,7 @@ export default function Middleware() {
     <p>Place a <code>middleware.ts</code> at the root of your project (next to <code>app/</code>, not inside it). This middleware runs on <strong>every app request</strong> before WebJs routes it to a page, API route, or server action. Any of <code>middleware.ts</code>, <code>.js</code>, <code>.mts</code>, or <code>.mjs</code> works, and <code>.ts</code> wins if you somehow have more than one.</p>
     <p>Two things are served ahead of it, so root middleware never sees them. The framework's own <code>/__webjs/*</code> assets and health probes bypass it in both dev and production, because they are framework infrastructure your app needs to boot rather than app routes. In <strong>development only</strong>, static files under <code>/public/*</code> (plus the <code>/sw.js</code> and <code>/offline.html</code> root remaps and <code>/favicon.ico</code>) are served ahead of it as well, so a stylesheet is never queued behind the dev server's startup analysis. In production those static files go through root middleware normally, so a middleware that protects an asset still protects it where it counts.</p>
     <code-block>my-app/
-  middleware.ts          # root middleware: runs on every request
+  middleware.ts          # root middleware: runs on every app request
   app/
     page.ts
     api/
@@ -33,7 +33,7 @@ export default async function middleware(
     <h2>Per-Segment Middleware</h2>
     <p>Place a <code>middleware.ts</code> inside any directory under <code>app/</code> to scope it to that subtree. It runs only for requests whose URL matches that segment and its children.</p>
     <code-block>my-app/
-  middleware.ts               # root: every request
+  middleware.ts               # root: every app request
   app/
     page.ts                   # /: root + no segment middleware
     dashboard/