[aralroca]

Four navigation gaps on one branch. Each was written test-first, and each failing test is quoted below.

---

1 — Announce and focus the new page

A cross-document load tells a screen-reader user the page changed. An SPA navigation told them nothing:

grep -n "focus()\|aria-live" packages/janux/src/client/navigate.ts   # zero results

And it was worse than "focus stays put". The diff replaces the link that was clicked, so focus fell back to <body> — the reader was silently dumped at the top of the document.

after an SPA navigation	before	after
document.activeElement	BODY	H1
live region	none	aria-live="assertive" with the new <title>

What changed — client/route-a11y.ts. Focus moves to the new page's <h1> (falling back to main / [role="main"]), made focusable with tabindex="-1" and focused with preventScroll. A visually hidden aria-live="assertive" aria-atomic="true" region carries the new <title>, clipped out of the flow so it is neither visible nor takes space, marked data-janux-keep so the diff does not delete it. Cleared and refilled in two turns, because a live region only speaks when its content changes.

Not stealing focus. Focus inside a persist island is saved before the diff and restored with its caret. It has to be restored, not left alone: the navigation lifts persisted islands out of the document, and removing a node blurs it. A widget the incoming page does not render is disposed, so that case falls back to the new content rather than stranding the reader on <body>.

VoiceOver was not verified end-to-end. I launched it against the real page but could not capture what it spoke: screencapture is blocked (no Screen Recording permission) and scripting VoiceOver's last phrase needs an Automation prompt that cannot be dismissed non-interactively. What I did verify is the layer VoiceOver reads — Chrome's AX tree (getFullAXTree): announcer live=assertive, atomic=true, ignored=false with child StaticText "Quick start — Janux docs", heading focused=true. 30-second manual check: build and start apps/docs, ⌘F5, click Quick start — expect "Quick start — Janux docs" and the VO cursor on the heading.

---

2 — Opt-in View Transitions

navigation.viewTransitions wraps navigations in a single transition, pairing elements that share a view-transition-name. No new API: CSSProperties extends csstype, so style={{ viewTransitionName: 'wordmark' }} already type-checks.

This one was blocked by a real bug. Wrapping the diff deadlocked: a transition renders-suppresses the document until its callback resolves, and requestAnimationFrame is tied to rendering, so rAF never fires inside one.

callback entered
rAF did NOT fire within 1500ms (+1509ms)
setTimeout fired (+1519ms)

diff-dom-streaming settled its stream walk on rAF alone, so the diff hung until Chrome's 4s cap killed the transition — the page froze for four seconds and then swapped with no animation at all. Fixed upstream in brisa-build/diff-dom-streaming#24, released as 0.6.9, which this PR requires.

The library's own transition: true avoids the deadlock but cannot produce a page morph — one transition per mutation batch, each skipping the last. Measured on one navigation: 51 started, 50 skipped, 1 animated.

	calls	animated	skipped
opted in	1	1	0
prefers-reduced-motion: reduce	0	0	0
apps/docs (not configured)	0	0	0

Tests assert ready resolved, not just that a call happened — an abandoned transition still applies the DOM change, so counting calls would pass on the very bug that blocked this.

Opting in changes how the page is applied: the incoming page is read in full before the swap instead of being diffed as it streams. The old page stays live and interactive for the whole download, then changes in one animated step. Apps that do not opt in keep the streaming diff untouched.

---

3 — Scroll restoration

Going back landed wherever the previous page happened to be. The browser offers to restore scroll for intercepted navigations, but it measures the document at that instant — and a page still streaming is far too short to hold the old offset, so the position is clamped away.

examples/hacker-news is the honest fixture: its list is a suspense island over a slow source, so coming back paints a 436px skeleton before the 649px list lands (36px vs 249px of scroll at the test viewport).

The failing test, before:

✗ restores the exact position when going back to a page that streams in
  Expected: 200   Received: 0

What changed — client/scroll.ts. The router takes scroll: 'manual', remembers each history entry's offset as it leaves it, and applies it as the last step of the swap. Traversals restore (back and forward), pushes open at the top, #anchor links still land on their anchor, and a superseded navigation never applies its offset.

That placement is what makes it agree with §2: the offset lands inside the transition, before the browser snapshots the new page, so the animation runs between two correctly-scrolled pages instead of animating to the old one and then jumping.

Verified in Chrome: before=200 onItem=0 afterBack=200 restored=true.

---

4 — Shallow routing

A filter, a tab or a URL-addressable dialog needs the address bar and the back button to be right while the page stays put. A query-only link was a full document load.

<a href="?tag=video" data-shallow>video</a>

janux.navigate('/orders?status=paid', { shallow: true, replace: true });

The URL and the history entry move; nothing is fetched and nothing re-renders — measured as 0 janux:navigate events with a sentinel on window surviving, against the same change without data-shallow, which destroys it.

Opt-in because a query param the server renders differently must still reach the server, and only the app knows which kind a param is.

The coherence fix urlState was missing: history.pushState fires no event, so a second binding on the same param silently went stale. Every shallow change now announces itself, so all bindings in every island read the same URL.

---

Not in this PR: parallel and intercepting routes

They stay on the roadmap. @slot and (.) are a router-grammar feature — directory parsing, multi-match resolution, slot-aware layouts, server render, plus soft-navigation semantics for modal-over-page and dismissal on back. That is comparable in size to everything above combined, and starting it here would have produced something half-done rather than the two items that were prioritised first. Both of those are closed and documented.

Docs

apps/docs/content/guide/navigation.md gains Scroll restoration, Shallow routing and View transitions (the last was shipped in §2 but undocumented, which also left a dangling anchor). architecture-and-roadmap.md's ships-today Routing line now names scroll restoration and shallow routing.

Gates

Branch synced with main (20 commits merged, conflicts were the test-count badge on both sides).

bun run test · bun run typecheck · bun run test:e2e (301 pass, 0 fail) · bun run test:census --min-coverage 0.93 (93.51% functions / 96.08% lines). Count updated to 4096.

The one failing test in bun run test (janux-vercel › "a bundled function with no node_modules beside it") is pre-existing on main — I verified it by checking out clean origin/main in a scratch worktree and reproducing it there. It is a @mcp-b/webmcp-polyfill × happy-dom Event incompatibility that only bites locally on macOS.

No examples/ workarounds; the four design invariants are untouched.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.