@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -0,0 +1,268 @@
+/**
+ * Vercel Runtime Cache Store
+ *
+ * A SegmentCacheStore backed by Vercel's Runtime Cache (`getCache()` from
+ * `@vercel/functions`). It is the production store analogue to CFCacheStore, but
+ * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
+ * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
+ * L1/L2 tiering, KV tag-marker comparison, marker memoization, or per-tier
+ * timeout budgets are needed here - the platform does that work. What this store
+ * adds on top of the raw primitive is the parts Vercel does NOT give us:
+ *
+ *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
+ *      simply becomes a miss. We store our own {staleAt, expiresAt} envelope and
+ *      set the Vercel ttl to (ttl + swr) so the entry survives its SWR window,
+ *      computing staleness ourselves via the shared cache-policy helpers.
+ *   2. A single-keyspace family split. `getCache` is one flat keyspace, whereas
+ *      the interface has three value families (segments, "use cache" items, full
+ *      responses). The memory store keeps three separate Maps; here they must be
+ *      namespaced by a prefix or a set() of a response would clobber a segment
+ *      cached under the same router key.
+ *   3. The platform guardrails: the 2 MB per-item ceiling (oversized writes
+ *      silently no-op on Vercel, so we skip + report), the per-item tag cap, and
+ *      cross-deploy non-reconciliation (TTL/tag updates are not reconciled across
+ *      deployments - bake a build id into `version` or the getCache namespace).
+ *
+ * Dependency stance: this module imports NOTHING from `@vercel/functions`. The
+ * runtime cache handle (and `waitUntil`) are injected through the constructor and
+ * typed against the local VercelRuntimeCache shape below, exactly as CFCacheStore
+ * takes its `kv`/`ctx` bindings by injection. The consumer passes the real
+ * `getCache(...)` result, which satisfies the shape structurally. That keeps the
+ * router free of a hard Vercel dependency.
+ */
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
+import type { RequestContext } from "../../server/request-context.js";
+/**
+ * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
+ * from `@vercel/functions`. Declared locally so @rangojs/router carries no hard
+ * dependency on `@vercel/functions`; the real handle satisfies it structurally.
+ *
+ * @see https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#getcache
+ */
+export interface VercelRuntimeCache {
+    /** Returns the stored value, or a nullish value on miss. Never throws on miss. */
+    get(key: string): Promise<unknown>;
+    /** Stores a value with optional TTL (seconds), tags, and observability name. */
+    set(key: string, value: unknown, options?: {
+        ttl?: number;
+        tags?: string[];
+        name?: string;
+    }): Promise<void>;
+    /** Removes a value by key. */
+    delete(key: string): Promise<void>;
+    /** Expires every entry tagged with any of `tag`. Global, ~300ms propagation. */
+    expireTag(tag: string | string[]): Promise<void>;
+}
+/**
+ * Vercel Runtime Cache hard per-item ceiling: 2 MB. Writes above this silently
+ * no-op on the platform, so the store measures the serialized envelope and skips
+ * (fail-open) entries at or above this size.
+ */
+export declare const VERCEL_MAX_ITEM_BYTES: number;
+/**
+ * Per-item tag ceiling. Vercel's getCache API reference lists 128 tags per item
+ * (https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#getcache).
+ * Tags beyond this are dropped with a warning at write time. Does NOT cap
+ * invalidateTags() - an invalidation must reach every requested tag.
+ */
+export declare const VERCEL_MAX_TAGS_PER_ITEM: number;
+/** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
+export declare const VERCEL_MAX_TAG_BYTES: number;
+/** Read-path outcome for the debug sink. */
+export type VercelCacheReadOutcome = "miss" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
+/** Diagnostic event emitted on every read when `debug` is set. */
+export interface VercelCacheReadDebugEvent {
+    op: "get" | "getItem" | "getResponse" | "getShell";
+    key: string;
+    outcome: VercelCacheReadOutcome;
+    staleAt?: number;
+    expiresAt?: number;
+    shouldRevalidate?: boolean;
+    /** Wall-clock ms spent in the backing cache.get(). */
+    readMs?: number;
+}
+/** `true` logs each read outcome; a function receives the structured event. */
+export type VercelCacheDebug = boolean | ((event: VercelCacheReadDebugEvent) => void);
+/**
+ * Options for VercelCacheStore.
+ */
+export interface VercelCacheStoreOptions<TEnv = unknown> {
+    /**
+     * The Vercel Runtime Cache handle - `getCache()` from `@vercel/functions`.
+     * Required. Construct it with a build-hash namespace to bust stale-shaped
+     * entries across deployments, since Vercel does not reconcile TTL/tags between
+     * deploys:
+     *
+     * ```ts
+     * import { getCache } from "@vercel/functions";
+     * new VercelCacheStore({ cache: getCache({ namespace: BUILD_ID }) });
+     * ```
+     */
+    cache: VercelRuntimeCache;
+    /**
+     * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
+     * write (herd dampening) off the response path - the router already
+     * backgrounds the actual writes. When omitted, the lock write runs detached
+     * (fire-and-forget) instead.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /**
+     * Default ttl/swr for cache() boundaries when not explicitly specified.
+     */
+    defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations (region/locale/user
+     * segmentation). Receives the request context and the default key.
+     */
+    keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Build/version id folded into every stored key as `v/{version}/...`. A second
+     * cross-deploy busting layer in addition to (or instead of) the getCache
+     * namespace. Changing it invalidates everything this store wrote previously.
+     */
+    version?: string;
+    /**
+     * Max serialized entry size in bytes before a write is skipped. Defaults to
+     * VERCEL_MAX_ITEM_BYTES (2 MB - the platform's hard cap).
+     */
+    maxItemBytes?: number;
+    /**
+     * Human-readable label passed as the Vercel `set({ name })` option for
+     * observability in the Vercel dashboard.
+     */
+    name?: string;
+    /**
+     * Read diagnostics. `true` logs each read outcome to the console; a function
+     * receives the structured VercelCacheReadDebugEvent.
+     */
+    debug?: VercelCacheDebug;
+}
+/**
+ * Vercel Runtime Cache-backed segment cache store.
+ *
+ * Suitable for production deployments on Vercel Functions (Node runtime). The
+ * store is best-effort: every read failure degrades to a miss and every write
+ * failure to a no-op (reported, never thrown) - the sole exception is
+ * invalidateTags(), which rejects when the injected cache's expireTag() rejects
+ * so an awaited updateTag() can surface the failure.
+ *
+ * Read-your-own-writes caveat: this honesty is only as strong as the cache
+ * handle. The official `@vercel/functions` cache (`BuildCache.expireTag`)
+ * CATCHES backend failures and resolves, so with the official client a failed
+ * expireTag is invisible here and an awaited updateTag() can report success that
+ * did not happen. Treat tag invalidation on the official Vercel client as
+ * best-effort, not a hard read-your-own-writes guarantee. (A custom cache handle
+ * that propagates expireTag rejections does get the strict guarantee, which is
+ * what the unit suite exercises.)
+ *
+ * Key hashing / family isolation. The store namespaces its three value tiers as
+ * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * disjoint keyspaces. That separation is only as strong as the cache's
+ * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
+ * bits (8 hex chars), so at a large live-key count a collision can let one
+ * entry's body be served for another key (same-family) or be misread as corrupt
+ * (cross-family). For deployments with many cached keys, pass a wider hash so
+ * the family split is real isolation, e.g. `getCache({ keyHashFunction })` with
+ * a sha256-based function.
+ *
+ * @example
+ * ```ts
+ * import { getCache, waitUntil } from "@vercel/functions";
+ * import { VercelCacheStore } from "@rangojs/router/cache";
+ *
+ * export const router = createRouter({
+ *   cache: () => ({
+ *     store: new VercelCacheStore({
+ *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ *       // would be undefined here) so cross-deploy busting via `version` works.
+ *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+ *       waitUntil,
+ *       defaults: { ttl: 60, swr: 300 },
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    readonly supportsPassiveShellReads: true;
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    private readonly cache;
+    private readonly waitUntil?;
+    private readonly version?;
+    private readonly maxItemBytes;
+    private readonly name?;
+    private readonly debug?;
+    constructor(options: VercelCacheStoreOptions<TEnv>);
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    getResponse(key: string): Promise<{
+        response: Response;
+        shouldRevalidate: boolean;
+    } | null>;
+    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
+    getItem(key: string): Promise<CacheItemResult | null>;
+    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
+    getShell(key: string, options?: {
+        claimRevalidation?: boolean;
+    }): Promise<{
+        entry: ShellCacheEntry;
+        shouldRevalidate?: boolean;
+    } | null>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /**
+     * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
+     * expireTag() keeps no queryable history, so invalidateTags() writes "tm"
+     * markers for runtime capture races and immutable build shells. Marker >=
+     * generation start wins; read errors fail open like the CF marker check.
+     */
+    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    invalidateTags(tags: string[]): Promise<void>;
+    private toStoreKey;
+    private write;
+    /**
+     * Normalize a value read back from the cache. Entries written by this store
+     * are pre-serialized JSON strings (see write()); legacy entries (written
+     * before that change, or by a client that deserializes for us) come back as
+     * objects. Parse strings, pass objects through, and treat a non-JSON string
+     * as corrupt (returns undefined, so the caller reports + evicts).
+     */
+    private decodeRaw;
+    /**
+     * Stale-read herd dampening via a tiny companion lock key. On a stale read,
+     * check `{storeKey}:lock`; if absent, claim it (write a short-TTL marker) and
+     * return true so THIS reader triggers revalidation. If present, another
+     * same-region reader already claimed it, so return false and serve the stale
+     * entry as fresh without piling on. Best-effort and non-blocking; never throws.
+     *
+     * Only the STALE path pays the extra lock read; the fresh-hit path takes no
+     * lock round trip. Unlike the prior whole-envelope re-stamp, a stale read now
+     * writes only the tiny lock, never the (potentially large) payload.
+     *
+     * Non-atomic (getCache has no compare-and-set): two readers can both find no
+     * lock and both revalidate. The window is REVALIDATION_LOCK_MS wide, after
+     * which the lock expires and the entry is re-claimed (or a fresh write has
+     * superseded it). A read-compare would not close the race without CAS.
+     */
+    private claimRevalidation;
+    /** Measure a pre-serialized entry against the per-item size cap (see write). */
+    private withinSizeLimit;
+    /**
+     * Drop tags Vercel cannot round-trip: over-length tags, and tags carrying a
+     * URL metacharacter the `@vercel/functions` client does not encode (see
+     * VERCEL_UNSAFE_TAG_CHARS). Runs on BOTH paths - the write path
+     * (clampTagsForWrite) and invalidateTags - so a tag that would silently fail
+     * invalidation is never stored in the first place. `category` reports the
+     * drop under the caller's real operation (write vs invalidate).
+     */
+    private validateTags;
+    /** validateTags + the per-item tag cap. Used on the write path. */
+    private clampTagsForWrite;
+    private safeDelete;
+    private emitDebug;
+    private asSegmentEnvelope;
+    private asItemEnvelope;
+    private asShellEnvelope;
+    private asResponseEnvelope;
+}

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,57 @@
+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;
+    /** 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;

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

@@ -0,0 +1,132 @@
+import type { ComponentType, ReactNode } from "react";
+import type { LoaderDefinition, TransitionConfig } from "../types.js";
+import type { TrieMatchResult } from "../router/trie-matching.js";
+import type { PathOptions } from "../urls/pattern-types.js";
+import type { SearchSchema } from "../search-params.js";
+import type { TypedLayoutItem, TypedRouteItem } from "../route-types.js";
+import type { ExtractRoutes } from "../urls/type-extraction.js";
+import type { UnnamedRoute } from "../urls/pattern-types.js";
+declare const CLIENT_URL_ITEM_BRAND: unique symbol;
+declare const CLIENT_URL_PATTERNS_BRAND: unique symbol;
+/** Opaque value returned by a clientUrls() helper. */
+export interface ClientUrlItem {
+    readonly [CLIENT_URL_ITEM_BRAND]: void;
+}
+export type ClientUrlItemInput = ClientUrlItem | readonly ClientUrlItemInput[];
+export type ClientUrlItems = readonly ClientUrlItemInput[];
+export type ClientUrlUse = () => ClientUrlItems;
+export type ClientPathOptions<TName extends string = string, TSearch extends SearchSchema = SearchSchema> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash">;
+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>>;
+/**
+ * Arguments a clientUrls() revalidate() predicate receives. A client-computable
+ * subset of the server ShouldRevalidateFn args — the predicate RUNS IN THE
+ * BROWSER (it is declared in a "use client" module and never crosses the
+ * projection boundary); only its decision is sent to the server. There is no
+ * `context` — no server handler context exists where this executes.
+ */
+export interface ClientRevalidateArgs {
+    /** Full URL of the page being navigated away from (current location). */
+    readonly currentUrl: URL;
+    /** Full URL of the navigation target (equals currentUrl for actions). */
+    readonly nextUrl: URL;
+    /** Route params of the held client route (definition-local match). */
+    readonly currentParams: Record<string, string>;
+    /** Route params for the navigation target (definition-local match). */
+    readonly nextParams: Record<string, string>;
+    /**
+     * The locked default decision for this loader, computed client-side with
+     * the same rules the server would apply: `true` on actions and when
+     * params/search changed, `false` otherwise. Return it for default behavior
+     * plus your own conditions.
+     */
+    readonly defaultShouldRevalidate: boolean;
+    /** True when this is a stale history-entry background revalidation. */
+    readonly stale: boolean;
+    /** True when revalidation is triggered by a server action. */
+    readonly isAction: boolean;
+    /** The triggering server action's id, when isAction. */
+    readonly actionId?: string;
+}
+export type ClientRevalidateFn = (args: ClientRevalidateArgs) => boolean;
+export interface ClientUrlLoaderRecord {
+    readonly loader: LoaderDefinition<any, any>;
+    /** Client-run per-loader revalidation predicates; empty = locked defaults. */
+    readonly revalidate: readonly ClientRevalidateFn[];
+}
+/**
+ * The data-only subset of TransitionConfig a clientUrls() route may declare:
+ * ViewTransition classes/name plus the boundary opt-out. The `when` gate is a
+ * server-executed predicate and stays in the server tree — it cannot cross the
+ * "use client" projection boundary.
+ */
+export type ClientTransitionConfig = Pick<TransitionConfig, "enter" | "exit" | "update" | "share" | "default" | "name" | "viewTransition">;
+export interface ClientUrlRouteRecord {
+    readonly id: string;
+    readonly pattern: string;
+    readonly name: string | undefined;
+    readonly options: Readonly<ClientPathOptions> | undefined;
+    readonly component: ComponentType;
+    readonly layouts: readonly ComponentType[];
+    readonly loaders: readonly ClientUrlLoaderRecord[];
+    readonly loading: ReactNode | undefined;
+    readonly transition: Readonly<ClientTransitionConfig> | undefined;
+}
+/**
+ * A restricted intercept declared inside clientUrls(). Compared to the server
+ * intercept() there is no `when` selector, no middleware, 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).
+ */
+export interface ClientUrlInterceptRecord {
+    readonly slotName: `@${string}`;
+    readonly targetName: string;
+    readonly component: ComponentType;
+    readonly loaders: readonly ClientUrlLoaderRecord[];
+    readonly loading: ReactNode | undefined;
+}
+export interface ClientUrlHelpers {
+    readonly path: ClientPathFn;
+    readonly layout: ClientLayoutFn;
+    /**
+     * Attach a projected loader. The optional use callback may contain
+     * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
+     * the function) is sent with the revalidation request.
+     */
+    readonly loader: <TData>(definition: LoaderDefinition<TData>, use?: ClientUrlUse) => ClientUrlItem;
+    readonly loading: (component: ReactNode) => ClientUrlItem;
+    /**
+     * Per-loader revalidation predicate, valid inside a loader() use callback
+     * only. Runs IN THE BROWSER with client-computable args; return true to
+     * re-run the loader, false to keep held data. Absent predicates (and
+     * requests that carry no decisions: no-JS, PE, prefetch, document loads)
+     * follow the locked server defaults.
+     */
+    readonly revalidate: (fn: ClientRevalidateFn) => 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;
+    /**
+     * 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.
+     */
+    readonly transition: (config: ClientTransitionConfig) => ClientUrlItem;
+}
+export type ClientUrlBuilder<TItems extends ClientUrlItems = ClientUrlItems> = (helpers: ClientUrlHelpers) => TItems;
+export interface ClientUrlPatterns<TRoutes extends Record<string, any> = Record<string, any>> {
+    readonly __brand: "client-urls";
+    readonly routes: readonly ClientUrlRouteRecord[];
+    readonly intercepts: readonly ClientUrlInterceptRecord[];
+    readonly [CLIENT_URL_PATTERNS_BRAND]: void;
+    readonly _routes?: TRoutes;
+    match(pathname: string): TrieMatchResult | null;
+}
+export {};