@rangojs/router 0.18.0 → 0.19.1

package/src/prerender/build-shell-capture.ts

@@ -33,12 +33,12 @@ import {
   deriveShellCaptureContext,
   captureAndStoreShell,
   settleCaptureRecord,
-  withinDeadline,
   delay,
-  SHELL_CAPTURE_MAX_WAIT_MS,
   SHELL_CAPTURE_RETRY_DELAY_MS,
   type ShellCaptureDescriptor,
 } from "../rsc/shell-capture.js";
+import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
+import { raceDeadline } from "../cache/background-task.js";
 import { buildFullPayload } from "../rsc/full-payload.js";
 import { buildRouteMiddlewareEntries } from "../rsc/helpers.js";
 import type { RscPayload, SSRModule } from "../rsc/types.js";
@@ -221,82 +221,81 @@ async function attemptBuildCapture(
     tags: opts.tags,
     captureTimeout: opts.captureTimeout,
     store: collector as any,
-    debug: opts.debug,
     maxSnapshotBytes: opts.maxSnapshotBytes,
   };
 
-  let mismatchedRouteName: string | undefined;
-  let timedOut = false;
-  const result = await runWithRequestContext(baseCtx, async () => {
-    const preview =
-      typeof router.previewMatch === "function"
-        ? await router.previewMatch(request, { env })
-        : undefined;
-    // These preview-based mismatches exit before any middleware/envelope runs,
-    // so nothing consumes a response — only result.outcome is read below.
-    if (preview === null) {
-      return { outcome: "route-mismatch" } as const;
-    }
-    if (preview?.routeKey && preview.routeKey !== opts.routeName) {
-      mismatchedRouteName = preview.routeKey;
-      return { outcome: "route-mismatch" } as const;
-    }
+  const result = await runWithRequestContext(
+    baseCtx,
+    async (): Promise<
+      | BuildCaptureRunResult
+      | { outcome: "route-mismatch"; matchedRouteName?: string }
+    > => {
+      const preview =
+        typeof router.previewMatch === "function"
+          ? await router.previewMatch(request, { env })
+          : undefined;
+      // These preview-based mismatches exit before any middleware/envelope runs,
+      // so nothing consumes a response.
+      if (preview === null) {
+        return { outcome: "route-mismatch" };
+      }
+      if (preview?.routeKey && preview.routeKey !== opts.routeName) {
+        return {
+          outcome: "route-mismatch",
+          matchedRouteName: preview.routeKey,
+        };
+      }
 
-    if (preview?.routeKey) {
-      setRequestContextParams(preview.params ?? {}, preview.routeKey);
-    }
+      if (preview?.routeKey) {
+        setRequestContextParams(preview.params ?? {}, preview.routeKey);
+      }
 
-    // Global-only, like the live request's middleware reverse
-    // (rsc/handler.ts: createReverseFunction(getRequiredRouteMap())): no
-    // include() scope, no param auto-fill. A scoped reverse here resolved
-    // `.name` at build while the live request threw `Unknown route`.
-    const middlewareReverse = createReverseFunction(getGlobalRouteMap());
+      // Global-only, like the live request's middleware reverse
+      // (rsc/handler.ts: createReverseFunction(getRequiredRouteMap())): no
+      // include() scope, no param auto-fill. A scoped reverse here resolved
+      // `.name` at build while the live request threw `Unknown route`.
+      const middlewareReverse = createReverseFunction(getGlobalRouteMap());
 
-    const runCapture = () =>
-      runBuildCaptureFinal({
-        baseCtx,
-        descriptor,
-        env,
-        opts,
-        request,
-        router,
-        url,
-        setMismatchedRouteName: (routeName) => {
-          mismatchedRouteName = routeName;
-        },
-        markTimedOut: () => {
-          timedOut = true;
-        },
-      });
+      const runCapture = () =>
+        runBuildCaptureFinal({
+          baseCtx,
+          descriptor,
+          env,
+          opts,
+          request,
+          router,
+          url,
+        });
+
+      const routeMiddleware =
+        preview?.routeMiddleware && preview.routeMiddleware.length > 0
+          ? buildRouteMiddlewareEntries(preview.routeMiddleware)
+          : [];
+      const runRouteMiddleware = () =>
+        runBuildMiddlewareEnvelope(
+          routeMiddleware,
+          request,
+          env,
+          variables,
+          runCapture,
+          middlewareReverse,
+          baseCtx,
+        );
 
-    const routeMiddleware =
-      preview?.routeMiddleware && preview.routeMiddleware.length > 0
-        ? buildRouteMiddlewareEntries(preview.routeMiddleware)
+      const globalMiddleware = Array.isArray(router.middleware)
+        ? matchMiddleware(url.pathname, router.middleware)
         : [];
-    const runRouteMiddleware = () =>
-      runBuildMiddlewareEnvelope(
-        routeMiddleware,
+      return runBuildMiddlewareEnvelope(
+        globalMiddleware,
         request,
         env,
         variables,
-        runCapture,
+        runRouteMiddleware,
         middlewareReverse,
         baseCtx,
       );
-
-    const globalMiddleware = Array.isArray(router.middleware)
-      ? matchMiddleware(url.pathname, router.middleware)
-      : [];
-    return runBuildMiddlewareEnvelope(
-      globalMiddleware,
-      request,
-      env,
-      variables,
-      runRouteMiddleware,
-      middlewareReverse,
-      baseCtx,
-    );
-  });
+    },
+  );
 
   const outcome = result.outcome;
   if (outcome === "stored" && collected !== null) {
@@ -304,9 +303,11 @@ async function attemptBuildCapture(
     return { outcome, entry: hit.entry, tags: hit.tags };
   }
   if (outcome === "route-mismatch") {
-    return { outcome, matchedRouteName: mismatchedRouteName };
+    return { outcome, matchedRouteName: result.matchedRouteName };
+  }
+  if (outcome === "no-shell" && "timedOut" in result && result.timedOut) {
+    return { outcome, timedOut: true };
   }
-  if (outcome === "no-shell" && timedOut) return { outcome, timedOut: true };
   return { outcome };
 }
 
@@ -315,6 +316,10 @@ type BuildShellCaptureOutcome = BuildShellCaptureResult["outcome"];
 interface BuildCaptureRunResult {
   outcome: BuildShellCaptureOutcome;
   response: Response;
+  /** On route-mismatch: what this router's match landed on. */
+  matchedRouteName?: string;
+  /** On no-shell: the attempt ran out of ppr.captureTimeout. */
+  timedOut?: true;
 }
 
 interface BuildCaptureFinalOptions {
@@ -325,9 +330,6 @@ interface BuildCaptureFinalOptions {
   request: Request;
   router: any;
   url: URL;
-  setMismatchedRouteName(routeName: string | undefined): void;
-  /** The attempt ran out of ppr.captureTimeout (BuildShellCaptureResult.timedOut). */
-  markTimedOut(): void;
 }
 
 async function runBuildMiddlewareEnvelope<TEnv>(
@@ -392,92 +394,99 @@ async function runBuildCaptureFinal(
     swr: opts.swr,
   });
   const { derivedCtx, freshHandleStore } = derivation;
+  // The capture generation starts before the match, as at runtime
+  // (ShellCacheEntry.createdAt; the build-shell read-through compares tag
+  // invalidations against it).
+  const captureStartedAt = Date.now();
 
-  const outcome = await runWithRequestContext(derivedCtx, async () => {
-    // Same one deadline as the runtime capture: the match, the record-first
-    // step, then the prerender with what is left.
-    const deadline =
-      Date.now() + (opts.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS);
-    let match: MatchResult;
-    try {
-      const matched = await withinDeadline<MatchResult>(
-        router.match(request, { env }),
-        deadline,
-      );
-      if (!matched.done) {
-        options.markTimedOut();
-        return "no-shell" as const;
+  const result = await runWithRequestContext(
+    derivedCtx,
+    async (): Promise<Omit<BuildCaptureRunResult, "response">> => {
+      // Same one deadline as the runtime capture: the match, the record-first
+      // step, then the prerender with what is left.
+      const deadline =
+        Date.now() + (opts.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS);
+      let match: MatchResult;
+      try {
+        const matched = await raceDeadline<MatchResult>(
+          router.match(request, { env }),
+          deadline,
+        );
+        if (!matched.done) return { outcome: "no-shell", timedOut: true };
+        match = matched.value;
+      } catch (error) {
+        if (isPlainPathMiss(error, opts.urlPath)) {
+          return { outcome: "route-mismatch" };
+        }
+        throw error;
       }
-      match = matched.value;
-    } catch (error) {
-      if (isPlainPathMiss(error, opts.urlPath)) {
-        return "route-mismatch" as const;
+      if (match.routeName !== opts.routeName) {
+        return { outcome: "route-mismatch", matchedRouteName: match.routeName };
       }
-      throw error;
-    }
-    if (match.routeName !== opts.routeName) {
-      options.setMismatchedRouteName(match.routeName);
-      return "route-mismatch" as const;
-    }
-    if (match.redirect) return "redirect" as const;
+      if (match.redirect) return { outcome: "redirect" };
 
-    setRequestContextParams(match.params, match.routeName);
+      setRequestContextParams(match.params, match.routeName);
 
-    // Same record-first step as the runtime capture. A prerendered URL's
-    // match comes from the prerender store (no handler runs, no doc record),
-    // which settleCaptureRecord reports as `prerender`.
-    const settled = await settleCaptureRecord(
-      match,
-      derivation,
-      descriptor,
-      deadline,
-    );
-    if (settled.kind === "refused") {
-      return derivedCtx._dynamic ? ("dynamic" as const) : ("refused" as const);
-    }
-    if (settled.kind === "timeout") {
-      options.markTimedOut();
-      return "no-shell" as const;
-    }
+      // Same record-first step as the runtime capture. A prerendered URL's
+      // match comes from the prerender store (no handler runs, no doc record),
+      // which settleCaptureRecord reports as `prerender`.
+      const settled = await settleCaptureRecord(
+        match,
+        derivation,
+        descriptor,
+        deadline,
+      );
+      if (settled.kind === "refused") {
+        return { outcome: derivedCtx._dynamic ? "dynamic" : "refused" };
+      }
+      if (settled.kind === "timeout") {
+        return { outcome: "no-shell", timedOut: true };
+      }
 
-    const payload = buildFullPayload(
-      settled.match,
-      // buildFullPayload reads only ctx.router.* and ctx.version.
-      { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
-      url,
-      derivedCtx,
-      freshHandleStore,
-    );
-    const rscStream = renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        if (opts.debug) {
-          console.warn(
-            `[rango] shell capture render error for ${opts.urlPath}:`,
-            error,
-          );
-        }
-      },
-    });
+      const payload = buildFullPayload(
+        settled.match,
+        // buildFullPayload reads only ctx.router.* and ctx.version.
+        {
+          router,
+          version: opts.buildVersion,
+        } as unknown as HandlerContext<any>,
+        url,
+        derivedCtx,
+        freshHandleStore,
+      );
+      const rscStream = renderToReadableStream<RscPayload>(payload, {
+        onError: (error: unknown) => {
+          if (opts.debug) {
+            console.warn(
+              `[rango] shell capture render error for ${opts.urlPath}:`,
+              error,
+            );
+          }
+        },
+      });
 
-    const captureOutcome = await captureAndStoreShell(
-      { captureShellHTML: opts.captureShellHTML } as SSRModule,
-      rscStream,
-      freshHandleStore,
-      derivedCtx,
-      { ...descriptor, captureTimeout: Math.max(1, deadline - Date.now()) },
-    );
-    if (captureOutcome === "no-shell" && Date.now() >= deadline) {
-      options.markTimedOut();
-    }
-    if (derivedCtx._dynamic) return "dynamic";
-    // A route cache() record that ran out mid-capture: the in-place retry
-    // (captureShellForBuild) reads or renders a newer one.
-    return captureOutcome === "expired" ? "no-shell" : captureOutcome;
-  });
+      const captureOutcome = await captureAndStoreShell(
+        { captureShellHTML: opts.captureShellHTML } as SSRModule,
+        rscStream,
+        derivedCtx,
+        { ...descriptor, captureTimeout: Math.max(1, deadline - Date.now()) },
+        captureStartedAt,
+      );
+      if (derivedCtx._dynamic) return { outcome: "dynamic" };
+      if (captureOutcome === "no-shell" && Date.now() >= deadline) {
+        return { outcome: "no-shell", timedOut: true };
+      }
+      // A route cache() record that ran out mid-capture: the in-place retry
+      // (captureShellForBuild) reads or renders a newer one.
+      return {
+        outcome: captureOutcome === "expired" ? "no-shell" : captureOutcome,
+      };
+    },
+  );
 
   return {
-    outcome,
-    response: responseForBuildCaptureOutcome(outcome),
+    ...result,
+    response: responseForBuildCaptureOutcome(result.outcome),
   };
 }
 

package/src/route-definition/dsl-helpers.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { assertTransitionWhenShape } from "../transition-when-ref.js";
 import type {
   PartialCacheOptions,
   Handler,
@@ -1007,6 +1008,7 @@ const transition = (
   const { store, ctx } = requireDslContext(
     "transition() must be called inside urls()",
   );
+  assertTransitionWhenShape(config.when);
 
   // Allocate a single index for this transition() call (used in all paths),
   // mirroring cache() — the child form uses it for the name, the wrapper form

package/src/route-definition/helpers-types.ts

@@ -188,7 +188,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *
    * // Conditional activation via the config object's `when` selector
    * intercept("@modal", "card", <CardModal />, {
-   *   when: ({ from }) => from.pathname.startsWith("/board"),
+   *   when: ({ from }) => from.url.pathname.startsWith("/board"),
    * })
    *
    * // Config + other use-items: config is arg 4, use is arg 5
@@ -196,7 +196,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   "@modal",
    *   "card",
    *   <CardModal />,
-   *   { when: ({ from }) => from.pathname.startsWith("/board") },
+   *   { when: ({ from }) => from.url.pathname.startsWith("/board") },
    *   () => [loader(CardDetailLoader)],
    * )
    * ```
@@ -501,12 +501,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * transition({}) is startTransition + ViewTransition under the default and
    * startTransition only when the router sets viewTransition: false.
    *
-   * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
-   * request. It normally runs server-side after the route handler. On a `ppr`
-   * route it is automatically hoisted before route handlers and reevaluated on
-   * every replay, so it may read URL/params/action/env and middleware-set context
-   * but not handler-set context. Returning false drops this transition for the
-   * request. This is distinct from intercept()'s match-time `when` selector.
+   * Conditional hold: pass `when` to gate the navigation in the browser,
+   * inline (the build hoists the literal into a client module) or as a
+   * "use client" export. It runs once per
+   * navigation with { kind, from, to, isAction, action }, never on the server;
+   * false makes the commit urgent (no hold, no view transition). This is
+   * distinct from intercept()'s match-time `when` selector.
    *
    * ```typescript
    * // Attach to a single route
@@ -525,15 +525,15 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   transition({ viewTransition: false }),
    * ])
    *
-   * // Hold only when the handler decided to (post-handler predicate):
+   * // Hold only when arriving from the list (a browser predicate):
    * path("/product/:id", ProductPage, { name: "product" }, () => [
-   *   transition({ when: (ctx) => ctx.get(KeepScroll) === true }),
+   *   transition({ when: ({ from }) => from.routeName === "products.list" }),
    * ])
    * ```
    * @param config - ViewTransition configuration (enter, exit, update, share,
    *   default, name), `viewTransition: "auto" | false` to toggle the router
    *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
-   *   `when: (ctx) => boolean` to gate the transition per request
+   *   `when` to gate the transition per navigation (a browser predicate)
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {

package/src/route-name.ts

@@ -32,6 +32,18 @@ export function isAutoGeneratedRouteName(name: string): boolean {
   });
 }
 
+/**
+ * The route name user code may see: a user-defined name, or undefined for an
+ * internal one (unnamed path(), hidden include scope). Internal names are
+ * route keys, not API, and must not leak into transition({ when }) or
+ * intercept({ when }) locations.
+ */
+export function publicRouteName(
+  routeKey: string | undefined,
+): string | undefined {
+  return routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
+}
+
 /**
  * Validate that a user-provided route name does not collide with
  * reserved internal prefixes. Checks every dot-separated segment,

package/src/router/content-negotiation.ts

@@ -6,6 +6,7 @@
  * RSC routes and response routes (JSON, text, image, stream, etc.).
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import type { EntryData } from "../server/context.js";
 import type { NegotiateVariant } from "../build/route-trie.js";
 import type { CollectedMiddleware } from "./middleware-types.js";
@@ -245,7 +246,9 @@ export async function negotiateRoute(
     return null;
   }
 
-  const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
+  const acceptEntries = parseAcceptTypes(
+    requestHeaders(request).get("accept") || "",
+  );
 
   // Variants carry the variant's own pa (positional param names); the synthetic
   // primary/RSC candidates have none (their params are already keyed correctly).

package/src/router/error-handling.ts

@@ -6,7 +6,8 @@
  */
 
 import { createElement, type ReactNode } from "react";
-import type { EntryData } from "../server/context";
+import type { EntryData } from "../server/context.js";
+import { runIdentityExempt } from "../cache/cache-exec-scope.js";
 import type {
   ResolvedSegment,
   ErrorInfo,
@@ -92,7 +93,9 @@ export function invokeOnError<TEnv = any>(
   };
 
   try {
-    const result = onError(errorContext);
+    // An observer: a request header it logs is not rendered, so the identity
+    // guards let it read one inside a capture or a cached scope (#976).
+    const result = runIdentityExempt(() => onError(errorContext));
     // If onError returns a promise, catch any rejections
     if (result instanceof Promise) {
       result.catch((callbackError) => {

package/src/router/handler-context.ts

@@ -21,7 +21,10 @@ import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
 } from "../server/context.js";
-import { assertThemeReadAllowed } from "../server/cookie-store.js";
+import {
+  guardRequestHeaders,
+  readGuardedTheme,
+} from "../server/cookie-store.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
@@ -38,7 +41,7 @@ const THEME_REQUEST_CONTEXT = Symbol("rango:theme-request-context");
 
 /**
  * ctx.theme is the visitor's theme cookie, guarded like cookies() (#971,
- * assertThemeReadAllowed): a getter, so creating the ctx reads nothing and
+ * readGuardedTheme): a getter, so creating the ctx reads nothing and
  * only a handler that reads the theme refuses a ppr capture or throws on a
  * cache() miss. Non-enumerable, so serializing the ctx does not read it:
  * React's dev Flight debug info JSON-stringifies server component props and
@@ -52,10 +55,7 @@ const THEME_REQUEST_CONTEXT = Symbol("rango:theme-request-context");
  */
 const THEME_DESCRIPTOR: PropertyDescriptor = {
   get(this: { [THEME_REQUEST_CONTEXT]?: RequestContext }) {
-    const requestContext = this[THEME_REQUEST_CONTEXT];
-    if (!requestContext?._themeConfig) return undefined;
-    assertThemeReadAllowed(_getRequestContext() ?? requestContext, "ctx.theme");
-    return requestContext._readTheme();
+    return readGuardedTheme(this[THEME_REQUEST_CONTEXT], "ctx.theme");
   },
   enumerable: false,
   configurable: true,
@@ -295,7 +295,10 @@ export function createHandlerContext<TEnv>(
       requestContext?.dynamic();
     },
     dev: false,
-    request,
+    // Usually the request context's (guarded at creation). A request the
+    // router builds and matches (the progressive-enhancement re-render, a
+    // navigation-only ppr capture) is guarded here, before any handler runs.
+    request: guardRequestHeaders(request),
     searchParams,
     search: searchSchema ? resolvedSearchParams : {},
     pathname,

package/src/router/intercept-resolution.ts

@@ -64,6 +64,8 @@ function latchPprHeaderScopeForInterceptTarget(
  * Check if an intercept's when conditions are satisfied.
  * All when() functions must return true for the intercept to activate.
  * If no when() conditions are defined, the intercept always activates.
+ * A selector that throws yields the conservative default, no intercept (the
+ * full page renders), and is logged; it never fails the request.
  *
  * During action revalidation, when() is NOT evaluated.
  */
@@ -84,7 +86,15 @@ export function evaluateInterceptWhen(
     return false;
   }
 
-  return intercept.when.every((fn) => fn(selectorContext));
+  try {
+    return intercept.when.every((fn) => fn(selectorContext));
+  } catch (error) {
+    console.error(
+      `[rango] intercept({ when }) for route "${selectorContext.to.routeName ?? intercept.routeName}" (${intercept.slotName}) threw; rendering the full page without the intercept.`,
+      error,
+    );
+    return false;
+  }
 }
 
 /**