@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/rsc/shell-serve.ts

@@ -0,0 +1,181 @@
+/**
+ * Integrated PPR shell serving (Axis 2, see docs/design/ppr-shell-resume.md).
+ *
+ * PPR is opt-in per PAGE ROUTE via the `ppr` path option
+ * (`path(pattern, Handler, { name, ppr: true | PartialPrerenderProps })`) and the
+ * serving logic is INTEGRAL to the render pipeline — there is no middleware to
+ * mount. This module owns the config/key/store plumbing the render layer
+ * (rsc-rendering.ts) uses at its COMMIT POINT, which sits after the WHOLE
+ * middleware chain (global `router.use()` chain AND route DSL `middleware()`,
+ * both of which wrap the render pass): any middleware rejection/redirect wins
+ * before a single shell byte is written.
+ *
+ * The shell store is the app-level `createRouter({ cache })` store
+ * (`requestCtx._cacheStore`). A store without the `getShell`/`putShell` family
+ * degrades a ppr route to axis 1 with a once-per-key warning (the declared
+ * intent cannot be honored — unlike an undeclared route, which is silent).
+ */
+
+import React from "react";
+import type { EntryData } from "../server/context.js";
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+
+/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
+export const SHELL_STATUS_HEADER = "x-rango-shell";
+
+/**
+ * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
+ * that omits `ttl`.
+ */
+export const DEFAULT_PPR_TTL_SECONDS = 300;
+
+/** The route's ppr option normalized to a concrete policy. */
+export interface ResolvedPprConfig {
+  ttl: number;
+  swr?: number;
+  tags?: string[];
+}
+
+/**
+ * Normalize the matched page route's `ppr` path option. Returns null when the
+ * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
+ * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
+ *
+ * PPR is a DOCUMENT-level property of the page route; there is no subtree
+ * inheritance (declaring it on a layout is not supported — a follow-up).
+ */
+export function resolvePprConfig(
+  entry: EntryData | undefined | null,
+): ResolvedPprConfig | null {
+  if (!entry || entry.type !== "route") return null;
+  const ppr = entry.ppr;
+  if (ppr === undefined || ppr === false) return null;
+  if (ppr === true) return { ttl: DEFAULT_PPR_TTL_SECONDS };
+  return {
+    ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
+    swr: ppr.swr,
+    tags: ppr.tags,
+  };
+}
+
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The key includes the request HOST: in a multi-tenant host-router deployment
+ * (one worker, one shared KV/runtime-cache store) a host-less key would serve
+ * tenant A's captured shell to tenant B's users.
+ */
+export function buildShellKey(url: URL): string {
+  const sorted = sortedSearchString(url.searchParams);
+  const searchSuffix = sorted ? `?${sorted}` : "";
+  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+}
+
+/**
+ * Version gates for a stored shell: reactVersion AND buildVersion must both
+ * match the running server. The postponed blob encodes hole positions against
+ * one exact tree, so resuming it under a different React OR a different app
+ * build tree-mismatches inside resume() — after the 200 + prelude committed,
+ * with no recovery. Either mismatch is a miss: the recapture overwrites the
+ * same key (self-healing) and the entry otherwise ages out via TTL. An entry
+ * with no buildVersion (stored before the field existed) is a miss for the
+ * same reason — its build is unknown, so it cannot be proven resumable.
+ */
+export function isValidShellHit(
+  entry: ShellCacheEntry,
+  buildVersion: string,
+): boolean {
+  return (
+    entry.reactVersion === React.version && entry.buildVersion === buildVersion
+  );
+}
+
+/**
+ * Payload integrity gate, run BEFORE the HIT response commits: a stored entry
+ * whose prelude is not decodable base64 or whose postponed blob is not
+ * parseable JSON would otherwise throw AFTER the 200 + full static prelude
+ * flushed (`serveShellHit` decodes at stream construction, `resumeShellHTML`
+ * parses in the tail) — the client gets a visually complete page that never
+ * hydrates, re-served on every request until the entry ages out (no eviction
+ * path exists; failure schedules no recapture by itself). Checking here turns
+ * a corrupt entry (store-layer fault) into a plain MISS the recapture
+ * overwrites. Cost: one duplicate decode/parse per HIT, sub-ms against a
+ * prelude flush that dominates the path.
+ */
+export function hasIntactShellPayload(entry: ShellCacheEntry): boolean {
+  try {
+    base64ToBytes(entry.prelude);
+    if (entry.postponed !== null) JSON.parse(entry.postponed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Decode a base64 prelude back into bytes for stream composition. */
+export function base64ToBytes(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** True when the store implements the shell entry family. */
+export function hasShellFamily(
+  store: SegmentCacheStore | undefined,
+): store is SegmentCacheStore & {
+  getShell: NonNullable<SegmentCacheStore["getShell"]>;
+  putShell: NonNullable<SegmentCacheStore["putShell"]>;
+} {
+  return !!store?.getShell && !!store?.putShell;
+}
+
+/** Keys already warned about a missing shell store family (once per key). */
+const warnedMissingStore = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but the app-level cache store
+ * does not implement the shell family (getShell/putShell), so the route stays on
+ * axis 1. Unlike an undeclared route (silent), a declared route that cannot be
+ * honored deserves a diagnostic.
+ */
+export function warnShellStoreMissingOnce(key: string): void {
+  if (warnedMissingStore.has(key)) return;
+  warnedMissingStore.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but the app-level ` +
+      "cache store does not implement the shell family (getShell/putShell), so " +
+      "the route is served on axis 1 without a shell. Use MemorySegmentCacheStore, " +
+      "CFCacheStore, or VercelCacheStore (or add the family to your custom store) " +
+      "via createRouter({ cache }).",
+  );
+}
+
+/** Keys already warned about an active per-request nonce (once per key). */
+const warnedNonceActive = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
+ * active for the request, so the route stays on axis 1 (a shared shell would
+ * freeze one request's nonce for every visitor — useNonce() renders it into every
+ * nonced script/style/meta and the browser's CSP would then reject the frozen
+ * nonce for all but the capture request). The nonce blocks capture whether it came
+ * from the `createRouter({ nonce })` provider or from a direct `ctx.set(nonce, …)`
+ * token write in middleware. Same declared-intent-cannot-be-honored doctrine as
+ * the missing-store warning above (an undeclared route stays silent).
+ */
+export function warnPprNonceActiveOnce(key: string): void {
+  if (warnedNonceActive.has(key)) return;
+  warnedNonceActive.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
+      "CSP nonce is active for this request (from createRouter({ nonce }) or a " +
+      "ctx.set(nonce, …) token write in middleware), so the route is served on " +
+      "axis 1 without a shell. A shell is shared per host+URL; baking one " +
+      "request's nonce into it would break CSP for every other visitor. Drop the " +
+      "ppr option on this route, or stop setting a per-request nonce for it.",
+  );
+}

package/src/rsc/transition-gate.ts

@@ -0,0 +1,89 @@
+import type { MatchResult } from "../types.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+import type { getRequestContext } from "../server/request-context.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * The predicates were collected during resolution (keyed by segment id) and
+ * stripped from the serialized config; here — after handlers ran and outside any
+ * cache scope — we evaluate each and drop the segment's transition when the
+ * predicate does not hold, so the navigation streams its loading fallback
+ * instead of holding the previous content. A predicate that throws is reported
+ * to the router's onError (phase "rendering") and then treated as "do not hold"
+ * (conservative), so a buggy predicate degrades to no transition rather than
+ * failing the response.
+ *
+ * Mutating the segments here is safe: the segment cache stores a serialized copy
+ * (segment-codec), written during match() BEFORE this gate runs, so dropping a
+ * transition never corrupts a cache entry. The flip side is that a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate) — combining transition({ when })
+ * with cache() on the same segment freezes the gate to its cached state, so
+ * avoid caching a route whose transition decision is request-dependent.
+ *
+ * Returns the same array (mutated) for inline use at the payload's `segments`
+ * field.
+ */
+export function gateTransitions(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+  onError?: OnErrorCallback,
+): MatchResult["segments"] {
+  const predicates = ctx._transitionWhen;
+  if (predicates && predicates.length) {
+    for (const { id, when } of predicates) {
+      let drop: boolean;
+      try {
+        // Assemble the ShouldRevalidateFn-shaped predicate context from the
+        // request context. Source fields (currentUrl/currentParams/fromRouteName)
+        // were stashed at match time from the navigation snapshot; action fields
+        // at the action-bearing gate call sites. nextUrl/nextParams/toRouteName/
+        // method/get/env come straight off ctx (setRequestContextParams ran
+        // before the gate). Source/action fields are undefined when absent —
+        // never fabricated (see TransitionWhenContext).
+        const whenCtx: TransitionWhenContext = {
+          currentUrl: ctx._gateCurrentUrl,
+          currentParams: ctx._gateCurrentParams,
+          fromRouteName:
+            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+          nextUrl: ctx.url,
+          nextParams: ctx.params,
+          toRouteName: ctx.routeName,
+          actionId: ctx._gateActionId,
+          actionUrl: ctx._gateActionUrl,
+          actionResult: ctx._gateActionResult,
+          formData: ctx._gateFormData,
+          method: ctx.request.method,
+          get: ctx.get,
+          env: ctx.env,
+        };
+        drop = when(whenCtx) === false;
+      } catch (error) {
+        // A throwing predicate must not fail the response: report it and treat
+        // the transition as gated off (do not hold). invokeOnError no-ops when
+        // onError is undefined.
+        drop = true;
+        invokeOnError(
+          onError,
+          error,
+          "rendering",
+          {
+            request: ctx.request,
+            url: ctx.url,
+            params: ctx.params,
+            segmentId: id,
+          },
+          "RSC",
+        );
+      }
+      if (drop) {
+        const seg = segments.find((s) => s.id === id);
+        if (seg) seg.transition = undefined;
+      }
+    }
+  }
+  return segments;
+}

package/src/rsc/types.ts

@@ -43,6 +43,10 @@ export interface RscPayload {
     version?: string;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
+    /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */
+    prefetchCacheSize?: number;
+    /** Max concurrent speculative prefetch requests on the client */
+    prefetchConcurrency?: number;
     /** Server-resolved rango state cookie name; the client reads it verbatim. */
     stateCookieName?: string;
     /** Theme configuration for FOUC prevention */
@@ -160,6 +164,32 @@ export interface SSRModule {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ) => Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * PPR shell CAPTURE strategy (Axis 2). Prerenders the loader-masked shell over
+   * the Flight stream, aborts once quiescent, and returns the prelude bytes plus
+   * the postponed resume state — or null when the prelude degraded and must not
+   * be stored. Present only when the SSR virtual entry wires
+   * createShellCaptureHandler; the render layer feature-detects it. See
+   * docs/design/ppr-shell-resume.md.
+   */
+  captureShellHTML?: (
+    rscStream: ReadableStream<Uint8Array>,
+    options: { quiesce: Promise<void>; maxWaitMs?: number },
+  ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
+
+  /**
+   * PPR shell RESUME strategy (Axis 2). Produces the per-request live portion of
+   * the document: resumes fizz over a fresh SsrRoot to emit only the postponed
+   * holes (or, for the DATA variant with postponed === null, just the fresh Flight
+   * payload scripts). The caller prepends the stored prelude bytes to form the
+   * composite response. Present only when the SSR virtual entry wires
+   * createShellResumeHandler; the render layer feature-detects it.
+   */
+  resumeShellHTML?: (
+    rscStream: ReadableStream<Uint8Array>,
+    options: { postponed: string | null; nonce?: string },
+  ) => Promise<ReadableStream<Uint8Array>>;
 }
 
 /**

package/src/segment-loader-promise.ts

@@ -1,4 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 
 /**
  * Cache of aggregate Promise.all results keyed on the first loader's
@@ -83,6 +84,23 @@ export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
   if (loaders.length === 0) {
     return Promise.resolve([]);
   }
+  // Debug tap (browser only): log when each PENDING loader promise settles —
+  // i.e. when its data actually lands from the flight stream — independent of
+  // when the tree build awaits it. `.then(cb, cb)` observes on a branch, so
+  // rejections still propagate to the real consumers untouched.
+  if (INTERNAL_RANGO_DEBUG && IS_BROWSER) {
+    const tapStart = performance.now();
+    for (const loader of loaders) {
+      if (loader.loaderData instanceof Promise) {
+        const settle = (outcome: string) => () =>
+          console.log(
+            `[Browser][segments] loader ${loader.loaderId} ${outcome} @ ${Math.round(performance.now())}ms`,
+            { msSinceRequested: Math.round(performance.now() - tapStart) },
+          );
+        loader.loaderData.then(settle("settled"), settle("rejected"));
+      }
+    }
+  }
   return Promise.all(
     loaders.map((loader) =>
       loader.loaderData instanceof Promise

package/src/segment-system.tsx

@@ -10,12 +10,29 @@ import {
   LoaderBoundary,
 } 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 {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
 
+/**
+ * Client-only debug log for the segment tree build. Gated on the baked flag
+ * AND `typeof window` (renderSegments also runs during SSR/RSC, which must
+ * stay silent). Timestamped so tree-build steps line up with the
+ * `[Browser][boot]` sequence around hydrateRoot.
+ */
+function segDebugLog(msg: string, details?: Record<string, unknown>): void {
+  if (!(INTERNAL_RANGO_DEBUG && typeof window === "object")) return;
+  const prefix = `[Browser][segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}
+
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
@@ -211,6 +228,17 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
+  const segDebug = INTERNAL_RANGO_DEBUG && typeof window === "object";
+  const segDebugStart = segDebug ? performance.now() : 0;
+  if (segDebug) {
+    segDebugLog("renderSegments start", {
+      segments: segments.map((s) => `${s.id}:${s.type}`),
+      isAction: !!isAction,
+      forceAwait: !!forceAwait,
+      intercepts: interceptSegments?.length ?? 0,
+    });
+  }
+
   const temporalLazyRefs: Promise<any>[] = [];
   const normalizedSegments = restoreParallelLoaderMarkers(segments);
   const normalizedInterceptSegments = interceptSegments
@@ -272,6 +300,15 @@ export async function renderSegments(
     );
     const { component, id, params, loading } = node.segment;
 
+    if (segDebug) {
+      segDebugLog(`segment ${id}`, {
+        type: node.segment.type,
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
+
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
     // transition scope drops the param from its key, so navigating between two
@@ -316,14 +353,47 @@ export async function renderSegments(
       resolvedComponent = await component;
     }
 
-    let nodeContent: ReactNode = isRenderableLoading(loading)
-      ? createElement(RouteContentWrapper, {
-          key: `suspense-loading-${id}`,
-          content: getMemoizedContentPromise(resolvedComponent),
-          fallback: loading,
-          segmentId: id,
-        })
-      : registerLazyRef(resolvedComponent);
+    let nodeContent: ReactNode = null;
+    if (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);
+      const loadingContent: Promise<ReactNode> | ReactNode = forceAwait
+        ? await contentPromise
+        : contentPromise;
+      nodeContent = createElement(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
+      // temporalLazyRefs and awaited before commit (see below) — which on builds
+      // where the segment component arrives deferred defeats client-nav streaming.
+      if (INTERNAL_RANGO_DEBUG && typeof window === "object") {
+        const c = resolvedComponent as unknown;
+        console.log("[VT-DIAG] renderSegments no-loading-branch segment", {
+          id,
+          type: node.segment.type,
+          componentIsPromise: c instanceof Promise,
+          componentIsLazy:
+            c != null && typeof c === "object" && "_payload" in c,
+          componentTypeof: typeof c,
+        });
+      }
+      nodeContent = registerLazyRef(resolvedComponent);
+    }
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
@@ -369,10 +439,25 @@ export async function renderSegments(
 
     if (loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
+      let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      if (forceAwait || isAction) {
+        const awaitStart = segDebug ? performance.now() : 0;
+        boundaryLoaderData = await loaderDataPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
+            loaderIds,
+            ms: Math.round(performance.now() - awaitStart),
+          });
+        }
+      } else if (segDebug) {
+        segDebugLog(
+          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
+          { loaderIds },
+        );
+      }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
-        loaderDataPromise:
-          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderDataPromise: boundaryLoaderData,
         loaderIds,
         fallback: loading,
         outletKey: key,
@@ -396,7 +481,17 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      // No loading() on this segment, so its loader data cannot stream behind
+      // a Suspense fallback — the tree build BLOCKS here until the data
+      // arrives. On the initial document this await runs before hydrateRoot.
+      const layoutAwaitStart = segDebug ? performance.now() : 0;
       const resolvedData = await buildLoaderPromise(layoutLoaders);
+      if (segDebug) {
+        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+          loaderIds: layoutLoaderIds,
+          ms: Math.round(performance.now() - layoutAwaitStart),
+        });
+      }
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
@@ -429,10 +524,27 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          p.loaderDataPromise =
-            (forceAwait || isAction) && aggregated instanceof Promise
-              ? await aggregated
-              : aggregated;
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            const parallelAwaitStart = segDebug ? performance.now() : 0;
+            p.loaderDataPromise = await aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                {
+                  loaderIds: p.loaderIds,
+                  ms: Math.round(performance.now() - parallelAwaitStart),
+                },
+              );
+            }
+          } else {
+            p.loaderDataPromise = aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                { loaderIds: p.loaderIds },
+              );
+            }
+          }
         }
       }
 
@@ -462,7 +574,24 @@ export async function renderSegments(
     children: content,
   });
   if (typeof window === "object") {
+    // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. If this await dominates the
+    // navigation time, a deferred/lazy segment component is being fully resolved
+    // before commit, which defeats client-nav streaming. The await itself is
+    // functional (it preloads lazy chunk refs); only the timing log is gated.
+    const vtDebug = INTERNAL_RANGO_DEBUG && temporalLazyRefs.length > 0;
+    const vtDebugStart = vtDebug ? performance.now() : 0;
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments awaiting temporalLazyRefs", {
+        count: temporalLazyRefs.length,
+      });
+    }
     await Promise.allSettled(temporalLazyRefs);
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments temporalLazyRefs settled", {
+        count: temporalLazyRefs.length,
+        ms: Math.round(performance.now() - vtDebugStart),
+      });
+    }
   }
 
   let result: ReactNode = errorBoundaryWrapped;
@@ -473,6 +602,12 @@ export async function renderSegments(
     });
   }
 
+  if (segDebug) {
+    segDebugLog("renderSegments complete", {
+      ms: Math.round(performance.now() - segDebugStart),
+    });
+  }
+
   return result;
 }
 

package/src/server/context.ts

@@ -150,6 +150,19 @@ export type InterceptWhenFn<TEnv = any> = (
   ctx: InterceptSelectorContext<TEnv>,
 ) => boolean;
 
+/**
+ * Config object passed to intercept() (its 4th argument). `when` gates whether
+ * the intercept activates on a soft navigation — a single match-time selector or
+ * an array of them (ALL must return true; omit to always activate). This is the
+ * intercept counterpart to transition({ when }); both express conditional
+ * behavior as a config field rather than a separate DSL helper.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface InterceptConfig<TEnv = any> {
+  when?: InterceptWhenFn<TEnv> | InterceptWhenFn<TEnv>[];
+}
+
 /**
  * Intercept entry stored in EntryData
  * Contains the slot name, route to intercept, and handler
@@ -220,6 +233,13 @@ export type EntryData =
       staticHandlerId?: string;
       /** Response type for non-RSC routes (json, text, image, any) */
       responseType?: string;
+      /**
+       * PPR (partial pre-rendering) opt-in from the path() `ppr` option. A
+       * document-level property of the page route: `true` uses the default
+       * shell policy, an object carries ttl/swr/tags. Read by the integrated
+       * PPR serve path (rsc/shell-serve.ts resolvePprConfig).
+       */
+      ppr?: boolean | import("../urls/pattern-types.js").PartialPrerenderProps;
     } & EntryPropCommon &
       EntryPropDatas &
       EntryPropSegments &
@@ -750,14 +770,23 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
 
 // Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
 // of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
-// invoked via ctx.use). Consulted ONLY by isInsideCacheScope() to exempt
-// request-scoped reads. It deliberately does NOT affect isInsideLoaderScope(),
-// so rendered()/barrier/deadlock gating (which must distinguish DSL from
-// handler-invoked loaders) is unchanged.
+// invoked via ctx.use). Consulted by isInsideCacheScope() to exempt
+// request-scoped reads, by getCurrentLoaderBodyId() for guard-warning
+// attribution, and by isInsideHandlerInvokedLoaderBody() for the
+// consumption-lane rule (the shell-capture guard exemption). It deliberately
+// does NOT affect isInsideLoaderScope(), so rendered()/barrier/deadlock
+// gating (which must distinguish DSL from handler-invoked loaders) is
+// unchanged.
 const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
-const loaderBodyScopeALS: AsyncLocalStorage<{ active: true }> = ((
-  globalThis as any
-)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+const loaderBodyScopeALS: AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}> = ((globalThis as any)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}>());
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
@@ -802,8 +831,37 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache-scope guards — loaders always run fresh.
  */
-export function runInsideLoaderBodyScope<T>(fn: () => T): T {
-  return loaderBodyScopeALS.run({ active: true }, fn);
+export function runInsideLoaderBodyScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  handlerInvoked?: boolean,
+): T {
+  return loaderBodyScopeALS.run({ active: true, loaderId, handlerInvoked }, fn);
+}
+
+/**
+ * The $$id of the loader whose body is currently executing, or undefined
+ * outside any loader body. Used by the shell-capture identity guard
+ * (cookie-store.ts) so its refusal warning can name the loader that read
+ * cookies()/headers() instead of blaming a lane it cannot see — the old
+ * hardcoded "bake-lane loader" text misled a live-lane debugging session
+ * (issue #672, secondary).
+ */
+export function getCurrentLoaderBodyId(): string | undefined {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
+
+/**
+ * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
+ * handler, not the DSL segment funnel) is executing. The consumption-lane
+ * rule keys off this: handler consumption yields a BAKED copy in every shared
+ * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
+ * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
+ * like the cache-purity guards do. DSL segment loaders (live lane masked at
+ * capture, bake lane guarded) never set the flag.
+ */
+export function isInsideHandlerInvokedLoaderBody(): boolean {
+  return loaderBodyScopeALS.getStore()?.handlerInvoked === true;
 }
 
 // Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).