@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

package/src/types/handler-context.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { Handle } from "../handle.js";
+import type { HandlePush } from "../defer.js";
 import type { ContextVar } from "../context-var.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { Theme } from "../theme/types.js";
@@ -19,6 +20,8 @@ import type {
   ResolvedRouteMap,
 } from "./route-config.js";
 import type { LoaderDefinition } from "./loader-types.js";
+import type { UseItems, HandlerUseItem } from "../route-types.js";
+import type { RequestScope } from "./request-scope.js";
 
 // Re-export MiddlewareFn for internal/advanced use
 export type { MiddlewareFn } from "../router/middleware.js";
@@ -41,7 +44,7 @@ export type { MiddlewareFn } from "../router/middleware.js";
  */
 export type ScopedRouteMap<
   TPrefix extends string,
-  TMap = RSCRouter.GeneratedRouteMap,
+  TMap = Rango.GeneratedRouteMap,
 > = {
   [K in keyof TMap as K extends `${TPrefix}.${infer Rest}`
     ? Rest
@@ -105,14 +108,6 @@ type StrictLocalParamsWithExtras<TEntry> =
     ? Record<string, string>
     : ExtractParamsFromEntry<TEntry, {}> & Record<string, string>;
 
-// HandlerContext.reverse is the only reverse surface with runtime param autofill
-// from the current matched request. Middleware/loaders/request context do not
-// have the same local-route guarantees, so they keep plain ScopedReverseFunction.
-//
-// When a handler has an explicit local route map, enforce that local route
-// params declared by that map are present while still allowing extra mount
-// params to be passed through. Global names remain autofill-friendly because
-// parent include() params are often unknown at the module definition site.
 type StrictLocalAutofillGlobalReverseFunction<TLocalRoutes, TGlobalRoutes> =
   ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
     <TName extends keyof TGlobalRoutes & string>(
@@ -135,7 +130,7 @@ export type Handler<
     | Record<string, any> = {},
   TRouteMap extends {} = DefaultHandlerRouteMap,
   TEnv = DefaultEnv,
-> = (
+> = ((
   ctx: HandlerContext<
     T extends `.${infer Local}`
       ? Local extends keyof TRouteMap
@@ -160,7 +155,10 @@ export type Handler<
       : ExtractSearchFromEntry<DefaultHandlerRouteMap, T>,
     TRouteMap extends DefaultHandlerRouteMap ? never : TRouteMap
   >,
-) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+) => ReactNode | Promise<ReactNode> | Response | Promise<Response>) & {
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
+};
 
 /**
  * Context passed to handlers (Hono-inspired type-safe context)
@@ -170,7 +168,7 @@ export type Handler<
  * - Cleaned route URL (`url`, `searchParams`, `pathname` — no `_rsc*` params)
  * - Original request (`request` — raw transport URL, headers, method, body)
  * - Platform bindings (env.DB, env.KV, env.SECRETS)
- * - Middleware variables (var.user, var.permissions)
+ * - Middleware variables (`get("user")`, `get("permissions")`)
  * - Getter/setter for variables (get('user'), set('user', ...))
  *
  * @example
@@ -178,8 +176,7 @@ export type Handler<
  * const handler = (ctx: HandlerContext<{ slug: string }, AppEnv>) => {
  *   ctx.params.slug        // Route param (string)
  *   ctx.env.DB             // Binding (D1Database)
- *   ctx.var.user           // Variable (User | undefined)
- *   ctx.get('user')        // Alternative getter
+ *   ctx.get('user')        // Variable (User | undefined)
  *   ctx.set('user', {...}) // Setter
  *   ctx.url                // Clean URL (no _rsc* params)
  *   ctx.searchParams       // Clean params (no _rsc* params)
@@ -192,7 +189,7 @@ export type HandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
   TRouteMap = never,
-> = {
+> = RequestScope<TEnv> & {
   /**
    * Route parameters extracted from the URL pattern.
    * Type-safe when using Handler<"/path/:param"> or Handler<{ param: string }>.
@@ -207,51 +204,19 @@ export type HandlerContext<
    */
   build: boolean;
   /**
-   * The original incoming Request object (transport URL intact).
-   * Use `ctx.url` / `ctx.searchParams` for application logic — those have
-   * internal `_rsc*` params stripped. `ctx.request` preserves the raw URL
-   * for cases where you need original headers, method, or body.
+   * True when running in Vite dev mode, false during production build or
+   * live request rendering. Use this to branch on runtime mode without
+   * changing build semantics (e.g., skip expensive operations in dev).
    */
-  request: Request;
-  /**
-   * Query parameters from the URL (system params like `_rsc*` are filtered).
-   * Always a standard URLSearchParams instance.
-   */
-  searchParams: URLSearchParams;
+  dev: boolean;
   /**
    * Typed search parameters parsed from URL query string via the route's
    * search schema. Empty object when no schema is defined.
    */
   search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
-  /**
-   * The pathname portion of the request URL.
-   */
-  pathname: string;
-  /**
-   * The full URL object (with internal `_rsc*` params stripped).
-   * Use this for application logic — routing, link generation, display.
-   */
-  url: URL;
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params. Use `ctx.url` for application
-   * logic — this is only needed for advanced cases like debugging
-   * or custom cache keying.
-   */
-  originalUrl: URL;
-  /**
-   * Platform bindings (DB, KV, secrets, etc.).
-   * Access resources like `ctx.env.DB`, `ctx.env.KV`.
-   */
-  env: TEnv;
-  /**
-   * Middleware-injected variables.
-   * Access values like `ctx.var.user`, `ctx.var.permissions`.
-   */
-  var: DefaultVars;
   /**
    * Type-safe getter for middleware variables.
-   * Alternative to `ctx.var.key` with better autocomplete.
+   * Preferred way to read middleware-injected variables.
    *
    * @example
    * ```typescript
@@ -310,6 +275,8 @@ export type HandlerContext<
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
    * Push accepts: direct value, Promise, or async callback (executed immediately).
+   * Or call `.defer()` to reserve the slot now and resolve it later (e.g. from a
+   * deep async component), with a timeout safety net — see {@link HandlePush}.
    *
    * @example
    * ```typescript
@@ -343,6 +310,13 @@ export type HandlerContext<
    *   });
    *   return <ProductPage />;
    * });
+   *
+   * // Handle usage - deferred (reserve the slot now, resolve from a deep component)
+   * route("product", (ctx) => {
+   *   const resolve = ctx.use(Breadcrumbs).defer({ timeoutMs: 5000, else: null });
+   *   loadCrumb(ctx.params.id).then(resolve); // resolver is push-equal
+   *   return <ProductPage />;                 // auto-resolves to `else` on timeout
+   * });
    * ```
    */
   use: {
@@ -351,7 +325,7 @@ export type HandlerContext<
     ): Promise<T>;
     <TData, TAccumulated = TData[]>(
       handle: Handle<TData, TAccumulated>,
-    ): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+    ): HandlePush<TData>;
   };
   /**
    * Current theme (from cookie or default).
@@ -448,6 +422,8 @@ export type InternalHandlerContext<
 > = HandlerContext<TParams, TEnv, TSearch> & {
   /** @internal Stub response for collecting headers/cookies. */
   res: Response;
+  /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+  _variables: Record<string, any>;
   /** Prerender-only control flow helper, attached when the runtime context supports it. */
   passthrough?: () => unknown;
   /** Current segment ID for handle data attribution. */
@@ -456,6 +432,18 @@ export type InternalHandlerContext<
   _responseType?: string;
   /** Route name for cache key scoping (prevents cross-route collisions). */
   _routeName?: string;
+  /**
+   * @internal Loader-cache override table: loaderId -> memoized data promise.
+   * A single stable ctx.use interceptor consults this instead of chaining one
+   * wrapper per cached loader (avoids O(N) dispatch). See loader-cache.ts.
+   */
+  _loaderCacheOverrides?: Map<string, Promise<any>>;
+  /**
+   * @internal ctx.use captured before the loader-cache interceptor was installed.
+   * The cache-miss execute runs the loader through this, bypassing the override
+   * table (so a loader cannot await its own in-flight memoized promise).
+   */
+  _loaderCacheOriginalUse?: (item: any) => any;
 };
 
 /**
@@ -497,13 +485,16 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * **Return Types:**
  * - `boolean` - Hard decision: immediately returns this value (short-circuits)
  * - `{ defaultShouldRevalidate: boolean }` - Soft decision: updates suggestion for next revalidator
+ * - `void` / `null` / `undefined` - Defer to the current suggestion (no opinion); the
+ *   loop continues to the next revalidator without changing the running default
  *
  * **Execution Flow:**
  * 1. Start with built-in `defaultShouldRevalidate` (true if params changed)
  * 2. Execute global revalidators first, then route-specific
  * 3. Hard decision (boolean): stop immediately and use that value
  * 4. Soft decision (object): update suggestion and continue to next revalidator
- * 5. If all return soft decisions: use the final suggestion
+ * 5. Defer (`void` / `null` / `undefined`): leave suggestion unchanged and continue
+ * 6. If no hard decision was returned: use the final running suggestion
  *
  * @param args.currentParams - Previous route params (generic by default, can be narrowed)
  * @param args.currentUrl - Previous URL
@@ -513,9 +504,10 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.context - App context (db, user, etc.)
  * @param args.actionResult - Result from action (future support)
  * @param args.formData - Form data from action (future support)
- * @param args.formMethod - HTTP method from action (future support)
+ * @param args.method - HTTP method: "GET" for navigation, "POST" for server actions
  *
- * @returns Hard decision (boolean) or soft suggestion (object)
+ * @returns Hard decision (boolean), soft suggestion (object), or defer
+ *   (`void` / `null` / `undefined`) to keep the running suggestion as-is.
  *
  * @example
  * ```typescript
@@ -535,20 +527,46 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * })
  * ```
  */
+/**
+ * A reference to a server action, used by `isAction()` in a revalidate predicate.
+ *
+ * Either a directly imported action (`import { addToCart }`) or a namespace
+ * import of an action module (`import * as CartActions`). Matching resolves the
+ * action's build-injected id (`path#export`) — the same identity the router uses
+ * for `actionId` — so a renamed or moved action breaks at compile time instead
+ * of silently failing to match.
+ */
+export type ActionRef =
+  | ((...args: never[]) => unknown)
+  | Record<string, unknown>;
+
 /**
  * Revalidation function called during client-side navigation to decide whether
  * a segment (layout, route, parallel slot, or loader) should be re-rendered.
  *
  * Return `true` to re-render, `false` to skip (keep client's current version),
- * or `{ defaultShouldRevalidate: boolean }` to override the default for
- * downstream segments.
+ * `{ defaultShouldRevalidate: boolean }` to update the running suggestion for
+ * downstream revalidators, or nothing (`void` / `null` / `undefined`) to defer
+ * to the current suggestion without changing it.
+ *
+ * Two idioms cover almost every case; they differ only in what an _unrelated_
+ * action does. Match actions by reference with `ctx.isAction()` (rename-safe)
+ * rather than `actionId?.includes("...")` (a renamed or moved action silently
+ * stops matching). Because `isAction` returns a raw boolean, combine it with
+ * `|| undefined` to defer or leave it bare to suppress.
  *
  * @example
  * ```ts
- * // Re-render only when a cart action happened or browser signals staleness
- * revalidate(({ actionId, stale }) =>
- *   actionId?.includes("cart") || stale || false
- * )
+ * import * as CartActions from "./actions/cart";
+ *
+ * // Idiom A — "mine, else defer": re-render on my actions, otherwise return
+ * // undefined so the segment's default decision still applies (and downstream
+ * // revalidators get a say).
+ * revalidate((ctx) => ctx.isAction(CartActions) || undefined)
+ *
+ * // Idiom B — "mine only": re-render on my actions and suppress everything
+ * // else (isAction returns a raw boolean, so an unrelated action yields false).
+ * revalidate((ctx) => ctx.isAction(CartActions))
  *
  * // Always re-render when params change (default behavior made explicit)
  * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)
@@ -574,8 +592,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
 
   // ── Segment metadata (which segment is being evaluated) ──────────────
 
-  /** The type of segment being revalidated. */
-  segmentType: "layout" | "route" | "parallel";
+  /**
+   * The type of segment being revalidated. `"loader"` is passed to revalidate
+   * functions attached to a `loader(Fn, () => [revalidate(...)])` registration.
+   */
+  segmentType: "layout" | "route" | "parallel" | "loader";
   /** Layout name (e.g., `"root"`, `"shop"`, `"auth"`). Only set for layout segments. */
   layoutName?: string;
   /** Slot name (e.g., `"@sidebar"`, `"@modal"`). Only set for parallel segments. */
@@ -591,21 +612,54 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * relative to the project root, followed by `#` and the exported function name.
    *
    * This is stable and can be used for path-based matching to revalidate
-   * when any action in a module or directory fires:
+   * when any action in a module or directory fires. Prefer `|| undefined`
+   * (defer to the segment default / downstream revalidators) over `?? false`
+   * (hard short-circuit that suppresses the default and ends the chain):
    *
    * @example
    * ```ts
    * // Match a specific action
-   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart")
+   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart" || undefined)
    *
    * // Match any action in the cart module
-   * revalidate(({ actionId }) => actionId?.includes("cart") ?? false)
+   * revalidate(({ actionId }) => actionId?.includes("cart") || undefined)
    *
    * // Match any action under src/apps/store/actions/
-   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") ?? false)
+   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") || undefined)
    * ```
    */
   actionId?: string;
+  /**
+   * Typed, rename-safe action matching. Returns `true` when the action that
+   * triggered this revalidation is one of the given references — or, for a
+   * namespace import (`import * as CartActions`), any export of that module —
+   * and `false` otherwise (including plain navigation with no action).
+   *
+   * Called with NO arguments it answers "is this request an action at all?":
+   * `true` for any action, `false` on plain navigation. Use the bare form when
+   * you want to revalidate on every action regardless of which one fired.
+   *
+   * Prefer this over hand-written `actionId` substring matches: it resolves the
+   * action's stable `path#export` id from the imported reference, so a rename is
+   * a type error in one place instead of silent drift across consumers. It
+   * resolves the reference the same way the action boundary derives `actionId`
+   * (`$id ?? $$id`), so it matches in both dev and production.
+   *
+   * Returns a raw boolean, so for the common "revalidate on match, else defer"
+   * intent combine with `|| undefined`:
+   *
+   * @example
+   * ```ts
+   * import { addToCart, removeFromCart } from "./actions/cart";
+   * import * as CartActions from "./actions/cart";
+   *
+   * revalidate((ctx) => ctx.isAction() || undefined); // any action
+   * revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
+   * revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
+   * revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any in the module
+   * ```
+   */
+  isAction: (...actions: ActionRef[]) => boolean;
   /** URL where the action was executed (the page the user was on when they triggered the action). */
   actionUrl?: URL;
   /** Return value from the action execution. Can be used to conditionally revalidate based on the action's outcome. */
@@ -641,7 +695,7 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * action that may have mutated backend state.
    */
   stale?: boolean;
-}) => boolean | { defaultShouldRevalidate: boolean };
+}) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported
 
@@ -746,7 +800,7 @@ export type Revalidate<
  * Middleware function with typed params and environment
  *
  * @template TParams - Params object (defaults to generic)
- * @template TEnv - Environment type (defaults to global RSCRouter.Env)
+ * @template TEnv - Environment type (defaults to global Rango.Env)
  *
  * Note: Middleware cannot directly use route names for params typing because
  * middleware is defined during router setup, before RegisteredRoutes is populated.
@@ -754,7 +808,7 @@ export type Revalidate<
  *
  * @example
  * ```typescript
- * // Basic middleware (uses global RSCRouter.Env via module augmentation)
+ * // Basic middleware (uses global Rango.Env via module augmentation)
  * const middleware: Middleware = async (ctx, next) => {
  *   ctx.set("user", { id: "123" }); // Type-safe!
  *   await next();

package/src/types/index.ts

@@ -1,14 +1,11 @@
-// Global namespace (must be imported for side effects: `declare global`)
 export type {
   GetRegisteredRoutes,
   DefaultHandlerRouteMap,
   DefaultReverseRouteMap,
   DefaultEnv,
 } from "./global-namespace.js";
-// Ensure the global namespace declaration is evaluated
 import "./global-namespace.js";
 
-// Route configuration
 export type {
   DocumentProps,
   ExtractParams,
@@ -19,7 +16,6 @@ export type {
   ResolvedRouteMap,
 } from "./route-config.js";
 
-// Boundaries (error/notFound)
 export type {
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -32,7 +28,6 @@ export type {
 } from "./boundaries.js";
 export { isLoaderDataResult } from "./boundaries.js";
 
-// Handler context and related types
 export type {
   MiddlewareFn,
   ScopedRouteMap,
@@ -42,6 +37,7 @@ export type {
   GenericParams,
   RevalidateParams,
   ShouldRevalidateFn,
+  ActionRef,
   RouteKeys,
   ExtractRouteParams,
   HandlersForRouteMap,
@@ -49,10 +45,11 @@ export type {
   Middleware,
 } from "./handler-context.js";
 
-// Segments
 export type {
   ViewTransitionClass,
   TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
   ResolvedSegment,
   SegmentMetadata,
   SlotState,
@@ -60,10 +57,8 @@ export type {
   MatchResult,
 } from "./segments.js";
 
-// Route entries
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
 
-// Loader types
 export type {
   LoaderContext,
   LoaderFn,
@@ -72,7 +67,6 @@ export type {
   LoaderDefinition,
 } from "./loader-types.js";
 
-// Cache types
 export type {
   CacheContext,
   CacheOptions,
@@ -80,7 +74,6 @@ export type {
   EntryCacheConfig,
 } from "./cache-types.js";
 
-// Error handling types
 export type {
   ErrorPhase,
   OnErrorContext,

package/src/types/loader-types.ts

@@ -1,12 +1,15 @@
 import type { ContextVar } from "../context-var.js";
+import type { Handle } from "../handle.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
+import type { UseItems, LoaderUseItem } from "../route-types.js";
 import type {
   DefaultEnv,
   DefaultReverseRouteMap,
   DefaultVars,
 } from "./global-namespace.js";
+import type { RequestScope } from "./request-scope.js";
 
 /**
  * Context passed to loader functions during execution
@@ -38,7 +41,7 @@ export type LoaderContext<
   TEnv = DefaultEnv,
   TBody = unknown,
   TSearch extends SearchSchema = {},
-> = {
+> = RequestScope<TEnv> & {
   params: TParams;
   /**
    * Route params extracted from the URL pattern match (server-side only).
@@ -47,22 +50,46 @@ export type LoaderContext<
    * resource scoping.
    */
   routeParams: Record<string, string>;
-  request: Request;
-  searchParams: URLSearchParams;
   search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
-  pathname: string;
-  url: URL;
-  env: TEnv;
-  var: DefaultVars;
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
   } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
   /**
-   * Access another loader's data (returns promise since loaders run in parallel)
+   * Access another loader's data, or read handle data after rendered().
+   *
+   * For loaders: returns a promise (loaders run in parallel).
+   * For handles: returns collected data (only after `await ctx.rendered()`).
+   */
+  use: {
+    <T, TLoaderParams = any>(
+      loader: LoaderDefinition<T, TLoaderParams>,
+    ): Promise<T>;
+    <TData, TAccumulated = TData[]>(
+      handle: Handle<TData, TAccumulated>,
+    ): TAccumulated;
+  };
+  /**
+   * **Experimental.** Wait for all non-loader segments to settle.
+   *
+   * After the returned promise resolves, handle data is available via
+   * `ctx.use(handle)`. Supported in DSL loaders, including on streaming
+   * trees that use `loading()` — the barrier waits for the streaming
+   * handlers to finish pushing before it resolves. Throws if called from a
+   * handler-invoked loader, or if a handler is already awaiting this loader
+   * via `ctx.use()` (that would deadlock — use a loader-to-loader
+   * dependency instead).
+   *
+   * @example
+   * ```typescript
+   * const PricesLoader = createLoader(async (ctx) => {
+   *   "use server";
+   *   await ctx.rendered();
+   *   const products = ctx.use(Products); // reads handle data
+   *   return pricing.getLive(products.map(p => p.id));
+   * });
+   * ```
    */
-  use: <T, TLoaderParams = any>(
-    loader: LoaderDefinition<T, TLoaderParams>,
-  ) => Promise<T>;
+  rendered: () => Promise<void>;
   /**
    * HTTP method (GET, POST, PUT, PATCH, DELETE)
    * Available when loader is called via load({ method: "POST", ... })
@@ -180,4 +207,6 @@ export type LoaderDefinition<
   __brand: "loader";
   $$id: string; // Injected by Vite plugin (exposeInternalIds) - unique identifier
   fn?: LoaderFn<T, TParams, any>; // Optional - server-side only, stored in registry for RSC
+  /** Composable default DSL items merged when the loader is mounted. */
+  use?: () => UseItems<LoaderUseItem>;
 };

package/src/types/request-scope.ts

@@ -0,0 +1,112 @@
+import type { DefaultEnv } from "./global-namespace.js";
+
+/**
+ * Minimal subset of Cloudflare Workers' ExecutionContext that the router
+ * uses. Defined locally so the package does not depend on
+ * `@cloudflare/workers-types`. Consumers that want the full type can cast.
+ *
+ * On non-Cloudflare runtimes (Node, dev server, tests), this is undefined
+ * — portable apps should prefer `ctx.waitUntil(...)`, which degrades
+ * gracefully. `ctx.executionContext` is the escape hatch for libraries
+ * (MCP, Durable Object routing, etc.) that type their arguments as the
+ * raw ExecutionContext.
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Fallback `waitUntil` body used when no Cloudflare `ExecutionContext`
+ * is available (Node, dev, tests). Runs the work fire-and-forget and
+ * logs errors so they don't silently swallow.
+ *
+ * Exported so every `waitUntil` call site degrades identically instead
+ * of inventing its own fallback policy.
+ */
+export function fireAndForgetWaitUntil(fn: () => Promise<void>): void {
+  // Defer fn() invocation to a microtask so a SYNCHRONOUS throw in a non-async
+  // callback (e.g. `() => { somethingThatThrows(); return p; }`) becomes a
+  // rejected promise we catch here, not an exception that escapes into the
+  // request flow. waitUntil is fire-and-forget: a background-task failure must
+  // never break the response.
+  Promise.resolve()
+    .then(fn)
+    .catch((err) => console.error("[waitUntil] Background task failed:", err));
+}
+
+/**
+ * Fields present on every user-facing request context.
+ *
+ * @template TEnv - Platform bindings type (Cloudflare env, etc.).
+ */
+export interface RequestScope<TEnv = DefaultEnv> {
+  /**
+   * The original incoming Request object (transport URL intact).
+   * Use `url` / `searchParams` for application logic — those have
+   * internal `_rsc*` params stripped. `request` preserves the raw URL
+   * when you need original headers, method, or body.
+   */
+  request: Request;
+
+  /**
+   * The request URL with internal `_rsc*` transport params stripped.
+   * Use this for routing, link generation, and display.
+   */
+  url: URL;
+
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `url` for application logic
+   * — this is only needed for advanced cases like debugging or custom
+   * cache keying.
+   */
+  originalUrl: URL;
+
+  /** URL pathname (same as `url.pathname`). */
+  pathname: string;
+
+  /**
+   * Query parameters from the URL (system params like `_rsc*` are
+   * filtered). Always a standard `URLSearchParams` instance.
+   */
+  searchParams: URLSearchParams;
+
+  /**
+   * Platform bindings (DB, KV, secrets, etc.). On Cloudflare Workers
+   * these are the `env` object passed to the Worker's `fetch()` handler.
+   */
+  env: TEnv;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, delegates to `executionContext.waitUntil()`.
+   * On Node / dev / tests, runs as fire-and-forget with error logging.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Raw Cloudflare Workers `ExecutionContext`, when running on a
+   * Cloudflare-compatible runtime. Undefined elsewhere.
+   *
+   * Escape hatch for libraries that type their arguments as
+   * `ExecutionContext` (MCP `fetch`, `routeAgentRequest`, etc.).
+   * For the common "do work after the response" case, prefer
+   * `ctx.waitUntil(...)` — it is platform-neutral.
+   *
+   * @example
+   * ```typescript
+   * path.any("/mcp", (ctx) =>
+   *   emailMcp.fetch(ctx.request, ctx.env, ctx.executionContext!),
+   * );
+   * ```
+   */
+  executionContext?: ExecutionContext;
+}