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

package/skills/prerender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prerender
-description: Pre-render route segments at build time with Prerender and Passthrough live fallback
+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.
 argument-hint: [passthrough]
 ---
 
@@ -11,6 +11,13 @@ deserialization path, same segment system. The worker handles every request --
 there are NO static .html or .rsc files served from assets. The worker reads
 pre-computed Flight payloads instead of executing handler code.
 
+## Not this skill if…
+
+- You want a cached HTML shell captured at runtime, with holes and loaders
+  staying live per request — see `/ppr`.
+- You want runtime segment caching with TTL/SWR — that is the `cache()` DSL:
+  see `/caching`. Prerender is the same cache filled at build time.
+
 ## API: Prerender
 
 ### Static Route (no params)

package/skills/rango/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rango
-description: Overview of @rangojs/router and available skills
+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".
 argument-hint:
 ---
 
@@ -109,7 +109,7 @@ stated, greppable contract.
 | modal / soft navigation                 | `intercept()`                      | /intercept              |
 | pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
 | feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
-| cache the HTML shell, keep loaders live | `createShellCacheMiddleware()`     | /ppr                    |
+| cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
 | stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
@@ -153,7 +153,7 @@ Same words, different jobs — this is the most common source of the
 | Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
 | React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
 | HTTP `Cache-Control` / ISR              | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                                                                           |
-| Next.js PPR (partial prerendering)      | HTML shell layer   | Same idea, different wiring: opt-in `createShellCacheMiddleware()` captures at runtime (no build-time default), and holes are route-level `loading()` boundaries — a hand-rolled `<Suspense>` is not a hole. See `/ppr`.                                                                |
+| Next.js PPR (partial prerendering)      | HTML shell layer   | Same idea, different wiring: the opt-in `ppr` path option captures at runtime (no build-time default); holes are render-defined — `loading()` subtrees plus pending promises under a consumer's own `<Suspense>`. See `/ppr`.                                                           |
 | Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
 
 See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
@@ -249,17 +249,17 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill             | Description                                                                                  |
-| ----------------- | -------------------------------------------------------------------------------------------- |
-| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                        |
-| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                      |
-| `/caching`        | Segment caching with memory or KV stores                                                     |
-| `/use-cache`      | Function-level caching with `"use cache"` directive                                          |
-| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                      |
-| `/document-cache` | Edge caching with Cache-Control headers                                                      |
-| `/ppr`            | PPR shell caching: cached HTML shell served instantly, live loader holes resumed per request |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                          |
-| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)   |
+| Skill             | Description                                                                                                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                                                                                             |
+| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                                                                                           |
+| `/caching`        | Segment caching with memory or KV stores                                                                                                                          |
+| `/use-cache`      | Function-level caching with `"use cache"` directive                                                                                                               |
+| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                                                                                           |
+| `/document-cache` | Edge caching with Cache-Control headers                                                                                                                           |
+| `/ppr`            | PPR shell caching: cached shell served instantly, live holes resumed — a hole is a `loading()` subtree OR a pending promise under `<Suspense>` (no loader needed) |
+| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                                                                                               |
+| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes)                                                                        |
 
 **Client & presentation** — build the client-side UX:
 

package/skills/response-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-routes
-description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses
+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.
 argument-hint: [json|text|html|xml|md|image|stream]
 ---
 

package/skills/route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: route
-description: Define routes with path() in @rangojs/router
+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.
 argument-hint: [pattern]
 ---
 

package/skills/router-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: router-setup
-description: Create and configure the RSC router with createRouter
+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.
 argument-hint: [option]
 ---
 

package/skills/scripts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scripts
-description: Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle
+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.
 argument-hint: "[vendor]"
 ---
 

package/skills/server-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-actions
-description: Define and call server actions (`"use server"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation
+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.
 argument-hint: "[action]"
 ---
 
@@ -24,7 +24,8 @@ with no framework wrapper. All standard React hooks (`useActionState`,
 Use loaders and route handlers for reads. Use actions for writes. After an
 action runs, the matched route tree can partially re-render so handlers and
 loaders that opt into revalidation see the new state — see "Revalidation"
-below.
+below. For the read-side APIs (`createLoader`, `useLoader`, `useFetchLoader`),
+see `/loader`.
 
 ## Revalidation Model
 

package/skills/shell-manifest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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
+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.
 argument-hint:
 ---
 

package/skills/streams-and-websockets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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.
 argument-hint: "[sse | websocket | agents]"
 ---
 

package/skills/tailwind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tailwind
-description: Set up Tailwind CSS v4 with the Document component and CSS imports
+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.
 argument-hint: [setup]
 ---
 

package/skills/testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement)
+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.
 argument-hint: [layer]
 ---
 

package/skills/theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theme
-description: Opt-in theme system with FOUC prevention for light/dark mode
+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).
 argument-hint: [setup]
 ---