@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/types/handler-context.ts

@@ -9,8 +9,9 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
 import type {
   DefaultEnv,
   DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
+  DefaultRouteName,
   DefaultVars,
-  GetRegisteredRoutes,
 } from "./global-namespace.js";
 import type {
   ExtractParams,
@@ -18,6 +19,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";
@@ -67,6 +70,65 @@ type ExtractSearchFromEntry<TMap, TKey> = TKey extends keyof TMap
     : {}
   : {};
 
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+
+type AutofillParamsFromEntry<TEntry> = TEntry extends string
+  ? string extends TEntry
+    ? Record<string, string>
+    : Partial<ExtractParams<TEntry>>
+  : TEntry extends { readonly path: infer P extends string }
+    ? string extends P
+      ? Record<string, string>
+      : Partial<ExtractParams<P>>
+    : Record<string, string>;
+
+type AutofillSearchFromEntry<TMap, TKey> = TKey extends keyof TMap
+  ? TMap[TKey] extends { readonly search: infer S extends SearchSchema }
+    ? ResolveSearchSchema<S>
+    : Record<string, unknown>
+  : Record<string, unknown>;
+
+type AutofillAwareReverseFunction<TLocalRoutes, TGlobalRoutes> =
+  ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
+    <TName extends keyof TGlobalRoutes & string>(
+      name: TName,
+      params?: AutofillParamsFromEntry<TGlobalRoutes[TName]>,
+      search?: AutofillSearchFromEntry<TGlobalRoutes, TName>,
+    ): string;
+    <TName extends keyof TLocalRoutes & string>(
+      name: `.${TName}`,
+      params?: AutofillParamsFromEntry<TLocalRoutes[TName]>,
+      search?: AutofillSearchFromEntry<TLocalRoutes, TName>,
+    ): string;
+  };
+
+type StrictLocalParamsWithExtras<TEntry> =
+  IsEmptyObject<ExtractParamsFromEntry<TEntry, {}>> extends true
+    ? 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>(
+      name: TName,
+      params?: AutofillParamsFromEntry<TGlobalRoutes[TName]>,
+      search?: AutofillSearchFromEntry<TGlobalRoutes, TName>,
+    ): string;
+    <TName extends keyof TLocalRoutes & string>(
+      name: `.${TName}`,
+      params: StrictLocalParamsWithExtras<TLocalRoutes[TName]>,
+      search?: AutofillSearchFromEntry<TLocalRoutes, TName>,
+    ): string;
+  };
+
 export type Handler<
   T extends
     | keyof DefaultHandlerRouteMap
@@ -75,7 +137,7 @@ export type Handler<
     | Record<string, any> = {},
   TRouteMap extends {} = DefaultHandlerRouteMap,
   TEnv = DefaultEnv,
-> = (
+> = ((
   ctx: HandlerContext<
     T extends `.${infer Local}`
       ? Local extends keyof TRouteMap
@@ -100,31 +162,32 @@ 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)
  *
  * Provides type-safe access to:
  * - Route params (from URL pattern)
- * - Request data (request, searchParams, pathname, url)
+ * - 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', ...))
  *
- * **Note:** System parameters (query params starting with `_rsc`) are automatically
- * filtered from `url`, `searchParams`, and `request.url` for cleaner access.
- *
  * @example
  * ```typescript
  * 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)
+ *   ctx.request            // Raw transport request (original URL intact)
  * }
  * ```
  */
@@ -133,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 }>.
@@ -143,46 +206,24 @@ export type HandlerContext<
   readonly _paramCheck?: (params: TParams) => TParams;
   /**
    * True during build-time pre-rendering, false at runtime.
-   * In dev mode, Prerender handlers run live so build is false.
-   * In production passthrough (live fallback), build is also false.
+   * Build-time collection and dev on-demand prerender use `true`.
+   * Live request rendering, including passthrough fallback, uses `false`.
    */
   build: boolean;
   /**
-   * The incoming Request object.
-   * System params (`_rsc*`) are filtered from the URL for cleaner access.
-   */
-  request: Request;
-  /**
-   * Query parameters from the URL (system params like `_rsc*` are filtered).
-   * Always a standard URLSearchParams instance.
+   * 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).
    */
-  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 system params filtered).
-   */
-  url: 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
@@ -203,24 +244,18 @@ export type HandlerContext<
    * ```
    */
   set: {
-    <T>(contextVar: ContextVar<T>, value: T): void;
-  } & (<K extends keyof DefaultVars>(key: K, value: DefaultVars[K]) => void);
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+  } & (<K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
+    options?: { cache?: boolean },
+  ) => void);
   /**
-   * Stub response for setting headers/cookies.
-   * Headers set here are merged into the final response.
-   *
-   * @example
-   * ```typescript
-   * route("product", (ctx) => {
-   *   ctx.res.headers.set("Cache-Control", "s-maxage=60");
-   *   return <ProductPage />;
-   * });
-   * ```
-   */
-  res: Response;
-  /**
-   * Shorthand for ctx.res.headers - response headers.
-   * Headers set here are merged into the final response.
+   * Response headers. Headers set here are merged into the final response.
    *
    * @example
    * ```typescript
@@ -234,8 +269,15 @@ export type HandlerContext<
   /**
    * Access loader data or push handle data.
    *
+   * Available in route handlers, layout handlers, middleware, server actions,
+   * and server components rendered within the request context.
+   *
    * For loaders: Returns a promise that resolves to the loader data.
    * Loaders are executed in parallel and memoized per request.
+   * Prefer DSL `loader()` + client `useLoader()` over `ctx.use(Loader)` —
+   * DSL loaders are always fresh and cache-safe. Use `ctx.use(Loader)` only
+   * when you need loader data in the handler itself (e.g., to set context
+   * variables or make routing decisions).
    *
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
@@ -243,10 +285,11 @@ export type HandlerContext<
    *
    * @example
    * ```typescript
-   * // Loader usage
-   * route("cart", async (ctx) => {
-   *   const cart = await ctx.use(CartLoader);
-   *   return <CartPage cart={cart} />;
+   * // Loader escape hatch — use when handler needs the data directly
+   * route("product", async (ctx) => {
+   *   const { product } = await ctx.use(ProductLoader);
+   *   ctx.set(Product, product); // make available to children
+   *   return <ProductPage />;
    * });
    *
    * // Handle usage - direct value
@@ -320,12 +363,26 @@ export type HandlerContext<
    * @example
    * ```typescript
    * route("product", (ctx) => {
-   *   ctx.setLocationState([ServerInfo({ data: "value" })]);
+   *   ctx.setLocationState(ServerInfo({ data: "value" }));
+   *   return <ProductPage />;
+   * });
+   * ```
+   */
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+  /**
+   * The matched route name, if the route has an explicit name.
+   * Undefined for unnamed routes (those without a `name` option in path()).
+   * Includes the namespace prefix from include() (e.g., "blog.post").
+   *
+   * @example
+   * ```typescript
+   * route("product", (ctx) => {
+   *   ctx.routeName // "product"
    *   return <ProductPage />;
    * });
    * ```
    */
-  setLocationState(entries: LocationStateEntry[]): void;
+  routeName?: DefaultRouteName;
   /**
    * Generate URLs from route names.
    *
@@ -341,8 +398,14 @@ export type HandlerContext<
    * ```
    */
   reverse: [TRouteMap] extends [never]
-    ? ScopedReverseFunction<GetRegisteredRoutes>
-    : ScopedReverseFunction<TRouteMap, GetRegisteredRoutes>;
+    ? AutofillAwareReverseFunction<
+        Record<string, string>,
+        DefaultReverseRouteMap
+      >
+    : StrictLocalAutofillGlobalReverseFunction<
+        TRouteMap,
+        DefaultReverseRouteMap
+      >;
 };
 
 /**
@@ -355,12 +418,18 @@ export type InternalHandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
 > = HandlerContext<TParams, TEnv, TSearch> & {
-  /** Raw request with all system parameters intact. */
-  _originalRequest: Request;
+  /** @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. */
   _currentSegmentId?: string;
   /** Response type tag (json, text, html, etc.) for cache key differentiation. */
   _responseType?: string;
+  /** Route name for cache key scoping (prevents cross-route collisions). */
+  _routeName?: string;
 };
 
 /**
@@ -402,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
@@ -420,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
@@ -440,27 +513,114 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * })
  * ```
  */
+/**
+ * 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),
+ * `{ 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
+ * revalidate(({ actionId, stale }) =>
+ *   actionId?.includes("cart") || stale || false
+ * )
+ *
+ * // Always re-render when params change (default behavior made explicit)
+ * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)
+ * ```
+ */
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
+  /** Route params from the page being navigated away from. */
   currentParams: TParams;
+  /** Full URL of the page being navigated away from. */
   currentUrl: URL;
+  /** Route params for the navigation target. */
   nextParams: TParams;
+  /** Full URL of the navigation target. */
   nextUrl: URL;
+  /**
+   * The router's default revalidation decision for this segment.
+   * `true` when params changed or the segment is new to the client.
+   * Return this when you want default behavior plus your own conditions.
+   */
   defaultShouldRevalidate: boolean;
+  /** Full handler context — access to `ctx.use()`, `ctx.env`, `ctx.params`, etc. */
   context: HandlerContext<TParams, TEnv>;
-  // Segment metadata (which segment is being evaluated):
+
+  // ── Segment metadata (which segment is being evaluated) ──────────────
+
+  /** The type of segment being revalidated. */
   segmentType: "layout" | "route" | "parallel";
-  layoutName?: string; // Layout name (e.g., "root", "shop", "auth") - only for layouts
-  slotName?: string; // Slot name (e.g., "@sidebar", "@modal") - only for parallels
-  // Action context (populated when revalidation triggered by server action):
-  actionId?: string; // Action identifier (e.g., "src/actions.ts#addToCart")
-  actionUrl?: URL; // URL where action was executed
-  actionResult?: any; // Return value from action execution
-  formData?: FormData; // FormData from action request
-  method?: string; // Request method: 'GET' for navigation, 'POST' for actions
-  routeName?: string; // Route name where action was executed (e.g., "products.detail")
-  // Stale cache revalidation (SWR pattern):
-  stale?: boolean; // True if this is a stale cache revalidation request
-}) => boolean | { defaultShouldRevalidate: boolean };
+  /** 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. */
+  slotName?: string;
+
+  // ── Action context (populated when revalidation is triggered by a server action) ──
+
+  /**
+   * Identifier of the server action that triggered revalidation.
+   * `undefined` during normal navigation (no action involved).
+   *
+   * Format: `"src/<path>#<exportName>"` — the file path is the source path
+   * 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:
+   *
+   * @example
+   * ```ts
+   * // Match a specific action
+   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart")
+   *
+   * // Match any action in the cart module
+   * revalidate(({ actionId }) => actionId?.includes("cart") ?? false)
+   *
+   * // Match any action under src/apps/store/actions/
+   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") ?? false)
+   * ```
+   */
+  actionId?: string;
+  /** 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. */
+  actionResult?: any;
+  /** FormData from the action request body. Only set for form-based actions (not inline `"use server"` actions). */
+  formData?: FormData;
+  /** HTTP method: `"GET"` for navigation, `"POST"` for server actions. */
+  method?: string;
+
+  // ── Route identity ───────────────────────────────────────────────────
+
+  /** Route name of the navigation target. Alias for `toRouteName`. */
+  routeName?: DefaultRouteName;
+  /**
+   * Route name being navigated away from.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  fromRouteName?: DefaultRouteName;
+  /**
+   * Route name being navigated to.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  toRouteName?: DefaultRouteName;
+
+  // ── Staleness signal ─────────────────────────────────────────────────
+
+  /**
+   * `true` when the browser signals that data may be stale — typically because
+   * a server action was executed in this or another tab (`_rsc_stale` header).
+   *
+   * This is NOT segment cache staleness (loaders are never segment-cached).
+   * Use this to decide whether loader data should be re-fetched after an
+   * action that may have mutated backend state.
+   */
+  stale?: boolean;
+}) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported
 

package/src/types/index.ts

@@ -2,6 +2,7 @@
 export type {
   GetRegisteredRoutes,
   DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
   DefaultEnv,
 } from "./global-namespace.js";
 // Ensure the global namespace declaration is evaluated
@@ -10,7 +11,6 @@ import "./global-namespace.js";
 // Route configuration
 export type {
   DocumentProps,
-  RouterEnv,
   ExtractParams,
   TrailingSlashMode,
   RouteConfig,

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,
-  DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
   DefaultVars,
 } from "./global-namespace.js";
+import type { RequestScope } from "./request-scope.js";
 
 /**
  * Context passed to loader functions during execution
@@ -38,28 +41,52 @@ export type LoaderContext<
   TEnv = DefaultEnv,
   TBody = unknown,
   TSearch extends SearchSchema = {},
-> = {
+> = RequestScope<TEnv> & {
   params: TParams;
-  request: Request;
-  searchParams: URLSearchParams;
+  /**
+   * Route params extracted from the URL pattern match (server-side only).
+   * Unlike `params`, these cannot be overridden by client-provided loader params.
+   * Use this when you need trusted, server-matched route params for auth or
+   * resource scoping.
+   */
+  routeParams: Record<string, string>;
   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]);
-  /** Get a cookie value from the request */
-  cookie(name: string): string | undefined;
-  /** Get all cookies from the request */
-  cookies(): Record<string, string>;
   /**
-   * 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)`. Only supported in DSL loaders on non-streaming
+   * trees (no `loading()`). Throws if called from a handler-invoked
+   * loader or when the tree uses streaming.
+   *
+   * @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", ... })
@@ -82,7 +109,7 @@ export type LoaderContext<
    */
   reverse: ScopedReverseFunction<
     Record<string, string>,
-    DefaultHandlerRouteMap
+    DefaultReverseRouteMap
   >;
 };
 
@@ -163,11 +190,11 @@ export type LoadOptions =
  *   return await db.products.findBySlug(slug);
  * });
  *
- * // Server usage
- * const cart = ctx.use(CartLoader);
+ * // Client usage (preferred — cache-safe, always fresh)
+ * const { data } = useLoader(CartLoader);
  *
- * // Client usage (fn is stripped, only name remains)
- * const cart = useLoader(CartLoader);
+ * // Server escape hatch (handler needs data directly)
+ * const cart = await ctx.use(CartLoader);
  * ```
  */
 export type LoaderDefinition<
@@ -177,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>;
 };