@rangojs/router 0.5.2 → 0.6.0

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

@@ -33,12 +33,29 @@ export interface RscPayload {
         /** Merged route params from the matched route */
         params?: Record<string, string>;
         slots?: Record<string, SlotState>;
+        /**
+         * Intercept TARGET route names reachable from this location as a
+         * navigation origin (see MatchResult.interceptTargets). The browser-local
+         * clientUrls matcher declines optimistic presentation for these.
+         */
+        interceptTargets?: string[];
         /** Root layout component for browser-side re-renders (client component reference) */
         rootLayout?: React.ComponentType<{
             children: React.ReactNode;
         }>;
         /** Handle data accumulated across route segments (async generator that yields on each push) */
         handles?: AsyncGenerator<HandleData, void, unknown>;
+        /**
+         * Document-lane late handle channel: full-state updates for pushes landing
+         * AFTER the handler barrier (streaming loader bodies writing handles
+         * mid-body). `handles` above is drained to completion in blocking
+         * positions (SSR seed, pre-hydration), so late pushes need this separate
+         * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+         * Empty/instantly-complete when no auxiliary-lane work is pending at the
+         * handler barrier. Full payloads only — partial payloads' `handles`
+         * generator streams to full settle already.
+         */
+        handlesLate?: AsyncGenerator<HandleData, void, unknown>;
         /** RSC version string for cache invalidation */
         version?: string;
         /** Cloudflare dev worker generation used for stale-document convergence. */
@@ -147,6 +164,17 @@ export interface SSRRenderOptions {
      * - `"allReady"` — await `stream.allReady` before returning.
      */
     streamMode?: import("../router/router-options.js").SSRStreamMode;
+    /**
+     * The live request's query string (`url.search`, `?`-prefixed or empty).
+     * Seeds the SSR navigation store so `useSearchParams` (and
+     * `useNavigation().location`) carry real values during document renders.
+     * Out-of-band by design — never payload metadata, which cached/prerendered
+     * payloads replay; search is not route identity. The build-time prerender
+     * pass passes none — build shells capture bare pathnames and serve
+     * search-less requests only (runtime ppr captures seed the shell key's
+     * search; see ShellCaptureOptions.search in the SSR entry).
+     */
+    search?: string;
 }
 /**
  * SSR module interface for HTML rendering
@@ -164,6 +192,7 @@ export interface SSRModule {
     captureShellHTML?: (rscStream: ReadableStream<Uint8Array>, options: {
         quiesce: Promise<void>;
         maxWaitMs?: number;
+        search?: string;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;
@@ -179,6 +208,7 @@ export interface SSRModule {
     resumeShellHTML?: (rscStream: ReadableStream<Uint8Array>, options: {
         postponed: string | null;
         nonce?: string;
+        search?: string;
     }) => Promise<ReadableStream<Uint8Array>>;
 }
 /**

package/dist/types/segment-system.d.ts

@@ -17,6 +17,8 @@ export interface RenderSegmentsOptions {
      * from cache without showing loading skeletons.
      */
     forceAwait?: boolean;
+    /** Seeded descendant client-route pending state for testing. */
+    outletPending?: boolean;
     /**
      * Intercept segments to inject into the tree.
      * These are parallel segments from intercept routes that need to be

package/dist/types/server/context.d.ts

@@ -82,6 +82,16 @@ export type LoaderEntry = {
     revalidate: ShouldRevalidateFn<any, any>[];
     /** Cache config for this specific loader (loaders are NOT cached by default) */
     cache?: EntryCacheConfig;
+    /**
+     * Document renders await this loader before segment resolution returns
+     * (loader(Def, { stream: "navigation" })), so its data, handle pushes, and
+     * thrown notFound()/redirect() deterministically precede first flush.
+     * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
+     * per-isSSR (router/manifest.ts cache key), so the flag is already
+     * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+     * appears on navigation-lane entries.
+     */
+    awaitBeforeFlush?: true;
 };
 /**
  * Segments state for intercept context

package/dist/types/server/handle-store.d.ts

@@ -49,6 +49,24 @@ export interface HandleStore {
      * to onError and telemetry.
      */
     onError?: (error: Error) => void;
+    /**
+     * Track a promise on the AUXILIARY (loader) settlement lane. Aux tracking
+     * keeps the store OPEN for pushes (a mid-body `ctx.handle(H)(...)` from a
+     * streaming loader is legal until this lane drains) WITHOUT joining
+     * `settled` — the handler barrier that rendered()-readers, the document
+     * handle snapshot, and prerender/cache collection wait on. Two lanes exist
+     * because loader bodies stream: joining them to `settled` would block SSR
+     * markup and hydration on the slowest loader (ssr-root.tsx and
+     * rsc-router.tsx both drain the document handle stream in blocking
+     * positions), and would self-deadlock any loader awaiting ctx.rendered().
+     */
+    trackAuxiliary<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * Promise that resolves when the store is sealed AND BOTH lanes (handler +
+     * auxiliary) have drained. Late-push legality and default stream completion
+     * key on this, not on `settled`.
+     */
+    readonly fullySettled: Promise<void>;
     /**
      * Push handle data for a specific handle and segment.
      * Multiple pushes to the same handle/segment accumulate in an array.
@@ -57,15 +75,28 @@ export interface HandleStore {
     push(handleName: string, segmentId: string, data: unknown): void;
     /**
      * Get all collected handle data after all handlers have settled.
-     * Waits for `settled`, then returns the finalized data.
+     * Waits for `settled` (handler lane), then returns the data at that point.
      */
     getData(): Promise<HandleData>;
     /**
      * Get an async iterator that yields handle data on each push.
-     * The iterator completes when all handlers have settled.
+     * Completes at the chosen settlement barrier: "fullySettled" (default —
+     * nav/action payloads, whose consumer applies each yield progressively) or
+     * "settled" (the document lane, whose consumers drain to completion in
+     * blocking positions and must not wait on loader bodies).
      * Each yield contains the full accumulated state (not just the delta).
+     * Safe for concurrent consumers (per-consumer version cursor).
+     */
+    stream(until?: "settled" | "fullySettled"): AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late channel: yields full-state updates for pushes that
+     * land AFTER the handler barrier (streaming loader bodies), completing at
+     * fullySettled. Returns without yielding when the auxiliary lane is empty
+     * by the time `settled` resolves. The client consumes this post-hydration
+     * (rsc-router.tsx) and merges via the same application path as nav-lane
+     * progressive handle updates.
      */
-    stream(): AsyncGenerator<HandleData, void, unknown>;
+    streamLate(): AsyncGenerator<HandleData, void, unknown>;
     /**
      * Get handle data for a specific segment (for caching).
      * Returns data in format: { handleName: [values...] }

package/dist/types/server/request-context.d.ts

@@ -507,6 +507,16 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * rendered() and a handler already awaits it, we can detect the deadlock.
      */
     _handlerLoaderDeps?: Set<string>;
+    /**
+     * @internal Loader IDs ($$id) whose entries carry `awaitBeforeFlush`
+     * (loader(Def, { stream: "navigation" })): segment resolution awaits these
+     * before returning, so the render barrier cannot resolve until they settle.
+     * rendered() checks this set to fail fast — a flagged loader awaiting the
+     * barrier is a guaranteed cycle, not a race. Registered by resolveLoaders
+     * (fresh.ts) before loader kickoff; only ever populated on document renders
+     * (the flag is stamped per-isSSR at DSL evaluation).
+     */
+    _awaitBeforeFlushLoaderIds?: Set<string>;
     /**
      * @internal Cached HandleData snapshot built at barrier resolution time.
      * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
@@ -588,7 +598,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/server.d.ts

@@ -13,3 +13,4 @@ export { registerRouteMap, setCachedManifest, clearCachedManifest, clearAllRoute
 export { registerLoaderById, setLoaderImports, } from "./server/loader-registry.js";
 export { createRequestContext, type CreateRequestContextOptions, } from "./server/request-context.js";
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
+export { clearClientUrlProjections, setClientUrlProjection, type ClientUrlProjection, } from "./client-urls/server-projection.js";

package/dist/types/ssr/index.d.ts

@@ -82,6 +82,14 @@ export interface SSRRenderOptions {
      * - `"allReady"` — await `stream.allReady` before returning.
      */
     streamMode?: import("../router/router-options.js").SSRStreamMode;
+    /**
+     * The live request's query string (`?`-prefixed or empty). Seeds the SSR
+     * navigation store location so `useSearchParams` carries real values
+     * during document renders. Absent on the build-time prerender pass —
+     * build shells capture bare pathnames and serve search-less requests
+     * only (runtime captures own the search variants, seeded per key).
+     */
+    search?: string;
 }
 /**
  * SSR dependencies from external packages
@@ -169,6 +177,13 @@ interface ShellCaptureOptions {
     quiesce: Promise<void>;
     /** Upper bound on how long to wait for `quiesce`. Default SHELL_CAPTURE_MAX_WAIT_MS. */
     maxWaitMs?: number;
+    /**
+     * The SHELL KEY's search string (`?`-prefixed, sorted, cache.searchParams
+     * filter applied — shellSearchSeed in rsc/shell-serve.ts), seeding the SSR
+     * store so static-part `useSearchParams` reads bake markup consistent with
+     * the shell's own key. MUST equal the resume pass's seed for the same key.
+     */
+    search?: string;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;
@@ -188,6 +203,13 @@ interface ShellResumeOptions {
     postponed: string | null;
     /** Nonce for CSP. */
     nonce?: string;
+    /**
+     * The SHELL KEY's search string — same derivation as the capture pass
+     * (shellSearchSeed). A HIT shares the capture's key, so seeding the same
+     * string keeps the resume tree identical to the captured tree above the
+     * postponed holes.
+     */
+    search?: string;
 }
 /**
  * Create an SSR handler that converts RSC streams to HTML.

package/dist/types/ssr/ssr-root.d.ts

@@ -48,6 +48,16 @@ export interface SsrRootOptions {
      * they postpone below the root.
      */
     onPayloadSettled?: () => void;
+    /**
+     * The query string seeding the SSR store location (`?`-prefixed or
+     * empty), so `useSearchParams`/`useNavigation` carry real values during
+     * document renders. Live fizz passes the request's raw search. The shell
+     * capture and resume passes pass the SHELL KEY's search (sorted,
+     * cache.searchParams filter applied — search is part of shell identity):
+     * a HIT shares the capture's key, so both passes seed the SAME string and
+     * the resume tree matches the captured tree above the postponed holes.
+     */
+    search?: string;
 }
 /**
  * Build the closure component that deserializes the Flight payload, consumes

package/dist/types/testing/dom.entry.d.ts

@@ -3,7 +3,7 @@
  *
  * Component-render testing: `renderRoute`, the React-Testing-Library-style stub
  * for client components that read router context (useParams / useReverse /
- * Outlet / useNavigation / useLoader).
+ * Outlet / useOutlet / useNavigation / useLoader).
  *
  * Separate from the main `@rangojs/router/testing` barrel so unit suites that
  * only test loaders, middleware, or `dispatch` never reference React, the

package/dist/types/testing/render-route.d.ts

@@ -19,18 +19,19 @@
  *     props crossing the RSC boundary), loader execution on the server,
  *     middleware, or handler ordering. Those are renderServerTree / renderHandler
  *     / e2e territory.
- *   - Loader data, location state, and handle output are SEEDED directly into
- *     client context (see the `loaders` / `locationState` / `handles` options) —
- *     nothing is executed on the server. This exercises the read path
- *     (useLoader / useLocationState / useHandle from context), not the run path.
+ *   - Loader data, location state, handle output, and outlet pending state are
+ *     SEEDED directly into client context (see the `loaders` / `locationState` /
+ *     `handles` / `outletPending` options) — nothing is executed on the server.
+ *     This exercises the context read path, not the run path.
  *   - navigate() commits synchronously, so it does NOT drive the navigation
  *     lifecycle: useNavigation().state, useLinkStatus().pending, and
  *     useAction().state stay "idle". Assert pending/loading/submitting transition
  *     states with renderServerTree / e2e instead (navigate() warns once if used).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
- * useRouter, usePathname, useSearchParams, Outlet nesting, useLoader /
- * useFetchLoader (seeded data), useLocationState (seeded), and useHandle (seeded).
+ * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
+ * descendant pending state, useLoader/useFetchLoader (seeded data),
+ * useLocationState (seeded), and useHandle (seeded).
  * Basename-mounted apps: pass the `basename` option so useRouter().basename,
  * <Link> prefixing, and useMount/useHref resolve against the mount prefix
  * (without it they resolve at the root "/"). For an include("/shop", ...)
@@ -96,6 +97,15 @@ export interface RenderRouteOptions {
      * the read path is exercised without executing any loader.
      */
     loaderData?: Record<string, unknown>;
+    /**
+     * Descendant client-route pending state to seed into each synthetic segment's
+     * production OutletProvider, so `useOutlet().pending` can be tested alongside
+     * `useOutlet().content`. Defaults to false.
+     *
+     * This is a seeded outlet-context value only. It does not model arbitrary
+     * Suspense, navigation, or action pending state.
+     */
+    outletPending?: boolean;
     /**
      * Loaders to seed by REFERENCE — the robust way to test a component that calls
      * `useLoader(loader)`. A real `createLoader()` handle has an empty `$$id` in a

package/dist/types/testing/run-loader.d.ts

@@ -52,6 +52,7 @@ export type TestLoaderContext<TEnv = any> = Omit<LoaderContext<any, TEnv>, "reve
     reverse: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string;
     get: {
         <T>(contextVar: ContextVar<T>): T | undefined;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
         <T = unknown>(key: string): T | undefined;
     };
 };
@@ -182,5 +183,13 @@ export interface RunLoaderResult<T> {
     locationState: Record<string, unknown>;
     /** The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). */
     stateCookieName: string;
+    /**
+     * Handle writes the loader made via `ctx.use(SomeHandle)({...})`, in push
+     * order. A `.defer()` resolver's value is recorded when the resolver runs.
+     */
+    handlePushes: Array<{
+        handle: Handle<any, any>;
+        value: unknown;
+    }>;
 }
 export declare function runLoaderResult<T>(loader: RunnableLoader<T>, opts?: RunLoaderOptions): Promise<RunLoaderResult<T>>;

package/dist/types/types/boundaries.d.ts

@@ -63,6 +63,28 @@ export type LoaderDataResult<T = unknown> = {
     ok: false;
     error: ErrorInfo;
     fallback: ReactNode | null;
+    /**
+     * Loader threw notFound() (DataNotFoundError). `fallback` carries the
+     * SERVER-RENDERED not-found UI (nearest notFoundBoundary → router
+     * notFound option → default), so the client swaps to 404 presentation
+     * with zero extra round trips. Routed by decodeLoaderEntry via
+     * LOADER_NOT_FOUND_FALLBACK, not the error-fallback marker.
+     */
+    notFound?: true;
+    /**
+     * Loader threw redirect(...) (a 3xx Response). `to` is resolved through
+     * the soft-redirect same-origin rules BEFORE leaving the server
+     * (resolveSoftRedirectUrl), so unsafe targets never reach the wire. The
+     * client navigates (replace) when the entry decodes. `state` is the
+     * resolved `redirect(url, { state })` record (`__rsc_ls_*` keys) — it
+     * travels on the marker because a streaming loader settles after
+     * payload metadata flushed; the redirect navigation merges it at the
+     * target entry.
+     */
+    redirect?: {
+        to: string;
+        state?: Record<string, unknown>;
+    };
 };
 export declare function isLoaderDataResult(value: unknown): value is LoaderDataResult;
 export interface NotFoundInfo {

package/dist/types/types/index.d.ts

@@ -6,6 +6,6 @@ export { isLoaderDataResult } from "./boundaries.js";
 export type { MiddlewareFn, ScopedRouteMap, Handler, HandlerContext, InternalHandlerContext, GenericParams, RevalidateParams, ShouldRevalidateFn, ActionRef, RouteKeys, ExtractRouteParams, HandlersForRouteMap, Revalidate, Middleware, } from "./handler-context.js";
 export type { ViewTransitionClass, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ResolvedSegment, SegmentMetadata, SlotState, RootLayoutProps, MatchResult, } from "./segments.js";
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
-export type { LoaderContext, LoaderFn, FetchableLoaderOptions, LoadOptions, LoaderDefinition, } from "./loader-types.js";
+export type { LoaderContext, LoaderFn, FetchableLoaderOptions, LoaderOptions, LoadOptions, LoaderDefinition, } from "./loader-types.js";
 export type { CacheContext, CacheOptions, PartialCacheOptions, EntryCacheConfig, } from "./cache-types.js";
 export type { ErrorPhase, OnErrorContext, OnErrorCallback, } from "./error-types.js";

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

@@ -1,5 +1,6 @@
 import type { ContextVar } from "../context-var.js";
 import type { Handle } from "../handle.js";
+import type { HandlePush } from "../defer.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
@@ -41,24 +42,50 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      */
     routeParams: Record<string, string>;
     search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
+    /**
+     * Read a context variable — or READ collected handle data after
+     * `await ctx.rendered()` (the rendered-barrier contract; handle reads
+     * moved here from ctx.use(handle), which is now the write).
+     */
     get: {
         <T>(contextVar: ContextVar<T>): T | undefined;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
     } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
     /**
-     * Access another loader's data, or read handle data after rendered().
+     * Access another loader's data, or WRITE handle data (meta, breadcrumbs, …)
+     * — handler parity: `ctx.use(Meta)({ title })` pushes exactly like it does
+     * in a handler. Handle READS live on `ctx.get(handle)` (after rendered()).
      *
      * For loaders: returns a promise (loaders run in parallel).
-     * For handles: returns collected data (only after `await ctx.rendered()`).
+     * For handles: returns the push function, legal for the whole body,
+     * streaming loaders included. Delivery is async by the race model: pushes
+     * that settle before the handler barrier ride the SSR handle snapshot;
+     * later ones stream to the client and apply post-hydration (document lane)
+     * or progressively (navigation/action lanes). To guarantee a loader's
+     * handles are in the SSR'd document, register it as
+     * `loader(Def, { stream: "navigation" })` so the document render awaits it
+     * (see {@link LoaderOptions}).
+     *
+     * @example
+     * ```typescript
+     * export const ProductLoader = createLoader(async (ctx) => {
+     *   "use server";
+     *   const product = await getProduct(ctx.params.slug);
+     *   ctx.use(Meta)({ title: product.name });
+     *   ctx.use(Breadcrumbs)({ label: product.name });
+     *   return product;
+     * });
+     * ```
      */
     use: {
         <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
-        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): TAccumulated;
+        <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): HandlePush<TData>;
     };
     /**
      * **Experimental.** Wait for all non-loader segments to settle.
      *
      * After the returned promise resolves, handle data is available via
-     * `ctx.use(handle)`. Supported in DSL loaders, including on streaming
+     * `ctx.get(handle)`. Supported in DSL loaders, including on streaming
      * trees that use `loading()` — the barrier waits for the streaming
      * handlers to finish pushing before it resolves. Throws if called from a
      * handler-invoked loader, or if a handler is already awaiting this loader
@@ -70,7 +97,7 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * const PricesLoader = createLoader(async (ctx) => {
      *   "use server";
      *   await ctx.rendered();
-     *   const products = ctx.use(Products); // reads handle data
+     *   const products = ctx.get(Products); // reads handle data
      *   return pricing.getLive(products.map(p => p.id));
      * });
      * ```
@@ -121,6 +148,31 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
  * ```
  */
 export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = DefaultEnv> = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
+/**
+ * Delivery mode for a DSL-registered loader: `loader(Def, { stream })`.
+ *
+ * Default (omitted): the loader streams on every render. Its data, its
+ * `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws may land
+ * AFTER the document Response is constructed, so none of them are guaranteed to
+ * be in the SSR'd HTML.
+ *
+ * `"navigation"` narrows streaming to client navigations only: on a DOCUMENT
+ * request the loader is awaited before first flush. `useLoader` still suspends,
+ * but on an already-settled promise, so no fallback paints. This is the
+ * SSR-completeness opt-in — the name is about WHERE streaming still applies, not
+ * about disabling it. Choose it when the loader feeds something that must exist
+ * in the document: `<head>` meta via a handle, or a real 404 status (an awaited
+ * `notFound()` deterministically precedes Response construction, where the
+ * streamed default only wins that race opportunistically). It does NOT change
+ * PPR capture behavior: capture renders mask loaders and skip this await.
+ *
+ * Scoped per LOADER, not per segment: a baked loader alongside a deliberately
+ * dynamic sibling awaits only itself, and the sibling keeps streaming behind its
+ * `loading()`/Suspense boundary.
+ */
+export type LoaderOptions = {
+    stream?: "navigation";
+};
 /**
  * Options for fetchable loaders
  *

package/dist/types/types/segments.d.ts

@@ -221,6 +221,13 @@ export interface MatchResult {
      * Slots are used for intercepting routes during soft navigation
      */
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable when this location is a navigation
+     * origin (chain walk of the matched entry, when-conditionals included).
+     * Shipped in payload metadata so the browser-local clientUrls matcher can
+     * decline its optimistic presentation for targets an intercept would claim.
+     */
+    interceptTargets?: string[];
     /**
      * Redirect URL for trailing slash normalization.
      * When set, the RSC handler should return a 308 redirect to this URL

package/dist/types/urls/path-helper-types.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, PartialCacheOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
+import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, LoaderDefinition, LoaderOptions, MiddlewareFn, NotFoundBoundaryHandler, PartialCacheOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
 import type { AllUseItems, TypedLayoutItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ResponseRouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, TypedCacheItem, TransitionItem, TypedTransitionItem, TypedRouteItem, TypedIncludeItem, UseItems } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import type { PrerenderHandlerDefinition, PassthroughHandlerDefinition } from "../prerender.js";
@@ -7,6 +7,7 @@ import type { StaticHandlerDefinition, StaticHandlerRef } from "../static-handle
 import type { ResponseHandler, ResponseHandlerContext, TextResponseHandler } from "./response-types.js";
 import type { UnnamedRoute, LocalOnlyInclude, PathOptions, UrlPatterns, IncludeOptions } from "./pattern-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 /**
  * Base path function signature for defining routes with URL patterns.
  */
@@ -45,7 +46,7 @@ type IncludeResolved<TEnv, TRoutes extends Record<string, any>, TResponses exten
     default: UrlPatterns<TEnv, TRoutes, TResponses>;
 };
 /** include() argument: an eager `urls()` value or an async provider thunk. */
-export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
+export type IncludeArg<TEnv, TRoutes extends Record<string, any>, TResponses extends Record<string, unknown>> = UrlPatterns<TEnv, TRoutes, TResponses> | ClientUrlPatterns<TRoutes> | (() => IncludeResolved<TEnv, TRoutes, TResponses> | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
 /**
  * Base include function signature.
  */
@@ -145,9 +146,14 @@ export type PathHelpers<TEnv> = {
      */
     revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
     /**
-     * Attach a data loader to the current route/layout
+     * Attach a data loader to the current route/layout.
+     *
+     * 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.
      */
-    loader: <TData>(loaderDef: LoaderDefinition<TData>, use?: () => LoaderUseItem[]) => LoaderItem;
+    loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]), use?: () => LoaderUseItem[]) => LoaderItem;
     /**
      * Attach a loading component to the current route/layout
      */

package/dist/types/vite/discovery/client-urls-projection.d.ts

@@ -0,0 +1,53 @@
+import { type ClientUrlProjection } from "../../client-urls/server-projection.js";
+import type { DiscoveryState } from "./state.js";
+interface ClientUrlSsrEnvironment {
+    readonly runner?: {
+        import(id: string): Promise<Record<string, unknown>>;
+    };
+}
+interface ClientUrlProjectionServerModule {
+    clearClientUrlProjections(): void;
+    setClientUrlProjection(referenceId: string, projection: ClientUrlProjection): void;
+}
+export declare function recordClientUrlsModule(state: DiscoveryState, code: string, id: string): void;
+export declare function resolveClientUrlsSource(state: DiscoveryState, referenceId: string): string | undefined;
+/**
+ * Deterministic filesystem discovery of clientUrls modules. Transform-based
+ * recording only sees modules that some environment actually loads — a
+ * clientUrls module not yet reachable from any transformed graph at discovery
+ * time (cold ordering, a mount added before its first import is served) would
+ * never be recorded and its include would fail with empty projections. Walking
+ * the project source (the same walk static route-type generation performs)
+ * makes recording independent of module-graph timing. The transform hooks
+ * still record too — they refresh dev HMR edits between scans.
+ */
+export declare function scanForClientUrlModules(state: DiscoveryState): void;
+/**
+ * Lenient pre-entry projection refresh. Re-serializes every RECORDED clientUrls
+ * module before the discovery pass imports the entry, so routers re-created by
+ * that import materialize against the CURRENT module contents.
+ *
+ * Scar: node-preset HMR served stale client-urls routes after a route-shape
+ * edit — the clientUrls module is an HMR-accepted client boundary in the rsc
+ * graph, and the strict registry-driven pass below only runs AFTER the entry
+ * import, so `.routes(reference)` materialized the previous pass's projection.
+ *
+ * Errors are deliberately swallowed per source (a module mid-edit keeps its
+ * last-known projection); the strict discoverClientUrlProjections() pass still
+ * surfaces real failures afterwards. No-ops on cold start (nothing recorded
+ * yet) and when the SSR runner is unavailable.
+ */
+export declare function refreshRecordedClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+/**
+ * Strict projection discovery over every RECORDED clientUrls module. Recorded
+ * modules — not router references — are the source of truth: include() mounts
+ * materialize lazily from the projection registry, so there is no router-level
+ * reference list to consult. Serializes every source before atomically
+ * installing the new projections (a failure preserves last-known state).
+ *
+ * A recorded source whose file no longer exists is dropped silently
+ * (recordClientUrlsModule never un-records, so deletions must self-heal here).
+ * A present-but-broken module is a hard error: it is part of the app graph.
+ */
+export declare function discoverClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+export {};

package/dist/types/vite/discovery/discover-routers.d.ts

@@ -14,4 +14,4 @@ import type { DiscoveryState } from "./state.js";
  * Returns the imported `@rangojs/router/server` module so the caller
  * can access the RouterRegistry and manifest setters.
  */
-export declare function discoverRouters(state: DiscoveryState, rscEnv: any): Promise<any>;
+export declare function discoverRouters(state: DiscoveryState, rscEnv: any, ssrEnv?: any): Promise<any>;

package/dist/types/vite/discovery/state.d.ts

@@ -6,6 +6,7 @@
  * to all extracted helper functions.
  */
 import type { ScanFilter } from "../../build/generate-route-types.js";
+import type { ClientUrlProjection } from "../../client-urls/server-projection.js";
 export declare const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 export interface PluginOptions {
     enableBuildPrerender?: boolean;
@@ -81,6 +82,10 @@ export interface ShellPrerenderCandidate {
         captureTimeout?: number;
     };
 }
+export interface ClientUrlDiscoveryState {
+    clientUrlSourceByReferenceId: Map<string, string>;
+    clientUrlProjectionMap: Map<string, ClientUrlProjection>;
+}
 export interface DiscoveryState {
     resolvedEntryPath: string | undefined;
     projectRoot: string;
@@ -107,6 +112,8 @@ export interface DiscoveryState {
     perRouterTrieMap: Map<string, any>;
     perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
     perRouterManifestDataMap: Map<string, Record<string, string>>;
+    clientUrlSourceByReferenceId?: Map<string, string>;
+    clientUrlProjectionMap?: Map<string, ClientUrlProjection>;
     prerenderManifestEntries: Record<string, string> | null;
     staticManifestEntries: Record<string, string> | null;
     /**
@@ -160,4 +167,4 @@ export interface DiscoveryState {
         at: number;
     } | null;
 }
-export declare function createDiscoveryState(entryPath: string | undefined, opts: PluginOptions | undefined): DiscoveryState;
+export declare function createDiscoveryState(entryPath: string | undefined, opts: PluginOptions | undefined): DiscoveryState & ClientUrlDiscoveryState;