@rangojs/router 0.0.0-experimental.84 → 0.0.0-experimental.86

package/src/browser/navigation-store.ts

@@ -12,7 +12,10 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import { clearPrefetchCache } from "./prefetch/cache.js";
+import {
+  clearPrefetchCache,
+  clearPrefetchCacheLocal,
+} from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -335,6 +338,18 @@ export function createNavigationStore(
     clearPrefetchCache();
   }
 
+  /**
+   * Drop this tab's navigation + prefetch caches without broadcasting or
+   * rotating shared state. Used when the local session changes in a way that
+   * doesn't affect other tabs — e.g. this tab crosses into a different app
+   * via a cross-router navigation. Other tabs in the old app keep their
+   * caches and their X-Rango-State token.
+   */
+  function clearCacheInternalLocal(): void {
+    historyCache.length = 0;
+    clearPrefetchCacheLocal();
+  }
+
   /**
    * Mark all cache entries as stale (internal - does not broadcast)
    */
@@ -668,6 +683,15 @@ export function createNavigationStore(
       clearCacheAndBroadcast();
     },
 
+    /**
+     * Drop this tab's navigation + prefetch caches locally without
+     * broadcasting or rotating shared state. Intended for cross-app
+     * transitions where the session state diverges for this tab only.
+     */
+    clearHistoryCacheLocal(): void {
+      clearCacheInternalLocal();
+    },
+
     /**
      * Mark cache as stale and broadcast to other tabs
      * Called after server actions - allows SWR pattern for popstate

package/src/browser/partial-update.ts

@@ -41,6 +41,13 @@ export interface PartialUpdateConfig {
   ) => Promise<ReactNode> | ReactNode;
   /** RSC version getter — returns the current version (may change after HMR) */
   getVersion?: () => string | undefined;
+  /**
+   * Replace the active app-shell when a cross-app navigation is detected.
+   * Called before the full-update tree replacement renders, so the new
+   * payload's rootLayout, basename, and version are picked up. Theme,
+   * warmup, and prefetch TTL are not part of the shell — see AppShell.
+   */
+  applyAppShell?: (next: import("./app-shell.js").AppShell) => void;
 }
 
 /**
@@ -110,6 +117,7 @@ export function createPartialUpdater(
     onUpdate,
     renderSegments,
     getVersion = () => undefined,
+    applyAppShell,
   } = config;
 
   /**
@@ -228,7 +236,12 @@ export function createPartialUpdater(
     // Detect app switch: if routerId changed, the navigation crossed into
     // a different router (e.g., via host router path mount). Downgrade
     // partial to full so the entire tree is replaced without reconciliation
-    // against stale segments from the previous app.
+    // against stale segments from the previous app, and replace the app
+    // shell (rootLayout, basename, version) so the target app's document
+    // and router config take effect instead of remaining captured from the
+    // initial load. Theme, warmup, and prefetch TTL are intentionally
+    // document-lifetime (see AppShell doc); a new document navigation
+    // applies them.
     if (payload.metadata?.routerId) {
       const prevRouterId = store.getRouterId?.();
       if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
@@ -236,6 +249,12 @@ export function createPartialUpdater(
           `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
         );
         payload.metadata.isPartial = false;
+        applyAppShell?.({
+          routerId: payload.metadata.routerId,
+          rootLayout: payload.metadata.rootLayout,
+          basename: payload.metadata.basename,
+          version: payload.metadata.version,
+        });
       }
       store.setRouterId?.(payload.metadata.routerId);
     }

package/src/browser/prefetch/cache.ts

@@ -296,3 +296,19 @@ export function clearPrefetchCache(): void {
   abortAllPrefetches();
   invalidateRangoState();
 }
+
+/**
+ * Drop all in-memory prefetch state for this tab without rotating rango-state.
+ *
+ * Use for local-only invalidations (e.g. app switch in this tab) where
+ * other tabs should NOT observe a state rotation. Unlike clearPrefetchCache,
+ * does not call invalidateRangoState, so the shared X-Rango-State token
+ * stays intact and siblings in the old app keep their prefetches.
+ */
+export function clearPrefetchCacheLocal(): void {
+  generation++;
+  inflight.clear();
+  inflightPromises.clear();
+  cache.clear();
+  abortAllPrefetches();
+}

package/src/browser/rango-state.ts

@@ -6,21 +6,37 @@
  * navigation requests. The server responds with `Vary: X-Rango-State`,
  * so the browser HTTP cache keys responses by (URL, X-Rango-State value).
  *
- * Format: `{buildVersion}:{invalidationTimestamp}`
+ * Value format: `{buildVersion}:{invalidationTimestamp}`
  * - Build version changes on deploy, busting all cached prefetches.
  * - Timestamp changes on server action invalidation.
  *
- * localStorage is cross-tab and survives page refresh, so:
- * - One tab's prefetch warms the cache for all tabs.
- * - Invalidation in one tab is picked up by other tabs on next fetch.
+ * Storage key is namespaced per routerId (`rango-state:{routerId}`) so
+ * tabs in different apps on the same origin do not collide. Two tabs in
+ * the same app share a key → one tab's invalidation is picked up by the
+ * other via the `storage` event. A smooth cross-app transition in this
+ * tab rebinds to the target app's key; other tabs still in the old app
+ * keep their own key intact.
+ *
+ * If no routerId is supplied, falls back to a single legacy key for
+ * backward compatibility (single-app deployments unaffected).
  */
 
-const STORAGE_KEY = "rango-state";
+const LEGACY_STORAGE_KEY = "rango-state";
+
+function buildStorageKey(routerId: string | undefined): string {
+  return routerId ? `${LEGACY_STORAGE_KEY}:${routerId}` : LEGACY_STORAGE_KEY;
+}
 
 // Module-level cache avoids hitting localStorage on every getRangoState() call.
 // Initialized from localStorage on first access or by initRangoState().
 let cachedState: string | null = null;
 
+// The localStorage key this tab is currently bound to. Rebinds on
+// initRangoState (document boot) and setRangoStateLocal (smooth app
+// switch). The storage listener filters cross-tab events by this key so
+// events from tabs in a different app are ignored.
+let currentStorageKey: string = LEGACY_STORAGE_KEY;
+
 // Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
 // to localStorage, keeping cachedState fresh without polling.
 let storageListenerAttached = false;
@@ -28,7 +44,10 @@ let storageListenerAttached = false;
 function attachStorageListener(): void {
   if (storageListenerAttached || typeof window === "undefined") return;
   window.addEventListener("storage", (e) => {
-    if (e.key !== STORAGE_KEY) return;
+    // Only react to events for this tab's current app namespace. Events
+    // under other routerId-scoped keys belong to other apps and must not
+    // clobber this tab's state.
+    if (e.key !== currentStorageKey) return;
     cachedState = e.newValue;
   });
   storageListenerAttached = true;
@@ -37,16 +56,22 @@ function attachStorageListener(): void {
 /**
  * Initialize the Rango state key in localStorage.
  * Called once at app startup with the build version from the server.
- * If localStorage already has a key with matching version prefix, keeps it
- * (preserves invalidation state across refresh). Otherwise writes a new key.
+ * The routerId scopes the storage key to this app; in multi-app setups
+ * each app owns its own `rango-state:{routerId}` key and cannot observe
+ * invalidations from sibling apps on the same origin.
+ *
+ * If localStorage already has a matching-version entry under the key,
+ * keeps it (preserves invalidation state across refresh). Otherwise
+ * writes a new value.
  */
-export function initRangoState(version: string): void {
+export function initRangoState(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
   if (typeof window === "undefined") return;
 
   attachStorageListener();
 
   try {
-    const existing = localStorage.getItem(STORAGE_KEY);
+    const existing = localStorage.getItem(currentStorageKey);
     if (existing) {
       const colonIdx = existing.indexOf(":");
       if (colonIdx > 0) {
@@ -59,7 +84,7 @@ export function initRangoState(version: string): void {
     }
     // New version or first load
     const newState = `${version}:${Date.now()}`;
-    localStorage.setItem(STORAGE_KEY, newState);
+    localStorage.setItem(currentStorageKey, newState);
     cachedState = newState;
   } catch {
     // localStorage may be unavailable (private browsing in some browsers)
@@ -77,7 +102,7 @@ export function getRangoState(): string {
   if (typeof window === "undefined") return "0:0";
 
   try {
-    const stored = localStorage.getItem(STORAGE_KEY);
+    const stored = localStorage.getItem(currentStorageKey);
     if (stored) {
       cachedState = stored;
       return stored;
@@ -89,6 +114,21 @@ export function getRangoState(): string {
   return "0:0";
 }
 
+/**
+ * Update the in-memory rango-state to a new version WITHOUT writing
+ * localStorage. Intended for smooth cross-app transitions in this tab only:
+ * subsequent requests from this tab send the new token, but other tabs
+ * still in the previous app do not observe a storage event. Rebinds this
+ * tab's storage key to the target app's namespace (`rango-state:{routerId}`)
+ * so subsequent storage events only reflect the new app. On the next hard
+ * reload, initRangoState reconciles localStorage from the server's
+ * authoritative version.
+ */
+export function setRangoStateLocal(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
+  cachedState = `${version}:${Date.now()}`;
+}
+
 /**
  * Invalidate the Rango state key. Called when server actions mutate data.
  * Updates the timestamp portion while keeping the version prefix.
@@ -105,7 +145,7 @@ export function invalidateRangoState(): void {
   if (typeof window === "undefined") return;
 
   try {
-    localStorage.setItem(STORAGE_KEY, newState);
+    localStorage.setItem(currentStorageKey, newState);
   } catch {
     // Silently handle localStorage errors
   }

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".
@@ -402,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-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/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/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>) => {