fix: keep classifying after a rebuild, and stop claiming an uncommitted swap

The feature turned itself off for every edit after the first in a burst.
doRebuild invalidates the lazy analysis, nothing re-warms it until an
HTTP request arrives, and the relay defers that request by its 2000ms
quiet window while the measured inter-save gap is about a second. So the
second save classified analysis-cold and the strongest-verdict rule
collapsed the whole batch to a full reload. The gate now reads whether
the derived sets are POPULATED rather than whether they are current,
which is what the rest of the code already assumed: classifying against
the previous build's graph is intended, and it is conservative in the
right direction, since a file that graph has never seen falls through to
a reload.

applySwap returns without committing on four paths (a missing frame, and
three degradations to a hard navigation), and all four still reported
applied true, which is the hole the flag exists to close. They return a
sentinel now and fetchAndApply maps it.

Three doc corrections. The gallery copy described a counter that is not
on that page. The skill reference kept the direct CLI invocation the
website copy had already dropped. And both runtime surfaces listed five
watched directories while the supervisor also watches root middleware,
so a middleware edit is a full reload rather than the in-place refresh
they implied.

Author: vivek7405

.agents/skills/webjs/references/runtime.md

@@ -40,7 +40,7 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 
 **The in-place dev refresh (#1398) needs the server process to SURVIVE the edit,** which is the whole of the Node-versus-Bun difference in that row. A page or layout never hydrates, so a freshly rendered page is the complete truth for it and the client router can swap it in without a reload, keeping scroll and (for a page edit) the hydrated state of components outside the changed region. The server classifies the changed file and puts the verdict on the live-reload event, so this needs a process that is still alive to do the classifying.
 
-Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. Node's `bun --hot` equivalent is `node --watch`, which RESTARTS the process on a change under `app`, `components`, `modules`, `lib`, or `actions`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE those five dirs (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `webjs dev --no-hot`, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
+Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. Node's `bun --hot` equivalent is `node --watch`, which RESTARTS the process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
 
 The 103 Early Hints gap costs only a small first-load latency edge where an edge proxy forwards the 103, never correctness. The `modulepreload` hints still ship in the document head on both runtimes.
 

gallery/modules/client-router/components/router-controls.ts

@@ -49,8 +49,9 @@ export class RouterControls extends WebComponent {
         </div>
         <p class="text-sm text-muted-foreground">
           refreshPage() re-renders THIS url on the server and swaps it in.
-          The server time above updates, the counter below keeps counting, and
-          your scroll position does not move.
+          The server time above updates, and your scroll position does not
+          move. On a page with hydrated components outside the swapped region,
+          their state survives too.
         </p>
         <p class="text-sm text-muted-foreground">
           Plain link:

packages/core/src/router-client.js

@@ -2958,9 +2958,11 @@ function handleNavigationError(href, status, error) {
  *   behaviour, so a page rendered through `notFound()`, `forbidden()`, or an
  *   `error.ts` boundary has `ok:false` and `applied:true`. It is `false`
  *   wherever no swap committed: a transport failure, a non-HTML body, an
- *   unparseable one, a 204/205, a discarded revalidation, and an abort. A
- *   caller deciding whether to fall back to a full page load wants `applied`;
- *   one reporting the submission's success wants `ok`.
+ *   unparseable one, a 204/205, a discarded revalidation, an abort, and every
+ *   `applySwap` path that returns without committing (a missing frame, or a
+ *   degradation to a hard navigation from an importmap mismatch or a poisoned
+ *   boundary scan). A caller deciding whether to fall back to a full page load
+ *   wants `applied`; one reporting the submission's success wants `ok`.
  */
 async function fetchAndApply(href, frameId, recordHistory, optimisticState, method, body, signal, token, revalidating, refresh) {
   method = method || 'GET';
@@ -3163,6 +3165,12 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
   if (!doc) { restoreOptimistic(optimisticState); handleNavigationError(href, null, new Error('navigation response did not parse as HTML')); return { ok: false, status: respStatus, aborted: false, applied: false }; }
 
   const disposition = applySwap(doc, frameId, !!revalidating, finalUrl, incomingBuild, incomingSrc, refresh);
+  // `'none'` means applySwap returned WITHOUT committing anything: the frame the
+  // response was for is missing, or it degraded to a hard navigation (an
+  // importmap/build mismatch, a poisoned boundary scan). The page is not left
+  // in a bad state either way, but nothing was applied IN PLACE, and `applied`
+  // has to say so or it repeats the hole it exists to close.
+  if (disposition === 'none') return { ok: respOk, status: respStatus, aborted: false, applied: false };
   // A discarded revalidation must be discarded OUTRIGHT: a streamed response's
   // boundary templates must not splice into the restored snapshot afterward
   // (boundary ids are per-render sequential, so a reduced render's numbering
@@ -3694,6 +3702,11 @@ let _swapCommit = Promise.resolve();
  * @param {string | null} href
  * @param {string | null} [incomingBuild]
  * @param {string | null} [incomingSrc]
+ * @returns {'discard' | 'none' | undefined} `'discard'` when a background
+ *   revalidation was thrown away, `'none'` when it returned without committing
+ *   anything (a missing frame, or a degradation to a hard navigation), and
+ *   `undefined` when a swap committed. `fetchAndApply` maps the first two to
+ *   `applied: false`.
  * @param {'page' | 'shell' | undefined} [refresh]  same-URL in-place refresh
  *   mode (#1398). `'shell'` takes the full-body tier directly, because the
  *   layout's OWN markup changed and that lives outside every children range.
@@ -3836,14 +3849,14 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc,
           if (sessionStorage) sessionStorage.setItem(flag, '1');
           reportFallback('deploy-mismatch', href);
           hardNavigate(href);
-          return;
+          return 'none';
         }
       } catch {
         // sessionStorage unavailable (private mode w/ quota etc.):
         // fall through to a single reload like before.
         reportFallback('deploy-mismatch', href);
         hardNavigate(href);
-        return;
+        return 'none';
       }
     } else if (!mismatch) {
       // No importmap/build mismatch, so no hard reload. But the app-source
@@ -3925,7 +3938,7 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc,
     if (!evt.defaultPrevented) {
       console.warn(`[webjs] frame "${frameId}" was not in the navigation response, leaving it unchanged. Handle "webjs:frame-missing" (preventDefault) to override.`);
     }
-    return;
+    return 'none';
   }
 
   // 1b. Same-URL refresh in `shell` mode (#1398). A boundary morph can only
@@ -4001,7 +4014,7 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc,
       : !there ? 'incoming-boundaries-malformed'
       : 'no-shared-boundary', href);
     hardNavigate(href);
-    return;
+    return 'none';
   }
 
   // A BACKGROUND revalidation (revalidating + href) with no trustworthy plan

packages/server/src/dev-classify.js

@@ -85,13 +85,19 @@ function verdictRank(v) {
  *
  * The ladder, first match wins:
  *
- * 1. The analysis is cold, so nothing is known yet. Fail safe. This mirrors
- *    Vite's pessimistic seed (`needFullReload = modules.length === 0`). A
- *    rebuild invalidates the lazy analysis, so this rung is live between a
- *    rebuild and the next request. In practice the reload or in-place refresh
- *    each verdict produces IS that request, so the analysis is warm again well
- *    before the next edit lands, and the rung only catches an edit that beat
- *    the browser to it.
+ * 1. The analysis has NEVER completed, so nothing is known yet. Fail safe. This
+ *    mirrors Vite's pessimistic seed (`needFullReload = modules.length === 0`).
+ *    In practice this is the window between boot and the first request.
+ *
+ *    `analysisReady` deliberately means "the sets are POPULATED", not "they are
+ *    current". A rebuild invalidates the lazy analysis and nothing re-warms it
+ *    until an HTTP request arrives, while the relay defers that request by its
+ *    2000ms quiet window (#1397), which is longer than the measured inter-save
+ *    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
+ *    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
  *    content the server reads at render time, never a browser module. It can

packages/server/src/dev.js

@@ -907,6 +907,16 @@ export async function createRequestHandler(opts) {
   // platform's traffic and probes are the retry loop. `readyError` holds a
   // propagating analysis failure so /__webjs/ready can report it.
   let analysisDone = false;        // deterministic analysis complete (readiness gate)
+  // Whether the analysis has EVER completed (#1398). Distinct from
+  // `analysisDone`, which `doRebuild` flips false on every edit: the live-reload
+  // classifier needs to know the derived sets are POPULATED, not that they are
+  // current, because it deliberately classifies against the previous build's
+  // graph (see the note in `doRebuild`). Gating it on `analysisDone` turned the
+  // feature off for every edit after the first in a burst, since nothing
+  // re-warms the analysis until an HTTP request arrives and the relay defers
+  // that request by its 2000ms quiet window (#1397), which is longer than the
+  // measured inter-save gap. Never reset.
+  let analysisEverDone = false;
   // A pinned app applied its FULL vendor map and published the build id at boot
   // (above). The deferred vendor stage still runs once (and after every rebuild)
   // to PRUNE that map to the elision-reachable specifiers, so a pinned app serves
@@ -1102,6 +1112,7 @@ export async function createRequestHandler(opts) {
               );
             }
             analysisDone = true;
+            analysisEverDone = true;
             ranAnalysis = true;
           }
           readyError = null;
@@ -1753,7 +1764,7 @@ export async function createRequestHandler(opts) {
       shippedFiles: state.shippedFiles,
       graphFiles: state.graphFiles,
       pageFiles: state.pageFiles,
-      analysisReady: analysisDone,
+      analysisReady: analysisEverDone,
       sep,
     }),
     appDir,

packages/server/test/dev/classify-live.test.js

@@ -138,6 +138,54 @@ Counter.register('my-counter');
   assert.equal(v.why, 'ships-to-browser');
 });
 
+// THE burst regression. A rebuild invalidates the lazy analysis, and nothing
+// re-warms it until an HTTP request arrives, which the relay defers by its
+// 2000ms quiet window (#1397) while the measured inter-save gap is about a
+// second. So gating the classifier on "the analysis is CURRENT" turned the
+// feature off for every edit after the first in a burst: the second save
+// classified `analysis-cold` and the strongest-verdict rule collapsed the whole
+// batch to a full reload. It is gated on "the sets are POPULATED" instead.
+//
+// Every other case here warms with a fetch before its single edit, so none of
+// them can see this; the second edit has to land with no request in between.
+test('a SECOND edit with no request in between still classifies (the burst case)', async () => {
+  const appDir = scaffold();
+  const srv = await startServer({ appDir, port: 0, dev: true });
+  const port = srv.server.address().port;
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/`);
+    assert.equal(res.status, 200);
+    await res.text();
+
+    const first = waitForReloadFrame(port, 6000);
+    await sleep(150);
+    writeFileSync(join(appDir, 'app/page.js'), `
+import { html } from '@webjsdev/core';
+import '../components/counter.js';
+export default function Page() {
+  return html\`<main>EDIT_ONE<my-counter></my-counter></main>\`;
+}
+`);
+    assert.equal(JSON.parse(await first).v, 'page', 'the first edit classifies');
+
+    // No fetch here on purpose: this is what a burst looks like.
+    const second = waitForReloadFrame(port, 6000);
+    await sleep(150);
+    writeFileSync(join(appDir, 'app/page.js'), `
+import { html } from '@webjsdev/core';
+import '../components/counter.js';
+export default function Page() {
+  return html\`<main>EDIT_TWO<my-counter></my-counter></main>\`;
+}
+`);
+    const v = JSON.parse(await second);
+    assert.equal(v.v, 'page', 'and so does the second, against the previous build\'s graph');
+    assert.equal(v.why, 'page-module', 'rather than falling back to analysis-cold');
+  } finally {
+    await srv.close();
+  }
+});
+
 test('a LAYOUT edit rides a `shell` verdict, because its own markup is outside every children range', async () => {
   const appDir = scaffold();
   const v = await verdictForEdit(appDir, 'app/layout.js', `

website/app/docs/runtime/page.ts

@@ -32,7 +32,7 @@ export default function Runtime() {
       </tbody>
     </table>
     <p>The in-place dev refresh needs the server process to <strong>survive</strong> the edit, which is the whole of that last row. A page or layout never hydrates, so a freshly rendered page is the complete truth for it and the client router can swap it in without a reload, keeping your scroll position and the hydrated state of components outside the changed region. The server classifies the changed file and puts the verdict on the live-reload event, so it needs a process that is still alive to do the classifying.</p>
-    <p>Bun's <code>bun --hot</code> invalidates modules in place without restarting, so it gets the refresh. On Node, <code>node --watch</code> restarts the process on a change under <code>app</code>, <code>components</code>, <code>modules</code>, <code>lib</code>, or <code>actions</code>, and a fresh process holds no record of what changed, so those edits are a full reload. Two Node cases still refresh in place: an edit outside those five directories (<code>db/schema.server.ts</code>, a <code>webjs.dev.watch</code> content directory), and <code>npm run dev -- --no-hot</code>, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because <code>customElements.define</code> is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.</p>
+    <p>Bun's <code>bun --hot</code> invalidates modules in place without restarting, so it gets the refresh. On Node, <code>node --watch</code> restarts the process on a change under <code>app</code>, <code>components</code>, <code>modules</code>, <code>lib</code>, or <code>actions</code>, or to a root <code>middleware</code> file, and a fresh process holds no record of what changed, so those edits are a full reload. Two Node cases still refresh in place: an edit outside that watched set (<code>db/schema.server.ts</code>, a <code>webjs.dev.watch</code> content directory), and <code>npm run dev -- --no-hot</code>, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because <code>customElements.define</code> is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.</p>
 
     <p>Either way the <code>.ts</code> stripping is position-preserving with no sourcemap, and the bytes the browser fetches are identical. The 103 Early Hints gap only costs a small first-load latency edge where your edge forwards 103, never correctness (the modulepreload hints still ship in the document head).</p>