@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.dacec167

package/src/testing/vitest.ts

@@ -0,0 +1,270 @@
+/**
+ * @rangojs/router/testing/vitest
+ *
+ * Vitest setup helper for the UNIT + INTEGRATION + DOM test project of a
+ * @rangojs/router consumer app. It returns the `resolve.alias` entries that make
+ * a real app's router / loaders / middleware importable in a bare Vitest process.
+ *
+ * Why this is needed (the documented "vi.mock(plugin-rsc) + import router"
+ * recipe is not sufficient for a real app):
+ *
+ * - `@rangojs/router` resolves to SERVER-ONLY STUBS outside the `react-server`
+ *   condition — `urls()`, `createRouter()`, `cookies()`, `getRequestContext()`
+ *   throw "only available in a react-server environment". Importing the app's own
+ *   router/loaders/middleware then fails immediately. Vitest does NOT apply the
+ *   `react-server` condition to bare-package exports resolution, and enabling it
+ *   globally flips React to its server build (no `createContext`), crashing the
+ *   router's client-boundary imports. The surgical fix is to alias ONLY the bare
+ *   `@rangojs/router` specifier to its react-server entry (real impls) while
+ *   leaving React as the client build — which is exactly what this helper does.
+ * - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
+ *   (whose real body imports unresolvable Vite virtuals) are stubbed.
+ * - Cloudflare apps additionally import the `cloudflare:workers` /
+ *   `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
+ *
+ * Usage (recommended one-call form — see {@link rangoTestConfig}):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     globals: true,
+ *     include: ["test/**\/*.test.{ts,tsx}"],
+ *     environment: "node",
+ *     ...rangoTestConfig({ preset: "cloudflare" }),
+ *   },
+ * });
+ * ```
+ *
+ * `rangoTestConfig` bundles the resolve aliases ({@link rangoTestAliases}) with
+ * the `server.deps.inline` contract ({@link rangoInlineDeps}) an installed
+ * consumer needs — @rangojs/router ships as TS source, and without `deps.inline`
+ * Vitest hands those `.ts` files to Node, which on Node >= 23 throws
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. Use the lower-level
+ * `rangoTestAliases` directly only if you wire `deps.inline` yourself.
+ *
+ * Notes:
+ * - This is for the node/DOM project. The Flight project (real RSC rendering via
+ *   `@rangojs/router/testing/flight`) uses the `react-server` condition and pure
+ *   leaf server components — it does NOT use this alias (which would crash under
+ *   the server React build). See the testing guide for the Flight config.
+ * - `renderRoute` (`@rangojs/router/testing/dom`) tests run in this same project
+ *   under a DOM environment (`happy-dom`/`jsdom`); the alias does not affect them.
+ * - LIMITATION: the FULL app router still cannot be imported if it uses
+ *   `Prerender()` / `createLoader()` (their build-time-injected `$$id` is absent
+ *   in a bare test). Build a router from an importable, Prerender-free include for
+ *   `dispatch`, or assert whole-router behavior with e2e.
+ */
+
+import { fileURLToPath } from "node:url";
+
+/** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
+export interface TestAlias {
+  find: string | RegExp;
+  replacement: string;
+}
+
+/** Options for {@link rangoTestAliases}. */
+export interface RangoTestAliasOptions {
+  /**
+   * Deployment preset, matching `rango({ preset })` in the Vite plugin. With
+   * `"cloudflare"` the helper additionally stubs the Cloudflare Workers runtime
+   * virtuals (`cloudflare:workers` / `cloudflare:email`) a CF app's route tree
+   * imports. A string (not a boolean) so more presets can be added without an
+   * API change. Default: `"node"`.
+   */
+  preset?: "node" | "cloudflare";
+}
+
+/**
+ * Resolve a path relative to this module. Anchored at the PACKAGE ROOT
+ * (`../../` from both `src/testing/vitest.ts` and the shipped
+ * `dist/testing/vitest.js` — each is two levels below the root), so the alias
+ * targets always point at the `src/*.ts` files Vite transpiles at test time,
+ * regardless of whether this helper is loaded as source (in-repo) or as the
+ * compiled `dist` entry (an installed consumer).
+ */
+function here(relativeFromRoot: string): string {
+  return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
+}
+
+/**
+ * Build the `resolve.alias` entries a consumer's node/DOM Vitest project needs to
+ * import a real @rangojs/router app's router/loaders/middleware. Spread into a
+ * Vitest config: `resolve: { alias: rangoTestAliases(...) }` (concat your own
+ * aliases as needed).
+ */
+export function rangoTestAliases(
+  opts: RangoTestAliasOptions = {},
+): TestAlias[] {
+  const aliases: TestAlias[] = [
+    // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
+    // subpaths (/testing, /client, /cache, ...) are untouched. React stays the
+    // client build, so createContext and "use client" modules work.
+    { find: /^@rangojs\/router$/, replacement: here("src/index.rsc.ts") },
+    {
+      find: "@rangojs/router:version",
+      replacement: here("src/testing/vitest-stubs/version.ts"),
+    },
+    {
+      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
+    },
+  ];
+
+  if (opts.preset === "cloudflare") {
+    aliases.push(
+      {
+        find: "cloudflare:workers",
+        replacement: here("src/testing/vitest-stubs/cloudflare-workers.ts"),
+      },
+      {
+        find: "cloudflare:email",
+        replacement: here("src/testing/vitest-stubs/cloudflare-email.ts"),
+      },
+    );
+  }
+
+  return aliases;
+}
+
+/**
+ * Vitest `server.deps.inline` patterns that force Vite (not Node) to transpile
+ * @rangojs/router's TypeScript source under test.
+ *
+ * REQUIRED for an installed (node_modules) consumer: @rangojs/router ships as TS
+ * source, and Vitest externalizes node_modules by default — so without this Node
+ * loads the `.ts` files directly and, on Node >= 23, throws
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. In this monorepo it is a no-op
+ * (the workspace symlink resolves to a realpath outside node_modules, which Vite
+ * already transpiles), which is precisely why an in-repo dogfood never surfaces
+ * the need and the contract has to be shipped explicitly.
+ */
+export const rangoInlineDeps: RegExp[] = [/@rangojs[/\\]router/];
+
+/** The Vitest `test`-block fragment {@link rangoTestConfig} returns. */
+export interface RangoTestConfig {
+  alias: TestAlias[];
+  server: { deps: { inline: RegExp[] } };
+}
+
+/**
+ * The complete Vitest `test`-block fragment a consumer needs: the resolve
+ * aliases ({@link rangoTestAliases}) AND the `server.deps.inline` contract
+ * ({@link rangoInlineDeps}). Spread it into your `test` block so both land in
+ * one place and a consumer cannot forget the `deps.inline` half (omitting it
+ * loads rango's TS source through Node and breaks on Node >= 23):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     globals: true,
+ *     include: ["test/**\/*.test.{ts,tsx}"],
+ *     environment: "node",
+ *     ...rangoTestConfig({ preset: "cloudflare" }),
+ *   },
+ * });
+ * ```
+ */
+export function rangoTestConfig(
+  opts: RangoTestAliasOptions = {},
+): RangoTestConfig {
+  return {
+    alias: rangoTestAliases(opts),
+    // fresh copy so the shared rangoInlineDeps const is never aliased into (or
+    // mutated through) a consumer's resolved config
+    server: { deps: { inline: [...rangoInlineDeps] } },
+  };
+}
+
+/** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
+interface FlightTransformPlugin {
+  name: string;
+  transform(
+    code: string,
+    id: string,
+  ): Promise<{ code: string; map: unknown } | undefined>;
+}
+
+/**
+ * A Vite plugin for the FLIGHT (react-server) Vitest project that applies the
+ * `"use client"` transform to a consumer's client modules — the same transform a
+ * real build applies. With it, `renderServerTree` (`@rangojs/router/testing/flight`)
+ * resolves client islands AUTOMATICALLY from the server tree's own imports: no
+ * `clientComponents` to pass, no filename convention. Without it, a `"use client"`
+ * module is imported as a plain (unmarked) function and would render server-side,
+ * so you must list islands via `renderServerTree(..., { clientComponents })`.
+ *
+ * Add it to your react-server Vitest project:
+ *
+ * ```ts
+ * // vitest.rsc.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { rangoUseClientTransform } from "@rangojs/router/testing/vitest";
+ *
+ * export default defineConfig({
+ *   resolve: { conditions: ["react-server"] },
+ *   plugins: [rangoUseClientTransform()],
+ *   test: {
+ *     include: ["test/**\/*.rsc-test.{ts,tsx}"],
+ *     pool: "forks",
+ *     execArgv: ["--conditions=react-server"],
+ *   },
+ * });
+ * ```
+ *
+ * Each `"use client"` module's exports are replaced with client references keyed
+ * by the module's absolute path (the boundary id), the export name becoming the
+ * boundary name. Modules without the directive (server components) are untouched,
+ * so `renderToFlightString` of pure leaf trees is unaffected.
+ */
+export function rangoUseClientTransform(): FlightTransformPlugin {
+  return {
+    name: "rango:testing-use-client",
+    async transform(code, id) {
+      if (id.includes("/node_modules/")) return undefined;
+      // Fast path: only parse modules that mention the directive.
+      if (!code.includes("use client")) return undefined;
+      const { parseAstAsync } = await import("vite");
+      const { hasDirective, transformDirectiveProxyExport } =
+        await import("@vitejs/plugin-rsc/transforms");
+      // vite's parser and the transforms ship structurally-compatible but
+      // distinctly-typed ASTs (oxc vs estree); cast through the transform's own
+      // parameter type, exactly as plugin-rsc does at runtime.
+      type TransformAst = Parameters<typeof transformDirectiveProxyExport>[0];
+      let ast: TransformAst;
+      try {
+        ast = (await parseAstAsync(code)) as unknown as TransformAst;
+      } catch {
+        return undefined;
+      }
+      if (!hasDirective(ast.body, "use client")) return undefined;
+      const result = transformDirectiveProxyExport(ast, {
+        directive: "use client",
+        code,
+        runtime: (name: string) =>
+          `$$RangoRSD.registerClientReference(` +
+          `() => { throw new Error("client reference " + ${JSON.stringify(name)} + " is not callable on the server"); }, ` +
+          `${JSON.stringify(id)}, ${JSON.stringify(name)})`,
+      });
+      if (!result) return undefined;
+      const { output } = result;
+      // The vendored server serializer is the one renderToFlightString uses;
+      // resolvable here under the react-server condition.
+      output.prepend(
+        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";\n`,
+      );
+      return {
+        code: output.toString(),
+        map: output.generateMap({ hires: true }),
+      };
+    },
+  };
+}

package/src/types/global-namespace.ts

@@ -7,7 +7,7 @@
  * ```typescript
  * // In env.ts or env.d.ts
  * declare global {
- *   namespace RSCRouter {
+ *   namespace Rango {
  *     interface Env extends AppBindings {}
  *     interface Vars extends AppVariables {}
  *   }
@@ -18,7 +18,7 @@
  * ```
  */
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
     interface Env {
       // Empty by default - users augment with their bindings (e.g., { DB: D1Database })
@@ -44,13 +44,25 @@ declare global {
 }
 
 /**
- * Get registered routes or fallback to generic Record<string, string>
- * When RSCRouter.RegisteredRoutes is augmented, provides autocomplete for route names
- * When not augmented, allows any string (no autocomplete)
+ * Route map for path-validation surfaces (`href`, `ValidPaths`, `PathResponse`).
+ *
+ * Resolution order:
+ * 1. `RegisteredRoutes` — manual `extends typeof router.routeMap`; richest map,
+ *    the only one carrying response-route payload metadata.
+ * 2. `GeneratedRouteMap` — auto-wired by `router.named-routes.gen.ts`; path +
+ *    search only. Lets `rango generate` alone enable `href()`/`ValidPaths` path
+ *    checking without a manual `RegisteredRoutes` declaration.
+ * 3. `Record<string, string>` — permissive fallback when nothing is registered.
+ *
+ * Referencing `GeneratedRouteMap` here is cycle-safe: it is declared in the
+ * standalone gen file with no imports, unlike `RegisteredRoutes extends typeof
+ * router.routeMap`.
  */
-export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
-  ? Record<string, string>
-  : RSCRouter.RegisteredRoutes;
+export type GetRegisteredRoutes = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
+    ? Record<string, string>
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Default route map for reverse() surfaces.
@@ -58,12 +70,11 @@ export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
  * cycles, but falls back to RegisteredRoutes for manual augmentation and then to
  * a permissive record when no route types are available.
  */
-export type DefaultReverseRouteMap =
-  keyof RSCRouter.GeneratedRouteMap extends never
-    ? keyof RSCRouter.RegisteredRoutes extends never
-      ? Record<string, string>
-      : RSCRouter.RegisteredRoutes
-    : RSCRouter.GeneratedRouteMap;
+export type DefaultReverseRouteMap = keyof Rango.GeneratedRouteMap extends never
+  ? keyof Rango.RegisteredRoutes extends never
+    ? Record<string, string>
+    : Rango.RegisteredRoutes
+  : Rango.GeneratedRouteMap;
 
 /**
  * Default route map for Handler type.
@@ -71,30 +82,32 @@ export type DefaultReverseRouteMap =
  * circular dependencies: router.tsx -> urls.tsx -> handler.tsx -> RegisteredRoutes -> router.tsx.
  * GeneratedRouteMap is declared in a standalone gen file with no imports.
  */
-export type DefaultHandlerRouteMap =
-  keyof RSCRouter.GeneratedRouteMap extends never
-    ? {}
-    : RSCRouter.GeneratedRouteMap;
+export type DefaultHandlerRouteMap = keyof Rango.GeneratedRouteMap extends never
+  ? {}
+  : Rango.GeneratedRouteMap;
 
 /**
- * Default environment type - uses global augmentation if available, any otherwise
+ * Default environment type - uses global augmentation if available.
+ *
+ * Falls back to `unknown` (not `any`) when `Rango.Env` is not augmented, so
+ * an app that forgets to register its bindings gets a compile error on
+ * `ctx.env.SOMETHING` instead of silently losing all env type-checking. Augment
+ * `Rango.Env` to type `ctx.env`.
  */
-export type DefaultEnv = keyof RSCRouter.Env extends never
-  ? any
-  : RSCRouter.Env;
+export type DefaultEnv = keyof Rango.Env extends never ? unknown : Rango.Env;
 
 /**
  * Default variables type - uses global augmentation if available, Record<string, any> otherwise
  */
-export type DefaultVars = keyof RSCRouter.Vars extends never
+export type DefaultVars = keyof Rango.Vars extends never
   ? Record<string, any>
-  : RSCRouter.Vars;
+  : Rango.Vars;
 
 /**
  * Default route name type for public `routeName` on contexts.
  * When GeneratedRouteMap is augmented, narrows to the known route names.
  * Otherwise falls back to `string` for untyped usage.
  */
-export type DefaultRouteName = keyof RSCRouter.GeneratedRouteMap extends never
+export type DefaultRouteName = keyof Rango.GeneratedRouteMap extends never
   ? string
-  : keyof RSCRouter.GeneratedRouteMap & string;
+  : keyof Rango.GeneratedRouteMap & string;

package/src/types/handler-context.ts

@@ -20,6 +20,7 @@ import type {
 } 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";
@@ -42,7 +43,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
@@ -195,7 +196,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 }>.
@@ -215,44 +216,11 @@ export type HandlerContext<
    * changing build semantics (e.g., skip expensive operations in dev).
    */
   dev: 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.
-   */
-  request: Request;
-  /**
-   * Query parameters from the URL (system params like `_rsc*` are filtered).
-   * Always a standard URLSearchParams instance.
-   */
-  searchParams: URLSearchParams;
   /**
    * 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;
   /**
    * Type-safe getter for middleware variables.
    * Preferred way to read middleware-injected variables.
@@ -503,13 +471,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
@@ -521,7 +492,8 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.formData - Form data from action (future support)
  * @param args.formMethod - HTTP method from action (future support)
  *
- * @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
@@ -541,19 +513,34 @@ 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.
  *
  * @example
  * ```ts
- * // Re-render only when a cart action happened or browser signals staleness
+ * // Re-render when a cart action happened or the browser signals staleness;
+ * // defer otherwise (|| undefined) so the segment default still applies
  * revalidate(({ actionId, stale }) =>
- *   actionId?.includes("cart") || stale || false
+ *   actionId?.includes("cart") || stale || undefined
  * )
  *
  * // Always re-render when params change (default behavior made explicit)
@@ -580,8 +567,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. */
@@ -597,21 +587,49 @@ 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).
+   *
+   * 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(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. */
@@ -647,7 +665,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
 
@@ -752,7 +770,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.
@@ -760,7 +778,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

@@ -42,6 +42,7 @@ export type {
   GenericParams,
   RevalidateParams,
   ShouldRevalidateFn,
+  ActionRef,
   RouteKeys,
   ExtractRouteParams,
   HandlersForRouteMap,

package/src/types/loader-types.ts

@@ -3,11 +3,13 @@ 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
@@ -39,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).
@@ -48,12 +50,7 @@ export type LoaderContext<
    * resource scoping.
    */
   routeParams: Record<string, string>;
-  request: Request;
-  searchParams: URLSearchParams;
   search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
-  pathname: string;
-  url: URL;
-  env: TEnv;
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
   } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
@@ -207,4 +204,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>;
 };