@rangojs/router 0.5.2 → 0.6.0

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();
     },
   };

package/src/server/request-context.ts

@@ -618,6 +618,17 @@ export interface RequestContext<
    */
   _handlerLoaderDeps?: Set<string>;
 
+  /**
+   * @internal Loader IDs ($$id) whose entries carry `awaitBeforeFlush`
+   * (loader(Def, { stream: "navigation" })): segment resolution awaits these
+   * before returning, so the render barrier cannot resolve until they settle.
+   * rendered() checks this set to fail fast — a flagged loader awaiting the
+   * barrier is a guaranteed cycle, not a race. Registered by resolveLoaders
+   * (fresh.ts) before loader kickoff; only ever populated on document renders
+   * (the flag is stamped per-isSSR at DSL evaluation).
+   */
+  _awaitBeforeFlushLoaderIds?: Set<string>;
+
   /**
    * @internal Cached HandleData snapshot built at barrier resolution time.
    * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
@@ -765,6 +776,7 @@ export type PublicRequestContext<
   | "_treeHasStreaming"
   | "_renderBarrierWaiters"
   | "_handlerLoaderDeps"
+  | "_awaitBeforeFlushLoaderIds"
   | "_renderBarrierHandleSnapshot"
   | "_renderBarrierGuardClosed"
   | "_reportBackgroundError"
@@ -1384,6 +1396,7 @@ export function wireRenderBarrier(
   ctx._renderBarrierHandleSnapshot = undefined;
   ctx._renderBarrierGuardClosed = undefined;
   ctx._handlerLoaderDeps = undefined;
+  ctx._awaitBeforeFlushLoaderIds = undefined;
   ctx._treeHasStreaming = undefined;
 
   // Lazy allocation: only create the Promise when a loader calls rendered().
@@ -1626,12 +1639,23 @@ export function createUseFunction<TEnv>(
       env: ctx.env as any,
       waitUntil: ctx.waitUntil.bind(ctx),
       executionContext: ctx.executionContext,
-      get: ctx.get as any,
-      use: (<TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        return ctx.use(dep);
-      }) as LoaderContext["use"],
+      get: ((keyOrVar: any) => {
+        // Handle READS need the rendered() barrier, which this lane
+        // (action/dispatch-invoked loaders) does not run. Fail with guidance
+        // instead of returning a misleading empty collect.
+        if (isHandle(keyOrVar)) {
+          throw new Error(
+            `ctx.get(handle) is only available in DSL loaders after ` +
+              `"await ctx.rendered()". It cannot be used from request-context ` +
+              `loaders or server actions.`,
+          );
+        }
+        return (ctx.get as any)(keyOrVar);
+      }) as any,
+      // Pass items through: loaders delegate to the request ctx's loader
+      // executor; a handle yields the ctx's push function (write parity —
+      // ctx.use(Meta)({...}) works in this lane exactly like in a handler).
+      use: ((item: any) => ctx.use(item)) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: createReverseFunction(

package/src/server.ts

@@ -47,3 +47,10 @@ export {
 
 // Component utilities (used internally for server/client boundary checks)
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
+
+// Client URL projection registry (Vite discovery/bootstrap bridge)
+export {
+  clearClientUrlProjections,
+  setClientUrlProjection,
+  type ClientUrlProjection,
+} from "./client-urls/server-projection.js";

package/src/ssr/index.tsx

@@ -105,6 +105,15 @@ export interface SSRRenderOptions {
    * - `"allReady"` — await `stream.allReady` before returning.
    */
   streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /**
+   * The live request's query string (`?`-prefixed or empty). Seeds the SSR
+   * navigation store location so `useSearchParams` carries real values
+   * during document renders. Absent on the build-time prerender pass —
+   * build shells capture bare pathnames and serve search-less requests
+   * only (runtime captures own the search variants, seeded per key).
+   */
+  search?: string;
 }
 
 /**
@@ -347,6 +356,13 @@ interface ShellCaptureOptions {
   quiesce: Promise<void>;
   /** Upper bound on how long to wait for `quiesce`. Default SHELL_CAPTURE_MAX_WAIT_MS. */
   maxWaitMs?: number;
+  /**
+   * The SHELL KEY's search string (`?`-prefixed, sorted, cache.searchParams
+   * filter applied — shellSearchSeed in rsc/shell-serve.ts), seeding the SSR
+   * store so static-part `useSearchParams` reads bake markup consistent with
+   * the shell's own key. MUST equal the resume pass's seed for the same key.
+   */
+  search?: string;
 }
 
 /**
@@ -368,6 +384,13 @@ interface ShellResumeOptions {
   postponed: string | null;
   /** Nonce for CSP. */
   nonce?: string;
+  /**
+   * The SHELL KEY's search string — same derivation as the capture pass
+   * (shellSearchSeed). A HIT shares the capture's key, so seeding the same
+   * string keeps the resume tree identical to the captured tree above the
+   * postponed holes.
+   */
+  search?: string;
 }
 
 /**
@@ -449,7 +472,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState, streamMode } = options ?? {};
+    const { nonce, formState, streamMode, search } = options ?? {};
 
     try {
       // Tee the stream:
@@ -461,6 +484,12 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         createFromReadableStream,
         rscStream: rscStream1,
         nonce,
+        // Live fizz seeds the request's RAW search. The shell capture pass
+        // below and its resume twin seed the SHELL KEY's search instead
+        // (sorted, cache.searchParams filter applied — shellSearchSeed):
+        // same key => same seed, so the resume tree matches the captured
+        // tree while static-part search reads render what the key names.
+        search,
       });
 
       // Get bootstrap script content
@@ -562,6 +591,9 @@ export function createShellCaptureHandler<TEnv = unknown>(
         createFromReadableStream,
         rscStream,
         onPayloadSettled: settlePayload,
+        // The shell key's own search: static-part search reads render what
+        // the key names, and the resume pass seeds the identical string.
+        search: opts.search,
       });
 
       // Bootstrap load raced against the deadline. A load that never resolves
@@ -735,7 +767,7 @@ export function createShellResumeHandler<TEnv = unknown>(
     rscStream: ReadableStream<Uint8Array>,
     opts: ShellResumeOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { postponed, nonce } = opts;
+    const { postponed, nonce, search } = opts;
 
     try {
       if (postponed === null) {
@@ -765,6 +797,9 @@ export function createShellResumeHandler<TEnv = unknown>(
         createFromReadableStream,
         rscStream: rscStream1,
         nonce,
+        // Same seed as the capture pass for this key: the resume tree must
+        // match the captured tree above the holes, search reads included.
+        search,
       });
 
       // EAGER injection (resume-only): the stored prelude — a complete document

package/src/ssr/ssr-root.tsx

@@ -63,11 +63,21 @@ async function consumeAsyncGenerator(
  */
 function createSsrEventController(opts: {
   pathname: string;
+  /**
+   * Query string seeding the store location. Live fizz passes the request's
+   * raw search; ppr capture/resume pass the SHELL KEY's search (sorted,
+   * cache.searchParams filter applied) so the shell renders what its key
+   * names and both passes agree byte-for-byte.
+   */
+  search?: string;
   params?: Record<string, string>;
   handleData?: HandleData;
   matched?: string[];
 }): EventController {
-  const location = new URL(opts.pathname, "http://localhost");
+  const location = new URL(
+    `${opts.pathname}${opts.search ?? ""}`,
+    "http://localhost",
+  );
   let params = opts.params ?? {};
   const rawMatched = opts.matched ?? [];
   const handleState = {
@@ -142,6 +152,16 @@ export interface SsrRootOptions {
    * they postpone below the root.
    */
   onPayloadSettled?: () => void;
+  /**
+   * The query string seeding the SSR store location (`?`-prefixed or
+   * empty), so `useSearchParams`/`useNavigation` carry real values during
+   * document renders. Live fizz passes the request's raw search. The shell
+   * capture and resume passes pass the SHELL KEY's search (sorted,
+   * cache.searchParams filter applied — search is part of shell identity):
+   * a HIT shares the capture's key, so both passes seed the SAME string and
+   * the resume tree matches the captured tree above the postponed holes.
+   */
+  search?: string;
 }
 
 /**
@@ -162,7 +182,13 @@ export interface SsrRootOptions {
  * re-running the whole segment-tree build unless the promise is memoized.
  */
 export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
-  const { createFromReadableStream, rscStream, nonce, onPayloadSettled } = opts;
+  const {
+    createFromReadableStream,
+    rscStream,
+    nonce,
+    onPayloadSettled,
+    search,
+  } = opts;
 
   let payload: Promise<RscPayload> | undefined;
   let handlesPromise: Promise<HandleData> | undefined;
@@ -211,6 +237,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
       store: null as any,
       eventController: createSsrEventController({
         pathname,
+        search,
         params: resolved.metadata?.params,
         handleData,
         matched: resolved.metadata?.matched,

package/src/testing/dom.entry.ts

@@ -3,7 +3,7 @@
  *
  * Component-render testing: `renderRoute`, the React-Testing-Library-style stub
  * for client components that read router context (useParams / useReverse /
- * Outlet / useNavigation / useLoader).
+ * Outlet / useOutlet / useNavigation / useLoader).
  *
  * Separate from the main `@rangojs/router/testing` barrel so unit suites that
  * only test loaders, middleware, or `dispatch` never reference React, the