@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/skills/typesafety/params-and-search.md

@@ -0,0 +1,153 @@
+# Params and Search Types
+
+## Typed Search Params
+
+Add a `search` schema to `path()` options for type-safe query parameters:
+
+```typescript
+// Route definition with search schema
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?", sort: "string?" },
+});
+```
+
+### Handler with typed search params
+
+`Handler<"name">` automatically resolves route params and search params from the
+global `GeneratedRouteMap` (the gen file). No explicit route map import needed:
+
+```typescript
+// pages/search.tsx
+import type { Handler } from "@rangojs/router";
+
+export const SearchPage: Handler<"search"> = (ctx) => {
+  // ctx.search is typed: { q: string; page?: number; sort?: string }
+  const { q, page, sort } = ctx.search;
+  return <SearchResults q={q} page={page} sort={sort} />;
+};
+```
+
+This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
+(from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
+
+You can also pass an explicit route map for per-module isolation (opt-in,
+after running `npx rango generate`). With a local map, the route name is
+**dot-prefixed** so params and search resolve from `routes`, not the global map:
+
+```typescript
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./urls.gen.js";
+
+export const SearchPage: Handler<".search", routes> = (ctx) => { ... };
+```
+
+Note the difference: `Handler<"search">` (no dot) resolves against the global
+`GeneratedRouteMap`; `Handler<".search", routes>` resolves against the local
+`routes` map. Mixing them — `Handler<"search", routes>` — silently ignores
+`routes` for param/search inference and only uses it for local `ctx.reverse(".x")`.
+
+Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
+Values are automatically coerced from query string (e.g., `"2"` becomes `2` for numbers).
+Routes without a `search` schema keep the standard `URLSearchParams` behavior.
+
+### RouteSearchParams and RouteParams utility types
+
+Extract typed params by route name for use in component props, return types, or anywhere:
+
+```typescript
+import type { RouteSearchParams, RouteParams } from "@rangojs/router";
+
+// RouteSearchParams<"name"> resolves the search schema to a typed object
+type SP = RouteSearchParams<"search">;
+// { q: string | undefined; page?: number; sort?: string }
+
+// RouteParams<"name"> resolves URL params from the route pattern
+type P = RouteParams<"blogPost">;
+// { slug: string }
+
+// Optional URL params (`:slug?`) resolve to `string | undefined`
+// because absent segments are omitted from `ctx.params` at runtime.
+type C = RouteParams<"checkout">;
+// { step?: string }
+// → ctx.params.step is `string | undefined`; use `?? "default"` to coalesce.
+
+// Use in component props
+interface SearchResultsProps {
+  params: RouteSearchParams<"search">;
+}
+```
+
+Both default to the global route map (`RegisteredRoutes` or `GeneratedRouteMap`).
+Pass an explicit route map as the second type argument when needed:
+
+```typescript
+import type { routes } from "./urls.gen.js";
+
+type SP = RouteSearchParams<"search", routes>;
+type P = RouteParams<"blogPost", routes>;
+```
+
+### Generated route types
+
+In the generated `router.named-routes.gen.ts`, routes with search schemas
+use `{ path, search }` objects:
+
+```typescript
+// router.named-routes.gen.ts (auto-generated)
+export const NamedRoutes = {
+  "search.index": {
+    path: "/search",
+    search: { q: "string", page: "number?", sort: "string?" },
+  },
+  "home.index": "/", // No search schema -> plain string
+} as const;
+```
+
+You never open a `.gen.ts` by hand. Treat the generated types as call-site
+honesty checks, not modules to read:
+
+- **Do not import `router.named-routes.gen.ts` directly**, and don't reach for
+  `Rango.GeneratedRouteMap`. It is the whole-app manifest, auto-wired
+  globally — `Handler<"name">` and `ctx.reverse("name")` already see it.
+- **Per-module `*.gen.ts` imports are fine** — they are the opt-in local-route
+  pattern for `useReverse(routes)` and explicit local handler typing
+  (`Handler<".name", routes>`). See `/links`.
+
+If a type error points at a generated map instead of your call site, that's a
+smell — fix the call site (or regenerate), never edit the generated file.
+
+## Loader Type Safety
+
+Loaders have typed return values:
+
+```typescript
+// loaders/product.ts
+export const ProductLoader = createLoader(async (ctx) => {
+  return {
+    id: ctx.params.slug,
+    name: "Widget",
+    price: 99,
+  };
+});
+
+// In server component - type is inferred
+import { useLoader } from "@rangojs/router/client";
+
+async function ProductPage() {
+  const product = await useLoader(ProductLoader);
+  // product: { id: string; name: string; price: number }
+  return <h1>{product.name}</h1>;
+}
+
+// In client component - same type
+"use client";
+import { useLoader } from "@rangojs/router/client";
+
+function ProductPrice() {
+  const { data } = useLoader(ProductLoader);
+  // data: { id: string; name: string; price: number }
+  const product = data;
+  return <span>${product.price}</span>;
+}
+```

package/skills/typesafety/route-types.md

@@ -0,0 +1,213 @@
+# Route Types
+
+## Route Definition with Type-Safe Names
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/products", ProductsPage, { name: "products" }),
+  path("/product/:slug", ProductPage, { name: "product" }),
+  path("/cart", CartPage, { name: "cart" }),
+  path("/checkout/:step?", CheckoutPage, { name: "checkout" }),
+]);
+
+// Route names are inferred from the { name } option
+```
+
+## Type-Safe href()
+
+### Server: ctx.reverse with route names
+
+In route handlers, `ctx.reverse()` uses two namespaces:
+
+- **`.name`** — local route, resolved within the current `include()` scope
+- **`name`** — global route, from the named-routes definition
+
+```typescript
+import type { Handler } from "@rangojs/router";
+
+export const ProductHandler: Handler<"shop.product"> = (ctx) => {
+  ctx.reverse(".cart"); // Local: /shop/cart
+  ctx.reverse(".product", { slug: "widget" }); // Local: /shop/product/widget
+  ctx.reverse("blog.post", { slug: "1" }); // Global: /blog/1
+};
+```
+
+For type-safe local names, generate a route types file with `npx rango generate urls/shop.tsx`
+and pass it as the second generic to `Handler` or `Prerender`:
+
+```typescript
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./shop.gen.js";
+
+export const ProductHandler: Handler<"shop.product", routes> = (ctx) => {
+  ctx.reverse(".cart"); // Type-safe local name
+  ctx.reverse(".product", { slug: "widget" }); // Type-safe local with params
+  ctx.reverse("blog.post", { slug: "hi" }); // Type-safe global name
+};
+```
+
+### Client: href + useHref
+
+On the client, `href()` validates paths against registered route patterns at compile time:
+
+```typescript
+"use client";
+import { href, useHref, Link } from "@rangojs/router/client";
+
+// href() validates absolute paths via PatternToPath types
+href("/about");                        // Valid path
+href("/blog/hello");                   // Matches /blog/:slug
+
+// useHref() auto-prefixes with include() mount
+function ShopNav() {
+  const href = useHref();
+  return <Link to={href("/cart")}>Cart</Link>; // "/shop/cart"
+}
+```
+
+`href()` and the `Rango.Path` type read from `RegisteredRoutes` when you augment
+it, otherwise from the auto-generated `GeneratedRouteMap` — so `rango generate`
+alone type-checks `href()` paths with no manual augmentation. The augmentation
+below is only needed for **`Rango.PathResponse`** (response-payload inference), which
+`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 AppRoutes {}
+  }
+}
+```
+
+For wrapper helpers, type the path parameter as `Rango.Path`. It is ambient (no
+import) and shares `href()`'s compile-time path checking, so a wrapper stays in
+sync with your routes automatically:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
+
+For response-route payloads, `Rango.PathResponse<T>` is the ambient lookup. It
+accepts a route _pattern_ **or** a concrete path, so it also serves as the return
+type of a typed `fetch` wrapper. It only resolves once `RegisteredRoutes` carries
+response metadata:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+type Same = Rango.PathResponse<"/api/products/42">; // by concrete path
+
+// Response inferred from the concrete path passed in:
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+const product = await get("/api/products/42"); // Product (bare value)
+```
+
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` describes the JSON **wire** shape, not the handler's raw
+return. A `path.json()` handler returning `{ createdAt: Date }` resolves here to
+`{ createdAt: string }` (bare value), matching what `r.json()` yields. This
+is applied via the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). A separate
+`Rango.FlightSerialize<T>` models the higher-fidelity RSC Flight boundary
+(loaders / RSC props, where `Date` is preserved) — do **not** use it for
+`path.json()`.
+
+### Overriding serialization globally
+
+For your own types, the zero-config way to control the JSON wire shape is a
+`toJSON()` method — `Rango.JsonSerialize` honors it, and it matches the runtime
+exactly (`JSON.stringify` calls `toJSON()`):
+
+```typescript
+class Money {
+  constructor(private cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+// Rango.JsonSerialize<Money> is number; Rango.PathResponse reflects it.
+```
+
+To override a transform for types you **don't** own (or for the Flight boundary,
+which has no `toJSON()`), augment its override slot. Because `Rango.JsonSerialize`
+/ `Rango.FlightSerialize` are type _aliases_ (TS can't merge those), you provide a
+single member that is your **complete** transform, delegating to the built-in for
+the cases you don't change:
+
+```typescript
+declare global {
+  namespace Rango {
+    interface JsonSerializeOverride<T> {
+      app: T extends Decimal ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
+  }
+}
+// Rango.JsonSerialize<Decimal> -> string; Rango.FlightSerialize<Money> -> number;
+// everything else stays on the built-in, recursively (nested fields too).
+```
+
+Rules: provide **exactly one** member (the slot is read as
+`Override<T>[keyof Override<T>]`, so multiple members union and conflict).
+Overrides win over `toJSON()` and apply at every nesting level. Caveat for JSON:
+the `path.json()` runtime is plain `JSON.stringify`, which only honors `toJSON()`,
+so a `JsonSerializeOverride` that disagrees with what the runtime emits will lie —
+prefer `toJSON()` for your own types and use the slot only for types you can't
+modify.
+
+See `/links` for full URL generation guide.
+
+## Stable identity: `path#export`
+
+Loaders, handles, cached functions (`functionId`), and server actions
+(`actionId`) all share one identity scheme: `{modulePath}#{exportName}`,
+injected at build by the `exposeInternalIds` and `exposeActionId` Vite plugins.
+This is also the identity React server actions carry across the Flight boundary,
+which is why a `revalidate()` predicate sees an action as a `path#export` string:
+
+```typescript
+revalidate(
+  ({ actionId }) => actionId === "src/actions/cart.ts#addToCart" || undefined,
+);
+```
+
+`actionId` is the only stable reference React exposes across the Flight boundary,
+so it stays as the floor and escape hatch. The hand-written-string surface
+(`actionId?.includes("cart.ts#")`) is brittle: a renamed action or moved file
+silently stops matching with no compile error. Prefer **`ctx.isAction()`** in a
+revalidate predicate — it resolves the action's id from an imported reference, so
+a rename is a type error in one place instead of silent drift:
+
+```ts
+import { addToCart, removeFromCart } from "./actions/cart";
+import * as CartActions from "./actions/cart";
+
+revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
+revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
+revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+```
+
+`ctx.isAction()` (only available on the revalidate predicate's context) returns a
+raw boolean — combine with `|| undefined` for the "revalidate on match, else
+defer" intent. It resolves the reference the same way the router derives
+`actionId` (`$id` in production, `$$id` in dev), so matching
+works in both modes. `actionId` stays available for advanced cases.

package/skills/use-cache/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-cache
-description: Function-level caching with "use cache" directive for RSC data functions and components
+description: Function-level caching with the "use cache" directive for RSC data functions and components in @rangojs/router. Use when a single function or component should memoize its own output, not a whole route/segment subtree or HTTP response.
 argument-hint: [profile-name]
 ---
 
@@ -10,6 +10,12 @@ Function-level caching for async server functions and RSC components. Caches
 return values with TTL + stale-while-revalidate. Complementary to the route-level
 `cache()` DSL and build-time `Static()`/`Prerender()`.
 
+## Not this skill if…
+
+- You want to cache a whole route or a rendered subtree of segments — that is
+  the segment-level `cache()` DSL: see `/caching`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+
 ## Basic Usage
 
 ### File-level (all exports cached with default profile)
@@ -52,8 +58,9 @@ export async function ProductCard({ id }: { id: string }) {
 
 ## Named Cache Profiles
 
-Define profiles in createRouter. Profile names map to `"use cache: <name>"` and
-`cache('<name>')` in the DSL.
+Define profiles in createRouter. Profile names map to `"use cache: <name>"` in
+the directive. The DSL `cache()` does not accept a string profile name; use an
+options object (`cache({ ttl: 60 })`) or the `"use cache: <name>"` directive.
 
 ```typescript
 createRouter({
@@ -62,13 +69,27 @@ createRouter({
     short: { ttl: 60, swr: 120 },
     long: { ttl: 3600, swr: 7200 },
     products: { ttl: 300, swr: 600, tags: ["products"] },
+    // Opt-in: a stale entry re-executes in the foreground during a server
+    // action's revalidation render (fresh action response), instead of SWR.
+    cms: { ttl: 300, swr: 600, foregroundOnAction: true },
   },
 });
 ```
 
 - `"use cache"` (no name) resolves to `default`.
 - `"use cache: short"` resolves to the `short` profile.
-- Unknown profile names throw at build/boot time.
+- `foregroundOnAction: true` (default false): a stale entry serves stale +
+  revalidates in the background on a plain navigation (SWR), but re-executes in
+  the FOREGROUND during a server action's revalidation render so the action
+  response reflects a fresh value (only the store write is deferred). Use it for
+  mutation-related cached data; incidental TTL staleness on an ordinary action
+  stays SWR so the action is not turned into a synchronous cache-refresh barrier.
+  For strong read-your-own-writes after a mutation, prefer `updateTag()` (a hard
+  purge, so the action's own re-render is a fresh foreground miss).
+- Unknown profile names throw at runtime, on the first invocation of the cached
+  function (the Vite transform does not validate names at build/boot). The error
+  is actionable -- it names the missing profile and shows the `createRouter({
+cacheProfiles: { ... } })` entry to add.
 
 ## Cache Key
 
@@ -77,18 +98,33 @@ use-cache:{functionId}:{serializedArgs}
 ```
 
 - `functionId` -- stable ID from Vite transform (module path + export name).
-- `serializedArgs` -- non-tainted arguments serialized via RSC `encodeReply()`.
+- `serializedArgs` -- key-generating arguments serialized via RSC `encodeReply()`.
+
+When there are no key-generating arguments, the key has no trailing colon -- it is
+just `use-cache:{functionId}`.
 
 Different functions always produce different cache keys, even for the same route.
 This is important for intercepted routes -- the path handler and intercept handler
 each have their own `functionId` and therefore their own cache entries.
 
+### Route context is folded into the key
+
+The tainted `ctx` object is excluded from arg serialization (see below), but
+route-identifying fields read off it are extracted into `serializedArgs`:
+`url.host`, route name (`_routeName`), `pathname`, `params`, response type
+(`_responseType`), and the user-facing sorted search params (internal `_rsc*`/`__`
+params excluded). The same cached function called with `ctx` on different routes,
+param combinations, hosts, response types, or query variants therefore produces
+distinct cache entries -- not one shared entry.
+
 ## Tainted Arguments (ctx, env, req)
 
 Request-scoped objects are branded with `Symbol.for('rango:nocache')` at creation.
 When detected:
 
 1. **Excluded from cache key** -- request-scoped, not meaningful for keying.
+   (The route-identifying fields read off `ctx` are still folded in -- see
+   "Route context is folded into the key" above.)
 2. **Handle data captured on miss** -- side effects via `ctx.use(Handle)` are recorded.
 3. **Handle data replayed on hit** -- restored into the current request's HandleStore.
 
@@ -117,17 +153,28 @@ const locale = cookies().get("locale")?.value ?? "en";
 const data = await getCachedData(locale); // locale is now in the cache key
 ```
 
+The guard does not reach into LOADER bodies consumed inside the cached
+function (`await ctx.use(loader)`): loaders always run fresh, so their reads
+are exempt — but the CONSUMED VALUE is captured into the shared cache entry
+like any other computed data. Same rule across `cache()` and the PPR shell:
+handler/cached-scope consumption = baked copy, client-side `useLoader` = live
+(the consumption-lane rule, `/rango` → Invariants).
+
 ### Side-Effect Guards
 
 These ctx methods **throw** inside a `"use cache"` function because their effects
 are lost on cache hit (the function body is skipped):
 
-- `ctx.set()` / `ctx.get()` for passing values to children
+- `ctx.set()` for passing values to children
 - `ctx.header()`
 - `ctx.setTheme()`
 - `ctx.setLocationState()`
 - `ctx.onResponse()`
 
+`ctx.get()` is **not** exec-guarded inside `"use cache"` -- it is a read, so it is
+safe. (It only throws when reading a non-cacheable variable inside the separate
+route-level `cache()` DSL boundary.)
+
 The error message recommends two alternatives:
 
 1. Extract the data fetch into a separate cached function and call ctx methods outside it.
@@ -260,6 +307,53 @@ intercept("@modal", ".product", async (ctx) => {
 }),
 ```
 
+## Embedding server actions in cached components
+
+A cached function may return a component that creates an inline `"use server"`
+action. The canonical case is a cached list whose items each carry an action --
+e.g. a cached article list where every row has a like button:
+
+```typescript
+export async function ArticleList() {
+  "use cache: articles";
+  const articles = await db.query("SELECT id, title FROM articles");
+  return (
+    <ul>
+      {articles.map((a) => {
+        const articleId = a.id; // captured -> frozen with the cache entry
+        async function like() {
+          "use server";
+          // runs live on click, in the CURRENT request scope
+          const user = cookies().get("session")?.value;
+          if (user) await db.like(articleId, user);
+        }
+        return <LikeButton key={a.id} title={a.title} action={like} />;
+      })}
+    </ul>
+  );
+}
+```
+
+Three behaviors, locked by `use-cache-inline-action.test.ts` (dev + prod):
+
+| What                                            | Behavior                  | Why                                                                                                                                                                           |
+| ----------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Values the action **closes over** (`articleId`) | **Frozen** at cache-write | The closure compiles to encrypted bound args, snapshotted when the entry is written and replayed verbatim on a hit. Correct for stable identities; wrong for volatile values. |
+| The action **body**                             | **Runs live** every call  | Once invoked it is an ordinary server function: fresh computation and live request context. `cookies()` / `headers()` work here (the body executes in the live request).      |
+| Invocability on a **cache hit**                 | **Works**                 | The action survives serialize -> cache -> deserialize and stays callable.                                                                                                     |
+
+Rule of thumb: **capture stable identities, read volatile/request-scoped values
+live in the body.** Do not close over a per-request token, the current user, or
+the current time and expect freshness -- those are frozen at cache-write. The
+`cookies()`/`headers()` read guard applies to the cached function body, NOT to an
+inline action's body.
+
+Deploy note: captured values are encrypted with a per-build key by default. If
+cache entries can outlive a deploy (a persistent store such as the Cloudflare
+cache store), set `RANGO_ENCRYPTION_KEY` (base64-encoded 32 bytes) in the build
+environment so actions embedded in entries written by a previous deploy still
+decrypt; without it they fail until the entry expires or revalidates.
+
 ## Vite Transform
 
 The `rango:use-cache` Vite plugin detects the directive and wraps exports with
@@ -304,18 +398,30 @@ export async function getProducts() {
 ## Backing Store
 
 Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
-One store, one configuration, one invalidation API. Tag-based invalidation
-(`revalidateTag`) works across all mechanisms.
+One store, one configuration.
+
+Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or runtime
+`cacheTag(...tags)`. `cacheTag` has two forms: inside a `"use cache"` function it
+tags that entry; called during a request render outside `"use cache"` it tags the
+request's document/shell artifact (rides `_requestTags`) instead of throwing. The
+built-in
+`MemorySegmentCacheStore` and `CFCacheStore` index by tag. Invalidate on demand
+with `updateTag(...tags)` (awaitable, read-your-own-writes; for server actions) or
+`revalidateTag(...tags)` (background, non-blocking; for route handlers/webhooks).
+Both hard-purge; the difference is awaitability, not stale-serving. For
+`CFCacheStore`, distributed invalidation needs a `kv` namespace (markers live in
+that same namespace). The separate `revalidate()` export is the client-update axis
+(which segments re-render on a navigation or action), not a cache bust.
 
 ## Interaction with Other Caching
 
-| Mechanism          | Granularity        | When       | Use case                                        |
-| ------------------ | ------------------ | ---------- | ----------------------------------------------- |
-| `"use cache"`      | Function/component | Runtime    | Cache individual data fetches or components     |
-| `cache()` DSL      | Route segment      | Runtime    | Cache entire route subtrees with children       |
-| `cache('profile')` | Route segment      | Runtime    | Same as cache() with a named profile            |
-| `Static()`         | Route segment      | Build-time | Render once, never re-render                    |
-| `Prerender()`      | Route segment      | Build-time | Pre-render known params, optional live fallback |
+| Mechanism            | Granularity        | When       | Use case                                        |
+| -------------------- | ------------------ | ---------- | ----------------------------------------------- |
+| `"use cache"`        | Function/component | Runtime    | Cache individual data fetches or components     |
+| `cache()` DSL        | Route segment      | Runtime    | Cache entire route subtrees with children       |
+| `cache({ ttl })` DSL | Route segment      | Runtime    | Cache a route subtree with explicit options     |
+| `Static()`           | Route segment      | Build-time | Render once, never re-render                    |
+| `Prerender()`        | Route segment      | Build-time | Pre-render known params, optional live fallback |
 
 ## Dev Mode