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

package/skills/migrate-react-router/route-mapping.md

@@ -0,0 +1,271 @@
+# Project Setup and Route Mapping
+
+## 1. Project Setup
+
+Replace React Router tooling with Vite + Rango:
+
+```bash
+# Framework mode:
+npm remove react-router @react-router/dev @react-router/node @react-router/serve
+# Library mode:
+npm remove react-router react-router-dom
+
+npm install @rangojs/router
+```
+
+Replace the `@react-router/dev` Vite plugin with `rango()`:
+
+```typescript
+// vite.config.ts
+// Before: import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [rango()],
+});
+```
+
+Delete `react-router.config.ts` — route configuration moves to the `urls()` DSL.
+
+```typescript
+// src/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
+import { urlpatterns } from "./urls";
+
+export default createRouter({
+  document: Document,
+}).routes(urlpatterns);
+```
+
+## 2. Route Mapping
+
+### RR7 framework mode: route modules → urls() DSL
+
+In framework mode, each route is a file with conventional exports (`loader`,
+`action`, `default`, `meta`, `headers`, `shouldRevalidate`, `handle`,
+`ErrorBoundary`, `HydrateFallback`). In Rango, all of these become part of the
+`urls()` DSL or move into the server component handler:
+
+```text
+RR7 route module export     → Rango equivalent
+─────────────────────────────────────────────────────
+default (Component)         → handler in path()
+loader                      → fetch in handler, or createLoader()
+action                      → "use server" function
+meta                        → ctx.use(Meta) in handler
+headers                     → ctx.header() in handler or middleware
+shouldRevalidate            → revalidate() DSL
+ErrorBoundary               → errorBoundary() DSL
+HydrateFallback             → loading() DSL
+handle                      → createHandle() for cross-segment data (breadcrumbs, etc.)
+clientLoader / clientAction → "use client" component with React hooks
+```
+
+#### Example: full route module migration
+
+```typescript
+// RR7 framework mode: app/routes/product.$slug.tsx
+import type { Route } from "./+types/product.$slug";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const product = await getProduct(params.slug);
+  if (!product) throw new Response("Not Found", { status: 404 });
+  return { product };
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  const formData = await request.formData();
+  await addToCart(formData.get("productId") as string);
+  return { ok: true };
+}
+
+export function meta({ data }: Route.MetaArgs) {
+  return [{ title: data.product.name }];
+}
+
+export function headers() {
+  return { "Cache-Control": "max-age=300" };
+}
+
+export function shouldRevalidate({ actionResult }) {
+  return !!actionResult;
+}
+
+export default function ProductPage({ loaderData }: Route.ComponentProps) {
+  return <div>{loaderData.product.name}</div>;
+}
+
+export function ErrorBoundary() {
+  return <div>Product error</div>;
+}
+```
+
+```typescript
+// Rango: urls.tsx + handler
+import { notFound } from "@rangojs/router";
+
+const ProductPage: Handler<"product"> = async (ctx) => {
+  const product = await getProduct(ctx.params.slug);
+  if (!product) notFound("Product not found");
+
+  const meta = ctx.use(Meta);
+  meta({ title: product.name });
+  ctx.header("Cache-Control", "max-age=300");
+
+  return <div>{product.name}</div>;
+};
+
+// In urls.tsx:
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  revalidate(({ actionId }) => !!actionId),
+  errorBoundary(() => <div>Product error</div>),
+  loading(<ProductSkeleton />),
+])
+```
+
+Key shift: the route module's scattered exports consolidate into the handler
+(data fetching, meta, headers) and the DSL (revalidation, error boundary, loading).
+
+### RR7 file routing → urls() DSL
+
+| RR7 file path                            | Rango                                                         |
+| ---------------------------------------- | ------------------------------------------------------------- |
+| `app/routes/_index.tsx`                  | `path("/", HomePage, { name: "home" })`                       |
+| `app/routes/about.tsx`                   | `path("/about", AboutPage, { name: "about" })`                |
+| `app/routes/blog.$slug.tsx`              | `path("/blog/:slug", BlogPost, { name: "blogPost" })`         |
+| `app/routes/files.$.tsx` (splat)         | `path("/files/:path*", FileBrowser, { name: "files" })`       |
+| `app/routes/dashboard.tsx` (layout)      | `layout(<DashboardLayout />, () => [...])`                    |
+| `app/routes/dashboard._index.tsx`        | `path("/dashboard", DashboardIndex, { name: "dashboard" })`   |
+| `app/routes/dashboard.settings.tsx`      | `path("/dashboard/settings", Settings, { name: "settings" })` |
+| `app/routes/_auth.tsx` (pathless layout) | `layout(<AuthLayout />, () => [...])`                         |
+| `app/routes/_auth.login.tsx`             | `path("/login", LoginPage, { name: "login" })`                |
+
+### Library mode: config routes → urls() DSL
+
+| React Router                           | Rango                                                   |
+| -------------------------------------- | ------------------------------------------------------- |
+| `path: "/"`                            | `path("/", HomePage, { name: "home" })`                 |
+| `path: "about"`                        | `path("/about", AboutPage, { name: "about" })`          |
+| `path: "blog/:slug"`                   | `path("/blog/:slug", BlogPost, { name: "blogPost" })`   |
+| `path: "files/*"` (splat)              | `path("/files/:path*", FileBrowser, { name: "files" })` |
+| `path: "docs/:lang?"` (optional param) | `path("/docs/:lang?", Docs, { name: "docs" })`          |
+
+The RR splat (`$` / `*`) matches the bare parent too (`/files` binds `""`), so
+it maps to `:path*` (zero-or-more). Use `:path+` only when you require at least
+one trailing segment. RR reads the splat at `params["*"]`; Rango exposes it as a
+named string at `ctx.params.path` with the `/` separators preserved (split to
+recover RR's array):
+
+```typescript
+path("/files/:path*", (ctx) => {
+  const parts = ctx.params.path === "" ? [] : ctx.params.path.split("/");
+  return <FileBrowser path={parts} />;
+}, { name: "files" });
+```
+
+### Layouts
+
+React Router layouts use `<Outlet />` — same concept in Rango:
+
+```typescript
+// React Router:
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <Outlet />
+    </div>
+  );
+}
+
+// route config:
+{ path: "dashboard", element: <DashboardLayout />, children: [...] }
+
+// Rango: same <Outlet />, from @rangojs/router/client
+import { Outlet } from "@rangojs/router/client";
+
+layout(<DashboardLayout />, () => [
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+  path("/dashboard/settings", Settings, { name: "settings" }),
+])
+```
+
+### Dynamic layouts (with data)
+
+```typescript
+// React Router: useLoaderData() in layout component
+function DashboardLayout() {
+  const { user } = useLoaderData();
+  return <Shell user={user}><Outlet /></Shell>;
+}
+
+// Rango: handler function layout (server component)
+layout(async (ctx) => {
+  const user = ctx.get("user");
+  return (
+    <Shell user={user}>
+      <Outlet />
+    </Shell>
+  );
+}, () => [
+  path("/dashboard", DashboardIndex, { name: "dashboard" }),
+])
+```
+
+### Nested routes
+
+React Router's nested route tree maps directly to Rango's `layout()` nesting:
+
+```typescript
+// React Router:
+createBrowserRouter([{
+  path: "/",
+  element: <RootLayout />,
+  children: [
+    { path: "dashboard",
+      element: <DashboardLayout />,
+      children: [
+        { index: true, element: <DashboardIndex /> },
+        { path: "settings", element: <Settings /> },
+      ]
+    },
+  ]
+}])
+
+// Rango:
+urls(({ path, layout }) => [
+  layout(<RootLayout />, () => [
+    layout(<DashboardLayout />, () => [
+      path("/dashboard", DashboardIndex, { name: "dashboard" }),
+      path("/dashboard/settings", Settings, { name: "settings" }),
+    ]),
+  ]),
+])
+```
+
+### Route groups / pathless layouts
+
+React Router's pathless routes (layout routes without a path) are Rango's
+layouts without a URL prefix:
+
+```typescript
+// React Router: { element: <AuthLayout />, children: [...] }
+
+// Rango: layout with no URL segment
+layout(<AuthLayout />, () => [
+  path("/login", LoginPage, { name: "login" }),
+  path("/register", RegisterPage, { name: "register" }),
+])
+```
+
+### Index routes
+
+```typescript
+// React Router: { index: true, element: <Home /> }
+
+// Rango: path with "/" inside a layout
+layout(<RootLayout />, () => [
+  path("/", HomePage, { name: "home" }),
+])
+```

package/skills/mime-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mime-routes
-description: Content negotiation — serve different response types (RSC, JSON, text, XML) from the same URL based on Accept header
+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.
 argument-hint: [negotiate|vary|accept]
 ---
 

package/skills/observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability
-description: Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing
+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.
 argument-hint:
 ---
 
@@ -58,6 +58,14 @@ Read the timeline as intervals:
 - Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
   appear as separate spans, so the slow phase is visible without guessing.
 
+**Deployed Cloudflare caveat**: on production Workers, timers are frozen
+during request execution (Spectre mitigation), so `Server-Timing` durations
+read as ~0 on the deployed edge — they only advance across genuine awaited
+I/O. The waterfall is a LOCAL diagnostic (dev, `vite preview`,
+`wrangler dev`); for deployed workers, measure from the client
+(`PerformanceResourceTiming`, TTFB) and use structured telemetry below for
+server-side events.
+
 ## Structured telemetry
 
 Use telemetry when you want durable production events rather than a one-request

package/skills/parallel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parallel
-description: Define parallel routes for multi-column layouts, sidebars, and modal slots in @rangojs/router
+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.
 argument-hint: [@slot-name]
 ---
 
@@ -8,6 +8,13 @@ argument-hint: [@slot-name]
 
 Parallel routes render multiple components simultaneously in named slots.
 
+## Not this skill if…
+
+- You want a modal or slide-over that appears only on soft navigation and shows
+  the full page on hard navigation — that is `intercept()`: see `/intercept`.
+- You want a slot rendered conditionally on HOW the user navigated — parallel
+  slots ALWAYS render alongside the page; see `/intercept`.
+
 ## Basic Parallel Routes
 
 ```typescript
@@ -232,6 +239,8 @@ layout(<AccountLayout />, () => [
 
 A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
 
+Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value (identity reads included) freezes into the artifact; consume the loader client-side (`useLoader` in a `"use client"` component) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
+
 The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
 
 `transition` is allowed in the slot allow-list, but slot-level rendering does **not** currently apply a `<ViewTransition>` wrapper — only the layout/route wraps take effect at render time. For a modal-only morph today, use an element-level React `<ViewTransition>` inside the slot's component. The reverse direction is the useful guarantee: a layout-level `transition()` fires when the layout's default outlet content changes but **not** when a `<ParallelOutlet />` mounts new content (modal opens are not subtree updates of the layout VT). See [skills/view-transitions](../view-transitions/SKILL.md) for the wrap rules and the intercept caveat.
@@ -264,6 +273,8 @@ parallel(
 
 Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
 
+Typing note: a BARE arrow slot handler infers its ctx (`"@cart": (ctx) => ...`), but an arrow inside a DESCRIPTOR needs an explicit annotation — `handler: (ctx: HandlerContext) => ...` — because `StaticHandlerDefinition` in the slot union contributes a second callable to the contextual type and TS declines to pick a signature.
+
 ## Slot Override Semantics
 
 When multiple `parallel()` calls define the same slot name, **the last
@@ -344,9 +355,17 @@ parallel(
 )
 ```
 
-Revalidating only the parallel does not re-run outer handlers/layouts.
-If the slot reads `ctx.get()` data established above it, opt the outer
-segment into revalidation as well.
+Where the slot sits decides its action default. A parallel under a
+`path()` (or one of its orphan layouts) belongs to the route entry and
+revalidates together with it on every action — handler-set data stays
+consistent with no configuration. A parallel under a standalone
+`layout()` entry follows the parent-chain default instead: skipped on
+actions unless a `revalidate()` opts it in.
+
+In either position, revalidating only the parallel does not re-run outer
+handlers/layouts. If the slot reads `ctx.get()` data established above
+it, opt the outer segment into revalidation as well (see `/rango` →
+"Passing data down the tree").
 
 A `revalidate()` callback may return a hard `boolean`, a soft
 `{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /