@rangojs/router 0.21.0 → 0.22.0

package/src/testing/action-form.ts

@@ -0,0 +1,66 @@
+/**
+ * createActionForm: the FormData a browser posts when a form is submitted
+ * before hydration (no JavaScript), for a server action.
+ *
+ * React's server render writes hidden fields on the form so the POST names its
+ * action and carries the bound state; decodeAction / decodeFormState read them
+ * back. A test cannot render those fields (react-dom/server does not load under
+ * the react-server condition), so this builds the same wire format and
+ * registers the action where the plugin-rsc stub's decodeAction resolves it,
+ * tagged as a server reference like a built "use server" export so the bound
+ * action keeps its `$$id` (onError's actionId, the action phase label).
+ * Post the result with `serveShellRequest(router, url, { form })`.
+ */
+
+import * as RSDServer from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+import { registerServerModule } from "./internal/server-modules.js";
+
+/** Options for {@link createActionForm}. */
+export interface CreateActionFormOptions {
+  /**
+   * The action's reference id, `<module id>#<export name>`, as the build gives
+   * a "use server" export. Any unique string of that shape in a test.
+   */
+  id: string;
+  /**
+   * A `useActionState` form (default): the action runs as `(prevState, formData)`
+   * and the POST carries the state key. false: a plain `<form action={fn}>`
+   * ($ACTION_ID_), the action runs as `(formData)`.
+   */
+  useActionState?: boolean;
+  /** The form's own fields, as the person filled them. */
+  fields?: Record<string, string>;
+}
+
+/**
+ * Build a no-JS form POST body for `action` and register it so a handler
+ * decodes it back to `action`.
+ */
+export function createActionForm(
+  action: (...args: any[]) => unknown,
+  options: CreateActionFormOptions,
+): FormData {
+  const { id, useActionState = true, fields = {} } = options;
+  const [moduleId, name] = id.split("#");
+  if (!moduleId || !name) {
+    throw new Error(
+      `createActionForm: id must be "<module id>#<export name>", received ${JSON.stringify(id)}`,
+    );
+  }
+  registerServerModule(moduleId, {
+    [name]: RSDServer.registerServerReference(action, moduleId, name),
+  });
+
+  const form = new FormData();
+  if (useActionState) {
+    form.set("$ACTION_REF_1", "");
+    form.set("$ACTION_1:0", JSON.stringify({ id, bound: "$@1" }));
+    // The state the hook held when the form was submitted: its initial null.
+    form.set("$ACTION_1:1", "[null]");
+    form.set("$ACTION_KEY", "k0");
+  } else {
+    form.set(`$ACTION_ID_${id}`, "");
+  }
+  for (const [field, value] of Object.entries(fields)) form.set(field, value);
+  return form;
+}

package/src/testing/flight-runtime.d.ts

@@ -22,6 +22,33 @@ declare module "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge" {
   /** Server-side temporary-reference set (a WeakMap). */
   export function createTemporaryReferenceSet(): unknown;
 
+  /** Resolve a no-JS form POST to its action, bound to the form data; null for a plain form. */
+  export function decodeAction(
+    body: FormData,
+    serverManifest: unknown,
+  ): Promise<unknown> | null;
+
+  /** Decode an action's encoded arguments; rejects for a raw form body. */
+  export function decodeReply(
+    body: string | FormData,
+    serverManifest: unknown,
+    options?: object,
+  ): Promise<unknown>;
+
+  /** The useActionState form state of a no-JS POST, or null. */
+  export function decodeFormState(
+    actionResult: unknown,
+    body: FormData,
+    serverManifest: unknown,
+  ): Promise<unknown>;
+
+  /** Tag a function as a server reference; `$$id` becomes `${id}#${exportName}`. */
+  export function registerServerReference<T>(
+    reference: T,
+    id: string,
+    exportName: string,
+  ): T;
+
   /**
    * Tag a value as a client reference. Mutates `impl` in place (defining
    * `$$typeof`/`$$id`/`$$async`) and returns it, so a server tree that imports

package/src/testing/flight.entry.ts

@@ -56,6 +56,9 @@ export type {
   StateCookieSeed,
 } from "./render-handler.js";
 
+export { createActionForm } from "./action-form.js";
+export type { CreateActionFormOptions } from "./action-form.js";
+
 export {
   serveShellRequest,
   resetShellTestState,

package/src/testing/index.ts

@@ -61,6 +61,25 @@ export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
 
+// On-demand prerender: an in-memory WritablePrerenderStore fake for unit-testing
+// code that calls router.prerender(). Dep-free (a plain Map), so it stays on this
+// React/RSC-free barrel. See @rangojs/router/prerender for the store contracts.
+export { createMemoryPrerenderStore } from "../prerender/memory-prerender-store.js";
+export type {
+  MemoryPrerenderStore,
+  MemoryPrerenderStoreOptions,
+} from "../prerender/memory-prerender-store.js";
+export type {
+  WritablePrerenderStore,
+  PrerenderStoredEntry,
+  PrerenderKey,
+} from "../prerender/writable-store.js";
+export type {
+  PrerenderConfig,
+  PrerenderResult,
+  PrerenderWarmCaches,
+} from "../prerender/on-demand.js";
+
 export {
   assertCacheStatus,
   assertCacheDecision,

package/src/testing/internal/server-modules.ts

@@ -0,0 +1,32 @@
+/**
+ * Server reference modules a test registered, by the module id the action's
+ * `$$id` (`<module id>#<export name>`) names. The plugin-rsc stub's module
+ * loader reads this when decodeAction resolves a no-JS form POST to its action.
+ */
+const SERVER_MODULES: Map<string, Record<string, unknown>> = new Map();
+
+/**
+ * Register `exports` as the server module `id`, merging into an earlier call.
+ * The module object is kept and mutated: the stub's require is memoized per
+ * id, so a later export must appear on the object it first returned.
+ */
+export function registerServerModule(
+  id: string,
+  exports: Record<string, unknown>,
+): void {
+  const existing = SERVER_MODULES.get(id);
+  if (existing) Object.assign(existing, exports);
+  else SERVER_MODULES.set(id, { ...exports });
+}
+
+/** The module a decoded server reference resolves to. */
+export function loadServerModule(id: string): Record<string, unknown> {
+  const found = SERVER_MODULES.get(id);
+  if (!found) {
+    throw new Error(
+      `plugin-rsc stub: server reference module "${id}" is not loadable in a test. ` +
+        "Build the form with createActionForm() so its action is registered.",
+    );
+  }
+  return found;
+}

package/src/testing/render-route.tsx

@@ -110,9 +110,9 @@ import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
 import { isUnderTestRunner } from "../runtime-env.js";
 import { setupNavigationBridgeDelegatedPrefetch } from "../browser/navigation-bridge.js";
-import { resetAdaptiveStrategyForTesting } from "../browser/prefetch/default-strategy.js";
 import { resetPrefetchObserverForTesting } from "../browser/prefetch/observer.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
+import { auditTreeCause } from "../suspense-audit.js";
 
 const TEST_ORIGIN = "http://localhost";
 let activePrefetchRegistrations = 0;
@@ -491,7 +491,6 @@ function DelegatedPrefetchRegistration({
             }
             pendingPrefetchReset = undefined;
             resetPrefetchObserverForTesting();
-            resetAdaptiveStrategyForTesting();
           });
         }
       }
@@ -529,13 +528,14 @@ function HydratedMarker(): null {
 }
 
 /**
- * Applies `lateHandles` from an effect after the tree's: where production's
- * root effect releases the document's late handle channel
- * (browser/rsc-router.tsx hydrationCommitted). A boundary that hydrates in a
- * later pass finds the update applied.
+ * Runs `run` from an effect after the tree's. That is where production's late
+ * handle channel writes a push that arrives after the root hydrated (the store
+ * holds it while the hydration window is open, EventController.lockHydration),
+ * and where the document has been revealed (browser/rsc-router.tsx
+ * documentRevealed).
  */
-function LateHandles({ apply }: { apply: () => void }): null {
-  useEffect(apply, [apply]);
+function AfterTree({ run }: { run: () => void }): null {
+  useEffect(run, [run]);
   return null;
 }
 
@@ -751,8 +751,15 @@ export async function renderRoute(
   const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
   const initialSegmentIds = initialSegments.map((s) => s.id);
   eventController.setHandleData(resolvedSeed, initialSegmentIds);
-  // As initBrowserApp before hydrateRoot: what a hydrating reader reads.
-  eventController.freezeHydrationHandleState();
+  // As initBrowserApp before hydrateRoot: until the provider's barrier commit,
+  // handle reads return this state and later writes wait.
+  if (options.hydrate) eventController.lockHydration();
+  let resolveDocumentRevealed: (() => void) | undefined;
+  const documentRevealed = options.hydrate
+    ? new Promise<void>((resolve) => {
+        resolveDocumentRevealed = resolve;
+      })
+    : undefined;
   // A late update carries the full state: the seed with these handles' values
   // replaced, resolved as the browser resolves a late yield before applying.
   let applyLateHandles: (() => void) | undefined;
@@ -866,11 +873,15 @@ export async function renderRoute(
     }
     const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
+      // As production's emitters name their cause (suspense-audit.ts I6).
+      auditTreeCause("navigation");
       // Production's transition() lane (browser/partial-update.ts). Its
       // same-structure / fully-prefetched / optimistic hold lanes are not
       // modeled: without transition() the commit stays urgent.
       if (shouldStartViewTransition(segments, gatedOff)) {
-        commitInTransition(emit, segments, { root, metadata }, ["navigation"]);
+        commitInTransition(store.loaders, emit, segments, { root, metadata }, [
+          "navigation",
+        ]);
       } else {
         emit({ root, metadata });
       }
@@ -938,11 +949,13 @@ export async function renderRoute(
           options.theme === undefined ? null : resolveThemeConfig(options.theme)
         }
         nonce={options.nonce}
+        hydration={documentRevealed ? { settled: documentRevealed } : undefined}
       />
       <DelegatedPrefetchRegistration bridge={bridge} />
       <LinkInterceptionRegistration bridge={bridge} />
       {options.hydrate && <HydratedMarker />}
-      {applyLateHandles && <LateHandles apply={applyLateHandles} />}
+      {applyLateHandles && <AfterTree run={applyLateHandles} />}
+      {resolveDocumentRevealed && <AfterTree run={resolveDocumentRevealed} />}
     </>
   );
 

package/src/testing/serve-shell-request.ts

@@ -27,6 +27,14 @@
  * capture refuses for a root postpone (a live loader read with no boundary
  * above it) or an SSR render error is captured here.
  *
+ * A `Prerender` route serves its handler layer from the artifact
+ * `router.matchForPrerender` bakes for the URL (on its first request, kept
+ * until resetShellTestState), through the production prerender store. Its
+ * first `ppr` request is a MISS with a runtime capture, as a URL without a
+ * build-time shell is in production; build-time shells are e2e-only. An
+ * on-demand route (`Prerender(..., { onDemand })`) bakes nothing here: it
+ * serves from its prerender store, as a refresh-only page does in production.
+ *
  * Must run under the `react-server` condition (the rsc Vitest project), with
  * `rangoTestAliases()` resolving `@vitejs/plugin-rsc/rsc/server` to the stub
  * that carries the Flight runtime.
@@ -36,9 +44,14 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { toInternal, type Rango } from "../router/router-interfaces.js";
 import { ensureRouterManifest } from "../route-map-builder.js";
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import {
+  awaitLaterMillisecond,
+  createCollectingExecutionContext,
+} from "../cache/background-task.js";
 import type { ExecutionContext } from "../types/request-scope.js";
 import type { HandlerCacheConfig, SSRModule } from "../rsc/types.js";
 import type { createRSCHandler } from "../rsc/handler.js";
+import { setDefaultSSRModuleLoaderForTests } from "../rsc/ssr-module-loader.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   SHELL_CAPTURE_MAX_WAIT_MS,
@@ -77,6 +90,14 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * `result.replayStatus`.
    */
   partial?: true | { from?: string; segments?: readonly string[] };
+  /**
+   * POST this form as a submit before hydration: the no-JS request the
+   * progressive-enhancement path runs the action for and re-renders the page
+   * after. Build it with `createActionForm`. The response is the document
+   * (`flight` is its payload, `formState` what the SSR render received).
+   * Not with `partial`.
+   */
+  form?: FormData;
 }
 
 /** A response's handle data, as the browser consumes it. */
@@ -136,6 +157,19 @@ export interface ServeShellRequestResult {
    * values resolved. Undefined when no Flight was rendered.
    */
   readHandles(): Promise<ShellRequestHandles | undefined>;
+  /**
+   * The form state the SSR render received (the `formState` render option),
+   * or undefined when it received none.
+   */
+  formState: unknown;
+  /**
+   * The payload's `formState` as the browser reads it, the value the entry
+   * hands `hydrateRoot`. Undefined when the payload carries none (or no
+   * Flight was rendered). Rejects when the action's state is not
+   * Flight-serializable: the document still renders, and the entry
+   * hydrates without it.
+   */
+  readPayloadFormState(): Promise<unknown>;
 }
 
 type ShellHandler = ReturnType<typeof createRSCHandler>;
@@ -149,6 +183,8 @@ interface Recorder {
   rendered?: boolean;
   /** The HIT tail's Flight text. */
   tail?: string;
+  /** The formState render option of the document render. */
+  formState?: unknown;
 }
 
 const recorders = new AsyncLocalStorage<Recorder>();
@@ -168,9 +204,12 @@ function recordShellKey(recorder: Recorder | undefined): void {
 }
 
 const SSR_STUB: SSRModule = {
-  async renderHTML(rscStream) {
+  async renderHTML(rscStream, options) {
     const recorder = recorders.getStore();
-    if (recorder) recorder.rendered = true;
+    if (recorder) {
+      recorder.rendered = true;
+      recorder.formState = options?.formState ?? undefined;
+    }
     recordShellKey(recorder);
     return rscStream;
   },
@@ -226,8 +265,24 @@ const SSR_STUB: SSRModule = {
   },
 };
 
+/**
+ * `router.prerender()` warms a route through `router.fetch`, whose handler is
+ * built with no `loadSSRModule` and so reaches for the Vite RSC module loader
+ * this project cannot run. It gets the stub the handlers below get:
+ * everything else on a warm's path (router.fetch, createRSCHandler, the match
+ * pipeline, the capture) is production code. A warm runs outside a
+ * serveShellRequest call, so the stub records nothing for it.
+ */
+setDefaultSSRModuleLoaderForTests(async () => SSR_STUB);
+
 type HandleChannel = AsyncIterable<HandleData> | undefined;
 
+/** Decode a Flight payload as the browser does. */
+async function decodePayload<T>(flight: string): Promise<T> {
+  const { deserializeResult } = await import("../cache/segment-codec.js");
+  return deserializeResult<T>(flight);
+}
+
 /**
  * Read a payload's two handle channels as browser/rsc-router.tsx does:
  * `handles` to its end, then every `handlesLate` state.
@@ -235,8 +290,7 @@ type HandleChannel = AsyncIterable<HandleData> | undefined;
 async function decodePayloadHandles(
   flight: string,
 ): Promise<ShellRequestHandles> {
-  const { deserializeResult } = await import("../cache/segment-codec.js");
-  const { metadata } = await deserializeResult<{
+  const { metadata } = await decodePayload<{
     metadata?: { handles?: HandleChannel; handlesLate?: HandleChannel };
   }>(flight);
   let hydration: HandleData = {};
@@ -248,12 +302,92 @@ async function decodePayloadHandles(
   return { hydration: await resolveDeferredHandleValues(hydration), late };
 }
 
+/**
+ * Each router's Prerender artifacts by manifest key, as `vite build` bakes
+ * them (router.matchForPrerender), baked on a URL's first request the way the
+ * dev server's /__rsc_prerender endpoint bakes them (`devMode`: a Passthrough
+ * route keeps getParams()). `baked` holds the pathnames already tried, one
+ * that baked nothing (ctx.passthrough()) included.
+ */
+let prerenderArtifacts = new WeakMap<
+  object,
+  { payloads: Map<string, string>; baked: Set<string> }
+>();
+
+/**
+ * Serve a Prerender route's handler layer from its build-time artifact, as
+ * production does: through the store the built worker reads
+ * (createPrerenderStore over globalThis.__loadPrerenderManifestModule,
+ * installed as shell-prerender-phase.ts installs it for build-time shells).
+ * `env` stands in for the build's `buildEnv`. Returns the undo, or undefined
+ * when `pathname` matches no Prerender route.
+ */
+async function servePrerenderArtifacts(
+  router: Rango<any, any>,
+  pathname: string,
+  env: unknown,
+): Promise<(() => void) | undefined> {
+  const internal = toInternal(router);
+  const matched = await internal.findMatch(pathname);
+  // A build bakes an on-demand route only for the params getParams() lists;
+  // a refresh-only page serves from its prerender store alone. A Passthrough
+  // route is baked here like a build bakes it: the `devMode` render below
+  // asks its getParams() and declines a param it does not list. A plain
+  // on-demand route is not: nothing here asks its getParams(), and baking
+  // every requested param would hide the 404 an unbaked one answers.
+  if (!matched?.pr || (matched.od && !matched.pt)) return undefined;
+  let artifacts = prerenderArtifacts.get(router);
+  if (!artifacts) {
+    prerenderArtifacts.set(
+      router,
+      (artifacts = { payloads: new Map(), baked: new Set() }),
+    );
+  }
+  const { payloads, baked } = artifacts;
+  if (!baked.has(pathname)) {
+    const result = await internal.matchForPrerender(
+      pathname,
+      {},
+      undefined,
+      matched.pt === true,
+      env,
+      true,
+    );
+    const { hashParams } = await import("../prerender/param-hash.js");
+    baked.add(pathname);
+    if (result && !result.passthrough) {
+      payloads.set(
+        `${result.routeName}/${hashParams(result.params)}`,
+        JSON.stringify({ segments: result.segments, handles: result.handles }),
+      );
+    }
+  }
+  const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =
+    await Promise.all([
+      import("../prerender/store.js"),
+      import("../router/match-middleware/cache-lookup.js"),
+    ]);
+  const previousLoader = globalThis.__loadPrerenderManifestModule;
+  globalThis.__loadPrerenderManifestModule = async () => ({
+    default: Object.fromEntries([...payloads.keys()].map((key) => [key, key])),
+    loadPrerenderAsset: async (key) => ({
+      default: JSON.parse(payloads.get(key)!),
+    }),
+  });
+  const previousStore = setPrerenderStoreForTests(createPrerenderStore());
+  return () => {
+    globalThis.__loadPrerenderManifestModule = previousLoader;
+    setPrerenderStoreForTests(previousStore);
+  };
+}
+
 /**
  * Handlers per router, keyed by the `cacheStore` override or the router. A
- * handler resolves its router's versions when it is created, so an entry is
- * reused only while the router would still resolve the versions it was made
- * with: a setBuildVersions() call (a simulated deploy) that changes them gets
- * a new handler.
+ * handler binds its router's document version when it is created, so an entry
+ * is reused only while the router would still resolve that version: a
+ * setBuildVersions() call (a simulated deploy) that changes it gets a new
+ * handler. The data version is read per request, so a data-only change reuses
+ * the handler, as a long-lived worker would.
  */
 const handlers = new WeakMap<
   object,
@@ -273,11 +407,10 @@ async function getHandler(
   const { resolveRouterVersions } =
     await import("../server/build-version-table.js");
   // What createRSCHandler would resolve for this router now.
-  const { data, document } = resolveRouterVersions(
+  const { document: versions } = resolveRouterVersions(
     internal.id,
     internal.version,
   );
-  const versions = `${data}\0${document}`;
   const cached = byStore.get(cacheStore ?? router);
   if (cached?.versions === versions) return cached.handler;
 
@@ -305,6 +438,18 @@ async function getHandler(
 function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
   const headers = new Headers(options.headers);
   const partial = options.partial;
+  if (options.form) {
+    if (partial) {
+      throw new Error(
+        "serveShellRequest: form cannot be combined with partial",
+      );
+    }
+    return new Request(url, {
+      method: "POST",
+      headers,
+      body: options.form,
+    });
+  }
   if (!partial) {
     if (!headers.has("accept")) headers.set("accept", "text/html");
     return new Request(url, { headers });
@@ -327,25 +472,30 @@ function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
  * starts as a fresh worker would: the capture's stampede guard, its backoff
  * (a refused capture backs its URL off for later tests too), the shell path's
  * once-per-key warnings, the build-shell manifest memo, the "use cache"
- * in-flight leaders and warnings, and CFCacheStore's isolate memos (shells,
+ * in-flight leaders and warnings, CFCacheStore's isolate memos (shells,
  * tag markers, tag hints) and warnings, which every CFCacheStore in the
- * process shares by namespace and URL. Call it in `beforeEach`, never while
- * a request is in flight. VercelCacheStore's memos live on the `cache`
- * handle it is given: a new handle starts empty.
+ * process shares by namespace and URL, and the Prerender artifacts baked so
+ * far. Call it in `beforeEach`, never while a request is in flight.
+ * VercelCacheStore's memos live on the `cache` handle it is given: a new
+ * handle starts empty.
  */
 export async function resetShellTestState(): Promise<void> {
-  const [capture, serve, buildShells, cf, cacheRuntime] = await Promise.all([
-    import("../rsc/shell-capture.js"),
-    import("../rsc/shell-serve.js"),
-    import("../rsc/shell-build-manifest.js"),
-    import("../cache/cf/cf-cache-store.js"),
-    import("../cache/cache-runtime.js"),
-  ]);
+  prerenderArtifacts = new WeakMap();
+  const [capture, serve, buildShells, cf, cacheRuntime, cacheLookup] =
+    await Promise.all([
+      import("../rsc/shell-capture.js"),
+      import("../rsc/shell-serve.js"),
+      import("../rsc/shell-build-manifest.js"),
+      import("../cache/cf/cf-cache-store.js"),
+      import("../cache/cache-runtime.js"),
+      import("../router/match-middleware/cache-lookup.js"),
+    ]);
   capture.resetShellCaptureStateForTests();
   serve.resetShellServeStateForTests();
   buildShells.resetBuildShellManifestForTests();
   cf.resetCFShellMemoForTests();
   cacheRuntime.resetCacheRuntimeForTests();
+  cacheLookup.resetOverlayRevalidationsForTests();
 }
 
 /** Settle background tasks, including ones scheduled while settling. */
@@ -387,19 +537,15 @@ export async function serveShellRequest<TEnv = any>(
   await ensureRouterManifest(router.id);
   const handler = await getHandler(router, options.cacheStore);
   const request = buildRequest(target, options);
-  const tasks: Promise<unknown>[] = [];
-  const executionContext: ExecutionContext = {
-    waitUntil(promise) {
-      tasks.push(
-        Promise.resolve(promise).catch((error) =>
-          console.error("[waitUntil] Background task failed:", error),
-        ),
-      );
-    },
-    passThroughOnException() {},
-  };
+  const executionContext = createCollectingExecutionContext();
+  const { tasks } = executionContext;
   const recorder: Recorder = {};
-  while (Date.now() === called) await macrotask();
+  const unservePrerender = await servePrerenderArtifacts(
+    router,
+    target.pathname,
+    options.env,
+  );
+  await awaitLaterMillisecond(called);
 
   const { response, body } = await recorders.run(recorder, async () => {
     try {
@@ -410,6 +556,7 @@ export async function serveShellRequest<TEnv = any>(
       return { response, body: await response.text() };
     } finally {
       await settle(tasks);
+      unservePrerender?.();
     }
   });
 
@@ -417,7 +564,8 @@ export async function serveShellRequest<TEnv = any>(
     recorder.cache && recorder.cache.enabled !== false
       ? recorder.cache
       : undefined;
-  const key = recorder.shellKey ?? shellCacheKey(target, config?.searchParams);
+  const key =
+    recorder.shellKey ?? shellCacheKey(router, target, config?.searchParams);
   const tail = recorder.tail;
   const isFlight =
     recorder.rendered ||
@@ -446,5 +594,13 @@ export async function serveShellRequest<TEnv = any>(
     async readHandles() {
       return flight ? decodePayloadHandles(flight) : undefined;
     },
+    formState: recorder.formState,
+    async readPayloadFormState() {
+      if (!flight) return undefined;
+      const payload = await decodePayload<{
+        formState?: Promise<unknown>;
+      }>(flight);
+      return payload.formState;
+    },
   };
 }

package/src/testing/shell-status.ts

@@ -15,7 +15,7 @@
  * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
  *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
  *    HIT is reported only when matching consumes the captured segment record.
- *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
+ *    Secondary unit signal: `store.getShell(shellCacheKey(router, url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
  * 3. **A real MISS → capture → HIT in unit tests:** `serveShellRequest`
@@ -82,10 +82,16 @@ export interface ShellCachePartition {
 }
 
 /**
- * Shell store key for a document URL: the production `buildShellKey` (host +
- * pathname + sorted search + `:shell`) and `partitionShellKey`, both from the
- * React-free leaf `rsc/shell-capture-constants.ts`, so the testing barrel never
- * imports the shell-serve module (it pulls React).
+ * Shell store key of `router` for a document URL: the production
+ * `buildShellKey` (router id + host + pathname + sorted search + `:shell`)
+ * and `partitionShellKey`, both from the React-free leaf
+ * `rsc/shell-capture-constants.ts`, so the testing barrel never imports the
+ * shell-serve module (it pulls React).
+ *
+ * `router` is the router that serves the URL, or anything carrying its `id`
+ * (`{ id }` where the router cannot be imported, as in a Playwright test). A
+ * shell belongs to one router: two routers serving one host and path keep
+ * two entries.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
  * resolve against `http://localhost`). Pass the router's `cache.searchParams`
@@ -101,13 +107,18 @@ export interface ShellCachePartition {
  *   `{ keys, generated }` (see {@link ShellCachePartition}).
  */
 export function shellCacheKey(
+  router: { readonly id: string },
   url: URL | string,
   searchParams?: CacheSearchParams,
   partition?: string | readonly string[] | ShellCachePartition,
 ): string {
   const resolved =
     typeof url === "string" ? new URL(url, "http://localhost") : url;
-  const key = buildShellKey(resolved, compileSearchParamsFilter(searchParams));
+  const key = buildShellKey(
+    router.id,
+    resolved,
+    compileSearchParamsFilter(searchParams),
+  );
   if (partition === undefined) return key;
   const { keys = [], generated = [] }: ShellCachePartition =
     typeof partition === "string"