@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/dist/bin/rango.js

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -22,10 +27,10 @@ function extractParamsFromPattern(pattern) {
 function formatRouteEntry(key, pattern, _params, search) {
   const hasSearch = search && Object.keys(search).length > 0;
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
-  const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  const searchBody = Object.entries(search).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ");
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }
 var init_param_extraction = __esm({
   "src/build/route-types/param-extraction.ts"() {
@@ -1287,7 +1292,6 @@ function createVersionPlugin() {
       }
       return null;
     },
-    // Track RSC module changes and update version
     async hotUpdate(ctx) {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";

package/dist/testing/vitest.js

@@ -0,0 +1,82 @@
+// src/testing/vitest.ts
+import { fileURLToPath } from "node:url";
+function here(relativeFromRoot) {
+  return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
+}
+function rangoTestAliases(opts = {}) {
+  const aliases = [
+    // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
+    // subpaths (/testing, /client, /cache, ...) are untouched. React stays the
+    // client build, so createContext and "use client" modules work.
+    { find: /^@rangojs\/router$/, replacement: here("src/index.rsc.ts") },
+    {
+      find: "@rangojs/router:version",
+      replacement: here("src/testing/vitest-stubs/version.ts")
+    },
+    {
+      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc.ts")
+    }
+  ];
+  if (opts.preset === "cloudflare") {
+    aliases.push(
+      {
+        find: "cloudflare:workers",
+        replacement: here("src/testing/vitest-stubs/cloudflare-workers.ts")
+      },
+      {
+        find: "cloudflare:email",
+        replacement: here("src/testing/vitest-stubs/cloudflare-email.ts")
+      }
+    );
+  }
+  return aliases;
+}
+var rangoInlineDeps = [/@rangojs[/\\]router/];
+function rangoTestConfig(opts = {}) {
+  return {
+    alias: rangoTestAliases(opts),
+    // fresh copy so the shared rangoInlineDeps const is never aliased into (or
+    // mutated through) a consumer's resolved config
+    server: { deps: { inline: [...rangoInlineDeps] } }
+  };
+}
+function rangoUseClientTransform() {
+  return {
+    name: "rango:testing-use-client",
+    async transform(code, id) {
+      if (id.includes("/node_modules/")) return void 0;
+      if (!code.includes("use client")) return void 0;
+      const { parseAstAsync } = await import("vite");
+      const { hasDirective, transformDirectiveProxyExport } = await import("@vitejs/plugin-rsc/transforms");
+      let ast;
+      try {
+        ast = await parseAstAsync(code);
+      } catch {
+        return void 0;
+      }
+      if (!hasDirective(ast.body, "use client")) return void 0;
+      const result = transformDirectiveProxyExport(ast, {
+        directive: "use client",
+        code,
+        runtime: (name) => `$$RangoRSD.registerClientReference(() => { throw new Error("client reference " + ${JSON.stringify(name)} + " is not callable on the server"); }, ${JSON.stringify(id)}, ${JSON.stringify(name)})`
+      });
+      if (!result) return void 0;
+      const { output } = result;
+      output.prepend(
+        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+`
+      );
+      return {
+        code: output.toString(),
+        map: output.generateMap({ hires: true })
+      };
+    }
+  };
+}
+export {
+  rangoInlineDeps,
+  rangoTestAliases,
+  rangoTestConfig,
+  rangoUseClientTransform
+};

package/dist/vite/index.js

@@ -431,7 +431,6 @@ function exposeActionId() {
         counterTransform?.record(id, performance.now() - start);
       }
     },
-    // Build mode: renderChunk runs after all transforms and bundling complete
     renderChunk(code, chunk) {
       const start = counterRender ? performance.now() : 0;
       try {
@@ -1345,6 +1344,7 @@ ${lazyImports.join(",\n")}
     // --------------- Loader pre-scan (build mode) ---------------
     async buildStart() {
       if (!isBuild) return;
+      if (this.environment && this.environment.name !== "rsc") return;
       const fs2 = await import("node:fs/promises");
       const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage"]);
       async function scanDir(dir) {
@@ -1997,7 +1997,6 @@ function clientRefDedup() {
       if (this.environment?.name !== "client") return;
       if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
       if (!source.includes("/node_modules/")) return;
-      if (!importer) return;
       const packageName = extractPackageName(source);
       if (!packageName) return;
       if (clientExclude.includes(packageName)) return;
@@ -2130,7 +2129,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.122",
+  version: "0.0.0-experimental.125",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2256,6 +2255,31 @@ var package_default = {
     "./host/testing": {
       types: "./src/host/testing.ts",
       default: "./src/host/testing.ts"
+    },
+    "./testing": {
+      types: "./src/testing/index.ts",
+      default: "./src/testing/index.ts"
+    },
+    "./testing/vitest": {
+      types: "./src/testing/vitest.ts",
+      default: "./dist/testing/vitest.js"
+    },
+    "./testing/dom": {
+      types: "./src/testing/dom.entry.ts",
+      default: "./src/testing/dom.entry.ts"
+    },
+    "./testing/e2e": {
+      types: "./src/testing/e2e/index.ts",
+      default: "./src/testing/e2e/index.ts"
+    },
+    "./testing/flight": {
+      types: "./src/testing/flight.entry.ts",
+      "react-server": "./src/testing/flight.entry.ts",
+      default: "./src/testing/flight.entry.ts"
+    },
+    "./testing/flight-matchers": {
+      types: "./src/testing/flight-matchers.ts",
+      default: "./src/testing/flight-matchers.ts"
     }
   },
   publishConfig: {
@@ -2263,14 +2287,15 @@ var package_default = {
     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",
+    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/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && 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"
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   },
   dependencies: {
     "@types/debug": "^4.1.12",
@@ -2278,35 +2303,50 @@ var package_default = {
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.3",
-    "rsc-html-stream": "^0.0.7"
+    "rsc-html-stream": "^0.0.7",
+    tinyexec: "^0.3.2"
   },
   devDependencies: {
     "@playwright/test": "^1.49.1",
     "@shared/e2e": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
     esbuild: "^0.27.0",
+    "happy-dom": "^20.10.1",
     jiti: "^2.6.1",
     react: "catalog:",
     "react-dom": "catalog:",
-    tinyexec: "^0.3.2",
     typescript: "^5.3.0",
     vitest: "^4.0.0"
   },
   peerDependencies: {
     "@cloudflare/vite-plugin": "^1.38.0",
+    "@playwright/test": "^1.49.1",
+    "@testing-library/react": ">=16",
     "@vitejs/plugin-rsc": "^0.5.26",
     react: ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
-    vite: "^8.0.0"
+    vite: "^8.0.0",
+    vitest: ">=3"
   },
   peerDependenciesMeta: {
     "@cloudflare/vite-plugin": {
       optional: true
     },
+    "@playwright/test": {
+      optional: true
+    },
+    "@testing-library/react": {
+      optional: true
+    },
     vite: {
       optional: true
+    },
+    vitest: {
+      optional: true
     }
   }
 };
@@ -2381,10 +2421,10 @@ function extractParamsFromPattern(pattern) {
 function formatRouteEntry(key, pattern, _params, search) {
   const hasSearch = search && Object.keys(search).length > 0;
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
-  const searchBody = Object.entries(search).map(([k, v]) => `${k}: "${v}"`).join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  const searchBody = Object.entries(search).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ");
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }
 
 // src/build/route-types/ast-route-extraction.ts
@@ -3241,7 +3281,6 @@ function createVersionPlugin() {
       }
       return null;
     },
-    // Track RSC module changes and update version
     async hotUpdate(ctx) {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";
@@ -3318,9 +3357,6 @@ function performanceTracksOptimizeDepsPlugin() {
   const RSDW_CLIENT_RE = /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
   return {
     name: "@rangojs/router:performance-tracks-optimize-deps",
-    // Vite 8 optimizes deps with Rolldown (Rollup-style plugin pipeline), so the
-    // pre-bundled RSDW client is patched via load() rather than esbuild's onLoad.
-    // Returning code overrides Rolldown's default filesystem read for the module.
     async load(id) {
       const cleanId = id.split("?")[0] ?? id;
       if (!RSDW_CLIENT_RE.test(cleanId)) return null;
@@ -3510,7 +3546,6 @@ 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";
@@ -4823,18 +4858,14 @@ async function discoverRouters(state, rscEnv) {
     if (manifest.routeTrailingSlash) {
       Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
     }
-    flattenLeafEntries(
-      manifest.prefixTree,
-      manifest.routeManifest,
-      newMergedPrecomputedEntries
-    );
-    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     const routerPrecomputed = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
       routerPrecomputed
     );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
+    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
     console.log(
       `[rango] Router "${id}" -> ${routeCount} routes (${staticRoutes} static, ${dynamicRoutes} dynamic)`
@@ -5159,7 +5190,7 @@ function generatePerRouterModule(state, routerId) {
       `export const precomputedEntries = ${jsonParseExpression(entries)};`
     );
   }
-  return lines.join("\n") || "// empty router manifest";
+  return lines.join("\n") || "";
 }
 
 // src/vite/discovery/bundle-postprocess.ts
@@ -5230,7 +5261,7 @@ function postprocessBundle(state) {
           manifestMap[key] = `./assets/${assetFileName}`;
         }
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           ""
@@ -6494,8 +6525,6 @@ async function rango(options) {
       enforce: "pre",
       config() {
         return {
-          // Exclude rsc-router modules from optimization to prevent module duplication
-          // This ensures the same Context instance is used by both browser entry and RSC proxy modules
           optimizeDeps: {
             exclude: excludeDeps,
             rolldownOptions: sharedRolldownOptions
@@ -6518,21 +6547,12 @@ 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
                   }
                 }
               },
-              // Pre-bundle rsc-html-stream to prevent discovery during first request
-              // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
                 include: [nested("rsc-html-stream/client")],
                 exclude: excludeDeps,
@@ -6540,12 +6560,9 @@ async function rango(options) {
               }
             },
             ssr: {
-              // Build SSR inside RSC directory so wrangler can deploy self-contained dist/rsc
               build: {
                 outDir: "./dist/rsc/ssr"
               },
-              // Pre-bundle SSR entry and React for proper module linking with childEnvironments
-              // All deps must be listed to avoid late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
               optimizeDeps: {
                 entries: [finalEntries.ssr],
                 include: [
@@ -6565,10 +6582,7 @@ async function rango(options) {
               }
             },
             rsc: {
-              // RSC environment needs exclude list and esbuild options
-              // Exclude rsc-router modules to prevent createContext in RSC environment
               optimizeDeps: {
-                // Pre-bundle all RSC deps to prevent late discovery triggering ERR_OUTDATED_OPTIMIZED_DEP
                 include: [
                   "react",
                   "react/jsx-runtime",
@@ -6654,13 +6668,6 @@ ${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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.122",
+  "version": "0.0.0-experimental.125",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -126,57 +126,97 @@
     "./host/testing": {
       "types": "./src/host/testing.ts",
       "default": "./src/host/testing.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    },
+    "./testing/vitest": {
+      "types": "./src/testing/vitest.ts",
+      "default": "./dist/testing/vitest.js"
+    },
+    "./testing/dom": {
+      "types": "./src/testing/dom.entry.ts",
+      "default": "./src/testing/dom.entry.ts"
+    },
+    "./testing/e2e": {
+      "types": "./src/testing/e2e/index.ts",
+      "default": "./src/testing/e2e/index.ts"
+    },
+    "./testing/flight": {
+      "types": "./src/testing/flight.entry.ts",
+      "react-server": "./src/testing/flight.entry.ts",
+      "default": "./src/testing/flight.entry.ts"
+    },
+    "./testing/flight-matchers": {
+      "types": "./src/testing/flight-matchers.ts",
+      "default": "./src/testing/flight-matchers.ts"
     }
   },
   "publishConfig": {
     "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",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.3",
-    "rsc-html-stream": "^0.0.7"
+    "rsc-html-stream": "^0.0.7",
+    "tinyexec": "^0.3.2"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@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",
+    "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "tinyexec": "^0.3.2",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.38.0",
+    "@playwright/test": "^1.49.1",
+    "@testing-library/react": ">=16",
     "@vitejs/plugin-rsc": "^0.5.26",
     "react": ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
-    "vite": "^8.0.0"
+    "vite": "^8.0.0",
+    "vitest": ">=3"
   },
   "peerDependenciesMeta": {
     "@cloudflare/vite-plugin": {
       "optional": true
     },
+    "@playwright/test": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
+    },
+    "vitest": {
+      "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/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && 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",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/caching/SKILL.md

@@ -471,6 +471,7 @@ cache({ store: checkoutCache }, () => [
 ```typescript
 import { urls } from "@rangojs/router";
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import * as CartActions from "./actions/cart";
 
 // Custom store for checkout (short TTL)
 const checkoutCache = new MemorySegmentCacheStore({
@@ -499,7 +500,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
       loader(ProductLoader, () => [cache({ ttl: 120 })]),
       loader(CartLoader, () => [
-        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
       ]),
     ]),
   ]),

package/skills/hooks/SKILL.md

@@ -89,8 +89,8 @@ import { useSegments } from "@rangojs/router/client";
 function Breadcrumbs() {
   const { path, segmentIds, location } = useSegments();
 
-  // path: ["/shop", "products", "123"]
-  // segmentIds: ["shop-layout", "products-route"]
+  // path: ["shop", "products", "123"] (split on "/", no leading slash on any element)
+  // segmentIds: ["L0", "L0L1", "L0L1R0"] (opaque internal short-codes, not route names)
   // location: URL object
 
   return <nav>{path.join(" > ")}</nav>;
@@ -683,33 +683,44 @@ ProductState.delete();
 | `.write()`  | yes (replace this slot) | no                                | throws              |
 | `.delete()` | yes (remove this slot)  | no                                | throws              |
 
-## Cache Hooks
+## Cache Control
 
-### useClientCache()
+### invalidateClientCache()
 
-Manually control client-side navigation cache:
+Force the client's caches to miss after a mutation the router can't see (a REST
+call, a WebSocket push, a login). It is a plain function, not a hook, so it works
+from module-level callbacks too. Imported from the root entry `@rangojs/router`,
+it is selected by export conditions: in a client component it marks the caches
+stale immediately; from a handler/server component it writes a rotated
+`Set-Cookie` for the responding client.
 
 ```tsx
 "use client";
-import { useClientCache } from "@rangojs/router/client";
+import { invalidateClientCache } from "@rangojs/router";
 
 function SaveButton() {
-  const { clear } = useClientCache();
-
   const handleSave = async () => {
     await fetch("/api/data", {
       method: "POST",
       body: JSON.stringify(data),
     });
 
-    // Invalidate cache after mutation
-    clear();
+    // Invalidate the client's caches after the mutation
+    invalidateClientCache();
   };
 
   return <button onClick={handleSave}>Save</button>;
 }
 ```
 
+A module-level subscription works the same way (no component needed):
+
+```ts
+import { invalidateClientCache } from "@rangojs/router";
+
+socket.on("catalog-updated", () => invalidateClientCache());
+```
+
 **Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.
 
 ## Outlet Components
@@ -892,22 +903,22 @@ See `/links` for the full URL generation guide. `ctx.reverse()` is server-only;
 
 ## Hook Summary
 
-| Hook                  | Purpose                           | Returns                                                            |
-| --------------------- | --------------------------------- | ------------------------------------------------------------------ |
-| `useParams()`         | Route params                      | `Readonly<T>` (default `Record<string, string>`) or selected value |
-| `usePathname()`       | Current pathname                  | `string`                                                           |
-| `useSearchParams()`   | URL search params                 | `ReadonlyURLSearchParams`                                          |
-| `useHref()`           | Mount-aware href                  | `(path) => string`                                                 |
-| `useMount()`          | Current include() mount path      | `string`                                                           |
-| `useReverse()`        | Local reverse for imported routes | `(name, params?, search?) => string`                               |
-| `useNavigation()`     | Reactive navigation state         | state, location, isStreaming                                       |
-| `useRouter()`         | Stable router actions             | push, replace, refresh, prefetch, back, forward                    |
-| `useSegments()`       | URL path & segment IDs            | path, segmentIds, location                                         |
-| `useLinkStatus()`     | Link pending state                | { pending }                                                        |
-| `useLoader()`         | Loader data (strict)              | data, isLoading, error                                             |
-| `useFetchLoader()`    | Loader with on-demand fetch       | data, load, isLoading                                              |
-| `useRefreshLoaders()` | Refresh cross-loader group(s)     | `() => (groups: string \| string[]) => Promise<void>`              |
-| `useHandle()`         | Accumulated handle data           | T (handle type)                                                    |
-| `useAction()`         | Server action state               | state, error, result                                               |
-| `useLocationState()`  | History state (persists or flash) | T \| undefined                                                     |
-| `useClientCache()`    | Cache control                     | { clear }                                                          |
+| Hook                      | Purpose                                                        | Returns                                                            |
+| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`           | Current pathname                                               | `string`                                                           |
+| `useSearchParams()`       | URL search params                                              | `ReadonlyURLSearchParams`                                          |
+| `useHref()`               | Mount-aware href                                               | `(path) => string`                                                 |
+| `useMount()`              | Current include() mount path                                   | `string`                                                           |
+| `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                               |
+| `useNavigation()`         | Reactive navigation state                                      | state, location, isStreaming                                       |
+| `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                    |
+| `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                         |
+| `useLinkStatus()`         | Link pending state                                             | { pending }                                                        |
+| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error                                             |
+| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading                                              |
+| `useRefreshLoaders()`     | Refresh cross-loader group(s)                                  | `() => (groups: string \| string[]) => Promise<void>`              |
+| `useHandle()`             | Accumulated handle data                                        | T (handle type)                                                    |
+| `useAction()`             | Server action state                                            | state, error, result                                               |
+| `useLocationState()`      | History state (persists or flash)                              | T \| undefined                                                     |
+| `invalidateClientCache()` | Force client caches to miss (function, not a hook; root entry) | `void`                                                             |