@rangojs/router 0.0.0-experimental.107 → 0.0.0-experimental.109

package/src/serialize.ts

@@ -0,0 +1,243 @@
+/**
+ * Wire-type serialization transforms.
+ *
+ * The type a handler or loader returns on the server is frequently NOT the type
+ * a client receives after serialization. These transforms model that boundary so
+ * consumer-facing types (e.g. `Rango.PathResponse`) describe the wire value, not
+ * the source value.
+ *
+ * Two serializers, two transforms — they are intentionally NOT interchangeable:
+ *
+ * - `JsonSerialize<T>` models plain `JSON.stringify` (`path.json()` /
+ *   `fetch().then(r => r.json())`). Lossy: `Date -> string`, `undefined` /
+ *   functions / symbols dropped, `Map`/`Set` -> `{}`. `bigint` *throws* (no wire
+ *   value), so it collapses the whole result to `never`. Honors `toJSON()`.
+ * - `FlightSerialize<T>` models React RSC Flight (loaders, RSC props, cache).
+ *   High fidelity: `Date`/`Map`/`Set`/`bigint`/typed arrays/`Promise` are
+ *   preserved; ordinary functions and non-global symbols do not cross.
+ *
+ * ## Overriding (full-transform replacement)
+ *
+ * Because `Rango.JsonSerialize` / `Rango.FlightSerialize` are type *aliases*, TS
+ * cannot let you redefine them directly (aliases don't merge). Instead each alias
+ * consults a generic override slot — augment it with a single member that is your
+ * complete transform. Delegate to the built-in for the cases you don't change:
+ *
+ * ```ts
+ * declare global {
+ *   namespace Rango {
+ *     interface FlightSerializeOverride<T> {
+ *       app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+ *     }
+ *   }
+ * }
+ * // now Rango.FlightSerialize<Money> is number; everything else is the built-in.
+ * ```
+ *
+ * Provide exactly one member: the slot is read as `Override<T>[keyof Override<T>]`,
+ * so multiple members union (and conflict). The built-in recurses through the
+ * override-aware alias, so an override applies at every nesting level.
+ */
+
+import type { ReactNode } from "react";
+
+type JsonPrimitive = string | number | boolean | null;
+
+type AnyFunction = (...args: never[]) => unknown;
+
+// --- JSON ---------------------------------------------------------------------
+
+/**
+ * Internal marker for a value that makes `JSON.stringify` throw (`bigint`, or a
+ * `toJSON()` returning one). Distinct from `never`, which means "omitted":
+ * `undefined`/function/symbol-valued keys are dropped, and such array slots
+ * become `null`. A throwing value has no valid JSON wire form, so it propagates
+ * up through every container and is excluded at the public boundary (`bigint`
+ * alone -> `never`; `{ id: bigint }` -> `never`).
+ */
+declare const JSON_THROWS: unique symbol;
+type JsonThrows = typeof JSON_THROWS;
+
+/** True if union `U` contains the throw marker. */
+type HasThrow<U> = [Extract<U, JsonThrows>] extends [never] ? false : true;
+
+/** Map a JSON array/tuple: propagate a throw; else omitted elements become null. */
+type JsonSerializeArray<T extends readonly unknown[]> =
+  HasThrow<{ [K in keyof T]: JsonRawResolve<T[K]> }[number]> extends true
+    ? JsonThrows
+    : {
+        [K in keyof T]: [JsonRawResolve<T[K]>] extends [never]
+          ? null
+          : JsonRawResolve<T[K]>;
+      };
+
+/** Map a JSON object: propagate a throw; else drop omitted keys. */
+type JsonSerializeObject<T> =
+  HasThrow<{ [K in keyof T]: JsonRawResolve<T[K]> }[keyof T]> extends true
+    ? JsonThrows
+    : {
+        [K in keyof T as [JsonRawResolve<T[K]>] extends [never]
+          ? never
+          : K]: JsonRawResolve<T[K]>;
+      };
+
+/**
+ * Built-in JSON rules, *raw* (may yield the throw marker). Honors `toJSON()` (so
+ * `Date -> string` and any class with `toJSON()` serialize correctly), preserves
+ * JSON primitives and literals, omits functions / symbols / `undefined`,
+ * collapses `Map`/`Set` to `{}`, and marks `bigint` as throwing. Recurses through
+ * the override-aware resolver, so registered overrides apply at every level.
+ */
+type JsonSerializeBuiltinRaw<T> = T extends {
+  toJSON(...args: never[]): infer R;
+}
+  ? JsonRawResolve<R>
+  : T extends JsonPrimitive
+    ? T
+    : T extends bigint
+      ? JsonThrows
+      : T extends AnyFunction
+        ? never
+        : T extends symbol
+          ? never
+          : T extends undefined
+            ? never
+            : T extends readonly unknown[]
+              ? JsonSerializeArray<T>
+              : T extends ReadonlyMap<unknown, unknown>
+                ? {}
+                : T extends ReadonlySet<unknown>
+                  ? {}
+                  : T extends object
+                    ? JsonSerializeObject<T>
+                    : never;
+
+/** Override-aware raw JSON resolution (the recursion entry). */
+type JsonRawResolve<T> = [keyof Rango.JsonSerializeOverride<T>] extends [never]
+  ? JsonSerializeBuiltinRaw<T>
+  : Rango.JsonSerializeOverride<T>[keyof Rango.JsonSerializeOverride<T>];
+
+/**
+ * Model the result of round-tripping a value through `JSON.stringify` /
+ * `JSON.parse`. A registered `Rango.JsonSerializeOverride` replaces the transform
+ * wholesale; otherwise the built-in rules apply. Throwing values collapse to
+ * `never`.
+ */
+export type JsonSerialize<T> = Exclude<JsonRawResolve<T>, JsonThrows>;
+
+// --- Flight -------------------------------------------------------------------
+
+/**
+ * Built-in Flight rules. Mirrors React's `ReactClientValue` contract: primitives
+ * including `bigint`, `undefined`, `null`, symbols, `Date`, `ArrayBuffer` and
+ * typed-array views, `Map`, `Set`, `FormData`, `Blob`, `Promise`,
+ * `ReadableStream`, and (async) iterables are preserved; ordinary functions
+ * resolve to `never`. JSX (`ReactNode`, and the async-node union
+ * `ReactNode | Promise<ReactNode>`) is preserved as-is via a non-distributive
+ * leaf, so handle/loader returns that carry JSX round-trip unchanged. Recurses
+ * through the override-aware `FlightSerialize`.
+ *
+ * The source of truth is React's own contract, which is intentionally NOT
+ * semver-stable across RSC framework APIs — this tracks the React version Rango
+ * pins. See:
+ * https://react.dev/reference/rsc/use-client#serializable-types-returned-by-server-components
+ *
+ * Type-level limitations (not detectable structurally, so not modeled): class
+ * instances and null-prototype objects are rejected by React at runtime but pass
+ * here as their structural shape; non-global symbols are rejected at runtime but
+ * `symbol` is preserved here; Server Functions would need an override to be
+ * distinguished from ordinary functions (which resolve to `never`).
+ */
+type FlightSerializeBuiltinRaw<T> = [T] extends [ReactNode | Promise<ReactNode>]
+  ? T
+  : T extends string | number | boolean | bigint | symbol | null | undefined
+    ? T
+    : T extends AnyFunction
+      ? never
+      : T extends Date
+        ? Date
+        : T extends ArrayBuffer
+          ? ArrayBuffer
+          : T extends ArrayBufferView
+            ? T
+            : T extends FormData
+              ? FormData
+              : T extends Blob
+                ? Blob
+                : T extends Map<infer K, infer V>
+                  ? Map<FlightSerialize<K>, FlightSerialize<V>>
+                  : T extends Set<infer V>
+                    ? Set<FlightSerialize<V>>
+                    : T extends Promise<infer V>
+                      ? Promise<FlightSerialize<V>>
+                      : T extends ReadableStream<infer V>
+                        ? ReadableStream<FlightSerialize<V>>
+                        : T extends readonly unknown[]
+                          ? { [K in keyof T]: FlightSerialize<T[K]> }
+                          : T extends AsyncIterable<infer V>
+                            ? AsyncIterable<FlightSerialize<V>>
+                            : T extends Iterable<infer V>
+                              ? Iterable<FlightSerialize<V>>
+                              : T extends object
+                                ? { [K in keyof T]: FlightSerialize<T[K]> }
+                                : never;
+
+/**
+ * Model React RSC Flight serialization. A registered `Rango.FlightSerializeOverride`
+ * replaces the transform wholesale; otherwise the built-in rules apply.
+ */
+export type FlightSerialize<T> = [
+  keyof Rango.FlightSerializeOverride<T>,
+] extends [never]
+  ? FlightSerializeBuiltinRaw<T>
+  : Rango.FlightSerializeOverride<T>[keyof Rango.FlightSerializeOverride<T>];
+
+// Module-scoped aliases so the ambient `Rango.*` members below can reference the
+// module-level transforms without the global namespace shadowing the names.
+type GlobalJsonSerialize<T> = JsonSerialize<T>;
+type GlobalJsonSerializeBuiltin<T> = JsonSerializeBuiltinRaw<T>;
+type GlobalFlightSerialize<T> = FlightSerialize<T>;
+type GlobalFlightSerializeBuiltin<T> = FlightSerializeBuiltinRaw<T>;
+
+/**
+ * Ambient serialization transforms and their override slots on the `Rango`
+ * namespace. Available with no import wherever the router's types are in scope,
+ * alongside `Rango.Path` / `Rango.PathResponse`.
+ *
+ * `Rango.JsonSerialize` is what `Rango.PathResponse` applies; `Rango.FlightSerialize`
+ * is exposed for RSC/loader/cache wire types and must NOT be used for `path.json()`.
+ * `Rango.JsonSerializeBuiltin` / `Rango.FlightSerializeBuiltin` are the defaults,
+ * exported so an override can delegate to them.
+ */
+declare global {
+  namespace Rango {
+    /**
+     * Full-transform override slot for `Rango.JsonSerialize`. Empty by default;
+     * augment with one member that is your complete transform (delegate to
+     * `Rango.JsonSerializeBuiltin<T>` for the cases you don't change).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface JsonSerializeOverride<T> {}
+
+    /**
+     * Full-transform override slot for `Rango.FlightSerialize`. Empty by default;
+     * augment with one member that is your complete transform (delegate to
+     * `Rango.FlightSerializeBuiltin<T>` for the cases you don't change).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface FlightSerializeOverride<T> {}
+
+    /** Wire type after `JSON.stringify` (`path.json()` / `fetch().json()`). */
+    type JsonSerialize<T> = GlobalJsonSerialize<T>;
+    /**
+     * Built-in `JsonSerialize` rules, for an override to delegate to. Raw: a
+     * `bigint`-bearing type yields the internal throw marker here, which
+     * `Rango.JsonSerialize` excludes to `never` at the boundary.
+     */
+    type JsonSerializeBuiltin<T> = GlobalJsonSerializeBuiltin<T>;
+    /** Wire type after RSC Flight serialization (loaders / RSC props / cache). */
+    type FlightSerialize<T> = GlobalFlightSerialize<T>;
+    /** Built-in `FlightSerialize` rules, for an override to delegate to. */
+    type FlightSerializeBuiltin<T> = GlobalFlightSerializeBuiltin<T>;
+  }
+}

package/src/server/context.ts

@@ -40,7 +40,7 @@ export interface MetricsStore {
   metrics: PerformanceMetric[];
 }
 // ============================================================================
-//  RSC Router Context
+//  Rango Context
 // ============================================================================
 
 /**
@@ -303,7 +303,7 @@ interface HelperContext {
 // hold references to the old instance — causing getStore() to return
 // undefined even inside a run() callback.
 const RSC_CONTEXT_KEY = Symbol.for("rangojs-router:rsc-context");
-export const RSCRouterContext: AsyncLocalStorage<HelperContext> = ((
+export const RangoContext: AsyncLocalStorage<HelperContext> = ((
   globalThis as any
 )[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage<HelperContext>());
 
@@ -330,12 +330,12 @@ export const getContext = (): {
     callback: (...args: any[]) => T,
   ) => T;
 } => {
-  const context = RSCRouterContext;
+  const context = RangoContext;
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
-      let store = RSCRouterContext.getStore();
+      let store = RangoContext.getStore();
       if (!store) {
         store = {
           manifest: new Map<string, EntryData>(),
@@ -355,7 +355,7 @@ export const getContext = (): {
       const store = context.getStore();
       if (!store) {
         throw new Error(
-          "RSC Router context store is not available. Make sure to run within RSC Router context.",
+          "Rango context store is not available. Make sure to run within Rango context.",
         );
       }
       return store;
@@ -372,7 +372,7 @@ export const getContext = (): {
       type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
+      invariant(store, "No context RangoContext available");
       store.counters[type] ??= 0;
       const index = store.counters[type];
       store.counters[type] = index + 1;
@@ -382,7 +382,7 @@ export const getContext = (): {
       type: "layout" | "parallel" | "route" | "loader" | "cache",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
+      invariant(store, "No context RangoContext available");
 
       const parent = store.parent;
       const prefix =
@@ -502,7 +502,7 @@ export function runWithPrefixes<T>(
   namePrefix: string | undefined,
   callback: () => T,
 ): T {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   if (!store) {
     throw new Error("runWithPrefixes must be called within router context");
   }
@@ -547,7 +547,7 @@ export function runWithPrefixes<T>(
         ? (store.rootScoped ?? false)
         : store.rootScoped;
 
-  return RSCRouterContext.run(
+  return RangoContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
@@ -562,7 +562,7 @@ export function runWithPrefixes<T>(
  * Get current URL prefix from context
  */
 export function getUrlPrefix(): string {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.urlPrefix || "";
 }
 
@@ -570,7 +570,7 @@ export function getUrlPrefix(): string {
  * Get current name prefix from context
  */
 export function getNamePrefix(): string | undefined {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.namePrefix;
 }
 
@@ -579,7 +579,7 @@ export function getNamePrefix(): string | undefined {
  * Returns true at root or inside { name: "" } includes, false inside named includes.
  */
 export function getRootScoped(): boolean {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.rootScoped ?? true;
 }
 
@@ -676,7 +676,7 @@ export function getParallelSlotCount(
  * ```
  */
 export function track(label: string, depth?: number): () => void {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
   if (!store?.metrics?.enabled) {
@@ -699,8 +699,8 @@ export function track(label: string, depth?: number): () => void {
 
 /**
  * Separate ALS for tracking loader execution scope.
- * Uses a dedicated ALS (not RSCRouterContext) to avoid issues with
- * nested RSCRouterContext.run() calls in Vite's module runner.
+ * Uses a dedicated ALS (not RangoContext) to avoid issues with
+ * nested RangoContext.run() calls in Vite's module runner.
  */
 const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
 const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
@@ -713,7 +713,7 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
  * (never cached), so non-cacheable reads are safe.
  */
 export function isInsideCacheScope(): boolean {
-  if (RSCRouterContext.getStore()?.insideCacheScope !== true) return false;
+  if (RangoContext.getStore()?.insideCacheScope !== true) return false;
   // Loaders are always fresh — even inside a cache() boundary, the loader
   // function re-executes on every request. Skip the guard when running
   // inside a loader.

package/src/static-handler.ts

@@ -96,7 +96,7 @@ export function Static<TParams extends Record<string, any>>(
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
+      "[rango] Static: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }

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

@@ -43,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
@@ -767,7 +767,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.
@@ -775,7 +775,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/urls/path-helper-types.ts

@@ -264,7 +264,7 @@ export type PathHelpers<TEnv> = {
    * Define an intercepting route for soft navigation
    * Note: routeName must match a named path() in this urlpatterns
    */
-  intercept: keyof RSCRouter.GeneratedRouteMap extends never
+  intercept: keyof Rango.GeneratedRouteMap extends never
     ? (
         slotName: `@${string}`,
         routeName: string,
@@ -273,7 +273,7 @@ export type PathHelpers<TEnv> = {
       ) => InterceptItem
     : (
         slotName: `@${string}`,
-        routeName: (keyof RSCRouter.GeneratedRouteMap & string) | `.${string}`,
+        routeName: (keyof Rango.GeneratedRouteMap & string) | `.${string}`,
         handler: ReactNode | Handler<any, any, TEnv>,
         use?: () => InterceptUseItem[],
       ) => InterceptItem;

package/src/urls/pattern-types.ts

@@ -88,6 +88,40 @@ export interface UrlPatterns<
   readonly _responses?: TResponses;
 }
 
+/**
+ * Extract the phantom env type carried by a UrlPatterns value.
+ */
+export type UrlPatternsEnv<T> =
+  T extends UrlPatterns<infer TEnv, any, any> ? TEnv : never;
+
+/**
+ * Guards `routes()` env compatibility without over-constraining.
+ *
+ * - An env-agnostic block (its env is `unknown` — e.g. a shared urls() module,
+ *   or an app that does not augment `Rango.Env`) attaches to any router.
+ * - A block carrying a concrete env is accepted only when the router env
+ *   (`TRouterEnv`) satisfies it; resolves to `never` otherwise, so a
+ *   `urls<{ DB: D1Database }>()` cannot be mounted on a `createRouter<{}>()`.
+ *
+ * Use as `patterns: T & EnvCompatible<T, TEnv>` so `T` still infers from the
+ * argument — a bare `EnvCompatible<T, TEnv>` parameter sits in a non-inferrable
+ * conditional position and would collapse `T` to its constraint.
+ *
+ * Known limitation: `TRouterEnv extends ...` distributes over a union router env,
+ * so a `urls<A>()` block is accepted on `createRouter<A | B>()` even though the
+ * `B` arm cannot supply `A`'s env. Suppressing distribution with
+ * `[TRouterEnv] extends [...]` would close that edge but breaks the common
+ * generic-`TEnv` call sites (a deferred type parameter can't resolve the tuple
+ * conditional, so the intersection stops reducing to `T`). A router has one env,
+ * so a union env is not a supported pattern; the distributive form is kept.
+ */
+export type EnvCompatible<TPatterns, TRouterEnv> =
+  unknown extends UrlPatternsEnv<TPatterns>
+    ? TPatterns
+    : TRouterEnv extends UrlPatternsEnv<TPatterns>
+      ? TPatterns
+      : never;
+
 /**
  * Options for include()
  */

package/src/urls/type-extraction.ts

@@ -1,4 +1,5 @@
 import type { ExtractParams } from "../types.js";
+import type { JsonSerialize } from "../serialize.js";
 import type {
   TypedRouteItem,
   TypedIncludeItem,
@@ -362,11 +363,15 @@ export type ResponseEnvelope<T> =
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
  * // ResponseEnvelope<{ status: string; timestamp: number }>
  * ```
+ *
+ * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
+ * `Rango.PathResponse` and what `fetch().then(r => r.json())` actually yields —
+ * e.g. a `Date` field resolves as `string`.
  */
 export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<Exclude<R[TName], Response>>
+    ? ResponseEnvelope<JsonSerialize<Exclude<R[TName], Response>>>
     : never
   : never;

package/src/use-loader.tsx

@@ -501,7 +501,7 @@ function useLoaderInternal<T>(
 export function useLoader<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
-): UseLoaderResult<T> {
+): UseLoaderResult<Rango.FlightSerialize<T>> {
   const result = useLoaderInternal(loader, options);
 
   // Strict mode: throw if data is not in context
@@ -513,7 +513,7 @@ export function useLoader<T>(
     );
   }
 
-  return result as UseLoaderResult<T>;
+  return result as UseLoaderResult<Rango.FlightSerialize<T>>;
 }
 
 /**
@@ -565,6 +565,8 @@ export function useLoader<T>(
 export function useFetchLoader<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
-): UseFetchLoaderResult<T> {
-  return useLoaderInternal(loader, options);
+): UseFetchLoaderResult<Rango.FlightSerialize<T>> {
+  return useLoaderInternal(loader, options) as UseFetchLoaderResult<
+    Rango.FlightSerialize<T>
+  >;
 }