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

package/README.md

@@ -1014,7 +1014,7 @@ Quick rule of thumb:
 
 - `GeneratedRouteMap` (auto-generated) — use for server-side named-route typing: `Handler<"name">`, `ctx.reverse()`, `Prerender<"name">`
 - `typeof router.routeMap` — use when you need route entries with response metadata
-- `RegisteredRoutes` (manual augmentation) — use to expose `typeof router.routeMap` globally for `href()`, `PathResponse`, `ValidPaths`, and other path/response-aware utilities
+- `RegisteredRoutes` (manual augmentation) — use to expose `typeof router.routeMap` globally for `href()`, `Rango.Path`, `Rango.PathResponse`, and other path/response-aware utilities
 
 For extracted reusable loaders or middleware, prefer global dotted names on
 `ctx.reverse()` by default. If you want type-safe local names for a specific

package/dist/vite/index.js

@@ -2049,7 +2049,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.108",
+  version: "0.0.0-experimental.109",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -5266,12 +5266,17 @@ function pickForwardedRunnerConfig(config) {
   if (r.extensions !== void 0) resolve10.extensions = r.extensions;
   if (r.preserveSymlinks !== void 0)
     resolve10.preserveSymlinks = r.preserveSymlinks;
-  const userEsbuild = config.esbuild;
-  const esbuild = userEsbuild && typeof userEsbuild === "object" ? { ...userEsbuild, jsx: "automatic", jsxImportSource: "react" } : { jsx: "automatic", jsxImportSource: "react" };
+  if (r.tsconfigPaths !== void 0) resolve10.tsconfigPaths = r.tsconfigPaths;
+  const userOxc = config.oxc;
+  const userJsx = userOxc && typeof userOxc === "object" && typeof userOxc.jsx === "object" && userOxc.jsx !== null ? userOxc.jsx : {};
+  const oxc = userOxc && typeof userOxc === "object" ? {
+    ...userOxc,
+    jsx: { ...userJsx, runtime: "automatic", importSource: "react" }
+  } : { jsx: { runtime: "automatic", importSource: "react" } };
   return {
     resolve: resolve10,
     define: config.define,
-    esbuild
+    oxc
   };
 }
 
@@ -5301,9 +5306,8 @@ async function createTempRscServer(state, options = {}) {
   const resolveConfig = runnerConfig?.resolve ?? {
     alias: state.userResolveAlias
   };
-  const esbuildConfig = runnerConfig?.esbuild ?? {
-    jsx: "automatic",
-    jsxImportSource: "react"
+  const oxcConfig = runnerConfig?.oxc ?? {
+    jsx: { runtime: "automatic", importSource: "react" }
   };
   return createViteServer({
     root: state.projectRoot,
@@ -5313,7 +5317,7 @@ async function createTempRscServer(state, options = {}) {
     logLevel: "silent",
     resolve: resolveConfig,
     ...runnerConfig?.define ? { define: runnerConfig.define } : {},
-    esbuild: esbuildConfig,
+    oxc: oxcConfig,
     ...options.cacheDir && { cacheDir: options.cacheDir },
     plugins: [
       rsc({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.108",
+  "version": "0.0.0-experimental.109",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/links/SKILL.md

@@ -213,7 +213,17 @@ function GlobalNav() {
 }
 ```
 
-`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via the `Rango.Path` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+When wrapping `href()`, type the wrapper's path parameter as `Rango.Path` so it
+keeps the same generated-route validation. `Rango.Path` is ambient — no import,
+just like `Rango.Env` / `Rango.Vars`:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
 
 `href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 

package/skills/mime-routes/SKILL.md

@@ -111,13 +111,13 @@ picks among the response-type candidates directly.
 ## Type Safety For Negotiated Paths
 
 `router.named-routes.gen.ts` validates route names, params, search, `href()`, and
-`ValidPaths`, but it does not carry response payload metadata. For MIME or
+the `Rango.Path` type, but it does not carry response payload metadata. For MIME or
 response payload types, use one of these surfaces:
 
 - `RouteResponse<typeof patterns, "routeName">` for a specific response variant
   by route name. This is the clearest option when several MIME variants share
   one URL pattern.
-- `PathResponse<"/products/:id">` for global URL-pattern lookup after the app
+- `Rango.PathResponse<"/products/:id">` (ambient, no import) for global lookup by URL pattern or concrete path after the app
   registers `typeof router.routeMap`:
 
 ```typescript

package/skills/response-routes/SKILL.md

@@ -236,13 +236,14 @@ type ProductsData = RouteResponse<typeof apiPatterns, "products">;
 // = ResponseEnvelope<{ id: string; name: string; price: number }[]>
 ```
 
-### PathResponse (global lookup by URL pattern)
+### Rango.PathResponse (global lookup by URL pattern or concrete path)
 
-`PathResponse` reads from `RegisteredRoutes`, which carries response payload
-metadata. That surface is **not** auto-wired — without the augmentation below,
-`PathResponse` falls back to the generated path/search map, or to a permissive
-map when nothing is generated. Either way, it has no response payload metadata,
-so response routes resolve to `ResponseEnvelope<never>`:
+`Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
+which carries response payload metadata. That surface is **not** auto-wired —
+without the augmentation below, `Rango.PathResponse` falls back to the generated
+path/search map, or to a permissive map when nothing is generated. Either way, it
+has no response payload metadata, so response routes resolve to
+`ResponseEnvelope<never>`:
 
 ```typescript
 // router.tsx
@@ -255,20 +256,44 @@ declare global {
 }
 ```
 
-With that in place, look up the response type by URL pattern:
+With that in place, look up the response type by URL pattern (ambient, no import):
 
 ```typescript
-import type { PathResponse } from "@rangojs/router/client";
-
 // After include("/api", apiPatterns) in main urls
-type Health = PathResponse<"/api/health">;
+type Health = Rango.PathResponse<"/api/health">;
 // = ResponseEnvelope<{ status: string; timestamp: number }>
 
 // RSC routes return ResponseEnvelope<never>
-type Home = PathResponse<"/">;
+type Home = Rango.PathResponse<"/">;
 // = ResponseEnvelope<never>
 ```
 
+`Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
+wrapper whose response is inferred from the path you pass:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+
+const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+```
+
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
+return: `path.json()` serializes with `JSON.stringify`, so a handler returning
+`{ createdAt: Date }` resolves to `ResponseEnvelope<{ createdAt: string }>`. This
+runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
+`RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
+both response lookups report the identical wire shape.
+
 For local/scoped response typing without global augmentation, prefer
 `RouteResponse<typeof patterns, "routeName">` (see the section above) — it reads
 the response payload straight from the `urls()` patterns and needs no
@@ -383,16 +408,16 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { PathResponse, ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router/client";
 
 // Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
 // = ResponseEnvelope<{ views: number; visitors: number }>
 
 // After mounting -- names get prefixed.
-// PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
 // otherwise it resolves to ResponseEnvelope<never>.
-type BlogStats = PathResponse<"/blog/api/stats">;
+type BlogStats = Rango.PathResponse<"/blog/api/stats">;
 // = ResponseEnvelope<{ views: number; visitors: number }>
 
 // Params work through nested includes

package/skills/typesafety/SKILL.md

@@ -38,7 +38,7 @@ available globally.
   instance, including response-route metadata such as `{ path, response }`.
 - `RegisteredRoutes` — manual global hook for exposing `typeof router.routeMap`
   to global utilities that need the exact router-builder map, especially
-  `PathResponse`.
+  `Rango.PathResponse`.
 
 ### Generated Route Type Surfaces
 
@@ -51,13 +51,13 @@ pick the one that matches what you need to type:
 | `routes`            | per-module `*.gen.ts` (`rango generate`) | local  | local names, params, search              | the global app map                                                                               |
 | `RegisteredRoutes`  | manual `extends typeof router.routeMap`  | global | paths, params, **response payloads**     | the `Handler`/`Prerender` default (those read `GeneratedRouteMap` to avoid a `router.tsx` cycle) |
 
-Key consequence: `href()` and `ValidPaths` are typed from whichever map is
-present — they prefer `RegisteredRoutes` when you wire it, otherwise fall back to
+Key consequence: `href()` and the ambient `Rango.Path` type are typed from
+whichever map is present — they prefer `RegisteredRoutes` when you wire it, otherwise fall back to
 the auto-generated `GeneratedRouteMap`, so **`rango generate` alone gives you
 path-checked `href()`** with no manual augmentation. Response and MIME payload
 inference is the exception: it comes only from `typeof router.routeMap` (via
 `RegisteredRoutes`), because `GeneratedRouteMap` carries paths + search but no
-payloads — so `PathResponse` resolves to `ResponseEnvelope<never>` until you wire
+payloads — so `Rango.PathResponse` resolves to `ResponseEnvelope<never>` until you wire
 `RegisteredRoutes`.
 
 Recommended setup:
@@ -121,7 +121,7 @@ There are two runtime/type surfaces with similar names:
   App code should not pass or import `$$routeNames` directly.
 - `router.routeMap` is the public router instance property for type extraction.
   Use `typeof router.routeMap` when augmenting `Rango.RegisteredRoutes` for
-  global response payload helpers such as `PathResponse`.
+  global response payload helpers such as `Rango.PathResponse`.
 
 Do not document or use a public `router.routeNames` API unless one is
 intentionally added. Today, the public extraction surface is `router.routeMap`;
@@ -196,10 +196,10 @@ function ShopNav() {
 }
 ```
 
-`href()` and `ValidPaths` read from `RegisteredRoutes` when you augment it,
-otherwise from the auto-generated `GeneratedRouteMap` — so `rango generate` alone
-type-checks `href()` paths with no manual augmentation. The augmentation below is
-only needed for **`PathResponse`** (response-payload inference), which
+`href()` and the `Rango.Path` type read from `RegisteredRoutes` when you augment
+it, otherwise from the auto-generated `GeneratedRouteMap` — so `rango generate`
+alone type-checks `href()` paths with no manual augmentation. The augmentation
+below is only needed for **`Rango.PathResponse`** (response-payload inference), which
 `GeneratedRouteMap` cannot provide:
 
 ```typescript
@@ -210,6 +210,93 @@ declare global {
 }
 ```
 
+For wrapper helpers, type the path parameter as `Rango.Path`. It is ambient (no
+import) and shares `href()`'s compile-time path checking, so a wrapper stays in
+sync with your routes automatically:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
+
+For response-route payloads, `Rango.PathResponse<T>` is the ambient lookup. It
+accepts a route _pattern_ **or** a concrete path, so it also serves as the return
+type of a typed `fetch` wrapper. It only resolves once `RegisteredRoutes` carries
+response metadata:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+type Same = Rango.PathResponse<"/api/products/42">; // by concrete path
+
+// Response inferred from the concrete path passed in:
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+```
+
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` describes the JSON **wire** shape, not the handler's raw
+return. A `path.json()` handler returning `{ createdAt: Date }` resolves here to
+`ResponseEnvelope<{ createdAt: string }>`, matching what `r.json()` yields. This
+is applied via the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). A separate
+`Rango.FlightSerialize<T>` models the higher-fidelity RSC Flight boundary
+(loaders / RSC props, where `Date` is preserved) — do **not** use it for
+`path.json()`.
+
+### Overriding serialization globally
+
+For your own types, the zero-config way to control the JSON wire shape is a
+`toJSON()` method — `Rango.JsonSerialize` honors it, and it matches the runtime
+exactly (`JSON.stringify` calls `toJSON()`):
+
+```typescript
+class Money {
+  constructor(private cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+// Rango.JsonSerialize<Money> is number; Rango.PathResponse reflects it.
+```
+
+To override a transform for types you **don't** own (or for the Flight boundary,
+which has no `toJSON()`), augment its override slot. Because `Rango.JsonSerialize`
+/ `Rango.FlightSerialize` are type _aliases_ (TS can't merge those), you provide a
+single member that is your **complete** transform, delegating to the built-in for
+the cases you don't change:
+
+```typescript
+declare global {
+  namespace Rango {
+    interface JsonSerializeOverride<T> {
+      app: T extends Decimal ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
+  }
+}
+// Rango.JsonSerialize<Decimal> -> string; Rango.FlightSerialize<Money> -> number;
+// everything else stays on the built-in, recursively (nested fields too).
+```
+
+Rules: provide **exactly one** member (the slot is read as
+`Override<T>[keyof Override<T>]`, so multiple members union and conflict).
+Overrides win over `toJSON()` and apply at every nesting level. Caveat for JSON:
+the `path.json()` runtime is plain `JSON.stringify`, which only honors `toJSON()`,
+so a `JsonSerializeOverride` that disagrees with what the runtime emits will lie —
+prefer `toJSON()` for your own types and use the slot only for types you can't
+modify.
+
 See `/links` for full URL generation guide.
 
 ## Environment Type Setup
@@ -814,9 +901,9 @@ export default router;
 // 4. Run `npx rango generate src/router.tsx` to generate
 //    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
 //    No manual RegisteredRoutes declaration is needed for named-route handlers,
-//    ctx.reverse, prerender, href(), or ValidPaths. Add `RegisteredRoutes
+//    ctx.reverse, prerender, href(), or Rango.Path. Add `RegisteredRoutes
 //    extends typeof router.routeMap` when global response payload helpers such
-//    as PathResponse need the richer router.routeMap metadata.
+//    as Rango.PathResponse need the richer router.routeMap metadata.
 
 // 5. loaders/*.ts - Type-safe loaders
 export const ProductLoader = createLoader(async (ctx) => {

package/src/__augment-tests__/augment.ts

@@ -19,10 +19,42 @@ export interface TestVars {
   requestId?: string;
 }
 
+/**
+ * A userland domain type that controls its own JSON wire shape via `toJSON()`.
+ * This is the augmentation hook: `Rango.JsonSerialize` honors `toJSON()`, so a
+ * consumer adjusts how their type serializes with no registry API.
+ */
+export class Money {
+  constructor(public cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+
+/**
+ * Mirrors `typeof router.routeMap`: the same routes as the generated map, plus a
+ * response route whose payload carries a userland class (`Money`, with
+ * `toJSON()`) and a `Date` — used to assert `Rango.PathResponse` reports the
+ * serialized JSON wire shape.
+ */
+export interface TestRegisteredRoutes {
+  readonly home: "/";
+  readonly "blog.post": "/blog/:slug";
+  readonly search: {
+    readonly path: "/search";
+    readonly search: { readonly q: "string"; readonly page: "number?" };
+  };
+  readonly order: {
+    readonly path: "/orders/:id";
+    readonly response: { id: string; total: Money; placedAt: Date };
+  };
+}
+
 declare global {
   namespace Rango {
     interface Env extends TestBindings {}
     interface Vars extends TestVars {}
+    interface RegisteredRoutes extends TestRegisteredRoutes {}
     // Mirrors the shape emitted into router.named-routes.gen.ts: plain string
     // patterns, plus { path, search } objects for routes with a search schema.
     interface GeneratedRouteMap {
@@ -33,5 +65,17 @@ declare global {
         readonly search: { readonly q: "string"; readonly page: "number?" };
       };
     }
+
+    // Userland serialization overrides: full-transform replacement that
+    // special-cases one type and delegates the rest to the built-in. Isolated to
+    // this augment-check program, so the main suite's built-in behavior (e.g.
+    // JsonSerialize<bigint> = never) is unaffected — demonstrating overrides are
+    // per-project augmentation.
+    interface JsonSerializeOverride<T> {
+      app: T extends bigint ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
   }
 }

package/src/__augment-tests__/augmented.check.ts

@@ -9,7 +9,8 @@ import "./augment.js";
 import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import { href } from "../href-client.js";
-import type { TestBindings } from "./augment.js";
+import type { ResponseEnvelope } from "../urls.js";
+import type { Money, TestBindings } from "./augment.js";
 
 type Expect<T extends true> = T;
 type Equal<A, B> =
@@ -51,7 +52,7 @@ type _search = Expect<
   Equal<RouteSearchParams<"search">, { q: string | undefined; page?: number }>
 >;
 
-// href / ValidPaths read GeneratedRouteMap even without a manual RegisteredRoutes
+// href / Rango.Path read GeneratedRouteMap even without a manual RegisteredRoutes
 // augmentation — this is the core of the "rango generate alone enables typed
 // href()" guarantee. The paths below come from the generated map in augment.ts.
 href("/");
@@ -60,5 +61,57 @@ href("/search");
 // @ts-expect-error - path is not in the generated route map
 href("/not-a-route");
 
+// Rango.Path is the ambient input type for wrapper functions around href().
+// No import needed — it reads the same generated map href() does.
+function wrappedHref(path: Rango.Path): string {
+  return href(path);
+}
+const arrowHref = (path: Rango.Path): string => href(path);
+
+wrappedHref("/blog/anything");
+arrowHref("/search?q=hello");
+// @ts-expect-error - wrapper preserves the same generated-map validation
+wrappedHref("/not-a-route");
+
+// Userland serialization augmentation: a consumer's custom class adjusts its JSON
+// wire shape via toJSON(), and Rango.PathResponse reports the serialized payload
+// (Money -> number, Date -> string) — both by pattern and by concrete path.
+type _orderWireByPattern = Expect<
+  Equal<
+    Rango.PathResponse<"/orders/:id">,
+    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+  >
+>;
+type _orderWireByPath = Expect<
+  Equal<
+    Rango.PathResponse<"/orders/42">,
+    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+  >
+>;
+
+// Project serialization overrides: the consumer augments JsonSerializeOverride /
+// FlightSerializeOverride (see augment.ts) with a full transform that delegates to
+// the built-in, and the transforms honor it — winning over the built-in rules.
+// bigint normally JSON-serializes to `never`; Money is a class React Flight would
+// otherwise reject structurally. Delegation keeps every other type (incl. the
+// /orders payload above) on the built-in behavior.
+type _jsonOverride = Expect<Equal<Rango.JsonSerialize<bigint>, string>>;
+type _jsonOverrideNested = Expect<
+  Equal<
+    Rango.JsonSerialize<{ id: bigint; name: string }>,
+    { id: string; name: string }
+  >
+>;
+type _flightOverride = Expect<Equal<Rango.FlightSerialize<Money>, number>>;
+
 // Reference the top-level assertion aliases so they are unambiguously evaluated.
-export type _Assertions = [_routeName, _params, _search];
+export type _Assertions = [
+  _routeName,
+  _params,
+  _search,
+  _orderWireByPattern,
+  _orderWireByPath,
+  _jsonOverride,
+  _jsonOverrideNested,
+  _flightOverride,
+];

package/src/browser/react/use-handle.ts

@@ -32,27 +32,35 @@ import { shallowEqual } from "./shallow-equal.js";
  * const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
  * ```
  */
-export function useHandle<T, A>(handle: Handle<T, A>): A;
+export function useHandle<T, A>(handle: Handle<T, A>): Rango.FlightSerialize<A>;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector: (data: A) => S,
+  selector: (data: Rango.FlightSerialize<A>) => S,
 ): S;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector?: (data: A) => S,
-): A | S {
+  selector?: (data: Rango.FlightSerialize<A>) => S,
+): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
   // Initial state from context event controller, or empty fallback without provider.
-  const [value, setValue] = useState<A | S>(() => {
+  const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
-      const collected = collectHandleData(handle, {}, []);
+      const collected = collectHandleData(
+        handle,
+        {},
+        [],
+      ) as Rango.FlightSerialize<A>;
       return selector ? selector(collected) : collected;
     }
 
     // On client, use event controller state
     const state = ctx.eventController.getHandleState();
-    const collected = collectHandleData(handle, state.data, state.segmentOrder);
+    const collected = collectHandleData(
+      handle,
+      state.data,
+      state.segmentOrder,
+    ) as Rango.FlightSerialize<A>;
     return selector ? selector(collected) : collected;
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -76,7 +84,7 @@ export function useHandle<T, A, S>(
       handle,
       currentHandleState.data,
       currentHandleState.segmentOrder,
-    );
+    ) as Rango.FlightSerialize<A>;
     const currentValue = selectorRef.current
       ? selectorRef.current(currentCollected)
       : currentCollected;
@@ -93,7 +101,7 @@ export function useHandle<T, A, S>(
         handle,
         state.data,
         state.segmentOrder,
-      );
+      ) as Rango.FlightSerialize<A>;
       const nextValue = selectorRef.current
         ? selectorRef.current(collected)
         : collected;

package/src/client.tsx

@@ -409,13 +409,10 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
-// Type-safe href for client-side path validation
-export {
-  href,
-  type ValidPaths,
-  type PatternToPath,
-  type PathResponse,
-} from "./href-client.js";
+// Type-safe href for client-side path validation. The path and response types
+// are ambient as `Rango.Path` / `Rango.PathResponse` (declared in
+// href-client.ts) — no import needed.
+export { href, type PatternToPath } from "./href-client.js";
 
 // Response envelope types for consuming JSON response routes
 export type { ResponseEnvelope, ResponseError } from "./urls.js";