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

package/dist/vite/index.js

@@ -2130,7 +2130,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.115",
+  version: "0.0.0-experimental.116",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3415,10 +3415,31 @@ function createVirtualEntriesPlugin(entries, routerPathRef) {
     }
   };
 }
+function isContentHashedAssetConflict(message) {
+  if (!message) return false;
+  const match = /The emitted file "?([^"\s]+)"? overwrites a previously emitted file/.exec(
+    message
+  );
+  if (!match) return false;
+  const fileName = match[1];
+  const base = fileName.slice(fileName.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const stem = base.slice(0, dot);
+  const HASH_LEN = 8;
+  if (stem.length < HASH_LEN + 1 || stem[stem.length - HASH_LEN - 1] !== "-") {
+    return false;
+  }
+  const hash = stem.slice(-HASH_LEN);
+  return /^[A-Za-z0-9_-]+$/.test(hash) && /[A-Z0-9]/.test(hash);
+}
 function onwarn(warning, defaultHandler) {
   if (warning.code === "MODULE_LEVEL_DIRECTIVE" || warning.code === "SOURCEMAP_ERROR" || warning.code === "EMPTY_BUNDLE" || warning.code === "INEFFECTIVE_DYNAMIC_IMPORT") {
     return;
   }
+  if (warning.code === "FILE_NAME_CONFLICT" && isContentHashedAssetConflict(warning.message)) {
+    return;
+  }
   if (warning.message?.includes("Sourcemap is likely to be incorrect")) {
     return;
   }
@@ -3441,6 +3462,75 @@ function getManualChunks(id) {
   return void 0;
 }
 
+// src/vite/plugins/client-ref-hashing.ts
+import { relative } from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+var debug7 = createRangoDebugger(NS.transform);
+var CLIENT_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
+var CLIENT_IN_SERVER_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
+var FS_PREFIX = "/@fs/";
+function hashRefKey(relativeId) {
+  return createHash2("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+function computeProductionHash(projectRoot, refKey) {
+  let toHash;
+  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
+    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
+  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
+    const absPath = decodeURIComponent(
+      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
+    );
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith(FS_PREFIX)) {
+    const absPath = refKey.slice(FS_PREFIX.length - 1);
+    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith("/")) {
+    toHash = refKey.slice(1);
+  } else {
+    return refKey;
+  }
+  return hashRefKey(toHash);
+}
+var REGISTER_CLIENT_REF_RE = /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
+function transformClientRefs(code, projectRoot) {
+  if (!code.includes("registerClientReference")) return null;
+  let hasReplacement = false;
+  const result = code.replace(
+    REGISTER_CLIENT_REF_RE,
+    (match, refKey) => {
+      const hash = computeProductionHash(projectRoot, refKey);
+      if (hash === refKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    }
+  );
+  return hasReplacement ? result : null;
+}
+function hashClientRefs(projectRoot) {
+  const counter = createCounter(debug7, "hash-client-refs");
+  return {
+    name: "@rangojs/router:hash-client-refs",
+    // Run after the RSC plugin's transform (default enforce is normal)
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformClientRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    }
+  };
+}
+
 // src/vite/utils/client-chunks.ts
 var debugChunks = createRangoDebugger(NS.chunks);
 function isSharedRuntime(meta) {
@@ -3467,10 +3557,14 @@ var ROUTE_ROOT_DIRS = /* @__PURE__ */ new Set([
   "screens",
   "sections"
 ]);
-function directoryClientChunks(meta) {
+function directoryClientChunks(meta, ctx) {
   if (isSharedRuntime(meta)) {
     return void 0;
   }
+  if (ctx?.fallbackRefs.size && ctx.fallbackRefs.has(hashRefKey(meta.normalizedId))) {
+    debugChunks?.("fallback %s -> app-fallback", meta.normalizedId);
+    return "app-fallback";
+  }
   const segments = meta.normalizedId.split("/").filter(Boolean);
   const dirCount = segments.length - 1;
   if (dirCount >= 1) {
@@ -3488,9 +3582,9 @@ function directoryClientChunks(meta) {
   );
   return void 0;
 }
-function resolveClientChunks(option) {
+function resolveClientChunks(option, ctx) {
   if (!option) return void 0;
-  if (option === true) return directoryClientChunks;
+  if (option === true) return (meta) => directoryClientChunks(meta, ctx);
   return option;
 }
 
@@ -3578,7 +3672,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
 }
 
 // src/vite/plugins/cjs-to-esm.ts
-var debug7 = createRangoDebugger(NS.transform);
+var debug8 = createRangoDebugger(NS.transform);
 function createCjsToEsmPlugin() {
   return {
     name: "@rangojs/router:cjs-to-esm",
@@ -3588,7 +3682,7 @@ function createCjsToEsmPlugin() {
       if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
         const isProd = process.env.NODE_ENV === "production";
         const cjsFile = isProd ? "./cjs/react-server-dom-webpack-client.browser.production.js" : "./cjs/react-server-dom-webpack-client.browser.development.js";
-        debug7?.("cjs-to-esm entry redirect %s", id);
+        debug8?.("cjs-to-esm entry redirect %s", id);
         return {
           code: `export * from "${cjsFile}";`,
           map: null
@@ -3624,7 +3718,7 @@ function createCjsToEsmPlugin() {
           "export const $1 ="
         );
         transformed = license + "\n" + transformed;
-        debug7?.("cjs-to-esm body rewrite %s", id);
+        debug8?.("cjs-to-esm body rewrite %s", id);
         return {
           code: transformed,
           map: null
@@ -3773,72 +3867,6 @@ function walk(node, visit) {
   }
 }
 
-// src/vite/plugins/client-ref-hashing.ts
-import { relative } from "node:path";
-import { createHash as createHash2 } from "node:crypto";
-var debug8 = createRangoDebugger(NS.transform);
-var CLIENT_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
-var CLIENT_IN_SERVER_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
-var FS_PREFIX = "/@fs/";
-function computeProductionHash(projectRoot, refKey) {
-  let toHash;
-  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
-    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
-  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
-    const absPath = decodeURIComponent(
-      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
-    );
-    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
-  } else if (refKey.startsWith(FS_PREFIX)) {
-    const absPath = refKey.slice(FS_PREFIX.length - 1);
-    toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
-  } else if (refKey.startsWith("/")) {
-    toHash = refKey.slice(1);
-  } else {
-    return refKey;
-  }
-  return createHash2("sha256").update(toHash).digest("hex").slice(0, 12);
-}
-var REGISTER_CLIENT_REF_RE = /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
-function transformClientRefs(code, projectRoot) {
-  if (!code.includes("registerClientReference")) return null;
-  let hasReplacement = false;
-  const result = code.replace(
-    REGISTER_CLIENT_REF_RE,
-    (match, refKey) => {
-      const hash = computeProductionHash(projectRoot, refKey);
-      if (hash === refKey) return match;
-      hasReplacement = true;
-      return match.replace(`"${refKey}"`, `"${hash}"`);
-    }
-  );
-  return hasReplacement ? result : null;
-}
-function hashClientRefs(projectRoot) {
-  const counter = createCounter(debug8, "hash-client-refs");
-  return {
-    name: "@rangojs/router:hash-client-refs",
-    // Run after the RSC plugin's transform (default enforce is normal)
-    enforce: "post",
-    applyToEnvironment(env) {
-      return env.name === "rsc";
-    },
-    buildEnd() {
-      counter?.flush();
-    },
-    transform(code, id) {
-      const start = counter ? performance.now() : 0;
-      try {
-        const result = transformClientRefs(code, projectRoot);
-        if (result === null) return;
-        return { code: result, map: null };
-      } finally {
-        counter?.record(id, performance.now() - start);
-      }
-    }
-  };
-}
-
 // src/vite/utils/bundle-analysis.ts
 function findMatchingParenInBundle(code, openParenPos) {
   let depth = 1;
@@ -3991,7 +4019,7 @@ function checkSelfGenWrite(state, filePath, consume) {
   }
 }
 
-// src/vite/utils/manifest-utils.ts
+// src/build/prefix-tree-utils.ts
 function flattenLeafEntries(prefixTree, routeManifest, result) {
   function visit(node, ancestorStaticPrefixes) {
     const children = node.children || {};
@@ -4032,6 +4060,8 @@ function buildRouteToStaticPrefix(prefixTree, result) {
     visit(node);
   }
 }
+
+// src/vite/utils/manifest-utils.ts
 function jsonParseExpression(value) {
   const json = JSON.stringify(value);
   const escaped = json.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
@@ -4729,6 +4759,15 @@ async function discoverRouters(state, rscEnv) {
   let mergedRouteTrailingSlash = {};
   let routerMountIndex = 0;
   const allManifests = [];
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx ? (refKey) => clientChunkCtx.fallbackRefs.add(
+    computeProductionHash(state.projectRoot, refKey)
+  ) : void 0;
+  const collectFromBoundaryNode = (node) => {
+    if (collectClientFallbackRef && buildMod.collectFallbackClientRefs) {
+      buildMod.collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
   const manifestGenStart = debug10 ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
@@ -4737,10 +4776,18 @@ async function discoverRouters(state, rscEnv) {
     const manifest = generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : void 0
+      {
+        ...router.__basename ? { urlPrefix: router.__basename } : {},
+        ...collectClientFallbackRef ? { collectClientFallbackRef } : {}
+      }
     );
     routerMountIndex++;
     allManifests.push({ id, manifest });
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
     const routeCount = Object.keys(manifest.routeManifest).length;
     const staticRoutes = Object.values(manifest.routeManifest).filter(
       (p) => !p.includes(":") && !p.includes("*")
@@ -4850,26 +4897,12 @@ async function discoverRouters(state, rscEnv) {
         passthroughRouteNames,
         mergedResponseTypeRoutes
       );
+      const buildPerRouterTrie = buildMod.buildPerRouterTrie;
       for (const { id, manifest } of allManifests) {
-        if (!manifest._routeAncestry || Object.keys(manifest._routeAncestry).length === 0)
-          continue;
-        const perRouterStaticPrefix = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie ? buildPerRouterTrie(manifest) : null;
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-        const perRouterPrerenderNames = manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : void 0;
-        const perRouterPassthroughNames = manifest.passthroughRoutes ? new Set(manifest.passthroughRoutes) : void 0;
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash,
-          perRouterPrerenderNames,
-          perRouterPassthroughNames,
-          manifest.responseTypeRoutes
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }
@@ -6428,9 +6461,10 @@ async function rango(options) {
   const resolvedOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
   const showBanner = resolvedOptions.banner ?? true;
-  const clientChunks = resolveClientChunks(
-    resolvedOptions.clientChunks ?? true
-  );
+  const clientChunksOption = resolvedOptions.clientChunks ?? true;
+  const useBuiltInClientChunks = clientChunksOption === true;
+  const clientChunkCtx = useBuiltInClientChunks ? { fallbackRefs: /* @__PURE__ */ new Set() } : void 0;
+  const clientChunks = resolveClientChunks(clientChunksOption, clientChunkCtx);
   debugConfig?.("rango(%s) setup start", preset);
   const plugins = [];
   const rangoAliases = { ...getPackageAliases(), ...getVendorAliases() };
@@ -6486,6 +6520,14 @@ async function rango(options) {
             client: {
               build: {
                 rollupOptions: {
+                  // FILE_NAME_CONFLICT (and any other client-build warning) is
+                  // emitted by the CLIENT environment build, which consults THIS
+                  // env's onwarn -- Vite 8's environment builds do NOT propagate
+                  // the top-level build.rollupOptions.onwarn into the client env.
+                  // Wire it here so the suppression runs where the conflicts
+                  // originate (the top-level handler is invoked 0x for these; the
+                  // client-env handler is invoked for all of them).
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks
                   }
@@ -6614,6 +6656,14 @@ ${list}`);
             client: {
               build: {
                 rollupOptions: {
+                  // FILE_NAME_CONFLICT (and any other client-build warning) is
+                  // emitted by the CLIENT environment build, which consults THIS
+                  // env's onwarn -- Vite 8's environment builds do NOT propagate
+                  // the top-level build.rollupOptions.onwarn into the client env.
+                  // Wire it here so the suppression runs where the conflicts
+                  // originate (the top-level handler is invoked 0x for these; the
+                  // client-env handler is invoked for all of them).
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks
                   }
@@ -6727,7 +6777,8 @@ ${list}`);
       routerPathRef: discoveryRouterRef,
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
-      preset
+      preset,
+      clientChunkCtx
     })
   );
   debugConfig?.(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.115",
+  "version": "0.0.0-experimental.116",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,16 +132,6 @@
     "access": "public",
     "tag": "experimental"
   },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.26",
@@ -152,17 +142,17 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.38.0",
@@ -178,5 +168,14 @@
     "vite": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
   }
-}
+}

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`           |