@rangojs/router 0.17.0 → 0.19.0

package/src/transition-when-ref.ts

@@ -0,0 +1,220 @@
+/**
+ * transition({ when }) references: what a route definition may carry as a
+ * `when`, how definitions are validated, and how the browser turns the carried
+ * value back into a callable predicate.
+ *
+ * `when` is a BROWSER predicate. The server never calls it; it only carries it
+ * to the browser inside the segment's transition config, as one of:
+ *
+ * - a React client reference: a function exported from a `"use client"`
+ *   module and imported into a server `urls()` file, or an inline literal the
+ *   build hoisted into one (vite/plugins/transition-when-hoist.ts). Flight
+ *   serializes it as a module reference and the browser resolves it to the
+ *   real function;
+ * - a clientUrls() when reference, synthesized by the projection materializer
+ *   (client-urls/server-projection.ts): the group's definition client
+ *   reference plus the route id. The browser resolves it to the `when` the
+ *   route declared in its `"use client"` module.
+ *
+ * A plain function (a server function) cannot cross Flight, and a
+ * non-function is never callable. Both are LOUD errors: route discovery
+ * (generateManifestFull `validateTransitionWhen`) fails dev startup, the
+ * build and HMR re-discovery, and attachTransitionWhen (rsc/) throws the same
+ * error at render time for a route discovery did not see.
+ *
+ * Telling a client reference apart from a server function needs the
+ * react-server module graph, where a `"use client"` import IS a client
+ * reference. Outside it (a node/DOM unit-test project that aliases the router
+ * entry) the import is the plain function, so strict validation is enabled
+ * only by the Vite plugin: discovery passes the option, and the generated
+ * routes-manifest module calls enableTransitionWhenValidation() in the app's
+ * RSC realm (vite/discovery/virtual-module-codegen.ts).
+ */
+
+import { isAutoGeneratedRouteName } from "./route-name.js";
+import type { TransitionWhenFn } from "./types/segments.js";
+
+const CLIENT_REFERENCE = Symbol.for("react.client.reference");
+
+/** String key, so the marker survives Flight (symbol keys are not serialized). */
+const CLIENT_URLS_WHEN_KEY = "__rangoClientUrlsWhen";
+
+interface ClientUrlsWhenRef {
+  readonly __rangoClientUrlsWhen: 1;
+  /** The clientUrls() definition: a client reference on the server, the definition object in the browser. */
+  readonly definition: unknown;
+  readonly routeId: string;
+}
+
+export function isClientReference(value: unknown): boolean {
+  if (typeof value !== "function" && (typeof value !== "object" || !value)) {
+    return false;
+  }
+  return (value as { $$typeof?: unknown }).$$typeof === CLIENT_REFERENCE;
+}
+
+function isClientUrlsWhenRef(value: unknown): value is ClientUrlsWhenRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[CLIENT_URLS_WHEN_KEY] === 1
+  );
+}
+
+export function createClientUrlsWhenRef(
+  definition: unknown,
+  routeId: string,
+): TransitionWhenFn {
+  const ref: ClientUrlsWhenRef = {
+    __rangoClientUrlsWhen: 1,
+    definition,
+    routeId,
+  };
+  return ref as unknown as TransitionWhenFn;
+}
+
+let strictValidation = false;
+
+/**
+ * Turn on server-function rejection for this realm. Called by the Vite
+ * plugin's generated routes-manifest module, never by tests: see the module
+ * comment for why it cannot be on by default.
+ */
+export function enableTransitionWhenValidation(): void {
+  strictValidation = true;
+}
+
+export function isTransitionWhenValidationEnabled(): boolean {
+  return strictValidation;
+}
+
+/** @internal Reset for unit tests. */
+export function resetTransitionWhenValidation(): void {
+  strictValidation = false;
+}
+
+/** Thrown for an invalid transition({ when }); recognized by the dev HMR overlay. */
+export class TransitionWhenError extends Error {
+  override readonly name: string = "TransitionWhenError";
+}
+
+/**
+ * The TransitionWhenError in an error's cause chain, matched by name: discovery
+ * throws it from the module runner's copy of this module (another class
+ * object), and include resolution wraps it (build/generate-manifest.ts).
+ */
+export function findTransitionWhenError(error: unknown): Error | undefined {
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (
+    typeof current === "object" &&
+    current !== null &&
+    !seen.has(current)
+  ) {
+    seen.add(current);
+    if ((current as Error).name === "TransitionWhenError") {
+      return current as Error;
+    }
+    current = (current as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+/** Where an invalid `when` was declared, for the error message. */
+export interface TransitionWhenSite {
+  /** The route the entry belongs to (the matched or enumerated route). */
+  readonly routeName?: string;
+  readonly pattern?: string;
+  /** The declaring entry's type when it is not the route itself. */
+  readonly entryType?: string;
+}
+
+function describeSite(site: TransitionWhenSite): string {
+  const named =
+    site.routeName && !isAutoGeneratedRouteName(site.routeName)
+      ? `route "${site.routeName}"${site.pattern ? ` (${site.pattern})` : ""}`
+      : site.pattern
+        ? `route ${site.pattern}`
+        : "a route";
+  if (!site.entryType || site.entryType === "route") return named;
+  return `a ${site.entryType} of ${named}`;
+}
+
+function describeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}
+
+/**
+ * The problem with a `when` value, or null when it is valid. Non-functions
+ * are always invalid; a plain function is invalid only under strict
+ * validation (see the module comment).
+ */
+export function transitionWhenProblem(
+  when: unknown,
+  strict: boolean,
+): "not-a-function" | "server-function" | null {
+  if (when === undefined || isClientUrlsWhenRef(when)) return null;
+  if (typeof when !== "function") return "not-a-function";
+  if (strict && !isClientReference(when)) return "server-function";
+  return null;
+}
+
+export function createTransitionWhenError(
+  when: unknown,
+  problem: "not-a-function" | "server-function",
+  site: TransitionWhenSite,
+): TransitionWhenError {
+  const where = `transition({ when }) on ${describeSite(site)}`;
+  const head =
+    problem === "not-a-function"
+      ? `${where} must be a function, got ${describeValue(when)}.`
+      : `${where} is not a client function.`;
+  return new TransitionWhenError(
+    `[rango] ${head} ` +
+      "`when` runs in the browser: write it inline in the transition() call " +
+      "(transition({ when: (ctx) => ... }), where transition is the urls() helper " +
+      'or imported from "@rangojs/router"; the build hoists that literal into a ' +
+      'client module) or export it from a "use client" module and import it ' +
+      "into your urls() file. It receives { kind, from, to, isAction, action }: " +
+      "URLs, params, route names, history state and action data; get(), env " +
+      'and handler state do not exist there. See skills/view-transitions "Conditional transitions".',
+  );
+}
+
+/**
+ * Definition-time shape check (the DSL's transition()). Runs in every
+ * environment, so it rejects only what is invalid everywhere: a non-function.
+ */
+export function assertTransitionWhenShape(when: unknown): void {
+  if (transitionWhenProblem(when, false) === "not-a-function") {
+    throw new TypeError(
+      createTransitionWhenError(when, "not-a-function", {}).message,
+    );
+  }
+}
+
+/**
+ * Browser: turn a transition config's `when` into the predicate to call.
+ * Undefined when there is none (or a clientUrls route no longer declares it).
+ */
+export function resolveTransitionWhen(
+  when: unknown,
+): TransitionWhenFn | undefined {
+  if (typeof when === "function") return when as TransitionWhenFn;
+  if (!isClientUrlsWhenRef(when)) return undefined;
+  const definition = when.definition as
+    | {
+        routes?: ReadonlyArray<{
+          id: string;
+          transition?: { when?: unknown };
+        }>;
+      }
+    | undefined;
+  const record = definition?.routes?.find(
+    (candidate) => candidate.id === when.routeId,
+  );
+  const fn = record?.transition?.when;
+  return typeof fn === "function" ? (fn as TransitionWhenFn) : undefined;
+}

package/src/types/cache-types.ts

@@ -72,7 +72,13 @@ export interface CacheOptions<TEnv = unknown> {
   /**
    * Override the cache store for this boundary.
    * When specified, this boundary and its children use this store
-   * instead of the app-level store from handler config.
+   * instead of the app-level store from handler config. The records of a
+   * boundary with a store here are partitioned by the `keyGenerator` of each
+   * enclosing cache() without a `key` whose store differs, the app-level
+   * store included: under `cache(() => [...])` on an app store with a
+   * `keyGenerator`, `cache({ store })` records are split by its result too.
+   * Likewise, without a `key` of its own, this store's `keyGenerator`
+   * partitions a nested cache() on another store.
    *
    * Useful for:
    * - Different backends per route section (memory vs KV vs Redis)
@@ -108,6 +114,8 @@ export interface CacheOptions<TEnv = unknown> {
   /**
    * Conditional cache read function.
    * Return false to skip cache for this request (always fetch fresh).
+   * It gates every cache() nested under this one too: a nested boundary
+   * caches only when every enclosing condition allows it.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
    * Runs after global and route middleware on RSC routes; on response routes,
@@ -130,7 +138,10 @@ export interface CacheOptions<TEnv = unknown> {
 
   /**
    * Custom cache key function - FULL OVERRIDE.
-   * Bypasses default key generation AND store's keyGenerator.
+   * Bypasses default key generation AND store's keyGenerator. The result is
+   * stored namespaced (`key:` plus its URI encoding), so no value it returns
+   * names another route's record; a nested cache() keys its records within
+   * this partition.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
    * Runs after global and route middleware on RSC routes; on response routes,
@@ -154,7 +165,8 @@ export interface CacheOptions<TEnv = unknown> {
 
   /**
    * Tags for cache invalidation.
-   * Can be a static array or a function that returns tags.
+   * Can be a static array or a function that returns tags. They tag the
+   * records of every cache() nested under this one too.
    *
    * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
    * `VercelCacheStore` index by tag.

package/src/types/handler-context.ts

@@ -342,6 +342,12 @@ export type HandlerContext<
    * Current theme (from cookie or default).
    * Only available when theme is enabled in router config.
    *
+   * The visitor's cookie, so it is guarded like `cookies()`: reading it on a
+   * `ppr` route refuses the shell capture, and inside a `cache()` boundary or
+   * a `"use cache"` function it throws (#971). Read it with `useTheme()` in a
+   * client component, or in a live loader, on those routes. A read-only,
+   * non-enumerable getter: `{ ...ctx }` does not carry it.
+   *
    * @example
    * ```typescript
    * route("settings", (ctx) => {
@@ -350,7 +356,7 @@ export type HandlerContext<
    * });
    * ```
    */
-  theme?: Theme;
+  readonly theme?: Theme;
   /**
    * Set the theme (only available when theme is enabled in router config).
    * Sets a cookie with the new theme value.
@@ -469,6 +475,13 @@ export type InternalHandlerContext<
    * from the page. See setupLoaderAccess.
    */
   _runLoaderIsolated?: (loader: any) => Promise<any>;
+  /**
+   * @internal A loader's cache() binding started with these cache() tags: an
+   * execution of that loader outside the binding (a reader started it first,
+   * or a stale refresh runs it) answers for them too (#964). See
+   * setupLoaderAccess.
+   */
+  _bindLoaderCacheTags?: (loaderId: string, tags: Set<string>) => void;
 };
 
 /**

package/src/types/index.ts

@@ -51,6 +51,9 @@ export type {
   TransitionConfig,
   TransitionWhenFn,
   TransitionWhenContext,
+  TransitionWhenKind,
+  RouteLocation,
+  ServerRouteLocation,
   ResolvedSegment,
   SegmentMetadata,
   SlotState,

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

@@ -59,30 +59,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/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

@@ -64,6 +64,14 @@ export async function runShellPrerenderPhase(
   const startTotal = performance.now();
   console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
 
+  // Hold the process open for the phase. The capture's waits are unref'd
+  // timers (retry delay, Flight quiesce hops) so a runtime capture never keeps
+  // Node alive; every bundle is already written and the build temp server has
+  // no file watcher (#947). Its only remaining handle is the HMR WebSocket on
+  // 24678, which fails to bind silently when another Vite server holds the
+  // port; `vite build` then exited 0 mid-phase without writing
+  // __shell-manifest.js.
+  const keepAlive = setInterval(() => {}, 60_000);
   let restoreClientRequire: (() => void) | undefined;
   try {
     // Runner access needs the RunnableDevEnvironment surface; the environments
@@ -282,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),
@@ -343,6 +349,7 @@ export async function runShellPrerenderPhase(
     // buildApp post hook's finally on success, buildEnd on an aborted build.
     delete (globalThis as any).__loadPrerenderManifestModule;
     restoreClientRequire?.();
+    clearInterval(keepAlive);
   }
 }