@rangojs/router 0.21.0 → 0.22.1

package/src/cache/memory-segment-store.ts

@@ -6,6 +6,7 @@
  */
 
 import type {
+  CacheStoreScope,
   SegmentCacheStore,
   CachedEntryData,
   CacheDefaults,
@@ -23,6 +24,7 @@ import {
   DEFAULT_FUNCTION_TTL,
 } from "./cache-policy.js";
 import { reportCacheError } from "./cache-error.js";
+import { responseStartedAt } from "./invalidation-order.js";
 
 const CACHE_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
 const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
@@ -146,6 +148,26 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
    * ```
    */
   maxEntries?: number;
+
+  /**
+   * Where an entry this store writes can be read; what `router.prerender()`
+   * checks before warming a route. Defaults to `"local"`: the maps live in one
+   * process, and the router cannot tell one long-running server from several
+   * replicas or serverless instances, so a warm into it is refused in
+   * production. Set `"global"` only when exactly one process serves the app
+   * (a single Node server); a warm then reports `warmed`. Under the Vite dev
+   * server a `"local"` instance already counts as shared.
+   *
+   * Like `defaults` and `keyGenerator`, the scope is per instance: two
+   * instances with the same `name` share their maps but each declares its own
+   * scope. Keep them identical.
+   *
+   * @example
+   * ```typescript
+   * const store = new MemorySegmentCacheStore({ scope: "global" });
+   * ```
+   */
+  scope?: CacheStoreScope;
 }
 
 /** Default per-family entry cap for MemorySegmentCacheStore (FIFO eviction). */
@@ -188,6 +210,13 @@ const DEFAULT_MAX_ENTRIES = 1000;
 export class MemorySegmentCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  /**
+   * SegmentCacheStore.scope: "local" unless `options.scope` says otherwise, so
+   * router.prerender() refuses to warm into these maps in production. Under
+   * the Vite dev server the gate counts a "local" instance as shared
+   * (store-scope.ts resolveWarmStoreScope).
+   */
+  readonly scope: CacheStoreScope;
   readonly supportsPassiveShellReads: true = true;
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
@@ -253,6 +282,7 @@ export class MemorySegmentCacheStore<
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
     this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.scope = options?.scope ?? "local";
   }
 
   /**
@@ -300,6 +330,7 @@ export class MemorySegmentCacheStore<
     ttl: number,
     _swr?: number,
   ): Promise<void> {
+    if (this.invalidatedAfter(data.tags, data.taggedAt)) return;
     const entry: CachedEntryData = {
       ...data,
       expiresAt: Date.now() + ttl * 1000,
@@ -358,6 +389,7 @@ export class MemorySegmentCacheStore<
     tags?: string[],
   ): Promise<void> {
     try {
+      const startedAt = responseStartedAt(response);
       const body = await response.clone().arrayBuffer();
       const headers: [string, string][] = [];
       response.headers.forEach((value, name) => {
@@ -368,6 +400,8 @@ export class MemorySegmentCacheStore<
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
 
+      // After the last await before the write.
+      if (this.invalidatedAfter(tags, startedAt)) return;
       const prefixedKey = `res:${key}`;
       this.unregisterTags(prefixedKey);
       this.evictIfNeeded(this.responseCache, key, "res");
@@ -415,6 +449,7 @@ export class MemorySegmentCacheStore<
     value: string,
     options?: CacheItemOptions,
   ): Promise<void> {
+    if (this.invalidatedAfter(options?.tags, options?.startedAt)) return;
     const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
@@ -486,7 +521,23 @@ export class MemorySegmentCacheStore<
     return this.tagsInvalidatedSince(tags, sinceMs);
   }
 
-  private tagsInvalidatedSince(tags: string[], sinceMs: number): boolean {
+  /**
+   * A tag invalidated in a millisecond after the write's execution started
+   * (#1068). Strictly after: the start's own millisecond is ambiguous, and
+   * invalidation-order.ts orders those exactly.
+   */
+  private invalidatedAfter(
+    tags: readonly string[] | undefined,
+    startedAt: number | undefined,
+  ): boolean {
+    if (!tags || tags.length === 0 || startedAt === undefined) return false;
+    return this.tagsInvalidatedSince(tags, startedAt + 1);
+  }
+
+  private tagsInvalidatedSince(
+    tags: readonly string[],
+    sinceMs: number,
+  ): boolean {
     for (const tag of tags) {
       const at = this.tagInvalidatedAt.get(tag);
       // >= so a same-millisecond invalidation wins (freshness over staleness),

package/src/cache/shell-snapshot.ts

@@ -32,6 +32,7 @@ import type {
   ShellCacheEntry,
   ShellSnapshotRecord,
   ShellSnapshotLoaderValue,
+  ShellSnapshotHandlesValue,
   CacheReadError,
 } from "./types.js";
 import { settleGrowing } from "./background-task.js";
@@ -452,6 +453,22 @@ export async function buildShellLoaderSeed(
   return seed.size > 0 ? seed : undefined;
 }
 
+/** The key of a snapshot's one `handles` record (ShellSnapshotHandlesValue). */
+export const SHELL_HANDLES_RECORD_KEY = "handles";
+
+/**
+ * The `handles` record of a prerender-served entry, which a HIT tail restores
+ * after the prerender store's handles (cache-lookup.ts yieldFromStore), or
+ * undefined: an entry with a doc record, or one written before the record
+ * existed (v0.21), which serves as it did.
+ */
+export function shellPrerenderHandles(
+  snapshot: readonly ShellSnapshotRecord[],
+): ShellSnapshotHandlesValue | undefined {
+  const record = snapshot.find((r) => r?.family === "handles");
+  return record?.value as ShellSnapshotHandlesValue | undefined;
+}
+
 /**
  * The implicit doc scope's store on a HIT tail and on a partial replay: it
  * serves the snapshot's segment records, the doc record among them, and

package/src/cache/store-scope.ts

@@ -0,0 +1,36 @@
+/**
+ * The store scope `router.prerender()` gates a warm on
+ * (prerender/create-prerender-trigger.ts). See
+ * docs/design/prerender-every-route.md, "The store declaration".
+ */
+
+import type { CacheStoreScope, SegmentCacheStore } from "./types.js";
+import { MemorySegmentCacheStore } from "./memory-segment-store.js";
+
+/**
+ * True under the Vite dev server: only its routes-manifest virtual module sets
+ * the dev origin (vite/discovery/virtual-module-codegen.ts). A build, a preview
+ * server and a test runner answer false.
+ */
+export function isViteDevServer(): boolean {
+  return typeof globalThis.__PRERENDER_DEV_URL === "string";
+}
+
+/**
+ * The scope a warm treats `store` as having: its own declaration, with none
+ * or an unknown value being `"local"`.
+ *
+ * One exception: under the Vite dev server a MemorySegmentCacheStore answers
+ * `"global"`, because that one process serves every request. Production reads
+ * the class's own `scope` (`"local"`): changing that declaration is what
+ * would admit it there.
+ */
+export function resolveWarmStoreScope(
+  store: SegmentCacheStore<any>,
+  devServer: boolean = isViteDevServer(),
+): CacheStoreScope {
+  const declared = store.scope;
+  if (declared === "global" || declared === "regional") return declared;
+  if (devServer && store instanceof MemorySegmentCacheStore) return "global";
+  return "local";
+}

package/src/cache/tag-invalidation.ts

@@ -49,6 +49,7 @@ import {
 export {
   executionStart,
   invalidatedSince,
+  markResponseStart,
   type ExecutionStart,
 } from "./invalidation-order.js";
 
@@ -147,11 +148,12 @@ function markFreshReads(stores: SegmentCacheStore[]): void {
  * The write gate of every cache execution (#977): whether one of `tags` was
  * invalidated after the execution that produced the value started.
  *
- * Every built-in store stamps an entry when it is written (CFCacheStore's
- * `taggedAt`, VercelCacheStore's `ta`) or checks nothing on write
- * (MemorySegmentCacheStore), so a value read before an invalidation and
- * written after it would be served as newer than the invalidation until it
- * expires. Two answers, either one skips the write:
+ * A store stamps an entry with the execution's start (CFCacheStore's
+ * `taggedAt`, VercelCacheStore's `ta`, #1068), but only CFCacheStore with KV
+ * markers rejects it on a later request's read, and MemorySegmentCacheStore
+ * refuses the write. The gate saves the write everywhere and is the only
+ * guard where a read compares nothing. Two answers, either one skips the
+ * write:
  *
  * - this isolate's order (invalidatedSince), which sees every request's
  *   updateTag()/revalidateTag() here, the calling one included;

package/src/cache/types.ts

@@ -42,6 +42,18 @@ export interface CacheGetResult {
   shouldRevalidate: boolean;
 }
 
+/**
+ * Where an entry a store writes during one request can be read by a later
+ * request. `router.prerender()` warms a route only when the app store answers
+ * `"global"` or `"regional"`: a warm fills the store where it runs, which
+ * serves other traffic only when the store is shared beyond that place.
+ * - `"global"`: every location reads the same entries.
+ * - `"regional"`: each region has its own copy; a warm fills the region it
+ *   runs in.
+ * - `"local"`: only the process, isolate or edge location that wrote it.
+ */
+export type CacheStoreScope = "global" | "regional" | "local";
+
 /**
  * Low-level segment cache store interface.
  *
@@ -59,6 +71,12 @@ export interface CacheGetResult {
  * @typeParam TEnv - Platform bindings type (e.g., Cloudflare env)
  */
 export interface SegmentCacheStore<TEnv = unknown> {
+  /**
+   * Where an entry this store writes can be read ({@link CacheStoreScope}).
+   * Absent: unknown to the router, treated as `"local"`.
+   */
+  readonly scope?: CacheStoreScope;
+
   /**
    * The store honors getShell(..., { claimRevalidation: false }) without
    * claiming an SWR lock. Navigation replay requires this opt-in because it
@@ -168,6 +186,11 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
    * @param tags - Optional cache tags for invalidation
+   *
+   * The built-in stores read the start of the render from the `Response`
+   * object itself (#1068). A custom store, or a wrapper that rebuilds the
+   * `Response` before delegating, stamps write time. The write gate
+   * (`predatesInvalidation`) runs before this call either way.
    */
   putResponse?(
     key: string,
@@ -451,9 +474,10 @@ export interface ShellCacheEntry {
    * bake-lane loader pins (pruned to what a HIT reads, issue #941). Replaying
    * them on a HIT keeps the freshly rendered hydration payload equal to the
    * frozen prelude after the underlying cache entries have drifted; every
-   * other read on a HIT, a hole's included, reads the store. Empty when the capture
-   * recorded nothing (a prerender-served capture without bake-lane loaders,
-   * a tombstone). A custom store returns it as putShell received it. See
+   * other read on a HIT, a hole's included, reads the store. A
+   * prerender-served capture holds a `handles` record instead of a doc record
+   * (ShellSnapshotHandlesValue). Empty for a tombstone. A custom store
+   * returns it as putShell received it. See
    * docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot: ShellSnapshotRecord[];
@@ -614,12 +638,26 @@ export interface ShellReadStats {
 
 /**
  * The families a shell snapshot pins: the doc segment record (recorded by
- * RecordingShellStore) and the settled CONTAINER of each bake-lane loader
- * (lane rule: see resolveLoaderData, loader-cache.ts). No cache read is
- * pinned: a HIT's holes, and a bake-lane loader body that runs on the HIT,
- * read the store.
+ * RecordingShellStore), the settled CONTAINER of each bake-lane loader
+ * (lane rule: see resolveLoaderData, loader-cache.ts), and a prerender-served
+ * entry's `handles` record. No cache read is pinned: a HIT's holes, and a bake-lane
+ * loader body that runs on the HIT, read the store.
  */
-export type ShellSnapshotFamily = "segment" | "loader";
+export type ShellSnapshotFamily = "segment" | "loader" | "handles";
+
+/**
+ * The stored form of the `handles` family: the handle arrays of a
+ * prerender-served capture that hold a loader-owned push, in the doc record's
+ * format (CachedEntryData `handles` + `handleOwners`). A Prerender + ppr
+ * route's handler layer comes from the prerender store, whose build-time
+ * entry has no loader push, so the entry keeps these for the HIT to restore
+ * as a doc record's (issue #1057, yieldFromStore in cache-lookup.ts). An
+ * entry written before it (v0.21) has none and serves as it did.
+ */
+export type ShellSnapshotHandlesValue = Pick<
+  CachedEntryData,
+  "handles" | "handleOwners"
+>;
 
 /**
  * The stored form of a loader-family snapshot value: the bake-lane loader's
@@ -654,17 +692,18 @@ export interface ShellSnapshotLoaderValue {
 }
 
 /**
- * One snapshot record: the doc segment record or a bake-lane loader pin.
- * `value` carries it in its stored/serialized shape so it round-trips
- * through a JSON-serializing store (KV, CF, Vercel) with the rest of the
- * ShellCacheEntry:
+ * One snapshot record: the doc segment record, a bake-lane loader pin, or a
+ * prerender-served entry's handle record. `value` carries it in its
+ * stored/serialized shape so it round-trips through a JSON-serializing store
+ * (KV, CF, Vercel) with the rest of the ShellCacheEntry:
  * - `segment` -> {@link CachedEntryData} (already JSON-able)
  * - `loader`  -> {@link ShellSnapshotLoaderValue}
+ * - `handles` -> {@link ShellSnapshotHandlesValue}
  */
 export interface ShellSnapshotRecord {
   family: ShellSnapshotFamily;
   key: string;
-  value: CachedEntryData | ShellSnapshotLoaderValue;
+  value: CachedEntryData | ShellSnapshotLoaderValue | ShellSnapshotHandlesValue;
 }
 
 /**
@@ -679,6 +718,17 @@ export interface CacheItemOptions {
   swr?: number;
   /** Cache tags for invalidation */
   tags?: string[];
+  /**
+   * Ms since epoch when the execution that produced the value started (#1068).
+   * A store stamps a tagged entry with it instead of its write time. Later
+   * requests then reject an entry an invalidation landed under in
+   * CFCacheStore with KV markers; MemorySegmentCacheStore refuses the write.
+   * Not rejected: VercelCacheStore (a read compares the stamp with the
+   * invalidating request's mask only) and CFCacheStore L1 hits in purge mode
+   * or without KV. Absent or not positive: write time. A custom store may
+   * ignore it.
+   */
+  startedAt?: number;
 }
 
 /**
@@ -726,7 +776,12 @@ export interface CachedEntryData {
   expiresAt: number;
   /** Cache tags for invalidation */
   tags?: string[];
-  /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+  /**
+   * Timestamp (ms since epoch) the entry's tags are valid as of, for
+   * distributed invalidation. The writer sets it to the start of the render
+   * that produced the record; a store stamps write time when it is absent
+   * (#1068). Which reads reject on it: see `CacheItemOptions.startedAt`.
+   */
   taggedAt?: number;
 }
 

package/src/cache/vercel/vercel-cache-store.ts

@@ -35,6 +35,7 @@
  */
 
 import type {
+  CacheStoreScope,
   SegmentCacheStore,
   CachedEntryData,
   CacheDefaults,
@@ -106,6 +107,7 @@ import {
   type MarkerFetch,
   type MarkerMemoOutcome,
 } from "../isolate-tag-memo.js";
+import { responseStartedAt, taggedStamp } from "../invalidation-order.js";
 
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
@@ -454,9 +456,15 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
-/** The envelope's `ta` write stamp, on tagged entries only. */
-function tagStamp(tags: string[]): { ta?: number } {
-  return tags.length > 0 ? { ta: Date.now() } : {};
+/**
+ * The envelope's `ta` stamp, on tagged entries only: the producing execution's
+ * start when the writer passed it, else write time (#1068). Only the request
+ * mask reads it (expireTag keeps no queryable history), so it decides whether
+ * the invalidating request's own late write is masked.
+ */
+function tagStamp(tags: string[], startedAt?: number): { ta?: number } {
+  const ta = taggedStamp(tags, startedAt);
+  return ta === undefined ? {} : { ta };
 }
 
 /**
@@ -512,6 +520,12 @@ function tagStamp(tags: string[]): { ta?: number } {
 export class VercelCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  /**
+   * SegmentCacheStore.scope: the Runtime Cache is per region. A
+   * router.prerender() warm fills the region it runs in, which is all traffic
+   * only when the project's functions run in one region.
+   */
+  readonly scope: CacheStoreScope = "regional";
   readonly supportsPassiveShellReads: true = true;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
@@ -649,7 +663,7 @@ export class VercelCacheStore<
         d,
         s: staleAt,
         e: expiresAt,
-        ...tagStamp(safeTags),
+        ...tagStamp(safeTags, data.taggedAt),
       };
       await this.write(
         this.toStoreKey(key, "s"),
@@ -797,7 +811,7 @@ export class VercelCacheStore<
         s: staleAt,
         e: expiresAt,
         t: safeTags.length > 0 ? safeTags : undefined,
-        ...tagStamp(safeTags),
+        ...tagStamp(safeTags, responseStartedAt(response)),
       };
       await this.write(
         this.toStoreKey(key, "r"),
@@ -903,7 +917,7 @@ export class VercelCacheStore<
         s: staleAt,
         e: expiresAt,
         t: safeTags.length > 0 ? safeTags : undefined,
-        ...tagStamp(safeTags),
+        ...tagStamp(safeTags, options?.startedAt),
       };
       await this.write(
         this.toStoreKey(key, "i"),

package/src/client.tsx

@@ -3,9 +3,11 @@
 import {
   Component,
   createElement,
+  isValidElement,
   useContext,
   useMemo,
   Suspense,
+  type ComponentProps,
   type ReactNode,
 } from "react";
 // Not `export * as Html`: plugin-rsc's "use client" proxy transform only
@@ -19,12 +21,15 @@ import {
   type ResolvedSegment,
 } from "./types";
 import {
+  AuditedLoaderBoundary,
+  AuditedRouteContent,
   RouteContentWrapper,
   LoaderBoundary,
 } from "./route-content-wrapper.js";
-import { OutletProvider } from "./outlet-provider.js";
+import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
+import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { getBoundaryContent } from "./segment-boundary-content.js";
 
 /**
  * Render the content for a named parallel/intercept slot segment.
@@ -39,7 +44,7 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
   const content: ReactNode =
     segment.loading || segment.component instanceof Promise ? (
       <RouteContentWrapper
-        content={getMemoizedContentPromise(segment.component)}
+        content={getBoundaryContent(segment.component)}
         fallback={segment.loading}
         segmentId={segment.id}
       />
@@ -83,6 +88,10 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
     result = content;
   }
 
+  if (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT) {
+    result = auditedSlot(result);
+  }
+
   if (segment.mountPath) {
     return (
       <MountContextProvider value={segment.mountPath}>
@@ -94,6 +103,34 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
   return result;
 }
 
+// Dev only (suspense-audit.ts): the boundaries renderSlotContent built, as
+// their audited components with the same props. After the fact, not a choice
+// per JSX element: a build must fold to the product elements alone (see
+// AuditedRouteContent, route-content-wrapper.tsx).
+function auditedSlot(node: ReactNode): ReactNode {
+  if (!isValidElement(node)) return node;
+  const props = node.props as Record<string, any>;
+  if (node.type === OutletProvider) {
+    return createElement(AuditedOutletProvider, {
+      ...(props as ComponentProps<typeof OutletProvider>),
+      content: auditedSlot(props.content),
+    });
+  }
+  if (node.type === LoaderBoundary) {
+    return createElement(AuditedLoaderBoundary, {
+      ...(props as ComponentProps<typeof LoaderBoundary>),
+      children: auditedSlot(props.children),
+    });
+  }
+  if (node.type === RouteContentWrapper) {
+    return createElement(
+      AuditedRouteContent,
+      props as ComponentProps<typeof RouteContentWrapper>,
+    );
+  }
+  return node;
+}
+
 function useSlotSegment(
   context: OutletContextValue | null,
   name: `@${string}` | undefined,

package/src/errors.ts

@@ -356,6 +356,18 @@ export function invariant(condition: any, message: string): asserts condition {
  * @param error - Error to sanitize
  * @returns Response suitable for sending to client
  */
+/**
+ * Vite replaces import.meta.env.DEV at compile time. The fallback covers
+ * non-Vite environments (plain Node, test runners without Vite transforms).
+ * SECURITY: fail closed — default to production when the environment is ambiguous.
+ */
+export function isDevEnvironment(): boolean {
+  return (
+    (import.meta as any).env?.DEV ??
+    globalThis.process?.env?.NODE_ENV === "development"
+  );
+}
+
 export function sanitizeError(error: unknown): Response {
   // CRITICAL: Consume stack trace to prevent memory leaks
   if (error && typeof error === "object" && "stack" in error) {
@@ -367,12 +379,7 @@ export function sanitizeError(error: unknown): Response {
     return error;
   }
 
-  // Vite replaces import.meta.env.DEV at compile time. The fallback covers
-  // non-Vite environments (plain Node, test runners without Vite transforms).
-  // SECURITY: fail closed — default to production when the environment is ambiguous.
-  const isDev =
-    (import.meta as any).env?.DEV ??
-    globalThis.process?.env?.NODE_ENV === "development";
+  const isDev = isDevEnvironment();
 
   if (isDev) {
     // Development: Send full error details for debugging

package/src/handles/deferred-resolution.ts

@@ -124,8 +124,13 @@ export async function* resolvedHandleStream(
   yield await resolveDeferredHandleValues(snapshot);
 }
 
-/** `snapshot` without the pushes a record leaves out (resolvedHandleStream). */
-function recordedHandleData(
+/**
+ * `snapshot` without the pushes a record leaves out. A shell capture renders
+ * (resolvedHandleStream) and waits (settleCaptureRecord) on this cut only: a
+ * promise the record drops has no slot in the prelude, and waiting for it
+ * could refuse a capture for a value the shell does not hold.
+ */
+export function recordedHandleData(
   handleStore: HandleStore,
   snapshot: HandleData,
 ): HandleData {

package/src/internal-suspense-audit.ts

@@ -0,0 +1,12 @@
+// Turns on the suspense audit (suspense-audit.ts) in a dev build. Only this
+// repo sets INTERNAL_RANGO_SUSPENSE_AUDIT: the e2e webServers and fixtures of
+// the router test-app and cloudflare-basic, and the router's vitest config.
+// A consumer's dev server and tests never print the audit's errors.
+//
+// Runtime fallback for non-Vite contexts (vitest, Node). In the Vite pipeline
+// the discovery plugin replaces this module with the build-time-resolved flag
+// (vite/inject-client-debug.ts), as it does for internal-debug.ts. Keep this
+// module to the single export: the transform replaces the whole file.
+export const INTERNAL_RANGO_SUSPENSE_AUDIT: boolean =
+  typeof process !== "undefined" &&
+  Boolean((process as any).env?.INTERNAL_RANGO_SUSPENSE_AUDIT);

package/src/loader-store.ts

@@ -29,9 +29,10 @@
  *     reclaim a bucket that is about to be reused, and is held until any
  *     in-flight load settles.
  *
- * The store is intentionally module-level: each browser tab is its own JS
- * realm, so there is no cross-request pollution. Server renders never mutate
- * the store — the hook falls back to `OutletContext.loaderData`.
+ * Each router's NavigationStore owns one (navigation-store.ts), and hooks reach
+ * it through NavigationStoreContext: the router store is the single source of
+ * truth. Server renders have no store — the hook falls back to
+ * `OutletContext.loaderData`.
  */
 
 import { unwrapsSynchronously } from "./thenable-status.js";
@@ -597,10 +598,4 @@ export class LoaderStore {
   }
 }
 
-/**
- * Module-level singleton. Each browser tab gets its own; SSR never mutates it.
- * The hook falls through to `OutletContext.loaderData` during the server render.
- */
-export const loaderStore: LoaderStore = new LoaderStore();
-
 export const EMPTY_LOADER_SNAPSHOT: LoaderEntry = EMPTY_SNAPSHOT;

package/src/outlet-provider.tsx

@@ -1,8 +1,14 @@
 "use client";
 
-import { useContext, useMemo, type ReactNode } from "react";
+import {
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import type { ResolvedSegment } from "./types.js";
+import { AuditedOutlet } from "./suspense-audit-react.js";
 
 /**
  * Outlet content provider — stores parent context for useLoader chain walking.
@@ -57,3 +63,21 @@ export function OutletProvider({
     <OutletContext.Provider value={value}>{children}</OutletContext.Provider>
   );
 }
+
+// Dev only (suspense-audit.ts): OutletProvider with the segment's mount
+// tracked under it. Chosen where the element is created, inside a NODE_ENV
+// test: see AuditedRouteContent (route-content-wrapper.tsx).
+export function AuditedOutletProvider({
+  children,
+  ...props
+}: ComponentProps<typeof OutletProvider>): ReactNode {
+  return (
+    <OutletProvider {...props}>
+      {props.segment ? (
+        <AuditedOutlet segmentId={props.segment.id}>{children}</AuditedOutlet>
+      ) : (
+        children
+      )}
+    </OutletProvider>
+  );
+}