@webjsdev/server 0.9.0 → 0.10.0

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');

package/src/dev-ready-probe.js

@@ -0,0 +1,69 @@
+/**
+ * The dev reload client's readiness probe, the BROWSER half (#893, #1689).
+ * Browser-safe and import-free: `reloadClientJs` (`dev/helpers.js`) inlines it
+ * after an `export` strip, so the unit test drives the exact code that ships.
+ *
+ * Every reload signal waits for `/__webjs/version` to answer before it is
+ * applied, so a tab never reloads INTO a server that is still restarting and
+ * paints a half-rendered page. The probe used to give up after 100 tries (about
+ * 10 seconds) and reload anyway, which turned any restart slower than that (a
+ * cold `dev.before` step, a laptop waking up) into the browser's own error page
+ * and a dead tab. It now waits for as long as it takes, Next's posture: 100ms
+ * between tries for the first 2 seconds, then 1s for 10 seconds, then every 5s,
+ * and it says once that it is waiting. It never reloads by itself.
+ *
+ * One loop runs at a time. A reload signal that arrives while a probe is
+ * already waiting joins it instead of starting a second one, so a burst of
+ * edits during a restart does not multiply the requests.
+ */
+
+/**
+ * @param {(url: string, init: object) => Promise<{ ok: boolean }>} fetchFn
+ * @param {string} url  the readiness endpoint
+ * @param {{ setTimeout: (fn: () => void, ms: number) => unknown }} [timers]
+ * @param {(msg: string) => void} [log]
+ * @returns {(cb: () => void) => void} `whenReady(cb)` runs `cb` once the server answers
+ */
+export function createReadyProbe(fetchFn, url, timers, log) {
+  const t = timers || { setTimeout: function (fn, ms) { return setTimeout(fn, ms); } };
+  const say = log || function (msg) { console.info(msg); };
+  /** @type {Array<() => void> | null} */
+  let waiting = null;
+
+  /** @param {number} failures */
+  function delayAfter(failures) {
+    if (failures <= 20) return 100;
+    if (failures <= 30) return 1000;
+    return 5000;
+  }
+
+  function settle() {
+    const cbs = waiting || [];
+    waiting = null;
+    for (const cb of cbs) {
+      try { cb(); } catch (e) { console.error('[webjs] dev reload handler threw', e); }
+    }
+  }
+
+  /** @param {number} failures */
+  function attempt(failures) {
+    let p;
+    try { p = fetchFn(url, { cache: 'no-store' }); } catch (_) { p = Promise.reject(_); }
+    Promise.resolve(p).then(function (r) {
+      if (r && r.ok) settle(); else again(failures + 1);
+    }, function () { again(failures + 1); });
+  }
+
+  /** @param {number} failures */
+  function again(failures) {
+    // Once per loop, when the fast tries run out (about 2 seconds in).
+    if (failures === 20) say('[webjs] waiting for the dev server...');
+    t.setTimeout(function () { attempt(failures); }, delayAfter(failures));
+  }
+
+  return function whenReady(cb) {
+    if (waiting) { waiting.push(cb); return; }
+    waiting = [cb];
+    attempt(0);
+  };
+}

package/src/dev-regenerate.js

@@ -63,8 +63,8 @@ export const REGENERATE_MANIFEST = '.webjs/regenerate.json';
  * Read + normalize the `webjs.dev.regenerate` rules from an app's
  * `package.json`. Defensive: a missing/malformed block yields `[]` (a plain app
  * runs unchanged). Each rule's `output` is normalized to an appDir-relative path
- * with no leading slash so it matches a served `/public/...` path after the
- * slash is stripped.
+ * with no leading slash (`public/tailwind.css`), the file a request for the
+ * root url `/tailwind.css` maps to under `public/`.
  *
  * @param {string} appDir
  * @param {(p: string) => Promise<string>} [read] injectable reader for tests

package/src/dev-reload-hold.js

@@ -6,9 +6,9 @@
  * intermediate save, and releases it when the build is done. The embed bridge
  * (`dev-embed-client.js`) owns the switch, the `__webjsEmbedHold` page global,
  * set from the host's `{ type: 'hold', enabled }` command. The reload client
- * routes every reload signal through this module: while held it keeps only the
- * STRONGEST verdict seen, and on release it applies that one reload, or nothing
- * when nothing changed.
+ * routes every reload signal through this module: while held it merges every
+ * verdict it sees, and on release it applies that one reload, or nothing when
+ * nothing changed.
  *
  * Import-free and inlined verbatim (`export` stripped) into the served reload
  * client by `reloadClientJs` in `dev/helpers.js`, the same shared-source rule as
@@ -19,42 +19,71 @@
  * Verdict strength, strongest first. Restated rather than imported from
  * `dev-reload-worker.js` because this file is inlined on its own.
  */
-var HOLD_STRENGTH = ['reload', 'shell', 'page'];
+var HOLD_STRENGTH = ['reload', 'shell', 'page', 'component', 'css'];
 
 /**
- * The stronger of two verdicts. Anything that is not a known verdict is a full
- * `reload`, the fail-safe every other reload path uses.
+ * Read one held signal into the verdict object shape. A bare string (a relay
+ * older than #1689 posts the name alone) becomes `{ v }`, and anything that
+ * is not a known verdict is a full `reload`, the fail-safe every other reload
+ * path uses.
  *
- * @param {string | null} a  the verdict held so far (null = none)
- * @param {unknown} b  the incoming verdict
- * @returns {string}
+ * @param {unknown} raw
+ * @returns {{ v: string, by: string, why: string, modules: string[], css: boolean }}
  */
-export function strongerHeldVerdict(a, b) {
-  var ib = HOLD_STRENGTH.indexOf(/** @type {string} */ (b));
-  if (ib === -1) ib = 0;
-  if (a === null) return HOLD_STRENGTH[ib];
-  var ia = HOLD_STRENGTH.indexOf(a);
-  if (ia === -1) ia = 0;
-  return HOLD_STRENGTH[Math.min(ia, ib)];
+function readHeldVerdict(raw) {
+  var o = typeof raw === 'string' ? { v: raw } : raw;
+  if (!o || typeof o !== 'object' || HOLD_STRENGTH.indexOf(/** @type {any} */ (o).v) === -1) {
+    return { v: 'reload', by: '', why: 'unreadable-frame', modules: [], css: false };
+  }
+  var a = /** @type {any} */ (o);
+  return {
+    v: a.v,
+    by: typeof a.by === 'string' ? a.by : '',
+    why: typeof a.why === 'string' ? a.why : '',
+    modules: Array.isArray(a.modules) ? a.modules.slice() : [],
+    css: a.css === true,
+  };
+}
+
+/**
+ * Merge an incoming verdict into the one held so far: the stronger `v` wins
+ * with its `by` / `why` (the held one on a tie), `modules` unions and `css`
+ * ORs, the same rule as the server's `mergeVerdicts`.
+ *
+ * @param {{ v: string, by: string, why: string, modules: string[], css: boolean } | null} a  held so far (null = none)
+ * @param {unknown} b  the incoming verdict, an object or a legacy string
+ * @returns {{ v: string, by: string, why: string, modules: string[], css: boolean }}
+ */
+export function mergeHeldVerdict(a, b) {
+  var next = readHeldVerdict(b);
+  if (a === null) return next;
+  var top = HOLD_STRENGTH.indexOf(a.v) <= HOLD_STRENGTH.indexOf(next.v) ? a : next;
+  var modules = a.modules.slice();
+  for (var i = 0; i < next.modules.length; i++) {
+    if (modules.indexOf(next.modules[i]) === -1) modules.push(next.modules[i]);
+  }
+  modules.sort();
+  return { v: top.v, by: top.by, why: top.why, modules: modules, css: a.css || next.css };
 }
 
 /**
  * Build the hold gate for one page.
  *
- * @param {(verdict: string) => void} apply  applies a reload (the client's own apply)
+ * @param {(verdict: { v: string, by: string, why: string, modules: string[], css: boolean }) => void} apply
+ *   applies a reload (the client's own apply)
  * @param {() => boolean} isHeld  whether the host currently holds reloads
- * @returns {{ offer: (verdict: unknown) => boolean, release: () => void, pending: () => string | null }}
+ * @returns {{ offer: (verdict: unknown) => boolean, release: () => void, pending: () => ({ v: string, by: string, why: string, modules: string[], css: boolean } | null) }}
  *   `offer` returns true when it kept the signal (held), false when the caller
  *   should apply it now; `release` applies the one pending reload once the hold
  *   is off.
  */
 export function createReloadHold(apply, isHeld) {
-  /** @type {string | null} */
+  /** @type {{ v: string, by: string, why: string, modules: string[], css: boolean } | null} */
   var held = null;
   return {
     offer: function (verdict) {
       if (!isHeld()) return false;
-      held = strongerHeldVerdict(held, verdict);
+      held = mergeHeldVerdict(held, verdict);
       return true;
     },
     release: function () {

package/src/dev-reload-reason.js

@@ -0,0 +1,61 @@
+/**
+ * Why the dev server reloaded the page, printed AFTER the reload (#1689), the
+ * BROWSER half. Browser-safe and import-free: `reloadClientJs` (`dev/helpers.js`)
+ * inlines it after an `export` strip, so the unit test drives the exact code
+ * that ships.
+ *
+ * A reload replaces the document, and with it the console of the page that
+ * decided to reload, so a reason logged before `location.reload()` is gone by
+ * the time anyone looks (Next prints its `REACT_REFRESH_FULL_RELOAD` reason for
+ * the same reason). `reloadWithReason` stores `{ why, by }` in
+ * `sessionStorage`, which survives a same-tab reload, and the reloaded page's
+ * client prints it once with `printPendingReason`:
+ * `[webjs] full reload: <why> (<by>)`. Where storage is unavailable (a
+ * sandboxed frame, storage disabled) the reason is logged before the reload
+ * instead, which is the best that can be done.
+ */
+
+const RELOAD_REASON_KEY = 'webjs:dev-reload-reason';
+
+/**
+ * @param {{ why?: string, by?: string }} r
+ * @returns {string}
+ */
+function reloadReasonLine(r) {
+  return '[webjs] full reload: ' + (r.why || 'reload') + (r.by ? ' (' + r.by + ')' : '');
+}
+
+/**
+ * Remember why, then reload.
+ * @param {{ v?: string, why?: string, by?: string }} verdict
+ * @param {{ reload: () => void }} loc
+ * @param {Storage | null | undefined} store
+ * @param {(msg: string) => void} log
+ */
+export function reloadWithReason(verdict, loc, store, log) {
+  const r = { why: (verdict && (verdict.why || verdict.v)) || 'reload', by: (verdict && verdict.by) || '' };
+  let kept = false;
+  try {
+    if (store) { store.setItem(RELOAD_REASON_KEY, JSON.stringify(r)); kept = true; }
+  } catch (_) { /* storage disabled or full: log it now instead */ }
+  if (!kept) log(reloadReasonLine(r));
+  loc.reload();
+}
+
+/**
+ * Print the reason a previous page stored before it reloaded, once.
+ * @param {Storage | null | undefined} store
+ * @param {(msg: string) => void} log
+ */
+export function printPendingReason(store, log) {
+  let raw = null;
+  try {
+    if (!store) return;
+    raw = store.getItem(RELOAD_REASON_KEY);
+    if (raw !== null) store.removeItem(RELOAD_REASON_KEY);
+  } catch (_) { return; }
+  if (!raw) return;
+  let r;
+  try { r = JSON.parse(raw); } catch (_) { return; }
+  if (r && typeof r === 'object') log(reloadReasonLine(r));
+}