@rangojs/router 0.0.0-experimental.114 → 0.0.0-experimental.116

package/skills/api-client/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: api-client
+description: Build a typed client for consuming your own response-route JSON APIs (no codegen)
+---
+
+# Typed API Client
+
+Response routes (`path.json()`) already ship typed responses — `RouteResponse<typeof patterns, "name">` resolves to the **bare payload**, inferred from your handler with no codegen. This skill wraps that inference in a small **typed client** so first-party TypeScript code calls your endpoints like functions instead of hand-writing `fetch` + URL building per call site.
+
+This is a **recipe, not a framework feature** — copy the helper below into your app. It depends only on **type-only** imports from `@rangojs/router` (`RouteResponse`, `ExtractParams`, `ProblemDetails`), which are erased at build time, so it runs anywhere a `fetch` does — **browser, worker, or server**. Nothing new to install or version.
+
+> **Scope:** the typed client is a **first-party TypeScript** convenience. External/third-party consumers use the plain wire directly — bare JSON on success, RFC 9457 `application/problem+json` on error — which needs no client. (Language-agnostic OpenAPI generation is a separate, future feature.)
+
+## What you get
+
+```ts
+const api = createApiClient(apiShopPatterns, routes, { baseUrl });
+
+await api.health.get(); // no params → callable bare
+await api.product.get({ params: { productId } }); // params typed + required
+await api.cart.post({ body: { productId, qty: 2 } }); // body sent as JSON
+//    ^ result is the bare payload type (RouteResponse), not `any`, no `.data`
+```
+
+- **Output typed** from the handler's return (`RouteResponse`), zero codegen.
+- **Params required + typed** from the route pattern (`/catalog/:productId` → `{ productId: string }`); a missing or misspelled param is a **compile error**, not a runtime 404.
+- **Autocomplete** over every route name; rename-safe.
+- **Errors throw a typed `ApiError`** carrying the `ProblemDetails` body.
+
+(`search` and `body` are _not_ route-typed — see Notes.)
+
+## The two inputs
+
+1. **The `urls()` patterns value** — the type source. `typeof apiShopPatterns` carries the per-route response payloads (`_responses`) and patterns (`_routes`).
+2. **The generated route map** — the name → pattern source. `rango generate` emits a per-module `<name>.gen.ts` exporting `routes`:
+
+```ts
+// api-shop.gen.ts (generated — do not edit)
+export const routes = {
+  catalog: "/catalog",
+  product: "/catalog/:productId",
+  cart: "/cart",
+  // ...
+} as const;
+```
+
+Routes that declare a **search schema** are generated as objects instead — `index: { path: "/", search: { q: "string" } }`. The helper accepts both the string and `{ path }` forms. If a `urls()` block is mounted under a name prefix, build a local-keyed map from your global `NamedRoutes` so the keys match the block's route names (e.g. `{ catalog: NamedRoutes["apiShop.catalog"], ... } as const`).
+
+## The helper (copy into your app)
+
+```ts
+// lib/api-client.ts
+import type {
+  RouteResponse,
+  ExtractParams,
+  ProblemDetails,
+} from "@rangojs/router";
+
+type SearchParams = Record<string, string | number | boolean>;
+
+// A generated route-map entry is a pattern string, or an object with `path`
+// (routes that declare a search schema generate the object form).
+type RouteMapEntry = string | { readonly path: string };
+type PatternOf<E> = E extends string
+  ? E
+  : E extends { readonly path: infer P extends string }
+    ? P
+    : never;
+
+// `params` is optional when the route has no *required* params (incl.
+// optional-only routes like `/:locale?`), required otherwise. Typed as
+// `ExtractParams` (not `undefined`) so optional params can still be passed.
+type Args<TPattern extends string> =
+  {} extends ExtractParams<TPattern>
+    ? {
+        params?: ExtractParams<TPattern>;
+        search?: SearchParams;
+        body?: unknown;
+      }
+    : {
+        params: ExtractParams<TPattern>;
+        search?: SearchParams;
+        body?: unknown;
+      };
+
+type Method<TPatterns, K extends string, TEntry> =
+  {} extends ExtractParams<PatternOf<TEntry>>
+    ? (args?: Args<PatternOf<TEntry>>) => Promise<RouteResponse<TPatterns, K>>
+    : (args: Args<PatternOf<TEntry>>) => Promise<RouteResponse<TPatterns, K>>;
+
+type ApiClient<TPatterns, TRouteMap extends Record<string, RouteMapEntry>> = {
+  [K in keyof TRouteMap & string]: {
+    get: Method<TPatterns, K, TRouteMap[K]>;
+    post: Method<TPatterns, K, TRouteMap[K]>;
+    put: Method<TPatterns, K, TRouteMap[K]>;
+    patch: Method<TPatterns, K, TRouteMap[K]>;
+    delete: Method<TPatterns, K, TRouteMap[K]>;
+  };
+};
+
+/** Thrown on a non-2xx response; carries the RFC 9457 problem body. */
+export class ApiError extends Error {
+  status: number;
+  problem: ProblemDetails;
+  constructor(status: number, problem: ProblemDetails) {
+    super(problem.detail || `HTTP ${status}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.problem = problem;
+  }
+}
+
+// Client-safe path builder: substitutes :params (incl. optional/constrained
+// forms) into the pattern. No dependency on the server-only createReverse.
+function fillPath(pattern: string, params?: Record<string, string>): string {
+  return pattern
+    .replace(/:([A-Za-z0-9_]+)(?:\([^)]*\))?\??/g, (_m, name: string) => {
+      const v = params?.[name];
+      return v == null ? "" : encodeURIComponent(String(v));
+    })
+    .replace(/\/{2,}/g, "/");
+}
+
+export function createApiClient<
+  TPatterns,
+  const TRouteMap extends Record<string, RouteMapEntry>,
+>(
+  _patterns: TPatterns,
+  routeMap: TRouteMap,
+  opts: { baseUrl?: string; fetch?: typeof fetch } = {},
+): ApiClient<TPatterns, TRouteMap> {
+  const doFetch = opts.fetch ?? fetch;
+  const baseUrl = opts.baseUrl ?? "";
+  const call =
+    (name: string, method: string) =>
+    async (args?: {
+      params?: Record<string, string>;
+      search?: SearchParams;
+      body?: unknown;
+    }) => {
+      const entry = routeMap[name];
+      const pattern = typeof entry === "string" ? entry : entry.path;
+      let url = baseUrl + fillPath(pattern, args?.params);
+      if (args?.search) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(args.search)) {
+          if (v != null) qs.append(k, String(v));
+        }
+        const s = qs.toString();
+        if (s) url += (url.includes("?") ? "&" : "?") + s;
+      }
+      const res = await doFetch(url, {
+        method,
+        ...(args?.body !== undefined
+          ? {
+              body: JSON.stringify(args.body),
+              headers: { "content-type": "application/json" },
+            }
+          : {}),
+      });
+      if (!res.ok) {
+        const problem = (await res.json().catch(() => ({}))) as ProblemDetails;
+        throw new ApiError(res.status, problem);
+      }
+      return res.json();
+    };
+  return new Proxy({} as any, {
+    get: (_t, name: string) => ({
+      get: call(name, "GET"),
+      post: call(name, "POST"),
+      put: call(name, "PUT"),
+      patch: call(name, "PATCH"),
+      delete: call(name, "DELETE"),
+    }),
+  }) as ApiClient<TPatterns, TRouteMap>;
+}
+```
+
+## Using it
+
+```ts
+import { apiShopPatterns } from "./urls/api-shop";
+import { routes } from "./urls/api-shop.gen";
+import { createApiClient, ApiError } from "./lib/api-client";
+
+const api = createApiClient(apiShopPatterns, routes, {
+  baseUrl: import.meta.env.VITE_API_URL ?? "",
+});
+
+try {
+  const product = await api.product.get({ params: { productId: "42" } });
+  // `product` is the handler's bare return type — e.g. `product.name` is typed.
+} catch (err) {
+  if (err instanceof ApiError && err.status === 404) {
+    console.warn(err.problem.code, err.problem.detail); // typed ProblemDetails
+  } else {
+    throw err;
+  }
+}
+```
+
+## Notes
+
+- **Client-safe by construction.** The helper imports only **types** from `@rangojs/router` (erased at build) and builds URLs itself by substituting `:params` into the pattern — it does **not** use `createReverse`, which is a server/RSC-only export that throws in the browser. So `createApiClient` works in client components, workers, and on the server alike.
+- **Params are route-typed; search and body are not.** Path params come from the route pattern (`ExtractParams`), so they are precise and required. `search` is generically typed (`Record<string, string | number | boolean>`), and `body` is `unknown` (serialized to JSON). Typed request **input** needs a declared schema layer, which is intentionally out of scope here — thread per-route schemas in yourself if you want typed search/body.
+- **Verb-agnostic wire.** Rango response routes do not dispatch on HTTP method — `.get`/`.post`/etc. set the request method but hit the same handler. Use whichever verb reads best for the operation.
+- **Path building.** `fillPath` handles standard `:param`, optional `:param?`, and constrained `:param(a|b)` forms. For exotic patterns or strict trailing-slash policies, swap in your own builder (or the router's `reverse` on the server).
+- **Want a return-based style instead of throwing?** Branch on `res.ok` yourself: the wire is the bare value on 2xx and `ProblemDetails` on non-2xx (see `/response-routes`). Wrapping the calls in a `{ ok, data } | { ok: false, error }` result type is a small variation on the same helper.
+- **Third parties.** The typed client is TypeScript-only and needs your route types. External consumers in any language use the plain wire as-is (bare JSON + problem+json); no client required.
+
+See `/response-routes` for the endpoint side and `/typesafety` for how `RouteResponse` / `PathResponse` inference works.

package/skills/mime-routes/SKILL.md

@@ -133,7 +133,7 @@ declare global {
 
 `RegisteredRoutes` is what exposes the richer routeMap entries containing
 response payload metadata. Without it, URL-pattern response lookup has paths but
-no payloads, so response types resolve to `ResponseEnvelope<never>`.
+no payloads, so response types resolve to `never`.
 
 ## How It Works
 

package/skills/rango/SKILL.md

@@ -192,6 +192,7 @@ Grouped by concern — read when you need to…
 | `/host-router`            | Multi-app host routing with domain/subdomain patterns                      |
 | `/links`                  | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
 | `/response-routes`        | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/api-client`             | Typed client for consuming your own response-route JSON APIs (recipe)      |
 | `/mime-routes`            | Content negotiation — same URL, different response types via Accept header |
 | `/streams-and-websockets` | SSE via `path.stream` and WebSocket upgrades via `path.any`                |
 | `/handler-use`            | Attach default loaders/middleware to a handler via `handler.use`           |

package/skills/response-routes/SKILL.md

@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,20 +241,23 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
+
 ### Rango.PathResponse (global lookup by URL pattern or concrete path)
 
 `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>`:
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
 // router.tsx
@@ -261,11 +275,11 @@ With that in place, look up the response type by URL pattern (ambient, no import
 ```typescript
 // After include("/api", apiPatterns) in main urls
 type Health = Rango.PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
-// RSC routes return ResponseEnvelope<never>
+// RSC routes (no JSON payload) return never
 type Home = Rango.PathResponse<"/">;
-// = ResponseEnvelope<never>
+// = never
 ```
 
 `Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
@@ -280,7 +294,7 @@ async function get<T extends Rango.Path>(
   return fetch(href(path)).then((r) => r.json());
 }
 
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -288,7 +302,7 @@ 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
+`{ createdAt: Date }` resolves to the bare `{ 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
@@ -412,13 +426,13 @@ 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 }>
+// = { views: number; visitors: number }
 
 // After mounting -- names get prefixed.
 // Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
-// otherwise it resolves to ResponseEnvelope<never>.
+// otherwise it resolves to never.
 type BlogStats = Rango.PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -462,7 +476,11 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/typesafety/SKILL.md

@@ -57,7 +57,7 @@ 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 `Rango.PathResponse` resolves to `ResponseEnvelope<never>` until you wire
+payloads — so `Rango.PathResponse` resolves to `never` until you wire
 `RegisteredRoutes`.
 
 Recommended setup:
@@ -237,7 +237,7 @@ async function get<T extends Rango.Path>(
 ): Promise<Rango.PathResponse<T>> {
   return fetch(href(path)).then((r) => r.json());
 }
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -245,7 +245,7 @@ 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
+`{ createdAt: string }` (bare value), 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

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

@@ -9,7 +9,6 @@ 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 { ResponseEnvelope } from "../urls.js";
 import type { Money, TestBindings } from "./augment.js";
 
 type Expect<T extends true> = T;
@@ -79,13 +78,13 @@ wrappedHref("/not-a-route");
 type _orderWireByPattern = Expect<
   Equal<
     Rango.PathResponse<"/orders/:id">,
-    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+    { id: string; total: number; placedAt: string }
   >
 >;
 type _orderWireByPath = Expect<
   Equal<
     Rango.PathResponse<"/orders/42">,
-    ResponseEnvelope<{ id: string; total: number; placedAt: string }>
+    { id: string; total: number; placedAt: string }
   >
 >;
 

package/src/build/collect-fallback-refs.ts

@@ -0,0 +1,107 @@
+// Collect the `"use client"` client-reference keys reachable from an error /
+// notFound boundary registration, for routing them into the dedicated
+// `app-fallback` chunk (see vite/utils/client-chunks.ts).
+//
+// A boundary registration is not always a bare client element. The common,
+// load-bearing pattern wraps the client boundary in providers a thrown handler
+// needs (the layout that would normally supply them did not mount):
+//
+//   defaultErrorBoundary: ({ error }) => (
+//     <FallbackIntl locales={...}>
+//       <ThemedError error={error} />   // <- the real "use client" boundary
+//     </FallbackIntl>
+//   )
+//
+// So the value may be (a) a handler FUNCTION returning a tree, or (b) an element
+// tree with the client boundary nested below server wrappers. We:
+//   1. If it's a function, CALL it with synthetic props to get the returned tree.
+//      This only constructs JSX — the inner components are element `type`s, never
+//      invoked — so no hooks run. Guarded: a boundary that needs a real render
+//      context (request globals, etc.) throws and is skipped (graceful: it simply
+//      stays on the default grouping, as before).
+//   2. Walk the resulting tree and report every element whose `.type` is a
+//      plugin-rsc client reference.
+//
+// Limit: a boundary that *conditionally* renders different client components based
+// on the runtime error cannot be resolved statically — only the branch taken with
+// the synthetic error is seen. Such cases fall back to the default chunk; the
+// custom `clientChunks` function is the escape hatch.
+
+const CLIENT_REF = Symbol.for("react.client.reference");
+const MAX_DEPTH = 40;
+
+// Synthetic props covering the error-boundary (`{ error, reset }`) and notFound
+// (`{ pathname }`) handler shapes. The handler destructures what it needs.
+const SYNTHETIC_PROPS = {
+  error: new Error("rango: build-time fallback-chunk discovery"),
+  reset: () => {},
+  pathname: "/",
+  info: { componentStack: "" },
+};
+
+interface MaybeElement {
+  type?: { $$typeof?: symbol; $$id?: string };
+  props?: Record<string, unknown>;
+}
+
+function isReactNodeLike(v: unknown): boolean {
+  return (
+    Array.isArray(v) ||
+    (typeof v === "object" && v !== null && "$$typeof" in (v as object))
+  );
+}
+
+function walkElementTree(
+  node: unknown,
+  report: (refKey: string) => void,
+  depth: number,
+): void {
+  if (node == null || depth > MAX_DEPTH) return;
+  if (Array.isArray(node)) {
+    for (const child of node) walkElementTree(child, report, depth + 1);
+    return;
+  }
+  if (typeof node !== "object") return;
+
+  const el = node as MaybeElement;
+  const type = el.type;
+  if (type?.$$typeof === CLIENT_REF && typeof type.$$id === "string") {
+    // $$id is `<referenceKey>#<exportName>` in build mode — keep the referenceKey.
+    report(type.$$id.split("#")[0]);
+  }
+
+  const props = el.props;
+  if (props && typeof props === "object") {
+    // Children are always nodes; other props are followed only when they look
+    // like React nodes (slots/icons), never arbitrary data objects.
+    walkElementTree(props.children, report, depth + 1);
+    for (const key in props) {
+      if (key === "children") continue;
+      const value = props[key];
+      if (isReactNodeLike(value)) walkElementTree(value, report, depth + 1);
+    }
+  }
+}
+
+/**
+ * Report every `"use client"` client-reference key reachable from a single
+ * error/notFound boundary registration (handler function or element tree).
+ */
+export function collectFallbackClientRefs(
+  boundary: unknown,
+  report: (refKey: string) => void,
+): void {
+  try {
+    let node = boundary;
+    if (typeof node === "function") {
+      node = (node as (props: unknown) => unknown)(SYNTHETIC_PROPS);
+    }
+    walkElementTree(node, report, 0);
+  } catch {
+    // The boundary needs a real render context (request globals, hooks at the
+    // top level) or its tree has hostile getters. Its client refs can't be
+    // resolved statically — skip. It stays on the default grouping (no
+    // regression vs. not collecting), and the custom clientChunks fn is the
+    // escape hatch for such cases.
+  }
+}

package/src/build/generate-manifest.ts

@@ -16,6 +16,7 @@ import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
+import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
 
 /**
  * Node in the prefix tree
@@ -290,7 +291,17 @@ export function generateManifest<TEnv>(
 export function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-  options?: { urlPrefix?: string },
+  options?: {
+    urlPrefix?: string;
+    /**
+     * Called once per `"use client"` component registered as an
+     * errorBoundary/notFoundBoundary fallback, with its client-reference key
+     * (`$$id`). Lets the build collect fallback module ids for dedicated
+     * chunking without exposing the otherwise-discarded EntryData tree. The
+     * EntryData map built below is local; this is the only seam that surfaces it.
+     */
+    collectClientFallbackRef?: (refKey: string) => void;
+  },
 ): FullManifest {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
@@ -328,6 +339,22 @@ export function generateManifestFull<TEnv>(
     },
   );
 
+  // Surface the "use client" components registered as error/notFound fallbacks
+  // (route-tree errorBoundary()/notFoundBoundary() helpers, stored on EntryData).
+  // The boundary may be a handler function and/or wrap the client boundary in
+  // server providers, so walk the whole tree (see collectFallbackClientRefs).
+  if (options?.collectClientFallbackRef) {
+    const report = options.collectClientFallbackRef;
+    const collect = (boundary: unknown[] | undefined) => {
+      for (const item of boundary ?? [])
+        collectFallbackClientRefs(item, report);
+    };
+    for (const entry of manifest.values()) {
+      collect(entry.errorBoundary);
+      collect(entry.notFoundBoundary);
+    }
+  }
+
   // Collect root-level routes and trailing slash config
   const routeTrailingSlash: Record<string, string> = {};
   for (const [name, pattern] of patternsMap.entries()) {

package/src/build/index.ts

@@ -22,7 +22,14 @@ export {
   type GeneratedManifest,
 } from "./generate-manifest.js";
 
-export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
+export {
+  buildRouteTrie,
+  buildPerRouterTrie,
+  type TrieNode,
+  type TrieLeaf,
+} from "./route-trie.js";
+
+export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
 
 export {
   writePerModuleRouteTypes,