@webjsdev/server 0.8.55 → 0.8.57

package/package.json

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

package/src/actions.js

@@ -267,7 +267,7 @@ export function serveServerOnlyStub(relPath) {
     `This file is server-only (a .server.{js,ts} file with no 'use server' directive). ` +
     `Either add 'use server' at the top of the file to expose its exports as RPC, ` +
     `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead. ` +
-    `Docs: https://docs.webjs.dev/docs/server-actions`;
+    `Docs: https://webjs.dev/docs/server-actions`;
   return `// webjs: server-only module stub for ${relPath} (no 'use server' directive)
 throw new Error(${JSON.stringify(msg)});
 `;

package/src/check.js

@@ -119,6 +119,11 @@ export const RULES = [
     description:
       'Flags genuinely browser-only APIs used in a WebComponent constructor, willUpdate, or render() method. The SSR pipeline instantiates the component, runs willUpdate plus controllers\' hostUpdate, reflects properties, and calls render() to produce HTML, on a server element shim that backs the attribute methods but has no real DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an unshimmed HTMLElement member on `this` (attachShadow, shadowRoot, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). The attribute methods (getAttribute/setAttribute/hasAttribute/removeAttribute/toggleAttribute), the event methods (addEventListener/removeEventListener/dispatchEvent), and attachInternals are shim-backed and run server-side, so they are NOT flagged. The flagged APIs belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor (or derive them in willUpdate) only from server-known inputs (attributes, props). Conservative: only the constructor, willUpdate, and render bodies are scanned, and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
   },
+  {
+    name: 'no-shadowed-native-member',
+    description:
+      'Flags a WebComponent class method whose name collides with a native DOM mutation method that WebJs relies on and INSTRUMENTS on every light-DOM host for the slot API (#1021): append, prepend, before, after, replaceWith, replaceChildren, remove, appendChild, insertBefore, removeChild, replaceChild. A method of the same name is SHADOWED at runtime (the instrumented native method wins), so the component method silently never runs, while TypeScript stays green because a zero/one-arg override is assignable to the native signature. Found dogfooding the stream demo (#248): a component named its button handler `append()`, so clicking Append called the slot-append no-op instead of the handler. Rename the handler to a non-native name (appendRow / prependRow / removeItem). The `render` / lifecycle hooks are MEANT to be overridden and are not flagged; only the native DOM mutation members are.',
+  },
   {
     name: 'no-server-import-in-browser-module',
     description:
@@ -659,6 +664,74 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: no-shadowed-native-member ---
+  // A WebComponent method named after a native DOM mutation method WebJs
+  // instruments on every light-DOM host for the slot API (#1021) is SHADOWED at
+  // runtime (the native/instrumented method wins), so the component method never
+  // runs, while TypeScript stays green (a shorter override is assignable). Rename
+  // the handler. The lifecycle hooks are meant to be overridden, so only the DOM
+  // mutation members are reserved.
+  {
+    const NATIVE_MEMBERS = [
+      'append', 'prepend', 'before', 'after', 'replaceWith', 'replaceChildren', 'remove',
+      'appendChild', 'insertBefore', 'removeChild', 'replaceChild',
+    ];
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        // The slot interception installs only on LIGHT-DOM hosts (the shadow
+        // branch keeps the true native methods), so a shadow component's method
+        // is never shadowed. Skip the whole class.
+        if (/static\s+shadow\s*=\s*true/.test(body)) continue;
+        // Brace-depth map over the (already string/comment-masked) class body,
+        // so only TOP-LEVEL class members flag: a same-named object-literal
+        // shorthand or function expression nested inside a method body is a
+        // different object's property and shadows nothing.
+        const depth = new Int32Array(body.length);
+        {
+          let d = 0;
+          for (let i = 0; i < body.length; i++) {
+            if (body[i] === '{') { depth[i] = d; d++; }
+            else if (body[i] === '}') { d--; depth[i] = d; }
+            else depth[i] = d;
+          }
+        }
+        for (const name of NATIVE_MEMBERS) {
+          // Two shadowed-definition shapes, both instance-level: the method /
+          // accessor form (`remove() {`, `get remove() {`), and the class-field
+          // FUNCTION form (`remove = () => {}` / `= function () {}`), which the
+          // connect-time interception install overwrites just the same. A
+          // `static` member lives on the constructor and shadows nothing.
+          const methodRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(?:async\\s+)?(?:get\\s+|set\\s+)?(${name})\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`,
+            'g',
+          );
+          const fieldRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(${name})\\s*=\\s*(?:async\\s*)?(?:function\\b|\\([^)]*\\)\\s*(?::[^=]*)?=>|[\\w$]+\\s*=>)`,
+            'g',
+          );
+          let flagged = false;
+          for (const re of [methodRe, fieldRe]) {
+            let m;
+            while (!flagged && (m = re.exec(body)) !== null) {
+              if (m[1]) continue;                       // static: not shadowed
+              const nameIdx = m.index + m[0].indexOf(m[2]);
+              if (depth[nameIdx] !== 0) continue;       // nested: another object's property
+              flagged = true;
+              violations.push({
+                rule: 'no-shadowed-native-member',
+                file: rel,
+                message: `Component member \`${name}\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
+                fix: `Rename the member to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
+              });
+            }
+            if (flagged) break;
+          }
+        }
+      }
+    }
+  }
+
   // --- Rule: no-redirect-in-api-route ---
   // `redirect()` from `@webjsdev/core` throws a control-flow signal designed
   // for the SSR page renderer. In a `route.ts` API handler it goes uncaught

package/src/dev.js

@@ -2259,21 +2259,40 @@ async function runWithSegmentMiddleware(req, files, terminal, dev) {
 }
 
 /**
- * Load the optional top-level `middleware.js`.
+ * Root-middleware filename candidates, in resolution order.
+ *
+ * Every other routing convention accepts all four extensions (the router
+ * matches on the STEM, so `app/<segment>/middleware.ts` has always worked),
+ * and both the scaffold and the dev supervisor write / watch `middleware.ts`.
+ * This lookup used to be the single literal `middleware.js`, so a root
+ * `middleware.ts` was silently never loaded: no error, no warning, the app
+ * just ran with no global middleware. TypeScript is the documented default
+ * for an app, so that was the common case, and it went unnoticed because the
+ * failure is invisible (a missing middleware looks exactly like an app that
+ * has none). `.ts` is tried first to match the dev supervisor's order.
+ */
+const ROOT_MIDDLEWARE_FILES = ['middleware.ts', 'middleware.js', 'middleware.mts', 'middleware.mjs'];
+
+/**
+ * Load the optional top-level `middleware.{ts,js,mts,mjs}`.
  * @param {string} appDir
  * @param {boolean} dev
  * @param {import('./logger.js').Logger} logger
  */
 async function loadMiddleware(appDir, dev, logger) {
-  const file = join(appDir, 'middleware.js');
-  if (!(await exists(file))) return null;
+  let file = null;
+  for (const name of ROOT_MIDDLEWARE_FILES) {
+    const candidate = join(appDir, name);
+    if (await exists(candidate)) { file = candidate; break; }
+  }
+  if (!file) return null;
   const url = pathToFileURL(file).toString();
   const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
   try {
     const mod = await import(url + bust);
     return typeof mod.default === 'function' ? mod.default : null;
   } catch (e) {
-    logger.error('failed to load middleware.js', { err: String(e) });
+    logger.error('failed to load root middleware', { file, err: String(e) });
     return null;
   }
 }
@@ -2575,7 +2594,7 @@ async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDevError)
           `Replace enum / namespace / parameter-property / legacy-decorator / ` +
           `import = require constructs with their erasable equivalents. ` +
           `Run \`webjs check\` for guidance (no-non-erasable-typescript rule). ` +
-          `Docs: https://docs.webjs.dev/docs/typescript`
+          `Docs: https://webjs.dev/docs/typescript`
         // Prod: terse, no path leak, no Node-message leak (Node's
         // message can include source snippets). Operators get the
         // detail in server logs above.

package/src/forwarded.js

@@ -32,23 +32,178 @@
  * @returns {URL}
  */
 export function urlFromRequest(req) {
-  const trust = process.env.WEBJS_NO_TRUST_PROXY !== '1';
-  let host = null;
-  let proto = null;
-  if (trust) {
-    host = firstHeaderValue(req.headers['x-forwarded-host']);
-    proto = firstHeaderValue(req.headers['x-forwarded-proto']);
+  const { host, proto } = readForwarded((n) => /** @type {any} */ (req.headers)[n]);
+  const rawHost = /** @type {string|undefined} */ (req.headers.host) || '';
+  const u = resolveOrigin(proto || 'http', host, rawHost);
+  // Assign the request target's parts rather than RESOLVING it against `u`.
+  // Resolving is unsafe: a request line may carry `//evil.com/x`, a
+  // scheme-relative reference, so `new URL('//evil.com/x', 'https://real-host')`
+  // resolves to `https://evil.com/x`, handing over the origin AND silently
+  // rewriting the path to `/x` so a different route matches. A request target
+  // is a path, never a full reference, so it is assigned as one.
+  const m = /^([^?#]*)(\?[^#]*)?(#.*)?$/.exec(req.url || '/');
+  u.pathname = (m && m[1]) || '/';
+  u.search = (m && m[2]) || '';
+  u.hash = (m && m[3]) || '';
+  return u;
+}
+
+/**
+ * Build the origin both entry points agree on, as an origin-only URL.
+ *
+ * Sharing this is what keeps the ORIGIN decision identical across the two
+ * shells rather than a coincidence of two similar-looking expressions. The
+ * layering matters: start from a known-good placeholder, apply the raw `Host`,
+ * then let the forwarded host override it. Each assignment goes through
+ * `setHost`, which ignores a value it cannot parse, so a junk header falls back
+ * to the previous layer rather than 500ing the request or collapsing to
+ * localhost.
+ *
+ * @param {string} proto  http / https. `normalizeProto` guarantees it for a
+ *   forwarded value; the callers' fallbacks pass the url's own scheme, which is
+ *   http or https for any request a listener shell can receive.
+ * @param {string | null} forwardedHost
+ * @param {string} rawHost  the `Host` header
+ * @returns {URL} an origin-only URL
+ */
+function resolveOrigin(proto, forwardedHost, rawHost) {
+  const u = new URL(`${proto}://localhost`);
+  if (rawHost) setHost(u, rawHost);
+  if (forwardedHost) setHost(u, forwardedHost);
+  return u;
+}
+
+/**
+ * Assign an authority, clearing any port the previous layer left behind.
+ *
+ * The `host` setter only updates the port when the new value CARRIES one, so
+ * layering `X-Forwarded-Host: docs.webjs.dev` over `Host: container:3000`
+ * otherwise yields `docs.webjs.dev:3000`: the public hostname wearing the
+ * internal port. Clearing first makes each layer a full replacement.
+ *
+ * @param {URL} u
+ * @param {string} value
+ */
+function setHost(u, value) {
+  let probe;
+  try {
+    probe = new URL(`${u.protocol}//${value}`);
+  } catch {
+    // Not a parseable authority (`a b`, `[`, a port over 65535). Leave the
+    // previous layer in place rather than throwing, so a junk header is never a
+    // 500 on the fetch path or a failed WS handshake.
+    return;
   }
-  const finalHost = host || /** @type {string|undefined} */ (req.headers.host) || 'localhost';
-  const finalProto = proto || 'http';
-  return new URL(req.url || '/', `${finalProto}://${finalHost}`);
+  u.hostname = probe.hostname;
+  // Assign the port unconditionally, including the empty string, so a value
+  // carrying no port clears one the previous layer left behind.
+  u.port = probe.port;
+}
+
+/**
+ * Apply the forwarded headers to an ALREADY-PARSED url, for a shell whose
+ * request is a web `Request` (Bun) rather than a node `IncomingMessage`.
+ *
+ * `urlFromRequest` above cannot be reused directly: it reads `req.headers` as a
+ * plain node object, while a web `Request` exposes a `Headers` instance whose
+ * values come from `.get()`. Reusing it against a `Request` silently reads
+ * `undefined` for every header, so it LOOKS wired up while changing nothing.
+ * Both entry points funnel through `readForwarded` (the trust switch, the
+ * allowed schemes, the comma-chain rule) and `resolveOrigin` (the host
+ * layering), so the HEADER and ORIGIN decisions cannot drift. What each shell
+ * RECEIVES still differs: node gets an origin-form request target it treats as
+ * a path, Bun gets a url its own parser already resolved, so an absolute-form
+ * request line routes differently between them. The security-relevant part, the
+ * origin, is decided here for both.
+ *
+ * Returns the SAME URL instance when nothing changes, so the caller can use
+ * identity to skip rebuilding a request on the hot path. That fast path also
+ * requires the url's own authority to already AGREE with the `Host` header:
+ * `Bun.serve` reports an absolute-form request line (`GET http://evil/x`) as
+ * the request's url, so returning early on "no forwarded headers" would let an
+ * unproxied app hand a client full control of `ctx.url.origin`. When they
+ * disagree the origin is rebuilt from `Host` and the client's authority is
+ * discarded. A normal request has `url.host === Host`, so the optimization is
+ * intact for every real request.
+ *
+ * The origin is rebuilt through the shared `resolveOrigin`, and the path parts
+ * are COPIED onto it rather than re-parsed against it. Re-parsing is unsafe:
+ * `url.pathname` for `GET //evil.com/x` is `//evil.com/x`, a scheme-relative
+ * reference, so `new URL('//evil.com/x', 'https://real-host')` resolves to
+ * `https://evil.com/x`. An attacker needed only the `X-Forwarded-Proto` every
+ * TLS-terminating proxy already sets to take over the origin AND silently
+ * change which route matched.
+ *
+ * The host FALLBACK is the `Host` header, not `url.host`, to match
+ * `urlFromRequest` exactly: node builds from the raw header string, so with
+ * `Host: webjs.dev:80` + `X-Forwarded-Proto: https` it judges the `:80` against
+ * https and keeps it. Falling back to the already-normalized `url.host` dropped
+ * it (port 80 is http's default), which made the two shells disagree on the
+ * exact proto-only shape this helper exists for.
+ *
+ * @param {URL} url  the url as the local listener saw it
+ * @param {Headers} headers  the web `Request` headers
+ * @returns {URL} the corrected url, or `url` itself when unchanged
+ */
+export function applyForwarded(url, headers) {
+  const { host, proto } = readForwarded((n) => headers.get(n));
+  const rawHost = headers.get('host') || url.host;
+  if (!host && !proto && url.host === rawHost) return url;
+  // `url.protocol` carries its trailing colon; the forwarded header does not.
+  const origin = resolveOrigin(proto || url.protocol.slice(0, -1), host, rawHost);
+  if (origin.host === url.host && origin.protocol === url.protocol) return url;
+  // Copy the path across verbatim. Never re-parse it against the new origin:
+  // `url.pathname` for `GET //evil.com/x` is `//evil.com/x`, a scheme-relative
+  // reference, so resolving would resolve the authority out of the PATH and
+  // hand an attacker the origin (plus a different matched route) using only the
+  // `X-Forwarded-Proto` every TLS-terminating proxy already sets.
+  origin.pathname = url.pathname;
+  origin.search = url.search;
+  origin.hash = url.hash;
+  return origin;
+}
+
+/**
+ * Read the forwarded host / proto through a header getter, honoring the
+ * `WEBJS_NO_TRUST_PROXY=1` opt-out. The one place the trust decision and the
+ * comma-chain rule live, shared by the node and Bun entry points above.
+ *
+ * @param {(name: string) => string | string[] | undefined | null} getHeader
+ * @returns {{ host: string | null, proto: string | null }}
+ */
+function readForwarded(getHeader) {
+  if (process.env.WEBJS_NO_TRUST_PROXY === '1') return { host: null, proto: null };
+  return {
+    host: firstHeaderValue(getHeader('x-forwarded-host')),
+    proto: normalizeProto(firstHeaderValue(getHeader('x-forwarded-proto'))),
+  };
+}
+
+/**
+ * Accept only `http` / `https` as a forwarded scheme (case-insensitively; the
+ * URL normal form is lowercase, and comparing a raw `HTTPS` against
+ * `url.protocol` otherwise misses the no-op case).
+ *
+ * Anything else is dropped rather than honored. A non-special scheme is the
+ * damaging shape: `X-Forwarded-Proto: javascript` produced
+ * `javascript://host/path`, whose `origin` is the literal string `null`, so
+ * every absolute URL the app derived became `null/...`. A proxy in front of an
+ * HTTP server only ever forwards http or https, so an allowlist costs nothing.
+ *
+ * @param {string | null} p
+ * @returns {string | null}
+ */
+function normalizeProto(p) {
+  if (!p) return null;
+  const v = p.toLowerCase();
+  return v === 'http' || v === 'https' ? v : null;
 }
 
 /**
  * Pick the first comma-separated value from a header that may be a
  * string, an array of strings, or undefined.
  *
- * @param {string | string[] | undefined} h
+ * @param {string | string[] | undefined | null} h
  * @returns {string | null}
  */
 function firstHeaderValue(h) {

package/src/listener-bun.js

@@ -45,7 +45,8 @@ import { EventEmitter } from 'node:events';
 import { Readable, pipeline } from 'node:stream';
 import { matchApi } from './router.js';
 import { registerClient } from './broadcast.js';
-import { setTrustedRemoteIp } from './rate-limit.js';
+import { setTrustedRemoteIp, propagateTrustedRemoteIp } from './rate-limit.js';
+import { applyForwarded } from './forwarded.js';
 import {
   isCompressible,
   isEventsPath,
@@ -104,7 +105,7 @@ export function startBunListener(ctx) {
         // head-start during SSR compute, not the preloads themselves.
 
         stampRemoteIp(req, srv);
-        const resp = await app.handle(req);
+        const resp = await app.handle(forwardedRequest(req, url));
         return compress ? await maybeCompress(resp, req) : resp;
       } catch (e) {
         logger.error('request pipeline threw', { err: e instanceof Error ? e.stack : String(e) });
@@ -237,7 +238,11 @@ async function bunUpgrade(req, srv, ctx) {
   }
 
   const wrapper = new BunWsAdapter();
-  const handlerReq = upgradeRequest(req, url);
+  // Behind a proxy the handshake arrives as plain http on the internal hop, so
+  // the handler request carries the ORIGINAL scheme + host too (the node WS path
+  // gets this from `urlFromRequest` in `buildRequestFromUpgrade`). Routing above
+  // keyed on `url.pathname`, which the origin swap leaves untouched.
+  const handlerReq = upgradeRequest(req, applyForwarded(url, req.headers));
   // Stamp the framework-trusted socket IP on the handler request so a `WS`
   // handler's `clientIp(req)` returns the real peer, not a spoofed inbound
   // `x-webjs-remote-ip` (#778). `srv.requestIP` must be queried with Bun's
@@ -317,6 +322,78 @@ function bunSseResponse(req, hub, app) {
   });
 }
 
+/**
+ * Rebuild the request behind a TLS-terminating reverse proxy so `req.url`
+ * carries the ORIGINAL scheme + host (`X-Forwarded-Proto` / `X-Forwarded-Host`).
+ *
+ * Why the request itself and not just a threaded url: everything downstream
+ * (the framework's own `new URL(req.url)` reads AND a user's `route.ts` doing
+ * `new URL(req.url).origin`) derives from `req.url`, so correcting only a side
+ * channel would fix the framework's absolute URLs and leave app code broken.
+ * The node shell gets this for free, since `toWebRequest` builds its `Request`
+ * FROM the already-corrected `urlFromRequest(req)`; Bun hands us a `Request`
+ * whose url reflects the internal `http://container` view, so the correction
+ * has to be applied here for the two shells to agree.
+ *
+ * Hot path: `applyForwarded` returns the SAME url instance when nothing
+ * changes, so an app with no proxy in front (local dev, direct exposure,
+ * `WEBJS_NO_TRUST_PROXY=1`) does ZERO extra work and keeps the #756 no-clone
+ * behaviour. Behind a proxy this costs one `Request` construction per request,
+ * which is still strictly less than the node shell, which constructs one
+ * unconditionally. The trusted IP is carried across the rebuild the same way
+ * the base-path rewrite in `dev.js` does it (#773), so `clientIp` stays
+ * authoritative and the inbound spoofable header is never consulted.
+ *
+ * @param {Request} req
+ * @param {URL} url  the url as `Bun.serve` saw it
+ * @returns {Request} `req` itself when unchanged, else the corrected request
+ */
+function forwardedRequest(req, url) {
+  const fwd = applyForwarded(url, req.headers);
+  if (fwd === url) return req;
+  // SECURITY (#778): drop any client-supplied `x-webjs-remote-ip` before it
+  // rides onto the rebuilt request. `trustedRemoteIp` reads the WeakMap first,
+  // so the header cannot win today, but every other rebuild site strips it
+  // (`dev.js`'s base-path rewrite, `upgradeRequest` below) and leaving it
+  // attached would re-arm the spoof the moment any later code path rebuilds
+  // this request without carrying the WeakMap across.
+  const headers = new Headers(req.headers);
+  headers.delete('x-webjs-remote-ip');
+  const next = new Request(fwd, { ...requestInitFrom(req), headers });
+  propagateTrustedRemoteIp(req, next);
+  return next;
+}
+
+/**
+ * The parts of a `Request` that must survive the rebuild, spelled out because
+ * the header strip above needs its own `Headers` and passing the `Request` as
+ * the init would ignore them.
+ *
+ * `duplex: 'half'` is required by the spec whenever a body is present, and
+ * `mode: 'navigate'` cannot be passed to the constructor, so it is dropped.
+ *
+ * @param {Request} req
+ */
+function requestInitFrom(req) {
+  /** @type {any} */
+  const init = {
+    method: req.method,
+    signal: req.signal,
+    credentials: req.credentials,
+    cache: req.cache,
+    redirect: req.redirect,
+    referrer: req.referrer,
+    referrerPolicy: req.referrerPolicy,
+    integrity: req.integrity,
+  };
+  if (req.mode && req.mode !== 'navigate') init.mode = req.mode;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    init.body = req.body;
+    init.duplex = 'half';
+  }
+  return init;
+}
+
 /**
  * Stamp the framework-trusted remote IP from Bun's `server.requestIP`,
  * out-of-band via `setTrustedRemoteIp` (#756). The previous implementation

package/src/ssr.js

@@ -1124,18 +1124,27 @@ function wrapInDocument(body, opts) {
  */
 function collectHoistedHeadTags(bodyHtml) {
   const tags = [];
-  // <script>…</script> and <style>…</style> are paired; <link …> is void.
-  // A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so a
-  // comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
+  // <script>…</script> and <style>…</style> are paired; <link …> and <meta …>
+  // are void. A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so
+  // a comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
   // between a favicon <link> and the stylesheet <link>) does not terminate
   // the leading run and strand the stylesheet in <body>, which caused FOUC
   // because a <link rel="stylesheet"> in <body> is not reliably
-  // render-blocking (#406). The `(?!/?wj:)` guard exempts client-router
-  // markers (<!--wj:children:…-->, <!--/wj:children-->) so a layout that
-  // renders children directly after its head tags still terminates the run
-  // there rather than swallowing the nesting marker.
+  // render-blocking (#406). A <meta …> is treated the same way for the same
+  // reason: a <meta name="color-scheme"> between the theme <script> and the
+  // stylesheet <link> would otherwise terminate the run and strand the
+  // stylesheet AND a <link rel="icon"> in <body> (a favicon in <body> is
+  // ignored by browsers, so the icon silently never renders). The `(?!/?wj:)`
+  // guard exempts client-router markers (<!--wj:children:…-->,
+  // <!--/wj:children-->) so a layout that renders children directly after its
+  // head tags still terminates the run there rather than swallowing the marker.
+  // The void-tag matchers are QUOTE-AWARE ((?:[^>"']|"[^"]*"|'[^']*')*): a `>`
+  // inside a quoted attribute value (a description meta like
+  // content="Guides > API") must not terminate the tag early, which would hoist
+  // a truncated tag, leak the remainder as visible body text, and strand the
+  // stylesheet (the #406 FOUC this hoist exists to prevent).
   const re =
-    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b[^>]*>)/i;
+    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b(?:[^>"']|"[^"]*"|'[^']*')*>|<meta\b(?:[^>"']|"[^"]*"|'[^']*')*>)/i;
   let remaining = bodyHtml;
   // `body` only advances to just-past the LAST hoisted head tag. Comments
   // are scanned through (so they don't terminate the run) but a comment that