@rangojs/router 0.17.0 → 0.19.0

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

@@ -4,9 +4,9 @@
  * Runs in the RSC realm of the build's temp server, AFTER all bundles are
  * written (the prelude embeds built client asset URLs — bootstrap module,
  * chunk preloads — that only exist post-client-build). The capture core is
- * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
- * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
- * quiesce, tags union, putShell barrier). Build capture first replays global
+ * producer A's, verbatim: deriveShellCaptureContext (push funnel, snapshot
+ * recording, implicit doc-cache scope) + settleCaptureRecord (the record-first
+ * step) + captureAndStoreShell (gates, quiesce, tags union, putShell barrier). Build capture first replays global
  * and route middleware with a synthetic build request context
  * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
  * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
@@ -21,6 +21,7 @@
  */
 
 import type { ShellCacheEntry } from "../cache/types.js";
+import type { MatchResult } from "../types.js";
 import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
 import {
   createRequestContext,
@@ -31,10 +32,13 @@ import {
 import {
   deriveShellCaptureContext,
   captureAndStoreShell,
+  settleCaptureRecord,
   delay,
   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";
@@ -134,18 +138,25 @@ export interface BuildShellCaptureResult {
   tags?: string[];
   /** On route-mismatch: what this router's match actually landed on. */
   matchedRouteName?: string;
+  /**
+   * On no-shell: the attempt ran out of ppr.captureTimeout. It is not
+   * retried: its match may still be running, and the retry would start the
+   * same work beside it (runtime twin: shell-capture.ts runShellCapture).
+   */
+  timedOut?: true;
 }
 
 /**
  * Capture the PPR shell for one prerendered URL at build time. Retries once
  * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
- * transform graph, mirroring producer A's cold-start retry — same delay).
+ * transform graph, mirroring producer A's cold-start retry — same delay),
+ * unless the attempt ran out of ppr.captureTimeout (`timedOut`).
  */
 export async function captureShellForBuild(
   opts: BuildShellCaptureOptions,
 ): Promise<BuildShellCaptureResult> {
   const first = await attemptBuildCapture(opts);
-  if (first.outcome !== "no-shell") return first;
+  if (first.outcome !== "no-shell" || first.timedOut) return first;
   if (opts.debug) {
     console.log(
       `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
@@ -210,78 +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;
-  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;
-        },
-      });
+      const runCapture = () =>
+        runBuildCaptureFinal({
+          baseCtx,
+          descriptor,
+          env,
+          opts,
+          request,
+          router,
+          url,
+        });
 
-    const routeMiddleware =
-      preview?.routeMiddleware && preview.routeMiddleware.length > 0
-        ? buildRouteMiddlewareEntries(preview.routeMiddleware)
+      const routeMiddleware =
+        preview?.routeMiddleware && preview.routeMiddleware.length > 0
+          ? buildRouteMiddlewareEntries(preview.routeMiddleware)
+          : [];
+      const runRouteMiddleware = () =>
+        runBuildMiddlewareEnvelope(
+          routeMiddleware,
+          request,
+          env,
+          variables,
+          runCapture,
+          middlewareReverse,
+          baseCtx,
+        );
+
+      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) {
@@ -289,7 +303,10 @@ 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 };
   }
   return { outcome };
 }
@@ -299,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 {
@@ -309,7 +330,6 @@ interface BuildCaptureFinalOptions {
   request: Request;
   router: any;
   url: URL;
-  setMismatchedRouteName(routeName: string | undefined): void;
 }
 
 async function runBuildMiddlewareEnvelope<TEnv>(
@@ -369,61 +389,104 @@ async function runBuildCaptureFinal(
   // invoking this when baseCtx._dynamic is set. A loader/handler opting out
   // DURING the capture render is caught by the derivedCtx._dynamic check below.
 
-  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+  const derivation = deriveShellCaptureContext(baseCtx, {
     ttl: opts.ttl,
     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 () => {
-    let match;
-    try {
-      match = await router.match(request, { env });
-    } catch (error) {
-      if (isPlainPathMiss(error, opts.urlPath)) {
-        return "route-mismatch" 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;
       }
-      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.routeName !== opts.routeName) {
+        return { outcome: "route-mismatch", matchedRouteName: match.routeName };
+      }
+      if (match.redirect) return { outcome: "redirect" };
 
-    setRequestContextParams(match.params, match.routeName);
+      setRequestContextParams(match.params, match.routeName);
 
-    const payload = buildFullPayload(
-      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,
-          );
-        }
-      },
-    });
+      // 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 captureOutcome = await captureAndStoreShell(
-      { captureShellHTML: opts.captureShellHTML } as SSRModule,
-      rscStream,
-      freshHandleStore,
-      derivedCtx,
-      descriptor,
-    );
-    return derivedCtx._dynamic ? "dynamic" : captureOutcome;
-  });
+      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,
+        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,
@@ -909,12 +910,13 @@ const loader: RouteHelpers<any, any>["loader"] = (
   // resolved here, at DSL-evaluation time, for the same reason
   // loading({ ssr: false }) is (below) — per-isSSR entry caching makes the
   // flag request-mode-correct with no isSSR threading; see LoaderEntry.
+  // `bake` is the lane, the same on both evaluations.
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
-    ...(optionsGiven?.ssr === false && ctx.isSSR
-      ? { awaitBeforeFlush: true as const }
-      : {}),
+    ...(optionsGiven?.ssr === false && { bake: true as const }),
+    ...(optionsGiven?.ssr === false &&
+      ctx.isSSR && { awaitBeforeFlush: true as const }),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use
@@ -1006,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

@@ -5,7 +5,10 @@
  */
 
 import type { HandlerContext, InternalHandlerContext } from "../types";
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import { getSearchSchema, isRouteRootScoped } from "../route-map-builder.js";
 import { parseSearchParams, serializeSearchParams } from "../search-params.js";
 import {
@@ -18,6 +21,10 @@ import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
 } from "../server/context.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";
@@ -29,6 +36,31 @@ import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 // once at module load instead of per createHandlerContext (per-request) call.
 const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
 
+/** The request context a handler ctx's `theme` getter reads (THEME_DESCRIPTOR). */
+const THEME_REQUEST_CONTEXT = Symbol("rango:theme-request-context");
+
+/**
+ * ctx.theme is the visitor's theme cookie, guarded like cookies() (#971,
+ * 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
+ * replayed console.log args, and an enumerable getter read there refused the
+ * capture of a route that never read the theme. The trade: a spread or
+ * Object.assign copy of the ctx does not carry `theme`. One shared getter
+ * with the request context on a symbol key: a getter closure per ctx gives
+ * every ctx its own property shape (V8 dictionary mode). The guard reads the
+ * ambient context, as cookies() does, and falls back to the ctx's own when
+ * there is none.
+ */
+const THEME_DESCRIPTOR: PropertyDescriptor = {
+  get(this: { [THEME_REQUEST_CONTEXT]?: RequestContext }) {
+    return readGuardedTheme(this[THEME_REQUEST_CONTEXT], "ctx.theme");
+  },
+  enumerable: false,
+  configurable: true,
+};
+
 /**
  * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
  * the handler ctx (createHandlerContext) and the middleware ctx
@@ -263,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,
@@ -279,7 +314,7 @@ export function createHandlerContext<TEnv>(
       // Read-time guard: non-cacheable var inside "use cache" or cache() →
       // throw. Works for both ContextVar tokens and string keys.
       if (isNonCacheable(variables, keyOrVar)) {
-        assertNonCacheableReadAllowed(keyOrVar);
+        assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
       }
       return contextGet(variables, keyOrVar);
     }) as HandlerContext<any, TEnv>["get"],
@@ -295,8 +330,7 @@ export function createHandlerContext<TEnv>(
     use: () => {
       throw new Error("ctx.use() called before loaders were initialized");
     },
-    // Theme support (when enabled via router config)
-    theme: requestContext?.theme,
+    // theme: THEME_DESCRIPTOR, defined after this literal.
     setTheme: requestContext?.setTheme,
     // Location state support (delegates to request context)
     setLocationState(entries) {
@@ -325,6 +359,9 @@ export function createHandlerContext<TEnv>(
     _responseType: responseType,
     _routeName: routeName,
   };
+  (ctx as { [THEME_REQUEST_CONTEXT]?: unknown })[THEME_REQUEST_CONTEXT] =
+    requestContext;
+  Object.defineProperty(ctx, "theme", THEME_DESCRIPTOR);
   // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;