@rangojs/router 0.18.0 → 0.19.0

package/skills/view-transitions/SKILL.md

@@ -227,8 +227,8 @@ interface TransitionConfig {
   default?: string | Record<string, string>; // fallback for any phase
   name?: string; // explicit view-transition-name
   viewTransition?: "auto" | false; // boundary opt-out (see below)
-  // Conditional server-side gate. PPR routes run it before route handlers and
-  // on every replay; other routes run it after handlers on fresh resolution.
+  // Browser predicate, once per navigation: false commits it urgently with no
+  // view transition. See "Conditional transitions".
   when?: (ctx: TransitionWhenContext) => boolean;
 }
 ```
@@ -240,47 +240,162 @@ interface TransitionConfig {
 
 ## Conditional transitions (`when`)
 
-`transition({ when })` gates the hold per request. The predicate runs server-side and outside any cache scope; return `false` to drop this segment's transition for the request. The hold is navigation-wide: the navigation streams its `loading()` fallback instead of holding only when no other matched segment still has a transition (the common case is a single `transition()` on the route).
+`transition({ when })` decides, per navigation, whether the navigation holds.
+It is a **browser** predicate: it runs once per navigation, at the first
+commit that presents the destination, and never on the server, on the
+document load, or on progressive-enhancement paths. Return `false` and the
+navigation commits urgently: the `loading()` skeleton streams and no view
+transition runs.
+
+Write it inline in `urls()`. The Vite plugin hoists the literal into a
+`"use client"` module, and the route carries it to the browser as a client
+reference. The hoist applies to the router's `transition`: the `urls()`
+helper (renamed or not) or `transition` imported from `@rangojs/router`,
+with the function written directly as the `when` value (an arrow, a
+`function`, or a `when() {}` method; `as` / `satisfies` wrappers are
+fine). A config built elsewhere, such as `transition(cfg)`, is not hoisted:
+export that predicate from a `"use client"` module instead.
 
-Timing follows the route's rendering contract:
+```ts
+// Hold unless the navigation leaves the "b" tab (the navigation SOURCE):
+transition({ when: ({ from }) => from.params.tab !== "b" });
+
+// Hold only for forward navigations inside /list:
+transition({
+  when: ({ kind, to }) => kind !== "pop" && to.url.pathname.startsWith("/list"),
+});
 
-- On an ordinary route it runs after the route handler during fresh resolution, so `get()` can read handler- and middleware-set context. Cache/prerender hits replay the stored decision.
-- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers, because a shell HIT never runs a handler.
+// Hold only after a specific action revalidated the route:
+transition({ when: ({ isAction }) => isAction(addToCart) });
+```
 
-Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
+For a predicate you share between routes or unit-test, export it from a
+`"use client"` module and import it into the urls file:
 
 ```ts
+// src/transitions.ts
+"use client";
 import type { TransitionWhenContext } from "@rangojs/router";
+import { Slide } from "./location-states.js";
 
-// Ordinary route: hold only when the handler marked this request:
-transition({ when: (ctx) => ctx.get(KeepScroll) === true });
+export function slideWhen({ to }: TransitionWhenContext): boolean {
+  return Slide.read(to)?.animate !== false;
+}
 
-// Hold only when arriving from a specific page (the navigation SOURCE):
-transition({
-  when: ({ currentUrl }) => currentUrl?.pathname.startsWith("/list") === true,
-});
-transition({ when: ({ fromRouteName }) => fromRouteName === "products.list" });
+// src/urls.tsx
+import { slideWhen } from "./transitions.js";
+path("/photos/:id", PhotoPage, { name: "photo" }, () => [
+  transition({ default: "slide", when: slideWhen }),
+]);
 
-// Hold only after a specific action revalidated the route:
-transition({
-  when: ({ actionId }) => actionId === "src/actions/cart.ts#addToCart",
-});
+// A Link that opts this navigation out through location state:
+<Link to="/photos/2" state={[Slide({ animate: false })]}>Next</Link>;
 ```
 
-| field                                                  | meaning                                      | populated                                                                             |
-| ------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `currentUrl` / `currentParams` / `fromRouteName`       | navigation **source**                        | soft nav + action-success; `undefined` on initial full load and action/PE error paths |
-| `nextUrl` / `nextParams`                               | navigation **target**                        | always                                                                                |
-| `toRouteName` (and `fromRouteName`)                    | route **name**                               | when the route is named (undefined for unnamed/auto-generated)                        |
-| `actionId` / `actionUrl` / `actionResult` / `formData` | the server action that triggered this render | action-triggered renders only                                                         |
-| `method`                                               | `"GET"` (nav) / `"POST"` (action)            | always                                                                                |
-| `get` / `env`                                          | read request vars + app env                  | always; PPR timing exposes middleware vars, not handler writes                        |
+Predicate modules (a `"use client"` export, or a hoisted inline literal) load
+with the client entry chunk, because the router must be able to call them at
+the first navigation. Keep them small: type imports and location-state
+definitions only, and nothing that touches `window` at module scope (the
+module is also evaluated during SSR).
+
+The rule is "a predicate runs where its effect lands": the hold is a browser
+commit decision, so the predicate runs in the browser. An inline literal may
+reference module-level imports only when they are client-safe (they are
+re-emitted into the hoisted module); a free server binding (a `const` in the
+urls file, a handler variable, a component used as JSX) or a server-only
+import is a build error that names it, and so are `import()`, `import.meta`
+other than `import.meta.env`, `this` / `arguments` of the enclosing
+function, and a `get when()` accessor. A server function passed by name, or a non-function, fails dev
+startup, the build and HMR re-discovery with the route name and pattern.
 
-A predicate that throws is reported to `router.onError` (phase `"rendering"`) and treated as no-hold (conservative).
+### Context
 
-**Same-route content-holds need the transition present on the FIRST render.** The same-route hold works by giving the route a param-agnostic key so a param change reconciles instead of remounting — but that key is established when the route first mounts. A source gate that returns `false` on the initial full load (where `currentUrl`/`currentParams`/`fromRouteName` are undefined) drops the transition before the route mounts, so the route mounts _outside_ a transition scope and **every** later same-route param nav remounts (flashing the skeleton) regardless of what the gate decides on those navs. Write source gates so they hold when there is no source — e.g. `({ currentParams }) => currentParams?.tab !== "raw"` (true on the initial load) rather than `=== "details"` (false on the initial load) — when the same-route content-hold must engage. This only affects same-route param navigations; action-only or cross-route gating is unaffected (no shared param key is in play).
+```ts
+interface RouteLocation {
+  url: URL;
+  params: Record<string, string>;
+  routeName: string | undefined;
+  state: unknown; // the entry's history.state; read slots with Def.read(location)
+}
 
-**Prefetch / cache caveat.** A **prefetched** navigation still decides at prefetch time — `currentUrl`/`currentParams`/`fromRouteName` reflect the page the prefetch fired from, not necessarily the click-time source. Non-PPR `cache()`/prerender hits also replay the stored transition without rerunning the predicate. PPR routes rerun it on the server for each cache/prerender/PPR match, but a completed browser prefetch still carries its earlier Flight decision. If the exact click-time source matters, source-scope the prefetch (`<Link prefetchKey=":source">`).
+interface TransitionWhenContext {
+  kind: "push" | "replace" | "pop" | "action" | "revalidate";
+  from: RouteLocation; // the committed location being left
+  to: RouteLocation; // the destination; === from for "action" and "revalidate"
+  isAction: IsActionFn; // the revalidate() matcher; false off-action
+  action?: { id; formData; result; error }; // kind "action" only
+}
+```
+
+| `kind`         | started by                                           | `to.state`                                                                                                                         |
+| -------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `"push"`       | `Link`, `router.push()`                              | the pushed state plus server `ctx.setLocationState()` (handler, middleware, action)                                                |
+| `"replace"`    | `Link replace`, `router.replace()`                   | same as push                                                                                                                       |
+| `"pop"`        | back/forward                                         | the target entry's stored state                                                                                                    |
+| `"action"`     | a server action's revalidation, error boundary incl. | the current entry's state plus action-set state (none on the error lane: an error response sets no location state); `action.*` set |
+| `"revalidate"` | `router.refresh()`, a stale entry's revalidation     | the current entry's state                                                                                                          |
+
+- `Def.read(location)` reads a location-state slot from `from` or `to`
+  without clearing flash state.
+- Middleware-set location state reaches `to.state` on a PPR replay HIT too
+  (middleware runs on every HIT); a route handler's does not, because a HIT
+  runs no handler. Set it from middleware when a `ppr` route decides on it.
+- A `clientUrls()` cross-route navigation decides at its optimistic swap,
+  before the server responds, so its `to.state` holds only the pushed
+  state.
+- On `"pop"`, `from.state` and `from.routeName` come from the router's
+  per-history-entry memory; after a reload they are `undefined`.
+- `get()`, `env` and handler state do not exist in the browser.
+
+### Combination and `false`
+
+- The navigation holds only when **every** committed segment's `when`
+  returns true, kept or re-sent: a layout the navigation keeps still gates
+  it ([#989](https://github.com/rangojs/rango/issues/989)). The same function
+  on several segments is called once.
+- `false` makes the whole navigation urgent, so no segment animates. Every
+  `<ViewTransition>` stays in the tree with its classes set to `"none"`, so a
+  same-route navigation that flips `true -> false -> true` never remounts
+  the route or loses its state
+  ([#995](https://github.com/rangojs/rango/issues/995)).
+- That holds for every kind, actions and revalidations included: a gated-off
+  action or revalidation commit is urgent too, so a segment it re-renders
+  streams its `loading()`. The router commits an action's result after the
+  response arrives, outside the transition React opens for a form action or
+  `useActionState` call, so React does not hold it either.
+- A predicate that throws counts as `false` and is logged with
+  `console.error` (the conservative default: no hold).
+- Intercept (modal) commits skip the evaluation, including a back/forward
+  that opens or closes a modal.
+- A stale revalidation the user navigated away from before it landed is
+  discarded without calling the predicate.
+- Intercept `from` differs: while a modal is open, an intercept selector's
+  `from` is the page under the modal (see the intercept skill); here it is
+  always the location on screen.
+- In a `clientUrls()` group, `false` also opts a same-route navigation out of
+  the group's default hold.
+
+`kind` lines up with the class keys in "Direction-aware transitions": a
+`"pop"` restored from the history cache animates with `"navigation-back"`
+(a pop that refetches uses `"navigation"`); `"push"`, `"replace"` and a
+`router.refresh()` (`"revalidate"`) use `"navigation"`; a stale entry's
+revalidation (`"revalidate"`) and an action's refetch (`"action"`) use
+`"action"`. An action's own commit (`useActionState`, a form action) carries
+no transition type (see the note under "Direction-aware transitions").
+
+### Opting out per navigation
+
+`router.push(url, { transition: false })`, `router.replace(url, {
+transition: false })` and `<Link transition={false}>` present one
+navigation the way `when` returning `false` does, without calling any
+predicate. Back/forward, actions and revalidation have no per-navigation
+options and are unaffected.
+
+```tsx
+<Link to="/photos/2" transition={false}>
+  Jump without the slide
+</Link>
+```
 
 ## Opting out of the router boundary (place your own `<ViewTransition>`)
 
@@ -361,6 +476,12 @@ await expect(page$).toBeVisible();
 Waiting for `toHaveCount(1)` first is not enough: the count passes through 1
 before the second host is inserted.
 
+Unit-test a `when` with `runTransitionWhen(when, { kind, from, to, action })`
+from `@rangojs/router/testing`, and a route's hold with `renderRoute`:
+`router.navigate()` decides with `kind: "push"`, `router.refresh()` with
+`kind: "revalidate"`. Pop, action and `clientUrls()` optimistic-swap
+decisions are e2e territory. See the testing skill, `predicates.md`.
+
 ## Recommendations
 
 **Put `<ParallelOutlet />` in layouts, not routes.** A route-level `transition` wraps the route component itself, so a `<ParallelOutlet />` rendered directly inside that route component remains inside the route VT subtree — modal opens on a route with a parallel outlet _will_ trigger the route's VT walker. The narrowing fix only applies at layout boundaries. If you combine intercept modals with route-level transitions, mount the slot one level up in a layout.

package/src/__augment-tests__/augmented.check.ts

@@ -10,10 +10,14 @@ import type {
   Handler,
   MiddlewareContext,
   ResponseHandlerContext,
+  RouteLocation,
   RouteParams,
   RouteSearchParams,
+  ServerRouteLocation,
+  TransitionWhenFn,
 } from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
+import type { InterceptWhenFn } from "../server/context.js";
 import { href } from "../href-client.js";
 import type { Money, TestBindings } from "./augment.js";
 
@@ -69,6 +73,23 @@ type _routeName = Expect<
   Equal<DefaultRouteName, "home" | "blog.post" | "search">
 >;
 
+// transition({ when }) / intercept({ when }) locations carry the public route
+// name (internal names never reach them), typed like every routeName.
+type _locationRouteName = Expect<
+  Equal<RouteLocation["routeName"], DefaultRouteName | undefined>
+>;
+type _serverLocationRouteName = Expect<
+  Equal<ServerRouteLocation["routeName"], DefaultRouteName | undefined>
+>;
+const transitionWhenTypo: TransitionWhenFn = ({ to }) =>
+  // @ts-expect-error - "blog.pots" is not a generated route name
+  to.routeName === "blog.pots";
+const interceptWhenTypo: InterceptWhenFn = ({ from }) =>
+  // @ts-expect-error - "hom" is not a generated route name
+  from.routeName === "hom";
+void transitionWhenTypo;
+void interceptWhenTypo;
+
 // RouteParams / RouteSearchParams resolve from the generated map with no
 // explicit route map argument.
 type _params = Expect<Equal<RouteParams<"blog.post">, { slug: string }>>;
@@ -131,6 +152,8 @@ type _flightOverride = Expect<Equal<Rango.FlightSerialize<Money>, number>>;
 // Reference the top-level assertion aliases so they are unambiguously evaluated.
 export type _Assertions = [
   _routeName,
+  _locationRouteName,
+  _serverLocationRouteName,
   _params,
   _search,
   _orderWireByPattern,

package/src/browser/event-controller.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type {
   NavigationLocation,
-  NavigateOptions,
+  NavigateOptionsInternal,
   TrackedActionState,
   ActionLifecycleState,
   InflightAction,
@@ -46,7 +46,7 @@ export interface NavigationEntry {
   abort: AbortController;
   phase: NavigationPhase;
   startedAt: number;
-  options?: NavigateOptions & { skipLoadingState?: boolean };
+  options?: NavigateOptionsInternal & { skipLoadingState?: boolean };
 }
 
 /**
@@ -206,7 +206,7 @@ export interface EventController {
   // Navigation operations
   startNavigation(
     url: string,
-    options?: NavigateOptions & { skipLoadingState?: boolean },
+    options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
   ): NavigationHandle;
   abortNavigation(): void;
 
@@ -632,7 +632,7 @@ export function createEventController(
 
   function startNavigation(
     url: string,
-    options?: NavigateOptions & { skipLoadingState?: boolean },
+    options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
   ): NavigationHandle {
     // Cancel existing navigation (switchMap semantics)
     if (currentNavigation) {

package/src/browser/history-state.ts

@@ -1,5 +1,8 @@
 import {
+  isLocationStateDefinition,
   isLocationStateEntry,
+  peekLocationStateKey,
+  replaceCurrentHistoryState,
   resolveLocationStateEntries,
 } from "./react/location-state-shared.js";
 
@@ -13,10 +16,49 @@ function isTypedLocationState(
   return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
 }
 
+/**
+ * Dev-only guard for the state mistakes `HistoryState` rejects at compile
+ * time, for untyped callers: a typed entry without its array (its `__rsc_ls_*`
+ * fields would be spread onto history.state, so useLocationState reads
+ * undefined), an uncalled definition (pushState throws DataCloneError), and an
+ * array mixing entries with plain values (only `state[0]` picks the format, so
+ * the rest land under history.state["undefined"] or are never read).
+ */
+function assertNavigationState(state: unknown): void {
+  if (isLocationStateEntry(state)) {
+    throw new Error(
+      `[rango] navigation state is a single location-state entry (key "${state.__rsc_ls_key}"). ` +
+        "Wrap it in an array: { state: [MyState(value)] }. " +
+        "Without the array, useLocationState(MyState) reads undefined.",
+    );
+  }
+  const definition = (Array.isArray(state) ? state : [state]).find(
+    isLocationStateDefinition,
+  );
+  if (definition) {
+    throw new Error(
+      `[rango] navigation state contains a location-state definition (key "${peekLocationStateKey(definition) ?? "unset"}") instead of an entry. ` +
+        "Call it with the value: { state: [MyState(value)] }, not [MyState].",
+    );
+  }
+  if (Array.isArray(state) && state.some(isLocationStateEntry)) {
+    const index = state.findIndex((item) => !isLocationStateEntry(item));
+    if (index !== -1) {
+      throw new Error(
+        `[rango] navigation state mixes location-state entries with other values (index ${index}). ` +
+          "Pass only entries ({ state: [MyState(value), Other(value)] }); plain state cannot sit next to typed entries.",
+      );
+    }
+  }
+}
+
 /**
  * Resolve navigation state - handles both LocationStateEntry[] and plain formats
  */
 export function resolveNavigationState(state: unknown): unknown {
+  if (process.env.NODE_ENV !== "production") {
+    assertNavigationState(state);
+  }
   if (
     Array.isArray(state) &&
     state.length > 0 &&
@@ -61,6 +103,15 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/** Check if a history state object contains location state keys. */
+export function hasLocationState(state: unknown): boolean {
+  if (!state || typeof state !== "object") return false;
+  return (
+    "state" in state ||
+    Object.keys(state).some((k) => k.startsWith("__rsc_ls_"))
+  );
+}
+
 /**
  * Stamp an `idx` on the next history entry's state and call push/replaceState.
  * Push increments the current idx; replace keeps it. Initial entry idx is 0.
@@ -117,7 +168,7 @@ export function mergeLocationState(
     ...window.history.state,
     ...locationState,
   };
-  window.history.replaceState(merged, "", window.location.href);
+  replaceCurrentHistoryState(merged);
   if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
     window.dispatchEvent(new Event("__rsc_locationstate"));
   }

package/src/browser/link-interceptor.ts

@@ -334,6 +334,7 @@ export function setupLinkInterception(
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
     const revalidateAttr = link.getAttribute("data-revalidate");
+    const transitionAttr = link.getAttribute("data-transition");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -345,6 +346,9 @@ export function setupLinkInterception(
     if (revalidateAttr === "false") {
       navigateOptions.revalidate = false;
     }
+    if (transitionAttr === "false") {
+      navigateOptions.transition = false;
+    }
 
     onNavigate(href, navigateOptions);
   };

package/src/browser/navigation-bridge.ts

@@ -14,7 +14,11 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  buildHistoryState,
+  hasLocationState,
+  pushHistoryWithIdx,
+} from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -30,7 +34,11 @@ import {
   setupDelegatedLinkPrefetch,
   setupLinkInterception,
 } from "./link-interceptor.js";
-import { createPartialUpdater } from "./partial-update.js";
+import {
+  createPartialUpdater,
+  shouldStartViewTransition,
+} from "./partial-update.js";
+import { decideCommitGatedOff, mergeSegmentParams } from "./transition-when.js";
 import { generateHistoryKey } from "./navigation-store.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
@@ -214,6 +222,7 @@ export function createNavigationBridge(
 
         // Snapshot old state before pushState/replaceState overwrites it
         const oldState = window.history.state;
+        const shallowRouteName = store.getHistoryEntryMemory()?.routeName;
 
         // Update browser URL (carry intercept context into history state)
         const historyState = buildHistoryState(
@@ -228,18 +237,11 @@ export function createNavigationBridge(
 
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();
+        // Same route, new entry (transition({ when }) back/forward source).
+        store.rememberDisplayedEntry(shallowRouteName);
 
         // Notify useLocationState() hooks when state changes
-        const hasOldState =
-          oldState &&
-          typeof oldState === "object" &&
-          ("state" in oldState ||
-            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
-        const hasNewState =
-          historyState &&
-          ("state" in historyState ||
-            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
-        if (hasOldState || hasNewState) {
+        if (hasLocationState(oldState) || hasLocationState(historyState)) {
           window.dispatchEvent(new Event("__rsc_locationstate"));
         }
 
@@ -344,9 +346,44 @@ export function createNavigationBridge(
         state: resolvedState,
         skipLoadingState: false,
       });
+      // A cross-route clientUrls() navigation presents its destination
+      // optimistically at once: transition({ when }) decides THERE (the first
+      // presentation), over the destination route's predicate and those of
+      // the segments the navigation keeps (everything outside the group's
+      // route segment), and the canonical commit reuses the decision.
+      // `transition: false` gates the navigation off without calling any
+      // predicate, on both the optimistic swap and the canonical commit.
+      const transitionOptOut = options?.transition === false;
       const clientUrlPresentation = beginClientUrlNavigation(
         targetUrl,
         tx.handle.signal,
+        transitionOptOut
+          ? () => true
+          : (destination) =>
+              decideCommitGatedOff(
+                store,
+                (
+                  store.getCachedSegments(store.getHistoryKey())?.segments ?? []
+                ).filter((segment) => segment.clientGroup === undefined),
+                options?.replace ? "replace" : "push",
+                {
+                  to: (from) => {
+                    // Mount (include prefix) params carry over; the origin
+                    // route's own params do not.
+                    const params = { ...from.params };
+                    for (const name of destination.originLocalParamNames) {
+                      delete params[name];
+                    }
+                    return {
+                      url: targetUrl,
+                      params: { ...params, ...destination.params },
+                      routeName: destination.routeName,
+                      state: buildHistoryState(resolvedState),
+                    };
+                  },
+                  extra: destination.when,
+                },
+              ),
       );
 
       // REVALIDATE: Fetch fresh data from server
@@ -365,6 +402,9 @@ export function createNavigationBridge(
             replace: options?.replace,
             scroll: options?.scroll,
             state: resolvedState,
+            transitionGatedOff: transitionOptOut
+              ? true
+              : clientUrlPresentation?.transitionGatedOff,
           }),
           isLeavingIntercept
             ? { type: "leave-intercept" as const }
@@ -394,6 +434,7 @@ export function createNavigationBridge(
           return this.navigate(redirectUrl, {
             state: error.state,
             replace: options?.replace,
+            transition: options?.transition,
             _skipCache: true,
           } as NavigateOptionsInternal);
         }
@@ -457,6 +498,7 @@ export function createNavigationBridge(
           false,
           tx.handle.signal,
           tx.with({ url: window.location.href, replace: true, scroll: false }),
+          { type: "navigate", refresh: true },
         );
       } catch (error) {
         // Aborted or superseded: bail without rendering a boundary (see navigate()).
@@ -567,6 +609,26 @@ export function createNavigationBridge(
       const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (cachedSegments && cachedSegments.length > 0) {
+        // transition({ when }) decides the restore (kind "pop") against the
+        // entry being left, so before the store moves to the restored entry.
+        // The decision the entry was committed with is not reused: it was
+        // made for a different source. A restore that opens or closes an
+        // intercept never holds or animates (hasTransition below), so it is
+        // not decided, like every intercept commit.
+        const cachedParams = mergeSegmentParams(cachedSegments);
+        const gatedOff =
+          !isIntercept &&
+          !isLeavingIntercept &&
+          decideCommitGatedOff(store, cachedSegments, "pop", {
+            to: () => ({
+              url,
+              params: cachedParams,
+              routeName: store.getHistoryEntryMemory(historyState?.key)
+                ?.routeName,
+              state: historyState,
+            }),
+          });
+
         // Update store to point to this history entry
         store.setHistoryKey(historyKey);
         store.setSegmentIds(cachedSegments.map((s) => s.id));
@@ -583,14 +645,11 @@ export function createNavigationBridge(
         try {
           const root = await renderSegments(cachedSegments, {
             forceAwait: true,
+            transitionGatedOff: gatedOff,
           });
-          // Merge params from cached segments for useParams restoration.
+          store.rememberDisplayedEntry();
           // Set params on event controller before onUpdate so both location
           // and params are current when the debounced notify() fires.
-          const cachedParams: Record<string, string> = {};
-          for (const s of cachedSegments) {
-            if (s.params) Object.assign(cachedParams, s.params);
-          }
           eventController.setParams(cachedParams);
 
           const popstateUpdate = {
@@ -613,7 +672,7 @@ export function createNavigationBridge(
           const hasTransition =
             !isIntercept &&
             !isLeavingIntercept &&
-            cachedSegments.some((s) => s.transition);
+            shouldStartViewTransition(cachedSegments, gatedOff);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {

package/src/browser/navigation-client.ts

@@ -122,9 +122,10 @@ export function createNavigationClient(
 
       // Check completed in-memory prefetch cache before making a network
       // request. Try the source-scoped key first (populated when the server
-      // tagged the prefetch response as source-sensitive, e.g. intercepts,
-      // or when a Link opted in with `prefetchKey=":source"`), then fall
-      // back to the wildcard slot shared across source pages.
+      // tagged the prefetch response as source-sensitive, e.g. a route an
+      // intercept targets, or when a Link opted in with
+      // `prefetchKey=":source"`), then fall back to the wildcard slot shared
+      // across source pages.
       // Both keys embed the Rango state, so state rotation (deploy or
       // server-action invalidation) auto-invalidates both scopes.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs