@webjsdev/server 0.8.91 → 0.10.0

package/src/dev-hot-classify.js

@@ -0,0 +1,291 @@
+/**
+ * Which dev edits can hot-swap a live component class instead of reloading the
+ * page (#1689). Pure and state-free like `dev-classify.js`, so every reason is
+ * unit-testable without booting a server; the handler feeds it the previous
+ * analysis and the files on disk.
+ *
+ * The browser half (`dev-hot-client.js`) patches the REGISTERED class in place,
+ * because `customElements.define` is once per tag and the native registry keeps
+ * the constructor and the lifecycle callbacks it read at define time. Some edits
+ * cannot be applied that way, and they are refused here, from source, before
+ * any frame is sent:
+ *
+ * - a changed `constructor`: the registry keeps constructing with the OLD one,
+ *   so a new default could never apply to a new element either;
+ * - a changed instance field initializer: it runs per instance at
+ *   construction, so a live element keeps the old value (an arrow handler
+ *   field would keep the old handler);
+ * - any `#private` member: a patched method carries a new private brand the
+ *   live instances lack, a `TypeError` on first use;
+ * - a changed `static shadow`: the render root is chosen once per element.
+ *
+ * The rest of the guards (a changed property shape, `observedAttributes`, an
+ * overridden native lifecycle callback) need the evaluated class and run in the
+ * browser at swap time.
+ */
+
+import { matchClosingBrace, matchClosingParenthesis, redactStringsAndTemplates } from './js-scan.js';
+
+/**
+ * @typedef {{ name: string, ctor: string, fields: string, priv: boolean, shadow: string }} HotClassSignature
+ * @typedef {{ classes: HotClassSignature[], componentOnlyExports: boolean }} HotSignature
+ */
+
+/** Collapse whitespace so a re-indent or a reflow is not read as a change. */
+const squash = (/** @type {string} */ s) => s.replace(/\s+/g, ' ').trim();
+
+/**
+ * Every named class declaration in `masked` (a position-preserving mask) with
+ * the offsets of its body, whatever it extends: a component that extends
+ * another component carries constructor and field state like any other.
+ * @param {string} masked
+ * @returns {Array<{ name: string, start: number, end: number }>}
+ */
+function classBodies(masked) {
+  const out = [];
+  const re = /\bclass\s+([\w$]+)(?:\s*<[^{}();]*?>)?\s*/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    let i = m.index + m[0].length;
+    if (masked.startsWith('extends', i)) {
+      i += 'extends'.length;
+      while (i < masked.length && /\s/.test(masked[i])) i++;
+      const id = /^[\w$.]+/.exec(masked.slice(i));
+      if (id) i += id[0].length;
+      while (i < masked.length && /\s/.test(masked[i])) i++;
+      if (masked[i] === '(') {
+        const close = matchClosingParenthesis(masked, i + 1);
+        if (close === -1) continue;
+        i = close + 1;
+        while (i < masked.length && /\s/.test(masked[i])) i++;
+      }
+    }
+    if (masked[i] !== '{') continue;
+    const end = matchClosingBrace(masked, i + 1);
+    if (end === -1) continue;
+    out.push({ name: m[1], start: i + 1, end });
+    re.lastIndex = end;
+  }
+  return out;
+}
+
+/**
+ * An initializer that ends this way cannot stop at the newline: it has no
+ * value yet, or it ends on an operator (`label =`, `a ||`, `cond ?`).
+ */
+const INIT_CONTINUES_RE = /(?:^|[=?:,.+\-*/%&|^!~<>])\s*$/;
+
+/**
+ * A line starting this way continues the initializer above it, as JavaScript
+ * reads it: no class member starts with an operator, and a `(`, `[` or a
+ * template after a field with no `;` is a call, an index or a tag of it.
+ */
+const LINE_CONTINUES_RE = /^\s*(?:[?:.+\-*/%&|^,=<>([`]|in\b|instanceof\b)/;
+
+/**
+ * The depth-0 members of a class body: the constructor's raw text, every
+ * instance field initializer's raw text, and a `static shadow` initializer.
+ * Reads positions from `maskedBody` (strings, templates and comments blanked)
+ * and text from `rawBody`, which shares its offsets.
+ * @param {string} maskedBody
+ * @param {string} rawBody
+ */
+function members(maskedBody, rawBody) {
+  let ctor = '';
+  let shadow = '';
+  /** @type {string[]} */
+  const fields = [];
+  let depth = 0;
+  let atStart = true;
+  let tpl = false;
+  for (let i = 0; i < maskedBody.length; i++) {
+    const c = maskedBody[i];
+    // A template's body is blanked but keeps its line breaks; skip it whole.
+    if (c === '`') { tpl = !tpl; atStart = false; continue; }
+    if (tpl) continue;
+    if (c === '{' || c === '(' || c === '[') { depth++; atStart = false; continue; }
+    if (c === '}' || c === ')' || c === ']') {
+      depth--;
+      // A method body closing at depth 0 ends the member.
+      if (depth === 0 && c === '}') atStart = true;
+      continue;
+    }
+    if (depth !== 0) continue;
+    if (c === ';' || c === '\n') { atStart = true; continue; }
+    if (!atStart || /\s/.test(c)) continue;
+    atStart = false;
+    const rest = maskedBody.slice(i);
+    const ctorM = /^constructor\s*\(/.exec(rest);
+    if (ctorM) {
+      const open = i + ctorM[0].length;
+      const close = matchClosingParenthesis(maskedBody, open);
+      if (close === -1) continue;
+      const brace = maskedBody.indexOf('{', close);
+      const end = brace === -1 ? -1 : matchClosingBrace(maskedBody, brace + 1);
+      if (end === -1) continue;
+      ctor = squash(rawBody.slice(i, end + 1));
+      i = end;
+      atStart = true;
+      continue;
+    }
+    const staticShadow = /^static\s+shadow\s*=/.exec(rest);
+    const field = staticShadow ? null : /^(?:(?:readonly|declare|accessor)\s+)*(#?[\w$]+)\s*=(?!=)/.exec(rest);
+    const assign = staticShadow || field;
+    if (!assign || /^static\b/.test(rest) && !staticShadow) continue;
+    // The initializer runs to the next depth-0 `;`, or to a line end that
+    // closes it: a Prettier-wrapped `label =\n  'Save'` or a multi-line
+    // ternary carries on, and cutting it at its first newline would read a
+    // changed value as unchanged and swap a class whose live elements keep
+    // the old one. Running long only ever refuses a swap.
+    const from = i + assign[0].length;
+    let j = from;
+    let d = 0;
+    let inTpl = false;
+    for (; j < maskedBody.length; j++) {
+      const ch = maskedBody[j];
+      if (ch === '`') { inTpl = !inTpl; continue; }
+      if (inTpl) continue;
+      if (ch === '{' || ch === '(' || ch === '[') d++;
+      else if (ch === '}' || ch === ')' || ch === ']') { if (d === 0) break; d--; }
+      else if (d === 0 && ch === ';') break;
+      else if (d === 0 && ch === '\n'
+        && !INIT_CONTINUES_RE.test(maskedBody.slice(from, j))
+        && !LINE_CONTINUES_RE.test(maskedBody.slice(j + 1))) break;
+    }
+    const text = squash(rawBody.slice(i, j));
+    if (staticShadow) shadow = squash(rawBody.slice(i + assign[0].length, j));
+    else fields.push(text);
+    i = j - 1;
+  }
+  return { ctor, shadow, fields: fields.join('\n') };
+}
+
+/**
+ * The hot-swap signature of a component module: per named class its
+ * constructor text, its instance field initializers, whether it has a
+ * `#private` member and its `static shadow` initializer, plus whether the
+ * module exports only classes it declares. Two signatures that differ in a
+ * class's `ctor`, `fields` or `shadow`, or in their class names, cannot be
+ * hot-swapped.
+ *
+ * @param {string} erasedSrc the module source with TypeScript types erased
+ * @returns {HotSignature}
+ */
+export function hotSignature(erasedSrc) {
+  const masked = redactStringsAndTemplates(erasedSrc, true);
+  const classes = classBodies(masked).map(({ name, start, end }) => {
+    const body = masked.slice(start, end);
+    const { ctor, shadow, fields } = members(body, erasedSrc.slice(start, end));
+    return { name, ctor, fields, shadow, priv: /(^|[^\w$])#[A-Za-z_$]/.test(body) };
+  });
+  const declared = new Set(classes.map((c) => c.name));
+  let componentOnlyExports = true;
+  for (const m of masked.matchAll(/\bexport\b\s*(default\s+)?([^\n;]*)/g)) {
+    const rest = m[2];
+    if (/^class\b/.test(rest)) continue;
+    const ident = /^([\w$]+)\s*$/.exec(rest);
+    if (m[1] && ident && declared.has(ident[1])) continue;
+    const list = /^\{([^}]*)\}\s*(from\b)?/.exec(rest);
+    if (list && !list[2]) {
+      const names = list[1].split(',').map((s) => s.trim().split(/\s+as\s+/)[0]).filter(Boolean);
+      if (names.every((n) => declared.has(n))) continue;
+    }
+    componentOnlyExports = false;
+    break;
+  }
+  return { classes, componentOnlyExports };
+}
+
+/**
+ * Start reading the hot-swap baseline of each file `baselines` has none for,
+ * WITHOUT waiting: the reads only matter once a later edit arrives, so the
+ * analysis that gates the first request must not wait on N reads and strips
+ * (#1689). Each entry holds the pending read until it lands, and
+ * `findHotBoundaries` awaits whatever `baselineOf` returns. A read that lands
+ * after a newer signature was recorded for its file (an edit's) is dropped.
+ *
+ * @param {Iterable<string>} files
+ * @param {Map<string, HotSignature | Promise<HotSignature | null>>} baselines
+ * @param {(abs: string) => Promise<HotSignature | null>} read never rejects
+ * @returns {void}
+ */
+export function primeHotBaselines(files, baselines, read) {
+  for (const f of files) {
+    if (baselines.has(f)) continue;
+    const pending = read(f).then((sig) => {
+      if (baselines.get(f) === pending) {
+        if (sig) baselines.set(f, sig);
+        else baselines.delete(f);
+      }
+      return sig;
+    });
+    baselines.set(f, pending);
+  }
+}
+
+/**
+ * Walk each changed shipped file UP the shipped importer graph to the component
+ * modules (the hot BOUNDARIES) that would have to be re-imported for the tab to
+ * run the edit. A component module stops the walk; a browser entry that is not
+ * a component (`instrumentation-client`; a page or layout never ships, #1686)
+ * or a module nothing shipped imports means the edit has no boundary and the
+ * page must reload. Every module the walk passes through on
+ * the way must have no module-scope side effect, because re-evaluating it would
+ * run that effect a second time. Each boundary must still be hot-swappable
+ * against the baseline signature the browser holds.
+ *
+ * @param {Iterable<string>} changed absolute paths of the changed shipped files
+ * @param {{
+ *   shipped: Set<string>,
+ *   componentFiles: Set<string>,
+ *   routeFiles: Set<string>,
+ *   importersOf: (abs: string) => Iterable<string>,
+ *   signatureOf: (abs: string) => HotSignature | null | Promise<HotSignature | null>,
+ *   baselineOf: (abs: string) => HotSignature | null | undefined | Promise<HotSignature | null>,
+ *   sideEffectOf: (abs: string) => boolean | Promise<boolean>,
+ *   rel?: (abs: string) => string,
+ * }} ctx
+ * @returns {Promise<{ ok: true, boundaries: string[] } | { ok: false, why: string, by: string }>}
+ */
+export async function findHotBoundaries(changed, ctx) {
+  const rel = ctx.rel || ((/** @type {string} */ f) => f);
+  const fail = (/** @type {string} */ why, /** @type {string} */ f) => ({ ok: /** @type {false} */ (false), why, by: rel(f) });
+  /** @type {Set<string>} */
+  const boundaries = new Set();
+  /** @type {Set<string>} */
+  const seen = new Set();
+  const queue = [...changed];
+  while (queue.length) {
+    const f = /** @type {string} */ (queue.shift());
+    if (seen.has(f)) continue;
+    seen.add(f);
+    // A component module is a boundary before anything else: one the boot
+    // imports from a route module's frontier has no shipped importer, and is
+    // still one.
+    if (ctx.componentFiles.has(f)) { boundaries.add(f); continue; }
+    if (ctx.routeFiles.has(f)) return fail('no-hot-boundary', f);
+    if (await ctx.sideEffectOf(f)) return fail('side-effect-module', f);
+    const importers = [...ctx.importersOf(f)].filter((i) => ctx.shipped.has(i));
+    if (!importers.length) return fail('no-hot-boundary', f);
+    queue.push(...importers);
+  }
+  if (!boundaries.size) return fail('no-hot-boundary', [...changed][0] || '');
+  for (const b of boundaries) {
+    const base = await ctx.baselineOf(b);
+    if (!base) return fail('no-hot-baseline', b);
+    const sig = await ctx.signatureOf(b);
+    if (!sig) return fail('no-hot-baseline', b);
+    if (sig.classes.some((c) => c.priv)) return fail('private-members', b);
+    const names = (/** @type {HotSignature} */ s) => s.classes.map((c) => c.name).sort().join(',');
+    if (names(sig) !== names(base)) return fail('class-set-changed', b);
+    const old = new Map(base.classes.map((c) => [c.name, c]));
+    for (const c of sig.classes) {
+      const o = /** @type {HotClassSignature} */ (old.get(c.name));
+      if (c.ctor !== o.ctor) return fail('constructor-changed', b);
+      if (c.fields !== o.fields) return fail('instance-fields-changed', b);
+      if (c.shadow !== o.shadow) return fail('static-shadow-changed', b);
+    }
+    if (!sig.componentOnlyExports) return fail('non-component-exports', b);
+  }
+  return { ok: true, boundaries: [...boundaries].sort() };
+}

package/src/dev-hot-client.js

@@ -0,0 +1,245 @@
+/**
+ * The dev component hot swap, BROWSER half (#1689). A browser-safe,
+ * import-free module that `reloadClientJs` (`dev/helpers.js`) inlines into
+ * `/__webjs/reload.js` after an `export`-keyword strip, like `dev-styles.js`,
+ * so the browser test drives the exact code that ships. Production never loads
+ * it, so `@webjsdev/core`'s `hot.js` reads find nothing there.
+ *
+ * `installHotClient(globalThis)` publishes `{ strings, replace, applyModules }`
+ * on `globalThis[Symbol.for('webjs.hot')]`, which core reads:
+ *
+ * - `strings(arr, kind)` interns template strings by their text, so the
+ *   re-evaluated module's unchanged templates keep the identity the reconciler
+ *   compares (`prev.strings === tr.strings`) and update in place, keeping
+ *   their DOM (focus, an input's value, a nested component), while a template
+ *   whose text changed rebuilds.
+ * - `replace(tag, Old, New)` is what core's `customElements.define` wrapper
+ *   calls on a second define of a known tag. The native registry keeps the
+ *   class and the lifecycle callbacks it read at define time, so the new
+ *   class's members are copied onto the REGISTERED one, level by level up to
+ *   the first class both chains share, and every live instance re-renders.
+ *   Reactive values live per instance in `__propValues` and instance signals in
+ *   fields, so both survive. A change the native registry would ignore throws
+ *   before anything is patched, and the reload client reloads with the reason.
+ * - `applyModules(urls)` imports the versioned component modules a
+ *   `component` verdict lists, in order, and reports the tags it swapped.
+ *
+ * The reload script runs before the page's boot script (`ssr/head.js`), so the
+ * interner sees every template from the first evaluation on.
+ */
+
+/** Callbacks the native registry captures at define time. */
+const HOT_NATIVE_CALLBACKS = [
+  'connectedCallback', 'disconnectedCallback', 'adoptedCallback', 'attributeChangedCallback',
+  'connectedMoveCallback', 'formAssociatedCallback', 'formResetCallback', 'formDisabledCallback',
+  'formStateRestoreCallback',
+];
+
+/** Statics that are part of a class's identity or compared by a guard, never copied. */
+const HOT_FIXED_STATICS = ['prototype', 'name', 'length', 'properties', 'elementProperties', 'elementStyles', 'observedAttributes', 'finalized'];
+
+/** @param {any} C */
+function hotChain(C) {
+  const out = [];
+  for (let c = C; c && c !== Function.prototype; c = Object.getPrototypeOf(c)) out.push(c);
+  return out;
+}
+
+/** @param {unknown} v */
+function hotText(v) {
+  if (v === undefined) return '';
+  if (typeof v === 'function') return String(v);
+  if (v && typeof v === 'object') {
+    const o = /** @type {Record<string, unknown>} */ (v);
+    return '{' + Object.keys(o).sort().map((k) => k + ':' + hotText(o[k])).join(',') + '}';
+  }
+  try { return JSON.stringify(v); } catch (_) { return String(v); }
+}
+
+/**
+ * The declared reactive property shape of a class, as one comparable string,
+ * plus the names (for the patch to skip their prototype accessors).
+ * @param {any} C
+ */
+function hotShape(C) {
+  /** @type {Record<string, unknown>} */
+  const all = {};
+  for (const c of hotChain(C).reverse()) {
+    if (Object.prototype.hasOwnProperty.call(c, 'properties') && c.properties && typeof c.properties === 'object') Object.assign(all, c.properties);
+  }
+  if (C.elementProperties instanceof Map) for (const [k, v] of C.elementProperties) all[k] = v;
+  const names = Object.keys(all).sort();
+  const text = names.map((name) => {
+    const raw = all[name];
+    const d = /** @type {any} */ (raw && typeof raw === 'object' ? raw : { type: raw });
+    return [name, d.type && d.type.name, hotText(d.attribute), !!d.reflect, !!d.state, !!d.noAccessor,
+      hotText(d.converter), hotText(d.hasChanged), hotText(d.default)].join('|');
+  }).join('\n');
+  return { names, text };
+}
+
+/** @param {any} C */
+function hotObserved(C) {
+  try { return [...(C.observedAttributes || [])].map(String).sort().join(','); } catch (_) { return '?'; }
+}
+
+/** @param {unknown} s @returns {CSSStyleSheet | null} */
+function hotSheet(s) {
+  if (typeof CSSStyleSheet !== 'undefined' && s instanceof CSSStyleSheet) return s;
+  const o = /** @type {any} */ (s);
+  if (o && typeof CSSStyleSheet !== 'undefined' && o.styleSheet instanceof CSSStyleSheet) return o.styleSheet;
+  if (o && typeof o.text === 'string' && typeof CSSStyleSheet !== 'undefined') {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(o.text);
+    return sheet;
+  }
+  return null;
+}
+
+/**
+ * Every element in `root` (and in each open shadow root below it) that is an
+ * instance of `C`, including instances of a subclass.
+ * @param {Document | ShadowRoot | Element} root
+ * @param {Function} C
+ * @param {Element[]} [out]
+ */
+function hotInstances(root, C, out = []) {
+  for (const el of root.querySelectorAll('*')) {
+    if (el instanceof C) out.push(el);
+    if (el.shadowRoot) hotInstances(el.shadowRoot, C, out);
+  }
+  return out;
+}
+
+/**
+ * The reason `New` cannot be patched onto the registered `Old`, or null.
+ * @param {any} Old
+ * @param {any} New
+ * @returns {{ why: string, depth: number }}
+ */
+function hotCheck(Old, New) {
+  const oldChain = hotChain(Old);
+  const newChain = hotChain(New);
+  const depth = newChain.findIndex((c) => oldChain.includes(c));
+  if (depth === -1 || oldChain.indexOf(newChain[depth]) !== depth) return { why: 'class-chain-changed', depth };
+  if (hotShape(Old).text !== hotShape(New).text) return { why: 'reactive-properties-changed', depth };
+  if (hotObserved(Old) !== hotObserved(New)) return { why: 'observed-attributes-changed', depth };
+  if (Old.shadow !== New.shadow) return { why: 'static-shadow-changed', depth };
+  if (Old.formAssociated !== New.formAssociated) return { why: 'form-associated-changed', depth };
+  for (let i = 0; i < depth; i++) {
+    for (const cb of HOT_NATIVE_CALLBACKS) {
+      const o = Object.getOwnPropertyDescriptor(oldChain[i].prototype, cb);
+      const n = Object.getOwnPropertyDescriptor(newChain[i].prototype, cb);
+      if (!!o !== !!n || (o && n && String(o.value) !== String(n.value))) return { why: cb + '-changed', depth };
+    }
+  }
+  return { why: '', depth };
+}
+
+/**
+ * Copy `from`'s own members onto `to`, then drop the ones `from` no longer
+ * has. `skip` names members that stay as they are.
+ * @param {any} to
+ * @param {any} from
+ * @param {(key: string | symbol) => boolean} skip
+ * @param {(key: string | symbol) => boolean} keep members never deleted
+ */
+function hotCopy(to, from, skip, keep) {
+  for (const key of Reflect.ownKeys(from)) {
+    if (skip(key)) continue;
+    const d = Object.getOwnPropertyDescriptor(from, key);
+    if (d) Object.defineProperty(to, key, d);
+  }
+  for (const key of Reflect.ownKeys(to)) {
+    if (skip(key) || keep(key) || Object.prototype.hasOwnProperty.call(from, key)) continue;
+    delete to[key];
+  }
+}
+
+/**
+ * Install the dev hot client on `g` (normally `globalThis`). Idempotent.
+ * @param {any} g
+ */
+export function installHotClient(g) {
+  const KEY = Symbol.for('webjs.hot');
+  if (g[KEY]) return g[KEY];
+  /** @type {WeakMap<object, any>} */
+  const canonical = new WeakMap();
+  /** @type {Map<string, any>} */
+  const byText = new Map();
+  /** @type {string[] | null} */
+  let swapped = null;
+
+  /** @param {any} arr @param {number} kind */
+  function strings(arr, kind) {
+    const hit = canonical.get(arr);
+    if (hit) return hit;
+    const key = kind + '\u0000' + Array.prototype.join.call(arr, '\u0001');
+    let c = byText.get(key);
+    if (!c) byText.set(key, (c = arr));
+    canonical.set(arr, c);
+    return c;
+  }
+
+  /** @param {string} tag @param {any} Old @param {any} New */
+  function replace(tag, Old, New) {
+    const { why, depth } = hotCheck(Old, New);
+    if (why) throw new Error('[webjs] hot swap of <' + tag + '> needs a reload: ' + why);
+    const props = new Set(hotShape(Old).names);
+    const oldChain = hotChain(Old);
+    const newChain = hotChain(New);
+    for (let i = 0; i < depth; i++) {
+      hotCopy(oldChain[i].prototype, newChain[i].prototype,
+        (k) => k === 'constructor' || props.has(/** @type {string} */ (k)) || HOT_NATIVE_CALLBACKS.includes(/** @type {string} */ (k)),
+        () => false);
+      hotCopy(oldChain[i], newChain[i],
+        (k) => HOT_FIXED_STATICS.includes(/** @type {string} */ (k)),
+        // Framework state cached on a class (a symbol, a `_`-prefixed name)
+        // is not the author's, so it is never deleted.
+        (k) => typeof k === 'symbol' || k.startsWith('_'));
+    }
+    // A class that memoizes its finalized styles (Lit's `elementStyles`) keeps
+    // the old ones in a cache; an own value shadows it with the new styles.
+    if (typeof Old.finalizeStyles === 'function') {
+      Object.defineProperty(Old, 'elementStyles', { value: Old.finalizeStyles(Old.styles), configurable: true, writable: true });
+    }
+    const doc = g.document;
+    if (doc) {
+      for (const el of hotInstances(doc, Old)) {
+        const C = /** @type {any} */ (el).constructor;
+        if (el.shadowRoot && C.shadow === true && 'adoptedStyleSheets' in el.shadowRoot) {
+          const styles = typeof C.finalizeStyles === 'function' ? C.elementStyles : C.styles;
+          const list = Array.isArray(styles) ? styles.flat(Infinity) : styles ? [styles] : [];
+          el.shadowRoot.adoptedStyleSheets = list.map(hotSheet).filter(Boolean);
+        }
+        const inst = /** @type {any} */ (el);
+        if (typeof inst.requestUpdate === 'function') inst.requestUpdate();
+      }
+    }
+    if (swapped) swapped.push(tag);
+    return Old;
+  }
+
+  /**
+   * Import the versioned component modules a `component` verdict lists, in
+   * order. A module whose define throws (a guard refused the swap) rejects its
+   * import, which ends the apply with that reason.
+   * @param {string[]} urls
+   * @returns {Promise<{ ok: true, tags: string[] } | { ok: false, why: string }>}
+   */
+  function applyModules(urls) {
+    /** @type {string[]} */
+    const tags = [];
+    swapped = tags;
+    let p = Promise.resolve();
+    for (const u of urls) p = p.then(() => import(u));
+    return p.then(
+      () => { swapped = null; return { ok: /** @type {true} */ (true), tags }; },
+      (e) => { swapped = null; return { ok: /** @type {false} */ (false), why: String((e && e.message) || e) }; },
+    );
+  }
+
+  const api = { strings, replace, applyModules };
+  g[KEY] = api;
+  return api;
+}

package/src/dev-import.js

@@ -22,17 +22,29 @@
  * a plain path, so on Bun it falls back to the file URL (no fresh import; the
  * dev supervisor's restart still picks the edit up).
  *
+ * The content query covers the ENTRY only: a module the entry imports is not
+ * re-imported through here. On Node the dev resolve hook (`dev/esm-hot-hooks.js`,
+ * #1689) versions everything below it, adding `webjs-v=<n>` to an edited module
+ * and its importers on top of this query, which is also what carries a
+ * dependency's edit to an entry whose own bytes did not change. Bun has no
+ * resolve hook, so there the dev source plugins stamp the versions below the
+ * entry (`dev/bun-app-source.js`) and this specifier adds the entry's own
+ * `webjs-v=<n>` after the content query.
+ *
  * Outside dev the specifier is the plain file URL, exactly as before.
  */
 import { pathToFileURL } from 'node:url';
 import { readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
+import { explainImportError } from './foreign-imports.js';
+import { moduleVersion } from './dev/esm-hot-hooks.js';
 
 /**
  * @param {string} file absolute file path
  * @param {boolean} dev whether to cache-bust
- * @param {{ bun?: boolean, version?: (file: string) => string }} [opts] test
- *   seams: the runtime (default: detected) and the content version
+ * @param {{ bun?: boolean, version?: (file: string) => string, moduleVersion?: (file: string) => number }} [opts]
+ *   test seams: the runtime (default: detected), the content version, and the
+ *   Bun module version (#1689)
  * @returns {string}
  */
 export function devImportSpecifier(file, dev, opts = {}) {
@@ -40,7 +52,10 @@ export function devImportSpecifier(file, dev, opts = {}) {
   if (!dev) return url;
   const bun = opts.bun ?? Boolean(typeof process !== 'undefined' && process.versions && process.versions.bun);
   const bust = `?t=${(opts.version ?? contentVersion)(file)}`;
-  if (bun && !/[?#]/.test(file)) return file + bust;
+  if (bun && !/[?#]/.test(file)) {
+    const v = (opts.moduleVersion ?? moduleVersion)(file);
+    return file + bust + (v ? `&webjs-v=${v}` : '');
+  }
   return url + bust;
 }
 
@@ -113,7 +128,9 @@ export async function devImport(file, dev) {
     // promise instead. A rejection is evicted so the next call re-imports (the
     // retry semantic a cold import had), and `clearProdImportCache` drops the
     // whole map on an embedded host's `rebuild()`.
-    const p = import(base);
+    // A load failure caused by a foreign import (`next/*`, `react`, `lit`)
+    // is rewritten to name the WebJs replacement (foreign-imports.js).
+    const p = import(base).catch((e) => { throw explainImportError(e, file); });
     PROD_MODULES.set(file, p);
     p.catch(() => { if (PROD_MODULES.get(file) === p) PROD_MODULES.delete(file); });
     return p;
@@ -123,6 +140,6 @@ export async function devImport(file, dev) {
     return await import(spec);
   } catch (e) {
     RETRY_KEYS.set(base, `${base}-r${++retrySeq}`);
-    throw e;
+    throw explainImportError(e, file);
   }
 }

package/src/dev-overlay.js

@@ -88,6 +88,32 @@ export function dismissDevOverlay() {
   __wjPendingSeq = -1;
 }
 
+/**
+ * Take the overlay down after a component hot swap only when the swap settled
+ * what it describes (#1689). A component swap re-renders nothing on the
+ * server, so nothing would re-raise a frame it wrongly dismissed: a `render`
+ * error on this page, or a `ts-strip` failure in some other module, would
+ * vanish while it still stands. So the overlay goes only for a `rebuild`
+ * frame (the rebuild that produced this swap succeeded) or a frame whose
+ * `file` is one the swap re-imported or was edited for, `paths` holding those
+ * as app-root paths (`/components/x.ts`).
+ *
+ * @param {string[]} paths
+ * @returns {boolean} whether it dismissed
+ */
+export function dismissDevOverlayCoveredBy(paths) {
+  const f = __wjFrame;
+  if (!f) return false;
+  let hit = f.kind === 'rebuild';
+  const file = String(f.file || '').replace(/\\/g, '/');
+  for (let i = 0; !hit && file && i < paths.length; i++) {
+    const p = paths[i];
+    hit = !!p && file.length >= p.length && file.slice(file.length - p.length) === p;
+  }
+  if (hit) dismissDevOverlay();
+  return hit;
+}
+
 /** Append a styled text row to `parent`. */
 function __wjRow(parent, css, text) {
   const d = document.createElement('div');