@rangojs/router 0.5.1 → 0.6.0

package/dist/types/browser/react/use-search-params.d.ts

@@ -1,19 +1,66 @@
 import type { ReadonlyURLSearchParams } from "../types.js";
 /**
- * Hook to access the current URL search params.
+ * Accepted shapes for the setter: a full replacement for the search string.
+ * Record values are stringified; array values append one entry per element;
+ * null/undefined values are skipped (ergonomic conditional spreads).
+ */
+export type SearchParamsInit = string | URLSearchParams | ReadonlyURLSearchParams | Record<string, string | number | boolean | readonly (string | number | boolean)[] | null | undefined>;
+export interface SetSearchParamsOptions {
+    /** Replace the current history entry instead of pushing (default false). */
+    replace?: boolean;
+    /** Scroll behavior for the navigation (default: router default, scroll). */
+    scroll?: boolean;
+    /**
+     * Set false to skip the server fetch and only update the URL (default
+     * true). Purely client-derived search state (open accordions, view modes)
+     * needs no loader re-run; all location-aware hooks still update. Same
+     * contract as NavigateOptions.revalidate — it only applies because the
+     * setter never changes the pathname.
+     */
+    revalidate?: boolean;
+}
+export type SetSearchParams = (init: SearchParamsInit | ((prev: URLSearchParams) => SearchParamsInit), options?: SetSearchParamsOptions) => Promise<void>;
+/**
+ * Hook to read and write the current URL search params
+ * (React Router-style tuple).
  *
- * Returns a read-only URLSearchParams object from the committed location.
- * Updates when navigation completes, not during pending navigation.
+ * The first element is a read-only URLSearchParams from the COMMITTED
+ * location — it updates when navigation completes, not during a pending
+ * navigation. During document SSR it carries the LIVE request's search (the
+ * SSR store is seeded from SSRRenderOptions.search), and the browser's
+ * first render seeds from its own store location (window.location) — the
+ * same URL, so hydration matches. Ppr capture/resume renders seed the SHELL
+ * KEY's search (sorted, cache.searchParams filter applied — search is part
+ * of shell identity like every other ppr key), so static-part reads bake
+ * markup consistent with the shell's own key. Two edges: a param EXCLUDED
+ * by cache.searchParams is absent in shell renders but present in the
+ * browser (exclusion declares "does not affect markup" — reading one
+ * anyway hydration-mismatches), and toString() renders sorted order while
+ * the browser holds the raw URL order.
  *
- * Note: During SSR the search params are not available (the server only sends
- * the pathname). The hook returns empty params during SSR and syncs from
- * the browser URL on mount.
+ * The setter REPLACES the whole search string (React Router semantics) and
+ * navigates to the current pathname with the new params — a same-route
+ * navigation, so route loaders re-evaluate per their revalidate() contract
+ * and the commit holds previous content (the same-structure transition
+ * lane). Pass a function to merge with the current params: it receives a
+ * MUTABLE copy read at call time. The hash is dropped, like React Router.
  *
  * @example
  * ```tsx
- * const searchParams = useSearchParams();
- * const query = searchParams.get("q"); // "react"
- * const page = searchParams.get("page"); // "2"
+ * const [searchParams, setSearchParams] = useSearchParams();
+ * const category = searchParams.get("category");
+ *
+ * // Replace the whole search string
+ * setSearchParams({ category: "electronics" });
+ *
+ * // Merge with what's there now
+ * setSearchParams((prev) => {
+ *   prev.set("page", "2");
+ *   return prev;
+ * });
+ *
+ * // Filter UIs usually want replace + preserved scroll
+ * setSearchParams({ category: "home" }, { replace: true, scroll: false });
  * ```
  */
-export declare function useSearchParams(): ReadonlyURLSearchParams;
+export declare function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams];

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

@@ -47,12 +47,27 @@ export interface RscMetadata {
      * Slots are used for intercepting routes during soft navigation
      */
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable from this location as a
+     * navigation origin. The browser-local clientUrls matcher declines its
+     * optimistic presentation for these targets (the canonical response would
+     * commit the intercept over the ORIGIN page, so destination loading would
+     * flash and revert). Missing/empty means no targets.
+     */
+    interceptTargets?: string[];
     /** Root layout component for browser-side re-renders */
     rootLayout?: ComponentType<{
         children: ReactNode;
     }>;
     /** Handle data accumulated across route segments (async generator that yields on each push) */
     handles?: AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late handle channel: pushes landing after the handler
+     * barrier (streaming loader ctx.use(Handle) writes). Consumed non-blocking
+     * post-hydration (rsc-router.tsx); `handles` above is drained in blocking
+     * positions and must complete at the handler barrier.
+     */
+    handlesLate?: AsyncGenerator<HandleData, void, unknown>;
     /** Cached handle data (for back/forward navigation from cache) */
     cachedHandleData?: HandleData;
     /**
@@ -438,6 +453,13 @@ export interface FetchPartialOptions {
     signal?: AbortSignal;
     /** If true, this is a stale cache revalidation request - server should force revalidators */
     staleRevalidation?: boolean;
+    /**
+     * Encoded client-run per-loader revalidation decisions
+     * (clientUrls revalidate() predicates executed in the browser); sent as
+     * X-Rango-Client-Reval and honored only by materialized client-urls loader
+     * stubs. Null/absent = locked server defaults.
+     */
+    clientRevalidation?: string | null;
     interceptSourceUrl?: string;
     /** RSC version for cache invalidation detection */
     version?: string;

package/dist/types/build/merge-full-manifests.d.ts

@@ -0,0 +1,3 @@
+import type { FullManifest } from "./generate-manifest.js";
+/** Merge ordered per-mount manifests without mutating any input manifest. */
+export declare function mergeFullManifests(manifests: readonly FullManifest[]): FullManifest;

package/dist/types/build/route-trie.d.ts

@@ -1,81 +1,12 @@
 /**
  * Build-time Route Trie Construction
  *
- * Builds a serializable trie from the route manifest for O(path_length)
- * route matching at runtime.
+ * Adapts generated manifests to the runtime-owned route trie builder.
  */
+import { buildRouteTrie, type TrieNode } from "../router/route-trie-builder.js";
 import type { FullManifest } from "./generate-manifest.js";
-/**
- * A response-type variant folded into a primary leaf's negotiate list. `pa` is
- * the variant's own positional param-name array, carried so the runtime can
- * re-key the matched params under the variant's names when it wins negotiation
- * (the trie match extracts params under the PRIMARY leaf's pa). Omitted when the
- * variant has no params; absent/identical pa means no re-key is needed.
- */
-export interface NegotiateVariant {
-    routeKey: string;
-    responseType: string;
-    pa?: string[];
-}
-export interface TrieLeaf {
-    /** Route name (e.g., "site.l1_500") */
-    n: string;
-    /** Static prefix of the entry (e.g., "/site") */
-    sp: string;
-    /** Constraint validation: paramName -> allowed values */
-    cv?: Record<string, string[]>;
-    /** Ordered param names for this route (positional) */
-    pa?: string[];
-    /** Trailing slash mode */
-    ts?: string;
-    /** Route has pre-rendered data available */
-    pr?: true;
-    /** Passthrough: handler kept in bundle for live fallback on unknown params */
-    pt?: true;
-    /** Response type for non-RSC routes (json, text, image, any) */
-    rt?: string;
-    /** Negotiate variants: response-type routes sharing this path */
-    nv?: NegotiateVariant[];
-    /** RSC-first: RSC route was defined before response-type variants */
-    rf?: true;
-}
-export interface TrieNode {
-    /** Route terminal at this node */
-    r?: TrieLeaf;
-    /** Static segment children */
-    s?: Record<string, TrieNode>;
-    /** Param child: { n: paramName, c: child node } */
-    p?: {
-        n: string;
-        c: TrieNode;
-    };
-    /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
-    xp?: Record<string, {
-        n: string;
-        c: TrieNode;
-    }>;
-    /**
-     * Wildcard terminal: leaf + paramName (`pn`). `pn` is "*" for the bare `/*`
-     * form and the param name for a named catch-all (`:name+`/`:name*`). `w1`
-     * marks a one-or-more catch-all (`:name+`): the runtime walker then rejects
-     * the zero-segment/empty-remainder case. Absent `w1` is zero-or-more.
-     */
-    w?: TrieLeaf & {
-        pn: string;
-        w1?: true;
-    };
-}
-/**
- * Build a route trie from build-time manifest data.
- *
- * @param routeManifest - Map of route name to full URL pattern
- * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
- * @param routeTrailingSlash - Optional map of route name to trailing slash mode
- * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
- * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
- * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
- */
-export declare function buildRouteTrie(routeManifest: Record<string, string>, routeToStaticPrefix: Record<string, string>, routeTrailingSlash?: Record<string, string>, prerenderRouteNames?: Set<string>, passthroughRouteNames?: Set<string>, responseTypeRoutes?: Record<string, string>): TrieNode;
+export { buildRouteTrie };
+export type { NegotiateVariant, TrieLeaf, TrieNode, } from "../router/route-trie-builder.js";
 /**
  * Build a per-router trie from a generated manifest. This is the single
  * construction path shared by build/discovery (discover-routers.ts, serialized

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

@@ -1,18 +1,20 @@
 import type { ScanFilter } from "./scan-filter.js";
 /**
  * Generate per-module route type files by statically parsing url module source.
- * Scans for files containing `urls(` and writes a sibling `.gen.ts` with the
- * extracted route name/pattern pairs. Only writes when content has changed.
+ * Scans for files containing `urls(` or `clientUrls(` and writes a sibling
+ * `.gen.ts` with the extracted route name/pattern pairs. Only writes when
+ * content has changed.
  */
 export declare function writePerModuleRouteTypes(root: string, filter?: ScanFilter): void;
 /**
- * Find all variable names assigned to urls() calls in source code.
+ * Find all variable names assigned to urls() or clientUrls() calls in source.
  * e.g. `export const patterns = urls(...)` -> ["patterns"]
  */
 export declare function findUrlsVariableNames(code: string): string[];
 /**
  * Generate per-module route types for a single url module file.
  * Follows include() calls recursively to produce the full route tree.
- * No-ops if the file doesn't contain `urls(` or has no named routes.
+ * No-ops if the file doesn't contain `urls(`/`clientUrls(` or has no named
+ * routes.
  */
 export declare function writePerModuleRouteTypesForFile(filePath: string): void;

package/dist/types/build/route-types/router-processing.d.ts

@@ -38,9 +38,8 @@ export declare function extractBasenameFromRouter(code: string): string | undefi
 export declare function genFileTsPath(sourceFile: string): string;
 export declare function resolveSearchSchemas(publicRouteNames: string[], runtimeSchemas: Record<string, Record<string, string>> | undefined, sourceFile: string): Record<string, Record<string, string>> | undefined;
 /**
- * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
- * or by parsing an inline builder function directly.
+ * Resolve routes and search schemas from every direct mount in a createRouter
+ * chain. Registrations are merged in runtime order, with later mounts winning.
  */
 export declare function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     routes: Record<string, string>;

package/dist/types/cache/cache-exec-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Execution-chain scope for "use cache" function bodies.
+ *
+ * The ambient guards (cookies(), headers(), ctx.set() reached via
+ * getRequestContext()) must fire for code running INSIDE a cached body and
+ * stay silent for everything else on the request. A property stamped on the
+ * shared RequestContext cannot express that: while a slow "use cache" body is
+ * in flight, every parallel read on the same request sees the stamp. Scar: a
+ * 2s cached product fetch running beside a sibling loader made the loader's
+ * cookies() read throw `cannot be called inside a "use cache" function` —
+ * same shared-object hazard as issue #684 plan 010, which fixed only the
+ * background-revalidation path. AsyncLocalStorage follows the cached body's
+ * own async chain, so parallel work is invisible to the guard while genuine
+ * in-body reads still throw.
+ *
+ * Deliberately NOT entered on the store-less bypass paths in cache-runtime.ts:
+ * there the body executes for real on every call, side effects take effect,
+ * and request-scoped reads are safe (see the bypass comments there).
+ *
+ * Kept separate from taint.ts so `node:async_hooks` stays out of that module —
+ * taint.ts is reachable from browser-bundled DSL helpers. The probe
+ * registration below wires assertNotInsideCacheExec to this scope without
+ * taint.ts importing it.
+ */
+/**
+ * Run fn with the "use cache" execution scope active. Continuations spawned
+ * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ */
+export declare function runWithCacheExecScope<T>(fn: () => T): T;
+/** True when the calling async chain is inside a "use cache" body. */
+export declare function isInsideCacheExecScope(): boolean;

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -65,8 +65,15 @@ export declare const MAX_REVALIDATION_INTERVAL = 30;
  *
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
  */
-export declare const EDGE_LOOKUP_TIMEOUT_MS = 10;
+export declare const EDGE_LOOKUP_TIMEOUT_MS = 25;
 /**
  * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
  * (response.json()) before treating the read as a miss.

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -302,6 +302,19 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /**
      * Convert string key to KV key string.
      * Uses same version prefix as Cache API for consistent invalidation.
+     *
+     * Single chokepoint for EVERY KV family (segments, items, shells, documents
+     * via toDocKVKey, tag markers via tagMarkerKey): a composed key over
+     * Cloudflare KV's 512-byte limit is normalized to a preserved readable
+     * prefix plus a SHA-256-derived 128-bit digest of the FULL key. Without
+     * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
+     * and the entry silently never reaches L2 (observed in production for
+     * "use cache" items whose serialized args — e.g. a CMS query object — blow
+     * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+     * normalization is semantics-preserving as long as distinct logical keys
+     * stay distinct: colliding requires an identical 400-byte prefix AND a
+     * 128-bit SHA-256 collision. Deterministic, so every family's read, write,
+     * and delete paths agree on the stored key.
      * @internal
      */
     private toKVKey;
@@ -546,7 +559,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      *
      * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
      * runs ONLY after that tag's KV marker write is confirmed. If any KV write
-     * fails (transient error, or an over-512-byte key), this rejects with the
+     * fails (transient error; over-limit keys are normalized by toKVKey rather
+     * than rejected), this rejects with the
      * failed tags so an awaiting updateTag() surfaces the failure instead of
      * silently reporting success while other requests/colos serve stale data. The
      * eager purge still fires for the whole batch first (it is additive).

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

@@ -288,7 +288,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * cannot stall the request; the read then falls through to its normal miss
      * path (L2/KV or render).
      *
-     * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+     * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (25). Set to 0 (or any value
      * <= 0) to disable the budget and always await `match`.
      */
     edgeLookupTimeoutMs?: number;

package/dist/types/cache/cf/cf-kv-utils.d.ts

@@ -9,6 +9,27 @@ export declare const KV_MAX_KEY_BYTES = 512;
 export declare const KV_MIN_EXPIRATION_TTL = 60;
 /** UTF-8 byte length of a KV key (multibyte tags can exceed the char count). */
 export declare function kvKeyByteLength(key: string): number;
+/**
+ * Bytes of a composed key preserved verbatim when an over-limit key is
+ * normalized (toKVKey). 400 leaves room for the `~` separator and the 32-hex
+ * digest inside KV_MAX_KEY_BYTES while keeping the version prefix and most of
+ * the logical key readable (and prefix-listable) in the KV dashboard.
+ */
+export declare const KV_KEY_PRESERVED_PREFIX_BYTES = 400;
+/**
+ * Truncate to at most `maxBytes` of UTF-8. A multibyte sequence split at the
+ * boundary decodes to U+FFFD, which is stripped — the result is deterministic
+ * for a given input, which is all key normalization needs.
+ */
+export declare function truncateToBytes(value: string, maxBytes: number): string;
+/**
+ * 128-bit hex digest (SHA-256 truncated) of a composed KV key. WebCrypto is
+ * available on workerd and Node alike; SHA-256 (not a fast non-crypto hash)
+ * because cache keys embed user-influenced serialized args — an engineered
+ * collision between two normalized keys would serve one entry's payload for
+ * the other's.
+ */
+export declare function kvKeyDigest(value: string): Promise<string>;
 /**
  * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
  * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the

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

@@ -11,14 +11,19 @@ export declare const NOCACHE_SYMBOL: unique symbol;
  */
 export declare function isTainted(value: unknown): boolean;
 /**
- * Symbol stamped on tainted ctx during "use cache" function execution.
- * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
- * throw if present — reads would cache per-request data under a shared key,
- * and side effects would be lost on cache hit.
+ * Symbol stamped on tainted ctx objects PASSED AS ARGUMENTS to a "use cache"
+ * function during its execution. ctx.set(), ctx.header(), etc. check this
+ * flag and throw if present — those side effects are lost on cache hit.
+ *
+ * Argument objects only. Ambient access (cookies()/headers() and ctx methods
+ * reached via getRequestContext()) is guarded by the AsyncLocalStorage scope
+ * in cache-exec-scope.ts instead: stamping the SHARED RequestContext made
+ * every parallel read on the request throw for the cached body's whole
+ * execution window (a 2s cached fetch poisoned a sibling loader's cookies()).
  *
  * The value is a numeric reference count, not a boolean. Multiple concurrent
- * cached functions sharing the same ctx/requestCtx each increment on entry
- * and decrement on exit. Guards fire when count > 0.
+ * cached functions sharing the same ctx each increment on entry and decrement
+ * on exit. Guards fire when count > 0.
  */
 export declare const INSIDE_CACHE_EXEC: unique symbol;
 /**
@@ -31,6 +36,7 @@ export declare function stampCacheExec(obj: object): void;
  * used by guards no longer fires.
  */
 export declare function unstampCacheExec(obj: object): void;
+export declare function _setCacheExecScopeProbe(probe: () => boolean): void;
 /**
  * Throw if ctx is inside a "use cache" execution.
  * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.

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

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import type { ClientUrlPatterns } from "./types.js";
+/**
+ * Server-materialized wrapper layout for a clientUrls() group that declares
+ * intercepts. Attachment scar: intercepts emitted at the TOP LEVEL of a lazily
+ * included module attach to the isolated parent clone
+ * (getIsolatedLazyParent in server/context.ts) and are silently discarded —
+ * only intercepts attached to a layout entry created WITHIN the expansion
+ * survive in origin chains. Materialization therefore wraps the group's routes
+ * and intercept entries in this layout; it renders the child outlet plus one
+ * named outlet per declared slot, so the modal presents inside the group's own
+ * subtree (module-local declaration, module-local presentation).
+ */
+export declare function ClientUrlsGroupLayout({ slotNames, }: {
+    slotNames: readonly `@${string}`[];
+}): ReactNode;
+/** Slot content for a client-declared intercept: renders the definition's
+ *  modal component; its useLoader() calls read the slot segment's loader data
+ *  from the surrounding outlet context. */
+export declare function ClientUrlsInterceptSlot({ definition, interceptIndex, }: {
+    definition: ClientUrlPatterns;
+    interceptIndex: number;
+}): ReactNode;
+export declare function ClientUrlsInterceptLoading({ definition, interceptIndex, }: {
+    definition: ClientUrlPatterns;
+    interceptIndex: number;
+}): ReactNode;
+export declare function ClientUrlsRoot({ definition, routeId, namePrefix, }: {
+    definition: ClientUrlPatterns;
+    routeId: string;
+    /** include() route-name prefix, injected at materialization for canonical
+     *  name composition (intercept-target coordination). */
+    namePrefix?: string;
+}): ReactNode;
+export declare function ClientUrlsLoading({ definition, routeId, }: {
+    definition: ClientUrlPatterns;
+    routeId: string;
+}): ReactNode;

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

@@ -0,0 +1,5 @@
+import type { ClientUrlBuilder, ClientUrlPatterns } from "./types.js";
+import type { ExtractRoutes } from "../urls/type-extraction.js";
+import type { ClientUrlItems } from "./types.js";
+export declare function clientUrls<const TItems extends ClientUrlItems>(builder: ClientUrlBuilder<TItems>): ClientUrlPatterns<ExtractRoutes<TItems>>;
+export type { ClientRevalidateArgs, ClientRevalidateFn, ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";

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

@@ -0,0 +1,38 @@
+import type { ClientUrlPatterns } from "./types.js";
+export interface ClientUrlNavigationIntent {
+    readonly routeId: string;
+}
+export declare function setActiveInterceptTargets(targets: readonly string[] | undefined): void;
+export interface ClientUrlNavigationPresentation {
+    readonly routeId: string;
+    clear(): void;
+}
+export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mount: string, namePrefix: string, setIntent: (intent: ClientUrlNavigationIntent | null) => void): () => void;
+export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal): ClientUrlNavigationPresentation | null;
+/**
+ * Run the held clientUrls route's per-loader revalidate() predicates and
+ * encode their decisions for the request header. Predicates are CLIENT code
+ * (declared in the "use client" definition module); only decisions cross the
+ * wire — the synthesized per-loader revalidate() on every materialized stub
+ * (server-projection.ts) reads them back by loader $$id.
+ *
+ * Decisions exist only for the loaders the client currently HOLDS: the local
+ * match of currentUrl. They matter when the server would re-evaluate those
+ * held loader segments — same-route param/search navs, actions, and stale
+ * restores. Cross-route targets render new segments unconditionally, so a
+ * decision would be ignored; we still compute against the current route since
+ * only its held segments are addressable.
+ *
+ * Returns null when no group is active, the current location is not a client
+ * route, or no predicate produced a decision that differs from the locked
+ * default — the server then applies defaults, which is also the behavior for
+ * requests that cannot carry decisions (no-JS, PE, prefetch, document loads).
+ */
+export declare function collectClientRevalidationDecisions(options: {
+    currentUrl: URL;
+    nextUrl: URL;
+    isAction: boolean;
+    actionId?: string;
+    stale: boolean;
+}): string | null;
+export declare function clearClientUrlNavigationRegistry(): void;

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

@@ -0,0 +1,25 @@
+/**
+ * Wire protocol for CLIENT-RUN per-loader revalidation decisions.
+ *
+ * clientUrls() revalidate() predicates are declared in a "use client" module,
+ * so they cannot cross the projection boundary as functions — instead they
+ * EXECUTE in the browser and only their DECISIONS cross: the browser attaches
+ * this header to partial-navigation and action requests, and the synthesized
+ * per-loader revalidate() on every materialized loader stub reads it back
+ * (see materializeRouteItems in server-projection.ts).
+ *
+ * Trust model: same class as `_rsc_segments` — a decision can only make the
+ * CLIENT's own view staler (skip) or fresher (force), and the synthesized
+ * predicates exist only on client-urls loader stubs, so the header can never
+ * influence server-tree loaders. Requests without the header (no-JS, PE,
+ * prefetch, document loads) fall back to the locked server defaults.
+ */
+export declare const CLIENT_REVALIDATION_HEADER = "X-Rango-Client-Reval";
+export interface ClientRevalidationDecisions {
+    /** Loader $$ids whose client predicate said false (keep held data). */
+    readonly skip: readonly string[];
+    /** Loader $$ids whose client predicate said true against a false default. */
+    readonly force: readonly string[];
+}
+export declare function encodeClientRevalidationDecisions(decisions: ClientRevalidationDecisions): string | null;
+export declare function decodeClientRevalidationDecisions(headerValue: string | null): ClientRevalidationDecisions | null;

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

@@ -0,0 +1,62 @@
+import type { SearchSchemaValue } from "../search-params.js";
+import type { TrailingSlashMode } from "../types.js";
+import type { UrlPatterns } from "../urls/pattern-types.js";
+import type { ClientTransitionConfig, ClientUrlPatterns } from "./types.js";
+export interface ClientUrlReference {
+    readonly $$typeof: symbol;
+    readonly $$id: string;
+}
+export type ClientUrlDefinitionSource = ClientUrlReference | ClientUrlPatterns;
+export interface ClientUrlProjectionOptions {
+    readonly search?: Readonly<Record<string, SearchSchemaValue>>;
+    readonly trailingSlash?: TrailingSlashMode;
+}
+export interface ClientUrlProjectionRoute {
+    readonly id: string;
+    readonly pattern: string;
+    readonly name: string | null;
+    readonly options: ClientUrlProjectionOptions;
+    readonly loaderIds: readonly string[];
+    readonly hasLoading: boolean;
+    /** Indices into loaderIds of loaders declared loader(Def, { stream:
+     *  "navigation" }); materialization passes the option through to the server
+     *  loader() so document renders await them before first flush. Absent (=
+     *  none) in projections serialized before stream support. */
+    readonly awaitedLoaderIndices?: readonly number[];
+    /** Data-only transition config (no `when` — server-tree only); absent in
+     *  projections serialized before transition support. */
+    readonly transition?: Readonly<ClientTransitionConfig>;
+}
+export interface ClientUrlProjectionIntercept {
+    readonly slotName: `@${string}`;
+    /** Bare local target name; materialization re-dots it so the server
+     *  intercept() helper composes it against the include's name prefix. */
+    readonly targetName: string;
+    readonly loaderIds: readonly string[];
+    readonly hasLoading: boolean;
+}
+export interface ClientUrlProjection {
+    readonly version: 1;
+    readonly routes: readonly ClientUrlProjectionRoute[];
+    /** Absent in projections serialized before intercept support; consumers
+     *  must treat missing as empty. */
+    readonly intercepts?: readonly ClientUrlProjectionIntercept[];
+}
+export declare function serializeClientUrlPatterns(patterns: ClientUrlPatterns): ClientUrlProjection;
+export declare function isClientUrlPatterns(value: unknown): value is ClientUrlPatterns;
+export declare function isClientUrlReference(value: unknown): value is ClientUrlReference;
+export declare function setClientUrlProjection(reference: string | ClientUrlReference, projection: ClientUrlProjection): void;
+export declare function getClientUrlProjection(reference: string | ClientUrlReference): ClientUrlProjection | undefined;
+export declare function clearClientUrlProjections(): void;
+export declare function materializeClientUrlPatterns(reference: ClientUrlDefinitionSource, projection: ClientUrlProjection): UrlPatterns;
+/**
+ * Adapt a clientUrls() source for `include()` mounting inside the canonical
+ * urls() tree. Materialization is DEFERRED into the returned handler: it
+ * resolves the discovery-installed projection at evaluation time (lazy include
+ * expansion, build manifest generation, dev per-request trie rebuild) — by
+ * then the routes-manifest bootstrap has installed projections, so registration
+ * order never matters. The include machinery applies the URL and route-name
+ * prefixes exactly as it does for any urls() module; surrounding RSC layouts,
+ * middleware scoping, and boundaries derive from the canonical server tree.
+ */
+export declare function clientUrlIncludePatterns(source: ClientUrlDefinitionSource): UrlPatterns;