@rangojs/router 0.17.0 → 0.19.0

package/dist/types/types/segments.d.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.
  * Can be a simple string or an object mapping transition types to class names
@@ -8,75 +9,88 @@ 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 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 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;
+}
 /**
- * Predicate that gates whether a transition() applies for the current request.
+ * 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 ServerRouteLocation = Omit<RouteLocation, "state">;
+/**
+ * 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;
 /**
@@ -108,13 +122,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;
 }
@@ -248,6 +257,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/dist/types/urls/path-helper-types.d.ts

@@ -194,10 +194,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/dist/types/urls/pattern-types.d.ts

@@ -53,30 +53,33 @@ export interface PartialPrerenderProps {
     /**
      * Operational tags attached to the captured shell entry for
      * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
-     * capture render auto-collects (the shell's own non-loader request tags).
+     * capture collects: its doc record's tags (what the handler layer and the
+     * server components it rendered recorded) and its bake-lane loaders'.
      */
     tags?: string[];
     /**
-     * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
-     * inside the shell entry. The snapshot duplicates every cache-store value
-     * the capture pinned, so a page over a large cache() segment can push the
-     * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
-     * Over the cap the snapshot is skipped: the shell is still stored and
-     * served, but pinned reads fall back to the live store, so drifted cached
-     * content can hydration-mismatch and be repaired client-side (the
-     * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+     * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
+     * 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
+     * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
      */
     maxSnapshotBytes?: number;
     /**
-     * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
-     * background capture: the wait for deferred shell material — top-level
-     * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
-     * are AWAITED and their settled values baked into the stored shell — AND
-     * the fizz prerender deadline. Declare it to tighten the budget below the
-     * default or when a route's shell material takes longer than 15s to
-     * settle. A budget that expires with pushes still pending REFUSES the
-     * capture (the route stays MISS with the once-per-key warning) — a shell
-     * with missing head material is never stored. Capture is background work
+     * Capture settle budget in MILLISECONDS (default 15000). One deadline for
+     * the whole background capture: the match (the handlers, and the loaders
+     * they await), the wait for handler output (handle pushes and the promises
+     * nested in them, bake-lane loaders, and the doc record's encode, which
+     * awaits handler promises and async server components), AND the fizz
+     * prerender. Everything a handler produces is
+     * awaited and baked into the stored shell. Declare it to tighten the
+     * budget below the default or when a route's shell material takes longer
+     * than 15s to settle. A budget that expires before the doc record is
+     * written REFUSES the capture (the route stays MISS with the once-per-key
+     * warning): a shell with missing handler output is never stored. Capture is background work
      * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
      * response; the platform waitUntil lifetime (workerd: ~30s past response
      * completion) is the physical ceiling — the default's derivation lives in

package/dist/types/vite/plugins/transition-when-hoist.d.ts

@@ -0,0 +1,45 @@
+import type { Plugin } from "vite";
+import MagicString from "magic-string";
+/** Specifiers that can never load in the browser. */
+export declare function isServerOnlySpecifier(source: string): boolean;
+export interface HoistTransitionWhenDeps {
+    /**
+     * Whether an import the literal re-emits is server-only beyond its
+     * specifier (the plugin resolves it and looks for `import "server-only"`).
+     */
+    isServerOnlyImport?(source: string): Promise<boolean> | boolean;
+}
+export interface HoistTransitionWhenResult {
+    readonly code: string;
+    readonly map: ReturnType<MagicString["generateMap"]>;
+    /** Virtual module source per hoisted literal, by index. */
+    readonly modules: readonly string[];
+}
+/**
+ * Hoist every inline `transition({ when: <function literal> })` of a urls
+ * module. Returns null when there is nothing to hoist. Throws a
+ * TransitionWhenError for a capture, a server-only import or module-loading
+ * expression, an accessor `when`, or a local identifier value.
+ */
+export declare function hoistTransitionWhens(code: string, id: string, deps?: HoistTransitionWhenDeps): Promise<HoistTransitionWhenResult | null>;
+/** The hoisted module index a `?rango-when=N` id names, or null. */
+export declare function parseHoistedWhenId(id: string): {
+    file: string;
+    index: number;
+} | null;
+/**
+ * The plugin: hoists in the RSC environment (where urls() modules are
+ * evaluated) and serves the `?rango-when=N` modules in every environment
+ * (RSC, SSR and client all load them).
+ *
+ * `load` serves the modules the transform emitted, not a re-hoist of the file
+ * on disk: the transform hoists the pipeline code, which an earlier plugin
+ * may have changed, so re-hoisting the disk source can number the literals
+ * differently and serve the wrong one for index N. The disk source is the
+ * fallback only when the transform has not seen the current file: an
+ * environment loading before the RSC transform ran (the order environments
+ * ask in is not fixed), or an edit the RSC environment has not re-transformed
+ * yet (serving the last transform would then be stale). The map is per
+ * plugin instance, so every environment of one dev server or build shares it.
+ */
+export declare function transitionWhenHoistPlugin(): Plugin;

package/dist/types/vite/router-discovery.d.ts

@@ -5,9 +5,36 @@
  * environment. Delegates to extracted modules for discovery, route types
  * generation, virtual module codegen, and bundle post-processing.
  */
-import type { Plugin } from "vite";
-import { VIRTUAL_ROUTES_MANIFEST_ID, type PluginOptions } from "./discovery/state.js";
+import type { Plugin, ViteDevServer } from "vite";
+import { VIRTUAL_ROUTES_MANIFEST_ID, type DiscoveryState, type PluginOptions } from "./discovery/state.js";
 export { VIRTUAL_ROUTES_MANIFEST_ID };
+/**
+ * Create a minimal Vite server for router discovery.
+ *
+ * Both dev-mode prerender and build-mode discovery need a temp RSC server
+ * to import user router files via module runner. This factory centralizes
+ * the shared config and the mode-specific differences:
+ * - Dev: path-based IDs (no forceBuild), separate cacheDir
+ * - Build: hashed IDs (forceBuild), hashClientRefs for production bundles
+ *
+ * Returns the ViteDevServer instance. Callers access .environments.rsc as needed.
+ * @internal Exported for tests.
+ */
+export declare function createTempRscServer(state: DiscoveryState, options?: {
+    forceBuild?: boolean;
+    cacheDir?: string;
+    /**
+     * Serve the REAL rango SSR entry (getVirtualEntrySSR) for
+     * "virtual:entry-ssr" instead of the discovery stub, so the dev
+     * /__rsc_shell endpoint can drive captureShellHTML in this server's SSR
+     * realm. Dev-correct by construction: the entry's bootstrap resolves to
+     * plugin-rsc's stable virtual browser-entry URL, which the MAIN dev
+     * server serves to the browser. Loaded lazily — discovery never imports
+     * the SSR entry, so the temp server stays as light as before until a
+     * shell capture actually runs.
+     */
+    realSsrEntry?: boolean;
+}): Promise<ViteDevServer>;
 /**
  * Plugin that discovers router instances at dev/build time via the RSC environment.
  *