@rangojs/router 0.0.0-experimental.137 → 0.0.0-experimental.139

package/skills/shell-manifest/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: shell-manifest
+description: Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices
+argument-hint:
+---
+
+# Shell Manifest — cache metadata for live loaders
+
+Use this when a cached or prerendered shell has dynamic holes, and the live
+data layer needs to know **what the shell actually contains** — which
+products, which slots, which keys. The frozen render describes itself
+through a handle; loaders (always live) read that description and fetch
+exactly the dynamic data the shell needs, in one batch.
+
+Canonical case: a prerendered product list where prices must stay live.
+
+## The problem this solves
+
+Any cached-shell-plus-live-holes design has a coordination gap: how does the
+live layer know what the holes need?
+
+- **Per-hole fetching** (each `<Price>` component fetching for itself) is the
+  N+1 default — N visible products, N queries.
+- **A loader that re-queries the list** ("current top products") drifts from
+  a stale shell — right prices attached to wrong products.
+
+The shell manifest closes the gap with a consistency guarantee: the loader
+reads the ids the shell _actually rendered_, replayed from the same stored
+artifact, so the holes can never desync from the shell and the query is
+batched.
+
+## The mechanism (three features composed)
+
+1. **Handles record data at render time.** The handler pushes to a handle
+   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on
+   the cache miss for `cache()`.
+2. **Replay on every hit.** Handle data is stored with the Flight payload
+   and replayed into the handle store on cache/prerender hits — handler code
+   does not re-run, but its pushes do.
+3. **Loaders read after the render barrier.** A DSL loader can
+   `await ctx.rendered()` (waits for all non-loader segments to settle —
+   fresh render or replay alike), then `ctx.use(Handle)` returns the
+   **collected** handle data.
+
+Loaders are live by default, so the read happens on every request even when
+the shell is a hit.
+
+## Canonical example: prerendered list, live prices
+
+```tsx
+// handles/rendered-products.ts
+import { createHandle } from "@rangojs/router";
+
+// TData = string (one push per product id), collected to a flat string[]
+export const RenderedProducts = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
+```
+
+```tsx
+// routes/products.tsx — the list is baked at build time; prices are not
+import { Prerender } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+import { Price } from "../components/price";
+
+export const ProductList = Prerender(
+  async () => [{ category: "espresso" }, { category: "filter" }],
+  async (ctx) => {
+    const products = await db.productsByCategory(ctx.params.category);
+    const track = ctx.use(RenderedProducts);
+    for (const p of products) track(p.id);
+    return (
+      <ul>
+        {products.map((p) => (
+          <li key={p.id}>
+            {p.name} <Price id={p.id} />
+          </li>
+        ))}
+      </ul>
+    );
+  },
+);
+```
+
+```ts
+// loaders/prices.ts — one batched query for exactly the rendered products
+import { createLoader } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+
+export const PriceLoader = createLoader(async (ctx) => {
+  "use server";
+  await ctx.rendered();
+  const ids = ctx.use(RenderedProducts);
+  return db.pricesFor(ids); // Map<string, number> keyed by product id
+});
+```
+
+```tsx
+// urls.tsx — wire the route and register the loader
+path("/products/:category", ProductList, { name: "products" }, () => [
+  loader(PriceLoader),
+]);
+```
+
+```tsx
+// components/price.tsx — live hole in the frozen shell
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import { PriceLoader } from "../loaders/prices";
+
+export function Price({ id }: { id: string }) {
+  const { data } = useLoader(PriceLoader);
+  return <span>{formatPrice(data[id])}</span>;
+}
+```
+
+Request flow on a hit: stored payload replays (handler never runs) → handle
+data lands in the store → render barrier resolves → `PriceLoader` reads the
+replayed ids → one query → prices stream into `<Price>` components.
+
+## Works with runtime cache() too
+
+`Prerender` is build-time caching; the replay mechanism is identical for the
+runtime segment cache. Wrap the route in `cache()` instead and the handler
+pushes on the miss, replays on every hit:
+
+```tsx
+cache({ ttl: 600, tags: ["products"] }, () => [
+  path("/products/:category", ProductList, { name: "products" }, () => [
+    loader(PriceLoader),
+  ]),
+]);
+```
+
+## Contract and gotchas
+
+- **The manifest is exactly as fresh as the shell.** Replayed handle data is
+  frozen with the payload. To change _which_ products render, invalidate the
+  shell (`updateTag("products")`, TTL expiry, rebuild) — never treat the
+  loader as the refresh path for the list itself. This is the point:
+  shell and holes cannot desync because they share one artifact.
+- **No request-scoped data in a manifest handle.** The handle data is baked
+  into a shared artifact — the same cross-user rule as any cached content.
+  Ids, slugs, slot names, variant keys: yes. Anything derived from
+  `cookies()`/`headers()`: no.
+- **`ctx.rendered()` is experimental and DSL-loaders-only.** It throws in
+  fetchable/standalone loader calls that run outside a route render.
+- **The reading loader serializes after the shell.** `await ctx.rendered()`
+  deliberately gives up loader/render parallelism — on a miss the loader
+  waits for segment resolution; on a hit (the common case for a cached
+  shell) replay is immediate and the wait is negligible. A
+  `debugPerformance` waterfall shows this loader after the render bar; for
+  this pattern that is the contract, not a regression.
+- **`ctx.use(Handle)` before `await ctx.rendered()` throws** in a loader,
+  with an error saying to await the barrier first.
+- **Deferred handle values are resolved before storage** (resolve-by-default),
+  so the manifest read always sees plain values, never promises.
+
+## Testing
+
+`runLoader` seeds the barrier and the collected handle value directly —
+matched by handle reference (the same seeding style as loader deps):
+
+```ts
+import { runLoader } from "@rangojs/router/testing";
+
+const prices = await runLoader(PriceLoader, {
+  rendered: true,
+  handles: [[RenderedProducts, ["widget-a", "widget-b"]]],
+  env: { DB: fakeDb },
+});
+```
+
+This tests the loader's post-barrier logic. The real
+push → store → replay → barrier wiring is covered at the e2e tier (dev +
+production), like every cache-path behavior.
+
+## Related
+
+- `/prerender` — `Prerender`/`Passthrough`, build flow, passthrough fallback
+- `/caching` — segment `cache()`, stores, tags
+- `/loader` — loader context, `ctx.rendered()`, streaming
+- `/hooks` — `useHandle` for reading handle data in client components
+- `/rango` → "Passing data down the tree" — this pattern is the frozen→live
+  counterpart of that ladder

package/skills/testing/reverse-and-types.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (node) + typecheck · **Import:** `@rangojs/router/client` (useReverse), `@rangojs/router/testing` (assertGeneratedRoutesMatch) · **DSL it tests:** `reverse`/`href`/`useReverse` (see `/typesafety`, `/links`)
 
-The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed.
+The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed. It (and `diffGeneratedRoutes`) are **async — `await` them** — because expanding an async `include(prefix, () => import("./routes"))` group means importing that module first.
 
 ## API
 
@@ -13,7 +13,7 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 | `router`       | `{ routeMap; findMatch? }`           | Your router (real impl). `routeMap` is the live name→pattern map; `findMatch` (when present) is called to force-expand lazy `include()`d routes.           |
 | `generatedMap` | `Record<string, unknown>` (optional) | The imported `*.named-routes.gen.ts` map (name→pattern, or `{ path }` objects). Omit to diff against the global route map (`getGlobalRouteMap()`) instead. |
 
-### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` returns)
+### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` resolves to)
 
 | Field      | Type                           | Meaning                                                                                                                                     |
 | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -24,7 +24,7 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 
 ### Returns — `assertGeneratedRoutesMatch`
 
-`void` on match. On drift, throws an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` returns the `GeneratedRoutesDiff` above without throwing.)
+`Promise<void>` — **await it**. Resolves on match; on drift the promise REJECTS with an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` resolves to the `GeneratedRoutesDiff` above and never rejects.) Both are async so an async `include(() => import())` group is imported and spliced into `routeMap` before the diff — call them without `await` and every route in that group reads as a false `missing`.
 
 ## Recipe
 
@@ -57,14 +57,15 @@ expectTypeOf<
 
 ```ts
 // 3. assertGeneratedRoutesMatch — a one-liner whole-app drift test. Real
-//    matching expands lazy include()d routes before the diff.
+//    matching expands lazy include()d routes before the diff. It is async
+//    (it awaits findMatch to import async include groups), so await it.
 import { it } from "vitest";
 import { assertGeneratedRoutesMatch } from "@rangojs/router/testing";
 import { router } from "../src/router";
 import generated from "../src/router.named-routes.gen";
 
-it("generated named-routes map is in sync with the router", () => {
-  assertGeneratedRoutesMatch(router, generated);
+it("generated named-routes map is in sync with the router", async () => {
+  await assertGeneratedRoutesMatch(router, generated);
 });
 ```
 
@@ -74,7 +75,7 @@ For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` file
 
 - Type tests run at TYPECHECK time (`tsc --noEmit`), NOT in the vitest runner. They are their own layer — wire them into CI as a real step (`pnpm run typecheck`). A type test nobody runs is just a comment.
 - `@ts-expect-error` ERRORS if the line below it ever starts compiling, so a regressed guard fails the typecheck. A runtime test cannot assert "this should not type-check".
-- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (calls `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
+- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (awaits `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. It is **async** so it can await the module import behind an async `include(() => import())` group; `await` the call (or the async group's routes read as `missing`). This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
 - MULTI-APP route-map isolation. `href()`/`reverse()` typing is GLOBAL — each app's generated file augments the one `Rango.GeneratedRouteMap` interface. A `renderRoute` suite that imports a client component from app B (which calls `href("/b-route")`) won't typecheck if the same tsconfig program also carries app A's augmentation: A's route union rejects B's name. `renderRoute` is app-agnostic at RUNTIME; the collision is purely the global `href` typing. Keep a `renderRoute` suite single-app, or give each app its OWN tsconfig program (see `/typesafety`); a quick sidestep is to probe `useMount`/`useHref` inline instead of importing the cross-app component.
 
 ## See also

package/skills/vercel/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: vercel
+description: Deploy a Rango app to Vercel Functions (Build Output API v3)
+argument-hint:
+---
+
+# Vercel deployment
+
+The `vercel` preset builds like the `node` preset (Vercel runs Node Functions, not Workers): rango owns the RSC entry, folds `process.env.NODE_ENV` for the SSR/RSC build, and after `vite build` assembles a `.vercel/output` directory (Build Output API v3) from `dist/` — a single streaming Node Function plus the static client assets.
+
+## Setup
+
+```bash
+npm install @vercel/functions
+```
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [react(), rango({ preset: "vercel" })],
+});
+```
+
+`@vercel/functions` is required: it backs the generated function launcher (`waitUntil`) and `VercelCacheStore`. The build fails with a clear error if it is missing.
+
+`vite build` produces `.vercel/output`; deploy with the Vercel CLI (`vercel deploy --prebuilt`) or via Git integration.
+
+## Function configuration
+
+Per-function knobs go under `vercel` and are written into `.vc-config.json`:
+
+```typescript
+rango({
+  preset: "vercel",
+  vercel: {
+    runtime: "nodejs22.x", // default
+    maxDuration: 30, // seconds, default
+    memory: 1024, // MB (platform default when omitted)
+    regions: ["fra1"], // pin regions (platform default when omitted)
+    functionName: "index", // the <name>.func dir + config.json route
+  },
+});
+```
+
+## Runtime Cache
+
+`VercelCacheStore` wraps the Vercel Runtime Cache. Locally (no `process.env.VERCEL`) fall back to an in-memory store so dev/preview work without the platform:
+
+```typescript
+import {
+  MemorySegmentCacheStore,
+  VercelCacheStore,
+} from "@rangojs/router/cache";
+import { getCache, waitUntil } from "@vercel/functions";
+
+const defaults = { ttl: 60, swr: 300 };
+const memoryStore = new MemorySegmentCacheStore({ defaults });
+
+function resolveCache() {
+  if (process.env.VERCEL) {
+    return {
+      store: new VercelCacheStore({
+        cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+        waitUntil,
+        defaults,
+      }),
+    };
+  }
+  return { store: memoryStore };
+}
+
+export const router = createRouter({ cache: resolveCache }).routes(/* ... */);
+```
+
+The cache factory receives `(env, ctx)`; on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`.
+
+## Host routers (multi-app)
+
+A multi-app host router deploys as a **single function** running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model). Two requirements:
+
+1. The host module exports the `HostRouter` **instance** (default export, or a named `hostRouter`/`router` export) — not a Cloudflare-style `{ fetch }` object, because rango owns the entry and calls `match()` for you.
+2. Point at the host entry (a host app has several `createRouter()` sub-apps, so auto-discovery can't pick one). rango auto-detects a lone `createHostRouter()` file; set `hostRouter` to be explicit:
+
+```typescript
+rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
+```
+
+```typescript
+// src/worker.rsc.tsx
+import { createHostRouter } from "@rangojs/router/host";
+
+export const hostRouter = createHostRouter();
+hostRouter.host(["admin.*"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
+
+export default hostRouter; // the instance
+```
+
+`{ env, ctx }` is threaded unchanged from the function to each matched sub-app's handler and its `cache(env, ctx)` factory. See the `host-router` skill for sub-app structure and routing patterns.
+
+## Tracing (custom spans)
+
+Vercel exposes tracing through OpenTelemetry. `createVercelTracing()` (from `@rangojs/router/vercel`) emits the router's `rango.*` phase spans onto the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs:
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config so
+// importing this module is what runs registerOTel(). A Rango/Vite app does NOT
+// auto-load `instrumentation.ts` like Next.js does, 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();
+
+// router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+import { tracing } from "./instrumentation.js";
+export const router = createRouter({ tracing }).routes(/* ... */);
+```
+
+`createVercelTracing(opts?)` takes `{ enabled, spans, tracerName, tracer }` — same phase set as `createCloudflareTracing` (`rango.request/middleware/action/loader/render/ssr`). Caveats: Node-runtime only (Vercel custom spans are unsupported on Edge); `registerOTel()` must run before the first request; `@vercel/otel` is what unlocks Vercel Session Tracing + Trace Drains. The deploy bundles `@vercel/otel` and its `@opentelemetry/*` peers into the function (no `node_modules` at runtime), so they must be installed. See `examples/vercel-basic` for a worked hybrid setup and the `observability` skill for the cross-platform tracing model.
+
+## Local validation without deploying
+
+`vite preview` serves the static client assets only. To preview the RSC **function**, serve the assembled `.vercel/output` behind filesystem-then-function routing — `examples/vercel-basic/scripts/preview.mjs` does this (and `pnpm preview:vercel` runs it). For a faithful deploy test (isolated filesystem, ESM, self-contained bundle), `examples/vercel-basic/scripts/smoke.mjs` serves it from a temp dir outside the repo. Both share `scripts/serve-vercel-output.mjs`.