@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/testing/generated-routes.ts

@@ -29,6 +29,10 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
  */
 interface RouterWithRouteMap {
   routeMap: Record<string, unknown>;
+  // findMatch is async (it may await an async include provider's import before
+  // the route's names are spliced into routeMap), so expandLazyIncludes awaits
+  // it. Typed `unknown` (not `unknown | Promise<unknown>`, which collapses to
+  // the same thing) — the awaited value is never read, only its side effect.
   findMatch?: (pathname: string) => unknown;
 }
 
@@ -42,16 +46,28 @@ function concretePath(pattern: string): string {
   );
 }
 
-function expandLazyIncludes(
+async function expandLazyIncludes(
   router: RouterWithRouteMap,
   patterns: Iterable<string>,
-): void {
+): Promise<void> {
   const findMatch = router.findMatch;
   if (typeof findMatch !== "function") return;
   for (const pattern of patterns) {
     try {
-      findMatch.call(router, concretePath(pattern));
-    } catch {}
+      // Await: an async include(`() => import()`) resolves its module + splices
+      // its routes into routeMap only after findMatch's Promise settles. Without
+      // the await, the routeMap read below races the import and reports the
+      // split-group routes as missing.
+      await findMatch.call(router, concretePath(pattern));
+    } catch (e) {
+      // A findMatch throw here is almost always a failing async include()
+      // provider (its `() => import()` rejected). Surface it — swallowed, it
+      // resurfaces downstream as a misleading "missing route" in the diff.
+      console.warn(
+        `[@rangojs/router] assertGeneratedRoutesMatch: could not expand include ` +
+          `for "${pattern}": ${(e as Error)?.message ?? String(e)}`,
+      );
+    }
   }
 }
 
@@ -91,13 +107,13 @@ function patternOf(value: unknown): string {
   return String(value);
 }
 
-export function diffGeneratedRoutes(
+export async function diffGeneratedRoutes(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
-): GeneratedRoutesDiff {
+): Promise<GeneratedRoutesDiff> {
   const generated = generatedMap ?? getGlobalRouteMap();
 
-  expandLazyIncludes(
+  await expandLazyIncludes(
     router,
     Object.values(generated).map((v) => patternOf(v)),
   );
@@ -145,14 +161,14 @@ export function diffGeneratedRoutes(
  * import generated from "./router.named-routes.gen";
  * import { router } from "./router";
  *
- * assertGeneratedRoutesMatch(router, generated);
+ * await assertGeneratedRoutesMatch(router, generated);
  * ```
  */
-export function assertGeneratedRoutesMatch(
+export async function assertGeneratedRoutesMatch(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
-): void {
-  const diff = diffGeneratedRoutes(router, generatedMap);
+): Promise<void> {
+  const diff = await diffGeneratedRoutes(router, generatedMap);
   if (diff.ok) return;
 
   const lines: string[] = [

package/src/testing/index.ts

@@ -47,6 +47,12 @@ export type {
   TestLoaderContext,
 } from "./run-loader.js";
 
+export { runTransitionWhen } from "./run-transition-when.js";
+export type {
+  RunTransitionWhenOptions,
+  RunTransitionWhenResult,
+} from "./run-transition-when.js";
+
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
 

package/src/testing/render-handler.ts

@@ -116,6 +116,15 @@ export interface RenderHandlerOptions<TEnv = any> {
    * `"use cache: profileName"` resolution once a `cacheStore` is wired.
    */
   cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Render as if inside a server action's revalidation render (production sets
+   * this in revalidateAfterAction). A stale `"use cache"` entry whose profile
+   * opts into `foregroundOnAction` then re-executes in the FOREGROUND (fresh
+   * result in this render) instead of being served stale + revalidated in the
+   * background. Without it, a stale entry keeps SWR. Pair with `cacheStore` +
+   * `cacheProfiles` to exercise the `foregroundOnAction` opt-in.
+   */
+  inActionRevalidation?: boolean;
   /**
    * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
    * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert,
@@ -238,6 +247,11 @@ export async function renderHandler<TEnv = any>(
       opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
   });
 
+  // Simulate an action revalidation render (production sets this in
+  // revalidateAfterAction) so a `foregroundOnAction` cache profile foregrounds a
+  // stale entry. See the foregroundOnAction option doc.
+  if (opts.inActionRevalidation) reqCtx._inActionRevalidation = true;
+
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
   const handlePushes = new Map<Handle<any, any>, unknown[]>();
 

package/src/testing/render-route.tsx

@@ -46,11 +46,15 @@ import {
   generateHistoryKey,
 } from "../browser/navigation-store.js";
 import { createEventController } from "../browser/event-controller.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import type { NavigationStore, NavigationBridge } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
 import { NavigationProvider } from "../browser/react/NavigationProvider.js";
-import { compilePattern } from "../router/pattern-matching.js";
+import {
+  compilePattern,
+  buildParamsFromMatch,
+} from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
 import type { LoaderDefinition } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
@@ -302,14 +306,9 @@ function matchLeaf(
   const compiled = compilePattern(pattern);
   const match = compiled.regex.exec(pathname);
   if (!match) return null;
-  const params: Record<string, string> = {};
-  compiled.paramNames.forEach((name, index) => {
-    const value = match[index + 1];
-    if (value !== undefined) {
-      params[name] = decodeURIComponent(value);
-    }
-  });
-  return params;
+  // Reuse the production param builder so the harness matches the real matcher
+  // exactly (named catch-all "" binding, decoding) instead of forking it.
+  return buildParamsFromMatch(match, compiled.paramNames, compiled.catchAll);
 }
 
 function staticPrefix(pattern: string): string {
@@ -481,8 +480,12 @@ export async function renderRoute(
 
   const eventController = createEventController({ initialLocation: url });
   eventController.setParams(initialMatch.params);
+  // Resolve-by-default: resolve any deferred (Promise) seeded handle values
+  // before applying, so the seeded handles reach collect/useHandle resolved —
+  // matching what the server/client do in a real app.
+  const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
   eventController.setHandleData(
-    handleSeed,
+    resolvedSeed,
     initialSegments.map((s) => s.id),
   );
 

package/src/testing/run-transition-when.ts

@@ -0,0 +1,164 @@
+/**
+ * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ *
+ * Runs the SAME two server functions the router uses — applyViewTransitionDefault
+ * (strips the `when` function from the serialized config and records the
+ * predicate on the request context) and gateTransitions (assembles the
+ * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * predicate sees exactly the navigation/action metadata it would at runtime
+ * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
+ * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
+ * whether the transition would apply this request. The result also exposes the
+ * assembled `whenContext` so tests can assert the exact fields without reaching
+ * into private request-context state.
+ *
+ * This is the public way to exercise a transition gate: the full
+ * match -> render pipeline that wires these together only runs under real RSC
+ * rendering (which the Flight primitives do not drive), so without this primitive
+ * a consumer could not test their predicate through @rangojs/router/testing.
+ *
+ * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
+ */
+
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { applyViewTransitionDefault } from "../router/segment-resolution/view-transition-default.js";
+import { gateTransitions } from "../rsc/transition-gate.js";
+import { createTestRequestContext, type VarsInit } from "./internal/context.js";
+import type {
+  ResolvedSegment,
+  TransitionConfig,
+  TransitionWhenContext,
+} from "../types/segments.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+const toURL = (v: string | URL, base: URL): URL =>
+  typeof v === "string" ? new URL(v, base.origin) : v;
+
+/**
+ * Options for runTransitionWhen. All navigation/action fields are optional and
+ * default to "absent", matching what the gate sees for an initial full load with
+ * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
+ * navigation source being unavailable, and omit the `action*` fields to model a
+ * plain (non-action) navigation.
+ */
+export interface RunTransitionWhenOptions<TEnv = any> {
+  /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
+  request?: Request | string;
+  /** Route params for the target (`nextParams`). */
+  params?: Record<string, string>;
+  /** Target route name (`toRouteName`). */
+  toRouteName?: string;
+  /** Environment bindings surfaced as `env` (and `ctx.env`). */
+  env?: TEnv;
+  /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+  vars?: VarsInit;
+  /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
+  currentUrl?: string | URL;
+  /** Source route params (`currentParams`). */
+  currentParams?: Record<string, string>;
+  /** Source route name (`fromRouteName`). */
+  fromRouteName?: string;
+  /** Id of the action that triggered a revalidation (`actionId`). */
+  actionId?: string;
+  /** Url the action was submitted from (`actionUrl`). */
+  actionUrl?: string | URL;
+  /** The action's return value (`actionResult`). */
+  actionResult?: unknown;
+  /** FormData from a form action (`formData`). */
+  formData?: FormData;
+  /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
+  onError?: OnErrorCallback;
+}
+
+/**
+ * Result of runTransitionWhen.
+ */
+export interface RunTransitionWhenResult<TEnv = any> {
+  /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
+  kept: boolean;
+  /** Convenience inverse of `kept`. */
+  dropped: boolean;
+  /**
+   * The production-assembled predicate context. Undefined when the config has
+   * no `when` predicate.
+   */
+  whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
+  /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
+  ctx: RequestContext<TEnv>;
+}
+
+export function runTransitionWhen<TEnv = any>(
+  config: TransitionConfig,
+  opts: RunTransitionWhenOptions<TEnv> = {},
+): RunTransitionWhenResult<TEnv> {
+  const { ctx } = createTestRequestContext<TEnv>({
+    env: opts.env,
+    request: opts.request,
+    vars: opts.vars,
+    params: opts.params,
+  });
+  const reqCtx = ctx as unknown as RequestContext<TEnv>;
+
+  // Target route name (the public field the gate reads for `toRouteName`).
+  if (opts.toRouteName !== undefined)
+    reqCtx.routeName = opts.toRouteName as RequestContext<TEnv>["routeName"];
+  // Source (match-time) data the gate reads for currentUrl/currentParams/fromRouteName.
+  if (opts.currentUrl !== undefined)
+    reqCtx._gateCurrentUrl = toURL(opts.currentUrl, reqCtx.url);
+  if (opts.currentParams !== undefined)
+    reqCtx._gateCurrentParams = opts.currentParams;
+  if (opts.fromRouteName !== undefined)
+    reqCtx._prevRouteKey = opts.fromRouteName;
+  // Action data the gate reads at the action-bearing call sites.
+  if (opts.actionId !== undefined) reqCtx._gateActionId = opts.actionId;
+  if (opts.actionUrl !== undefined)
+    reqCtx._gateActionUrl = toURL(opts.actionUrl, reqCtx.url);
+  if (opts.actionResult !== undefined)
+    reqCtx._gateActionResult = opts.actionResult;
+  if (opts.formData !== undefined) reqCtx._gateFormData = opts.formData;
+
+  let whenContext:
+    | TransitionWhenContext<Record<string, string>, TEnv>
+    | undefined;
+  const when = config.when;
+  const configForGate: TransitionConfig = when
+    ? {
+        ...config,
+        when: (c) => {
+          whenContext = c as TransitionWhenContext<
+            Record<string, string>,
+            TEnv
+          >;
+          return when(c);
+        },
+      }
+    : config;
+
+  return runWithRequestContext(reqCtx, () => {
+    // The real resolution-time collection + post-handler gate, so the predicate
+    // sees the production-assembled TransitionWhenContext.
+    const serialized = applyViewTransitionDefault(
+      configForGate,
+      undefined,
+      "tx-when-seg",
+    );
+    const segment = {
+      id: "tx-when-seg",
+      namespace: "r",
+      type: "route",
+      index: 0,
+      component: null,
+      transition: serialized,
+    } as ResolvedSegment;
+    gateTransitions(
+      [segment],
+      reqCtx as Parameters<typeof gateTransitions>[1],
+      opts.onError,
+    );
+    const kept = segment.transition !== undefined;
+    return { kept, dropped: !kept, whenContext, ctx: reqCtx };
+  });
+}

package/src/theme/ThemeProvider.tsx

@@ -109,27 +109,6 @@ function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   }
 }
 
-function getStoredTheme(config: ResolvedThemeConfig): Theme {
-  const { storageKey, themes, defaultTheme, enableSystem } = config;
-
-  let stored = readThemeFromCookie(storageKey);
-
-  if (!stored) {
-    stored = readThemeFromStorage(storageKey);
-  }
-
-  if (stored) {
-    if (stored === "system" && enableSystem) {
-      return "system";
-    }
-    if (themes.includes(stored)) {
-      return stored as Theme;
-    }
-  }
-
-  return defaultTheme;
-}
-
 export function ThemeProvider({
   config,
   initialTheme,
@@ -137,17 +116,48 @@ export function ThemeProvider({
 }: ThemeProviderProps): React.ReactNode {
   const [mounted, setMounted] = useState(false);
 
-  const [theme, setThemeState] = useState<Theme>(() => {
-    if (initialTheme) return initialTheme;
-    if (typeof window === "undefined") return config.defaultTheme;
-    return getStoredTheme(config);
-  });
+  // HYDRATION PARITY: this initializer is the server (SSR/resume) render AND
+  // the client's hydration render — both must produce the same value. It must
+  // NEVER read cookie/localStorage: whenever the payload's initialTheme
+  // differs from the visitor's stored theme (a PPR shell HIT deliberately
+  // replays the CAPTURE's initialTheme), a storage-reading initializer makes
+  // the client's first render diverge from the server tree. Any raw-theme text
+  // (a toggle label) then fails hydration, React regenerates the tree, and the
+  // FOUC-applied class is wiped from <html>. The visitor's stored theme is
+  // applied by the post-mount re-sync effect below instead.
+  const [theme, setThemeState] = useState<Theme>(
+    () => initialTheme ?? config.defaultTheme,
+  );
 
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
   useEffect(() => {
     setMounted(true);
     setSystemTheme(getSystemTheme());
+    // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
+    // comes from the payload and can legitimately differ from the visitor's
+    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's theme
+    // (the resume tree must match the frozen prelude; see
+    // ShellCacheEntry.initialTheme). The FOUC script already applied the stored
+    // theme to the document pre-paint; this brings the provider state (toggles,
+    // useTheme readers) in line with it, and is the ONLY place the provider
+    // reads storage (the initializer must not — see the parity note above).
+    // Only an explicit cookie/localStorage value re-syncs — a defaultTheme
+    // fallback must not override a server-provided initialTheme when the
+    // visitor never chose a theme.
+    // First VALID candidate wins — an empty/garbage cookie value (e.g. a
+    // deleted cookie leaving "theme=") must not shadow a valid localStorage
+    // value behind a bare null-coalesce.
+    const explicit =
+      [
+        readThemeFromCookie(config.storageKey),
+        readThemeFromStorage(config.storageKey),
+      ].find((v) => v !== null && isValidTheme(v, config)) ?? null;
+    if (explicit !== null && explicit !== theme) {
+      setThemeState(explicit as Theme);
+      applyThemeToDocument(explicit as Theme, config);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   const setTheme = useCallback(

package/src/types/handler-context.ts

@@ -504,7 +504,7 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.context - App context (db, user, etc.)
  * @param args.actionResult - Result from action (future support)
  * @param args.formData - Form data from action (future support)
- * @param args.formMethod - HTTP method from action (future support)
+ * @param args.method - HTTP method: "GET" for navigation, "POST" for server actions
  *
  * @returns Hard decision (boolean), soft suggestion (object), or defer
  *   (`void` / `null` / `undefined`) to keep the running suggestion as-is.

package/src/types/index.ts

@@ -48,6 +48,8 @@ export type {
 export type {
   ViewTransitionClass,
   TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
   ResolvedSegment,
   SegmentMetadata,
   SlotState,

package/src/types/route-config.ts

@@ -10,20 +10,29 @@ export type DocumentProps = {
 type ParseConstraint<T extends string> =
   T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
 
+// Named catch-all (`:name*` / `:name+`) is matched BEFORE the `?`/suffix
+// branches. Its modifier is anchored to the END of the token (no trailing
+// `${string}`) so it is a true suffix and never mis-splits a constraint body
+// such as `id(\d+)`. Both are a required `string`: a matched catch-all always
+// binds a value (possibly ""), so the key is always present.
 type ExtractParamInfo<T extends string> =
   T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
     : T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : T extends `${infer Name}?${string}`
-        ? { name: Name; optional: true; type: string }
-        : T extends `${infer Name}.${string}`
+      : T extends `${infer Name}*`
+        ? { name: Name; optional: false; type: string }
+        : T extends `${infer Name}+`
           ? { name: Name; optional: false; type: string }
-          : T extends `${infer Name}-${string}`
-            ? { name: Name; optional: false; type: string }
-            : T extends `${infer Name}~${string}`
+          : T extends `${infer Name}?${string}`
+            ? { name: Name; optional: true; type: string }
+            : T extends `${infer Name}.${string}`
               ? { name: Name; optional: false; type: string }
-              : { name: T; optional: false; type: string };
+              : T extends `${infer Name}-${string}`
+                ? { name: Name; optional: false; type: string }
+                : T extends `${infer Name}~${string}`
+                  ? { name: Name; optional: false; type: string }
+                  : { name: T; optional: false; type: string };
 
 type ParamFromInfo<Info> = Info extends {
   name: infer N extends string;
@@ -51,12 +60,15 @@ type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
  * - Optional params: /:locale? -> { locale?: string }
  * - Constrained params: /:locale(en|gb) -> { locale: "en" | "gb" }
  * - Optional + constrained: /:locale(en|gb)? -> { locale?: "en" | "gb" }
+ * - Named catch-all: /:path+ (one-or-more), /:slug* (zero-or-more) -> string
  *
  * @example
  * ExtractParams<"/products/:id"> // { id: string }
  * ExtractParams<"/:locale?/blog/:slug"> // { locale?: string; slug: string }
  * ExtractParams<"/:locale(en|gb)/blog"> // { locale: "en" | "gb" }
  * ExtractParams<"/:locale(en|gb)?/blog/:slug"> // { locale?: "en" | "gb"; slug: string }
+ * ExtractParams<"/docs/:slug*"> // { slug: string }
+ * ExtractParams<"/shop/:path+"> // { path: string }
  */
 export type ExtractParams<
   T extends string,

package/src/types/segments.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
+import type { RevalidateParams, HandlerContext } from "./handler-context.js";
 
 /**
  * CSS class(es) for a ViewTransition phase.
@@ -8,6 +9,96 @@ import type { ErrorInfo, NotFoundInfo } from "./boundaries.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 post-handler 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. `get` is the way to read what the handler/middleware set
+ * via `ctx.set(...)` this request.
+ *
+ * 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 `cache()`/prerender hit replays the stored transition with the predicate NOT
+ * re-run at all. So a source-sensitive predicate can be frozen to prefetch-time
+ * or store-time state. This is accepted (~99% of navigations match), but if your
+ * gate must reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`) and do not `cache()` that segment.
+ */
+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">;
+
+/**
+ * Predicate that gates whether a transition() applies for the current request.
+ *
+ * Evaluated server-side AFTER the route's handler runs (so `get(...)` can read
+ * handler/middleware-set state) and outside any cache scope. 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).
+ *
+ * Distinct from intercept()'s `when` config selector, which runs at MATCH time
+ * over `{ from, to, params, segments, … }`; a transition `when` runs
+ * post-handler over the resolved payload.
+ *
+ * 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).
+ *
+ * Evaluated on every fresh (cache-miss) resolution; it is NOT re-run when a
+ * segment is replayed from the runtime cache or a build-time prerender, and a
+ * prefetched navigation freezes it to prefetch-time state — see the caveat on
+ * {@link TransitionWhenContext}.
+ */
+export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
+
 /**
  * Configuration for React's <ViewTransition> component.
  *
@@ -36,6 +127,15 @@ export interface TransitionConfig {
    * When unset, inherits the createRouter({ viewTransition }) default.
    */
   viewTransition?: "auto" | false;
+  /**
+   * Optional server-side predicate that gates this transition per request. When
+   * present and it returns false (evaluated post-handler), the router drops this
+   * segment's transition for the request, so the navigation streams its loading
+   * fallback instead of holding. The predicate is server-only and never
+   * serialized to the client; only its resolved effect (transition kept or
+   * dropped) crosses. See {@link TransitionWhenFn}.
+   */
+  when?: TransitionWhenFn;
 }
 
 /**

package/src/urls/include-helper.ts

@@ -9,6 +9,7 @@ import {
   validateUserRouteName,
 } from "../route-name.js";
 import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
+import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
 
 function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
@@ -60,7 +61,11 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
 export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   return (
     prefix: string,
-    patterns: UrlPatterns<TEnv>,
+    // A `urls()` value (eager) OR an async provider thunk
+    // (`() => import("./routes")`) whose evaluation is deferred to the first
+    // request matching `prefix`. The provider is stored unevaluated and
+    // resolved by the runtime lazy-include expansion / build-time discovery.
+    patterns: UrlPatterns<TEnv> | IncludeProvider<TEnv>,
     options?: IncludeOptions,
   ): IncludeItem => {
     const { ctx } = requireDslContext("include() must be called inside urls()");
@@ -81,10 +86,9 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
         ? capturedUrlPrefix + prefix.slice(1)
         : capturedUrlPrefix + prefix
       : prefix;
-    const internalScope = !hasExplicitName
-      ? allocateInternalIncludeScopeId(ctx.counters)
-      : undefined;
-    const nextSegment = hasExplicitName ? explicitName : internalScope;
+    const nextSegment = hasExplicitName
+      ? explicitName
+      : allocateInternalIncludeScopeId(ctx.counters);
     const fullNamePrefix =
       nextSegment !== undefined && nextSegment !== ""
         ? capturedNamePrefix
@@ -117,9 +121,7 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
     if (capturedParent?.shortCode) {
       const includeCounterKey = `${capturedParent.shortCode}${parentScope}_include`;
       ctx.counters[includeCounterKey] ??= 0;
-      const includeIdx = ctx.counters[includeCounterKey];
-      ctx.counters[includeCounterKey] = includeIdx + 1;
-      includeScope = `${parentScope}I${includeIdx}`;
+      includeScope = `${parentScope}I${ctx.counters[includeCounterKey]++}`;
     }
 
     // Snapshot parent's counters AFTER allocating the include scope so lazy