@rangojs/router 0.0.0-experimental.121 → 0.0.0-experimental.124

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)

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.121",
+  version: "0.0.0-experimental.124",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2256,6 +2256,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 +2288,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 +2304,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
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.121",
+  "version": "0.0.0-experimental.124",
   "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/cache-guide/SKILL.md

@@ -7,8 +7,9 @@ argument-hint:
 # cache() vs "use cache" — When to Use Which
 
 Both mechanisms share the same backing store and cache profiles, and both accept
-an optional `tags` field (not yet honored by the built-in stores — see "Two axes"
-below). They differ in scope, cache key, execution model, and runtime control.
+an optional `tags` field (honored by the built-in stores — invalidate with
+`updateTag`/`revalidateTag`; see "Two axes" below). They differ in scope, cache
+key, execution model, and runtime control.
 
 ## Two axes — do not conflate
 
@@ -18,10 +19,11 @@ caching:
 
 1. **Stored-value freshness** — _is a cached value still good?_
    → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
-   Entries expire by **TTL/SWR**. They accept an optional `tags` field, but the
-   built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) do not yet index or
-   invalidate by tag, so tag-based invalidation (`revalidateTag`) is a
-   forward-looking API requiring a custom store with secondary indices.
+   Entries expire by **TTL/SWR** and can be tagged (`cache({ tags })` or runtime
+   `cacheTag(...tags)`). Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
+   index by tag; invalidate on demand with `updateTag(...tags)` (awaitable,
+   read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking).
+   Both hard-purge; the difference is awaitability, not stale-serving.
 2. **Client-update selection** — _should this segment re-run and stream to the
    client on this navigation/action?_
    → `revalidate()`. Covered in `/loader` and `/route`, **not here**.

package/skills/caching/SKILL.md

@@ -81,6 +81,78 @@ cache(
 );
 ```
 
+## Tag-Based Invalidation
+
+Tag cached entries, then invalidate them on demand. Tags can be attached three ways:
+
+```typescript
+// 1. Static tags in the cache() DSL
+cache({ ttl: 300, tags: ["products"] }, () => [path("/products", List)]);
+
+// 2. Dynamic tags (function of ctx)
+cache(
+  { ttl: 300, tags: (ctx) => [`product:${ctx.params.id}`, "products"] },
+  () => [path("/products/:id", Detail)],
+);
+
+// 3. Runtime tags inside a "use cache" function
+async function getProduct(id: string) {
+  "use cache";
+  cacheTag(`product:${id}`, "products"); // variadic, additive
+  return db.getProduct(id);
+}
+```
+
+Invalidate with one of two server-only verbs (both variadic, imported from
+`@rangojs/router`):
+
+```typescript
+// Server Action — read-your-own-writes. Await it so the action's own re-render
+// (and the next navigation) sees fresh data.
+async function updateProduct(formData: FormData) {
+  "use server";
+  await db.updateProduct(formData);
+  await updateTag("products");
+}
+
+// Route handler / webhook — background, non-blocking (waitUntil). Hard-purge:
+// the next read re-renders fresh (NOT stale-while-revalidate).
+export async function POST() {
+  "use server";
+  revalidateTag("products");
+  return new Response("ok");
+}
+```
+
+| API                      | Timing                      | Use in                    | Semantics                                             |
+| ------------------------ | --------------------------- | ------------------------- | ----------------------------------------------------- |
+| `updateTag(...tags)`     | awaitable (`Promise<void>`) | server actions            | immediate; next read is fresh                         |
+| `revalidateTag(...tags)` | background (`void`)         | route handlers / webhooks | background (non-blocking); next read re-renders fresh |
+
+Both built-in stores support tags. For `CFCacheStore`, distributed (cross-colo)
+invalidation requires a `kv` namespace — the tag-invalidation markers live in
+that same namespace; there is **no** separate tag-invalidation store to wire.
+If no tag-capable store is configured, `updateTag`/`revalidateTag` warn and no-op.
+
+By default `CFCacheStore` reads the KV marker on every tagged cache read
+(strongest invalidation latency). To cut KV reads on hot tagged routes, set
+`tagCacheTtl` (seconds) to cache each marker in the per-colo edge cache for that
+window — the colo running `updateTag`/`revalidateTag` writes the fresh marker
+into its own edge cache immediately (read-your-own-writes), while other colos
+converge within `tagCacheTtl` (the **maximum extra cross-colo invalidation
+latency** when no purge is wired). Keep it small (e.g. 30–60), or wire a purge
+(below) and set it large. (Contrast `tagInvalidationTtl`, which must be _large_
+— it bounds how long the KV marker itself lives and must exceed your max entry
+TTL+SWR.)
+
+To make other colos prompt without a short `tagCacheTtl`, pass `onRevalidateTag`:
+each cached marker carries a namespaced Cloudflare `Cache-Tag`, and the hook is
+handed exactly those tags (batched, once per `updateTag`/`revalidateTag` call) to
+feed Cloudflare's purge-by-tag API — evicting the cached lookups everywhere.
+Purge-by-tag is available on all plans (since April 2025), subject to per-plan
+rate limits, so the batched single call matters. With a purge wired, `tagCacheTtl`
+becomes a pure read-cost reducer + fallback window.
+
 ## Named Profile Shorthand
 
 Use a named cache profile string instead of an options object. The profile must be
@@ -212,6 +284,80 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
+### Resilience & latency budgets
+
+Every cache read is **fail-safe**: a degraded tier never stalls or fails the
+request — it degrades to the next tier (L1 → L2 → render). Three optional latency
+budgets (milliseconds) bound each tier so a slow colo or KV namespace cannot pin
+a request behind it:
+
+| Option                | Default | Bounds                              |
+| --------------------- | ------- | ----------------------------------- |
+| `edgeLookupTimeoutMs` | `10`    | L1 `cache.match` (the lookup)       |
+| `edgeReadTimeoutMs`   | `20`    | L1 body read (CF streams it lazily) |
+| `kvReadTimeoutMs`     | `170`   | L2 / KV read                        |
+
+Set any to `0` (or a negative value) to disable that budget and always await the
+read. A non-finite value (e.g. `Number(env.UNSET)`) falls back to the default.
+The tag-invalidation marker reads inherit these same budgets and **fail open** on
+a KV timeout — the entry is served rather than wrongly treated as invalidated.
+
+```typescript
+new CFCacheStore({
+  ctx,
+  kv: env.CACHE_KV,
+  defaults: { ttl: 60, swr: 300 },
+  // Raise a budget only if your HEALTHY reads legitimately run slower (large
+  // Flight payloads, far-from-colo regions); measure the p99 first. These are
+  // degradation guard-rails, not tuning levers for "slow is normal here".
+  kvReadTimeoutMs: 250,
+});
+```
+
+Failure handling, by kind — none of these fail the request:
+
+| Failure                         | Behavior                                                                                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Transient read error (5xx/blip) | Degrade to the next tier; entry left intact                                                                                                       |
+| Read budget exceeded (timeout)  | Abandon the read, degrade to the next tier                                                                                                        |
+| Corrupt / unparseable L1 entry  | Reported corrupt; degrade to L2 (served if present). The L1 entry is evicted ONLY when L2 has no copy — so the evict can't race the L2→L1 promote |
+| Corrupt / unparseable KV entry  | Reported corrupt; evicted (self-heal) + render (no tier below it)                                                                                 |
+| Write failure                   | No-op (entry simply not cached); never throws                                                                                                     |
+
+Each is surfaced to the router's `onError` callback (phase `"cache"`, with
+`metadata.category` one of `cache-read`, `cache-corrupt`, `cache-write`,
+`cache-delete`, `cache-invalidate`, `stale-revalidation`) so you can observe
+cache health without affecting users.
+
+### Validating cache behavior with `debug`
+
+Pass `debug` to emit one structured event per L1 read — use it to confirm on a
+real deployment (via `wrangler tail`) that the store behaves as expected before
+relying on it. It is intended for validation, not steady-state production.
+
+```typescript
+new CFCacheStore({
+  ctx,
+  kv: env.CACHE_KV,
+  debug: true, // logs each CFCacheReadDebugEvent to the console
+  // ...or capture programmatically:
+  // debug: (event) => myTelemetry.record(event),
+});
+```
+
+Each event reports which tier answered and why (`outcome`: `l1-fresh`,
+`l1-stale-revalidate`, `l1-revalidating-guarded`, `match-timeout`, `match-error`,
+`body-timeout`, `body-error`, `non-200`, `tag-invalidated`, `l1-miss`, `kv-fresh`,
+`kv-stale`, `kv-stale-suppressed`, `kv-miss`, `kv-timeout`, `error`), the
+staleness / revalidating timestamps, and the measured per-tier durations:
+`matchMs` (the L1 `match`), `markerMs` (the tag-marker resolution tail for a
+tagged entry, between `matchMs` and `bodyReadMs`; absent or 0 for an untagged
+entry or a per-request memo hit), and `bodyReadMs` (the L1 body read). A
+persistently large `markerMs` signals a degraded KV namespace; on a healthy
+deployment KV keeps markers hot in its per-colo edge cache, so it stays a few
+milliseconds. `match-error` (a transient `cache.match` rejection that falls
+through to L2) is kept distinct from a plain `l1-miss`.
+
 ## Cache purity & tainted objects
 
 A `cache()` boundary caches everything except loaders, so anything read inside a
@@ -325,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({
@@ -353,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

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

package/skills/host-router/SKILL.md

@@ -189,12 +189,26 @@ Logs pattern matching, route registration, and cookie override decisions to cons
 ## Testing
 
 ```typescript
-import { createTestRequest, testPattern } from "@rangojs/router/host/testing";
+import {
+  createTestRequest,
+  testPattern,
+  matchesHost,
+} from "@rangojs/router/host/testing";
 
-// Test pattern matching
+// Test pattern matching (host-only)
 testPattern("admin.*", "admin.example.com"); // true
 testPattern([".", "www.*"], "example.com"); // true
 
+// Path-based patterns need the third pathname arg (defaults to "/", so a
+// host-only pattern still works with two args):
+testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin"); // true
+
+// Or match a pattern against a real Request (hostname + pathname from the URL):
+matchesHost(
+  "**.workers.dev/admin",
+  new Request("https://foo.workers.dev/admin"),
+); // true
+
 // Create requests for integration tests
 const request = createTestRequest({
   host: "admin.example.com",

package/skills/intercept/SKILL.md

@@ -107,8 +107,10 @@ Use named revalidation contracts on both the outer producer and the intercept
 consumer when they share `ctx.set()` data:
 
 ```typescript
-export const revalidateProductShell = ({ actionId }) =>
-  actionId?.includes("src/actions/product.ts#") || undefined;
+import * as ProductActions from "./actions/product";
+
+export const revalidateProductShell = (ctx) =>
+  ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns