research: fragility audit + production-readiness hardening (router is the hotspot, keep auto-elision)

[vivek7405]

Problem

Production-readiness question raised: what is the most fragile subsystem of WebJs, is it elision, and should auto-elision be replaced with a manual 'use client'-style opt-in? This issue records the investigation and scopes the hardening needed before calling the framework production ready.

Findings

Two evidence sweeps were run: a full git log fix-clustering pass (259 fix: commits across 1172 total) and a code read of the elision analyzer.

Elision is not the most fragile feature. The client router / soft-nav reconciliation is, by a wide margin:

Subsystem	fix: count
Client router / reconciliation / navigation	37
CLI / scaffold	31
Hydration / components / signals	22
SSR / streaming / suspense	15
Dev server / watch / reload	12
Caching	10
Serializer / rich types	9
TypeScript stripper	8
Server actions / RPC / seed	6
Elision	5
Bun parity	4

The router is still generating bugs recently (#907 reconcile-into-hydrated-components, #910 slot re-projection on reuse, #936 stylesheet stripping + fragment parse context). Recurring theme: a soft nav corrupting already-hydrated DOM.

On the 'use client' question: keep auto-elision, do not switch. Rationale:

• The analyzer is engineered fail-safe: every ambiguity ships JS. A manual annotation inverts the failure mode onto every app author, and in a no-build framework there is no compiler to catch a forgotten annotation, so a missed "ship me" directive fails silently (SSRs fine, never hydrates). That is exactly the failure elision's conservatism avoids.
• 'use client' semantics do not map. WebJs modules are isomorphic, there is no server/client component split to annotate.
• Elision is load-bearing for import-only page emission (Elide page/layout modules that ship only to import interactive components #605) and vendor importmap pruning. Removing it regresses the no-build perf story.
• Elision's own fix history is overwhelmingly the benign direction (over-shipping, a perf miss). Only ~3 incidents were the dangerous direction of wrongly eliding into silent interactivity loss (Ship display-only components observed via whenDefined/:defined/instanceof #171, fix: track string-literal dynamic import() in the browser graph #767, fix: capture a dynamic import() inside a template ${} hole #919), and those are now guarded by the differential on/off CI test (test/elision/differential-elision.test.js), the lifecycle/sigil drift guards, and scanner fuzzing. The two remaining wrongly-elide residuals (a runtime-computed tag string, an external-stylesheet :defined rule) already have the static interactive = true escape hatch.

Correctness observation worth flagging: because WebJs ships raw Web Components plus request-time type stripping plus automatic elision instead of a compiler that would fail naturally, a lot of correctness is outsourced to 19 check.js lint rules. Guardrail trust therefore matters more than in a compiled framework.

Answers to the open questions (full detail in the deep-dive comments below)

The five open questions have been investigated. Each has a dedicated deep-dive comment on this issue with file:line references.

• Router reconciliation invariants + fuzz harness (comment 1). Derived the full 21-invariant set for packages/core/src/router-client.js, each mapped to its enforcing code and its origin (roughly half incident-hardened, half by design). A property-based harness is feasible and low-friction: the module already exports a test seam (_applySwap, _reconcileChildren, _diffElementInPlace, _keyOf, _LIVE_ATTRS, nav-token controls at L3541-3622) that the existing 145 KB unit suite drives under linkedom. Recommended shape: tier 1 fast-check + linkedom over the pure reconciler (identity / LIVE_ATTRS / permanents / head merge oracles); tier 2 a small browser generative harness for the ~5 invariants linkedom cannot express (DSD setHTMLUnsafe, real slot reprojection, hydration symbol, shadow upgrade, view transitions).
• e2e nav-matrix holes (comment 2). Coverage is dense on the incident clusters; 10 holes remain, top priority: live view-transition nav (only stubbed today), shadow-DOM preservation across a soft nav, streamed Suspense under popstate / abort, the 422 page-action swap into a deep nested layout, and any focus-invariant assertion (zero today).
• Elision contract tests (comment 3). The static interactive override and static shadow always-ship rule ARE analyser-tested, but the two documented residuals are unasserted: no test uses a runtime-computed .register(tagVar) tag, none pairs that shape with the override rescuing it, none covers the external-stylesheet :defined residual, and no serve/e2e test proves the override verdict is honoured end-to-end (no fixture app has a static interactive = true component). Confirmed the differential guard masks the whole JS-loaded set, so over-ship is invisible to it by construction.
• Dev-time elision visibility (comment 4). Verdicts are already in scope at first request (dev.js:882-884, the same if (dev) block that logs orphan warnings + timing), so a server-console first-request summary is trivial and a browser-console push is small (a dev-only inline script at boot emission, or a new SSE event on the existing SseHub, mirroring the webjs-error overlay channel).
• Production-readiness scorecard (comment 5). Only 7 open issues repo-wide; the sole live code debt in non-router subsystems is the streaming-RPC e2e flake (de-flake the streaming-RPC e2e (mid-stream snapshot races the stream end) #972/dogfood: de-flake the #489 streaming-RPC e2e (mid<final race) #973). Ratings: serializer 5/5, caching 5/5, TS stripper 5/5, core hydration 4.5/5, Bun parity 4/5 (one documented permanent gap: 103 Early Hints), actions/RPC/CSRF/seed 4/5 (flaky streaming e2e), dev server 4/5 (most-iterated; dogfood: dev live-reload infinite loop (browser refreshes ~5x/sec), reconnect treated as edit #968 closed with no named regression guard).

Recommended hardening (recorded here, not yet filed)

Left unfiled at the maintainer's direction; capture the candidates for later triage.

1. Router reconciliation property / fuzz harness (tier 1 fast-check + linkedom over the exported seams; tier 2 browser generative for the DSD / slot / hydration / stylesheet / view-transition invariants).
2. Fill the 10 e2e soft-nav holes, prioritizing shadow-DOM across soft nav, streaming under popstate / abort, live view transitions, the nested-layout 422, and focus.
3. Elision residual contract tests (dynamic-tag elided without override / ships with static interactive = true; external-stylesheet :defined; an end-to-end override-ships fixture in examples/blog or test/e2e/fixtures/).
4. Dev-time elision visibility (first-request server-console summary + a browser-console push, reusing the verdicts at dev.js:882-884).
5. Misc hardening: a generated-corpus parity fuzz for the TS stripper, a named regression guard for the dogfood: dev live-reload infinite loop (browser refreshes ~5x/sec), reconnect treated as edit #968 dev reconnect loop, and a Tailwind stale-CSS watcher-crash test.
6. Streaming-RPC e2e flake is already tracked as de-flake the streaming-RPC e2e (mid-stream snapshot races the stream end) #972/dogfood: de-flake the #489 streaming-RPC e2e (mid<final race) #973; no new issue needed.

Implementation notes (for a later implementing agent)

• Elision analyzer: packages/server/src/component-elision.js (~1259 lines), the signal list is in analyzeComponentSource() and analyzeElision(). Import-only emission (Elide page/layout modules that ship only to import interactive components #605) and inert classification (Stabilize: elision analyzer masks comments/strings (no false signals from prose) #179) live in analyzeElision() around L1135. The static interactive / static shadow signals are INTERACTIVITY_STATIC_FIELDS at L153, applied L570-575. Escape-hatch env reads in packages/server/src/dev.js (readElideEnabled, elideEnvOverride).
• Router: packages/core/src/router-client.js. Recent fix landmarks: fix: client router must not reconcile into hydrated components #907, fix: client router re-projects slotted content of a reused component #910, dogfood: CSS drops on client-router soft nav on real Android Chrome (styled on refresh) #936. Test seam re-exports at L3541-3622.
• Differential guard: test/elision/differential-elision.test.js, plus e2e cases in test/e2e/e2e.test.mjs (gated WEBJS_E2E=1).
• Landmine: the differential test masks the JS-loaded set (importmap, boot script, preload hints) so only the dangerous direction (SSR output changed) can fail. Over-ship is invisible to it by design.
• Dev-visibility verdicts: dev.js:882-884 (compute), L2146-2148 (SSR emit), L1001 (timing log seam). SseHub at listener-core.js:343; webjs-error browser listener at dev.js:2842.

This is a research / decision record plus a scoping issue. It stays In Progress while the hardening direction is confirmed.

[vivek7405]

Deep-dive Q1: router reconciliation invariants + fuzz-harness feasibility

Full read of packages/core/src/router-client.js (3633 lines). The swap entry point is applySwap (L2311), which branches to three paths: frame swap (L2455), deepest-shared-layout marker swap (L2496), and destructive full-body fallback (L2513). The keyed reconciler chain is swapMarkerRange then reconcileSiblings then diffElementInPlace then reconcileChildren (L2576-3003).

The full invariant set (21), with code location and origin

#	Invariant	Enforced at	Origin
1	Never reconcile into a hydrated custom element's subtree (its lit-html parts hold direct node refs; recursing corrupts them into dead clicks)	isHydratedComponent L2762 (tests Symbol.for('webjs.instance')); guard in diffElementInPlace L2738	INCIDENT #906/#907
2	Preserve slot projection when a component instance is reused (page-authored slotted content is not render-owned, so it IS reconciled: the one carve-out to #1)	reprojectSlottedContent L2868, called at L2739; actual/fallback transitions via slot.js	INCIDENT #908/#910/#912/#914
3a	Parse partial fragments in BODY context (document-context parse hoists the leading wj:children marker out of <body>, defeating the shared-slot match and forcing a destructive full-body swap that strips head CSS)	parseHTML L102 (uses body.setHTMLUnsafe)	INCIDENT #936
3b	Never remove <style> / <link rel=stylesheet> on soft nav (deliberate divergence from Turbo; the X-Webjs-Have reduced head means absent does not equal removed)	isPersistentHeadStyle L3282, mergeHead skip L3320	INCIDENT #936
4	Preserve outer-layout DOM identity (replace only the deepest shared layout's children slot)	collectChildrenSlots L724, longestSharedPath L772, swapMarkerRange L2576	DESIGN (core mechanism)
5	Add-only head merge on partial swap (runtime-injected head such as Tailwind CSS must survive)	addNewHeadElements L3232, used L2463 + L2504	DESIGN, reinforced by #936
6	Preserve live form/input/disclosure state (value, checked, selected, indeterminate, disabled, open, popover)	LIVE_ATTRS L3026, skipped in diffElementInPlace L2707/L2713	DESIGN (header comment L51)
7	Scroll restoration (manual control; snapshot scrollX/Y; restore on back/forward; instant scroll-to-top on forward; hash to scrollIntoView)	scrollRestoration='manual' L239, snapshotCurrent L802, popstate restore L900, forward instant L1864, hash L1858	DESIGN base + INCIDENT #603/#610 (instant scroll)
8	Blur the outgoing activator (avoid a stuck :focus-visible ring; do NOT steal focus to the new heading)	blurOutgoingFocus L2558, called in all 3 swap paths	DESIGN (a11y)
9	Permanent elements (data-webjs-permanent + id) survive by NODE identity across every swap path including nested	regraftPermanentElements L2201, regraftPermanentInSlice L2241, self-diff guard L2698, reconcileChildren regraft L2938	DESIGN feature #250/#343
10	View transitions opt-in (<meta name="view-transition">); wrap swaps, byte-identical fallback when absent	viewTransitionsEnabled L2131, runWithTransition L2153	DESIGN #343; races later fixed
11	webjs-frame partial swap takes precedence; a response missing the frame surfaces webjs:frame-missing rather than a silent full-page swap	applySwap step 1 L2455	DESIGN #253/#346; missing-frame INCIDENT #294
12	Streamed Suspense mid-swap (swap shell immediately, apply boundaries progressively, guard with isCurrent, forward late resolvers)	forwardSuspenseResolvers L3370, readStreamedShell L3389, applyStreamedResolve L3474, streamBoundariesProgressively L3500	FEATURE #471/#473
13	Nav supersession / abort (a late response must not clobber newer settled state)	activeAbortController L138, currentNavigationToken L148, token checks e.g. L3081	DESIGN (Turbo navigator.stop)
14	Cross-deploy hard reload + cache eviction on importmap / data-webjs-build / data-webjs-src / data-webjs-track mismatch; infinite-reload guard	applySwap L2335-2453	INCIDENT #147, #899/#900
15	Ingest SSR action seeds before components upgrade (a navigated async component resolves from seed, not a refetch)	scanSeeds(doc) L2317	FEATURE #472
16	Re-apply CSP nonce from the page-load meta across nav (a per-request nonce would be rejected by the original CSP cache)	getCspNonce L3137, cloneScriptWithCorrectNonce L3162, outerHTMLForDiff L3220	DESIGN (Turbo parity)
17	Custom-element upgrade after swap, traversing shadow roots; a global safety-net observer	upgradeCustomElements / upgradeTree L3345/L3351, ensureUpgradeObserver L156	INCIDENT (multiple)
18	Script reactivation after swap	reactivateScripts L3531	DESIGN
19	Failed nav recovers in place (preserve shell/scroll/focus; cancelable webjs:navigation-error) never a destructive reload	handleNavigationError L1631, renderInPlaceNavError L1581	FEATURE #249/#339
20	Do not hijack JS-handled links/forms (bubble-phase listeners so defaultPrevented is visible)	onClick L377, onSubmit L431, bubble registration L218	INCIDENT #151/#157
21	Optimistic loading skeleton is token-guarded (a slow nav's late failure cannot revert a faster settled nav)	applyOptimisticLoading L3049, restoreOptimistic L3077	DESIGN (per-segment loading.ts)

Net: roughly half the invariants are incident-hardened (1, 2, 3a, 3b, 7-instant, 11-missing, 14, 17, 20), and half are by-design mechanism (4, 5, 6, 9, 10, 12, 13, 15, 16, 18, 19, 21).

Property-based / fuzz-harness feasibility

Verdict: feasible and low-friction at the unit tier; a second browser tier is required for about 5 invariants.

Seams that make it easy: the module deliberately re-exports an internal test surface (L3541-3622): _applySwap, _reconcileChildren, _diffElementInPlace, _parseHTML, _collectChildrenSlots, _longestSharedPath, _keyOf, _mergeHead, _addNewHeadElements, _regraftPermanentElements, _regraftPermanentInSlice, _LIVE_ATTRS, plus nav-race controls (_navToken, _bumpNavToken, _setCurrentPageUrl), cache handles, and resets. The reconcile core is pure DOM-in / DOM-out (no fetch). The existing unit suite packages/core/test/routing/router-client.test.js (145 KB) already drives _applySwap / _reconcileChildren / _diffElementInPlace against linkedom globals stamped on globalThis before import. So a generator emitting (liveHTML, incomingHTML) tree pairs, parsing them, running the reconciler, and asserting oracles (keyed-node identity preserved, LIVE_ATTRS untouched, permanents kept by identity, stylesheets kept, unmatched removed) drops straight in. _keyOf / _LIVE_ATTRS being exported lets the oracle share the system-under-test's own key function.

Obstacles:

• applySwap / swapMarkerRange require document to be the live document (they call document.importNode, document.head/body, CSS.escape, sessionStorage, location). The fuzzer must set those globals and reset document.body / head per case, as the unit test does.
• linkedom is a weak oracle. Test comments flag missing CSS.escape, Web Storage, SubmitEvent, and, critically, no setHTMLUnsafe / DSD processing. So the dogfood: CSS drops on client-router soft nav on real Android Chrome (styled on refresh) #936 body-context DSD path (3a), shadow-root upgrade (17), and slot re-projection (2, which needs the real slot.js runtime + SLOT_STATE) are only faithful in a real browser.
• Invariant 1 depends on Symbol.for('webjs.instance') set by a real hydration (render-client.js); unit fuzzing can only simulate it by stamping the symbol manually.
• performNavigation / fetchAndApply / performSubmission are NOT exported; full-nav fuzzing needs the event + fetch monkey-patch harness, not the pure seam.
• No fast-check dependency exists today (only a hand-rolled seeded loop in test/serializer/round-trip-property.test.js); adding fast-check is the one new dev-dep.

Recommended shape: tier 1 uses node:test + linkedom + fast-check over _reconcileChildren / _diffElementInPlace / _applySwap (identity / attr / permanent / key / head invariants, where most regressions live); tier 2 is a small generative harness under web-test-runner (chromium/firefox/webkit already configured at web-test-runner.config.js) for the DSD / slot / hydrated-instance / stylesheet / view-transition invariants.

[vivek7405]

Deep-dive Q2: e2e soft-nav matrix coverage and holes

Sources read: test/e2e/e2e.test.mjs (77 tests), test/e2e/form-submission-and-race.test.mjs, test/e2e/nested-layout-partial-swap.test.mjs, and the browser suites under packages/core/test/routing/browser/ (reconcile-hydrated-component.test.js, view-transitions-permanent.test.js, destructive-fallback.test.js, partial-fragment-css.test.js, frame-*.test.js, nav-scroll-instant.test.js, page-action-submit.test.js, progressive-stream.test.js).

Covered today

• Nested layouts: nested-layout-partial-swap.test.mjs:44 (sidenav scroll + identity), :148 (back-button snapshot); e2e:1293 (header survives same-layout swap).
• Slots: e2e:1429 (nav away + back preserves projection), :1460 (input value in slotted content); the browser reconcile-hydrated suite (11 cases: actual/fallback transitions, named + default first-wins, slotchange semantics, nested-child non-clobber).
• Hydrated-component preservation: browser reconcile-hydrated L40/L71/L98 (dogfood: client router reconciler corrupts hydrated components on soft nav (dead click) #906/fix: client router must not reconcile into hydrated components #907); e2e:652/744/775 (counter after nav, rapid back-forth).
• Streamed Suspense: e2e:303/590 (feat: progressive soft-nav streaming in the client router (follow-up to #469) #473 progressive soft-nav), :575 (feat: <webjs-suspense> streaming SSR boundary + per-component streaming (follow-up to #469) #471 initial-load), :1169; browser progressive-stream.
• Forms / page actions: form-submission-and-race.mjs (GET promote, POST FormData, 422 in-place, data-no-router, abort race, scroll restore); e2e:2649-2760 (no-JS + enhanced 422/303); chat :2284.
• webjs-frame: e2e:2325/2380/2409/2457 (external link, _top break-out, aria-busy + events, lazy src self-load); browser frame-targeting / frame-missing / frame-src-self-load.
• View transitions: browser view-transitions-permanent.js (marker + frame wrapped, meta absent, startViewTransition unavailable).
• Scroll restoration: form-...:374 (back-button window scroll), nested-layout:148, browser nav-scroll-instant.
• Back/forward popstate: e2e:1152, nested-layout:148.
• Stylesheet preservation: browser destructive-fallback.js (dogfood: CSS drops on client-router soft nav on real Android Chrome (styled on refresh) #936: reduced-head keeps CSS, stale non-style removed, empty-have prefetch skipped), partial-fragment-css.js.
• Permanent element: e2e:1312 (partial swap identity); browser view-transitions-permanent.js:216/248/283 (full-body, frame, marker identity + counter-case).

Holes (untested combinations), prioritized

1. View transitions have no REAL-navigation e2e. Only browser tests that stub startViewTransition. No live-engine VT nav, and no VT with permanent-element or VT with streamed-boundary interaction (both mutate identity during the VT snapshot).
2. Shadow-DOM component preservation across a SOFT NAV. DSD tests (e2e:806-979) are initial-load / hydration only; the reconcile-hydrated suite is light-DOM. Nothing asserts a hydrated shadow component's subtree stays opaque (dogfood: client router reconciler corrupts hydrated components on soft nav (dead click) #906) across soft nav, nor that shadow-slot content behaves across nav.
3. Streamed Suspense with popstate / with abort. Streaming is only tested on forward nav. No back/forward-into-a-streaming-page, and no test that a superseded nav cancels a mid-stream reader (streamBoundariesProgressively isCurrent guard has unit coverage only).
4. Forms / page-action into a nested layout. The 422 in-place swap is tested single-layout only, never landing into a deep layout children slot.
5. Focus invariant (blurOutgoingFocus) has zero e2e assertion. Nothing verifies the focus ring is cleared or that focus is not stolen after a nav.
6. Scroll restoration into a deep nested-layout slot on FORWARD nav (only back-button + top-level window scroll tested).
7. Optimistic loading skeleton (applyOptimisticLoading / restoreOptimistic). No e2e that a per-segment loading template shows then reverts on fetch failure, and no race test that a slow nav's late failure does not revert a faster settled nav.
8. Cross-deploy hard reload / importmap-mismatch (applySwap L2335-2453). No e2e simulating a deploy bump mid-session (form-preservation, cache eviction, infinite-reload guard).
9. CSP-nonce path across soft nav. No e2e navigating under strict CSP (invariant 16 is unit / implied only).
10. Permanent element with a frame swap on popstate, and prefetch combined with frame or streaming. Prefetch is tested for plain links only (e2e:1985/2130/2186/2234).

The densest, best-covered areas are the light-DOM hydrated-component + slot reprojection paths (the #906/#908/#912 incident cluster) and stylesheet preservation (#936). The thinnest are live view-transition behaviour, shadow-DOM-across-soft-nav, streaming under popstate/abort, focus, and the optimistic-loading + cross-deploy paths.

[vivek7405]

Deep-dive Q3: elision contract-test gap

Test-suite inventory (packages/server/test/elision/, 16 files)

Three harness patterns are in use:

• Pattern A: inline source strings feeding the analyser unit (analyzeComponentSource, computeElidableComponents, extractRenderedTags). No filesystem, no graph.
• Pattern B: inline module-graph fixtures feeding analyzeElision via a run({ files, edges, components, routeModules }) helper that fakes the graph.
• Pattern C: a real fixture app + createRequestHandler (renders examples/blog on/off in one process).

Key files: analyze.test.js (52 KB, the per-component interactivity verdict), route-elision.test.js (inert / import-only page verdicts), path-aware-import-only.test.js (#963 truncated walk), differential-elision.test.js (the on/off guard), lifecycle-coverage.test.js and sigil-coverage.test.js (reflection guards asserting every core hook / sigil is classified, and that INTERACTIVITY_STATIC_FIELDS = ['shadow','interactive']).

The differential guard masking claim is confirmed

differential-elision.test.js: maskJsSet() (L46-70) strips the importmap <script>, every <script type="module"> (the boot set), all <link rel="modulepreload">, the vendor preconnect / dns-prefetch hints, and the data-webjs-build / data-webjs-src stamps before the byte comparison (L117-134). The file header states it: "Only the DANGEROUS direction (elision changed what the SSR emits) can fail here; the SAFE direction (over-ship) lives entirely inside the masked region" (L11-13). So over-ship is invisible to this guard by construction. The one non-vacuity check (L137-151) asserts the ON preload set is a strict subset of OFF, which only proves elision did some work on the known display-only badges, not any specific residual's verdict.

The two residuals: what IS and ISN'T tested

The escape hatch is a LIVE analyser signal, not docs-only, in code: INTERACTIVITY_STATIC_FIELDS = ['shadow','interactive'] (component-elision.js:153), reasons L157-158, applied in the verdict loop L570-575. The residuals THEMSELVES are prose-only (component-elision.js:144-148).

Tests that DO exist (all Pattern A, analyser-unit only):

• static interactive = true forces a ship: analyze.test.js:266 (Retire misleading static refresh and repurpose it as force-ship override static interactive #962).
• static interactive = false does not: analyze.test.js:281.
• static shadow = true always ships even when display-only: analyze.test.js:227 / L94 / L253.

Contract tests that are MISSING:

1. Residual (a): a runtime-computed tag string is elided WITHOUT the override. No test anywhere uses a variable / computed .register(tagVar) or customElements.define(expr, C) in the elision suite. The documented wrongly-elide behaviour is unasserted.
2. Residual (a) rescued: the SAME dynamic-tag component ships once static interactive = true is added. The generic override test (analyze.test.js:266) uses a statically analysable async-render component, not the dynamic-tag shape it is meant to rescue. The residual-to-override pairing is not captured.
3. Residual (b): an external stylesheet :defined rule outside the module graph. TAG_DEFINED_RE (component-elision.js:240) only detects :defined inside graph-reachable modules; the external-stylesheet residual is prose-only (L147-148) and untested.
4. No serve / boot / e2e-level assertion that static interactive = true forces an actual ship. Every override test stops at the analyzeComponentSource(...).interactive verdict; none proves dev.js / ssr.js keeps the module in the served boot script. static shadow has the same gap.

Where the missing tests naturally live

• The residual-verdict pair (dynamic tag elided without override; ships with it) belongs in analyze.test.js following the inline-source analyzeComponentSource(src) cases at L266-292. Cheapest and most direct.
• A graph-level ship assertion (module retained through analyzeElision) follows route-elision.test.js's run({ files, edges, components, routeModules }) helper (L36).
• An end-to-end "override actually ships" contract follows either differential-elision.test.js's createRequestHandler(examples/blog) pattern or the network-probe e2e cases in test/e2e/e2e.test.mjs:1578/1819. Neither examples/blog nor test/e2e/fixtures/ currently contains a static interactive = true component (grep confirms only static shadow = true fixtures exist), so an end-to-end residual test needs a new fixture component added there.

[vivek7405]

Deep-dive Q4: dev-time elision visibility

elision-report.js and how doctor invokes it

analyzeAppElision(appDir) (packages/server/src/elision-report.js:31) builds the module graph, scans components, builds the route table, runs analyzeElision over the page + layout set (L52-60), and returns { analysed, shipped: [{ file, blocker, reason }] } (the pages that ship whole with the first client-effecting blocker pinning each). It is advisory-only and returns empty for a non-app / malformed / elision-off app (L34-46).

Doctor invokes it in packages/cli/lib/doctor.js: checkElisionCarriers(appDir) (L814) dynamically imports analyzeAppElision from @webjsdev/server (L818) and warns one line per shipped page naming the blocker (L833-842). This runs only under webjs doctor (explicit, on-demand), never proactively during dev. It is pull, not push.

Where elision verdicts already live at request time

The authoritative dev-server verdicts are computed inside ensureReady() and stored on state:

• dev.js:882-884: state.elidableComponents, state.inertRouteModules, state.importOnlyRouteModules (set right after the analyzeElision call at L878-881).
• Consumed at serve time: dev.js:2069-2080 (source-stripping opts) and dev.js:2146-2148 (fed to the SSR boot emission).

So at first request the full verdict set is already in scope in ensureReady, in the same block where a per-pass timing breakdown and orphan-component warnings already log.

Push channels that exist in dev

1. Server console access log: logger.info('request', {...}) one line per request (dev.js:1284-1291); carries no elision data.
2. Server console analysis logs: ensureReady already emits a per-pass timing line including elision ${ms} (dev.js:1001, L994-998) and orphan-component warnings (dev.js:951-956), both gated if (dev). This is the natural seam: the verdicts at L882-884 are three lines above.
3. Browser dev error overlay: reportDevError (dev.js:793) then buildDevErrorFrame (dev-error.js) pushed over SSE as a webjs-error event, rendered client-side by reloadClientJs (dev.js:2785), which opens an EventSource and es.addEventListener('webjs-error', ...) (dev.js:2842). Fresh tabs get a replay (dev.js:1757). Errors-only today.
4. SSE / live-reload channel: SseHub in listener-core.js:343 with reload() (L369) and devError() (L372); the hub is built at dev.js:1627 and fs.watch rebuilds call hub.reload(). A new event type could fan out here.
5. Browser console: the client runtime does NOT log any elision summary in dev. reloadClientJs only wires reload + error handling. Browser console is currently silent about elision.

What it would take

• Server console (trivial): the verdicts are already in scope at dev.js:882-884, inside the if (dev) block that already logs at L950-957 / L1001. A one-time first-request summary ("N display-only components elided, N route modules dropped as inert / import-only, N shipped whole") is a few lines reusing state.elidableComponents / state.inertRouteModules / state.importOnlyRouteModules. For the "shipped instead of eliding" advisory (blocker + reason), reuse analyzeElision's shippedRouteModules map (already returned, Advisory diagnostic: explain why a page/layout ships (names the elision blocker) #646) or call analyzeAppElision exactly as doctor does.
• Browser console (small): no existing elision push to the browser, so add one via either (a) a dev-only inline <script> at the SSR boot (ssr.js, where state.importOnlyRouteModules is already passed at dev.js:2146-2148) that console.infos the summary on first paint, or (b) a new SSE event on the existing SseHub (listener-core.js:343, mirror devError()), logged client-side next to the webjs-error listener (dev.js:2842). The overlay / SSE path is the established precedent for pushing dev diagnostics to the tab.

Precedent for verdict reuse (check.js)

The no-server-import-in-browser-module rule does NOT thread dev.js's state; it re-runs the analysis independently over identical inputs: builds its own graph / components / routeTable (check.js:1381-1385), reconstructs the exact page + layout route-module set the dev server feeds analyzeElision (check.js:1392-1400, commented "exactly the set the dev server feeds"), reads the same elision flag via readElideEnabledForCheck (check.js:1428), and calls analyzeElision(...) directly (L1429-1431). So a new consumer has two clean options: reuse state.* in-process inside dev.js (populated at L882-884), or call analyzeElision / analyzeAppElision the way check.js and doctor do out of process. Both converge on the same verdict because they feed the same route-module set.

[vivek7405]

Deep-dive Q5: production-readiness scorecard (subsystems other than the router)

Note on the window: the repo history starts 2026-04-15, so "6 months" effectively means the repo's entire lifetime (1173 commits, 259 fix:). Only 7 open issues repo-wide. This is a heavily-dogfooded, low-open-debt codebase, so churn signals complexity, not instability, because nearly everything is closed.

Open-issue debt (all 7)

#	Bucket	Subsystem
976	research	this audit (meta)
975	enhancement	CLI agent affordances
973	bug	streaming RPC e2e flake (#489)
972	bug	streaming RPC e2e flake (same root cause)
957	documentation	dogfood Remix-clone experiment
934	bug	check / scanner false positive (reactive-props)
396	enhancement	publish VS Code extension

The only live code debt in the target subsystems is the streaming-RPC e2e flake (#972/#973): a mid-stream snapshot races the stream end.

Per-subsystem

1. Serializer / rich types: 5/5. 1 fix ever (harden the wire deserializer against prototype pollution, fix: harden the wire deserializer against prototype pollution #493). ~57 tests (packages/core/test/serializer/) including a property-based round-trip with cycles, plus proto-pollution on both JSON and non-JSON paths. All risky edges covered (invalid Date, non-primitive Map keys, self-referencing Map, BigInt, Blob/File/FormData byte-identity, typed arrays, cycles + shared refs, Symbol.for vs local-Symbol-throws, NaN/Infinity/-0, position-preserving undefined). Optional: confirm RegExp is intentionally unsupported (appears in no test).

2. Bun parity: 4/5. ~10 bun-surface fixes. 46 files in test/bun/. The runner scripts/run-bun-tests.js is soundness-first (zero-tests-run counts as failure, only a 3-entry documented denylist). Documented gap list is exactly one: 103 Early Hints (Bun.serve has no informational-response API), documented at listener-bun.js:37 and the runtime / deployment docs. Costs first-load latency only, never correctness. Permanent platform limit, no action beyond docs.

3. Caching correctness: 5/5. 4 fixes (atomic revalidateTag via store set-ops fix: make the revalidateTag index atomic via store set ops #768, cache() preserves rich types via RPC serializer fix: cache() preserves rich types via the RPC serializer, not JSON #759, per-user leak defense, de-magic'd auto-detection). ~95 tests across the cache dir + html-cache (21) + conditional-get (15). The multi-user leakage guard is strong: html-cache.js treats any Set-Cookie as per-user and never caches it, and serves fresh + warns when a render reads per-user request state (Add a server HTML response cache with TTL and on-demand revalidation #241, L264-310). Optional hardening: a cache() stampede / dedupe-under-load test; the Redis store path is denylisted everywhere (unit mocks only).

4. TypeScript stripper: 5/5. 0 fixes on ts-strip.js. ts-strip/ts-strip.test.js asserts amaro output is byte-identical to Node's built-in stripTypeScriptTypes (which is why the Bun path is safe), plus scanner-fuzz differential tests. Only gap: the parity test uses fixed sources, not a generated corpus. Adding a property / fuzz corpus feeding random valid TS through both strippers is the one real gap.

5. Server actions / RPC / CSRF / seed: 4/5. 5 fixes (sanitize prod action errors to generic message + digest fix: sanitize prod server-action errors to a generic message + digest #764/IMPORTANT: sanitize prod server-action error messages (verbatim leak of DB/internal errors) #749, seed facade fail-open fix: make the seed facade fail-open on an export-enumeration miss #538). CSRF csrf/csrf.test.js (11) covers the full Sec-Fetch-Site / Origin-fallback / allowlist model. Error sanitization (6, IMPORTANT: sanitize prod server-action error messages (verbatim leak of DB/internal errors) #749). Seed ~25 (feat: seed SSR action results into hydration so async render does not re-fetch (follow-up to #469) #472). Streaming (feat: streaming RPC results (return a ReadableStream/AsyncIterable from an action) #489) covered by browser + frame-protocol + verb-dispatch suites. The two open bugs (de-flake the streaming-RPC e2e (mid-stream snapshot races the stream end) #972/dogfood: de-flake the #489 streaming-RPC e2e (mid<final race) #973) are here: the streaming-RPC e2e is flaky (mid-stream snapshot races the stream end). Feature solid, test racy. Hardening: de-flake by waiting on a deterministic frame boundary rather than a timed snapshot; add a negative test for a forged x-forwarded-host on the Sec-Fetch-Site path.

6. Dev server / watch / reload: 4/5. Highest churn: 22 fixes, 94 touching commits (first-class hot-reload no-restart-flash fix: first-class dev hot-reload (no restart flash, watch outside appDir) #896, multi-tab live-reload + no empty-CSS fix: multi-tab dev live-reload + no empty-CSS on hot reload #890, reflect deploys via content signals fix: reflect app/framework deploys on client nav via content signals #900, bun --hot fix: hot-reload webjs dev under Bun via bun --hot (#514) #519). Most complex / most-iterated, trending toward stabilization. dogfood: dev live-reload infinite loop (browser refreshes ~5x/sec), reconnect treated as edit #968 (dev live-reload infinite loop, reconnect-as-edit) is CLOSED not-planned and was addressed by the reload-dedup work, but has no NAMED regression guard. Stale-CSS risk is explicitly guarded (dev.js:2013 avoids a watcher that could die mid-session; fix: multi-tab dev live-reload + no empty-CSS on hot reload #890 fixed empty-CSS-on-hot-reload). Hardening: add a named regression test reproducing the dogfood: dev live-reload infinite loop (browser refreshes ~5x/sec), reconnect treated as edit #968 reconnect loop; assert the Tailwind watcher restarts rather than serving stale after a mid-session crash.

7. Hydration / components / signals (core): 4.5/5. 17 fixes across component.js / render-client.js / render-server.js / signal.js / html.js (~71 touching commits): valid hydration marker so slots work on iOS fix(core): valid hydration marker so slot components work on iOS (#730) #744, in-place array reconcile fix: reconcile plain .map() arrays in place instead of rebuilding (#353) #354, attribute decode + first-paint comments fix: decode Object/Array attributes at SSR; comments first paint; kit idiom #221, DSD injection regex edges, boolean-attr SSR coercion. Very broad browser suite (300+ tests) under packages/core/test/*/browser/. Risky hydration edges (SSR-to-client parity, light-DOM hydration, reconcile) explicitly covered. The iOS / Safari DSD path (fix(core): valid hydration marker so slot components work on iOS (#730) #744) is the recurring fragile spot; add a Safari-lane assertion in CI if not already gated.

Stability signal (zero fixes ever)

serializer.js, csrf.js, conditional-get.js, ts-strip.js, sitemap.js have never received a fix: commit and were last touched weeks ago. Combined with strong coverage, these are the most production-hard, lowest-risk surfaces. (session.js 1 fix, rate-limit.js 2 fixes, also stable.)

Summary table

Subsystem	Rating	Fix churn	Tests	Open issues
Serializer	5	1	~57	0
Caching	5	4	~95	0
TS stripper	5	0	~20	0
Core hydration / signals	4.5	17	~300 browser	0
Bun parity	4	~10	46 files	0 (1 documented platform gap)
Actions / RPC / CSRF / seed	4	5	~120	2 (#972/#973 streaming e2e flake)
Dev server / watch	4	22	~40	0 (#968 closed not-planned)

Top hardening actions, ranked: (1) de-flake the #489 streaming-RPC e2e (#972/#973), the only live code debt; (2) add a fuzz corpus to the TS-stripper parity test; (3) add a named regression guard for the #968 dev reconnect loop.