@rangojs/router 0.5.1 → 0.5.2

package/dist/vite/index.js

@@ -22,26 +22,26 @@ function createRangoDebugger(namespace) {
   if (shadow.enabled) return shadow;
   return void 0;
 }
-async function timed(debug12, label, fn) {
-  if (!debug12) return await fn();
+async function timed(debug13, label, fn) {
+  if (!debug13) return await fn();
   const start = performance.now();
   try {
     return await fn();
   } finally {
-    debug12("%s (%sms)", label, (performance.now() - start).toFixed(1));
+    debug13("%s (%sms)", label, (performance.now() - start).toFixed(1));
   }
 }
-function timedSync(debug12, label, fn) {
-  if (!debug12) return fn();
+function timedSync(debug13, label, fn) {
+  if (!debug13) return fn();
   const start = performance.now();
   try {
     return fn();
   } finally {
-    debug12("%s (%sms)", label, (performance.now() - start).toFixed(1));
+    debug13("%s (%sms)", label, (performance.now() - start).toFixed(1));
   }
 }
-function createCounter(debug12, label) {
-  if (!debug12) return void 0;
+function createCounter(debug13, label) {
+  if (!debug13) return void 0;
   let n = 0;
   let totalMs = 0;
   let slowestMs = 0;
@@ -75,7 +75,7 @@ function createCounter(debug12, label) {
     },
     flush() {
       if (n === 0) return;
-      debug12(
+      debug13(
         "%s: %d files, %sms total, slowest %sms %s",
         label,
         n,
@@ -446,6 +446,11 @@ function findCallParenAfterGenerics(code, afterCalleeIndex) {
   return -1;
 }
 
+// src/vite/plugins/server-reference-pattern.ts
+function registerServerReferenceRegex() {
+  return /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+}
+
 // src/vite/plugins/expose-action-id.ts
 init_debug();
 var debug = createRangoDebugger(NS.transform);
@@ -515,7 +520,7 @@ function applyRegisterReferenceWrapping(code, s, hashToFileMap) {
   if (!code.includes("registerServerReference(")) {
     return false;
   }
-  const pattern = /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
+  const pattern = registerServerReferenceRegex();
   let hasChanges = false;
   let match;
   while ((match = pattern.exec(code)) !== null) {
@@ -627,6 +632,17 @@ function exposeActionId() {
   };
 }
 
+// src/vite/encryption-key.ts
+import { randomBytes } from "node:crypto";
+var cachedKey;
+function buildEncryptionKey() {
+  cachedKey ??= process.env.RANGO_ENCRYPTION_KEY ?? randomBytes(32).toString("base64");
+  return cachedKey;
+}
+function defineEncryptionKeyExpr() {
+  return JSON.stringify(buildEncryptionKey());
+}
+
 // src/vite/plugins/expose-internal-ids.ts
 import { parseAst as parseAst2 } from "vite";
 import MagicString3 from "magic-string";
@@ -1527,6 +1543,27 @@ var debug3 = createRangoDebugger(NS.transform);
 var VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
 var RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
 var VIRTUAL_HANDLER_PREFIX = "virtual:handler-extract:";
+function createLoaderScanStubPlugin() {
+  let projectRoot = "";
+  let rscApi;
+  return {
+    name: "@rangojs/router:loader-scan-stubs",
+    apply: "build",
+    configResolved(config) {
+      projectRoot = config.root;
+      rscApi = config.plugins.find((plugin) => plugin.name === "rsc:minimal")?.api;
+    },
+    transform(code, id) {
+      if (!rscApi?.manager?.isScanBuild || this.environment?.name === "rsc" || id.includes("/node_modules/") || !code.includes("createLoader") || !hasCreateLoaderImport(code)) {
+        return;
+      }
+      const fnNames = getImportedFnNames(code, "createLoader");
+      const bindings = collectCreateExportBindings(code, fnNames);
+      const filePath = normalizePath(path4.relative(projectRoot, id));
+      return generateClientLoaderStubs(bindings, code, filePath, true) ?? void 0;
+    }
+  };
+}
 function exposeInternalIds(options) {
   let config;
   let isBuild = false;
@@ -2530,7 +2567,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.5.1",
+  version: "0.5.2",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2721,7 +2758,7 @@ var package_default = {
   },
   dependencies: {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.27",
+    "@vitejs/plugin-rsc": "^0.5.30",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.4",
@@ -2754,7 +2791,7 @@ var package_default = {
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.27",
+    "@vitejs/plugin-rsc": "^0.5.30",
     react: ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
     vite: "^8.0.16",
@@ -4251,11 +4288,6 @@ function onwarn(warning, defaultHandler) {
 }
 function getManualChunks(id) {
   const normalized = Vite.normalizePath(id);
-  if (/\/browser\/prefetch\/(?:runtime|fetch|queue|observer|policy|resource-ready)\.[cm]?[jt]sx?(?:[?#].*)?$/.test(
-    normalized
-  )) {
-    return void 0;
-  }
   if (normalized.includes("node_modules/react/") || normalized.includes("node_modules/react-dom/") || normalized.includes("node_modules/react-server-dom-webpack/") || normalized.includes("node_modules/@vitejs/plugin-rsc/")) {
     return "react";
   }
@@ -4887,6 +4919,49 @@ function walk(node, visit) {
 // src/vite/router-discovery.ts
 init_client_ref_hashing();
 
+// src/vite/plugins/server-ref-hashing.ts
+init_debug();
+init_client_ref_hashing();
+var debug9 = createRangoDebugger(NS.transform);
+function transformServerRefs(code, projectRoot) {
+  if (!code.includes("registerServerReference")) return null;
+  let hasReplacement = false;
+  const result = code.replace(
+    registerServerReferenceRegex(),
+    (match, _value, refKey) => {
+      const cleanKey = refKey.split("?")[0];
+      const hash = computeProductionHash(projectRoot, cleanKey);
+      if (hash === cleanKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    }
+  );
+  return hasReplacement ? result : null;
+}
+function hashServerRefs(projectRoot) {
+  const counter = createCounter(debug9, "hash-server-refs");
+  return {
+    name: "@rangojs/router:hash-server-refs",
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformServerRefs(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;
@@ -5605,11 +5680,11 @@ function copyStagedBuildAssets(projectRoot, fileNames) {
 
 // src/vite/discovery/prerender-collection.ts
 init_debug();
-var debug9 = createRangoDebugger(NS.prerender);
+var debug10 = createRangoDebugger(NS.prerender);
 async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   if (!state.opts?.enableBuildPrerender || !state.isBuildMode) return;
-  const overallStart = debug9 ? performance.now() : 0;
-  debug9?.(
+  const overallStart = debug10 ? performance.now() : 0;
+  debug10?.(
     "expandPrerenderRoutes: start (%d router manifest(s))",
     allManifests.length
   );
@@ -5662,7 +5737,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
           });
         } else {
           if (def?.getParams) {
-            const getParamsStart = debug9 ? performance.now() : 0;
+            const getParamsStart = debug10 ? performance.now() : 0;
             try {
               const buildVars = {};
               const buildEnv = state.resolvedBuildEnv;
@@ -5681,7 +5756,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
                 }
               };
               const paramsList = await def.getParams(getParamsCtx);
-              debug9?.(
+              debug10?.(
                 "getParams %s -> %d params (%sms)",
                 routeName,
                 paramsList.length,
@@ -5753,7 +5828,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
     }
   }
   if (entries.length === 0) {
-    debug9?.(
+    debug10?.(
       "no prerender entries (done in %sms)",
       (performance.now() - overallStart).toFixed(1)
     );
@@ -5764,7 +5839,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   console.log(
     `[rango] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`
   );
-  debug9?.(
+  debug10?.(
     "prerender loop: %d entries, max concurrency %d",
     entries.length,
     maxConcurrency
@@ -5872,7 +5947,7 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   console.log(
     `[rango] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`
   );
-  debug9?.(
+  debug10?.(
     "expandPrerenderRoutes done: %d done, %d skipped, %sms (overall %sms)",
     doneCount,
     skipCount,
@@ -5883,8 +5958,8 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
 async function renderStaticHandlers(state, rscEnv, registry) {
   if (!state.opts?.enableBuildPrerender || !state.isBuildMode || !state.resolvedStaticModules?.size)
     return;
-  const overallStart = debug9 ? performance.now() : 0;
-  debug9?.(
+  const overallStart = debug10 ? performance.now() : 0;
+  debug10?.(
     "renderStaticHandlers: start (%d static module(s))",
     state.resolvedStaticModules.size
   );
@@ -5974,7 +6049,7 @@ async function renderStaticHandlers(state, rscEnv, registry) {
   console.log(
     `[rango] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`
   );
-  debug9?.(
+  debug10?.(
     "renderStaticHandlers done: %d done, %d skipped, %sms (overall %sms)",
     staticDone,
     staticSkip,
@@ -6082,16 +6157,16 @@ function describeDiscoveryFailure(err, opts = {}) {
 // src/vite/discovery/discover-routers.ts
 init_debug();
 init_client_ref_hashing();
-var debug10 = createRangoDebugger(NS.discovery);
+var debug11 = createRangoDebugger(NS.discovery);
 async function discoverRouters(state, rscEnv) {
   if (!state.resolvedEntryPath) return;
   await timed(
-    debug10,
+    debug11,
     "inner: import entry",
     () => rscEnv.runner.import(state.resolvedEntryPath)
   );
   const serverMod = await timed(
-    debug10,
+    debug11,
     "inner: import @rangojs/router/server",
     () => rscEnv.runner.import("@rangojs/router/server")
   );
@@ -6107,7 +6182,7 @@ async function discoverRouters(state, rscEnv) {
         const handlerErrors = await resolveHostRouterHandlers(hostRegistry);
         discoveryErrors.push(...handlerErrors);
         for (const { context, error } of handlerErrors) {
-          debug10?.("caught error while resolving %s: %O", context, error);
+          debug11?.("caught error while resolving %s: %O", context, error);
         }
         const freshServerMod = await rscEnv.runner.import(
           "@rangojs/router/server"
@@ -6126,12 +6201,12 @@ async function discoverRouters(state, rscEnv) {
     }
   }
   const buildMod = await timed(
-    debug10,
+    debug11,
     "inner: import @rangojs/router/build",
     () => rscEnv.runner.import("@rangojs/router/build")
   );
   const generateManifestFull = buildMod.generateManifestFull;
-  debug10?.("inner: found %d router(s) in registry", registry.size);
+  debug11?.("inner: found %d router(s) in registry", registry.size);
   const nestedRouterConflict = findNestedRouterConflict(
     [...registry.values()].map((router) => router.__sourceFile).filter(
       (sourceFile) => typeof sourceFile === "string"
@@ -6156,7 +6231,7 @@ async function discoverRouters(state, rscEnv) {
       collectFallbackClientRefs(node, collectClientFallbackRef);
     }
   };
-  const manifestGenStart = debug10 ? performance.now() : 0;
+  const manifestGenStart = debug11 ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
       continue;
@@ -6230,12 +6305,12 @@ async function discoverRouters(state, rscEnv) {
       );
     }
   }
-  debug10?.(
+  debug11?.(
     "inner: generated manifests for %d router(s) (%sms)",
     allManifests.length,
     (performance.now() - manifestGenStart).toFixed(1)
   );
-  const trieStart = debug10 ? performance.now() : 0;
+  const trieStart = debug11 ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
     for (const { id, manifest } of allManifests) {
       const perRouterTrie = buildPerRouterTrie(manifest);
@@ -6244,7 +6319,7 @@ async function discoverRouters(state, rscEnv) {
       }
     }
   }
-  debug10?.(
+  debug11?.(
     "inner: trie build done (%sms)",
     (performance.now() - trieStart).toFixed(1)
   );
@@ -6279,7 +6354,7 @@ function buildShellManifestKey(pathname) {
 
 // src/vite/discovery/shell-prerender-phase.ts
 init_debug();
-var debug11 = createRangoDebugger(NS.prerender);
+var debug12 = createRangoDebugger(NS.prerender);
 async function runShellPrerenderPhase(s, builder) {
   const tempServer = s.shellPhaseTempServer;
   if (!s.isBuildMode || !s.shellCandidates?.length || !tempServer) return;
@@ -6335,7 +6410,7 @@ async function runShellPrerenderPhase(s, builder) {
     const base = builder?.config?.base ?? "/";
     const normalizedBase = base.endsWith("/") ? base : `${base}/`;
     const bootstrapContent = `import("${normalizedBase}assets/${entryFile}")`;
-    debug11?.("shell prerender bootstrap: %s", bootstrapContent);
+    debug12?.("shell prerender bootstrap: %s", bootstrapContent);
     const minimalPlugin = (tempServer.config?.plugins ?? []).find(
       (p) => p?.name === "rsc:minimal"
     );
@@ -6417,7 +6492,7 @@ async function runShellPrerenderPhase(s, builder) {
             buildEnv: s.resolvedBuildEnv,
             buildVersion,
             captureShellHTML,
-            debug: !!debug11
+            debug: !!debug12
           });
           if (res.outcome === "route-mismatch") {
             mismatches.push(res.matchedRouteName ?? "(no match)");
@@ -6983,7 +7058,7 @@ function postprocessBundle(state) {
 }
 
 // src/vite/discovery/gate-state.ts
-function createDiscoveryGate(s, debug12) {
+function createDiscoveryGate(s, debug13) {
   let gatePending = false;
   let gateResolver = () => {
   };
@@ -7000,7 +7075,7 @@ function createDiscoveryGate(s, debug12) {
   const resolveGate = () => {
     if (!gatePending) return;
     if (inProgress || queued || pendingEvents) {
-      debug12?.(
+      debug13?.(
         "hmr: resolveGate deferred \u2014 work in flight (inProgress=%s queued=%s pendingEvents=%s)",
         inProgress,
         queued,
@@ -7009,7 +7084,7 @@ function createDiscoveryGate(s, debug12) {
       return;
     }
     gatePending = false;
-    debug12?.("hmr: discoveryDone resolved");
+    debug13?.("hmr: discoveryDone resolved");
     gateResolver();
   };
   const noteRouteEvent = () => {
@@ -7019,7 +7094,7 @@ function createDiscoveryGate(s, debug12) {
   const runRefreshCycle = async (work) => {
     if (inProgress) {
       queued = true;
-      debug12?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
+      debug13?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
       return;
     }
     pendingEvents = false;
@@ -7030,16 +7105,16 @@ function createDiscoveryGate(s, debug12) {
       inProgress = false;
       if (queued) {
         queued = false;
-        debug12?.("hmr: consuming queued rediscovery");
+        debug13?.("hmr: consuming queued rediscovery");
         runRefreshCycle(work).catch((err) => {
-          debug12?.(
+          debug13?.(
             "hmr: queued cycle rejected \u2014 releasing gate (%s)",
             err instanceof Error ? err.message : String(err)
           );
           resolveGate();
         });
       } else if (pendingEvents) {
-        debug12?.(
+        debug13?.(
           "hmr: holding gate for pending events (debounce not yet fired)"
         );
       } else {
@@ -7154,10 +7229,25 @@ async function createTempRscServer(state, options = {}) {
           client: "virtual:entry-client",
           ssr: "virtual:entry-ssr",
           rsc: state.resolvedEntryPath
-        }
+        },
+        // The temp server renders Static/Prerender output and encrypts inline-
+        // action bound args. Give it the SAME key as the main build/dev runtime
+        // (defineEncryptionKeyExpr is process-cached) so those args decrypt at
+        // invocation. Unconditional, NOT build-only: under Cloudflare/workerd dev
+        // the RSC env has no module runner, so prerender is rendered by THIS temp
+        // server (via /__rsc_prerender), and the action decrypts in the main
+        // runtime with the rango.ts key -- gating on forceBuild left dev encrypting
+        // with the temp server's own random key, failing decryptActionBoundArgs.
+        // (hashServerRefs stays build-only: dev keeps dev-style ids the dev runtime
+        // resolves directly.)
+        defineEncryptionKey: defineEncryptionKeyExpr()
       }),
-      // hashClientRefs only in build mode — production bundles need hashed refs
-      ...options.forceBuild ? [hashClientRefs(state.projectRoot)] : [],
+      // hashClientRefs/hashServerRefs only in build mode — production bundles
+      // need hashed refs. hashServerRefs is the server-side analog: it rewrites
+      // registerServerReference dev-style ids to production hashes so a
+      // server-created action embedded in prerendered/static Flight resolves
+      // against the production manifest on a build-time-cache hit.
+      ...options.forceBuild ? [hashClientRefs(state.projectRoot), hashServerRefs(state.projectRoot)] : [],
       createVersionPlugin(),
       // Before the stub plugin, so "virtual:entry-ssr" resolves to the real
       // SSR entry when the shell endpoint needs it (see the option doc).
@@ -8668,7 +8758,10 @@ async function rango(options) {
       rsc({
         entries: finalEntries,
         serverHandler: false,
-        clientChunks
+        clientChunks,
+        // Share one encryption key with the build-discovery temp server so
+        // build-time prerender/static inline-action bound args decrypt at runtime.
+        defineEncryptionKey: defineEncryptionKeyExpr()
       })
     );
     plugins.push(clientRefDedup());
@@ -8857,7 +8950,10 @@ If this is a multi-app host router, export a createHostRouter() instance and set
     plugins.push(
       rsc({
         entries: finalEntries,
-        clientChunks
+        clientChunks,
+        // Share one encryption key with the build-discovery temp server so
+        // build-time prerender/static inline-action bound args decrypt at runtime.
+        defineEncryptionKey: defineEncryptionKeyExpr()
       })
     );
     plugins.push(clientRefDedup());
@@ -8879,6 +8975,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
       }
     }
   });
+  plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());
   plugins.push(exposeInternalIds());
@@ -8923,7 +9020,7 @@ function poke() {
     apply: "serve",
     configureServer(server) {
       const stdin = process.stdin;
-      const debug12 = process.env.RANGO_POKE_DEBUG === "1";
+      const debug13 = process.env.RANGO_POKE_DEBUG === "1";
       const triggerReload = (source) => {
         server.hot.send({ type: "full-reload", path: "*" });
         server.config.logger.info(`  browser reload (${source})`, {
@@ -8956,7 +9053,7 @@ function poke() {
         lines.pop();
         return lines;
       };
-      if (debug12) {
+      if (debug13) {
         server.config.logger.info(
           `  poke debug enabled (isTTY=${stdin.isTTY ? "yes" : "no"}, isRaw=${stdin.isTTY ? stdin.isRaw ? "yes" : "no" : "n/a"})`,
           { timestamp: true }
@@ -8969,7 +9066,7 @@ function poke() {
         );
       }
       const onData = (data) => {
-        if (debug12) {
+        if (debug13) {
           server.config.logger.info(`  poke stdin ${formatChunk(data)}`, {
             timestamp: true
           });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -191,7 +191,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.27",
+    "@vitejs/plugin-rsc": "^0.5.30",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -224,7 +224,7 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.27",
+    "@vitejs/plugin-rsc": "^0.5.30",
     "react": ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
     "vite": "^8.0.16",

package/skills/caching/SKILL.md

@@ -388,7 +388,7 @@ a request behind it:
 
 | Option                | Default | Bounds                              |
 | --------------------- | ------- | ----------------------------------- |
-| `edgeLookupTimeoutMs` | `10`    | L1 `cache.match` (the lookup)       |
+| `edgeLookupTimeoutMs` | `25`    | L1 `cache.match` (the lookup)       |
 | `edgeReadTimeoutMs`   | `20`    | L1 body read (CF streams it lazily) |
 | `kvReadTimeoutMs`     | `170`   | L2 / KV read                        |
 

package/skills/mime-routes/SKILL.md

@@ -132,9 +132,11 @@ response payload types, use one of these surfaces:
 // router.tsx
 export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```

package/skills/response-routes/SKILL.md

@@ -289,9 +289,11 @@ has no response payload metadata, so response routes resolve to `never`:
 // router.tsx
 export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```
@@ -480,7 +482,7 @@ type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
 // = { views: number; visitors: number }
 
 // After mounting -- names get prefixed.
-// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// Rango.PathResponse needs the RegisteredRoutes augmentation (see above),
 // otherwise it resolves to never.
 type BlogStats = Rango.PathResponse<"/blog/api/stats">;
 // = { views: number; visitors: number }

package/skills/typesafety/generated-files-and-cli.md

@@ -38,11 +38,11 @@ available globally.
 There are three distinct typing surfaces. They are **not** interchangeable —
 pick the one that matches what you need to type:
 
-| Surface             | Source                                   | Scope  | Gives                                    | Does not give                                                                                    |
-| ------------------- | ---------------------------------------- | ------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `GeneratedRouteMap` | `router.named-routes.gen.ts` (auto)      | global | route names, path params, search schemas | response/MIME payloads                                                                           |
-| `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) |
+| Surface             | Source                                               | Scope  | Gives                                    | Does not give                                                                                    |
+| ------------------- | ---------------------------------------------------- | ------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `GeneratedRouteMap` | `router.named-routes.gen.ts` (auto)                  | global | route names, path params, search schemas | response/MIME payloads                                                                           |
+| `routes`            | per-module `*.gen.ts` (`rango generate`)             | local  | local names, params, search              | the global app map                                                                               |
+| `RegisteredRoutes`  | manual `extends` of a `typeof router.routeMap` alias | global | paths, params, **response payloads**     | the `Handler`/`Prerender` default (those read `GeneratedRouteMap` to avoid a `router.tsx` cycle) |
 
 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
@@ -63,11 +63,15 @@ import type { AppBindings, AppVars } from "./env";
 
 export const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109).
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVars {}
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```
@@ -257,10 +261,12 @@ export const router = createRouter<ShopEnv>({ document: Document }).routes(
   urlpatterns,
 );
 
+type ShopRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
     interface Env extends ShopEnv {}
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends ShopRoutes {}
   }
 }
 ```
@@ -312,8 +318,9 @@ export default router;
 //    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
 //    No manual RegisteredRoutes declaration is needed for named-route handlers,
 //    ctx.reverse, prerender, href(), or Rango.Path. Add `RegisteredRoutes
-//    extends typeof router.routeMap` when global response payload helpers such
-//    as Rango.PathResponse need the richer router.routeMap metadata.
+//    extends AppRoutes` (an alias of typeof router.routeMap) when global
+//    response payload helpers such as Rango.PathResponse need the richer
+//    router.routeMap metadata.
 
 // 5. loaders/*.ts - Type-safe loaders
 export const ProductLoader = createLoader(async (ctx) => {

package/skills/typesafety/route-types.md

@@ -76,9 +76,13 @@ below is only needed for **`Rango.PathResponse`** (response-payload inference),
 `GeneratedRouteMap` cannot provide:
 
 ```typescript
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109).
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```