@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/ssr/index.tsx

@@ -1,9 +1,8 @@
 import React from "react";
 import { renderSegments } from "../segment-system.js";
-import { initHandleDataSync } from "../browser/react/use-handle.js";
-import { initSegmentsSync } from "../browser/react/use-segments.js";
-import { initThemeConfigSync } from "../theme/theme-context.js";
+import { filterSegmentOrder } from "../browser/react/filter-segment-order.js";
 import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { NonceContext } from "../browser/react/nonce-context.js";
 import { NavigationStoreContext } from "../browser/react/context.js";
 import type { NavigationStoreContextValue } from "../browser/react/context.js";
 import type { HandleData } from "../browser/types.js";
@@ -34,6 +33,13 @@ interface RenderToReadableStreamOptions {
   formState?: unknown;
 }
 
+/**
+ * ReadableStream with the allReady promise added by react-dom/server.edge.
+ */
+interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
+  allReady: Promise<void>;
+}
+
 /**
  * Options for the renderHTML function
  */
@@ -50,6 +56,14 @@ export interface SSRRenderOptions {
    * Nonce for Content Security Policy (CSP)
    */
   nonce?: string;
+
+  /**
+   * SSR stream mode.
+   *
+   * - `"stream"` (default) — start flushing HTML immediately.
+   * - `"allReady"` — await `stream.allReady` before returning.
+   */
+  streamMode?: import("../router/router-options.js").SSRStreamMode;
 }
 
 /**
@@ -69,7 +83,7 @@ export interface SSRDependencies<TEnv = unknown> {
   renderToReadableStream: (
     element: React.ReactNode,
     options?: RenderToReadableStreamOptions,
-  ) => Promise<ReadableStream<Uint8Array>>;
+  ) => Promise<ReactDOMReadableStream>;
 
   /**
    * injectRSCPayload from rsc-html-stream/server
@@ -117,6 +131,7 @@ interface RscPayload {
     params?: Record<string, string>;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
+    version?: string;
   };
 }
 
@@ -138,8 +153,18 @@ async function consumeAsyncGenerator(
  * Create a minimal event controller for SSR.
  * This provides the correct pathname so useNavigation returns the right value during SSR.
  */
-function createSsrEventController(pathname: string): EventController {
-  const location = new URL(pathname, "http://localhost");
+function createSsrEventController(opts: {
+  pathname: string;
+  params?: Record<string, string>;
+  handleData?: HandleData;
+  matched?: string[];
+}): EventController {
+  const location = new URL(opts.pathname, "http://localhost");
+  let params = opts.params ?? {};
+  const handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+  };
   const state: DerivedNavigationState = {
     state: "idle",
     isStreaming: false,
@@ -150,6 +175,7 @@ function createSsrEventController(pathname: string): EventController {
 
   return {
     getState: () => state,
+    getLocation: () => location,
     subscribe: () => () => {},
     getActionState: () => ({
       state: "idle",
@@ -161,9 +187,11 @@ function createSsrEventController(pathname: string): EventController {
     subscribeToAction: () => () => {},
     subscribeToHandles: () => () => {},
     setHandleData: () => {},
-    getHandleState: () => ({ data: {}, segmentOrder: [] }),
-    setParams: () => {},
-    getParams: () => ({}),
+    getHandleState: () => handleState,
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
     setLocation: () => {},
     startNavigation: () => {
       throw new Error("Navigation not supported during SSR");
@@ -175,6 +203,7 @@ function createSsrEventController(pathname: string): EventController {
     abortAllActions: () => {},
     getCurrentNavigation: () => null,
     getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
   };
 }
 
@@ -216,7 +245,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState } = options ?? {};
+    const { nonce, formState, streamMode } = options ?? {};
 
     try {
       // Tee the stream:
@@ -231,35 +260,31 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       function SsrRoot() {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
-
-        // Initialize segments state before children render (for useSegments hook)
-        initSegmentsSync(
-          resolved.metadata?.matched,
-          resolved.metadata?.pathname,
-          resolved.metadata?.params,
-        );
-
-        // Initialize theme config for MetaTags to render theme script
         const themeConfig = resolved.metadata?.themeConfig ?? null;
-        initThemeConfigSync(themeConfig);
+        const pathname = resolved.metadata?.pathname ?? "/";
 
-        // Await handles and initialize state before children render
+        // Await handles before creating SSR event controller so hooks can
+        // read request-local handle data via NavigationStoreContext.
         // The handles property is an async generator that yields on each push
         // Memoize the promise since async generators can only be iterated once
+        let handleData: HandleData = {};
         if (resolved.metadata?.handles) {
           handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
-          const handleData = React.use(handlesPromise);
-          initHandleDataSync(handleData, resolved.metadata.matched);
+          handleData = React.use(handlesPromise);
         }
 
-        // Create SSR context with correct pathname for useNavigation
+        // Create SSR context with request-local pathname/params/handles.
         ssrContextValue ??= {
           store: null as any,
-          eventController: createSsrEventController(
-            resolved.metadata?.pathname ?? "/",
-          ),
+          eventController: createSsrEventController({
+            pathname,
+            params: resolved.metadata?.params,
+            handleData,
+            matched: resolved.metadata?.matched,
+          }),
           navigate: async () => {},
           refresh: async () => {},
+          version: resolved.metadata?.version,
         };
 
         // Build content tree from segments.
@@ -287,9 +312,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           );
         }
 
+        // Wrap with NonceContext so client components (e.g. MetaTags) can
+        // apply CSP nonces to inline scripts during SSR. Always present to
+        // match the browser-side NavigationProvider tree shape for hydration.
+        content = (
+          <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
+        );
+
         // Wrap with NavigationStoreContext for useNavigation hook
         return (
-          <NavigationStoreContext.Provider value={ssrContextValue}>
+          <NavigationStoreContext.Provider value={ssrContextValue!}>
             {content}
           </NavigationStoreContext.Provider>
         );
@@ -307,6 +339,13 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         nonce,
       });
 
+      // Wait for all Suspense boundaries to resolve when streamMode is "allReady".
+      // This buffers the entire HTML before flushing — used for bots that
+      // cannot process streamed HTML.
+      if (streamMode === "allReady") {
+        await htmlStream.allReady;
+      }
+
       // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
       return htmlStream.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
     } catch (error) {

package/src/static-handler.ts

@@ -82,6 +82,13 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
+  if (!id) {
+    throw new Error(
+      "[rsc-router] Static: missing $$id. " +
+        "Ensure the exposeInternalIds Vite plugin is configured.",
+    );
+  }
+
   return {
     __brand: "staticHandler" as const,
     $$id: id,

package/src/theme/ThemeProvider.tsx

@@ -50,7 +50,12 @@ function readThemeFromCookie(storageKey: string): string | null {
   for (const cookie of cookies) {
     const [name, ...rest] = cookie.trim().split("=");
     if (name === storageKey) {
-      return decodeURIComponent(rest.join("="));
+      const raw = rest.join("=");
+      try {
+        return decodeURIComponent(raw);
+      } catch {
+        return raw;
+      }
     }
   }
   return null;

package/src/theme/index.ts

@@ -1,9 +1,10 @@
 /**
  * Theme module exports for @rangojs/router/theme
  *
- * This module provides theme management for rsc-router:
+ * This module provides the public theme API:
  * - useTheme: Hook for accessing theme state in client components
  * - ThemeProvider: Component for manual theme provider setup (typically not needed)
+ * - ThemeScript: FOUC-prevention script component for document/head usage
  * - Types for theme configuration
  *
  * @example
@@ -43,20 +44,5 @@ export type {
   ThemeContextValue,
 } from "./types.js";
 
-// Constants (for advanced use cases)
-export {
-  THEME_DEFAULTS,
-  THEME_COOKIE,
-  resolveThemeConfig,
-} from "./constants.js";
-
-// Script generation (for advanced SSR use cases)
-export { generateThemeScript, getNonceAttribute } from "./theme-script.js";
-
-// Context (for advanced use cases)
-export {
-  ThemeContext,
-  useThemeContext,
-  initThemeConfigSync,
-  getSSRThemeConfig,
-} from "./theme-context.js";
+// Constants
+export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/src/theme/theme-context.ts

@@ -10,7 +10,7 @@
  */
 
 import { createContext, useContext, type Context } from "react";
-import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
+import type { ThemeContextValue } from "./types.js";
 
 /**
  * React context for theme state
@@ -19,33 +19,6 @@ import type { ResolvedThemeConfig, ThemeContextValue } from "./types.js";
 export const ThemeContext: Context<ThemeContextValue | null> =
   createContext<ThemeContextValue | null>(null);
 
-/**
- * SSR module-level state for theme config.
- * Populated by initThemeConfigSync before React renders.
- * Used by MetaTags during SSR to render the theme script.
- */
-let ssrThemeConfig: ResolvedThemeConfig | null = null;
-
-/**
- * Initialize theme config synchronously for SSR.
- * Called before rendering to populate state for MetaTags.
- *
- * @param config - Theme config from router, or null if theme is disabled
- */
-export function initThemeConfigSync(config: ResolvedThemeConfig | null): void {
-  ssrThemeConfig = config;
-}
-
-/**
- * Get theme config for SSR/hydration.
- * Used by MetaTags to render the theme script.
- *
- * @returns Theme config if available, null otherwise
- */
-export function getSSRThemeConfig(): ResolvedThemeConfig | null {
-  return ssrThemeConfig;
-}
-
 /**
  * Get theme context (internal use)
  * Returns null if theme is not enabled

package/src/theme/theme-script.ts

@@ -40,7 +40,8 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     for (var i = 0; i < cookies.length; i++) {
       var cookie = cookies[i].trim();
       if (cookie.indexOf(storageKey + '=') === 0) {
-        return decodeURIComponent(cookie.substring(storageKey.length + 1));
+        try { return decodeURIComponent(cookie.substring(storageKey.length + 1)); }
+        catch (e) { return cookie.substring(storageKey.length + 1); }
       }
     }
     // Fall back to localStorage

package/src/types/cache-types.ts

@@ -134,7 +134,7 @@ export interface CacheOptions<TEnv = unknown> {
    * key: (ctx) => `${ctx.env.REGION}:product:${ctx.params.id}`
    *
    * // Include cookies
-   * key: (ctx) => `${ctx.cookie('locale')}:${ctx.pathname}`
+   * key: (ctx) => `${cookies().get('locale')?.value ?? 'en'}:${ctx.pathname}`
    * ```
    */
   key?: (
@@ -145,6 +145,11 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
+   * Note: Tags are passed through to the store but built-in stores
+   * (MemorySegmentCacheStore, CFCacheStore) do not yet index or
+   * invalidate by tag. Effective tag-based invalidation requires a
+   * custom store implementation with secondary indices.
+   *
    * @example
    * ```typescript
    * // Static tags

package/src/types/error-types.ts

@@ -10,6 +10,7 @@
  * - "rendering": Invoked during SSR rendering errors (ssr/index.tsx, separate callback)
  * - "action": Invoked when server action execution fails (rsc/handler.ts, router.ts)
  * - "revalidation": Invoked when revalidation fails (router.ts, conditional with action)
+ * - "origin": Invoked when cross-origin request validation rejects a request (rsc/handler.ts)
  * - "unknown": Fallback for unclassified errors (not currently invoked)
  */
 export type ErrorPhase =
@@ -21,8 +22,10 @@ export type ErrorPhase =
   | "rendering" // During RSC/SSR rendering (SSR handler uses separate callback)
   | "action" // During server action execution
   | "revalidation" // During revalidation evaluation
+  | "cache" // During "use cache" background operations (stale revalidation, async cache writes)
   | "prerender" // During build-time pre-rendering (Vite closeBundle)
   | "static" // During build-time static handler rendering (Vite closeBundle)
+  | "origin" // During cross-origin request validation (CSRF protection)
   | "unknown"; // Fallback for unclassified errors
 
 /**

package/src/types/global-namespace.ts

@@ -52,6 +52,19 @@ export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
   ? Record<string, string>
   : RSCRouter.RegisteredRoutes;
 
+/**
+ * Default route map for reverse() surfaces.
+ * Prefers GeneratedRouteMap to avoid router.tsx -> urls.tsx -> types -> router.tsx
+ * 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;
+
 /**
  * Default route map for Handler type.
  * Uses GeneratedRouteMap (from gen file) instead of RegisteredRoutes to avoid
@@ -76,3 +89,12 @@ export type DefaultEnv = keyof RSCRouter.Env extends never
 export type DefaultVars = keyof RSCRouter.Vars extends never
   ? Record<string, any>
   : RSCRouter.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
+  ? string
+  : keyof RSCRouter.GeneratedRouteMap & string;

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,
@@ -67,6 +68,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
@@ -107,14 +167,12 @@ export type Handler<
  *
  * 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)
  * - 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>) => {
@@ -125,6 +183,7 @@ export type Handler<
  *   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)
  * }
  * ```
  */
@@ -143,13 +202,15 @@ 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.
+   * 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;
   /**
@@ -320,12 +381,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 +416,14 @@ export type HandlerContext<
    * ```
    */
   reverse: [TRouteMap] extends [never]
-    ? ScopedReverseFunction<GetRegisteredRoutes>
-    : ScopedReverseFunction<TRouteMap, GetRegisteredRoutes>;
+    ? AutofillAwareReverseFunction<
+        Record<string, string>,
+        DefaultReverseRouteMap
+      >
+    : StrictLocalAutofillGlobalReverseFunction<
+        TRouteMap,
+        DefaultReverseRouteMap
+      >;
 };
 
 /**
@@ -355,12 +436,14 @@ export type InternalHandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
 > = HandlerContext<TParams, TEnv, TSearch> & {
-  /** Raw request with all system parameters intact. */
-  _originalRequest: Request;
+  /** 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;
 };
 
 /**
@@ -457,7 +540,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
   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")
+  routeName?: DefaultRouteName; // Route name of the navigation target (alias for toRouteName)
+  // Named-route identity for both ends of a navigation transition.
+  // Undefined for unnamed internal routes (those without a `name` option).
+  fromRouteName?: DefaultRouteName; // Route name being navigated away from
+  toRouteName?: DefaultRouteName; // Route name being navigated to
   // Stale cache revalidation (SWR pattern):
   stale?: boolean; // True if this is a stale cache revalidation request
 }) => boolean | { defaultShouldRevalidate: boolean };

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

@@ -4,7 +4,7 @@ import type { ScopedReverseFunction } from "../reverse.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
 import type {
   DefaultEnv,
-  DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
   DefaultVars,
 } from "./global-namespace.js";
 
@@ -40,6 +40,13 @@ export type LoaderContext<
   TSearch extends SearchSchema = {},
 > = {
   params: TParams;
+  /**
+   * 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>;
   request: Request;
   searchParams: URLSearchParams;
   search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
@@ -50,10 +57,6 @@ export type LoaderContext<
   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)
    */
@@ -82,7 +85,7 @@ export type LoaderContext<
    */
   reverse: ScopedReverseFunction<
     Record<string, string>,
-    DefaultHandlerRouteMap
+    DefaultReverseRouteMap
   >;
 };