@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7d061845

package/skills/middleware/SKILL.md

@@ -10,9 +10,6 @@ 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()`)
@@ -32,17 +29,26 @@ When the router has a `basename`, pattern-scoped `.use()` patterns are automatic
 
 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).
 
+> **Implication for auth:** route middleware cannot guard server actions. Use `router.use("/admin/*", requireAuth)` (global, scoped) for action protection, or check inside the action body. See `/server-actions` for action-side auth patterns.
+
 ```
 Request flow (with action):
-  global mw -> action executes -> route mw -> layout -> handler -> loaders
+  global mw -> action executes -> route mw -> render pass
 
 Request flow (no action):
-  global mw -> route mw -> layout -> handler -> loaders
+  global mw -> route mw -> render pass
 
 Progressive enhancement (no-JS form POST):
   global mw -> action executes -> route mw -> full page re-render
 ```
 
+The **render pass** resolves handler, layouts, parallels, and loaders together —
+it is not a handler-then-loaders sequence. Handler-first ordering is guaranteed
+only between a route handler and its child/orphan layouts and parallels (so
+`ctx.set` is visible); loaders run **concurrently** and stream their results, so
+their latency overlaps rendering rather than blocking it. See `/loader` →
+"Parallel and streaming".
+
 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
@@ -62,7 +68,7 @@ and consumer segments, even when middleware is present in the chain.
 
 ```typescript
 export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") ?? false;
+  actionId?.includes("src/actions/cart.ts#") || undefined;
 
 layout(CartLayout, () => [
   middleware(cartRenderMiddleware),
@@ -190,7 +196,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.env.DB; // D1Database
   ctx.env.KV; // KVNamespace
 
-  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
   // Continue to next middleware/handler
@@ -231,8 +237,8 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
 ```
 
 This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
-via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
-data; use RSCRouter.Vars for app-wide middleware state.
+via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use Rango.Vars for app-wide middleware state.
 
 ## Redirect with State in Middleware
 

package/skills/migrate-nextjs/SKILL.md

@@ -225,7 +225,7 @@ Loaders are Rango's live data layer. Use them when you need:
 
 - **Client-side data refresh** — `useLoader()` in client components for reactive data
 - **Per-loader caching** — opt in with `loader(MyLoader, () => [cache({ ttl: 60 })])`; loaders stay live by default
-- **Revalidation control** — `revalidate()` targets specific loaders after actions
+- **Revalidation control** — `revalidate()` targets specific segments and loaders after actions
 - **Loading skeletons** — `loading()` shows a Suspense fallback while loaders resolve
 
 ```typescript
@@ -302,7 +302,7 @@ re-rendering. This is about the segment tree, not cache invalidation:
 ```typescript
 // Re-run this layout when a blog action fires
 layout(BlogLayout, () => [
-  revalidate(({ actionId }) => actionId?.includes("updateBlog") ?? false),
+  revalidate(({ actionId }) => actionId?.includes("updateBlog") || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
 ]);
 
@@ -463,6 +463,8 @@ 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 `revalidatePath()` / `revalidateTag()` have no direct equivalent — Rango partially re-renders matched route segments (path/layout/parallel/intercept) and re-resolves their loaders, and you scope re-runs by attaching a `revalidate(({ actionId }) => ...)` rule to any segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads) and `/loader` for revalidation rule semantics.
+
 ## 8. Metadata / Head
 
 Rango uses the `Meta` handle + `<MetaTags />` client component:

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

@@ -483,6 +483,10 @@ Since Rango uses RSC server actions, all React action patterns work:
 `useActionState`, `useOptimistic`, `useTransition`, `startTransition`,
 and plain `<form action={serverAction}>`. No framework-specific hook needed.
 
+For the full guide — defining actions, validation with Zod, error handling,
+revalidation rules, file uploads, and progressive enhancement — see
+`/server-actions`.
+
 ### clientLoader / clientAction (framework mode)
 
 RR7 framework mode's `clientLoader` and `clientAction` run in the browser.
@@ -635,6 +639,7 @@ layout(<ShopLayout />, () => [
 | `useLocation().pathname`                  | `usePathname()` from `@rangojs/router/client`                                    |
 | `useSearchParams()`                       | `useSearchParams()` from `@rangojs/router/client`                                |
 | `useParams()`                             | `useParams()` from `@rangojs/router/client` (or `ctx.params` in server handlers) |
+| `useParams<T>()`                          | `useParams<T>()` — same generic annotation pattern                               |
 | `<NavLink>`                               | `<Link>` with `usePathname()` for active state                                   |
 
 ### useNavigate → useRouter

package/skills/mime-routes/SKILL.md

@@ -108,6 +108,33 @@ path.text("/api/data", () => "plain text version", { name: "dataText" }),
 Without an RSC primary, there is no `text/html` candidate — the Accept header
 picks among the response-type candidates directly.
 
+## Type Safety For Negotiated Paths
+
+`router.named-routes.gen.ts` validates route names, params, search, `href()`, and
+the `Rango.Path` type, but it does not carry response payload metadata. For MIME or
+response payload types, use one of these surfaces:
+
+- `RouteResponse<typeof patterns, "routeName">` for a specific response variant
+  by route name. This is the clearest option when several MIME variants share
+  one URL pattern.
+- `Rango.PathResponse<"/products/:id">` (ambient, no import) for global lookup by URL pattern or concrete path after the app
+  registers `typeof router.routeMap`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+`RegisteredRoutes` is what exposes the richer routeMap entries containing
+response payload metadata. Without it, URL-pattern response lookup has paths but
+no payloads, so response types resolve to `ResponseEnvelope<never>`.
+
 ## How It Works
 
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.

package/skills/observability/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: observability
+description: Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing
+argument-hint:
+---
+
+# Observability
+
+Use this when you need to understand request latency, cache decisions,
+revalidation behavior, loader overlap, or production traces.
+
+Rango exposes two 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.
+
+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.
+
+## Performance timeline
+
+Enable globally while debugging:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+});
+```
+
+Or enable for selected requests from middleware:
+
+```typescript
+middleware(async (ctx, next) => {
+  if (ctx.url.searchParams.has("debug")) {
+    ctx.debugPerformance();
+  }
+  await next();
+});
+```
+
+Call `ctx.debugPerformance()` before `await next()`. The request then prints a
+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.
+
+## Structured telemetry
+
+Use telemetry when you want durable production events rather than a one-request
+debug waterfall.
+
+```typescript
+import { createRouter, createConsoleSink } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
+```
+
+For OpenTelemetry:
+
+```typescript
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
+
+Custom sinks implement `emit(event)`:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: {
+    emit(event) {
+      myMetrics.record(event);
+    },
+  },
+});
+```
+
+Events include `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, and `revalidation.decision`.
+
+## Debugging revalidation and stale data
+
+When stale UI or unexpected partial renders are the question, use all three
+layers together:
+
+```typescript
+import { createConsoleSink, createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+  telemetry: createConsoleSink(),
+});
+```
+
+Then inspect:
+
+- `revalidation.decision` telemetry to see which segment re-ran or skipped.
+- cache spans / `cache.decision` events to see hit, miss, stale, and background
+  revalidation behavior.
+- loader spans to confirm live loaders overlap the render rather than blocking
+  first paint.
+- the `Server-Timing` header to compare local logs with browser-network timing.
+
+## 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.

package/skills/parallel/SKILL.md

@@ -8,9 +8,6 @@ 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
@@ -237,6 +234,8 @@ A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an
 
 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.
 
+`transition` is allowed in the slot allow-list, but slot-level rendering does **not** currently apply a `<ViewTransition>` wrapper — only the layout/route wraps take effect at render time. For a modal-only morph today, use an element-level React `<ViewTransition>` inside the slot's component. The reverse direction is the useful guarantee: a layout-level `transition()` fires when the layout's default outlet content changes but **not** when a `<ParallelOutlet />` mounts new content (modal opens are not subtree updates of the layout VT). See [skills/view-transitions](../view-transitions/SKILL.md) for the wrap rules and the intercept caveat.
+
 ### Two scopes for explicit `use`: shared (broadcast) and slot-local
 
 `parallel({...slots}, () => [...use])` runs the shared `use()` callback **once per slot** ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)) — items in that callback land on every slot's entry. That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`). (Slots cannot bring `middleware` or `layout` — see the allowed-types note above.)
@@ -338,7 +337,7 @@ parallel(
   () => [
     loader(CartLoader),
     // Revalidate when cart actions occur
-    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
   ]
 )
 ```
@@ -347,6 +346,13 @@ 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.
 
+A `revalidate()` callback may return a hard `boolean`, a soft
+`{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /
+`undefined`) to defer to the next revalidator. See
+[loader/SKILL.md#revalidate-return-shapes](../loader/SKILL.md#revalidate-return-shapes)
+for the full contract — it's the same across `loader()`, `path()`,
+`layout()`, `parallel()`, and `intercept()`.
+
 ### Revalidation Contracts for Parallel Dependencies
 
 Prefer named revalidation contracts shared by both the upstream producer and
@@ -355,7 +361,7 @@ the parallel consumer:
 ```typescript
 // revalidation-contracts.ts
 export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") ?? false;
+  actionId?.includes("src/actions/cart.ts#") || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -473,7 +479,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
       ]
     ),
 

package/skills/prerender/SKILL.md

@@ -11,9 +11,6 @@ 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)
@@ -361,16 +358,16 @@ Both error types propagate to the router's `onError` callback with phase
 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] 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 done, 1 skipped (120ms total)
+[rango] Pre-rendering 12 URL(s) (concurrency: 4)...
+[rango]   OK   /articles/hello            (42ms)
+[rango]   PASS /articles/remote-only      (5ms) - live fallback
+[rango]   SKIP /articles/draft-post       (3ms) - Article is a draft
+[rango] Pre-render complete: 11 done, 1 skipped (1204ms total)
+
+[rango] Rendering 3 static handler(s)...
+[rango]   OK   DocsLayout                 (28ms)
+[rango]   SKIP TocSidebar                 (1ms) - Not ready
+[rango] 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
@@ -466,9 +463,9 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 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)
+[rango]   OK   /blog/a                          (42ms)
+[rango]   PASS /blog/b                          (3ms) - live fallback
+[rango]   OK   /blog/c                          (38ms)
 ```
 
 ## Edge Cases and Constraints
@@ -640,16 +637,7 @@ At runtime, the cache-lookup middleware uses these flags:
 
 ## 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
+Before changing prerender behavior, run these tests.
 
 ### Tests to run
 
@@ -676,10 +664,3 @@ pnpm --filter @rangojs/router exec playwright test handler-first
   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