@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.a99e6916

package/skills/prerender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prerender
-description: Pre-render route segments at build time with Prerender and passthrough fallback
+description: Pre-render route segments at build time with Prerender and Passthrough live fallback
 argument-hint: [passthrough]
 ---
 
@@ -54,8 +54,14 @@ path("/blog/:slug", BlogPost, { name: "blog.post" })
 
 ### With Passthrough (live fallback for unknown params)
 
+Wrap a `Prerender` definition with `Passthrough()` to add a separate live handler
+for unknown params at runtime. The build handler runs at build time, the live
+handler runs at request time.
+
 ```typescript
-export const ProductPage = Prerender(
+import { Prerender, Passthrough } from "@rangojs/router";
+
+export const ProductPageDef = Prerender(
   async () => {
     const top = await db.query("SELECT id FROM products WHERE featured");
     return top.map(p => ({ id: p.id }));
@@ -64,32 +70,41 @@ export const ProductPage = Prerender(
     const product = await db.query("SELECT * FROM products WHERE id = ?", ctx.params.id);
     return <Product data={product} />;
   },
-  { passthrough: true, concurrency: 4 }
+  { concurrency: 4 }
 );
+
+// In route definition:
+path("/products/:id", Passthrough(ProductPageDef, async (ctx) => {
+  const product = await ctx.env.DB.query("SELECT * FROM products WHERE id = ?", ctx.params.id);
+  return <Product data={product} />;
+}), { name: "product" })
 ```
 
-## Passthrough Mode
+## Passthrough Wrapper
 
-Controls whether the handler stays in the RSC server bundle after build:
+`Passthrough(prerenderDef, liveHandler)` wraps a `Prerender` definition with a
+separate handler for runtime fallback. The build and live handlers are separate
+functions — no `ctx.build` branching needed.
 
-|                     | `passthrough: false` (default)          | `passthrough: true`                     |
-| ------------------- | --------------------------------------- | --------------------------------------- |
-| Known params        | Served from pre-rendered Flight payload | Served from pre-rendered Flight payload |
-| Unknown params      | Handler evicted, no live fallback       | Handler runs live at request time       |
-| `ctx.passthrough()` | Throws (not allowed)                    | Skips artifact, defers to live fallback |
-| Bundle size         | Handler code + imports removed          | Handler code kept in RSC bundle         |
-| `revalidate()`      | Not allowed (handler gone)              | Allowed (handler can re-render)         |
-| `loading()`         | Ignored (segments fully resolved)       | Works for live fallback renders         |
+|                     | Plain `Prerender` (no wrapper)          | `Passthrough(def, liveHandler)`          |
+| ------------------- | --------------------------------------- | ---------------------------------------- |
+| Known params        | Served from pre-rendered Flight payload | Served from pre-rendered Flight payload  |
+| Unknown params      | Handler evicted, no live fallback       | Live handler runs at request time        |
+| `ctx.passthrough()` | Throws (not on Passthrough route)       | Skips artifact, defers to live handler   |
+| Bundle size         | Build handler code + imports removed    | Build handler evicted, live handler kept |
+| `revalidate()`      | Not allowed (handler gone)              | Allowed (live handler can re-render)     |
+| `loading()`         | Ignored (segments fully resolved)       | Works for live fallback renders          |
 
-### When to use passthrough
+### When to use Passthrough
 
-Use `passthrough: true` when:
+Use `Passthrough()` when:
 
 - The route has a large or open-ended param space (e.g., user profiles, product pages)
 - You want to pre-render popular/known params for speed but still serve unknown params live
 - You need `revalidate()` on the route
+- The live handler needs runtime bindings (e.g., `ctx.env.DB`)
 
-Use `passthrough: false` (default) when:
+Use plain `Prerender` (no wrapper) when:
 
 - All possible params are known at build time (e.g., markdown files, config-driven pages)
 - You want maximum bundle size reduction (handler code + node:fs imports removed)
@@ -103,6 +118,7 @@ Handlers receive `BuildContext` at build time, a subset of the runtime `HandlerC
 interface BuildContext<TParams> {
   params: TParams; // From getParams
   build: true; // Always true at build time
+  dev: boolean; // true in Vite dev mode, false during production build
   use: <T>(handle: Handle<T>) => (data: T) => void; // Push handle data
   url: URL; // Synthetic URL from pattern + params
   pathname: string; // Pathname from synthetic URL
@@ -115,8 +131,9 @@ interface BuildContext<TParams> {
     params?: Record<string, string>,
     search?: Record<string, unknown>,
   ): string; // URL generation
-  passthrough(): PrerenderPassthroughResult; // Skip local artifact (passthrough routes only)
-  // NOT available: req, headers, cookies, env (throws descriptive errors)
+  passthrough(): PrerenderPassthroughResult; // Skip local artifact (Passthrough routes only)
+  env: DefaultEnv; // Available when buildEnv is configured in rango() (throws otherwise)
+  // NOT available: request, headers, cookies (always throw)
 }
 ```
 
@@ -183,18 +200,17 @@ In production builds, `Prerender` exports are replaced with stubs:
 // Original
 export const BlogPost = Prerender(getParams, handler);
 
-// Stubbed (ships to server bundle when passthrough: false)
+// Stubbed (all Prerender handlers are evicted)
 export const BlogPost = {
   __brand: "prerenderHandler",
   $$id: "abc123#BlogPost",
 };
 ```
 
-The original module and its imports (node:fs, markdown libs) are excluded from
-the bundle. With `passthrough: true`, the handler code stays in the RSC bundle.
+All Prerender handlers are evicted in production. The live handler for
+`Passthrough()` routes lives in the urls module and is not evicted.
 
-In client and SSR environments, ALL prerender handlers are always stubbed
-(passthrough only affects the RSC server bundle).
+In client and SSR environments, ALL prerender handlers are always stubbed.
 
 ## Sub-use Semantics
 
@@ -231,15 +247,15 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 | DSL item       | Behavior with Prerender                                                                                                                                                                                                                                             |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                       |
-| `revalidate()` | Not allowed without passthrough. Allowed with passthrough.                                                                                                                                                                                                          |
+| `revalidate()` | Not allowed without Passthrough. Allowed with Passthrough.                                                                                                                                                                                                          |
 | `cache()`      | Orthogonal -- use on parent layouts and loaders.                                                                                                                                                                                                                    |
 | `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                |
 | `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                        |
 | `middleware()` | Skipped during pre-render (no request). Runs at request time for loaders.                                                                                                                                                                                           |
-| `loading()`    | Ignored without passthrough. Works for live fallback with passthrough.                                                                                                                                                                                              |
+| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                              |
 | `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when()` conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
-When passthrough revalidation is enabled, remember that revalidation is
+When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
 implicitly re-run outer prerender-derived handlers/layouts.
 
@@ -304,12 +320,19 @@ export const BlogPost = Prerender(
     }
     return <PostPage slug={ctx.params.slug} />;
   },
-  { passthrough: true },
 );
+
+// Wrap with Passthrough to serve skipped params live at runtime
+export const BlogPost = Passthrough(BlogPostDef, async (ctx) => {
+  if (ctx.params.slug === "draft") {
+    throw new Skip("Draft articles are not pre-rendered");
+  }
+  return <PostPage slug={ctx.params.slug} />;
+});
 ```
 
-Skipped entries are excluded from the build output. With `passthrough: true`,
-the handler stays in the bundle and serves skipped params live at request time.
+Skipped entries are excluded from the build output. With `Passthrough()`,
+the live handler serves skipped params at request time.
 
 `Skip` also works in `Static` handlers:
 
@@ -326,7 +349,7 @@ export const TocSidebar = Static(() => {
 | Handler outcome             | Effect                                                |
 | --------------------------- | ----------------------------------------------------- |
 | JSX / `null`                | Normal prerender entry, log OK                        |
-| `return ctx.passthrough()`  | Skip entry, log PASS, continue (passthrough routes)   |
+| `return ctx.passthrough()`  | Skip entry, log PASS, continue (Passthrough routes)   |
 | `throw new Skip("reason")`  | Skip entry, log SKIP, continue with remaining entries |
 | `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail the build      |
 
@@ -366,56 +389,59 @@ falls back according to normal dev/runtime behavior.
 
 ## Per-Param Passthrough with ctx.passthrough()
 
-On `{ passthrough: true }` routes, a handler can return `ctx.passthrough()`
-to skip writing a local prerender artifact for a specific param set. At
-runtime, the missing entry falls through to the live handler.
+On routes wrapped with `Passthrough()`, the build handler can return
+`ctx.passthrough()` to skip writing a local prerender artifact for a specific
+param set. At runtime, the missing entry falls through to the live handler.
 
 ```typescript
-export const BlogPost = Prerender(
+export const BlogPostDef = Prerender(
   async () => [{ slug: "a" }, { slug: "b" }, { slug: "c" }],
   async (ctx) => {
     const post = await getPost(ctx.params.slug);
     if (!post) return ctx.passthrough();
     return <article>{post.content}</article>;
   },
-  { passthrough: true },
 );
+
+export const BlogPost = Passthrough(BlogPostDef, async (ctx) => {
+  const post = await getPost(ctx.params.slug);
+  return <article>{post.content}</article>;
+});
 ```
 
 ### Semantics
 
-- JSX or `null` from the handler produces a normal prerender entry.
+- JSX or `null` from the build handler produces a normal prerender entry.
 - `ctx.passthrough()` returns a sentinel that signals "no local artifact".
   The build skips the manifest entry for that param set.
-- `ctx.passthrough()` on a non-passthrough route throws an invariant error.
+- `ctx.passthrough()` on a route not wrapped with `Passthrough()` throws.
 - `ctx.passthrough()` at runtime (`ctx.build === false`) also throws.
   It is a build-time-only control flow.
-- `getParams()` still enumerates the param set; the handler decides per-param
-  whether to produce an artifact or defer to runtime.
+- `getParams()` still enumerates the param set; the build handler decides
+  per-param whether to produce an artifact or defer to the live handler.
 
 ### Difference from Skip
 
-| Mechanism           | Effect on build        | Runtime behavior                                     |
-| ------------------- | ---------------------- | ---------------------------------------------------- |
-| `throw new Skip()`  | Skips entry, logs SKIP | No artifact, no live fallback unless passthrough     |
-| `ctx.passthrough()` | Skips entry, logs PASS | Always defers to live handler (requires passthrough) |
+| Mechanism           | Effect on build        | Runtime behavior                                       |
+| ------------------- | ---------------------- | ------------------------------------------------------ |
+| `throw new Skip()`  | Skips entry, logs SKIP | No artifact, no live fallback unless Passthrough route |
+| `ctx.passthrough()` | Skips entry, logs PASS | Always defers to live handler (requires Passthrough)   |
 
-Use `ctx.passthrough()` when you want the handler to run live at request time
+Use `ctx.passthrough()` when you want the live handler to run at request time
 for specific params. Use `Skip` when you want to exclude params entirely.
 
 ### Use case: Remote storage
 
 `ctx.passthrough()` enables a pattern where build-time data is stored in a
-remote KV store instead of the local prerender manifest. The handler
+remote KV store instead of the local prerender manifest. The build handler
 pre-computes data during `getParams`, pushes it to KV, then calls
 `ctx.passthrough()` so the local build skips the artifact. At runtime,
-the live handler reads from KV:
+the Passthrough live handler reads from KV:
 
 ```typescript
-export const Product = Prerender(
+export const ProductDef = Prerender(
   async () => {
     const products = await db.getFeaturedProducts();
-    // Pre-compute and store in remote KV during build
     for (const p of products) {
       await kv.put(`product:${p.id}`, await renderProduct(p));
     }
@@ -423,14 +449,16 @@ export const Product = Prerender(
   },
   async (ctx) => {
     // At build time: skip local artifact, data is in KV
-    if (ctx.build) return ctx.passthrough();
-    // At runtime: read from KV
-    const cached = await kv.get(`product:${ctx.params.id}`);
-    if (cached) return cached;
-    return <Product data={await db.getProduct(ctx.params.id)} />;
+    return ctx.passthrough();
   },
-  { passthrough: true },
 );
+
+export const Product = Passthrough(ProductDef, async (ctx) => {
+  // At runtime: read from KV, fall back to DB
+  const cached = await kv.get(`product:${ctx.params.id}`);
+  if (cached) return cached;
+  return <Product data={await ctx.env.DB.getProduct(ctx.params.id)} />;
+});
 ```
 
 ### Build logs
@@ -458,8 +486,8 @@ Flight payload. They do not update at request time.
 ### Server actions work normally
 
 Actions do not re-render the B segment. The pre-rendered handler output stays
-frozen. Loaders are live and can be revalidated by actions. With `passthrough: true`
-and `revalidate()`, the handler itself can re-render live.
+frozen. Loaders are live and can be revalidated by actions. With `Passthrough()`
+and `revalidate()`, the live handler can re-render.
 
 ### Empty getParams
 
@@ -470,21 +498,21 @@ If `getParams` returns an empty array, no Flight payloads are written. No error.
 Routes using `Prerender` must have a `name` in path options.
 The name is used as the storage key for Flight payloads.
 
-### No revalidate without passthrough
+### No revalidate without Passthrough
 
-Using `revalidate()` with `passthrough: false` produces a build-time warning.
+Using `revalidate()` without `Passthrough()` produces a build-time warning.
 The handler is evicted -- there is nothing to re-render.
 
-### loading() is ignored without passthrough
+### loading() is ignored without Passthrough
 
 Pre-rendered segments are fully resolved at build time and never suspend.
-With `passthrough: true`, `loading()` works for live fallback renders.
+With `Passthrough()`, `loading()` works for live fallback renders.
 
 ## Complete Example
 
 ```typescript
 // pages/guides-handler.tsx
-import { Prerender } from "@rangojs/router";
+import { Prerender, Passthrough } from "@rangojs/router";
 import { Link } from "@rangojs/router/client";
 import { href } from "../router.js";
 
@@ -493,7 +521,7 @@ const knownGuides: Record<string, string> = {
   caching: "Caching Guide",
 };
 
-export const GuidesDetail = Prerender<{ slug: string }>(
+export const GuidesDetailDef = Prerender<{ slug: string }>(
   async () => Object.keys(knownGuides).map((slug) => ({ slug })),
   async (ctx) => {
     const title = knownGuides[ctx.params.slug] ?? `Guide: ${ctx.params.slug}`;
@@ -509,9 +537,23 @@ export const GuidesDetail = Prerender<{ slug: string }>(
       </div>
     );
   },
-  { passthrough: true },
 );
 
+export const GuidesDetail = Passthrough(GuidesDetailDef, async (ctx) => {
+  const title = knownGuides[ctx.params.slug] ?? `Guide: ${ctx.params.slug}`;
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>Slug: {ctx.params.slug}</p>
+      <nav>
+        <Link to={href("guides.detail", { slug: "routing" })}>Routing</Link>
+        {" | "}
+        <Link to={href("guides.detail", { slug: "dynamic-test" })}>Dynamic</Link>
+      </nav>
+    </div>
+  );
+});
+
 // pages/guides.tsx
 import { urls } from "@rangojs/router";
 import { GuidesDetail } from "./guides-handler.js";
@@ -588,12 +630,12 @@ Loaders run fresh at request time for both variants.
 Pre-rendered routes set flags on the route trie leaf at build time:
 
 - `pr: true` -- route has pre-rendered B segment data
-- `pt: true` -- passthrough mode (handler available for live fallback)
+- `pt: true` -- route wrapped with `Passthrough()` (live handler available)
 
 At runtime, the cache-lookup middleware uses these flags:
 
 - `pr + hit` -- serve pre-rendered Flight payload
-- `pr + pt + miss` -- fall through to live handler (handler kept in bundle)
+- `pr + pt + miss` -- fall through to Passthrough live handler
 - `pr + miss` (no pt) -- fall through (handler stubbed, no live render)
 
 ## Contributor Checklist
@@ -603,7 +645,7 @@ Before changing prerender behavior, read these docs and run these tests.
 ### Docs to re-read
 
 - [Prerender API design](../../docs/prerender-api-design.md) -- canonical
-  architecture: build-time flow, runtime flow, storage, passthrough, intercept
+  architecture: build-time flow, runtime flow, storage, Passthrough, intercept
 - [Execution model](../../docs/internal/execution-model.md) -- handler-first
   ordering, middleware scope, context visibility rules
 - [Semantic change checklist](../../docs/internal/semantic-change-checklist.md)
@@ -612,7 +654,7 @@ Before changing prerender behavior, read these docs and run these tests.
 ### Tests to run
 
 ```bash
-# Core prerender e2e (passthrough, eviction, loaders, sub-use, intercept)
+# Core prerender e2e (Passthrough, eviction, loaders, sub-use, intercept)
 pnpm --filter @rangojs/router exec playwright test prerender
 
 # Prerender-specific unit test
@@ -632,7 +674,7 @@ pnpm --filter @rangojs/router exec playwright test handler-first
   `/__rsc_prerender` endpoint tests and node.js dev-server fallback.
 - Log-based assertions (build output lines, debug cache logs) are inherently
   dev/build-only and do not need a production counterpart.
-- Behavioral assertions (rendered content, loader freshness, passthrough
+- Behavioral assertions (rendered content, loader freshness, Passthrough
   fallback, intercept variant selection) must work in the production build.
 
 ## Maintenance References

package/skills/rango/SKILL.md

@@ -10,28 +10,30 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 
 ## Skills
 
-| Skill              | Description                                                                |
-| ------------------ | -------------------------------------------------------------------------- |
-| `/router-setup`    | Create and configure the RSC router                                        |
-| `/route`           | Define routes with `urls()` and `path()`                                   |
-| `/layout`          | Layouts that wrap child routes                                             |
-| `/loader`          | Data loaders with `createLoader()`                                         |
-| `/middleware`      | Request processing and authentication                                      |
-| `/intercept`       | Modal/slide-over patterns for soft navigation                              |
-| `/parallel`        | Multi-column layouts and sidebars                                          |
-| `/caching`         | Segment caching with memory or KV stores                                   |
-| `/use-cache`       | Function-level caching with `"use cache"` directive                        |
-| `/cache-guide`     | When to use `cache()` vs `"use cache"` — differences and decision guide    |
-| `/document-cache`  | Edge caching with Cache-Control headers                                    |
-| `/theme`           | Light/dark mode with FOUC prevention                                       |
-| `/links`           | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
-| `/hooks`           | Client-side React hooks                                                    |
-| `/typesafety`      | Type-safe routes, params, href, and environment                            |
-| `/host-router`     | Multi-app host routing with domain/subdomain patterns                      |
-| `/tailwind`        | Set up Tailwind CSS v4 with `?url` imports                                 |
-| `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
-| `/mime-routes`     | Content negotiation — same URL, different response types via Accept header |
-| `/fonts`           | Load web fonts with preload hints                                          |
+| Skill                   | Description                                                                |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `/router-setup`         | Create and configure the RSC router                                        |
+| `/route`                | Define routes with `urls()` and `path()`                                   |
+| `/layout`               | Layouts that wrap child routes                                             |
+| `/loader`               | Data loaders with `createLoader()`                                         |
+| `/middleware`           | Request processing and authentication                                      |
+| `/intercept`            | Modal/slide-over patterns for soft navigation                              |
+| `/parallel`             | Multi-column layouts and sidebars                                          |
+| `/caching`              | Segment caching with memory or KV stores                                   |
+| `/use-cache`            | Function-level caching with `"use cache"` directive                        |
+| `/cache-guide`          | When to use `cache()` vs `"use cache"` — differences and decision guide    |
+| `/document-cache`       | Edge caching with Cache-Control headers                                    |
+| `/theme`                | Light/dark mode with FOUC prevention                                       |
+| `/links`                | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
+| `/hooks`                | Client-side React hooks                                                    |
+| `/typesafety`           | Type-safe routes, params, href, and environment                            |
+| `/host-router`          | Multi-app host routing with domain/subdomain patterns                      |
+| `/tailwind`             | Set up Tailwind CSS v4 with `?url` imports                                 |
+| `/response-routes`      | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/mime-routes`          | Content negotiation — same URL, different response types via Accept header |
+| `/fonts`                | Load web fonts with preload hints                                          |
+| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango                              |
+| `/migrate-react-router` | Migrate a React Router / Remix project to Rango                            |
 
 ## Quick Start
 

package/skills/router-setup/SKILL.md

@@ -78,6 +78,11 @@ interface RSCRouterOptions<TEnv> {
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
+  // URL prefix for sub-path deployments (e.g. "/admin")
+  // All routes, reverse(), href(), Link, redirect(), and router.use()
+  // patterns are automatically prefixed. Route names stay unprefixed.
+  basename?: string;
+
   // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
@@ -124,6 +129,36 @@ interface RSCRouterOptions<TEnv> {
 }
 ```
 
+## Basename (Sub-Path Deployment)
+
+When your app is served under a sub-path (e.g. `/admin` or `/v2`), set `basename`:
+
+```typescript
+const router = createRouter({
+  basename: "/admin",
+  document: Document,
+}).routes(({ path, include }) => [
+  path("/", Dashboard, { name: "home" }), // matches /admin
+  path("/users", Users, { name: "users" }), // matches /admin/users
+  include("/api", apiPatterns, { name: "api" }), // matches /admin/api/*
+]);
+
+router.reverse("home"); // "/admin"
+router.reverse("users"); // "/admin/users"
+```
+
+Router-owned APIs are basename-aware:
+
+- `reverse()` returns prefixed paths
+- `<Link to="/users">` renders `<a href="/admin/users">`
+- `redirect("/login")` redirects to `"/admin/login"`
+- `router.use("/users/*", mw)` matches `/admin/users/*`
+- `useRouter().push("/users")` navigates to `/admin/users`
+- Route names stay unprefixed (`"home"`, not `"admin.home"`)
+
+Note: `href()` is a raw path helper and does **not** auto-prefix with basename.
+Use `reverse()` or `<Link>` for basename-aware URLs.
+
 ## Using the Request Handler
 
 The router provides a `fetch` method to handle RSC requests:

package/src/__internal.ts

@@ -225,7 +225,7 @@ export type {
  * @internal
  * Type guard for prerender handler definitions.
  */
-export { isPrerenderHandler } from "./prerender.js";
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
 
 /**
  * @internal

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

package/src/browser/navigation-bridge.ts

@@ -4,6 +4,7 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
@@ -67,8 +68,8 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments, version } =
-    config;
+  const { store, client, eventController, onUpdate, renderSegments } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -76,7 +77,7 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   return {
@@ -260,18 +261,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -447,6 +454,12 @@ export function createNavigationBridge(
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
+        // Restore router identity from cache so subsequent navigations
+        // don't falsely detect an app switch.
+        if (cached?.routerId) {
+          store.setRouterId?.(cached.routerId);
+        }
+
         // Render from cache - force await to skip loading fallbacks
         try {
           const root = await renderSegments(cachedSegments, {
@@ -632,6 +645,12 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }