@rangojs/router 0.0.0-experimental.134 → 0.0.0-experimental.135

package/skills/loader/SKILL.md

@@ -671,6 +671,16 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+> **No registration needed — and no worker-entry import.** A fetchable loader
+> does not have to be registered with `loader()` in the route DSL, and it does
+> not have to be imported by any server module. Importing it into the client
+> component that calls `useFetchLoader()` / `load()` is enough. Rango discovers
+> every `createLoader(fn, true)` at build time and registers it for the
+> `_rsc_loader` endpoint, so a loader reachable only through a client component
+> still resolves in production — on both the generated entry and a hand-written
+> worker entry (e.g. a Cloudflare `worker.rsc.tsx`). You do **not** need to
+> force-import the loader in your worker entry to make it resolve.
+
 ### Fetchable Loader with Middleware
 
 Pass an options object instead of `true` to attach per-loader middleware.

package/skills/migrate-react-router/SKILL.md

@@ -740,7 +740,135 @@ function ThemeToggle() {
 
 See `/theme` for full API including system detection and cookie persistence.
 
-## 10. Key Conceptual Differences
+## 10. Cloudflare Workers: streaming, dev tooling, and deploy
+
+This is the part of an RR7-on-Cloudflare migration that the API tables above do
+**not** cover, and it produces symptoms that look like router bugs but aren't.
+RR7 serves a fully-rendered HTML/Turbo-Stream response; Rango serves a **streamed**
+RSC/SSR response. Anything in the request path that was harmless for RR7 but
+**buffers the response** silently kills that stream — the `loading()` /
+`<Suspense>` fallback never shows and the page appears "awaited" (old content
+held until everything resolves).
+
+### 10a. Never buffer the Rango response in a custom worker entry
+
+RR7 Cloudflare entries commonly **rewrite the response body** — `await
+response.text()` / `await response.arrayBuffer()`, `HTMLRewriter`, cookie/URL
+rewriting, hybrid-proxy bridging. That is fine for RR7's complete HTML, but if it
+runs on the **Rango** path it consumes the stream and you lose streaming
+entirely.
+
+Rule: in the worker entry, the Rango response must pass through as a **stream**.
+Buffer only on non-Rango branches (a legacy/SFRA proxy, an error page).
+
+```typescript
+// BAD — buffers the whole RSC stream before returning (no streaming, no fallback)
+const response = await router.fetch(request, { env, ctx });
+const body = await response.text(); // <- drains the stream
+return new Response(rewrite(body), response);
+
+// GOOD — pass the body through as a stream (re-wrap headers only)
+const response = await router.fetch(request, { env, ctx });
+return new Response(response.body, response); // <- streams; safe to add headers
+```
+
+If you keep a legacy proxy (e.g. an SFRA/host fallback) that legitimately buffers
+to rewrite HTML, gate it so it only runs for proxied paths — never for the
+`router.fetch()` result.
+
+Keep the custom entry itself (host/site resolution, sessions, proxy fallback) —
+that's real product logic, not a deviation. Just don't let it touch the stream.
+
+### 10b. Use `vite dev` / `vite preview`, not `wrangler dev`, for local work
+
+The `@cloudflare/vite-plugin` runs **your worker entry** inside miniflare for both
+`vite dev` and `vite preview`, with bindings + `.dev.vars`, and it **streams**.
+`wrangler dev` does **not** stream RSC locally: it gzip-compresses the response by
+buffering the entire body before sending. Measured on a bare streaming Worker
+under `wrangler dev`: `Accept-Encoding: gzip` → first byte at the full delay
+(buffered); `Accept-Encoding: identity` → first byte at ~3ms (streams). The
+deployed Cloudflare edge does **streaming** compression, so this is a
+**local-`wrangler dev`-only artifact** — do not mistake it for a production
+streaming bug (verify the deployed edge with `curl` and watch chunk timing /
+`transfer-encoding: chunked`).
+
+```jsonc
+// package.json — the standard rango-on-Workers shape
+"dev":     "vite",          // streams, bindings, .dev.vars live
+"build":   "vite build",
+"preview": "vite preview",  // runs the built worker in workerd; also streams
+// wrangler is only for: wrangler deploy / wrangler secret
+```
+
+If a workflow truly requires `wrangler dev`, declare `Content-Encoding: identity`
+on streamed responses, gated to local hostnames (so the edge still compresses):
+
+```typescript
+if (
+  isLocalHostname(url.hostname) &&
+  response.body &&
+  !response.headers.has("content-encoding")
+) {
+  const ct = (response.headers.get("content-type") ?? "").toLowerCase();
+  if (ct.includes("text/html") || ct.includes("text/x-component")) {
+    const headers = new Headers(response.headers);
+    headers.set("content-encoding", "identity"); // wrangler skips gzip -> streams
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+}
+```
+
+### 10c. `.dev.vars` loads differently per tool
+
+A frequent "my env vars vanished after migration" symptom — it's the tool, not
+the file:
+
+| Command        | How `.dev.vars` is loaded                                                            |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `wrangler dev` | Loaded natively at runtime (RR7's path — why it "worked before")                     |
+| `vite dev`     | Loaded **live** by the plugin (+ `.dev.vars.<CLOUDFLARE_ENV>` if a named env is set) |
+| `vite preview` | Read from the **build output** `dist/<env>/.dev.vars`, written at `vite build` time  |
+
+So `vite preview` only sees vars that were present when you built — re-run
+`vite build` after editing `.dev.vars`. (`vite dev` is the simplest: live vars +
+streaming, no rebuild.)
+
+### 10d. Build output moves from `build/` to `dist/`
+
+RR7's `react-router build` writes to `build/`; Rango's `vite build` writes to
+`dist/` (`dist/client`, `dist/rsc`, …). The leftover `build/` paths in
+`wrangler.toml` and cleanup scripts must move, or you deploy stale/empty assets:
+
+```toml
+# wrangler.toml — was RR7's react-router build output
+- assets = { directory = "./build/client/", binding = "ASSETS" }
++ assets = { directory = "./dist/client/",  binding = "ASSETS" }
+```
+
+```jsonc
+// package.json — clean the real output dir
+- "cleanup": "rimraf ./build ./public/build"
++ "cleanup": "rimraf ./dist ./build ./public/build"
+```
+
+### 10e. Deploy the built worker, not the source entry
+
+`vite build` emits the **deployable** Worker config at `dist/<env>/wrangler.json`
+with `main: "index.js"` (the bundled worker), `no_bundle: true`, and
+`assets: "../client"`. A plain `wrangler deploy` run from the repo root uses the
+**root** `wrangler.toml`, where `main` points at your **source** entry
+(`app/.../worker.ts`) — and wrangler's bundler cannot resolve Rango's
+`virtual:rsc-router/*` modules, so deploying the source entry fails or ships a
+broken worker. Deploy the build output instead (e.g.
+`wrangler deploy -c dist/<env>/wrangler.json`) or use the plugin's deploy flow.
+RR7's `wrangler deploy` from root worked only because its worker was already
+fully bundled by `react-router build`.
+
+## 11. Key Conceptual Differences
 
 | Concept             | React Router                        | Rango                                  |
 | ------------------- | ----------------------------------- | -------------------------------------- |
@@ -769,3 +897,18 @@ See `/theme` for full API including system detection and cookie persistence.
 11. [ ] Update metadata to use `Meta` handle + `<MetaTags />`
 12. [ ] Replace custom theme provider with `theme: true` in createRouter (see `/theme`)
 13. [ ] Run `npx rango generate src/` to generate route types
+
+**Cloudflare Workers (if migrating an RR7-on-Workers app):**
+
+14. [ ] Audit the custom worker entry — the `router.fetch()` response must pass
+        through as a **stream** (`new Response(response.body, response)`); remove
+        any `.text()`/`.arrayBuffer()`/`HTMLRewriter` buffering from the Rango
+        path (keep it only on legacy/proxy branches). See §10a.
+15. [ ] Switch local dev to `vite dev` / `vite preview` (they stream + load
+        `.dev.vars` + provide bindings); stop using `wrangler dev` for local
+        verification — it gzip-buffers and kills streaming. See §10b.
+16. [ ] Move build output paths from RR7's `build/` to vite's `dist/` in
+        `wrangler.toml` (`assets` → `./dist/client/`) and cleanup scripts. See §10d.
+17. [ ] Fix deploy to use the built config `dist/<env>/wrangler.json`
+        (`no_bundle: true`), not a root `wrangler deploy` against the source
+        worker entry (which can't bundle Rango's virtual modules). See §10e.

package/skills/testing/render-handler.md

@@ -8,20 +8,21 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 
 ### Options — `RenderHandlerOptions`
 
-| Field              | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                              |
-| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `params`           | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
-| `env`              | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
-| `request`          | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
-| `headers`          | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`.                                                                                                                                                                                                                                                                                                                   |
-| `vars`             | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
-| `routeName`        | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
-| `routeMap`         | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
-| `loaders`          | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                       |
-| `clientComponents` | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                   |
-| `stateCookie`      | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the value is `{version}:{timestamp}`, default `"0"`). |
-| `cacheStore`       | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                        |
-| `cacheProfiles`    | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                      |
+| Field                  | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
+| `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
+| `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
+| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`.                                                                                                                                                                                                                                                                                                                   |
+| `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
+| `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
+| `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
+| `loaders`              | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                       |
+| `clientComponents`     | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                   |
+| `stateCookie`          | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the value is `{version}:{timestamp}`, default `"0"`). |
+| `cacheStore`           | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                        |
+| `cacheProfiles`        | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                      |
+| `inActionRevalidation` | `boolean`                                              | Render as if inside a server action's revalidation render (production sets this in `revalidateAfterAction`). A stale `"use cache"` entry whose profile sets `foregroundOnAction: true` then re-executes in the FOREGROUND (fresh result in this render) instead of SWR. Pair with `cacheStore` + `cacheProfiles` to exercise the opt-in.                                             |
 
 ### Context — `HandlerContext` (what your handler receives)
 

package/skills/use-cache/SKILL.md

@@ -63,12 +63,23 @@ createRouter({
     short: { ttl: 60, swr: 120 },
     long: { ttl: 3600, swr: 7200 },
     products: { ttl: 300, swr: 600, tags: ["products"] },
+    // Opt-in: a stale entry re-executes in the foreground during a server
+    // action's revalidation render (fresh action response), instead of SWR.
+    cms: { ttl: 300, swr: 600, foregroundOnAction: true },
   },
 });
 ```
 
 - `"use cache"` (no name) resolves to `default`.
 - `"use cache: short"` resolves to the `short` profile.
+- `foregroundOnAction: true` (default false): a stale entry serves stale +
+  revalidates in the background on a plain navigation (SWR), but re-executes in
+  the FOREGROUND during a server action's revalidation render so the action
+  response reflects a fresh value (only the store write is deferred). Use it for
+  mutation-related cached data; incidental TTL staleness on an ordinary action
+  stays SWR so the action is not turned into a synchronous cache-refresh barrier.
+  For strong read-your-own-writes after a mutation, prefer `updateTag()` (a hard
+  purge, so the action's own re-render is a fresh foreground miss).
 - Unknown profile names throw at runtime, on the first invocation of the cached
   function (the Vite transform does not validate names at build/boot). The error
   is actionable -- it names the missing profile and shows the `createRouter({

package/src/browser/navigation-client.ts

@@ -8,6 +8,7 @@ import type {
 import { NetworkError, ServerRedirect, isNetworkError } from "../errors.js";
 import {
   browserDebugLog,
+  debugLog,
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.js";
@@ -316,7 +317,18 @@ export function createNavigationClient(
       }
 
       try {
+        // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Times how long the RSC
+        // payload ROOT takes to resolve: ~full-stream duration means the root
+        // model is not flushed early (server/runtime buffering, e.g. wrangler
+        // dev gzip); fast means the block, if any, is downstream in render.
+        const vtDebugStart = isBrowserDebugEnabled() ? performance.now() : 0;
         const payload = await payloadPromise;
+        if (isBrowserDebugEnabled()) {
+          debugLog("[VT-DIAG] payloadResolved", {
+            ms: Math.round(performance.now() - vtDebugStart),
+            isPartial: payload.metadata?.isPartial,
+          });
+        }
 
         if (tx) {
           browserDebugLog(tx, "response received", {

package/src/browser/partial-update.ts

@@ -20,7 +20,7 @@ import {
 } from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
-import { debugLog } from "./logging.js";
+import { debugLog, isBrowserDebugEnabled } from "./logging.js";
 import {
   validateRedirectOrigin,
   validateExternalRedirect,
@@ -491,6 +491,21 @@ export function createPartialUpdater(
       debugLog("[partial-update] updating document");
 
       const hasTransition = shouldStartViewTransition(reconciled.segments);
+      // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Reports which reconciled
+      // segment still carries a transition after the server-side when-gate, and
+      // whether the commit will be held in a startTransition. If `withTransition`
+      // lists an ancestor (layout/root) id rather than the gated leaf, an ungated
+      // ancestor transition is holding the subtree (missing loading() fallback).
+      if (isBrowserDebugEnabled()) {
+        debugLog("[VT-DIAG] commit", {
+          mode: mode.type,
+          hasTransition,
+          withTransition: reconciled.segments
+            .filter((s) => s.transition)
+            .map((s) => s.id),
+          all: reconciled.segments.map((s) => s.id),
+        });
+      }
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {

package/src/cache/cache-runtime.ts

@@ -20,7 +20,10 @@ import {
   encodeReply,
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../server/request-context.js";
 import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
@@ -307,7 +310,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       }
     }
 
-    if (cached?.shouldRevalidate) {
+    // foregroundOnAction (opt-in; see CacheProfile.foregroundOnAction): during an
+    // action's revalidation render, a stale entry falls through to the foreground
+    // miss path below instead of SWR. The flag is set by revalidateAfterAction.
+    const foregroundOnActionRevalidation =
+      requestCtx?._inActionRevalidation === true &&
+      profile.foregroundOnAction === true;
+    if (cached?.shouldRevalidate && !foregroundOnActionRevalidation) {
       // Stale hit: return stale value, revalidate in background
       try {
         const result = await serveCached(cached);
@@ -316,8 +325,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         // live response or throw LateHandlePushError on the completed store.
         // Same isolation pattern as route-level background-revalidation.ts.
         runBackground(requestCtx, async () => {
-          // Reuse closure-captured requestCtx instead of calling
-          // getRequestContext() — ALS context may be gone inside waitUntil.
+          // The closure-captured requestCtx is reused for the framework's own
+          // reads (handle store swap, error reporting) AND, below, to
+          // re-establish the request-context ALS around the user fn. ALS context
+          // may be gone inside waitUntil: on workerd a waitUntil task runs
+          // detached from the request's I/O context, so getRequestContext()
+          // inside the cached body would otherwise throw.
           let originalHandleStore:
             | ReturnType<typeof createHandleStore>
             | undefined;
@@ -360,7 +373,15 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
 
           try {
-            const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+            // Re-establish the request-context ALS so a "use cache" body that
+            // reads the ambient getRequestContext() (e.g.
+            // getRequestContext().env.ApiKey) resolves during the background
+            // revalidation instead of throwing "called outside of a request
+            // context". runWithRequestContext sets the store for fn's
+            // synchronous kickoff; its async continuations inherit it.
+            const scoped = runWithRequestContext(requestCtx, () =>
+              runWithCacheTagScope(() => fn.apply(this, args)),
+            );
             const freshResult = await scoped.result;
             bgStopCapture?.();
             // Merge profile/DSL tags with runtime cacheTag() tags, read after

package/src/cache/document-cache.ts

@@ -15,6 +15,7 @@ import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { hasPerClientSignal } from "../browser/cookie-name.js";
 import {
   getRequestContext,
+  runWithRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
@@ -330,7 +331,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
 
         runBackground(requestCtx, async () => {
           try {
-            const fresh = await next();
+            // Re-establish the request-context ALS around the background
+            // re-render: next() re-runs the full handler pipeline, and on
+            // workerd a waitUntil task runs detached from the request's I/O
+            // context, so a handler/component reading getRequestContext() would
+            // otherwise throw. Same fix as the route-level/use-cache background
+            // revalidation paths.
+            const fresh = await runWithRequestContext(requestCtx, () => next());
             const directives = shouldCacheResponse(fresh);
 
             if (directives && fresh.body) {
@@ -348,10 +355,15 @@ export function createDocumentCacheMiddleware<TEnv = any>(
               log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
             }
           } catch (error) {
+            // Pass requestCtx explicitly: this runs in a detached waitUntil task
+            // where the ALS context is gone, so onError only fires if we hand it
+            // the captured context (reportCacheError falls back to _getRequestContext
+            // otherwise, which is null here).
             reportCacheError(
               error,
               "cache-write",
               "[DocumentCache] revalidation",
+              requestCtx,
             );
           }
         });
@@ -401,10 +413,14 @@ export function createDocumentCacheMiddleware<TEnv = any>(
               collectRequestTags(requestCtx),
             );
           } catch (error) {
+            // Detached waitUntil task — pass the captured requestCtx so onError
+            // fires even though the ALS context is gone (see the revalidation
+            // catch above).
             reportCacheError(
               error,
               "cache-write",
               "[DocumentCache] cache write",
+              requestCtx,
             );
           }
         });

package/src/cache/profile-registry.ts

@@ -15,6 +15,21 @@ export interface CacheProfile {
   swr?: number;
   /** Default cache tags for invalidation */
   tags?: string[];
+  /**
+   * When true, a stale entry encountered during a server action's revalidation
+   * render is re-executed in the FOREGROUND (the action response reflects the
+   * refreshed value) instead of being served stale + revalidated in the
+   * background. Only the store write is deferred. Use this for mutation-related
+   * cached data that an action should refresh immediately; ordinary navigations
+   * always keep SWR. Default false: incidental TTL staleness must not turn an
+   * unrelated action into a synchronous cache-refresh barrier — for strong
+   * read-your-own-writes after a mutation, prefer updateTag() (a hard purge, so
+   * the action's own re-render is a fresh foreground miss).
+   *
+   * Honored only by `"use cache"` functions; route-level `cache()` and cached
+   * loaders ignore it (use updateTag() there).
+   */
+  foregroundOnAction?: boolean;
 }
 
 const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };

package/src/cache/read-through-swr.ts

@@ -36,6 +36,14 @@ export interface ReadThroughItemConfig<T> {
   key: string;
   /** Execute the underlying function/loader on miss or revalidation */
   execute: () => Promise<T>;
+  /**
+   * Optional wrapper applied to execute() ONLY on the background
+   * stale-revalidation path (not the foreground miss, where the caller's context
+   * is already established). Used to re-establish the request-context ALS, which
+   * a detached waitUntil task loses on workerd. Defaults to calling execute()
+   * directly.
+   */
+  wrapBackground?: (run: () => Promise<T>) => Promise<T>;
   /** Serialize result for storage. Return null to skip caching. */
   serialize: (data: T) => Promise<string | null>;
   /** Deserialize cached value back to the original type */
@@ -77,6 +85,7 @@ export async function readThroughItem<T>(
     onMiss,
     onCached,
     host,
+    wrapBackground,
   } = config;
 
   // Cache lookup. An infra read failure (getItem) is reported by the store
@@ -106,7 +115,12 @@ export async function readThroughItem<T>(
         host,
         async () => {
           try {
-            const fresh = await execute();
+            // Re-establish the caller's context (request-context ALS) for the
+            // detached background execution; the foreground miss below calls
+            // execute() directly since its context is already established.
+            const fresh = await (wrapBackground
+              ? wrapBackground(execute)
+              : execute());
             const serialized = await serialize(fresh);
             if (serialized !== null) {
               await setItem(key, serialized, storeOptions);

package/src/router/match-middleware/background-revalidation.ts

@@ -105,6 +105,10 @@ import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
 
 /**
  * Creates background revalidation middleware
@@ -183,33 +187,46 @@ export function withBackgroundRevalidation<TEnv>(
         const freshLoaderPromises = new Map<string, Promise<any>>();
         setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
 
-        const freshSegments = await ctx.Store.run(() =>
-          resolveAllSegments(
-            ctx.entries,
-            ctx.routeKey,
-            ctx.matched.params,
-            freshHandlerContext,
-            freshLoaderPromises,
-            { skipLoaders: true },
-          ),
+        // Re-establish the request-context ALS around the re-render. ctx.Store
+        // is a different ALS (DSL build context); on workerd a waitUntil task
+        // runs detached from the request's I/O context, so a handler/component
+        // that reads the ambient getRequestContext() during this background
+        // re-render would otherwise throw "called outside of a request context".
+        const freshSegments = await runWithRequestContext(
+          requestCtx as RequestContext<TEnv>,
+          () =>
+            ctx.Store.run(() =>
+              resolveAllSegments(
+                ctx.entries,
+                ctx.routeKey,
+                ctx.matched.params,
+                freshHandlerContext,
+                freshLoaderPromises,
+                { skipLoaders: true },
+              ),
+            ),
         );
 
         let freshInterceptSegments: ResolvedSegment[] = [];
         if (ctx.interceptResult) {
-          freshInterceptSegments = await ctx.Store.run(() =>
-            resolveInterceptEntry(
-              ctx.interceptResult!.intercept,
-              ctx.interceptResult!.entry,
-              ctx.matched.params,
-              freshHandlerContext,
-              true,
-              undefined,
-              // Skip intercept middleware: this is a post-response background
-              // re-render to refresh a stale cached route. The foreground
-              // already ran the middleware; re-running it would double its side
-              // effects and a short-circuit Response would abort the write.
-              { skipMiddleware: true },
-            ),
+          freshInterceptSegments = await runWithRequestContext(
+            requestCtx as RequestContext<TEnv>,
+            () =>
+              ctx.Store.run(() =>
+                resolveInterceptEntry(
+                  ctx.interceptResult!.intercept,
+                  ctx.interceptResult!.entry,
+                  ctx.matched.params,
+                  freshHandlerContext,
+                  true,
+                  undefined,
+                  // Skip intercept middleware: this is a post-response background
+                  // re-render to refresh a stale cached route. The foreground
+                  // already ran the middleware; re-running it would double its
+                  // side effects and a short-circuit Response would abort the write.
+                  { skipMiddleware: true },
+                ),
+              ),
           );
         }