feat(router): expose opt-in navigation diagnostics

[NathanDrake2406]

Overview

Area	Change
Configuration	Adds the disabled-by-default VINEXT_DEBUG_NAVIGATION=1 build-time flag
Runtime	Emits correlated reuse, prefetch, optimistic-shell, fetch, abort, synchronous history-restore, and commit events
Architecture	Keeps browser entry points wiring-only and places deterministic event construction and navigation correlation in a separate client module
Safety	Includes application URLs for correlation, but never response bodies, cookies, or request headers
Coverage	Exercises fresh dynamic-param navigation and committed-cache sibling-route Back restoration in a self-contained Playwright project

Why

Issue #2597 reports a navigation race whose final DOM mixes stale server-layout data with current client params. The reporter needs the existing structured NavigationTrace decisions at runtime together with the concrete RSC URL, cache key, fetch lifecycle, supersession, history-snapshot restoration, and final commit outcome.

Running the PR preview against the reporter's public reproduction now captures the failure: the B RSC request succeeds and reaches an authoritative commit, but that commit preserves the dynamic layout identity carried through the detached optimistic shell. The diagnostics therefore narrow the follow-up fix to the optimistic-to-authoritative preservation boundary rather than history snapshot restoration.

The original diagnostic path entered through navigateRsc(). Synchronous history-snapshot restores bypass that function, even though they can commit a cached route tree directly. Leaving that boundary unreported made the diagnostics incomplete for the issue's sibling-route Back symptom.

This PR adds observability without changing navigation decisions. Refs #2597.

What changed

Scenario	Before	After
Fresh or prefetched navigation	Correlated reuse, fetch, abort, and commit events	Unchanged
Synchronous history-snapshot restore	Commit event had no correlated start lifecycle	Emits a correlated traverse start followed by a committed-cache commit
Dynamic param A → Back → B	No issue-shaped diagnostic regression	Verifies B issues an RSC request and commits matching server/client params
Sibling child → Back	Restore path was not covered by diagnostics E2E	Verifies server page, client params, and usePathname() restore together
Diagnostic E2E bootstrap	Relied on inherited process state and could reuse a non-diagnostic optimized graph locally	Owns the build-time flag in a dedicated Vite config and forces optimizer isolation
Pages Router instrumentation tests	Request-error cleanup could erase the one-time startup signal in a parallel test	Clears only request errors and preserves the startup invariant

The diagnostic schema remains internal and may change between releases.

Validation

• vp check on all seven touched source, fixture, and E2E files
• vp test run tests/app-navigation-debug.test.ts tests/app-browser-entry.test.ts (228 tests)
• vp run vinext#build
• Dedicated app-router-navigation-debug Playwright project (3 tests)
• Pages Router instrumentation startup and error-reporting specs together (6 tests, 2 workers)
• The two App Router: soft navigation between different dynamic params reuses the committed shared-layout subtree without fetching the new RSC payload #2597-shaped browser cases repeated 10 times each (20 passes)
• Repository pre-commit staged checks, full check, and knip

Risk and compatibility

• No public API change.
• Diagnostics remain disabled by default.
• Navigation, history restoration, and cache decisions are unchanged.
• The restore lifecycle is started only after a snapshot is approved, so cache misses still fall through to the existing navigateRsc() lifecycle without a phantom diagnostic event.
• The reporter is settled in finally so failed restore attempts cannot leave stale diagnostic correlation state.

Non-goals

• This PR does not claim to fix App Router: soft navigation between different dynamic params reuses the committed shared-layout subtree without fetching the new RSC payload #2597.
• It does not expose a stable telemetry schema.
• It does not include response bodies, cookies, request headers, or rendered application data.
• It does not enable diagnostics for the shared App Router E2E suite.

References

Reference	Why it matters
Issue #2597	Reports stale dynamic-layout data and mixed sibling-route history restoration
Prior test-only debugger #1168	Earlier invariant debugger that did not expose browser lifecycle telemetry
Existing vinext navigation trace model	Structured planner and commit decision model reused by this PR
Next.js navigation debug-info boundary	Upstream precedent for retaining navigation debug context

Refs #2597

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@vinext/cloudflare@2598

npm i https://pkg.pr.new/create-vinext-app@2598

npm i https://pkg.pr.new/vinext@2598

commit: 078d53a

[github-actions]

Performance benchmarks

Compared 078d53a against base 8d0a18d using alternating same-runner rounds. Next.js was unchanged and skipped.

0 improved · 0 regressed · 6 within ±1.5%

Scenario	Framework	Baseline	Current	Change
Client bundle size (gzip)	vinext	126.6 KB	127.2 KB	⚫ +0.5%
Client entry size (gzip)	vinext	120.6 KB	121.2 KB	⚫ +0.5%
Dev server cold start	vinext	2.70 s	2.73 s	⚫ +1.2%
Production build time	vinext	2.86 s	2.83 s	⚫ -1.1%
RSC entry closure size (gzip)	vinext	98.6 KB	98.6 KB	⚫ -0.0%
Server bundle size (gzip)	vinext	165.3 KB	165.3 KB	⚫ -0.0%

View detailed results and traces

_{🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head}