@webjsdev/server 0.8.67 → 0.8.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.67",
+  "version": "0.8.68",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",

package/src/auth.js

@@ -15,6 +15,10 @@ const enc = new TextEncoder();
 const dec = new TextDecoder();
 const AUTH_COOKIE = 'webjs.auth';
 const STATE_COOKIE = 'webjs.auth.state';
+// Carries the post-sign-in target across the OAuth round trip (#1495). Signed
+// with the auth secret and short-lived (the same 10 minutes as the state
+// cookie), so the callback only ever lands on a path this app chose.
+const REDIRECT_COOKIE = 'webjs.auth.redirect';
 const DEFAULT_MAX_AGE = 30 * 24 * 60 * 60; // 30 days (seconds)
 
 // -- Web Crypto helpers -----------------------------------------------------
@@ -65,6 +69,27 @@ function randomId() {
   return b64url(bytes.buffer);
 }
 
+/**
+ * Accept a post-sign-in target only when it is a same-origin local path: one
+ * leading `/`, the next character neither `/` nor `\` (both make a
+ * protocol-relative URL a browser follows off-site), and no control
+ * characters or whitespace a browser might strip before resolving. Anything
+ * else returns `null` and the caller falls back to its default. A bad value is
+ * DROPPED, never repaired, since a repaired open redirect is still one.
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function safeRedirectPath(value) {
+  if (typeof value !== 'string') return null;
+  if (value.length === 0 || value.length > 2048) return null;
+  if (value[0] !== '/') return null;
+  if (value[1] === '/' || value[1] === '\\') return null;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f\s\\]/.test(value)) return null;
+  return value;
+}
+
 // -- Cookie helpers ---------------------------------------------------------
 
 /** @param {string} header @returns {Record<string,string>} */
@@ -290,11 +315,16 @@ export function createAuth(config) {
         if (ok === false) return new Response(null, { status: 302, headers: { location: pages.error || '/?error=AccessDenied' } });
       }
       const cookie = await writeSession(user);
-      const redirectTo = opts.redirectTo || (data && data.redirectTo) || '/';
+      // `opts.redirectTo` is the app's own server-side choice and is trusted.
+      // `data.redirectTo` usually arrives from a submitted form, so it goes
+      // through the same local-path check the OAuth flow uses (#1495).
+      const redirectTo = opts.redirectTo || safeRedirectPath(data && data.redirectTo) || '/';
       return new Response(null, { status: 302, headers: { location: /** @type {string} */ (redirectTo), 'set-cookie': cookie } });
     }
 
-    if (provider.type === 'oauth') return oauthRedirect(provider, opts);
+    if (provider.type === 'oauth') {
+      return oauthRedirect(provider, { ...opts, redirectTo: opts.redirectTo || (data && data.redirectTo) });
+    }
     return new Response('Unsupported provider type', { status: 400 });
   }
 
@@ -332,9 +362,30 @@ export function createAuth(config) {
     const hdrs = new Headers();
     hdrs.set('location', url.toString());
     hdrs.append('set-cookie', setCookie(STATE_COOKIE, await sign(state, secret), 600_000, secure()));
+    // The post-sign-in target rides in its own signed cookie (#1495). With no
+    // valid target, any leftover cookie from an abandoned earlier attempt is
+    // cleared so it cannot steer this sign-in somewhere stale.
+    const target = safeRedirectPath(opts.redirectTo);
+    hdrs.append('set-cookie', target
+      ? setCookie(REDIRECT_COOKIE, await sign(target, secret), 600_000, secure())
+      : clearCookie(REDIRECT_COOKIE));
     return new Response(null, { status: 302, headers: hdrs });
   }
 
+  /**
+   * Read the signed post-sign-in target the redirect leg stored, re-checking it
+   * as a local path (defence in depth: the signature proves this app wrote it,
+   * the check proves it is still a safe target). Null when absent or invalid.
+   *
+   * @param {Request} req
+   * @returns {Promise<string | null>}
+   */
+  async function readRedirectCookie(req) {
+    const raw = parseCookies(req.headers.get('cookie') || '')[REDIRECT_COOKIE];
+    if (!raw) return null;
+    return safeRedirectPath(await unsign(raw, secret));
+  }
+
   async function oauthCallback(req, provider) {
     const url = new URL(req.url);
     const code = url.searchParams.get('code');
@@ -376,13 +427,20 @@ export function createAuth(config) {
 
     if (cb.signIn) {
       const ok = await cb.signIn({ user, account: { provider: provider.id, accessToken } });
-      if (ok === false) return new Response(null, { status: 302, headers: { location: pages.error || '/?error=AccessDenied' } });
+      if (ok === false) {
+        const denied = new Headers();
+        denied.set('location', pages.error || '/?error=AccessDenied');
+        denied.append('set-cookie', clearCookie(STATE_COOKIE));
+        denied.append('set-cookie', clearCookie(REDIRECT_COOKIE));
+        return new Response(null, { status: 302, headers: denied });
+      }
     }
 
     const hdrs = new Headers();
-    hdrs.set('location', '/');
+    hdrs.set('location', (await readRedirectCookie(req)) || '/');
     hdrs.append('set-cookie', await writeSession(user));
     hdrs.append('set-cookie', clearCookie(STATE_COOKIE));
+    hdrs.append('set-cookie', clearCookie(REDIRECT_COOKIE));
     return new Response(null, { status: 302, headers: hdrs });
   }
 
@@ -401,7 +459,7 @@ export function createAuth(config) {
     if (seg[0] === 'signin' && seg[1]) {
       const p = providers.get(seg[1]);
       if (!p || p.type !== 'oauth') return new Response('Unknown OAuth provider', { status: 404 });
-      return oauthRedirect(p, { req });
+      return oauthRedirect(p, { req, redirectTo: new URL(req.url).searchParams.get('redirectTo') });
     }
     if (seg[0] === 'callback' && seg[1]) {
       const p = providers.get(seg[1]);
@@ -423,28 +481,31 @@ export function createAuth(config) {
     if (seg[0] === 'signin' && seg[1]) {
       const provider = providers.get(seg[1]);
       if (!provider) return new Response('Unknown provider', { status: 404 });
-      if (provider.type === 'credentials') {
-        // Bounded body read (issue #237): the credentials sign-in endpoint is
-        // public and unauthenticated, so cap its body to defend against
-        // memory exhaustion. Credentials are small fixed-shape JSON / form
-        // data, so the JSON / RPC limit applies. An over-limit body is a 413
-        // before any parse, and is never buffered whole (see body-limit.js).
-        const limits = getBodyLimits();
-        const limit = limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
-        let body = {};
-        const ct = req.headers.get('content-type') || '';
-        if (ct.includes('json')) {
-          const { tooLarge, text } = await readTextBounded(req, limit);
-          if (tooLarge) return payloadTooLarge();
-          body = text ? JSON.parse(text) : {};
-        } else if (ct.includes('form')) {
-          const { tooLarge, formData } = await readFormDataBounded(req, limit);
-          if (tooLarge) return payloadTooLarge();
-          for (const [k, v] of formData.entries()) body[k] = v;
-        }
-        return signInFn('credentials', body, { req });
+      // Bounded body read (issue #237): the sign-in endpoint is public and
+      // unauthenticated, so cap its body to defend against memory exhaustion.
+      // Credentials (and an OAuth form's `redirectTo`, #1495) are small
+      // fixed-shape JSON / form data, so the JSON / RPC limit applies. An
+      // over-limit body is a 413 before any parse, and is never buffered
+      // whole (see body-limit.js).
+      const limits = getBodyLimits();
+      const limit = limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
+      /** @type {Record<string, unknown>} */
+      let body = {};
+      const ct = req.headers.get('content-type') || '';
+      if (ct.includes('json')) {
+        const { tooLarge, text } = await readTextBounded(req, limit);
+        if (tooLarge) return payloadTooLarge();
+        body = text ? JSON.parse(text) : {};
+      } else if (ct.includes('form')) {
+        const { tooLarge, formData } = await readFormDataBounded(req, limit);
+        if (tooLarge) return payloadTooLarge();
+        for (const [k, v] of formData.entries()) body[k] = v;
+      }
+      if (provider.type === 'credentials') return signInFn('credentials', body, { req });
+      if (provider.type === 'oauth') {
+        const redirectTo = body.redirectTo ?? new URL(req.url).searchParams.get('redirectTo');
+        return oauthRedirect(provider, { req, redirectTo });
       }
-      if (provider.type === 'oauth') return oauthRedirect(provider, { req });
     }
     if (seg[0] === 'signout') return signOutFn({ req });
     return new Response('Not found', { status: 404 });

package/src/dev/handler.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -16,6 +16,8 @@ import {
   buildActionIndex,
 } from '../actions.js';
 import { registerActionHooks } from '../action-seed.js';
+import { sourceLocationsRequested } from '../dev-source-locations.js';
+import { registerSourceLocationHook } from '../dev-source-locations-hook.js';
 import { readRegenerateRules, isRegenerateOutputPath } from '../dev-regenerate.js';
 import { classifyChangedPath } from '../dev-classify.js';
 import { ensureStripper } from '../ts-strip.js';
@@ -39,6 +41,7 @@ import { setAssetUrlProvider, setFormActionResolver } from '@webjsdev/core';
 import { resolveActionIdentity } from '../form-action-identity.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, resolveAssetUrl } from '../asset-hash.js';
 import { applySecurityHeaders, webRequestIsHttps } from '../headers.js';
+import { parseEmbedOrigins, setEmbedOrigins, allowEmbedFraming } from '../dev-embed.js';
 import {
   applyRedirects,
   applyTrailingSlash,
@@ -213,6 +216,13 @@ export async function createRequestHandler(opts) {
   // analysis pass re-reads it each rebuild so a dev toggle takes effect live.
   setClientRouterEnabled(await readClientRouterEnabled(appDir));
 
+  // Dev embed bridge (#1498): `WEBJS_EMBED_ORIGINS` lets the listed parent
+  // origins frame this dev server and receive the bridge's messages. Read once
+  // here, and only in dev, so a production handler records no origins and
+  // neither injects the script nor relaxes a framing header.
+  const embedOriginsValue = dev ? parseEmbedOrigins(process.env.WEBJS_EMBED_ORIGINS) : [];
+  setEmbedOrigins(embedOriginsValue);
+
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
   // URLs depending on whether the resolved @webjsdev/core install
@@ -278,6 +288,19 @@ export async function createRequestHandler(opts) {
   // on seeding would mean `webjs.seed: false` silently broke every no-JS form.
   await registerActionHooks({ seed: await readSeedEnabled(appDir), dev });
 
+  // Dev source locations (#1499): `WEBJS_SOURCE_LOCATIONS=1` under `webjs dev`
+  // stamps `data-webjs-src="<file>:<line>"` on the element opening tags of the
+  // app's `html` templates. Read once (the SSR load hook is process-global and
+  // cannot be uninstalled), never in prod. The browser half reads
+  // `state.sourceLocations` in serve.js; the SSR half is this load hook, which
+  // must be in place before any app module is imported.
+  const sourceLocations = dev && sourceLocationsRequested();
+  if (sourceLocations) {
+    registerSourceLocationHook(appDir);
+    // Module URLs are realpaths, so a symlinked app dir registers both forms.
+    try { const real = realpathSync(appDir); if (real !== appDir) registerSourceLocationHook(real); } catch { /* keep appDir only */ }
+  }
+
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no
   // network). Resolve it AT BOOT and publish the build id immediately so the
@@ -430,6 +453,9 @@ export async function createRequestHandler(opts) {
     // settings (a multi-tenant embedder, or the differential elision test)
     // must not share it, or the second would serve the first's elided source.
     tsCache: new Map(),
+    // Dev source locations (#1499), fixed for the handler's lifetime, so the
+    // per-handler tsCache above never mixes annotated and plain bytes.
+    sourceLocations,
     // The most recent unresolved dev error frame (#264), or null. Pushed to the
     // SSE channel for the live overlay and replayed to a freshly-connected tab.
     // Dev-only (never populated when !dev); cleared on a successful rebuild.
@@ -996,6 +1022,12 @@ export async function createRequestHandler(opts) {
         }
       }
 
+      // Dev embed bridge (#1498): let the allowed origins frame the page. Runs
+      // after every header source above (defaults, webjs.headers, middleware,
+      // the CSP), so it overrides them all, which is the point: the variable
+      // is the developer saying "this dev server is framed by these origins".
+      if (embedOriginsValue.length) allowEmbedFraming(merged.headers, embedOriginsValue);
+
       // Server HTML cache write (#241): if the SSR marked this response as a
       // cache candidate (an opted-in `revalidate` page), store the FINAL body
       // now, after segment middleware has added any per-user Set-Cookie (which

package/src/dev/serve.js

@@ -28,6 +28,7 @@ import { stripTypeScript } from '../ts-strip.js';
 import { serveDownloadedBundle } from '../vendor.js';
 import { resolveImport } from '../module-graph.js';
 import { elideImportsFromSource } from '../component-elision.js';
+import { annotateSourceLocations, isSourceLocationCandidate, sourceLocationFile } from '../dev-source-locations.js';
 import { basePath } from '../importmap.js';
 import { withBasePath } from '../base-path.js';
 import { versionModuleImports } from '../asset-hash.js';
@@ -322,6 +323,9 @@ export async function handleCore(req, ctx) {
         moduleGraph: state.moduleGraph,
         elidableComponents: state.elidableComponents,
         appDir,
+        // Dev source locations (#1499): annotate the served module's `html`
+        // templates exactly as the SSR load hook annotates the server's copy.
+        sourceLocations: state.sourceLocations === true,
       };
       // A `?v=<hash>` app-module request is content-addressed -> immutable
       // (#243); an un-fingerprinted request keeps the 1h fallback.
@@ -691,7 +695,7 @@ export async function jsModuleResponse(abs, dev, elideOpts, immutable) {
   try { source = await readFile(abs, 'utf8'); }
   catch { return new Response('Not found', { status: 404 }); }
   let code = elideImportsFromSource(
-    source, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
+    annotateServedModule(source, abs, elideOpts), abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
   );
   // Version same-origin relative import specifiers so the URL the browser
   // fetches matches the `?v=`-versioned modulepreload + boot specifier (#369).
@@ -707,6 +711,24 @@ export async function jsModuleResponse(abs, dev, elideOpts, immutable) {
   return new Response(code, { status: 200, headers });
 }
 
+/**
+ * Dev source locations (#1499): stamp `data-webjs-src` on the element opening
+ * tags of a served app module's `html` templates, the same transform the SSR
+ * load hook applies to the server's copy, so the two renders agree. A no-op
+ * unless the handler was built with `WEBJS_SOURCE_LOCATIONS=1` under dev, and
+ * for any module outside the app or under `node_modules`. Runs on the stripped
+ * code, which keeps every line where the source had it.
+ *
+ * @param {string} code
+ * @param {string} abs
+ * @param {{ appDir: string, sourceLocations?: boolean } | undefined} opts
+ * @returns {string}
+ */
+function annotateServedModule(code, abs, opts) {
+  if (!opts || !opts.sourceLocations || !isSourceLocationCandidate(abs, opts.appDir)) return code;
+  return annotateSourceLocations(code, sourceLocationFile(abs, opts.appDir));
+}
+
 /**
  * Strip TypeScript types from `source` via Node's built-in
  * `module.stripTypeScriptTypes`. Position-preserving whitespace
@@ -815,6 +837,7 @@ export async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDe
     throw err;
   }
   if (elideOpts) {
+    code = annotateServedModule(code, abs, elideOpts);
     code = elideImportsFromSource(
       code, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
     );

package/src/dev-embed-client.js

@@ -0,0 +1,331 @@
+/**
+ * The dev embed bridge, BROWSER half (#1498).
+ *
+ * A tool that previews a WebJs app inside an iframe (an AI app builder, a docs
+ * playground, an editor pane) learns what the framed page is doing from this
+ * bridge, and can drive it. It is a browser-safe module with no imports, so it
+ * is both unit-tested in a real browser AND inlined into every dev document by
+ * `embedScriptTag` (`dev-embed.js` reads this file's source, strips the
+ * `export` keyword, and wraps it in a nonce-carrying inline `<script>`). One
+ * source, so the test drives the exact code that ships.
+ *
+ * Dev-only and opt-in: the server emits it only under `webjs dev` with
+ * `WEBJS_EMBED_ORIGINS` set, and never under `webjs start`.
+ *
+ * Wire protocol. Every message the page sends is `{ source: 'webjs-embed',
+ * type, ...fields }`, posted to `window.parent` with an EXACT target origin
+ * from the allow list (never `'*'`), so a parent on any other origin never
+ * receives a byte of it. The host sends `{ source: 'webjs-embed-host', type,
+ * ...fields }`, honoured only when it comes from `window.parent` on an allowed
+ * origin.
+ *
+ * Security: the highlight box is built with `createElement` + inline style
+ * only, never `innerHTML`, and host input is validated (a navigate path must
+ * be a same-origin local path) before it touches the page.
+ */
+
+/**
+ * Install the bridge. Idempotent per window: a second call is a no-op, so an
+ * inlined copy in a re-rendered document cannot double-wrap `fetch`.
+ *
+ * @param {string[]} origins the allowed parent origins (already normalized)
+ * @param {{ win?: Window, parent?: { postMessage: (msg: unknown, origin: string) => void } }} [opts]
+ *   test seams: the window to instrument, and a stand-in for `window.parent`
+ * @returns {{ uninstall: () => void } | null} null when not framed or nothing allowed
+ */
+export function installEmbedBridge(origins, opts) {
+  var win = (opts && opts.win) || window;
+  var parent = (opts && opts.parent) || (win.parent !== win ? win.parent : null);
+  if (!parent || !origins || !origins.length) return null;
+  if (win.__webjsEmbedInstalled) return null;
+  win.__webjsEmbedInstalled = true;
+  var doc = win.document;
+  var cleanups = [];
+  // Once the host has spoken from an allowed origin we know its exact origin
+  // and post only there. Until then, post once per allowed origin: the browser
+  // delivers a message only when the target origin matches the parent's real
+  // origin, so at most one copy lands and a non-listed parent gets nothing.
+  var known = null;
+  var ancestors = win.location && win.location.ancestorOrigins;
+  if (ancestors && ancestors.length && origins.indexOf(ancestors[0]) !== -1) known = ancestors[0];
+
+  function post(type, fields) {
+    var msg = { source: 'webjs-embed', type: type };
+    if (fields) for (var k in fields) msg[k] = fields[k];
+    var targets = known ? [known] : origins;
+    for (var i = 0; i < targets.length; i++) {
+      try { parent.postMessage(msg, targets[i]); } catch (_) { /* a non-cloneable field: drop it */ }
+    }
+  }
+
+  function here() {
+    return win.location.pathname + win.location.search + win.location.hash;
+  }
+
+  // A url as a same-origin path when it is one (so the host sees `/api/x`, not
+  // the dev server's host and port), else the absolute url unchanged.
+  function toPath(u) {
+    try {
+      var url = new URL(String(u), win.location.href);
+      return url.origin === win.location.origin ? url.pathname + url.search : url.href;
+    } catch (_) { return String(u); }
+  }
+
+  function clip(s, n) {
+    s = String(s == null ? '' : s);
+    return s.length > n ? s.slice(0, n) + '...' : s;
+  }
+
+  function describe(v) {
+    if (v instanceof Error) return v.message;
+    if (typeof v === 'string') return v;
+    try { return JSON.stringify(v); } catch (_) { return String(v); }
+  }
+
+  function listen(target, name, fn, capture) {
+    target.addEventListener(name, fn, capture);
+    cleanups.push(function () { target.removeEventListener(name, fn, capture); });
+  }
+
+  // ready: once the document has parsed.
+  function sendReady() { post('ready', { path: here(), title: doc.title }); }
+  if (doc.readyState === 'loading') listen(doc, 'DOMContentLoaded', sendReady);
+  else sendReady();
+
+  // navigate: every client-router navigation, and history traversal.
+  function sendNavigate() { post('navigate', { path: here(), title: doc.title }); }
+  listen(doc, 'webjs:navigate', sendNavigate);
+  listen(win, 'popstate', sendNavigate);
+
+  // console: error + warn, rate limited to 20 per second. What the limit drops
+  // is counted and reported on the next message that gets through, so a loop
+  // that logs forever cannot flood the host and the host still knows.
+  var windowStart = 0;
+  var inWindow = 0;
+  var dropped = 0;
+  var con = win.console;
+  ['error', 'warn'].forEach(function (level) {
+    var orig = con[level];
+    con[level] = function () {
+      var now = Date.now();
+      if (now - windowStart > 1000) { windowStart = now; inWindow = 0; }
+      if (++inWindow <= 20) {
+        var parts = [];
+        for (var i = 0; i < arguments.length; i++) parts.push(describe(arguments[i]));
+        var fields = { level: level, message: clip(parts.join(' '), 2000) };
+        if (dropped) { fields.dropped = dropped; dropped = 0; }
+        post('console', fields);
+      } else {
+        dropped++;
+      }
+      return orig.apply(this, arguments);
+    };
+    cleanups.push(function () { con[level] = orig; });
+  });
+
+  // error: uncaught exceptions and unhandled promise rejections. A resource
+  // load failure also fires `error` on window in the capture phase but is not
+  // an ErrorEvent, so the `message` guard skips it.
+  listen(win, 'error', function (e) {
+    if (!e || typeof e.message !== 'string' || !e.message) return;
+    post('error', {
+      message: clip(e.message, 2000),
+      stack: e.error && e.error.stack ? clip(e.error.stack, 8000) : null,
+      file: e.filename ? toPath(e.filename) : null,
+      line: e.lineno || null,
+      column: e.colno || null,
+    });
+  });
+  listen(win, 'unhandledrejection', function (e) {
+    var r = e && e.reason;
+    post('error', {
+      message: clip('Unhandled rejection: ' + describe(r), 2000),
+      stack: r && r.stack ? clip(r.stack, 8000) : null,
+      file: null,
+      line: null,
+      column: null,
+    });
+  });
+
+  // network: fetch and XHR answering >= 500, or failing outright. The dev
+  // server's own probes are skipped: `/__webjs/version` is polled on purpose
+  // while a restarting server refuses connections, which is not an app fault.
+  function ignored(path) {
+    return path.indexOf('/__webjs/version') !== -1 || path.indexOf('/__webjs/events') !== -1;
+  }
+  function sendNetwork(method, url, status, error) {
+    var path = toPath(url);
+    if (ignored(path)) return;
+    var fields = { method: String(method || 'GET').toUpperCase(), url: path, status: status };
+    if (error) fields.error = clip(error, 500);
+    post('network', fields);
+  }
+  var origFetch = win.fetch;
+  if (typeof origFetch === 'function') {
+    win.fetch = function (input, init) {
+      var method = (init && init.method) || (input && typeof input === 'object' && input.method) || 'GET';
+      var url = input && typeof input === 'object' && 'url' in input ? input.url : input;
+      return origFetch.apply(this, arguments).then(function (res) {
+        if (res && res.status >= 500) sendNetwork(method, url, res.status, null);
+        return res;
+      }, function (err) {
+        // An abort is the caller's own decision (a superseded navigation, a
+        // cancelled prefetch), not a failure.
+        if (!(err && err.name === 'AbortError')) sendNetwork(method, url, 0, describe(err));
+        throw err;
+      });
+    };
+    cleanups.push(function () { win.fetch = origFetch; });
+  }
+  var XHR = win.XMLHttpRequest;
+  if (XHR && XHR.prototype) {
+    var origOpen = XHR.prototype.open;
+    var origSend = XHR.prototype.send;
+    XHR.prototype.open = function (method, url) {
+      this.__webjsEmbed = { method: method, url: url };
+      return origOpen.apply(this, arguments);
+    };
+    XHR.prototype.send = function () {
+      var xhr = this;
+      var info = xhr.__webjsEmbed;
+      if (info) {
+        xhr.addEventListener('load', function () {
+          if (xhr.status >= 500) sendNetwork(info.method, info.url, xhr.status, null);
+        });
+        xhr.addEventListener('error', function () { sendNetwork(info.method, info.url, 0, 'Network error'); });
+      }
+      return origSend.apply(this, arguments);
+    };
+    cleanups.push(function () { XHR.prototype.open = origOpen; XHR.prototype.send = origSend; });
+  }
+
+  // server-error: the dev error overlay went up. `renderDevOverlay` is the one
+  // gate deciding a frame belongs on this page (#1047), and it dispatches
+  // `webjs:dev-overlay` exactly when it renders, so this relays what the
+  // developer would see, no more.
+  listen(doc, 'webjs:dev-overlay', function (e) {
+    var f = (e && e.detail) || {};
+    post('server-error', {
+      kind: f.kind || 'render',
+      message: clip(f.message || '', 2000),
+      file: f.file || null,
+      line: f.line || null,
+      path: here(),
+    });
+  });
+
+  // Inspect mode: hover highlights the element under the pointer and a click
+  // is captured (never reaching the app) and reported as `select`, carrying
+  // the nearest `data-webjs-src` (set by `WEBJS_SOURCE_LOCATIONS=1`, #1499).
+  var box = null;
+  var inspecting = false;
+  // The element the event is really about, through any shadow root.
+  function targetOf(e) {
+    var p = e.composedPath ? e.composedPath() : null;
+    var t = p && p.length ? p[0] : e.target;
+    return t && t.nodeType === 1 ? t : null;
+  }
+  // `closest('[data-webjs-src]')` that also climbs out of shadow roots, and
+  // only takes a `file:line` value: the importmap script carries an unrelated
+  // `data-webjs-src` (the app-source deploy id).
+  function sourceOf(el) {
+    for (var n = el; n; n = n.parentNode || n.host) {
+      if (n.nodeType === 1 && /:\d+$/.test(n.getAttribute('data-webjs-src') || '')) return n;
+    }
+    return null;
+  }
+  function rectOf(el) {
+    var r = el.getBoundingClientRect();
+    return { x: Math.round(r.left), y: Math.round(r.top), width: Math.round(r.width), height: Math.round(r.height) };
+  }
+  function onOver(e) {
+    var el = targetOf(e);
+    if (!el || !box) return;
+    var r = rectOf(sourceOf(el) || el);
+    box.style.transform = 'translate(' + r.x + 'px,' + r.y + 'px)';
+    box.style.width = r.width + 'px';
+    box.style.height = r.height + 'px';
+    box.style.display = 'block';
+  }
+  function swallow(e) {
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.stopImmediatePropagation) e.stopImmediatePropagation();
+  }
+  var hostClick = false;
+  function onClick(e) {
+    // The host's own `navigate` clicks an anchor; that click must pass.
+    if (hostClick) return;
+    var el = targetOf(e);
+    if (!el) return;
+    swallow(e);
+    var src = sourceOf(el);
+    var picked = src || el;
+    post('select', {
+      src: src ? src.getAttribute('data-webjs-src') : null,
+      tag: picked.localName,
+      text: (picked.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
+      rect: rectOf(picked),
+    });
+  }
+  function setInspect(on) {
+    if (on === inspecting) return;
+    inspecting = on;
+    var verbs = ['pointerdown', 'mousedown', 'pointerup', 'mouseup'];
+    if (on) {
+      box = doc.createElement('div');
+      box.setAttribute('data-webjs-embed-highlight', '');
+      box.style.cssText = 'position:fixed;left:0;top:0;z-index:2147483646;pointer-events:none;display:none;' +
+        'box-sizing:border-box;border:2px solid #22d3ee;background:rgba(34,211,238,.12);border-radius:2px';
+      (doc.body || doc.documentElement).appendChild(box);
+      doc.addEventListener('pointerover', onOver, true);
+      doc.addEventListener('click', onClick, true);
+      for (var i = 0; i < verbs.length; i++) doc.addEventListener(verbs[i], swallow, true);
+    } else {
+      if (box) box.remove();
+      box = null;
+      doc.removeEventListener('pointerover', onOver, true);
+      doc.removeEventListener('click', onClick, true);
+      for (var j = 0; j < verbs.length; j++) doc.removeEventListener(verbs[j], swallow, true);
+    }
+  }
+  cleanups.push(function () { setInspect(false); });
+
+  // Host commands. Only from the parent window, only from an allowed origin.
+  listen(win, 'message', function (e) {
+    if (!e || e.source !== parent || origins.indexOf(e.origin) === -1) return;
+    var d = e.data;
+    if (!d || typeof d !== 'object' || d.source !== 'webjs-embed-host') return;
+    known = e.origin;
+    if (d.type === 'reload') {
+      win.location.reload();
+    } else if (d.type === 'navigate') {
+      // A local path only: one leading slash, not `//host` or `/\host`, which
+      // a browser would resolve to another origin.
+      var p = d.path;
+      if (typeof p !== 'string' || p.charAt(0) !== '/' || p.charAt(1) === '/' || p.charAt(1) === '\\') return;
+      // Click a detached-from-layout anchor so the client router takes it as
+      // the soft navigation a user click would be; with no router (an app that
+      // opted out, or a page shipping no component) the browser follows the
+      // link as a normal full navigation. Either way the router's own rules
+      // apply, so nothing here has to know whether it is installed.
+      var a = doc.createElement('a');
+      a.href = p;
+      a.style.display = 'none';
+      (doc.body || doc.documentElement).appendChild(a);
+      hostClick = true;
+      try { a.click(); } finally { hostClick = false; }
+      a.remove();
+    } else if (d.type === 'inspect') {
+      setInspect(d.enabled === true);
+    }
+  });
+
+  return {
+    uninstall: function () {
+      for (var i = cleanups.length - 1; i >= 0; i--) cleanups[i]();
+      cleanups = [];
+      win.__webjsEmbedInstalled = false;
+    },
+  };
+}