@rangojs/router 0.5.2 → 0.6.0

package/dist/types/client.d.ts

@@ -42,8 +42,9 @@ import { type ClientErrorBoundaryFallbackProps } from "./types";
  * }
  * ```
  */
-export declare function Outlet({ name }?: {
+export declare function Outlet({ name, fallback, }?: {
     name?: `@${string}`;
+    fallback?: ReactNode;
 }): ReactNode;
 /**
  * ParallelOutlet component - renders content for a named parallel slot
@@ -74,7 +75,7 @@ export declare function ParallelOutlet({ name }: {
     name: `@${string}`;
 }): ReactNode;
 /**
- * Hook to access outlet content programmatically
+ * Hook to access outlet content and descendant pending state programmatically.
  *
  * Alternative to using <Outlet /> component. Useful when you need
  * direct access to the outlet content in your logic.
@@ -83,12 +84,18 @@ export declare function ParallelOutlet({ name }: {
  * ```tsx
  * function BlogLayout() {
  *   const outlet = useOutlet();
- *   return <div><h1>Blog</h1>{outlet}</div>;
+ *   return <div aria-busy={outlet.pending}><h1>Blog</h1>{outlet.content}</div>;
  * }
  * ```
  */
-export declare function useOutlet(): ReactNode;
+export interface OutletState {
+    readonly content: ReactNode;
+    readonly pending: boolean;
+}
+export declare function useOutlet(): OutletState;
 export { useLoader, useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
+export { clientUrls } from "./client-urls/client-urls.js";
+export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
 /**
  * Props for the ErrorBoundary component
  */
@@ -156,6 +163,7 @@ export { useNavigation } from "./browser/react/use-navigation.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
 export { useSearchParams } from "./browser/react/use-search-params.js";
+export type { SearchParamsInit, SetSearchParams, SetSearchParamsOptions, } from "./browser/react/use-search-params.js";
 export { useParams } from "./browser/react/use-params.js";
 export { useNonce } from "./browser/react/nonce-context.js";
 export type { RouterInstance, RouterNavigateOptions, ReadonlyURLSearchParams, ActionState, ActionLifecycleState, } from "./browser/types.js";

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

@@ -8,12 +8,15 @@
  * The bundler uses the "react-server" export condition to select this file
  * in RSC context, while the regular client.tsx is used in client components.
  */
-export { Outlet, ParallelOutlet, useOutlet, useLoader, ErrorBoundary, type ErrorBoundaryProps, } from "./client.js";
+export { Outlet, ParallelOutlet, useOutlet, type OutletState, useLoader, ErrorBoundary, type ErrorBoundaryProps, } from "./client.js";
 export { useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
 export { createLoader } from "./route-definition.js";
+export { clientUrls } from "./client-urls/client-urls.js";
+export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
 export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
 export { useSearchParams } from "./browser/react/use-search-params.js";
+export type { SearchParamsInit, SetSearchParams, SetSearchParamsOptions, } from "./browser/react/use-search-params.js";
 export { useParams } from "./browser/react/use-params.js";
 export { useNonce } from "./browser/react/nonce-context.js";
 export { useMount } from "./browser/react/use-mount.js";

package/dist/types/decode-loader-results.d.ts

@@ -1,5 +1,42 @@
 import type { ReactNode } from "react";
+/**
+ * Markers for loader-thrown AUTHORITY SIGNALS (notFound()/redirect()) on the
+ * reconstructed read-site error. Siblings of LOADER_ERROR_FALLBACK, routed
+ * differently by StreamedLoaderErrorBoundary: NOT_FOUND renders the
+ * server-rendered not-found UI riding the envelope; REDIRECT triggers a
+ * client replace-navigation to the (server-resolved, same-origin-guarded)
+ * target. Signals are control flow, not failures — they take precedence over
+ * the plain error-fallback path.
+ *
+ * Only decodeLoaderEntry (the read-site path — client components, so the
+ * throw lands in the router-owned boundary; during document SSR, Fizz emits
+ * the Suspense fallback and replays the throw at hydration) throws these.
+ * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
+ * lanes, where a throw would collapse the whole payload — it routes signals
+ * through the errorFallback slot instead (same visual: the slot replaces the
+ * children under OutletProvider).
+ */
+export declare const LOADER_NOT_FOUND_FALLBACK: unique symbol;
+export declare const LOADER_REDIRECT: unique symbol;
 export declare function decodeLoaderResults(resolvedData: any[], loaderIds: string[]): {
     loaderData: Record<string, any>;
     errorFallback: ReactNode;
 };
+/**
+ * Marker property carrying the errorBoundary() fallback on a read-site loader
+ * error. decodeLoaderEntry attaches the pre-rendered boundary node (produced
+ * server-side by loader-resolution) to the thrown error; the router-owned
+ * StreamedLoaderErrorBoundary above the readers (segment-system wires it for
+ * every loader-bearing segment) catches by this marker and renders the
+ * fallback — restoring the build-time errorFallback-swap contract for
+ * streamed loaders. Errors without the marker rethrow to the app's boundaries.
+ */
+export declare const LOADER_ERROR_FALLBACK: unique symbol;
+/**
+ * Streaming useLoader: single-entry decode for read-site resolution. Mirrors
+ * decodeLoaderResults for one result. An error entry throws the reconstructed
+ * error (name/stack/code/cause preserved); when the entry carries an
+ * errorBoundary() fallback, the node rides the throw via
+ * LOADER_ERROR_FALLBACK for the boundary above the readers to render.
+ */
+export declare function decodeLoaderEntry(result: any): any;

package/dist/types/errors.d.ts

@@ -38,6 +38,7 @@ export declare class DataNotFoundError extends Error {
     cause?: unknown;
     constructor(message?: string, options?: ErrorOptions);
 }
+export declare function isDataNotFoundError(error: unknown): error is DataNotFoundError;
 /**
  * Convenience function to throw a DataNotFoundError
  * Shorter syntax for common not-found scenarios

package/dist/types/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./errors.js";
 export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, // Supports params object, path pattern, or route name
-HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, } from "./types.js";
+HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, LoaderOptions, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, } from "./types.js";
 export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams, } from "./search-params.js";
 export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./cache/search-params-filter.js";
 export { createLoader } from "./loader.js";

package/dist/types/loader-redirect.d.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+/**
+ * Executes a loader-thrown redirect() once mounted. The target was resolved
+ * through the soft-redirect same-origin rules server-side
+ * (wrapLoaderWithErrorHandling), so anything absolute AND cross-origin here is
+ * an explicit `{ external: true }` opt-in — those leave via location.replace
+ * (the SPA router cannot cross origins); everything else is a router
+ * replace-navigation. Renders nothing while the navigation commits.
+ *
+ * Own module (not route-content-wrapper.tsx) because BOTH consumers need it
+ * without a cycle: the StreamedLoaderErrorBoundary redirect branch (read-site
+ * throw path) and decodeLoaderResults (aggregate forceAwait/action path, which
+ * runs during the server tree build and cannot throw — it plants this element
+ * in the errorFallback slot instead).
+ */
+export declare function LoaderRedirect({ to, state, }: {
+    to: string;
+    /**
+     * Resolved `redirect(url, { state })` record off the loader-result marker.
+     * Delivered as the redirect navigation's state (same application path as
+     * the ServerRedirect lane in navigation-bridge.ts: buildHistoryState
+     * spreads the `__rsc_ls_*` keys into the target entry). `_skipCache`
+     * matches that lane — a cached segment commit must not skip the re-render
+     * that lets useLocationState read the fresh entry.
+     */
+    state?: Record<string, unknown>;
+}): ReactNode;

package/dist/types/outlet-context.d.ts

@@ -2,9 +2,21 @@ import { type Context, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 export interface OutletContextValue {
     content: ReactNode;
+    /** Unresolved client-route work owned by descendants of this outlet. */
+    pending?: boolean;
     parallel?: ResolvedSegment[];
     segment?: ResolvedSegment;
     loaderData?: Record<string, any>;
+    /**
+     * SPIKE (streaming useLoader): per-loader UNDECODED results keyed by loader
+     * $$id. A value may be a pending Promise (loader still streaming) or an
+     * already-settled result entry. useLoader `use()`es a pending value at the
+     * read site — implicit suspension to the nearest consumer Suspense boundary —
+     * and decodes via decodeLoaderEntry. Populated instead of `loaderData` on
+     * streaming lanes (plain navs, document SSR); forceAwait/action lanes keep
+     * the resolved `loaderData` record.
+     */
+    loaderStreams?: Record<string, unknown>;
     parent?: OutletContextValue | null;
     /** Loading component for Suspense fallback (from segment's loading() definition) */
     loading?: ReactNode;

package/dist/types/outlet-provider.d.ts

@@ -3,10 +3,12 @@ import type { ResolvedSegment } from "./types.js";
 /**
  * Outlet content provider — stores parent context for useLoader chain walking.
  */
-export declare function OutletProvider({ content, parallel, segment, loaderData, children, }: {
+export declare function OutletProvider({ content, parallel, segment, loaderData, loaderStreams, pending, children, }: {
     content: ReactNode;
     parallel?: ResolvedSegment[];
     segment?: ResolvedSegment;
     loaderData?: Record<string, any>;
+    loaderStreams?: Record<string, unknown>;
+    pending?: boolean;
     children: ReactNode;
 }): ReactNode;

package/dist/types/redirect-origin.d.ts

@@ -58,6 +58,10 @@ export declare function resolveSoftRedirectUrl(url: string, requestOrigin: strin
 export declare function markExternalRedirect(response: Response): void;
 /** Read the out-of-band `{ external: true }` brand off a Response. */
 export declare function isExternalRedirect(response: Response): boolean;
+/** Brand a redirect Response with its RESOLVED location-state record. */
+export declare function attachRedirectState(response: Response, state: Record<string, unknown>): void;
+/** Read the resolved location-state record off a redirect Response. */
+export declare function getRedirectState(response: Response): Record<string, unknown> | undefined;
 /**
  * Reserved internal header name. No longer a trust signal -- the external
  * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild

package/dist/types/route-content-wrapper.d.ts

@@ -1,5 +1,39 @@
 import type { ReactNode } from "react";
+import { Component } from "react";
 import type { ResolvedSegment } from "./types.js";
+/**
+ * Router-owned error boundary for read-site loader errors. segment-system
+ * wraps every loader-bearing segment's children in one (unconditionally —
+ * streams and forceAwait lanes alike, so the tree shape never differs between
+ * navigation lanes; see docs/tree-structure.md). A loader error thrown by a
+ * suspending read carries its errorBoundary() fallback via
+ * LOADER_ERROR_FALLBACK (decodeLoaderEntry); this boundary renders that node,
+ * restoring the pre-streaming errorFallback-swap contract.
+ *
+ * Loader-thrown AUTHORITY SIGNALS ride sibling markers:
+ * - LOADER_NOT_FOUND_FALLBACK (notFound()): renders the SERVER-RENDERED
+ *   not-found UI carried on the marker — nearest notFoundBoundary → router
+ *   notFound option — zero extra fetches. Document lane: Fizz emitted the
+ *   Suspense fallback and replays the throw at hydration, so the swap happens
+ *   client-side (the HTTP status was already set opportunistically by the
+ *   producer when the rejection won the flush race).
+ * - LOADER_REDIRECT (redirect()): mounts LoaderRedirect, which navigates.
+ *
+ * Errors without any marker rethrow to the app's own boundaries.
+ */
+export declare class StreamedLoaderErrorBoundary extends Component<{
+    children: ReactNode;
+}, {
+    error: unknown;
+}> {
+    state: {
+        error: unknown;
+    };
+    static getDerivedStateFromError(error: unknown): {
+        error: unknown;
+    };
+    render(): ReactNode;
+}
 /**
  * Stable async wrapper component for route content
  * Using a module-level component ensures React sees the same component reference
@@ -30,6 +64,13 @@ export declare function RouteContentWrapper({ content, fallback, segmentId, }: {
 export interface LoaderBoundaryProps {
     loaderDataPromise: Promise<any[]> | any[];
     loaderIds: string[];
+    /**
+     * SPIKE (streaming useLoader): per-loader UNDECODED results from the
+     * producer (values or individually-pending promises). When present, the
+     * resolver passes them through instead of resolving the aggregate above
+     * the children; useLoader suspends per loader at the read site.
+     */
+    loaderStreams?: Record<string, unknown>;
     fallback?: ReactNode;
     outletKey: string;
     outletContent: ReactNode;
@@ -37,4 +78,4 @@ export interface LoaderBoundaryProps {
     parallel?: ResolvedSegment[];
     children: ReactNode;
 }
-export declare function LoaderBoundary({ loaderDataPromise, loaderIds, fallback, outletKey, outletContent, segment, parallel, children, }: LoaderBoundaryProps): ReactNode;
+export declare function LoaderBoundary({ loaderDataPromise, loaderIds, loaderStreams, fallback, outletKey, outletContent, segment, parallel, children, }: LoaderBoundaryProps): ReactNode;

package/dist/types/route-definition/helpers-types.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { ExtractRouteParams, Handler, PartialCacheOptions, ErrorBoundaryHandler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ResolvedRouteMap, RouteDefinition, ShouldRevalidateFn, TransitionConfig } from "../types.js";
+import type { ExtractRouteParams, Handler, PartialCacheOptions, ErrorBoundaryHandler, LoaderDefinition, LoaderOptions, MiddlewareFn, NotFoundBoundaryHandler, ResolvedRouteMap, RouteDefinition, ShouldRevalidateFn, TransitionConfig } from "../types.js";
 import type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, CacheItem, TransitionItem, UseItems } from "../route-types.js";
 import type { StaticHandlerRef } from "../static-handler.js";
 export type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, CacheItem, } from "../route-types.js";
@@ -208,10 +208,21 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   return <div>{data.name}</div>;
      * }
      * ```
+     * 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 in the same segment keeps streaming.
+     *
+     * ```typescript
+     * loader(ProductLoader, { stream: "navigation" }, () => [cache()]),
+     * loader(RecommendationsLoader),  // still streams behind loading()
+     * ```
+     *
      * @param loaderDef - Loader created with createLoader()
+     * @param optionsOrUse - Delivery options, or the use() callback when passing none
      * @param use - Optional callback for loader-specific revalidation rules
      */
-    loader: <TData>(loaderDef: LoaderDefinition<TData>, use?: () => UseItems<LoaderUseItem>) => LoaderItem;
+    loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => UseItems<LoaderUseItem>), use?: () => UseItems<LoaderUseItem>) => LoaderItem;
     /**
      * Attach a loading component to the current route/layout
      * ```typescript

package/dist/types/router/error-handling.d.ts

@@ -4,7 +4,7 @@
  * Error boundary and not-found boundary handling for Rango.
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { EntryData } from "../server/context";
 import type { ResolvedSegment, ErrorInfo, ErrorBoundaryHandler, NotFoundInfo, NotFoundBoundaryHandler, ErrorPhase, OnErrorCallback } from "../types";
 /**
@@ -69,6 +69,40 @@ export declare function createErrorSegment(errorInfo: ErrorInfo, fallback: React
 export declare function createNotFoundInfo(error: {
     message: string;
 }, segmentId: string, segmentType: NotFoundInfo["segmentType"], pathname?: string): NotFoundInfo;
+/** Router-level `createRouter({ notFound })` option shape. */
+export type NotFoundComponentOption = ReactNode | ((props: {
+    pathname: string;
+}) => ReactNode);
+/**
+ * Pick the effective notFound fallback: nearest `notFoundBoundary`, else the
+ * router-level `notFound` option, else a plain default.
+ *
+ * The router option is resolved ONLY when no nearer boundary won — it may be a
+ * user render function doing arbitrary work, so computing it eagerly (as three
+ * earlier copies of this policy did) burned a full render on every 404 that a
+ * boundary was going to handle anyway.
+ *
+ * Every 404 origin routes through here — segment resolution
+ * (`segment-resolution/helpers.ts`), loader-thrown `notFound()`
+ * (`loader-resolution.ts`), and the unmatched-route path (`rsc/handler.ts`) —
+ * so the default text and the boundary-wins precedence cannot drift apart.
+ */
+export declare function resolveNotFoundFallback(boundary: ReactNode | NotFoundBoundaryHandler | null | undefined, notFoundComponent: NotFoundComponentOption | undefined, pathname: string | undefined): ReactNode | NotFoundBoundaryHandler;
+/**
+ * The router-level default alone: `createRouter({ notFound })` rendered, or the
+ * plain fallback node. Separate from {@link resolveNotFoundFallback} for the
+ * unmatched-route path, which has no entry chain and therefore no boundary to
+ * consult — it gets a `ReactNode` back rather than a possible handler.
+ */
+export declare function resolveDefaultNotFound(notFoundComponent: NotFoundComponentOption | undefined, pathname: string | undefined): ReactNode;
+/**
+ * Invoke a notFound fallback that may be a boundary handler or a plain node.
+ *
+ * Callers that cannot propagate a throw (the loader envelope) wrap this in
+ * their own try/catch; it deliberately does not swallow, so a throwing boundary
+ * still surfaces where that is the correct behavior.
+ */
+export declare function renderNotFoundFallback(fallback: ReactNode | NotFoundBoundaryHandler, notFoundInfo: NotFoundInfo): ReactNode;
 /**
  * Create a notFound segment with the fallback component
  * Renders the fallback with not found info

package/dist/types/router/intercept-resolution.d.ts

@@ -19,6 +19,18 @@ export declare function evaluateInterceptWhen(intercept: InterceptEntry, selecto
  * Find an intercept for the target route by walking up the entry chain.
  * Returns the first (innermost) matching intercept along with the entry that defines it.
  */
+/**
+ * Collect every intercept TARGET route name reachable from an origin entry —
+ * the same chain walk findInterceptForRoute() performs when this location is
+ * the navigation origin. Shipped in payload metadata so the browser-local
+ * clientUrls matcher can DECLINE its optimistic presentation for targets an
+ * intercept would claim (the committed result keeps the origin page + modal,
+ * so destination loading would flash and revert). Deliberately includes
+ * `when`-conditional intercepts: selectors need the live navigation context,
+ * so the browser stays conservative — worst case a non-intercepted navigation
+ * loses its optimistic loading, never the reverse.
+ */
+export declare function collectInterceptTargetNames(fromEntry: EntryData | null): string[];
 export declare function findInterceptForRoute(targetRouteKey: string, fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean): {
     intercept: InterceptEntry;
     entry: EntryData;

package/dist/types/router/loader-resolution.d.ts

@@ -5,7 +5,7 @@
  */
 import type { ReactNode } from "react";
 import type { EntryData } from "../server/context";
-import type { HandlerContext, LoaderDataResult, ErrorBoundaryHandler, ErrorInfo } from "../types";
+import type { HandlerContext, LoaderDataResult, ErrorBoundaryHandler, ErrorInfo, NotFoundBoundaryHandler } from "../types";
 /**
  * Internal callback signature for loader error notifications.
  * This is a simplified callback for internal use in wrapLoaderWithErrorHandling.
@@ -21,12 +21,34 @@ export type LoaderErrorCallback = (error: unknown, context: {
  * Catches errors and converts them to LoaderDataResult objects that include
  * error info and pre-rendered fallback UI when an error boundary is available.
  *
+ * Loader-thrown SIGNALS are routed before error handling — they are control
+ * flow, not failures (onError is not invoked for them):
+ * - notFound(): the not-found UI is resolved and rendered HERE, server-side
+ *   (nearest notFoundBoundary → router notFound option → default), exactly
+ *   like the consumption lane (segment-resolution/helpers.ts), and rides the
+ *   envelope's `fallback` — the client swaps with zero extra fetches. The
+ *   response status is opportunistically set to 404 via the request stub: if
+ *   the rejection settles before the document Response is constructed the
+ *   status is a real 404; after, the stub write is inert (streamed fix-up
+ *   only). Nav-lane payloads are 200 either way — the client owns 404
+ *   presentation there.
+ * - redirect() (thrown 3xx Response): the target is resolved through the
+ *   soft-redirect same-origin rules NOW so unsafe targets never leave the
+ *   server; the client navigates when the entry decodes. No document-lane
+ *   302 — pre-stream redirect authority belongs to middleware (doctrine);
+ *   a loader redirect is always a client-side navigate.
+ *
  * @param onError - Optional callback invoked when loader errors occur.
  *   This has a simplified signature for internal use - the caller (typically
  *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
  *   OnErrorCallback with complete request context (request, url, env, etc.).
  */
-export declare function wrapLoaderWithErrorHandling<T>(promise: Promise<T>, entry: EntryData, segmentId: string, pathname: string, findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null, createErrorInfo: (error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]) => ErrorInfo, onError?: LoaderErrorCallback): Promise<LoaderDataResult<T>>;
+export declare function wrapLoaderWithErrorHandling<T>(promise: Promise<T>, entry: EntryData, segmentId: string, pathname: string, findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null, createErrorInfo: (error: unknown, segmentId: string, segmentType: ErrorInfo["segmentType"]) => ErrorInfo, onError?: LoaderErrorCallback, notFoundDeps?: {
+    findNearestNotFoundBoundary: (entry: EntryData | null) => ReactNode | NotFoundBoundaryHandler | null;
+    notFoundComponent?: ReactNode | ((props: {
+        pathname: string;
+    }) => ReactNode);
+}): Promise<LoaderDataResult<T>>;
 /**
  * Set up the use() method on handler context to access loaders and handles.
  *

package/dist/types/router/revalidation.d.ts

@@ -43,10 +43,17 @@ interface EvaluateRevalidationOptions<TEnv> {
      * reason flows into the trace. Callers use this when client-knowledge
      * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
      * instead of the params/method-based heuristic.
+     *
+     * `floor` makes a `true` seed a guarantee rather than a suggestion: user fns
+     * may raise the decision but never lower it. Set it when the segment has no
+     * client-side content to fall back on, so a `false` would render nothing
+     * instead of keeping a cached copy — see the parallel-slot call site in
+     * segment-resolution/revalidation.ts.
      */
     defaultOverride?: {
         value: boolean;
         reason: string;
+        floor?: boolean;
     };
 }
 /**

package/dist/types/router/route-trie-builder.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Runtime Route Trie Construction
+ *
+ * Builds a serializable trie from route manifest data for O(path_length)
+ * route matching at runtime.
+ */
+/**
+ * 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 route 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;

package/dist/types/router/router-interfaces.d.ts

@@ -2,6 +2,7 @@ import type { ComponentType } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
@@ -27,6 +28,11 @@ export interface RouterRequestInput<TEnv, TVars = DefaultVars> {
     vars?: Partial<TVars>;
     ctx?: ExecutionContext;
 }
+/** One materialized UrlPatterns registration and its live router mount index. */
+export interface UrlPatternMount<TEnv = any> {
+    readonly patterns: UrlPatterns<TEnv, any>;
+    readonly mountIndex: number;
+}
 /**
  * Merge route patterns with response types into a single route map.
  * Routes with response types get { path, response } objects; others stay as strings.
@@ -79,6 +85,12 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```
      */
     routes<T extends UrlPatterns<any, any, any>>(patterns: T & EnvCompatible<T, TEnv>): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]> : Record<string, string>)>;
+    /**
+     * Pure-client mounting shorthand: normalizes to a root include in the
+     * canonical urls() tree (`include("/", definition, { name: "" })`) — same
+     * lazy materialization as mounting through include() yourself.
+     */
+    routes<T extends ClientUrlPatterns<any>>(patterns: T): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? NonNullable<T["_routes"]> : Record<string, string>)>;
     routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
     /**
      * Add global middleware that runs on all routes
@@ -184,7 +196,15 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * `urls<{ DB }>()` cannot be mounted on a `createRouter<{}>()`.
      */
     routes<T extends UrlPatterns<any, any, any>>(patterns: T & EnvCompatible<T, TEnv>): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]> : Record<string, string>)>;
+    /**
+     * Pure-client mounting shorthand: normalizes to a root include in the
+     * canonical urls() tree (`include("/", definition, { name: "" })`) — same
+     * lazy materialization as mounting through include() yourself.
+     */
+    routes<T extends ClientUrlPatterns<any>>(patterns: T): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? NonNullable<T["_routes"]> : Record<string, string>)>;
     routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
+    /** Materialized UrlPatterns registrations in registration order. */
+    readonly __urlpatternMounts: readonly UrlPatternMount<TEnv>[];
     /**
      * Add global middleware that runs on all routes
      */

package/dist/types/router/segment-resolution/helpers.d.ts

@@ -7,7 +7,7 @@
  * - Layout handler resolution with static fallback
  * - Error boundary segment creation
  */
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import type { EntryData } from "../../server/context";
 import type { ResolvedSegment, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";

package/dist/types/router/trie-matching.d.ts

@@ -4,7 +4,7 @@
  * Walks the pre-built trie by path segments in O(path_length) time.
  * Falls back to null when no match is found (caller uses regex fallback).
  */
-import type { TrieNode, NegotiateVariant } from "../build/route-trie.js";
+import type { TrieNode, NegotiateVariant } from "./route-trie-builder.js";
 export interface TrieMatchResult {
     /** Route name */
     routeKey: string;

package/dist/types/rsc/manifest-init.d.ts

@@ -1,13 +1,13 @@
 /**
  * Router Manifest Initialization
  *
- * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
- * where the manifest exists but the trie needs rebuilding.
+ * Builds a fresh route trie from every registered URL-pattern mount for
+ * dev/HMR scenarios where the manifest exists but the trie needs rebuilding.
  */
 /**
- * Build a fresh route trie from router.urlpatterns and store it in the
- * per-router cache. Also sets the per-router manifest and merges into
- * the global manifest for reverse()/href().
+ * Build a fresh route trie from the router's URL-pattern mounts and store it in
+ * the per-router cache. Also sets the per-router manifest and merges into the
+ * global manifest for reverse()/href().
  *
  * Called when manifest data may exist but the per-router trie is missing,
  * which happens in dev mode after HMR: the virtual module sets the manifest

package/dist/types/rsc/shell-capture.d.ts

@@ -273,6 +273,15 @@ export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>,
  */
 export interface ShellCaptureDescriptor {
     key: string;
+    /**
+     * The key's search portion (shellSearchSeed: `?`-prefixed sorted search,
+     * cache.searchParams filter applied, or ""). Seeds the capture render's SSR
+     * store so static-part `useSearchParams` reads bake markup consistent with
+     * the shell's own key; the resume pass derives the identical string from
+     * the HIT request. Computed next to the key so the two cannot drift.
+     * Omitted (build-time bare-pathname captures) = search-less, same as "".
+     */
+    searchSeed?: string;
     /**
      * The RSC handler's build version (HandlerContext.version), stamped into the
      * stored entry as ShellCacheEntry.buildVersion — the serve-side

package/dist/types/rsc/shell-serve.d.ts

@@ -94,6 +94,17 @@ export declare function resolvePprConfig(entry: EntryData | undefined | null): R
  * and lookup makes every shell request a permanent miss.
  */
 export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
 /**
  * Version gates for a stored shell: reactVersion AND buildVersion must both
  * match the running server. The postponed blob encodes hole positions against