dogfood: dev error overlay leaks across the gallery after an intentional-throw page

[vivek7405]

Problem

In dev, after visiting a page that throws during SSR (the scaffold's app/features/boundaries/crash demo, which intentionally throw new Error('demo: this page threw during render')), the "Server render error" overlay popup then appears randomly across the rest of the gallery, on pages that render fine. It reliably reappears on/around the boundary pages. A hard refresh of a good page clears it; navigating there via the client router does not.

Observed against a scaffolded app (webjs create, Bun runtime) at app/features/boundaries/crash/page.ts.

Design / approach

Two dev-only mechanisms keep a stale error alive, neither cleared by a successful client-router navigation:

1. The overlay is a body-level injected element (data-webjs-error-overlay, dev-overlay.js renderDevOverlay) dismissed ONLY by its close button or dismissDevOverlay(). It sits outside the client router's swap range, so a soft-nav to a good page leaves it on screen.
2. The dev SharedWorker retains lastError and re-broadcasts it to every tab and every new port/reconnect (dev-reload-worker.js L55 sets lastError on each webjs-error, L65 re-posts it to every newly-connecting port). So a reconnect or a new tab re-shows the last error even though nothing is currently wrong ("appears randomly").

Fix direction: a successful navigation / successful render should clear the overlay. Have the client router call dismissDevOverlay() after a clean swap (dev builds only), AND have the worker drop lastError once a subsequent successful render or reload supersedes it (or gate re-broadcast on the error still being current). Keep it strictly dev-only (production ships no overlay).

Implementation notes (for the implementing agent)

• Where to edit:
  • packages/server/src/dev-overlay.js: renderDevOverlay (appends the overlay), dismissDevOverlay (L18). The overlay is body-level.
  • packages/server/src/dev-reload-worker.js: lastError retention (L55) + re-post to new ports (L65). Decide when lastError is stale.
  • packages/server/src/dev.js: __webjsApplyError (~L2807) and the SharedWorker onmessage / __webjsDirectEvents wiring (~L2842-2856). The reload client is assembled here from DEV_OVERLAY_SRC.
  • Client hook: packages/core/src/router-client.js after a successful applySwap (the two-tier boundary swap ~L2818 / frame swap) is where a "clear dev overlay on successful nav" call would live, guarded so it is a no-op in prod (the overlay dismiss fn only exists in the dev reload client, so call it via a global check like window.dismissDevOverlay / a documented dev hook, not a static import from server code).
• Landmines:
  • Strictly DEV-only. packages/core must not import server/dev code; reach the dismiss via a global the dev reload client installs, or dispatch a documented event the dev client listens for. Do not pull dev-overlay into the production browser bundle.
  • The boundaries/crash demo is an INTENTIONAL uncaught throw (its own comment says expected failures should use ActionResult / notFound() / forbidden()). So the overlay SHOWING on that page is correct; only its LEAK to other pages is the bug. Do not "fix" the demo.
  • Don't clear the overlay on a FAILED navigation (a real error should stay). Only a clean render clears it.
  • dogfood: Node dev full-restarts on every app edit (downtime + CSS flash) #893 context: the worker deliberately retains state to survive restarts and re-show a still-relevant error; the fix must not reintroduce the missing-error-after-restart gap. Distinguish "same error still current" from "superseded by a good render".
• Invariants: no build step, .js + JSDoc in packages/ (root + packages/core/packages/server AGENTS.md). Dev-overlay behaviour has browser tests already (dev-overlay.js is imported directly by a browser test per dev.js comment ~L2773); extend those.
• Tests + docs: browser test that applies an error frame, then simulates a successful navigation, and asserts the overlay is gone. Counterfactual: fails before the fix. Docs: the dev error overlay is described in framework-dev.md (dev error overlay section); sync if behaviour changes.

Acceptance criteria

• After a client-router navigation to a cleanly-rendering page, no stale dev error overlay remains on screen
• A reconnect / new tab does not resurrect an error that a later successful render superseded
• The overlay still shows on the page that actually threw, and a genuine current error is not cleared prematurely
• Strictly dev-only: nothing added to the production browser bundle
• Browser test covers apply-error then navigate-clean, with a counterfactual

[vivek7405]

Verified live, and it subsumes the "stuck skeleton" report

Confirmed real, with a sharper root cause than the body first stated. Driving a real browser against a bun scaffold (framework 0.8.55):

• Open a FRESH tab straight to /features/view-transitions (renders fine, I never visited the crash demo in that tab). The full-screen overlay is already there, showing boundaries/crash/page.ts:6:13. A window marker I set survived, so nothing reloaded. The dev SharedWorker pushed the stale error into this new tab.
• Same on a fresh hard load of /features/optimistic-ui: the page renders fine, yet the overlay (position:fixed; inset:0; z-index:2147483647; background:rgba(10,10,12,.92)) covers the whole viewport with the crash error.

Root cause (two parts):

1. The server keeps state.lastDevError and replays it to every new SSE connection and every new SharedWorker port. It is cleared ONLY on a successful REBUILD (a file edit), never on a successful render or navigation. The boundaries/crash demo throws on every render, so lastDevError stays armed indefinitely, and every fresh tab / SSE reconnect re-shows it.
2. The overlay is full-screen and dismissed ONLY by its own button (dismissDevOverlay). No navigation clears it. So it blanket-covers every page and, as I saw, intercepts clicks.

This also explains the two other symptoms from the same report:

• "Error popup appears randomly across the gallery" is exactly this full-screen overlay leaking onto good pages on each SSE (re)connect.
• "Sometimes I click a boundary card, keep seeing the skeleton, then refresh shows the content or the popup" is the overlay covering a page while it is mid-navigation; the refresh either lands on a good render (content) or re-arms the overlay (popup).

I tried to reproduce an INDEPENDENT Suspense stuck-skeleton bug and could not: 12+ soft navs into the streamed /features/boundaries and /features/suspense (including mid-stream interrupt races) all resolved cleanly (fallback replaced by content, no leftover resolve templates). So there is no separate "stuck skeleton" issue to file; it folds into this one. The fix here should (a) clear lastDevError / dismiss the overlay on a successful render or navigation, not only on a rebuild, and (b) stop re-broadcasting a superseded error to new connections.

[vivek7405]

Correction: the stuck skeleton is NOT this issue, it is real and now filed as #1048

My earlier comment was wrong to fold the "stuck skeleton" into this overlay issue. On a closer look it IS a real, separate bug, filed as #1048.

I reproduced it deterministically: with view transitions enabled, soft-navigating into a streamed Suspense page (e.g. /features/boundaries, auto-wrapped by loading.ts) leaves the skeleton stuck 8/8. Removing the view-transition meta (VT off) makes the same navigation resolve to content. So it is a race between the async startViewTransition swap and the synchronous streamed-Suspense resolve, not the overlay.

This issue (#1047, the dev-overlay leak) still stands on its own for the "error popup across the gallery" symptom. The stuck skeleton belongs to #1048. Note #1046 (the view-transition meta leak) is what turns VT on across the whole gallery, so it is the trigger that exposes #1048 everywhere.