@rangojs/router 0.21.0 → 0.22.1

package/src/testing/vitest-stubs/plugin-rsc.ts

@@ -17,10 +17,15 @@
  *
  * Without the condition React's server build refuses to load, so the codec
  * functions throw and a "use cache" call runs uncached. Any other load failure
- * (a moved vendored path, a missing peer) throws. The action entries stay
- * inert either way: no primitive decodes an action request.
+ * (a moved vendored path, a missing peer) throws. decodeAction and
+ * decodeFormState decode a no-JS form POST under the condition, resolving its
+ * action from the modules createActionForm() registered, as do
+ * `loadServerAction` and `decodeReply` for a plain form action. Without the
+ * condition they stay inert.
  */
 
+import { loadServerModule } from "../internal/server-modules.js";
+
 /** React's server build throws this on load without the react-server condition. */
 const MISSING_REACT_SERVER_CONDITION =
   /"react-server" condition must be enabled/;
@@ -52,11 +57,7 @@ async function loadFlightRuntime() {
   // Resolves the `$$decode-client:` / `$$preserve:` ids a cached value's client
   // and server references decode to; any other id would load a server module.
   core.setRequireModule({
-    load: (id) => {
-      throw new Error(
-        `plugin-rsc stub: server reference module "${id}" is not loadable in a test`,
-      );
-    },
+    load: (id) => loadServerModule(id),
   });
   return { server, client, core };
 }
@@ -121,7 +122,32 @@ export const encodeReply = (
     : unavailable("encodeReply");
 export const createClientTemporaryReferenceSet = (): unknown =>
   runtime ? runtime.client.createTemporaryReferenceSet() : {};
-export const loadServerAction = (): undefined => undefined;
-export const decodeReply = (): undefined => undefined;
-export const decodeAction = (): undefined => undefined;
-export const decodeFormState = (): undefined => undefined;
+export const loadServerAction = (id: string): Promise<unknown> | undefined => {
+  if (!runtime) return undefined;
+  const [file, name] = id.split("#");
+  return Promise.resolve(loadServerModule(file!)[name!]);
+};
+export const decodeReply = (
+  body: string | FormData,
+  options?: object,
+): Promise<unknown> | undefined =>
+  runtime
+    ? runtime.server.decodeReply(body, referenceManifest("$$server:"), options)
+    : undefined;
+export const decodeAction = (
+  body: FormData,
+): Promise<unknown> | null | undefined =>
+  runtime
+    ? runtime.server.decodeAction(body, referenceManifest("$$server:"))
+    : undefined;
+export const decodeFormState = (
+  actionResult: unknown,
+  body: FormData,
+): Promise<unknown> | undefined =>
+  runtime
+    ? runtime.server.decodeFormState(
+        actionResult,
+        body,
+        referenceManifest("$$server:"),
+      )
+    : undefined;

package/src/thenable-status.ts

@@ -14,3 +14,13 @@ export function unwrapsSynchronously(stream: Promise<unknown>): boolean {
     status === "resolved_module"
   );
 }
+
+/**
+ * A resolved thenable for a use() whose result is ignored: React reads the
+ * "fulfilled" stamp and returns at once. `_debugInfo` keeps React DevTools from
+ * listing a 0 ms promise on every reader that calls it.
+ */
+export const SETTLED_THENABLE: Promise<undefined> = Object.assign(
+  Promise.resolve(undefined),
+  { status: "fulfilled", value: undefined, _debugInfo: [] },
+);

package/src/types/handler-context.ts

@@ -449,6 +449,13 @@ export type InternalHandlerContext<
   _responseType?: string;
   /** Route name for cache key scoping (prevents cross-route collisions). */
   _routeName?: string;
+  /**
+   * @internal The on-demand overlay holds a "removed" marker for this request
+   * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On
+   * this context, not the request's: withCacheLookup documents that the
+   * request ALS can be lost mid-pipeline on workerd.
+   */
+  _prerenderRemoved?: true;
   /**
    * @internal Loader-cache override table: loaderId -> memoized data promise.
    * A single stable ctx.use interceptor consults this instead of chaining one

package/src/types/route-entry.ts

@@ -82,6 +82,12 @@ export interface RouteEntry<TEnv = any> {
    */
   passthroughRouteKeys?: Set<string>;
 
+  /**
+   * Route keys in this entry that opted into on-demand prerender.
+   * Used by the non-trie match path to set the `od` flag.
+   */
+  onDemandRouteKeys?: Set<string>;
+
   // === Lazy evaluation fields ===
 
   /**

package/src/urls/path-helper.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Handler } from "../types.js";
+import type { Handler, InternalHandlerContext } from "../types.js";
 import type { RouteItem, RouteUseItem, UseItems } from "../route-types.js";
 import {
   getUrlPrefix,
@@ -8,7 +8,7 @@ import {
   requireDslContext,
   stampStaticDefScope,
 } from "../server/context";
-import { invariant, DataNotFoundError } from "../errors";
+import { invariant, DataNotFoundError, isDevEnvironment } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import {
   isPrerenderHandler,
@@ -60,6 +60,41 @@ function resolveResponseType(
   return options?.[RESPONSE_TYPE];
 }
 
+const NO_PRERENDER_DATA_MESSAGE = "No prerender data found for this route";
+
+/**
+ * A retained on-demand producer must never render on a live production
+ * request: bundle eviction is skipped for onDemand routes (the producer body
+ * stays available for router.prerender()), so without this gate an
+ * overlay+manifest miss on a plain Prerender(..., { onDemand }) route would
+ * execute the producer in-request — uncached per-request renders with the
+ * personalization guard unarmed. Keep the pre-retention miss contract instead
+ * (DataNotFoundError -> 404). Producer runs (build-time bake and
+ * router.prerender()) arrive with ctx.build true (createPrerenderContext);
+ * Vite dev keeps the documented live fall-through on a dev-store miss, except
+ * for a page the overlay marks removed (`_prerenderRemoved`): a live render
+ * would show in dev a page production answers with a 404.
+ * Pass-through when the route is not onDemand.
+ *
+ * @internal Exported for the unit test.
+ */
+export function gateOnDemandProducer<TEnv>(
+  producer: Handler<any, any, TEnv>,
+  isOnDemand: boolean,
+): Handler<any, any, TEnv> {
+  if (!isOnDemand) return producer;
+  return (ctx) => {
+    if (
+      !ctx.build &&
+      (!isDevEnvironment() ||
+        (ctx as InternalHandlerContext<any, TEnv>)._prerenderRemoved)
+    ) {
+      throw new DataNotFoundError(NO_PRERENDER_DATA_MESSAGE);
+    }
+    return producer(ctx);
+  };
+}
+
 export function createPathHelper<TEnv>(): PathFn<TEnv> {
   return ((
     pattern: string,
@@ -117,6 +152,31 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
 
+    // On-demand opt-in lives on the (inner) Prerender def's options for both
+    // plain Prerender and Passthrough-wrapped routes. Presence (truthy, not
+    // false) marks the route ISR-eligible; the trie od flag + producer retention
+    // key off it.
+    const onDemandDef = isPassthroughHandler(handler)
+      ? handler.prerenderDef
+      : isPrerenderHandler(handler)
+        ? handler
+        : undefined;
+    const onDemandOpt = onDemandDef?.options?.onDemand;
+    const isOnDemand = onDemandOpt != null && onDemandOpt !== false;
+
+    // onDemand routes are excluded from the PPR shell lane (a writable refresh
+    // cannot atomically replace the captured shell), so ppr has no effect there.
+    // Thrown ahead of the forRoute early return so lazy evaluation of another
+    // route cannot skip it.
+    if (isOnDemand && options?.ppr !== undefined && options.ppr !== false) {
+      throw new Error(
+        `[rango] Route "${routeName}" sets both ppr and onDemand: onDemand ` +
+          `routes are excluded from the PPR shell lane, so ppr has no ` +
+          `effect here and the route serves without the shell fast path. ` +
+          `Drop one of the two options.`,
+      );
+    }
+
     if (ctx.forRoute && routeName !== ctx.forRoute) {
       store.getShortCode("route");
       return { type: "route" } as RouteItem;
@@ -129,17 +189,16 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
           ? typeof handler.prerenderDef.handler === "function"
             ? (handler.prerenderDef.handler as Handler<any, any, TEnv>)
             : () => {
-                throw new DataNotFoundError(
-                  "No prerender data found for this route",
-                );
+                throw new DataNotFoundError(NO_PRERENDER_DATA_MESSAGE);
               }
           : isPrerenderHandler(handler)
             ? typeof handler.handler === "function"
-              ? (handler.handler as Handler<any, any, TEnv>)
+              ? gateOnDemandProducer(
+                  handler.handler as Handler<any, any, TEnv>,
+                  isOnDemand,
+                )
               : () => {
-                  throw new DataNotFoundError(
-                    "No prerender data found for this route",
-                  );
+                  throw new DataNotFoundError(NO_PRERENDER_DATA_MESSAGE);
                 }
             : isStaticHandler(handler)
               ? (handler.handler as Handler<any, any, TEnv>)
@@ -168,6 +227,7 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
               prerenderDef: handler as PrerenderHandlerDefinition,
             }
           : {}),
+      ...(isOnDemand ? { isOnDemand: true as const } : {}),
       ...(isStaticHandler(handler)
         ? {
             isStaticPrerender: true as const,

package/src/use-loader.tsx

@@ -14,9 +14,17 @@ import {
   type ReactNode,
 } from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
-import { loaderStore, type LoaderEntry } from "./loader-store.js";
+import {
+  EMPTY_LOADER_SNAPSHOT,
+  type LoaderEntry,
+  type LoaderStore,
+} from "./loader-store.js";
+import { NavigationStoreContext } from "./browser/react/context.js";
 import { decodeLoaderEntry } from "./decode-loader-results.js";
 import { warnAwaitedSsrSuspension } from "./ssr-suspension-warning.js";
+import { SETTLED_THENABLE } from "./thenable-status.js";
+import { useReadAudit } from "./suspense-audit-react.js";
+import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
 function isShareableGet(options: LoadOptions | undefined): boolean {
@@ -202,15 +210,18 @@ function useLoaderInternal<T>(
     }
     return { contextData: undefined, hasContextData: false };
   }, [context, loader.$$id]);
-
   // SPIKE (streaming useLoader): a pending per-loader stream suspends HERE —
-  // the implicit-suspense read. use() is exempt from hook-order rules, so the
-  // conditional call is legal; on replay after resolution it returns
+  // the implicit-suspense read. On replay after resolution use() returns
   // synchronously and the decoded value takes the contextData slot. Hooks
   // below never run in a suspended render, so their order is stable across
   // every COMPLETED render.
   const { hasContextData } = walk;
   let contextData = walk.contextData;
+  // Dev only (suspense-audit.ts): the stream this reader is handed. The test
+  // is a build-time constant, so the hook is called on every render or never.
+  if (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT) {
+    useReadAudit(loader.$$id, walk.pendingStream);
+  }
   if (walk.pendingStream) {
     warnAwaitedSsrSuspension(
       loader.$$id,
@@ -218,6 +229,10 @@ function useLoaderInternal<T>(
       walk.pendingStream,
     );
     contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
+  } else if (hasContextData) {
+    // React logs a render that finishes without use() at a place whose reader
+    // suspended in use() on mount, so every read with route context calls it.
+    use(SETTLED_THENABLE);
   }
 
   const loaderId = loader.$$id;
@@ -245,10 +260,15 @@ function useLoaderInternal<T>(
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
+  // The router store's loader data (loader-store.ts). None on the server,
+  // where the hook reads the route's loader data only.
+  const loaders: LoaderStore | undefined = useContext(NavigationStoreContext)
+    ?.store?.loaders;
+
   const groupRefetch = useCallback(async (): Promise<void> => {
-    if (!loaderId) return;
-    const requestId = loaderStore.reserveRequestId(bucketKey);
-    loaderStore.beginRequest(bucketKey, requestId);
+    if (!loaderId || !loaders) return;
+    const requestId = loaders.reserveRequestId(bucketKey);
+    loaders.beginRequest(bucketKey, requestId);
     try {
       const url = new URL(window.location.href);
       url.searchParams.set("_rsc_loader", loaderId);
@@ -261,15 +281,15 @@ function useLoaderInternal<T>(
       if (payload.loaderError) {
         throw new Error(payload.loaderError.message);
       }
-      loaderStore.finishData(bucketKey, requestId, payload.loaderResult);
+      loaders.finishData(bucketKey, requestId, payload.loaderResult);
     } catch (e) {
       const err = e instanceof Error ? e : new Error(String(e));
-      loaderStore.finishError(bucketKey, requestId, err);
+      loaders.finishError(bucketKey, requestId, err);
       throw err;
     } finally {
-      loaderStore.setLoading(bucketKey, requestId, false);
+      loaders.setLoading(bucketKey, requestId, false);
     }
-  }, [loaderId, bucketKey]);
+  }, [loaderId, bucketKey, loaders]);
 
   // Held-navigation pin: a transition commit whose stream for this loader is
   // still pending announces it (loader-store.ts announcePendingStreams, which
@@ -283,14 +303,17 @@ function useLoaderInternal<T>(
     snapshot: LoaderEntry;
   }>(() => ({
     bucketKey,
-    snapshot: loaderStore.getSnapshot(bucketKey),
+    snapshot: loaders?.getSnapshot(bucketKey) ?? EMPTY_LOADER_SNAPSHOT,
   }));
+  // A new bucket (its key changed) reads nothing from the store during
+  // render: it renders empty until the effect below delivers its snapshot.
   const sharedSnapshot =
     sharedState.bucketKey === bucketKey
       ? sharedState.snapshot
-      : loaderStore.getSnapshot(bucketKey);
+      : EMPTY_LOADER_SNAPSHOT;
   useEffect(() => {
-    const initial = loaderStore.getSnapshot(bucketKey);
+    if (!loaders) return;
+    const initial = loaders.getSnapshot(bucketKey);
     if (initial !== sharedSnapshot) {
       startTransition(() => {
         setSharedState({ bucketKey, snapshot: initial });
@@ -299,10 +322,10 @@ function useLoaderInternal<T>(
     // ephemeral: a reader with no route context has no route-context reset
     // trigger, so its keyed bucket is reference-counted by the store. A
     // route-registered reader makes the bucket sticky (reset via clearFamily).
-    return loaderStore.subscribe(
+    return loaders.subscribe(
       bucketKey,
       () => {
-        const next = loaderStore.getSnapshot(bucketKey);
+        const next = loaders.getSnapshot(bucketKey);
         startTransition(() => {
           setSharedState({ bucketKey, snapshot: next });
         });
@@ -323,7 +346,7 @@ function useLoaderInternal<T>(
     // groupKey, and groupRefetch are the only inputs that require a fresh
     // subscription (groupList is memoized on groupKey; groupRefetch is stable
     // per bucketKey).
-  }, [bucketKey, hasContextData, groupKey, groupRefetch]);
+  }, [bucketKey, hasContextData, groupKey, groupRefetch, loaders]);
 
   // Local state holds the result of:
   //   - parameterized / mutation `load()` calls (load({ params }), POST,
@@ -369,10 +392,10 @@ function useLoaderInternal<T>(
       lastSharedRequestIdRef.current = null;
       // Reset every sticky bucket of this loader (keyed or not). Ephemeral
       // (unregistered keyed) buckets are left to their refcount lifecycle.
-      loaderStore.clearFamily(loaderId);
+      loaders?.clearFamily(loaderId);
       prevContextDataRef.current = contextData;
     }
-  }, [contextData, loaderId]);
+  }, [contextData, loaderId, loaders]);
 
   // Read priority: a committed parameterized load() result overrides the shared
   // snapshot; a committed shared snapshot overrides the server-seeded context.
@@ -408,15 +431,17 @@ function useLoaderInternal<T>(
       const bucket = bucketKeyRef.current;
       const hasDedicatedBucket = bucket !== id;
 
-      const shared = hasDedicatedBucket
-        ? isShareableGet(loadOptions)
-        : isPlainRefetch(loadOptions) && hasContextDataRef.current;
+      const shared =
+        loaders !== undefined &&
+        (hasDedicatedBucket
+          ? isShareableGet(loadOptions)
+          : isPlainRefetch(loadOptions) && hasContextDataRef.current);
       let sharedRequestId = -1;
       let localRequestId = -1;
       if (shared) {
-        sharedRequestId = loaderStore.reserveRequestId(bucket);
+        sharedRequestId = loaders.reserveRequestId(bucket);
         lastSharedRequestIdRef.current = sharedRequestId;
-        loaderStore.beginRequest(bucket, sharedRequestId);
+        loaders.beginRequest(bucket, sharedRequestId);
       } else {
         localRequestId = ++localRequestIdRef.current;
         setLocalIsLoading(true);
@@ -503,7 +528,7 @@ function useLoaderInternal<T>(
 
         const result = payload.loaderResult;
         if (shared) {
-          loaderStore.finishData(bucket, sharedRequestId, result);
+          loaders.finishData(bucket, sharedRequestId, result);
         } else if (localRequestId === localRequestIdRef.current) {
           startTransition(() => {
             setLocalFetchedData({ has: true, value: result });
@@ -514,7 +539,7 @@ function useLoaderInternal<T>(
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
         if (shared) {
-          loaderStore.finishError(bucket, sharedRequestId, err);
+          loaders.finishError(bucket, sharedRequestId, err);
         } else if (localRequestId === localRequestIdRef.current) {
           setLocalError(err);
           setLocalIsLoading(false);
@@ -525,11 +550,11 @@ function useLoaderInternal<T>(
         return dataRef.current as T;
       } finally {
         if (shared) {
-          loaderStore.setLoading(bucket, sharedRequestId, false);
+          loaders.setLoading(bucket, sharedRequestId, false);
         }
       }
     },
-    [throwOnError],
+    [throwOnError, loaders],
   );
 
   if (throwOnError) {
@@ -708,8 +733,10 @@ export function useFetchLoader<T>(
 export function useRefreshLoaders(): (
   groups: string | string[],
 ) => Promise<void> {
+  const loaders = useContext(NavigationStoreContext)?.store?.loaders;
   return useCallback(
-    (groups: string | string[]) => loaderStore.refreshGroups(groups),
-    [],
+    (groups: string | string[]) =>
+      loaders ? loaders.refreshGroups(groups) : Promise.resolve(),
+    [loaders],
   );
 }

package/src/vite/discovery/bundle-postprocess.ts

@@ -33,6 +33,10 @@ export function postprocessBundle(state: DiscoveryState): void {
   );
 
   // 1. Evict handler code from whichever chunks contain handler exports.
+  // onDemand retention needs no cross-check here: the chunk scan marks
+  // onDemand exports directly from state.onDemandHandlerIds (the evaluated
+  // source's $$id set), so retention and the runtime od trie flag share one
+  // derivation and cannot disagree.
   // handlerChunkInfoMap/staticHandlerChunkInfoMap are populated by generateBundle
   // after the production RSC build. In Vite 6 multi-environment builds, the
   // RSC build runs twice (analysis + production). The maps are cleared at the

package/src/vite/discovery/discover-routers.ts

@@ -337,6 +337,20 @@ export async function discoverRouters(
     (performance.now() - trieStart).toFixed(1),
   );
 
+  // handlerId -> route name for onDemand routes, from the evaluated source —
+  // the authoritative side of postprocessBundle's retention cross-check.
+  const newOnDemandHandlerIds = new Map<string, string>();
+  for (const { manifest } of allManifests) {
+    if (!manifest.onDemandRoutes) continue;
+    const defs = manifest._prerenderDefs || {};
+    for (const routeName of manifest.onDemandRoutes) {
+      const handlerId = defs[routeName]?.$$id;
+      if (typeof handlerId === "string") {
+        newOnDemandHandlerIds.set(handlerId, routeName);
+      }
+    }
+  }
+
   // Commit all local state to the shared discovery state atomically.
   // This ensures a failed re-discovery (e.g. from a transient module
   // evaluation error) preserves the last known-good state.
@@ -345,6 +359,7 @@ export async function discoverRouters(
   state.perRouterManifestDataMap = newPerRouterManifestDataMap;
   state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
   state.perRouterTrieMap = newPerRouterTrieMap;
+  state.onDemandHandlerIds = newOnDemandHandlerIds;
 
   // Install the route tries into the RSC realm BEFORE prerender collection.
   // matchForPrerender resolves each enumerated URL via findMatch, and without

package/src/vite/discovery/shell-prerender-phase.ts

@@ -206,10 +206,10 @@ export async function runShellPrerenderPhase(
     const staged: Array<{ key: string; value: string }> = [];
     let skipCount = 0;
 
-    // Manifest keys are pathname-only (see shell-manifest-key.ts): two
-    // candidates on one pathname (two routers prerendering the same path)
-    // would be ambiguous at serve time — decline ALL of that pathname's
-    // entries rather than bake a wrong-router shell.
+    // A candidate names no router (the sweep below gives it to the first one
+    // whose match lands on its route): two candidates on one pathname (two
+    // routers prerendering the same path) would be ambiguous — decline ALL of
+    // that pathname's entries rather than bake a wrong-router shell.
     const pathCounts = new Map<string, number>();
     for (const cand of candidates) {
       pathCounts.set(cand.urlPath, (pathCounts.get(cand.urlPath) ?? 0) + 1);
@@ -282,7 +282,7 @@ export async function runShellPrerenderPhase(
             tags: res.tags,
           };
           staged.push({
-            key: buildShellManifestKey(cand.urlPath),
+            key: buildShellManifestKey(routerId, cand.urlPath),
             value: JSON.stringify(value),
           });
           console.log(

package/src/vite/discovery/state.ts

@@ -61,7 +61,12 @@ export interface PrecomputedEntry {
 
 export interface ChunkInfo {
   fileName: string;
-  exports: Array<{ name: string; handlerId: string; passthrough: boolean }>;
+  exports: Array<{
+    name: string;
+    handlerId: string;
+    passthrough: boolean;
+    onDemand: boolean;
+  }>;
 }
 
 export interface PerRouterManifestEntry {
@@ -163,6 +168,16 @@ export interface DiscoveryState {
   buildData: import("./build-versions.js").BuildDataRecord[];
   handlerChunkInfoMap: Map<string, ChunkInfo>;
   staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
+  /**
+   * handlerId ($$id) -> route name for every route the evaluated source marks
+   * onDemand. Written during discovery (buildStart), consumed by the
+   * generateBundle chunk scan (extractHandlerExportsFromChunk) as the
+   * authoritative onDemand set driving producer retention — the same source
+   * that sets the runtime od trie flag, so any truthy onDemand spelling
+   * (literal, spread, imported const) both marks the route and retains its
+   * producer.
+   */
+  onDemandHandlerIds: Map<string, string>;
   rscEntryFileName: string | null;
   resolvedPrerenderModules: Map<string, string[]> | undefined;
   resolvedStaticModules: Map<string, string[]> | undefined;
@@ -225,6 +240,7 @@ export function createDiscoveryState(
     buildData: [],
     handlerChunkInfoMap: new Map(),
     staticHandlerChunkInfoMap: new Map(),
+    onDemandHandlerIds: new Map(),
     rscEntryFileName: null,
     resolvedPrerenderModules: undefined,
     resolvedStaticModules: undefined,

package/src/vite/inject-client-debug.ts

@@ -12,37 +12,59 @@ import type { Connect } from "vite";
  * runs on the module regardless of how (or whether) the define is delivered, in
  * both dev and build and for every environment, so the discovery plugin uses this
  * to replace the module with the resolved literal.
+ *
+ * internal-suspense-audit.ts takes the same path for INTERNAL_RANGO_SUSPENSE_AUDIT,
+ * the repo-only switch of the dev suspense audit.
  */
 
+// The router's flag modules, by file name: each exports one boolean named after
+// the env var it is baked from.
+const FLAG_MODULE =
+  /\/(internal-debug|internal-suspense-audit)\.[cm]?[jt]sx?(\?|$)/;
+const FLAG_NAMES: Record<string, string> = {
+  "internal-debug": "INTERNAL_RANGO_DEBUG",
+  "internal-suspense-audit": "INTERNAL_RANGO_SUSPENSE_AUDIT",
+};
+
 /**
- * Scope to the router's own internal-debug module: the published package
- * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
- * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
- * consumer file that merely sits under a directory named `rangojs-router`.
- * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
+ * The env var a router flag module is baked from, or undefined. Scoped to the
+ * router's own modules: the published package (`/@rangojs/router/`, incl.
+ * pnpm's nested layout) or the monorepo workspace (`/packages/rangojs-router/`).
+ * The package-anchored path avoids matching a consumer file that merely sits
+ * under a directory named `rangojs-router`. Accepts module ids and dev-server
+ * URLs (`/@fs/...internal-debug.ts?v=abc`).
  */
-export function isRouterInternalDebugId(id: string): boolean {
-  if (!id.includes("internal-debug")) return false;
+function routerFlagName(id: string): string | undefined {
+  if (!id.includes("internal-")) return undefined;
   const norm = id.replace(/\\/g, "/");
-  return (
-    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
-    (norm.includes("/@rangojs/router/") ||
-      norm.includes("/packages/rangojs-router/"))
-  );
+  if (
+    !norm.includes("/@rangojs/router/") &&
+    !norm.includes("/packages/rangojs-router/")
+  ) {
+    return undefined;
+  }
+  const match = FLAG_MODULE.exec(norm);
+  return match ? FLAG_NAMES[match[1]!] : undefined;
+}
+
+/** A router flag module: internal-debug.ts or internal-suspense-audit.ts. */
+export function isRouterInternalDebugId(id: string): boolean {
+  return routerFlagName(id) !== undefined;
 }
 
 /**
- * Transform: replace the module with the resolved literal.
- * Returns null for any module that is not the router's internal-debug module.
+ * Transform: replace a router flag module with the resolved literal.
+ * Returns null for any other module.
  */
 export function injectClientDebugFlag(
   id: string,
 ): { code: string; map: null } | null {
   // Cheap early-out: this hook runs on every module in every environment.
-  if (!isRouterInternalDebugId(id)) return null;
-  // Emit the whole module: internal-debug.ts has a single export, kept in sync.
+  const name = routerFlagName(id);
+  if (name === undefined) return null;
+  // Emit the whole module: each flag module has a single export, kept in sync.
   return {
-    code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
+    code: `export const ${name} = ${!!process.env[name]};\n`,
     map: null,
   };
 }
@@ -63,9 +85,9 @@ export function injectClientDebugFlag(
  * immune -- workspace source is outside node_modules and served no-cache --
  * which is why this bit only npm consumers.
  *
- * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
- * are byte-identical across flag states), so forcing revalidation for this one
- * tiny module is sufficient and costs one conditional request per session. The
+ * The two flag modules are the only flag-varying modules in the graph (their
+ * importers are byte-identical across flag states), so forcing revalidation for
+ * them is sufficient and costs a conditional request each per session. The
  * middleware is unconditional (not gated on the flag) so an already-poisoned
  * cache heals in both directions. Alternatives that do not work: a plugin
  * `resolveId` appending a flag query never fires in Vite 8 dev for

package/src/vite/plugins/virtual-entries.ts

@@ -28,6 +28,12 @@ async function initializeApp() {
   // is the default; createRouter({ strictMode: false }) ships the opt-out in the
   // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
   const { strictMode, initialPayload } = await initBrowserApp({ rscStream, deps });
+  // Set only on a document a no-JS useActionState POST rendered: React needs
+  // the server's form state to hydrate the hook without resetting it. A state
+  // Flight could not carry rejects: hydrate without it, as before.
+  const formState = await Promise.resolve(initialPayload.formState).catch(
+    () => undefined
+  );
 
   if (import.meta.hot) {
     const { startDevDiscoveryHandshake } = await import(
@@ -42,7 +48,8 @@ async function initializeApp() {
   const app = createElement(Rango);
   hydrateRoot(
     document,
-    strictMode === false ? app : createElement(StrictMode, null, app)
+    strictMode === false ? app : createElement(StrictMode, null, app),
+    formState ? { formState } : undefined
   );
 }