@rangojs/router 0.5.2 → 0.7.0

package/src/client-urls/types.ts

@@ -0,0 +1,201 @@
+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" | "ppr"
+>;
+
+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. Under a
+   * `ppr` group route the flag BAKES: the loader executes at shell capture
+   * and its settled return freezes into the shell (nested promises stay
+   * live holes).
+   */
+  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;
+}

package/src/client.rsc.tsx

@@ -15,6 +15,7 @@ export {
   Outlet,
   ParallelOutlet,
   useOutlet,
+  type OutletState,
   useLoader,
   ErrorBoundary,
   type ErrorBoundaryProps,
@@ -31,6 +32,12 @@ export {
 
 export { createLoader } from "./route-definition.js";
 
+export { clientUrls } from "./client-urls/client-urls.js";
+export type {
+  ClientUrlPatterns,
+  ClientUrlRouteRecord,
+} from "./client-urls/client-urls.js";
+
 // "use client" hooks the default ./client entry exports. They are client
 // references in the RSC graph, identical in kind to useHref/useReverse/
 // useHandle already forwarded below; forward them so the RSC client entry's
@@ -39,6 +46,11 @@ export { createLoader } from "./route-definition.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";
 // CSP nonce for userland head-script components (analytics/GTM/inline init);
 // forwarded so the RSC client entry's hook surface matches the default entry.

package/src/client.tsx

@@ -141,17 +141,41 @@ function useSlotSegment(
  * }
  * ```
  */
-export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
+export function Outlet({
+  name,
+  fallback,
+}: { name?: `@${string}`; fallback?: ReactNode } = {}): ReactNode {
   const context = useContext(OutletContext);
   const namedSegment = useSlotSegment(context, name);
 
   if (name) {
-    return renderSlotContent(namedSegment);
+    const slot = renderSlotContent(namedSegment);
+    // EXPERIMENT (Outlet fallback): layout-declared pending UI for a named
+    // slot — an outer Suspense catching whatever the slot's content leaves
+    // unhandled.
+    return fallback !== undefined ? (
+      <Suspense fallback={fallback}>{slot}</Suspense>
+    ) : (
+      slot
+    );
   }
 
   // Default: render child content
   const content = context?.content ?? null;
 
+  // EXPERIMENT (Outlet fallback): the layout owns the outlet position, so it
+  // may declare the placeholder for pending child content right where it
+  // renders — a plain Suspense boundary, no DSL wiring, no segment-resolution
+  // threading. With read-site useLoader suspension this covers loading()'s
+  // roles by construction: document SSR streams the fallback then the
+  // content; PPR postpones unresolved readers here (the outlet becomes the
+  // hole); same-route re-renders are held before commit so the fallback does
+  // NOT flash; cross-route navs show it as destination feedback. An explicit
+  // prop wins over the child segment's loading().
+  if (fallback !== undefined) {
+    return <Suspense fallback={fallback}>{content}</Suspense>;
+  }
+
   // If this segment defines a loading component, wrap outlet content with Suspense
   // The loading component becomes the Suspense fallback, shown during streaming/navigation
   if (context?.loading) {
@@ -199,7 +223,7 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
 // internal component and is intentionally not part of the public ./client API.
 
 /**
- * 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.
@@ -208,13 +232,21 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
  * ```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 function useOutlet(): ReactNode {
+export interface OutletState {
+  readonly content: ReactNode;
+  readonly pending: boolean;
+}
+
+export function useOutlet(): OutletState {
   const context = useContext(OutletContext);
-  return context?.content ?? null;
+  return {
+    content: context?.content ?? null,
+    pending: context?.pending ?? false,
+  };
 }
 
 export {
@@ -227,6 +259,12 @@ export {
   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
  */
@@ -339,6 +377,11 @@ 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";
 // CSP nonce for the active request, for userland components that inject their
 // own <script>/<style> into the document head (analytics, GTM, inline init).

package/src/decode-loader-results.ts

@@ -1,5 +1,66 @@
 import type { ReactNode } from "react";
+import { createElement } from "react";
 import { isLoaderDataResult } from "./types.js";
+import { LoaderRedirect } from "./loader-redirect.js";
+
+/**
+ * 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 const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
+  "rango.loaderNotFound",
+);
+export const LOADER_REDIRECT: unique symbol = Symbol("rango.loaderRedirect");
+
+function throwSignal(result: any): void {
+  if (result.notFound === true) {
+    const err = new Error(result.error?.message ?? "Not found");
+    err.name = result.error?.name ?? "DataNotFoundError";
+    (err as any)[LOADER_NOT_FOUND_FALLBACK] = result.fallback ?? null;
+    throw err;
+  }
+  if (result.redirect) {
+    const err = new Error(result.error?.message ?? "Loader redirect");
+    err.name = "LoaderRedirect";
+    (err as any)[LOADER_REDIRECT] = result.redirect;
+    throw err;
+  }
+}
+
+/**
+ * Non-throwing signal resolution for the aggregate path. Returns the node to
+ * place in the errorFallback slot, or undefined when the result carries no
+ * signal.
+ */
+function signalFallback(result: any): ReactNode | undefined {
+  if (result.notFound === true) {
+    return (result.fallback ?? null) as ReactNode;
+  }
+  if (result.redirect) {
+    const redirect = result.redirect as {
+      to: string;
+      state?: Record<string, unknown>;
+    };
+    return createElement(LoaderRedirect, {
+      to: redirect.to,
+      state: redirect.state,
+    });
+  }
+  return undefined;
+}
 
 // Shared by segment-system (server) and LoaderResolver (client) so the
 // legacy/ok/error-fallback/throw decode of resolved loader values lives once.
@@ -25,6 +86,16 @@ export function decodeLoaderResults(
       continue;
     }
 
+    // Authority signals take the errorFallback slot (this decode runs during
+    // the server tree build on forceAwait/action lanes — throwing here would
+    // collapse the payload). A signal outranks a plain error fallback and
+    // stops the scan: notFound renders the server-rendered 404 UI, redirect
+    // mounts LoaderRedirect which navigates.
+    const signal = signalFallback(result);
+    if (signal !== undefined) {
+      return { loaderData, errorFallback: signal };
+    }
+
     // null/undefined is the producer's ONLY "no boundary found" sentinel
     // (loader-resolution.ts sets fallback: null for the no-boundary and the
     // fallback-render-threw cases). A matched boundary's rendered ReactNode can
@@ -50,3 +121,45 @@ export function decodeLoaderResults(
 
   return { loaderData, errorFallback };
 }
+
+/**
+ * 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 const LOADER_ERROR_FALLBACK: unique symbol = Symbol(
+  "rango.loaderErrorFallback",
+);
+
+/**
+ * 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 function decodeLoaderEntry(result: any): any {
+  if (!isLoaderDataResult(result)) {
+    return result;
+  }
+  if (result.ok) {
+    return result.data;
+  }
+  throwSignal(result);
+  const info = result.error;
+  const err = new Error(
+    info.message,
+    info.cause !== undefined ? { cause: info.cause } : undefined,
+  );
+  if (info.name) err.name = info.name;
+  if (info.stack) err.stack = info.stack;
+  if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  if (result.fallback != null) {
+    (err as any)[LOADER_ERROR_FALLBACK] = result.fallback;
+  }
+  throw err;
+}

package/src/errors.ts

@@ -62,6 +62,20 @@ export class DataNotFoundError extends Error {
   }
 }
 
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails — same rationale as isRouteNotFoundError above. Every
+// notFound() origin (segment resolution, loader envelopes, fetchable loaders)
+// must use this rather than a bare instanceof, or the same thrown signal is
+// honored on one path and escapes as a 500 on another.
+export function isDataNotFoundError(
+  error: unknown,
+): error is DataNotFoundError {
+  return (
+    error instanceof DataNotFoundError ||
+    (error instanceof Error && error.name === "DataNotFoundError")
+  );
+}
+
 /**
  * Convenience function to throw a DataNotFoundError
  * Shorter syntax for common not-found scenarios

package/src/handles/deferred-resolution.ts

@@ -92,14 +92,21 @@ async function resolveValues(values: unknown[]): Promise<unknown[]> {
 export async function* resolvedHandleStream(
   handleStore: HandleStore,
 ): AsyncGenerator<HandleData, void, unknown> {
-  // Drain stream() (NOT getData()) for the converged snapshot: stream() sets the
-  // store's `completed` flag on seal+settle, and that flag is what makes a LATE
-  // push throw LateHandlePushError — an async JSX subtree that suspended and later
-  // calls ctx.use(Handle)(...) after collection. getData() never sets `completed`,
-  // so the late push would silently land. Both wait for the same settle barrier, so
-  // the final yielded value is identical; we just keep the late-push guard.
+  // Drain stream() (NOT getData()) for the converged snapshot: consuming a
+  // stream arms the store's late-push guard (LateHandlePushError for pushes
+  // after FULL settle — an async JSX subtree that suspended and later calls
+  // ctx.use(Handle)(...) after collection). getData() never arms it, so the
+  // late push would silently land.
+  //
+  // Scoped to the HANDLER barrier ("settled"), NOT full settle: both document
+  // consumers (ssr-root.tsx React.use, rsc-router.tsx pre-hydration drain)
+  // block on this generator's COMPLETION, so waiting for the auxiliary
+  // (loader) lane would hold SSR markup and hydration hostage to the slowest
+  // streaming loader. Loader pushes that beat the handler barrier are in this
+  // snapshot (the race); later ones ride metadata.handlesLate
+  // (handleStore.streamLate()), applied client-side post-hydration.
   let snapshot: HandleData = {};
-  for await (const data of handleStore.stream()) {
+  for await (const data of handleStore.stream("settled")) {
     snapshot = data;
   }
   yield await resolveDeferredHandleValues(snapshot);

package/src/index.ts

@@ -50,6 +50,7 @@ export type {
   LoaderDefinition,
   LoaderFn,
   LoaderContext,
+  LoaderOptions,
   FetchableLoaderOptions,
   LoadOptions,
   // Error boundary types

package/src/loader-redirect.tsx

@@ -0,0 +1,64 @@
+"use client";
+import type { ReactNode } from "react";
+import { useEffect } from "react";
+import type { NavigateOptionsInternal } from "./browser/types.js";
+import { useRouter } from "./browser/react/use-router.js";
+import { validateExternalRedirect } from "./browser/validate-redirect-origin.js";
+import { resolveSameOriginRedirect } from "./redirect-origin.js";
+
+/**
+ * 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 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 {
+  const router = useRouter();
+  useEffect(() => {
+    const origin = window.location.origin;
+    // Same-origin first: a target that resolves on-origin is a router
+    // navigation. Only when it does NOT is this the `{ external: true }`
+    // opt-in, which waives same-origin but NOT scheme safety — both branches
+    // go through the shared resolvers in redirect-origin.ts so this channel
+    // cannot drift from the fetch/action/document ones.
+    // Pure resolver (not validateRedirectOrigin) for the probe: an off-origin
+    // target here is the legitimate external opt-in, not a blocked redirect,
+    // so it must not log a "blocked" error on its way to the branch below.
+    const sameOrigin = resolveSameOriginRedirect(to, origin);
+    if (sameOrigin) {
+      const options: Omit<NavigateOptionsInternal, "replace"> | undefined =
+        state ? { state, _skipCache: true } : undefined;
+      void router.replace(sameOrigin, options);
+      return;
+    }
+    const externalUrl = validateExternalRedirect(to, origin);
+    if (externalUrl) {
+      window.location.replace(externalUrl);
+    }
+    // Redirect targets are request-scoped constants; re-running on identity
+    // change only (StrictMode double-invoke is idempotent — same target).
+  }, [to, state, router]);
+  return null;
+}

package/src/outlet-context.ts

@@ -3,9 +3,21 @@ 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/src/outlet-provider.tsx

@@ -12,12 +12,16 @@ export function OutletProvider({
   parallel,
   segment,
   loaderData,
+  loaderStreams,
+  pending = false,
   children,
 }: {
   content: ReactNode;
   parallel?: ResolvedSegment[];
   segment?: ResolvedSegment;
   loaderData?: Record<string, any>;
+  loaderStreams?: Record<string, unknown>;
+  pending?: boolean;
   children: ReactNode;
 }): ReactNode {
   // Get parent context to enable walking up the chain for loader lookups
@@ -29,10 +33,20 @@ export function OutletProvider({
       parallel,
       segment,
       loaderData,
+      loaderStreams,
+      pending,
       parent: parentContext,
       loading: segment?.loading,
     }),
-    [content, parallel, segment, loaderData, parentContext],
+    [
+      content,
+      parallel,
+      segment,
+      loaderData,
+      loaderStreams,
+      pending,
+      parentContext,
+    ],
   );
 
   return (