@rangojs/router 0.5.2 → 0.7.0

package/src/redirect-origin.ts

@@ -134,6 +134,35 @@ export function isExternalRedirect(response: Response): boolean {
   return externalRedirects.has(response);
 }
 
+/**
+ * Out-of-band carrier for `redirect(url, { state })` location state, keyed on
+ * the Response object like the external brand above. Needed by the LOADER
+ * lane: streaming loaders settle AFTER attachLocationStateIfPresent stamped
+ * payload metadata (rsc-rendering.ts runs it between payload prep and Flight
+ * serialization), so request-context state set at throw time misses the
+ * payload. The thrown Response IS the object loader-resolution catches — no
+ * rebuild path intervenes — so a WeakMap entry survives to the catch site,
+ * where it is serialized onto the loader-result redirect marker and delivered
+ * WITH the redirect navigation (LoaderRedirect), merging at the target like
+ * an action write. Handler/middleware/action redirects keep the metadata lane.
+ */
+const redirectStates = new WeakMap<Response, Record<string, unknown>>();
+
+/** Brand a redirect Response with its RESOLVED location-state record. */
+export function attachRedirectState(
+  response: Response,
+  state: Record<string, unknown>,
+): void {
+  redirectStates.set(response, state);
+}
+
+/** Read the resolved location-state record off a redirect Response. */
+export function getRedirectState(
+  response: Response,
+): Record<string, unknown> | undefined {
+  return redirectStates.get(response);
+}
+
 /**
  * Reserved internal header name. No longer a trust signal -- the external
  * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild

package/src/route-content-wrapper.tsx

@@ -1,9 +1,64 @@
 "use client";
 import type { ReactNode } from "react";
-import { Suspense, use } from "react";
+import { Component, Suspense, use } from "react";
 import { OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
-import { decodeLoaderResults } from "./decode-loader-results.js";
+import {
+  decodeLoaderResults,
+  LOADER_ERROR_FALLBACK,
+  LOADER_NOT_FOUND_FALLBACK,
+  LOADER_REDIRECT,
+} from "./decode-loader-results.js";
+import { LoaderRedirect } from "./loader-redirect.js";
+
+/**
+ * Router-owned error boundary for read-site loader errors. segment-system
+ * wraps every loader-bearing segment's children in one (unconditionally —
+ * streams and forceAwait lanes alike, so the tree shape never differs between
+ * navigation lanes; see docs/tree-structure.md). A loader error thrown by a
+ * suspending read carries its errorBoundary() fallback via
+ * LOADER_ERROR_FALLBACK (decodeLoaderEntry); this boundary renders that node,
+ * restoring the pre-streaming errorFallback-swap contract.
+ *
+ * Loader-thrown AUTHORITY SIGNALS ride sibling markers:
+ * - LOADER_NOT_FOUND_FALLBACK (notFound()): renders the SERVER-RENDERED
+ *   not-found UI carried on the marker — nearest notFoundBoundary → router
+ *   notFound option — zero extra fetches. Document lane: Fizz emitted the
+ *   Suspense fallback and replays the throw at hydration, so the swap happens
+ *   client-side (the HTTP status was already set opportunistically by the
+ *   producer when the rejection won the flush race).
+ * - LOADER_REDIRECT (redirect()): mounts LoaderRedirect, which navigates.
+ *
+ * Errors without any marker rethrow to the app's own boundaries.
+ */
+export class StreamedLoaderErrorBoundary extends Component<
+  { children: ReactNode },
+  { error: unknown }
+> {
+  state: { error: unknown } = { error: null };
+
+  static getDerivedStateFromError(error: unknown): { error: unknown } {
+    return { error };
+  }
+
+  render(): ReactNode {
+    const { error } = this.state;
+    if (error !== null && error !== undefined) {
+      const marked = error as Record<PropertyKey, unknown>;
+      const notFoundFallback = marked[LOADER_NOT_FOUND_FALLBACK];
+      if (notFoundFallback !== undefined) return notFoundFallback as ReactNode;
+      const redirect = marked[LOADER_REDIRECT];
+      if (redirect !== undefined) {
+        const r = redirect as { to: string; state?: Record<string, unknown> };
+        return <LoaderRedirect to={r.to} state={r.state} />;
+      }
+      const fallback = marked[LOADER_ERROR_FALLBACK];
+      if (fallback !== undefined) return fallback as ReactNode;
+      throw error;
+    }
+    return this.props.children;
+  }
+}
 
 /**
  * Stable async wrapper component for route content
@@ -67,6 +122,13 @@ const Suspender = ({
 export interface LoaderBoundaryProps {
   loaderDataPromise: Promise<any[]> | any[];
   loaderIds: string[];
+  /**
+   * SPIKE (streaming useLoader): per-loader UNDECODED results from the
+   * producer (values or individually-pending promises). When present, the
+   * resolver passes them through instead of resolving the aggregate above
+   * the children; useLoader suspends per loader at the read site.
+   */
+  loaderStreams?: Record<string, unknown>;
   fallback?: ReactNode;
   outletKey: string;
   outletContent: ReactNode;
@@ -78,6 +140,7 @@ export interface LoaderBoundaryProps {
 export function LoaderBoundary({
   loaderDataPromise,
   loaderIds,
+  loaderStreams,
   fallback,
   outletKey,
   outletContent,
@@ -90,6 +153,7 @@ export function LoaderBoundary({
       <LoaderResolver
         loaderDataPromise={loaderDataPromise}
         loaderIds={loaderIds}
+        loaderStreams={loaderStreams}
         outletKey={outletKey}
         outletContent={outletContent}
         segment={segment}
@@ -103,17 +167,46 @@ export function LoaderBoundary({
 
 /**
  * Internal component that resolves loader promises and renders OutletProvider
+ *
+ * SPIKE (streaming useLoader): when the producer provides per-loader streams,
+ * nothing resolves here above the children — the streams pass through
+ * OutletProvider and useLoader suspends at the read site, with the
+ * LoaderBoundary's loading() fallback as the catching boundary. The streams
+ * MUST be per-loader promises from the producer: deriving them by splitting
+ * the aggregate (aggregate.then(r => r[i])) is wrong — Promise.all resolves
+ * at the SLOWEST loader, so every derived promise inherits the slowest
+ * timing and per-loader granularity is erased (measured: a 400ms loader's
+ * content held until a 2000ms sibling resolved).
+ *
+ * Without streams, the pre-spike behavior is preserved: a pending aggregate
+ * resolves ABOVE via use() (parallel/intercept slots still take this path —
+ * ResolvedSegment carries only the aggregate for slots), and a resolved
+ * array decodes synchronously (forceAwait/action lanes commit whole).
  */
 function LoaderResolver({
   loaderDataPromise,
   loaderIds,
+  loaderStreams,
   outletKey,
   outletContent,
   segment,
   parallel,
   children,
 }: Omit<LoaderBoundaryProps, "fallback">): ReactNode {
-  // Resolve loader promises using React's use()
+  if (loaderStreams) {
+    return (
+      <OutletProvider
+        key={outletKey}
+        content={outletContent}
+        segment={segment}
+        parallel={parallel}
+        loaderStreams={loaderStreams}
+      >
+        {children}
+      </OutletProvider>
+    );
+  }
+
   const resolvedData =
     loaderDataPromise instanceof Promise
       ? use(loaderDataPromise)

package/src/route-definition/dsl-helpers.ts

@@ -19,6 +19,7 @@ import {
   type HelperContext,
   type InterceptEntry,
   type InterceptConfig,
+  type LoaderEntry,
 } from "../server/context";
 import { invariant } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
@@ -782,7 +783,11 @@ const intercept = (
 /**
  * Loader helper - attaches a loader to the current entry
  */
-const loader: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
+const loader: RouteHelpers<any, any>["loader"] = (
+  loaderDef,
+  optionsOrUse,
+  maybeUse,
+) => {
   const { store, ctx } = requireDslContext(
     "loader() must be called inside urls()",
   );
@@ -792,12 +797,32 @@ const loader: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
     invariant(false, "No parent entry available for loader()");
   }
 
+  // loader(Def, use) and loader(Def, options, use) — same options-or-use
+  // disambiguation path() uses, so the long-standing 2-arg form is untouched.
+  const optionsGiven =
+    typeof optionsOrUse === "function" ? undefined : optionsOrUse;
+  const use = typeof optionsOrUse === "function" ? optionsOrUse : maybeUse;
+  invariant(
+    !(typeof optionsOrUse === "function" && maybeUse !== undefined),
+    "loader() received two use() callbacks. Pass loader(Def, options, use) or loader(Def, use).",
+  );
+  invariant(
+    optionsGiven?.stream === undefined || optionsGiven.stream === "navigation",
+    `loader() stream must be "navigation" (got ${JSON.stringify(optionsGiven?.stream)}). Omit it to stream on every render.`,
+  );
+
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
 
-  // Create loader entry with empty revalidate array
-  const loaderEntry = {
+  // Create loader entry with empty revalidate array. awaitBeforeFlush is
+  // resolved here, at DSL-evaluation time, for the same reason
+  // loading({ ssr: false }) is (below) — per-isSSR entry caching makes the
+  // flag request-mode-correct with no isSSR threading; see LoaderEntry.
+  const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
+    ...(optionsGiven?.stream === "navigation" && ctx.isSSR
+      ? { awaitBeforeFlush: true as const }
+      : {}),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use

package/src/route-definition/helpers-types.ts

@@ -5,6 +5,7 @@ import type {
   PartialCacheOptions,
   ErrorBoundaryHandler,
   LoaderDefinition,
+  LoaderOptions,
   MiddlewareFn,
   NotFoundBoundaryHandler,
   ResolvedRouteMap,
@@ -309,11 +310,23 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   return <div>{data.name}</div>;
    * }
    * ```
+   * Pass `{ stream: "navigation" }` to await this loader before first flush on
+   * DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders whose
+   * data, handle pushes, or thrown notFound()/redirect() must be in the SSR'd
+   * HTML. Per-loader: a dynamic sibling in the same segment keeps streaming.
+   *
+   * ```typescript
+   * loader(ProductLoader, { stream: "navigation" }, () => [cache()]),
+   * loader(RecommendationsLoader),  // still streams behind loading()
+   * ```
+   *
    * @param loaderDef - Loader created with createLoader()
+   * @param optionsOrUse - Delivery options, or the use() callback when passing none
    * @param use - Optional callback for loader-specific revalidation rules
    */
   loader: <TData>(
     loaderDef: LoaderDefinition<TData>,
+    optionsOrUse?: LoaderOptions | (() => UseItems<LoaderUseItem>),
     use?: () => UseItems<LoaderUseItem>,
   ) => LoaderItem;
   /**

package/src/route-definition/redirect.ts

@@ -1,9 +1,13 @@
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import {
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
-import { markExternalRedirect } from "../redirect-origin.js";
+import {
+  attachRedirectState,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 
 /**
  * Create a soft redirect Response for middleware short-circuit
@@ -77,23 +81,6 @@ export function redirect(
   if (state) {
     const ctx = getRequestContext();
     ctx.setLocationState(state);
-
-    if (process.env.NODE_ENV !== "production") {
-      const reqCtx = getRequestContext();
-      // Warn only on true full-page SSR loads. SPA partial requests and server
-      // actions both deliver state through Flight payloads, so suppress for those.
-      if (
-        reqCtx &&
-        !reqCtx.originalUrl.searchParams.has("_rsc_partial") &&
-        !reqCtx.request.headers.has("rsc-action") &&
-        !reqCtx.originalUrl.searchParams.has("_rsc_action")
-      ) {
-        console.warn(
-          `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
-            "Location state is only delivered during SPA navigations and will be lost on this request.",
-        );
-      }
-    }
   }
 
   // Auto-prefix root-relative URLs with basename for app-local redirects.
@@ -120,6 +107,18 @@ export function redirect(
 
   const response = new Response(null, { status, headers });
 
+  // Also brand the Response itself with the resolved state (see
+  // redirect-origin.ts): the request-context write above misses the payload
+  // when a STREAMING loader throws this Response after metadata flushed, so
+  // the loader lane reads the state off the thrown object and ships it on
+  // the redirect marker instead.
+  if (state) {
+    attachRedirectState(
+      response,
+      resolveLocationStateEntries(Array.isArray(state) ? state : [state]),
+    );
+  }
+
   // Mark an explicit off-host redirect with an out-of-band brand so the
   // same-origin guard (rsc/redirect-guard.ts) lets it through. The brand is a
   // WeakSet membership on this Response object -- NOT a wire header -- so the

package/src/router/error-handling.ts

@@ -5,7 +5,7 @@
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
 
-import type { ReactNode } from "react";
+import { createElement, type ReactNode } from "react";
 import type { EntryData } from "../server/context";
 import type {
   ResolvedSegment,
@@ -281,6 +281,69 @@ export function createNotFoundInfo(
   };
 }
 
+/** Router-level `createRouter({ notFound })` option shape. */
+export type NotFoundComponentOption =
+  | ReactNode
+  | ((props: { pathname: string }) => ReactNode);
+
+/**
+ * Pick the effective notFound fallback: nearest `notFoundBoundary`, else the
+ * router-level `notFound` option, else a plain default.
+ *
+ * The router option is resolved ONLY when no nearer boundary won — it may be a
+ * user render function doing arbitrary work, so computing it eagerly (as three
+ * earlier copies of this policy did) burned a full render on every 404 that a
+ * boundary was going to handle anyway.
+ *
+ * Every 404 origin routes through here — segment resolution
+ * (`segment-resolution/helpers.ts`), loader-thrown `notFound()`
+ * (`loader-resolution.ts`), and the unmatched-route path (`rsc/handler.ts`) —
+ * so the default text and the boundary-wins precedence cannot drift apart.
+ */
+export function resolveNotFoundFallback(
+  boundary: ReactNode | NotFoundBoundaryHandler | null | undefined,
+  notFoundComponent: NotFoundComponentOption | undefined,
+  pathname: string | undefined,
+): ReactNode | NotFoundBoundaryHandler {
+  if (boundary !== null && boundary !== undefined) return boundary;
+  return resolveDefaultNotFound(notFoundComponent, pathname);
+}
+
+/**
+ * The router-level default alone: `createRouter({ notFound })` rendered, or the
+ * plain fallback node. Separate from {@link resolveNotFoundFallback} for the
+ * unmatched-route path, which has no entry chain and therefore no boundary to
+ * consult — it gets a `ReactNode` back rather than a possible handler.
+ */
+export function resolveDefaultNotFound(
+  notFoundComponent: NotFoundComponentOption | undefined,
+  pathname: string | undefined,
+): ReactNode {
+  if (typeof notFoundComponent === "function") {
+    return notFoundComponent({ pathname: pathname ?? "" });
+  }
+  return notFoundComponent ?? createElement("h1", null, "Not Found");
+}
+
+/**
+ * Invoke a notFound fallback that may be a boundary handler or a plain node.
+ *
+ * Callers that cannot propagate a throw (the loader envelope) wrap this in
+ * their own try/catch; it deliberately does not swallow, so a throwing boundary
+ * still surfaces where that is the correct behavior.
+ */
+export function renderNotFoundFallback(
+  fallback: ReactNode | NotFoundBoundaryHandler,
+  notFoundInfo: NotFoundInfo,
+): ReactNode {
+  if (typeof fallback === "function") {
+    return fallback({
+      notFound: notFoundInfo,
+    } satisfies NotFoundBoundaryFallbackProps);
+  }
+  return fallback;
+}
+
 /**
  * Create a notFound segment with the fallback component
  * Renders the fallback with not found info
@@ -291,16 +354,7 @@ export function createNotFoundSegment(
   entry: EntryData,
   params: Record<string, string>,
 ): ResolvedSegment {
-  let component: ReactNode;
-
-  if (typeof fallback === "function") {
-    const props: NotFoundBoundaryFallbackProps = {
-      notFound: notFoundInfo,
-    };
-    component = fallback(props);
-  } else {
-    component = fallback;
-  }
+  const component: ReactNode = renderNotFoundFallback(fallback, notFoundInfo);
 
   return {
     id: `${entry.shortCode}.notFound`,

package/src/router/intercept-resolution.ts

@@ -86,6 +86,35 @@ export function evaluateInterceptWhen(
  * Find an intercept for the target route by walking up the entry chain.
  * Returns the first (innermost) matching intercept along with the entry that defines it.
  */
+/**
+ * Collect every intercept TARGET route name reachable from an origin entry —
+ * the same chain walk findInterceptForRoute() performs when this location is
+ * the navigation origin. Shipped in payload metadata so the browser-local
+ * clientUrls matcher can DECLINE its optimistic presentation for targets an
+ * intercept would claim (the committed result keeps the origin page + modal,
+ * so destination loading would flash and revert). Deliberately includes
+ * `when`-conditional intercepts: selectors need the live navigation context,
+ * so the browser stays conservative — worst case a non-intercepted navigation
+ * loses its optimistic loading, never the reverse.
+ */
+export function collectInterceptTargetNames(
+  fromEntry: EntryData | null,
+): string[] {
+  const names = new Set<string>();
+  let current: EntryData | null = fromEntry;
+  while (current) {
+    // Tolerate partial entries (unit-test mocks omit the arrays); real
+    // registration always populates layout/intercept.
+    for (const source of [current, ...(current.layout ?? [])]) {
+      for (const intercept of source.intercept ?? []) {
+        names.add(intercept.routeName);
+      }
+    }
+    current = current.parent;
+  }
+  return [...names];
+}
+
 export function findInterceptForRoute(
   targetRouteKey: string,
   fromEntry: EntryData | null,