@rangojs/router 0.24.4 → 0.25.0

package/skills/view-transitions/SKILL.md

@@ -101,7 +101,7 @@ Navigating between `/`, `/about`, and `/contact` cross-fades the `<Outlet />` co
 
 ## Direction-aware transitions
 
-`ViewTransitionClass` accepts an object form keyed by transition type. Rango tags forward navigations as `"navigation"` and back/forward navigations restored from the client cache as `"navigation-back"` (a back/forward that has to refetch from the server is tagged `"navigation"`):
+`ViewTransitionClass` accepts an object form keyed by transition type. Every commit the router runs in a transition carries its kind (`"push"`, `"replace"`, `"pop"`, `"action"`, `"revalidate"`, see [Transition kinds](#transition-kinds)). Under `transition()`, Rango also tags forward navigations as `"navigation"` and back/forward navigations restored from the client cache as `"navigation-back"` (a back/forward that has to refetch from the server is tagged `"navigation"`). The restore runs a view transition: it commits on the next task after the `popstate` event, with its saved scroll applied before the new snapshot is taken (see [Back and Forward](#back-and-forward)):
 
 ```tsx
 layout(<ShopShell />, () => [
@@ -132,7 +132,40 @@ layout(<ShopShell />, () => [
 /* @keyframes slide-out-to-left, slide-in-from-right, ... defined as usual */
 ```
 
-> Note: `"action"` is only tagged on partial-update action/refetch paths today; ordinary `server-action-bridge` commits (`useAction` / `useActionState` revalidations) are not currently tagged. Don't rely on an `action`-keyed class to fire on every form action.
+### Transition kinds
+
+Every commit the router runs in a transition adds its `transition({ when })` kind as a transition type, first, before the types above. A map keyed by kind tells a link navigation from a server action's revalidation, with or without `transition()` on the route:
+
+| Kind           | Commits                                                                                                                                                                                    |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `"push"`       | A link, `router.push()`, `navigate()`: the same-route content hold (search or catch-all change), a fully prefetched click, an intercept, the commit after a `clientUrls()` optimistic swap |
+| `"replace"`    | `router.replace()`, `<Link replace>`                                                                                                                                                       |
+| `"pop"`        | A back/forward: one that refetches, and under `transition()` one restored from the history cache                                                                                           |
+| `"action"`     | A server action's revalidation and its error-boundary commit                                                                                                                               |
+| `"revalidate"` | `router.refresh()`, a stale entry's background revalidation                                                                                                                                |
+
+```tsx
+// Animate navigations; keep action revalidations and background refreshes still.
+<ViewTransition update={{ push: "page", replace: "page", default: "none" }}>
+  <ProductGrid />
+</ViewTransition>
+```
+
+- Tagging alone animates nothing: React starts a view transition only where a `<ViewTransition>` resolves a class other than `"none"` for the commit's types.
+- A commit outside a transition carries no type: a cold click that mounts new segments, a gated-off commit (`when` returned `false`), and a back/forward restored from the history cache on a route without `transition()` (it commits inside the `popstate` event). Under `transition()` that restore carries `"pop"` and `"navigation-back"`.
+- Under `transition()`, a stale entry's revalidation carries `"revalidate"` and `"action"`. An `action`-keyed map that must skip it also keys `revalidate: "none"` (`"none"` wins over any other match).
+- The types reach the commit that brings the page. React keeps one queue of transition types per root, and the first transition commit takes the whole queue. No router hook update takes them first: `useHandle()` and `useSegments()` commit with the page, and a `useNavigation()` value that moves while neither the state nor the URL does (`pendingUrl` as the response starts streaming, `isStreaming` as it ends) commits with the page while the reader has a held value, urgently otherwise, so it starts no view transition of its own. A transition your own code starts while React holds a navigation's page can still take them. Handle values on a held page land in the commit right after the page, by design; see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design). Use a kind map to choose an animation, never for correctness.
+
+### Back and Forward
+
+A back/forward the router restores from its history cache animates like a link under `transition()`:
+
+- It commits on the next task after the `popstate` event, in a view transition whose types are `"pop"` and `"navigation-back"`. React commits a transition started inside the event synchronously, with no view transition, so the router waits that one task; the page being left stays on screen until then, and the location hooks change with the restored page.
+- The saved scroll position is applied in the commit's layout effect, before the view transition takes its new snapshot, so the restored page animates in at the position it was left.
+- A traversal the browser animated itself (`PopStateEvent.hasUAVisualTransition`: the iOS Safari and Chrome Android back swipe) commits at once and is not animated again.
+- A second Back or Forward before the first one's restore commits wins; the first restore is dropped.
+- Without `transition()` the restore commits inside the event, with no view transition and no type.
+- So does an entry whose scroll the browser restores itself (`history.scrollRestoration` is `"auto"`: the document renders no `<Html.ScrollRestoration>`, which Rango's default document does, or the entry predates it). The browser restores that scroll right after the event, on whatever page is then on screen.
 
 ## Wrapper form: applying transition to a group of routes
 
@@ -234,7 +267,7 @@ interface TransitionConfig {
 ```
 
 - `default` is the catch-all if a phase-specific prop is unset.
-- The object form keys are React transition types tagged by rango: `"navigation"` (forward navigations), `"navigation-back"` (popstate cache restores), and `"action"` (partial-update action/refetch paths only — see the caveat in "Direction-aware transitions").
+- The object form keys are React transition types tagged by rango: the commit's kind (`"push"`, `"replace"`, `"pop"`, `"action"`, `"revalidate"`, see [Transition kinds](#transition-kinds)) and, under `transition()`, `"navigation"` (forward navigations), `"navigation-back"` (popstate cache restores) and `"action"` (action and stale revalidations).
 - `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
 - `viewTransition` toggles whether rango places its own `<ViewTransition>` boundary. `"auto"` (default) wraps as described above; `false` opts out — see the next section.
 
@@ -380,13 +413,13 @@ interface TransitionWhenContext {
 - 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").
+`kind` is also the transition type the commit carries (see "Transition
+kinds"): `{ push: "page", default: "none" }` animates the commits `when` sees
+as `"push"`. Under `transition()` the older keys stay: a `"pop"` restored from
+the history cache adds `"navigation-back"` (a pop that refetches adds
+`"navigation"`); `"push"`, `"replace"` and a `router.refresh()`
+(`"revalidate"`) add `"navigation"`; a stale entry's revalidation adds
+`"action"`.
 
 ### Opting out per navigation
 

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

@@ -8,6 +8,7 @@
 import "./augment.js";
 import type {
   Handler,
+  LoaderContext,
   MiddlewareContext,
   ResponseHandlerContext,
   RouteLocation,
@@ -17,6 +18,7 @@ import type {
   TransitionWhenFn,
 } from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
+import type { RequestContext } from "../server/request-context.js";
 import type { InterceptWhenFn } from "../server/context.js";
 import { href } from "../href-client.js";
 import { rewrite, type Rewrite } from "../route-definition/rewrite.js";
@@ -62,6 +64,32 @@ function responseReverse(ctx: ResponseHandlerContext): void {
 }
 void responseReverse;
 
+// Loader ctx.reverse and getRequestContext().reverse take the same optional
+// params as handlers: after the route match the runtime fills them from the
+// matched route's params.
+function loaderReverse(ctx: LoaderContext): void {
+  ctx.reverse("home");
+  ctx.reverse("blog.post");
+  ctx.reverse("blog.post", { slug: "hello" });
+  ctx.reverse("search", {}, { q: "hats" });
+  // @ts-expect-error - unknown param name is rejected
+  ctx.reverse("blog.post", { slugg: "hello" });
+  // @ts-expect-error - unknown global name is rejected
+  ctx.reverse("nope");
+}
+void loaderReverse;
+
+function requestContextReverse(ctx: RequestContext): void {
+  ctx.reverse("home");
+  ctx.reverse("blog.post");
+  ctx.reverse("blog.post", { slug: "hello" });
+  // @ts-expect-error - unknown param name is rejected
+  ctx.reverse("blog.post", { slugg: "hello" });
+  // @ts-expect-error - unknown global name is rejected
+  ctx.reverse("nope");
+}
+void requestContextReverse;
+
 function middlewareReverse(ctx: MiddlewareContext): void {
   ctx.reverse("blog.post", { slug: "hello" });
   // @ts-expect-error - dot-local name; no include() scope to resolve it

package/src/browser/event-controller.ts

@@ -72,6 +72,8 @@ export interface ActionEntry {
   result?: unknown;
   /** Error from action (set on failure) */
   error?: unknown;
+  /** A loader that failed while it re-ran after the action (set on success) */
+  revalidationError?: unknown;
   /** Segment IDs that were revalidated by this action */
   revalidatedSegments: string[];
   /** Timestamp when action started */
@@ -117,9 +119,15 @@ export type StateListener = () => void;
 export type ActionStateListener = (state: TrackedActionState) => void;
 
 /**
- * Handle state listener
+ * Handle state listener. `signal`, from a payload update: "anchor" when it
+ * hands React a page in a transition (route state on screen until it
+ * commits), "release" when it hands one urgently; "release" again once the
+ * page committed (useCommitAnchoredState, react/use-handle.ts).
  */
-export type HandleListener = () => void;
+export type HandleListener = (signal?: RouteStateSignal) => void;
+
+/** See HandleListener. */
+export type RouteStateSignal = "anchor" | "release";
 
 /**
  * Internal handle state stored in controller.
@@ -200,8 +208,8 @@ export interface ActionHandle extends Disposable {
    * later-initiated winner's response lands and overwrites it.
    */
   claimLocationState(state: Record<string, unknown>): Record<string, unknown>;
-  /** Complete the action with result */
-  complete(result?: unknown): void;
+  /** Complete the action with result, and a loader rerun's error, if any */
+  complete(result?: unknown, revalidationError?: unknown): void;
   /** Fail the action with error */
   fail(error: unknown): void;
   /** Whether action was completed (success or failure) */
@@ -260,8 +268,18 @@ export interface EventController {
    * Deliver queued location, params, navigation, and handle notifications now.
    * NavigationProvider calls this inside the payload update so React assigns
    * every route-state hook update to the same normal or transition lane.
+   * `signal`: handle readers learn how the page is handed over. After
+   * "anchor" (a page in a transition) values that arrive before
+   * releaseRouteState() wait for it (useCommitAnchoredState,
+   * react/use-handle.ts).
+   */
+  flushRouteState(signal?: RouteStateSignal): void;
+  /**
+   * The page the last flushRouteState("anchor") announced has committed:
+   * NavigationProvider calls this from its layout effect, and handle readers
+   * apply what waited, in that task.
    */
-  flushRouteState(): void;
+  releaseRouteState(): void;
 
   // Handle operations
   setHandleData(
@@ -403,12 +421,14 @@ export function subscribeToLocationChange(
   };
 }
 
-const DEFAULT_ACTION_STATE: TrackedActionState = {
+/** An action with no tracked entry: idle, nothing reported. */
+export const DEFAULT_ACTION_STATE: TrackedActionState = {
   state: "idle",
   actionId: null,
   payload: null,
   error: null,
   result: null,
+  revalidationError: null,
 };
 
 // Shared empty inflight-actions list. getState() hands back this exact reference
@@ -437,20 +457,23 @@ function matchesActionId(
 
 interface DebouncedNotifier {
   schedule(): void;
-  flush(): void;
+  flush(signal?: RouteStateSignal): void;
 }
 
 // Batch rapid notifications into one task to prevent render storms. The
-// explicit flush lets a React update owner preserve its scheduling lane.
-function makeDebouncedNotifier(listeners: Set<() => void>): DebouncedNotifier {
+// explicit flush lets a React update owner preserve its scheduling lane; a
+// signal is delivered even with nothing queued.
+function makeDebouncedNotifier(
+  listeners: Set<(signal?: RouteStateSignal) => void>,
+): DebouncedNotifier {
   let timeout: ReturnType<typeof setTimeout> | null = null;
-  const flush = () => {
-    if (timeout === null) return;
-    clearTimeout(timeout);
+  const flush = (signal?: RouteStateSignal) => {
+    if (timeout === null && !signal) return;
+    clearTimeout(timeout ?? undefined);
     timeout = null;
     notifyListeners(
       [...listeners],
-      (listener) => listener(),
+      (listener) => listener(signal),
       (listener) => listeners.has(listener),
     );
   };
@@ -613,9 +636,9 @@ export function createEventController(
 
   const notifyHandles = makeDebouncedNotifier(handleListeners);
 
-  function flushRouteState(): void {
+  function flushRouteState(signal?: RouteStateSignal): void {
     notifyStateListeners.flush();
-    notifyHandles.flush();
+    notifyHandles.flush(signal);
   }
 
   function getState(): DerivedNavigationState {
@@ -700,6 +723,7 @@ export function createEventController(
       payload: entry.payload,
       error: entry.error ?? null,
       result: entry.result ?? null,
+      revalidationError: entry.revalidationError ?? null,
     };
   }
 
@@ -871,7 +895,7 @@ export function createEventController(
     let actionCompleted = false;
     let cohortReleased = false;
     let pendingResult:
-      | { type: "success"; value?: unknown }
+      | { type: "success"; value?: unknown; revalidationError?: unknown }
       | { type: "error"; value: unknown }
       | null = null;
 
@@ -922,6 +946,7 @@ export function createEventController(
         entry.error = pendingResult.value;
       } else if (pendingResult?.type === "success") {
         entry.result = pendingResult.value;
+        entry.revalidationError = pendingResult.revalidationError;
       }
       entry.phase = "settling";
       notify();
@@ -997,8 +1022,8 @@ export function createEventController(
         return winning;
       },
 
-      complete(result?: unknown) {
-        settleWith({ type: "success", value: result });
+      complete(result?: unknown, revalidationError?: unknown) {
+        settleWith({ type: "success", value: result, revalidationError });
       },
 
       fail(error: unknown) {
@@ -1258,6 +1283,7 @@ export function createEventController(
     subscribeToAction,
     subscribeToHandles,
     flushRouteState,
+    releaseRouteState: () => notifyHandles.flush("release"),
 
     // Direct access
     getCurrentNavigation: () => currentNavigation,

package/src/browser/intercept-utils.ts

@@ -4,10 +4,11 @@ import type { SlotState } from "../types.js";
 /**
  * Check if a segment is an intercept segment.
  * Intercept segments have namespace starting with "intercept:" — both the
- * parallel container (@modal) and its content children receive this namespace
+ * parallel container (@modal) and its loader segments receive this namespace
  * from intercept-resolution.ts. Regular parallel segments like @sidebar do not.
+ * Server-safe: the cache and match pipeline share it.
  */
-export function isInterceptSegment(s: ResolvedSegment): boolean {
+export function isInterceptSegment(s: { namespace?: string }): boolean {
   return s.namespace?.startsWith("intercept:") === true;
 }
 

package/src/browser/merge-segment-loaders.ts

@@ -1,90 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
 import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
-import { settledValue } from "../thenable-status.js";
-
-/**
- * Merge partial loader data from server with cached loader data.
- *
- * During partial revalidation (stale or action), the server may return only
- * some loaders that pass the revalidation check, none when every one is held.
- * The component still needs all loader data, so we merge fresh data with
- * cached data. Two settled aggregates merge into the array itself: a fresh
- * Promise.all over settled parts is a promise React has not read, and content
- * on screen handed one suspends (docs/internal/suspense-contract.md, rule 2).
- *
- * @param fromServer - Segment returned from server with partial loaders
- * @param fromCache - Cached segment with full loader data
- * @returns Merged segment with complete loader data
- */
-export function mergeSegmentLoaders(
-  fromServer: ResolvedSegment,
-  fromCache: ResolvedSegment,
-): ResolvedSegment {
-  const serverLoaderIds = fromServer.loaderIds || [];
-  const cachedLoaderIds = fromCache.loaderIds || [];
-
-  if (IS_BROWSER_DEBUG) {
-    debugLog(
-      `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
-    );
-  }
-
-  // Fresh data for the loaders the server re-ran, cached data for the rest.
-  const merge = (newData: any[], cachedData: any[]): any[] =>
-    cachedLoaderIds.map((id: string, i: number) => {
-      const newIndex = serverLoaderIds.indexOf(id);
-      return newIndex !== -1 ? newData[newIndex] : cachedData[i];
-    });
-  const settledNew = settledValue(fromServer.loaderDataPromise!);
-  const settledCached = settledValue(fromCache.loaderDataPromise!);
-
-  return {
-    ...fromCache,
-    // The server re-ran the slot's handler and layout: their render applies,
-    // as it does when every loader re-runs. Only the loaders it held keep
-    // their cached data.
-    component: fromServer.component,
-    layout: fromServer.layout,
-    // Every loader held: the cached aggregate itself, so a boundary still
-    // waiting on it keeps its one thenable (suspense-contract.md, rule 1).
-    loaderDataPromise:
-      serverLoaderIds.length === 0
-        ? fromCache.loaderDataPromise
-        : settledNew && settledCached
-          ? merge(settledNew, settledCached)
-          : Promise.all([
-              fromServer.loaderDataPromise!,
-              fromCache.loaderDataPromise!,
-            ]).then(([newData, cachedData]) => merge(newData, cachedData)),
-    // Keep all loader IDs from cache
-    loaderIds: fromCache.loaderIds,
-    // The rebuilt aggregate is the source of truth. Cached per-loader
-    // streams would make LoaderResolver ignore loaderDataPromise.
-    loaderStreams: undefined,
-    awaitedLoaderIds: undefined,
-  };
-}
-
-/**
- * Check if segments need loader merging during partial revalidation.
- *
- * Returns true when:
- * - Server returned fewer loaders than cached (partial revalidation)
- * - Both segments have loader data promises
- */
-export function needsLoaderMerge(
-  fromServer: ResolvedSegment,
-  fromCache: ResolvedSegment | undefined,
-): fromCache is ResolvedSegment {
-  return !!(
-    fromCache &&
-    fromServer.loaderIds &&
-    fromCache.loaderIds &&
-    fromServer.loaderIds.length < fromCache.loaderIds.length &&
-    fromServer.loaderDataPromise &&
-    fromCache.loaderDataPromise
-  );
-}
 
 /**
  * Insert diff segments that aren't in the matched array into allSegments.