@rangojs/router 0.17.0 → 0.18.0

package/skills/migrate-nextjs/SKILL.md

@@ -40,8 +40,10 @@ Common reasons to migrate:
   build-time rendering instead of mixing rendering and caching behind conventions.
   See: `/prerender`
 - **Partial prerendering, shipped** — the `ppr` path option caches a page's
-  HTML shell and resumes only the live holes on each request; loaders stay
-  fresh. The equivalent of Next's `experimental_ppr`, stable and per-route.
+  HTML shell and resumes its holes per request: loaders without `ssr: false`,
+  read under `loading()` or an inline `<Suspense>`. Handler output bakes into
+  the shell. It maps to Next's `experimental_ppr`, stable and per-route, but
+  holes come from loaders, not from any `<Suspense>`.
   See: `/ppr`
 - **Composable route tree** — layouts, includes, middleware, parallels, and
   intercepts compose directly in the route definition.
@@ -93,6 +95,13 @@ its call site with the real Rango API:
 | `next/font`                                                                  | see `/fonts`                                                                                   |
 | `next/script` `Script`                                                       | see `/scripts`                                                                                 |
 | `next-themes`                                                                | `theme: true` in `createRouter` (see §10)                                                      |
+| `next/dynamic` `dynamic(() => import(...), { ssr: false })`                  | render it after mount in a `"use client"` component (see the note below)                       |
+
+`next/dynamic`'s `{ ssr: false }` keeps a component out of server rendering:
+render it only after mount in a `"use client"` component (a `useEffect` flag,
+with `React.lazy()` if its code should split out). Do not map it to
+`loader(L, { ssr: false })`, which does the opposite: the server settles that
+loader before the first flush, and under `ppr` it bakes into the shell.
 
 If an import has no row here and no obvious Rango equivalent, stop and surface
 it to the user — do not mock it to keep the build green.
@@ -418,9 +427,12 @@ Next.js route segment config maps onto Rango's explicit primitives:
 ### Partial prerendering → the `ppr` path option
 
 Next.js PPR statically prerenders a shell at build time and streams the parts
-inside `<Suspense>` at request time. Rango ships the same model as a path
+inside `<Suspense>` at request time. Rango ships a similar model as a path
 option — the shell is captured at runtime into the app cache store and resumed
-on later requests, with the holes rendered fresh per request:
+on later requests, with the holes rendered fresh per request. The difference is
+what counts as a hole: in Rango everything a handler produces is shell
+material, as it is under `cache()`, including a promise it hands to a component
+under `<Suspense>`. A live hole is loader data:
 
 ```typescript
 // Next.js: app/products/[id]/page.tsx
@@ -435,14 +447,14 @@ export default async function Page({ params }) {
   );
 }
 
-// Rango, step 1 — direct carry-over. Your Suspense tree IS the hole model:
-// hand the un-awaited promise down, keep the boundary, add the ppr option.
-// No loader, no loading(), no restructuring.
+// Rango: the direct carry-over BAKES. Under ppr the capture awaits a promise
+// the handler hands down (bounded by ppr.captureTimeout), and every shell HIT
+// shows the captured price.
 import { Suspense } from "react";
 import type { HandlerContext } from "@rangojs/router";
 
 function ProductPage(ctx: HandlerContext) {
-  const price = fetchPrice(ctx.params.id); // pending promise — NOT awaited
+  const price = fetchPrice(ctx.params.id); // awaited at capture, then frozen
   return (
     <ProductShell>
       <Suspense fallback={<PriceSkeleton />}>
@@ -451,41 +463,54 @@ function ProductPage(ctx: HandlerContext) {
     </ProductShell>
   );
 }
-path("/products/:id", ProductPage, {
-  name: "product",
-  ppr: { ttl: 600, swr: 120 }, // or ppr: true (default ttl 300s)
-});
 
-// Rango, step 2 (optional refinement) — promote the fetch to a live loader
-// (no ssr: false) for a GUARANTEED hole, even when the value resolves
-// instantly; loading() is its boundary (/ppr → The loader lane rule).
+// Rango, live price: a loader without ssr: false, read with
+// useLoader(LivePriceLoader) in a client component. loading() (or an inline
+// <Suspense> around the reader) is the hole boundary (/ppr → The loader lane
+// rule).
+function ProductPageLive() {
+  return (
+    <ProductShell>
+      <LivePriceFromLoader /> {/* "use client": useLoader(LivePriceLoader) */}
+    </ProductShell>
+  );
+}
 path(
   "/products/:id",
-  ProductPage,
-  { name: "product", ppr: { ttl: 600, swr: 120 } },
+  ProductPageLive,
+  { name: "product", ppr: { ttl: 600, swr: 120 } }, // or ppr: true (ttl 300s)
   () => [loader(LivePriceLoader), loading(<PriceSkeleton />)],
 ),
 ```
 
 Differences that matter during migration:
 
-- **The Suspense/promise model carries over.** As in Next, a still-pending
-  promise handed to a component that suspends under its own `<Suspense>`
-  postpones at capture and becomes a hole — existing Next PPR trees keep
-  working as-is, no `loading()` required. One container rule everywhere
-  (handlers, handles, loaders): awaited/settled data bakes into the shell; a
-  promise nested inside your data stays a live hole. For loaders, `ssr: false`
-  (not `loading()`) selects the lane — see `/ppr` → The loader lane rule.
-  Identity reads (`cookies()`/`headers()`) where the value would bake refuse
-  the capture by construction.
+- **Handler output bakes; loader data is the hole.** Unlike Next, a pending
+  promise the handler hands to a component under `<Suspense>` does NOT make a
+  hole. Everything a handler produces — that promise, an async server
+  component, a nested promise in a handle it pushes, a loader it awaits — is
+  awaited at capture (bounded by `ppr.captureTimeout`) and served frozen for
+  the shell's lifetime; a shell HIT never runs a handler. Keep the parts that
+  must be fresh in loaders without `ssr: false`, read with `useLoader` under
+  `loading()` or an inline `<Suspense>`; inside an `ssr: false` loader, return
+  them as nested promises. For loaders, `ssr: false` (not `loading()`) selects
+  the lane — see `/ppr` → The loader lane rule.
 - **Shell freshness is explicit.** Next's PPR shell is fixed until the next
   build; Rango's has `ttl`/`swr`/`tags` per route, and `updateTag()` /
   `revalidateTag()` drop the shell (`revalidate()` does not — it is a data
-  lever and never touches shell HTML).
-- **`cookies()`/`headers()` in shell material THROW during capture** (in Next
-  they silently force dynamic rendering). Per-user reads must move into a live
-  loader (no `ssr: false`; a nested promise does not help). The refusal
-  surfaces at migration time, which is the point.
+  lever and never touches shell HTML). Under a route `cache()`, the shell
+  lives no longer than that entry: its ttl/swr are capped by the entry's (dev
+  warns when an explicit `ppr` window is reduced). A route `cache({ key })`
+  gives one shell per key value, and `cache(false)` or a false `condition()`
+  means no shell.
+- **Request-scoped reads in shell material refuse the capture** (in Next they
+  silently force dynamic rendering). `cookies()`, `headers()`, a
+  `{ cache: false }` variable, and `ctx.dynamic()` refuse it anywhere the
+  capture waits: a handler, a promise it passes or pushes, an async component,
+  a loader it awaits. Per-user reads must move into a live loader (no
+  `ssr: false`; a nested promise does not help). A normal `ctx.get()` value is
+  not guarded and bakes as the capturing request's value. The refusal surfaces
+  at migration time, which is the point.
 - **A store is required.** PPR needs the app-level `createRouter({ cache })`
   store to implement the shell family (`MemorySegmentCacheStore`,
   `CFCacheStore`, `VercelCacheStore`). Without one the route quietly stays
@@ -506,19 +531,25 @@ tag-based cache invalidation now maps directly.
 with `cache({ tags })` or runtime `cacheTag(...tags)`. `cacheTag()` works inside a
 `"use cache"` function (tags that entry) AND render-callable in a plain server
 component (no `"use cache"` needed — it tags the document / PPR shell the component
-renders into). Then invalidate by tag:
+renders into, and the route `cache()` entry it renders inside). Then invalidate by tag:
 
 ```typescript
 // Next.js                    Rango
 // revalidateTag("products")  →  await updateTag("products")  // in a server action: awaitable,
 //                                                            // read-your-own-writes (next render is fresh)
 //                            or  revalidateTag("products")    // in a route handler / webhook:
-//                                                            // background, non-blocking (hard-purge)
+//                                                            // background, non-blocking (evicts)
 ```
 
 `updateTag` is awaitable and immediate; `revalidateTag` is fire-and-forget. Both
-hard-purge (the next read re-renders fresh); the only difference is awaitability —
-despite the Next.js name, `revalidateTag` here is NOT stale-while-revalidate.
+evict (despite the Next.js name, `revalidateTag` here is NOT
+stale-while-revalidate), and the request that calls either reads its own
+writes. `updateTag()` also waits for the durable write and rejects when it
+fails; `revalidateTag()` runs it in the background. The mutating user's next
+requests skip the stores' per-isolate PPR shell memos via the fresh-reads
+cookie (`rango-state-fresh`); other users, and other locations on
+`CFCacheStore`, see the invalidation once the memo refreshes and KV
+propagates (`/caching` → "The fresh-reads cookie").
 Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`, `VercelCacheStore`)
 index by tag. Next's
 `revalidatePath` has no path-based equivalent — tag the relevant entries instead.
@@ -756,7 +787,7 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
-Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data; `revalidateTag(tag)` is a background (non-blocking) hard-purge and is NOT read-your-own-writes, so reserve it for route handlers / webhooks (calling it from an action can leave that action's re-render stale). `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, the route, the segments inside its `path()`, and all loaders already re-run after every action; layouts and parallels above the route are skipped. To re-render one of those skipped segments after an action, attach `revalidate((ctx) => ctx.isAction(updateBlog) || undefined)` to it; to narrow a loader or route segment to one action, use `revalidate((ctx) => (ctx.isAction() ? ctx.isAction(updateBlog) : undefined))` (match the imported action by reference, as in §3). See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data, and it rejects when the store's durable write fails; `revalidateTag(tag)` is a background (non-blocking) hard-purge for route handlers / webhooks. The request that calls `revalidateTag()` also reads its own writes, but a failed durable write only reaches `onError`. `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, the route, the segments inside its `path()`, and all loaders already re-run after every action; layouts and parallels above the route are skipped. To re-render one of those skipped segments after an action, attach `revalidate((ctx) => ctx.isAction(updateBlog) || undefined)` to it; to narrow a loader or route segment to one action, use `revalidate((ctx) => (ctx.isAction() ? ctx.isAction(updateBlog) : undefined))` (match the imported action by reference, as in §3). See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
 
 ## 8. Metadata / Head
 

package/skills/migrate-react-router/SKILL.md

@@ -33,7 +33,8 @@ Common reasons to migrate:
   See: `/middleware`, `/loader`
 - **Live data layer** — `createLoader()` and `loader()` keep data fresh
   independently of cached UI. A route can serve cached segments while loaders
-  still resolve live on every request.
+  still resolve live on every request (on a `ppr` route, a loader registered
+  with `ssr: false` bakes into the cached HTML shell instead; see `/ppr`).
   See: `/loader`, `/caching`, `/cache-guide`
 - **Explicit caching model** — `cache()` DSL, `revalidate()`, `use cache`, and
   custom cache stores make data and render caching a first-class part of the router.

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

@@ -154,7 +154,9 @@ 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 `<Html.Meta />` in the Document component's `<head>`:
 

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

@@ -48,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

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

@@ -142,10 +142,13 @@ 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/observability/SKILL.md

@@ -63,6 +63,70 @@ Read the timeline as intervals:
   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` →

package/skills/parallel/SKILL.md

@@ -148,13 +148,18 @@ route overrides via its own `@meta` slot. The route's slot pushes after the
 layout, and `Meta` keeps the last value per key, so the override wins.
 
 > **Loader-derived metadata: push from the loader instead.** This slot's
-> `await ctx.use(ProductLoader)` routes the data through HANDLER consumption —
-> the baked lane under `cache()`/PPR — just to reach a `ctx.use(Meta)` call.
-> The loader can now push `Meta` itself (`/loader` → "Writing Handles from
-> Loaders"), keeping the data on the live lane; add
-> `loader(Def, { ssr: false })` when the meta must be in the SSR'd
-> head. Keep the `@meta` slot for metadata that is NOT loader-derived
-> (templates, static descriptions, structured data with independent inputs).
+> `await ctx.use(ProductLoader)` routes the data through HANDLER consumption
+> just to reach a `ctx.use(Meta)` call: under `cache()` the slot's output is
+> stored with the segment, and on a `ppr` route it bakes into the shell and a
+> HIT replays it without running the slot. The loader can push `Meta` itself
+> (`/loader` → "Writing Handles from Loaders"). Without `ssr: false` the
+> loader runs per request, but on a `ppr` route its push is not in the
+> shell's `<head>` (it applies after hydration). Add
+> `loader(Def, { ssr: false })` when the meta must be in the SSR'd head; on a
+> `ppr` route that bakes the push into the shell, and a HIT serves it without
+> running the loader when its value has no promises. Keep the `@meta` slot for
+> metadata that is NOT loader-derived (templates, static descriptions,
+> structured data with independent inputs).
 
 ```typescript
 // Layout sets defaults
@@ -275,7 +280,7 @@ 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").
+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 freezes into the artifact. Under `cache()`/`"use cache"` an identity read (`cookies()`, `headers()`) inside the loader bakes too; under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) 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.