@rangojs/router 0.0.0-experimental.105 → 0.0.0-experimental.106

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.105",
+  version: "0.0.0-experimental.106",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.105",
+  "version": "0.0.0-experimental.106",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -9,6 +9,98 @@ argument-hint:
 Both mechanisms share the same backing store, cache profiles, and tag-based
 invalidation. They differ in scope, cache key, execution model, and runtime control.
 
+## Two axes — do not conflate
+
+Everything on this page is **axis 1: stored-value freshness** — _is a cached
+value still good?_ There is a second, orthogonal axis it is easy to mistake for
+caching:
+
+1. **Stored-value freshness** — _is a cached value still good?_
+   → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
+   Entries are coupled across the one store by **tags** (`revalidateTag`).
+2. **Client-update selection** — _should this segment re-run and stream to the
+   client on this navigation/action?_
+   → `revalidate()`. Covered in `/loader` and `/route`, **not here**.
+
+They are orthogonal and compose: a segment selected by `revalidate()` still
+consults its cache (hit → no recompute); a cache bust does **not** force a client
+update, and `revalidate()` never reads, writes, or expires a cached value. If you
+know React Router, `revalidate()` is `shouldRevalidate`, not `Cache-Control`. See
+`/rango` → "Coming from another framework" for the cross-framework mapping.
+
+## Correctness & invalidation
+
+rango's caches are built so a hit can't serve wrong or stale-shaped data. These
+guarantees are mostly automatic — worth knowing so you don't reimplement
+protection the framework already gives you (or assume one it deliberately
+doesn't).
+
+### Cross-deploy safety: version-segmented store keys
+
+`CFCacheStore` prefixes every **physical** store key (the CF Cache API URL and
+the KV key) with the build version — auto-generated from the
+`@rangojs/router:version` virtual module, overridable via the store's `version`
+option. A new deploy reads under a new prefix, so it can **never** read a
+previous build's entries: no cross-deploy shape drift, and no dead client-chunk
+references baked into cached RSC.
+
+The tradeoff to know: **loader/data caches use the same store**, so they're
+version-segmented too. Every deploy is therefore a _cold data cache_ — SWR can't
+soften it, because no stale entry exists under the new key. For high-traffic,
+frequently-deploying, data-bound apps that's a deploy-time origin warm-up. Decide
+deliberately: accept it (correctness over hit-rate), or split the policy — let
+the render/edge cache auto-version while a separate data store gets a stable
+`version` so its entries survive deploys. (Per-process stores like
+`MemorySegmentCacheStore` are cold on every restart anyway; this matters for
+persistent stores.) See `/caching` for store setup.
+
+### Client cache: forward/back is mutation-aware
+
+The browser keeps a history (forward/back) cache of rendered segments. Any
+client-side mutation (a server action) marks those entries **stale** and
+broadcasts it to other tabs. On back/forward (popstate) the router looks up the
+entry, sees it's stale, and revalidates — so your `revalidate()` predicates re-run
+and the segment refreshes (SWR: the stale view paints instantly, fresh data
+streams in). It's the client-side analog of the server-cache correctness problem,
+solved on the partial-render axis.
+
+### Request-scoped data: the `cache: false` taint
+
+`createVar({ cache: false })` (or a `ctx.set(var, v, { cache: false })` write)
+taints a value as request-scoped; reading it **directly** with `ctx.get()` inside
+a `cache()` boundary throws — the guard against the catastrophic "serve user A's
+data to user B" bug. The guarantee is precise and intentionally narrow — see
+"Context Variable Cache Safety" below for exactly what it does and does not catch.
+
+## Stale-while-revalidate
+
+SWR is a first-class cache behavior when the backing store supports it: while an
+entry is within its SWR window the cache serves the **stale value instantly** and
+refreshes it in the **background** (`waitUntil`), so users never wait on a
+recompute for a merely-aging entry.
+
+- **`"use cache"`** resolves to the `default` profile `{ ttl: 900, swr: 1800 }`,
+  so function/component caching gets a 30-minute SWR window **out of the box**.
+  Tune or add profiles via `createRouter({ cacheProfiles: { … } })`
+  (`"use cache: short"` → the `short` profile).
+- **`cache()` DSL and loader caches** take an explicit `swr` in seconds (or
+  inherit `store.defaults.swr`): `cache({ ttl: 60, swr: 300 })` → fresh ≤60s,
+  stale-served 60–360s, miss after 360s in stores that implement SWR for that
+  layer.
+- **Client forward/back** is SWR after a mutation — see "Correctness &
+  invalidation" → Client cache.
+- **Edge / document layer** uses the HTTP `stale-while-revalidate` directive; see
+  `/document-cache`.
+
+SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
+has no stale entry to serve (see version-segmented store keys above).
+
+Store support is layer-specific. `CFCacheStore` supports SWR for segment,
+document/response, and `"use cache"` item entries. `MemorySegmentCacheStore`
+supports SWR for response and `"use cache"` item entries, but its route-segment
+entries expire at TTL and never background-revalidate. Use the memory store for
+local/dev behavior, not as proof that segment SWR is active.
+
 ## Key Differences
 
 |                      | `cache()` DSL                                         | `"use cache"` directive                            |
@@ -18,7 +110,7 @@ invalidation. They differ in scope, cache key, execution model, and runtime cont
 | **Cache key**        | Request type + pathname + params (+ optional custom)  | Function identity + serialized non-tainted args    |
 | **Execution on hit** | All-or-nothing: entire handler skipped                | Partial: function body skipped, calling code runs  |
 | **Runtime control**  | `condition` to disable, custom `key` function         | None — if the directive is present, it caches      |
-| **Side effects**     | No guards needed — handler doesn't run on hit         | `ctx.header()`, `ctx.set()`, etc. throw at runtime |
+| **Side effects**     | Response side effects throw inside the boundary       | `ctx.header()`, `ctx.set()`, etc. throw at runtime |
 | **Handle data**      | Captured and replayed                                 | Captured and replayed                              |
 | **Loaders**          | Always fresh — excluded from cache, opt-in per loader | Can be used inside loaders                         |
 | **Nesting**          | Nest `cache()` boundaries with different TTLs         | Compose by calling cached functions from uncached  |
@@ -144,13 +236,38 @@ On cache hit for the route, the handler doesn't run and `getProductData` is neve
 called. On cache miss, the handler runs and `getProductData` may itself return a
 cached value from a previous call with the same slug.
 
+### Nesting rule: the outer window bounds the inner
+
+A cache's window bounds everything rendered inside it (loaders excepted). An
+inner shorter TTL only takes effect when the **enclosing** cache recomputes — it
+does **not** keep a value fresher than its parent:
+
+- Outer `cache()` **fresh hit** → the subtree is served from stored RSC, so inner
+  `"use cache"` functions are **not consulted** (frozen at the outer's age — no
+  code inside the boundary runs on a hit).
+- Outer **miss / SWR revalidation** → inner caches are consulted, each per its own
+  ttl/swr. With SWR on the outer, a stale subtree serves instantly and refreshes
+  in the background, so under traffic it keeps refreshing rather than rotting to
+  the worst case.
+- **Loaders are the exception** — excluded from the segment cache, re-resolved
+  live even on an outer hit.
+
+So `"use cache: short"` (60s) inside `cache({ ttl: 600 })` yields ~600s freshness
+on hits, **not** 60s. This is not a bug: setting `cache({ ttl: 600 })` declares
+"this subtree may be ~600s stale." **If a value must be fresher than its
+enclosing segment, put it in a loader** (always live). `debugPerformance` prints
+cache hits per layer, so the actual per-request behavior is observable.
+
 ## Headers and Cookies
 
 Neither mechanism caches response headers or cookies.
 
-- **cache()**: Headers set by handlers are naturally absent on hit because no
-  handler runs. If you need headers on every response, set them in middleware
-  (which runs before cache lookup).
+- **cache()**: Response-level side effects throw inside the cache boundary even
+  on a miss: `ctx.header()`, `ctx.setCookie()`, `ctx.deleteCookie()`,
+  `ctx.setStatus()`, `ctx.onResponse()`, and direct `ctx.headers` mutation. On a
+  hit the handler would be skipped, so allowing the write on a miss would produce
+  inconsistent responses. If you need headers or cookies on every response, set
+  them in middleware or a live segment outside the cache boundary.
 - **"use cache"**: cookies() and headers() throw inside the cached function
   (both reads and writes). ctx.header() also throws. Move them outside.
 
@@ -165,8 +282,9 @@ middleware(async (ctx, next) => {
 ## Context Variable Cache Safety
 
 Context variables created with `createVar()` are cacheable by default and can
-be read freely inside `cache()` and `"use cache"` scopes. Non-cacheable vars
-throw at read time to prevent request-specific data from being captured.
+be read freely inside cached scopes. A non-cacheable var throws when read
+**directly** with `ctx.get()` inside a `cache()` boundary — where the value would
+otherwise be serialized into the stored segment.
 
 There are two ways to mark a value as non-cacheable:
 
@@ -181,19 +299,65 @@ ctx.set(Theme, derivedTheme, { cache: false });
 "Least cacheable wins": if either the var definition or the `ctx.set()` call
 specifies `cache: false`, the value is non-cacheable.
 
-**Behavior inside cache scopes:**
+**Behavior inside a `cache()` boundary:**
 
-| Operation                           | Inside `cache()` / `"use cache"` |
-| ----------------------------------- | -------------------------------- |
-| `ctx.get(cacheableVar)`             | Allowed                          |
-| `ctx.get(nonCacheableVar)`          | Throws                           |
-| `ctx.set(var, value)` (cacheable)   | Allowed                          |
-| `ctx.header()`, `ctx.cookie()`, etc | Throws (response side effects)   |
+| Operation                         | Inside a `cache()` boundary                        |
+| --------------------------------- | -------------------------------------------------- |
+| `ctx.get(cacheableVar)`           | Allowed                                            |
+| `ctx.get(nonCacheableVar)`        | Throws (would be baked in)                         |
+| `ctx.set(var, value)` (cacheable) | Allowed                                            |
+| `ctx.header()` / cookie writes    | Throws (response side effect would be lost on hit) |
+
+(Inside a `"use cache"` function the scoping differs: `ctx.set`, `ctx.header()`,
+`cookies()`, and `headers()` **throw** via the cache-exec guard. Inside
+`cache()`, response side effects throw via the cache-boundary guard, while the
+`ctx.get(nonCacheableVar)` taint check above is tied to the `cache()` boundary —
+see "Headers and Cookies" and the precise guarantee below.)
 
 Write is dumb — `ctx.set()` stores the cache metadata but does not enforce.
 Enforcement happens at read time (`ctx.get()`), where ALS detects the cache
 scope and rejects non-cacheable reads.
 
+### The guarantee is precise — a direct read inside `cache()`, not propagating
+
+The guard fires on a **direct** `ctx.get(taintedVar)` **inside a `cache()`
+boundary** (the scope `isInsideCacheScope` detects). The taint lives on the
+variable; a value **derived** from it and read **outside** the boundary is not
+tracked:
+
+```typescript
+// CAUGHT — direct read of a tainted var inside a cache() boundary
+cache({ ttl: 60 }, () => [
+  path("/dashboard", (ctx) => {
+    const user = ctx.get(User); // throws: non-cacheable read inside cache()
+    return <Dashboard user={user} />;
+  }, { name: "dashboard" }),
+]);
+
+// NOT CAUGHT — read outside the boundary, derived value cached
+layout((ctx) => {
+  const name = ctx.get(User).name; // allowed — this layout is not cached
+  ctx.set(UserName, name); // now a plain (cacheable) string
+  return <Outlet />;
+}, () => [
+  cache({ ttl: 60 }, () => [
+    // a child reads ctx.get(UserName) and silently caches user-derived data
+  ]),
+]);
+```
+
+So do **not** read this as "you can't cache user data" — that overstates it and
+breeds the false confidence that makes the derived leak _more_ likely. The guard
+is deliberately non-propagating (propagation would cost a wrapper per derivation
+on the hot path), and it is scoped to the `cache()` segment boundary — `"use
+cache"` functions guard request data differently (tainted `ctx`/`env`/`req` args
+are excluded from the cache key, and `cookies()` / `headers()` throw inside them;
+see "Headers and Cookies"). The pattern that stays safe is also the natural one:
+**read tainted context at the point of use, in the path that needs it (a loader or
+live segment) — never extract user data into a plain value and cache that.**
+Loaders are exempt because they run outside the cache scope and resolve fresh
+every request.
+
 ## Loaders Are Always Fresh
 
 Loaders are **never cached** by route-level `cache()`. Even on a full cache hit

package/skills/caching/SKILL.md

@@ -245,7 +245,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
       loader(ProductLoader, () => [cache({ ttl: 120 })]),
       loader(CartLoader, () => [
-        revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
       ]),
     ]),
   ]),

package/skills/composability/SKILL.md

@@ -55,7 +55,9 @@ import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/
 // Shared caching configuration
 const withCaching = () => [
   cache({ ttl: 600_000 }),
-  revalidate(({ actionId }) => !!actionId),
+  // Defer on navigation (|| undefined) so each route keeps its own param/search
+  // revalidation default; only force a re-run when an action ran.
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
 ];
 
 // Shared loading and error handling
@@ -71,6 +73,29 @@ const withAuth = () => [
 ];
 ```
 
+> **Factories compose logic, not just values.** A `revalidate()` predicate in a
+> shared factory applies its logic to _every_ route that composes it, so a
+> footgun here is amplified across the app. Two rules:
+>
+> 1. Use `|| undefined` (defer), not `?? false` (hard short-circuit), in shared
+>    predicates — a hard `false` ends the chain and overrides each consuming
+>    route's own default, and a downstream revalidator never runs. See `/loader`
+>    → "`|| undefined` (defer) vs `?? false` (hard)".
+> 2. Match actions with `ctx.isAction(Action)`, not an inline
+>    `actionId.includes("…")` buried in a factory: it resolves the action from an
+>    imported reference, so a rename is a compile error in one place instead of
+>    silent drift across every consumer.
+>
+> Remember the axis: a factory's `revalidate()` controls client-update
+> selection, while its `cache()` controls stored-value freshness. They are
+> independent even when bundled in the same factory (`/cache-guide` → "Two axes").
+
+> **Keep factories small and intention-named.** The anti-pattern that kills
+> readability is over-bundling — a `withDefaults()` that secretly adds five
+> things — and factory-of-factories nesting (leaning on `.flat(3)`). Surprising
+> config stays inline; extract only the boring, repeated parts; compose by
+> _naming concerns_ (`withAuth()`, `withCaching()`), not by hiding them.
+
 ## Using Factories in Routes
 
 Place factory calls inside `path()` or `layout()` use callbacks. The returned arrays are flattened automatically (up to 3 levels):
@@ -107,7 +132,7 @@ import { authMiddleware } from "./middleware/auth";
 
 export const withPublicDefaults = () => [
   cache({ ttl: 300 }),
-  revalidate(({ actionId }) => !!actionId),
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
 ];
 
 export const withProtectedDefaults = () => [

package/skills/intercept/SKILL.md

@@ -8,9 +8,6 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Basic Intercept
 
 ```typescript
@@ -111,7 +108,7 @@ consumer when they share `ctx.set()` data:
 
 ```typescript
 export const revalidateProductShell = ({ actionId }) =>
-  actionId?.includes("src/actions/product.ts#") ?? false;
+  actionId?.includes("src/actions/product.ts#") || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns

package/skills/layout/SKILL.md

@@ -8,9 +8,6 @@ argument-hint: [component]
 
 Layouts wrap child routes and persist during navigation within their scope.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Basic Layout
 
 ```typescript
@@ -206,7 +203,7 @@ layout(<ShopLayout />, () => [
 
 // Or revalidate based on conditions
 layout(<CartLayout />, () => [
-  revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+  revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
 
   path("/cart", CartPage, { name: "cart" }),
 ])
@@ -225,7 +222,7 @@ them on both producer and consumer segments:
 ```typescript
 // revalidation-contracts.ts
 export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#addToCart") ?? false;
+  actionId?.includes("src/actions/cart.ts#addToCart") || undefined;
 ```
 
 ```typescript
@@ -247,7 +244,7 @@ You can also package them as importable handoff helpers:
 import { revalidate } from "@rangojs/router";
 
 export const revalidateAuthData = ({ actionId }) =>
-  actionId?.includes("src/actions/auth.ts#") ?? false;
+  actionId?.includes("src/actions/auth.ts#") || undefined;
 export const revalidateAuth = () => [revalidate(revalidateAuthData)];
 ```
 
@@ -294,7 +291,7 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   }, () => [
     // Layout loaders
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
     ]),
 
     // Parallel routes

package/skills/loader/SKILL.md

@@ -244,15 +244,23 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
     revalidate(() => false), // Never revalidate
   ]),
 
-  // Loader that revalidates after cart actions
+  // Loader that revalidates after cart actions (defer otherwise — keeps the
+  // permissive loader defaults for navigation and other actions intact)
   loader(CartLoader, () => [
-    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
   ]),
 ]);
 ```
 
 ### `revalidate()` return shapes
 
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether a segment (here, a loader) re-runs and streams to the
+> client on a navigation or action — never whether a cached value is stale. The
+> cache decides hit/miss/ttl/swr independently and never reads `revalidate()`.
+> Caching a loader is a separate, opt-in step (`loader(Fn, () => [cache({...})])`).
+> See `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
 A `revalidate(fn)` callback can return one of four shapes. The chain
 processes revalidators in order; each call's return controls how the
 chain continues:
@@ -282,6 +290,58 @@ revalidate(() => null); // explicit defer
 If every revalidator on a segment defers, the segment-type default
 (e.g. params-changed for routes, `false` for parallels) is used.
 
+#### `|| undefined` (defer) vs `?? false` (hard) — pick deliberately
+
+A boolean return — including `false` — is a **hard** decision: it short-circuits
+the chain and overrides the segment default. `undefined` **defers** to the
+running suggestion / segment default. They are not interchangeable:
+
+```typescript
+// Defer: "revalidate on match, otherwise let the default/downstream decide."
+revalidate(({ actionId }) => actionId?.includes("Cart") || undefined);
+
+// Hard: "revalidate ONLY on match, suppress everything else."
+revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
+```
+
+This matters most for loaders, whose defaults are permissive: a loader defaults
+to revalidating on **any** action (`POST`) and on **param/search changes**
+during navigation. So `?? false` on a loader silently suppresses both — the
+loader will not refetch when you navigate to a different `:id`. Use
+`|| undefined` when you want to _add_ a revalidation signal on top of the
+sensible defaults, and reserve `?? false` for the rare case where you genuinely
+want the loader to refetch on nothing but your matched action.
+
+When **composing multiple revalidators** on one segment (see below), defer is
+mandatory: the first hard `?? false` ends the chain and the later contracts
+never run.
+
+#### Matching actions: `ctx.isAction()`
+
+To revalidate after specific server actions, match them by **reference** with
+`ctx.isAction()` rather than hand-written `actionId` substrings. A rename or
+moved file then becomes a type error instead of silently failing to match:
+
+```typescript
+import { addToCart, removeFromCart } from "../actions/cart";
+import * as CartActions from "../actions/cart";
+
+loader(CartLoader, () => [
+  revalidate((ctx) => ctx.isAction(addToCart) || undefined), // one action
+]);
+revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
+revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+```
+
+`isAction()` is a method on the revalidate predicate's **context argument** —
+there is no standalone `isAction` import; you always reach it through the callback
+parameter (`revalidate((ctx) => ctx.isAction(...))`). It returns a raw boolean, so
+pair it with `|| undefined` for the usual "revalidate on match, else defer"
+intent. It returns `false` on plain navigation and on non-matches, and resolves
+the reference the same way the router derives `actionId` (`$id` in production,
+`$$id` in dev), so it matches in both modes. The raw `actionId` string stays
+available on the same context as an escape hatch.
+
 ### Revalidation Contracts for Loader Dependencies
 
 If a loader reads `ctx.get()` data produced by an outer handler/layout, share
@@ -289,8 +349,12 @@ the same named revalidation contract across producer and consumer segments.
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateAccountScope = ({ actionId }) =>
-  actionId?.includes("src/actions/account.ts#") ?? false;
+import * as AccountActions from "./actions/account";
+
+// Match by reference with ctx.isAction() (rename-safe), and defer (|| undefined)
+// so these contracts compose — a hard `false` would short-circuit the rest.
+export const revalidateAccountScope = (ctx) =>
+  ctx.isAction(AccountActions) || undefined;
 
 layout(AccountLayout, () => [
   revalidate(revalidateAccountScope), // producer reruns
@@ -333,6 +397,64 @@ follows the same rule: at build time, loaders are skipped entirely (there is no
 real request context), and at runtime the worker resolves them fresh against
 the live database.
 
+### Parallel and streaming — latency overlaps first paint
+
+Loaders do not block the page. As the render pass begins — the pass that route
+middleware wraps, so loaders run right after middleware, not in a later
+phase — every matched loader is kicked off **concurrently** (their promises start in the
+same tick), and each result is **streamed** to the client as its own RSC Flight
+chunk rather than awaited up front. Pair a loader with `loading()` (or a
+client `<Suspense>`) and the shell paints immediately while the data streams in.
+
+This is why **"cached UI still pays full data latency" is the wrong intuition**:
+on a `cache()` hit the UI segments stream instantly from cache while the live
+loaders resolve fresh **in parallel** — data latency _overlaps_ first paint
+instead of being added on top of it. (Without a `loading()` / `<Suspense>`
+boundary a parallel loader blocks its parent, so add one to keep the overlap.)
+
+If you come from a framework where the loader is a blocking step that runs
+before the response is built, this is the shift to internalize: here the
+response starts streaming first and loader data fills in.
+
+### See it: `debugPerformance`
+
+Turn on the per-request performance timeline early — it is the fastest way to
+confirm loaders overlap rather than serialize, and to find the real bottleneck
+locally instead of guessing:
+
+```typescript
+const router = createRouter({ document: Document, debugPerformance: true });
+```
+
+Or enable it per-request from middleware (e.g. only when `?debug` is present) by
+calling `ctx.debugPerformance()` **before** `await next()`. Each HTML request
+then prints a shared-axis waterfall (and emits a `Server-Timing` header):
+
+```
+[RSC Perf] GET /product/widget (24.53ms)
+start      dur  span                          timeline
+ 0.08ms  3.20ms  route-matching               |#####...................................|
+ 3.40ms  8.70ms  ssr-render-html              |.....##############.....................|
+ 3.42ms 11.90ms  loader:…#ProductLoader       |.....###################................|
+ 3.45ms 11.40ms  loader:…#ReviewsLoader        |.....##################.................|
+ 0.00ms 24.53ms  handler:total                |########################################|
+```
+
+How to read it:
+
+- **Humans:** scan the `#` bars on the shared axis. Bars that start at the same
+  offset and run side by side are executing **in parallel** — loaders should
+  overlap `ssr-render-html` / `render:total`, not sit alone to the right of
+  everything. A lone `loader:*` bar past the render bar is serialized latency to
+  chase. `handler:total` is the whole request; `render:total` is the render pass.
+- **LLMs / programmatic:** read each row as `{ start, dur, label }`. A loader
+  overlaps paint when its `[start, start+dur]` interval intersects
+  `render:total` / `ssr-render-html`. Flag a regression when a `loader:*`
+  interval is **disjoint from and starts after** `render:total`, or when its
+  `dur` approaches `handler:total` — that loader is on the critical path instead
+  of overlapping it. Two `loader:*` rows with near-equal `start` confirm
+  parallel execution.
+
 ### Opting a Loader into Caching
 
 To cache a specific loader's data, attach a `cache()` child:
@@ -648,7 +770,7 @@ export const CartLoader = createLoader(async (ctx) => {
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
     ]),
 
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [

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()`)
@@ -36,15 +33,22 @@ Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wra
 
 ```
 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
@@ -64,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),

package/skills/migrate-nextjs/SKILL.md

@@ -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" }),
 ]);