@rangojs/router 0.0.0-experimental.110 → 0.0.0-experimental.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.110",
+  "version": "0.0.0-experimental.112",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,6 +132,16 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.26",
@@ -142,13 +152,14 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
@@ -167,13 +178,5 @@
     "vite": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
   }
-}
+}

package/skills/handler-use/SKILL.md

@@ -297,7 +297,7 @@ QuickViewModal.use = () => [
 
 ## `loading()` is a single-assignment item — scope it correctly
 
-Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loadingFn`](../../src/route-definition/dsl-helpers.ts)).
+Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loading`](../../src/route-definition/dsl-helpers.ts)).
 
 For pages, layouts, and intercepts that's straightforward: explicit `loading()` at the mount site replaces any `loading()` from `handler.use`. The merge order is `handler.use → explicit`, so the explicit one is the last writer and wins.
 

package/skills/rango/SKILL.md

@@ -142,6 +142,18 @@ by reference with `ctx.isAction(Action)` (rename-safe, where `CartActions` is an
 `import * as CartActions from "./actions/cart"`); see `/typesafety` → "Stable
 identity".
 
+The predicate arg carries the action's full context, not just its identity. Match
+_which_ action with `ctx.isAction(addToCart)` (rename-safe); branch on _what it
+returned_ with `ctx.actionResult` — the value your `"use server"` function
+returned, for outcome-conditional revalidation. The arg also exposes `actionId`
+(raw `path#export`), `actionUrl`, `formData`, `method`, and `stale` (cross-tab
+`_rsc_stale` signal). All are `undefined` on plain navigation (no action).
+
+```ts
+// re-render only when checkout actually succeeded; defer otherwise
+revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
+```
+
 **The source is the source of truth.** Structure, types, and update policy are
 visible and local in the tree — read top-down, no hidden global model to hold in
 your head. A snippet earns its place only if, from the code alone, you can answer:
@@ -150,6 +162,14 @@ without leaving the call site?_ (type-safety), _what re-renders after this
 action?_ (partial rendering). If any answer needs another file, it isn't legible
 yet.
 
+**Reading Rango's own source.** Rango is consumed as raw TypeScript — the
+`exports` map resolves `@rangojs/router` and its subpaths to `./src/*.ts` for
+both types and runtime, so a consuming app bundles Rango straight from source.
+Only the `./vite` plugin entry and the CLI `bin` load from `dist/`. To confirm
+any runtime or type detail against an installed copy, read the resolved source
+under `node_modules/@rangojs/router/src/`, not `dist/` — the runtime does not
+resolve `dist/` outside `./vite`, and it may lag `src/`.
+
 ## Skills
 
 Grouped by concern — read when you need to…

package/src/browser/action-coordinator.ts

@@ -1,9 +1,21 @@
-import {
-  classifyActionResponse,
-  type ActionScenario,
-} from "./action-response-classifier.js";
 import type { ActionEntry } from "./event-controller.js";
 
+/**
+ * Post-reconciliation action outcome (discriminated union). Error and
+ * full-update-unsupported cases are handled inline in the bridge before
+ * reconciliation; this only covers successfully-reconciled partial responses.
+ */
+export type ActionScenario =
+  | {
+      type: "navigated-away";
+      historyKeyChanged: boolean;
+      onInterceptRoute: boolean;
+    }
+  | { type: "hmr-missing" }
+  | { type: "consolidation-needed"; segmentIds: string[] }
+  | { type: "concurrent-skip"; otherFetchingCount: number }
+  | { type: "normal" };
+
 /**
  * Plain data inputs for classifying a post-reconciliation action outcome.
  * No browser objects or controller references — all values are snapshots.
@@ -33,20 +45,15 @@ export interface ActionOutcomeInput {
   currentInterceptSource: string | null;
 }
 
-/**
- * Compute consolidation segments from concurrent action state.
- *
- * Returns segment IDs that need re-fetching when concurrent actions
- * have each revalidated different parts of the tree, or null if
- * consolidation is not needed.
- */
+// Segment IDs to re-fetch when concurrent actions each revalidated different
+// parts of the tree; null when consolidation does not apply. Returns null while
+// any action is still fetching — consolidation must wait for all to land.
 function computeConsolidationSegments(
   input: ActionOutcomeInput,
 ): string[] | null {
   if (!input.hadAnyConcurrentActions) return null;
   if (input.revalidatedSegments.size === 0) return null;
 
-  // Can't consolidate while any action is still waiting for a server response
   const stillFetchingCount = [...input.inflightActions.values()].filter(
     (a) => a.phase === "fetching",
   ).length;
@@ -55,9 +62,6 @@ function computeConsolidationSegments(
   return Array.from(input.revalidatedSegments);
 }
 
-/**
- * Count other actions still in "fetching" phase (excluding this handle).
- */
 function countOtherFetchingActions(input: ActionOutcomeInput): number {
   let count = 0;
   for (const [, a] of input.inflightActions) {
@@ -69,29 +73,42 @@ function countOtherFetchingActions(input: ActionOutcomeInput): number {
 }
 
 /**
- * Classify a post-reconciliation action outcome into one of 5 scenarios.
- *
- * This is the single entry point for post-action decision logic.
- * It gathers consolidation and concurrency data from the plain inputs,
- * then delegates to the pure classifyActionResponse function.
- *
- * The server-action-bridge calls this after reconciliation to decide
- * whether to render, skip, consolidate, or refetch.
+ * Classify a post-reconciliation action outcome. Ordered priority chain: each
+ * case assumes the earlier ones are false (e.g. concurrent-skip only applies on
+ * the still-current route, consolidation only once no action is still fetching).
+ * The bridge calls this to decide whether to render, skip, consolidate, or refetch.
  */
 export function classifyActionOutcome(
   input: ActionOutcomeInput,
 ): ActionScenario {
-  return classifyActionResponse({
-    actionStartPathname: input.actionStartPathname,
-    currentPathname: input.currentPathname,
-    actionStartLocationKey: input.actionStartLocationKey,
-    currentLocationKey: input.currentLocationKey,
-    reconciledSegmentCount: input.reconciledSegmentCount,
-    matchedCount: input.matchedCount,
-    currentInterceptSource: input.currentInterceptSource,
-    consolidationSegments: computeConsolidationSegments(input),
-    otherFetchingActionCount: countOtherFetchingActions(input),
-  });
-}
+  if (
+    input.currentPathname !== input.actionStartPathname ||
+    input.currentLocationKey !== input.actionStartLocationKey
+  ) {
+    return {
+      type: "navigated-away",
+      historyKeyChanged:
+        input.currentLocationKey !== input.actionStartLocationKey,
+      onInterceptRoute: input.currentInterceptSource !== null,
+    };
+  }
+
+  if (input.reconciledSegmentCount < input.matchedCount) {
+    return { type: "hmr-missing" };
+  }
+
+  const consolidationSegments = computeConsolidationSegments(input);
+  if (consolidationSegments && consolidationSegments.length > 0) {
+    return { type: "consolidation-needed", segmentIds: consolidationSegments };
+  }
+
+  const otherFetchingActionCount = countOtherFetchingActions(input);
+  if (otherFetchingActionCount > 0) {
+    return {
+      type: "concurrent-skip",
+      otherFetchingCount: otherFetchingActionCount,
+    };
+  }
 
-export type { ActionScenario };
+  return { type: "normal" };
+}

package/src/browser/event-controller.ts

@@ -268,6 +268,20 @@ function matchesActionId(
   return entryActionId.endsWith(`#${subscriptionId}`);
 }
 
+// Coalesce rapid notifications into one microtask-deferred fan-out; the
+// setTimeout(0) batching prevents render storms. Each notifier owns its timer
+// so listener kinds coalesce independently.
+function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  return () => {
+    if (timeout !== null) clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      timeout = null;
+      listeners.forEach((listener) => listener());
+    }, 0);
+  };
+}
+
 // ============================================================================
 // Implementation
 // ============================================================================
@@ -334,18 +348,7 @@ export function createEventController(
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
 
-  // Debounce state notifications to batch rapid updates
-  let notifyTimeout: ReturnType<typeof setTimeout> | null = null;
-
-  function notify() {
-    if (notifyTimeout !== null) {
-      clearTimeout(notifyTimeout);
-    }
-    notifyTimeout = setTimeout(() => {
-      notifyTimeout = null;
-      stateListeners.forEach((listener) => listener());
-    }, 0);
-  }
+  const notify = makeDebouncedNotifier(stateListeners);
 
   // Debounce per-action notifications
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -371,18 +374,7 @@ export function createEventController(
     );
   }
 
-  // Debounce handle notifications
-  let handleNotifyTimeout: ReturnType<typeof setTimeout> | null = null;
-
-  function notifyHandles() {
-    if (handleNotifyTimeout !== null) {
-      clearTimeout(handleNotifyTimeout);
-    }
-    handleNotifyTimeout = setTimeout(() => {
-      handleNotifyTimeout = null;
-      handleListeners.forEach((listener) => listener());
-    }, 0);
-  }
+  const notifyHandles = makeDebouncedNotifier(handleListeners);
 
   // ========================================================================
   // Derived State
@@ -429,22 +421,17 @@ export function createEventController(
   }
 
   function getActionState(actionId: string): TrackedActionState {
-    // Find the most recent action with this ID that's not settling
-    // Uses suffix matching when actionId is just a name (no #)
-    const activeEntry = [...inflightActions.values()]
-      .filter(
-        (a) => matchesActionId(actionId, a.actionId) && a.phase !== "settling",
-      )
-      .sort((a, b) => b.startedAt - a.startedAt)[0];
-
-    // Also check for settling entries to get result/error
-    const settlingEntry = [...inflightActions.values()]
-      .filter(
-        (a) => matchesActionId(actionId, a.actionId) && a.phase === "settling",
-      )
-      .sort((a, b) => b.startedAt - a.startedAt)[0];
-
-    const entry = activeEntry || settlingEntry;
+    // Prefer the most-recent non-settling entry; fall back to most-recent
+    // settling so a just-settled action's result/error stays readable.
+    const entry = [...inflightActions.values()]
+      .filter((a) => matchesActionId(actionId, a.actionId))
+      .reduce<ActionEntry | undefined>((best, a) => {
+        if (!best) return a;
+        const aActive = a.phase !== "settling";
+        const bActive = best.phase !== "settling";
+        if (aActive !== bActive) return aActive ? a : best;
+        return a.startedAt > best.startedAt ? a : best;
+      }, undefined);
 
     if (!entry) {
       return { ...DEFAULT_ACTION_STATE };
@@ -632,6 +619,19 @@ export function createEventController(
       doSettle();
     }
 
+    // streamingEnded is forced here for the "streaming never started" case so
+    // tryFinalize can run; otherwise the streaming token's end() finalizes.
+    function settleWith(result: NonNullable<typeof pendingResult>) {
+      if (!inflightActions.has(id) || settled) return;
+      actionCompleted = true;
+      entry.completed = true;
+      pendingResult = result;
+      if (entry.phase === "fetching" || streamingEnded) {
+        streamingEnded = true;
+        tryFinalize();
+      }
+    }
+
     return {
       id,
       abort,
@@ -668,35 +668,11 @@ export function createEventController(
       },
 
       complete(result?: unknown) {
-        if (!inflightActions.has(id) || settled) return;
-
-        actionCompleted = true;
-        entry.completed = true;
-        pendingResult = { type: "success", value: result };
-
-        // If streaming never started or already ended, finalize immediately
-        // Otherwise wait for streaming to end
-        if (entry.phase === "fetching" || streamingEnded) {
-          streamingEnded = true; // Mark as ended if never started
-          tryFinalize();
-        }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+        settleWith({ type: "success", value: result });
       },
 
       fail(error: unknown) {
-        if (!inflightActions.has(id) || settled) return;
-
-        actionCompleted = true;
-        entry.completed = true;
-        pendingResult = { type: "error", value: error };
-
-        // If streaming never started or already ended, finalize immediately
-        // Otherwise wait for streaming to end
-        if (entry.phase === "fetching" || streamingEnded) {
-          streamingEnded = true; // Mark as ended if never started
-          tryFinalize();
-        }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+        settleWith({ type: "error", value: error });
       },
 
       getRevalidatedSegments(): Set<string> {

package/src/browser/navigation-bridge.ts

@@ -707,6 +707,10 @@ export function createNavigationBridge(
       };
     },
 
+    getVersion(): string | undefined {
+      return version;
+    },
+
     updateVersion(newVersion: string): void {
       version = newVersion;
       setAppVersion(newVersion);

package/src/browser/navigation-client.ts

@@ -15,6 +15,7 @@ import { getRangoState } from "./rango-state.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
 } from "./response-adapter.js";
 import {
@@ -148,21 +149,17 @@ export function createNavigationClient(
         source: string,
       ): Response | Promise<Response> => {
         // Version mismatch — server wants a full page reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          if (tx) {
-            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
-              reloadUrl: reload.url,
-            });
-          }
-          window.location.href = reload.url;
-          // Block further processing — page is reloading
-          return new Promise<Response>(() => {});
-        }
+        const reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) => {
+            if (tx) {
+              browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+                reloadUrl: url,
+              });
+            }
+          },
+        });
+        if (reloadResult) return reloadResult;
 
         // Server-side redirect without state: the server returned 204 with
         // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow

package/src/browser/navigation-store.ts

@@ -283,18 +283,17 @@ export function createNavigationStore(
   /**
    * Create a debounced function that batches rapid calls
    */
+  // A non-keyed notifier is the keyed one restricted to a single constant key;
+  // its own keyed instance means the "" key never collides with action keys.
   function createDebouncedNotifier<T extends (...args: any[]) => void>(
     fn: T,
     ms: number = 20,
   ): T {
-    let timeout: ReturnType<typeof setTimeout> | null = null;
-    return ((...args: Parameters<T>) => {
-      if (timeout !== null) clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        timeout = null;
-        fn(...args);
-      }, ms);
-    }) as T;
+    const keyed = createKeyedDebouncedNotifier(
+      (_key: string, ...args: any[]) => fn(...args),
+      ms,
+    );
+    return ((...args: Parameters<T>) => keyed("", ...args)) as T;
   }
 
   /**

package/src/browser/navigation-transaction.ts

@@ -236,30 +236,16 @@ export function createNavigationTransaction(
           segments: ResolvedSegment[],
           overrides?: BoundCommitOverrides,
         ) => {
-          // Allow overrides to disable scroll (e.g., for intercepts)
-          const finalScroll =
-            overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
-          // Allow overrides to force replace (e.g., for intercepts)
-          const finalReplace =
-            overrides?.replace !== undefined ? overrides.replace : opts.replace;
-          // Intercept info: overrides take precedence, fallback to opts
-          const intercept =
-            overrides?.intercept !== undefined
-              ? overrides.intercept
-              : opts.intercept;
+          const finalScroll = overrides?.scroll ?? opts.scroll;
+          const finalReplace = overrides?.replace ?? opts.replace;
+          const intercept = overrides?.intercept ?? opts.intercept;
           const interceptSourceUrl =
-            overrides?.interceptSourceUrl !== undefined
-              ? overrides.interceptSourceUrl
-              : opts.interceptSourceUrl;
-          // Cache-only mode: overrides take precedence, fallback to opts
-          const cacheOnly =
-            overrides?.cacheOnly !== undefined
-              ? overrides.cacheOnly
-              : opts.cacheOnly;
-          // User state: overrides take precedence, fallback to opts
+            overrides?.interceptSourceUrl ?? opts.interceptSourceUrl;
+          const cacheOnly = overrides?.cacheOnly ?? opts.cacheOnly;
+          // state is `unknown` (null is meaningful) so `??` would wrongly drop a
+          // null override; serverState always comes from overrides, never opts.
           const state =
             overrides?.state !== undefined ? overrides.state : opts.state;
-          // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
           return commit({
             ...opts,

package/src/browser/partial-update.ts

@@ -103,7 +103,7 @@ export type UpdateMode =
       /** Source URL for intercept restore (popstate cache miss) */
       interceptSourceUrl?: string;
     }
-  | { type: "leave-intercept" }
+  | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
   | { type: "action"; interceptSourceUrl?: string };
 
@@ -169,13 +169,7 @@ export function createPartialUpdater(
     // Capture history key at start for stale revalidation consistency check
     const historyKeyAtStart = store.getHistoryKey();
 
-    // Derive interceptSourceUrl from modes that carry it
-    const interceptSourceUrl =
-      mode.type === "stale-revalidation" ||
-      mode.type === "action" ||
-      mode.type === "navigate"
-        ? mode.interceptSourceUrl
-        : undefined;
+    const interceptSourceUrl = mode.interceptSourceUrl;
 
     // When leaving intercept, filter out intercept-specific segments
     let segments: string[];
@@ -218,13 +212,11 @@ export function createPartialUpdater(
     // When navigating with targetCacheSegments, use those for consistency.
     // Otherwise fall back to current page's segments (for same-route revalidation).
     const targetCache =
-      mode.type === "navigate" ? mode.targetCacheSegments : undefined;
-    const cachedSegs =
-      targetCache && targetCache.length > 0
-        ? targetCache
-        : getCurrentCachedSegments();
-    const cachedSegsSource =
-      targetCache && targetCache.length > 0 ? "history-cache" : "current-page";
+      mode.type === "navigate" && mode.targetCacheSegments?.length
+        ? mode.targetCacheSegments
+        : undefined;
+    const cachedSegs = targetCache ?? getCurrentCachedSegments();
+    const cachedSegsSource = targetCache ? "history-cache" : "current-page";
     debugLog(
       `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
     );
@@ -318,7 +310,7 @@ export function createPartialUpdater(
           .filter(Boolean) as ResolvedSegment[];
 
         // When navigating with cached segments to a different route, render them.
-        if (mode.type === "navigate" && targetCache && targetCache.length > 0) {
+        if (mode.type === "navigate" && targetCache) {
           debugLog(
             "[Browser] No diff but navigating with cached segments - rendering target route",
           );

package/src/browser/react/NavigationProvider.tsx

@@ -28,7 +28,7 @@ import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
-import type { AppShellRef } from "../app-shell.js";
+import { createAppShellRef, type AppShellRef } from "../app-shell.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -217,38 +217,33 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never
-  // change). When an appShellRef is supplied, `basename` and `version` are
-  // installed as live getters so app-switch transitions (which update the ref)
-  // propagate to consumers without forcing a tree-wide rerender.
+  // basename/version are always read through a shell ref so the context value
+  // has a single shape: a supplied appShellRef stays live (app-switch updates
+  // it), the standalone fallback is a frozen ref over the mount-time props.
+  const fallbackShellRef = useRef<AppShellRef | null>(null);
+  if (!fallbackShellRef.current) {
+    fallbackShellRef.current = createAppShellRef({ basename, version });
+  }
+  const shellRef = appShellRef ?? fallbackShellRef.current;
+
   const contextValue = useMemo<NavigationStoreContextValue>(() => {
-    if (appShellRef) {
-      const value = {
-        store,
-        eventController,
-        navigate,
-        refresh,
-      } as NavigationStoreContextValue;
-      Object.defineProperty(value, "basename", {
-        configurable: true,
-        enumerable: true,
-        get: () => appShellRef.get().basename,
-      });
-      Object.defineProperty(value, "version", {
-        configurable: true,
-        enumerable: true,
-        get: () => appShellRef.get().version,
-      });
-      return value;
-    }
-    return {
+    const value = {
       store,
       eventController,
       navigate,
       refresh,
-      version,
-      basename,
-    };
+    } as NavigationStoreContextValue;
+    Object.defineProperty(value, "basename", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().basename,
+    });
+    Object.defineProperty(value, "version", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().version,
+    });
+    return value;
   }, []);
 
   // Connection warmup: keep TLS alive after idle periods.
@@ -410,21 +405,15 @@ export function NavigationProvider({
         }).catch((err) =>
           console.error("[NavigationProvider] Error consuming handles:", err),
         );
-      } else if (update.metadata.cachedHandleData) {
-        // For back/forward navigation from cache, restore the cached handleData
-        // This restores breadcrumbs to the exact state they were when the page was cached
-        eventController.setHandleData(
-          update.metadata.cachedHandleData,
-          update.metadata.matched,
-          false, // full replace - restore entire cached state
-        );
       } else if (update.metadata.matched) {
-        // For cached navigations without handleData, update segmentOrder to clean up stale data
+        // cachedHandleData present -> full restore (back/forward); absent ->
+        // partial cleanup of segments no longer matched.
+        const cached = update.metadata.cachedHandleData;
         eventController.setHandleData(
-          {}, // Empty data - all existing data not in matched will be cleaned up
+          cached ?? {},
           update.metadata.matched,
-          true, // partial update - will clean up segments not in matched
-          update.metadata.resolvedIds,
+          cached === undefined,
+          cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
     });