@rangojs/router 0.0.0-experimental.ede38110 → 0.0.0-experimental.f2d1a2f1

package/src/browser/react/Link.tsx

@@ -98,25 +98,30 @@ export interface LinkProps extends Omit<
    */
   prefetch?: PrefetchStrategy;
   /**
-   * Custom prefetch cache key for source-agnostic cache reuse.
-   * When set, prefetch responses are cached independently of the current
-   * page URL, so navigating to the same target from different source pages
-   * reuses the cached prefetch.
+   * Opt-in override for the prefetch cache scope.
    *
-   * - String: static group name (e.g., `"pages"`)
-   * - Function: receives current URL (`window.location.href`), returns a
-   *   normalized source key
+   * The default cache is source-agnostic: one shared entry per target,
+   * keyed on Rango state + target URL. This is correct for routes whose
+   * response shape doesn't depend on where the user navigates from.
+   *
+   * Set `":source"` when this Link's response would legitimately differ
+   * based on the source page — typically when the target route (or one
+   * of its layouts) uses a custom `revalidate()` handler that reads
+   * `currentUrl` / `currentParams`, and the wildcard entry would
+   * therefore serve the wrong diff to a navigation from a different
+   * source.
+   *
+   * Intercept responses are auto-scoped to the source via a server-side
+   * tag, so `":source"` is only needed for custom revalidation logic.
    *
    * @example
    * ```tsx
-   * // Static group — all "pages" links share one cache entry per target
-   * <Link to="/page/3" prefetch="hover" prefetchKey="pages" />
-   *
-   * // Normalize — strip trailing page number from source URL
-   * <Link to="/page/3" prefetch="hover" prefetchKey={(from) => from.replace(/\/\d+$/, '')} />
+   * // Route uses a `revalidate()` that branches on currentUrl — opt in
+   * // so prefetches don't bleed across source pages.
+   * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
    * ```
    */
-  prefetchKey?: string | ((from: string) => string);
+  prefetchKey?: ":source";
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.

package/src/browser/react/NavigationProvider.tsx

@@ -28,6 +28,7 @@ import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
+import type { AppShellRef } from "../app-shell.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -133,15 +134,23 @@ export interface NavigationProviderProps {
   warmupEnabled?: boolean;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Forwarded to context for cache key building.
+   * App version from server payload.
+   * Used only as a fallback when `appShellRef` is not supplied.
    */
   version?: string;
 
   /**
    * URL prefix for all routes (from createRouter({ basename })).
+   * Used only as a fallback when `appShellRef` is not supplied.
    */
   basename?: string;
+
+  /**
+   * Live app-shell ref. When provided, the context's `basename` and `version`
+   * properties become live getters that track app-switch updates without
+   * invalidating the memoized context value.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -175,6 +184,7 @@ export function NavigationProvider({
   warmupEnabled,
   version,
   basename,
+  appShellRef,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -196,18 +206,39 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never change)
-  const contextValue = useMemo<NavigationStoreContextValue>(
-    () => ({
+  // Context value is stable (store, eventController, navigate, refresh never
+  // change). When an appShellRef is supplied, `basename` and `version` are
+  // installed as live getters so app-switch transitions (which update the ref)
+  // propagate to consumers without forcing a tree-wide rerender.
+  const contextValue = useMemo<NavigationStoreContextValue>(() => {
+    if (appShellRef) {
+      const value = {
+        store,
+        eventController,
+        navigate,
+        refresh,
+      } as NavigationStoreContextValue;
+      Object.defineProperty(value, "basename", {
+        configurable: true,
+        enumerable: true,
+        get: () => appShellRef.get().basename,
+      });
+      Object.defineProperty(value, "version", {
+        configurable: true,
+        enumerable: true,
+        get: () => appShellRef.get().version,
+      });
+      return value;
+    }
+    return {
       store,
       eventController,
       navigate,
       refresh,
       version,
       basename,
-    }),
-    [],
-  );
+    };
+  }, []);
 
   // Connection warmup: keep TLS alive after idle periods.
   // After 60s of no user interaction, marks connection as "cold".
@@ -345,8 +376,12 @@ export function NavigationProvider({
         metadata: update.metadata,
       });
 
-      // Update route params
-      eventController.setParams(update.metadata.params ?? {});
+      // Update route params. Only reset when the server actually sends a params
+      // map — an absent `params` field means "no change" (e.g., legacy action
+      // responses that omitted params). Explicit `{}` still clears correctly.
+      if (update.metadata.params !== undefined) {
+        eventController.setParams(update.metadata.params);
+      }
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
@@ -398,7 +433,11 @@ export function NavigationProvider({
   // Build the content tree
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
-  // Wrap with ThemeProvider when theme is enabled
+  // Wrap with ThemeProvider when theme is enabled. The ThemeProvider is
+  // document-lifetime: its config comes from the initial load and does NOT
+  // swap on cross-app transitions, because the ThemeProvider sits above the
+  // segment tree and a smooth (no-reload) app switch cannot safely remount
+  // it. A new theme config only takes effect on a full document load.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>

package/src/browser/react/use-navigation.ts

@@ -53,6 +53,12 @@ export function useNavigation<T>(
   });
   const prevState = useRef(baseValue);
 
+  // Tracks whether the most recent setOptimisticValue call pinned the value
+  // to a non-idle state. Used to decide whether to emit a release update when
+  // returning to idle, so the optimistic store doesn't stay pinned if a
+  // parent transition (e.g. <Link> click) is still pending.
+  const optimisticPinnedRef = useRef(false);
+
   // useOptimistic allows immediate updates during transitions/actions
   const [value, setOptimisticValue] = useOptimistic(baseValue);
 
@@ -78,17 +84,30 @@ export function useNavigation<T>(
       if (!shallowEqual(nextSelected, prevState.current)) {
         prevState.current = nextSelected;
 
-        // Always mirror into the optimistic store inside a transition.
-        // useOptimistic returns the optimistic value while any transition that
-        // includes a setOptimisticValue is pending. Calling it only when
-        // entering "loading" left the optimistic store stuck on the previous
-        // value when going back to "idle" — if a parent transition (e.g., a
-        // <Link> click) was still pending, useOptimistic would keep returning
-        // the stale loading value even after baseValue flipped to idle.
-        // Updating in both directions keeps the optimistic store in sync.
-        startTransition(() => {
-          setOptimisticValue(nextSelected);
-        });
+        // Check if any actions are in progress for optimistic updates
+        const hasInflightActions =
+          ctx.eventController.getInflightActions().size > 0;
+
+        const shouldPin = hasInflightActions || publicState.state !== "idle";
+
+        if (shouldPin) {
+          // Pin the optimistic store so the loading value shows immediately
+          // even if a parent transition (e.g. <Link> click) defers the
+          // urgent setBaseValue commit.
+          startTransition(() => {
+            setOptimisticValue(nextSelected);
+          });
+          optimisticPinnedRef.current = true;
+        } else if (optimisticPinnedRef.current) {
+          // Release a previously-pinned optimistic value. Without this,
+          // useOptimistic keeps returning the stale loading value while
+          // any parent transition is still pending, even after baseValue
+          // flipped to idle.
+          startTransition(() => {
+            setOptimisticValue(nextSelected);
+          });
+          optimisticPinnedRef.current = false;
+        }
 
         // Always update base state so UI reflects current state
         setBaseValue(nextSelected);

package/src/browser/react/use-params.ts

@@ -16,11 +16,21 @@ import { shallowEqual } from "./shallow-equal.js";
  * const params = useParams();
  * // { productId: "123" }
  *
+ * // Annotate the expected shape via a generic
+ * const { productId } = useParams<{ productId: string }>();
+ *
  * // With selector
  * const productId = useParams(p => p.productId);
  * ```
  */
-export function useParams(): Record<string, string>;
+// `T extends object` (not `Record<string, string | undefined>`) so that
+// interface shapes pass the constraint — interfaces lack an implicit
+// index signature and would otherwise be rejected. The generic is a
+// shape annotation, not a runtime check; the body always returns the
+// underlying params map unchanged.
+export function useParams<
+  T extends object = Record<string, string>,
+>(): Readonly<T>;
 export function useParams<T>(
   selector: (params: Record<string, string>) => T,
 ): T;

package/src/browser/react/use-router.ts

@@ -13,6 +13,10 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  * useRouter() do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
+ * Methods read `basename` from the live context on each call so that
+ * cross-app navigation (app-switch) sees the current app's basename
+ * rather than the one captured at mount time.
+ *
  * @example
  * ```tsx
  * const router = useRouter();
@@ -29,7 +33,10 @@ export function useRouter(): RouterInstance {
     throw new Error("useRouter must be used within NavigationProvider");
   }
 
-  // Stable reference: ctx is itself stable (NavigationProvider memoizes with [])
+  // Stable reference: ctx itself is stable, and reads on each method call
+  // pick up live basename values from the context (backed by a live ref
+  // in NavigationProvider), so app-switch transitions are reflected without
+  // recreating this object.
   return useMemo<RouterInstance>(() => {
     /** Prefix a root-relative path with basename if not already prefixed. */
     function withBasename(url: string): string {

package/src/browser/rsc-router.tsx

@@ -28,6 +28,7 @@ import {
   isInterceptSegment,
   splitInterceptSegments,
 } from "./intercept-utils.js";
+import { createAppShellRef } from "./app-shell.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -114,6 +115,13 @@ export interface BrowserAppContext {
   warmupEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
+  /**
+   * Live app-shell ref. Cross-app navigations replace its contents so the
+   * NavigationProvider and renderSegments pick up the target app's
+   * rootLayout, basename, and version without consumer rerenders. Theme,
+   * warmup, and prefetch TTL are document-lifetime (see AppShell).
+   */
+  appShellRef?: import("./app-shell.js").AppShellRef;
 }
 
 // Module-level state for the initialized app
@@ -204,13 +212,23 @@ export async function initBrowserApp(
   // Create composable utilities
   const client = createNavigationClient(deps);
 
-  // Extract rootLayout and version from metadata for browser-side re-renders
-  const rootLayout = initialPayload.metadata?.rootLayout;
+  // Capture the per-router app-shell so cross-app navigations can replace
+  // it atomically. rootLayout, basename, and version live here and are
+  // read through the ref at call time rather than closed over. Theme,
+  // warmup, and prefetch TTL are deliberately excluded — they are
+  // document-lifetime and stay stable across smooth cross-app transitions.
   const version = initialPayload.metadata?.version;
+  const appShellRef = createAppShellRef({
+    routerId: initialPayload.metadata?.routerId,
+    rootLayout: initialPayload.metadata?.rootLayout,
+    basename: initialPayload.metadata?.basename,
+    version,
+  });
 
   // Initialize the localStorage state key for cache invalidation.
-  // Uses the build version so a new deploy automatically busts all cached prefetches.
-  initRangoState(version ?? "0");
+  // The build version busts cached prefetches on deploy; the routerId
+  // namespaces the key so sibling apps on the same origin don't collide.
+  initRangoState(version ?? "0", initialPayload.metadata?.routerId);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.
@@ -220,11 +238,17 @@ export async function initBrowserApp(
     initPrefetchCache(prefetchCacheTTL);
   }
 
-  // Create a bound renderSegments that includes rootLayout
+  // Create a bound renderSegments that reads rootLayout through the shell
+  // ref. On app switch the ref is updated before the tree re-renders, so
+  // the new app's Document (rootLayout) replaces the previous one.
   const renderSegments = (
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
-  ) => baseRenderSegments(segments, { ...options, rootLayout });
+  ) =>
+    baseRenderSegments(segments, {
+      ...options,
+      rootLayout: appShellRef.get().rootLayout,
+    });
 
   // Lazy reference for navigation bridge — the action bridge is created first
   // but may need to trigger SPA navigation for action redirects.
@@ -256,6 +280,7 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version: version,
+    appShellRef,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -416,6 +441,7 @@ export async function initBrowserApp(
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
     version,
+    appShellRef,
   };
   browserAppContext = context;
 
@@ -481,6 +507,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
     initialTheme,
     warmupEnabled,
     version,
+    appShellRef,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -501,6 +528,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       warmupEnabled={warmupEnabled}
       version={version}
       basename={initialPayload.metadata?.basename}
+      appShellRef={appShellRef}
     />
   );
 }

package/src/browser/types.ts

@@ -427,6 +427,12 @@ export interface NavigationStore {
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
+  /**
+   * Clear this tab's nav + prefetch caches without broadcasting or rotating
+   * shared state. Intended for app-switch transitions that affect only this
+   * tab's session.
+   */
+  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -542,6 +548,13 @@ export interface NavigationBridge {
   registerLinkInterception(): () => void;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
   updateVersion(newVersion: string): void;
+  /**
+   * Replace the active app-shell snapshot (rootLayout, basename, version)
+   * atomically. Used on cross-app navigations when the response's routerId
+   * indicates the user entered a different app. Theme, warmup, and prefetch
+   * TTL are document-lifetime and not part of the shell.
+   */
+  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**

package/src/cache/cf/cf-cache-store.ts

@@ -67,13 +67,11 @@ export const MAX_REVALIDATION_INTERVAL = 30;
 // Types
 // ============================================================================
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+// Re-exported from the canonical home so cf-cache-store consumers keep
+// importing `ExecutionContext` from this module without a second interface
+// drifting over time.
+export type { ExecutionContext } from "../../types/request-scope.js";
+import type { ExecutionContext } from "../../types/request-scope.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.

package/src/index.rsc.ts

@@ -172,6 +172,9 @@ export type { PublicRequestContext as RequestContext } from "./server/request-co
 import type { PublicRequestContext } from "./server/request-context.js";
 import type { DefaultEnv } from "./types/global-namespace.js";
 
+// Shared base for every user-facing request context (mirrors index.ts).
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 export const getRequestContext: <
   TEnv = DefaultEnv,
 >() => PublicRequestContext<TEnv> = _getRequestContextInternal;

package/src/index.ts

@@ -264,6 +264,9 @@ export function transition(): never {
 // Request context type (safe for client)
 export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
 
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 // Cookie store types (safe for client)
 export type {
   CookieStore,

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {

package/src/response-utils.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export function isWebSocketUpgradeResponse(response: Response): boolean {
+  return (
+    response.status === 101 ||
+    (response as unknown as { webSocket?: unknown }).webSocket != null
+  );
+}

package/src/reverse.ts

@@ -1,6 +1,7 @@
 import type { ExtractParams } from "./types.js";
 import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
 import { serializeSearchParams } from "./search-params.js";
+import { encodePathSegment } from "./router/url-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -318,7 +319,7 @@ export function createReverse<TRoutes extends Record<string, string>>(
             hadOmittedOptional = true;
             return "";
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Second pass: required params (no trailing ?)
@@ -329,7 +330,7 @@ export function createReverse<TRoutes extends Record<string, string>>(
           if (value === undefined) {
             throw new Error(`Missing param "${key}" for route "${name}"`);
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Clean up slashes only when an optional param was actually omitted,

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

@@ -304,6 +304,15 @@ const cache: RouteHelpers<any, any>["cache"] = (
     return { name: namespace, type: "cache" } as CacheItem;
   }
 
+  // Inside a loader() use() callback, only the direct form — cache()/cache(opts)/
+  // cache("profile") — writes cache config to the loader entry. The wrapper
+  // form creates a structural cache boundary with its own children scope, which
+  // has no effect on the loader and would silently no-op.
+  invariant(
+    !(ctx.parent && (ctx.parent as any).type === "loader"),
+    "cache() wrapper form is not valid inside loader() use(). Use cache({...}) without children to configure the loader's cache.",
+  );
+
   // With children: create a cache entry (like layout with caching semantics)
   const namespace = `${ctx.namespace}.${cacheIndex}`;
   const cacheShortCode = store.getShortCode("cache");
@@ -750,8 +759,12 @@ const loaderFn: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
     revalidate: [] as ShouldRevalidateFn<any, any>[],
   };
 
-  // If use() callback provided, run it to collect revalidation rules and cache config
-  if (use && typeof use === "function") {
+  // Merge handler.use defaults (attached to the loader definition) with explicit use
+  const handlerUseFn = resolveHandlerUse(loaderDef);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "loader");
+
+  // If any use callback is in effect, run it to collect revalidation rules and cache config
+  if (mergedUse) {
     // Temporarily set context for revalidate()/cache() calls to target this loader
     const originalParent = ctx.parent;
     // Create a temporary "parent" with type "loader" so cache() can detect it.
@@ -764,7 +777,7 @@ const loaderFn: RouteHelpers<any, any>["loader"] = (loaderDef, use) => {
     };
     ctx.parent = tempParent as EntryData;
 
-    const result = use()?.flat(3);
+    const result = mergedUse()?.flat(3);
 
     // Copy cache config only if cache() was called during the use() callback.
     // The spread from originalParent may carry an inherited .cache from

package/src/route-definition/resolve-handler-use.ts

@@ -21,6 +21,10 @@ export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
   if (isStaticHandler(handler)) {
     return (handler as any).use;
   }
+  // Loader definitions from createLoader() — branded objects with optional .use
+  if (typeof handler === "object" && (handler as any).__brand === "loader") {
+    return (handler as any).use;
+  }
   // Plain handler function
   if (typeof handler === "function") {
     return (handler as any).use;
@@ -99,6 +103,8 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
     "when",
     "transition",
   ]),
+  // LoaderUseItem — only revalidate + cache can attach to a loader entry
+  loader: new Set(["revalidate", "cache"]),
 };
 
 /**

package/src/router/handler-context.ts

@@ -18,6 +18,8 @@ import { isInsideCacheScope } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
+import { encodePathSegment } from "./url-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -181,7 +183,7 @@ export function createReverseFunction(
             hadOmittedOptional = true;
             return "";
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Second pass: required params (no trailing ?)
@@ -192,7 +194,7 @@ export function createReverseFunction(
           if (value === undefined) {
             throw new Error(`Missing param "${key}" for route "${name}"`);
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Clean up slashes only when an optional param was actually omitted,
@@ -281,8 +283,12 @@ export function createHandlerContext<TEnv>(
     search: searchSchema ? resolvedSearchParams : {},
     pathname,
     url,
-    originalUrl: new URL(request.url),
+    originalUrl: requestContext?.originalUrl ?? new URL(request.url),
     env: bindings,
+    waitUntil: requestContext
+      ? requestContext.waitUntil.bind(requestContext)
+      : fireAndForgetWaitUntil,
+    executionContext: requestContext?.executionContext,
     _variables: variables,
     get: ((keyOrVar: any) => {
       // Read-time guard: non-cacheable var inside cache() → throw.
@@ -387,6 +393,12 @@ export function createPrerenderContext<TEnv>(
           "Configure buildEnv in your rango() plugin options to enable build-time env access.",
       );
     },
+    // Build-time prerender has no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect — these are meant to outlive the live response).
+    // executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
     _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {
@@ -476,6 +488,11 @@ export function createStaticContext<TEnv>(
           "Configure buildEnv in your rango() plugin options to enable build-time env access.",
       );
     },
+    // Static() handlers have no live request. waitUntil is a true no-op
+    // (running fn() here would fire side effects during build, which is
+    // incorrect). executionContext is absent for the same reason.
+    waitUntil: () => {},
+    executionContext: undefined,
     _variables: variables,
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     set: ((keyOrVar: any, value: any) => {

package/src/router/lazy-includes.ts

@@ -1,7 +1,7 @@
 import { registerRouteMap } from "../route-map-builder.js";
 import { extractStaticPrefix } from "./pattern-matching.js";
 import {
-  EntryData,
+  type EntryData,
   RSCRouterContext,
   runWithPrefixes,
   getIsolatedLazyParent,

package/src/router/loader-resolution.ts

@@ -266,7 +266,10 @@ function createLoaderExecutor<TEnv>(
       search: (ctx as any).search,
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env,
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
       get: ((keyOrVar: any) =>
         contextGet(variables, keyOrVar)) as typeof ctx.get,
       use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {