@webjsdev/server 0.8.91 → 0.10.0

package/src/dev/helpers.js

@@ -203,8 +203,8 @@ export const MIME = {
  * The transformed bytes are cached per request handler in `state.tsCache`
  * (a `Map<string, { mtimeMs, code, map }>`), bounded to `TS_CACHE_MAX`
  * entries. The cache is per-handler rather than module-global because the
- * cached code bakes in that handler's elision verdict, so two handlers for
- * the same app with different elision settings must not share it.
+ * cached code bakes in that handler's lazy-component set, so two handlers for
+ * the same app at different moments must not share it.
  */
 export const TS_CACHE_MAX = 500;
 
@@ -245,42 +245,6 @@ export function shouldAccessLog(pathname) {
   return !pathname.startsWith('/__webjs/');
 }
 
-/**
- * Auto-load `<appDir>/.env` into `process.env` once at boot. Mirrors
- * what Rails / Next / Astro do out of the box: a scaffolded app with
- * a committed `.env.example` and a developer-copied `.env` should
- * "just work" without the user having to add a dotenv import or set
- * the file path on the CLI.
- *
- * Uses Node 24+'s built-in `process.loadEnvFile`, which is dotenv-
- * compatible and DOES NOT override pre-existing `process.env` values.
- * Calls that hit a missing file or parse error are silenced; the
- * server should still come up cleanly when there's no `.env`.
- *
- * Idempotent: re-running is a no-op for any env var the user already
- * exported (e.g. via the host shell or a process manager). That
- * keeps the "shell-set wins over file" precedence Rails users
- * expect.
- *
- * Must run before any server-only module is loaded by
- * buildActionIndex, since module-init code in `lib/*.server.ts`
- * (e.g. `createAuth({ secret: process.env.AUTH_SECRET })`) reads
- * process.env at import time. createRequestHandler is the
- * single entry point where this is guaranteed.
- *
- * @param {string} appDir
- */
-export function loadAppEnv(appDir) {
-  try {
-    if (typeof process.loadEnvFile === 'function') {
-      process.loadEnvFile(join(appDir, '.env'));
-    }
-  } catch {
-    // No .env file, malformed file, or Node version without
-    // loadEnvFile. Either way, fall through silently: the user
-    // may not need any env vars, or they may set them via shell.
-  }
-}
 
 /**
  * Walk the route table + component scanner to collect every file the
@@ -317,25 +281,6 @@ export function loadAppEnv(appDir) {
  * @param {string} appDir
  * @returns {Set<string>}
  */
-/**
- * Collect every page + layout file across the route table. These are the
- * modules the client boot script imports, and thus the candidates for
- * inert-route elision (dropping a module that does no client work).
- * `route.{js,ts}` / middleware / metadata are excluded: they never ship.
- *
- * @param {Awaited<ReturnType<typeof buildRouteTable>>} routeTable
- * @returns {string[]}
- */
-export function collectRouteModules(routeTable) {
-  /** @type {Set<string>} */
-  const mods = new Set();
-  for (const page of routeTable.pages || []) {
-    if (page.file) mods.add(page.file);
-    for (const f of page.layouts || []) mods.add(f);
-  }
-  return [...mods];
-}
-
 /**
  * List the app's top-level source directory names, for expanding a `#*`
  * catch-all import alias into one browser importmap prefix scope per dir (#555).
@@ -421,6 +366,21 @@ const RELOAD_WORKER_SRC = readFileSync(new URL('../dev-reload-worker.js', import
 const DEV_STYLES_SRC = readFileSync(new URL('../dev-styles.js', import.meta.url), 'utf8')
   .replace(/^export /gm, '');
 
+// The component hot swap (#1689), same shared-source rule. It installs the
+// template interner and the class patcher core reads, so the reload client
+// must evaluate before the page's boot script (`ssr/head.js` orders them).
+const DEV_HOT_CLIENT_SRC = readFileSync(new URL('../dev-hot-client.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
+// The readiness probe every reload waits on (#893, #1689), same shared-source
+// rule.
+const DEV_READY_PROBE_SRC = readFileSync(new URL('../dev-ready-probe.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
+// Why a full reload happened, printed after it (#1689), same shared-source rule.
+const DEV_RELOAD_REASON_SRC = readFileSync(new URL('../dev-reload-reason.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
 // The embed host's reload hold (#1532), same shared-source rule.
 const DEV_RELOAD_HOLD_SRC = readFileSync(new URL('../dev-reload-hold.js', import.meta.url), 'utf8')
   .replace(/^export /gm, '');
@@ -481,10 +441,20 @@ export function reloadClientJs(bp) {
   const workerUrl = JSON.stringify(withBasePath('/__webjs/reload-worker.js', bp));
   const versionUrl = JSON.stringify(withBasePath('/__webjs/version', bp));
   return `// webjs dev reload client
+${DEV_HOT_CLIENT_SRC}
+var __webjsHot = installHotClient(globalThis);
 ${DEV_OVERLAY_SRC}
 ${RELOAD_WORKER_SRC}
 ${DEV_STYLES_SRC}
 ${DEV_RELOAD_HOLD_SRC}
+${DEV_READY_PROBE_SRC}
+${DEV_RELOAD_REASON_SRC}
+// Every full reload goes through here, so the reloaded page can say why
+// (#1689); the reason a previous page stored is printed once, now.
+function __webjsStore() { try { return globalThis.sessionStorage || null; } catch (_) { return null; } }
+function __webjsInfo(msg) { console.info(msg); }
+function __webjsReload(verdict) { reloadWithReason(verdict, location, __webjsStore(), __webjsInfo); }
+printPendingReason(__webjsStore(), __webjsInfo);
 // A framing host holds reloads while its agent builds (#1532): the embed bridge
 // sets __webjsEmbedHold, every signal below is kept (strongest verdict wins),
 // and releasing the hold applies that one reload, or none if nothing changed.
@@ -499,54 +469,66 @@ function __webjsApplyError(data) {
 // frame that arrived before the URL advanced goes up once it does. The gate
 // itself lives inside renderDevOverlay, so __webjsApplyError needs no change.
 installDevOverlayNavSync();
-// Never reload INTO a server that is still restarting (Node's node --watch
-// briefly kills the process on an edit), which would paint a style-less,
-// half-rendered page (#893). Probe the lightweight /__webjs/version endpoint
-// until it answers, THEN reload. Under an in-process reload the server is up,
-// so the first probe passes and the reload is instant; under a restart the
-// probes fail until the fresh server is listening, so the old page stays put
-// until the new one is ready. Bounded, so a genuinely-dead server still
-// reloads (and shows the browser's own error) rather than hanging forever.
-function __webjsWhenReady(then) {
-  var tries = 0;
-  function attempt() {
-    fetch(${versionUrl}, { cache: 'no-store' }).then(function (r) {
-      if (r && r.ok) then(); else again();
-    }).catch(again);
-  }
-  function again() { if (++tries > 100) location.reload(); else setTimeout(attempt, 100); }
-  attempt();
+// Never reload INTO a server that is still restarting (a restart file's edit,
+// a crash), which would paint a style-less, half-rendered page (#893). Probe
+// the lightweight /__webjs/version endpoint until it answers, THEN apply.
+// Under an in-process reload the server is up, so the first probe passes and
+// the apply is instant; under a restart the old page stays put until the new
+// server is ready, however long that takes (#1689: it used to give up after
+// about 10 seconds and reload into the browser's error page). One probe loop
+// at a time, so a burst of signals during a restart joins it.
+var __webjsWhenReady = createReadyProbe(function (u, o) { return fetch(u, o); }, ${versionUrl});
+// A relay message's verdict as an object (#1689). A SharedWorker another tab
+// started before an upgrade can still be alive and posts the bare verdict name,
+// so a string becomes { v }, and anything unreadable is a full reload.
+function __webjsVerdictOf(v) {
+  if (typeof v === 'string') return { v: v, by: '', why: '', modules: [], css: false };
+  return v && typeof v === 'object' ? v : { v: 'reload', by: '', why: 'unreadable-frame', modules: [], css: false };
 }
 // Apply a reload signal at the lightest correct weight (#1398). A page or
 // layout edit never changes browser-bound JS, so the server's re-render is the
 // complete truth and the client router can swap it in place: scroll and (for a
 // page edit) the hydrated state of components outside the changed region
-// survive. Anything else, including every signal the server could not classify,
-// is the full reload this always was.
+// survive. A \`component\` verdict (#1689) re-imports the versioned component
+// modules it lists, which patch the registered classes in place, so the live
+// elements keep their state. A \`css\` verdict re-requests the stylesheets and
+// swaps them in, with no re-render at all. Anything else, including every signal
+// the server could not classify, is the full reload this always was.
 function __webjsApplyReload(verdict) {
   if (__webjsHold.offer(verdict)) return;
   __webjsWhenReady(function () {
+    var mods = verdict.modules || [];
+    if (verdict.v !== 'reload' && mods.length) { __webjsApplyHot(verdict, mods); return; }
+    if (verdict.v === 'css') {
+      // Every same-origin sheet, not just the edited file, so an @import-ed
+      // partial and a webjs.dev.regenerate output (Tailwind) come out right.
+      // The clone-swap keeps the working sheet when a re-request fails.
+      preloadStyles().then(function (styles) {
+        styles.commit();
+        console.info('[webjs] stylesheets refreshed' + (verdict.by ? ' (' + verdict.by + ')' : ''));
+      }).then(null, function () { __webjsReload({ why: 'styles-failed', by: verdict.by }); });
+      return;
+    }
     // Runtime feature detection, never an assumption. The refresh entry is
     // published by enableClientRouter and removed by disableClientRouter, so its
     // ABSENCE covers both no-router cases at once: an app that opted out with
     // \`webjs.clientRouter: false\`, and a page that ships no component at all so
     // @webjsdev/core never loads in the browser and the module never runs.
     var refresh = globalThis.__webjsRefreshPage;
-    if ((verdict === 'page' || verdict === 'shell') && typeof refresh === 'function') {
-      // Take any error overlay down BEFORE re-rendering. DEFENSIVE, and the
-      // reasoning is worth recording because the obvious scenario for it does
-      // NOT hold. The overlay's own teardown is keyed on the URL CHANGING,
-      // which a same-url refresh never does, so a refresh has no exit for a
-      // live overlay the way a full reload did (it replaced the document).
+    var mode = verdict.v;
+    if ((mode === 'page' || mode === 'shell') && typeof refresh === 'function') {
+      // Take any error overlay down BEFORE re-rendering. The overlay's own
+      // teardown is keyed on the URL CHANGING, which a same-url refresh never
+      // does, so a refresh has no exit for a live overlay the way a full reload
+      // did (it replaced the document).
       //
-      // The scenario that looks like it needs this, a page-render error, is not
-      // reachable: the dev 500 page carries no children boundaries and no
-      // layout, so applying it shares no boundary with the live page and
-      // degrades to a hard navigation, in BOTH directions. Breaking a page
-      // reloads, and so does fixing it, and the reload clears the overlay. What
-      // is left is the narrow case of an UNSCOPED frame (a \`rebuild\` or
-      // \`ts-strip\` failure), which the nav sync deliberately never clears and
-      // which can coexist with a page that still renders and so still refreshes.
+      // A page-render error is the main case (#1689). Its response is marked
+      // \`x-webjs-dev-error\`, so the refresh that hits it leaves the last good
+      // page on screen under the overlay instead of applying the error page,
+      // and the edit that FIXES it refreshes in place, which is when this
+      // takes the overlay down. An UNSCOPED frame (a \`rebuild\` or
+      // \`ts-strip\` failure), which the nav sync deliberately never clears, is
+      // the other.
       //
       // Before rather than after, so the ordering is self-correcting: if this
       // render also fails, the server pushes a fresh frame DURING it and the
@@ -558,16 +540,65 @@ function __webjsApplyReload(verdict) {
       // seconds, and markup swapped in before it lands paints a new class with
       // no rule. The old sheets stay applied until the swap, then go.
       preloadStyles().then(function (styles) {
-        return refresh(verdict).then(function (ok) {
-          if (!ok) { location.reload(); return; }
+        return refresh(mode).then(function (outcome) {
+          if (!outcome || outcome === 'failed') { __webjsReload({ why: 'refresh-failed', by: verdict.by }); return; }
           styles.commit();
+          __webjsLogRefresh(outcome, mode, verdict.by);
         });
-      }).then(null, function () { location.reload(); });
+      }).then(null, function () { __webjsReload({ why: 'refresh-failed', by: verdict.by }); });
       return;
     }
-    location.reload();
+    // The reloaded page says why (#1689): the server's reason (a component
+    // edit the hot swap refused names its guard, such as constructor-changed),
+    // or that this page has no client router to apply a refresh with.
+    __webjsReload(mode === 'page' || mode === 'shell' ? { why: 'no-client-router', by: verdict.by } : verdict);
   });
 }
+// Apply a verdict that carries component modules (#1689): load the rebuilt
+// stylesheets, re-import the modules (each re-define patches its registered
+// class and re-renders the live elements), then re-render the page for a
+// \`page\` / \`shell\` verdict in the same batch, then swap the sheets. A
+// refused swap (a guard the hot client checks, a module that fails to load)
+// reloads and says why.
+function __webjsApplyHot(verdict, mods) {
+  var refresh = globalThis.__webjsRefreshPage;
+  var mode = verdict.v;
+  var by = verdict.by ? ' (' + verdict.by + ')' : '';
+  function reload(why) { __webjsReload({ why: why, by: verdict.by }); }
+  if ((mode === 'page' || mode === 'shell') && typeof refresh !== 'function') { reload('no-client-router'); return; }
+  // A page / shell refresh re-raises an error that still stands (see the
+  // refresh path above), so it may dismiss first. A component-only swap
+  // re-renders nothing on the server, so it takes down only an overlay the
+  // swap settled: the edited file, a re-imported module, or a rebuild error.
+  if (mode === 'page' || mode === 'shell') dismissDevOverlay();
+  else {
+    var bp = ${JSON.stringify(bp || '')};
+    dismissDevOverlayCoveredBy(mods.map(function (u) {
+      var p = String(u).split('?')[0];
+      return bp && p.indexOf(bp + '/') === 0 ? p.slice(bp.length) : p;
+    }).concat(verdict.by ? ['/' + verdict.by] : []));
+  }
+  preloadStyles().then(function (styles) {
+    return __webjsHot.applyModules(mods).then(function (r) {
+      if (!r.ok) { reload(r.why); return; }
+      var after = mode === 'page' || mode === 'shell' ? refresh(mode) : Promise.resolve('applied');
+      return after.then(function (outcome) {
+        if (!outcome || outcome === 'failed') { reload('refresh-failed'); return; }
+        styles.commit();
+        console.info('[webjs] hot-swapped ' + (r.tags.length ? r.tags.map(function (t) { return '<' + t + '>'; }).join(', ') : 'nothing') + by);
+        if (outcome === 'dev-error') __webjsLogRefresh(outcome, mode, verdict.by);
+      });
+    });
+  }).then(null, function (e) { reload(String((e && e.message) || e)); });
+}
+// The one console line an in-place refresh leaves (#1689). A refresh the dev
+// server answered with a render error applied nothing, so it must not claim the
+// page was updated: the last good render is still on screen under the overlay.
+function __webjsLogRefresh(outcome, mode, by) {
+  var file = by ? ' (' + by + ')' : '';
+  if (outcome === 'dev-error') { console.info('[webjs] the page did not render, so the last good version stays under the error overlay' + file); return; }
+  console.info('[webjs] ' + (mode === 'shell' ? 'layout' : 'page') + ' updated in place' + file);
+}
 function __webjsDirectEvents() {
   // No SharedWorker (Chrome for Android has none) or its construction threw (a
   // strict dev CSP with no worker-src). Run the SAME relay here in the tab over
@@ -594,7 +625,7 @@ function __webjsDirectEvents() {
     // dev-overlay bug leaves no trace, which would be a new behaviour rather
     // than a restored one.
     try {
-      if (m.type === 'reload') __webjsApplyReload(m.verdict);
+      if (m.type === 'reload') __webjsApplyReload(__webjsVerdictOf(m.verdict));
       else if (m.type === 'webjs-error') __webjsApplyError(m.data);
     } catch (_) {
       console.error('[webjs] dev reload handler threw', _);
@@ -657,7 +688,7 @@ try {
     const w = new SharedWorker(${workerUrl});
     w.port.onmessage = (e) => {
       const m = e.data || {};
-      if (m.type === 'reload') __webjsApplyReload(m.verdict);
+      if (m.type === 'reload') __webjsApplyReload(__webjsVerdictOf(m.verdict));
       else if (m.type === 'webjs-error') __webjsApplyError(m.data);
     };
     // The worker's SCRIPT can fail to load where the page itself loaded: a

package/src/dev/hot-host.js

@@ -36,12 +36,37 @@ import { pathToFileURL } from 'node:url';
 const HOSTS = Symbol.for('webjs.dev.hotHosts');
 
 /**
- * Sent to the `webjs dev` supervisor over IPC once the hot host is up, so it
- * stops restarting the process for plugin-served edits this server now reloads
- * in place. Mirrors `HOT_IN_PLACE_MESSAGE` in `@webjsdev/cli`'s `dev-reload.js`.
+ * Sent to the `webjs dev` supervisor over IPC once the server is up and able
+ * to reload app edits in place: the Bun hot host (plugin-served edits, #1575),
+ * or a Node server with the module resolve hook (`esm-hot-hooks.js`, #1689).
+ * The supervisor then restarts only for its restart files. Mirrors
+ * `HOT_IN_PLACE_MESSAGE` in `@webjsdev/cli`'s `dev-reload.js`.
  */
 export const HOT_IN_PLACE_MESSAGE = 'hot-reload-in-place';
 
+/**
+ * Sent to the `webjs dev` supervisor to restart this server for an edit it
+ * cannot apply in place (#1689): a module the CommonJS loader holds, which no
+ * version reaches. The restart is the reload. Mirrors `HOT_RESTART_MESSAGE` in
+ * `@webjsdev/cli`'s `dev-reload.js`.
+ */
+export const HOT_RESTART_MESSAGE = 'hot-reload-restart';
+
+/**
+ * Ask the supervisor (when there is one) to restart for `path`, app-relative.
+ * @param {string} path
+ * @returns {boolean} whether the request was sent
+ */
+export function requestSupervisorRestart(path) {
+  try {
+    if (typeof process.send === 'function' && process.connected) {
+      process.send({ webjs: HOT_RESTART_MESSAGE, path });
+      return true;
+    }
+  } catch { /* no supervisor, or it is gone */ }
+  return false;
+}
+
 /** Tell the supervisor (when there is one) that edits reload in place. */
 export function announceHotInPlace() {
   try {
@@ -157,9 +182,11 @@ const INERT_ASSET = /\.(?:css|md|mdx|txt|log|map|png|jpe?g|gif|webp|avif|ico|svg
  * plugin, the rest through `dev/bun-app-source.js` or the source-locations
  * plugin), which `bun --hot` never watches.
  *
- * `isRouteOnly` answers whether a module path is one only the router loads
- * (nothing imports it; see `needsRegistryReset` on the request handler): its
- * dev re-import is keyed by content, so it needs no reset. Anything the
+ * `isRouteOnly` answers whether a module path needs no reset (see
+ * `needsRegistryReset` on the request handler): a module the dev plugins
+ * already served, which the module versions re-evaluate in place with its
+ * importers (#1689), or a module only the router loads, whose dev re-import is
+ * keyed by content. A new or deleted module still resets. Anything the
  * dev server cannot place, such as the extensionless temp file `sed -i`
  * renames over the real one, gets the reset, because the event may name the
  * temp file rather than the module it replaced.

package/src/dev/poke-state.js

@@ -0,0 +1,110 @@
+import { mergeVerdicts } from '../dev-classify.js';
+
+/**
+ * The edits a `bun --hot` registry reset has yet to apply (#1575, #1689).
+ *
+ * Under `bun --hot` an edit to a module some other module imports cannot be
+ * rebuilt straight away: the module registry has to be reset first, or the next
+ * request would still import the stale module. So the watcher POKES the re-run
+ * sentinel, keeps the batch here, and the re-run rebuilds with it. If the
+ * re-run does not arrive within `fallbackMs`, the fallback rebuilds anyway, so
+ * an edit is never lost to a sentinel `bun --hot` did not see.
+ *
+ * The race this owns: a large edit can make the re-run arrive AFTER the
+ * fallback. The fallback rebuilt and notified against the PRE-reset registry,
+ * so the browser applied the edit against stale modules, and the late re-run
+ * found nothing pending and rebuilt silently, so the tab never learned the
+ * fresh modules were there. The fallback's batch is therefore kept as `fired`,
+ * and a re-run with nothing pending rebuilds and notifies again with it.
+ *
+ * `fired` lives only `firedMs` (twice the fallback by default) past the
+ * fallback. A re-run that late is not the one the batch was waiting for: the
+ * reset was genuinely lost, and replaying the batch into a later, unrelated
+ * edit would merge its old verdict in (an old `reload` turning a page morph
+ * into a full reload) and bump its files' versions a second time, dropping
+ * server module state for a chain nobody touched.
+ *
+ * @param {{
+ *   setTimeout?: (fn: () => void, ms: number) => unknown,
+ *   clearTimeout?: (t: unknown) => void,
+ *   fallbackMs?: number,
+ *   firedMs?: number,
+ * }} [opts]
+ */
+export function createPokeState(opts = {}) {
+  const set = opts.setTimeout || ((fn, ms) => setTimeout(fn, ms));
+  const clear = opts.clearTimeout || ((t) => clearTimeout(/** @type {any} */ (t)));
+  const fallbackMs = opts.fallbackMs ?? 1500;
+  const firedMs = opts.firedMs ?? fallbackMs * 2;
+  /** @type {import('../dev-classify.js').ReloadVerdict | null} */
+  let verdict = null;
+  /** @type {Set<string>} */
+  let changed = new Set();
+  /** @type {{ verdict: import('../dev-classify.js').ReloadVerdict | null, changed: string[] } | null} */
+  let fired = null;
+  /** @type {unknown} */
+  let timer = null;
+  /** @type {unknown} */
+  let firedTimer = null;
+  const dropFired = () => {
+    clear(firedTimer);
+    firedTimer = null;
+    fired = null;
+  };
+
+  return {
+    /**
+     * Keep a batch for the coming re-run and (re)arm the fallback.
+     * @param {import('../dev-classify.js').ReloadVerdict | null | undefined} v
+     * @param {Iterable<string>} files
+     * @param {(verdict: import('../dev-classify.js').ReloadVerdict | null, changed: string[]) => void} onFallback
+     */
+    poke: function (v, files, onFallback) {
+      verdict = mergeVerdicts(verdict, v || null);
+      for (const f of files) changed.add(f);
+      // A fresh poke inside the fired batch's window supersedes it: the
+      // coming re-run carries both, so the browser hears once, at the end.
+      if (fired) {
+        verdict = mergeVerdicts(fired.verdict, verdict);
+        for (const f of fired.changed) changed.add(f);
+        dropFired();
+      }
+      clear(timer);
+      timer = set(() => {
+        timer = null;
+        const batch = { verdict, changed: [...changed] };
+        verdict = null;
+        changed = new Set();
+        dropFired();
+        fired = batch;
+        firedTimer = set(dropFired, firedMs);
+        onFallback(batch.verdict, batch.changed);
+      }, fallbackMs);
+    },
+
+    /**
+     * What a registry-reset re-run should rebuild with: the pending batch when
+     * there is one, else the batch the fallback already applied against the old
+     * registry (notify again so the tab picks up the fresh modules), else
+     * nothing, a silent re-derive.
+     * @returns {{ verdict: import('../dev-classify.js').ReloadVerdict | null, changed: string[], notify: boolean }}
+     */
+    takeForRerun: function () {
+      clear(timer);
+      timer = null;
+      if (verdict || changed.size) {
+        const out = { verdict, changed: [...changed], notify: !!verdict };
+        verdict = null;
+        changed = new Set();
+        dropFired();
+        return out;
+      }
+      if (fired) {
+        const out = { verdict: fired.verdict, changed: fired.changed, notify: !!fired.verdict };
+        dropFired();
+        return out;
+      }
+      return { verdict: null, changed: [], notify: false };
+    },
+  };
+}