@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/skills/middleware/SKILL.md

@@ -8,6 +8,89 @@ argument-hint: [middleware-name]
 
 Middleware runs before/after route handlers using the onion model.
 
+## Execution Model
+
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
+There are two levels of middleware with different execution scopes:
+
+### Global middleware (`router.use()`)
+
+Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders.
+
+```typescript
+const router = createRouter<AppEnv>({})
+  .use(loggerMiddleware) // all routes
+  .use("/admin/*", authMiddleware) // pattern-scoped
+  .routes(urlpatterns);
+```
+
+When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
+
+### Route middleware (`middleware()` in `urls()`)
+
+Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
+
+```
+Request flow (with action):
+  global mw -> action executes -> route mw -> layout -> handler -> loaders
+
+Request flow (no action):
+  global mw -> route mw -> layout -> handler -> loaders
+
+Progressive enhancement (no-JS form POST):
+  global mw -> action executes -> route mw -> full page re-render
+```
+
+The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
+
+Revalidation is still partial. Route middleware wraps the render pass that
+does happen, but it does not force unrelated outer segments to recompute.
+If a child segment depends on data established by an outer handler/layout,
+revalidate that outer segment too, or have the child guard/reload the
+data itself.
+
+### Revalidation Contracts with Middleware-Backed Trees
+
+Middleware can establish request-level context (`ctx.set`) for segments that
+execute in the current render pass. It does not change partial revalidation
+boundaries between handler/layout/parallel segments.
+
+For shared segment data, use named revalidation contracts on both the producer
+and consumer segments, even when middleware is present in the chain.
+
+```typescript
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#") ?? false;
+
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidate(revalidateCartData), // producer reruns
+  parallel(
+    { "@cart": CartSummary },
+    () => [revalidate(revalidateCartData)], // consumer reruns
+  ),
+]);
+```
+
+You can package those contracts as importable helpers to avoid repeating
+`revalidate(...)` at each segment:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
+Route middleware is the right place for per-route concerns that affect rendering (setting context variables for handlers, adding response headers, reading cookies set by actions). It is NOT the right place for action guards -- use global middleware for that.
+
 ## Basic Middleware
 
 ```typescript

package/skills/parallel/SKILL.md

@@ -8,6 +8,9 @@ argument-hint: [@slot-name]
 
 Parallel routes render multiple components simultaneously in named slots.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Parallel Routes
 
 ```typescript
@@ -56,8 +59,21 @@ parallel({
 
 ## Reading Handler Data
 
-When a parallel is inside a route that uses `ctx.set()`, it can read that
-data via `ctx.get()`. The route handler always executes before its children.
+Parallels can read `ctx.set()` values from their parent handler or layout
+via `ctx.get()`. The handler always executes before its parallels
+(handler-first).
+
+Visibility follows tree structure:
+
+- Layout-level parallels see layout data, but not path handler data
+  (the path is a separate entry).
+- Parallels inside a path (or its orphan layouts) see both layout and
+  path handler data.
+
+This applies to full render passes. During partial action revalidation,
+only revalidated segments are recomputed. If a parallel depends on data
+set by an outer handler or layout, revalidate that outer segment too, or
+have the parallel reload/guard the data itself.
 
 ```typescript
 path("/dashboard/:id", (ctx) => {
@@ -76,6 +92,73 @@ path("/dashboard/:id", (ctx) => {
 ])
 ```
 
+## Setting Handles (Meta, Breadcrumbs)
+
+Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
+push handle data. The data is associated with the **parent** layout or route
+segment, not the parallel segment itself. This is because parallels execute
+after their parent handler and inherit its segment scope.
+
+This works well for document-level metadata — the handle data follows the
+parent's lifecycle (appears when the parent is mounted, removed when it
+unmounts).
+
+```typescript
+parallel({
+  "@meta": (ctx) => {
+    const meta = ctx.use(Meta);
+    meta({ title: "Product Detail" });
+    meta({ name: "description", content: "..." });
+    return null; // UI-less slot, only sets metadata
+  },
+  "@sidebar": (ctx) => <Sidebar />,
+})
+```
+
+Multiple parallels on the same parent can each push handle data — they all
+accumulate under the parent segment ID.
+
+### Pattern: `@meta` slot for per-route metadata overrides
+
+A dedicated `@meta` parallel slot lets routes define metadata separately from
+their handler logic. The layout sets defaults via a title template, and each
+route overrides via its own `@meta` slot. Since child segments push after
+parents and `collectMeta` uses last-wins deduplication, overrides work
+naturally.
+
+```typescript
+// Layout sets defaults
+layout((ctx) => {
+  ctx.use(Meta)({ title: { template: "%s | Store", default: "Store" } });
+  return <StoreLayout />;
+}, () => [
+  // Route with @meta override — decoupled from handler rendering
+  path("/:slug", ProductPage, { name: "product" }, () => [
+    parallel({
+      "@meta": async (ctx) => {
+        const product = await ctx.use(ProductLoader);
+        const meta = ctx.use(Meta);
+        meta({ title: product.name });
+        meta({ name: "description", content: product.description });
+        meta({
+          "script:ld+json": {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            name: product.name,
+            description: product.description,
+          },
+        });
+        return null; // UI-less slot
+      },
+    }),
+  ]),
+])
+```
+
+This keeps the route handler focused on rendering UI while metadata
+(title, description, Open Graph, JSON-LD) lives in a composable slot that
+can be added, removed, or swapped per route without touching the handler.
+
 ## Parallel Routes with Loaders
 
 Add loaders and loading states to parallel routes:
@@ -93,6 +176,65 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript
@@ -142,6 +284,45 @@ parallel(
 )
 ```
 
+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.
+
+### Revalidation Contracts for Parallel Dependencies
+
+Prefer named revalidation contracts shared by both the upstream producer and
+the parallel consumer:
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#") ?? false;
+
+layout(CartLayout, () => [
+  revalidate(revalidateCartData), // producer reruns
+  parallel(
+    { "@cart": CartSummary },
+    () => [revalidate(revalidateCartData)], // consumer reruns
+  ),
+]);
+```
+
+If the slot consumes multiple upstream domains, compose the contracts on both
+segments.
+
+Handoff helper style also works:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
 ## Named Outlets
 
 Use `ParallelOutlet` to render slots in layouts:

package/skills/prerender/SKILL.md

@@ -11,6 +11,9 @@ deserialization path, same segment system. The worker handles every request --
 there are NO static .html or .rsc files served from assets. The worker reads
 pre-computed Flight payloads instead of executing handler code.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## API: Prerender
 
 ### Static Route (no params)
@@ -69,13 +72,14 @@ export const ProductPage = Prerender(
 
 Controls whether the handler stays in the RSC server bundle after build:
 
-|                | `passthrough: false` (default)          | `passthrough: true`                     |
-| -------------- | --------------------------------------- | --------------------------------------- |
-| Known params   | Served from pre-rendered Flight payload | Served from pre-rendered Flight payload |
-| Unknown params | Handler evicted, no live fallback       | Handler runs live at request time       |
-| Bundle size    | Handler code + imports removed          | Handler code kept in RSC bundle         |
-| `revalidate()` | Not allowed (handler gone)              | Allowed (handler can re-render)         |
-| `loading()`    | Ignored (segments fully resolved)       | Works for live fallback renders         |
+|                     | `passthrough: false` (default)          | `passthrough: true`                     |
+| ------------------- | --------------------------------------- | --------------------------------------- |
+| Known params        | Served from pre-rendered Flight payload | Served from pre-rendered Flight payload |
+| Unknown params      | Handler evicted, no live fallback       | Handler runs live at request time       |
+| `ctx.passthrough()` | Throws (not allowed)                    | Skips artifact, defers to live fallback |
+| Bundle size         | Handler code + imports removed          | Handler code kept in RSC bundle         |
+| `revalidate()`      | Not allowed (handler gone)              | Allowed (handler can re-render)         |
+| `loading()`         | Ignored (segments fully resolved)       | Works for live fallback renders         |
 
 ### When to use passthrough
 
@@ -98,6 +102,7 @@ Handlers receive `BuildContext` at build time, a subset of the runtime `HandlerC
 ```typescript
 interface BuildContext<TParams> {
   params: TParams; // From getParams
+  build: true; // Always true at build time
   use: <T>(handle: Handle<T>) => (data: T) => void; // Push handle data
   url: URL; // Synthetic URL from pattern + params
   pathname: string; // Pathname from synthetic URL
@@ -105,6 +110,12 @@ interface BuildContext<TParams> {
   set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
   get(key: string): any; // Read context variable (string key)
   get<T>(contextVar: ContextVar<T>): T | undefined; // Read typed context variable
+  reverse(
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ): string; // URL generation
+  passthrough(): PrerenderPassthroughResult; // Skip local artifact (passthrough routes only)
   // NOT available: req, headers, cookies, env (throws descriptive errors)
 }
 ```
@@ -130,6 +141,16 @@ All items inside the path's use() callback (child layouts, parallels) also recei
 `BuildContext` during pre-rendering. Loaders are the exception -- they run at
 request time with full server context.
 
+This is one reason prerender is a good fit for handler-first composition:
+the handler and its child layouts/parallels participate in the same full
+render pass, so data set with `ctx.set()` is available downstream via
+`ctx.get()`.
+
+At runtime, partial action revalidation follows a narrower rule: only
+revalidated segments are recomputed. If a child segment depends on data
+established by an outer handler/layout, that outer segment must also be
+revalidated, or the child must load/guard the data independently.
+
 ## Supported Export Patterns
 
 All of the following are equivalent and fully supported by the Vite transform:
@@ -218,11 +239,25 @@ path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
 | `loading()`    | Ignored without passthrough. Works for live fallback with passthrough.                                                                                                                                                                                              |
 | `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when()` conditions are skipped at build time (all intercepts are pre-rendered unconditionally). |
 
+When passthrough revalidation is enabled, remember that revalidation is
+still partial: opting a child segment into revalidation does not
+implicitly re-run outer prerender-derived handlers/layouts.
+
 ## Dev Mode
 
-In dev mode, `Prerender` is a normal handler. Routes render live
-on every request. No stubbing, no build-time pre-rendering. The handler runs
-with full runtime context (not BuildContext).
+In dev mode there is no production-style prerender build pass and no handler
+stubbing.
+
+**Node.js dev server** — `Prerender` acts as a normal handler. Routes render
+live on every request with full runtime context (`ctx.build === false`).
+
+**Non-Node runtimes (Cloudflare workerd, Deno workers)** — Handlers that
+depend on Node APIs (e.g. `node:fs`) cannot run in-process. The Vite plugin
+can intercept these requests and resolve them via the `/__rsc_prerender`
+endpoint, which runs `matchForPrerender` in a Node.js temp server. In this
+path the handler receives `BuildContext` (`ctx.build === true`) and segments
+are resolved identically to production prerendering, then served on-demand.
+This only applies when `__PRERENDER_DEV_URL` is set by the plugin.
 
 ## Storage Layout
 
@@ -288,8 +323,10 @@ export const TocSidebar = Static(() => {
 
 ### Error behavior at build time
 
-| Throw type                  | Effect                                                |
+| Handler outcome             | Effect                                                |
 | --------------------------- | ----------------------------------------------------- |
+| JSX / `null`                | Normal prerender entry, log OK                        |
+| `return ctx.passthrough()`  | Skip entry, log PASS, continue (passthrough routes)   |
 | `throw new Skip("reason")`  | Skip entry, log SKIP, continue with remaining entries |
 | `throw new Error("reason")` | Log FAIL, stop ALL pre-rendering, fail the build      |
 
@@ -303,21 +340,108 @@ The build produces per-URL timing logs:
 ```
 [rsc-router] Pre-rendering 12 URL(s) (concurrency: 4)...
 [rsc-router]   OK   /articles/hello            (42ms)
+[rsc-router]   PASS /articles/remote-only      (5ms) - live fallback
 [rsc-router]   SKIP /articles/draft-post       (3ms) - Article is a draft
-[rsc-router]   FAIL /articles/broken           (15ms) - DB connection refused
-[rsc-router] Pre-render complete: 10 ok, 1 skipped, 1 failed (1204ms total)
+[rsc-router] Pre-render complete: 11 done, 1 skipped (1204ms total)
 
 [rsc-router] Rendering 3 static handler(s)...
 [rsc-router]   OK   DocsLayout                 (28ms)
 [rsc-router]   SKIP TocSidebar                 (1ms) - Not ready
-[rsc-router] Static render complete: 2 ok, 1 skipped (120ms total)
+[rsc-router] Static render complete: 2 done, 1 skipped (120ms total)
 ```
 
+A `FAIL` line is logged per-URL when a handler throws a non-Skip error. The
+error is re-thrown immediately, so no summary line is printed — the build
+stops at the first failure.
+
 ### Dev mode behavior
 
-In dev mode, `Skip` is a regular Error. Throwing it in a handler will surface
-as a runtime error (no build-time skip logic exists in dev). This matches the
-general dev-mode principle where Prerender handlers run live per request.
+**Node.js dev server** — `Skip` behaves like a regular runtime error because
+the handler runs live with `ctx.build === false`.
+
+**Non-Node runtimes using `/__rsc_prerender`** — `Skip` participates in the
+on-demand prerender path, so build-style skip logic does run for that request.
+The dev prerender endpoint treats it like a prerender miss and the request
+falls back according to normal dev/runtime behavior.
+
+## Per-Param Passthrough with ctx.passthrough()
+
+On `{ passthrough: true }` routes, a handler can return `ctx.passthrough()`
+to skip writing a local prerender artifact for a specific param set. At
+runtime, the missing entry falls through to the live handler.
+
+```typescript
+export const BlogPost = Prerender(
+  async () => [{ slug: "a" }, { slug: "b" }, { slug: "c" }],
+  async (ctx) => {
+    const post = await getPost(ctx.params.slug);
+    if (!post) return ctx.passthrough();
+    return <article>{post.content}</article>;
+  },
+  { passthrough: true },
+);
+```
+
+### Semantics
+
+- JSX or `null` from the handler produces a normal prerender entry.
+- `ctx.passthrough()` returns a sentinel that signals "no local artifact".
+  The build skips the manifest entry for that param set.
+- `ctx.passthrough()` on a non-passthrough route throws an invariant error.
+- `ctx.passthrough()` at runtime (`ctx.build === false`) also throws.
+  It is a build-time-only control flow.
+- `getParams()` still enumerates the param set; the handler decides per-param
+  whether to produce an artifact or defer to runtime.
+
+### Difference from Skip
+
+| Mechanism           | Effect on build        | Runtime behavior                                     |
+| ------------------- | ---------------------- | ---------------------------------------------------- |
+| `throw new Skip()`  | Skips entry, logs SKIP | No artifact, no live fallback unless passthrough     |
+| `ctx.passthrough()` | Skips entry, logs PASS | Always defers to live handler (requires passthrough) |
+
+Use `ctx.passthrough()` when you want the handler to run live at request time
+for specific params. Use `Skip` when you want to exclude params entirely.
+
+### Use case: Remote storage
+
+`ctx.passthrough()` enables a pattern where build-time data is stored in a
+remote KV store instead of the local prerender manifest. The handler
+pre-computes data during `getParams`, pushes it to KV, then calls
+`ctx.passthrough()` so the local build skips the artifact. At runtime,
+the live handler reads from KV:
+
+```typescript
+export const Product = Prerender(
+  async () => {
+    const products = await db.getFeaturedProducts();
+    // Pre-compute and store in remote KV during build
+    for (const p of products) {
+      await kv.put(`product:${p.id}`, await renderProduct(p));
+    }
+    return products.map(p => ({ id: p.id }));
+  },
+  async (ctx) => {
+    // At build time: skip local artifact, data is in KV
+    if (ctx.build) return ctx.passthrough();
+    // At runtime: read from KV
+    const cached = await kv.get(`product:${ctx.params.id}`);
+    if (cached) return cached;
+    return <Product data={await db.getProduct(ctx.params.id)} />;
+  },
+  { passthrough: true },
+);
+```
+
+### Build logs
+
+Passthrough entries are logged distinctly:
+
+```
+[rsc-router]   OK   /blog/a                          (42ms)
+[rsc-router]   PASS /blog/b                          (3ms) - live fallback
+[rsc-router]   OK   /blog/c                          (38ms)
+```
 
 ## Edge Cases and Constraints
 
@@ -397,10 +521,10 @@ export const guidesPatterns = urls(({ path }) => [
 ]);
 
 // urls.tsx
-import { urls, include } from "@rangojs/router";
+import { urls } from "@rangojs/router";
 import { guidesPatterns } from "./pages/guides.js";
 
-export const urlpatterns = urls(({ path }) => [
+export const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/guides", guidesPatterns, { name: "guides" }),
 ]);
@@ -471,3 +595,49 @@ At runtime, the cache-lookup middleware uses these flags:
 - `pr + hit` -- serve pre-rendered Flight payload
 - `pr + pt + miss` -- fall through to live handler (handler kept in bundle)
 - `pr + miss` (no pt) -- fall through (handler stubbed, no live render)
+
+## Contributor Checklist
+
+Before changing prerender behavior, read these docs and run these tests.
+
+### Docs to re-read
+
+- [Prerender API design](../../docs/prerender-api-design.md) -- canonical
+  architecture: build-time flow, runtime flow, storage, passthrough, intercept
+- [Execution model](../../docs/internal/execution-model.md) -- handler-first
+  ordering, middleware scope, context visibility rules
+- [Semantic change checklist](../../docs/internal/semantic-change-checklist.md)
+  -- gate for any change to execution semantics
+
+### Tests to run
+
+```bash
+# Core prerender e2e (passthrough, eviction, loaders, sub-use, intercept)
+pnpm --filter @rangojs/router exec playwright test prerender
+
+# Prerender-specific unit test
+pnpm --filter @rangojs/router run test:unit -- prerender-passthrough
+
+# Semantic matrix (prerender rows cover intercept + ctx propagation)
+pnpm --filter @rangojs/router exec playwright test semantic-matrix
+
+# Handler-first (ctx.set/get visibility with prerender handlers)
+pnpm --filter @rangojs/router exec playwright test handler-first
+```
+
+### Dev-only vs build-parity
+
+- Prerender e2e tests run against a real production build by default (the
+  fixture builds the test app). Dev-mode prerender behavior is tested via
+  `/__rsc_prerender` endpoint tests and node.js dev-server fallback.
+- Log-based assertions (build output lines, debug cache logs) are inherently
+  dev/build-only and do not need a production counterpart.
+- Behavioral assertions (rendered content, loader freshness, passthrough
+  fallback, intercept variant selection) must work in the production build.
+
+## Maintenance References
+
+- [Stability next steps plan](../../docs/internal/stability-next-steps-plan.md)
+  -- completed parity and cleanup pass (reference for decisions made)
+- [Test quality baseline](../../docs/internal/test-quality-baseline.md) --
+  measured test inventory, sleep debt, production coverage gaps

package/skills/rango/SKILL.md

@@ -32,7 +32,6 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
 | `/mime-routes`     | Content negotiation — same URL, different response types via Accept header |
 | `/fonts`           | Load web fonts with preload hints                                          |
-| `/testing`         | Unit test route trees with `buildRouteTree()`                              |
 
 ## Quick Start