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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.e9c0b2f2",
+  "version": "0.0.0-experimental.ea9f40f2",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -180,7 +180,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.26",
+    "@vitejs/plugin-rsc": "^0.5.27",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -190,6 +190,8 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
     "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
@@ -197,24 +199,24 @@
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "esbuild": "^0.27.0",
+    "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
-    "jiti": "^2.6.1",
+    "jiti": "^2.7.0",
     "react": "catalog:",
     "react-dom": "catalog:",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
-    "@cloudflare/vite-plugin": "^1.38.0",
+    "@cloudflare/vite-plugin": "^1.42.1",
     "@opentelemetry/api": "^1.9.0",
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.26",
+    "@vitejs/plugin-rsc": "^0.5.27",
     "react": ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
-    "vite": "^8.0.0",
+    "vite": "^8.0.16",
     "vitest": ">=3"
   },
   "peerDependenciesMeta": {

package/skills/api-client/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-client
-description: Build a typed client for consuming your own response-route JSON APIs (no codegen)
+description: Build a typed client for consuming your own response-route JSON APIs (no codegen). Use when calling your own JSON endpoints from another service or script, or you want typed fetch calls without a codegen step.
 ---
 
 # Typed API Client

package/skills/breadcrumbs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: breadcrumbs
-description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments
-argument-hint: [setup]
+description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.
+argument-hint: "[setup]"
 ---
 
 # Breadcrumbs
@@ -90,7 +90,9 @@ a deep async component, not the handler — call `.defer()` on the push function
 slot synchronously and returns a **resolver that is push-equal** — you call it
 later, anywhere in the render, with the same argument you'd have passed to the
 push (a value, a `Promise`, or a thunk). The only added behavior is a timeout, so a
-forgotten resolve can't hold the Flight stream (and the HTTP response) open forever.
+forgotten resolve can't hang the render (and the HTTP response): resolve-by-default
+awaits the reserved slot before any consumer reads it, and the timeout guarantees it
+settles to `else` instead of blocking forever.
 
 Reserve the slot in the handler, then resolve it from a nested async component
 that closes over the resolver — no extra wiring (the resolver is a plain closure,
@@ -131,15 +133,17 @@ hung request. `timeoutMs: 0` or `Infinity` disable the timeout intentionally; an
 other non-finite or negative value falls back to the default rather than silently
 disabling the safety net.
 
-**Consumer note:** because `.defer()` reserves the slot for the WHOLE item, a
-client reading the handle (`useHandle(Breadcrumbs)`) sees that entry as a
-`Promise` until it resolves. Type such reads with the exported
-`DeferredHandleEntry<BreadcrumbItem>` (from `@rangojs/router/client`); a
-deferred-aware consumer should `use()` thenable entries inside `<Suspense>`, while
-a simple one can skip them (`typeof entry.then === "function"`). Use `.defer()`
-only when even `label`/`href` are unknown at handler time — if you know them and
-only the `content` is async, push a concrete item with a `Promise` `content` field
-instead (no `.defer()` needed).
+**Consumer note (resolve-by-default):** a deferred crumb is RESOLVED before any
+consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
+`Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
+On a full/SSR load the value is resolved server-side; on a soft navigation the
+breadcrumbs HOLD the previous resolved value until the deferred value lands, then
+swap in — no blank, no pending entry. If the slot times out to `else: null`/
+undefined, the entry is simply dropped. Use `.defer()` only when even
+`label`/`href` are unknown at handler time — if you know them and only the
+`content` is async, push a concrete item with a `Promise` `content` field instead
+(the `content` field is a nested promise you resolve with `use()` in your
+component; no `.defer()` needed).
 
 ## Consuming Breadcrumbs (Client)
 
@@ -274,15 +278,28 @@ Create your own handle with `createHandle()`:
 ```typescript
 import { createHandle } from "@rangojs/router";
 
-// Default: flatten into array
+// Custom collect: last value wins.
 export const PageTitle = createHandle<string, string>(
   (segments) => segments.flat().at(-1) ?? "Default Title",
 );
 
-// No collect function: default flattens into T[]
+// No collect: the DEFAULT is the identity (lossless) — `collect` receives the
+// per-segment data (TData[][], one array per segment that pushed, in segment
+// order) and passes it through as-is. `useHandle(Warnings)` is `string[][]`, so a
+// consumer can tell which/how-many segments contributed.
 export const Warnings = createHandle<string>();
+
+// Want a single flat list instead? Opt in:
+export const FlatWarnings = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
 ```
 
+A handle whose module is never imported (so `createHandle()` never ran to register
+its collect) falls back to this same identity default and **warns in dev** — a
+handle with a custom collect that failed to register would otherwise return the
+wrong shape silently, and the runtime can't tell it from one that wanted the default.
+
 The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
 file path and export name. No manual naming required for project-local code.
 

package/skills/cache-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cache-guide
-description: When to use cache() DSL vs "use cache" directive — key differences and decision 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".
 argument-hint:
 ---
 
@@ -20,7 +20,9 @@ caching:
 1. **Stored-value freshness** — _is a cached value still good?_
    → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
    Entries expire by **TTL/SWR** and can be tagged (`cache({ tags })` or runtime
-   `cacheTag(...tags)`). Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
+   `cacheTag(...tags)` — inside `"use cache"` it tags that entry; called during a
+   request render outside `"use cache"` it tags the document/shell artifact).
+   Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
    index by tag; invalidate on demand with `updateTag(...tags)` (awaitable,
    read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking).
    Both hard-purge; the difference is awaitability, not stale-serving.
@@ -484,3 +486,4 @@ overrides — see `/loader` for the full reference.
 - `/caching` — cache() DSL setup, stores, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
 - `/document-cache` — Edge caching with Cache-Control headers (different layer)
+- `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)

package/skills/caching/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: caching
-description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router
-argument-hint: [setup]
+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.
+argument-hint: "[setup]"
 ---
 
 # Caching
@@ -14,6 +14,16 @@ argument-hint: [setup]
 > route-segment entries expire at TTL with no background revalidation — use
 > `CFCacheStore` for real segment SWR. See `/cache-guide`.
 
+## Not this skill if…
+
+- You want to cache ONE function or component's return value — that is
+  `"use cache"`: see `/use-cache`.
+- You want the whole HTTP response frozen at the edge, loader output included —
+  see `/document-cache`.
+- You want the HTML shell cached while loaders stay live per request — see
+  `/ppr`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+
 ## cache() is Partial Prerendering (PPR)
 
 `cache()` caches **everything except loaders**. On a cache hit, the cached
@@ -81,9 +91,27 @@ cache(
 );
 ```
 
+## When cache() does not pay
+
+A cache hit is not free: it still runs middleware, the store read, and the
+document render AROUND the cached segment. The win is proportional to what
+the cached render itself costs — measured on a deployed Cloudflare worker
+(2026-07), a trivial page inside `cache()` served hits at p50 36 ms while
+misses (render + store) served at 35 ms: indistinguishable. The same
+boundary around an expensive render (slow data, big trees) is where the TTL
+pays for itself.
+
+Rule of thumb: reach for `cache()` when the segment's own render cost is
+meaningfully above your latency floor — expensive render-embedded data work,
+large component trees, third-party calls captured in the render. Do not wrap cheap
+pages "just in case": you add store traffic and invalidation surface for no
+latency win. If the data is what's expensive and it changes per-request,
+prefer a loader with `cache()` on the loader DATA (see "Loader-Level
+Caching") over caching the rendered segment.
+
 ## Tag-Based Invalidation
 
-Tag cached entries, then invalidate them on demand. Tags can be attached three ways:
+Tag cached entries, then invalidate them on demand. Tags can be attached four ways:
 
 ```typescript
 // 1. Static tags in the cache() DSL
@@ -101,8 +129,22 @@ async function getProduct(id: string) {
   cacheTag(`product:${id}`, "products"); // variadic, additive
   return db.getProduct(id);
 }
+
+// 4. Render-callable — a plain server component (no "use cache" in its tree)
+//    records onto the request's document/shell artifact.
+function CampaignBanner() {
+  cacheTag("campaign:spring"); // rides ctx._requestTags → shell/document entry
+  return <aside>Spring sale</aside>;
+}
 ```
 
+Form 4 is how you make a PPR shell or a `/document-cache` page tag-invalidatable
+without wrapping anything in `"use cache"`: the tag rides the request's
+`_requestTags` onto the shell/document entry, and `revalidateTag` then evicts it.
+On a route that is neither PPR nor document-cached the tag records where nothing
+reads it — a silent no-op, so don't expect a bare `cacheTag()` to tag an ordinary
+uncached page.
+
 Invalidate with one of two server-only verbs (both variadic, imported from
 `@rangojs/router`):
 
@@ -143,7 +185,8 @@ converge within `tagCacheTtl` (the **maximum extra cross-colo invalidation
 latency** when no purge is wired). Keep it small (e.g. 30–60), or wire a purge
 (below) and set it large. (Contrast `tagInvalidationTtl`, which must be _large_
 — it bounds how long the KV marker itself lives and must exceed your max entry
-TTL+SWR.)
+TTL+SWR. Left unset there is no expiry: KV markers accumulate unbounded under
+high-cardinality tags, so set it above your largest entry TTL+SWR to bound them.)
 
 To make other colos prompt without a short `tagCacheTtl`, pass `onRevalidateTag`:
 each cached marker carries a namespaced Cloudflare `Cache-Tag`, and the hook is
@@ -235,9 +278,15 @@ import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
+  maxEntries: 1000, // per-family FIFO cap (default 1000)
 });
 ```
 
+Each internal family (segments, responses, `"use cache"` items, PPR shells) is
+capped at `maxEntries`; on insert past the cap the oldest entry is evicted FIFO
+and its tag-index entries are cleaned up, so a long-lived process cannot grow
+without bound. TTL expiry stays lazy on top of the cap.
+
 ### Cloudflare Edge Cache Store
 
 For distributed caching on Cloudflare Workers using the Cache API:
@@ -401,6 +450,12 @@ is **not** guarded. `ctx.use()` is a server-side escape hatch for non-rendered
 uses (set a ctx var, make a routing decision); never render its result inside a
 cached handler.
 
+This is the **consumption-lane rule**, and it holds identically for every
+shared artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`):
+handler consumption = baked copy with identity reads permitted; client-side
+`useLoader` = live. Stated once in `/rango` → Invariants; pinned by
+semantic-matrix row PPR3 and the `e2e/cache.test.ts` "baked copy" case.
+
 ```typescript
 // WRONG — throws: cookies() read directly in a cached handler
 cache({ ttl: 60 }, () => [

package/skills/catalog.json

@@ -0,0 +1,271 @@
+{
+  "$schema-note": "Generated by tools/generate-skills-catalog.mjs — do not edit by hand.",
+  "package": "@rangojs/router",
+  "entry": "rango",
+  "skills": [
+    {
+      "name": "api-client",
+      "description": "Build a typed client for consuming your own response-route JSON APIs (no codegen). Use when calling your own JSON endpoints from another service or script, or you want typed fetch calls without a codegen step.",
+      "argumentHint": "",
+      "path": "skills/api-client/SKILL.md"
+    },
+    {
+      "name": "breadcrumbs",
+      "description": "Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.",
+      "argumentHint": "[setup]",
+      "path": "skills/breadcrumbs/SKILL.md"
+    },
+    {
+      "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.",
+      "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\".",
+      "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.",
+      "argumentHint": "[setup]",
+      "path": "skills/caching/SKILL.md"
+    },
+    {
+      "name": "comparison",
+      "description": "Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.",
+      "argumentHint": "",
+      "path": "skills/comparison/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "pattern-name",
+      "path": "skills/composability/SKILL.md"
+    },
+    {
+      "name": "css",
+      "description": "Import and apply CSS in a Rango app. Render document/app stylesheets in the Document `<head>` with Vite's `?url` import plus a `precedence`-managed `<link rel=\"stylesheet\">` (React 19 resource model — deduped, ordered, loaded before paint). Use when wiring global/app CSS or a Document `<head>` stylesheet, or when deciding between `?url` + `<link>` and side-effect imports. Cross-app (host-router) navigation is a full document load, so each app's document CSS is always re-established by its own load.",
+      "argumentHint": "",
+      "path": "skills/css/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "",
+      "path": "skills/debug-manifest/SKILL.md"
+    },
+    {
+      "name": "defer-hydration",
+      "description": "Keep the full body HTML in a PPR shell's first paint while moving a heavy subtree's hydration off the initial main-thread task — a gated Suspense boundary with the content as its own fallback, released on first idle. Use when a shell HIT paints fast but one long hydration task blocks the main thread, TTI/INP is poor despite instant paint, or a plain Suspense boundary left an empty hole in the frozen prelude.",
+      "argumentHint": "",
+      "path": "skills/defer-hydration/SKILL.md"
+    },
+    {
+      "name": "document-cache",
+      "description": "Cache the whole HTTP response at the edge with Cache-Control headers. Use when caching an entire page or response at a CDN edge, setting Cache-Control headers, or cutting origin hits for public pages — not for caching a single segment or function.",
+      "argumentHint": "[setup]",
+      "path": "skills/document-cache/SKILL.md"
+    },
+    {
+      "name": "fonts",
+      "description": "Load and configure web fonts with preload hints for optimal performance. Use when adding a custom font to a Rango app, fonts flash or swap on load (FOUT/FOIT), or you want font preload for performance.",
+      "argumentHint": "[provider]",
+      "path": "skills/fonts/SKILL.md"
+    },
+    {
+      "name": "handler-use",
+      "description": "Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites. Use when a handler needs its own default middleware/loader without repeating use() at every mount site, or deciding between handler-level defaults and per-route use().",
+      "argumentHint": "[handler]",
+      "path": "skills/handler-use/SKILL.md"
+    },
+    {
+      "name": "hooks",
+      "description": "Client-side React hooks for navigation, loaders, and state in @rangojs/router. Use when a client component needs the current URL, params, search params, navigation state, or loader data — e.g. \"how do I read the route param in a component\".",
+      "argumentHint": "[hook-name]",
+      "path": "skills/hooks/SKILL.md"
+    },
+    {
+      "name": "host-router",
+      "description": "Multi-app host routing with domain/subdomain patterns. Use when running multiple apps behind one domain or across subdomains, or routing requests to different apps based on hostname.",
+      "argumentHint": "",
+      "path": "skills/host-router/SKILL.md"
+    },
+    {
+      "name": "i18n",
+      "description": "Locale-aware routing with `include(\"/:locale?\", ...)`, locale resolution chains, and react-intl integration. Use when building a multi-language app, routes need a locale segment, or wiring up react-intl translations.",
+      "argumentHint": "[topic]",
+      "path": "skills/i18n/SKILL.md"
+    },
+    {
+      "name": "intercept",
+      "description": "Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router. Use when opening a route as a modal/overlay on top of the current page while keeping the URL shareable, or asking \"how do I show this page in a modal\".",
+      "argumentHint": "[@slot-name] [route-to-intercept]",
+      "path": "skills/intercept/SKILL.md"
+    },
+    {
+      "name": "layout",
+      "description": "Define layout routes that wrap child routes in @rangojs/router. Use when sharing a persistent UI shell (nav, sidebar) across nested routes, or asking how to wrap child pages with a common layout.",
+      "argumentHint": "[component]",
+      "path": "skills/layout/SKILL.md"
+    },
+    {
+      "name": "links",
+      "description": "URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse. Use when generating a link to a route by name instead of hardcoding a path, or a link breaks after routes move or get mounted elsewhere.",
+      "argumentHint": "[ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]",
+      "path": "skills/links/SKILL.md"
+    },
+    {
+      "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, or client components need reactive server data.",
+      "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.",
+      "argumentHint": "[middleware-name]",
+      "path": "skills/middleware/SKILL.md"
+    },
+    {
+      "name": "migrate-nextjs",
+      "description": "Migrate a Next.js App Router project to @rangojs/router. Use when the user asks to \"migrate from Next.js\", \"convert Next.js to Rango\", \"replace Next.js\", or has a Next.js app they want to port.",
+      "argumentHint": "[path-to-nextjs-app]",
+      "path": "skills/migrate-nextjs/SKILL.md"
+    },
+    {
+      "name": "migrate-react-router",
+      "description": "Migrate a React Router v7/v6 project to @rangojs/router. Use when the user asks to \"migrate from React Router\", \"convert React Router to Rango\", \"replace React Router\", \"move from Remix to Rango\", or has a React Router / Remix app they want to port.",
+      "argumentHint": "path-to-react-router-app",
+      "path": "skills/migrate-react-router/SKILL.md"
+    },
+    {
+      "name": "mime-routes",
+      "description": "Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header. Use when the same URL needs to return JSON for API clients and HTML/RSC for browsers, or branching a handler on the Accept header.",
+      "argumentHint": "[negotiate|vary|accept]",
+      "path": "skills/mime-routes/SKILL.md"
+    },
+    {
+      "name": "observability",
+      "description": "Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing. Use when a request feels slow and you need to see where time is spent, or wiring up tracing/telemetry for production requests.",
+      "argumentHint": "",
+      "path": "skills/observability/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "[@slot-name]",
+      "path": "skills/parallel/SKILL.md"
+    },
+    {
+      "name": "ppr",
+      "description": "PPR shell caching — opt a page route in with the `ppr` path option; the router serves the cached HTML shell instantly and resumes the live holes. Use when a page should render instantly from a cached shell while specific parts stay live, or asking about partial prerendering in Rango.",
+      "argumentHint": "[setup]",
+      "path": "skills/ppr/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "[passthrough]",
+      "path": "skills/prerender/SKILL.md"
+    },
+    {
+      "name": "rango",
+      "description": "Overview of @rangojs/router and available skills. Use when unsure which skill to reach for, starting a new task in a Rango app, or asking \"what can this router do\".",
+      "argumentHint": "",
+      "path": "skills/rango/SKILL.md"
+    },
+    {
+      "name": "react-compiler",
+      "description": "Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.",
+      "argumentHint": "",
+      "path": "skills/react-compiler/SKILL.md"
+    },
+    {
+      "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.",
+      "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.",
+      "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.",
+      "argumentHint": "[option]",
+      "path": "skills/router-setup/SKILL.md"
+    },
+    {
+      "name": "scripts",
+      "description": "Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle. Use when adding Google Tag Manager, an analytics snippet, or a third-party widget script to the page.",
+      "argumentHint": "[vendor]",
+      "path": "skills/scripts/SKILL.md"
+    },
+    {
+      "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.",
+      "argumentHint": "[action]",
+      "path": "skills/server-actions/SKILL.md"
+    },
+    {
+      "name": "shell-manifest",
+      "description": "Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices. Use when a cached/prerendered shell needs to feed IDs or metadata to a live loader for freshly-fetched data.",
+      "argumentHint": "",
+      "path": "skills/shell-manifest/SKILL.md"
+    },
+    {
+      "name": "streams-and-websockets",
+      "description": "Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats. Use when streaming live updates to the browser, or opening a WebSocket connection from a route on Cloudflare Workers.",
+      "argumentHint": "[sse | websocket | agents]",
+      "path": "skills/streams-and-websockets/SKILL.md"
+    },
+    {
+      "name": "tailwind",
+      "description": "Set up Tailwind CSS v4 with the Document component and CSS imports. Use when adding Tailwind CSS to a Rango app, or Tailwind classes aren't being applied or generated.",
+      "argumentHint": "[setup]",
+      "path": "skills/tailwind/SKILL.md"
+    },
+    {
+      "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.",
+      "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).",
+      "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.",
+      "argumentHint": "[setup]",
+      "path": "skills/typesafety/SKILL.md"
+    },
+    {
+      "name": "use-cache",
+      "description": "Function-level caching with the \"use cache\" directive for RSC data functions and components in @rangojs/router. Use when a single function or component should memoize its own output, not a whole route/segment subtree or HTTP response.",
+      "argumentHint": "[profile-name]",
+      "path": "skills/use-cache/SKILL.md"
+    },
+    {
+      "name": "vercel",
+      "description": "Deploy a Rango app to Vercel Functions (Build Output API v3). Use when deploying a Rango app to Vercel, or asking how the router works with Vercel Functions and the Build Output API.",
+      "argumentHint": "",
+      "path": "skills/vercel/SKILL.md"
+    },
+    {
+      "name": "view-transitions",
+      "description": "Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router. Use when navigation should animate smoothly between pages, or wiring up React View Transitions on a route or layout.",
+      "argumentHint": "[layout|route|parallel|intercept]",
+      "path": "skills/view-transitions/SKILL.md"
+    }
+  ]
+}

package/skills/comparison/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: comparison
+description: Compare Rango with Next.js App Router, TanStack Start, and Waku. Use when evaluating React frameworks, explaining why Rango, writing positioning or adoption guidance, answering migration questions, or checking claims about Rango's routing, loaders, caching, rendering, prefetching, safety, testing, observability, and production behavior.
+---
+
+# Compare Rango with other React frameworks
+
+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.
+
+## Comparison rules
+
+1. Compare capabilities and architecture separately from ecosystem size, hiring,
+   integrations, and organizational familiarity.
+2. Present Rango's range clearly: start with `path()` and a component, then add
+   named routes, `include()`, loaders, caching, `revalidate()`, slots, intercepts,
+   safety, and diagnostics in the same declared route graph.
+3. Do not confuse Rango's `revalidate()` with cache invalidation. Cache APIs decide
+   stored-value freshness; `revalidate()` decides client render selection.
+4. Describe loaders as live-by-default RSC data slots beneath cached or prerendered
+   UI, not as renamed Remix or TanStack route loaders.
+5. Include production correctness where relevant: Rango State, userland client-cache
+   invalidation, deployment-skew recovery, tainted request context, CSP nonce
+   propagation, default CSRF origin checks, prefetch guards, testing, and timing.
+6. State boundaries and tradeoffs. In particular, distinguish origin checking from
+   token-based CSRF protection, nonce plumbing from application-owned CSP policy,
+   and reload-based skew recovery from Vercel deployment pinning.
+7. Credit competing frameworks where they lead. Next.js leads in ecosystem and
+   hiring, TanStack in search-param ergonomics and client/data devtools, and Waku
+   in minimal surface area.
+
+## Currency and evidence
+
+- Treat Rango identifiers and behavior as source-verifiable. Check the current
+  package source or the relevant Rango skill when changing a precise claim.
+- Competitor details age quickly. Before publishing or materially revising a claim,
+  verify it against current official documentation and link that primary source.
+- Do not weaken a current, sourced claim merely because an older model remembers a
+  previous release. Check first: examples include TanStack Start's Rsbuild support,
+  Next.js `proxy.ts` and Cache Components, and Waku handler interceptors.
+- Avoid declaring a framework universally "better." State which model fits the
+  application's constraints and why.
+
+## Output shape
+
+Lead with the decision or differentiator. For a short answer, use the TL;DR and the
+relevant framework-specific paragraph from the reference. For a decision memo,
+cover the at-a-glance table, the simple-to-complex growth path, substantive runtime
+differences, and the section where competitors still lead.

package/skills/comparison/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Rango Comparison"
+  short_description: "Compare Rango with other React frameworks"
+  default_prompt: "Use $comparison to compare Rango with Next.js, TanStack Start, and Waku."