@rangojs/router 0.5.2 → 0.6.0

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) {

package/src/urls/path-helper-types.ts

@@ -5,6 +5,7 @@ import type {
   Handler,
   HandlerContext,
   LoaderDefinition,
+  LoaderOptions,
   MiddlewareFn,
   NotFoundBoundaryHandler,
   PartialCacheOptions,
@@ -57,6 +58,7 @@ import type {
   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.
@@ -175,6 +177,11 @@ export type IncludeArg<
   TResponses extends Record<string, unknown>,
 > =
   | UrlPatterns<TEnv, TRoutes, TResponses>
+  // clientUrls() definitions mount through include() like any urls() module;
+  // on the server the runtime value is the module's client reference, but the
+  // TypeScript type of that default export IS ClientUrlPatterns, so route
+  // names flow into NamedRoutes through the same TRoutes inference.
+  | ClientUrlPatterns<TRoutes>
   | (() =>
       | IncludeResolved<TEnv, TRoutes, TResponses>
       | Promise<IncludeResolved<TEnv, TRoutes, TResponses>>);
@@ -338,10 +345,16 @@ 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>,
+    optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]),
     use?: () => LoaderUseItem[],
   ) => LoaderItem;
 

package/src/use-loader.tsx

@@ -3,6 +3,7 @@
 import {
   isValidElement,
   startTransition,
+  use,
   useCallback,
   useContext,
   useEffect,
@@ -13,6 +14,7 @@ import {
 } from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import { loaderStore, type LoaderEntry } from "./loader-store.js";
+import { decodeLoaderEntry } from "./decode-loader-results.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
 function isShareableGet(options: LoadOptions | undefined): boolean {
@@ -34,19 +36,47 @@ let privateGroupBucketSeq = 0;
 
 const NOT_FOUND = Symbol("not-found");
 
+/**
+ * SPIKE (streaming useLoader): lookup results distinguish a synchronously
+ * available value from a still-streaming per-loader promise. A pending stream
+ * is `use()`d at the read site (implicit suspension); the promise identity is
+ * stable per commit (it comes from the provider's memoized context value /
+ * element props), which use() requires across replays.
+ */
+type LoaderLookup =
+  | typeof NOT_FOUND
+  | { value: unknown }
+  | { stream: Promise<unknown> };
+
+function lookupLoaderStreams(
+  loaderStreams: Record<string, unknown> | undefined,
+  loaderId: string,
+): LoaderLookup {
+  if (!loaderStreams || !(loaderId in loaderStreams)) return NOT_FOUND;
+  const entry = loaderStreams[loaderId];
+  // Within the loaderStreams channel a Promise always means "still streaming";
+  // settled entries are undecoded result values, never promises.
+  return entry instanceof Promise
+    ? { stream: entry }
+    : { value: decodeLoaderEntry(entry) };
+}
+
 function extractContentLoaderData(
   node: ReactNode,
   loaderId: string,
-): unknown | typeof NOT_FOUND {
+): LoaderLookup {
   if (!isValidElement(node)) return NOT_FOUND;
   const props = node.props as Record<string, any> | undefined;
   if (!props) return NOT_FOUND;
 
   // Direct OutletProvider with loaderData
   if (props.loaderData && loaderId in props.loaderData) {
-    return props.loaderData[loaderId];
+    return { value: props.loaderData[loaderId] };
   }
 
+  const streamed = lookupLoaderStreams(props.loaderStreams, loaderId);
+  if (streamed !== NOT_FOUND) return streamed;
+
   if (
     props.loaderIds &&
     Array.isArray(props.loaderIds) &&
@@ -57,9 +87,9 @@ function extractContentLoaderData(
     if (idx !== -1) {
       const data = (props.loaderDataPromise as any[])[idx];
       if (data && typeof data === "object" && "ok" in data) {
-        return data.ok ? data.data : NOT_FOUND;
+        return data.ok ? { value: data.data } : NOT_FOUND;
       }
-      return data;
+      return { value: data };
     }
   }
 
@@ -102,9 +132,10 @@ function useLoaderInternal<T>(
 ): UseFetchLoaderResult<T> {
   const context = useContext(OutletContext);
 
-  const { contextData, hasContextData } = useMemo((): {
+  const walk = useMemo((): {
     contextData: T | undefined;
     hasContextData: boolean;
+    pendingStream?: Promise<unknown>;
   } => {
     let current: OutletContextValue | null | undefined = context;
     while (current) {
@@ -114,18 +145,48 @@ function useLoaderInternal<T>(
           hasContextData: true,
         };
       }
+      const streamed = lookupLoaderStreams(current.loaderStreams, loader.$$id);
+      if (streamed !== NOT_FOUND) {
+        if ("stream" in streamed) {
+          return {
+            contextData: undefined,
+            hasContextData: true,
+            pendingStream: streamed.stream,
+          };
+        }
+        return { contextData: streamed.value as T, hasContextData: true };
+      }
       const contentData = extractContentLoaderData(
         current.content,
         loader.$$id,
       );
       if (contentData !== NOT_FOUND) {
-        return { contextData: contentData as T, hasContextData: true };
+        if ("stream" in contentData) {
+          return {
+            contextData: undefined,
+            hasContextData: true,
+            pendingStream: contentData.stream,
+          };
+        }
+        return { contextData: contentData.value as T, hasContextData: true };
       }
       current = current.parent;
     }
     return { contextData: undefined, hasContextData: false };
   }, [context, loader.$$id]);
 
+  // SPIKE (streaming useLoader): a pending per-loader stream suspends HERE —
+  // the implicit-suspense read. use() is exempt from hook-order rules, so the
+  // conditional call is legal; on replay after resolution it returns
+  // synchronously and the decoded value takes the contextData slot. Hooks
+  // below never run in a suspended render, so their order is stable across
+  // every COMPLETED render.
+  const { hasContextData } = walk;
+  let contextData = walk.contextData;
+  if (walk.pendingStream) {
+    contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
+  }
+
   const loaderId = loader.$$id;
   const key = options?.key;
   const refreshGroupOption = options?.refreshGroup;