@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/root-error-boundary.tsx

@@ -3,26 +3,17 @@
 import { Component, useState, type ReactNode } from "react";
 import type { ClientErrorBoundaryFallbackProps } from "./types.js";
 
-/**
- * Check if an error is a network-related error
- */
 function isNetworkError(error: Error): boolean {
   return error.name === "NetworkError";
 }
 
-/**
- * Network error fallback UI with retry functionality
- * Shows a connection-specific message and allows retrying via page refresh
- */
 function NetworkErrorFallback({
   error,
-  reset,
 }: ClientErrorBoundaryFallbackProps): ReactNode {
   const [isRetrying, setIsRetrying] = useState(false);
 
   const handleRetry = (): void => {
     setIsRetrying(true);
-    // Refresh the page to retry the request
     window.location.reload();
   };
 
@@ -42,7 +33,6 @@ function NetworkErrorFallback({
           marginBottom: "1rem",
         }}
       >
-        {/* Simple cloud with x icon using CSS */}
         <span style={{ color: "#9ca3af" }}>&#9729;</span>
       </div>
       <h1
@@ -101,10 +91,6 @@ function NetworkErrorFallback({
   );
 }
 
-/**
- * Default fallback UI for root error boundary
- * This is shown when an unhandled error bubbles up to the root
- */
 function RootErrorFallback({
   error,
   reset,
@@ -230,7 +216,6 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidMount(): void {
-    // Listen for popstate (back/forward navigation) to reset error state
     window.addEventListener("popstate", this.handlePopState);
   }
 
@@ -247,15 +232,13 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidUpdate(prevProps: { children: ReactNode }): void {
-    // Reset error state when children change (e.g., navigation)
-    // This allows the app to recover after navigation away from an errored route
+    // Reset error on children change (navigation).
     if (this.state.hasError && prevProps.children !== this.props.children) {
       this.setState({ hasError: false, error: null });
     }
   }
 
   handlePopState = (): void => {
-    // Reset error state on back/forward navigation
     if (this.state.hasError) {
       this.setState({ hasError: false, error: null });
     }
@@ -276,7 +259,6 @@ export class RootErrorBoundary extends Component<
         segmentType: "route" as const,
       };
 
-      // Use specialized fallback for network errors
       if (isNetworkError(this.state.error)) {
         return <NetworkErrorFallback error={errorInfo} reset={this.reset} />;
       }

package/src/route-content-wrapper.tsx

@@ -1,10 +1,63 @@
 "use client";
 import type { ReactNode } from "react";
-import { Suspense, use, useId } from "react";
-import { invariant } from "./errors";
+import { Component, Suspense, use } from "react";
 import { OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
-import { isLoaderDataResult } from "./types.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) {
+        return <LoaderRedirect to={(redirect as { to: string }).to} />;
+      }
+      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
@@ -22,14 +75,12 @@ export function RouteContentWrapper({
   fallback,
   segmentId,
 }: {
-  content: Promise<ReactNode>;
+  // Normally a pending promise (use() suspends -> fallback). forceAwait paths
+  // pass an already-resolved node so Suspender renders it without suspending.
+  content: Promise<ReactNode> | ReactNode;
   fallback?: ReactNode;
   segmentId?: string;
 }): ReactNode {
-  if (!content) {
-    // Already resolved
-    return content as ReactNode;
-  }
   return (
     <Suspense
       fallback={fallback ?? null}
@@ -40,57 +91,20 @@ export function RouteContentWrapper({
   );
 }
 
-export function RouteContentWrapperCallback<T>({
-  resolve,
-  fallback,
-  children,
-}: {
-  resolve: Promise<T> | T;
-  fallback?: ReactNode;
-  children: (data: T) => ReactNode;
-}): ReactNode {
-  const id = useId();
-  invariant(children, "RouteContentWrapperCallback requires children");
-  invariant(
-    typeof children === "function",
-    "RouteContentWrapperCallback requires children to be a function",
-  );
-  invariant(
-    resolve !== undefined,
-    "RouteContentWrapperCallback requires resolve",
-  );
-  return (
-    <Suspense
-      fallback={fallback ?? null}
-      key={"route-content-suspense-callback-" + id}
-    >
-      <SuspenderCallback resolve={resolve} key={id}>
-        {children}
-      </SuspenderCallback>
-    </Suspense>
-  );
-}
-
 const Suspender = ({
   content,
 }: {
   content: Promise<ReactNode> | ReactNode;
 }): ReactNode => {
-  invariant(content instanceof Promise, "Suspender expects a Promise content");
-
-  return use(content);
-};
-
-const SuspenderCallback = <T,>({
-  resolve,
-  children,
-}: {
-  resolve: Promise<T> | T;
-  children: (data: T) => ReactNode;
-}): ReactNode => {
-  return resolve instanceof Promise
-    ? children(use(resolve))
-    : children(resolve);
+  // Normally content is a pending promise -> use() suspends and the wrapping
+  // Suspense shows the loading() fallback. forceAwait paths (popstate,
+  // stale-revalidation, fully-prefetched nav) instead pass the ALREADY-RESOLVED
+  // node so first render does not suspend for a microtask and flash the loading()
+  // fallback on a NORMAL (non-transition) commit. The wrapper tree
+  // (RouteContentWrapper > Suspense > Suspender) is identical either way, so this
+  // preserves tree structure (see docs/tree-structure.md) — only whether use()
+  // suspends differs, exactly like LoaderResolver's resolved-data branch.
+  return content instanceof Promise ? use(content) : content;
 };
 
 /**
@@ -107,6 +121,13 @@ const SuspenderCallback = <T,>({
 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;
@@ -118,6 +139,7 @@ export interface LoaderBoundaryProps {
 export function LoaderBoundary({
   loaderDataPromise,
   loaderIds,
+  loaderStreams,
   fallback,
   outletKey,
   outletContent,
@@ -130,6 +152,7 @@ export function LoaderBoundary({
       <LoaderResolver
         loaderDataPromise={loaderDataPromise}
         loaderIds={loaderIds}
+        loaderStreams={loaderStreams}
         outletKey={outletKey}
         outletContent={outletContent}
         segment={segment}
@@ -143,44 +166,55 @@ 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)
       : loaderDataPromise;
 
-  // Build loaderData record from resolved values
-  const loaderData: Record<string, any> = {};
-  let loaderErrorFallback: ReactNode = null;
-
-  loaderIds.forEach((id, i) => {
-    const result = resolvedData[i];
-
-    if (isLoaderDataResult(result)) {
-      if (result.ok) {
-        loaderData[id] = result.data;
-      } else {
-        if (result.fallback) {
-          loaderErrorFallback = result.fallback;
-        } else {
-          throw new Error(result.error.message);
-        }
-      }
-    } else {
-      // Legacy format - direct data
-      loaderData[id] = result;
-    }
-  });
+  const { loaderData, errorFallback } = decodeLoaderResults(
+    resolvedData,
+    loaderIds,
+  );
 
   return (
     <OutletProvider
@@ -190,7 +224,7 @@ function LoaderResolver({
       parallel={parallel}
       loaderData={Object.keys(loaderData).length > 0 ? loaderData : undefined}
     >
-      {loaderErrorFallback ?? children}
+      {errorFallback ?? children}
     </OutletProvider>
   );
 }