@rangojs/router 0.16.0 → 0.18.0

package/skills/catalog.json

@@ -17,19 +17,19 @@
     },
     {
       "name": "bundle-analysis",
-      "description": "Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.",
+      "description": "Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and poor client-chunk grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.",
       "argumentHint": "<app-dir>",
       "path": "skills/bundle-analysis/SKILL.md"
     },
     {
       "name": "cache-guide",
-      "description": "When to use cache() DSL vs \"use cache\" directive — key differences and decision guide. Use when unsure which caching mechanism fits a given problem, comparing route/segment caching, function-level caching, and document-level caching, or asking \"which cache API should I use\".",
+      "description": "Decision guide for Rango's cache layers — \"use cache\", loader cache(), segment cache(), Prerender/Static, the ppr HTML shell, and document/CDN caching — with the cache() vs \"use cache\" comparison (keys, guards, SWR, nesting). Use when unsure which caching mechanism fits a problem, comparing layers, or asking \"which cache API should I use\".",
       "argumentHint": "",
       "path": "skills/cache-guide/SKILL.md"
     },
     {
       "name": "caching",
-      "description": "Configure route/segment-subtree caching with memory, Cloudflare KV, or Vercel cache stores in @rangojs/router. Use when responses should be cached or revalidated, data is stale or not updating after code changes, or you are wiring up a cache store.",
+      "description": "Configure segment caching with the cache() DSL in @rangojs/router — TTL/SWR, tags and updateTag/revalidateTag, loader-level caching, and the Memory, Cloudflare (Cache API + optional KV), and Vercel Runtime Cache stores. Use when responses should be cached or revalidated, data is stale or not updating after changes, or you are wiring up a cache store.",
       "argumentHint": "[setup]",
       "path": "skills/caching/SKILL.md"
     },
@@ -53,7 +53,7 @@
     },
     {
       "name": "composability",
-      "description": "Reusable composition patterns with globally importable route helpers in @rangojs/router. Use when sharing loaders, middleware, or handler logic across multiple route files, or avoiding copy-pasting the same route setup everywhere.",
+      "description": "Reusable composition patterns with globally importable route helpers and include() modules in @rangojs/router. Use when sharing loaders, middleware, or caching config across multiple route files, splitting routes into eager or code-split include() groups, or avoiding copy-pasting the same route setup everywhere.",
       "argumentHint": "pattern-name",
       "path": "skills/composability/SKILL.md"
     },
@@ -65,7 +65,7 @@
     },
     {
       "name": "debug-manifest",
-      "description": "Debug and inspect route manifest structure. Use when routes aren't matching as expected, you need to see the generated route tree, or a path resolves to the wrong handler.",
+      "description": "Inspect the router's route manifest (route/layout tree, shortCodes, parent links, loader/middleware flags) and diff it between versions. Use when routes aren't matching as expected, you need to see the generated route tree, or a path resolves to the wrong handler.",
       "argumentHint": "",
       "path": "skills/debug-manifest/SKILL.md"
     },
@@ -137,13 +137,13 @@
     },
     {
       "name": "loader",
-      "description": "Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (ssr:false).",
+      "description": "Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, or must be settled in the SSR'd document (ssr:false).",
       "argumentHint": "[loader]",
       "path": "skills/loader/SKILL.md"
     },
     {
       "name": "middleware",
-      "description": "Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.",
+      "description": "Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects. Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, or deciding whether middleware wraps server actions.",
       "argumentHint": "[middleware-name]",
       "path": "skills/middleware/SKILL.md"
     },
@@ -173,7 +173,7 @@
     },
     {
       "name": "parallel",
-      "description": "Define parallel routes for multi-column layouts, sidebars, and modal slots in @rangojs/router. Use when a layout needs multiple independently-loading regions (e.g. a sidebar and main panel), or rendering more than one route segment at the same URL.",
+      "description": "Define parallel routes (named slots) for multi-column layouts, sidebars, and UI-less metadata slots in @rangojs/router. Use when a layout needs multiple independently-loading regions (e.g. a sidebar and main panel), or rendering more than one route segment at the same URL.",
       "argumentHint": "[@slot-name]",
       "path": "skills/parallel/SKILL.md"
     },
@@ -185,7 +185,7 @@
     },
     {
       "name": "prerender",
-      "description": "Pre-render route segments at build time with Prerender and Passthrough live fallback. Use when a page's content is mostly static and shouldn't render on every request, speeding up cold responses, or deciding which routes to prerender vs render live.",
+      "description": "Pre-render route segments at build time with Prerender (with getParams), Passthrough live fallback, Static segments, and Skip. Use when a page's content is mostly static and shouldn't render on every request, speeding up cold responses, reading build-only data (files, build env), or deciding which routes to prerender vs render live.",
       "argumentHint": "[passthrough]",
       "path": "skills/prerender/SKILL.md"
     },
@@ -203,19 +203,19 @@
     },
     {
       "name": "response-routes",
-      "description": "Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, or asking how to return raw JSON instead of RSC from a route.",
+      "description": "Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, asking how to return raw JSON instead of RSC from a route, or protecting a state-changing endpoint from CSRF.",
       "argumentHint": "[json|text|html|xml|md|image|stream]",
       "path": "skills/response-routes/SKILL.md"
     },
     {
       "name": "route",
-      "description": "Define routes with path() in @rangojs/router. Use when creating a new page or route, or asking how to define a URL path and its handler.",
+      "description": "Define routes with path() in @rangojs/router — URL params, catch-alls, typed search params, the handler context, handler-to-child data, and redirects. Use when creating a new page or route, or asking how to define a URL path and its handler.",
       "argumentHint": "[pattern]",
       "path": "skills/route/SKILL.md"
     },
     {
       "name": "router-setup",
-      "description": "Create and configure the RSC router with createRouter. Use when bootstrapping a new Rango app, or configuring top-level router options like base path, cache store, or environment.",
+      "description": "Create and configure a Rango app with createRouter() and the rango() Vite plugin. Use when bootstrapping a new app, wiring vite.config, writing the Document or worker entry, or setting top-level router options (basename, cache store, prefetch, timeouts, origin check, telemetry, SSR streaming).",
       "argumentHint": "[option]",
       "path": "skills/router-setup/SKILL.md"
     },
@@ -227,7 +227,7 @@
     },
     {
       "name": "server-actions",
-      "description": "Define and call server actions (`\"use server\"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation. Use when handling a form submission on the server, calling a server function from a client component, or needing optimistic UI after a mutation.",
+      "description": "Define and call server actions (`\"use server\"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, post-action revalidation, client-cache control (keepClientCache), and the default CSRF origin check. Use when handling a form submission on the server, calling a server function from a client component, choosing what re-renders after a mutation, needing optimistic UI after a mutation, or asking how actions are protected from CSRF.",
       "argumentHint": "[action]",
       "path": "skills/server-actions/SKILL.md"
     },
@@ -251,19 +251,19 @@
     },
     {
       "name": "testing",
-      "description": "Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader or middleware, or asking how to test a route end-to-end in dev and production.",
+      "description": "Test @rangojs/router apps — unit (loaders, middleware, server actions, handles, transition/clientUrls predicates), client components (renderRoute), RSC/Flight (renderServerTree, renderHandler, serveShellRequest for PPR shells), integration (dispatch), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader, middleware, action, or handler, setting up vitest for a Rango app, or testing a route end-to-end in dev and production.",
       "argumentHint": "[layer]",
       "path": "skills/testing/SKILL.md"
     },
     {
       "name": "theme",
-      "description": "Opt-in theme system with FOUC prevention for light/dark mode. Use when adding a light/dark mode toggle, or the page flashes the wrong theme on load (FOUC).",
+      "description": "Opt-in light/dark theme system with FOUC prevention, server-side theme access, and a useTheme() hook. Use when adding a light/dark mode toggle, reading or setting the theme in handlers or middleware, or when the page flashes the wrong theme on load (FOUC).",
       "argumentHint": "[setup]",
       "path": "skills/theme/SKILL.md"
     },
     {
       "name": "typesafety",
-      "description": "Set up type-safe routes, params, and environment types in @rangojs/router. Use when route or search params aren't typed, TypeScript can't infer a loader's return type, or wiring up typed environment bindings.",
+      "description": "Set up type-safe route names, params, search params, response payloads, and environment types in @rangojs/router. Use when route or search params aren't typed, ctx.env or ctx.get() is untyped, TypeScript can't infer a loader's return type, or wiring RegisteredRoutes / the generated route map.",
       "argumentHint": "[setup]",
       "path": "skills/typesafety/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -119,20 +119,27 @@ The async form works without a server wrapper module too:
 behavior, no startup win, uniform with code-split server groups.
 
 Route names compose through the include (`shop.index`, `shop.product`) and
-flow into the generated route map, so `href`/`reverse` and `Handler<"...">`
-typing work exactly as for server routes (`/typesafety`).
+flow into the generated route map, so `href()`, `ctx.reverse()` and
+`RouteParams<"shop.product">` typing work exactly as for server routes
+(`/typesafety`). `rango generate` also writes a per-module `.gen.ts` for a
+`clientUrls()` module, so components inside the group can link with
+`useReverse(routes)` (`/links`).
 
 ## Helpers: what exists inside clientUrls()
 
-| Helper         | Notes                                                                                                                                                          |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see /ppr skill; loader routes need `loading()` or capture refuses); no response variants |
-| `layout()`     | Must contain at least one `path()`                                                                                                                             |
-| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                         |
-| `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait          |
-| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
-| `transition()` | Data-only ViewTransition animation config — no `when`; same-route navs in a group already hold previous content without it                                     |
-| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
+| Helper         | Notes                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see `/ppr` → The loader lane rule); no response variants. Use callback may contain `loader()`, `loading()`, `transition()` |
+| `layout()`     | `layout(Component, () => [...])` — children are required and must contain at least one `path()`; may also hold `loader()`, `loading()`, `intercept()`, nested `layout()`                         |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                                                           |
+| `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait                                            |
+| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                                                               |
+| `transition()` | Inside a `path()` use callback only (at most one). Data-only ViewTransition config — no `when`; same-route navs in a group already hold previous content without it                              |
+| `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                                                            |
+
+At the top level of the builder only `path()`, `layout()` and `intercept()`
+are accepted, and the builder must define at least one `path()`. Any helper
+name not in this table throws (`clientUrls() has no route() helper`).
 
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
 `notFoundBoundary` **throw** — and that is a design position, not a gap.
@@ -201,16 +208,23 @@ browser — which is why the matcher (resolving an imported reference's
 import { addToCart, removeFromCart } from "./actions/cart";
 import * as CartActions from "./actions/cart";
 
-revalidate(({ isAction }) => isAction()); // any action
-revalidate(({ isAction }) => isAction(addToCart)); // one action
-revalidate(({ isAction }) => isAction(addToCart, removeFromCart)); // several
-revalidate(({ isAction }) => isAction(CartActions)); // import * as
-revalidate(({ isAction }) => isAction({ addToCart, removeFromCart })); // object
+// After an action, re-run only for cart actions; on navigation, keep the default.
+revalidate(({ isAction }) => (isAction() ? isAction(CartActions) : undefined));
+
+// Matcher forms (each returns a boolean):
+isAction(); // any action
+isAction(addToCart); // one action
+isAction(addToCart, removeFromCart); // several
+isAction(CartActions); // import * as
+isAction({ addToCart, removeFromCart }); // object
 ```
 
 Bare `isAction()` is "is this an action at all?". `actionId` stays as the
-string escape hatch. Return `isAction(refs) || undefined` to defer to the
-locked default on a non-match (same idiom as the server).
+string escape hatch. A group loader's locked default already re-runs after
+every action, so `isAction(refs) || undefined` changes nothing there; narrow
+with the ternary above instead (same rule as a server-tree loader). A bare
+`isAction(refs)` is a hard `false` on navigation too, so the loader stops
+refetching when params change.
 
 Two scars worth copying:
 
@@ -226,10 +240,12 @@ Two scars worth copying:
 Everything a DSL loader can do in the server tree works here — the loader body
 is server code either way.
 
-**Authority signals.** A loader may `throw notFound()` or
+**Authority signals.** A loader may call `notFound()` (it throws) or
 `throw redirect(url)`:
 
 ```ts
+import { createLoader, notFound, redirect } from "@rangojs/router";
+
 export const ProductLoader = createLoader(async (ctx) => {
   const moved = LEGACY_SLUGS[ctx.params.slug];
   if (moved) throw redirect(`/shop/product/${moved}`);
@@ -252,8 +268,9 @@ handler parity — `ctx.use(Meta)({ title })` pushes exactly like a handler
 push. Reads moved to `ctx.get(handle)`, gated behind `await ctx.rendered()`.
 Delivery follows the race model: pushes that settle before the handler barrier
 ride the SSR handle snapshot; later ones stream and apply post-hydration
-(document loads) or progressively (navigations). See `/loader` for the full
-contract.
+(document loads) or progressively (navigations). On a `ppr` shell HIT a loader
+without `ssr: false` never ran during the capture, so its pushes are never in
+the shell and always apply client-side. See `/loader` for the full contract.
 
 ## `ssr: false` — the SSR-completeness opt-in
 
@@ -265,7 +282,11 @@ document — `<head>` meta via a handle, or a real 404 status — flag it:
 
 ```ts
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { ssr: false }, () => [revalidate(productData)]),
+  loader(ProductLoader, { ssr: false }, () => [
+    revalidate(({ currentParams, nextParams, defaultShouldRevalidate }) =>
+      currentParams.slug !== nextParams.slug ? defaultShouldRevalidate : false,
+    ),
+  ]),
   loader(RelatedLoader),   // untouched: still streams behind its boundary
 ]),
 ```
@@ -286,13 +307,17 @@ Constraints:
   construction. It throws a deadlock error naming the fix.
 - `intercept()` loaders reject the flag — intercepts render on client
   navigations only, so a document-render await can never apply.
-- It does not change PPR capture behavior: capture renders mask loaders and
-  skip the await.
-
-Every document load pays the flagged loader's latency before first byte —
-that is the point, but it is a real cost. Keep flagged loaders fast (existence
-checks before expensive fetches) and flag the loaders that need it, not the
-route.
+- Under a `ppr` group route the flag is the bake lane, exactly as on a server
+  route (`/ppr` → The loader lane rule).
+
+Every document render that is not a `ppr` shell HIT pays the flagged
+loader's latency before first byte — that is the point, but it is a real cost.
+On a shell HIT the shell flushes first: a flagged loader whose value has no
+promises is served from the shell and does not run (unless the capture marked
+it to run: see `/ppr` → On a shell HIT), and one whose value
+carries promises runs on every HIT to fill its holes. Keep flagged loaders
+fast (existence checks before expensive fetches) and flag the loaders that
+need it, not the route.
 
 Pinned end to end by dev + production e2e in the router repository.
 
@@ -321,15 +346,17 @@ a hard load of the target URL renders the full route.
 - **Duplicate patterns or names throw** at definition time, per definition.
 - **`layout()` with no `path()` inside throws** — a client layout exists only
   to wrap routes.
-- **`loading()` vs inline Suspense:** same-route SEARCH navigations
-  (filters, tabs) hold previous content by default — the canonical commit
-  runs in a `startTransition` when no new segments mount, and the wrapping
-  layout sees `useOutlet().pending === true` for the held window; a
-  route-level `loading()` no longer re-flashes there. PARAM navigations
-  still remount (fresh skeleton, fresh state) unless the route declares
-  `transition()` — that opt-in drops the param from the segment key. Inline
-  `<Suspense>` above each `useLoader` read is still the finer-grained tool
-  when different reads on one route should wait independently.
+- **`loading()` vs inline Suspense:** same-route navigations hold previous
+  content by default, for SEARCH changes (filters, tabs) and PARAM changes
+  alike — group route segments are keyed by the group (`cg:<group>`,
+  `segment-system.tsx`), not by route id + params, so the mounted instance
+  reconciles instead of remounting. The canonical commit runs in a
+  `startTransition` when no new segments mount, and the wrapping layout sees
+  `useOutlet().pending === true` for the held window; a route-level
+  `loading()` does not re-flash there. `transition()` is not needed for the
+  hold; it adds the view-transition animation. Inline `<Suspense>` above each
+  `useLoader` read is still the finer-grained tool when different reads on
+  one route should wait independently.
 - **Two parallel loaders with equal latency look "SSR'd" together.** Loaders
   kick off in parallel, so awaiting one (`ssr: false`) gives
   same-or-faster siblings time to settle coincidentally. Do not read "it was

package/skills/cloudflare/SKILL.md

@@ -5,30 +5,36 @@ description: Deploy and operate @rangojs/router on Cloudflare Workers with the C
 
 # Cloudflare Workers deployment
 
+This skill covers running a Rango app on Cloudflare Workers: Vite and Wrangler
+config, the Worker entry, typed bindings, caching, and deployment. The
+references cover D1/KV setup, streaming and deploy diagnostics, and webhooks.
+For router options in general see `/router-setup`.
+
 Use the Cloudflare Vite plugin as the runtime bridge. It runs the real Worker
 entry in workerd during `vite dev` and `vite preview`, supplies bindings, and
-emits the deployable Worker configuration during `vite build`.
+emits the deployable Worker configuration during `vite build`. Unlike the Node
+and Vercel presets, you own the Worker entry.
 
 ## Install and configure
 
 ```bash
 pnpm add @rangojs/router react react-dom
-pnpm add -D vite @vitejs/plugin-react @cloudflare/vite-plugin \
-  @cloudflare/workers-types wrangler typescript
+pnpm add -D vite @cloudflare/vite-plugin @cloudflare/workers-types wrangler typescript
+# optional: @vitejs/plugin-react (e.g. for the React Compiler, see /react-compiler)
 ```
 
-Keep plugin order stable: React first, then Rango, then Cloudflare.
+Rango needs Node 24+ for the Vite toolchain. Keep plugin order stable:
+`react()` first when you use it, then `rango()`, then `cloudflare()`.
 
 ```typescript
 // vite.config.ts
 import { cloudflare } from "@cloudflare/vite-plugin";
-import react from "@vitejs/plugin-react";
 import { rango } from "@rangojs/router/vite";
 import { defineConfig } from "vite";
 
 export default defineConfig({
   plugins: [
-    react(),
+    // react(), // optional; first when used
     rango({ preset: "cloudflare", buildEnv: "auto" }),
     cloudflare({
       configPath: "./wrangler.json",
@@ -38,8 +44,16 @@ export default defineConfig({
 });
 ```
 
-`buildEnv: "auto"` exposes build-safe bindings to static/prerender collection.
-Omit it when build rendering must not access bindings.
+`viteEnvironment` must name the `rsc` environment with `ssr` as a child: the
+Worker runs the RSC entry and loads SSR inside the same isolate.
+
+`buildEnv: "auto"` gives `Prerender` and `Static` handlers a real `ctx.env` at
+build time through Wrangler's `getPlatformProxy()` (local bindings). Omit it
+(default `false`) when build-time rendering must not touch bindings; `ctx.env`
+then throws during build rendering. See `/prerender`.
+
+`wrangler.json` points `main` at the Worker entry and serves the client build
+as static assets:
 
 ```json
 {
@@ -81,7 +95,13 @@ does not need `@types/node` just to type-check Rango:
 }
 ```
 
-## Preserve the response stream
+## Worker entry
+
+Pass both `env` and `ctx` to `router.fetch`. Bindings reach handlers as
+`ctx.env`; the `ExecutionContext` backs `waitUntil`, `CFCacheStore`, and
+tracing. A bare `export default { fetch: router.fetch }` loses both, because
+Workers call `fetch(request, env, ctx)` while `router.fetch` takes
+`(request, { env, ctx })`.
 
 ```typescript
 // src/worker.rsc.tsx
@@ -97,8 +117,10 @@ export default {
 ```
 
 Do not call `response.text()` or `response.arrayBuffer()` on the Rango response
-in a custom Worker entry. That drains RSC/SSR streaming. Rewrap
-`new Response(response.body, response)` when only headers must change.
+in the Worker entry: that buffers the whole body and removes RSC/SSR streaming.
+When only headers must change, rewrap the body stream instead
+(`new Response(response.body, response)`); see
+[references/streaming-and-deploy.md](references/streaming-and-deploy.md).
 
 ## Choose the next reference
 
@@ -114,6 +136,7 @@ in a custom Worker entry. That drains RSC/SSR streaming. Rewrap
 Use the Cache API as L1 and KV as optional cross-colo L2:
 
 ```typescript
+import { createRouter } from "@rangojs/router";
 import { CFCacheStore } from "@rangojs/router/cache";
 
 export const router = createRouter<AppBindings>({
@@ -121,7 +144,7 @@ export const router = createRouter<AppBindings>({
   urls: urlpatterns,
   cache: (env, ctx) => ({
     store: new CFCacheStore({
-      ctx,
+      ctx: ctx!, // typed optional on the factory; always present on Workers
       kv: env.CACHE_KV,
       defaults: { ttl: 60, swr: 300 },
     }),
@@ -129,12 +152,54 @@ export const router = createRouter<AppBindings>({
 });
 ```
 
-PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
-L2; a KV hit promotes the coupled shell envelope back into L1. KV is optional:
-`CFCacheStore` without `kv` runs the shell family L1-only (edge-only ppr —
-each colo captures and serves its own shell). Tag eviction then needs purge
-mode (`tagPurge`); a tagged shell without either warns once and expires by
-ttl+swr only.
+`ctx` is required: the store schedules non-blocking writes with
+`ctx.waitUntil`, which is why the Worker entry must pass `{ env, ctx }` to
+`router.fetch`.
+
+Tag invalidation (`updateTag()` / `revalidateTag()`) stores its markers in the
+same `kv` namespace. Without `kv`, configure purge mode instead:
+`tagPurge: { zoneId, apiToken }` (an API token with `Zone.Cache Purge`, stored
+as a Worker secret) evicts tagged Cache API entries through Cloudflare's
+purge-by-tag API.
+
+PPR shells use the Cache API as the per-colo L1 and KV as the durable
+cross-colo L2; a KV hit promotes the shell back into L1. Without `kv` the shell
+family runs L1-only (each colo captures and serves its own shell). A tagged
+shell with neither `kv` nor `tagPurge` logs a warning once and expires only by
+ttl+swr. See `/caching` and `/ppr`.
+
+Shell reads are stale-while-revalidate through per-isolate memos: a warm
+isolate serves a shell it read within `memo.shellMs` (default 2000) from
+memory, and with `kv` it checks tag markers through a memo that is used as is
+for `memo.markerFreshMs` (default 1000) and while it refreshes in the
+background up to `memo.markerMaxStaleMs` (default 10000). After
+`updateTag()`/`revalidateTag()` the response sets the fresh-reads cookie
+(`rango-state-fresh` by default), so the mutating user's next requests skip
+the memos. That makes them fresh in the colo that ran the mutation; other
+colos converge once KV propagates the marker and their cached marker
+(`tagCacheTtl`) expires. In purge mode without `kv`, another isolate's memo
+keeps serving a purged shell until `memo.shellMs` passes. Set
+`memo: { shellMs: 0, markerFreshMs: 0 }` to remove the memo delay for every
+user's next request; cross-colo KV propagation (and `tagCacheTtl`) still
+applies. Details: `/caching` → "The fresh-reads cookie".
+
+## Tracing on Workers
+
+`createCloudflareTracing()` from `@rangojs/router/cloudflare` emits the
+router's phases as native Workers custom spans next to the automatic KV/D1/fetch
+spans. It reads the tracer from the `ctx` passed to `router.fetch`, and does
+nothing when Workers tracing is not enabled for the Worker. See
+`/observability`.
+
+```typescript
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
+export const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createCloudflareTracing(),
+});
+```
 
 ## Commands
 
@@ -149,5 +214,7 @@ ttl+swr only.
 }
 ```
 
-Use `vite dev` and `vite preview` for local RSC work. Reserve Wrangler for
-resource provisioning, migrations, secrets, and deployment.
+Always deploy the output of `vite build` (`dist/rsc/wrangler.json`; a plain
+`wrangler deploy` right after a build follows the plugin's redirect to it),
+never the source config. Use `vite dev` and `vite preview` for local RSC work. Reserve
+Wrangler for resource provisioning, migrations, secrets, and deployment.

package/skills/cloudflare/references/d1-and-local-dev.md

@@ -1,5 +1,8 @@
 # D1, KV, and local parity
 
+Provisioning D1/KV bindings, applying migrations, loading local secrets, and
+testing that `vite dev` and `vite preview` behave like the deployed Worker.
+
 ## Contents
 
 - [Provision bindings](#provision-bindings)
@@ -50,9 +53,11 @@ therefore visible to both `vite dev` and `vite preview`; treat the internal
 `.wrangler/state` layout as an implementation detail.
 
 Add a real handler probe while setting up the binding, then remove it after the
-first production-shaped test:
+first production-shaped test. `path.json` is a response route (`/response-routes`):
+return a value and it is serialized as JSON.
 
 ```typescript
+// inside urls(({ path }) => [ ... ])
 path.json("/__db-check", async (ctx) => {
   const row = await ctx.env.DB.prepare(
     "SELECT COUNT(*) AS n FROM users",
@@ -65,9 +70,17 @@ path.json("/__db-check", async (ctx) => {
 
 ## Use bindings
 
-Handlers, loaders, and middleware all receive the same typed bindings:
+Handlers, loaders, and middleware all receive the same typed bindings on
+`ctx.env`:
 
 ```typescript
+import {
+  cookies,
+  createLoader,
+  redirect,
+  type Middleware,
+} from "@rangojs/router";
+
 export const UserLoader = createLoader(async (ctx) =>
   ctx.env.DB.prepare("SELECT * FROM users WHERE id = ?")
     .bind(ctx.params.id)

package/skills/cloudflare/references/streaming-and-deploy.md

@@ -1,5 +1,9 @@
 # Streaming, preview, and deployment
 
+Keeping responses streamed through a custom Worker entry, choosing local
+tooling, route-owned CORS, deploying the built Worker, and isolating
+dev/preview differences.
+
 ## Contents
 
 - [Keep streamed responses intact](#keep-streamed-responses-intact)
@@ -80,9 +84,12 @@ pnpm exec vite build
 pnpm exec wrangler deploy -c dist/rsc/wrangler.json
 ```
 
-Do not deploy the source `main` from the root config after building. Wrangler's
-bundler cannot reconstruct Rango's Vite virtual modules. If the RSC environment
-has a custom name, use its matching `dist/<name>/wrangler.json` path.
+`vite build` also writes a `.wrangler/deploy/config.json` redirect, so a plain
+`wrangler deploy` run after the build picks up the same generated config. Never
+deploy the source `main` (for example `wrangler deploy -c wrangler.json`, or a
+deploy with no fresh build): Wrangler's bundler cannot reconstruct Rango's Vite
+virtual modules. If the RSC environment has a custom name, use its matching
+`dist/<name>/wrangler.json` path.
 
 Before deployment:
 

package/skills/cloudflare/references/webhooks-and-crypto.md

@@ -1,5 +1,9 @@
 # Webhooks and WebCrypto on Workers
 
+Verifying signed webhooks against the raw request body, testing them offline,
+porting Node crypto to WebCrypto, and keeping large SDKs out of the Worker's
+startup path.
+
 ## Contents
 
 - [Read the original request body](#read-the-original-request-body)
@@ -136,10 +140,13 @@ provider behavior when upgrading the SDK major.
 
 ## Keep SDKs off the cold path
 
-Put a large, rarely used webhook/billing group behind an async include:
+Put a large, rarely used webhook/billing group behind an async include with
+its own URL prefix. The chunk is imported on the first request that reaches
+that prefix, not at Worker startup (`/composability`):
 
 ```typescript
-include("/", () => import("./urls/billing.js"), { name: "billing" });
+// urls/billing.ts: `export default urls(({ path }) => [ ... ])`
+include("/api/billing", () => import("./urls/billing.js"), { name: "billing" });
 ```
 
 Measure a before/after production build before claiming an SDK's incremental

package/skills/comparison/SKILL.md

@@ -5,6 +5,11 @@ description: Compare Rango with Next.js App Router, TanStack Start, and Waku. Us
 
 # Compare Rango with other React frameworks
 
+This skill positions Rango against Next.js App Router, TanStack Start, and Waku
+on capabilities and architecture. Use it for "why Rango" questions, adoption
+memos, and fact-checking a comparative claim. For the mechanics of actually
+porting an app, use `/migrate-nextjs` or `/migrate-react-router`.
+
 Use the canonical [framework comparison](references/framework-comparison.md) as
 the factual baseline. Read the sections relevant to the question; read the full
 reference when producing an overall evaluation or editing the comparison itself.