@webjsdev/server 0.8.67 → 0.8.69

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;
+    },
+  };
+}

package/src/dev-embed.js

@@ -0,0 +1,147 @@
+/**
+ * The dev embed bridge, SERVER half (#1498).
+ *
+ * `webjs dev` with `WEBJS_EMBED_ORIGINS` set (a comma-separated list of parent
+ * origins, e.g. `https://builder.example,http://localhost:8080`), or the app's
+ * `webjs.dev.embedOrigins` list (#1504), makes an app ready to be previewed
+ * inside an iframe on those origins:
+ *
+ *   1. every HTML document gets a small inline script (the browser half,
+ *      `dev-embed-client.js`) that reports page state to the parent and takes
+ *      a few commands from it, carrying the request's CSP nonce like every
+ *      other inline script WebJs emits;
+ *   2. the response stops refusing the frame: `X-Frame-Options` is dropped
+ *      and a CSP `frame-ancestors` directive is widened to the listed origins.
+ *
+ * Unset, both are a no-op and a document is byte-identical to before. Under
+ * `webjs start` (`dev: false`) neither ever happens: the handler records no
+ * origins and `wrapHead` gates on `opts.dev` as well.
+ *
+ * The origins are a module-level switch (mirroring `setClientRouterEnabled`),
+ * set by `createRequestHandler`, so no option has to thread through every
+ * render path that reaches `wrapHead`.
+ */
+import { readFileSync } from 'node:fs';
+import { jsonForScriptTag } from './script-tag-json.js';
+import { escapeAttr } from './ssr/escape.js';
+
+/**
+ * The browser half, read once and inlined: its `export` keyword stripped, and
+ * its comments too, since they are the bulk of the file and every framed page
+ * would carry them. The source has no string or regex containing a comment
+ * opener, which `test/dev/dev-embed.test.js` pins.
+ */
+const CLIENT_SRC = readFileSync(new URL('./dev-embed-client.js', import.meta.url), 'utf8')
+  .replace(/\/\*[\s\S]*?\*\//g, '')
+  .replace(/^\s*\/\/.*$/gm, '')
+  .replace(/^export /gm, '')
+  .replace(/^\s+/gm, '')
+  .trim();
+
+/** @type {string[]} */
+let _origins = [];
+
+/**
+ * Parse `WEBJS_EMBED_ORIGINS`. Each entry must be an http(s) origin; a path or
+ * trailing slash is normalized away (`https://a.dev/` is `https://a.dev`).
+ * Anything else (a bare host, `*`, another scheme) is dropped with a warning,
+ * because a wildcard would hand every page's console and errors to any site
+ * that frames it.
+ *
+ * @param {string | undefined} raw
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {string[]} unique normalized origins, in input order
+ */
+export function parseEmbedOrigins(raw, opts) {
+  if (typeof raw !== 'string' || !raw.trim()) return [];
+  const warn = (opts && opts.warn) || ((m) => console.warn(m));
+  /** @type {string[]} */
+  const out = [];
+  for (const part of raw.split(',')) {
+    const v = part.trim();
+    if (!v) continue;
+    let origin = '';
+    try {
+      const u = new URL(v);
+      if (u.protocol === 'http:' || u.protocol === 'https:') origin = u.origin;
+    } catch { /* not a URL */ }
+    if (!origin) {
+      warn(`[webjs] WEBJS_EMBED_ORIGINS: ignoring "${v}", expected an origin like https://example.com`);
+      continue;
+    }
+    if (!out.includes(origin)) out.push(origin);
+  }
+  return out;
+}
+
+/**
+ * The effective embed origins (#1504): `WEBJS_EMBED_ORIGINS`, when set and
+ * non-empty, replaces the app's `webjs.dev.embedOrigins`; otherwise the config
+ * list applies. Both go through `parseEmbedOrigins`, so a bad entry is dropped
+ * with the same warning wherever it was written.
+ *
+ * @param {string | undefined} envRaw
+ * @param {unknown} configured the app's `webjs.dev.embedOrigins`
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {string[]}
+ */
+export function resolveEmbedOrigins(envRaw, configured, opts) {
+  if (typeof envRaw === 'string' && envRaw.trim()) return parseEmbedOrigins(envRaw, opts);
+  if (!Array.isArray(configured)) return [];
+  return parseEmbedOrigins(configured.filter((o) => typeof o === 'string').join(','), opts);
+}
+
+/**
+ * Record the allowed embed origins for this process. `createRequestHandler`
+ * calls it at construction: the parsed env value in dev, `[]` otherwise.
+ *
+ * @param {string[]} origins
+ */
+export function setEmbedOrigins(origins) {
+  _origins = Array.isArray(origins) ? origins.slice() : [];
+}
+
+/** @returns {string[]} the allowed embed origins (empty = bridge off) */
+export function embedOrigins() {
+  return _origins;
+}
+
+/**
+ * The inline bridge `<script>` for a document, or `''` when the bridge is off.
+ * Includes its own leading newline so the off case adds zero bytes to the
+ * head (the same shape as the client-router opt-out flag beside it).
+ *
+ * @param {{ dev: boolean, nonce?: string }} opts
+ * @returns {string}
+ */
+export function embedScriptTag(opts) {
+  if (!opts.dev || !_origins.length) return '';
+  const n = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
+  return `\n<script${n} data-webjs-embed>(function(){${CLIENT_SRC}\ninstallEmbedBridge(${jsonForScriptTag(_origins)});})();</script>`;
+}
+
+/**
+ * Let the listed origins frame a dev response: drop `X-Frame-Options` (it has
+ * no way to name another origin) and add the origins to a `frame-ancestors`
+ * directive in either CSP header. A policy without `frame-ancestors` already
+ * allows any parent, so it is left alone. Mutates `headers` in place.
+ *
+ * @param {Headers} headers
+ * @param {string[]} origins
+ */
+export function allowEmbedFraming(headers, origins) {
+  if (!origins.length) return;
+  headers.delete('x-frame-options');
+  for (const name of ['content-security-policy', 'content-security-policy-report-only']) {
+    const value = headers.get(name);
+    if (!value) continue;
+    const next = value.split(';').map((d) => {
+      const t = d.trim();
+      if (!/^frame-ancestors(\s|$)/i.test(t)) return d;
+      const sources = t.split(/\s+/).slice(1).filter((s) => s !== "'none'");
+      for (const o of origins) if (!sources.includes(o)) sources.push(o);
+      return ` frame-ancestors ${sources.join(' ')}`;
+    }).join(';').trim();
+    try { headers.set(name, next); } catch { /* keep the original policy */ }
+  }
+}

package/src/dev-overlay.js

@@ -158,6 +158,14 @@ export function renderDevOverlay(f, currentPath) {
   (document.body || document.documentElement).appendChild(o);
   __wjOverlay = o;
   __wjFrame = f;
+  // Announce that an overlay is now on screen, for the dev embed bridge
+  // (#1498), which relays it to a host framing this page. Dispatched here,
+  // after the scope gate above, so a frame held for another url never counts.
+  try {
+    document.dispatchEvent(new CustomEvent('webjs:dev-overlay', {
+      detail: { kind: f.kind || 'render', message: f.message || '', file: f.file || null, line: f.line || null },
+    }));
+  } catch (_) { /* a listener throwing must not break the overlay */ }
 }
 
 /**

package/src/dev-source-locations-hook.js

@@ -0,0 +1,139 @@
+/**
+ * The SSR half of dev source locations (#1499): a module load hook that runs
+ * `annotateSourceLocations` over every app module the SERVER imports, so SSR
+ * output carries the same `data-webjs-src` attributes the browser-served copy
+ * of the module renders (the browser half is in `dev/serve.js`).
+ *
+ * Installed only by the dev handler, only when `WEBJS_SOURCE_LOCATIONS=1`, and
+ * before any app module is imported (ESM caches by URL, so a module loaded
+ * first would stay unannotated until its next dev cache-bust re-import). The
+ * hook is process-global and cannot be uninstalled, so it is scoped to the app
+ * roots registered with it: a module outside every registered root is never
+ * touched.
+ *
+ * Node: `module.registerHooks` with a `load` hook that calls `nextLoad` FIRST
+ * and transforms its result. That keeps it chained with the `'use server'`
+ * seed hook (which it never sees anyway: `*.server.*` modules are excluded) and
+ * keeps Node's own TypeScript stripping, since a `.ts` result keeps its
+ * `module-typescript` format and Node strips it after the hook.
+ *
+ * Bun: `Bun.plugin` `onLoad`. A Bun `onLoad` must return contents for every
+ * path its filter matches, and when two plugins match the same path the first
+ * registered wins, so the filter itself excludes `node_modules` and `*.server.*`
+ * (a lookahead, which Bun's filter honours). The seed plugin therefore keeps
+ * every server module whatever the registration order.
+ */
+import * as nodeModule from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { relative, isAbsolute } from 'node:path';
+import { serverRuntime } from './listener-core.js';
+import {
+  annotateSourceLocations,
+  isSourceLocationCandidate,
+  sourceLocationFile,
+} from './dev-source-locations.js';
+
+/** App roots the hook annotates. */
+const _roots = new Set();
+let _installed = false;
+
+/**
+ * The registered app root containing `abs`, or null.
+ * @param {string} abs
+ * @returns {string | null}
+ */
+function rootFor(abs) {
+  for (const root of _roots) {
+    const rel = relative(root, abs);
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return root;
+  }
+  return null;
+}
+
+/**
+ * Annotate one module's source, or return null when it is not a candidate.
+ * @param {string} abs absolute path, no query
+ * @param {string} src
+ * @returns {string | null}
+ */
+export function transformForSsr(abs, src) {
+  const root = rootFor(abs);
+  if (!root || !isSourceLocationCandidate(abs, root)) return null;
+  return annotateSourceLocations(src, sourceLocationFile(abs, root));
+}
+
+/**
+ * Node `load` hook. Fail-open: any surprise returns `nextLoad`'s result as is.
+ * @param {string} url
+ * @param {object} context
+ * @param {(u: string, c: object) => any} nextLoad
+ */
+function sourceLocationLoadHook(url, context, nextLoad) {
+  const result = nextLoad(url, context);
+  try {
+    if (!url.startsWith('file:') || !result || result.source == null) return result;
+    if (result.format !== 'module' && result.format !== 'module-typescript') return result;
+    const abs = fileURLToPath(url.split('?')[0]);
+    const src = typeof result.source === 'string'
+      ? result.source
+      : Buffer.from(result.source).toString('utf8');
+    const out = transformForSsr(abs, src);
+    if (out == null || out === src) return result;
+    return { ...result, source: out };
+  } catch {
+    return result;
+  }
+}
+
+/**
+ * Escape a string for use inside a RegExp.
+ * @param {string} s
+ */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+}
+
+/**
+ * Register `appDir` with the SSR source-location hook, installing the hook on
+ * the first call. Idempotent per root.
+ *
+ * @param {string} appDir absolute app root
+ * @returns {boolean} whether the hook is (now) installed
+ */
+export function registerSourceLocationHook(appDir) {
+  if (_roots.has(appDir)) return _installed;
+  _roots.add(appDir);
+  if (serverRuntime() === 'bun') {
+    // One plugin per root, each with a filter that can never match a
+    // `node_modules` or `*.server.*` path (see the module comment).
+    const filter = new RegExp(
+      '^' + escapeRe(appDir) + '/(?:(?!node_modules/)(?!.*\\.server\\.).)*\\.m?[jt]s(\\?.*)?$',
+    );
+    /** @type {any} */ (globalThis).Bun.plugin({
+      name: 'webjs-source-locations',
+      setup(build) {
+        build.onLoad({ filter }, async (args) => {
+          const abs = args.path.split('?')[0];
+          const loader = /\.m?ts$/.test(abs) ? 'ts' : 'js';
+          const src = readFileSync(abs, 'utf8');
+          let contents = src;
+          try {
+            contents = transformForSsr(abs, src) ?? src;
+          } catch { /* fail open: the raw module */ }
+          return { contents, loader };
+        });
+      },
+    });
+    _installed = true;
+    return true;
+  }
+  if (_installed) return true;
+  if (typeof nodeModule.registerHooks !== 'function') {
+    console.warn('[webjs] WEBJS_SOURCE_LOCATIONS: this runtime has no module.registerHooks, so SSR output carries no data-webjs-src (client renders still do).');
+    return false;
+  }
+  nodeModule.registerHooks({ load: sourceLocationLoadHook });
+  _installed = true;
+  return true;
+}