@rangojs/router 0.5.1 → 0.6.0

package/src/segment-system.tsx

@@ -8,6 +8,7 @@ import { invariant } from "./errors.js";
 import {
   RouteContentWrapper,
   LoaderBoundary,
+  StreamedLoaderErrorBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
@@ -113,6 +114,9 @@ export interface RenderSegmentsOptions {
    */
   forceAwait?: boolean;
 
+  /** Seeded descendant client-route pending state for testing. */
+  outletPending?: boolean;
+
   /**
    * Intercept segments to inject into the tree.
    * These are parallel segments from intercept routes that need to be
@@ -231,6 +235,7 @@ export async function renderSegments(
     isAction,
     interceptSegments,
     forceAwait,
+    outletPending = false,
     rootLayout: RootLayout,
   } = options || {};
 
@@ -448,9 +453,30 @@ export async function renderSegments(
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
 
+    // Loader-bearing segments get the router-owned error boundary around
+    // their children so a read-site loader error renders its errorBoundary()
+    // fallback (LOADER_ERROR_FALLBACK marker on the thrown error) instead of
+    // escaping to app boundaries. Wrapped UNCONDITIONALLY on loader presence
+    // — streams and forceAwait lanes must produce the same tree shape or
+    // lane changes remount the subtree (docs/tree-structure.md).
+    if (loaderEntries.length > 0) {
+      nodeContent = createElement(StreamedLoaderErrorBoundary, {
+        children: nodeContent,
+      });
+    }
+
     if (loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      // SPIKE (streaming useLoader): per-loader streams for the boundary's
+      // readers. MUST come from the individual loader refs — splitting the
+      // aggregate client-side is wrong (Promise.all resolves at the slowest
+      // loader, erasing per-loader timing; measured 400ms data held to a
+      // 2000ms sibling). Zero-loader boundaries pass NO streams so the
+      // resolver keeps the fresh-promise resolve-above suspension — that
+      // microtask suspension is what makes SSR emit the loading() fallback
+      // for content-suspending routes (segment-loader-promise.ts).
+      let boundaryLoaderStreams: Record<string, unknown> | undefined;
       if (forceAwait || isAction) {
         const awaitStart = segDebug ? performance.now() : 0;
         boundaryLoaderData = await loaderDataPromise;
@@ -460,16 +486,23 @@ export async function renderSegments(
             ms: Math.round(performance.now() - awaitStart),
           });
         }
-      } else if (segDebug) {
-        segDebugLog(
-          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
-          { loaderIds },
-        );
+      } else if (loaderEntries.length > 0) {
+        boundaryLoaderStreams = {};
+        for (const l of loaderEntries) {
+          boundaryLoaderStreams[l.loaderId!] = l.loaderData;
+        }
+        if (segDebug) {
+          segDebugLog(
+            `segment ${id}: per-loader streams via LoaderBoundary (read-site suspense)`,
+            { loaderIds },
+          );
+        }
       }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
         loaderDataPromise: boundaryLoaderData,
         loaderIds,
+        loaderStreams: boundaryLoaderStreams,
         fallback: loading,
         outletKey: key,
         outletContent,
@@ -483,6 +516,7 @@ export async function renderSegments(
         content: outletContent,
         segment: node.segment,
         parallel: node.parallel,
+        pending: outletPending,
         children: nodeContent,
       });
     } else {
@@ -492,29 +526,50 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
-      // No loading() on this segment, so its loader data cannot stream behind
-      // a Suspense fallback — the tree build BLOCKS here until the data
-      // arrives. On the initial document this await runs before hydrateRoot.
-      const layoutAwaitStart = segDebug ? performance.now() : 0;
-      const resolvedData = await buildLoaderPromise(layoutLoaders);
-      if (segDebug) {
-        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
-          loaderIds: layoutLoaderIds,
-          ms: Math.round(performance.now() - layoutAwaitStart),
-        });
-      }
-      const decodeStart = segDebug ? performance.now() : 0;
-      const { loaderData, errorFallback } = decodeLoaderResults(
-        resolvedData,
-        layoutLoaderIds,
-      );
-      if (segDebug) {
-        const decodeMs = Math.round(performance.now() - decodeStart);
-        if (decodeMs > 0) {
-          segDebugLog(`segment ${id}: loader results decoded`, {
-            ms: decodeMs,
+      // SPIKE (streaming useLoader): a segment without loading() used to BLOCK
+      // the tree build here (await buildLoaderPromise) so its data was always
+      // resolved before render. Streaming lanes now skip the await and pass
+      // per-loader UNDECODED results (possibly pending promises) through
+      // OutletProvider.loaderStreams — useLoader suspends at the read site to
+      // the nearest CONSUMER Suspense boundary. forceAwait (popstate, stale
+      // revalidation, fully-prefetched) and action lanes keep the blocking
+      // await so those commits stay whole with no fallback flash.
+      let loaderData: Record<string, any> = {};
+      let errorFallback: ReactNode = null;
+      let loaderStreams: Record<string, unknown> | undefined;
+      if (forceAwait || isAction) {
+        const layoutAwaitStart = segDebug ? performance.now() : 0;
+        const resolvedData = await buildLoaderPromise(layoutLoaders);
+        if (segDebug) {
+          segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+            loaderIds: layoutLoaderIds,
+            ms: Math.round(performance.now() - layoutAwaitStart),
           });
         }
+        const decodeStart = segDebug ? performance.now() : 0;
+        ({ loaderData, errorFallback } = decodeLoaderResults(
+          resolvedData,
+          layoutLoaderIds,
+        ));
+        if (segDebug) {
+          const decodeMs = Math.round(performance.now() - decodeStart);
+          if (decodeMs > 0) {
+            segDebugLog(`segment ${id}: loader results decoded`, {
+              ms: decodeMs,
+            });
+          }
+        }
+      } else if (layoutLoaders.length > 0) {
+        loaderStreams = {};
+        for (const l of layoutLoaders) {
+          loaderStreams[l.loaderId!] = l.loaderData;
+        }
+        if (segDebug) {
+          segDebugLog(
+            `segment ${id}: layout loaders streaming to read sites (no loading())`,
+            { loaderIds: layoutLoaderIds },
+          );
+        }
       }
 
       if (parallelOwnedLoaders.length > 0) {
@@ -574,6 +629,8 @@ export async function renderSegments(
         segment: node.segment,
         parallel: node.parallel,
         loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
+        loaderStreams,
+        pending: outletPending,
         children: errorFallback ?? nodeContent,
       });
     }

package/src/server/context.ts

@@ -106,6 +106,16 @@ export type LoaderEntry = {
   revalidate: ShouldRevalidateFn<any, any>[];
   /** Cache config for this specific loader (loaders are NOT cached by default) */
   cache?: EntryCacheConfig;
+  /**
+   * Document renders await this loader before segment resolution returns
+   * (loader(Def, { stream: "navigation" })), so its data, handle pushes, and
+   * thrown notFound()/redirect() deterministically precede first flush.
+   * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
+   * per-isSSR (router/manifest.ts cache key), so the flag is already
+   * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+   * appears on navigation-lane entries.
+   */
+  awaitBeforeFlush?: true;
 };
 
 /**

package/src/server/cookie-store.ts

@@ -14,7 +14,7 @@ import {
   getCurrentLoaderBodyId,
   isInsideHandlerInvokedLoaderBody,
 } from "./context.js";
-import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
+import { isInsideCacheExecScope } from "../cache/cache-exec-scope.js";
 
 /**
  * A single cookie entry returned by get() and getAll().
@@ -65,7 +65,7 @@ export interface CookieStore {
  */
 export function cookies(): CookieStore {
   const ctx = getRequestContext();
-  assertNotInsideCacheContext(ctx, "cookies");
+  assertNotInsideCacheContext("cookies");
   assertNotInsideShellCapture(ctx, "cookies");
   return createCookieStore(ctx);
 }
@@ -91,9 +91,10 @@ type HeadersIterator<T> = IterableIterator<T>;
 
 /**
  * Throw if called inside a cache boundary — either a "use cache" function
- * (`INSIDE_CACHE_EXEC` stamped on ctx by the cache runtime) or a `cache()`
- * DSL boundary (`isInsideCacheScope()` — the render-store flag set while
- * resolving a `type: "cache"` route entry).
+ * (`isInsideCacheExecScope()` — the AsyncLocalStorage scope the cache runtime
+ * enters around the cached body) or a `cache()` DSL boundary
+ * (`isInsideCacheScope()` — the render-store flag set while resolving a
+ * `type: "cache"` route entry).
  *
  * Reading request-scoped data (cookies, headers) inside a cached scope
  * produces per-request values that are NOT reflected in the cache key, so
@@ -103,18 +104,17 @@ type HeadersIterator<T> = IterableIterator<T>;
  * here is baked into the shell exactly like a `"use cache"` return value is
  * baked into its cache entry.
  *
- * `isInsideCacheScope()` returns false inside loaders (loaders always run
- * fresh on every request, even on a cache hit), so reading cookies()/headers()
- * from a loader is allowed — loaders are the dynamic "holes" of a cached
- * document.
+ * Both checks are scoped so loaders stay exempt — loaders are the dynamic
+ * "holes" of a cached document and always run fresh. `isInsideCacheScope()`
+ * returns false inside loaders by construction; `isInsideCacheExecScope()`
+ * follows the cached body's own async chain, so a loader running in PARALLEL
+ * with a slow "use cache" fetch on the same request reads cookies() freely.
+ * (Scar: the previous INSIDE_CACHE_EXEC stamp on the shared RequestContext
+ * made exactly that parallel read throw for the cached fetch's whole
+ * execution window — see cache-exec-scope.ts.)
  */
-function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
-  if (
-    ctx !== null &&
-    ctx !== undefined &&
-    typeof ctx === "object" &&
-    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
-  ) {
+function assertNotInsideCacheContext(fnName: string): void {
+  if (isInsideCacheExecScope()) {
     throw new Error(
       `${fnName}() cannot be called inside a "use cache" function. ` +
         `Request-scoped data (cookies, headers) varies per request but is not ` +
@@ -222,7 +222,7 @@ const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
  */
 export function headers(): ReadonlyHeaders {
   const ctx = getRequestContext();
-  assertNotInsideCacheContext(ctx, "headers");
+  assertNotInsideCacheContext("headers");
   assertNotInsideShellCapture(ctx, "headers");
   return new Proxy(ctx.request.headers, {
     get(target, prop, receiver) {
@@ -262,7 +262,7 @@ export function invalidateClientCache(): void {
     }
     return;
   }
-  assertNotInsideCacheContext(ctx, "invalidateClientCache");
+  assertNotInsideCacheContext("invalidateClientCache");
   ctx._rotateStateCookie();
 }
 
@@ -287,7 +287,7 @@ export function keepClientCache(): void {
     }
     return;
   }
-  assertNotInsideCacheContext(ctx, "keepClientCache");
+  assertNotInsideCacheContext("keepClientCache");
   ctx._setKeepCacheDirective();
 }
 

package/src/server/handle-store.ts

@@ -92,6 +92,26 @@ export interface HandleStore {
    */
   onError?: (error: Error) => void;
 
+  /**
+   * Track a promise on the AUXILIARY (loader) settlement lane. Aux tracking
+   * keeps the store OPEN for pushes (a mid-body `ctx.handle(H)(...)` from a
+   * streaming loader is legal until this lane drains) WITHOUT joining
+   * `settled` — the handler barrier that rendered()-readers, the document
+   * handle snapshot, and prerender/cache collection wait on. Two lanes exist
+   * because loader bodies stream: joining them to `settled` would block SSR
+   * markup and hydration on the slowest loader (ssr-root.tsx and
+   * rsc-router.tsx both drain the document handle stream in blocking
+   * positions), and would self-deadlock any loader awaiting ctx.rendered().
+   */
+  trackAuxiliary<T>(promise: Promise<T>): Promise<T>;
+
+  /**
+   * Promise that resolves when the store is sealed AND BOTH lanes (handler +
+   * auxiliary) have drained. Late-push legality and default stream completion
+   * key on this, not on `settled`.
+   */
+  readonly fullySettled: Promise<void>;
+
   /**
    * Push handle data for a specific handle and segment.
    * Multiple pushes to the same handle/segment accumulate in an array.
@@ -101,16 +121,32 @@ export interface HandleStore {
 
   /**
    * Get all collected handle data after all handlers have settled.
-   * Waits for `settled`, then returns the finalized data.
+   * Waits for `settled` (handler lane), then returns the data at that point.
    */
   getData(): Promise<HandleData>;
 
   /**
    * Get an async iterator that yields handle data on each push.
-   * The iterator completes when all handlers have settled.
+   * Completes at the chosen settlement barrier: "fullySettled" (default —
+   * nav/action payloads, whose consumer applies each yield progressively) or
+   * "settled" (the document lane, whose consumers drain to completion in
+   * blocking positions and must not wait on loader bodies).
    * Each yield contains the full accumulated state (not just the delta).
+   * Safe for concurrent consumers (per-consumer version cursor).
    */
-  stream(): AsyncGenerator<HandleData, void, unknown>;
+  stream(
+    until?: "settled" | "fullySettled",
+  ): AsyncGenerator<HandleData, void, unknown>;
+
+  /**
+   * Document-lane late channel: yields full-state updates for pushes that
+   * land AFTER the handler barrier (streaming loader bodies), completing at
+   * fullySettled. Returns without yielding when the auxiliary lane is empty
+   * by the time `settled` resolves. The client consumes this post-hydration
+   * (rsc-router.tsx) and merges via the same application path as nav-lane
+   * progressive handle updates.
+   */
+  streamLate(): AsyncGenerator<HandleData, void, unknown>;
 
   /**
    * Get handle data for a specific segment (for caching).
@@ -151,20 +187,64 @@ export interface HandleStore {
 export function createHandleStore(): HandleStore {
   const data: HandleData = {};
 
-  // Settlement barrier: resolved only when sealed AND inflight === 0.
-  // seal() signals "no more track() calls". Each track() increments
-  // inflightCount, each promise.finally() decrements. settled resolves
-  // once both conditions are met — even if tracks are added while
-  // earlier ones are still in flight.
+  // Settlement barriers: `settled` (handler lane) resolves when sealed AND
+  // handler inflight === 0. `fullySettled` additionally waits for the
+  // auxiliary (loader) lane. seal() signals "no more track() calls"; each
+  // track/trackAuxiliary increments its lane's count, each promise settle
+  // decrements. Barriers resolve once their conditions are met — even if
+  // tracks are added while earlier ones are still in flight.
   let sealed = false;
   let inflightCount = 0;
+  let auxInflightCount = 0;
   let drainWaiters: (() => void)[] = [];
+  let fullDrainWaiters: (() => void)[] = [];
+
+  // Swap the waiter list out before resolving: a resolver may synchronously
+  // re-await and push onto the fresh list, which must not be drained by this
+  // pass. All three waiter lists (drain, full-drain, emission) flush through
+  // here so that ordering rule cannot drift between them.
+  function flushWaiters(waiters: (() => void)[]): void {
+    for (const resolve of waiters) resolve();
+  }
+
+  // Both lanes settle identically — the handler lane (`track`) gates `settled`,
+  // the auxiliary loader lane (`trackAuxiliary`) gates `fullySettled`. Shared so
+  // neither copy can lose this rule: .then() rather than .finally(), because
+  // .finally() re-throws on a NEW branch, producing an unhandled rejection that
+  // can crash the process when the tracked promise rejects.
+  function trackSettlement<T>(
+    promise: Promise<T>,
+    release: () => void,
+  ): Promise<T> {
+    const onSettle = () => {
+      release();
+      notifyDrain();
+    };
+    promise.then(onSettle, onSettle);
+    return promise;
+  }
 
   function notifyDrain() {
     if (sealed && inflightCount === 0 && drainWaiters.length > 0) {
       const waiters = drainWaiters;
       drainWaiters = [];
-      for (const resolve of waiters) resolve();
+      flushWaiters(waiters);
+    }
+    if (sealed && inflightCount === 0 && auxInflightCount === 0) {
+      if (streamConsumed && !completed) {
+        // Late-push guard + stream termination key on FULL drain, so a
+        // streaming loader body's ctx.handle() push stays legal until the
+        // auxiliary lane empties. Armed only once a stream consumer exists —
+        // getData()-only paths (prerender collection) keep their historical
+        // no-guard behavior.
+        completed = true;
+        signalEmission();
+      }
+      if (fullDrainWaiters.length > 0) {
+        const waiters = fullDrainWaiters;
+        fullDrainWaiters = [];
+        flushWaiters(waiters);
+      }
     }
   }
 
@@ -174,44 +254,50 @@ export function createHandleStore(): HandleStore {
     notifyDrain();
   }
 
-  // Dirty flag for pending emissions and resolver for waiting consumer.
-  // stream() only ever yields the latest full state, so we track a single
-  // dirty bit and clone `data` once at yield time instead of per push.
-  let hasPendingEmission = false;
-  let emissionResolver: (() => void) | null = null;
+  // Emission versioning. Each push bumps `version`; every stream consumer
+  // keeps its own cursor and yields whenever the version advanced past it.
+  // Multi-consumer safe (the document "settled" stream and the late channel
+  // overlap until the handler barrier): a single dirty bit + single resolver
+  // slot would drop wakeups for all but one consumer.
+  let version = 0;
+  let emissionWaiters: (() => void)[] = [];
   let completed = false;
+  let streamConsumed = false;
 
-  // Signal that a new emission is available
+  // Wake every waiting consumer (new push or a settlement barrier fired).
   function signalEmission() {
-    if (emissionResolver) {
-      const resolver = emissionResolver;
-      emissionResolver = null;
-      resolver();
+    if (emissionWaiters.length > 0) {
+      const waiters = emissionWaiters;
+      emissionWaiters = [];
+      flushWaiters(waiters);
     }
   }
 
   // Wait for the next emission or completion
-  function waitForEmission(): Promise<void> {
-    if (hasPendingEmission || completed) {
+  // Resolve when the consumer's cursor is behind the current version, the
+  // given done-flag reader reports termination, or a new signal arrives.
+  function waitForEmission(seen: number, isDone: () => boolean): Promise<void> {
+    if (version > seen || isDone()) {
       return Promise.resolve();
     }
     return new Promise((resolve) => {
-      emissionResolver = resolve;
+      emissionWaiters.push(resolve);
     });
   }
 
   return {
     track<T>(promise: Promise<T>): Promise<T> {
       inflightCount++;
-      // Use .then() instead of .finally() to avoid creating an unhandled rejection
-      // branch when the promise rejects. .finally() re-throws on a new branch that
-      // can crash the process if not caught.
-      const onSettle = () => {
+      return trackSettlement(promise, () => {
         inflightCount--;
-        notifyDrain();
-      };
-      promise.then(onSettle, onSettle);
-      return promise;
+      });
+    },
+
+    trackAuxiliary<T>(promise: Promise<T>): Promise<T> {
+      auxInflightCount++;
+      return trackSettlement(promise, () => {
+        auxInflightCount--;
+      });
     },
 
     seal() {
@@ -225,6 +311,15 @@ export function createHandleStore(): HandleStore {
       });
     },
 
+    get fullySettled(): Promise<void> {
+      if (sealed && inflightCount === 0 && auxInflightCount === 0) {
+        return Promise.resolve();
+      }
+      return new Promise<void>((resolve) => {
+        fullDrainWaiters.push(resolve);
+      });
+    },
+
     push(handleName: string, segmentId: string, value: unknown): void {
       if (completed) {
         const error = createLateHandlePushError(handleName, segmentId);
@@ -240,8 +335,8 @@ export function createHandleStore(): HandleStore {
       }
       data[handleName][segmentId].push(value);
 
-      // Mark dirty; the actual snapshot is cloned once at yield time.
-      hasPendingEmission = true;
+      // Bump the version; each consumer's cursor decides when to clone+yield.
+      version++;
       signalEmission();
     },
 
@@ -250,33 +345,75 @@ export function createHandleStore(): HandleStore {
       return this.settled.then(() => cloneHandleData(data));
     },
 
-    async *stream(): AsyncGenerator<HandleData, void, unknown> {
+    async *stream(
+      until: "settled" | "fullySettled" = "fullySettled",
+    ): AsyncGenerator<HandleData, void, unknown> {
+      streamConsumed = true;
       sealInternal();
-
-      this.settled.then(() => {
-        completed = true;
+      // Re-evaluate: the store may have been sealed and drained BEFORE this
+      // consumer existed (seal() then stream()); sealInternal early-returns
+      // then, so the completed flag must be armed here.
+      notifyDrain();
+
+      // Per-consumer termination flag driven by the chosen barrier. The
+      // global `completed` (late-push guard) always keys on FULL drain via
+      // notifyDrain — a "settled"-scoped consumer finishing does not make
+      // later loader pushes illegal.
+      let done = false;
+      const barrier = until === "settled" ? this.settled : this.fullySettled;
+      barrier.then(() => {
+        done = true;
         signalEmission();
       });
 
       // Batch rapid synchronous pushes with initial delay
       await new Promise((resolve) => setTimeout(resolve, 0));
 
-      if (Object.keys(data).length > 0) {
-        hasPendingEmission = false;
-        yield cloneHandleData(data);
+      let seen = 0;
+      while (true) {
+        if (version > seen && Object.keys(data).length > 0) {
+          seen = version;
+          yield cloneHandleData(data);
+        }
+        if (done) break;
+        await waitForEmission(seen, () => done);
       }
+    },
 
-      while (!completed) {
-        await waitForEmission();
+    async *streamLate(): AsyncGenerator<HandleData, void, unknown> {
+      streamConsumed = true;
+      sealInternal();
+      // Re-evaluate: the store may have been sealed and drained BEFORE this
+      // consumer existed (seal() then stream()); sealInternal early-returns
+      // then, so the completed flag must be armed here.
+      notifyDrain();
+
+      // Skip everything the handler-barrier snapshot already carried; the
+      // document consumers (SSR seed + pre-hydration drain) deliver that
+      // state. This channel exists only for pushes that land AFTER `settled`
+      // — streaming loader bodies writing meta/breadcrumbs mid-body.
+      await this.settled;
+      let seen = version;
+      if (auxInflightCount === 0) {
+        // Auxiliary lane already drained: every loader push (if any) beat the
+        // handler barrier and rode the normal snapshot. Nothing late follows —
+        // handler pushes after settled are illegal by contract.
+        return;
+      }
 
-        if (hasPendingEmission) {
-          hasPendingEmission = false;
+      let done = false;
+      this.fullySettled.then(() => {
+        done = true;
+        signalEmission();
+      });
+
+      while (true) {
+        if (version > seen) {
+          seen = version;
           yield cloneHandleData(data);
         }
-      }
-
-      if (hasPendingEmission) {
-        yield cloneHandleData(data);
+        if (done) break;
+        await waitForEmission(seen, () => done);
       }
     },
 
@@ -303,7 +440,7 @@ export function createHandleStore(): HandleStore {
         // segment, not accumulate on top of data from a different route.
         data[handleName][segmentId] = [...segmentHandles[handleName]];
       }
-      hasPendingEmission = true;
+      version++;
       signalEmission();
     },
   };