@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.ede38110

package/skills/parallel/SKILL.md

@@ -206,6 +206,65 @@ parallel(
 )
 ```
 
+## Composable Slots via `handler.use`
+
+Slot handlers can carry their own loader, loading, error/notFound boundaries, revalidation, and transition defaults via `.use`. The mount site then declares **just the slot names** — no per-call data wiring.
+
+```typescript
+const CartSummary: Handler = async (ctx) => {
+  const cart = await ctx.use(CartLoader);
+  return <CartSummaryView cart={cart} />;
+};
+CartSummary.use = () => [
+  loader(CartLoader),
+  loading(<CartSkeleton />),
+  revalidate(revalidateCartData),
+];
+
+// Same slot, no copy-pasted plumbing across layouts.
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+
+layout(<AccountLayout />, () => [
+  parallel({ "@cart": CartSummary }),
+  path("/account", AccountIndex, { name: "account.index" }),
+]);
+```
+
+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.
+
+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.
+
+### Two scopes for explicit `use`: shared (broadcast) and slot-local
+
+`parallel({...slots}, () => [...use])` runs the shared `use()` callback **once per slot** ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)) — items in that callback land on every slot's entry. That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`). (Slots cannot bring `middleware` or `layout` — see the allowed-types note above.)
+
+For single-assignment items like `loading()`, broadcasting overwrites every slot's `handler.use` default. Pass a **slot descriptor** `{ handler, use }` instead — items in the descriptor's `use` apply only to that slot:
+
+```typescript
+// @cart gets a custom skeleton; @notifs keeps its handler.use default.
+parallel({
+  "@cart": {
+    handler: Cart,
+    use: () => [loading(<CustomCartSkeleton />)],
+  },
+  "@notifs": Notifs,
+});
+
+// Opt one slot out of streaming while siblings still stream the broadcast.
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] },
+    "@notifs": Notifs,
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+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.
+
 ## Slot Override Semantics
 
 When multiple `parallel()` calls define the same slot name, **the last

package/skills/rango/SKILL.md

@@ -10,28 +10,30 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 
 ## Skills
 
-| Skill              | Description                                                                |
-| ------------------ | -------------------------------------------------------------------------- |
-| `/router-setup`    | Create and configure the RSC router                                        |
-| `/route`           | Define routes with `urls()` and `path()`                                   |
-| `/layout`          | Layouts that wrap child routes                                             |
-| `/loader`          | Data loaders with `createLoader()`                                         |
-| `/middleware`      | Request processing and authentication                                      |
-| `/intercept`       | Modal/slide-over patterns for soft navigation                              |
-| `/parallel`        | Multi-column layouts and sidebars                                          |
-| `/caching`         | Segment caching with memory or KV stores                                   |
-| `/use-cache`       | Function-level caching with `"use cache"` directive                        |
-| `/cache-guide`     | When to use `cache()` vs `"use cache"` — differences and decision guide    |
-| `/document-cache`  | Edge caching with Cache-Control headers                                    |
-| `/theme`           | Light/dark mode with FOUC prevention                                       |
-| `/links`           | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
-| `/hooks`           | Client-side React hooks                                                    |
-| `/typesafety`      | Type-safe routes, params, href, and environment                            |
-| `/host-router`     | Multi-app host routing with domain/subdomain patterns                      |
-| `/tailwind`        | Set up Tailwind CSS v4 with `?url` imports                                 |
-| `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
-| `/mime-routes`     | Content negotiation — same URL, different response types via Accept header |
-| `/fonts`           | Load web fonts with preload hints                                          |
+| Skill                   | Description                                                                |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `/router-setup`         | Create and configure the RSC router                                        |
+| `/route`                | Define routes with `urls()` and `path()`                                   |
+| `/layout`               | Layouts that wrap child routes                                             |
+| `/loader`               | Data loaders with `createLoader()`                                         |
+| `/middleware`           | Request processing and authentication                                      |
+| `/intercept`            | Modal/slide-over patterns for soft navigation                              |
+| `/parallel`             | Multi-column layouts and sidebars                                          |
+| `/caching`              | Segment caching with memory or KV stores                                   |
+| `/use-cache`            | Function-level caching with `"use cache"` directive                        |
+| `/cache-guide`          | When to use `cache()` vs `"use cache"` — differences and decision guide    |
+| `/document-cache`       | Edge caching with Cache-Control headers                                    |
+| `/theme`                | Light/dark mode with FOUC prevention                                       |
+| `/links`                | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
+| `/hooks`                | Client-side React hooks                                                    |
+| `/typesafety`           | Type-safe routes, params, href, and environment                            |
+| `/host-router`          | Multi-app host routing with domain/subdomain patterns                      |
+| `/tailwind`             | Set up Tailwind CSS v4 with `?url` imports                                 |
+| `/response-routes`      | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/mime-routes`          | Content negotiation — same URL, different response types via Accept header |
+| `/fonts`                | Load web fonts with preload hints                                          |
+| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango                              |
+| `/migrate-react-router` | Migrate a React Router / Remix project to Rango                            |
 
 ## Quick Start
 

package/skills/route/SKILL.md

@@ -383,6 +383,30 @@ urls(({ path, layout }) => [
 ])
 ```
 
+## Handler-attached `.use`
+
+Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.
+
+```typescript
+const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <ProductView product={product} />;
+};
+ProductPage.use = () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  middleware(async (ctx, next) => {
+    await next();
+    ctx.header("Cache-Control", "private, max-age=60");
+  }),
+];
+
+// Mount site has no per-page wiring — defaults travel with the handler.
+path("/product/:slug", ProductPage, { name: "product" });
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for the merge order, allowed item types per mount site, and override semantics.
+
 ## Complete Example
 
 ```typescript

package/src/browser/navigation-bridge.ts

@@ -261,18 +261,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -412,6 +418,15 @@ export function createNavigationBridge(
         eventController.abortAllActions();
       }
 
+      // Popstate that exits an intercept to a non-intercept destination. The
+      // fallback fetch path below needs `leave-intercept` mode so it filters
+      // the cached @modal segment from the request and forces a re-render —
+      // otherwise a cache-miss popstate whose server response has an empty
+      // diff hits the "no changes" branch in partial-update and the modal
+      // stays on screen.
+      const isLeavingIntercept =
+        !isIntercept && currentInterceptSource !== null;
+
       // Compute history key from URL (with intercept suffix if applicable)
       const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
@@ -562,7 +577,11 @@ export function createNavigationBridge(
             intercept: isIntercept,
             interceptSourceUrl,
           }),
-          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });

package/src/browser/partial-update.ts

@@ -167,9 +167,16 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // For intercept revalidation, use the intercept source URL as previousUrl
+    // For intercept revalidation, use the intercept source URL as previousUrl.
+    // For leave-intercept, tx.currentUrl captures window.location.href at tx
+    // creation, which on popstate is already the destination URL and would
+    // tell the server "from == to". segmentState.currentUrl still points at
+    // the URL the cached segments render (the intercept URL), which is the
+    // correct "from" for the server's diff computation.
     const previousUrl =
-      interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+      mode.type === "leave-intercept"
+        ? segmentState.currentUrl || tx.currentUrl
+        : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
     debugLog(`\n[Browser] >>> NAVIGATION`);
     debugLog(`[Browser] From: ${previousUrl}`);

package/src/browser/prefetch/fetch.ts

@@ -25,6 +25,23 @@ import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
 import { debugLog } from "../logging.js";
 
+/**
+ * Check if a URL resolves to the current page (same pathname + search).
+ * Used to prevent same-page prefetching with prefetchKey, which would
+ * produce a trivial diff that corrupts the wildcard cache.
+ */
+function isSamePage(url: string): boolean {
+  try {
+    const target = new URL(url, window.location.origin);
+    return (
+      target.pathname + target.search ===
+      window.location.pathname + window.location.search
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Build an RSC partial URL for prefetching.
  * Includes _rsc_segments so the server can diff against currently mounted
@@ -122,7 +139,7 @@ export function prefetchDirect(
   if (!targetUrl) return;
   // Skip same-page prefetch with prefetchKey — a same-page diff is trivial
   // and would corrupt the wildcard cache entry for cross-page navigation.
-  if (prefetchKey != null && targetUrl.pathname === window.location.pathname) {
+  if (prefetchKey != null && isSamePage(url)) {
     return;
   }
   const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
@@ -160,7 +177,7 @@ export function prefetchQueued(
   if (!targetUrl) return "";
   // Skip same-page prefetch with prefetchKey — a same-page diff is trivial
   // and would corrupt the wildcard cache entry for cross-page navigation.
-  if (prefetchKey != null && targetUrl.pathname === window.location.pathname) {
+  if (prefetchKey != null && isSamePage(url)) {
     return "";
   }
   const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
@@ -173,7 +190,6 @@ export function prefetchQueued(
     return key;
   }
   const fetchUrlStr = targetUrl.toString();
-  const targetPathname = targetUrl.pathname;
   enqueuePrefetch(key, (signal) => {
     // Re-check at execution time: a hover-triggered prefetchDirect may
     // have started or completed this key while the item sat in the queue.
@@ -181,7 +197,7 @@ export function prefetchQueued(
     // By execution time, the user may have navigated to the target page.
     // A same-page prefetch produces a trivial diff that would overwrite
     // the useful cross-page entry in the wildcard cache.
-    if (prefetchKey != null && targetPathname === window.location.pathname) {
+    if (prefetchKey != null && isSamePage(url)) {
       return Promise.resolve();
     }
     return executePrefetchFetch(key, fetchUrlStr, signal).then(() => {});

package/src/browser/react/use-navigation.ts

@@ -78,16 +78,17 @@ export function useNavigation<T>(
       if (!shallowEqual(nextSelected, prevState.current)) {
         prevState.current = nextSelected;
 
-        // Check if any actions are in progress for optimistic updates
-        const hasInflightActions =
-          ctx.eventController.getInflightActions().size > 0;
-
-        if (hasInflightActions || publicState.state !== "idle") {
-          // Use optimistic update for immediate feedback during transitions
-          startTransition(() => {
-            setOptimisticValue(nextSelected);
-          });
-        }
+        // Always mirror into the optimistic store inside a transition.
+        // useOptimistic returns the optimistic value while any transition that
+        // includes a setOptimisticValue is pending. Calling it only when
+        // entering "loading" left the optimistic store stuck on the previous
+        // value when going back to "idle" — if a parent transition (e.g., a
+        // <Link> click) was still pending, useOptimistic would keep returning
+        // the stale loading value even after baseValue flipped to idle.
+        // Updating in both directions keeps the optimistic store in sync.
+        startTransition(() => {
+          setOptimisticValue(nextSelected);
+        });
 
         // Always update base state so UI reflects current state
         setBaseValue(nextSelected);

package/src/browser/segment-reconciler.ts

@@ -184,20 +184,16 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
       );
 
-      // For non-action actors: cached segments the server decided not to re-render.
-      // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - Preserve parallel segment loading so renderSegments can reconstruct
-      //   parallel-owned loader markers from the cached slot metadata
-      // - Clear other truthy loading values to prevent suspense on cached content
-      if (actor !== "action") {
-        if (fromCache.type === "parallel" && fromCache.loading !== undefined) {
-          return fromCache;
-        }
-        if (fromCache.loading !== undefined && fromCache.loading !== false) {
-          return { ...fromCache, loading: undefined };
-        }
-      }
-
+      // Return the cached segment as-is, regardless of actor. We used to clear
+      // truthy `loading` here to prevent a stale Suspense fallback from
+      // committing against cached content, but that swapped the render tree
+      // from the LoaderBoundary branch to the plain OutletProvider branch
+      // inside renderSegments, causing React to unmount the entire chain
+      // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
+      // Suspender) every time the user opened an intercept or navigated back
+      // to a cached page. The flicker is now prevented by renderSegments'
+      // promise memoization keeping React's use() in "known fulfilled" state,
+      // so preserving `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/build/route-trie.ts

@@ -98,8 +98,14 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
@@ -107,14 +113,13 @@ function insertRoute(
   index: number,
   leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      paramNames.push(seg.value);
       if (seg.optional) {
         optionalParams.push(seg.value);
       }
@@ -124,21 +129,15 @@ function insertRoute(
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
     ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Recursively insert segments into the trie.
- * For optional params, we add a terminal at the current node (param absent)
- * AND continue inserting into the param child (param present).
- */
 /**
  * Extract ancestry map from a built trie by visiting all leaf nodes.
  * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
@@ -218,15 +217,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -235,12 +244,19 @@ function insertSegments(
   if (segment.type === "static") {
     if (!node.s) node.s = {};
     if (!node.s[segment.value]) node.s[segment.value] = {};
-    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } else if (segment.type === "param") {
     if (segment.optional) {
-      // Optional param: add terminal at current node (param absent)
-      mergeLeaf(node, leaf);
-      // AND continue with param child (param present)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
     if (segment.suffix) {
       // Suffix param: keyed by suffix string (e.g., ".html")
@@ -248,16 +264,26 @@ function insertSegments(
       if (!node.xp[segment.suffix]) {
         node.xp[segment.suffix] = { n: segment.value, c: {} };
       }
-      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     } else {
       if (!node.p) {
         node.p = { n: segment.value, c: {} };
       }
-      insertSegments(node.p.c, segments, index + 1, leaf);
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*",
+    };
     const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
     const merged = mergeLeaves(existing, wildLeaf);
     node.w = merged as TrieLeaf & { pn: string };