@webjsdev/server 0.8.58 → 0.8.59

package/src/actions.js

@@ -20,6 +20,7 @@ import { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
+import { FORM_ACTION_ID_KEY } from '@webjsdev/core';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -417,11 +418,18 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
     lines.push(`  return __body(fn, key, __METHOD, sig);`);
     lines.push(`}`);
   }
+  // Each stub carries its own `<hash>/<fn>` identity (#1155), so a client
+  // re-render of `<form action=${action}>` can bind the live form
+  // synchronously. The server resolves the REAL function's identity through the
+  // load-hook registry instead; both produce the same string, which is what
+  // makes the SSR'd form and the re-rendered one submit the same value.
+  // Non-enumerable so `import * as actions` and a spread stay unchanged.
+  lines.push(`const __id = (fn, name) => { try { Object.defineProperty(fn, ${J(FORM_ACTION_ID_KEY)}, { value: __HASH + '/' + name }); } catch {} return fn; };`);
   for (const name of fnNames) {
     lines.push(
       name === 'default'
-        ? `export default (...args) => __call('default', args);`
-        : `export const ${name} = (...args) => __call(${J(name)}, args);`,
+        ? `export default __id((...args) => __call('default', args), 'default');`
+        : `export const ${name} = __id((...args) => __call(${J(name)}, args), ${J(name)});`,
     );
   }
   return lines.join('\n') + '\n';

package/src/base-path.js

@@ -11,7 +11,10 @@
  * hydrates. `createRequestHandler` explicitly targets embedding, where a
  * sub-path mount is the norm.
  *
- * The model is strip-at-ingress + prefix-on-emit, two seams only:
+ * The model is strip-at-ingress + prefix-on-emit. Two seams carry it, plus two
+ * further `stripBasePath` consumers on the CACHE path (`dev.js`'s HTML-cache
+ * write and `html-cache.js`'s `revalidatePath`), which key on the
+ * app-root-relative path so a mounted app hits its own cache:
  *
  *   1. STRIP AT INGRESS. At the very start of request handling, when the
  *      request pathname starts with the basePath, strip it so all

package/src/body-limit.js

@@ -3,7 +3,7 @@
  *
  * webjs's prod server reads request bodies on three paths: the server-action
  * RPC endpoint (actions.js), `route.{js,ts}` handlers via `readBody` (json.js),
- * and the no-JS page-action form path (page-action.js). Without a cap, an
+ * and the no-JS form-submission path (form-dispatch.js). Without a cap, an
  * uncapped body is a memory-exhaustion vector. This module is the SINGLE place
  * that decides the limit and performs a bounded read, so every body-read site
  * enforces it uniformly.
@@ -31,7 +31,7 @@
 export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
 /**
- * Default form / multipart body cap: 10 MiB. A form submission (the page-action
+ * Default form / multipart body cap: 10 MiB. A form submission (the form-dispatch
  * path) may legitimately carry more than a JSON RPC call (a textarea, a small
  * upload), so it gets a separate, higher, still-bounded limit. Large file
  * uploads are a distinct concern (#247) with their own streaming story.
@@ -40,7 +40,7 @@ export const DEFAULT_MAX_MULTIPART_BYTES = 10 * 1024 * 1024;
 
 /**
  * Thrown by `readBody` (json.js) when a route handler's body exceeds the limit.
- * The RPC and page-action paths return a 413 Response inline, but `readBody`
+ * The RPC and form-dispatch paths return a 413 Response inline, but `readBody`
  * runs INSIDE a user route handler and returns parsed data, so it signals the
  * over-limit case by throwing. The API dispatcher (`handleApi`) catches this and
  * maps it to a 413, so a handler that just does `await readBody(req)` gets the
@@ -266,7 +266,7 @@ export async function readTextBounded(req, limit) {
 }
 
 /**
- * Read a request body as `FormData`, bounded by `limit`. Used by the page-action
+ * Read a request body as `FormData`, bounded by `limit`. Used by the form-dispatch
  * form path. Reconstructs a bounded Request from the already-read bytes and
  * defers to the platform `formData()` parser, so multipart and
  * urlencoded bodies are decoded exactly as before, just size-checked first.

package/src/check.js

@@ -3,6 +3,7 @@ import { join, relative, sep, basename, dirname } from 'node:path';
 import { walk } from './fs-walk.js';
 import {
   redactStringsAndTemplates,
+  redactToPlaceholders,
   extractWebComponentClassBodies,
   matchClosingBrace,
   parsePropEntries,
@@ -134,6 +135,11 @@ export const RULES = [
     description:
       'A `\'use server\'` action file that declares HTTP-verb config (any of `method` / `cache` / `tags` / `invalidates` / `validate`, #488) must export exactly ONE callable action function. The config is file-level (it applies to the action in the file), so a second exported function would silently inherit the same verb / cache, which is almost never intended and makes the contract ambiguous. Move the extra function to its own `.server.ts` file (the one-function-per-file convention), or, if it is a private helper, do not export it. Files with no verb config are unaffected.',
   },
+  {
+    name: 'form-action-not-a-get-action',
+    description:
+      'Flags `<form action=${someAction}>` bound to a `\'use server\'` action whose file declares `export const method = \'GET\'` (#488). A GET action is a READ: it is CSRF-exempt and rides its arguments in the url, while a form submission is a CSRF-checked POST carrying a body, so the two contracts contradict each other and the submission is answered with a 405 at runtime. The rule reads the imported action\'s own file, so it only fires when the binding really does resolve to a GET-declared action. Fix by dropping the `method` export (an action with no `method` is a POST, which is what a form wants) or by binding a different action; if the form really is a read, use a plain `<form method="get" action="/search">` with no bound action.',
+  },
   {
     name: 'no-redirect-in-api-route',
     description:
@@ -475,6 +481,36 @@ function enumerableExports(scan) {
  * @param {string} clause  the text between `import` and `from`
  * @returns {string[]|null}
  */
+/**
+ * The `{ local, imported }` pairs a named import clause binds, for a rule that
+ * has to match the LOCAL name against code (`action=${reader}`) while reporting
+ * the IMPORTED one (`readIt`, which is what the target module calls it).
+ *
+ * `importedValueNames` cannot serve here: it returns only the imported side,
+ * which is the wrong name to match against a template hole under `as`.
+ *
+ * @param {string} clause  the text between `import` and `from`
+ * @returns {{ local: string, imported: string }[]}
+ */
+function importedLocalNames(clause) {
+  if (/^\s*type\b/.test(clause)) return [];
+  const brace = clause.match(/\{([^}]*)\}/);
+  if (!brace) return [];
+  /** @type {{ local: string, imported: string }[]} */
+  const out = [];
+  for (const part of brace[1].split(',')) {
+    const seg = part.trim().replace(/^type\s+/, '');
+    if (!seg) continue;
+    const as = seg.split(/\s+as\s+/);
+    const imported = as[0].trim();
+    const local = (as[1] || as[0]).trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(local) && /^[A-Za-z_$][\w$]*$/.test(imported)) {
+      out.push({ local, imported });
+    }
+  }
+  return out;
+}
+
 function importedValueNames(clause) {
   if (/^\s*type\b/.test(clause)) return null; // import type { ... }
   const brace = clause.match(/\{([^}]*)\}/);
@@ -489,8 +525,9 @@ function importedValueNames(clause) {
 /**
  * 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
+ * Every rule is a correctness check (a crash, a security leak, a reactive
+ * prop that silently stops re-rendering, or a build/type-strip failure), so
+ * they all run unconditionally. There is no
  * per-project disabling: project conventions (layout, style, process) live in
  * CONVENTIONS.md as guidance, not in this tool.
  *
@@ -1333,6 +1370,90 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: form-action-not-a-get-action (#1155) ---
+  // `<form action=${fn}>` binds a server action to a POST submission. An action
+  // declaring `method = 'GET'` cannot serve one: it is CSRF-exempt and takes its
+  // args in the url, so the dispatcher answers 405. Catch it at edit time.
+  {
+    // A `'use server'` file's declared method, or absent when it declares none.
+    const methodByAbs = new Map();
+    for (const f of files) {
+      if (!/\.server\.m?[jt]s$/.test(f.rel)) continue;
+      if (!hasUseServerDirective(f.content)) continue;
+      const m = /\bexport\s+const\s+method\s*(?::[^=]*)?=\s*['"`]([A-Za-z]+)['"`]/.exec(f.scan);
+      if (m) methodByAbs.set(f.abs, m[1].toUpperCase());
+    }
+    if (methodByAbs.size) {
+      const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+      for (const { abs, rel, content } of files) {
+        // PLACEHOLDER redaction, not either mask, and the choice is forced.
+        // The default mask blanks a tagged template outright, so a real
+        // `html`<form action=${fn}>`` disappears and the rule could never fire;
+        // the fully-blanked mask does the same. Placeholder mode keeps `${...}`
+        // holes as REAL code while turning each literal BODY into one opaque
+        // `__STR_n__` token, so a live binding is readable and a `<form
+        // action=${x}>` shown as text inside a docs sample is a single token
+        // with no hole in it. That distinction is the whole carve-out: the
+        // framework's own website renders this exact shape as a code sample.
+        const { redacted, literals } = redactToPlaceholders(content);
+        // A hole binds an action when the literal segment IMMEDIATELY before it
+        // ends inside a start tag at the attribute that tag can really bind:
+        // `action=` on a `<form>` (#1155), or `formaction=` on a `<button>` /
+        // `<input>` submitter (#1207). Reading the segment rather than the whole
+        // template is what keeps `<div action=${x}>` out. The tag and the
+        // attribute are matched as a PAIR, so `<form formaction=${x}>` and
+        // `<button action=${x}>` stay out too: both are refused at render time,
+        // and neither is this rule's failure mode.
+        const bound = new Set();
+        for (const m of redacted.matchAll(/__STR_(\d+)__\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) {
+          const before = literals[Number(m[1])] || '';
+          // The last `<` opens the tag the hole sits in. Requiring no `>`
+          // after it keeps the match inside that one start tag.
+          const tagAt = before.lastIndexOf('<');
+          if (tagAt < 0) continue;
+          const tag = before.slice(tagAt);
+          if (tag.includes('>')) continue;
+          const bindsForm = /^<form\b/i.test(tag) && /\saction=$/i.test(tag);
+          const bindsSubmitter = /^<(?:button|input)\b/i.test(tag) && /\sformaction=$/i.test(tag);
+          if (!bindsForm && !bindsSubmitter) continue;
+          bound.add(m[2]);
+        }
+        if (!bound.size) continue;
+        reImport.lastIndex = 0;
+        let im;
+        while ((im = reImport.exec(redacted))) {
+          // The specifier is a placeholder token in this view, so read the real
+          // one back out of `literals`.
+          const tok = /__STR_(\d+)__/.exec(redacted.slice(reImport.lastIndex, reImport.lastIndex + 24));
+          if (!tok) continue;
+          const spec = literals[Number(tok[1])] || '';
+          if (!/^(?:\.|#)/.test(spec)) continue;
+          const names = importedLocalNames(im[1]);
+          if (!names.length) continue;
+          const target = resolveImport(spec, abs, appDir);
+          // ONLY a GET is contradictory, and the rule must say exactly what the
+          // dispatcher does or it is a false positive. A browser form always
+          // submits as a POST, and the dispatcher runs a PUT / PATCH / DELETE
+          // action on that POST: the declared verb governs the RPC transport,
+          // not whether the function can serve a form. A GET is different in
+          // kind (CSRF-exempt, args in the url, no body), which is why it is
+          // the one the dispatcher answers with a 405.
+          const method = target ? methodByAbs.get(target) : undefined;
+          if (method !== 'GET') continue;
+          for (const { local, imported } of names) {
+            if (!bound.has(local)) continue;
+            violations.push({
+              rule: 'form-action-not-a-get-action',
+              file: rel,
+              message: `Binds \`${imported}\` to a form, but \`${spec}\` declares \`method = 'GET'\`. A GET action rides its arguments in the url and skips the CSRF check, so it cannot answer a form POST; the submission is a 405.`,
+              fix: `Drop the \`method\` export from \`${spec}\` (an action with no method is a POST, which is what a form submits), or bind an action that takes a POST.`,
+            });
+          }
+        }
+      }
+    }
+  }
+
   return violations;
 }
 

package/src/context.js

@@ -17,7 +17,7 @@ import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
  *
  * `bodyLimits` holds the resolved request body-size caps (issue #237) so
  * `readBody` (used inside `route.{js,ts}` handlers, which have no handle to the
- * server state) can enforce the same limit the RPC and page-action paths do. The
+ * server state) can enforce the same limit the RPC and form-dispatch paths do. The
  * handler writes it per request via `setBodyLimits`.
  *
  * `requestId` holds the per-request correlation id (issue #239). The handler

package/src/csp.js

@@ -50,8 +50,9 @@ const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/;
  * with webjs's own output, which is: nonce-signed inline `<script>` tags
  * (the boot script, the public-env shim, the importmap), nonce-signed
  * `<link rel="modulepreload">`, ES modules fetched same-origin and from
- * the configured vendor CDN, and Tailwind's runtime which injects a
- * `<style>` element (so inline styles must be allowed).
+ * the configured vendor CDN, and one inline `<style>` in the head. The
+ * nonce covers scripts only, so that rule and every app-authored style
+ * alike are admitted by `'unsafe-inline'` (see the `style-src` note).
  *
  * `script-src` uses `'strict-dynamic'` so a nonce-loaded module can pull
  * in its own dependencies (the importmap-driven per-file ESM graph)
@@ -67,10 +68,25 @@ const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/;
 const DEFAULT_DIRECTIVES = {
   'default-src': "'self'",
   'script-src': "'nonce-__NONCE__' 'strict-dynamic' 'self' https:",
-  // Tailwind's browser runtime injects a <style> element, and webjs
-  // emits an inline <style> for adopted component styles, so inline
-  // styles must be permitted. Style elements are not a script-injection
-  // vector, so this does not weaken the script protection.
+  // NOTE this directive carries no nonce source, unlike `script-src`, so a
+  // nonce attribute on a <style> is INERT here and every inline style is
+  // admitted by 'unsafe-inline' alone. That includes WebJs's own head rule
+  // (the @layer webjs-host block), which SSR does stamp with the nonce but
+  // which this policy never checks it against. Dropping 'unsafe-inline'
+  // would block that rule too, not only app style.
+  //
+  // What keeps the allowance necessary is inline style with no realistic
+  // nonce path, and it arrives in four shapes. A page or layout may write
+  // an inline <style>, which an author could nonce by hand but does not by
+  // default. A light-DOM component's <style> and a shadow component's
+  // `static styles`, serialized into its declarative shadow root, are both
+  // emitted by the core renderer with no nonce and no way to supply one.
+  // And every style="..." attribute is unfixable in principle, since a
+  // nonce applies to elements and never to attributes. No styling library
+  // is involved in any of them.
+  //
+  // Style elements are not a script-injection vector, so this does not
+  // weaken the script protection.
   'style-src': "'self' 'unsafe-inline'",
   'img-src': "'self' data: https:",
   'font-src': "'self' data: https:",

package/src/csrf.js

@@ -19,7 +19,10 @@
  *   2. When `Sec-Fetch-Site` is absent (an older browser), fall back to
  *      comparing the `Origin` host to the request host; an absent `Origin`
  *      can't be checked so it passes (a handcrafted / non-browser request
- *      can't carry a victim's SameSite cookies cross-site anyway).
+ *      can't carry a victim's SameSite cookies cross-site anyway). That
+ *      request host comes from `requestHost` below, which resolves
+ *      `x-forwarded-host` through the shared `trustProxy()` seam in
+ *      `forwarded.js` (#1104), so this file holds no trust posture of its own.
  *
  * Scope:
  *   - Internal RPC only. A `route.ts` REST endpoint (hand-written or via the
@@ -28,6 +31,8 @@
  *   - Session / auth cookies stay `SameSite=Lax` as defense-in-depth.
  */
 
+import { trustProxy } from './forwarded.js';
+
 /**
  * Parse cookies off a standard Request. Retained as a general cookie reader
  * (used by `context.js` for `cookies()`), independent of CSRF.
@@ -56,21 +61,37 @@ function hostOf(value) {
 }
 
 /**
- * The host the request was addressed to. Honors `x-forwarded-host` first
- * (set by a reverse proxy / CDN like the Cloudflare-in-front-of-Railway
- * setup), then the `Host` header, then the request URL.
+ * The host the request was addressed to: `x-forwarded-host` when a proxy is
+ * trusted to speak for the client (the Cloudflare-in-front-of-Railway setup),
+ * then the `Host` header, then the request URL.
+ *
+ * Trust note, preserved from before this read went through `trustProxy()`
+ * (#1104), because it is correct and non-obvious: reading `x-forwarded-host`
+ * here was never a CSRF weakness. A CSRF attack is browser-driven and a
+ * browser cannot set `x-forwarded-host` (or `Origin`); only a direct
+ * non-browser client can, and such a client carries no victim SameSite
+ * cookies to abuse. The primary `Sec-Fetch-Site` path does not reach this
+ * function at all, only the legacy no-`Sec-Fetch-Site` fallback in
+ * `verifyOrigin` does. The value CAN still be attacker-chosen, since a proxy
+ * of the kind above forwards a client-supplied one rather than overwriting
+ * it; see the threat model in `forwarded.js` for what that does reach.
+ *
+ * What changed is the POSTURE, not a hole: the read now honors
+ * `WEBJS_NO_TRUST_PROXY=1` like every other forwarded-header read, so an
+ * operator who sets the flag because their container is directly reachable
+ * gets one answer from the whole package instead of two. Behind a proxy
+ * WITHOUT the flag nothing changes. With the flag set on a genuinely proxied
+ * deploy (a misconfiguration) the fallback compares `Origin` against the raw
+ * `Host`, so a legitimate cross-host request can now be rejected. That is the
+ * flag's intended meaning.
  *
- * Trust note: `x-forwarded-host` is only meaningful behind a proxy that
- * overwrites it. This is NOT a CSRF weakness, because a CSRF attack is
- * browser-driven and a browser cannot set `x-forwarded-host` (or `Origin`);
- * only a direct non-browser client can, and such a client carries no victim
- * SameSite cookies to abuse. The primary `Sec-Fetch-Site` path does not use
- * this at all.
  * @param {Request} req
  */
 export function requestHost(req) {
-  const xfh = req.headers.get('x-forwarded-host');
-  if (xfh) return xfh.split(',')[0].trim().toLowerCase();
+  if (trustProxy()) {
+    const xfh = req.headers.get('x-forwarded-host');
+    if (xfh) return xfh.split(',')[0].trim().toLowerCase();
+  }
   const host = req.headers.get('host');
   if (host) return host.toLowerCase();
   return hostOf(req.url);

package/src/dev-error.js

@@ -91,9 +91,19 @@ export function readCodeFrame(file, line, column, context = 3) {
 /**
  * Build a dev error frame from an error. DEV-ONLY (the caller gates on `dev`).
  *
+ * `opts.url` stamps the frame with the request URL that produced it (#1047).
+ * Only a `render` frame carries one, and the browser overlay uses it to refuse a
+ * frame belonging to a page the tab is not looking at (another tab's crash, a
+ * background render of some other url, a page navigated away from). A frame with
+ * no url renders unconditionally, which is what a `rebuild` / `ts-strip` frame
+ * wants: those describe a still-broken build, not one URL.
+ *
+ * A speculative link prefetch is NOT in that list, and cannot be: `dev.js` drops
+ * the report hook for one, so no frame is ever built for it to refuse.
+ *
  * @param {unknown} error
- * @param {{ kind?: 'render' | 'ts-strip' | 'rebuild', appDir?: string, file?: string, line?: number, column?: number, hint?: string }} [opts]
- * @returns {{ kind: string, message: string, stack: string|null, file: string|null, line: number|null, column: number|null, codeFrame: string|null, hint: string|null }}
+ * @param {{ kind?: 'render' | 'ts-strip' | 'rebuild', appDir?: string, file?: string, line?: number, column?: number, hint?: string, url?: string }} [opts]
+ * @returns {{ kind: string, message: string, stack: string|null, file: string|null, line: number|null, column: number|null, codeFrame: string|null, hint: string|null, url: string|null }}
  */
 export function buildDevErrorFrame(error, opts = {}) {
   const err = error instanceof Error ? error : new Error(String(error));
@@ -125,5 +135,6 @@ export function buildDevErrorFrame(error, opts = {}) {
     column,
     codeFrame,
     hint: opts.hint || null,
+    url: typeof opts.url === 'string' && opts.url ? opts.url : null,
   };
 }

package/src/dev-overlay.js

@@ -9,14 +9,83 @@
  * Security: the overlay is built with `createElement` + `textContent` only,
  * NEVER `innerHTML`, so a hostile error message / file path / code frame is
  * rendered as inert text and can never inject markup or script.
+ *
+ * Scope (#1047): a `render` frame is stamped server-side with the URL that
+ * produced it, and this module is the single gate deciding whether a frame
+ * belongs on the page currently being viewed. Without it, a body-level overlay
+ * outlives every client-router swap (which works strictly inside the keyed
+ * boundary comment ranges), and any render of a page this tab is NOT looking at
+ * raises an overlay over the one it is, in every open tab, since the frame fans
+ * out over the shared SSE channel. (The other half of #1047, a link prefetch
+ * reporting a frame at all, is cut server-side in `dev.js`, not here.)
+ *
+ * The gate cannot be a plain refuse-and-drop, because the SSE frame is pushed
+ * DURING the render, before the navigation response is even sent, so it reaches
+ * the browser while `location` is still the old page. So there are two slots: a
+ * RENDERED frame and a PENDING one the gate refused. A refused frame is held,
+ * and the nav sync re-evaluates it once the URL advances.
+ *
+ * A held frame is only ever rendered for the navigation it actually belongs to,
+ * which is what `__wjNavSeq` is for. A frame that arrives while a navigation is
+ * IN FLIGHT is that navigation's; one that arrived while the tab sat idle is
+ * not, and must never paint on a later visit to that url, because by then the
+ * page may well render fine. An idle-time frame comes from a render this tab
+ * did not navigate for: another tab's page, or a background fetch of some other
+ * url. NOT from a link prefetch, which reports no frame at all. Both look
+ * identical once held, so the seq records which navigation was in flight when
+ * the frame landed, and the sync renders it only if that is still the one
+ * finishing. `webjs:before-cache` is the nav-START signal (the router snapshots
+ * the page it is leaving before it fetches); a navigation that does not emit one
+ * leaves the seq unchanged, which fails toward SHOWING the frame, the same way
+ * the rest of the gate fails open.
  */
 
 /** The single live overlay element, or null. */
 let __wjOverlay = null;
+/** The frame the live overlay was built from, or null. */
+let __wjFrame = null;
+/** The most recent frame the scope gate refused, awaiting a URL that matches. */
+let __wjPending = null;
+/** The navigation that was in flight when `__wjPending` arrived. */
+let __wjPendingSeq = -1;
+/** Bumped at the start of each client-router navigation. */
+let __wjNavSeq = 0;
 
-/** Remove the overlay if one is showing. */
-export function dismissDevOverlay() {
+/** The path the gate compares a frame's url against. */
+function __wjCurrentPath() {
+  return typeof location !== 'undefined' ? location.pathname + location.search : '';
+}
+
+/**
+ * Compare a frame url against a browser path. Encoding-tolerant on purpose: a
+ * mismatch fails CLOSED (no overlay), so a percent-encoding difference on a
+ * dynamic segment would otherwise hide a genuine error.
+ */
+function __wjSamePath(a, b) {
+  if (a === b) return true;
+  try { return decodeURI(a) === decodeURI(b); } catch (_) { return false; }
+}
+
+/** True when `f` is a frame the scope gate applies to (a url-stamped render). */
+function __wjScoped(f) {
+  return !!f && f.kind === 'render' && typeof f.url === 'string' && f.url !== '';
+}
+
+/** Take the overlay off the page. Leaves the pending slot alone. */
+function __wjRemoveOverlay() {
   if (__wjOverlay) { __wjOverlay.remove(); __wjOverlay = null; }
+  __wjFrame = null;
+}
+
+/**
+ * Remove the overlay if one is showing, and forget any pending frame. This is
+ * what the Dismiss button calls, so a frame the user dismissed by hand is never
+ * resurrected by a later navigation.
+ */
+export function dismissDevOverlay() {
+  __wjRemoveOverlay();
+  __wjPending = null;
+  __wjPendingSeq = -1;
 }
 
 /** Append a styled text row to `parent`. */
@@ -30,11 +99,27 @@ function __wjRow(parent, css, text) {
 
 /**
  * Render the dev error overlay for a frame, replacing any prior one.
- * @param {{ kind?: string, message?: string, file?: string|null, line?: number|null, column?: number|null, codeFrame?: string|null, hint?: string|null }} f
+ *
+ * A url-stamped `render` frame for a DIFFERENT path than `currentPath` is not
+ * rendered; it is held in the pending slot for `syncDevOverlayToLocation` to
+ * re-evaluate once the URL advances (#1047). The gate runs BEFORE any removal,
+ * so a refused frame never wipes what is on screen (a live `rebuild` /
+ * `ts-strip` overlay describes a still-broken build and must survive it) and
+ * never paints even briefly. A frame with no `url`, or any other kind, renders
+ * exactly as it always did.
+ *
+ * @param {{ kind?: string, message?: string, file?: string|null, line?: number|null, column?: number|null, codeFrame?: string|null, hint?: string|null, url?: string|null }} f
+ * @param {string} [currentPath] defaults to `location.pathname + location.search`
  */
-export function renderDevOverlay(f) {
-  dismissDevOverlay();
-  if (!f) return;
+export function renderDevOverlay(f, currentPath) {
+  if (!f) { dismissDevOverlay(); return; }
+  const here = currentPath === undefined ? __wjCurrentPath() : currentPath;
+  if (__wjScoped(f) && !__wjSamePath(f.url, here)) {
+    __wjPending = f;
+    __wjPendingSeq = __wjNavSeq;
+    return;
+  }
+  __wjRemoveOverlay();
   const o = document.createElement('div');
   o.setAttribute('data-webjs-error-overlay', '');
   o.style.cssText = 'position:fixed;inset:0;z-index:2147483647;background:rgba(10,10,12,.92);color:#e6e6e6;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;padding:32px;overflow:auto';
@@ -72,4 +157,131 @@ export function renderDevOverlay(f) {
   o.appendChild(card);
   (document.body || document.documentElement).appendChild(o);
   __wjOverlay = o;
+  __wjFrame = f;
+}
+
+/**
+ * Re-evaluate the scope gate against the page now being viewed (#1047). Called
+ * on every client-router navigation, so an overlay the navigation just made
+ * stale comes down, and a frame that arrived before the URL advanced (the usual
+ * ordering, since the SSE frame is pushed during the render that produces the
+ * navigation response) goes up.
+ *
+ * @param {string} [currentPath] defaults to `location.pathname + location.search`
+ */
+export function syncDevOverlayToLocation(currentPath) {
+  const here = currentPath === undefined ? __wjCurrentPath() : currentPath;
+  // The BACKSTOP for an overlay element this module does not own. Any such node
+  // is unremovable and its Dismiss button carries no listener, so it would sit
+  // there forever: a `document.body.replaceChildren` from cached HTML is the way
+  // that happens. The router's OWN back/forward snapshot is already handled
+  // upstream, since `before-cache` detaches the overlay across its `outerHTML`
+  // read, so what is left here is everything else (a snapshot cached before this
+  // client installed its listeners, or any other wholesale body replacement).
+  // Also notice when the node we did own was replaced out from under us: it is
+  // detached, so `.remove()` would no-op and the slot would lie about what is
+  // on screen.
+  if (typeof document !== 'undefined') {
+    const live = __wjOverlay && __wjOverlay.isConnected ? __wjOverlay : null;
+    __wjOverlay = live;
+    document.querySelectorAll('[data-webjs-error-overlay]').forEach((el) => {
+      if (el !== live) el.remove();
+    });
+  }
+  // A live overlay whose page we have navigated away from comes down. An
+  // unscoped overlay (rebuild / ts-strip) is untouched: it describes the build,
+  // not one URL, and only the next successful rebuild clears it.
+  if (__wjScoped(__wjFrame) && !__wjSamePath(__wjFrame.url, here)) __wjRemoveOverlay();
+  // Still the right frame for this page, but its node was swept away by the
+  // restore above: put a REAL one back, with a working Dismiss button.
+  if (__wjFrame && !__wjOverlay) renderDevOverlay(__wjFrame, here);
+  // The pending frame is consumed by this navigation either way. It renders
+  // only if this is BOTH the page it names and the navigation it belongs to;
+  // a frame held from an idle-time render (another tab's page, a background
+  // fetch of some other url) is dropped, because by the time you actually
+  // visit that url the page may render perfectly well, and an overlay over it
+  // would be the very bug this whole gate exists to stop.
+  const p = __wjPending;
+  const seq = __wjPendingSeq;
+  __wjPending = null;
+  __wjPendingSeq = -1;
+  if (p && seq === __wjNavSeq && __wjSamePath(p.url, here)) renderDevOverlay(p, here);
+}
+
+/**
+ * Mark the start of a client-router navigation (#1047), so a frame arriving
+ * from here on is known to belong to it. Exported for the browser test; the
+ * shipping wiring is `installDevOverlayNavSync`.
+ */
+export function markDevOverlayNavStart() {
+  __wjNavSeq++;
+}
+
+/**
+ * Wire the scope gate to the client router's navigation events (#1047), so the
+ * overlay tracks the page actually on screen. Browser-safe and dev-only: the
+ * reload client that calls this is served only in dev.
+ *
+ * Three events, each for a distinct reason:
+ * - `webjs:navigate` on `document`, the applied-navigation signal, dispatched
+ *   after `history.pushState` so `location` is already current.
+ * - `popstate` on `window`, because a back/forward restore served from the
+ *   router's snapshot cache returns before it dispatches `webjs:navigate`.
+ * - `webjs:before-cache` on `document`, which does two things. It is the
+ *   nav-START marker (the router dispatches it from `snapshotCurrent`, at the
+ *   top of every navigation and form submission, before the fetch), the only
+ *   signal separating a frame belonging to the navigation in flight from one
+ *   held since the tab was idle. And it detaches the overlay across the
+ *   snapshot read, re-attaching it a microtask later, so the cached HTML
+ *   carries no copy. What it must NOT do is strip the overlay for good, which
+ *   the event's own contract invites: it fires on EVERY navigation, so that
+ *   would tear a `rebuild` / `ts-strip` overlay off the page the moment you
+ *   clicked any link, while the build was still broken.
+ *
+ * @param {{ document?: any, window?: any, getPath?: () => string }} [opts] injection seam for the browser test
+ * @returns {() => void} an uninstall thunk
+ */
+export function installDevOverlayNavSync(opts) {
+  const o = opts || {};
+  const doc = o.document || (typeof document !== 'undefined' ? document : null);
+  const win = o.window || (typeof window !== 'undefined' ? window : null);
+  const getPath = o.getPath || __wjCurrentPath;
+  const onNav = () => syncDevOverlayToLocation(getPath());
+  const onBeforeCache = () => {
+    markDevOverlayNavStart();
+    // Keep the overlay out of the snapshot the router is about to take. It
+    // reads `outerHTML` SYNCHRONOUSLY right after this event, so detaching here
+    // and re-attaching in a microtask (which runs once that read has returned,
+    // and long before any paint) means the cached HTML never carries a copy,
+    // while the overlay on screen never flickers.
+    //
+    // This is not the strip that used to live here. That one dropped the frame
+    // permanently, so any link click tore down a `rebuild` / `ts-strip`
+    // overlay while the build was still broken; this puts the SAME node back.
+    // The sweep in `syncDevOverlayToLocation` stays as the backstop, because
+    // it cannot cover every ordering on its own: under an opt-in view
+    // transition the router defers the body swap past the sync, so a copy
+    // parsed in afterwards would otherwise sit there undismissable.
+    const el = __wjOverlay;
+    if (!el || !el.isConnected) return;
+    const parent = el.parentNode;
+    el.remove();
+    queueMicrotask(() => {
+      // Only if it is still the live overlay: a frame arriving meanwhile may
+      // have replaced it, or the user may have dismissed it.
+      if (__wjOverlay === el && !el.isConnected && parent) parent.appendChild(el);
+    });
+  };
+  if (doc) {
+    doc.addEventListener('webjs:navigate', onNav);
+    doc.addEventListener('webjs:before-cache', onBeforeCache);
+  }
+  if (win) win.addEventListener('popstate', onNav);
+  return () => {
+    if (doc) {
+      doc.removeEventListener('webjs:navigate', onNav);
+      doc.removeEventListener('webjs:before-cache', onBeforeCache);
+    }
+    if (win) win.removeEventListener('popstate', onNav);
+  };
 }