@rangojs/router 0.18.0 → 0.19.0

package/src/types/segments.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
-import type { RevalidateParams, HandlerContext } from "./handler-context.js";
+import type { IsActionFn } from "./handler-context.js";
+import type { DefaultRouteName } from "./global-namespace.js";
 
 /**
  * CSS class(es) for a ViewTransition phase.
@@ -10,96 +11,97 @@ import type { RevalidateParams, HandlerContext } from "./handler-context.js";
 export type ViewTransitionClass = Record<string, string> | string;
 
 /**
- * The context a transition({ when }) predicate receives.
- *
- * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
- * gets — the same navigation/action metadata — so the two read the same shape,
- * plus `get`/`env` for request-context reads. There is no full `HandlerContext`
- * here: the gate runs at the RSC-payload layer with the request context, not a
- * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
- * absent by design. On ordinary routes, `get` can read what handlers or
- * middleware set via `ctx.set(...)`. On `ppr` routes the gate runs before route
- * handlers, so only middleware-established values are available.
- *
- * Field availability (all source fields are optional — never fabricated):
- * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
- *   populated on soft navigations and action-success revalidations. They are
- *   undefined on an initial full document load and on action-error / no-JS error
- *   paths that skip the navigation snapshot — there is no prior page to name.
- * - `nextUrl` / `nextParams` / `get` / `env` / `method` are always present;
- *   `toRouteName` is present only when the target route is named (undefined for
- *   unnamed/auto-generated routes, like `fromRouteName`).
- * - `actionId` / `actionUrl` / `actionResult` / `formData` are populated only
- *   when a server action triggered the render; `method` is "POST" then, "GET"
- *   otherwise. On no-JS (progressive-enhancement) action paths `actionId` may be
- *   undefined when React cannot surface the action's stable id: the success
- *   re-render still sets `actionUrl`/`formData` for a recognized action, but the
- *   error-boundary re-render exposes `actionUrl` only when `actionId` resolved.
- *   Malformed form bodies that fail before action detection expose no action
- *   fields. Treat `actionId` as "the action, if known", not as "was this an
- *   action".
- *
- * PREFETCH / CACHE CAVEAT (read this before gating on the source): the gate runs
- * server-side during resolution. A PREFETCHED navigation renders at prefetch
- * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
- * prefetch fired from, NOT necessarily the page the user actually navigates from
- * — the decision is baked into the stored Flight payload and replayed verbatim.
- * A non-PPR `cache()`/prerender hit replays the stored transition with the
- * predicate NOT re-run. A `ppr` route instead evaluates the predicate before
- * handlers on every match, including cache, prerender, and PPR replay. Prefetch
- * still freezes the server decision into its Flight payload. If the gate must
- * reflect the exact click-time source, source-scope the prefetch
- * (`<Link prefetchKey=":source">`).
+ * One side of a navigation as the browser knows it when a
+ * `transition({ when })` predicate runs.
+ */
+export interface RouteLocation {
+  readonly url: URL;
+  /** Merged route params of the location. */
+  readonly params: Readonly<Record<string, string>>;
+  /**
+   * The matched route's name (include prefixes applied), typed from the
+   * generated route map; undefined for an unnamed route or when unknown.
+   * Internal names never appear here.
+   */
+  readonly routeName: DefaultRouteName | undefined;
+  /**
+   * `history.state` of this entry at decision time. Read a typed slot with
+   * `Def.read(location)` (a `createLocationState()` definition).
+   */
+  readonly state: unknown;
+}
+
+/**
+ * A navigation side as the server sees it, for intercept's `when` selector:
+ * a {@link RouteLocation} without `state` (history state never reaches the
+ * server).
  */
-export type TransitionWhenContext<
-  TParams = Record<string, string>,
-  TEnv = unknown,
-> = Partial<
-  Pick<
-    RevalidateParams<TParams, TEnv>,
-    "currentUrl" | "currentParams" | "fromRouteName"
-  >
-> &
-  Pick<
-    RevalidateParams<TParams, TEnv>,
-    | "nextUrl"
-    | "nextParams"
-    | "toRouteName"
-    | "actionId"
-    | "actionUrl"
-    | "actionResult"
-    | "formData"
-    | "method"
-  > &
-  Pick<HandlerContext<any, TEnv>, "get" | "env">;
+export type ServerRouteLocation = Omit<RouteLocation, "state">;
 
 /**
- * Predicate that gates whether a transition() applies for the current request.
+ * How the navigation being decided was started.
  *
- * Evaluated server-side outside any cache scope. On ordinary routes it runs
- * AFTER the route's handler, so `get(...)` can read handler/middleware state. A
- * route with `ppr` automatically hoists it before route handlers and reevaluates
- * it on every cache/prerender/PPR replay; there `get(...)` can read middleware
- * state, but not values set by route handlers. Return false to drop this
- * segment's transition for the request; return true to apply it. The
- * context ({@link TransitionWhenContext}) carries the same navigation/action
- * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
- * error is reported to the router's onError (phase "rendering") and the
- * transition is dropped (the navigation does not hold).
+ * - `"push"` / `"replace"`: a Link click, `router.push()` / `router.replace()`
+ *   or `navigate()`.
+ * - `"pop"`: browser back/forward (restored from the history cache or
+ *   refetched).
+ * - `"action"`: the commit that applies a server action's revalidation,
+ *   including the error-boundary commit of a failed action.
+ * - `"revalidate"`: a re-render of the current URL: `router.refresh()`,
+ *   cross-tab invalidation, or the background revalidation of a stale entry.
+ */
+export type TransitionWhenKind =
+  | "push"
+  | "replace"
+  | "pop"
+  | "action"
+  | "revalidate";
+
+/**
+ * The context a `transition({ when })` predicate receives. The predicate runs
+ * in the BROWSER, once per navigation, at the first commit that presents the
+ * destination. The server never calls it.
  *
- * Distinct from intercept()'s `when` config selector, which runs at MATCH time
- * over `{ from, to, params, segments, … }`.
+ * - `from`: the committed location being left.
+ * - `to`: the destination. The same object as `from` for `"action"` and
+ *   `"revalidate"`.
+ * - `isAction`: the matcher `revalidate()` predicates get; `false` off an
+ *   action.
+ * - `action`: present only for `kind: "action"`.
+ */
+export interface TransitionWhenContext {
+  readonly kind: TransitionWhenKind;
+  readonly from: RouteLocation;
+  readonly to: RouteLocation;
+  readonly isAction: IsActionFn;
+  /** Present only for `kind: "action"`. */
+  readonly action?: {
+    /** The action's hashed `$$id` in the browser; match with `isAction(fn)` instead. */
+    readonly id: string | undefined;
+    /** The FormData argument the action received (the 2nd argument under `useActionState`). */
+    readonly formData: FormData | undefined;
+    /** The action's return value on success. */
+    readonly result: unknown;
+    /** What a failed action threw (its error-boundary commit); `result` is undefined then. */
+    readonly error: unknown;
+  };
+}
+
+/**
+ * Browser-run predicate that gates whether a navigation holds and animates.
  *
- * Scope: dropping a transition removes only THIS segment's contribution to the
- * navigation's hold. The startTransition hold is navigation-wide — it engages if
- * any matched segment still has a transition — so `when: false` makes the
- * navigation stream its loading fallback only when no other matched segment
- * keeps a transition (the common case: a single transition on the route).
+ * In `urls()` write it inline (`transition({ when: (ctx) => ... })`, which
+ * the build hoists into a client module; it may reference only its own
+ * bindings, globals and client-safe imports) or export it from a
+ * `"use client"` module and import it; in `clientUrls()` it is an inline
+ * function. Anything else (a server function, a non-function) fails route
+ * discovery.
  *
- * On non-PPR routes it runs only during fresh resolution. On PPR routes it runs
- * before handlers for every match, including runtime cache, build-time
- * prerender, and PPR segment replay. A prefetched navigation still freezes the
- * result to prefetch time; see {@link TransitionWhenContext}.
+ * `false` makes the navigation an urgent commit: no hold, no view transition,
+ * and a same-route navigation streams its `loading()` fallback. The segment
+ * keeps its key and its `<ViewTransition>` element (every class "none"), so
+ * nothing remounts. One predicate returning false decides for the whole
+ * navigation. A throw is logged with `console.error` and counts as `false`.
  */
 export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
 
@@ -132,13 +134,8 @@ export interface TransitionConfig {
    */
   viewTransition?: "auto" | false;
   /**
-   * Optional server-side predicate that gates this transition per request. When
-   * present and it returns false, the router drops this segment's transition for
-   * the request, so the navigation streams its loading fallback instead of
-   * holding. PPR routes evaluate it before route handlers and on every replay;
-   * other routes evaluate it after handlers on fresh resolution. The predicate
-   * is server-only and never serialized to the client; only its resolved effect
-   * crosses. See {@link TransitionWhenFn}.
+   * Optional browser-run predicate that gates this transition per
+   * navigation. See {@link TransitionWhenFn}.
    */
   when?: TransitionWhenFn;
 }
@@ -285,6 +282,12 @@ export interface MatchResult {
    * decline its optimistic presentation for targets an intercept would claim.
    */
   interceptTargets?: string[];
+  /**
+   * Set on a partial match when an intercept targets the matched route,
+   * whether or not it applied from this source. The response depends on the
+   * source, so the RSC handler scopes its prefetch entry to it (#1007).
+   */
+  interceptTargeted?: true;
   /**
    * Redirect URL for trailing slash normalization.
    * When set, the RSC handler should return a 308 redirect to this URL

package/src/urls/path-helper-types.ts

@@ -417,10 +417,9 @@ export type PathHelpers<TEnv> = {
    * transition cannot fire without a startTransition. See
    * skills/view-transitions for the startTransition x ViewTransition matrix.
    *
-   * Pass `when: (ctx) => boolean` to gate the transition per request. It normally
-   * runs after the route handler; `ppr` routes automatically run it before route
-   * handlers and on every replay, where `ctx.get(...)` sees middleware state but
-   * not handler-set values.
+   * Pass `when` (inline, hoisted into a client module by the build, or a
+   * "use client" export) to gate the navigation's hold and view transition in
+   * the browser (never on the server); see TransitionWhenFn.
    */
   transition: {
     (): TransitionItem;

package/src/urls/pattern-types.ts

@@ -65,10 +65,9 @@ export interface PartialPrerenderProps {
   tags?: string[];
   /**
    * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
-   * data snapshot: the loader records and the cache values loaders read,
-   * duplicated into the shell entry. The doc record (the handler layer every
-   * HIT replays) is exempt. Over the cap the pins are dropped: the shell is
-   * still stored and every HIT still replays the handler layer, but the
+   * data snapshot: the bake-lane loader records. The doc record (the handler
+   * layer every HIT replays) is exempt. Over the cap the pins are dropped: the
+   * shell is still stored and every HIT still replays the handler layer, but the
    * pinned loaders read the live store, so drifted cached content can
    * hydration-mismatch and be repaired client-side. Reported once per key.
    * Defaults to 8 MiB. The whole entry is bounded separately by the store's

package/src/vite/discovery/discover-routers.ts

@@ -211,6 +211,9 @@ export async function discoverRouters(
           routerId: id,
           ...(router.__basename ? { urlPrefix: router.__basename } : {}),
           ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+          // Discovery evaluates the tree in the react-server graph, where a
+          // "use client" import is a client reference: reject server `when`s.
+          validateTransitionWhen: true,
         }),
       );
       routerMountIndex++;

package/src/vite/discovery/shell-prerender-phase.ts

@@ -290,9 +290,7 @@ export async function runShellPrerenderPhase(
           const value: BuildShellEntry = {
             entry: res.entry,
             ttl: policy.ttl,
-            swr: policy.swr,
             tags: res.tags,
-            routeName: cand.routeName,
           };
           staged.push({
             key: buildShellManifestKey(cand.urlPath),

package/src/vite/discovery/virtual-module-codegen.ts

@@ -24,6 +24,14 @@ import type { DiscoveryState } from "./state.js";
  */
 const MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
 
+/**
+ * Strict transition({ when }) validation for the app's RSC realm: under the
+ * plugin a "use client" import is a client reference, so the render-time
+ * backstop (rsc/attach-transition-when.ts) can reject a server function. Off
+ * by default in the router, where unit-test projects cannot tell them apart.
+ */
+const TRANSITION_WHEN_VALIDATION = `enableTransitionWhenValidation();`;
+
 function devDiscoveryBootstrap(state: DiscoveryState): string[] {
   if (
     state.isBuildMode ||
@@ -80,6 +88,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     }
 
     const serverImports = [
+      "enableTransitionWhenValidation",
       "setCachedManifest",
       "setRouterManifest",
       ...(state.isBuildMode ? ["registerRouterManifestLoader"] : []),
@@ -97,6 +106,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       // because it's not in the HMR invalidation chain. Without this clear, the
       // handler finds stale trie data and never rebuilds from updated urlpatterns.
       `clearAllRouterData();`,
+      TRANSITION_WHEN_VALIDATION,
     ];
 
     if (hasClientUrlModules) {
@@ -182,12 +192,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     return lines.join("\n");
   }
 
-  const lines: string[] = [];
+  const lines: string[] = [
+    `import { ${hasClientUrlModules ? "clearClientUrlProjections, " : ""}enableTransitionWhenValidation } from "@rangojs/router/server";`,
+    TRANSITION_WHEN_VALIDATION,
+  ];
   if (hasClientUrlModules) {
-    lines.push(
-      `import { clearClientUrlProjections } from "@rangojs/router/server";`,
-      `clearClientUrlProjections();`,
-    );
+    lines.push(`clearClientUrlProjections();`);
   }
   if (!state.isBuildMode) {
     const origin =
@@ -201,7 +211,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     }
   }
   lines.push(...devDiscoveryBootstrap(state));
-  return lines.join("\n") || `// Route manifest will be populated at runtime`;
+  return lines.join("\n");
 }
 
 /**