@rangojs/router 0.20.0 → 0.22.0

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.
  *
@@ -49,9 +61,22 @@ export interface CacheGetResult {
  * The store deals with serialized data - RSC serialization is handled
  * by the cache provider layer.
  *
+ * A store that outlives the process has to keep one build from reading what
+ * other code wrote. The built-in stores prefix their keys with the serving
+ * router's cache versions; a custom store reads the same pair with
+ * `getCacheVersions()` (`@rangojs/router/cache`): `data` for segment entries
+ * and items, `document` for responses and shells, and no version on its
+ * tag-invalidation records, so an invalidation reaches every version.
+ *
  * @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
@@ -161,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,
@@ -415,13 +445,14 @@ export interface ShellCacheEntry {
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
-   * Build version captured at prerender time (the RSC handler's `version` —
-   * the `@rangojs/router:version` build stamp by default, bumped per build and
-   * on dev RSC-module edits). The second read-time gate: a persistent shared
+   * Build version captured at prerender time: the RSC handler's `version`,
+   * which is the router's DOCUMENT version (router-versions.ts) — a hash of
+   * its server code and the client asset names by default, a stamp bumped on
+   * dev RSC-module edits. The second read-time gate: a persistent shared
    * store (KV/runtime-cache) survives deploys, and an app-code change that
    * keeps the same React version would otherwise leave a stale-build
-   * prelude+postponed live under the same key. A custom store returns it as
-   * putShell received it.
+   * prelude+postponed live under the same key. A deploy that changes neither
+   * keeps the entry. A custom store returns it as putShell received it.
    */
   buildVersion: string;
   /**
@@ -443,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[];
@@ -606,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
@@ -646,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;
 }
 
 /**
@@ -671,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;
 }
 
 /**
@@ -718,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;
 }
 
@@ -761,10 +824,13 @@ export type SegmentHandleData = Record<string, unknown[]>;
  * index (null: not owned). Only a PPR shell capture writes owners: the
  * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
  * the loaders it awaits, and its own cache() replays), which the record keeps
- * because the prelude rendered them. A document HIT restores a bake-lane
- * owner's value through HandleStore.pushRestored, and it stands against a run
- * of its loader there; a live-lane owner's (a hole), and every owner's on
- * any other replay of the record (a client navigation), go through
- * pushReplayed, so a run of the loader replaces it with its live push.
+ * because the prelude rendered them. A restore of the record
+ * (handle-snapshot.ts restoreHandles) keeps an owner's value where the
+ * request serves that loader from the pin stored with the record
+ * (HandleStore.pushRestored: it stands against a run of the loader), on a
+ * document HIT and on a navigation replay alike. Every other owner's value
+ * is a placeholder (pushPlaceholder): a live-lane loader's, and every
+ * owner's where the record has no pin for it. The loader's run, or its own
+ * cache() entry, replaces it.
  */
 export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

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

@@ -23,7 +23,8 @@
  *   3. The platform guardrails: the 2 MB per-item ceiling (oversized writes
  *      silently no-op on Vercel, so we skip + report), the per-item tag cap, and
  *      cross-deploy non-reconciliation (TTL/tag updates are not reconciled across
- *      deployments - bake a build id into `version` or the getCache namespace).
+ *      deployments - every key carries the serving router's cache version, see
+ *      toStoreKey).
  *
  * Dependency stance: this module imports NOTHING from `@vercel/functions`. The
  * runtime cache handle (and `waitUntil`) are injected through the constructor and
@@ -34,6 +35,7 @@
  */
 
 import type {
+  CacheStoreScope,
   SegmentCacheStore,
   CachedEntryData,
   CacheDefaults,
@@ -52,6 +54,10 @@ import {
   _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import {
+  versionKeyPrefix,
+  type KeyVersion,
+} from "../../server/build-version-table.js";
 import { isPerClientSignalHeader } from "../../browser/cookie-name.js";
 import {
   resolveTtl,
@@ -101,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()`
@@ -170,6 +177,19 @@ const REVALIDATION_LOCK_MS = 30_000;
  *  the suffix; `rg:` namespaces every Rango entry. `h` is the PPR shell tier. */
 type CacheFamily = "s" | "i" | "r" | "h" | "tm";
 
+/**
+ * Which of the serving router's versions each family's keys carry
+ * (versionKeyPrefix). A tag marker carries none: an invalidation applies to
+ * every version, including one a rollback brings back.
+ */
+const FAMILY_VERSION: Record<CacheFamily, KeyVersion> = {
+  s: "data",
+  i: "data",
+  r: "document",
+  h: "document",
+  tm: null,
+};
+
 /**
  * TTL for tag-invalidation marker entries ("tm" family), written by
  * invalidateTags for isTagsInvalidatedSince (the build-shell read-through,
@@ -177,7 +197,7 @@ type CacheFamily = "s" | "i" | "r" | "h" | "tm";
  * The platform's expireTag() DELETES tagged entries (no queryable
  * history), so the markers are rango's own record of "tag X was invalidated
  * at T". One year: runtime tagged-shell retention is capped to this lifetime,
- * while buildVersion retires build shells on the next deploy. An expired marker
+ * while a build shell is replaced by the next build's. An expired marker
  * therefore cannot resurrect a runtime shell that outlived its invalidation.
  */
 const TAG_MARKER_TTL_SECONDS = 365 * 24 * 60 * 60;
@@ -299,14 +319,20 @@ export type VercelCacheDebug =
 export interface VercelCacheStoreOptions<TEnv = unknown> {
   /**
    * The Vercel Runtime Cache handle - `getCache()` from `@vercel/functions`.
-   * Required. Construct it with a build-hash namespace to bust stale-shaped
-   * entries across deployments, since Vercel does not reconcile TTL/tags between
-   * deploys:
+   * Required.
    *
    * ```ts
    * import { getCache } from "@vercel/functions";
-   * new VercelCacheStore({ cache: getCache({ namespace: BUILD_ID }) });
+   * new VercelCacheStore({ cache: getCache() });
    * ```
+   *
+   * Vercel does not reconcile entries between deployments; the store does it
+   * through its keys, which carry the serving router's cache versions (see
+   * `version`). So a deploy that changes a router's code stops reading that
+   * router's old entries, and a deploy that does not keeps them. A namespace
+   * that changes per deployment (`getCache({ namespace: VERCEL_DEPLOYMENT_ID })`)
+   * still works and clears the cache on every deploy, which is what you want
+   * only if you need that.
    */
   cache: VercelRuntimeCache;
 
@@ -336,9 +362,15 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
   ) => string | Promise<string>;
 
   /**
-   * Build/version id folded into every stored key as `v/{version}/...`. A second
-   * cross-deploy busting layer in addition to (or instead of) the getCache
-   * namespace. Changing it invalidates everything this store wrote previously.
+   * Version override, folded into every versioned key as `v/{version}/...`.
+   * When set, this exact value is used for cached data and stored HTML alike;
+   * changing it makes everything this store wrote before unreachable.
+   *
+   * Leave it unset for the default: the store keys with the versions of the
+   * router serving the request, as CFCacheStore does. Segments and `"use
+   * cache"` items use the router's data version; responses and PPR shells use
+   * its document version (see `createRouter({ version })`). Tag markers are
+   * never versioned, so an invalidation applies to every version.
    */
   version?: string;
 
@@ -424,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 };
 }
 
 /**
@@ -447,8 +485,8 @@ function tagStamp(tags: string[]): { ta?: number } {
  * that propagates expireTag rejections does get the strict guarantee, which is
  * what the unit suite exercises.)
  *
- * Key hashing / family isolation. The store namespaces its three value tiers as
- * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * Key hashing / family isolation. The store namespaces its value tiers as
+ * `rg:{s|i|r|h}:{key}` so segment, `"use cache"`, response and shell entries occupy
  * disjoint keyspaces. That separation is only as strong as the cache's
  * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
  * bits (8 hex chars), so at a large live-key count a collision can let one
@@ -464,11 +502,9 @@ function tagStamp(tags: string[]): { ta?: number } {
  *
  * // One handle per process: getCache() resolves the platform cache on every
  * // call, and the PPR shell and tag-marker memos are kept per handle.
- * // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
- * // would be undefined here) so cross-deploy busting via `version` works.
- * const runtimeCache = getCache({
- *   namespace: process.env.VERCEL_DEPLOYMENT_ID,
- * });
+ * // No deployment id in the namespace: the store's keys carry the serving
+ * // router's cache versions, so a deploy keeps what its code did not change.
+ * const runtimeCache = getCache();
  *
  * export const router = createRouter({
  *   cache: () => ({
@@ -484,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?: (
@@ -493,7 +535,8 @@ export class VercelCacheStore<
 
   private readonly cache: VercelRuntimeCache;
   private readonly waitUntil?: (promise: Promise<unknown>) => void;
-  private readonly version?: string;
+  /** The `version` option: used for every versioned family when set. */
+  private readonly explicitVersion?: string;
   private readonly maxItemBytes: number;
   private readonly memo: ResolvedShellMemoOptions;
   private readonly handleMemos: VercelHandleMemos;
@@ -518,7 +561,7 @@ export class VercelCacheStore<
     this.waitUntil = options.waitUntil;
     this.defaults = options.defaults;
     this.keyGenerator = options.keyGenerator;
-    this.version = options.version;
+    this.explicitVersion = options.version;
     this.maxItemBytes = options.maxItemBytes ?? VERCEL_MAX_ITEM_BYTES;
     this.maxShellEntryBytes = Math.floor((this.maxItemBytes * 3) / 4);
     this.memo = resolveShellMemoOptions(options.memo, {
@@ -620,7 +663,7 @@ export class VercelCacheStore<
         d,
         s: staleAt,
         e: expiresAt,
-        ...tagStamp(safeTags),
+        ...tagStamp(safeTags, data.taggedAt),
       };
       await this.write(
         this.toStoreKey(key, "s"),
@@ -768,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"),
@@ -874,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"),
@@ -1469,8 +1512,7 @@ export class VercelCacheStore<
   // cross-family one reads as corrupt. See the class doc for passing a wider
   // hash (sha256) when many keys are live.
   private toStoreKey(key: string, family: CacheFamily): string {
-    const versionPrefix = this.version ? `v/${this.version}/` : "";
-    return `${versionPrefix}rg:${family}:${key}`;
+    return `${versionKeyPrefix(this.explicitVersion, FAMILY_VERSION[family])}rg:${family}:${key}`;
   }
 
   private async write(

package/src/client-urls/client-root.tsx

@@ -172,6 +172,7 @@ export function ClientUrlsRoot({
               params: presented.params,
               pathname: presented.pathname,
               search: presented.search,
+              state: presented.state,
             },
           }
         : null,

package/src/client-urls/navigation.ts

@@ -17,6 +17,8 @@ export interface ClientUrlNavigationIntent {
   /** Absolute destination pathname (mount included) and search ("?..." or ""). */
   readonly pathname: string;
   readonly search: string;
+  /** `history.state` the navigation will push (OptimisticLocation.state). */
+  readonly state: unknown;
   /**
    * transition({ when }) gated this navigation off at the swap: the
    * destination presents urgently instead of in a transition lane.
@@ -37,6 +39,8 @@ export interface ClientUrlDestination {
    * params minus these are the mount's (include prefix) params.
    */
   readonly originLocalParamNames: readonly string[];
+  /** `history.state` the navigation will push (ClientUrlNavigationIntent.state). */
+  readonly state: unknown;
 }
 
 interface ActiveClientUrlGroup {
@@ -124,6 +128,8 @@ export function registerClientUrlGroup(
 export function beginClientUrlNavigation(
   targetUrl: URL,
   signal: AbortSignal,
+  /** Builds the entry state; called only when the group presents the target. */
+  buildState?: () => unknown,
   decideTransition?: (destination: ClientUrlDestination) => boolean,
 ): ClientUrlNavigationPresentation | null {
   const group = activeGroup;
@@ -149,6 +155,8 @@ export function beginClientUrlNavigation(
     : undefined;
   if (canonicalName && activeInterceptTargets.has(canonicalName)) return null;
 
+  const state = buildState?.();
+
   // A same-route intent never swaps (ClientUrlsRoot), so transition({ when })
   // decides at the canonical commit; a cross-route one decides here, at the
   // navigation's first presentation.
@@ -163,6 +171,7 @@ export function beginClientUrlNavigation(
       routeName: canonicalName,
       when: typeof when === "function" ? when : undefined,
       originLocalParamNames: Object.keys(originMatch?.params ?? {}),
+      state,
     });
   }
 
@@ -171,6 +180,7 @@ export function beginClientUrlNavigation(
     params: match.params,
     pathname: targetUrl.pathname,
     search: targetUrl.search,
+    state,
     transitionGatedOff,
   };
   group.intent = intent;

package/src/client-urls/optimistic-location.ts

@@ -6,16 +6,22 @@ import { createContext, type Context } from "react";
  * Route identity of an optimistically rendered clientUrls() destination:
  * the values the local trie match produced for the URL the user navigated
  * to. Provided by ClientUrlsRoot around the optimistic branch ONLY, so
- * useParams / usePathname / useSearchParams inside that branch describe the
- * route being rendered while the same hooks in chrome outside it keep the
- * committed location until the canonical response commits (or redirects, in
- * which case the branch — and these values — are discarded).
+ * useParams / usePathname / useSearchParams / useLocationState inside that
+ * branch describe the route being rendered while the same hooks in chrome
+ * outside it keep the committed location until the canonical response commits
+ * (or redirects, in which case the branch — and these values — are discarded).
  */
 export interface OptimisticLocation {
   readonly params: Readonly<Record<string, string>>;
   readonly pathname: string;
   /** Search string including the leading "?" (or ""). */
   readonly search: string;
+  /**
+   * `history.state` the navigation will push: its `state` option, without
+   * what the server adds (that arrives with the canonical commit). History
+   * still holds the entry being left, so useLocationState reads this instead.
+   */
+  readonly state: unknown;
 }
 
 export const OptimisticLocationContext: Context<OptimisticLocation | null> =

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