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

package/src/router/match-middleware/cache-store.ts

@@ -101,7 +101,10 @@
  *   - Non-GET request (only GET requests are cacheable)
  */
 import type { ResolvedSegment } from "../../types.js";
-import { getRequestContext } from "../../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
@@ -231,34 +234,46 @@ export function withCacheStore<TEnv>(
             setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
 
             const Store = ctx.Store;
-            const freshSegments = await Store.run(() =>
-              resolveAllSegments(
-                ctx.entries,
-                ctx.routeKey,
-                ctx.matched.params,
-                proactiveHandlerContext,
-                proactiveLoaderPromises,
-                { skipLoaders: true },
+            // Re-establish the request-context ALS around the re-render. 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, () =>
+              Store.run(() =>
+                resolveAllSegments(
+                  ctx.entries,
+                  ctx.routeKey,
+                  ctx.matched.params,
+                  proactiveHandlerContext,
+                  proactiveLoaderPromises,
+                  { skipLoaders: true },
+                ),
               ),
             );
 
             let freshInterceptSegments: ResolvedSegment[] = [];
             if (ctx.interceptResult) {
-              freshInterceptSegments = await Store.run(() =>
-                resolveInterceptEntry(
-                  ctx.interceptResult!.intercept,
-                  ctx.interceptResult!.entry,
-                  ctx.matched.params,
-                  proactiveHandlerContext,
-                  true, // belongsToRoute
-                  // No revalidationContext = render fresh
-                  undefined,
-                  // Skip intercept middleware: the foreground already ran it
-                  // before the response was sent. Re-running here (post-response,
-                  // background) would fire side effects twice and a short-circuit
-                  // Response would silently abort this cache write.
-                  { skipMiddleware: true },
-                ),
+              freshInterceptSegments = await runWithRequestContext(
+                requestCtx,
+                () =>
+                  Store.run(() =>
+                    resolveInterceptEntry(
+                      ctx.interceptResult!.intercept,
+                      ctx.interceptResult!.entry,
+                      ctx.matched.params,
+                      proactiveHandlerContext,
+                      true, // belongsToRoute
+                      // No revalidationContext = render fresh
+                      undefined,
+                      // Skip intercept middleware: the foreground already ran it
+                      // before the response was sent. Re-running here (post-
+                      // response, background) would fire side effects twice and a
+                      // short-circuit Response would silently abort this write.
+                      { skipMiddleware: true },
+                    ),
+                  ),
               );
             }
 

package/src/router/segment-resolution/loader-cache.ts

@@ -21,7 +21,10 @@
 import type { LoaderEntry } from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
-import { getRequestContext } from "../../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
@@ -202,11 +205,20 @@ export function resolveLoaderData<TEnv>(
       ctx.params,
     );
 
+    // Capture the request context up front (foreground, ALS present) so the
+    // background stale revalidation can re-establish it. On workerd a waitUntil
+    // task runs detached from the request's I/O context, so a loader body that
+    // reads the ambient getRequestContext() would otherwise throw "called
+    // outside of a request context" and the revalidation would fail silently.
+    // The wrap is applied via wrapBackground (background path only); the
+    // foreground miss runs execute() directly since its context is present.
+    const requestCtxForExecute = getRequestContext();
     return readThroughItem({
       getItem: (k) => store.getItem!(k),
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
       execute: () => runMiss(loaderEntry.loader),
+      wrapBackground: (run) => runWithRequestContext(requestCtxForExecute, run),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },
@@ -214,7 +226,7 @@ export function resolveLoaderData<TEnv>(
       onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
       onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
       onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
-      host: getRequestContext(),
+      host: requestCtxForExecute,
     });
   })();
 

package/src/rsc/progressive-enhancement.ts

@@ -153,6 +153,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         handleStore,
         nonce,
         useActionStateId,
+        true, // an action ran and threw
       );
       if (errorHtml) return errorHtml;
 
@@ -206,6 +207,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         handleStore,
         nonce,
         directActionId,
+        true, // an action ran and threw
       );
       if (errorHtml) return errorHtml;
 
@@ -270,6 +272,14 @@ export async function handleProgressiveEnhancement<TEnv>(
       headers,
     });
 
+    // JS/PE parity: this is an action's revalidation render, so mark it BEFORE
+    // matching — a stale `foregroundOnAction` cache entry must re-execute in the
+    // foreground during the re-render, exactly as the JS path's
+    // revalidateAfterAction does. The transition({ when }) gate fields below are
+    // set post-match (the gate reads them after rendering); foregroundOnAction
+    // reads _inActionRevalidation during the match, so it must be set here.
+    getRequestContext()._inActionRevalidation = true;
+
     const match = await ctx.router.match(renderRequest, { env });
 
     if (match.redirect) {
@@ -383,7 +393,22 @@ async function renderPeErrorBoundary<TEnv>(
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
   actionId?: string | null,
+  // True when an action actually ran and threw (vs a malformed form body, where
+  // no action executed). Drives _inActionRevalidation for JS/PE parity — it must
+  // NOT be inferred from actionId, since a useActionState bound action can run
+  // and throw with no $$id (actionId === undefined) yet still be an action error.
+  actionRan = false,
 ): Promise<Response | null> {
+  // JS/PE parity for an action-triggered error re-render: a stale
+  // `foregroundOnAction` cache entry inside the error boundary must foreground
+  // too, exactly as the JS path (revalidateAfterAction sets this unconditionally
+  // before rendering the error boundary). Set BEFORE matchError (the cached fn
+  // runs during it). Gated on actionRan, NOT actionId — a malformed form body
+  // (actionRan=false) ran no action and must keep SWR.
+  if (actionRan) {
+    getRequestContext()._inActionRevalidation = true;
+  }
+
   let errorResult;
   try {
     errorResult = await ctx.router.matchError(request, { env }, error, "route");

package/src/rsc/server-action.ts

@@ -372,6 +372,12 @@ async function revalidateAfterActionInner<TEnv>(
   reqCtx._gateActionResult = actionContext?.actionResult;
   reqCtx._gateFormData = actionContext?.formData;
 
+  // Mark the rest of this request as an action revalidation render. The "use
+  // cache" runtime reads this to re-execute a stale entry in the foreground
+  // (fresh data in the action response) rather than serving stale + revalidating
+  // in the background. See registerCachedFunction in cache/cache-runtime.ts.
+  reqCtx._inActionRevalidation = true;
+
   // Action threw and a boundary matched: render the (already-matched) error
   // boundary here so it runs inside the route-middleware wrapper, exactly like
   // the success branch below. setRequestContextParams + the payload mirror the

package/src/segment-system.tsx

@@ -10,6 +10,7 @@ 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,
@@ -340,6 +341,21 @@ export async function renderSegments(
         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);
     }
 
@@ -480,7 +496,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;

package/src/server/loader-registry.ts

@@ -67,7 +67,19 @@ export async function getLoaderLazy(
     }
   }
 
-  // Dev fallback: parse ID (format: "src/path/to/file.ts#ExportName") and import
+  // The remaining dev fallback (parse the id as "src/path/file.ts#ExportName"
+  // and import it by path) only makes sense in dev, where ids ARE file paths
+  // and the dev loader manifest is intentionally empty. In production ids are
+  // hashed ("<hash>#ExportName") and every resolvable loader is reached above
+  // via the in-memory registry or the lazy import manifest. The hash is not a
+  // path, so a production fall-through would run import("/<hash>") and throw a
+  // misleading "No such module <hash>" 500 instead of reporting the loader as
+  // unregistered. Return undefined in production so a genuinely unknown loader
+  // is a clean 404 "not found in registry" from handleLoaderFetch.
+  if (process.env.NODE_ENV === "production") {
+    return undefined;
+  }
+
   const hashIndex = id.indexOf("#");
   if (hashIndex !== -1) {
     const filePath = id.slice(0, hashIndex);

package/src/server/request-context.ts

@@ -316,6 +316,16 @@ export interface RequestContext<
   _gateActionResult?: unknown;
   _gateFormData?: FormData;
 
+  /**
+   * @internal True while the post-action revalidation render is running (set by
+   * revalidateAfterAction). The "use cache" runtime reads this to prefer
+   * freshness over a fast stale response during an action: a stale entry
+   * re-executes in the foreground (so the action response reflects the refreshed
+   * value) with only the store write deferred, instead of serving stale and
+   * revalidating in the background. A plain navigation (flag unset) keeps SWR.
+   */
+  _inActionRevalidation?: boolean;
+
   /**
    * @internal Render barrier for experimental `rendered()` API.
    * Resolves when all non-loader segments have settled and handle data
@@ -453,6 +463,7 @@ export type PublicRequestContext<
   | "_gateActionUrl"
   | "_gateActionResult"
   | "_gateFormData"
+  | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"

package/src/testing/render-handler.ts

@@ -116,6 +116,15 @@ export interface RenderHandlerOptions<TEnv = any> {
    * `"use cache: profileName"` resolution once a `cacheStore` is wired.
    */
   cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Render as if inside a server action's revalidation render (production sets
+   * this in revalidateAfterAction). A stale `"use cache"` entry whose profile
+   * opts into `foregroundOnAction` then re-executes in the FOREGROUND (fresh
+   * result in this render) instead of being served stale + revalidated in the
+   * background. Without it, a stale entry keeps SWR. Pair with `cacheStore` +
+   * `cacheProfiles` to exercise the `foregroundOnAction` opt-in.
+   */
+  inActionRevalidation?: boolean;
   /**
    * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
    * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert,
@@ -238,6 +247,11 @@ export async function renderHandler<TEnv = any>(
       opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
   });
 
+  // Simulate an action revalidation render (production sets this in
+  // revalidateAfterAction) so a `foregroundOnAction` cache profile foregrounds a
+  // stale entry. See the foregroundOnAction option doc.
+  if (opts.inActionRevalidation) reqCtx._inActionRevalidation = true;
+
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
   const handlePushes = new Map<Handle<any, any>, unknown[]>();
 

package/src/vite/plugins/version-injector.ts

@@ -2,12 +2,25 @@ import type { Plugin } from "vite";
 import { resolve } from "node:path";
 import * as Vite from "vite";
 import { resolveRscEntryFromConfig } from "../utils/shared-utils.js";
+import { RSC_ENTRY_BOOTSTRAP_IMPORTS } from "./virtual-entries.js";
 
 /**
- * Plugin that auto-injects VERSION and routes-manifest into custom entry.rsc files.
- * If a custom entry.rsc file uses createRSCHandler but doesn't pass version,
- * this transform adds the import and property automatically.
- * Also ensures the routes-manifest virtual module is always imported.
+ * Plugin that auto-injects VERSION, routes-manifest, and loader-manifest into
+ * custom entry.rsc files. If a custom entry.rsc file uses createRSCHandler but
+ * doesn't pass version, this transform adds the import and property
+ * automatically. It also ensures the routes-manifest and loader-manifest
+ * virtual modules are always imported.
+ *
+ * The loader-manifest import is what makes fetchable loaders resolvable on a
+ * custom worker entry. The virtual RSC entry (getVirtualEntryRSC) imports the
+ * loader manifest itself, but a hand-written entry (e.g. a Cloudflare
+ * worker.rsc.tsx) does not — so without this injection, setLoaderImports() is
+ * never bundled, lazyLoaderImports stays null at runtime, and a fetchable
+ * loader that is never imported by the server graph (not registered via
+ * loader(), reachable only through a client component) cannot be found by the
+ * _rsc_loader endpoint in production. Dev still works because it resolves
+ * loaders by parsing their id into a file path; only production relied on the
+ * manifest, hence the production-only failure this fixes.
  * @internal
  */
 export function createVersionInjectorPlugin(
@@ -36,9 +49,11 @@ export function createVersionInjectorPlugin(
         return null;
       }
 
-      const prepend: string[] = [
-        `import "virtual:rsc-router/routes-manifest";`,
-      ];
+      // Same startup bootstrap imports the generated virtual RSC entry uses,
+      // from the single shared list so the two paths cannot drift.
+      const prepend: string[] = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+        (id) => `import "${id}";`,
+      );
 
       let newCode = code;
       const needsVersion =

package/src/vite/plugins/virtual-entries.ts

@@ -51,7 +51,32 @@ export const renderHTML = createSSRHandler({
 });
 `.trim();
 
+/**
+ * Virtual modules an RSC entry must import at startup to register the data the
+ * request handler needs before the first request arrives:
+ *
+ * - routes-manifest: the pre-generated route map so href()/matching work on a
+ *   cold start (full map in build, in-memory no-op in dev).
+ * - loader-manifest: setLoaderImports() for fetchable loaders. Critical for
+ *   serverless/multi-process deployments and for fetchable loaders reachable
+ *   only through a client component — without it those loaders are never
+ *   registered for the _rsc_loader endpoint and fail in production.
+ *
+ * Single source of truth: both the generated virtual RSC entry below and the
+ * custom-entry injector (version-injector) consume this list, so a new
+ * bootstrap manifest cannot be added to one path and forgotten on the other.
+ * That exact drift (loader-manifest present here but missing from the injector)
+ * is what left fetchable loaders unresolved on custom worker entries.
+ */
+export const RSC_ENTRY_BOOTSTRAP_IMPORTS: readonly string[] = [
+  "virtual:rsc-router/routes-manifest",
+  "virtual:rsc-router/loader-manifest",
+];
+
 export function getVirtualEntryRSC(routerPath: string): string {
+  const bootstrapImports = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+    (id) => `import "${id}";`,
+  ).join("\n");
   return `
 import {
   renderToReadableStream,
@@ -65,15 +90,9 @@ import { router } from "${routerPath}";
 import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
 import { VERSION } from "@rangojs/router:version";
 
-// Import loader manifest to ensure all fetchable loaders are registered at startup
-// This is critical for serverless/multi-process deployments where the loader module
-// might not be imported before a GET request arrives
-import "virtual:rsc-router/loader-manifest";
-
-// Import pre-generated route manifest so href() works immediately on cold start.
-// In build mode, this contains the full route map generated at build time.
-// In dev mode, this is a no-op (manifest is populated in-memory by the discovery plugin).
-import "virtual:rsc-router/routes-manifest";
+// Startup bootstrap imports (routes + loader manifests). See
+// RSC_ENTRY_BOOTSTRAP_IMPORTS — the same list the custom-entry injector uses.
+${bootstrapImports}
 
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may