@rangojs/router 0.29.0 → 0.30.1

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.29.0",
+      version: "0.30.1",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/browser/react/use-action.d.ts

@@ -13,11 +13,12 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * tracks the state of individual server action invocations.
  *
  * Uses the event controller for reactive state management.
- * State is derived from the inflight actions tracked by the controller.
+ * State is derived from the calls the controller tracks: those in flight,
+ * and each action's last settled call.
  *
  * Features:
  * - Tracks action lifecycle: idle → loading → streaming → idle
- * - Captures result/error locally (React handles cleanup)
+ * - Keeps the settled call's state until the action is called again.
  * - If the same action fires several times, reports the latest call to
  *   start. An earlier call that settles later changes nothing it reports;
  *   a latest call that was aborted reports idle with nothing. One call at a

package/dist/types/browser/react/use-handle.d.ts

@@ -39,6 +39,7 @@ export declare function useHandle<T, A, S>(handle: Handle<T, A>, selector: (data
  * location commit with their page.
  *
  * A value shallow-equal to the last one sets nothing, so a reader renders only
- * when its value moves.
+ * when its value moves. A release is compared with what React committed, as in
+ * useRouteState.
  */
 export declare function useCommitAnchoredState<T>(init: () => T, waitForRelease?: boolean): [T, (value: T, signal?: RouteStateSignal) => void];

package/dist/types/browser/react/use-route-state.d.ts

@@ -0,0 +1,45 @@
+import type { RouteStateSignal } from "../event-controller.js";
+/**
+ * The value a reader rendered in React's last commit of it, written by its
+ * layout effect. A page's release runs in the provider's layout effect, after
+ * every reader's (children first), so it reads the commit that brings the
+ * page.
+ */
+export declare function useCommitted<T>(value: T): {
+    readonly current: T;
+};
+/**
+ * Sets a route-state reader's value. `next` maps the value React ends on once
+ * every set so far commits (`latest`) to the reader's value; `rebase` sets
+ * `next` itself, so React recomputes it on whatever base it renders. The value
+ * must not be a function.
+ */
+export type RouteStateSetter<T> = (next: (base: T) => T, signal?: RouteStateSignal, rebase?: boolean) => void;
+/**
+ * Route state a reader sets as the router store notifies it, in the lane of
+ * the notification that carries it. A notification equal to `latest` sets
+ * nothing, so a reader renders only when its value moves.
+ *
+ * A release is compared with what React committed, not with `latest`: while
+ * React holds a page, its set is not on screen, and an urgent page that ends
+ * the hold brings an equal value. A release that finds every set committed
+ * with its value sets nothing.
+ */
+export declare function useRouteState<T>(init: () => T, same: (a: T, b: T) => boolean): [T, RouteStateSetter<T>];
+/** The route a URL hook reads. */
+export interface UrlRoute {
+    location: URL;
+    params: Record<string, string>;
+}
+/**
+ * A URL hook's value (usePathname, useParams, useSearchParams): `read` of the
+ * route, seeded from the hydration snapshot while the document hydrates, then
+ * set as the store notifies it and at a page's release (useRouteState). The
+ * release rides the handle channel. `read` applies when the store changes,
+ * never in a later render: a new one takes effect from the next change.
+ *
+ * A read equal to the value it is set over keeps that value, so an object
+ * reader changes identity once per value: a release that ends a hold sets the
+ * held page's object, which React's render of the held lane keeps.
+ */
+export declare function useUrlValue<T>(read: (route: UrlRoute) => T, same: (a: T, b: T) => boolean): T;

package/dist/types/browser/types.d.ts

@@ -231,7 +231,11 @@ export type ActionLifecycleState = "idle" | "loading" | "streaming";
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface TrackedActionState {
-    /** Current lifecycle state of the action */
+    /**
+     * Current lifecycle state of the action. Once the call settles it is
+     * "idle" and the rest of the call's state is kept until the action's next
+     * call.
+     */
     state: ActionLifecycleState;
     /** Server action function ID (e.g., "addToCart") */
     actionId: string | null;
@@ -239,12 +243,12 @@ export interface TrackedActionState {
     payload: unknown[] | FormData | null;
     /** Error if action failed */
     error: unknown | null;
-    /** Result data from the action (preserved after completion) */
+    /** Result data from the action */
     result: unknown | null;
     /**
      * The error of a loader that threw while it re-ran after this successful
-     * action (the first, when several did). The loader also throws at its
-     * useLoader read, where the nearest error boundary catches it.
+     * action (the first, when several did). The loader also throws at its useLoader read, where the nearest
+     * error boundary catches it.
      */
     revalidationError: unknown | null;
 }

package/dist/types/suspense-audit.d.ts

@@ -68,6 +68,19 @@ export interface BoundaryAudit {
     /** The fallback's effect was cleaned up in this task (auditFallback). */
     fallbackGone: boolean;
 }
+/**
+ * One loaded copy of this module. A test that re-imports the module after
+ * vi.resetModules() runs two, and the one its static imports use is not the
+ * one on `__rangoSuspenseAudit`. The router's unit-test lock resets and
+ * checks each (src/__tests__/kit/suspense-audit-lock.ts).
+ */
+export interface SuspenseAuditInstance {
+    /** The violation counters above zero and the last events, if any. */
+    violations(): string | undefined;
+    forget(): void;
+    /** Resolves once the judgments queued so far have run. */
+    settle(): Promise<void>;
+}
 export declare function createBoundaryAudit(boundary: string, segmentId: string): BoundaryAudit;
 /**
  * Render phase: the value this render hands the boundary.
@@ -153,5 +166,10 @@ export declare function auditTreeCause(cause: TreeUpdateCause): void;
  * readers subscribe to, or through a pending promise read with use().
  */
 export declare function auditTreeUpdate(root?: unknown): void;
-/** Forget every tree and mount seen so far. For tests of the audit itself. */
+/**
+ * Forget every tree, mount, hand-over and count seen so far: the root that
+ * held them is gone. A test unmounts its root, production never does
+ * (testing/render-route.tsx, src/__tests__/kit/suspense-audit-lock.ts).
+ * Creates no report: with the audit off there is none.
+ */
 export declare function forgetSuspenseAudit(): void;

package/dist/types/testing/render-route.d.ts

@@ -385,15 +385,15 @@ export interface TestRouterHandle {
      * await act(async () => tail.resolve());
      * // useNavigation(): idle, isStreaming false
      *
-     * A navigation started while React holds a page goes inside
-     * `await act(async () => ...)`. Its first update makes React retry the held
-     * page, which suspends again; a synchronous act() scope drops that retry
-     * and React renders no later update of the same priority.
+     * A navigation started while React holds a page shows its page once the
+     * call resolves, with or without act(). A `<Link>` click over a held page
+     * still goes inside `await act(async () => ...)` (docs/testing.md).
      *
      * @example
-     * await act(async () => {
-     *   await router.navigate("/products/3", { transition: false });
-     * });
+     * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+     * // React holds /products/2
+     * await router.navigate("/products/3", { transition: false });
+     * // /products/3 is on screen
      */
     navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition"> & {
         streamUntil?: Promise<unknown>;

package/dist/types/vite/discovery/build-versions.d.ts

@@ -194,22 +194,26 @@ export declare function isSourceMap(fileName: string): boolean;
  * hashed by the routers that reach it (resolveRouterMembers), so nothing the
  * map says is lost by skipping it.
  *
- * Works on the region comments, so a minified server build (which has none)
- * keeps the map in every router's hash: more clearing, never less.
+ * Works on the module markers, so a minified server build (which has none),
+ * or a map no marker follows, keeps the map in every router's hash: more
+ * clearing, never less.
  */
 export declare function stripServerReferenceMap(source: string): string;
 /**
- * Take the module paths out of a chunk's region comments.
+ * Take the module paths out of a chunk's module markers.
  *
- * The bundler prints one before each module's code, and the path says where
- * the build ran, not what it built: it is relative to the directory `vite
- * build` was started from (`vite build apps/web` from a repository root
- * prints other paths than `vite build` in the app), it holds the pnpm store
- * directory with its peer suffix, and a virtual id is printed verbatim,
- * absolute paths in its query included. The code under the comment is hashed
- * either way.
+ * The path says where the build ran, not what it built: it is relative to the
+ * directory `vite build` was started from (`vite build apps/web` from a
+ * repository root prints other paths than `vite build` in the app), it holds
+ * the pnpm store directory with its peer suffix, and a virtual id is printed
+ * verbatim, absolute paths in its query included. The code after the marker
+ * is hashed either way.
+ *
+ * A `//#region` line is always a marker. A `// ` line is one only when it
+ * names a module of the chunk (`moduleIds`): a kept comment or a line of a
+ * multi-line string can start the same way, and is hashed.
  */
-export declare function stripRegionPaths(source: string): string;
+export declare function stripModulePaths(source: string, moduleIds: readonly string[]): string;
 /** One thing a version is a hash of: its name and the digest of its bytes. */
 export type VersionInput = readonly [name: string, digest: string];
 /** One bundle file, digested once for every router. */
@@ -237,8 +241,8 @@ export interface DigestedFile {
  *
  * Three things are taken out of a chunk's text first, each because it says
  * where or how the build ran: the server-reference map's body
- * ({@link stripServerReferenceMap}), the paths in region comments
- * ({@link stripRegionPaths}), and the hashed names of bundle files. A name
+ * ({@link stripServerReferenceMap}), the paths in module markers
+ * ({@link stripModulePaths}), and the hashed names of bundle files. A name
  * carries the content hash of its file, and every chunk importing the file
  * has the name in its bytes, so one router's change would otherwise move the
  * digest of every chunk naming its chunk. Only names with a content hash are

package/dist/types/vite/plugins/stable-rsc-output.d.ts

@@ -41,7 +41,7 @@ export declare function canonicalAssetsManifestBinding(code: string): string | u
  *    (`ServerReferencesManager.claimMap`), which varies with the concurrent
  *    scan builds (e2e/test-app: 2 of 2 consecutive builds differed). Sorted
  *    here so a minified server build, where stripServerReferenceMap finds no
- *    region comments, still hashes the same bytes.
+ *    module markers, still hashes the same bytes.
  * 2. Local name of the assets-manifest import. plugin-rsc imports the manifest
  *    under three names; the bundler merges them into one import per chunk and
  *    keeps a different one from build to build (the cache-versions fixture:

package/dist/vite/index.js

@@ -4491,13 +4491,13 @@ import {
   Component as Component3,
   createElement as createElement4,
   isValidElement as isValidElement2,
-  useContext as useContext17,
+  useContext as useContext18,
   useMemo as useMemo9,
   Suspense as Suspense2
 } from "react";
 
 // src/browser/react/use-handle.ts
-import { useContext, useState, useEffect, useRef } from "react";
+import { useContext as useContext2, useState as useState2, useEffect as useEffect2, useRef as useRef2 } from "react";
 
 // src/missing-id-error.ts
 var SELF_FILES = /* @__PURE__ */ new Set([
@@ -4575,6 +4575,19 @@ var NavigationStoreContext = createContext(null);
 var LocationStateContext = createContext(void 0);
 var HydrationBarrierContext = createContext(0);
 
+// src/browser/react/use-route-state.ts
+import {
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState
+} from "react";
+var NO_ROUTE = {
+  location: new URL("/", "http://localhost"),
+  params: Object.freeze({})
+};
+
 // src/handles/meta.ts
 function isUnsetDescriptor(descriptor) {
   return typeof descriptor === "object" && descriptor !== null && "unset" in descriptor && typeof descriptor.unset === "string";
@@ -4704,18 +4717,18 @@ function collectMeta(segments) {
 var Meta = createHandle(collectMeta, "__rsc_router_meta__");
 
 // src/theme/theme-context.ts
-import { createContext as createContext2, useContext as useContext2 } from "react";
+import { createContext as createContext2, useContext as useContext3 } from "react";
 var ThemeContext = createContext2(null);
 
 // src/browser/react/nonce-context.ts
-import { createContext as createContext3, useContext as useContext3 } from "react";
+import { createContext as createContext3, useContext as useContext4 } from "react";
 var NonceContext = createContext3(void 0);
 
 // src/handles/MetaTags.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 // src/handles/Scripts.tsx
-import { useState as useState2 } from "react";
+import { useState as useState3 } from "react";
 
 // src/handles/script.ts
 function validateConfigDev(config) {
@@ -4769,7 +4782,7 @@ var Script = createHandle(collectScripts, "__rsc_router_script__");
 import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 
 // src/browser/react/ScrollRestoration.tsx
-import { useEffect as useEffect2 } from "react";
+import { useEffect as useEffect3 } from "react";
 
 // src/browser/scroll-restoration.ts
 init_logging();
@@ -4783,12 +4796,12 @@ import { Component, Suspense, use as use2, useMemo as useMemo3 } from "react";
 
 // src/outlet-provider.tsx
 import {
-  useContext as useContext4,
+  useContext as useContext5,
   useMemo
 } from "react";
 
 // src/suspense-audit-react.tsx
-import { useEffect as useEffect3, useLayoutEffect, useRef as useRef2 } from "react";
+import { useEffect as useEffect4, useLayoutEffect as useLayoutEffect2, useRef as useRef3 } from "react";
 
 // src/suspense-audit.ts
 init_internal_debug();
@@ -4803,13 +4816,13 @@ import { jsx as jsx3 } from "react/jsx-runtime";
 import { createElement as createElement2 } from "react";
 
 // src/loader-redirect.tsx
-import { useEffect as useEffect4 } from "react";
+import { useEffect as useEffect5 } from "react";
 
 // src/browser/react/use-router.ts
-import { useContext as useContext6, useMemo as useMemo2 } from "react";
+import { useContext as useContext7, useMemo as useMemo2 } from "react";
 
 // src/browser/react/use-mount.ts
-import { useContext as useContext5 } from "react";
+import { useContext as useContext6 } from "react";
 
 // src/browser/react/mount-context.ts
 import {
@@ -5002,12 +5015,12 @@ import {
   startTransition,
   use as use3,
   useCallback,
-  useContext as useContext7,
-  useEffect as useEffect5,
+  useContext as useContext8,
+  useEffect as useEffect6,
   useMemo as useMemo4,
   useOptimistic,
-  useRef as useRef3,
-  useState as useState3
+  useRef as useRef4,
+  useState as useState4
 } from "react";
 
 // src/loader-store.ts
@@ -5169,37 +5182,23 @@ function insertSegments(node, segments, index, leafBase, paramNames) {
 }
 
 // src/browser/react/use-navigation.ts
-import {
-  useContext as useContext8,
-  useState as useState4,
-  useEffect as useEffect6,
-  useLayoutEffect as useLayoutEffect2,
-  useRef as useRef4
-} from "react";
+import { useContext as useContext9, useEffect as useEffect7, useRef as useRef5 } from "react";
 
 // src/browser/react/use-pathname.ts
-import { useContext as useContext9, useState as useState5, useEffect as useEffect7, useRef as useRef5 } from "react";
+import { useContext as useContext10 } from "react";
 
 // src/client-urls/optimistic-location.ts
 import { createContext as createContext6 } from "react";
 var OptimisticLocationContext = createContext6(null);
 
 // src/browser/react/use-search-params.ts
-import {
-  useCallback as useCallback2,
-  useContext as useContext10,
-  useEffect as useEffect8,
-  useMemo as useMemo5,
-  useRef as useRef6,
-  useState as useState6
-} from "react";
+import { useCallback as useCallback2, useContext as useContext11, useMemo as useMemo5 } from "react";
 
 // src/browser/react/use-params.ts
-import { useContext as useContext11, useState as useState7, useEffect as useEffect9, useRef as useRef7 } from "react";
-var EMPTY_PARAMS = Object.freeze({});
+import { useContext as useContext12 } from "react";
 
 // src/browser/react/use-action.ts
-import { useContext as useContext12, useState as useState8, useEffect as useEffect10, useRef as useRef8 } from "react";
+import { useContext as useContext13, useState as useState5, useEffect as useEffect8, useRef as useRef6 } from "react";
 
 // src/browser/event-controller.ts
 init_notify_listeners();
@@ -5262,31 +5261,31 @@ function subscribeToLocationChange(eventController, listener) {
 }
 
 // src/browser/react/use-segments.ts
-import { useContext as useContext13, useEffect as useEffect11, useRef as useRef9 } from "react";
+import { useContext as useContext14, useEffect as useEffect9, useRef as useRef7 } from "react";
 
 // src/browser/react/NavigationProvider.tsx
 import {
-  useState as useState11,
-  useEffect as useEffect13,
+  useState as useState8,
+  useEffect as useEffect11,
   useLayoutEffect as useLayoutEffect4,
   useCallback as useCallback4,
   useMemo as useMemo7,
-  useRef as useRef11,
+  useRef as useRef9,
   use as use4,
   startTransition as startTransition2
 } from "react";
 
 // src/root-error-boundary.tsx
-import { Component as Component2, useState as useState9 } from "react";
+import { Component as Component2, useState as useState6 } from "react";
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 
 // src/theme/ThemeProvider.tsx
 import {
   useCallback as useCallback3,
-  useEffect as useEffect12,
+  useEffect as useEffect10,
   useLayoutEffect as useLayoutEffect3,
   useMemo as useMemo6,
-  useState as useState10
+  useState as useState7
 } from "react";
 
 // src/theme/constants.ts
@@ -5320,18 +5319,18 @@ import { jsx as jsx7 } from "react/jsx-runtime";
 import {
   forwardRef,
   useCallback as useCallback5,
-  useContext as useContext15,
-  useEffect as useEffect15,
+  useContext as useContext16,
+  useEffect as useEffect13,
   useMemo as useMemo8,
-  useRef as useRef12
+  useRef as useRef10
 } from "react";
 
 // src/browser/react/use-link-status.ts
 import {
   createContext as createContext7,
-  useContext as useContext14,
-  useState as useState12,
-  useEffect as useEffect14
+  useContext as useContext15,
+  useState as useState9,
+  useEffect as useEffect12
 } from "react";
 var LinkContext = createContext7(
   null
@@ -5532,14 +5531,14 @@ var Link = forwardRef(function Link2({
   onClick,
   ...props
 }, ref) {
-  const ctx = useContext15(NavigationStoreContext);
+  const ctx = useContext16(NavigationStoreContext);
   const isExternal = isExternalUrl(to, ctx?.origin);
   const resolvedTo = useMemo8(
     () => isExternal ? to : prefixBasename(to, ctx?.basename),
     [to, isExternal, ctx?.basename]
   );
   const configuredStrategy = prefetch ?? ctx?.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
-  const internalRef = useRef12(null);
+  const internalRef = useRef10(null);
   const setRef = useCallback5(
     (node) => {
       internalRef.current = node;
@@ -5551,7 +5550,7 @@ var Link = forwardRef(function Link2({
     },
     [ref]
   );
-  const stateRef = useRef12(state);
+  const stateRef = useRef10(state);
   stateRef.current = state;
   const handleClick = useCallback5(
     (e) => {
@@ -5608,7 +5607,7 @@ var Link = forwardRef(function Link2({
       );
     }
   }, [configuredStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
-  useEffect15(() => {
+  useEffect13(() => {
     if (isExternal || !ctx?.store) return;
     if (configuredStrategy !== "viewport" && configuredStrategy !== "render" && configuredStrategy !== "adaptive") {
       return;
@@ -5728,7 +5727,7 @@ var Breadcrumbs = createHandle(
 );
 
 // src/browser/react/location-state.ts
-import { useContext as useContext16, useEffect as useEffect16 } from "react";
+import { useContext as useContext17, useEffect as useEffect14 } from "react";
 
 // src/browser/react/use-href.tsx
 import { useCallback as useCallback6 } from "react";
@@ -5944,7 +5943,7 @@ import {
   useDeferredValue,
   useLayoutEffect as useLayoutEffect5,
   useMemo as useMemo10,
-  useState as useState13
+  useState as useState10
 } from "react";
 
 // src/client-urls/navigation.ts
@@ -7142,7 +7141,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.29.0",
+  version: "0.30.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -8054,20 +8053,39 @@ var SERVER_CSS_MODULE = /^virtual:vite-rsc\/css\?type=rsc&id=([^&]+)/;
 function isSourceMap(fileName) {
   return fileName.endsWith(".map");
 }
-var SERVER_REFERENCES_REGION_START = `//#region \\0${SERVER_REFERENCES_MODULE_ID.slice(1)}
-`;
-var REGION_END = "//#endregion";
+var MODULE_MARKER = /^\/\/(#region)? (.+)$/gm;
+var SERVER_REFERENCE_MAP = new RegExp(
+  `(^//(?:#region)? ${escapeRegExp(`\\0${SERVER_REFERENCES_MODULE_ID.slice(1)}`)}
+)[\\s\\S]*?(?=^//(?: |#endregion))`,
+  "m"
+);
 function stripServerReferenceMap(source) {
-  const start = source.indexOf(SERVER_REFERENCES_REGION_START);
-  if (start === -1) return source;
-  const bodyStart = start + SERVER_REFERENCES_REGION_START.length;
-  const end = source.indexOf(REGION_END, bodyStart);
-  if (end === -1) return source;
-  return source.slice(0, bodyStart) + source.slice(end);
+  return source.replace(SERVER_REFERENCE_MAP, "$1");
 }
-var REGION_LINE = /^\/\/#region .*$/gm;
-function stripRegionPaths(source) {
-  return source.replace(REGION_LINE, "//#region");
+function printedModuleIds(moduleIds) {
+  const printed = /* @__PURE__ */ new Set();
+  for (const id of moduleIds) {
+    if (!isAbsolutePath(id)) {
+      printed.add(id.replaceAll("\0", "\\0"));
+      continue;
+    }
+    const segments = id.replaceAll("\\", "/").split("/");
+    for (let index = 0; index < segments.length; index++) {
+      printed.add(segments.slice(index).join("/"));
+    }
+  }
+  return printed;
+}
+function stripModulePaths(source, moduleIds) {
+  let printed;
+  return source.replace(
+    MODULE_MARKER,
+    (line, region, name) => {
+      if (region) return "//#region";
+      printed ??= printedModuleIds(moduleIds);
+      return printed.has(name.replace(/^(?:\.\.\/)+/, "")) ? "//" : line;
+    }
+  );
 }
 var FILE_REFERENCE = "\0";
 var FOREIGN_FILE = "~";
@@ -8119,8 +8137,9 @@ function digestBundle(bundle, projectRoot, read, label) {
       };
     }
     const references = [];
-    const text = stripRegionPaths(
-      stripServerReferenceMap(decoder3.decode(bytes))
+    const text = stripModulePaths(
+      stripServerReferenceMap(decoder3.decode(bytes)),
+      chunk.moduleIds
     );
     const blanked = reference ? text.replace(reference, (name) => {
       references.push(fileOfBaseName.get(name));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/client-urls/SKILL.md

@@ -450,16 +450,12 @@ function StockPanel() {
 }
 
 function SaveStock({ sku }: { sku: string }) {
+  // Kept until the next save starts.
   const { revalidationError } = useAction(saveStock);
-  const [stale, setStale] = useState(false);
-  // useAction resets to idle once the action has settled: keep the notice.
-  useEffect(() => {
-    if (revalidationError) setStale(true);
-  }, [revalidationError]);
   return (
     <form action={saveStock.bind(null, sku)}>
       <button>Save</button>
-      {stale && (
+      {revalidationError != null && (
         <p role="status">Saved. The stock count could not be refreshed.</p>
       )}
     </form>

package/skills/hooks/handle-and-actions.md

@@ -196,6 +196,14 @@ Track the lifecycle of a server action, wherever on the page it was invoked.
 If the same action fires several times, the hook reports the latest call: the
 last one to start.
 
+- Once the call settles, `state` is `idle` and the rest of its state
+  (`result`, `error`, `revalidationError`, `payload`, `actionId`) stays until
+  the same action is called again: through navigations and Back/Forward, and
+  in a component that mounts after the call settled. Every reader of the
+  same action (a function or a full id) reads the same call; a string reader
+  follows the latest call of any action with that export name. The next
+  call reads `loading` with none of them, then its own. A document load
+  starts with nothing.
 - When the latest call returns before an earlier one, the hook shows its
   result. The earlier call settling afterwards changes nothing the hook
   reports, a result or an error alike. That call still runs to its end: its
@@ -203,8 +211,7 @@ last one to start.
   page, and an error-boundary response replaces it.
 - A latest call that was aborted reports nothing: `idle`, with no result or
   error. The hook does not fall back to an earlier call. The router aborts
-  calls in flight when another call's response is an error boundary, and on
-  Back/Forward into or out of an intercept.
+  the other calls in flight when a call's response is an error boundary.
 - `useNavigation()` stays `loading` while any call runs.
 
 Which calls count as the same action depends on what you pass:

package/skills/hooks/navigation.md

@@ -90,9 +90,9 @@ reads (a selector, the full state): work that starts shows at once
 when the response stream ended earlier, and agrees with every other
 `useNavigation()` reader on the screen. A page that ends the hold urgently (a
 Back to a page without `transition()`, a link with `transition={false}`)
-shows with its own values in every `useNavigation()` reader. `usePathname()`
-can read the path of the page being left on that page's first screen, until
-React finishes the render of the page it held.
+shows with its own values in every `useNavigation()` reader, and with its URL
+in `usePathname()`, `useParams()`, `useSearchParams()` and `useSegments()`,
+also when it is the URL React was holding.
 
 The rule holds for readers mounted before the page was handed to React. A
 reader that mounts while the page is held (a menu opened during the wait)

package/skills/hooks/urls.md

@@ -123,6 +123,7 @@ click or `router.push()`.
 | Back/Forward, entry fetched again                 | when the fetched page commits; until then the page being left is on screen |
 | a Back/Forward whose fetch fails                  | with the error boundary: they report the entry the browser is on           |
 | `router.push(url, { revalidate: false })`         | at once: nothing is fetched and the page stays                             |
+| `transition={false}` over a held page             | with that page's first screen, also on the URL React was holding           |
 | inside an optimistic `clientUrls()` destination   | at the click, for that branch only (see `/client-urls`)                    |
 
 **A newer click that fails while a page is held.** Click a link, and while