@rangojs/router 0.5.2 → 0.7.0

package/src/server/request-context.ts

@@ -618,6 +618,17 @@ export interface RequestContext<
    */
   _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.
@@ -765,6 +776,7 @@ export type PublicRequestContext<
   | "_treeHasStreaming"
   | "_renderBarrierWaiters"
   | "_handlerLoaderDeps"
+  | "_awaitBeforeFlushLoaderIds"
   | "_renderBarrierHandleSnapshot"
   | "_renderBarrierGuardClosed"
   | "_reportBackgroundError"
@@ -1384,6 +1396,7 @@ export function wireRenderBarrier(
   ctx._renderBarrierHandleSnapshot = undefined;
   ctx._renderBarrierGuardClosed = undefined;
   ctx._handlerLoaderDeps = undefined;
+  ctx._awaitBeforeFlushLoaderIds = undefined;
   ctx._treeHasStreaming = undefined;
 
   // Lazy allocation: only create the Promise when a loader calls rendered().
@@ -1626,12 +1639,23 @@ export function createUseFunction<TEnv>(
       env: ctx.env as any,
       waitUntil: ctx.waitUntil.bind(ctx),
       executionContext: ctx.executionContext,
-      get: ctx.get as any,
-      use: (<TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        return ctx.use(dep);
-      }) as LoaderContext["use"],
+      get: ((keyOrVar: any) => {
+        // Handle READS need the rendered() barrier, which this lane
+        // (action/dispatch-invoked loaders) does not run. Fail with guidance
+        // instead of returning a misleading empty collect.
+        if (isHandle(keyOrVar)) {
+          throw new Error(
+            `ctx.get(handle) is only available in DSL loaders after ` +
+              `"await ctx.rendered()". It cannot be used from request-context ` +
+              `loaders or server actions.`,
+          );
+        }
+        return (ctx.get as any)(keyOrVar);
+      }) as any,
+      // Pass items through: loaders delegate to the request ctx's loader
+      // executor; a handle yields the ctx's push function (write parity —
+      // ctx.use(Meta)({...}) works in this lane exactly like in a handler).
+      use: ((item: any) => ctx.use(item)) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: createReverseFunction(

package/src/server.ts

@@ -47,3 +47,10 @@ export {
 
 // Component utilities (used internally for server/client boundary checks)
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
+
+// Client URL projection registry (Vite discovery/bootstrap bridge)
+export {
+  clearClientUrlProjections,
+  setClientUrlProjection,
+  type ClientUrlProjection,
+} from "./client-urls/server-projection.js";

package/src/ssr/index.tsx

@@ -105,6 +105,15 @@ 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;
 }
 
 /**
@@ -347,6 +356,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;
 }
 
 /**
@@ -368,6 +384,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;
 }
 
 /**
@@ -449,7 +472,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState, streamMode } = options ?? {};
+    const { nonce, formState, streamMode, search } = options ?? {};
 
     try {
       // Tee the stream:
@@ -461,6 +484,12 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         createFromReadableStream,
         rscStream: rscStream1,
         nonce,
+        // Live fizz seeds the request's RAW search. The shell capture pass
+        // below and its resume twin seed the SHELL KEY's search instead
+        // (sorted, cache.searchParams filter applied — shellSearchSeed):
+        // same key => same seed, so the resume tree matches the captured
+        // tree while static-part search reads render what the key names.
+        search,
       });
 
       // Get bootstrap script content
@@ -562,6 +591,9 @@ export function createShellCaptureHandler<TEnv = unknown>(
         createFromReadableStream,
         rscStream,
         onPayloadSettled: settlePayload,
+        // The shell key's own search: static-part search reads render what
+        // the key names, and the resume pass seeds the identical string.
+        search: opts.search,
       });
 
       // Bootstrap load raced against the deadline. A load that never resolves
@@ -735,7 +767,7 @@ export function createShellResumeHandler<TEnv = unknown>(
     rscStream: ReadableStream<Uint8Array>,
     opts: ShellResumeOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { postponed, nonce } = opts;
+    const { postponed, nonce, search } = opts;
 
     try {
       if (postponed === null) {
@@ -765,6 +797,9 @@ export function createShellResumeHandler<TEnv = unknown>(
         createFromReadableStream,
         rscStream: rscStream1,
         nonce,
+        // Same seed as the capture pass for this key: the resume tree must
+        // match the captured tree above the holes, search reads included.
+        search,
       });
 
       // EAGER injection (resume-only): the stored prelude — a complete document

package/src/ssr/ssr-root.tsx

@@ -63,11 +63,21 @@ async function consumeAsyncGenerator(
  */
 function createSsrEventController(opts: {
   pathname: string;
+  /**
+   * Query string seeding the store location. Live fizz passes the request's
+   * raw search; ppr capture/resume pass the SHELL KEY's search (sorted,
+   * cache.searchParams filter applied) so the shell renders what its key
+   * names and both passes agree byte-for-byte.
+   */
+  search?: string;
   params?: Record<string, string>;
   handleData?: HandleData;
   matched?: string[];
 }): EventController {
-  const location = new URL(opts.pathname, "http://localhost");
+  const location = new URL(
+    `${opts.pathname}${opts.search ?? ""}`,
+    "http://localhost",
+  );
   let params = opts.params ?? {};
   const rawMatched = opts.matched ?? [];
   const handleState = {
@@ -142,6 +152,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;
 }
 
 /**
@@ -162,7 +182,13 @@ export interface SsrRootOptions {
  * re-running the whole segment-tree build unless the promise is memoized.
  */
 export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
-  const { createFromReadableStream, rscStream, nonce, onPayloadSettled } = opts;
+  const {
+    createFromReadableStream,
+    rscStream,
+    nonce,
+    onPayloadSettled,
+    search,
+  } = opts;
 
   let payload: Promise<RscPayload> | undefined;
   let handlesPromise: Promise<HandleData> | undefined;
@@ -211,6 +237,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
       store: null as any,
       eventController: createSsrEventController({
         pathname,
+        search,
         params: resolved.metadata?.params,
         handleData,
         matched: resolved.metadata?.matched,

package/src/testing/dom.entry.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/src/testing/render-route.tsx

@@ -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", ...)
@@ -149,6 +150,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
@@ -560,7 +570,9 @@ export async function renderRoute(
     const match = resolve(nextUrl.pathname);
     const segments = buildSegments(routes, match.params, loaderData, mount);
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
-    const root = await renderSegments(segments);
+    const root = await renderSegments(segments, {
+      outletPending: options.outletPending,
+    });
     eventController.setLocation(nextUrl);
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
@@ -595,7 +607,9 @@ export async function renderRoute(
     ...makeMetadata(url.pathname, initialSegments, initialMatch.params),
     defaultPrefetch: options.defaultPrefetch,
   };
-  const initialTree = await renderSegments(initialSegments);
+  const initialTree = await renderSegments(initialSegments, {
+    outletPending: options.outletPending,
+  });
 
   // Wrap render in an awaited async act so a tree that suspends (async loaders,
   // loading states, deferred handle entries that arrive as a Promise) settles its

package/src/testing/run-loader.ts

@@ -42,6 +42,7 @@ import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import type { LoaderContext, LoaderDefinition } from "../types.js";
 import type { ContextVar } from "../context-var.js";
 import { isHandle, type Handle } from "../handle.js";
+import { withDefer } from "../defer.js";
 import { collectHandle } from "./collect-handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import type { SegmentCacheStore } from "../cache/types.js";
@@ -74,6 +75,9 @@ export type TestLoaderContext<TEnv = any> = Omit<
   ) => string;
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
+    <TData, TAccumulated = TData[]>(
+      handle: Handle<TData, TAccumulated>,
+    ): TAccumulated;
     <T = unknown>(key: string): T | undefined;
   };
 };
@@ -248,6 +252,7 @@ function runWithLoaderContext<R>(
   reqCtx: RequestContext<any>,
   opts: RunLoaderOptions,
   fn: (ctx: TestLoaderContext) => R,
+  pushRecorder?: Array<{ handle: Handle<any, any>; value: unknown }>,
 ): R {
   const handleSeeds = new Map<unknown, unknown>(opts.handles ?? []);
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
@@ -275,17 +280,37 @@ function runWithLoaderContext<R>(
       env: reqCtx.env,
       waitUntil: reqCtx.waitUntil.bind(reqCtx),
       executionContext: reqCtx.executionContext,
-      get: reqCtx.get as TestLoaderContext["get"],
+      get: ((keyOrVar: any) => {
+        // Handle READ (mirrors production's ctx.get(handle)): rendered-gated,
+        // seeded via the `handles` option.
+        if (isHandle(keyOrVar)) {
+          if (!renderedResolved) {
+            throw new Error(
+              `ctx.get(handle) in a loader requires "await ctx.rendered()" first. ` +
+                `Handle "${(keyOrVar as Handle<any, any>).$$id}" cannot be read until ` +
+                `the render tree has settled.`,
+            );
+          }
+          if (handleSeeds.has(keyOrVar)) return handleSeeds.get(keyOrVar);
+          return collectHandle(keyOrVar, []);
+        }
+        return (reqCtx.get as any)(keyOrVar);
+      }) as TestLoaderContext["get"],
       use: ((dep: LoaderDefinition<any, any> | Handle<any, any>) => {
-        if (isHandle(dep) && !renderedResolved) {
-          throw new Error(
-            `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
-              `Handle "${(dep as Handle<any, any>).$$id}" cannot be read until ` +
-              `the render tree has settled.`,
-          );
+        // Handle WRITE (mirrors production's ctx.use(Meta)({...}) push): the
+        // same withDefer wrapper shape, recording into the result envelope's
+        // `handlePushes` so tests assert what the loader wrote. Deferred
+        // resolvers record their resolved value when called.
+        if (isHandle(dep)) {
+          const handleDef = dep as Handle<any, any>;
+          return withDefer((dataOrFn: unknown) => {
+            const value =
+              typeof dataOrFn === "function"
+                ? (dataOrFn as () => unknown)()
+                : dataOrFn;
+            pushRecorder?.push({ handle: handleDef, value });
+          });
         }
-        if (handleSeeds.has(dep)) return handleSeeds.get(dep);
-        if (isHandle(dep)) return collectHandle(dep, []);
         // Production ctx.use(Loader) ALWAYS returns a Promise (the cached loader
         // promise). The seeded path must match, so a consumer composing on the
         // result (ctx.use(Dep).then(...), Promise.race, etc.) works the same as
@@ -313,7 +338,7 @@ function runWithLoaderContext<R>(
                   "requires the DSL render barrier, which only exists during a " +
                   "full route match. To unit-test a loader's post-barrier logic, " +
                   "pass { rendered: true } to mock the barrier and { handles: " +
-                  "[[SomeHandle, accumulatedData]] } to seed ctx.use(SomeHandle). " +
+                  "[[SomeHandle, accumulatedData]] } to seed ctx.get(SomeHandle). " +
                   "For the real push/accumulate/barrier wiring, use an e2e test.",
               );
             },
@@ -361,6 +386,11 @@ 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 async function runLoaderResult<T>(
@@ -372,14 +402,22 @@ export async function runLoaderResult<T>(
     buildLoaderCtxOpts(opts),
   );
   const reqCtx = ctx as RequestContext<any>;
+  const handlePushes: Array<{ handle: Handle<any, any>; value: unknown }> = [];
   let result: T | undefined;
   let thrown: unknown;
   try {
-    result = await runWithLoaderContext(reqCtx, opts, (loaderCtx) =>
-      Promise.resolve(loaderFn(loaderCtx)),
+    result = await runWithLoaderContext(
+      reqCtx,
+      opts,
+      (loaderCtx) => Promise.resolve(loaderFn(loaderCtx)),
+      handlePushes,
     );
   } catch (error) {
     thrown = error;
   }
-  return { result, ...buildRunSnapshot(reqCtx, thrown, stateCookieName) };
+  return {
+    result,
+    handlePushes,
+    ...buildRunSnapshot(reqCtx, thrown, stateCookieName),
+  };
 }

package/src/types/boundaries.ts

@@ -74,6 +74,25 @@ 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 function isLoaderDataResult(value: unknown): value is LoaderDataResult {

package/src/types/index.ts

@@ -63,6 +63,7 @@ export type {
   LoaderContext,
   LoaderFn,
   FetchableLoaderOptions,
+  LoaderOptions,
   LoadOptions,
   LoaderDefinition,
 } from "./loader-types.js";

package/src/types/loader-types.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";
@@ -51,14 +52,42 @@ export type LoaderContext<
    */
   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>(
@@ -66,13 +95,13 @@ export type LoaderContext<
     ): Promise<T>;
     <TData, TAccumulated = TData[]>(
       handle: Handle<TData, TAccumulated>,
-    ): 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
@@ -84,7 +113,7 @@ export type LoaderContext<
    * 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));
    * });
    * ```
@@ -144,6 +173,32 @@ export type LoaderFn<
   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/src/types/segments.ts

@@ -258,6 +258,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/src/urls/include-helper.ts

@@ -11,6 +11,12 @@ import {
 import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
 import type { IncludeProvider } from "./include-provider.js";
 import type { IncludeFn } from "./path-helper-types.js";
+import {
+  clientUrlIncludePatterns,
+  isClientUrlPatterns,
+  isClientUrlReference,
+} from "../client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 
 function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
   return !!options && Object.prototype.hasOwnProperty.call(options, "name");
@@ -61,15 +67,27 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
 export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
   return (
     prefix: string,
-    // A `urls()` value (eager) OR an async provider thunk
+    // A `urls()` value (eager), an async provider thunk
     // (`() => import("./routes")`) whose evaluation is deferred to the first
-    // request matching `prefix`. The provider is stored unevaluated and
-    // resolved by the runtime lazy-include expansion / build-time discovery.
-    patterns: UrlPatterns<TEnv> | IncludeProvider<TEnv>,
+    // request matching `prefix`, or a clientUrls() definition (object or
+    // client reference). Providers are stored unevaluated and resolved by the
+    // runtime lazy-include expansion / build-time discovery.
+    patterns: UrlPatterns<TEnv> | IncludeProvider<TEnv> | ClientUrlPatterns,
     options?: IncludeOptions,
   ): IncludeItem => {
     const { ctx } = requireDslContext("include() must be called inside urls()");
 
+    // clientUrls() sources mount through include() like any urls() module.
+    // Detect them FIRST: a client REFERENCE is a callable proxy, so the
+    // downstream provider check (`typeof === "function"`) would otherwise
+    // invoke it as an async include thunk. The substituted handler defers
+    // materialization to evaluation time, when the discovery-installed
+    // projection is available; the include machinery then applies URL and
+    // route-name prefixes exactly as for server modules.
+    if (isClientUrlPatterns(patterns) || isClientUrlReference(patterns)) {
+      patterns = clientUrlIncludePatterns(patterns) as UrlPatterns<TEnv>;
+    }
+
     const explicitName = options?.name;
     const hasExplicitName = hasExplicitNameOption(options);
     if (hasExplicitName && explicitName) {