fix: diagnose a boundary failure by the fallback, not the marker alone

The marker records a layout that throws when CALLED. It cannot record one
that fails while being SERIALIZED, the idiomatic async form with a rejecting
template hole, because by then the layout's output is fused into one tree
with the boundary's and renderToString cannot say which half threw. Treating
unmarked as tree-broken therefore skipped the standalone fallback for that
whole class, so a 403 whose layout had a rejecting hole served a bare
heading where it used to serve the boundary page, reported under the wrong
label. The fallback's OUTCOME is the other half of the diagnosis: if the
boundary renders alone the fault was layout-side, marked or not.

The unrouted 404 also gains the supersede rule its matched-page sibling has:
a later successful render of the same url clears the frame it retained, so
an intermittently-failing not-found cannot leave one that paints over a page
that has since recovered. Only reachable once the stamp was correct enough
for the overlay to accept the frame at all, which the previous commit did.

Author: vivek7405

packages/server/src/dev/serve.js

@@ -503,7 +503,15 @@ export async function handleCore(req, ctx) {
   // No `route` is passed on purpose: nothing matched, so there is no layout
   // chain to render the boundary inside, and the response stays a bare
   // document with no boot script.
-  return ssrNotFound(state.routeTable.notFound || state.routeTable.globalNotFound, {
+  // Same supersede rule the matched-page branch follows (#1047 / #893): a
+  // LATER successful render of this same url clears the frame it retained, so
+  // an intermittently-failing not-found (a query behind it, not a source edit,
+  // which the rebuild already clears) cannot leave a frame that paints over a
+  // page that has since recovered. Scoped to this url, so a good render here
+  // never erases an error still current for a page the user is looking at.
+  const devErrorUrl = withBasePath(url.pathname, basePath()) + url.search;
+  const before = dev ? state.lastDevError : null;
+  const resp = await ssrNotFound(state.routeTable.notFound || state.routeTable.globalNotFound, {
     dev,
     appDir,
     req,
@@ -524,12 +532,14 @@ export async function handleCore(req, ctx) {
     // `state.lastDevError` for the SSE to replay into a fresh tab. Prefetch is
     // on by default and fetches unrouted hrefs too, so this is reachable.
     onDevError: dev && req.headers.get('x-webjs-prefetch') !== '1'
-      ? (e) => reportDevError(e, {
-        kind: 'render',
-        url: withBasePath(url.pathname, basePath()) + url.search,
-      })
+      ? (e) => reportDevError(e, { kind: 'render', url: devErrorUrl })
       : undefined,
   });
+  if (
+    before && state.lastDevError === before
+    && before.kind === 'render' && before.url === devErrorUrl
+  ) state.lastDevError = null;
+  return resp;
 }
 
 /** @param {Request} req @param {string} path */

packages/server/src/ssr/render.js

@@ -701,24 +701,36 @@ async function ssrBoundaryHtml(file, heading, opts) {
             body = await renderToString(tree, { ssr: true, dev: opts.dev });
           }
         } catch (layoutErr) {
-          // A TREE failure is not this catch's business: the standalone
-          // fallback would re-render the same tree and fail the same way, so
-          // rethrow and let the outer catch report it ONCE under the boundary
-          // label. Reporting here as well would double-report it and call it a
-          // layout crash.
-          if (!isLayoutPhase(layoutErr)) throw layoutErr;
-          // A wrapped layout threw. Degrade to the standalone render this has
-          // always produced, and to its empty boot set with it. Report it
-          // either way: these paths execute layout modules for the first time
-          // since #1298, so a genuine layout crash would otherwise vanish.
-          reportBoundaryLayoutError(layoutErr, opts, { overlay: true });
+          // Always attempt the standalone render, which is the degradation
+          // this path has always produced. Its OUTCOME is half the diagnosis
+          // and the phase marker is the other half; neither alone is enough.
+          //
+          // The marker records a layout that threw when it was CALLED. It
+          // cannot record a layout that fails while being SERIALIZED (the
+          // idiomatic `html`<nav>${getNav()}</nav>${children}`` with a
+          // rejecting hole), because by then its output is fused into one tree
+          // with the boundary's and `renderToString` cannot say which half
+          // threw. That is what the fallback answers: if the boundary renders
+          // alone, the fault was layout-side whether or not it was marked.
+          let treeErr = null;
           try {
             body = await renderToString(tree, { ssr: true, dev: opts.dev });
             moduleUrls = [];
-          } catch (treeErr) {
-            // BOTH are broken. The layout crash is already reported above, so
-            // hand the outer catch the TREE error: it is a second, distinct
-            // failure, and it is the one whose text the dev body should show.
+          } catch (e) {
+            treeErr = e;
+          }
+          if (treeErr === null) {
+            // The boundary is fine on its own, so the chain is what failed.
+            reportBoundaryLayoutError(layoutErr, opts, { overlay: true });
+          } else {
+            // The boundary's own tree is broken too. Report a MARKED layout
+            // failure as the separate thing it is, then hand the outer catch
+            // the tree error: it is what defeated the fallback and what the
+            // dev body should show. An UNMARKED one is not reported here,
+            // because it may be this same tree error arriving twice.
+            if (isLayoutPhase(layoutErr)) {
+              reportBoundaryLayoutError(layoutErr, opts, { overlay: false });
+            }
             throw treeErr;
           }
         }
@@ -781,13 +793,20 @@ async function ssrNotFoundHtml(notFoundFile, opts) {
             body = await renderToString(tree, { ssr: true, dev: opts.dev });
           }
         } catch (layoutErr) {
-          // Same phase rule as ssrBoundaryHtml above.
-          if (!isLayoutPhase(layoutErr)) throw layoutErr;
-          reportBoundaryLayoutError(layoutErr, opts, { overlay: true });
+          // Same diagnosis rule as ssrBoundaryHtml above.
+          let treeErr = null;
           try {
             body = await renderToString(tree, { ssr: true, dev: opts.dev });
             moduleUrls = [];
-          } catch (treeErr) {
+          } catch (e) {
+            treeErr = e;
+          }
+          if (treeErr === null) {
+            reportBoundaryLayoutError(layoutErr, opts, { overlay: true });
+          } else {
+            if (isLayoutPhase(layoutErr)) {
+              reportBoundaryLayoutError(layoutErr, opts, { overlay: false });
+            }
             throw treeErr;
           }
         }

packages/server/test/routing/global-boundaries.test.js

@@ -187,3 +187,38 @@ test('a PREFETCH of an unrouted url raises no dev overlay frame (#1047)', async
   assert.equal(frames.length, 0, 'no overlay frame from a speculative fetch');
   assert.equal(errors.length, 1, 'but the APM sink still hears about it, since the render really threw');
 });
+
+test('a recovered unrouted 404 clears the frame it retained (#1047 supersede)', async () => {
+  // An intermittently-failing not-found must not leave a frame that paints
+  // over the same url once it renders again. A source edit is cleared by the
+  // rebuild; this is the other route in, and it only became reachable once the
+  // frame stamp was correct enough for the overlay to accept it.
+  const appDir = makeApp({
+    'package.json': pkg,
+    'app/page.js': page('export default function H() { return html`<main>home</main>`; }'),
+    // Fails on the first render of a url, succeeds afterwards.
+    // globalThis, not module scope: dev re-imports the module per request with
+    // a cache-bust query, so module-level state resets every time.
+    'app/not-found.js': `import { html } from ${JSON.stringify(CORE)};
+export default function NF() {
+  if (!globalThis.__flakyNfSeen) { globalThis.__flakyNfSeen = true; throw new Error('FLAKY_NF_BOOM'); }
+  return html\`<main>missing</main>\`;
+}
+`,
+  });
+  const app = await createRequestHandler({ appDir, dev: true });
+  const prev = console.error;
+  console.error = () => {};
+  try {
+    const first = await app.handle(new Request('http://x/gone?q=1'));
+    assert.equal(first.status, 404);
+    const second = await app.handle(new Request('http://x/gone?q=1'));
+    assert.equal(second.status, 404);
+    assert.match(await second.text(), /missing/, 'the second render succeeded');
+  } finally { console.error = prev; }
+  // Observed directly, not through a probe endpoint that might not exist: a
+  // conditional assertion here would pass whether or not the fix works.
+  assert.equal(typeof app.getLastDevError, 'function', 'the handler exposes the retained frame');
+  const held = app.getLastDevError();
+  assert.equal(held, null, 'no stale frame retained for a url that recovered');
+});

test/ssr/ssr.test.js

@@ -2525,6 +2525,37 @@ test('boundary: when the layout AND the tree are broken, BOTH are reported', asy
   assert.match(await resp.text(), /TREE_HALF_BOOM/);
 });
 
+test('boundary: a layout failing in a TEMPLATE HOLE still degrades to the boundary', async () => {
+  // The idiomatic async layout: it returns fine and fails while being
+  // serialized. The phase marker cannot see this, because by then the layout's
+  // output is fused into one tree with the boundary's, so the FALLBACK is what
+  // diagnoses it: the boundary renders alone, therefore the chain was at fault.
+  // Getting this wrong serves a bare heading instead of the boundary page.
+  const { route, appDir } = makeBoundaryApp({
+    files: {
+      'layout.js': HTML_IMPORT + `export default function Root({ children }) {
+        return html\`<nav>\${Promise.reject(new Error('LAYOUT_HOLE_BOOM'))}</nav>\${children}\`;
+      }\n`,
+      'admin/forbidden.js': HTML_IMPORT + `export default function F() { return html\`<p id="fb">no access</p>\`; }\n`,
+      'admin/page.js': `import { forbidden } from ${JSON.stringify(WEBJS_MODULE_URL)};\nexport default function Page() { forbidden(); }\n`,
+    },
+    page: 'admin/page.js',
+    layouts: ['layout.js'],
+    forbiddens: ['admin/forbidden.js'],
+  });
+  const seen = [];
+  const resp = await SILENT(() => ssrPage(route, {}, new URL('http://localhost/admin'), {
+    dev: false, appDir, onError: (e) => seen.push(e),
+  }));
+  assert.equal(resp.status, 403);
+  const body = await resp.text();
+  assert.ok(body.includes('id="fb"'), 'the boundary page is served, not a bare heading');
+  assert.equal(markersOf(body).length, 0, 'chrome-less, since the chain could not render');
+  assert.ok(!body.includes('<script type="module">'), 'and no boot set for a chain that did not render');
+  const hits = seen.filter((e) => /LAYOUT_HOLE_BOOM/.test(String(e && e.message)));
+  assert.equal(hits.length, 1, 'the layout failure is reported exactly once');
+});
+
 test('boundary: a boundary response is never storable and never reduced', async () => {
   // Two independent guarantees. The HTML cache refuses a non-200 outright, and
   // the reduced X-Webjs-Have path is structurally unreachable: the boundary