@rangojs/router 0.16.0 → 0.18.0

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}`.
@@ -107,6 +142,11 @@ 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.
 
+The key is only what the function declares: its id and arguments. A call made
+inside a route `cache()` with a `key()` does not inherit that key, so a value
+the route partitions by (a tier header, a session) must be passed in as an
+argument. The same holds for a loader's own `cache()` (`/loader` → "Cache Key").
+
 ### Route context is folded into the key
 
 The tainted `ctx` object is excluded from arg serialization (see below), but
@@ -117,16 +157,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 +208,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,27 +236,57 @@ 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).
+(the consumption-lane rule, `/rango` → Invariants). The PPR shell is stricter
+about the loader's own reads: during a capture, `cookies()`, `headers()`, and a
+`{ cache: false }` variable read inside a handler-consumed loader refuse the
+capture.
 
 ### 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()` 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 +370,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 +468,104 @@ 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 what the render stores: the enclosing route `cache()`
+entry, a cached loader's own entry when called in its body, and the `ppr`
+shell or document-cache entry built from them (on a `ppr` route, only when
+shell material calls it). See `/caching` → "Tag-Based Invalidation". All
+built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`,
+`VercelCacheStore`) index by tag. Invalidate on demand with
+`updateTag(...tags)` (awaitable; for server actions) or
+`revalidateTag(...tags)` (background, non-blocking; for route
+handlers/webhooks). Both evict rather than mark stale, and the request that
+calls either reads its own writes; `updateTag()` also waits for the durable
+write. PPR shell reads on `CFCacheStore`/`VercelCacheStore` go through
+per-isolate memos, which the invalidating user skips via the fresh-reads
+cookie. 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 control (which segments re-render
+on a navigation or action), not a cache bust.
+
+A route `cache()` entry stores the tags of the `"use cache"` reads inside it,
+so `updateTag()` of one evicts the enclosing entry and any `ppr` shell or
+document built from it. A loader's own `cache()` entry does the same for the
+reads in its body. The exception is a `"use cache"` function called inside
+another `"use cache"` function: its tags do not reach the enclosing entry, so
+invalidating one of them neither evicts the outer entry nor keeps this request
+from joining or storing an outer call that started before the invalidation
+([#980](https://github.com/rangojs/rango/issues/980)).
 
 ## 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). A
+hole's own read (in a loader without `ssr: false` under `loading()` or an
+inline `<Suspense>`) returns the current entry, not the shell's copy, unless a
+loader the capture ran (an `ssr: false` loader, or one a handler awaits) read
+the same entry.
+
+## 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,
@@ -80,12 +89,24 @@ import { getCache, waitUntil } from "@vercel/functions";
 
 const defaults = { ttl: 60, swr: 300 };
 const memoryStore = new MemorySegmentCacheStore({ defaults });
+// One handle per process: getCache() resolves the platform cache on every
+// call, and VercelCacheStore keeps its PPR shell and tag-marker memos per
+// handle. After updateTag(), the same process misses at once, the rest of the
+// region once its marker memo refreshes (memo.markerMaxStaleMs, default 2000),
+// and the mutating user at once (the fresh-reads cookie skips the memos).
+// Another region serves a memoized shell until memo.shellMs (default 2000)
+// passes, since the tag markers are regional and only expireTag is global. A
+// platform expireTag issued outside rango writes no marker, so every memo
+// serves the shell until its window passes.
+const runtimeCache = process.env.VERCEL
+  ? getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })
+  : undefined;
 
 function resolveCache() {
-  if (process.env.VERCEL) {
+  if (runtimeCache) {
     return {
       store: new VercelCacheStore({
-        cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+        cache: runtimeCache,
         waitUntil,
         defaults,
       }),
@@ -97,7 +118,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 +142,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 +159,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`.