@rangojs/router 0.15.1 → 0.17.0

package/skills/view-transitions/SKILL.md

@@ -8,7 +8,7 @@ argument-hint: [layout|route|parallel|intercept]
 
 `transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
-1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions.
+1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions. While the hold lasts, `useLoader` readers of the loaders being re-run report `isLoading: true` — keyed by loader family (`$$id`), not by segment; see the hooks skill, `data.md`.
 2. **`<ViewTransition>` (the animation, layered on top).** On React 19.3+ (or an experimental build), rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs 19.3+; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
 > The `<ViewTransition>` layer requires a React that exports `<ViewTransition>` / `addTransitionType`: stable 19.3+ or an experimental build. Rango feature-detects it; on React 19.2 that layer is a no-op — but the `startTransition` driving (content hold) still applies.
@@ -52,7 +52,7 @@ A simple cross-fade between pages that share a layout:
 import { urls } from "@rangojs/router";
 import { Outlet } from "@rangojs/router/client";
 
-function ShopShell({ children }: { children: React.ReactNode }) {
+function ShopShell() {
   return (
     <div className="shop">
       <NavBar />
@@ -74,23 +74,34 @@ export const urlpatterns = urls(({ layout, path, transition }) => [
 ]);
 ```
 
+The config values are React `<ViewTransition>` classes: React applies them as
+`view-transition-class`, so the CSS targets the view-transition
+pseudo-elements by class:
+
 ```css
-::view-transition-old(root) {
-  animation: fade-out 200ms ease both;
+::view-transition-old(.page-fade) {
+  animation: 200ms ease both fade-out;
+}
+::view-transition-new(.page-fade) {
+  animation: 200ms ease both fade-in;
 }
-::view-transition-new(root) {
-  animation: fade-in 200ms ease both;
+@keyframes fade-out {
+  to {
+    opacity: 0;
+  }
 }
-.page-fade {
-  /* class hooks per phase */
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
 }
 ```
 
-Navigating between `/`, `/about`, and `/contact` morphs the `<Outlet />` content with the `page-fade` class. The shell (NavBar, Footer) does not morph because the wrap sits inside the shell, not around it.
+Navigating between `/`, `/about`, and `/contact` cross-fades the `<Outlet />` content with the `page-fade` class. The shell (NavBar, Footer) does not animate because the wrap sits inside the shell, not around it.
 
 ## Direction-aware transitions
 
-`ViewTransitionClass` accepts an object form keyed by transition type. Rango tags forward navigations as `"navigation"` and back/forward popstate as `"navigation-back"`:
+`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"`):
 
 ```tsx
 layout(<ShopShell />, () => [
@@ -106,12 +117,19 @@ layout(<ShopShell />, () => [
 ```
 
 ```css
-.slide-left {
-  animation-name: slide-from-right;
+::view-transition-old(.slide-left) {
+  animation: 250ms ease both slide-out-to-left;
+}
+::view-transition-new(.slide-left) {
+  animation: 250ms ease both slide-in-from-right;
 }
-.slide-right {
-  animation-name: slide-from-left;
+::view-transition-old(.slide-right) {
+  animation: 250ms ease both slide-out-to-right;
 }
+::view-transition-new(.slide-right) {
+  animation: 250ms ease both slide-in-from-left;
+}
+/* @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.
@@ -147,8 +165,8 @@ function GalleryShell() {
       <main>
         <Outlet /> {/* page transition lands here */}
       </main>
-      <ParallelOutlet name="@modal" />{" "}
-      {/* modal mounts here — sibling of the VT */}
+      {/* modal mounts here, as a sibling of the VT */}
+      <ParallelOutlet name="@modal" />
     </>
   );
 }
@@ -222,7 +240,7 @@ 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 navigation streams its `loading()` fallback instead of holding).
+`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).
 
 Timing follows the route's rendering contract:
 
@@ -280,7 +298,10 @@ urls(({ path, transition }) => [
   ]),
 ]);
 
-// ProductPage renders the boundary itself, exactly where it's wanted:
+// ProductPage renders the boundary itself, exactly where it's wanted
+// (ViewTransition is exported by React 19.3+ and experimental builds):
+import { ViewTransition } from "react";
+
 function ProductPage() {
   return (
     <ViewTransition name="hero">
@@ -311,7 +332,7 @@ const router = createRouter<AppEnv>({ viewTransition: false });
 | `transition({ viewTransition: false })`  | `"auto"`                | no wrap (per-route wins) | **ST only** |
 | `transition({ viewTransition: false })`  | `false`                 | no wrap                  | ST only     |
 
-On stable React the "VT" column is always a no-op (there is no `<ViewTransition>`), so every row collapses to its `startTransition`-only behavior there.
+On React 19.2 (no `<ViewTransition>` export) the "VT" column is a no-op, so every row collapses to its `startTransition`-only behavior there.
 
 | Config                                               | Router boundary  | startTransition driving (no skeleton flash) | Your own `<ViewTransition name>`   |
 | ---------------------------------------------------- | ---------------- | ------------------------------------------- | ---------------------------------- |
@@ -320,7 +341,7 @@ On stable React the "VT" column is always a no-op (there is no `<ViewTransition>
 | `transition({ viewTransition: false })`              | none             | yes                                         | fires alone                        |
 | global `viewTransition: false`, route `transition()` | none             | yes                                         | fires alone                        |
 
-> On **stable** React there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
+> On React 19.2 there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
 ## Testing a transition() route
 

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

@@ -6,7 +6,13 @@
  * turns these into tsc errors. Run via tsconfig.augment-check.json.
  */
 import "./augment.js";
-import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
+import type {
+  Handler,
+  MiddlewareContext,
+  ResponseHandlerContext,
+  RouteParams,
+  RouteSearchParams,
+} from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import { href } from "../href-client.js";
 import type { Money, TestBindings } from "./augment.js";
@@ -39,6 +45,25 @@ const varsHandler: Handler<"home"> = (ctx) => {
 };
 void varsHandler;
 
+// Response-route and middleware ctx.reverse resolve global names only (no
+// include() scope): generated names and params are validated, `.name` is not.
+function responseReverse(ctx: ResponseHandlerContext): void {
+  ctx.reverse("home");
+  ctx.reverse("blog.post", { slug: "hello" });
+  // @ts-expect-error - dot-local name; no include() scope to resolve it
+  ctx.reverse(".home");
+  // @ts-expect-error - unknown global name is rejected
+  ctx.reverse("nope");
+}
+void responseReverse;
+
+function middlewareReverse(ctx: MiddlewareContext): void {
+  ctx.reverse("blog.post", { slug: "hello" });
+  // @ts-expect-error - dot-local name; no include() scope to resolve it
+  ctx.reverse(".home");
+}
+void middlewareReverse;
+
 // routeName narrows to the generated route names.
 type _routeName = Expect<
   Equal<DefaultRouteName, "home" | "blog.post" | "search">

package/src/browser/index.ts

@@ -3,10 +3,10 @@
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, Rango } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "@rangojs/router/browser";
 //
 // For React components (Link, useNavigation, etc.):
-//   import { Link, useNavigation, useAction, href } from "rsc-router/client";
+//   import { Link, useNavigation, useAction, href } from "@rangojs/router/client";
 //
 // ============================================================================
 

package/src/browser/navigation-bridge.ts

@@ -18,6 +18,7 @@ import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
+  handleTraversalStart,
   ensureHistoryKey,
 } from "./scroll-restoration.js";
 
@@ -496,6 +497,7 @@ export function createNavigationBridge(
     async handlePopstate(): Promise<void> {
       // Abort any pending navigation to prevent race conditions
       eventController.abortNavigation();
+      handleTraversalStart();
 
       const url = window.location.href;
 
@@ -698,7 +700,7 @@ export function createNavigationBridge(
           tx.handle.signal,
           tx.with({
             url,
-            replace: true,
+            traversal: true,
             scroll: false,
             intercept: isIntercept,
             interceptSourceUrl,
@@ -771,9 +773,6 @@ export function createNavigationBridge(
             "[Browser] Page restored from bfcache, resetting navigation state",
           );
           eventController.abortNavigation();
-          // pagehide flips scrollRestoration to "auto" for bfcache compat;
-          // restore "manual" so the router controls scroll on SPA navigations.
-          window.history.scrollRestoration = "manual";
         }
       };
 

package/src/browser/navigation-transaction.ts

@@ -11,7 +11,11 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  buildHistoryState,
+  mergeLocationState,
+  pushHistoryWithIdx,
+} from "./history-state.js";
 
 export { resolveNavigationState } from "./history-state.js";
 
@@ -49,6 +53,12 @@ interface CommitOptions {
   cacheOnly?: boolean;
   /** Server-set location state to merge into history.pushState */
   serverState?: Record<string, unknown>;
+  /**
+   * Back/forward: history is already at this entry. Its state (scroll key,
+   * location state, idx) stays as the browser restored it; serverState is
+   * merged in. The page left was saved by handleTraversalStart.
+   */
+  traversal?: boolean;
 }
 
 /**
@@ -131,6 +141,7 @@ export function createNavigationTransaction(
       interceptSourceUrl,
       cacheOnly,
       serverState,
+      traversal,
     } = opts;
 
     const parsedUrl = new URL(url, window.location.origin);
@@ -145,7 +156,7 @@ export function createNavigationTransaction(
       return { scroll: false };
     }
 
-    handleNavigationStart();
+    if (!traversal) handleNavigationStart();
 
     store.setSegmentIds(segmentIds);
     store.setCurrentUrl(url);
@@ -162,6 +173,15 @@ export function createNavigationTransaction(
       return { scroll: false };
     }
 
+    if (traversal) {
+      if (serverState && Object.keys(serverState).length > 0) {
+        mergeLocationState(serverState);
+      }
+      handle.complete(parsedUrl);
+      debugLog("[Browser] Traversal committed, historyKey:", historyKey);
+      return { scroll };
+    }
+
     const historyState = buildHistoryState(
       opts.state,
       { intercept, sourceUrl: interceptSourceUrl },

package/src/browser/partial-update.ts

@@ -31,6 +31,7 @@ import {
 } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
 import { OPTIMISTIC_COMMIT_TRANSITION_TYPE } from "./optimistic-commit.js";
+import { loaderStore } from "../loader-store.js";
 import {
   collectClientRevalidationDecisions,
   setActiveInterceptTargets,
@@ -42,7 +43,9 @@ function toScrollPayload(
   return { enabled: scroll !== false ? scroll : false };
 }
 
-function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
+export function shouldStartViewTransition(
+  segments: ResolvedSegment[],
+): boolean {
   let hasIntercept = false;
   let hasTransition = false;
   for (const s of segments) {
@@ -52,6 +55,29 @@ function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
   return !hasIntercept && hasTransition;
 }
 
+/**
+ * Transition commit. Every held commit announces the loader streams the
+ * committed tree is still receiving (loader-store.ts announcePendingStreams)
+ * so held useLoader readers pin isLoading:true until this transition lands;
+ * settled/cached segments make it a no-op. Urgent commits call onUpdate
+ * directly: nothing is held there, a reader of a pending stream suspends to
+ * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
+ */
+export function commitInTransition(
+  onUpdate: UpdateSubscriber,
+  segments: readonly ResolvedSegment[],
+  update: NavigationUpdate,
+  transitionTypes: readonly string[],
+): void {
+  startTransition(() => {
+    loaderStore.announcePendingStreams(segments);
+    if (addTransitionType) {
+      for (const type of transitionTypes) addTransitionType(type);
+    }
+    onUpdate(update);
+  });
+}
+
 /**
  * Configuration for creating a partial updater
  */
@@ -351,12 +377,9 @@ export function createPartialUpdater(
           };
 
           if (shouldStartViewTransition(existingSegments)) {
-            startTransition(() => {
-              if (addTransitionType) {
-                addTransitionType("navigation");
-              }
-              onUpdate(cachedUpdate);
-            });
+            commitInTransition(onUpdate, existingSegments, cachedUpdate, [
+              "navigation",
+            ]);
           } else {
             onUpdate(cachedUpdate);
           }
@@ -589,31 +612,27 @@ export function createPartialUpdater(
 
       const scrollPayload = toScrollPayload(navScroll);
 
+      const update: NavigationUpdate = {
+        root: newTree,
+        metadata: payload.metadata!,
+        scroll: scrollPayload,
+      };
       if (mode.type === "action" || mode.type === "stale-revalidation") {
-        startTransition(() => {
-          if (hasTransition && addTransitionType) {
-            addTransitionType("action");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: scrollPayload,
-          });
-        });
+        commitInTransition(
+          onUpdate,
+          reconciled.mainSegments,
+          update,
+          hasTransition ? ["action"] : [],
+        );
       } else if (hasTransition) {
-        startTransition(() => {
-          if (addTransitionType) {
-            addTransitionType("navigation");
-            if (optimisticPresented) {
-              addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);
-            }
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: scrollPayload,
-          });
-        });
+        commitInTransition(
+          onUpdate,
+          reconciled.mainSegments,
+          update,
+          optimisticPresented
+            ? ["navigation", OPTIMISTIC_COMMIT_TRANSITION_TYPE]
+            : ["navigation"],
+        );
       } else if (fullyPrefetched || isSameStructureNav || optimisticPresented) {
         // Content-hold commit, two triggers. Fully-prefetched nav: the payload
         // is fully resolved (forceAwait above), so the transition commits
@@ -637,26 +656,18 @@ export function createPartialUpdater(
         // optimistic clientUrls() presentation commits here too: the group
         // segment reconciles in place (clientGroup key), so a read that still
         // suspends must hold the presented content, not flash a fallback.
-        startTransition(() => {
-          if (optimisticPresented && addTransitionType) {
-            addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: scrollPayload,
-          });
-        });
+        commitInTransition(
+          onUpdate,
+          reconciled.mainSegments,
+          update,
+          optimisticPresented ? [OPTIMISTIC_COMMIT_TRANSITION_TYPE] : [],
+        );
       } else {
         // Cold/partially-prefetched nav that mounts NEW segments: normal
         // commit so fallbacks stream like a first load and the click has
         // visible feedback. Explicit transition() routes keep the
         // content-hold via the hasTransition branch above (the opt-in).
-        onUpdate({
-          root: newTree,
-          metadata: payload.metadata!,
-          scroll: scrollPayload,
-        });
+        onUpdate(update);
       }
 
       debugLog("[Browser] Navigation complete");
@@ -689,6 +700,11 @@ export function createPartialUpdater(
 
       const fullHasTransition = shouldStartViewTransition(segments);
       const fullScrollPayload = toScrollPayload(fullScroll);
+      const fullUpdate: NavigationUpdate = {
+        root: newTree,
+        metadata: payload.metadata!,
+        scroll: fullScrollPayload,
+      };
 
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
@@ -704,44 +720,23 @@ export function createPartialUpdater(
           );
           return;
         }
-        startTransition(() => {
-          if (fullHasTransition && addTransitionType) {
-            addTransitionType("action");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: fullScrollPayload,
-          });
-        });
+        commitInTransition(
+          onUpdate,
+          segments,
+          fullUpdate,
+          fullHasTransition ? ["action"] : [],
+        );
       } else if (mode.type === "action") {
-        startTransition(() => {
-          if (fullHasTransition && addTransitionType) {
-            addTransitionType("action");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: fullScrollPayload,
-          });
-        });
+        commitInTransition(
+          onUpdate,
+          segments,
+          fullUpdate,
+          fullHasTransition ? ["action"] : [],
+        );
       } else if (fullHasTransition) {
-        startTransition(() => {
-          if (addTransitionType) {
-            addTransitionType("navigation");
-          }
-          onUpdate({
-            root: newTree,
-            metadata: payload.metadata!,
-            scroll: fullScrollPayload,
-          });
-        });
+        commitInTransition(onUpdate, segments, fullUpdate, ["navigation"]);
       } else {
-        onUpdate({
-          root: newTree,
-          metadata: payload.metadata!,
-          scroll: fullScrollPayload,
-        });
+        onUpdate(fullUpdate);
       }
 
       return;

package/src/browser/react/ScrollRestoration.tsx

@@ -4,7 +4,7 @@ import { useEffect } from "react";
 import { initScrollRestoration } from "../scroll-restoration.js";
 
 /**
- * Props for ScrollRestoration component
+ * Props for `<Html.ScrollRestoration />`.
  */
 export interface ScrollRestorationProps {
   /**
@@ -25,10 +25,10 @@ export interface ScrollRestorationProps {
    * const byPathname = (location) => location.pathname;
    *
    * // Restore based on pathname (same URL = same scroll)
-   * <ScrollRestoration getKey={byPathname} />
+   * <Html.ScrollRestoration getKey={byPathname} />
    *
    * // Restore based on unique history entry (default)
-   * // <ScrollRestoration /> — omit getKey to use location.key
+   * // <Html.ScrollRestoration /> — omit getKey to use location.key
    * ```
    */
   getKey?: (location: {
@@ -40,7 +40,7 @@ export interface ScrollRestorationProps {
 }
 
 /**
- * ScrollRestoration component
+ * Public as `Html.ScrollRestoration` (`@rangojs/router/client`).
  *
  * Enables scroll position restoration across navigations:
  * - Saves scroll positions to sessionStorage
@@ -57,7 +57,7 @@ export interface ScrollRestorationProps {
  *   return (
  *     <html>
  *       <body>
- *         <ScrollRestoration />
+ *         <Html.ScrollRestoration />
  *         {children}
  *       </body>
  *     </html>
@@ -78,7 +78,7 @@ export function ScrollRestoration({ getKey }: ScrollRestorationProps) {
 /**
  * Hook to initialize scroll restoration
  *
- * Alternative to the ScrollRestoration component for more control.
+ * Alternative to `<Html.ScrollRestoration />` for more control.
  *
  * @example
  * ```tsx

package/src/browser/rsc-router.tsx

@@ -655,7 +655,7 @@ export interface RangoProps {}
  *
  * @example
  * ```tsx
- * import { initBrowserApp, Rango } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "@rangojs/router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *