@rangojs/router 0.0.0-experimental.142 → 0.0.0-experimental.144

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.142",
+  version: "0.0.0-experimental.144",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2583,6 +2583,8 @@ var package_default = {
   },
   devDependencies: {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
     "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
@@ -2592,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",
@@ -4595,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() {
@@ -6841,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.142",
+  "version": "0.0.0-experimental.144",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -190,6 +190,8 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
     "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
@@ -199,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

@@ -91,9 +91,27 @@ cache(
 );
 ```
 
+## When cache() does not pay
+
+A cache hit is not free: it still runs middleware, the store read, and the
+document render AROUND the cached segment. The win is proportional to what
+the cached render itself costs — measured on a deployed Cloudflare worker
+(2026-07), a trivial page inside `cache()` served hits at p50 36 ms while
+misses (render + store) served at 35 ms: indistinguishable. The same
+boundary around an expensive render (slow data, big trees) is where the TTL
+pays for itself.
+
+Rule of thumb: reach for `cache()` when the segment's own render cost is
+meaningfully above your latency floor — expensive render-embedded data work,
+large component trees, third-party calls captured in the render. Do not wrap cheap
+pages "just in case": you add store traffic and invalidation surface for no
+latency win. If the data is what's expensive and it changes per-request,
+prefer a loader with `cache()` on the loader DATA (see "Loader-Level
+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
@@ -111,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`):
 
@@ -153,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
@@ -417,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/composability/SKILL.md

@@ -210,6 +210,38 @@ in the group — including nested `include()`s inside the split module. Only the
 module's runtime evaluation defers. `rango generate` resolves the `() => import()`
 the same way, so a code-split group is still fully typed.
 
+### Sizing async include groups (measured)
+
+The first request into an async group pays that group's chunk import; every
+request after that is flat. Measured on a deployed Cloudflare worker with
+26k routes (2026-07, warm RTT floor ~23 ms):
+
+| Group size                 | First-hit latency                    |
+| -------------------------- | ------------------------------------ |
+| ~240 routes                | ~75 ms (≈ RTT + eval)                |
+| ~5,000 routes              | ~137 ms                              |
+| ~9,000 routes              | ~188 ms                              |
+| 3-level nested async chain | ~464 ms (levels import sequentially) |
+
+Three rules fall out of those numbers:
+
+1. **Prefer more, smaller groups over few giant ones.** First-hit cost scales
+   with routes-per-chunk; fifty 250-route groups each cost a fraction of one
+   9k-route group, and only the group actually visited pays anything.
+2. **Keep async-include chains shallow on latency-sensitive paths.** Each
+   nested `() => import()` level awaits in sequence, so depth multiplies the
+   first hit. Nesting eager includes inside one async module costs one chunk;
+   nesting async inside async costs one chunk per level.
+3. **Give sibling groups distinct static prefixes.** Siblings that share a
+   static prefix (`include("/x/:a", …)` next to `include("/x/:b", …)`) all
+   import on the first hit to that prefix — the router cannot tell which one
+   matches before loading them.
+
+Warm-path matching is O(path segments) via the precomputed trie regardless of
+group layout — this sizing only shapes cold/first-hit behavior. For
+latency-critical prefixes, a post-deploy warmup ping (one request per prefix)
+erases first-hit cost for the isolate entirely.
+
 ## Composition Types
 
 For typed factories, import the composition types:

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/observability/SKILL.md

@@ -58,6 +58,14 @@ Read the timeline as intervals:
 - Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
   appear as separate spans, so the slow phase is visible without guessing.
 
+**Deployed Cloudflare caveat**: on production Workers, timers are frozen
+during request execution (Spectre mitigation), so `Server-Timing` durations
+read as ~0 on the deployed edge — they only advance across genuine awaited
+I/O. The waterfall is a LOCAL diagnostic (dev, `vite preview`,
+`wrangler dev`); for deployed workers, measure from the client
+(`PerformanceResourceTiming`, TTFB) and use structured telemetry below for
+server-side events.
+
 ## Structured telemetry
 
 Use telemetry when you want durable production events rather than a one-request

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.
@@ -271,6 +273,8 @@ parallel(
 
 Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
 
+Typing note: a BARE arrow slot handler infers its ctx (`"@cart": (ctx) => ...`), but an arrow inside a DESCRIPTOR needs an explicit annotation — `handler: (ctx: HandlerContext) => ...` — because `StaticHandlerDefinition` in the slot union contributes a second callable to the contextual type and TS declines to pick a signature.
+
 ## Slot Override Semantics
 
 When multiple `parallel()` calls define the same slot name, **the last