@rangojs/router 0.24.4 → 0.25.0

package/src/browser/partial-update.ts

@@ -8,8 +8,9 @@ import type { ReactNode } from "react";
 import * as React from "react";
 import { startTransition } from "react";
 
-// addTransitionType is only available in React experimental
-const addTransitionType: ((type: string) => void) | undefined =
+// React 19.3+ and experimental builds. Call it only inside startTransition:
+// outside one, React starts a transition of its own.
+export const addTransitionType: ((type: string) => void) | undefined =
   "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 
 import type { RenderSegmentsOptions } from "../segment-system.js";
@@ -32,7 +33,12 @@ import {
   IS_BROWSER_DEBUG,
 } from "./logging.js";
 import { validatePayloadRedirect } from "./validate-redirect-origin.js";
-import type { HandleData, NavigationUpdate, RscMetadata } from "./types.js";
+import type {
+  HandleData,
+  NavigationUpdate,
+  RscMetadata,
+  ShownEntry,
+} from "./types.js";
 import { OPTIMISTIC_COMMIT_TRANSITION_TYPE } from "./optimistic-commit.js";
 import type { LoaderStore } from "../loader-store.js";
 import { setActiveInterceptTargets } from "../client-urls/navigation.js";
@@ -45,6 +51,7 @@ import { buildHistoryState } from "./history-state.js";
 import { addLocationState } from "./react/location-state-shared.js";
 import { isPlaceholder, type TransitionWhenKind } from "../types/segments.js";
 import { auditTreeCause, type TreeUpdateCause } from "../suspense-audit.js";
+import { revalidationErrorOf } from "../decode-loader-results.js";
 
 /**
  * Hold/animate decision for a commit: a non-intercept segment carries a
@@ -79,19 +86,24 @@ function treeCause(mode: UpdateMode, traversal?: boolean): TreeUpdateCause {
  * 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).
+ * Every commit is tagged with its transition({ when }) `kind` (#1165), then
+ * `transitionTypes`.
  */
 export function commitInTransition(
   loaders: LoaderStore,
   onUpdate: UpdateSubscriber,
   segments: readonly ResolvedSegment[],
   update: NavigationUpdate,
+  kind: TransitionWhenKind,
   transitionTypes: readonly string[],
 ): void {
   startTransition(() => {
     loaders.announcePendingStreams(segments);
     if (addTransitionType) {
+      addTransitionType(kind);
       for (const type of transitionTypes) addTransitionType(type);
     }
+    update.inTransition = true;
     onUpdate(update);
   });
 }
@@ -124,13 +136,15 @@ export interface PartialUpdateConfig {
     /** What the response's handlers pushed, to the handle store. */
     handles(metadata: RscMetadata): void;
     /**
-     * Deliver the navigation state to its readers now. A page built with
-     * holes commits in the task of its click, before the notification of the
-     * click has gone out (event-controller.ts makeDebouncedNotifier), and
-     * React holds that commit where a hole is read with no boundary: without
-     * this useNavigation() reads idle, on the page being left, for the whole
-     * wait. Delivered first, `loading` is on screen when the commit is
-     * handed over, and stays while React holds it, as for a plain click.
+     * Deliver the navigation state to its readers now, and commit it. A page
+     * built with holes commits in the task of its click, before the
+     * notification of the click has gone out (event-controller.ts
+     * makeDebouncedNotifier), and React holds that commit where a hole is
+     * read with no boundary: without this useNavigation() reads idle, on the
+     * page being left, for the whole wait. Committed first, `loading` is on
+     * screen when the commit is handed over, and stays while React holds it,
+     * as for a plain click. Delivered at default priority it joins the
+     * commit's urgent batch, which brings idle with the URL, and never shows.
      */
     flush(): void;
   };
@@ -185,8 +199,8 @@ export interface CommitOverrides {
   interceptSourceUrl?: string;
   /** Server-set location state to merge into history.pushState */
   serverState?: Record<string, unknown>;
-  /** The committed route's name (payload metadata), remembered per history entry. */
-  routeName?: string;
+  /** The payload's metadata: its route name and rewrite target, remembered per history entry. */
+  metadata?: ShownEntry;
 }
 
 /**
@@ -233,7 +247,9 @@ export type UpdateMode =
     };
 
 /**
- * Type for the fetchPartialUpdate function
+ * Type for the fetchPartialUpdate function. In `action` mode it resolves with
+ * the error of a loader that threw while it re-ran (revalidationErrorOf);
+ * the loader throws at its read.
  */
 export type PartialUpdater = (
   targetUrl: string,
@@ -242,7 +258,7 @@ export type PartialUpdater = (
   signal: AbortSignal | undefined,
   tx: BoundTransaction,
   mode?: UpdateMode,
-) => Promise<void>;
+) => Promise<Error | undefined>;
 
 export function createPartialUpdater(
   config: PartialUpdateConfig,
@@ -545,7 +561,7 @@ export function createPartialUpdater(
     signal: AbortSignal | undefined,
     tx: BoundTransaction,
     mode: UpdateMode = { type: "navigate" },
-  ): Promise<void> {
+  ): Promise<Error | undefined> {
     const segmentState = store.getSegmentState();
     const url = targetUrl || window.location.href;
 
@@ -666,6 +682,11 @@ export function createPartialUpdater(
       targetUrl: url,
       segmentIds: segments,
       previousUrl,
+      // The entry being left (a popstate has not moved it yet), unless
+      // previousUrl names an intercept's source.
+      rewriteTarget: interceptSourceUrl
+        ? undefined
+        : store.getHistoryEntryMemory()?.rewriteTarget,
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
       version: getVersion(),
@@ -755,7 +776,7 @@ export function createPartialUpdater(
           const { scroll: commitScroll } = tx.commit(
             matchedIds,
             existingSegments,
-            { routeName: payload.metadata.routeName },
+            { metadata: payload.metadata },
           );
           if (cachedHandleData) {
             store.updateCacheHandleData(
@@ -781,6 +802,7 @@ export function createPartialUpdater(
               onUpdate,
               existingSegments,
               cachedUpdate,
+              whenKind,
               ["navigation"],
             );
           } else {
@@ -804,7 +826,7 @@ export function createPartialUpdater(
           const { scroll: leaveScroll } = tx.commit(
             matchedIds,
             existingSegments,
-            { routeName: payload.metadata.routeName },
+            { metadata: payload.metadata },
           );
 
           if (process.env.NODE_ENV !== "production") {
@@ -824,7 +846,7 @@ export function createPartialUpdater(
           "[Browser] No changes - all revalidations returned false, keeping existing UI",
         );
         tx.commit(matchedIds, existingSegments, {
-          routeName: payload.metadata.routeName,
+          metadata: payload.metadata,
           treeless: true,
         });
         debugLog("[Browser] Navigation complete (no re-render)");
@@ -910,6 +932,13 @@ export function createPartialUpdater(
       // prefetch is decided against the real source.
       const gatedOff = decideGatedOff(reconciled.segments, payload.metadata);
 
+      const isInterceptResponse = hasActiveInterceptSlots(
+        payload.metadata?.slots,
+      );
+      // The source the commit records for an intercept, and its fill's.
+      const effectiveInterceptSource =
+        interceptSourceUrl || segmentState.currentUrl;
+
       // The fill: one request for what the prefetch deferred, listing what
       // the client holds once this payload commits. It leaves now, before
       // the tree is rendered, with this navigation's signal.
@@ -921,8 +950,15 @@ export function createPartialUpdater(
           answer: client.fetchPartial({
             targetUrl: url,
             segmentIds: heldIds,
-            // The page the fill completes is the page it is on.
-            previousUrl: url,
+            // The page the fill completes is the page it is on: from the
+            // target itself nothing intercepts, so an intercept's fill names
+            // its source, as a request from the open modal does.
+            previousUrl: isInterceptResponse ? effectiveInterceptSource : url,
+            ...(isInterceptResponse && {
+              interceptSourceUrl: effectiveInterceptSource,
+            }),
+            // The server ignores it beside an intercept source.
+            rewriteTarget: payload.metadata?.rewriteTarget,
             fill: true,
             signal,
             version: getVersion(),
@@ -1029,15 +1065,19 @@ export function createPartialUpdater(
         newTree = await renderSegments(reconciled.mainSegments, renderOptions);
       }
 
+      // A background refresh keeps the stale page on screen when a loader it
+      // re-ran threw (its entries settled in the build): nothing is committed,
+      // and navigation-bridge logs the rejection (dc-t65). Every other lane
+      // throws it at the read. Before the abort check: the await yields.
+      if (mode.type === "stale-revalidation") {
+        const failed = await revalidationErrorOf(serverSegments);
+        if (failed) throw failed;
+      }
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
         return;
       }
 
-      const isInterceptResponse = hasActiveInterceptSlots(
-        payload.metadata?.slots,
-      );
-
       // Same-structure revalidation: every segment this commit will render
       // already exists on screen (by id) — the navigation mounts nothing new,
       // it only refreshes what the user is looking at. The hold this enables
@@ -1053,8 +1093,6 @@ export function createPartialUpdater(
       const isSameStructureNav =
         mode.type === "navigate" && holdsAll(reconciled.segments);
 
-      const effectiveInterceptSource =
-        interceptSourceUrl || segmentState.currentUrl;
       if (mode.type !== "action" && mode.type !== "stale-revalidation") {
         if (isInterceptResponse) {
           store.setInterceptSourceUrl(effectiveInterceptSource);
@@ -1065,7 +1103,7 @@ export function createPartialUpdater(
 
       const serverLocationState = payload.metadata?.locationState;
       const overrides: CommitOverrides = {
-        routeName: payload.metadata?.routeName,
+        metadata: payload.metadata,
         ...(isInterceptResponse && {
           scroll: false,
           intercept: true,
@@ -1148,6 +1186,7 @@ export function createPartialUpdater(
           onUpdate,
           reconciled.mainSegments,
           update,
+          whenKind,
           hasTransition ? ["action"] : [],
         );
       } else if (hasTransition) {
@@ -1156,6 +1195,7 @@ export function createPartialUpdater(
           onUpdate,
           reconciled.mainSegments,
           update,
+          whenKind,
           optimisticPresented
             ? ["navigation", OPTIMISTIC_COMMIT_TRANSITION_TYPE]
             : ["navigation"],
@@ -1181,7 +1221,7 @@ export function createPartialUpdater(
         // flash). Inside a transition React holds the current UI until the
         // suspended data lands, the action treatment; nothing new mounts (by
         // the isSameStructureNav definition), so no fallback is being withheld
-        // from a first paint. No addTransitionType: this is the React
+        // from a first paint. Its kind is its only type (#1165): a React
         // content-hold, not a view transition. Deliberate trade-off (#622
         // introduced, #624 reverted, then reinstated): a client component that
         // suspends during its FIRST render (use() of a promise created at
@@ -1199,6 +1239,7 @@ export function createPartialUpdater(
           onUpdate,
           reconciled.mainSegments,
           update,
+          whenKind,
           optimisticPresented ? [OPTIMISTIC_COMMIT_TRANSITION_TYPE] : [],
         );
       } else {
@@ -1223,6 +1264,7 @@ export function createPartialUpdater(
       if (holes) await fillHoles(holes, signal, url, gatedOff);
 
       debugLog("[Browser] Navigation complete");
+      if (mode.type === "action") return revalidationErrorOf(serverSegments);
       return;
     } else {
       console.warn(`[Browser] Full update (fallback)`);
@@ -1235,6 +1277,12 @@ export function createPartialUpdater(
         transitionGatedOff: fullGatedOff,
       });
 
+      // A background refresh keeps the page, as in the partial branch: its
+      // loaders streamed, so this waits for them before anything commits.
+      if (mode.type === "stale-revalidation") {
+        const failed = await revalidationErrorOf(segments);
+        if (failed) throw failed;
+      }
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
         return;
@@ -1242,7 +1290,7 @@ export function createPartialUpdater(
 
       const fullUpdateServerState = payload.metadata?.locationState;
       const { scroll: fullScroll } = tx.commit(segmentIds, segments, {
-        routeName: payload.metadata?.routeName,
+        metadata: payload.metadata,
         ...(fullUpdateServerState && { serverState: fullUpdateServerState }),
       });
 
@@ -1283,6 +1331,7 @@ export function createPartialUpdater(
             onUpdate,
             segments,
             fullUpdate,
+            whenKind,
             fullHasTransition ? ["action"] : [],
           );
         }
@@ -1292,16 +1341,25 @@ export function createPartialUpdater(
           onUpdate,
           segments,
           fullUpdate,
+          whenKind,
           fullHasTransition ? ["action"] : [],
         );
       } else if (fullHasTransition) {
-        commitInTransition(store.loaders, onUpdate, segments, fullUpdate, [
-          "navigation",
-        ]);
+        commitInTransition(
+          store.loaders,
+          onUpdate,
+          segments,
+          fullUpdate,
+          whenKind,
+          ["navigation"],
+        );
       } else {
         onUpdate(fullUpdate);
       }
 
+      // This render streamed its loaders (no isAction); the pending action
+      // call waits for them only to report, as the partial lane's commit does.
+      if (mode.type === "action") return revalidationErrorOf(segments);
       return;
     }
   }

package/src/browser/prefetch/cache.ts

@@ -91,6 +91,14 @@ export interface DecodedPrefetch {
    * one prefetch serves unlimited adoptions within TTL/state validity.
    */
   respawn?: () => DecodedPrefetch;
+  /**
+   * The prefetch's stall timer (executePrefetchFetch). Navigation clears it on
+   * the entry it serves: from then on the click owns the stream, which runs to
+   * its end (a Flight response that arrived is never aborted mid-stream). A
+   * prefetch nobody adopted keeps it, so a stalled one is still aborted.
+   * Absent on a respawned entry, which has no timer.
+   */
+  stallTimer?: ReturnType<typeof setTimeout>;
   /**
    * Release the buffered reserve bytes. Called when the entry is evicted
    * without being consumed (expiry, FIFO, sweep, cache clear) so the tee

package/src/browser/prefetch/fetch.ts

@@ -37,6 +37,7 @@ import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../../segment-fragments.js";
 import { PREFETCH_HEADER } from "../../prefetch-markers.js";
 import type { RscPayload } from "../types.js";
+import { getRegisteredStore } from "../navigation-store-handle.js";
 
 /**
  * Decoder injected at app startup (see setPrefetchDecoder). This is
@@ -162,6 +163,13 @@ function buildPrefetchUrl(
   if (routerId) {
     targetUrl.searchParams.set("_rsc_rid", routerId);
   }
+  // The page's rewrite target, so the server diffs against the route that
+  // rendered it, as for the navigation.
+  const rewriteTarget =
+    getRegisteredStore()?.getHistoryEntryMemory()?.rewriteTarget;
+  if (rewriteTarget) {
+    targetUrl.searchParams.set("_rsc_rt", rewriteTarget);
+  }
   return targetUrl;
 }
 
@@ -218,8 +226,9 @@ function executePrefetchFetch(
   // hover/direct path (no caller signal) and the queue-driven path (whose caller
   // signal only aborts on navigation, never on a stall). On fire it aborts the
   // fetch/stream and evicts the published entry if one exists; it is NOT cleared
-  // when headers arrive (see below) — it is cleared when the stream completes, or
-  // in `.finally()` for paths that publish no streaming entry.
+  // when headers arrive (see below) — it is cleared when the stream completes,
+  // when a navigation serves the entry (DecodedPrefetch.stallTimer), or in
+  // `.finally()` for paths that publish no streaming entry.
   let publishedKey: string | undefined;
   let publishedEntry: DecodedPrefetch | undefined;
   const timeoutController = new AbortController();
@@ -341,6 +350,7 @@ function executePrefetchFetch(
         streamComplete,
         scope,
         complete: false,
+        stallTimer: timeoutId,
         ...(reserve && {
           dispose: () => {
             reserve.cancel().catch(() => {});
@@ -369,6 +379,7 @@ function executePrefetchFetch(
       // reserve would replay broken bytes, so it stays one-shot (and its
       // buffered reserve is released via the removePrefetch dispose above).
       Promise.allSettled([payload, streamComplete]).then(([decode]) => {
+        clearTimeout(timeoutId);
         if (decode.status === "fulfilled" && endedCleanly) {
           entry.complete = true;
           if (reserve) {
@@ -388,7 +399,6 @@ function executePrefetchFetch(
             }
           }
         }
-        clearTimeout(timeoutId);
       });
       return entry;
     })

package/src/browser/rango-marker.ts

@@ -0,0 +1,13 @@
+import { PACKAGE_VERSION } from "@rangojs/router:version";
+
+/**
+ * Publishes `window.__rango = { version }` so outside tools can tell a page is
+ * a Rango app and which router release serves it. Write-only and informational:
+ * nothing in the router reads it (rango-marker.test.ts greps src/ for reads),
+ * and only the npm semver is exposed, no build hash, router id or config.
+ */
+export function publishRangoMarker(): void {
+  (window as { __rango?: unknown }).__rango = Object.freeze({
+    version: PACKAGE_VERSION,
+  });
+}

package/src/browser/react/NavigationProvider.tsx

@@ -505,9 +505,16 @@ export function NavigationProvider({
 
   // The last navigation's scroll decision, until React commits its update.
   const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
+  // The last payload handed to React, until it commits: route state that
+  // arrived behind it waits for that commit (flushRouteState("anchor")).
+  const committingRef = useRef<typeof payload | undefined>(undefined);
 
   // Apply scroll after React commits the new content to the DOM
   useLayoutEffect(() => {
+    if (payload === committingRef.current) {
+      committingRef.current = undefined;
+      eventController.releaseRouteState();
+    }
     const scrollAction = pendingScrollRef.current;
     if (!scrollAction) return;
     pendingScrollRef.current = undefined;
@@ -518,6 +525,7 @@ export function NavigationProvider({
       restore: scrollAction.restore,
       scroll: scrollAction.enabled,
       isStreaming: scrollAction.isStreaming,
+      committed: true,
     });
   });
 
@@ -544,7 +552,9 @@ export function NavigationProvider({
         eventController.releaseHydrationLock();
       }
 
-      setPayload({ root: update.root, metadata: update.metadata });
+      const next = { root: update.root, metadata: update.metadata };
+      committingRef.current = next;
+      setPayload(next);
       // The state of the entry this payload renders, as its commit recorded
       // it: one update, so one lane, so one React commit with the tree.
       setLocationState(eventController.getLocationState());
@@ -556,9 +566,23 @@ export function NavigationProvider({
         eventController.setParams(update.metadata.params);
       }
 
+      // tx.commit() and the metadata updates above mutate the controller
+      // synchronously, but its ordinary notifications are task-debounced. Flush
+      // them here so hook setState calls inherit this payload update's lane. In
+      // a transition that suspends, the source tree therefore keeps its source
+      // pathname/params until the destination payload commits with them.
+      // A page in a transition: route state that arrives from here waits for
+      // this payload's commit (useCommitAnchoredState). An urgent page: it is
+      // set at default priority, in the page's lane, and commits with it.
+      eventController.flushRouteState(
+        update.inTransition ? "anchor" : "release",
+      );
+
       // A page rendered from a history-cache entry (back/forward, or a link
       // to it) starts from the entry's pushes, and its response's handles
       // merge onto them: the page on screen's pushes are not its segments'.
+      // After the flush: a crumb whose content is still pending would hold
+      // the page in its transition; it waits and lands in the page's task.
       const { matched, cachedHandleData } = update.metadata;
       if (matched && cachedHandleData) {
         eventController.setHandleData(cachedHandleData, matched);
@@ -575,12 +599,6 @@ export function NavigationProvider({
           update.metadata.resolvedIds,
         );
       }
-
-      // tx.commit() and the metadata updates above mutate the controller
-      // synchronously, but its ordinary notifications are task-debounced. Flush
-      // them here so hook setState calls inherit this payload update's lane. In
-      // a transition that suspends, the source tree therefore keeps its source
-      // pathname/params until the destination payload commits with them.
       eventController.flushRouteState();
     });
 

package/src/browser/react/filter-segment-order.ts

@@ -9,6 +9,19 @@ export function isLoaderSegmentId(id: string): boolean {
   return LOADER_SEGMENT_ID.test(id);
 }
 
+/**
+ * The parent of a loader sub-id (`${parentId}D${index}.${loaderId}`); any
+ * other id unchanged. parentId is a shortCode (never "D"), or
+ * `${shortCode}.${slotName}` for an intercept slot's loaders, where the
+ * user-chosen name may hold an uppercase "D" ("@Detail"). Strip from the first
+ * `D<index>.`: splitting on a bare "D" mis-cut "@Detail" to "@" and silently
+ * dropped the loader's data. Correct only because slot names cannot contain
+ * "." (assertValidSlotName, route-definition/dsl-helpers.ts).
+ */
+export function loaderParentId(id: string): string {
+  return id.replace(/D\d+\..*$/, "");
+}
+
 /**
  * Build the handle-collection segment order from a raw `matched` list.
  *

package/src/browser/react/use-action.ts

@@ -11,19 +11,9 @@ import {
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 import type { TrackedActionState } from "../types.js";
+import { DEFAULT_ACTION_STATE } from "../event-controller.js";
 import { invariant } from "../../errors.js";
 
-/**
- * Default action state (idle with no payload)
- */
-const DEFAULT_ACTION_STATE: TrackedActionState = {
-  state: "idle",
-  actionId: null,
-  payload: null,
-  error: null,
-  result: null,
-};
-
 /**
  * Extract action ID from a server action function or string.
  *
@@ -49,10 +39,13 @@ function getActionId(action: ServerActionFunction | string): string {
     return action;
   }
 
-  // If we get here, this is likely an action passed as prop from a server component
-  // These lose their metadata during RSC serialization
+  // If we get here, this is likely an action passed as prop from a server
+  // component: these lose their metadata during RSC serialization. The
+  // guidance is dev-only: it was about 225 B gzip of every client build that
+  // calls useAction.
   throw new Error(
-    `useAction: Cannot extract action ID from function reference.
+    process.env.NODE_ENV !== "production"
+      ? `useAction: Cannot extract action ID from function reference.
 
 This typically happens when an action is passed as a prop from a server component.
 Actions passed through RSC lose their metadata during serialization.
@@ -65,7 +58,8 @@ Solutions:
 2. Use the action name as a string:
    const state = useAction("myAction");
 
-The string must match the exported function name from your "use server" file.`,
+The string must match the exported function name from your "use server" file.`
+      : "useAction: Cannot extract action ID from function reference.",
   );
 }