@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

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]
 ---
 
@@ -81,7 +81,7 @@ export const urlpatterns = urls(({ path }) => [
 - `Accept: application/json` — JSON handler
 - `Accept: text/plain` — text handler
 - `Accept: application/xml` — XML handler
-- `Accept: */*` — first variant (JSON, since it was registered first)
+- `Accept: */*` — RSC page (the primary, since it was registered first)
 
 ## Wildcard Routes
 
@@ -133,7 +133,7 @@ declare global {
 
 `RegisteredRoutes` is what exposes the richer routeMap entries containing
 response payload metadata. Without it, URL-pattern response lookup has paths but
-no payloads, so response types resolve to `ResponseEnvelope<never>`.
+no payloads, so response types resolve to `never`.
 
 ## How It Works
 

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
@@ -73,19 +81,75 @@ const router = createRouter({
 });
 ```
 
-For OpenTelemetry:
+For OpenTelemetry — phase spans come from the `tracing` slot
+(`createOTelTracing`), discrete-fact spans from the `telemetry` sink
+(`createOTelSink`):
 
 ```typescript
-import { createRouter, createOTelSink } from "@rangojs/router";
+import {
+  createRouter,
+  createOTelTracing,
+  createOTelSink,
+} from "@rangojs/router";
 import { trace } from "@opentelemetry/api";
 
+const tracer = trace.getTracer("my-app");
+
 const router = createRouter({
   document: Document,
   urls: urlpatterns,
-  telemetry: createOTelSink(trace.getTracer("my-app")),
+  tracing: createOTelTracing(tracer), // request/loader/render/… phase spans
+  telemetry: createOTelSink(tracer), // handler errors, cache decisions, …
 });
 ```
 
+On **Cloudflare Workers**, use `createCloudflareTracing` for the `tracing` slot
+instead — it emits the same phases as native Cloudflare custom spans (in the
+Workers trace waterfall, next to the automatic KV/D1/fetch spans), with no
+`@opentelemetry/api` dependency:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createCloudflareTracing(), // all phases on by default
+  // tracing: createCloudflareTracing({ spans: { ssr: false } }), // toggle phases
+});
+```
+
+On **Vercel Functions** (Node runtime), use `createVercelTracing` — a thin
+wrapper over `createOTelTracing` that reads the global OTel tracer
+`@vercel/otel`'s `registerOTel()` installs, so you do not call `trace.getTracer`
+yourself. Custom spans are Node-only (unsupported on the Edge runtime):
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config.
+// Importing this module is what runs registerOTel() — a Rango/Vite app does not
+// auto-load instrumentation.ts like Next.js, so a standalone registerOTel() that
+// nothing imports is a silent no-op.
+import { registerOTel } from "@vercel/otel";
+import { createVercelTracing } from "@rangojs/router/vercel";
+registerOTel({ serviceName: "my-app" });
+export const tracing = createVercelTracing(); // { enabled, spans, tracerName, tracer }
+
+// router.tsx — importing `tracing` runs instrumentation.ts
+import { createRouter } from "@rangojs/router";
+import { tracing } from "./instrumentation.js";
+
+const router = createRouter({ document: Document, urls: urlpatterns, tracing });
+```
+
+These factories return a `RouterTracingConfig` for the same `tracing` slot;
+`telemetry` stays independent (events only, no phase spans). Phase spans:
+`rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
+`rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline
+shows, co-emitted from one site. Off-platform (no Cloudflare tracing destination
+/ no OTel SDK) every span call is a transparent pass-through, so the request
+behaves as if tracing were off.
+
 Custom sinks implement `emit(event)`:
 
 ```typescript
@@ -103,7 +167,8 @@ const router = createRouter({
 ```
 
 Events include `request.start/end/error`, `loader.start/end/error`,
-`handler.error`, `cache.decision`, and `revalidation.decision`.
+`handler.error`, `cache.decision`, `revalidation.decision`, `request.timeout`,
+and `request.origin-rejected`.
 
 ## Debugging revalidation and stale data
 

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
@@ -330,6 +341,8 @@ parallel({
 Control when parallel routes revalidate:
 
 ```typescript
+import * as CartActions from "./actions/cart";
+
 parallel(
   {
     "@cart": () => <CartSummary />,
@@ -337,14 +350,22 @@ parallel(
   () => [
     loader(CartLoader),
     // Revalidate when cart actions occur
-    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
   ]
 )
 ```
 
-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` /
@@ -360,8 +381,10 @@ the parallel consumer:
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") || undefined;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -429,6 +452,7 @@ function MyLayout() {
 ```typescript
 import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
   return (
@@ -479,7 +503,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
       ]
     ),