@rangojs/router 0.5.2 → 0.7.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/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,71 @@
+import type { SearchSchemaValue } from "../search-params.js";
+import type { TrailingSlashMode } from "../types.js";
+import type { PartialPrerenderProps, 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;
+    /**
+     * The `ppr` path option, JSON-projected. Materialization passes it onto
+     * the group route's server `path()` verbatim, so the manifest entry
+     * carries it and the runtime shell capture/serve lanes engage exactly as
+     * for a hand-written server route (search is part of shell identity —
+     * the capture render seeds the key's own search, so group static parts
+     * may read useSearchParams).
+     */
+    readonly ppr?: true | Readonly<PartialPrerenderProps>;
+}
+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;

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

@@ -0,0 +1,147 @@
+import type { ComponentType, ReactNode } from "react";
+import type { LoaderDefinition, LoaderOptions, 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" | "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>>;
+/**
+ * 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[];
+    /**
+     * loader(Def, { stream: "navigation" }): document renders await this loader
+     * before first flush (see {@link LoaderOptions}). Projected into the server
+     * tree, where the per-isSSR entry stamping applies — client navigations
+     * stream regardless.
+     */
+    readonly stream?: "navigation";
+}
+/**
+ * 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.
+     *
+     * Pass `{ stream: "navigation" }` to await this loader before first flush
+     * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
+     * whose data, handle pushes, or thrown notFound()/redirect() must be in the
+     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
+     * `ppr` group route the flag BAKES: the loader executes at shell capture
+     * and its settled return freezes into the shell (nested promises stay
+     * live holes).
+     */
+    readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | ClientUrlUse, 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 {};