@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/server/request-context.ts

@@ -13,13 +13,43 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { CookieOptions } from "../router/middleware.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type {
+  DefaultEnv,
+  DefaultReverseRouteMap,
+  DefaultRouteName,
+} from "../types/global-namespace.js";
 import type { Handle } from "../handle.js";
-import { createHandleStore, type HandleStore } from "./handle-store.js";
+import {
+  type ContextVar,
+  contextGet,
+  contextSet,
+  isNonCacheable,
+} from "../context-var.js";
+import {
+  createHandleStore,
+  buildHandleSnapshot,
+  type HandleStore,
+  type HandleData,
+} from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track } from "./context.js";
+import { track, type MetricsStore } from "./context.js";
+import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import { THEME_COOKIE } from "../theme/constants.js";
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
+import { isInsideCacheScope } from "./context.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
+import { invariant } from "../errors.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 
 /**
  * Unified request context available via getRequestContext()
@@ -28,46 +58,50 @@ import { THEME_COOKIE } from "../theme/constants.js";
  * Use this when you need access to request data outside of route handlers.
  */
 export interface RequestContext<
-  TEnv = unknown,
+  TEnv = DefaultEnv,
   TParams = Record<string, string>,
-> {
-  /** Platform bindings (Cloudflare env, etc.) */
-  env: TEnv;
-  /** Original HTTP request */
-  request: Request;
-  /** Parsed URL (system params like _rsc* are NOT filtered here) */
-  url: URL;
-  /** URL pathname */
-  pathname: string;
-  /** URL search params (system params like _rsc* are NOT filtered here) */
-  searchParams: URLSearchParams;
-  /** Variables set by middleware (same as ctx.var) */
-  var: Record<string, any>;
+> extends RequestScope<TEnv> {
+  /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+  _variables: Record<string, any>;
   /** Get a variable set by middleware */
-  get: <K extends string>(key: K) => any;
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+    <K extends string>(key: K): any;
+  };
   /** Set a variable (shared with middleware and handlers) */
-  set: <K extends string>(key: K, value: any) => void;
+  set: {
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+    <K extends string>(key: K, value: any, options?: { cache?: boolean }): void;
+  };
   /**
    * Route params (populated after route matching)
    * Initially empty, then set to matched params
    */
   params: TParams;
-  /**
-   * Stub response for setting headers/cookies
-   * Headers set here are merged into the final response
-   */
-  res: Response;
+  /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
+  readonly res: Response;
 
-  /** Get a cookie value from the request */
+  /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
   cookie(name: string): string | undefined;
-  /** Get all cookies from the request */
+  /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
   cookies(): Record<string, string>;
-  /** Set a cookie on the response */
+  /** @internal Set a cookie on the response. Use cookies().set() instead. */
   setCookie(name: string, value: string, options?: CookieOptions): void;
-  /** Delete a cookie */
-  deleteCookie(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+  /** @internal Delete a cookie. Use cookies().delete() instead. */
+  deleteCookie(
+    name: string,
+    options?: Pick<CookieOptions, "domain" | "path">,
+  ): void;
   /** Set a response header */
   header(name: string, value: string): void;
+  /** Set the response status code */
+  setStatus(status: number): void;
+  /** @internal Set status bypassing cache-exec guard (for framework error handling) */
+  _setStatus(status: number): void;
 
   /**
    * Access loader data or push handle data.
@@ -89,10 +123,12 @@ export interface RequestContext<
    * ```
    */
   use: {
-    <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
-    <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): (
-      data: TData | Promise<TData> | (() => Promise<TData>)
-    ) => void;
+    <T, TLoaderParams = any>(
+      loader: LoaderDefinition<T, TLoaderParams>,
+    ): Promise<T>;
+    <TData, TAccumulated = TData[]>(
+      handle: Handle<TData, TAccumulated>,
+    ): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
   };
 
   /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
@@ -104,19 +140,11 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
-  /**
-   * Schedule work to run after the response is sent.
-   * On Cloudflare Workers, uses ctx.waitUntil().
-   * On Node.js, runs as fire-and-forget.
-   *
-   * @example
-   * ```typescript
-   * ctx.waitUntil(async () => {
-   *   await cacheStore.set(key, data, ttl);
-   * });
-   * ```
-   */
-  waitUntil(fn: () => Promise<void>): void;
+  /** @internal Cache profiles for "use cache" profile resolution (per-router) */
+  _cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
 
   /**
    * Register a callback to run when the response is created.
@@ -177,8 +205,176 @@ export interface RequestContext<
 
   /** @internal Theme configuration (null if theme not enabled) */
   _themeConfig?: ResolvedThemeConfig | null;
+
+  /**
+   * Attach location state entries to the current response.
+   *
+   * For partial (SPA) requests, the state is included in the RSC payload
+   * metadata and merged into history.pushState on the client. For redirect
+   * responses, the state travels through the redirect payload so the target
+   * page can read it via useLocationState.
+   *
+   * Multiple calls accumulate entries.
+   *
+   * @example
+   * ```typescript
+   * ctx.setLocationState(Flash({ text: "Item saved!" }));
+   * ```
+   */
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+
+  /** @internal Accumulated location state entries */
+  _locationState?: LocationStateEntry[];
+
+  /**
+   * The matched route name, if the route has an explicit name.
+   * Undefined before route matching or for unnamed routes.
+   * Includes the namespace prefix from include() (e.g., "blog.post").
+   */
+  routeName?: DefaultRouteName;
+
+  /**
+   * Generate URLs from route names.
+   * Uses the global route map. After route matching, scoped (`.name`) resolution
+   * works within the matched include() scope.
+   */
+  reverse: ScopedReverseFunction<
+    Record<string, string>,
+    DefaultReverseRouteMap
+  >;
+
+  /** @internal Route name from route matching, used for scoped reverse resolution */
+  _routeName?: string;
+
+  /** @internal Previous route key (from the navigation source), used for revalidation */
+  _prevRouteKey?: string;
+
+  /**
+   * @internal Render barrier for experimental `rendered()` API.
+   * Resolves when all non-loader segments have settled and handle data
+   * is available. Used by DSL loaders that call `ctx.rendered()`.
+   */
+  _renderBarrier: Promise<void>;
+
+  /**
+   * @internal Resolve the render barrier. Accepts resolved segments, filters
+   * out loaders, and captures non-loader segment IDs as the handle ordering.
+   * Called after segment resolution (fresh) or handle replay (cache/prerender).
+   */
+  _resolveRenderBarrier: (
+    segments: Array<{ type: string; id: string }>,
+  ) => void;
+
+  /**
+   * @internal Segment order at barrier resolution time, used by loader
+   * ctx.use(handle) to collect handle data in correct order.
+   */
+  _renderBarrierSegmentOrder?: string[];
+
+  /**
+   * @internal Set to true when the matched entry tree contains any `loading()`
+   * entries (streaming). Used by rendered() to fail fast.
+   */
+  _treeHasStreaming?: boolean;
+
+  /**
+   * @internal Loader IDs that have called rendered() and are waiting for the
+   * barrier. Used to detect deadlocks when a handler tries to await the same
+   * loader via ctx.use(Loader).
+   */
+  _renderBarrierWaiters?: Set<string>;
+
+  /**
+   * @internal Loader IDs that handlers have started awaiting via ctx.use().
+   * Used for bidirectional deadlock detection: if a loader later calls
+   * rendered() and a handler already awaits it, we can detect the deadlock.
+   */
+  _handlerLoaderDeps?: Set<string>;
+
+  /**
+   * @internal Cached HandleData snapshot built at barrier resolution time.
+   * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
+   */
+  _renderBarrierHandleSnapshot?: HandleData;
+
+  /** @internal Per-request error dedup set for onError reporting */
+  _reportedErrors: WeakSet<object>;
+
+  /**
+   * @internal Report a non-fatal background error through the router's
+   * onError callback. Wired by the RSC handler / router during request
+   * creation. Cache-runtime and other subsystems call this to surface
+   * errors without failing the response.
+   */
+  _reportBackgroundError?: (error: unknown, category: string) => void;
+
+  /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
+  _debugPerformance?: boolean;
+
+  /** @internal Request-scoped performance metrics store */
+  _metricsStore?: MetricsStore;
+
+  /** @internal Router basename for this request (used by redirect()) */
+  _basename?: string;
+
+  /**
+   * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
+   * to avoid a second resolveRoute call. Cleared on HMR invalidation.
+   */
+  _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+   * header. Populated by match/matchPartial only when the debug cache signal
+   * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+   * the response-finalization path (createResponseWithMergedHeaders). Undefined
+   * when the gate is off, so no header is emitted.
+   */
+  _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
+/**
+ * Public view of RequestContext, without internal methods and fields.
+ *
+ * This is the type exported to library consumers. Internal code should
+ * use the full RequestContext interface directly.
+ */
+export type PublicRequestContext<
+  TEnv = DefaultEnv,
+  TParams = Record<string, string>,
+> = Omit<
+  RequestContext<TEnv, TParams>,
+  | "cookie"
+  | "cookies"
+  | "setCookie"
+  | "deleteCookie"
+  | "_handleStore"
+  | "_cacheStore"
+  | "_cacheProfiles"
+  | "_onResponseCallbacks"
+  | "_themeConfig"
+  | "_locationState"
+  | "_routeName"
+  | "_prevRouteKey"
+  | "_reportedErrors"
+  | "_renderBarrier"
+  | "_resolveRenderBarrier"
+  | "_renderBarrierSegmentOrder"
+  | "_treeHasStreaming"
+  | "_renderBarrierWaiters"
+  | "_handlerLoaderDeps"
+  | "_renderBarrierHandleSnapshot"
+  | "_reportBackgroundError"
+  | "_debugPerformance"
+  | "_metricsStore"
+  | "_basename"
+  | "_setStatus"
+  | "_variables"
+  | "_classifiedRoute"
+  | "_cacheSignal"
+  | "res"
+>;
+
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
@@ -188,16 +384,33 @@ const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
  */
 export function runWithRequestContext<TEnv, T>(
   context: RequestContext<TEnv>,
-  fn: () => T
+  fn: () => T,
 ): T {
   return requestContextStorage.run(context, fn);
 }
 
 /**
  * Get the current request context
- * Returns undefined if not running within a request context
+ * Throws if called outside of a request context
+ */
+export function getRequestContext<TEnv = DefaultEnv>(): RequestContext<TEnv> {
+  const ctx = requestContextStorage.getStore() as
+    | RequestContext<TEnv>
+    | undefined;
+  invariant(
+    ctx,
+    "getRequestContext() called outside of a request context. " +
+      "This function must be called from within a route handler, loader, middleware, " +
+      "server action, or server component.",
+  );
+  return ctx;
+}
+
+/**
+ * @internal Get the request context without throwing — for internal code that
+ * may run outside a request context (cache stores, optional handle lookups, etc.)
  */
-export function getRequestContext<TEnv = unknown>():
+export function _getRequestContext<TEnv = DefaultEnv>():
   | RequestContext<TEnv>
   | undefined {
   return requestContextStorage.getStore() as RequestContext<TEnv> | undefined;
@@ -205,38 +418,71 @@ export function getRequestContext<TEnv = unknown>():
 
 /**
  * Update params on the current request context
- * Called after route matching to populate route params
+ * Called after route matching to populate route params and route name
  */
-export function setRequestContextParams(params: Record<string, string>): void {
+export function setRequestContextParams(
+  params: Record<string, string>,
+  routeName?: string,
+): void {
   const ctx = requestContextStorage.getStore();
   if (ctx) {
     ctx.params = params;
+    if (routeName !== undefined) {
+      ctx._routeName = routeName;
+      ctx.routeName = (
+        routeName && !isAutoGeneratedRouteName(routeName)
+          ? routeName
+          : undefined
+      ) as DefaultRouteName | undefined;
+    }
+    // Update reverse with scoped resolution now that route is known
+    ctx.reverse = createReverseFunction(
+      getGlobalRouteMap(),
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    );
   }
 }
 
 /**
- * Get the current request context, throwing if not available
- * Use this when context is required (e.g., in loader actions)
+ * Store the previous route key on the request context.
+ * Called during partial-match context creation to make the navigation source
+ * route key available for revalidation and intercept evaluation.
+ * @internal
  */
-export function requireRequestContext<TEnv = unknown>(): RequestContext<TEnv> {
-  const ctx = getRequestContext<TEnv>();
-  if (!ctx) {
-    throw new Error(
-      "Request context not available. This function must be called from within a server action " +
-        "executed through the RSC handler."
-    );
+export function setRequestContextPrevRouteKey(
+  prevRouteKey: string | undefined,
+): void {
+  const ctx = requestContextStorage.getStore();
+  if (ctx && prevRouteKey !== undefined) {
+    ctx._prevRouteKey = prevRouteKey;
   }
-  return ctx;
 }
 
 /**
- * Cloudflare Workers ExecutionContext (subset we need)
+ * Get accumulated location state entries from the current request context.
+ * Returns undefined if no state has been set.
+ *
+ * @internal Used by the RSC handler to include state in payload metadata.
  */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
+export function getLocationState(): LocationStateEntry[] | undefined {
+  const ctx = getRequestContext();
+  return ctx?._locationState;
 }
 
+/**
+ * Get the current request context, throwing if not available
+ * @deprecated Use getRequestContext() directly — it now throws if outside context
+ */
+export function requireRequestContext<
+  TEnv = DefaultEnv,
+>(): RequestContext<TEnv> {
+  return getRequestContext<TEnv>();
+}
+
+export type { ExecutionContext };
+
 /**
  * Options for creating a request context
  */
@@ -245,8 +491,15 @@ export interface CreateRequestContextOptions<TEnv> {
   request: Request;
   url: URL;
   variables: Record<string, any>;
+  /** Optional initial response stub headers/status to seed effective cookie reads */
+  initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /** Optional cache profiles for "use cache" resolution (per-router) */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
   /** Optional Cloudflare execution context for waitUntil support */
   executionContext?: ExecutionContext;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
@@ -262,20 +515,37 @@ export interface CreateRequestContextOptions<TEnv> {
  * - Passed to handlers as ctx
  */
 export function createRequestContext<TEnv>(
-  options: CreateRequestContextOptions<TEnv>
+  options: CreateRequestContextOptions<TEnv>,
 ): RequestContext<TEnv> {
-  const { env, request, url, variables, cacheStore, executionContext, themeConfig } = options;
+  const {
+    env,
+    request,
+    url,
+    variables,
+    initialResponse,
+    cacheStore,
+    cacheProfiles,
+    executionContext,
+    themeConfig,
+  } = options;
   const cookieHeader = request.headers.get("Cookie");
   let parsedCookies: Record<string, string> | null = null;
 
-  // Create stub response for collecting headers/cookies
-  const stubResponse = new Response(null, { status: 200 });
+  // Create stub response for collecting headers/cookies.
+  // All cookie/header mutations go here; cookie reads derive from it.
+  let stubResponse = initialResponse
+    ? new Response(null, {
+        status: initialResponse.status,
+        statusText: initialResponse.statusText,
+        headers: new Headers(initialResponse.headers),
+      })
+    : new Response(null, { status: 200 });
 
   // Create handle store and loader memoization for this request
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
 
-  // Lazy parse cookies
+  // Lazy parse cookies from the original Cookie header
   const getParsedCookies = (): Record<string, string> => {
     if (!parsedCookies) {
       parsedCookies = parseCookiesFromHeader(cookieHeader);
@@ -283,11 +553,47 @@ export function createRequestContext<TEnv>(
     return parsedCookies;
   };
 
+  // Cached response cookie mutations — invalidated on setCookie/deleteCookie/setTheme
+  let responseCookieCache: Map<string, string | null> | null = null;
+  const getResponseCookies = (): Map<string, string | null> => {
+    if (!responseCookieCache) {
+      responseCookieCache = parseResponseCookies(stubResponse);
+    }
+    return responseCookieCache;
+  };
+  const invalidateResponseCookieCache = () => {
+    responseCookieCache = null;
+  };
+
+  // Guard: throw if a response-level side effect is called inside a cache() scope.
+  // Uses ALS to detect the scope (set during segment resolution).
+  function assertNotInsideCacheScopeALS(methodName: string): void {
+    if (isInsideCacheScope()) {
+      throw new Error(
+        `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+          `On cache hit the handler is skipped, so this side effect would be lost. ` +
+          `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+      );
+    }
+  }
+
+  // Effective cookie read: response stub Set-Cookie wins, then original header.
+  // The stub IS the source of truth for same-request mutations.
+  const effectiveCookie = (name: string): string | undefined => {
+    const mutations = getResponseCookies();
+    if (mutations.has(name)) {
+      const v = mutations.get(name);
+      return v === null ? undefined : v;
+    }
+    return getParsedCookies()[name];
+  };
+
   // Theme helpers (only used when themeConfig is provided)
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
-    const stored = getParsedCookies()[themeConfig.storageKey];
+    // Use overlay-aware read so setTheme() in the same request is reflected
+    const stored = effectiveCookie(themeConfig.storageKey);
     if (stored) {
       // Validate stored value
       if (stored === "system" && themeConfig.enableSystem) {
@@ -305,65 +611,129 @@ export function createRequestContext<TEnv>(
 
     // Validate theme value
     if (theme !== "system" && !themeConfig.themes.includes(theme)) {
-      console.warn(`[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`);
+      console.warn(
+        `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
+      );
       return;
     }
 
-    // Set cookie
+    // Write to stub — effectiveCookie() will pick it up on next read
     stubResponse.headers.append(
       "Set-Cookie",
       serializeCookieValue(themeConfig.storageKey, theme, {
         path: THEME_COOKIE.path,
         maxAge: THEME_COOKIE.maxAge,
         sameSite: THEME_COOKIE.sameSite,
-      })
+      }),
     );
+    invalidateResponseCookieCache();
   };
 
+  // Strip internal _rsc* params so userland sees a clean URL.
+  const cleanUrl = stripInternalParams(url);
+
   // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
-    url,
+    url: cleanUrl,
+    originalUrl: new URL(request.url),
     pathname: url.pathname,
-    searchParams: url.searchParams,
-    var: variables,
-    get: <K extends string>(key: K) => variables[key],
-    set: <K extends string>(key: K, value: any) => {
-      variables[key] = value;
-    },
+    searchParams: cleanUrl.searchParams,
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as RequestContext<TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: any) => {
+      assertNotInsideCacheExec(ctx, "set");
+      contextSet(variables, keyOrVar, value, options);
+    }) as RequestContext<TEnv>["set"],
     params: {} as Record<string, string>,
-    res: stubResponse,
+
+    get res(): Response {
+      return stubResponse;
+    },
+    set res(_: Response) {
+      throw new Error(
+        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
+      );
+    },
 
     cookie(name: string): string | undefined {
-      return getParsedCookies()[name];
+      return effectiveCookie(name);
     },
 
     cookies(): Record<string, string> {
-      return { ...getParsedCookies() };
+      const parsed = getParsedCookies();
+      const mutations = getResponseCookies();
+      if (mutations.size === 0) return { ...parsed };
+      // Build result without delete (avoids V8 dictionary-mode de-opt)
+      const deleted = new Set<string>();
+      for (const [k, v] of mutations) {
+        if (v === null) deleted.add(k);
+      }
+      const result: Record<string, string> = {};
+      for (const key of Object.keys(parsed)) {
+        if (!deleted.has(key)) result[key] = parsed[key];
+      }
+      for (const [k, v] of mutations) {
+        if (v !== null) result[k] = v;
+      }
+      return result;
     },
 
     setCookie(name: string, value: string, options?: CookieOptions): void {
+      assertNotInsideCacheExec(ctx, "setCookie");
+      assertNotInsideCacheScopeALS("setCookie");
       stubResponse.headers.append(
         "Set-Cookie",
-        serializeCookieValue(name, value, options)
+        serializeCookieValue(name, value, options),
       );
+      invalidateResponseCookieCache();
     },
 
     deleteCookie(
       name: string,
-      options?: Pick<CookieOptions, "domain" | "path">
+      options?: Pick<CookieOptions, "domain" | "path">,
     ): void {
+      assertNotInsideCacheExec(ctx, "deleteCookie");
+      assertNotInsideCacheScopeALS("deleteCookie");
       stubResponse.headers.append(
         "Set-Cookie",
-        serializeCookieValue(name, "", { ...options, maxAge: 0 })
+        serializeCookieValue(name, "", { ...options, maxAge: 0 }),
       );
+      invalidateResponseCookieCache();
     },
 
     header(name: string, value: string): void {
+      assertNotInsideCacheExec(ctx, "header");
+      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
+    setStatus(status: number): void {
+      assertNotInsideCacheExec(ctx, "setStatus");
+      assertNotInsideCacheScopeALS("setStatus");
+      stubResponse = new Response(null, {
+        status,
+        headers: stubResponse.headers,
+      });
+    },
+
+    _setStatus(status: number): void {
+      stubResponse = new Response(null, {
+        status,
+        headers: stubResponse.headers,
+      });
+    },
+
     // Placeholder - will be replaced below
     use: null as any,
 
@@ -371,29 +741,102 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        // Cloudflare Workers: use native waitUntil
         executionContext.waitUntil(fn());
       } else {
-        // Node.js / dev: fire-and-forget with error logging
-        fn().catch((err) => console.error("[waitUntil] Background task failed:", err));
+        fireAndForgetWaitUntil(fn);
       }
     },
 
+    executionContext,
+
     _onResponseCallbacks: [],
 
     onResponse(callback: (response: Response) => Response): void {
+      assertNotInsideCacheExec(ctx, "onResponse");
+      assertNotInsideCacheScopeALS("onResponse");
       this._onResponseCallbacks.push(callback);
     },
 
     // Theme properties (only set when themeConfig is provided)
-    theme: themeConfig ? getTheme() : undefined,
-    setTheme: themeConfig ? setTheme : undefined,
+    get theme() {
+      return themeConfig ? getTheme() : undefined;
+    },
+    setTheme: themeConfig
+      ? (theme: Theme) => {
+          assertNotInsideCacheExec(ctx, "setTheme");
+          setTheme(theme);
+        }
+      : undefined,
     _themeConfig: themeConfig,
+
+    setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void {
+      assertNotInsideCacheExec(ctx, "setLocationState");
+      const arr = Array.isArray(entries) ? entries : [entries];
+      this._locationState = this._locationState
+        ? [...this._locationState, ...arr]
+        : arr;
+    },
+    _locationState: undefined,
+
+    _reportedErrors: new WeakSet<object>(),
+    _metricsStore: undefined,
+
+    // Render barrier: deferred promise resolved after non-loader segments settle.
+    _renderBarrier: null as any, // set below
+    _resolveRenderBarrier: null as any, // set below
+    _renderBarrierSegmentOrder: undefined,
+
+    reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
+  // Lazy render barrier: only allocate the Promise when a loader actually
+  // calls rendered(). Requests that don't use rendered() pay zero cost.
+  let barrierResolved = false;
+  let resolveBarrier: (() => void) | undefined;
+  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._resolveRenderBarrier = (
+    segments: Array<{ type: string; id: string }>,
+  ) => {
+    if (barrierResolved) return;
+    barrierResolved = true;
+    const segOrder = segments
+      .filter((s) => s.type !== "loader")
+      .map((s) => s.id);
+    ctx._renderBarrierSegmentOrder = segOrder;
+    // Build and cache handle snapshot so loader ctx.use(handle) calls
+    // don't rebuild it on every invocation.
+    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+      handleStore,
+      segOrder,
+    );
+    ctx._renderBarrierWaiters = undefined;
+    ctx._handlerLoaderDeps = undefined;
+    if (resolveBarrier) resolveBarrier();
+  };
+  Object.defineProperty(ctx, "_renderBarrier", {
+    get() {
+      // Barrier already resolved (cache/prerender hit) or first lazy access.
+      // Either way, replace the getter with a concrete value to avoid
+      // repeated Promise.resolve() allocations on subsequent reads.
+      const p = barrierResolved
+        ? Promise.resolve()
+        : new Promise<void>((resolve) => {
+            resolveBarrier = resolve;
+          });
+      Object.defineProperty(ctx, "_renderBarrier", {
+        value: p,
+        writable: false,
+        configurable: false,
+      });
+      return p;
+    },
+    configurable: true,
+  });
+
   // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
@@ -401,14 +844,53 @@ export function createRequestContext<TEnv>(
     getContext: () => ctx,
   });
 
+  // Brand with taint symbol so "use cache" excludes ctx from cache keys
+  (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }
 
+/**
+ * Parse Set-Cookie headers from a response into effective cookie state.
+ * Returns a map of cookie name -> value (string) or name -> null (deleted).
+ * Last-write-wins: later Set-Cookie entries for the same name overwrite earlier ones.
+ * Max-Age=0 is treated as a delete.
+ */
+const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
+
+function parseResponseCookies(response: Response): Map<string, string | null> {
+  const result = new Map<string, string | null>();
+  const setCookies = response.headers.getSetCookie();
+
+  for (const header of setCookies) {
+    // First segment before ';' is the name=value pair
+    const semiIdx = header.indexOf(";");
+    const pair = semiIdx === -1 ? header : header.substring(0, semiIdx);
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx === -1) continue;
+
+    let name: string;
+    let value: string;
+    try {
+      name = decodeURIComponent(pair.substring(0, eqIdx).trim());
+      value = decodeURIComponent(pair.substring(eqIdx + 1).trim());
+    } catch {
+      // Malformed encoding — skip this entry
+      continue;
+    }
+
+    // Max-Age=0 means the cookie is being deleted
+    const isDeleted = MAX_AGE_ZERO_RE.test(header);
+    result.set(name, isDeleted ? null : value);
+  }
+
+  return result;
+}
+
 /**
  * Parse cookies from Cookie header
  */
 function parseCookiesFromHeader(
-  cookieHeader: string | null
+  cookieHeader: string | null,
 ): Record<string, string> {
   if (!cookieHeader) return {};
 
@@ -418,7 +900,13 @@ function parseCookiesFromHeader(
   for (const pair of pairs) {
     const [name, ...rest] = pair.trim().split("=");
     if (name) {
-      cookies[name] = decodeURIComponent(rest.join("="));
+      const raw = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(raw);
+      } catch {
+        // Malformed percent-encoded value (e.g. %zz, %2) - fall back to raw value
+        cookies[name] = raw;
+      }
     }
   }
 
@@ -431,7 +919,7 @@ function parseCookiesFromHeader(
 function serializeCookieValue(
   name: string,
   value: string,
-  options: CookieOptions = {}
+  options: CookieOptions = {},
 ): string {
   let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
 
@@ -463,7 +951,7 @@ export interface CreateUseFunctionOptions<TEnv> {
  * - For handles: returns a push function to add handle data
  */
 export function createUseFunction<TEnv>(
-  options: CreateUseFunctionOptions<TEnv>
+  options: CreateUseFunctionOptions<TEnv>,
 ): RequestContext["use"] {
   const { handleStore, loaderPromises, getContext } = options;
 
@@ -477,16 +965,19 @@ export function createUseFunction<TEnv>(
       if (!segmentId) {
         throw new Error(
           `Handle "${handle.$$id}" used outside of handler context. ` +
-            `Handles must be used within route/layout handlers.`
+            `Handles must be used within route/layout handlers.`,
         );
       }
 
       // Return a push function bound to this handle and segment
-      return (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+      return (
+        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
+      ) => {
         // If it's a function, call it immediately to get the promise
-        const valueOrPromise = typeof dataOrFn === "function"
-          ? (dataOrFn as () => Promise<unknown>)()
-          : dataOrFn;
+        const valueOrPromise =
+          typeof dataOrFn === "function"
+            ? (dataOrFn as () => Promise<unknown>)()
+            : dataOrFn;
 
         // Push directly - promises will be serialized by RSC and streamed
         handleStore.push(handle.$$id, segmentId, valueOrPromise);
@@ -504,8 +995,6 @@ export function createUseFunction<TEnv>(
     // Get loader function - either from loader object or fetchable registry
     let loaderFn = loader.fn;
     if (!loaderFn) {
-      // Lazy import to avoid circular dependency
-      const { getFetchableLoader } = require("../loader.rsc.js");
       const fetchable = getFetchableLoader(loader.$$id);
       if (fetchable) {
         loaderFn = fetchable.fn;
@@ -514,7 +1003,7 @@ export function createUseFunction<TEnv>(
 
     if (!loaderFn) {
       throw new Error(
-        `Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`
+        `Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`,
       );
     }
 
@@ -523,25 +1012,40 @@ export function createUseFunction<TEnv>(
     // Create loader context with recursive use() support
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
+      routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
+      search: (ctx as any).search ?? {},
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env as any,
-      var: ctx.var as any,
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
       get: ctx.get as any,
-      use: <TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>
+      use: (<TDep, TDepParams = any>(
+        dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
         // Recursive call - will start dep loader if not already started
         return ctx.use(dep);
-      },
+      }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
+      reverse: createReverseFunction(
+        getGlobalRouteMap(),
+        ctx._routeName,
+        ctx.params as Record<string, string>,
+        ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
+      ),
+      rendered: () => {
+        throw new Error(
+          `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
+            `It cannot be used from request-context loaders or server actions.`,
+        );
+      },
     };
 
-    // Start loader execution with tracking
-    const doneLoader = track(`loader:${loader.$$id}`);
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
       doneLoader();
     });