@rangojs/router 0.21.0 → 0.22.0

package/skills/migrate-nextjs/SKILL.md

@@ -416,13 +416,82 @@ default) or serves an open-ended param space. See `/prerender` for full API.
 
 Next.js route segment config maps onto Rango's explicit primitives:
 
-| Next.js segment config                              | Rango                                                        |
-| --------------------------------------------------- | ------------------------------------------------------------ |
-| `dynamic = "force-static"` + `generateStaticParams` | `Static()` / `Prerender()` (see `/prerender`)                |
-| `revalidate = 60` (ISR)                             | `cache({ ttl: 60, swr: ... })` on the route (see `/caching`) |
-| `dynamic = "force-dynamic"`                         | the default — routes are dynamic unless you cache them       |
-| `dynamicParams = true`                              | `Passthrough()` (above)                                      |
-| `experimental_ppr = true`                           | the `ppr` path option (below, and `/ppr`)                    |
+| Next.js segment config                              | Rango                                                                                                                     |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `dynamic = "force-static"` + `generateStaticParams` | `Static()` / `Prerender()` (see `/prerender`)                                                                             |
+| `revalidate = 60` (ISR)                             | `cache({ ttl: 60, swr: ... })` on the route (see `/caching`), or on-demand prerender with `onDemand: { ttl: 60 }` (below) |
+| `dynamic = "force-dynamic"`                         | the default — routes are dynamic unless you cache them                                                                    |
+| `dynamicParams = true`                              | `Passthrough()` (above)                                                                                                   |
+| `experimental_ppr = true`                           | the `ppr` path option (below, and `/ppr`)                                                                                 |
+
+### On-demand ISR → `Prerender(..., { onDemand })` + `router.prerender()`
+
+A Next.js page with `generateStaticParams` refreshed by `revalidatePath()` or
+`revalidateTag()` from a CMS webhook maps to an on-demand prerender route. The
+route opts in, a store holds refreshed payloads, and the webhook re-renders the
+page instead of invalidating it:
+
+```typescript
+// Next.js:
+export const revalidate = 3600;
+export async function generateStaticParams() {
+  return (await getFeatured()).map((p) => ({ id: p.id }));
+}
+// app/api/revalidate/route.ts
+revalidatePath(`/products/${id}`);
+revalidateTag(`product:${id}`);
+
+// Rango:
+export const ProductPage = Prerender<{ id: string }>(
+  async () => (await getFeatured()).map((p) => ({ id: p.id })),
+  async (ctx) => <Product data={await getProduct(ctx.params.id)} />,
+  { onDemand: { ttl: 3600, tags: ({ params }) => [`product:${params.id}`] } },
+);
+
+// router: createRouter({ prerender: { store, ttl, onRevalidate? } })
+// webhook (route handler, cron or queue):
+const prerender = router.prerender({ env, ctx });
+await prerender(`/products/${id}`); // revalidatePath
+await prerender.markStale([`product:${id}`]); // revalidateTag
+```
+
+| Next.js                               | Rango                                                                                               |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `revalidatePath(path)` on an ISR page | `await router.prerender({ env, ctx })(path)`: renders now, serves the new payload next request      |
+| `revalidateTag(tag)` on ISR pages     | `router.prerender({ env, ctx }).markStale([tag])`: marks only; a stale hit schedules `onRevalidate` |
+| `revalidate = N` (time-based ISR)     | `onDemand: { ttl: N }` + `onRevalidate`; `ttl` is soft, entries never expire                        |
+| `dynamicParams = false`               | plain on-demand `Prerender`: an unknown param 404s until something refreshes it                     |
+| `dynamicParams = true`                | wrap it in `Passthrough()`: unknown params render live until refreshed                              |
+
+A page whose item was deleted. In the Pages Router, `getStaticProps` returns
+`{ notFound: true }` on a revalidation: "With `notFound: true`, the page will
+return a `404` even if there was a successfully generated page before. This is
+meant to support use cases like user-generated content getting removed by its
+author. Note, `notFound` follows the same `revalidate` behavior described
+here." In Rango a `notFound()` anywhere in the on-demand render (the route
+handler, a layout or slot handler, any server component) does the same on the
+next `prerender(path)`: the result is `{ ok: true, status: "removed" }`, the
+page answers 404 instead of the page or its build-time entry, and the removal
+is rechecked per the route's `ttl`, as Next's is per `revalidate`. When the
+data source may be failing, throw anything else: that keeps the page.
+`prerender.remove(path)` removes without rendering, for a webhook that already
+knows the item is gone, and is permanent until a `prerender(path)` renders the
+page again. See `/prerender` → "Remove a page".
+
+Three differences to plan for:
+
+- Prerender tags are their own namespace. `updateTag()` / `revalidateTag()`
+  from `@rangojs/router` purge the runtime cache and never reach on-demand
+  entries; `markStale()` never reaches the runtime cache.
+- A refresh is requestless: `cookies()` / `headers()` in the page make it
+  return `skipped-personalized`, and `ctx.env` is the live env you pass.
+- `markStale()` does not re-render: without `onRevalidate` or a cron calling
+  `prerender(target, { onlyIfStale: true })` (the runner from
+  `router.prerender({ env, ctx })`), a marked page keeps
+  serving its old payload.
+
+See `/prerender` → "On-demand refresh (ISR)" for the store options, the serve
+table and the rules.
 
 ### Partial prerendering → the `ppr` path option
 
@@ -552,7 +621,9 @@ cookie (`rango-state-fresh`); other users, and other locations on
 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.
+`revalidatePath` has no path-based equivalent for runtime-cached data — tag the
+relevant entries instead. For a prerendered ISR page it is
+`router.prerender({ env, ctx })(path)` (see "On-demand ISR" above).
 
 **2. Partial-render selection (which segments re-run after an action).** This is
 NOT cache invalidation — it is `revalidate()`, controlling which segments
@@ -594,7 +665,9 @@ When migrating:
 
 - `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
   `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
-- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+- `revalidatePath(path)` on an ISR page → `router.prerender({ env, ctx })(path)`
+  (on-demand prerender, §3); on runtime-cached data, no path-based
+  equivalent; tag the entries on that
   route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
 - To also force specific segments to re-render after the action (independent of
   cache busting), attach a `revalidate()` rule at those segment boundaries.

package/skills/ppr/SKILL.md

@@ -170,7 +170,7 @@ The partition follows nested scopes (issue #970): a `ppr` route under a
 inner boundary has none, and by both composed (outermost first, joined by
 `|`) when it has its own. Each `key()` result is namespaced as `key:` plus
 its URI encoding (issue #975), exactly as in the record key, so the shell of
-`key: () => "tier:gold"` is `<host><path>:shell|key%3Atier%253Agold`. The
+`key: () => "tier:gold"` is `<router>@<host><path>:shell|key%3Atier%253Agold`. The
 route's record adds the inner boundary's own default key when it has no
 `key`; the shell partition does not, since the shell key already carries the
 URL (a store `keyGenerator`'s result is kept when it adds anything, an
@@ -220,10 +220,10 @@ does not render from: otherwise the first variant captured is served for every
 value of it.
 
 In tests, `serveShellRequest` reports the key the serve path resolved
-(`result.key`, partition included); `shellCacheKey(url, searchParams,
+(`result.key`, partition included); `shellCacheKey(router, url, searchParams,
 partition)` builds the same key from the `key()` result, namespacing it as
 production does. Under nested keyed scopes, pass the `key()` results as an
-array, outermost first (`shellCacheKey(url, undefined, ["tier:gold",
+array, outermost first (`shellCacheKey(router, url, undefined, ["tier:gold",
 "v:a"])`); for a store `keyGenerator` partition pass
 `{ keys, generated }` (`/testing`, `cache-prerender.md`).
 
@@ -264,7 +264,7 @@ On a document GET to a ppr route the router runs:
    DSL `middleware()`; both are guards, and the COMMIT POINT is after all of
    them: any rejection/redirect/401 wins before a single shell byte, on MISS
    and on a warmed HIT alike;
-3. **shell lookup** — `getShell(key)` on the app store (key =
+3. **shell lookup** — `getShell(key)` on the app store (key = router id +
    host+pathname+sorted search). `CFCacheStore` stores the entry prelude-first
    and the serve path reads only its head and prelude here, with the tag-marker
    read running alongside; the capture snapshot is read off the commit path.
@@ -561,6 +561,19 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   writes, and marker rejection, with `cf-ray`/colo and read timings. The flag is baked at
   build time; setting only a Worker runtime variable is too late.
 
+### Capturing a shell before the first visitor
+
+A shell is captured by the first document MISS for its key, so the first
+visitor after a deploy or an `updateTag()` renders without one. To capture it
+ahead of them, warm the URL: `router.prerender({ env, ctx })(url)` renders it
+through the handler, schedules the capture and waits for it, so the next
+document request is a HIT. A warm replaces a stored shell in place (the old
+one serves until the new one is written) and reports the capture's outcome
+(`result.caches.shell`, with `refusal` when the capture refused). It is not
+subject to the per-key in-flight dedup or the refused-capture backoff, which
+exist to stop a herd of visitors repeating work; every correctness guard on
+this page still decides. See `/prerender` → "Warm any route before traffic".
+
 ### Unit / integration testing (public primitives)
 
 Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
@@ -571,17 +584,18 @@ Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
 | `assertShellStatus(res, "HIT" \| "MISS")`         | Document Response from a real RSC serve / e2e `page.request` |
 | `assertPprReplayStatus(res, expected)`            | Partial response fresh/stale replay or bounded bypass        |
 | `parsePprReplayStatus(res)`                       | Read structured replay/bypass status or null                 |
-| `shellCacheKey(url)`                              | Production store key for `store.getShell` / custom stores    |
+| `shellCacheKey(router, url)`                      | Production store key for `store.getShell` / custom stores    |
 | `MemorySegmentCacheStore` + `getShell`/`putShell` | Custom store contract / tag eviction (no faked HIT)          |
 | `serveShellRequest(router, url, opts)`            | A real MISS → capture → HIT (react-server Vitest)            |
 
 ```ts
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 import { assertShellStatus, shellCacheKey } from "@rangojs/router/testing";
+import { router } from "./router";
 
 // Unit: store + key (after a real putShell / capture flush in e2e)
 const store = new MemorySegmentCacheStore();
-const key = shellCacheKey("http://localhost/products/1");
+const key = shellCacheKey(router, "http://localhost/products/1");
 // ... after production putShell ...
 expect(await store.getShell(key)).not.toBeNull();
 
@@ -788,6 +802,9 @@ identifiers — served to anonymous visitors.)
 - `ctx.use(H)(promise)` from a handler — a TOP-LEVEL pushed promise is awaited
   at capture and BAKED into the shell (bounded by `ppr.captureTimeout`, 15s by
   default).
+- A promise pushed from a LOADER is never in the shell and the capture does not
+  wait for it: however slow it is (or if it never settles), the shell is still
+  stored, and the HIT's own loader run delivers the value after hydration.
 - `ctx.use(H)({ x: promise })` from a HANDLER — also baked. The capture waits
   for every promise nested in a handler's push, at any depth of plain objects,
   arrays and JSX props, before it records the handles every HIT replays. Keep
@@ -930,6 +947,11 @@ pin: a snapshot captured by a navigation alone carries none, and a shell over
 `ppr.maxSnapshotBytes` drops them. There the loader runs fresh, and its
 pushes are that run's, like its data.
 
+A `Prerender` + `ppr` page follows the same table. Its handler layer comes
+from the prerendered payload, which never holds a loader push (loaders do not
+run at build), so the shell entry records the loader pushes its HTML rendered
+on its own, and a HIT restores them as above (#1057).
+
 A dependency the route does not register, which an `ssr: false` loader
 awaited at capture outside any live loader, is on neither lane: its settled
 pushes stay as the prelude rendered them, even where a live loader also
@@ -1347,8 +1369,9 @@ shrink what the shell bakes or move large regions under a live loader's
 boundary.
 
 The shell store is always the app-level `createRouter({ cache })` store; the
-default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so
-multi-tenant shells never collide).
+default key is `${routerId}@${host}${pathname}${sortedSearch}:shell`: host-scoped
+so multi-tenant shells never collide, and router-scoped so two routers on one
+store keep their own (see `/host-router`, "Shared cache store").
 
 These options control the in-function shell entry only. They do not emit HTTP
 `Cache-Control`. Adding `s-maxage` separately allows a platform CDN to cache the