@webjsdev/server 0.9.0 → 0.10.0

package/src/dev/server.js

@@ -1,11 +1,12 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { strongerVerdict } from '../dev-classify.js';
-import { createWatchIgnore } from './watch-ignore.js';
+import { mergeVerdicts } from '../dev-classify.js';
+import { createWatchIgnore, editorTempTarget } from './watch-ignore.js';
 import { watchTree } from './watch-tree.js';
+import { createPokeState } from './poke-state.js';
 import { relative, resolve } from 'node:path';
 import {
   hotRerunCapable, hotHostKey, getHotHost, setHotHost, deleteHotHost,
-  armHotSentinel, pokeHotSentinel, removeHotSentinel, needsHotReset, announceHotInPlace,
+  armHotSentinel, pokeHotSentinel, removeHotSentinel, needsHotReset, announceHotInPlace, requestSupervisorRestart,
 } from './hot-host.js';
 import { createServer as createHttp1Server } from 'node:http';
 import { createRequestHandler } from './handler.js';
@@ -33,6 +34,29 @@ const SERVER_VERSION = (() => {
  */
 const POKE_FALLBACK_MS = 1500;
 
+/**
+ * The root files the `webjs dev` supervisor restarts this child for (#1689),
+ * as the pattern the supervisor hands over in `__WEBJS_DEV_RESTART_FILES`, or
+ * null when no supervisor will (`--no-hot`, an embedder, an older CLI). This
+ * watcher sees the same files, and a reload frame it sent for one would reload
+ * the tab a second time on top of the restart, which already reloads it.
+ * @returns {RegExp | null}
+ */
+export function supervisorRestartFile(env = process.env) {
+  if (env.__WEBJS_DEV_CHILD !== '1' || !env.__WEBJS_DEV_RESTART_FILES) return null;
+  try { return new RegExp(env.__WEBJS_DEV_RESTART_FILES); } catch { return null; }
+}
+
+/**
+ * An internal test seam (like `__WEBJS_DEV_CHILD`): how long a `bun --hot`
+ * re-run waits before taking its batch, so `test/bun/dev-late-rerun.mjs` can
+ * land it after the poke fallback every time, the race #1689 fixed. Unset is 0.
+ */
+function rerunDelayMs() {
+  const n = Number(process.env.__WEBJS_RERUN_DELAY_MS || 0);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
 function debounce(fn, ms) {
   let t;
   return (...args) => {
@@ -286,7 +310,9 @@ export async function startServer(opts) {
   // identically on both). Built before the handler so its onReload / onDevError
   // callbacks can fan out through it.
   // A Bun hot host, or a server outside the dev supervisor (`--no-hot`, an
-  // embedder), applies an edit in place; a supervised Node child is restarted.
+  // embedder), applies an edit in place. A supervised Node child does too once
+  // its handler has the module resolve hook (#1689), which is set below; only a
+  // Node without `module.registerHooks` is still restarted.
   const hub = new SseHub({ inPlace: dev && (!!hotKey || process.env.__WEBJS_DEV_CHILD !== '1') });
   // Pages render the stream's state into a meta tag (#1516), so the relay can
   // re-check a page against the server on every reconnect.
@@ -306,13 +332,14 @@ export async function startServer(opts) {
     hub.closeAll();
     throw e;
   }
+  // Node re-evaluates edited app modules in place (#1689), so its frames say so
+  // and the relay waits the short in-place window rather than a restart's.
+  if (app.hotModules) hub.inPlace = true;
 
   /** @type {AbortController | null} */
   let watcherAbort = null;
-  /** The strongest verdict of the edits a poked re-run has yet to apply. */
-  /** @type {import('../dev-classify.js').ReloadVerdict | null} */
-  let pokedVerdict = null;
-  /** @type {any} */ let pokeFallback = null;
+  /** The edits a poked re-run has yet to apply, and the fallback's late re-run (#1689). */
+  const poked = createPokeState({ fallbackMs: POKE_FALLBACK_MS });
   if (dev) {
     // Watch the app tree with Node's built-in `fs.watch` (no external dep):
     // `watchTree` (#1521) watches the root plus each non-ignored top-level dir,
@@ -323,34 +350,32 @@ export async function startServer(opts) {
     // (module-level, exported for tests) skips node_modules, .git, .webjs/, and
     // the SQLite dev DB (db/dev.db) + db/migrations so a file the dev server itself writes never loops.
     // Live-reload classification (#1398). Several files can change inside one
-    // 50ms debounce window (80ms before #1575), so hold the STRONGEST verdict of the window and
-    // hand it to the rebuild. Same rule as the browser relay's cross-batch
-    // accumulation, for the same reason: a window mixing a page edit and a
-    // component edit is a component edit, and taking the last one would morph
-    // fresh markup onto the old component class.
-    /** @type {import('../dev-classify.js').ReloadVerdict | null} */
-    let pendingVerdict = null;
+    // 50ms debounce window (80ms before #1575), so merge the verdicts of the
+    // window and hand the result to the rebuild. Same rule as the browser
+    // relay's cross-batch accumulation, for the same reason: a window mixing a
+    // page edit and a component edit is a component edit, and taking the last
+    // one would morph fresh markup onto the old component class. The window's
+    // changed files ride along (#1689), so the rebuild can version exactly the
+    // modules the edit touched.
+    /** @type {{ verdict: import('../dev-classify.js').ReloadVerdict | null, changed: Set<string> }} */
+    const pending = { verdict: null, changed: new Set() };
     // Under `bun --hot`, a window that changed a module a `Bun.plugin` serves
     // pokes the re-run sentinel instead of rebuilding (#1575): the rebuild has
     // to wait for the registry reset, or the next request would still import
     // the stale module. The re-run (`hotRerun` below) rebuilds with the verdict.
     let pendingPoke = false;
     const rebuild = debounce(() => {
-      const v = pendingVerdict;
-      pendingVerdict = null;
+      const v = pending.verdict;
+      const files = [...pending.changed];
+      pending.verdict = null;
+      pending.changed.clear();
       if (pendingPoke) {
         pendingPoke = false;
-        pokedVerdict = strongerVerdict(pokedVerdict, v);
+        poked.poke(v, files, (pv, pf) => { if (pv) app.rebuild(pv, { changed: pf }); });
         pokeHotSentinel(app.appDir);
-        clearTimeout(pokeFallback);
-        pokeFallback = setTimeout(() => {
-          const pv = pokedVerdict;
-          pokedVerdict = null;
-          if (pv) app.rebuild(pv);
-        }, POKE_FALLBACK_MS);
         return;
       }
-      app.rebuild(v || undefined);
+      app.rebuild(v || undefined, { changed: files });
     }, 50);
     watcherAbort = new AbortController();
     // One warning per unwatchable path (#1521): an EACCES / ENOENT on a single
@@ -363,27 +388,55 @@ export async function startServer(opts) {
       warned.add(key);
       logger.warn(`file watcher skipped ${err && err.path ? err.path : 'a path'} (${err && err.code ? err.code : String(err)})`);
     };
+    let pollFallbackWarned = false;
+    const restartFile = supervisorRestartFile();
     const watchRoot = (root) => {
       // Output nothing serves (`*.log`, coverage/, ...) and the root's
       // `.gitignore` never reload the page: `npm run dev > dev.log` made every
       // log line a reload (watch-ignore.js).
       const unserved = createWatchIgnore(root);
       const close = watchTree(root, {
-        ignore: (rel) => shouldIgnoreWatchPath(rel) || unserved(rel),
+        // An editor temp file renamed over a real file is let through, and
+        // reported below as the file it saved (#1689): Bun's fs.watch names
+        // only the temp file for such a save.
+        ignore: (rel) => shouldIgnoreWatchPath(rel) || (unserved(rel) && !editorTempTarget(rel)),
         onEvent: (filename) => {
+          const target = editorTempTarget(filename);
+          if (target) {
+            if (unserved(target) || !existsSync(resolve(root, target))) return;
+            filename = target;
+          }
           // A regenerate output (#967) is a build product the server itself
           // writes on request; ignoring it stops a spurious rebuild + reload
           // (and a reload -> refetch -> recompile -> reload cycle), same as the
           // db/dev.db carve-out above. `app` exposes the check because `state`
           // lives in createRequestHandler's scope, not here.
           if (app.isRegenerateOutput(filename)) return;
-          pendingVerdict = strongerVerdict(pendingVerdict, app.classifyWatchPath(filename, root));
+          // The supervisor restarts the process for this one, and the restart
+          // is the reload; a frame from here would be a second one (#1689).
+          if (restartFile && root === app.appDir && restartFile.test(filename)) return;
+          // A module the CommonJS loader holds cannot be versioned, so the
+          // edit needs a fresh process (#1689): the supervisor restarts, and
+          // that restart is the reload, so no frame goes out from here.
+          if (restartFile && app.isCommonJsModule(resolve(root, filename))
+            && requestSupervisorRestart(relative(app.appDir, resolve(root, filename)))) return;
+          pending.verdict = mergeVerdicts(pending.verdict, app.classifyWatchPath(filename, root));
+          pending.changed.add(resolve(root, filename));
           if (hotKey && needsHotReset(filename, (f) => !app.needsRegistryReset(f, root))) pendingPoke = true;
           // A status wait (#1664) holds until the rebuild this event schedules.
           app.noteChange?.();
           rebuild();
         },
         onError: onWatchError,
+        // Out of inotify watches (#1689): the directory is polled instead, and
+        // the fix is printed once per process rather than per directory.
+        onFallback: (name, err) => {
+          if (pollFallbackWarned) return;
+          pollFallbackWarned = true;
+          const code = (err && err.code) || 'ENOSPC';
+          const what = name ? `${name}/` : 'the app root';
+          logger.warn(`[webjs] the file watch limit is reached (${code}), so ${what} is watched by polling every 1s. Raise it: sudo sysctl fs.inotify.max_user_watches=524288 (persist it in /etc/sysctl.d/).`);
+        },
       });
       watcherAbort.signal.addEventListener('abort', close, { once: true });
     };
@@ -436,21 +489,27 @@ export async function startServer(opts) {
          * then re-derive the analysis so it re-imports the app's modules (the
          * middleware, the components it primes) from that registry. A re-run a
          * poke asked for carries the verdict of the edits behind it and tells the
-         * browser; any other is silent, since the watcher already sent that
-         * edit's own reload frame.
+         * browser, and so does one that arrives after the poke's fallback
+         * already rebuilt against the old registry (#1689), so the tab picks up
+         * the fresh modules; any other is silent, since the watcher already
+         * sent that edit's own reload frame.
          */
         rerun: async () => {
           await armHotSentinel(app.appDir);
-          const pv = pokedVerdict;
-          pokedVerdict = null;
-          clearTimeout(pokeFallback);
-          await app.rebuild(pv || undefined, { notify: !!pv });
+          if (rerunDelayMs()) await new Promise((r) => setTimeout(r, rerunDelayMs()));
+          const { verdict: pv, changed: pf, notify } = poked.takeForRerun();
+          await app.rebuild(pv || undefined, { notify, changed: pf });
           return owned;
         },
         poke: () => pokeHotSentinel(app.appDir),
       });
       announceHotInPlace();
     }
+    // A Node child with the module resolve hook (#1689) tells the supervisor
+    // the same thing, so an app edit no longer restarts it; only the restart
+    // files (`instrumentation.*`, `env.*`, `.env`, `package.json`, a lockfile)
+    // still do.
+    if (app.hotModules) announceHotInPlace();
     return handle;
   } catch (e) {
     // The listener never came up (a taken port, #1527): stop what was started

package/src/dev/specifier-versions.js

@@ -0,0 +1,125 @@
+/**
+ * Browser module versions for `webjs dev` (#1689), runtime-neutral.
+ *
+ * A browser keeps one module instance per URL for the life of the page, so a
+ * re-imported module whose own URL is unchanged comes back as the old instance,
+ * and so does every module it imports. To hand a tab the edited code without a
+ * reload, a rebuild bumps each changed file the browser holds AND every module
+ * that imports it (transitively, through the shipped graph), and the server
+ * rewrites the import specifiers of every served app module so an import of a
+ * bumped file carries `?t=<n>` (`&t=<n>` when the specifier already has a
+ * query), the technique the Remix asset server uses. A re-import of a bumped
+ * boundary then walks a fresh URL chain down to the edited file, while every
+ * module nothing changed under keeps its bare URL and therefore its original
+ * instance, which is what keeps `@webjsdev/core` (a bare specifier, never
+ * versioned) and every module-scope signal one instance.
+ *
+ * The map is separate from the server's (`esm-hot-hooks.js`) because Bun has no
+ * resolve hook and the browser's module map is separate anyway. It lives on the
+ * handler's state and is never cleared on a rebuild.
+ */
+
+import { dynamicEdges, expandImportAlias, importSpecifierRanges, resolveImport } from '../module-graph.js';
+
+/**
+ * @typedef {{
+ *   bump: (changed: Iterable<string>, importers: Map<string, Set<string>> | null, shipped: Set<string>) => Set<string>,
+ *   versionOf: (abs: string) => number,
+ *   clear: () => void,
+ * }} BrowserVersions
+ */
+
+/**
+ * Who imports whom among the modules the browser holds: for each module, the
+ * shipped modules that import it statically or through a string-literal
+ * dynamic import. One walk of the graph per rebuild, shared by the version
+ * bump and the hot-swap boundary walk (`hotVerdict` in `handler.js`).
+ * @param {Map<string, Set<string>>} graph
+ * @param {Set<string>} shipped
+ * @returns {Map<string, Set<string>>}
+ */
+export function shippedImporters(graph, shipped) {
+  /** @type {Map<string, Set<string>>} */
+  const importers = new Map();
+  for (const edges of [graph, dynamicEdges(graph)]) {
+    for (const [from, tos] of edges) {
+      if (!shipped.has(from)) continue;
+      for (const to of tos) {
+        let set = importers.get(to);
+        if (!set) importers.set(to, (set = new Set()));
+        set.add(from);
+      }
+    }
+  }
+  return importers;
+}
+
+/** @returns {BrowserVersions} */
+export function createBrowserVersions() {
+  /** @type {Map<string, number>} */
+  const versions = new Map();
+  let next = 0;
+  return {
+    // Give each changed file the browser holds and every shipped module that
+    // imports it (`shippedImporters`) ONE new version. A changed file outside
+    // `shipped` is skipped, since the browser holds no instance of it. Returns
+    // the files that moved.
+    bump(changed, importers, shipped) {
+      /** @type {Set<string>} */
+      const reached = new Set();
+      if (!importers) return reached;
+      const stack = [];
+      for (const f of changed) if (shipped.has(f)) stack.push(f);
+      while (stack.length) {
+        const f = /** @type {string} */ (stack.pop());
+        if (reached.has(f)) continue;
+        reached.add(f);
+        for (const imp of importers.get(f) || []) if (!reached.has(imp)) stack.push(imp);
+      }
+      if (reached.size) {
+        next++;
+        for (const f of reached) versions.set(f, next);
+      }
+      return reached;
+    },
+    versionOf(abs) {
+      return versions.get(abs) || 0;
+    },
+    clear() {
+      versions.clear();
+    },
+  };
+}
+
+/**
+ * Append `t=<version>` to every import specifier in `code` that resolves to an
+ * app file with a version above 0. Static imports, `export … from` and
+ * string-literal dynamic imports are rewritten; a type-only clause, a
+ * specifier written inside a string, template or comment, and a bare specifier
+ * are left alone. Returns `code` itself when nothing applies.
+ *
+ * @param {string} code a served module's source (after type stripping)
+ * @param {string} importerAbs the module's absolute path
+ * @param {string} appDir
+ * @param {(abs: string) => number} versionOf
+ * @returns {string}
+ */
+export function versionImportSpecifiers(code, importerAbs, appDir, versionOf) {
+  /** @type {Array<{ end: number, add: string }>} */
+  const edits = [];
+  const seen = new Set();
+  for (const { start, end, spec } of importSpecifierRanges(code)) {
+    if (seen.has(start)) continue;
+    seen.add(start);
+    if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
+    const resolved = resolveImport(spec, importerAbs, appDir);
+    if (!resolved) continue;
+    const n = versionOf(resolved);
+    if (n > 0) edits.push({ end, add: (spec.includes('?') ? '&' : '?') + 't=' + n });
+  }
+  if (!edits.length) return code;
+  edits.sort((a, b) => b.end - a.end);
+  let out = code;
+  for (const { end, add } of edits) out = out.slice(0, end) + add + out.slice(end);
+  return out;
+}

package/src/dev/watch-ignore.js

@@ -24,15 +24,60 @@
 import { readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
-const OUTPUT = /(?:^|[\\/])(?:coverage|\.cache|\.nyc_output|test-results|playwright-report|\.turbo)(?:[\\/]|$)|\.log$|(?:^|[\\/])\.DS_Store$|\.swp$|~$/;
+const OUTPUT = /(?:^|[\\/])(?:coverage|\.cache|\.nyc_output|test-results|playwright-report|\.turbo)(?:[\\/]|$)|\.log$|(?:^|[\\/])\.DS_Store$|(?:^|[\\/])(?:\.#[^\\/]*|#[^\\/]*#|\.goutputstream-[^\\/]*|~\$[^\\/]*)$|\.(?:sw[a-p]|tmp|crswap|kate-swp)$|___jb_(?:tmp|old)___$|~$/;
+
+/**
+ * Vim's write probe, an all-digit FILE (`4913`, then `5036` and up when that
+ * one exists) it creates and deletes in the directory it saves into. Only a
+ * file is a probe: a directory named by digits (`app/blog/2024/`, `app/404/`)
+ * is app source, and the walkers ask about directories by the same path test.
+ */
+const DIGIT_LEAF = /(?:^|[\\/])\d+$/;
+
+/**
+ * Whether `rel` is vim's write probe: an all-digit name that is not a
+ * directory under `root` (a probe is usually already deleted when its event
+ * arrives, and a missing path is not a directory either).
+ * @param {string} rel
+ * @param {string} [root] the app root; without one an all-digit name is taken as a file
+ * @returns {boolean}
+ */
+export function isVimProbe(rel, root) {
+  if (!DIGIT_LEAF.test(rel || '')) return false;
+  if (!root) return true;
+  try { return !statSync(join(root, rel)).isDirectory(); } catch { return true; }
+}
+
+/**
+ * Editor temp files that are RENAMED over the file they save (#1689): `x.tmp`
+ * (`sed`-style and many atomic writers), JetBrains' `x___jb_tmp___` /
+ * `x___jb_old___`, and Chrome's `x.crswap`. Bun's `fs.watch` reports such a
+ * save ONLY under the temp name, so ignoring it outright would lose the edit
+ * there; the watcher reports the target instead.
+ */
+const RENAMED_TEMP = /(?:\.tmp|\.crswap|___jb_(?:tmp|old)___)$/;
+
+/**
+ * The file an editor temp file is renamed over, or null when the name says
+ * nothing about it (vim's `4913`, an emacs lock, a gedit stream).
+ * @param {string} rel
+ * @returns {string | null}
+ */
+export function editorTempTarget(rel) {
+  const p = String(rel || '');
+  const m = RENAMED_TEMP.exec(p);
+  if (!m || m.index === 0 || /[\\/]$/.test(p.slice(0, m.index))) return null;
+  return p.slice(0, m.index);
+}
 
 /**
  * Tool output that is never served, whatever `.gitignore` says.
  * @param {string} rel path relative to the app root
+ * @param {string} [root] the app root, which tells vim's all-digit probe file from a directory
  * @returns {boolean}
  */
-export function isUnservedOutput(rel) {
-  return OUTPUT.test(rel || '');
+export function isUnservedOutput(rel, root) {
+  return OUTPUT.test(rel || '') || isVimProbe(rel, root);
 }
 
 /**
@@ -115,7 +160,7 @@ export function createWatchIgnore(root) {
   try { rules = parseGitignore(readFileSync(join(root, '.gitignore'), 'utf8')); } catch { /* no .gitignore */ }
   return (rel) => {
     const p = String(rel || '').replace(/\\/g, '/');
-    if (isUnservedOutput(p)) return true;
+    if (isUnservedOutput(p, root)) return true;
     if (/(?:^|\/)\.env(?:\.[^/]*)?$/.test(p)) return false;
     let dir = false;
     if (rules.length) { try { dir = statSync(join(root, p)).isDirectory(); } catch { /* gone or unreadable */ } }

package/src/dev/watch-poll.js

@@ -0,0 +1,78 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Poll a directory for changes, the dev watcher's fallback when the OS has no
+ * watch left to give (#1689). Linux caps inotify watches per user
+ * (`fs.inotify.max_user_watches`, often 8192 on older distributions and lower
+ * in containers), and a large repo or a second dev server reaches it: `fs.watch`
+ * then fails with ENOSPC (EMFILE for open files), and the directory used to be
+ * dropped for the rest of the session, so its edits never reloaded anything.
+ * Polling is slower and costs a directory walk per tick, but it never stops.
+ *
+ * Each tick takes a snapshot `Map<rel, 'mtimeMs:size'>` of every file under
+ * `dir` that `ignore` admits (directories are walked, not reported) and diffs it
+ * against the previous one, so an added, a changed and a removed file are each
+ * reported once. The first snapshot is the baseline and reports nothing. The
+ * timer is `unref()`ed, so a forgotten poller never holds the process open.
+ *
+ * @param {string} dir  absolute directory to poll
+ * @param {{
+ *   ignore?: (relPath: string) => boolean,
+ *   onEvent: (relPath: string) => void,
+ *   intervalMs?: number,
+ *   recursive?: boolean,
+ * }} opts  `relPath` is relative to `dir`, with OS separators. `recursive:
+ *   false` reports the direct entries only (directories included), the shape
+ *   the root of a watched tree needs.
+ * @returns {() => void} stops polling
+ */
+export function pollTree(dir, { ignore = () => false, onEvent, intervalMs = 1000, recursive = true }) {
+  /** @returns {Map<string, string>} */
+  const snapshot = () => {
+    /** @type {Map<string, string>} */
+    const out = new Map();
+    /** @param {string} rel */
+    const walk = (rel) => {
+      let entries;
+      try { entries = readdirSync(rel ? join(dir, rel) : dir, { withFileTypes: true }); } catch { return; }
+      for (const e of entries) {
+        const child = rel ? join(rel, e.name) : e.name;
+        if (ignore(child)) continue;
+        let st;
+        try { st = statSync(join(dir, child)); } catch { continue; }
+        if (st.isDirectory()) {
+          if (recursive) walk(child);
+          else out.set(child, 'dir');
+        } else {
+          out.set(child, `${st.mtimeMs}:${st.size}`);
+        }
+      }
+    };
+    walk('');
+    return out;
+  };
+
+  let prev = snapshot();
+  const timer = setInterval(() => {
+    const next = snapshot();
+    for (const [rel, sig] of next) if (prev.get(rel) !== sig) onEvent(rel);
+    for (const rel of prev.keys()) if (!next.has(rel)) onEvent(rel);
+    prev = next;
+  }, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+/**
+ * Whether a watch failure means the OS is out of watches (or file
+ * descriptors), the two failures polling can stand in for. Any other watch
+ * error (EACCES, ENOENT on a vanished path) is about one path and stays a
+ * warning.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isWatchLimitError(err) {
+  const code = err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
+  return code === 'ENOSPC' || code === 'EMFILE';
+}

package/src/dev/watch-tree.js

@@ -1,6 +1,7 @@
 import { watch, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { watchRecursive } from './watch-recursive.js';
+import { pollTree, isWatchLimitError } from './watch-poll.js';
 
 /**
  * The dev live-reload watcher over one root (#1521).
@@ -25,58 +26,94 @@ import { watchRecursive } from './watch-recursive.js';
  * root watcher's events, so `mkdir lib` mid-session is watched like it was
  * there at boot.
  *
+ * When the OS runs out of watches (ENOSPC once the inotify limit is reached,
+ * EMFILE for file descriptors, #1689), the directory that failed is polled
+ * instead (`watch-poll.js`) and `onFallback` is told once per directory, so its
+ * edits keep arriving, a second slower, instead of never. A root watcher that
+ * fails that way polls the root's direct entries.
+ *
  * @param {string} root  absolute directory to watch
  * @param {{
  *   ignore: (relPath: string) => boolean,
  *   onEvent: (relPath: string) => void,
  *   onError: (err: NodeJS.ErrnoException) => void,
- * }} opts  `relPath` is relative to `root`, with OS separators.
+ *   onFallback?: (name: string, err: NodeJS.ErrnoException) => void,
+ *   watchFn?: typeof watch,
+ *   pollMs?: number,
+ * }} opts  `relPath` is relative to `root`, with OS separators. `onFallback`
+ *   gets the top-level directory name (`''` for the root). `watchFn` and
+ *   `pollMs` are test seams.
  * @returns {() => void} closes every watcher
  */
-export function watchTree(root, { ignore, onEvent, onError }) {
-  /** @type {Map<string, import('node:fs').FSWatcher>} */
+export function watchTree(root, { ignore, onEvent, onError, onFallback, watchFn = watch, pollMs = 1000 }) {
+  /** @type {Map<string, { close: () => void, polled?: boolean }>} */
   const dirs = new Map();
   let closed = false;
 
-  const guard = (/** @type {import('node:fs').FSWatcher} */ w) => {
-    w.on('error', (err) => onError(/** @type {NodeJS.ErrnoException} */ (err)));
-    return w;
-  };
-
   const isDir = (name) => {
     try { return statSync(join(root, name)).isDirectory(); } catch { return false; }
   };
 
+  /** Replace a top-level directory's watcher with a poller. */
+  const pollDir = (name, /** @type {NodeJS.ErrnoException} */ err) => {
+    if (closed || dirs.get(name)?.polled) return;
+    try { dirs.get(name)?.close(); } catch {}
+    const stop = pollTree(join(root, name), {
+      ignore: (rel) => ignore(join(name, rel)),
+      onEvent: (rel) => onEvent(join(name, rel)),
+      intervalMs: pollMs,
+    });
+    dirs.set(name, { close: stop, polled: true });
+    onFallback?.(name, err);
+  };
+
   const watchDir = (name) => {
     if (closed || dirs.has(name) || ignore(name)) return;
+    const failed = (/** @type {NodeJS.ErrnoException} */ err) => {
+      if (isWatchLimitError(err)) pollDir(name, err);
+      else onError(err);
+    };
     try {
       // `watchRecursive` (#1529): on Linux under Node a per-directory walker,
       // since Node 24's recursive watcher goes deaf to a file once it is
       // replaced (`sed -i`, an editor's atomic save).
-      const w = guard(watchRecursive(join(root, name), (_type, filename) => {
+      const w = watchRecursive(join(root, name), (_type, filename) => {
         const rel = filename ? join(name, String(filename)) : name;
         if (!ignore(rel)) onEvent(rel);
-      }, { ignore: (rel) => ignore(join(name, rel)) }));
+      }, { ignore: (rel) => ignore(join(name, rel)), watchFn });
+      w.on('error', (err) => failed(/** @type {NodeJS.ErrnoException} */ (err)));
       dirs.set(name, w);
     } catch (err) {
-      onError(/** @type {NodeJS.ErrnoException} */ (err));
+      failed(/** @type {NodeJS.ErrnoException} */ (err));
     }
   };
 
-  /** @type {import('node:fs').FSWatcher | null} */
+  /** A top-level entry changed: start or stop following it as a directory. */
+  const onTop = (/** @type {string} */ name) => {
+    if (ignore(name)) return;
+    if (isDir(name)) watchDir(name);
+    else if (dirs.has(name)) { try { dirs.get(name)?.close(); } catch {} dirs.delete(name); }
+    onEvent(name);
+  };
+
+  /** @type {{ close: () => void } | null} */
   let top = null;
+  const pollRoot = (/** @type {NodeJS.ErrnoException} */ err) => {
+    if (closed) return;
+    try { top?.close(); } catch {}
+    top = { close: pollTree(root, { ignore, onEvent: onTop, intervalMs: pollMs, recursive: false }) };
+    onFallback?.('', err);
+  };
+  const rootFailed = (/** @type {NodeJS.ErrnoException} */ err) => {
+    if (isWatchLimitError(err)) pollRoot(err);
+    else onError(err);
+  };
   try {
-    top = guard(watch(root, (_type, filename) => {
-      if (!filename) return;
-      const name = String(filename);
-      if (ignore(name)) return;
-      // A top-level entry changed: start or stop following it as a directory.
-      if (isDir(name)) watchDir(name);
-      else if (dirs.has(name)) { try { dirs.get(name)?.close(); } catch {} dirs.delete(name); }
-      onEvent(name);
-    }));
+    const w = watchFn(root, (_type, filename) => { if (filename) onTop(String(filename)); });
+    w.on('error', (err) => rootFailed(/** @type {NodeJS.ErrnoException} */ (err)));
+    top = w;
   } catch (err) {
-    onError(/** @type {NodeJS.ErrnoException} */ (err));
+    rootFailed(/** @type {NodeJS.ErrnoException} */ (err));
   }
 
   let entries = [];