@rangojs/router 0.21.0 → 0.22.1

package/src/segment-system.tsx

@@ -5,7 +5,7 @@ import {
   type ComponentType,
   isValidElement,
 } from "react";
-import { OutletProvider } from "./outlet-provider.js";
+import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
@@ -13,17 +13,25 @@ import { decodeLoaderResults } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
 import {
+  AuditedLoaderBoundary,
+  AuditedRouteContent,
   RouteContentWrapper,
   LoaderBoundary,
   StreamedLoaderErrorBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
-import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
+import { getBoundaryContent } from "./segment-boundary-content.js";
 import {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
+import {
+  auditSegmentElement,
+  finishTreeAudit,
+  startTreeAudit,
+} from "./suspense-audit.js";
 
 /**
  * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
@@ -212,13 +220,25 @@ function wrapDefaultOutletContent(
     } as any);
   }
 
-  if (content.type === OutletProvider && props.segment?.type === "layout") {
+  if (
+    content.type ===
+      (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+        ? AuditedOutletProvider
+        : OutletProvider) &&
+    props.segment?.type === "layout"
+  ) {
     return React.cloneElement(content, {
       content: wrapDefaultOutletContent(props.content, transition),
     } as any);
   }
 
-  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+  if (
+    content.type ===
+      (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+        ? AuditedLoaderBoundary
+        : LoaderBoundary) &&
+    props.segment?.type === "layout"
+  ) {
     return React.cloneElement(content, {
       outletContent: wrapDefaultOutletContent(props.outletContent, transition),
     } as any);
@@ -376,6 +396,10 @@ export async function renderSegments(
   }
   // Separate segments by type, passing intercept segments for explicit injection
   const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
+  // Dev only: the wrapper chain per segment, compared with the previous
+  // tree's (suspense-audit.ts, I5).
+  const treeAudit =
+    process.env.NODE_ENV !== "production" ? startTreeAudit() : undefined;
 
   // A route is "in a transition scope" when its own segment OR any layout in
   // its matched chain declares transition(). Both transition() forms land here:
@@ -473,34 +497,33 @@ export async function renderSegments(
 
     let nodeContent: ReactNode = null;
     if (!clientGroup && isRenderableLoading(loading)) {
-      // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
-      // loading() route with the route content ALREADY resolved, so its
-      // RouteContentWrapper Suspender does not suspend for a microtask and flash
-      // the loading() fallback on a NORMAL (non-transition) commit. The router
-      // data is known-ready on these paths, so awaiting the content here is free.
-      // The wrapper tree is unchanged (RouteContentWrapper is still created with
-      // the same key/fallback) — only the `content` prop is a resolved node
-      // instead of a pending promise, which Suspender renders synchronously. This
-      // mirrors the forceAwait loaderData unwrap above; a CLIENT component that
-      // suspends on mount inside the content still reveals a fallback (it is not
-      // pre-resolved).
-      const contentPromise = getMemoizedContentPromise(resolvedComponent);
-      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      // The wrapper tree is the same on every path; only `content` differs. A
+      // settled component is handed over as the node (getBoundaryContent), a
+      // pending one as its promise, so only pending work shows the loading()
+      // fallback. forceAwait also awaits a pending component here. A CLIENT
+      // component that suspends on mount inside the content still reveals a
+      // fallback.
+      let loadingContent: ReactNode = getBoundaryContent(resolvedComponent);
       if (forceAwait) {
         const contentAwaitStart = segDebug ? performance.now() : 0;
-        loadingContent = await contentPromise;
+        loadingContent = await loadingContent;
         if (segDebug) {
           segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
             ms: Math.round(performance.now() - contentAwaitStart),
           });
         }
       }
-      nodeContent = createElement(RouteContentWrapper, {
-        key: `suspense-loading-${id}`,
-        content: loadingContent,
-        fallback: loading,
-        segmentId: id,
-      });
+      nodeContent = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedRouteContent
+          : RouteContentWrapper,
+        {
+          key: `suspense-loading-${id}`,
+          content: loadingContent,
+          fallback: loading,
+          segmentId: id,
+        },
+      );
     } else {
       // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. A segment in the no-loading()
       // branch whose component decodes as a Promise/lazy gets registered into
@@ -593,7 +616,10 @@ export async function renderSegments(
       let boundaryAwaitedLoaderIds: string[] | undefined;
       if (forceAwait || isAction) {
         const awaitStart = segDebug ? performance.now() : 0;
-        boundaryLoaderData = await loaderDataPromise;
+        boundaryLoaderData =
+          loaderDataPromise instanceof Promise
+            ? await loaderDataPromise
+            : loaderDataPromise;
         if (segDebug) {
           segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
             loaderIds,
@@ -621,28 +647,38 @@ export async function renderSegments(
           );
         }
       }
-      content = createElement(LoaderBoundary, {
-        key: `loader-boundary-${key}`,
-        loaderDataPromise: boundaryLoaderData,
-        loaderIds,
-        loaderStreams: boundaryLoaderStreams,
-        awaitedLoaderIds: boundaryAwaitedLoaderIds,
-        fallback: loading,
-        outletKey: key,
-        outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        children: nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedLoaderBoundary
+          : LoaderBoundary,
+        {
+          key: `loader-boundary-${key}`,
+          loaderDataPromise: boundaryLoaderData,
+          loaderIds,
+          loaderStreams: boundaryLoaderStreams,
+          awaitedLoaderIds: boundaryAwaitedLoaderIds,
+          fallback: loading,
+          outletKey: key,
+          outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          children: nodeContent,
+        },
+      );
     } else if (loaderEntries.length === 0) {
-      content = createElement(OutletProvider, {
-        key,
-        content: outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        pending: outletPending,
-        children: nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedOutletProvider
+          : OutletProvider,
+        {
+          key,
+          content: outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          pending: outletPending,
+          children: nodeContent,
+        },
+      );
     } else {
       const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
       const parallelOwnedLoaders = loaderEntries.filter(
@@ -776,17 +812,23 @@ export async function renderSegments(
         }
       }
 
-      content = createElement(OutletProvider, {
-        key,
-        content: outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
-        loaderStreams,
-        awaitedLoaderIds,
-        pending: outletPending,
-        children: errorFallback ?? nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedOutletProvider
+          : OutletProvider,
+        {
+          key,
+          content: outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          loaderData:
+            Object.keys(loaderData).length > 0 ? loaderData : undefined,
+          loaderStreams,
+          awaitedLoaderIds,
+          pending: outletPending,
+          children: errorFallback ?? nodeContent,
+        },
+      );
     }
 
     // Wrap with MountContextProvider for include() scoped components.
@@ -800,6 +842,22 @@ export async function renderSegments(
       });
     }
 
+    if (process.env.NODE_ENV !== "production") {
+      auditSegmentElement(
+        treeAudit,
+        id,
+        node.segment.type,
+        key,
+        content,
+        node.segment.type === "layout" &&
+          !!ReactViewTransition &&
+          !!transition &&
+          transition.viewTransition !== false,
+        node.parallel.map((p) => p.id),
+        [node.segment, ...node.parallel, ...node.loaders],
+      );
+    }
+
     if (segDebug) {
       segDebugLog(`segment ${id} built`, {
         type: node.segment.type,
@@ -849,6 +907,8 @@ export async function renderSegments(
     });
   }
 
+  if (process.env.NODE_ENV !== "production") finishTreeAudit(treeAudit, result);
+
   return result;
 }
 

package/src/server/build-version-table.ts

@@ -39,6 +39,21 @@ export function resolveRouterVersions(
   );
 }
 
+/**
+ * The version an on-demand prerender overlay key carries: the router's data
+ * version, because the overlay stores segment data, as the segment cache does
+ * (a client-only deploy keeps both). The write side (`router.prerender`,
+ * router.ts) and the read side (rsc/handler.ts) both call this with
+ * `createRouter({ version })`, the only override the trigger can see, so they
+ * cannot disagree; a `createRSCHandler({ version })` does not move it.
+ */
+export function resolvePrerenderVersion(
+  routerId: string | undefined,
+  routerVersion: string | undefined,
+): string {
+  return resolveRouterVersions(routerId, routerVersion).data;
+}
+
 /** The table gives some router a pair of its own. */
 function hasRouterVersions(): boolean {
   if (!table) return false;

package/src/server/context.ts

@@ -15,6 +15,10 @@ import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
 import { PPR_LANE_HINT } from "../rsc/shell-capture-constants.js";
+import {
+  noteWarmIdentityRead,
+  type WarmContext,
+} from "../prerender/warm-request.js";
 import {
   endIdentityExempt,
   isInsideCacheExecScope,
@@ -261,8 +265,13 @@ export type EntryData =
       /** Original PrerenderHandlerDefinition (for build-time getParams access) */
       prerenderDef?: {
         getParams?: (ctx: any) => Promise<any[]> | any[];
-        options?: { concurrency?: number };
+        options?: {
+          concurrency?: number;
+          onDemand?: import("../prerender/on-demand.js").OnDemandOption;
+        };
       };
+      /** Set when the route opted into on-demand prerender (Prerender(..., { onDemand })) */
+      isOnDemand?: true;
       /** Set when route is wrapped with Passthrough() — has a separate live handler */
       isPassthrough?: true;
       /** Live handler for runtime fallback (only set on Passthrough routes) */
@@ -428,6 +437,7 @@ export const getContext = (): {
   getStore: () => HelperContext;
   getParent: () => EntryData | null;
   getOrCreateStore: (forRoute?: string) => HelperContext;
+  runIsolated: <T>(forRoute: string, callback: () => T) => T;
   getNextIndex: (
     type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
   ) => string;
@@ -447,26 +457,29 @@ export const getContext = (): {
   ) => T;
 } => {
   const context = RangoContext;
+  const createStore = (forRoute?: string): HelperContext => ({
+    manifest: new Map<string, EntryData>(),
+    namespace: "",
+    parent: null,
+    forRoute,
+    counters: {},
+    patterns: new Map<string, string>(),
+    patternsByPrefix: new Map<string, Map<string, string>>(),
+    trailingSlash: new Map<string, "never" | "always" | "ignore">(),
+    searchSchemas: new Map<string, Record<string, string>>(),
+  });
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
       let store = RangoContext.getStore();
       if (!store) {
-        store = {
-          manifest: new Map<string, EntryData>(),
-          namespace: "",
-          parent: null,
-          forRoute,
-          counters: {},
-          patterns: new Map<string, string>(),
-          patternsByPrefix: new Map<string, Map<string, string>>(),
-          trailingSlash: new Map<string, "never" | "always" | "ignore">(),
-          searchSchemas: new Map<string, Record<string, string>>(),
-        } satisfies HelperContext;
+        store = createStore(forRoute);
       }
       return store;
     },
+    runIsolated: <T>(forRoute: string, callback: () => T): T =>
+      context.run(createStore(forRoute), callback),
     getStore: (): HelperContext => {
       const store = context.getStore();
       if (!store) {
@@ -959,19 +972,20 @@ export interface IdentityReadWording {
  * nothing and are not captured reads: they take refuseInCacheScope alone.
  */
 export function guardIdentityRead(
-  ctx: unknown,
+  ctx: WarmContext | null | undefined,
   surface: string,
   wording: IdentityReadWording,
 ): void {
   if (isInsideIdentityExempt()) return;
   const { verb, fix } = wording;
   if (tripShellCaptureGuard(ctx, surface, fix.warning)) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} while capturing a shared shell ` +
         `(ppr shell capture). ${fix.capture}`,
     );
   }
-  refuseInCacheScope(surface, wording);
+  refuseInCacheScope(surface, wording, ctx);
   if (wording.record !== false) recordLoaderIdentityRead(surface, verb);
 }
 
@@ -982,13 +996,16 @@ export function guardIdentityRead(
 export function refuseInCacheScope(
   surface: string,
   { verb, fix }: IdentityReadWording,
+  ctx?: WarmContext | null,
 ): void {
   if (isInsideCacheExecScope()) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} inside a "use cache" function. ${fix.useCache}`,
     );
   }
   if (isInsideCacheScope()) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} inside a cache() boundary. ${fix.cacheScope}`,
     );
@@ -1074,7 +1091,7 @@ const NON_CACHEABLE_READ: IdentityReadWording = {
  */
 export function assertNonCacheableReadAllowed(
   keyOrVar: string | ContextVar<unknown>,
-  requestCtx?: unknown,
+  requestCtx?: WarmContext | null,
 ): void {
   const name = typeof keyOrVar === "string" ? ` "${keyOrVar}"` : "";
   guardIdentityRead(
@@ -1276,7 +1293,10 @@ export function isInsideAnyLoaderScope(): boolean {
 
 /**
  * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
- * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (`false`, undefined, and on-demand routes mean plain axis 1). A writable
+ * prerender refresh cannot atomically replace the separate document shell, so
+ * combining those lanes would pair a fresh tail with a stale prelude. Shared by
+ * the serve path
  * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
  * the two layers can never drift on what counts as a ppr route.
  */
@@ -1285,7 +1305,10 @@ export function isPprEntry(entry: EntryData): entry is EntryData & {
   ppr: true | import("../urls/pattern-types.js").PartialPrerenderProps;
 } {
   return (
-    entry.type === "route" && entry.ppr !== undefined && entry.ppr !== false
+    entry.type === "route" &&
+    entry.isOnDemand !== true &&
+    entry.ppr !== undefined &&
+    entry.ppr !== false
   );
 }
 

package/src/server/cookie-store.ts

@@ -21,6 +21,7 @@ import {
   requestReadCaptureFix,
   type IdentityReadWording,
 } from "./context.js";
+import { assertNotInsidePrerenderProducer } from "../prerender/producer-guard.js";
 import { requestHeaders, shadowRequestHeaders } from "./request-headers.js";
 
 /**
@@ -72,6 +73,7 @@ export interface CookieStore {
  */
 export function cookies(): CookieStore {
   const ctx = getRequestContext();
+  assertNotInsidePrerenderProducer(ctx, "cookies()");
   guardIdentityRead(ctx, "cookies()", COOKIES_READ);
   return createCookieStore(ctx);
 }
@@ -273,6 +275,7 @@ const HEADERS_READ_PROPS = new Set<string | symbol>([
  */
 export function headers(): ReadonlyHeaders {
   const ctx = getRequestContext();
+  assertNotInsidePrerenderProducer(ctx, "headers()");
   guardIdentityRead(ctx, "headers()", HEADERS_READ);
   return new Proxy(requestHeaders(ctx.request), {
     get(target, prop, receiver) {
@@ -313,6 +316,7 @@ export function invalidateClientCache(): void {
     }
     return;
   }
+  assertNotInsidePrerenderProducer(ctx, "invalidateClientCache()");
   refuseInCacheScope("invalidateClientCache()", COOKIES_READ);
   ctx._rotateStateCookie();
 }
@@ -338,6 +342,7 @@ export function keepClientCache(): void {
     }
     return;
   }
+  assertNotInsidePrerenderProducer(ctx, "keepClientCache()");
   refuseInCacheScope("keepClientCache()", COOKIES_READ);
   ctx._setKeepCacheDirective();
 }

package/src/server/handle-store.ts

@@ -340,6 +340,9 @@ export interface HandleStore {
     segmentId: string,
   ): Record<string, (string | null)[]> | undefined;
 
+  /** The segment ids for which getRecordOwners returns an entry. */
+  getOwnedSegmentIds(): string[];
+
   /**
    * Replay cached handle data back into the store (for cache hits).
    * Used to restore handle data when serving cached segments.
@@ -1087,6 +1090,16 @@ export function createHandleStore(): HandleStore {
       return result;
     },
 
+    getOwnedSegmentIds(): string[] {
+      const ids = new Set<string>();
+      for (const handleName in data) {
+        for (const id in data[handleName]) {
+          if (!ids.has(id) && this.getRecordOwners(id)) ids.add(id);
+        }
+      }
+      return [...ids];
+    },
+
     replaySegmentData(
       segmentId: string,
       segmentHandles: Record<string, unknown[]>,

package/src/server/loader-registry.ts

@@ -86,7 +86,12 @@ export async function getLoaderLazy(
 
     // Same as the lazy branch: a thrown import is a server error, not a
     // not-found. Let it propagate to the caller for a 500 + onError.
-    await import(/* @vite-ignore */ `/${filePath}`);
+    // Not a template literal: es-module-lexer 3 reports `/${x}` as the
+    // specifier "/*", and plugin-rsc's client-reference scan build rewrites
+    // every import to `import "<specifier>"`, so the build fails to resolve
+    // "/*" (dynamic-import-specifiers.test.ts).
+    const modulePath = "/" + filePath;
+    await import(/* @vite-ignore */ modulePath);
 
     const registered = getFetchableLoader(id);
     if (registered) {