@rangojs/router 0.16.0 → 0.18.0

package/skills/migrate-react-router/component-migration.md

@@ -2,7 +2,8 @@
 
 ## 4. Middleware / Route Protection
 
-React Router doesn't have built-in middleware. Protection is typically done in loaders:
+React Router v6 and Remix v2 have no middleware, so protection is typically done
+in loaders (v7 route `middleware` exports map to the same Rango shape below):
 
 ```typescript
 // React Router: auth check in loader
@@ -13,9 +14,27 @@ export async function loader({ request }) {
 }
 
 // Rango: router.use() for request-level auth
+import {
+  createRouter,
+  cookies,
+  redirect,
+  type Middleware,
+} from "@rangojs/router";
+
+const authInit: Middleware = async (ctx, next) => {
+  const session = cookies().get("session")?.value;
+  if (session) ctx.set("user", await getUserFromSession(session));
+  await next();
+};
+
+const requireAuth: Middleware = async (ctx, next) => {
+  if (!ctx.get("user")) return redirect("/login");
+  await next();
+};
+
 const router = createRouter({})
   .use(authInit) // all routes — resolves session
-  .use("/dashboard/*", requireAuth) // scoped guard
+  .use("/dashboard/*", requireAuth) // /dashboard and everything under it
   .routes(urlpatterns);
 ```
 
@@ -122,7 +141,7 @@ export function meta() {
 }
 
 // Rango: Meta handle in server handlers
-import { Meta } from "@rangojs/router";
+import { Meta, type Handler } from "@rangojs/router";
 
 const HomePage: Handler<"home"> = (ctx) => {
   const meta = ctx.use(Meta);
@@ -135,18 +154,20 @@ const HomePage: Handler<"home"> = (ctx) => {
 RR's data-derived `meta({ data })` maps to the same push from the LOADER that
 owns the data — `ctx.use(Meta)({ title: data.name })` in the loader body, with
 `loader(Def, { ssr: false })` when the title must be in the SSR'd
-head. See `/loader` → "Writing Handles from Loaders".
+head. See `/loader` → "Writing Handles from Loaders". The loader flag is
+unrelated to RR7's `ssr: false` (SPA mode), which has no route-wide Rango
+equivalent: it makes the server settle that loader before the first flush.
 
-Add `<MetaTags />` in the Document component's `<head>`:
+Add `<Html.Meta />` in the Document component's `<head>`:
 
 ```typescript
-import { MetaTags } from "@rangojs/router/client";
+import { Html } from "@rangojs/router/client";
 
 function Document({ children }: { children: ReactNode }) {
   return (
     <html>
       <head>
-        <MetaTags />
+        <Html.Meta />
       </head>
       <body>{children}</body>
     </html>

package/skills/migrate-react-router/data-and-actions.md

@@ -20,6 +20,8 @@ function ProductPage() {
 }
 
 // Rango: handler fetches and renders directly
+import type { Handler } from "@rangojs/router";
+
 const ProductPage: Handler<"product"> = async (ctx) => {
   const product = await getProduct(ctx.params.slug);
   return <div>{product.name}</div>;
@@ -46,7 +48,9 @@ Use it only when you need capabilities beyond what the handler provides:
   document loads, never an HTTP 302 — pre-stream 302s move to middleware)
 - **`meta({ data })` / `handle` exports** — data-derived page metadata becomes
   a handle push from the loader body (`ctx.use(Meta)({ title: data.name })`),
-  with `loader(L, { ssr: false })` when it must be in the SSR'd head
+  with `loader(L, { ssr: false })` when it must be in the SSR'd head (not
+  RR7's `ssr: false` SPA mode, which has no route-wide Rango equivalent: the
+  loader flag makes the server settle that loader before the first flush)
 
 If the React Router loader just fetches data for its page component AND the
 component can become a server component, merge it into the handler. If the
@@ -76,6 +80,7 @@ function EditProfile() {
 }
 
 // Rango: "use server" action + native form or useActionState
+// actions/profile.ts
 "use server";
 import { redirect } from "@rangojs/router";
 
@@ -84,7 +89,10 @@ export async function updateProfile(formData: FormData): Promise<void> {
   throw redirect("/profile");
 }
 
-// Client component:
+// EditProfile.tsx — a server or client component; passing the action itself
+// (not a wrapper function) keeps the form working with JavaScript disabled.
+import { updateProfile } from "./actions/profile";
+
 function EditProfile() {
   return (
     <form action={updateProfile}>
@@ -122,9 +130,12 @@ function ProductPrice() {
 }
 ```
 
-`useLoader()` provides live data that stays fresh — it re-fetches on navigation
-and after actions (controlled by `revalidate()`). This is different from
-`useLoaderData()` which just reads a snapshot.
+`useLoader()` provides live data that stays fresh — the loader re-runs on
+navigation and after actions (controlled by `revalidate()`), and the result also
+exposes `isLoading`, `error`, `load`, and `refetch`. Register the loader on the
+route (`loader(PriceLoader)`) so its data is in the tree the component reads;
+the read suspends until it arrives, so keep a `<Suspense>` or `loading()` above
+it. See `/loader` and `/hooks`.
 
 ### useActionData
 
@@ -155,8 +166,12 @@ function EditForm() {
 // Rango: useActionState (standard React hook)
 "use client";
 import { useActionState } from "react";
-import { saveForm } from "../actions"; // "use server" function
+// "use server" function with the useActionState shape:
+//   export async function saveForm(prev: State, formData: FormData): Promise<State>
+import { saveForm } from "../actions";
 
+// Pass the imported action straight to useActionState — not an inline closure —
+// so the form still posts and re-renders with JavaScript disabled.
 function EditForm() {
   const [state, action, pending] = useActionState(saveForm, null);
   return (

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

@@ -10,9 +10,13 @@ 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
+npm install @rangojs/router   # keep react and react-dom
 ```
 
+`rango()` includes `@vitejs/plugin-rsc` and supplies the client and server
+entries. Add `@vitejs/plugin-react` only if you want Fast Refresh or the React
+Compiler.
+
 Replace the `@react-router/dev` Vite plugin with `rango()`:
 
 ```typescript
@@ -34,7 +38,7 @@ import { createRouter } from "@rangojs/router";
 import { Document } from "./document";
 import { urlpatterns } from "./urls";
 
-export default createRouter({
+export const router = createRouter({
   document: Document,
 }).routes(urlpatterns);
 ```
@@ -58,7 +62,7 @@ loader                      → fetch in handler, or createLoader() — a Rango
 action                      → "use server" function
 meta                        → ctx.use(Meta) in handler; meta({ data }) →
                               ctx.use(Meta) push in the loader that owns data
-headers                     → ctx.header() in handler or middleware
+headers                     → ctx.headers.set() in a handler; ctx.header() in middleware
 shouldRevalidate            → revalidate() DSL
 ErrorBoundary               → errorBoundary() DSL
 HydrateFallback             → loading() DSL
@@ -107,15 +111,15 @@ export function ErrorBoundary() {
 
 ```typescript
 // Rango: urls.tsx + handler
-import { notFound } from "@rangojs/router";
+import { Meta, notFound, type Handler } from "@rangojs/router";
 
 const ProductPage: Handler<"product"> = async (ctx) => {
   const product = await getProduct(ctx.params.slug);
-  if (!product) notFound("Product not found");
+  if (!product) notFound("Product not found"); // throws: nearest notFoundBoundary, else the router's notFound
 
   const meta = ctx.use(Meta);
   meta({ title: product.name });
-  ctx.header("Cache-Control", "max-age=300");
+  ctx.headers.set("Cache-Control", "max-age=300"); // response headers
 
   return <div>{product.name}</div>;
 };
@@ -130,16 +134,21 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 
 Key shift: the route module's scattered exports consolidate into the handler
 (data fetching, meta, headers) and the DSL (revalidation, error boundary, loading).
+The `action` export becomes a `"use server"` function (see
+[`./data-and-actions.md`](./data-and-actions.md)).
 
 The loader-shaped variant is equally valid — and closer to the RR module when
 the loader carried authority. A `createLoader()` body can throw `notFound()`
 for the missing product AND push the data-derived meta itself
 (`ctx.use(Meta)({ title: product.name })`); register it with
 `loader(ProductLoader, { ssr: false })` when the 404 status and
-title must be in the document deterministically. See `/loader` → "Loader
-Authority" and "Writing Handles from Loaders". (One RR habit that does NOT
-carry over: a loader `throw redirect()` is a client-side navigate on document
-loads, never an HTTP 302 — pre-stream 302s belong in middleware.)
+title must be in the document deterministically (the flag makes the server
+settle that loader before the first flush; it is unrelated to RR7's
+`ssr: false` SPA mode, which has no route-wide Rango equivalent). See
+`/loader` → "Loader Authority" and "Writing Handles from Loaders". (One RR
+habit that does NOT carry over: a loader `throw redirect()` is a client-side
+navigate on document loads, never an HTTP 302 — pre-stream 302s belong in
+middleware.)
 
 ### RR7 file routing → urls() DSL
 

package/skills/mime-routes/SKILL.md

@@ -15,12 +15,14 @@ See also: `/response-routes` for the base response route API (path.json, path.te
 ## Defining Negotiated Routes
 
 Declare the same URL pattern with both an RSC route and one or more response-type routes.
-Order within the `urls()` array does not matter — the trie merges them at build time.
+The trie merges them into one negotiated leaf at build time, whatever their order. Order
+only decides the default for `*/*`, a missing `Accept`, or an `Accept` no variant serves:
+the first-defined route wins (rule 4 below).
 
 ```typescript
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout, include }) => [
+export const urlpatterns = urls(({ path }) => [
   // RSC page + JSON API on the same URL
   path("/products/:id", ProductPage, { name: "product" }),
   path.json(
@@ -38,10 +40,10 @@ When an API client requests the same URL (`Accept: application/json`), the JSON
 
 ## Negotiation Rules
 
-1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
+1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC); `q=0` entries are ignored
 2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
-3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
-4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
+3. **Specific MIME match** — the variant whose MIME type appears in Accept wins; a type wildcard such as `text/*` picks the first candidate of that type
+4. **Wildcard / empty / unmatched Accept** — `*/*`, a missing Accept, and an Accept that no candidate serves fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
 5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
 
 RSC participates as a candidate alongside response-type variants under two MIME
@@ -150,9 +152,12 @@ no payloads, so response types resolve to `never`.
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.
    RSC routes become the primary trie leaf; response-type routes are stored in the `nv`
    (negotiate variants) array on the leaf. The `rf` (rsc-first) flag tracks definition order.
-2. **Runtime**: `previewRoute()` reads `negotiateVariants` from the trie match result.
+2. **Runtime**: `negotiateRoute()` (called during request classification) reads `negotiateVariants` from the trie match result.
    It parses the `Accept` header (extracting q-values and order), builds a candidate list
-   (RSC as `text/html` + response-type variants), and calls `pickNegotiateVariant()`.
+   (the response-type variants in definition order, plus RSC as `text/html` and `text/x-component` —
+   placed first when the RSC route was defined first, otherwise last),
+   and calls `pickNegotiateVariant()`. When a variant with different param names wins
+   (`/widgets/:id` vs `/widgets/:file`), params are re-keyed to the variant's names.
 3. **Candidate matching**: walks the client's sorted Accept list (by q desc, then order asc),
    matching each entry against candidates. Wildcards (`*/*`, `text/*`) fall back to definition order.
 4. **Vary header**: both the response-route handler wrapper and the RSC handler wrapper

package/skills/observability/SKILL.md

@@ -9,15 +9,17 @@ argument-hint:
 Use this when you need to understand request latency, cache decisions,
 revalidation behavior, loader overlap, or production traces.
 
-Rango exposes two complementary observability surfaces:
+Rango exposes three complementary observability surfaces:
 
 1. **Performance timeline** (`debugPerformance`) — per-request waterfall for
    local or targeted debugging. It prints to the console and emits
    `Server-Timing`.
-2. **Structured telemetry** (`telemetry`) — lifecycle events sent to a pluggable
-   sink for production monitoring, OpenTelemetry, or custom metrics.
+2. **Structured telemetry** (`telemetry`) — discrete lifecycle events sent to a
+   pluggable sink for production monitoring, OpenTelemetry, or custom metrics.
+3. **Tracing** (`tracing`) — the same phases as the timeline, emitted as spans
+   into OpenTelemetry, Cloudflare Workers, or Vercel traces.
 
-The essentials are below. The exported `TelemetryEvent` union type
+All three are off by default. The essentials are below. The exported `TelemetryEvent` union type
 (`import type { TelemetryEvent } from "@rangojs/router"`) is the full event
 contract — every event kind and its fields are typed there.
 
@@ -35,7 +37,8 @@ const router = createRouter({
 });
 ```
 
-Or enable for selected requests from middleware:
+Or enable for selected requests from middleware (route `middleware()` inside
+`urls()`, or `router.use()` for every request):
 
 ```typescript
 middleware(async (ctx, next) => {
@@ -52,11 +55,83 @@ shared-axis waterfall and adds a `Server-Timing` header.
 Read the timeline as intervals:
 
 - `handler:total` is the whole router request.
-- `render:total` / `ssr-render-html` show the render pass.
-- `loader:*` rows should overlap render work. If a loader starts only after the
-  render bar, it is serialized latency.
-- Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
-  appear as separate spans, so the slow phase is visible without guessing.
+- `render:total:<routeName>` (or `render:total` for unnamed routes) and
+  `ssr:render-html` show the render pass.
+- `loader:<id>` rows should overlap render work. If a loader starts only after
+  the render bar, it is serialized latency.
+- Route matching (`match:*`), middleware (`middleware:<name>:pre` / `:post`),
+  actions (`action:<id>`), cache, RSC serialization, and SSR setup appear as
+  separate rows, so the slow phase is visible without guessing.
+
+### Reading a PPR shell HIT
+
+A `ppr` route serving from its shell cache commits the response as soon as the
+stored prelude is read, so its waterfall ends at `ppr:shell-commit`; what runs
+after the commit (the capture snapshot, the seeded tail, the resumed holes)
+prints as one `shell tail` line when it finishes, and rides the NEXT request's
+`Server-Timing` as `ppr-tail`. The store-read rows under `ppr:shell-read` come
+from the built-in stores (`CFCacheStore`'s prelude-first read shown here;
+`VercelCacheStore` reports `hit store`, one `ppr:shell-match (store)` row, and
+a `serial` marker read); other stores show `ppr:shell-read`,
+`ppr:shell-open`, and `ppr:shell-commit` only. From `vite preview` of
+`tests/cloudflare-basic` `/ppr-large/holes` (614 KB prelude, 1.0 MB capture
+snapshot), with the timeline column dropped:
+
+```
+[RSC Perf] GET /ppr-large/holes (4.00ms)
+ start     dur  span
+1.00ms  0.00ms      middleware:*#2
+1.00ms  3.00ms    ppr:shell-read (hit l1)
+1.00ms  1.00ms      ppr:shell-match (l1)
+1.00ms  3.00ms    render:total:pprLargeHoles
+2.00ms  0.00ms      ppr:shell-head (bytes=27943)
+2.00ms  2.00ms      ppr:shell-prelude (bytes=628949)
+2.00ms  0.00ms      ppr:shell-marker (tags=0 parallel commit-wait=0.00ms)
+4.00ms  0.00ms    ppr:shell-open (cpu raw prelude=628949b)
+4.00ms  0.00ms    ppr:shell-commit (cpu chunks=20 prelude=628949b)
+0.00ms  4.00ms    handler:total
+```
+
+and, when the tail finishes, one console line (wrapped here):
+
+```
+[RSC Perf] GET /ppr-large/holes shell tail: complete snapshot=4ms
+snapshot-read=2ms snapshot-bytes=1019145b snapshot-parse-cpu=2ms
+records=segment:1 pruned=item:5 seed=4ms seed-cpu=0ms match=4ms handover=4ms
+first-html=5ms complete=55ms prelude=628949b tail=1033762b
+```
+
+- `ppr:shell-match` then `head` then `prelude`: the store read. Only the head
+  and the prelude are read before the first byte; the snapshot is read off the
+  commit path (`snapshot=` in the tail line). A KV hit after a Cache API miss
+  starts with a `ppr:shell-l1-miss` row (the L1 attempt and why it missed). A
+  `ppr:shell-memo (hit …)` row means the shell came from the isolate's memo:
+  no store read, only the marker check.
+- `ppr:shell-marker` is the tag-marker check, on every `CFCacheStore` read; it
+  runs alongside `ppr:shell-prelude`, and `commit-wait` is how much it held the
+  commit back (with `tags=0` it resolves at once). For a tagged shell it adds
+  `memo=` (how the per-isolate marker memo answered: `fresh`, `stale` served
+  while it refreshes, `read` from the store, `bypass` for a request carrying
+  the fresh-reads cookie), `hint=<shell tags hinted>/<tags hinted>` with `lead=` (how long the
+  hinted marker reads ran before the entry named its tags), and `fresh-reads`
+  when the request carried the cookie.
+- `records=` counts the snapshot records the tail was seeded with, by
+  family; `pruned=` counts the ones the capture dropped because no reader of
+  the entry consumes them. Here every HIT tail replays the handler layer from
+  the one segment record, so the five `"use cache"` item records that produced
+  it were not stored.
+- `snapshot=`, `seed=`, `match=`, `first-html=` are offsets from the commit,
+  not durations; `snapshot-read=`, `snapshot-parse-cpu=` and `seed-cpu=` are
+  durations.
+- On a deployed worker the clock only moves on I/O, so the CPU-only numbers
+  (`ppr:shell-open`, `ppr:shell-commit`, `snapshot-parse-cpu`, `seed-cpu`)
+  read 0 there; the byte counts are the cost to watch.
+
+The console waterfall uses these labels as written. In the `Server-Timing`
+header, colons become hyphens and other non-alphanumeric characters are
+dropped (`ssr:render-html` → `ssr-render-html`, `handler:total` →
+`handler-total`), and nested rows get a `d<depth>-` prefix. The full metric
+list is in the repository's `packages/rangojs-router/docs/telemetry.md`.
 
 **Deployed Cloudflare caveat**: on production Workers, timers are frozen
 during request execution (Spectre mitigation), so `Server-Timing` durations
@@ -106,7 +181,9 @@ const router = createRouter({
 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:
+`@opentelemetry/api` dependency. It reads the tracer from the `ctx` your Worker
+passes to `router.fetch(request, { env, ctx })`, and is a pass-through when
+Workers tracing is not enabled for the Worker:
 
 ```typescript
 import { createRouter } from "@rangojs/router";
@@ -226,6 +303,7 @@ Then inspect:
 
 ## Zero-overhead defaults
 
-`debugPerformance` is off by default, and `telemetry` emits nothing unless a sink
-is configured. Per-request `ctx.debugPerformance()` lets you turn on the
-waterfall only for the route, user, or query param you are investigating.
+`debugPerformance` is off by default, `telemetry` emits nothing unless a sink
+is configured, and with `tracing` unset every span call runs the work directly.
+Per-request `ctx.debugPerformance()` lets you turn on the waterfall only for the
+route, user, or query param you are investigating.