@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/skills/observability/SKILL.md

@@ -73,19 +73,75 @@ const router = createRouter({
 });
 ```
 
-For OpenTelemetry:
+For OpenTelemetry — phase spans come from the `tracing` slot
+(`createOTelTracing`), discrete-fact spans from the `telemetry` sink
+(`createOTelSink`):
 
 ```typescript
-import { createRouter, createOTelSink } from "@rangojs/router";
+import {
+  createRouter,
+  createOTelTracing,
+  createOTelSink,
+} from "@rangojs/router";
 import { trace } from "@opentelemetry/api";
 
+const tracer = trace.getTracer("my-app");
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createOTelTracing(tracer), // request/loader/render/… phase spans
+  telemetry: createOTelSink(tracer), // handler errors, cache decisions, …
+});
+```
+
+On **Cloudflare Workers**, use `createCloudflareTracing` for the `tracing` slot
+instead — it emits the same phases as native Cloudflare custom spans (in the
+Workers trace waterfall, next to the automatic KV/D1/fetch spans), with no
+`@opentelemetry/api` dependency:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
 const router = createRouter({
   document: Document,
   urls: urlpatterns,
-  telemetry: createOTelSink(trace.getTracer("my-app")),
+  tracing: createCloudflareTracing(), // all phases on by default
+  // tracing: createCloudflareTracing({ spans: { ssr: false } }), // toggle phases
 });
 ```
 
+On **Vercel Functions** (Node runtime), use `createVercelTracing` — a thin
+wrapper over `createOTelTracing` that reads the global OTel tracer
+`@vercel/otel`'s `registerOTel()` installs, so you do not call `trace.getTracer`
+yourself. Custom spans are Node-only (unsupported on the Edge runtime):
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config.
+// Importing this module is what runs registerOTel() — a Rango/Vite app does not
+// auto-load instrumentation.ts like Next.js, so a standalone registerOTel() that
+// nothing imports is a silent no-op.
+import { registerOTel } from "@vercel/otel";
+import { createVercelTracing } from "@rangojs/router/vercel";
+registerOTel({ serviceName: "my-app" });
+export const tracing = createVercelTracing(); // { enabled, spans, tracerName, tracer }
+
+// router.tsx — importing `tracing` runs instrumentation.ts
+import { createRouter } from "@rangojs/router";
+import { tracing } from "./instrumentation.js";
+
+const router = createRouter({ document: Document, urls: urlpatterns, tracing });
+```
+
+These factories return a `RouterTracingConfig` for the same `tracing` slot;
+`telemetry` stays independent (events only, no phase spans). Phase spans:
+`rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
+`rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline
+shows, co-emitted from one site. Off-platform (no Cloudflare tracing destination
+/ no OTel SDK) every span call is a transparent pass-through, so the request
+behaves as if tracing were off.
+
 Custom sinks implement `emit(event)`:
 
 ```typescript
@@ -103,7 +159,8 @@ const router = createRouter({
 ```
 
 Events include `request.start/end/error`, `loader.start/end/error`,
-`handler.error`, `cache.decision`, and `revalidation.decision`.
+`handler.error`, `cache.decision`, `revalidation.decision`, `request.timeout`,
+and `request.origin-rejected`.
 
 ## Debugging revalidation and stale data
 

package/skills/parallel/SKILL.md

@@ -330,6 +330,8 @@ parallel({
 Control when parallel routes revalidate:
 
 ```typescript
+import * as CartActions from "./actions/cart";
+
 parallel(
   {
     "@cart": () => <CartSummary />,
@@ -337,7 +339,7 @@ parallel(
   () => [
     loader(CartLoader),
     // Revalidate when cart actions occur
-    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
   ]
 )
 ```
@@ -360,8 +362,10 @@ the parallel consumer:
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") || undefined;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -429,6 +433,7 @@ function MyLayout() {
 ```typescript
 import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
   return (
@@ -479,7 +484,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
       ]
     ),
 

package/skills/prerender/SKILL.md

@@ -119,6 +119,8 @@ interface BuildContext<TParams> {
   use: <T>(handle: Handle<T>) => (data: T) => void; // Push handle data
   url: URL; // Synthetic URL from pattern + params
   pathname: string; // Pathname from synthetic URL
+  searchParams: URLSearchParams; // URLSearchParams from the synthetic URL (always empty for prerender)
+  search: {}; // Typed search params -- always {} for prerender (no real query string)
   set(key: string, value: any): void; // Set context variable (string key)
   set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
   get(key: string): any; // Read context variable (string key)
@@ -343,14 +345,31 @@ export const TocSidebar = Static(() => {
 
 ### Error behavior at build time
 
-| Handler outcome             | Effect                                                |
-| --------------------------- | ----------------------------------------------------- |
-| JSX / `null`                | Normal prerender entry, log OK                        |
-| `return ctx.passthrough()`  | Skip entry, log PASS, continue (Passthrough routes)   |
-| `throw new Skip("reason")`  | Skip entry, log SKIP, continue with remaining entries |
-| `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail the build      |
+When a render throws a non-`Skip` error, it is **surfaced to the build** — never
+baked into a frozen error page served as a 200 (issue #587). What happens next is
+controlled by `prerender.onError` in your `rango()` options:
 
-Both error types propagate to the router's `onError` callback with phase
+```ts
+rango({ prerender: { onError: "warn" } }); // default is "fail"
+```
+
+| Handler outcome             | `onError: "fail"` (default)                  | `onError: "warn"`                |
+| --------------------------- | -------------------------------------------- | -------------------------------- |
+| JSX / `null`                | Normal prerender entry, log OK               | Normal prerender entry, log OK   |
+| `return ctx.passthrough()`  | Skip entry, log PASS (Passthrough routes)    | Skip entry, log PASS             |
+| `throw new Skip("reason")`  | Skip entry, log SKIP, continue               | Skip entry, log SKIP, continue   |
+| `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail build | Log WARN, skip the URL, continue |
+
+With `"warn"` the errored entry is logged and left un-baked (never served as a baked
+200 error page). `"warn"` is a build-unblock, not a runtime contract: the route falls
+through to normal resolution — it may render live (its handler is still bundled) or
+404 (once other baked entries trigger prerender handler eviction), so the outcome
+depends on the rest of the build, and a skipped `Static()` handler's evicted code can
+surface as an error. For DEFINED runtime behavior reach for `Passthrough()` (a live
+fallback) or `throw new Skip()` (an intentional skip — works in the render fn, not
+only `getParams()`); otherwise prefer the default `"fail"`.
+
+Both `Skip` and hard errors propagate to the router's `onError` callback with phase
 `"prerender"` or `"static"`.
 
 ### Build logs
@@ -370,9 +389,11 @@ The build produces per-URL timing logs:
 [rango] Static render complete: 2 done, 1 skipped (120ms total)
 ```
 
-A `FAIL` line is logged per-URL when a handler throws a non-Skip error. The
-error is re-thrown immediately, so no summary line is printed — the build
-stops at the first failure.
+A `FAIL` line is logged per-URL when a handler throws a non-Skip error (with the
+default `prerender.onError: "fail"`). The error is re-thrown immediately, so no
+summary line is printed — the build stops at the first failure. Under
+`prerender.onError: "warn"` the same case logs a `WARN` line, skips that URL, and
+the build continues.
 
 ### Dev mode behavior
 

package/skills/rango/SKILL.md

@@ -154,6 +154,12 @@ returned, for outcome-conditional revalidation. The arg also exposes `actionId`
 (raw `path#export`), `actionUrl`, `formData`, `method`, and `stale` (cross-tab
 `_rsc_stale` signal). All are `undefined` on plain navigation (no action).
 
+Two idioms, picked by what an _unrelated_ action should do. `ctx.isAction()`
+returns a raw boolean, so combine it with `|| undefined` to **defer** ("mine,
+else let the default decide": `ctx.isAction(CartActions) || undefined`) or leave
+it bare to **suppress** ("mine only": `ctx.isAction(CartActions)`). Prefer the
+defer form unless a sibling segment must own the unrelated-action decision.
+
 ```ts
 // re-render only when checkout actually succeeded; defer otherwise
 revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
@@ -192,6 +198,7 @@ Grouped by concern — read when you need to…
 | `/host-router`            | Multi-app host routing with domain/subdomain patterns                      |
 | `/links`                  | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
 | `/response-routes`        | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/api-client`             | Typed client for consuming your own response-route JSON APIs (recipe)      |
 | `/mime-routes`            | Content negotiation — same URL, different response types via Accept header |
 | `/streams-and-websockets` | SSE via `path.stream` and WebSocket upgrades via `path.any`                |
 | `/handler-use`            | Attach default loaders/middleware to a handler via `handler.use`           |
@@ -211,16 +218,18 @@ Grouped by concern — read when you need to…
 
 **Client & presentation** — build the client-side UX:
 
-| Skill               | Description                                                               |
-| ------------------- | ------------------------------------------------------------------------- |
-| `/hooks`            | Client-side React hooks                                                   |
-| `/theme`            | Light/dark mode with FOUC prevention                                      |
-| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration |
-| `/fonts`            | Load web fonts with preload hints                                         |
-| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                |
-| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots             |
-| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                     |
-| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope        |
+| Skill               | Description                                                                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `/hooks`            | Client-side React hooks                                                                                                            |
+| `/theme`            | Light/dark mode with FOUC prevention                                                                                               |
+| `/i18n`             | Locale routing with `:locale?`, resolution chains, react-intl integration                                                          |
+| `/fonts`            | Load web fonts with preload hints                                                                                                  |
+| `/css`              | Import CSS in the Document `<head>` (`?url` + managed `precedence` links)                                                          |
+| `/scripts`          | Inject third-party scripts (GTM/analytics) into head/body via the `Script` handle; nonce auto-applied to document-rendered scripts |
+| `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                                                                         |
+| `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
+| `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
+| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |
 
 **Observability & production health**:
 
@@ -230,6 +239,18 @@ Grouped by concern — read when you need to…
 | `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
 | `/debug-manifest`  | Inspect route manifest structure                                         |
 
+**Deployment**:
+
+| Skill     | Description                                                                               |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `/vercel` | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing` |
+
+**Testing**:
+
+| Skill      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `/testing` | Unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement) |
+
 **Setup, types & migration**:
 
 | Skill                   | Description                                     |

package/skills/response-routes/SKILL.md

@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,20 +241,23 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
+
 ### Rango.PathResponse (global lookup by URL pattern or concrete path)
 
 `Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
 which carries response payload metadata. That surface is **not** auto-wired —
 without the augmentation below, `Rango.PathResponse` falls back to the generated
 path/search map, or to a permissive map when nothing is generated. Either way, it
-has no response payload metadata, so response routes resolve to
-`ResponseEnvelope<never>`:
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
 // router.tsx
@@ -261,11 +275,11 @@ With that in place, look up the response type by URL pattern (ambient, no import
 ```typescript
 // After include("/api", apiPatterns) in main urls
 type Health = Rango.PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
-// RSC routes return ResponseEnvelope<never>
+// RSC routes (no JSON payload) return never
 type Home = Rango.PathResponse<"/">;
-// = ResponseEnvelope<never>
+// = never
 ```
 
 `Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
@@ -280,7 +294,7 @@ async function get<T extends Rango.Path>(
   return fetch(href(path)).then((r) => r.json());
 }
 
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -288,7 +302,7 @@ route can match several patterns and union their responses.
 
 `Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
 return: `path.json()` serializes with `JSON.stringify`, so a handler returning
-`{ createdAt: Date }` resolves to `ResponseEnvelope<{ createdAt: string }>`. This
+`{ createdAt: Date }` resolves to the bare `{ createdAt: string }`. This
 runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
 honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
 `RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
@@ -302,7 +316,7 @@ the response payload straight from the `urls()` patterns and needs no
 ### ParamsFor with Response Routes
 
 ```typescript
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // Works for both RSC and response routes
 type ProductParams = ParamsFor<"api.productDetail">;
@@ -408,17 +422,17 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
 // After mounting -- names get prefixed.
 // Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
-// otherwise it resolves to ResponseEnvelope<never>.
+// otherwise it resolves to never.
 type BlogStats = Rango.PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -462,7 +476,11 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/route/SKILL.md

@@ -246,10 +246,12 @@ the producer route and the consumer child segments.
 
 ```typescript
 // revalidation-contracts.ts
+import * as CheckoutActions from "./actions/checkout";
+
 // Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
 // so when the same segment composes multiple contracts the later ones never run.
-export const revalidateCheckoutData = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") || undefined;
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -294,6 +296,12 @@ path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
 path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 ```
 
+> **Redirecting from a route with `loading()`:** an `async` handler that returns
+> a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
+> so the redirect is rendered into the RSC stream instead of becoming an HTTP
+> redirect. Issue the redirect from `middleware`, a loader, or a **synchronous**
+> handler return instead. (Dev logs a warning if this is hit.)
+
 ### Redirect with location state
 
 Carry typed state through redirects (e.g. flash messages):
@@ -338,6 +346,10 @@ state persists on back/forward. See `/hooks` for details.
 Attach location state to any server response (not just redirects):
 
 ```typescript
+import { createLocationState } from "@rangojs/router";
+
+const ServerInfo = createLocationState<{ data: string }>();
+
 path("/dashboard", (ctx) => {
   ctx.setLocationState(ServerInfo({ data: "welcome" }));
   return <Dashboard />;

package/skills/router-setup/SKILL.md

@@ -62,6 +62,9 @@ urls(
     revalidate, // Control revalidation
     intercept, // Intercept routes for modals
     when, // Conditional rendering
+    errorBoundary, // Add an error boundary
+    notFoundBoundary, // Add a not-found boundary
+    transition, // Configure view transitions
   }) => [
     // Route definitions here
   ],
@@ -469,14 +472,35 @@ const router = createRouter({
 ```
 
 ```typescript
-// OpenTelemetry for production
-import { createRouter, createOTelSink } from "@rangojs/router";
+// OpenTelemetry for production: phase spans via the tracing slot,
+// discrete-fact spans via the telemetry sink.
+import {
+  createRouter,
+  createOTelTracing,
+  createOTelSink,
+} from "@rangojs/router";
 import { trace } from "@opentelemetry/api";
 
+const tracer = trace.getTracer("my-app");
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createOTelTracing(tracer),
+  telemetry: createOTelSink(tracer),
+});
+```
+
+```typescript
+// On Cloudflare Workers, swap the tracing factory for native custom spans
+// (no @opentelemetry/api dependency); the telemetry slot is unchanged.
+// On Vercel (Node runtime) use createVercelTracing() from @rangojs/router/vercel.
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
 const router = createRouter({
   document: Document,
   urls: urlpatterns,
-  telemetry: createOTelSink(trace.getTracer("my-app")),
+  tracing: createCloudflareTracing(), // { spans: { ssr: false } } to toggle phases
 });
 ```