@rangojs/router 0.16.0 → 0.17.0

package/skills/typesafety/route-types.md

@@ -1,12 +1,19 @@
 # Route Types
 
+Route names come from the `name` option on `path()`. Names are typed in two
+places: the `urls()` value itself (local names, patterns and response payloads
+as phantom types) and the generated `router.named-routes.gen.ts` (the global
+name map behind `Handler<"name">`, `ctx.reverse()` and `href()`). See
+[`./generated-files-and-cli.md`](./generated-files-and-cli.md) for which surface
+feeds which API.
+
 ## Route Definition with Type-Safe Names
 
 ```typescript
 // urls.tsx
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout }) => [
+export const urlpatterns = urls(({ path }) => [
   path("/", HomePage, { name: "home" }),
   path("/products", ProductsPage, { name: "products" }),
   path("/product/:slug", ProductPage, { name: "product" }),
@@ -17,7 +24,7 @@ export const urlpatterns = urls(({ path, layout }) => [
 // Route names are inferred from the { name } option
 ```
 
-## Type-Safe href()
+## Type-Safe URL Generation
 
 ### Server: ctx.reverse with route names
 
@@ -36,8 +43,15 @@ export const ProductHandler: Handler<"shop.product"> = (ctx) => {
 };
 ```
 
-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`:
+Without a local route map, `.name` calls accept any string (the include scope
+is only known at runtime). Middleware and response-route handlers are the
+exception: their `ctx.reverse` (`GlobalReverseFunction`) has no include scope,
+so it takes global names only and a `.name` call there is a type error. Global names are checked against the generated
+map once it exists. For type-safe local names, generate a route types file with
+`npx rango generate urls/shop.tsx` and pass its `routes` type as the second
+generic to `Handler` or `Prerender`. With a local map, local names also
+require their params (mount params such as `:tenantId` may still be passed as
+extras):
 
 ```typescript
 import type { Handler } from "@rangojs/router";
@@ -61,6 +75,7 @@ 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
+href("/blog/hello?page=2#top");        // Query and hash suffixes are allowed
 
 // useHref() auto-prefixes with include() mount
 function ShopNav() {
@@ -69,6 +84,10 @@ function ShopNav() {
 }
 ```
 
+`href()` is compile-time only: at runtime it returns the path unchanged. It
+does not resolve route names. `useHref()` prepends the mount but its argument
+is typed as any `/${string}`, not checked against routes.
+
 `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
@@ -76,6 +95,7 @@ below is only needed for **`Rango.PathResponse`** (response-payload inference),
 `GeneratedRouteMap` cannot provide:
 
 ```typescript
+// router.tsx, below `export const router = createRouter(...).routes(urlpatterns)`
 // The alias is required: an interface heritage clause cannot take a `typeof`
 // type query directly (TS1109).
 type AppRoutes = typeof router.routeMap;
@@ -200,15 +220,31 @@ 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
-revalidate((ctx) => ctx.isAction({ addToCart, removeFromCart }) || undefined); // object form
+import * as OrderActions from "./actions/order";
+
+// On a loader: after an action, re-run only for cart actions; on navigation,
+// keep the default.
+revalidate((ctx) => (ctx.isAction() ? ctx.isAction(CartActions) : undefined));
+
+// Matcher forms (each returns a boolean):
+ctx.isAction(); // any action at all
+ctx.isAction(addToCart); // one action
+ctx.isAction(addToCart, removeFromCart); // several
+ctx.isAction(CartActions); // any action in the module
+ctx.isAction({ addToCart, removeFromCart }); // object form
+ctx.isAction({ Cart: CartActions, Order: OrderActions }); // grouped namespaces
 ```
 
-`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.
+`ctx.isAction()` (only available on the revalidate predicate's argument)
+returns a raw boolean and is `false` on plain navigation. Wrap it by what the
+segment's default already does: `|| undefined` adds a re-render on a parent
+layout or layout-level parallel (skipped after actions by default); on a loader
+or route segment, which already re-run after every action, `|| undefined`
+changes nothing, so narrow with the ternary above. Avoid a bare
+`ctx.isAction(X)`: it is a hard `false` on navigation too. See `/loader` →
+"`revalidate()` return shapes". It resolves
+the reference the same way the router derives `actionId` (`$id ?? $$id`: the
+file-path `$id` injected in a production RSC build, otherwise React's `$$id`),
+so matching works in dev and production. `actionId` stays available for
+advanced cases. In `clientUrls()` groups the predicate runs in the browser,
+where `actionId` is the hashed form (see `/client-urls`).

package/skills/use-cache/SKILL.md

@@ -6,14 +6,21 @@ argument-hint: [profile-name]
 
 # "use cache" Directive
 
-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()`.
+Function-level caching for async server functions and RSC components. Put the
+directive in a function (or at the top of a module) and its return value is
+cached with a TTL and a stale-while-revalidate window, keyed by its arguments.
+Use it when one data fetch or one component is expensive and is reused across
+routes or requests; the code around the call keeps running.
+
+It complements the route-level `cache()` DSL (a whole segment subtree) and
+build-time `Static()`/`Prerender()`. `"use cache"` needs an app-level store
+(`createRouter({ cache })`); without one the function runs uncached.
 
 ## 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 want a value fresh on every request — use a loader (see `/loader`).
 - You are unsure which cache layer you need — start at `/cache-guide`.
 
 ## Basic Usage
@@ -56,6 +63,16 @@ export async function ProductCard({ id }: { id: string }) {
 }
 ```
 
+### Results that are not cached
+
+A result Flight cannot encode cleanly is not cached: an async child component
+that throws, a promise in the result or in a handle push that rejects, a
+function or a class instance. Storing it would bake the failure into every hit
+until expiry. Instead the write is skipped and reported to `onError` (phase
+`"cache"`, category `cache-write`, or `stale-revalidation` for a background
+refresh): a miss still returns the live result, the next call runs the
+function again, and a stale entry keeps serving.
+
 ## Named Cache Profiles
 
 Define profiles in createRouter. Profile names map to `"use cache: <name>"` in
@@ -85,11 +102,17 @@ createRouter({
   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).
+  purge, so the action's own re-render is a fresh foreground miss). Only
+  `"use cache"` honors this flag; `cache()` boundaries and cached loaders ignore
+  it.
+- `default` is built in as `{ ttl: 900, swr: 1800 }`; defining `default`
+  overrides it.
+- Profile names must match `[a-zA-Z0-9_-]+`, and `ttl`/`swr` must be finite and
+  non-negative; `createRouter()` throws otherwise.
 - 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.
+  names the missing profile and shows the `createRouter({ cacheProfiles })` entry
+  to add.
 
 ## Cache Key
 
@@ -97,8 +120,20 @@ cacheProfiles: { ... } })` entry to add.
 use-cache:{functionId}:{serializedArgs}
 ```
 
-- `functionId` -- stable ID from Vite transform (module path + export name).
-- `serializedArgs` -- key-generating arguments serialized via RSC `encodeReply()`.
+- `functionId` -- stable ID from Vite transform (module path + export name in
+  dev, a hash of both in production builds).
+- `serializedArgs` -- key-generating arguments: a stable JSON encoding when every
+  argument is JSON-safe, otherwise serialized via RSC `encodeReply()`.
+
+React elements (`header`, `children` slots) and client or server references
+are left out of the key: the first call's rendered slot is part of the cached
+output, and a hit returns it for any slot passed.
+
+If any other argument cannot be serialized, top-level or nested (a function, a
+class instance such as a database client, a symbol), the call runs uncached and
+warns once per function in dev. Flight's encoder writes the same placeholder
+for every such value, so keying on it would serve one caller's result to every
+other caller. Pass the serializable values the function needs.
 
 When there are no key-generating arguments, the key has no trailing colon -- it is
 just `use-cache:{functionId}`.
@@ -117,16 +152,48 @@ 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:
+## Request-Scoped Arguments (ctx, Request, env)
+
+Three request-scoped arguments are kept out of the serialized arguments:
+
+- **`ctx`** is branded with `Symbol.for('rango:nocache')` at creation. Its route
+  fields are folded into the key, and its handle pushes are captured and
+  replayed (below). Every ctx is branded: handler, loader, middleware,
+  response-route and the request context. A loader ctx keys exactly like the
+  handler ctx of the same request. A middleware ctx keys by host, pathname,
+  its params and search, plus the route name once the route is matched (a
+  global middleware before `next()` has none yet). A ctx carrying a request
+  body (a fetchable loader called with `method: "POST"` and a `body` or form
+  data) runs the call uncached and warns in dev: the body is not in the key.
+  The method is not in the key either.
+- **A `Request`** (such as `ctx.request`) keys by its URL: host, pathname and
+  the user-facing sorted search params, with the same internal-param exclusion
+  and `cache.searchParams` filter as the URL-keyed tiers. Headers, cookies and
+  the method are not in the key; read what you need outside and pass the values.
+- **The request's `env`** (the object `ctx.env` returns) is left out of the key:
+  it is fixed per deployment. A binding passed on its own (`env.DB`) is a class
+  instance and runs uncached; pass `env` instead.
+
+When a `ctx` is 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.
+2. **Handle data captured on miss** -- side effects via `ctx.use(Handle)` are recorded:
+   the function's own pushes (and those of cached functions it calls), not the
+   handler's or loaders' pushes into the same request.
+3. **Handle data replayed on hit** -- appended to the calling segment (for a
+   loader ctx, the segment that declares the loader), after what the handler
+   and loaders already pushed, as if the body had run (a layout and its page
+   calling the same function each get their copy). A
+   stale hit's background refresh records its pushes into the refreshed entry only.
+4. **A loader the function reads shows its pushes once** -- pushes from a loader
+   read with `ctx.use(Loader)` inside the function are recorded under that
+   loader. Loaders stay live, so if the handler or a DSL loader also reads it,
+   that live run's pushes are the ones on the page: a live run before the hit
+   makes the replay skip them, and one after it replaces the replayed values in
+   place. A loader read only inside the function is replayed once, also when
+   a layout and its page both call the function.
 
 ```typescript
 export async function getProductData(ctx) {
@@ -136,6 +203,17 @@ export async function getProductData(ctx) {
   return await db.query("SELECT * FROM products");
 }
 // On hit: return value restored, breadcrumb replayed.
+
+export async function getProduct(ctx) {
+  "use cache";
+  const category = await ctx.use(CategoryLoader); // pushes a category crumb
+  return db.product(ctx.params.id, category.id);
+}
+// Handler: `await getProduct(ctx); await ctx.use(CategoryLoader);`
+// On hit: one category crumb, from the handler's live CategoryLoader run.
+
+export const ProductLoader = createLoader(async (ctx) => getProduct(ctx));
+// A loader ctx keys like the handler ctx: one entry per route, params and query.
 ```
 
 ## Request-Scoped Guards
@@ -153,10 +231,35 @@ 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:
+`ctx.get()` of a **non-cacheable variable** (`createVar({ cache: false })`, or
+a value written with `ctx.set(key, value, { cache: false })`) throws the same
+way, whether it goes through `getRequestContext().get()` or a `ctx` passed in
+(handler, loader, middleware or response-route).
+The key does not include the value, so the first caller's value would be
+served to later callers. Read it before the call and pass it in:
+
+```typescript
+const Tenant = createVar<string>({ cache: false });
+
+async function getNav(tenant: string) {
+  "use cache";
+  return loadNav(tenant); // tenant is part of the key
+}
+
+// in a handler or loader, outside the cached function
+const nav = await getNav(ctx.get(Tenant)!);
+```
+
+Ordinary (cacheable) variables stay readable. Calling the cached function from
+a loader does not exempt it: the loader re-runs on every request, but the
+cached body does not.
+
+The non-cacheable variable guard does not reach into LOADER bodies consumed
+inside the cached function (`await ctx.use(loader)`): loaders always run
+fresh, so their variable reads are exempt — but the CONSUMED VALUE is captured
+into the shared cache entry like any other computed data. (`cookies()` and
+`headers()` still throw there: that guard follows the cached body's whole
+async chain, loaders included.) Same rule across `cache()` and the PPR shell:
 handler/cached-scope consumption = baked copy, client-side `useLoader` = live
 (the consumption-lane rule, `/rango` → Invariants).
 
@@ -165,15 +268,17 @@ handler/cached-scope consumption = baked copy, client-side `useLoader` = live
 These ctx methods **throw** inside a `"use cache"` function because their effects
 are lost on cache hit (the function body is skipped):
 
-- `ctx.set()` for passing values to children
-- `ctx.header()`
+- `ctx.set()` for passing values to children (handler and middleware ctx)
+- `ctx.headers.set()` and the other mutating `Headers` methods (handler and
+  middleware ctx), and a middleware's `ctx.header()`
+- cookie writes and the request-context writers `header()`, `setCookie()`,
+  `deleteCookie()`, `setStatus()`, `onResponse()`
 - `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.)
+`ctx.get()` is a read, not a side effect: it stays allowed for ordinary
+variables and throws only for a non-cacheable one (see "Read Guards" above).
+The same non-cacheable read throws inside a route-level `cache()` boundary.
 
 The error message recommends two alternatives:
 
@@ -257,9 +362,8 @@ On cache miss, the function executes and the result is serialized inline (blocki
 The cache **store write** (`setItem`) is deferred to `waitUntil` and does NOT block
 the response.
 
-On stale hit, stale data is returned immediately. Background revalidation (re-execute
-
-- store) runs entirely inside `waitUntil`.
+On stale hit, stale data is returned immediately. Background revalidation
+(re-execute + store write) runs entirely inside `waitUntil`.
 
 | Phase                                | Blocks response? |
 | ------------------------------------ | ---------------- |
@@ -356,75 +460,89 @@ 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
-`registerCachedFunction()`:
+The `@rangojs/router:use-cache` Vite plugin (part of `rango()`) detects the directive and wraps each cached
+function with `registerCachedFunction(fn, functionId, profileName)` from
+`@rangojs/router/cache-runtime`. You never call it yourself. Simplified output:
 
 ```typescript
-// Input
-"use cache"
+// Input (file-level directive)
+"use cache";
 export async function getProducts() { ... }
 
-// Output
-import { registerCachedFunction } from '@rangojs/router/cache-runtime';
+// Output (simplified)
+import { registerCachedFunction } from "@rangojs/router/cache-runtime";
 export const getProducts = registerCachedFunction(
   async function getProducts() { ... },
-  "src/data/products.ts#getProducts",
-  "default"
+  "src/data/products.ts#getProducts", // a hash of this in production builds
+  "default",
 );
 ```
 
-Function-level directives are hoisted:
+A function-level directive (`"use cache: short"` inside the body) is hoisted out
+of the function and wrapped the same way, with the profile name from the
+directive.
 
-```typescript
-// Input
-export async function getProducts() {
-  "use cache: short";
-  return await db.query("...");
-}
+File-level rules:
 
-// Output
-const __rango_cached_getProducts = registerCachedFunction(
-  async function getProducts() {
-    return await db.query("...");
-  },
-  "src/data/products.ts#getProducts",
-  "short",
-);
-export async function getProducts() {
-  return __rango_cached_getProducts();
-}
-```
+- Only exports that are statically confirmed functions are wrapped
+  (`export async function foo() {}`, `export const foo = async () => {}`). Any
+  other export (a constant, or a factory call like `makeCached(fn)`) fails the
+  build — move it to another module.
+- The default export of a file named `layout.tsx` or `template.tsx` (any
+  `.ts/.tsx/.js/.jsx` extension) is not wrapped: it receives `children`, which
+  cannot be part of a cache key.
+- Functions carrying their own `"use server"` directive are server actions, not
+  cached functions, and are left alone.
 
 ## Backing Store
 
-Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
-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.
+`"use cache"` reads and writes the app-level store from `createRouter({ cache })`
+— the same store `cache()` boundaries and cached loaders use. One store, one
+configuration. (`Static()`/`Prerender()` output is not in this store; it is
+built into the server bundle, see `/prerender`.)
+
+Entries are tagged by the profile's `tags` plus any runtime `cacheTag(...tags)`
+calls in the function body. `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 `ppr` shell / document-cache entry instead
+(see `/caching` → "Tag-Based Invalidation"). All built-in stores
+(`MemorySegmentCacheStore`, `CFCacheStore`, `VercelCacheStore`) 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`, cross-colo
+invalidation needs a `kv` namespace (markers live in that same namespace) or
+`tagPurge`. The separate `revalidate()` export is the client-update axis (which
+segments re-render on a navigation or action), not a cache bust.
+
+A `"use cache"` entry's tags do not propagate to an enclosing `cache()` segment
+entry: invalidating them re-runs the function on the next miss of the outer
+boundary, not before (see `/cache-guide` → "Nesting rule").
 
 ## 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({ 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
-
-In development, the Vite transform still wraps functions, but the cache store is
-a `MemorySegmentCacheStore` that works locally. Functions cache normally in dev
-for testing cache behavior.
+| Mechanism        | Granularity        | When       | Use case                                              |
+| ---------------- | ------------------ | ---------- | ----------------------------------------------------- |
+| `"use cache"`    | Function/component | Runtime    | Cache individual data fetches or components           |
+| loader `cache()` | One loader's data  | Runtime    | Cache a loader result while the page stays live       |
+| `cache()` DSL    | Route segment tree | Runtime    | Cache entire route subtrees with children             |
+| `ppr`            | HTML shell         | Runtime    | Serve a cached HTML shell, resume live holes (`/ppr`) |
+| `Static()`       | One segment        | Build-time | Render once at build, no params                       |
+| `Prerender()`    | Route segment tree | Build-time | Pre-render known params, optional live fallback       |
+
+Inside a `ppr` shell, a `"use cache"` value that renders as shell material is
+pinned at capture time for the life of that shell (see `/ppr` → Pitfalls).
+
+## Dev Mode and tests
+
+The transform runs in dev exactly as in production, but caching only happens
+when the router has a store: there is no implicit dev store. Configure one (a
+`MemorySegmentCacheStore` is the usual dev/test choice) to see cache hits
+locally.
+
+With no item-capable store configured, a `"use cache"` function simply runs on
+every call. The request-scoped guards (`cookies()`, `ctx.set()`, …) are not
+active on that uncached path, so a guard violation only shows up once a store is
+configured — test with a store. Under Vitest, `runLoader`, `renderHandler`, and
+the other `@rangojs/router/testing` helpers take `{ cacheStore, cacheProfiles }`
+and warn when a cached function ran without one (see `/testing`).

package/skills/vercel/SKILL.md

@@ -6,7 +6,11 @@ argument-hint:
 
 # Vercel deployment
 
-The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry, folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/` — a single streaming Node Function plus the static client assets.
+This skill covers deploying a Rango app to Vercel Functions: the `vercel`
+preset, function settings, the Runtime Cache store, host routers, tracing, and
+local validation. For router options in general see `/router-setup`.
+
+The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry (it imports the named `router` export of your `createRouter()` module), folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/`: a single streaming Node Function plus the static client assets.
 
 ## Deployment boundary
 
@@ -30,27 +34,27 @@ checklist before adding shared-cache headers.
 ## Setup
 
 ```bash
-npm install @vercel/functions
+pnpm add @vercel/functions
 ```
 
 ```typescript
 // vite.config.ts
 import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
-  plugins: [react(), rango({ preset: "vercel" })],
+  plugins: [rango({ preset: "vercel" })], // add react() first if you use @vitejs/plugin-react
 });
 ```
 
 `@vercel/functions` is required: it backs the generated function launcher (`waitUntil`) and `VercelCacheStore`. The build fails with a clear error if it is missing.
 
-`vite build` produces `.vercel/output`; deploy with the Vercel CLI (`vercel deploy --prebuilt`) or via Git integration.
+`vite build` produces `.vercel/output`; deploy with the Vercel CLI (`vercel deploy --prebuilt`) or via Git integration. The generated routing serves files first (hashed assets under the assets directory get `Cache-Control: public, max-age=31536000, immutable`) and sends everything else to the function.
 
 ## Function configuration
 
-Per-function knobs go under `vercel` and are written into `.vc-config.json`:
+Per-function knobs go under `vercel` and are written into `.vc-config.json`
+(`functionName` also sets the `config.json` route):
 
 ```typescript
 rango({
@@ -60,11 +64,15 @@ rango({
     maxDuration: 30, // seconds, default
     memory: 1024, // MB (platform default when omitted)
     regions: ["fra1"], // pin regions (platform default when omitted)
-    functionName: "index", // the <name>.func dir + config.json route
+    functionName: "index", // the <name>.func dir + config.json route (default)
   },
 });
 ```
 
+`runtime` must be a `nodejs*` runtime. The preset emits a Node serverless
+function, so the build fails on any other value; the Edge runtime is not
+supported.
+
 ## Runtime Cache
 
 `VercelCacheStore` wraps the Vercel Runtime Cache for segment, item, response,
@@ -72,6 +80,7 @@ and PPR shell families. Locally (no `process.env.VERCEL`) fall back to an
 in-memory store so dev/preview work without the platform:
 
 ```typescript
+import { createRouter } from "@rangojs/router";
 import {
   MemorySegmentCacheStore,
   VercelCacheStore,
@@ -97,7 +106,7 @@ function resolveCache() {
 export const router = createRouter({ cache: resolveCache }).routes(/* ... */);
 ```
 
-The cache factory receives `(env, ctx)`; on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`.
+The cache factory receives `(env, ctx)`: on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`; off-platform `ctx` is `undefined`. Cache semantics and tag invalidation: `/caching`, `/cache-guide`.
 
 ## Host routers (multi-app)
 
@@ -121,7 +130,7 @@ hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
 export default hostRouter; // the instance
 ```
 
-`{ env, ctx }` is threaded unchanged from the function to each matched sub-app's handler and its `cache(env, ctx)` factory. See the `host-router` skill for sub-app structure and routing patterns.
+`{ env, ctx }` is threaded unchanged from the function to each matched sub-app's handler and its `cache(env, ctx)` factory. See `/host-router` for sub-app structure and routing patterns.
 
 ## Tracing (custom spans)
 
@@ -138,12 +147,13 @@ registerOTel({ serviceName: "my-app" });
 export const tracing = createVercelTracing();
 
 // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+import { createRouter } from "@rangojs/router";
 import { tracing } from "./instrumentation.js";
 export const router = createRouter({ tracing }).routes(/* ... */);
 ```
 
-`createVercelTracing(opts?)` takes `{ enabled, spans, tracerName, tracer }` — same phase set as `createCloudflareTracing` (`rango.request/middleware/action/loader/render/ssr`). Caveats: Node-runtime only (Vercel custom spans are unsupported on Edge); `registerOTel()` must run before the first request; `@vercel/otel` is what unlocks Vercel Session Tracing + Trace Drains. The deploy bundles `@vercel/otel` and its `@opentelemetry/*` peers into the function (no `node_modules` at runtime), so they must be installed. See `examples/vercel-basic` for a worked hybrid setup and the `observability` skill for the cross-platform tracing model.
+`createVercelTracing(opts?)` takes `{ enabled, spans, tracerName, tracer }` (`tracerName` defaults to `"rango"`; `tracer` overrides the global tracer) and emits the same phases as `createCloudflareTracing`: `rango.request`, `rango.middleware`, `rango.action`, `rango.loader`, `rango.handler`, `rango.render`, `rango.ssr`, `rango.response`, and `rango.background`. Caveats: Node-runtime only (Vercel custom spans are unsupported on Edge); `registerOTel()` must run before the first request; `@vercel/otel` is what unlocks Vercel Session Tracing + Trace Drains. The deploy bundles `@vercel/otel` and its `@opentelemetry/*` peers into the function (no `node_modules` at runtime), so they must be installed. The Rango repository's `examples/vercel-basic` (not shipped in this package) has a worked setup; `/observability` covers the cross-platform tracing model.
 
 ## Local validation without deploying
 
-`vite preview` serves the static client assets only. To preview the RSC **function**, serve the assembled `.vercel/output` behind filesystem-then-function routing — `examples/vercel-basic/scripts/preview.mjs` does this (and `pnpm preview:vercel` runs it). For a faithful deploy test (isolated filesystem, ESM, self-contained bundle), `examples/vercel-basic/scripts/smoke.mjs` serves it from a temp dir outside the repo. Both share `scripts/serve-vercel-output.mjs`.
+`vite preview` does not run the assembled function. To exercise it locally, serve `.vercel/output` with filesystem-then-function routing (static files first, everything else to `functions/<name>.func/index.mjs`). The Rango repository's `examples/vercel-basic` (not shipped in this package) has two scripts for this: `scripts/preview.mjs` (`pnpm preview:vercel`) serves it in place, and `scripts/smoke.mjs` copies it to a temp dir outside the repo for a faithful deploy test (isolated filesystem, ESM, self-contained bundle). Both share `scripts/serve-vercel-output.mjs`.