fix(router): redirect on cross-app navigation so the target document is fully re-established - #555

Problem

Under a host router (createHostRouter) that mounts multiple apps on one origin (e.g. a site app at / and a store app at /shop), a client-side navigation that crosses an app boundary renders the target app with a broken document. The component tree mounts, but document-level state is silently not re-established:

• Stylesheets shared across apps are dropped. React 19 de-duplicates <link rel="stylesheet"> by href. When the source app renders a shared href unmanaged (no precedence) and the target renders the same href managed, the soft switch removes the source's link and dedupes the target's against the still-registered href → the target renders unstyled (the .css bytes stay cached; only the applying <link> is gone). This is overwhelmingly a Tailwind problem: every app's @import "tailwindcss" compiles to one shared hashed asset.
• Theme never takes effect. applyAppShell deliberately omits themeConfig/initialTheme (also warmupEnabled, prefetchCacheTTL) — they're document-lifetime. So the target app runs under the source app's theme runtime; if the source has no theme and the target calls useTheme(), it throws.

The root cause is one class: a soft cross-app swap cannot faithfully re-establish the target app's document.

Fix

Make a cross-app navigation a real document navigation instead of a soft swap. A full document load re-establishes the entire target document — stylesheets, theme, meta, warmup, prefetch-TTL — by construction, fixing the whole class at once.

A cross-app SPA request (_rsc_partial with a _rsc_rid that doesn't match the matched app) now classifies as a terminal app-switch plan; the server emits X-RSC-Reload: <target> (the exact mechanism version-mismatch already uses), and the client — which already honors it — does window.location.href = target. Within-app navigation is unchanged (soft SPA).

Before vs. after

Same consumer code (a normal cross-app link); only the runtime behavior changes:

// In the site app (mounted at /), linking into the store app (mounted at /shop)
<Link to="/shop">Store</Link>

Semantics

Code changes

• router/request-classification.ts — new terminal AppSwitchReloadPlan (mode: "app-switch", clean reloadUrl); a cross-app partial returns it instead of silently downgrading to full-render. The check runs before route resolution (like version-mismatch), so a cross-app navigation to a route that doesn't exist in the target app still reloads — rather than throwing RouteNotFoundError and rendering the target's 404 in place under the source app's document.
• rsc/handler.ts — emits X-RSC-Reload for the app-switch plan.
• rsc/origin-guard.ts — app-switch classified terminal (no origin check) — the exhaustiveness guard required it.
• browser/partial-update.ts — the soft app-switch branch is removed (see cleanup below).

Cleanup (also in this PR)

With the soft cross-app transition gone, the client-side soft app-switch machinery is dead:

• Removed the dead soft-switch machinery (net −159 lines): applyAppShell + the unused updateAppShell, AppShellRef.update (the shell is set once at init, read-only now), the clearHistoryCacheLocal → clearCacheInternalLocal → clearPrefetchCacheLocal chain, and setRangoStateLocal — each only reachable through the soft app-switch that no longer happens. clearPrefetchCache (the broadcasting variant) stays.
• Removed the dead store.setRouterId sync in partial-update.ts — it re-read routerId from partial payloads, but routerId is a session constant (seeded at init, restored from history-cache on popstate, cross-app crossings hard-reload), so it stored a value the store already held.
• routerId stays serialized in all payloads (full + partial + action) so the frontend can read the current app/router identity. With the redirect it always equals the current app's id — a cross-app crossing is intercepted server-side (X-RSC-Reload) and never delivers a different-router payload, so it can't signal a different router at runtime, but it remains available as the current-app identity.
• version unchanged — the dev HMR refetch (classified partial-render) learns a bumped version only from that payload (no reload in dev), so it must stay; it looks redundant on the steady-state nav path (which only sends _rsc_v outbound) but the HMR refetch rides the same branch.

Client integrity guard (defense in depth)

The server is authoritative for cross-app detection, but the client previously trusted that a response belonged to its app and applied whatever came back. Two complementary layers now verify it — both inert in normal operation (within-app responses carry a matching routerId; cross-app crossings redirect), firing only if a foreign payload appears from a stale/edge cache, a proxy mixing responses, or a server bug:

• Pre-decode (header). The server stamps X-RSC-Router-Id on RSC content responses only (not on control reload/redirect responses, so reloads stay self-steering). The client checks it via checkRouterIdHeader (both-present guard) before createFromFetch — refusing a foreign payload before its chunks are imported. Wired, ordered strictly after the reload handler (no reload loop), into: navigation (validateRscHeaders → reload to target), server actions (server-action-bridge → reload — this apply path has its own decode and is not covered by the post-decode guard, so it was the real gap), and prefetch (executePrefetchFetch → drop, never warm).
• Post-decode (payload). The partial-update guard rejects a payload whose metadata.routerId mismatches before merge. Kept as the authoritative backstop for the warm/inflight-prefetch reuse paths (navigation runs no fetch at click time, so the pre-decode nav check is bypassed) and any header-absent response.

This is the concrete reason routerId stays serialized in every payload. The full server response-site + client decode-site surface was mapped (incl. bypass + false-positive analysis) so no path is missed and no legitimate response (init/redirect/reload/unseeded) can false-fire.

Test plan

• Unit (request-classification.test.ts): a cross-app partial → app-switch reload with the clean URL; a cross-app partial to a missing route (findMatch → null) still classifies as app-switch (not a throw); a direct (non-partial) cross-app load still full-render.
• e2e — dev + production (examples/cloudflare-multi-router): a cross-app nav does a full reload (expectFullReload helper); the target's CSS applies afterward (including a stylesheet shared across apps, via shared-tailwind.css); the target's theme applies (app-b opts into data-theme, site doesn't → <html data-theme="dark"> after the switch); and a cross-app nav to a missing target route (/app-b/does-not-exist) reloads rather than 404-ing in place — proven to catch the regression (disabling the reload check makes this test fail); and a same-app nav to a missing route stays a soft in-place 404 (no reload — only crossing an app boundary reloads). Within-app nav still asserts expectNoReload. 54 passed.
• Unit — integrity guard. partial-update.test.ts (post-decode: mismatch discarded+reload, match applied); response-adapter.test.ts (checkRouterIdHeader match/mismatch/absent — the false-positive guard); navigation-client.test.ts (mismatch → reload to target; reload header wins over a routerId mismatch — no double reload); prefetch-fetch.test.ts (mismatch → dropped, never decoded).
• typecheck, unit (3402), lint, format.
• Full router e2e — 1667 passed; the only failures were flaky hmr-intercept (confirmed green in a clean isolated run — HMR reads version, which is kept, never routerId), plus the CI-excluded route-types-hmr watcher tests. The cleanup was independently verified by an earlier full e2e (1684 passed).

Notes / follow-ups

• This intentionally removes the soft cross-app transition (every cross-app nav is now a full document load). For independently-authored apps with separate documents/themes, a hard boundary is the correct semantics. Within-app navigation is unaffected.
• The soft applyAppShell machinery (+ the rango-state "smooth cross-app transition" helpers) has been removed in this PR (see the cleanup section above). routerId remains serialized in payloads as the current-app identity for frontend consumers.
• Skills updated in this PR: /host-router (cross-app = full reload), /css (general CSS guidance; precedence is good practice, not a cross-app requirement), /tailwind (same), /rango catalog.
• This supersedes an earlier soft-fix approach (a dev+prod "stylesheet dropped" warning + "use precedence everywhere" guidance), which the theme finding showed was incomplete — the reload fixes the whole class.