@rangojs/router 0.5.1 → 0.6.0

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

@@ -0,0 +1,144 @@
+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">;
+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.
+     */
+    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 {};

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/handles/is-thenable.d.ts

@@ -1,8 +1,6 @@
 /**
- * Single thenable predicate for the resolve-by-default handle machinery
- * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
- * handle entries are deferred (`Promise`) values to await before any consumer
- * sees them, and which pass through verbatim.
+ * Shared thenable predicate for framework orchestration. It decides which values
+ * participate in promise lifecycles and which pass through synchronously.
  *
  * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
  * `"then" in obj` membership check, so a non-promise carrying a `then` field

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.backup/build/route-trie.d.ts → types/router/route-trie-builder.d.ts}

@@ -1,10 +1,9 @@
 /**
- * Build-time Route Trie Construction
+ * Runtime Route Trie Construction
  *
- * Builds a serializable trie from the route manifest for O(path_length)
+ * Builds a serializable trie from route manifest data for O(path_length)
  * route matching at runtime.
  */
-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
@@ -49,7 +48,7 @@ export interface TrieNode {
         n: string;
         c: TrieNode;
     };
-    /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
+    /** Suffix-param children keyed by suffix (e.g., ".html" -> { n: "productId", c: ... }) */
     xp?: Record<string, {
         n: string;
         c: TrieNode;
@@ -66,7 +65,7 @@ export interface TrieNode {
     };
 }
 /**
- * Build a route trie from build-time manifest data.
+ * 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
@@ -76,14 +75,3 @@ export interface TrieNode {
  * @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;
-/**
- * Build a per-router trie from a generated manifest. This is the single
- * construction path shared by build/discovery (discover-routers.ts, serialized
- * into the production chunk) and the dev/HMR runtime rebuild
- * (rsc/manifest-init.ts). Keeping one code path is what guarantees the dev
- * runtime trie and the production serialized trie are byte-for-byte identical.
- *
- * Returns null when the manifest has no routes, matching the prior guard at
- * both call sites.
- */
-export declare function buildPerRouterTrie(manifest: FullManifest): TrieNode | null;