@webjsdev/server 0.9.0 → 0.10.0

package/src/dev-classify.js

@@ -18,9 +18,8 @@
  * heuristic ("anything under `app/**` named `page.ts` can morph") is wrong in
  * both directions and neither failure is exotic:
  *
- * - A page that imports a client-effecting non-component util SHIPS WHOLE (the
- *   import-only rule in `component-elision.js`, #605 / #963). Editing it changes
- *   browser-bound JS, so it must reload despite being a page.
+ * - A page never ships (#1686), but a helper it imports may also be imported by
+ *   a component, which makes it browser-bound JS: editing it must reload.
  * - A helper under `modules/<feature>/utils/` imported by both a page and a
  *   component is a component edit by reachability, and its path says nothing.
  *
@@ -29,9 +28,9 @@
  */
 
 /**
- * The three verdicts, STRONGEST FIRST. The index in this array IS the strength
- * order, which is what `strongerVerdict` compares and what lets a batch of
- * changes collapse to the strongest verdict it contains rather than the last.
+ * The verdicts, STRONGEST FIRST. The index in this array IS the strength order,
+ * which is what `mergeVerdicts` compares and what lets a batch of changes
+ * collapse to the strongest verdict it contains rather than the last.
  *
  * - `reload`: a component module, anything transitively reaching one, or any
  *   path the server cannot place. The browser does `location.reload()`.
@@ -40,21 +39,40 @@
  * - `page`: a page module and nothing else. The browser re-renders the current
  *   URL and morphs the deepest shared boundary, preserving scroll AND the
  *   hydrated state of components outside the changed region.
+ * - `component`: browser modules the tab re-imports and patches onto the live
+ *   component classes (#1689), listed in the verdict's `modules`. A tab with no
+ *   hot-swap support applies it as a full reload.
+ * - `css`: a stylesheet and nothing else (#1689). The tab re-requests its
+ *   stylesheets and swaps them in. A tab with no support reloads.
  *
- * @type {readonly ['reload', 'shell', 'page']}
+ * @type {readonly ['reload', 'shell', 'page', 'component', 'css']}
  */
-export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page']);
+export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page', 'component', 'css']);
 
 /**
- * @typedef {{ v: 'page' | 'shell' | 'reload', by: string, why: string }} ReloadVerdict
+ * A live-reload verdict. `modules` lists the versioned browser URLs a
+ * `component` verdict asks the tab to re-import, and `css` says a stylesheet
+ * changed too, so the tab refreshes its sheets on top of whatever else it does.
+ *
+ * @typedef {{
+ *   v: 'reload' | 'shell' | 'page' | 'component' | 'css',
+ *   by: string,
+ *   why: string,
+ *   modules?: string[],
+ *   css?: true,
+ * }} ReloadVerdict
  */
 
 /**
- * The stronger of two verdicts, treating `null` / `undefined` as weakest and an
- * unrecognised one as `reload` (fail safe, never fail open).
+ * Merge two verdicts into the one a batch applies, treating `null` /
+ * `undefined` as nothing and an unrecognised name as `reload` (fail safe, never
+ * fail open). `v`, `by` and `why` come from the stronger verdict (the first on
+ * a tie). `modules` is the sorted union of both and `css` is set when either
+ * sets it, because a weaker change in the batch still needs its own work done
+ * alongside the stronger one.
  *
  * Used twice for the same reason. The watcher can see several files change
- * inside one 80ms debounce window, and the browser relay coalesces a burst of
+ * inside one debounce window, and the browser relay coalesces a burst of
  * signals into ONE emitted reload (#1397). In both places a batch mixing a page
  * edit and a component edit is a COMPONENT edit, so taking the last verdict
  * would leave the old component class running against fresh markup.
@@ -63,10 +81,16 @@ export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page']
  * @param {ReloadVerdict | null | undefined} b
  * @returns {ReloadVerdict | null}
  */
-export function strongerVerdict(a, b) {
+export function mergeVerdicts(a, b) {
   if (!a) return b || null;
   if (!b) return a;
-  return verdictRank(a.v) <= verdictRank(b.v) ? a : b;
+  const top = verdictRank(a.v) <= verdictRank(b.v) ? a : b;
+  /** @type {ReloadVerdict} */
+  const out = { v: top.v, by: top.by, why: top.why };
+  const modules = [...new Set([...(a.modules || []), ...(b.modules || [])])].sort();
+  if (modules.length) out.modules = modules;
+  if (a.css || b.css) out.css = true;
+  return out;
 }
 
 /**
@@ -96,7 +120,7 @@ function verdictRank(v) {
  *    gap. Reading currency here would therefore turn the feature off for every
  *    edit after the first in a burst. Classifying against the previous build's
  *    graph is the intended behaviour, and it is conservative in the right
- *    direction: a file the stale graph has never seen falls to rung 6 and
+ *    direction: a file the stale graph has never seen falls to rung 7 and
  *    reloads.
  * 2. The path is outside `appDir`. The watcher only fires for `appDir` plus the
  *    opt-in `webjs.dev.watch` roots (#894), and a file outside `appDir` is
@@ -104,25 +128,33 @@ function verdictRank(v) {
  *    change what any layout renders, so it takes the whole-body `shell` swap.
  * 3. The path is in the SHIPPED closure. This is the transitive answer and the
  *    one that matters: the browser holds this module, so the page must reload.
- * 4. The path is a page module. Morphable.
- * 5. The path is somewhere else in the module graph (a layout, a server-only
+ *    A CSS module script (`import s from './x.css' with { type: 'css' }`) is in
+ *    the closure too, so it stops here and never reaches rung 4.
+ * 4. The path is a stylesheet (`.css`) the browser does not hold as a module
+ *    (#1689): a `public/` sheet, an `@import`ed partial, a
+ *    `webjs.dev.regenerate` input such as Tailwind's. The tab re-requests every
+ *    same-origin stylesheet and swaps them in place, with no reload and no
+ *    re-render. Every sheet rather than the changed one, which is what makes a
+ *    partial and a regenerate output come out right, since neither is the file
+ *    the page links.
+ * 5. The path is a page module. Morphable.
+ * 6. The path is somewhere else in the module graph (a layout, a server-only
  *    util, a `.server.*` file reachable only from a page). Server-only by
  *    elimination, so `shell`.
- * 6. Anything else. A brand-new file, a deleted file, and every `public/` asset
- *    land here. `public/` is not in the module graph at all, so the server
- *    cannot tell what the file IS or what depends on it, and most of what lives
- *    there (an image, a font, a service worker, a hand-written script) is
- *    something no amount of re-rendering picks up. The refresh does re-request
- *    the page's stylesheets, so a `public/` CSS edit alone would now survive a
- *    morph, but that is one knowable case inside a rung whose whole point is
- *    that the file is unknowable.
+ * 7. Anything else. A brand-new file, a deleted file, and every other `public/`
+ *    asset land here. `public/` is not in the module graph at all, so the
+ *    server cannot tell what the file IS or what depends on it, and most of
+ *    what lives there (an image, a font, a service worker, a hand-written
+ *    script) is something no amount of re-rendering picks up. A stylesheet is
+ *    the one kind it can name from the path alone, which is why rung 4 takes
+ *    it out first.
  *
  * Note what step 3 sweeps in deliberately. A `'use server'` action file
  * imported by a SHIPPING component is inside the closure (the graph keeps a
  * `.server.*` node and stops at it), so editing it reloads. That is correct
  * rather than merely conservative, because adding an export to that file
  * changes the generated RPC stub the browser holds. The same action imported
- * only by a page falls to step 5 and gets `shell`.
+ * only by a page falls to step 6 and gets `shell`.
  *
  * @param {string} abs  absolute path of the changed file
  * @param {object} ctx
@@ -141,6 +173,7 @@ export function classifyChangedPath(abs, ctx) {
   if (!ctx.analysisReady) return { v: 'reload', by, why: 'analysis-cold' };
   if (!isUnder(abs, ctx.appDir, sep)) return { v: 'shell', by, why: 'extra-watch-root' };
   if (ctx.shippedFiles && ctx.shippedFiles.has(abs)) return { v: 'reload', by, why: 'ships-to-browser' };
+  if (abs.endsWith('.css')) return { v: 'css', by, why: 'stylesheet', css: true };
   if (ctx.pageFiles && ctx.pageFiles.has(abs)) return { v: 'page', by, why: 'page-module' };
   if (ctx.graphFiles && ctx.graphFiles.has(abs)) return { v: 'shell', by, why: 'server-only-module' };
   return { v: 'reload', by, why: 'unknown-path' };

package/src/dev-error.js

@@ -14,7 +14,10 @@
  * offending source file for the code frame (a read failure degrades to no
  * frame, never throws).
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { findDecorator, decoratorReport, parseMissingExport, isCoreModule, missingCoreNameFix } from './lit-hints.js';
+import { coreSurface, isTypeOnlyAnywhere } from './core-exports.js';
 
 /**
  * Pull the first useful `file:line:column` out of an error stack. Prefers a
@@ -40,7 +43,9 @@ export function parseStackLocation(stack, appDir) {
   // (the `file:///` URL form, whose path uses forward slashes, still resolves).
   // That matches the framework's POSIX-first dev posture; it degrades, never
   // crashes.
-  const re = /(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+):(\d+)/g;
+  // The lookbehind keeps a runtime-internal frame (`node:internal/modules/...`)
+  // from reading as the path `/modules/...`.
+  const re = /(?<![\w.-])(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+):(\d+)/g;
   /** @type {{ file: string, line: number, column: number }[]} */
   const frames = [];
   let m;
@@ -114,6 +119,15 @@ export function buildDevErrorFrame(error, opts = {}) {
   let file = opts.file || null;
   let line = opts.line != null ? opts.line : null;
   let column = opts.column != null ? opts.column : null;
+  // A module that fails to PARSE (a decorator is the common case) throws a
+  // SyntaxError whose stack OPENS with a bare `file:///abs/x.ts:2` header (a
+  // line, no column) and continues with node:internal frames only, which the
+  // frame pattern would misread as a path. The header names the source, so it
+  // wins.
+  if (!file && stack) {
+    const head = /^(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+)[ \t]*\n/.exec(stack);
+    if (head) { file = head[1]; line = Number(head[2]); }
+  }
   if (!file && stack) {
     const loc = parseStackLocation(stack, opts.appDir);
     if (loc) { file = loc.file; line = loc.line; column = loc.column; }
@@ -125,6 +139,20 @@ export function buildDevErrorFrame(error, opts = {}) {
     const loc = parseStackLocation(`${err.message}\n${stack || ''}`, opts.appDir);
     if (loc && loc.file === file) { line = loc.line; column = loc.column; }
   }
+  // A module that fails to PARSE, caught rather than crashing the process,
+  // carries no location at all on Node (the `file:line` arrow header is only
+  // printed for an uncaught error), so a decorator three imports down leaves
+  // the overlay with nothing to point at. The usual cause of an unexpected
+  // token in a WebJs app is a decorator, so look for one in the app source.
+  let hint = opts.hint || null;
+  if (!hint && !file && err instanceof SyntaxError && opts.appDir) {
+    const found = findAppDecorator(opts.appDir);
+    if (found) {
+      file = found.file; line = found.hit.line; column = found.hit.column;
+      const { message, fix } = decoratorReport(found.hit);
+      hint = `${message} ${fix}`;
+    }
+  }
   const codeFrame = file && line ? readCodeFrame(file, line, column || 0) : null;
   return {
     kind,
@@ -134,7 +162,80 @@ export function buildDevErrorFrame(error, opts = {}) {
     line,
     column,
     codeFrame,
-    hint: opts.hint || null,
+    hint: hint || inferHint(err, file, opts.appDir) || null,
     url: typeof opts.url === 'string' && opts.url ? opts.url : null,
   };
 }
+
+/**
+ * Name the WebJs fix for an error whose own message does not, so the overlay
+ * says what to write instead of only what broke.
+ *
+ * A decorator (`@customElement`, `@property`, ...) is the case it exists for.
+ * Node fails the module with a bare `SyntaxError: Invalid or unexpected
+ * token`, and Bun, which runs legacy decorators, with a `ReferenceError` for
+ * the undefined decorator function. Neither names the fix, so when the failing
+ * file carries a decorator the hint is the one `webjs check` prints.
+ *
+ * The other is a name `@webjsdev/core` does not export (`LitElement`, a
+ * decorator function, a type imported as a value). Node says `does not provide
+ * an export named X` and Bun `Export named 'X' not found`; the hint is the one
+ * the `core-imports-exist` check rule prints for the same import.
+ *
+ * @param {Error} err
+ * @param {string | null} file  the located source file, when there is one
+ * @param {string} [appDir]  resolves the core package the app imports
+ * @returns {string | null}
+ */
+export function inferHint(err, file, appDir) {
+  const missing = parseMissingExport(err.message);
+  if (missing && isCoreModule(missing.module)) {
+    const surface = coreSurface(appDir);
+    const typeOnly = !!surface && isTypeOnlyAnywhere(surface, missing.name);
+    return `\`${missing.name}\` is not a runtime export of @webjsdev/core. ${missingCoreNameFix(missing.name, { typeOnly })}`;
+  }
+  if ((err instanceof SyntaxError || err instanceof ReferenceError) && file) {
+    let src = null;
+    try { src = readFileSync(file, 'utf8'); } catch { src = null; }
+    const hit = src ? findDecorator(src) : null;
+    if (hit) {
+      const { message, fix } = decoratorReport(hit);
+      return `${message} ${fix}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The first decorator in the app's own source, walking every JS / TS file
+ * outside node_modules, `public/`, and dot or underscore folders. Dev-only and
+ * reached only for an unlocated SyntaxError, so the synchronous walk costs
+ * nothing on the happy path.
+ *
+ * @param {string} appDir
+ * @returns {{ file: string, hit: { name: string, index: number, line: number, column: number } } | null}
+ */
+function findAppDecorator(appDir) {
+  /** @type {string[]} */
+  const stack = [appDir];
+  let budget = 5000;
+  while (stack.length && budget-- > 0) {
+    const dir = /** @type {string} */ (stack.pop());
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name.startsWith('.') || e.name.startsWith('_')) continue;
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (dir === appDir && e.name === 'public') continue;
+        stack.push(abs);
+      } else if (/\.m?[jt]s$/.test(e.name)) {
+        let src;
+        try { src = readFileSync(abs, 'utf8'); } catch { continue; }
+        const hit = findDecorator(src);
+        if (hit) return { file: abs, hit };
+      }
+    }
+  }
+  return null;
+}

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() };
+}