@rangojs/router 0.0.0-experimental.78a48627 → 0.0.0-experimental.7dc955ec

package/skills/caching/SKILL.md

@@ -120,9 +120,9 @@ const store = new MemorySegmentCacheStore({
 });
 ```
 
-### Cloudflare KV Store
+### Cloudflare Edge Cache Store
 
-For distributed caching on Cloudflare Workers:
+For distributed caching on Cloudflare Workers using the Cache API:
 
 ```typescript
 import { CFCacheStore } from "@rangojs/router/cache";
@@ -132,14 +132,55 @@ const router = createRouter<AppBindings>({
   urls: urlpatterns,
   cache: (env, ctx) => ({
     store: new CFCacheStore({
-      kv: env.CACHE_KV,
-      waitUntil: (fn) => ctx!.waitUntil(fn),
+      ctx,
+      defaults: { ttl: 60, swr: 300 },
     }),
     enabled: true,
   }),
 });
 ```
 
+### With KV L2 Persistence
+
+Add a KV namespace for global cross-colo persistence. On Cache API miss, KV is
+checked and hits are promoted back to L1. Writes go to both layers.
+
+```typescript
+import { CFCacheStore } from "@rangojs/router/cache";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  cache: (env, ctx) => ({
+    store: new CFCacheStore({
+      ctx,
+      kv: env.CACHE_KV, // optional KV namespace binding
+      defaults: { ttl: 60, swr: 300 },
+    }),
+    enabled: true,
+  }),
+});
+```
+
+**How the two layers work:**
+
+| Scenario     | L1 (Cache API) | L2 (KV) | Result                        |
+| ------------ | -------------- | ------- | ----------------------------- |
+| Hot request  | HIT            | —       | Serve from L1 (fast)          |
+| Cold colo    | MISS           | HIT     | Serve from KV, promote to L1  |
+| First render | MISS           | MISS    | Render, write to both L1 + KV |
+
+KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
+are only cached in L1.
+
+## Context Variables Inside Cache Boundaries
+
+Context variables (`createVar`) are cacheable by default and can be read and
+written inside `cache()` scopes. Variables marked with `{ cache: false }` (at
+the var level or write level) throw when read inside a cache scope. Response
+side effects (`ctx.header()`, `ctx.cookie()`) always throw inside cache
+boundaries. See `/cache-guide` for the full cache safety table.
+
 ## Nested Cache Boundaries
 
 Override cache settings for specific sections:

package/skills/parallel/SKILL.md

@@ -92,6 +92,73 @@ path("/dashboard/:id", (ctx) => {
 ])
 ```
 
+## Setting Handles (Meta, Breadcrumbs)
+
+Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
+push handle data. The data is associated with the **parent** layout or route
+segment, not the parallel segment itself. This is because parallels execute
+after their parent handler and inherit its segment scope.
+
+This works well for document-level metadata — the handle data follows the
+parent's lifecycle (appears when the parent is mounted, removed when it
+unmounts).
+
+```typescript
+parallel({
+  "@meta": (ctx) => {
+    const meta = ctx.use(Meta);
+    meta({ title: "Product Detail" });
+    meta({ name: "description", content: "..." });
+    return null; // UI-less slot, only sets metadata
+  },
+  "@sidebar": (ctx) => <Sidebar />,
+})
+```
+
+Multiple parallels on the same parent can each push handle data — they all
+accumulate under the parent segment ID.
+
+### Pattern: `@meta` slot for per-route metadata overrides
+
+A dedicated `@meta` parallel slot lets routes define metadata separately from
+their handler logic. The layout sets defaults via a title template, and each
+route overrides via its own `@meta` slot. Since child segments push after
+parents and `collectMeta` uses last-wins deduplication, overrides work
+naturally.
+
+```typescript
+// Layout sets defaults
+layout((ctx) => {
+  ctx.use(Meta)({ title: { template: "%s | Store", default: "Store" } });
+  return <StoreLayout />;
+}, () => [
+  // Route with @meta override — decoupled from handler rendering
+  path("/:slug", ProductPage, { name: "product" }, () => [
+    parallel({
+      "@meta": async (ctx) => {
+        const product = await ctx.use(ProductLoader);
+        const meta = ctx.use(Meta);
+        meta({ title: product.name });
+        meta({ name: "description", content: product.description });
+        meta({
+          "script:ld+json": {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            name: product.name,
+            description: product.description,
+          },
+        });
+        return null; // UI-less slot
+      },
+    }),
+  ]),
+])
+```
+
+This keeps the route handler focused on rendering UI while metadata
+(title, description, Open Graph, JSON-LD) lives in a composable slot that
+can be added, removed, or swapped per route without touching the handler.
+
 ## Parallel Routes with Loaders
 
 Add loaders and loading states to parallel routes:
@@ -109,6 +176,65 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript

package/skills/route/SKILL.md

@@ -181,6 +181,37 @@ String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
 Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
 and intercepts can only read via `ctx.get()`.
 
+#### Non-cacheable context variables
+
+Mark a var as non-cacheable when it holds inherently request-specific data
+(sessions, auth tokens, per-request IDs). There are two ways:
+
+```typescript
+// Var-level: every value written to this var is non-cacheable
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level: escalate a normally-cacheable var for this specific write
+const Theme = createVar<string>();
+ctx.set(Theme, userTheme, { cache: false });
+```
+
+"Least cacheable wins" — if either the var definition or the write site says
+`cache: false`, the value is non-cacheable.
+
+Reading a non-cacheable var inside `cache()` or `"use cache"` throws at
+runtime. This prevents request-specific data from leaking into cached output:
+
+```typescript
+// This throws — Session is non-cacheable
+async function CachedWidget(ctx) {
+  "use cache";
+  const session = ctx.get(Session); // Error: non-cacheable var read inside cache scope
+  return <Widget />;
+}
+```
+
+Cacheable vars (the default) can be read freely inside cache scopes.
+
 ### Revalidation Contracts for Handler Data
 
 Handler-first guarantees apply within a single full render pass. For partial

package/skills/typesafety/SKILL.md

@@ -369,8 +369,18 @@ interface PaginationData {
   perPage: number;
 }
 export const Pagination = createVar<PaginationData>();
+
+// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+const Session = createVar<SessionData>({ cache: false });
 ```
 
+`createVar` accepts an optional options object. The `cache` option (default
+`true`) controls whether the var's values can be read inside cache scopes.
+Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
+marks a specific write as non-cacheable even if the var itself is cacheable.
+"Least cacheable wins" — if either says `cache: false`, the value throws on
+read inside `cache()` or `"use cache"`.
+
 ### Producer (handler or middleware)
 
 ```typescript

package/src/browser/event-controller.ts

@@ -79,6 +79,8 @@ export interface DerivedNavigationState {
   state: "idle" | "loading";
   /** Whether any operation is streaming */
   isStreaming: boolean;
+  /** Whether a navigation is active (fetching or streaming, before commit) */
+  isNavigating: boolean;
   /** Current committed location */
   location: NavigationLocation;
   /** URL being navigated to (null if idle) */
@@ -389,6 +391,9 @@ export function createEventController(
     return {
       state,
       isStreaming,
+      // True when a navigation is active (fetching or streaming, before
+      // commit). Broader than pendingUrl which clears during streaming.
+      isNavigating: currentNavigation !== null,
       location,
       // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending.
       // Background revalidations (skipLoadingState) don't expose a pending URL.

package/src/browser/navigation-client.ts

@@ -17,7 +17,11 @@ import {
   emptyResponse,
   teeWithCompletion,
 } from "./response-adapter.js";
-import { buildPrefetchKey, consumePrefetch } from "./prefetch/cache.js";
+import {
+  buildPrefetchKey,
+  consumeInflightPrefetch,
+  consumePrefetch,
+} from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -85,49 +89,33 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_v", version);
       }
 
-      // Check in-memory prefetch cache before making a network request.
+      // Check completed in-memory prefetch cache before making a network request.
       // The cache key includes the source URL (previousUrl) because the
       // server's diff response depends on the source page context.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
+      //
+      const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
       const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse =
-        !staleRevalidation && !hmr && !interceptSourceUrl
-          ? consumePrefetch(cacheKey)
-          : null;
-
+      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
+      const inflightResponsePromise = canUsePrefetch
+        ? consumeInflightPrefetch(cacheKey)
+        : null;
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
         resolveStreamComplete = resolve;
       });
 
-      let responsePromise: Promise<Response>;
-
-      if (cachedResponse) {
-        if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
-        }
-        // Cached response body is already fully buffered (arrayBuffer),
-        // so stream completion is immediate.
-        responsePromise = Promise.resolve(cachedResponse).then((response) => {
-          return teeWithCompletion(
-            response,
-            () => {
-              if (tx) browserDebugLog(tx, "stream complete (from cache)");
-              resolveStreamComplete();
-            },
-            signal,
-          );
-        });
-      } else {
+      /** Start a fresh navigation fetch (no cache / inflight hit). */
+      const doFreshFetch = (): Promise<Response> => {
         if (tx) {
           browserDebugLog(tx, "fetching", {
             path: `${fetchUrl.pathname}${fetchUrl.search}`,
           });
         }
 
-        responsePromise = fetch(fetchUrl, {
+        return fetch(fetchUrl, {
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
             "X-Rango-State": getRangoState(),
@@ -183,6 +171,51 @@ export function createNavigationClient(
             signal,
           );
         });
+      };
+
+      let responsePromise: Promise<Response>;
+
+      if (cachedResponse) {
+        if (tx) {
+          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+        }
+        // Cached response body is already fully buffered (arrayBuffer),
+        // so stream completion is immediate.
+        responsePromise = Promise.resolve(cachedResponse).then((response) => {
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete (from cache)");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      } else if (inflightResponsePromise) {
+        if (tx) {
+          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+        }
+        responsePromise = inflightResponsePromise.then(async (response) => {
+          if (!response) {
+            if (tx) {
+              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
+            }
+            return doFreshFetch();
+          }
+
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) {
+                browserDebugLog(tx, "stream complete (from inflight prefetch)");
+              }
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      } else {
+        responsePromise = doFreshFetch();
       }
 
       try {

package/src/browser/partial-update.ts

@@ -19,6 +19,14 @@ import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
 import { debugLog } from "./logging.js";
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import type { NavigationUpdate } from "./types.js";
+
+/** Build a scroll payload from the commit's scroll option */
+function toScrollPayload(
+  scroll: boolean | undefined,
+): NonNullable<NavigationUpdate["scroll"]> {
+  return { enabled: scroll !== false ? scroll : false };
+}
 
 /**
  * Configuration for creating a partial updater
@@ -251,6 +259,17 @@ export function createPartialUpdater(
             existingSegments,
           );
 
+          // Fix: tx.commit() cached the source page's handleData because
+          // eventController hasn't been updated yet. Overwrite with the
+          // correct cached handleData to prevent cache corruption on
+          // subsequent navigations to this same URL.
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
+
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
           // Remove `handles` from metadata to prevent NavigationProvider from
@@ -263,10 +282,7 @@ export function createPartialUpdater(
               ...metadataWithoutHandles,
               cachedHandleData: mode.targetCacheHandleData,
             },
-            scroll:
-              commitScroll !== false
-                ? { enabled: commitScroll }
-                : { enabled: false },
+            scroll: toScrollPayload(commitScroll),
           };
 
           const cachedHasTransition = existingSegments.some(
@@ -305,10 +321,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
-            scroll:
-              leaveScroll !== false
-                ? { enabled: leaveScroll }
-                : { enabled: false },
+            scroll: toScrollPayload(leaveScroll),
           });
 
           debugLog("[Browser] Navigation complete (left intercept)");
@@ -462,10 +475,7 @@ export function createPartialUpdater(
       // Emit update to trigger React render.
       // Scroll info is included so NavigationProvider applies it after React commits.
       const hasTransition = reconciled.mainSegments.some((s) => s.transition);
-      const scrollPayload =
-        navScroll !== false
-          ? { enabled: navScroll }
-          : { enabled: false as const };
+      const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
         startTransition(() => {
@@ -529,10 +539,7 @@ export function createPartialUpdater(
       const fullHasTransition = segments.some(
         (s: ResolvedSegment) => s.transition,
       );
-      const fullScrollPayload =
-        fullScroll !== false
-          ? { enabled: fullScroll }
-          : { enabled: false as const };
+      const fullScrollPayload = toScrollPayload(fullScroll);
 
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;

package/src/browser/prefetch/cache.ts

@@ -1,16 +1,20 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetch Response objects for instant cache hits
+ * In-memory cache storing prefetched Response objects for instant cache hits
  * on subsequent navigation. Cache key is source-dependent (includes the
  * current page URL) because the server's diff-based response depends on
  * where the user navigates from.
  *
+ * Also tracks in-flight prefetch promises. Each promise resolves to the
+ * navigation branch of a tee'd Response, allowing navigation to adopt a
+ * still-downloading prefetch without reparsing or buffering the body.
+ *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
  */
 
-import { cancelAllPrefetches } from "./queue.js";
+import { abortAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
 
 // Default TTL: 5 minutes. Overridden by initPrefetchCache() with
@@ -44,6 +48,13 @@ interface PrefetchCacheEntry {
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
+/**
+ * In-flight promise map. When a prefetch fetch is in progress, its
+ * Promise<Response | null> is stored here so navigation can await
+ * it instead of starting a duplicate request.
+ */
+const inflightPromises = new Map<string, Promise<Response | null>>();
+
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
 // started before a clear carry a stale generation and must not store their
 // response (the data may be stale due to a server action invalidation).
@@ -78,6 +89,9 @@ export function hasPrefetch(key: string): boolean {
  * Consume a cached prefetch response. Returns null if not found or expired.
  * One-time consumption: the entry is deleted after retrieval.
  * Returns null when caching is disabled (TTL <= 0).
+ *
+ * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
+ * for that (returns a Promise instead of a Response).
  */
 export function consumePrefetch(key: string): Response | null {
   if (cacheTTL <= 0) return null;
@@ -91,10 +105,33 @@ export function consumePrefetch(key: string): Response | null {
   return entry.response;
 }
 
+/**
+ * Consume an in-flight prefetch promise. Returns null if no prefetch is
+ * in-flight for this key. The returned Promise resolves to the buffered
+ * Response (or null if the fetch failed/was aborted).
+ *
+ * One-time consumption: the promise entry is removed so a second call
+ * returns null. The `inflight` set entry is intentionally kept so that
+ * hasPrefetch() continues to return true while the underlying fetch is
+ * still downloading — this prevents prefetchDirect() or other callers
+ * from starting a duplicate request during the handoff window. The
+ * inflight flag is cleaned up naturally by clearPrefetchInflight() in
+ * the fetch's .finally().
+ */
+export function consumeInflightPrefetch(
+  key: string,
+): Promise<Response | null> | null {
+  const promise = inflightPromises.get(key);
+  if (!promise) return null;
+  // Remove the promise (one-time consumption) but keep the inflight flag.
+  inflightPromises.delete(key);
+  return promise;
+}
+
 /**
  * Store a prefetch response in the in-memory cache.
- * The response body must be fully buffered (e.g. via arrayBuffer()) before
- * storing, so the cached Response is self-contained and network-independent.
+ * The response should be a clone() of the original so the caller can
+ * still consume the body. The clone's body streams independently.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).
@@ -136,19 +173,34 @@ export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
 
+/**
+ * Store the in-flight Promise for a prefetch so navigation can reuse it.
+ */
+export function setInflightPromise(
+  key: string,
+  promise: Promise<Response | null>,
+): void {
+  inflightPromises.set(key, promise);
+}
+
 export function clearPrefetchInflight(key: string): void {
   inflight.delete(key);
+  inflightPromises.delete(key);
 }
 
 /**
  * Invalidate all prefetch state. Called when server actions mutate data.
  * Clears the in-memory cache, cancels in-flight prefetches, and rotates
  * the Rango state key so CDN-cached responses are also invalidated.
+ *
+ * Uses abortAllPrefetches (hard cancel) because in-flight responses
+ * may contain stale data after a mutation.
  */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
+  inflightPromises.clear();
   cache.clear();
-  cancelAllPrefetches();
+  abortAllPrefetches();
   invalidateRangoState();
 }