@rangojs/router 0.24.4 → 0.25.0

package/dist/types/browser/partial-update.d.ts

@@ -1,10 +1,12 @@
 import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegment } from "./types.js";
 import type { ReactNode } from "react";
+export declare const addTransitionType: ((type: string) => void) | undefined;
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
-import type { HandleData, NavigationUpdate, RscMetadata } from "./types.js";
+import type { HandleData, NavigationUpdate, RscMetadata, ShownEntry } from "./types.js";
 import type { LoaderStore } from "../loader-store.js";
 import { type TransitionWhenActionInput } from "./transition-when.js";
+import { type TransitionWhenKind } from "../types/segments.js";
 /**
  * Hold/animate decision for a commit: a non-intercept segment carries a
  * transition, no intercept is presented, and this navigation's
@@ -18,8 +20,10 @@ export declare function shouldStartViewTransition(segments: readonly ResolvedSeg
  * settled/cached segments make it a no-op. Urgent commits call onUpdate
  * directly: nothing is held there, a reader of a pending stream suspends to
  * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
+ * Every commit is tagged with its transition({ when }) `kind` (#1165), then
+ * `transitionTypes`.
  */
-export declare function commitInTransition(loaders: LoaderStore, onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, transitionTypes: readonly string[]): void;
+export declare function commitInTransition(loaders: LoaderStore, onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, kind: TransitionWhenKind, transitionTypes: readonly string[]): void;
 /**
  * Configuration for creating a partial updater
  */
@@ -45,13 +49,15 @@ export interface PartialUpdateConfig {
         /** What the response's handlers pushed, to the handle store. */
         handles(metadata: RscMetadata): void;
         /**
-         * Deliver the navigation state to its readers now. A page built with
-         * holes commits in the task of its click, before the notification of the
-         * click has gone out (event-controller.ts makeDebouncedNotifier), and
-         * React holds that commit where a hole is read with no boundary: without
-         * this useNavigation() reads idle, on the page being left, for the whole
-         * wait. Delivered first, `loading` is on screen when the commit is
-         * handed over, and stays while React holds it, as for a plain click.
+         * Deliver the navigation state to its readers now, and commit it. A page
+         * built with holes commits in the task of its click, before the
+         * notification of the click has gone out (event-controller.ts
+         * makeDebouncedNotifier), and React holds that commit where a hole is
+         * read with no boundary: without this useNavigation() reads idle, on the
+         * page being left, for the whole wait. Committed first, `loading` is on
+         * screen when the commit is handed over, and stays while React holds it,
+         * as for a plain click. Delivered at default priority it joins the
+         * commit's urgent batch, which brings idle with the URL, and never shows.
          */
         flush(): void;
     };
@@ -70,8 +76,8 @@ export interface CommitOverrides {
     interceptSourceUrl?: string;
     /** Server-set location state to merge into history.pushState */
     serverState?: Record<string, unknown>;
-    /** The committed route's name (payload metadata), remembered per history entry. */
-    routeName?: string;
+    /** The payload's metadata: its route name and rewrite target, remembered per history entry. */
+    metadata?: ShownEntry;
 }
 /**
  * Discriminated update mode for partial updates.
@@ -120,8 +126,10 @@ export type UpdateMode = {
     action?: TransitionWhenActionInput;
 };
 /**
- * Type for the fetchPartialUpdate function
+ * Type for the fetchPartialUpdate function. In `action` mode it resolves with
+ * the error of a loader that threw while it re-ran (revalidationErrorOf);
+ * the loader throws at its read.
  */
-export type PartialUpdater = (targetUrl: string, segmentIds: string[] | undefined, isRetry: boolean, signal: AbortSignal | undefined, tx: BoundTransaction, mode?: UpdateMode) => Promise<void>;
+export type PartialUpdater = (targetUrl: string, segmentIds: string[] | undefined, isRetry: boolean, signal: AbortSignal | undefined, tx: BoundTransaction, mode?: UpdateMode) => Promise<Error | undefined>;
 export declare function createPartialUpdater(config: PartialUpdateConfig): PartialUpdater;
 export { createPartialUpdater as default };

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

@@ -86,6 +86,14 @@ export interface DecodedPrefetch {
      * one prefetch serves unlimited adoptions within TTL/state validity.
      */
     respawn?: () => DecodedPrefetch;
+    /**
+     * The prefetch's stall timer (executePrefetchFetch). Navigation clears it on
+     * the entry it serves: from then on the click owns the stream, which runs to
+     * its end (a Flight response that arrived is never aborted mid-stream). A
+     * prefetch nobody adopted keeps it, so a stalled one is still aborted.
+     * Absent on a respawned entry, which has no timer.
+     */
+    stallTimer?: ReturnType<typeof setTimeout>;
     /**
      * Release the buffered reserve bytes. Called when the entry is evicted
      * without being consumed (expiry, FIFO, sweep, cache clear) so the tee

package/dist/types/browser/rango-marker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Publishes `window.__rango = { version }` so outside tools can tell a page is
+ * a Rango app and which router release serves it. Write-only and informational:
+ * nothing in the router reads it (rango-marker.test.ts greps src/ for reads),
+ * and only the npm semver is exposed, no build hash, router id or config.
+ */
+export declare function publishRangoMarker(): void;

package/dist/types/browser/react/filter-segment-order.d.ts

@@ -5,6 +5,16 @@
 export declare const LOADER_SEGMENT_ID: RegExp;
 /** True for a loader sub-id ("M0L0D1.user"), false for a layout/route/slot id. */
 export declare function isLoaderSegmentId(id: string): boolean;
+/**
+ * The parent of a loader sub-id (`${parentId}D${index}.${loaderId}`); any
+ * other id unchanged. parentId is a shortCode (never "D"), or
+ * `${shortCode}.${slotName}` for an intercept slot's loaders, where the
+ * user-chosen name may hold an uppercase "D" ("@Detail"). Strip from the first
+ * `D<index>.`: splitting on a bare "D" mis-cut "@Detail" to "@" and silently
+ * dropped the loader's data. Correct only because slot names cannot contain
+ * "." (assertValidSlotName, route-definition/dsl-helpers.ts).
+ */
+export declare function loaderParentId(id: string): string;
 /**
  * Build the handle-collection segment order from a raw `matched` list.
  *

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

@@ -1,4 +1,5 @@
 import type { Handle } from "../../handle.js";
+import type { RouteStateSignal } from "../event-controller.js";
 /**
  * Hook to access collected handle data.
  *
@@ -19,3 +20,22 @@ import type { Handle } from "../../handle.js";
  */
 export declare function useHandle<T, A>(handle: Handle<T, A>): Rango.FlightSerialize<A>;
 export declare function useHandle<T, A, S>(handle: Handle<T, A>, selector: (data: Rango.FlightSerialize<A>) => S): S;
+/**
+ * Route state the controller's handle notifications drive (useHandle,
+ * useSegments) commits with the page it belongs to. NavigationProvider
+ * flushes the controller inside every payload update, so a value known then
+ * is set in the page's lane. A page handed over urgently (signal "release")
+ * takes a value that arrives before it commits the same way: set at default
+ * priority, it renders in the page's lane, and the page's effects read it.
+ * A page in a transition (signal "anchor") does not: until it commits
+ * (releaseRouteState() from the provider's layout effect, signal "release"),
+ * a new value waits, and is applied in the commit's task, right after the
+ * page's own commit. In the page's lane, a value that suspends in a revealed
+ * <Suspense> (a crumb's content) would hold the page; in a lane of its own,
+ * it commits over the page being left and takes the page's transition types
+ * (#1165); and a transition entangled with the page misses its commit when it
+ * is set after React rendered the page, before its view transition's
+ * mutation, and starts a view transition of its own. A value shallow-equal to
+ * the last one sets nothing, so a reader renders only when its value moves.
+ */
+export declare function useCommitAnchoredState<T>(init: () => T): [T, (value: T, signal?: RouteStateSignal) => void];

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

@@ -5,6 +5,12 @@
  * include() mount prefix. Inside an include("/shop", ...) scope,
  * the returned function resolves local paths relative to /shop.
  *
+ * Under a parameterized mount (`include("/:accountId", ...)`) the mount's
+ * params are filled from the current route params, as `useReverse` does:
+ * `href("/issues")` at `/acme/board` returns `/acme/issues`. A mount param
+ * missing from the current match throws `Missing param` when the returned
+ * function is called.
+ *
  * For absolute paths (outside the current mount), use the bare
  * href() function directly instead.
  *

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

@@ -13,7 +13,12 @@ import type { RouterInstance } from "../types.js";
  *
  * RELATIVE paths (no leading `/`, no scheme/query/hash) resolve against the
  * current include() mount: `router.push("cart")` inside `include("/shop")`
- * navigates to `/shop/cart`. Absolute paths stay APP-absolute — unlike
+ * navigates to `/shop/cart`. Under a parameterized mount
+ * (`include("/:accountId", ...)`) the mount's params are filled from the
+ * current route params: `router.push("issues")` at `/acme/board` navigates
+ * to `/acme/issues`, and a missing mount param rejects the push/replace
+ * promise with `Missing param` (a prefetch skips the target).
+ * Absolute paths stay APP-absolute — unlike
  * basename, the mount is scoped, and absolute pushes legitimately target
  * outside it, so they are never auto-prefixed.
  *

package/dist/types/browser/response-adapter.d.ts

@@ -48,9 +48,11 @@ export declare function handleReloadHeader(response: Response, opts: {
  * end-of-stream, calling onComplete when done.
  *
  * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
- * on a read error or an abort (the signal cancelled the reader). Callers that
- * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
- * treat a non-clean end as incomplete — a broken stream is not complete data.
+ * on a read error, an abort (the signal cancelled the reader), or a body that
+ * ends with PREFETCH_FAILED_ROW (a prefetch whose render reported an error,
+ * rsc/prefetch-render-error.ts). Callers that gate a "fully complete" fast
+ * path (e.g. prefetch's `entry.complete`) must treat a non-clean end as
+ * incomplete — a broken stream is not complete data.
  *
  * If the response has no body, onComplete fires synchronously with `true`
  * (an empty body is a clean, complete stream).

package/dist/types/browser/scroll-restoration.d.ts

@@ -63,10 +63,12 @@ export declare function cancelScrollRestorationPolling(): void;
  *
  * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
  * @param options.isStreaming - Function to check if streaming is in progress
+ * @param options.committed - React has committed the restored tree (a layout effect)
  */
 export declare function restoreScrollPosition(options?: {
     retryIfStreaming?: boolean;
     isStreaming?: () => boolean;
+    committed?: boolean;
 }): boolean;
 /**
  * Handle hash link scrolling.
@@ -86,9 +88,11 @@ export declare function scrollToTop(): void;
 export declare function handleNavigationStart(): void;
 /**
  * Handle scroll for a back/forward traversal, at popstate before anything
- * renders: save the page being left under ITS key (history has already moved,
- * so saveCurrentScrollPosition would use the destination's key) and track the
- * destination as the displayed entry.
+ * renders: save the page on screen under ITS key (history has already moved,
+ * so saveCurrentScrollPosition would use the destination's key). A second
+ * traversal before the first one's restore commits (a rapid double Back, a
+ * deferred animated restore) saves the page still on screen, never an entry
+ * it did not show.
  */
 export declare function handleTraversalStart(): void;
 /**
@@ -96,11 +100,13 @@ export declare function handleTraversalStart(): void;
  * @param options.restore - If true, restore saved position (for popstate)
  * @param options.scroll - If false, don't scroll at all
  * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
+ * @param options.committed - Called after React committed the new tree
  */
 export declare function handleNavigationEnd(options: {
     restore?: boolean;
     scroll?: boolean;
     isStreaming?: () => boolean;
+    committed?: boolean;
 }): void;
 /**
  * Update the history state key after pushState/replaceState.

package/dist/types/browser/segment-reconciler.d.ts

@@ -2,15 +2,17 @@ import type { ResolvedSegment } from "./types.js";
 /**
  * Determines the merging behavior for segment reconciliation.
  *
- * - 'action': From server-action-bridge's own merge. Always merges loaders,
- *   always preserves cached loading (even undefined), never clears cached
- *   segment loading.
- * - 'navigation': From partial-update during normal navigation. Does NOT merge
- *   loaders, preserves cached loading only when defined, clears truthy loading
- *   on cached segments not in server diff.
+ * - 'action': From server-action-bridge's own merge. Always preserves cached
+ *   loading (even undefined), never clears cached segment loading.
+ * - 'navigation': From partial-update during normal navigation. Preserves
+ *   cached loading only when defined, clears truthy loading on cached
+ *   segments not in server diff.
  * - 'stale-revalidation': From partial-update during stale revalidation or
- *   action-triggered refetch. Merges loaders, always preserves cached loading
- *   (same as action), clears truthy loading on cached segments not in server diff.
+ *   action-triggered refetch. Always preserves cached loading (same as
+ *   action), clears truthy loading on cached segments not in server diff.
+ *
+ * No actor merges loader data: a loader the server skipped, an intercept's
+ * included, is its own cached segment in `matched`.
  */
 export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
 export interface ReconcileInput {
@@ -52,11 +54,6 @@ export interface ReconcileResult {
  *   (not undefined). When cached is undefined, lets server value through
  *   because we're building a new tree.
  *
- * Loader merging:
- * - action/stale-revalidation: Merges partial loader data when server returns
- *   fewer loaders than cached (revalidation only updated some loaders).
- * - navigation: Does not merge (full navigation fetches complete data).
- *
  * Cached segment handling (segments in matched but not in server response):
  * - action: Returns cached segment as-is (preserve tree structure).
  * - navigation/stale-revalidation: Clears truthy loading to undefined

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

@@ -29,6 +29,11 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
  */
 export interface RscMetadata {
     pathname: string;
+    /**
+     * Path and search of the URL the route rendered, when middleware rewrote
+     * the request there. Kept per history entry and sent back as `_rsc_rt`.
+     */
+    rewriteTarget?: string;
     segments: ResolvedSegment[];
     /** Router instance ID — the current app's identity. A mismatch with the
      *  client's id (sent as _rsc_rid) is detected server-side and answered with
@@ -223,6 +228,12 @@ export interface TrackedActionState {
     error: unknown | null;
     /** Result data from the action (preserved after completion) */
     result: unknown | null;
+    /**
+     * The error of a loader that threw while it re-ran after this successful
+     * action (the first, when several did). The loader also throws at its
+     * useLoader read, where the nearest error boundary catches it.
+     */
+    revalidationError: unknown | null;
 }
 /**
  * The value returned by {@link useAction} when called without a selector.
@@ -262,13 +273,23 @@ export interface SegmentState {
     currentUrl: string;
     currentSegmentIds: string[];
 }
+/**
+ * What a committed payload says about the page it shows, remembered per
+ * history entry (NavigationStore.rememberDisplayedEntry).
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface ShownEntry {
+    readonly routeName?: string;
+    readonly rewriteTarget?: string;
+}
 /**
  * What the router remembers about one history entry for transition({ when })
- * (NavigationStore.rememberDisplayedEntry).
+ * and the requests made from it (NavigationStore.rememberDisplayedEntry).
  *
  * @internal This type is an implementation detail and may change without notice.
  */
-export interface HistoryEntryMemory {
+export interface HistoryEntryMemory extends ShownEntry {
     readonly routeName: string | undefined;
     /** The entry's `history.state` as last recorded. */
     readonly state: unknown;
@@ -295,6 +316,12 @@ export interface NavigationUpdate {
         /** Function to check if streaming is in progress */
         isStreaming?: () => boolean;
     };
+    /**
+     * Handed to React inside startTransition (commitInTransition, an action's
+     * commit, a cached back/forward's): NavigationProvider joins the route
+     * state that arrives while React holds it to its commit.
+     */
+    inTransition?: true;
 }
 /**
  * Plain object accepted as {@link PlainHistoryState}. The `any` string index
@@ -504,12 +531,12 @@ export interface NavigationStore {
     /**
      * Per-history-entry memory for transition({ when }) sources: record the
      * entry on screen (keyed by its `history.state.key`) with its current
-     * `history.state` and, when given, its route name (kept from the last
-     * record otherwise; every push/replace creates a new key, so a stale name
-     * never carries to another entry). Called after every commit, restore and
-     * state merge.
+     * `history.state` and, when `shown` is given, its route name and rewrite
+     * target (both kept from the last record otherwise; every push/replace
+     * creates a new key, so a stale record never carries to another entry).
+     * Called after every commit, restore and state merge.
      */
-    rememberDisplayedEntry(routeName?: string): void;
+    rememberDisplayedEntry(shown?: ShownEntry): void;
     /**
      * The memory of the entry on screen, or of `entryKey`. At popstate
      * history.state already belongs to the destination, so back/forward reads
@@ -570,6 +597,8 @@ export interface FetchPartialOptions {
     targetUrl: string;
     segmentIds: string[];
     previousUrl: string;
+    /** The page's RscMetadata.rewriteTarget, sent as `_rsc_rt`. */
+    rewriteTarget?: string;
     signal?: AbortSignal;
     /** If true, this is a stale cache revalidation request - server should force revalidators */
     staleRevalidation?: boolean;
@@ -638,7 +667,8 @@ export interface ServerActionBridgeConfig {
 export interface NavigationBridge {
     navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
     refresh(): Promise<void>;
-    handlePopstate(): Promise<void>;
+    /** `event`: the popstate event; a traversal the browser animated itself (hasUAVisualTransition) is not animated again. */
+    handlePopstate(event?: PopStateEvent): Promise<void>;
     registerLinkInterception(): () => void;
     registerDelegatedPrefetch(): () => void;
     /** Current RSC version (live, reflects the latest updateVersion). */

package/dist/types/build/route-types/per-module-writer.d.ts

@@ -11,6 +11,18 @@ export declare function writePerModuleRouteTypes(root: string, filter?: ScanFilt
  * e.g. `export const patterns = urls(...)` -> ["patterns"]
  */
 export declare function findUrlsVariableNames(code: string): string[];
+export interface PerModuleRouteTypesPlan {
+    genPath: string;
+    /** A urls()/clientUrls() variable resolved to zero routes; content is empty. */
+    isPlaceholder: boolean;
+    content: string;
+}
+/**
+ * Pure half of the per-module writer: reads sources, never writes. Returns
+ * null when the file has no `urls(`/`clientUrls(` or no named routes and no
+ * urls() variable. Throws on failure.
+ */
+export declare function planPerModuleRouteTypesForFile(filePath: string): PerModuleRouteTypesPlan | null;
 /**
  * Generate per-module route types for a single url module file.
  * Follows include() calls recursively to produce the full route tree.

package/dist/types/cache/cf/cf-shell-frame.d.ts

@@ -37,6 +37,8 @@ export interface ShellFrameHead {
     ta?: number;
     /** ShellCacheEntry.initialTheme */
     i?: string;
+    /** ShellCacheEntry.pathname (a visitor-keyed shell's rendered location). */
+    lp?: string;
     /** ShellCacheEntry.docKey; navigation replay needs it after any round trip. */
     dk?: string;
     /** ShellCacheEntry.prunedRecords (diagnostic). */

package/dist/types/cache/types.d.ts

@@ -412,6 +412,14 @@ export interface ShellCacheEntry {
      * ThemeProvider.
      */
     initialTheme?: string;
+    /**
+     * The payload pathname of a shell keyed by the visitor's URL
+     * (`rewrite(...).shell("visitor")`, visitorShellKey); absent when the
+     * capture rendered its key's own URL. The serve tail replays it as it does
+     * `initialTheme`, and the serve gate serves the entry only to a request
+     * that renders this location.
+     */
+    pathname?: string;
     /**
      * The CAPTURE DATA SNAPSHOT, in stored/serialized form: the doc segment
      * record every HIT replays the handler layer from (`docKey`) and the

package/dist/types/client-urls/client-urls.d.ts

@@ -1,7 +1,11 @@
 import { type TrieNode } from "../router/route-trie-builder.js";
-import type { ClientUrlBuilder, ClientUrlPatterns } from "./types.js";
+import type { ClientUrlBuilder, ClientUrlHelpers, ClientUrlPatterns } from "./types.js";
 import type { ExtractRoutes } from "../urls/type-extraction.js";
 import type { ClientUrlItems } from "./types.js";
+export declare const loader: ClientUrlHelpers["loader"];
+export declare const revalidate: ClientUrlHelpers["revalidate"];
+export declare const loading: ClientUrlHelpers["loading"];
+export declare const transition: ClientUrlHelpers["transition"];
 export declare function clientUrls<const TItems extends ClientUrlItems>(builder: ClientUrlBuilder<TItems>): ClientUrlPatterns<ExtractRoutes<TItems>>;
 /**
  * The router's trie over a group's routes, each pattern joined to the
@@ -24,4 +28,4 @@ export declare function buildClientUrlsTrie(routes: readonly {
         readonly trailingSlash?: string;
     };
 }[], mount: string, foreign?: readonly string[]): TrieNode;
-export type { ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";
+export type { ClientTransitionConfig, ClientUrlBuilder, ClientUrlComponent, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";

package/dist/types/client-urls/revalidate-registry.d.ts

@@ -1,4 +1,4 @@
 import type { ShouldRevalidateFn } from "../types.js";
-export declare function registerClientUrlRevalidators(fns: Readonly<Record<string, ShouldRevalidateFn<any, any>>>): void;
+export declare function registerClientUrlRevalidators(fns: Readonly<Record<string, ShouldRevalidateFn<any, any> | boolean>>): void;
 export declare function getClientUrlRevalidator(key: string): ShouldRevalidateFn<any, any> | undefined;
 export declare function clearClientUrlRevalidators(): void;

package/dist/types/client-urls/server-projection.d.ts

@@ -38,11 +38,11 @@ export interface ClientUrlProjectionRoute {
      *  loader(), so a prefetch of the route defers them. Absent (= none) in
      *  projections serialized before the option existed. */
     readonly deferrableLoaderIndices?: readonly number[];
-    /** Per loader (aligned with loaderIds), the keys of its hoisted
-     *  revalidate() predicates in declaration order; materialization attaches
-     *  the registered predicates (revalidate-registry.ts). Absent when no
-     *  loader declares one. */
-    readonly loaderRevalidate?: readonly (readonly string[])[];
+    /** Per loader (aligned with loaderIds), its revalidate() arguments in
+     *  declaration order: a hoisted predicate's key, whose registration
+     *  materialization attaches (revalidate-registry.ts), or a boolean
+     *  literal. Absent when no loader declares one. */
+    readonly loaderRevalidate?: readonly (readonly (string | boolean)[])[];
     /** One per leading loader its layout()s declare
      *  (ClientUrlRouteRecord.layoutLoaders): the record's ordinal in the
      *  definition. Two routes whose loader at an index carries the same ordinal
@@ -62,6 +62,10 @@ export interface ClientUrlProjectionIntercept {
     readonly targetName: string;
     readonly loaderIds: readonly string[];
     readonly hasLoading: boolean;
+    /** As on a route (ClientUrlProjectionRoute.deferrableLoaderIndices). */
+    readonly deferrableLoaderIndices?: readonly number[];
+    /** As on a route (ClientUrlProjectionRoute.loaderRevalidate). */
+    readonly loaderRevalidate?: readonly (readonly (string | boolean)[])[];
 }
 export interface ClientUrlProjection {
     readonly version: 1;

package/dist/types/client-urls/types.d.ts

@@ -17,17 +17,29 @@ export interface ClientUrlItem {
 export type ClientUrlItemInput = ClientUrlItem | readonly ClientUrlItemInput[];
 export type ClientUrlItems = readonly ClientUrlItemInput[];
 export type ClientUrlUse = () => ClientUrlItems;
+/**
+ * A component path(), layout() or intercept() mounts. Its optional `use`
+ * carries its own items, as a server handler's `.use` does, built with the
+ * helpers `@rangojs/router/client` exports: they come before the mount
+ * site's explicit items (an explicit loading() or transition() wins, loaders
+ * accumulate). A page component may carry loader(), loading() and
+ * transition(); a layout or intercept component loader() and loading().
+ */
+export type ClientUrlComponent = ComponentType & {
+    readonly use?: ClientUrlUse;
+};
 export type ClientPathOptions<TName extends string = string, TSearch extends SearchSchema = SearchSchema> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash" | "ppr">;
-export type ClientPathFn = <const TPattern extends string, const TName extends string = UnnamedRoute, const TSearch extends SearchSchema = {}>(pattern: TPattern, component: ComponentType, optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
-export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: ComponentType, children: () => TItems) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
+export type ClientPathFn = <const TPattern extends string, const TName extends string = UnnamedRoute, const TSearch extends SearchSchema = {}>(pattern: TPattern, component: ClientUrlComponent, optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
+export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: ClientUrlComponent, children: () => TItems) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
 export interface ClientUrlLoaderRecord {
     readonly loader: LoaderDefinition<any, any>;
     /**
      * Per-loader revalidate() predicates, run on the server; empty = the
      * router's defaults. Under the rango Vite plugin the browser and SSR copies
-     * hold the marker the build left in place of each hoisted predicate.
+     * hold the marker the build left in place of each hoisted predicate; a
+     * boolean literal stays in place.
      */
-    readonly revalidate: readonly (ShouldRevalidateFn<any, DefaultEnv> | HoistedRevalidateRef)[];
+    readonly revalidate: readonly (ShouldRevalidateFn<any, DefaultEnv> | HoistedRevalidateRef | boolean)[];
     /**
      * loader(Def, { ssr: false }): document renders await this loader before
      * first flush (see {@link LoaderOptions}). Projected into the server tree,
@@ -36,11 +48,10 @@ export interface ClientUrlLoaderRecord {
      */
     readonly ssr?: false;
     /**
-     * loader(Def, { prefetch: false }): a prefetch of the route defers this
-     * loader and the click that adopts it runs it in its fill request (see
-     * {@link LoaderOptions}). Projected onto the materialized stub. Inside
-     * intercept() it is not recorded: intercept loaders ignore the flag, as in
-     * urls().
+     * loader(Def, { prefetch: false }): a prefetch of the route, or of an
+     * intercept's target from its source, defers this loader and the click
+     * that adopts it runs it in its fill request (see {@link LoaderOptions}).
+     * Projected onto the materialized stub.
      */
     readonly prefetch?: false;
 }
@@ -78,7 +89,7 @@ export interface ClientUrlRouteRecord {
 }
 /**
  * A restricted intercept declared inside clientUrls(). Compared to the server
- * intercept() there is no `when` selector, no middleware, and the target must
+ * intercept() there is no `when` selector, and the target must
  * be a dot-local NAMED route in the same definition — every field is
  * JSON-projectable, which is what makes the declaration legal in a
  * "use client" module. `targetName` is stored bare (no leading dot).
@@ -111,8 +122,8 @@ export interface ClientUrlHelpers {
      * the destination at once, commits the adopted prefetch with the other
      * loaders' data, and runs only the flagged loaders in its one fill
      * request. A `layout()` loader with the flag is flagged on every route
-     * below it. Inside intercept() the flag is accepted and ignored, as in
-     * urls().
+     * below it. Inside intercept() it defers the loader in a prefetch of the
+     * intercept from its source, as in urls().
      */
     readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: Pick<LoaderOptions, "ssr" | "prefetch"> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
     readonly loading: (component: ReactNode) => ClientUrlItem;
@@ -123,22 +134,24 @@ export interface ClientUrlHelpers {
      * names, ...): the build moves it out of this "use client" module. It may
      * reference imports and globals only; a binding of this module, `this`,
      * `import()`, a browser global, an `async` function or an import from a
-     * "use client" module fails the build with its file and line.
+     * "use client" module fails the build with its file and line. A boolean
+     * is shorthand for `() => true` / `() => false`.
      */
-    readonly revalidate: (fn: ShouldRevalidateFn<any, DefaultEnv>) => ClientUrlItem;
+    readonly revalidate: (fn: ShouldRevalidateFn<any, DefaultEnv> | boolean) => ClientUrlItem;
     /**
      * Declare an intercept for a named route in THIS definition. The target is
      * dot-local (`.detail`); scoping is module-local — only navigations whose
      * origin is inside this clientUrls() group render the intercept. `use` may
      * contain loader() and loading() only.
      */
-    readonly intercept: (slotName: `@${string}`, targetName: `.${string}`, component: ComponentType, use?: ClientUrlUse) => ClientUrlItem;
+    readonly intercept: (slotName: `@${string}`, targetName: `.${string}`, component: ClientUrlComponent, use?: ClientUrlUse) => ClientUrlItem;
     /**
      * Opt THIS route into transition-driven navigation: the canonical commit
      * holds previous content instead of re-streaming the loading() fallback,
      * and on experimental React the config's ViewTransition classes apply.
      * Data-only — no `when` gate (server-executed; declare it in the server
-     * tree). Valid inside a path() use callback only.
+     * tree). Valid inside a path() use callback, or a page component's
+     * `.use`.
      */
     readonly transition: (config: ClientTransitionConfig) => ClientUrlItem;
 }

package/dist/types/client.d.ts

@@ -95,8 +95,8 @@ export interface OutletState {
 }
 export declare function useOutlet(): OutletState;
 export { useLoader, useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
-export { clientUrls } from "./client-urls/client-urls.js";
-export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
+export { clientUrls, loader, loading, revalidate, transition, } from "./client-urls/client-urls.js";
+export type { ClientUrlComponent, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./client-urls/client-urls.js";
 /**
  * Props for the ErrorBoundary component
  */

package/dist/types/client.rsc.d.ts

@@ -12,8 +12,8 @@ import * as Html from "./html.js";
 export { Outlet, ParallelOutlet, useOutlet, type OutletState, useLoader, ErrorBoundary, type ErrorBoundaryProps, } from "./client.js";
 export { useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
 export { createLoader } from "./route-definition.js";
-export { clientUrls } from "./client-urls/client-urls.js";
-export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
+export { clientUrls, loader, loading, revalidate, transition, } from "./client-urls/client-urls.js";
+export type { ClientUrlComponent, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./client-urls/client-urls.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
 export { useSearchParams } from "./browser/react/use-search-params.js";