fix(app-router): announce committed route changes

[NathanDrake2406]

Overview

Goal	Restore Next.js-compatible route announcements for App Router soft navigations
Runtime boundary	Client-side App Router commits only
User impact	Screen readers receive the new page title, or first h1 as a fallback, after navigation
Compatibility	Uses Next.js's next-route-announcer shadow-DOM contract

Why

vinext updates the document title during App Router navigation, but it did not expose Next.js's route-announcer live region. A client navigation therefore changed the visible page without announcing that change to assistive technology.

The important lifecycle invariant is that an announcement must describe content the user can actually see. Tying the effect to the generic render ID could announce a render that was later superseded or aborted. This implementation instead reacts to visibleCommitVersion, vinext's approved visible-commit boundary.

What changed

• Add an App Router announcer with the same custom-element name, shadow root, live-region attributes, and visually hidden styling as Next.js.
• Leave the live region empty on initial hydration because the browser already announces a full document load.
• After an approved soft-navigation commit, announce a changed document.title, falling back to the first h1.
• Mount the announcer alongside the route error boundary so route rendering failures do not tear down the accessibility primitive.
• Add a Playwright regression that observes the real shadow-DOM live region before and after a client-side navigation.

Behavior

Scenario	Result
Initial document load	Announcer exists but stays empty
Approved soft navigation	Announces the changed title or first heading
Superseded or aborted render	No announcement because no visible commit occurred
Repeated identical title	No duplicate announcement

References

• Next.js App Router implementation: app-router-announcer.tsx
• Next.js browser coverage: app-a11y E2E test
• Related Pages Router work: #2571. That PR implements the Pages Router path in shims/router.ts; this PR covers the separate App Router runtime and has no overlapping files.

Verification

The regression was first run without the implementation and failed because the announcer host was absent (null instead of an empty live region).

• vp check
  • 2,431 files correctly formatted
  • no warnings, lint errors, or type errors in 1,081 files
• Focused App Router navigation matrix
  • 16 test files passed
  • 402 tests passed
• vp run vinext#build
  • passed
• PLAYWRIGHT_PROJECT=app-router npx playwright test tests/e2e/app-router/nextjs-compat/metadata.spec.ts
  • 9 tests passed, including the new route-announcer regression
• Commit hooks
  • staged checks, full check, and knip passed

Scope and risk

This is client-only App Router behavior. It adds no dependency, configuration, server, Workers, or public API surface. The live region uses a shadow root to prevent application CSS from changing its accessibility behavior.

Pages Router announcements remain owned by #2571. Focus management and generic navigation-status UI are intentionally out of scope.

[pkg-pr-new]

Open in StackBlitz

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

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

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

commit: 8324f7f

[github-actions]

Performance benchmarks

Compared 8324f7f 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.1 KB	⚫ +0.4%
Client entry size (gzip)	vinext	120.6 KB	121.1 KB	⚫ +0.4%
Dev server cold start	vinext	2.22 s	2.25 s	⚫ +1.4%
Production build time	vinext	2.32 s	2.31 s	⚫ -0.3%
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}