@webjsdev/server 0.8.91 → 0.9.0

package/src/component-elision.js

@@ -170,7 +170,7 @@ const STATIC_FIELD_REASONS = {
  * component with no OTHER client signal renders identical HTML with or
  * without its JS and is elidable like any display-only component, saving a
  * module download plus a redundant on-hydration re-fetch. It ships only when
- * it ALSO carries an independent signal: an `@event`, a non-`state` reactive
+ * it ALSO carries an independent signal: an `@event`, a declared reactive
  * prop, a reactive import, a lifecycle hook (`renderFallback()` included, via
  * CLIENT_LIFECYCLE_HOOKS), a `<slot>`, `static shadow = true`, `static
  * interactive = true`, cross-module observation, or a transitively-reachable
@@ -211,11 +211,11 @@ const escapeForCharClass = (c) => c.replace(/[\\\]^-]/g, '\\$&');
  * is classified above. (unquoted per invariant 4)
  */
 const EVENT_BINDING_RE = new RegExp(
-  `[${SSR_DROPPED_PREFIXES.map(escapeForCharClass).join('')}][A-Za-z][\\w-]*\\s*=\\s*\\$\\{`,
+  `[${SSR_DROPPED_PREFIXES.map(escapeForCharClass).join('')}][A-Za-z][\\w-]*\\s*=\\s*[\"']?\\$\\{`,
 );
 
 /** Match a `.onclick=${...}` (native event-handler property) binding. */
-const EVENT_PROP_RE = /\.on[a-z]+\s*=\s*\$\{/;
+const EVENT_PROP_RE = /\.on[a-z]+\s*=\s*["']?\$\{/;
 
 /**
  * Narrow dynamic-slot signals (#1015, retained under #1021's native-parity
@@ -247,7 +247,17 @@ const CLIENT_ROUTER_SUBPATH_RE = /['"]@webjsdev\/core\/client-router['"]/;
  */
 export const CLIENT_ROUTER_IMPORTS = ['navigate', 'enableClientRouter', 'disableClientRouter', 'revalidate', 'refreshPage', 'loadFrame'];
 
-/** Identifiers that only exist in a browser; their presence means client work. */
+/**
+ * Identifiers that only exist in a browser; their presence means client work.
+ * Both this and COMPONENT_CLIENT_GLOBAL_RE are tested against the
+ * PLACEHOLDER redaction (`redactToPlaceholders`), never against raw or
+ * comment-masked source: a quoted string body or a template literal's TEXT is
+ * data, not a reference, so `'lucide-app-window'` must not read as `window`,
+ * while code inside a `${...}` hole stays real code and still matches. A global
+ * written in template text is SSR output (an inline `<script>` runs from the
+ * served HTML whether or not the module ships), the reasoning #623 applied to
+ * route modules, now extended to every module.
+ */
 const CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|customElements|matchMedia|addEventListener)\b/;
 
 /**
@@ -268,6 +278,14 @@ const INSTANCEOF_RE = /\binstanceof\s+([A-Z][A-Za-z0-9_$]*)/g;
  * `customElements.define(...)` legitimately uses it and must not force ship). */
 const COMPONENT_CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|matchMedia|addEventListener)\b/;
 
+/**
+ * The same globals reached through a string key on the global object
+ * (`globalThis['matchMedia']`, `self["document"]`). The global scan reads the
+ * placeholder redaction, which blanks string literals, and `globalThis` itself
+ * exists on the server, so this one form has to be read from the RAW source.
+ */
+const COMPONENT_CLIENT_GLOBAL_KEY_RE = /\b(?:globalThis|self)\s*(?:\?\.)?\[\s*(['"`])(?:window|document|navigator|localStorage|sessionStorage|matchMedia|addEventListener)\1\s*\]/;
+
 /**
  * Constructors that produce inert DATA with no side effect, so a module-scope
  * `export const X = new Set([...])` (a lookup table, a compiled RegExp, a
@@ -528,7 +546,7 @@ export function hasModuleScopeSideEffect(src, literals) {
     // statement. Exempt it so a display-only factory-form component stays
     // elidable; a genuinely interactive one still ships via the per-class and
     // module-level signal checks below (events, slots, shadow, lifecycle, a
-    // non-state factory prop, a reactive import). Scoped to the `extends`
+    // declared factory prop, a reactive import). Scoped to the `extends`
     // position, so a top-level `WebComponent(...)` call used anywhere else
     // still counts as a side effect (#604).
     if (ident === 'WebComponent' && /\bextends\s+$/.test(frame.slice(0, m.index))) continue;
@@ -699,11 +717,13 @@ export function analyzeComponentSource(src) {
   // loads, and a browser global (window/document/…, excluding the
   // registration's customElements) means the module does client work even
   // if its render is otherwise pure. Eliding such a component would drop
-  // that effect, so ship. (Mirrors the route-module analysis.)
+  // that effect, so ship. (Mirrors the route-module analysis.) The global
+  // scan reads the placeholder redaction, so a name inside a string or in
+  // template text is not a reference, while one in a `${...}` hole still is.
   if (importsSideEffectNonCorePackage(src)) {
     return { interactive: true, reason: 'side-effect imports an npm package' };
   }
-  if (COMPONENT_CLIENT_GLOBAL_RE.test(src)) {
+  if (COMPONENT_CLIENT_GLOBAL_RE.test(redactToPlaceholders(src).redacted) || COMPONENT_CLIENT_GLOBAL_KEY_RE.test(src)) {
     return { interactive: true, reason: 'references a browser global at module scope' };
   }
   if (hasModuleScopeSideEffect(src)) {
@@ -744,10 +764,10 @@ export function analyzeComponentSource(src) {
         return { interactive: true, reason: `calls '${call}'` };
       }
     }
-    if (hasNonStateReactiveProperty(body) || hasNonStateFactoryProperty(factoryArg)) {
+    if (hasReactiveProperty(body) || hasFactoryProperty(factoryArg)) {
       return {
         interactive: true,
-        reason: 'declares a reactive property that is not { state: true }',
+        reason: 'declares a reactive property',
       };
     }
   }
@@ -834,113 +854,62 @@ function importsReactivePrimitive(src, literals) {
 
 /**
  * True if the class body declares a `static properties` block with any
- * entry that is NOT marked `{ state: true }`. Non-state reactive
- * properties ride an attribute or a `.prop` binding, the channel through
- * which a parent pushes updates, which is client-side reactivity.
+ * entry. A reactive property rides an attribute or a `.prop` binding, the
+ * channel through which a parent pushes updates, which is client-side
+ * reactivity. Internal state is a signal, not a declared property (the
+ * factory refuses a `state` option, #1677), so every entry counts.
  *
- * Conservative on parse failure: a `static get properties()` accessor or
- * an unbalanced object literal returns true (ship).
+ * Conservative on parse failure: a `static get properties()` accessor, a
+ * non-literal assignment, a spread, or an unbalanced object literal returns
+ * true (ship).
  *
  * @param {string} classBody
  * @returns {boolean}
  */
-function hasNonStateReactiveProperty(classBody) {
+function hasReactiveProperty(classBody) {
   // No reactive properties declared at all: nothing rides an attribute.
   if (!/\bstatic\s+(?:get\s+)?properties\b/.test(classBody)) return false;
-  // Properties ARE declared. We can only clear a component as inert when
-  // the declaration is a brace literal whose every entry is { state: true }.
   // A getter (`static get properties()`) or a non-literal assignment
-  // (`= buildProps()`, `= SHARED_PROPS`, `= Object.assign(...)`) cannot be
-  // parsed for state flags, so ship conservatively. `[^=]*` tolerates a TS
-  // type annotation between the name and `=` without crossing the `=`.
+  // (`= buildProps()`, `= SHARED_PROPS`) cannot be read, so ship
+  // conservatively. `[^=]*` tolerates a TS type annotation between the name
+  // and `=` without crossing the `=`.
   const m = /\bstatic\s+properties\b[^=]*=\s*\{/.exec(classBody);
   if (!m) return true;
   const objStart = m.index + m[0].length;
   const objEnd = matchClosingBrace(classBody, objStart);
   if (objEnd === -1) return true;
-  const obj = classBody.slice(objStart, objEnd);
-  // A spread (`...BASE_PROPS`) can inject reactive properties we cannot
-  // see; ship rather than guess they are all { state: true }.
-  if (/\.\.\./.test(obj)) return true;
-  for (const entry of topLevelPropertyValues(obj)) {
-    // Object-literal descriptor: inert only when it carries `state: true` at
-    // its top level (descriptorDeclaresState blanks strings and ignores a
-    // nested state flag, e.g. inside a converter, so it cannot be forged).
-    if (entry.startsWith('{')) {
-      if (!descriptorDeclaresState(entry)) return true;
-    } else {
-      // Shorthand like `count: Number` rides an attribute, not state.
-      return true;
-    }
-  }
-  return false;
+  return declaresAnyEntry(classBody.slice(objStart, objEnd));
 }
 
 /**
  * True if the class factory argument (`extends WebComponent({ … })`) declares
- * any reactive property that is NOT `{ state: true }`. A non-state property
- * rides an HTML attribute or a `.prop` hydration binding, the channel that
- * forces the component to ship; a `state: true` property is component-local
- * reactive state with no such channel, so a component whose only signal is
- * state props stays elidable.
- *
- * A property value is treated as state ONLY when its descriptor declares
- * `state: true` at the TOP LEVEL (see `descriptorDeclaresState`), which covers
- * the bare descriptor `{ state: true }` and the `prop()` helper forms
- * `prop({ state: true })` / `prop(Type, { state: true })`. Anything else (a bare
- * type `Number`, `prop(Number)`, an options object without `state: true`) is
- * non-state and ships. Conservative on a spread or an unbalanced brace (cannot
- * prove every entry is state, so ship).
+ * any reactive property. Each one rides an HTML attribute or a `.prop`
+ * hydration binding, the channel that forces the component to ship.
+ * Conservative on a spread or an unbalanced brace (ship).
  *
  * @param {string} factoryArg
  * @returns {boolean}
  */
-function hasNonStateFactoryProperty(factoryArg) {
+function hasFactoryProperty(factoryArg) {
   if (!factoryArg) return false;
   const objStart = factoryArg.indexOf('{');
   if (objStart === -1) return false;
   // matchClosingBrace starts at depth 1, so pass the index AFTER the brace.
   const objEnd = matchClosingBrace(factoryArg, objStart + 1);
   if (objEnd === -1) return true;
-  const obj = factoryArg.slice(objStart + 1, objEnd);
-  if (/\.\.\./.test(obj)) return true; // spread: cannot prove all entries state
-  for (const entry of topLevelPropertyValues(obj)) {
-    if (!descriptorDeclaresState(entry)) return true;
-  }
-  return false;
+  return declaresAnyEntry(factoryArg.slice(objStart + 1, objEnd));
 }
 
 /**
- * True if a reactive-property descriptor declares `state: true` at the TOP
- * LEVEL of its options object (brace-depth 1). Restricting to depth 1 is a
- * direction-of-safety fix: a `state: true` buried deeper (a converter /
- * hasChanged body that happens to return `{ state: true }`) must NOT forge the
- * flag, because wrongly treating an attribute-riding property as state would
- * ELIDE an interactive component and break the page. Strings / templates are
- * blanked first, so `attribute: 'data-state: true'` does not match, and the
- * `\b` word boundary keeps a key like `firstate: true` from matching. In every
- * legitimate shape (`{ state: true }`, `prop({ state: true })`,
- * `prop(Type, { state: true })`) the descriptor object is the only brace group,
- * so its `state` key sits at depth 1.
+ * True if a properties object body holds at least one entry. A spread
+ * (`...BASE_PROPS`) can inject entries we cannot see, so it counts.
  *
- * @param {string} entry  the property VALUE text
+ * @param {string} obj  the body between the outer braces
  * @returns {boolean}
  */
-function descriptorDeclaresState(entry) {
-  const code = entry
-    .replace(/'[^'\n]*'/g, "''")
-    .replace(/"[^"\n]*"/g, '""')
-    .replace(/`[^`]*`/g, '``');
-  // Keep only text at brace-depth <= 1 (the descriptor's own level); blank
-  // deeper nesting so a nested `state: true` cannot count.
-  let depth = 0;
-  let shallow = '';
-  for (const c of code) {
-    if (c === '{') { depth++; if (depth <= 1) shallow += c; continue; }
-    if (c === '}') { if (depth <= 1) shallow += c; if (depth > 0) depth--; continue; }
-    if (depth <= 1) shallow += c;
-  }
-  return /\bstate\s*:\s*true\b/.test(shallow);
+function declaresAnyEntry(obj) {
+  if (/\.\.\./.test(obj)) return true;
+  return topLevelPropertyValues(obj).length > 0;
 }
 
 /**
@@ -1196,7 +1165,9 @@ function scanFileUncached(file, src, { isRoute, isComponent, appDir, scanStrippe
   // `@event`, a browser global, an `import`, or a `whenDefined` written in a
   // comment must not register as a real signal. String and template content
   // is kept, so a real rendered tag, a real `@click=${}` in an html template,
-  // and a real `whenDefined('tag')` (the tag rides a string) still match.
+  // and a real `whenDefined('tag')` (the tag rides a string) still match. The
+  // browser-global scans are the exception: they read `redacted` below, since
+  // a global's name inside a string or template text is data, not a reference.
   // (`importsSideEffectNonCorePackage` / `hasModuleScopeSideEffect` /
   // `analyzeComponentSource` also redact strings/templates internally; running
   // them on the comment-masked source just additionally drops comment prose.)
@@ -1206,15 +1177,20 @@ function scanFileUncached(file, src, { isRoute, isComponent, appDir, scanStrippe
   // A page/layout NEVER hydrates (#605), so its `html` TEMPLATE content is
   // SSR output, not module client work: an inline `<script>`'s browser
   // globals run from the rendered HTML, and a page-template `@event` is
-  // dropped at SSR. For a route module, scan those two template-borne signals
-  // on the template-redacted source so they do not pin the module, while a
-  // genuine module-scope `document.x` OUTSIDE any template still flags (#623).
+  // dropped at SSR. For a route module, scan the `@event` signals on the
+  // template-redacted source so they do not pin the module; a non-route
+  // module keeps its template text, because a helper's `@click=${}` binds when
+  // a shipping component renders it. The browser-global scan reads `redacted`
+  // for EVERY module: a global's name in a string or template text is data
+  // (an inline `<script>` runs from the HTML, a `'lucide-app-window'` class
+  // is a class), while a genuine `document.x` in code, including code in a
+  // `${...}` hole, still flags (#623).
   // The import-based checks stay on `redacted`: a real `import 'pkg'` side
   // effect DOES run when a page/layout module loads in the browser, and
   // `importsSideEffectNonCorePackage` itself skips local `#`-alias imports.
   const templateScan = isRoute ? redacted : masked;
   const clientGlobalOrBare = EVENT_BINDING_RE.test(templateScan) || EVENT_PROP_RE.test(templateScan) ||
-    importsSideEffectNonCorePackage(redacted, appDir, literals) || CLIENT_GLOBAL_RE.test(templateScan) ||
+    importsSideEffectNonCorePackage(redacted, appDir, literals) || CLIENT_GLOBAL_RE.test(redacted) ||
     hasModuleScopeSideEffect(redacted, literals);
   let interactive = false;
   /** @type {string | null} */

package/src/dev/dev-status.js

@@ -0,0 +1,122 @@
+/**
+ * The dev server's "has my edit settled, and did it break anything" state
+ * (#1664), behind `GET /__webjs/dev/status` and the `webjs status` command.
+ *
+ * An agent editing a running app could not tell when the reload finished or
+ * whether it errored, so it slept a few seconds, fetched a page, and grepped
+ * the HTML for "Server error". The reload frame does not answer it either: it
+ * is sent before anything is re-imported, so a syntax error only surfaces on
+ * the next request.
+ *
+ * This module holds two things the handler feeds:
+ *
+ *   - A short ring of recent errors: render, TS strip, rebuild, route,
+ *     action, middleware, metadata, and request-pipeline failures, each as a
+ *     dev error frame (message, file, line, code frame). The overlay keeps only
+ *     the newest one, and never saw an action error at all. A rebuild clears
+ *     every kind EXCEPT `render`: a page broken by an edit stays broken across
+ *     an unrelated rebuild, so its error stays listed until that page renders
+ *     again (`renderSucceeded`).
+ *   - Whether a change is still in flight: a watcher event not yet rebuilt, or
+ *     a rebuild still running. The handler adds readiness on top, since the
+ *     lazy analysis is what actually re-imports the app.
+ *
+ * Dev only. Nothing here runs in production, where the endpoint is a 404.
+ *
+ * @module
+ */
+
+/** How many recent errors the ring keeps. */
+export const DEV_STATUS_MAX_ERRORS = 20;
+
+/**
+ * How long a watcher event may stay pending without a rebuild before it is
+ * treated as settled anyway (an event that classified to nothing, a poke that
+ * never re-ran), so a status wait can never hang on a lost signal.
+ */
+export const PENDING_CHANGE_TTL_MS = 10_000;
+
+/**
+ * @typedef {{
+ *   kind: string, message: string, file?: string | null, line?: number | null,
+ *   column?: number | null, codeFrame?: string | null, hint?: string | null,
+ *   url?: string | null, at: string,
+ * }} DevStatusError
+ */
+
+/**
+ * @param {{ now?: () => number }} [opts] `now` is injectable for tests.
+ */
+export function createDevStatus({ now = Date.now } = {}) {
+  /** @type {DevStatusError[]} */
+  let errors = [];
+  let rebuilds = 0;
+  let rebuildsInFlight = 0;
+  /** @type {number | null} */
+  let changeAt = null;
+
+  return {
+    /**
+     * Record an error frame (the shape `buildDevErrorFrame` returns).
+     * @param {Record<string, unknown>} frame
+     */
+    record(frame) {
+      if (!frame || typeof frame !== 'object') return;
+      const entry = /** @type {DevStatusError} */ ({
+        kind: String(frame.kind || 'error'),
+        message: String(frame.message || ''),
+        file: /** @type {any} */ (frame.file) ?? null,
+        line: /** @type {any} */ (frame.line) ?? null,
+        column: /** @type {any} */ (frame.column) ?? null,
+        codeFrame: /** @type {any} */ (frame.codeFrame) ?? null,
+        hint: /** @type {any} */ (frame.hint) ?? null,
+        url: /** @type {any} */ (frame.url) ?? null,
+        at: new Date(now()).toISOString(),
+      });
+      // The same failure seen again (a broken page requested twice) is one
+      // entry; the newer one replaces it, so `at` is the latest sighting.
+      errors = errors.filter((e) => !(e.kind === entry.kind && e.message === entry.message
+        && e.file === entry.file && e.line === entry.line && e.url === entry.url));
+      errors.push(entry);
+      if (errors.length > DEV_STATUS_MAX_ERRORS) errors = errors.slice(-DEV_STATUS_MAX_ERRORS);
+    },
+    /** A watcher saw an app change that a rebuild will follow. */
+    noteChange() { changeAt = now(); },
+    /**
+     * A rebuild started. It builds every change noted so far, so the pending
+     * marker clears HERE; a change noted while it runs sets it again and keeps
+     * the status unsettled until the rebuild that change schedules.
+     */
+    rebuildStarted() { rebuildsInFlight++; changeAt = null; },
+    /**
+     * A rebuild finished.
+     * @param {{ cleared?: boolean }} [opts] `cleared` drops the recorded errors
+     *   that described the build just replaced. Render errors are kept: only a
+     *   successful render of that page proves it was fixed.
+     */
+    rebuildFinished({ cleared = true } = {}) {
+      rebuildsInFlight = Math.max(0, rebuildsInFlight - 1);
+      rebuilds++;
+      if (cleared) errors = errors.filter((e) => e.kind === 'render');
+    },
+    /**
+     * A page rendered without a server error, so its recorded render error is
+     * stale. Each candidate is matched with its query string ignored.
+     * @param {Array<string | null | undefined>} urls the page's path, and its
+     *   public url (base path included) as the overlay stamps it
+     */
+    renderSucceeded(urls) {
+      const paths = new Set(urls.filter(Boolean).map((u) => String(u).split('?')[0]));
+      errors = errors.filter((e) => !(e.kind === 'render' && e.url && paths.has(String(e.url).split('?')[0])));
+    },
+    /** True while a change is waiting on, or inside, a rebuild. */
+    changing() {
+      if (rebuildsInFlight > 0) return true;
+      if (changeAt === null) return false;
+      if (now() - changeAt > PENDING_CHANGE_TTL_MS) { changeAt = null; return false; }
+      return true;
+    },
+    /** @returns {{ rebuilds: number, errors: DevStatusError[] }} */
+    snapshot() { return { rebuilds, errors: errors.slice() }; },
+  };
+}

package/src/dev/handler.js

@@ -54,6 +54,9 @@ import {
 import { applyConditionalGet } from '../conditional-get.js';
 import { commitHtmlCache, setAppSourceFingerprint } from '../html-cache.js';
 import { buildDevErrorFrame } from '../dev-error.js';
+import { isControlFlowThrow } from '../action-error.js';
+import { createDevStatus } from './dev-status.js';
+import { devReloadState } from '../dev-reload-state.js';
 
 import {
   readElideEnabled,
@@ -189,6 +192,48 @@ export async function createRequestHandler(opts) {
   // Both the programmatic opts.onError AND any sink an instrumentation.{js,ts}
   // register() installed via setOnError fire (they compose, #848).
   const onErrorSinks = [opts.onError, instrumentationOnError].filter((f) => typeof f === 'function');
+  // What `/__webjs/dev/status` reports (#1664): the errors since the last
+  // rebuild and whether a change is still in flight. Dev only.
+  const devStatus = dev ? createDevStatus() : null;
+  // Each error OBJECT is recorded once, under the first (most specific) kind
+  // that reaches it: a route handler's throw is recorded as `route` before the
+  // root middleware wrapping it reports the same error as `middleware`, and a
+  // render error the overlay already framed is not recorded again from the
+  // onError funnel.
+  /** @type {WeakSet<object>} Reset on every rebuild, so an error object an
+   * unchanged module throws again after a rebuild (a rejected module-scope
+   * promise awaited per request) is recorded again. */
+  let devRecorded = new WeakSet();
+
+  /**
+   * Record an error in the dev status. A thrown redirect() / notFound() /
+   * forbidden() / unauthorized() is control flow the framework answers, not a
+   * failure, so it is never recorded.
+   * @param {unknown} error
+   * @param {Request | null | undefined} request
+   * @param {string} kind
+   * @param {Record<string, unknown>} [frame] an already-built dev error frame
+   */
+  function recordDevStatus(error, request, kind, frame) {
+    if (!devStatus || isControlFlowThrow(error)) return;
+    if (error && typeof error === 'object') {
+      if (devRecorded.has(error)) return;
+      devRecorded.add(error);
+    }
+    try {
+      let url;
+      try { url = request && request.url ? new URL(request.url).pathname : undefined; } catch { /* no url */ }
+      const code = error && typeof error === 'object' ? /** @type {any} */ (error).code : undefined;
+      if (typeof code === 'string' && code.startsWith('WEBJS_FORM_')) {
+        // A framework diagnostic about the page's own markup (a POST form that
+        // binds no action, a bound form submitted as GET). Its stack points
+        // into the framework, so it is recorded against the page instead.
+        devStatus.record({ kind: 'form', message: `${code}: ${/** @type {any} */ (error).message}`, url });
+        return;
+      }
+      devStatus.record(frame || buildDevErrorFrame(error, { kind, appDir, url }));
+    } catch { /* best effort */ }
+  }
   const hasOnError = onErrorSinks.length > 0;
 
   /**
@@ -199,6 +244,10 @@ export async function createRequestHandler(opts) {
    * @param {string} phase
    */
   function reportError(error, request, phase) {
+    // Dev status (#1664). Recorded BEFORE the no-sink return, because an app
+    // with no onError sink is exactly the one whose action errors were
+    // invisible to an agent. An `ssr` error is a render failure.
+    recordDevStatus(error, request, phase === 'ssr' ? 'render' : phase);
     if (!hasOnError) return;
     const ctx = { request, requestId: getRequestId(), phase };
     for (const sink of onErrorSinks) {
@@ -495,6 +544,9 @@ export async function createRequestHandler(opts) {
     // SSE channel for the live overlay and replayed to a freshly-connected tab.
     // Dev-only (never populated when !dev); cleared on a successful rebuild.
     lastDevError: null,
+    // The dev status (#1664), on `state` so the page-render path can tell it a
+    // page rendered again. Null in prod.
+    devStatus,
     // On-request regeneration rules (#967): `webjs.dev.regenerate` from the app's
     // package.json. Dev-only (prod builds its outputs via `start.before`). Loaded
     // now and refreshed on each rebuild so a config edit takes effect without a
@@ -529,6 +581,7 @@ export async function createRequestHandler(opts) {
     try {
       const frame = buildDevErrorFrame(error, { ...info, appDir });
       state.lastDevError = frame;
+      recordDevStatus(error, null, frame.kind, frame);
       opts.onDevError?.(frame);
     } catch { /* ignore */ }
   }
@@ -932,7 +985,14 @@ export async function createRequestHandler(opts) {
    *   without a reload frame (a `bun --hot` registry reset, #1575).
    */
   async function rebuild(verdict, { notify = true } = {}) {
-    rebuildInFlight = rebuildInFlight.then(() => doRebuild(verdict, notify)).catch((e) => {
+    devStatus?.rebuildStarted();
+    rebuildInFlight = rebuildInFlight.then(() => doRebuild(verdict, notify)).then(() => {
+      // The recorded errors described the build this one replaced.
+      devStatus?.rebuildFinished();
+      devRecorded = new WeakSet();
+    }, (e) => {
+      devStatus?.rebuildFinished();
+      devRecorded = new WeakSet();
       logger.error?.(`[webjs] rebuild failed:`, e);
       // Push the failure to the open tab so the overlay appears live after a
       // breaking edit, not only on the next manual navigation (#264).
@@ -1014,6 +1074,48 @@ export async function createRequestHandler(opts) {
     if (notify) opts.onReload?.(verdict || { v: 'reload', by: '', why: 'no-verdict' });
   }
 
+  /**
+   * The `/__webjs/dev/status` body (#1664). Waits up to `waitMs` for a pending
+   * change to be rebuilt, then drives the lazy analysis so readiness describes
+   * the CURRENT source rather than the build before the edit.
+   * @param {number} waitMs
+   * @returns {Promise<Response>}
+   */
+  async function devStatusResponse(waitMs) {
+    const status = /** @type {NonNullable<typeof devStatus>} */ (devStatus);
+    const deadline = Date.now() + waitMs;
+    while (waitMs && status.changing() && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    const warm = ensureReady().catch(() => {});
+    if (waitMs && !status.changing()) {
+      const left = Math.max(0, deadline - Date.now());
+      await Promise.race([warm, new Promise((r) => setTimeout(r, left))]);
+    }
+    const { rebuilds, errors } = status.snapshot();
+    // The same decision `/__webjs/ready` makes: once warm, a later retry's error
+    // (a transient vendor failure the server tolerates) does not un-ready it.
+    const ready = readyDone ? 'ok' : readyError ? 'error' : 'pending';
+    const settled = !status.changing() && ready !== 'pending';
+    if (ready === 'error') {
+      errors.unshift({
+        kind: 'ready', message: String((readyError && readyError.message) || readyError),
+        file: null, line: null, column: null, codeFrame: null, hint: null, url: null, at: new Date().toISOString(),
+      });
+    }
+    const reload = devReloadState();
+    const body = {
+      status: errors.length ? 'error' : settled ? 'ok' : 'pending',
+      settled,
+      ready,
+      boot: reload ? reload.boot : null,
+      seq: reload ? reload.seq : null,
+      rebuilds,
+      errors,
+    };
+    return Response.json(body, { headers: { 'cache-control': 'no-store' } });
+  }
+
   /** A routing-convention module under `app/`, which only the router loads. */
   const ROUTE_MODULE_FILE = /^app\/(?:.*\/)?(?:page|layout|route|loading|error|not-found|forbidden|unauthorized|global-error|global-not-found|middleware)\.m?[jt]s$/;
   /** @type {WeakMap<object, Set<string>>} every file some app module imports, per graph */
@@ -1175,6 +1277,15 @@ export async function createRequestHandler(opts) {
       // Use the STRIPPED path for the suppression check (issue #256) so a
       // framework probe at `<basePath>/__webjs/*` is suppressed just like the
       // root-mounted `/__webjs/*`. The logged `path` stays the RAW client URL.
+      // Dev status (#1664): a GET that answered below 500 supersedes a render
+      // error recorded for that url, whatever answered it. A page fixed in
+      // place renders 200, a deleted or renamed one 404s or redirects, and in
+      // every case its old render error is stale. A speculative prefetch is
+      // not a view of anything, so it clears nothing.
+      if (devStatus && (req.method === 'GET' || req.method === 'HEAD') && conditioned.status < 500
+        && req.headers.get('x-webjs-prefetch') !== '1') {
+        devStatus.renderSucceeded([headerPathname, pathname]);
+      }
       if (shouldAccessLog(headerPathname)) {
         try {
           // #1309: fold the dev-only seeding counters into the ONE access-log
@@ -1335,6 +1446,19 @@ export async function createRequestHandler(opts) {
       return Response.json({ status: 'ok' }, { headers: noStore });
     }
 
+    // Dev status (#1664): has the last edit settled, and what broke since the
+    // last rebuild. Answered before ensureReady like the other probes, and only
+    // in dev, since it carries file paths and stacks, the same exposure as the
+    // error overlay. `?wait=<seconds>` (capped at 60) holds the response until
+    // the change has been rebuilt and the analysis re-run, which is the part
+    // the reload frame cannot tell anyone: it goes out before any re-import.
+    if (probePath === '/__webjs/dev/status') {
+      if (!devStatus) return new Response('Not Found', { status: 404 });
+      let waitParam = 0;
+      try { waitParam = Number(new URL(req.url).searchParams.get('wait')) || 0; } catch { /* no wait */ }
+      return devStatusResponse(Math.min(Math.max(waitParam, 0), 60) * 1000);
+    }
+
     // Framework-internal static assets (the @webjsdev/core runtime, the dev
     // reload client, downloaded vendor bundles) depend on neither the analysis
     // nor the vendor importmap, so serve them BEFORE ensureReady(). Otherwise a
@@ -1379,6 +1503,9 @@ export async function createRequestHandler(opts) {
       dev,
       reportError,
       reportDevError,
+      // Dev only: in production the API dispatch takes its plain path with no
+      // recording wrapper at all.
+      recordDevStatus: dev ? recordDevStatus : undefined,
       hasOnError,
       logger,
       cspEnabled: cspConfig.enabled,
@@ -1464,6 +1591,9 @@ export async function createRequestHandler(opts) {
      * startServer to a freshly-connected SSE client so the overlay shows even
      * after a navigation, not only on the breaking edit. Always null in prod. */
     getLastDevError: () => state.lastDevError,
+    /** Tell the dev status (#1664) a watched app file changed, so a status
+     * wait holds until the rebuild that follows. A no-op in prod. */
+    noteChange: () => devStatus?.noteChange(),
     /** Whether a dev-watcher filename is a `webjs.dev.regenerate` OUTPUT (#967),
      * so `startServer`'s file watcher (a different scope, with no access to
      * `state`) can skip a build product the server itself writes and avoid a

package/src/dev/serve.js

@@ -201,7 +201,7 @@ export async function tryServePublicAsset(path, ctx) {
 }
 
 export async function handleCore(req, ctx) {
-  const { state, appDir, coreDir, dev, reportError, reportDevError, hasOnError, logger, cspEnabled, allowedOrigins } = ctx;
+  const { state, appDir, coreDir, dev, reportError, reportDevError, recordDevStatus, hasOnError, logger, cspEnabled, allowedOrigins } = ctx;
   const url = new URL(req.url);
   // Decode percent-encoded characters so filesystem lookups match real
   // filenames. Dynamic route segments like `[slug]` and route groups like
@@ -240,7 +240,7 @@ export async function handleCore(req, ctx) {
     // Pass the onError sink (issue #239): a server action that throws
     // unexpectedly is reported to the APM hook before the sanitized 500.
     const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;
-    return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req, onActionError, allowedOrigins);
+    return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req, onActionError, allowedOrigins, logger);
   }
 
   // Static: /public/*, the #830 root remaps, and /favicon.ico. In dev this
@@ -387,7 +387,14 @@ export async function handleCore(req, ctx) {
   // API route (route.js handler)
   const api = matchApi(state.routeTable, path);
   if (api) {
-    const handler = () => handleApi(api.route, api.params, req, dev);
+    // A handler that throws is recorded in the dev status as a `route` error
+    // HERE, before a root middleware wrapping `next()` reports the same error
+    // as its own (#1664). The rethrow keeps the response path unchanged.
+    const handler = recordDevStatus
+      ? async () => {
+        try { return await handleApi(api.route, api.params, req, dev); } catch (e) { recordDevStatus(e, req, 'route'); throw e; }
+      }
+      : () => handleApi(api.route, api.params, req, dev);
     return runWithSegmentMiddleware(req, api.route.middlewares, handler, dev);
   }
 
@@ -456,10 +463,11 @@ export async function handleCore(req, ctx) {
         // to turn any page into an error.
         reportFormSubmittedAsGet(
           url, req,
-          // Gated on hasOnError, not on `reportError`: that is always a
-          // function here and no-ops internally, so passing it would spend a
-          // dedupe slot on a report nobody receives.
-          hasOnError ? (e) => reportError(e, req, 'action') : undefined,
+          // Gated on a sink OR dev, not on `reportError` alone, which is
+          // always a function: with neither, nobody receives the report and it
+          // would only spend a dedupe slot. In dev the dev status receives it
+          // (#1664), the same as the POST variant below.
+          hasOnError || dev ? (e) => reportError(e, req, 'action') : undefined,
           logger, dev, page.route,
         );
         // A successful render of URL U supersedes a RETAINED render error for
@@ -490,7 +498,9 @@ export async function handleCore(req, ctx) {
       const deps = {
         actionIndex: state.actionIndex,
         allowedOrigins,
-        onError: hasOnError ? (e) => reportError(e, req, 'action') : undefined,
+        // Also passed in dev with no sink, so a failing form action reaches the
+        // dev status error list (#1664); `reportError` records it first.
+        onError: hasOnError || dev ? (e) => reportError(e, req, 'action') : undefined,
         logger,
       };
       const handler = () => runFormAction(page.route, page.params, url, req, ssrOpts, deps);