@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.142

package/skills/caching/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: caching
-description: Configure segment caching with memory or Cloudflare KV stores in @rangojs/router
+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]"
 ---
 
@@ -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
@@ -235,9 +245,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:

package/skills/catalog.json

@@ -0,0 +1,265 @@
+{
+  "$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": "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/references/framework-comparison.md

@@ -526,7 +526,7 @@ There are two distinct things named "revalidate", and the split is deliberate:
    the pathname is unchanged (a search or hash change), it updates the URL and all
    location hooks but skips the server fetch and re-render entirely. For filters,
    tabs, and pagination. See
-   [shallow-navigation.md](../../../docs/shallow-navigation.md).
+   [shallow-navigation.md](../../../docs/design/shallow-navigation.md).
 
 Both are separate from `revalidateTag()`/`updateTag()`, which hard-purge tagged
 cache entries. `updateTag()` is awaitable for read-your-own-writes;

package/skills/composability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: composability
-description: Reusable composition patterns with globally importable route helpers in @rangojs/router
+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.
 argument-hint: "pattern-name"
 ---
 

package/skills/debug-manifest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-manifest
-description: Debug and inspect route manifest structure
+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.
 argument-hint:
 ---
 

package/skills/document-cache/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: document-cache
-description: Cache full HTTP responses at the edge with Cache-Control headers
+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.
 argument-hint: [setup]
 ---
 
@@ -8,6 +8,14 @@ argument-hint: [setup]
 
 Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control headers. Routes opt-in by setting `s-maxage`.
 
+## Not this skill if…
+
+- You want loaders to stay live while rendered segments are reused — document
+  caching freezes the WHOLE response, loader output included; segment caching
+  is `cache()`: see `/caching`.
+- You want a cached HTML shell with per-request live holes — see `/ppr`.
+- You are unsure which cache layer you need — start at `/cache-guide`.
+
 ## Setup
 
 Document caching is a middleware. Add `createDocumentCacheMiddleware()` to the

package/skills/fonts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fonts
-description: Load and configure web fonts with preload hints for optimal performance
+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.
 argument-hint: [provider]
 ---
 

package/skills/handler-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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
+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().
 argument-hint: "[handler]"
 ---