@rangojs/router 0.0.0-experimental.143 → 0.0.0-experimental.145

package/dist/vite/index.js

@@ -2393,7 +2393,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.143",
+  version: "0.0.0-experimental.145",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2594,7 +2594,7 @@ var package_default = {
     "@types/react-dom": "catalog:",
     esbuild: "^0.28.1",
     "happy-dom": "^20.10.1",
-    jiti: "^2.6.1",
+    jiti: "^2.7.0",
     react: "catalog:",
     "react-dom": "catalog:",
     typescript: "^5.3.0",
@@ -4597,17 +4597,33 @@ import { createRequire as createRequire3, register } from "node:module";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
 // src/vite/inject-client-debug.ts
-function injectClientDebugFlag(id) {
-  if (!id.includes("internal-debug")) return null;
+function isRouterInternalDebugId(id) {
+  if (!id.includes("internal-debug")) return false;
   const norm = id.replace(/\\/g, "/");
-  const isInternalDebug = /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) && (norm.includes("/@rangojs/router/") || norm.includes("/packages/rangojs-router/"));
-  if (!isInternalDebug) return null;
+  return /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) && (norm.includes("/@rangojs/router/") || norm.includes("/packages/rangojs-router/"));
+}
+function injectClientDebugFlag(id) {
+  if (!isRouterInternalDebugId(id)) return null;
   return {
     code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};
 `,
     map: null
   };
 }
+function internalDebugNoCacheMiddleware() {
+  return function rangoInternalDebugNoCache(req, res, next) {
+    if (req.url && isRouterInternalDebugId(req.url)) {
+      const setHeader = res.setHeader.bind(res);
+      res.setHeader = (name, value) => {
+        return setHeader(
+          name,
+          name.toLowerCase() === "cache-control" ? "no-cache" : value
+        );
+      };
+    }
+    next();
+  };
+}
 
 // src/vite/plugins/virtual-stub-plugin.ts
 function createVirtualStubPlugin() {
@@ -6843,6 +6859,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       if (s.isBuildMode) return;
       if (globalThis.__rscRouterDiscoveryActive) return;
       s.devServer = server;
+      server.middlewares.use(internalDebugNoCacheMiddleware());
       let resolveDiscovery;
       const discoveryPromise = new Promise((resolve12) => {
         resolveDiscovery = resolve12;
@@ -8200,6 +8217,7 @@ function poke() {
   };
 }
 export {
+  directoryClientChunks,
   poke,
   rango
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.143",
+  "version": "0.0.0-experimental.145",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -201,7 +201,7 @@
     "@types/react-dom": "catalog:",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
-    "jiti": "^2.6.1",
+    "jiti": "^2.7.0",
     "react": "catalog:",
     "react-dom": "catalog:",
     "typescript": "^5.3.0",

package/skills/cache-guide/SKILL.md

@@ -20,7 +20,9 @@ caching:
 1. **Stored-value freshness** — _is a cached value still good?_
    → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
    Entries expire by **TTL/SWR** and can be tagged (`cache({ tags })` or runtime
-   `cacheTag(...tags)`). Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
+   `cacheTag(...tags)` — inside `"use cache"` it tags that entry; called during a
+   request render outside `"use cache"` it tags the document/shell artifact).
+   Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
    index by tag; invalidate on demand with `updateTag(...tags)` (awaitable,
    read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking).
    Both hard-purge; the difference is awaitability, not stale-serving.

package/skills/caching/SKILL.md

@@ -111,7 +111,7 @@ Caching") over caching the rendered segment.
 
 ## Tag-Based Invalidation
 
-Tag cached entries, then invalidate them on demand. Tags can be attached three ways:
+Tag cached entries, then invalidate them on demand. Tags can be attached four ways:
 
 ```typescript
 // 1. Static tags in the cache() DSL
@@ -129,8 +129,22 @@ async function getProduct(id: string) {
   cacheTag(`product:${id}`, "products"); // variadic, additive
   return db.getProduct(id);
 }
+
+// 4. Render-callable — a plain server component (no "use cache" in its tree)
+//    records onto the request's document/shell artifact.
+function CampaignBanner() {
+  cacheTag("campaign:spring"); // rides ctx._requestTags → shell/document entry
+  return <aside>Spring sale</aside>;
+}
 ```
 
+Form 4 is how you make a PPR shell or a `/document-cache` page tag-invalidatable
+without wrapping anything in `"use cache"`: the tag rides the request's
+`_requestTags` onto the shell/document entry, and `revalidateTag` then evicts it.
+On a route that is neither PPR nor document-cached the tag records where nothing
+reads it — a silent no-op, so don't expect a bare `cacheTag()` to tag an ordinary
+uncached page.
+
 Invalidate with one of two server-only verbs (both variadic, imported from
 `@rangojs/router`):
 
@@ -171,7 +185,8 @@ converge within `tagCacheTtl` (the **maximum extra cross-colo invalidation
 latency** when no purge is wired). Keep it small (e.g. 30–60), or wire a purge
 (below) and set it large. (Contrast `tagInvalidationTtl`, which must be _large_
 — it bounds how long the KV marker itself lives and must exceed your max entry
-TTL+SWR.)
+TTL+SWR. Left unset there is no expiry: KV markers accumulate unbounded under
+high-cardinality tags, so set it above your largest entry TTL+SWR to bound them.)
 
 To make other colos prompt without a short `tagCacheTtl`, pass `onRevalidateTag`:
 each cached marker carries a namespaced Cloudflare `Cache-Tag`, and the hook is
@@ -435,6 +450,12 @@ is **not** guarded. `ctx.use()` is a server-side escape hatch for non-rendered
 uses (set a ctx var, make a routing decision); never render its result inside a
 cached handler.
 
+This is the **consumption-lane rule**, and it holds identically for every
+shared artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`):
+handler consumption = baked copy with identity reads permitted; client-side
+`useLoader` = live. Stated once in `/rango` → Invariants; pinned by
+semantic-matrix row PPR3 and the `e2e/cache.test.ts` "baked copy" case.
+
 ```typescript
 // WRONG — throws: cookies() read directly in a cached handler
 cache({ ttl: 60 }, () => [

package/skills/catalog.json

@@ -57,6 +57,12 @@
       "argumentHint": "",
       "path": "skills/debug-manifest/SKILL.md"
     },
+    {
+      "name": "defer-hydration",
+      "description": "Keep the full body HTML in a PPR shell's first paint while moving a heavy subtree's hydration off the initial main-thread task — a gated Suspense boundary with the content as its own fallback, released on first idle. Use when a shell HIT paints fast but one long hydration task blocks the main thread, TTI/INP is poor despite instant paint, or a plain Suspense boundary left an empty hole in the frozen prelude.",
+      "argumentHint": "",
+      "path": "skills/defer-hydration/SKILL.md"
+    },
     {
       "name": "document-cache",
       "description": "Cache the whole HTTP response at the edge with Cache-Control headers. Use when caching an entire page or response at a CDN edge, setting Cache-Control headers, or cutting origin hits for public pages — not for caching a single segment or function.",

package/skills/defer-hydration/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: defer-hydration
+description: Keep the full body HTML in a PPR shell's first paint while moving a heavy subtree's hydration off the initial main-thread task — a gated Suspense boundary with the content as its own fallback, released on first idle. Use when a shell HIT paints fast but one long hydration task blocks the main thread, TTI/INP is poor despite instant paint, or a plain Suspense boundary left an empty hole in the frozen prelude.
+argument-hint:
+---
+
+# Deferred hydration: gated boundary, content-as-fallback
+
+PPR (`/ppr`) makes first paint instant — the frozen prelude flushes before any
+render work. It does nothing about what happens next: React hydrates the page
+as one synchronous main-thread task, and on a content-heavy page that task can
+block every click and scroll handler for seconds. Measured on a production
+storefront homepage (shell HIT, production build, M-series laptop): a single
+2543ms task. On the dev server the same page produced a 7.2s task — the page
+was dead for ~11s. Fast paint, frozen page.
+
+The obvious fix — wrap the heavy subtree in `<Suspense>` so it hydrates later —
+trades the paint away: under shell capture that boundary postpones, and the
+frozen prelude ships an empty `<main>`. This recipe gets both: the full body
+HTML in the prelude AND its hydration off the initial task, released on first
+idle at retry-lane priority.
+
+|                                  | baseline | plain `fallback={null}` boundary | gated content-as-fallback |
+| -------------------------------- | -------- | -------------------------------- | ------------------------- |
+| body in first paint              | yes      | **no — empty `<main>`**          | yes                       |
+| worst main-thread task           | 2543ms   | 844ms                            | **386ms**                 |
+| total blocked time (>50ms tasks) | 2705ms   | 1436ms                           | **554ms**                 |
+| interactive (menu click works)   | ~3.5s    | ~1.6s                            | ~1.6s                     |
+
+Measure your own page before and after — the win depends on how much of the
+hydration cost lives under the boundary (see "Verifying and measuring").
+
+## The recipe
+
+~40 lines, plain React, no rango imports — copy it into your app:
+
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import { Suspense, startTransition, use, useEffect } from "react";
+
+let released = false;
+let releaseFn: (() => void) | undefined;
+const gate = new Promise<void>((resolve) => {
+  releaseFn = resolve;
+});
+
+function releaseHydrationGate() {
+  if (released) return;
+  released = true;
+  // Transition so the boundary retry/hydration is scheduled non-urgent,
+  // never as a sync flush from the idle callback.
+  startTransition(() => releaseFn?.());
+}
+
+function HydrationGate() {
+  // Server: inert (children SSR normally). Client before release: suspend,
+  // so React skips hydrating the boundary and KEEPS the server DOM.
+  if (typeof window !== "undefined" && !released) use(gate);
+  return null;
+}
+
+function ReleaseHydrationGate() {
+  // Sibling of the boundary — NEVER under it (its effect would deadlock
+  // holding its own key). Hydrates with the early pass.
+  useEffect(() => {
+    if (released) return;
+    if ("requestIdleCallback" in window) {
+      requestIdleCallback(releaseHydrationGate, { timeout: 1500 });
+    } else {
+      setTimeout(releaseHydrationGate, 200);
+    }
+  }, []);
+  return null;
+}
+
+export function DeferredHydration({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <ReleaseHydrationGate />
+      <Suspense fallback={children}>
+        <HydrationGate />
+        {children}
+      </Suspense>
+    </>
+  );
+}
+```
+
+Wrap the heavy subtree — typically the page body under the app chrome:
+
+```tsx
+<DeferredHydration>
+  <HomePageBody />
+</DeferredHydration>
+```
+
+The chrome (header, nav — whatever must respond to the first click) stays
+outside the boundary and hydrates in the early, now-small task. Everything
+inside hydrates after first idle.
+
+## Why `fallback={children}` is load-bearing
+
+This is not a style choice; it is the half of the recipe that makes it
+PPR-compatible.
+
+Shell capture aborts on flight byte-quiet (`src/rsc/shell-capture.ts`,
+`FLIGHT_QUIET_HOPS`): once the Flight source has been byte-silent for the
+quiet window, the fizz render freezes. A big HTML subtree under _any_
+`<Suspense>` boundary cannot finish inside that window, so the boundary always
+postpones — boundary placement cannot fix it. Verified both ways: wrapping the
+client island from outside AND placing the boundary inside the island both
+baked `<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the
+frozen prelude.
+
+With the content as the fallback, the unavoidable postpone _becomes the
+delivery mechanism_: the shell bakes the fallback, and the fallback IS the
+body. In `/ppr` hole-doctrine terms, this is the PHYSICS class exploited
+deliberately — you cannot stop the boundary from becoming a hole, so you make
+the hole's baked fallback carry the real markup.
+
+## Why the client gate is free
+
+Suspending during hydration keeps the **server DOM**, not the fallback. When
+`HydrationGate` suspends on the client, React skips hydrating that boundary
+and leaves the baked HTML in place — visible, styled, inert. On release, the
+boundary retries on the retry lane (interruptible, non-urgent thanks to the
+`startTransition` in `releaseHydrationGate`), and the existing DOM hydrates in
+place. No blank, no flicker, no re-paint.
+
+## The sync-update trap (scar tissue)
+
+A **synchronous** update that reaches into a dehydrated boundary makes React
+abandon hydration and client-render it instead. That client render suspends on
+the gate and renders the fallback. With `fallback={children}` this is a visual
+no-op (but wasted work); with `fallback={null}` it blanks the page.
+
+The corollary: provider data syncs that land right after the chrome hydrates —
+basket, wishlist, auth state read from storage in an effect — MUST be
+`startTransition`-wrapped. This was measured, not theorized: without the
+transitions, the boundary was force-hydrated synchronously and the split
+evaporated (the 2543ms task survived intact).
+
+```tsx
+useEffect(() => {
+  const stored = readBasketFromStorage();
+  startTransition(() => setBasket(stored)); // NOT a bare setBasket(stored)
+}, []);
+```
+
+## Pre-release interaction semantics
+
+Between paint and release (window ≈ one idle, capped by the `requestIdleCallback`
+timeout — 1500ms in the reference):
+
+- **Native anchors work** — they are plain HTML in the server DOM, plus any
+  click-delegation living above the boundary.
+- **React `onClick`s inside the gated subtree queue** via React's event replay
+  and fire on hydration after release.
+
+If the gated subtree's first-click latency matters more than idle timing,
+release on interaction instead (see Variations).
+
+## Known cost: the body rides twice (measure it, don't guess)
+
+On a shell HIT the gated subtree's HTML is in the response twice — once as the
+baked fallback in the prelude, once as the resumed hole content (the resume
+re-renders and re-ships it; there is no bake-through). Homepage measurement:
+234KB → 302KB gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth,
+not render-blocking — the visible prelude streams first — but it is real bytes
+on every document GET. Weigh it per page; on a small body the recipe may not
+pay for itself.
+
+## Verifying and measuring
+
+Production build only — dev-server hydration numbers are noise (module
+transforms dominate; the 7.2s dev task above vs 2543ms in production).
+
+**Body in the prelude.** Fetch the document and check a distinctive piece of
+body markup appears BEFORE the first resumed segment:
+
+```
+curl -s -H "Accept: text/html" http://localhost:4173/ \
+  | awk '{ if (match($0, /<div hidden id="S:/)) { print substr($0, 1, RSTART); exit } print }' \
+  | grep -c "Best Sellers"    # any string unique to the gated body
+```
+
+`0` with `<!--$?--><template id="B:` markers inside `<main>` means an empty
+hole baked instead — the fallback is not the content (wrong boundary, or a
+plain `fallback={null}`/skeleton boundary).
+
+**Main-thread tasks.** Paste a longtask observer in the console before
+reloading, then compare the worst task with the recipe on and off:
+
+```js
+new PerformanceObserver((l) =>
+  l
+    .getEntries()
+    .forEach((e) => console.log("longtask", Math.round(e.duration))),
+).observe({ entryTypes: ["longtask"] });
+```
+
+**Interactivity.** Click the chrome (menu, nav) immediately after paint — it
+should respond while the gated body is still inert.
+
+## Variations
+
+- **Release on visible** — an `IntersectionObserver` per boundary instead of
+  `requestIdleCallback`: below-the-fold sections hydrate only when scrolled
+  near.
+- **Release on first interaction** — a capture-phase listener
+  (`pointerdown`/`keydown` on `window`) that releases immediately: the queued
+  event replays into the touched boundary and React's selective hydration
+  prioritizes it. Best when the gated subtree is itself the interaction
+  target.
+- **One shared gate vs per-boundary gates** — the reference uses one
+  module-level gate (first release wins, all boundaries hydrate together).
+  Multiple independent boundaries (visible-based, per-section) need one
+  gate/`released` pair per boundary — factor the module into a
+  `createHydrationGate()` if you go there.
+
+## What this deliberately is not
+
+The duplicated payload has an obvious framework-level fix: a "bake-through"
+boundary that bakes the boundary _content_ into the prelude and skips the
+redundant hole resume. That is deliberately NOT part of this recipe — a recipe
+has zero API commitment, and React's `<Activity>`/postpone work may land under
+this exact space. The recipe survives that future; a primitive might not.
+
+## Related
+
+- `/ppr` — the shell/hole mechanics this recipe rides on (hole doctrine:
+  PHYSICS class), and why the capture postpones any big Suspense subtree
+- `src/rsc/shell-capture.ts` — the byte-quiet capture window
+  (`FLIGHT_QUIET_HOPS`) that makes `fallback={children}` mandatory

package/skills/loader/SKILL.md

@@ -147,6 +147,11 @@ same memoized result — loaders never run twice per request.
 - The handler output depends on the loader data. If the route is inside
   `cache()`, the handler is cached with the loader result baked in —
   defeating the live data guarantee.
+- The same holds under a PPR shell capture (`/ppr`): handler consumption is
+  the BAKED lane — the loader executes at capture (identity reads permitted)
+  and the rendered value is a capture-time copy; `useLoader` client-side is
+  the live lane. One rule across `cache()`, `"use cache"`, and PPR: the
+  consumption-lane rule (`/rango` → Invariants).
 - Non-cacheable variable reads (`createVar({ cache: false })`) inside the
   handler still throw, even if the data came from a loader.
 - Prefer DSL `loader()` + client `useLoader()` for data that depends on

package/skills/migrate-nextjs/SKILL.md

@@ -447,8 +447,10 @@ Next.js conflates two things under "revalidation." Rango separates them — and
 tag-based cache invalidation now maps directly.
 
 **1. Cache invalidation (bust cached values) — direct equivalent.** Tag entries
-with `cache({ tags })` or, inside a `"use cache"` function, runtime
-`cacheTag(...tags)`. Then invalidate by tag:
+with `cache({ tags })` or runtime `cacheTag(...tags)`. `cacheTag()` works inside a
+`"use cache"` function (tags that entry) AND render-callable in a plain server
+component (no `"use cache"` needed — it tags the document / PPR shell the component
+renders into). Then invalidate by tag:
 
 ```typescript
 // Next.js                    Rango

package/skills/parallel/SKILL.md

@@ -239,6 +239,8 @@ layout(<AccountLayout />, () => [
 
 A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
 
+Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value (identity reads included) freezes into the artifact; consume the loader client-side (`useLoader` in a `"use client"` component) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
+
 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.

package/skills/ppr/SKILL.md

@@ -251,18 +251,18 @@ async function Handler(ctx: HandlerContext) {
 | already-resolved / instant / synchronous values | `loader(() => Promise.resolve(x))` + `loading()`                  | a raw promise that settles inside the quiet window BAKES; only the live lane guarantees live     |
 | none of the above                               | nothing                                                           | it bakes — that is what the shell is for                                                         |
 
-The physics caveat in one line: promise holes are holes because the I/O is
-genuinely pending at capture. If the value can resolve near-instantly (memory
-read, warmed cache), it may bake into the shell — when liveness must be
-guaranteed rather than probable, use the live lane (`loading()`). The same
-physics governs bake-lane nested promises, with one shape guarantee: a nested
-promise that settles inside the window pins its VALUE, but the container key
-KEEPS its promise shape on HITs (the snapshot rehydrates a
-`Promise.resolve(pinned)`), so an unconditional `use(data.x)` consumer never
-breaks — it just reads the pinned value. Note the timing consequence: whether
-such a value is pinned or live can vary per capture (concurrent loader traffic
-extends the quiet window), so treat "fast-resolving promise on the bake lane"
-as PINNED for correctness purposes.
+The physics caveat in one line: HANDLER-created promise props are holes only
+because the I/O is genuinely pending at capture — if the value can resolve
+near-instantly (memory read, warmed cache), it may bake into the shell; when
+liveness must be guaranteed rather than probable, use a loader. BAKE-LANE
+NESTED promises are exempt from that race: the capture MASKS every thenable
+nested in a bake-lane container regardless of settle timing
+(`maskNestedContainerThenables`, loader-cache.ts), so the consuming boundary
+always postpones as a hole and every HIT streams the FRESH value — the
+promise SHAPE is the liveness declaration, not a bet on latency. (Before the
+mask, a nested promise that settled inside the window pinned its capture-time
+value into the shared shell; found live as a storefront basket — with the
+capturing session's identifiers — served to anonymous visitors.)
 
 ### Handles: "nesting = liveness"
 
@@ -272,7 +272,11 @@ as PINNED for correctness purposes.
   by the capture's 5s guard).
 - `ctx.use(H)({ x: promise })` — the container passes through verbatim
   (resolution is shallow); the nested promise streams to the consumer, who must
-  `<Suspense>` it. Under capture that boundary postpones — a hole.
+  `<Suspense>` it. Under capture that boundary postpones — a hole — REGARDLESS
+  of settle timing: the capture masks nested thenables in pushed handle
+  containers (the capture store's push wrap, shell-capture.ts), so even an
+  already-resolved nested promise holes instead of baking its value into the
+  shared shell. Same shape-is-the-declaration rule as bake-lane loaders.
 
 ### Want a hole for already-resolved data?
 
@@ -284,8 +288,9 @@ how fast the value settles.
 
 A loader on an entry with no renderable `loading()` EXECUTES during capture
 (the capture gate holds open for its real latency, bounded by the 5s guard).
-Its settled container bakes into the prelude; every promise still nested in it
-postpones at the consumer's own `<Suspense>` — a hole. On every HIT the
+Its settled container bakes into the prelude; every promise nested in it is
+masked at capture (regardless of how fast it settles) and postpones at the
+consumer's own `<Suspense>` — a hole. On every HIT the
 capture snapshot's loader family overlays the recorded container onto the
 fresh run, so the payload matches the frozen prelude byte-for-byte while the
 nested promises run fresh. The return shape is the declaration:
@@ -368,16 +373,27 @@ stay live. Your levers, in order of preference:
    Slot-owned loaders are masked at capture and GUARANTEED fresh per serve —
    use this where the bake lane's physics (a fast resolve bakes) or pinning
    (capture-time data for the shell's lifetime) is not acceptable, at the cost
-   of a widget-sized fallback in the shell.
+   of a widget-sized fallback in the shell. The slot handler must hand the
+   loader to a CLIENT component (`useLoader` in a `"use client"` component)
+   for the freshness guarantee to reach the rendered value: server-side
+   `await ctx.use(...)` in the handler is the BAKED lane (the consumption-lane
+   rule, `/rango` → Invariants) — it executes at capture with identity reads
+   permitted, but the value it renders is a capture-time copy wherever it is
+   not shielded by the slot's masked LoaderBoundary.
 
 4. **Shared layout data can also leave the loader lane entirely**: an
    un-awaited handler promise under the consumer's `<Suspense>` (a physics
    hole) or `cache()`/`"use cache"` to bake it with tag-invalidation.
 
 The identity rule, stated once: per-user data on a PPR page lives in a NESTED
-promise (a hole, fresh per request) or behind `loading()` (the live lane).
-Reading `cookies()`/`headers()` where the value would bake — handler shell
-material or a bake-lane container — refuses the capture by construction.
+promise (a hole, fresh per request) or behind `loading()` with CLIENT-side
+consumption (the live lane). Reading `cookies()`/`headers()` where the value
+would bake as SEGMENT material — handler/render code or a bake-lane loader
+container — refuses the capture by construction. The one exemption is
+handler-INVOKED loader bodies (`await ctx.use(loader)`): they execute at
+capture with identity reads permitted, and the value bakes as a shared
+capture-time copy — mirroring `cache()` semantics (the consumption-lane
+rule; semantic-matrix row PPR3).
 
 ## Execution matrix
 
@@ -505,10 +521,11 @@ multi-tenant shells never collide).
 HTML; `revalidate()` is a DATA lever that never touches it.
 
 A captured shell auto-carries the UNION of the non-loader tags recorded during
-the capture render — every `cacheTag(...)` from a `"use cache"` function or
-`cache()` segment that ran as shell material. Loader tags never attach (the
-holes are already live). `ppr.tags` adds operational tags the render cannot
-know (a tenant id, a deploy marker).
+the capture render — every `cacheTag(...)` that ran as shell material, whether
+from a `"use cache"` function, a `cache()` segment, or a render-callable
+`cacheTag()` in a plain server component (no `"use cache"`/`cache()` in its
+tree). Loader tags never attach (the holes are already live). `ppr.tags` adds
+operational tags the render cannot know (a tenant id, a deploy marker).
 
 | Lever                                         | Reaches the frozen shell?                                     | Reaches the holes?                                  |
 | --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- |
@@ -516,6 +533,12 @@ know (a tenant id, a deploy marker).
 | `updateTag` / `revalidateTag` on a LOADER tag | no — loader tags never attach to a shell                      | drops that loader's cached value (if it `cache()`s) |
 | `revalidate()` (named revalidation contract)  | **no** — re-runs segments/loaders for the PAYLOAD, never HTML | yes — the hole re-renders with fresh data           |
 
+A server action's automatic invalidation refreshes the CLIENT only — it re-runs
+the holes and streams a fresh payload, but does NOT evict the server shell.
+Shell-baked data stays stale until the shell's TTL unless you tag-invalidate it
+(`updateTag` on a shell tag). Data baked into the shell WITHOUT a tag cannot be
+evicted by tag at all — move always-fresh data under a `loading()` hole.
+
 ## Pitfalls
 
 - **A bake-lane loader that reads `cookies()`/`headers()`**: the capture is
@@ -534,21 +557,22 @@ know (a tenant id, a deploy marker).
 - **The session-object bake trap (the guard cannot save you here)**: the
   capture guard sees `cookies()`/`headers()` calls ONLY. A bake-lane loader
   reading a middleware-provided session object (`ctx.get("session")`) refuses
-  nothing — and its FAST-RESOLVE branch is the killer:
+  nothing. Per-user data survives ONLY behind a nested promise — the shape is
+  the declaration, and it holds for BOTH branches regardless of settle timing
+  (nested thenables are masked at capture):
 
   ```typescript
   const CartLoader = createLoader(async (ctx) => {
     const basketId = ctx.get("session")!.get("basketId");
-    if (!basketId) return { cart: Promise.resolve(null) }; // SETTLED → BAKES
-    return { cart: fetchBasket(basketId) }; // pending → hole
+    if (!basketId) return { cart: Promise.resolve(null) }; // nested thenable → masked → hole, fresh per HIT
+    return { cart: fetchBasket(basketId) }; // nested thenable → masked → hole, fresh per HIT
   });
   ```
 
-  If the capturing request is anonymous (it usually is), `cart: null` bakes
-  and is snapshot-pinned: every logged-in user gets the anonymous badge on
-  every HIT. The branch asymmetry makes it nondeterministic per capture. Any
-  loader whose data is per-user belongs on the live lane — for a header
-  widget, a parallel slot with its own `loading()` (playbook lever 3).
+  The remaining trap is returning per-user data as PLAIN container material:
+  `return { user: session.user }` bakes it into the shared shell like any
+  other settled value — deterministically, not by race. Wrap it in a promise
+  (even an already-resolved one) or put the loader on the live lane.
 
 - **Theme on a HIT is capture-then-corrected**: the resume tree replays the
   CAPTURE's `initialTheme` (resume requires it to match the frozen prelude);
@@ -563,8 +587,11 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   tag-invalidated. This is deliberate — parity beats freshness inside the shell.
   If a shell region needs to be fresh, put it under a hole — `loading()` for
   loader data, or an un-awaited promise under the consumer's `<Suspense>`
-  (holes are never pinned) — or make the SHELL itself invalidatable by adding
-  the tag to `ppr.tags`. Ring-1/ring-3 tag invalidation does NOT drop the shell.
+  (holes are never pinned) — or make the SHELL itself invalidatable by tagging
+  it: call `cacheTag(...)` from the shell-material render code (the render-time
+  lever), or add the tag to `ppr.tags` (operational tags the render cannot know —
+  a tenant id, a deploy marker). Ring-1/ring-3 tag invalidation does NOT drop the
+  shell.
 - **Uncached nondeterminism in the shell is a hydration hazard**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
   material (outside any cache ring) drifts between capture and hit and the
@@ -586,6 +613,9 @@ cache"` value baked into the shell is PINNED at capture (the capture data
 
 ## Related
 
+- `/defer-hydration` — keep the full body HTML in the shell while moving a
+  heavy subtree's hydration off the initial main-thread task (gated boundary,
+  content-as-fallback)
 - `/document-cache` — whole-response edge caching (no live holes)
 - `/caching` and `/cache-guide` — segment/function caching (axis 1 data)
 - `/shell-manifest` — replayed handles as cache metadata read by live loaders

package/skills/rango/SKILL.md

@@ -117,6 +117,15 @@ stated, greppable contract.
 - `path()`/`include()` are always visible in `urls()`; config helpers are extractable.
 - **Cache decides freshness; `revalidate()` decides client-update.** Orthogonal; compose.
 - Loaders resolve fresh every request (even inside `cache()`) and never run twice/request.
+- **The consumption-lane rule.** For every shared artifact (`cache()`,
+  `"use cache"`, the PPR shell): server-side handler consumption
+  (`await ctx.use(loader)`) yields a BAKED copy — identity reads
+  (`cookies()`/`headers()`) are permitted there and the capture-time value
+  freezes into the shared artifact (a documented footgun; see `/caching` →
+  "Cache purity & tainted objects"). Client-side consumption (`useLoader` in
+  a `"use client"` component) is the LIVE lane. DSL `loader()` segments
+  follow their lane machinery (live under renderable `loading()`, bake
+  otherwise). Pinned by semantic-matrix row PPR3.
 - Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
   is captured on miss and replayed on hit. (The non-cacheable read guard is a
@@ -273,6 +282,7 @@ Grouped by concern — read when you need to…
 | `/scripts`          | Inject third-party scripts (GTM/analytics) into head/body via the `Script` handle; nonce auto-applied to document-rendered scripts |
 | `/tailwind`         | Set up Tailwind CSS v4 with `?url` imports                                                                                         |
 | `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
+| `/defer-hydration`  | Full body HTML in the PPR shell + hydration off the critical path (gated Suspense boundary, content-as-fallback)                   |
 | `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
 | `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |