@rangojs/router 0.0.0-experimental.69 → 0.0.0-experimental.6c70a2ab

package/src/router/segment-resolution/fresh.ts

@@ -419,6 +419,10 @@ export async function resolveOrphanLayout<TEnv>(
         deps,
         orphan.shortCode,
       );
+      // Tag as inherited so buildMatchResult can deduplicate when safe
+      for (const s of inheritedLoaders) {
+        s._inherited = true;
+      }
       segments.push(...inheritedLoaders);
     }
   }
@@ -511,6 +515,14 @@ export async function resolveParallelEntry<TEnv>(
       if (handler === undefined) {
         continue;
       }
+      // Pin `_currentSegmentId` to the slot's own id so handle pushes from
+      // inside the slot handler get their own bucket in the HandleStore.
+      // Parent-keying would collapse them into the parent layout's bucket;
+      // the partial-update merge then replaces the parent's bucket on a
+      // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
+      // filterSegmentOrder() retains slot ids so the client preserves them.
+      (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+        `${parentShortCode}.${slot}`;
       const doneParallelHandler = track(
         `handler:${parallelEntry.id}.${slot}`,
         2,
@@ -728,6 +740,7 @@ export async function resolveLoadersOnly<TEnv>(
         for (const seg of inherited) {
           if (!seenIds.has(seg.id)) {
             seenIds.add(seg.id);
+            seg._inherited = true;
             loaderSegments.push(seg);
           }
         }

package/src/router/segment-resolution/revalidation.ts

@@ -89,6 +89,27 @@ function observeStreamedHandler(
   });
 }
 
+/**
+ * Trace a parallel slot that's being force-rendered on a full refetch (client
+ * has no cached state). User revalidate fns are bypassed in this case — see
+ * the call sites for the load-bearing rationale.
+ */
+function traceFullRefetchedParallelSlot(
+  parallelId: string,
+  belongsToRoute: boolean,
+): void {
+  if (!isTraceActive()) return;
+  pushRevalidationTraceEntry({
+    segmentId: parallelId,
+    segmentType: "parallel",
+    belongsToRoute,
+    source: "parallel",
+    defaultShouldRevalidate: true,
+    finalShouldRevalidate: true,
+    reason: "full-refetch",
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Revalidation telemetry helper
 // ---------------------------------------------------------------------------
@@ -346,6 +367,7 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
         for (const seg of inherited.segments) {
           if (!seenIds.has(seg.id)) {
             seenIds.add(seg.id);
+            seg._inherited = true;
             allLoaderSegments.push(seg);
           }
         }
@@ -447,44 +469,30 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
 
     const isFullRefetch = clientSegmentIds.size === 0;
     const isNewParent = !clientSegmentIds.has(entry.shortCode);
-    if (
-      isFullRefetch ||
-      clientSegmentIds.has(parallelId) ||
-      belongsToRoute ||
-      isNewParent
-    ) {
-      matchedIds.push(parallelId);
-    }
+    // Always announce the slot in matchedIds — it's unconditionally appended
+    // to `segments` below, and a segment present in segments but missing from
+    // matched lets the client prune it (then it's missing from clientSegmentIds
+    // on the next request, perpetuating the staleness).
+    matchedIds.push(parallelId);
 
-    const shouldResolve = await (async () => {
-      if (isFullRefetch) {
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: parallelId,
-            segmentType: "parallel",
-            belongsToRoute,
-            source: "parallel",
-            defaultShouldRevalidate: true,
-            finalShouldRevalidate: true,
-            reason: "full-refetch",
-          });
-        }
-        return true;
-      }
+    let shouldResolve: boolean;
+    if (isFullRefetch) {
+      // Client has nothing cached — slot MUST render. User revalidate fns are
+      // bypassed here because returning false would leave the segment blank
+      // with no client-side fallback.
+      traceFullRefetchedParallelSlot(parallelId, belongsToRoute);
+      shouldResolve = true;
+    } else {
+      // For non-empty client sets, consult user revalidate fns. When the slot
+      // is unknown to the client, override the type-derived default so the
+      // soft chain seeds with the right "new segment" / "parent-chain" value.
+      let defaultOverride: { value: boolean; reason: string } | undefined;
       if (!clientSegmentIds.has(parallelId)) {
-        const result = belongsToRoute || isNewParent;
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: parallelId,
-            segmentType: "parallel",
-            belongsToRoute,
-            source: "parallel",
-            defaultShouldRevalidate: result,
-            finalShouldRevalidate: result,
-            reason: result ? "new-segment" : "skip-parent-chain",
-          });
-        }
-        return result;
+        const value = belongsToRoute || isNewParent;
+        defaultOverride = {
+          value,
+          reason: value ? "new-segment" : "skip-parent-chain",
+        };
       }
 
       const dummySegment: ResolvedSegment = {
@@ -502,7 +510,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -518,8 +526,9 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -528,8 +537,11 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     );
 
     let component: ReactNode | undefined;
+    let handlerRan = false;
     if (shouldResolve) {
       component = await tryStaticSlot(parallelEntry, slot, parallelId);
+      // tryStaticSlot returning a value means the static cache supplied the
+      // component — handler did NOT run. handlerRan stays false.
     }
     if (component === undefined) {
       const hasLoadingFallback =
@@ -540,29 +552,37 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         // Handler evicted (production static slot) but static lookup missed.
         // Nothing to render — use null so the client keeps its cached version.
         component = null;
-      } else if (hasLoadingFallback) {
-        const result =
-          typeof handler === "function" ? handler(context) : handler;
-        if (result instanceof Promise) {
-          const tracked = deps.trackHandler(result, {
-            segmentId: parallelId,
-            segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            parallelId,
-            "parallel",
-            context.pathname,
-            routeKey,
-            params,
-          );
-          component = tracked as ReactNode;
+      } else {
+        // Slot-keyed pushes — slot owns its own bucket, parent layout owns
+        // its own. On slot-only revalidations the partial merge updates only
+        // the slot's bucket; the parent's bucket stays intact.
+        (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+          parallelId;
+        handlerRan = true;
+        if (hasLoadingFallback) {
+          const result =
+            typeof handler === "function" ? handler(context) : handler;
+          if (result instanceof Promise) {
+            const tracked = deps.trackHandler(result, {
+              segmentId: parallelId,
+              segmentType: "parallel",
+            });
+            observeStreamedHandler(
+              tracked,
+              parallelId,
+              "parallel",
+              context.pathname,
+              routeKey,
+              params,
+            );
+            component = tracked as ReactNode;
+          } else {
+            component = result as ReactNode;
+          }
         } else {
-          component = result as ReactNode;
+          component =
+            typeof handler === "function" ? await handler(context) : handler;
         }
-      } else {
-        component =
-          typeof handler === "function" ? await handler(context) : handler;
       }
     }
 
@@ -576,6 +596,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       transition: parallelEntry.transition,
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath
@@ -630,6 +651,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
 ): Promise<{ segment: ResolvedSegment; matchedId: string }> {
   const matchedId = entry.shortCode;
 
+  let handlerRan = false;
   const component = await revalidate(
     async () => {
       const hasSegment = clientSegmentIds.has(entry.shortCode);
@@ -706,6 +728,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       return shouldRevalidate;
     },
     async () => {
+      handlerRan = true;
       const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         entry.shortCode;
@@ -787,6 +810,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       ? { layoutName: entry.id }
       : {}),
     ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+    _handlerRan: handlerRan,
   };
 
   return { segment, matchedId };
@@ -867,7 +891,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         true,
         deps,
         actionContext,
@@ -952,7 +975,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         false,
         deps,
         actionContext,
@@ -979,7 +1001,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   prevUrl: URL,
   nextUrl: URL,
   routeKey: string,
-  loaderPromises: Map<string, Promise<any>>,
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
@@ -1036,6 +1057,10 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       orphan.shortCode,
       stale,
     );
+    // Tag as inherited so buildMatchResult can deduplicate when safe
+    for (const s of inheritedResult.segments) {
+      s._inherited = true;
+    }
     segments.push(...inheritedResult.segments);
     matchedIds.push(...inheritedResult.matchedIds);
   }
@@ -1126,6 +1151,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     );
 
     if (!resolvedParallelEntries.has(parallelEntry.id)) {
+      // shortCodeOverride must match the parent layout, not the parallel entry.
       const loaderResult = await resolveLoadersWithRevalidation(
         parallelEntry,
         context,
@@ -1138,7 +1164,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         routeKey,
         deps,
         actionContext,
-        undefined,
+        orphan.shortCode,
         stale,
       );
       segments.push(...loaderResult.segments);
@@ -1160,21 +1186,20 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     const parallelId = `${orphan.shortCode}.${slot}`;
     matchedIds.push(parallelId);
 
-    const shouldResolve = await (async () => {
-      if (!clientSegmentIds.has(parallelId)) {
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: parallelId,
-            segmentType: "parallel",
-            belongsToRoute,
-            source: "parallel",
-            defaultShouldRevalidate: true,
-            finalShouldRevalidate: true,
-            reason: "new-segment",
-          });
-        }
-        return true;
-      }
+    const isFullRefetch = clientSegmentIds.size === 0;
+    let shouldResolve: boolean;
+    if (isFullRefetch) {
+      // Same load-bearing rationale as the main parallel path: full refetch
+      // means the client has nothing to fall back to, so the slot must render.
+      traceFullRefetchedParallelSlot(parallelId, belongsToRoute);
+      shouldResolve = true;
+    } else {
+      // When slot is unknown to the client, seed the soft chain with `true`
+      // (orphan parallels always belong to the route — we want them rendered
+      // unless the user explicitly opts out via revalidate()).
+      const defaultOverride = clientSegmentIds.has(parallelId)
+        ? undefined
+        : { value: true, reason: "new-segment" };
 
       const dummySegment: ResolvedSegment = {
         id: parallelId,
@@ -1191,7 +1216,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1207,8 +1232,9 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -1217,6 +1243,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     );
 
     let component: ReactNode | undefined;
+    let handlerRan = false;
     if (shouldResolve) {
       component = await tryStaticSlot(parallelEntry, slot, parallelId);
     }
@@ -1228,29 +1255,35 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       } else if (handler === undefined) {
         // Handler evicted (production static slot) but static lookup missed.
         component = null;
-      } else if (hasLoadingFallback) {
-        const result =
-          typeof handler === "function" ? handler(context) : handler;
-        if (result instanceof Promise) {
-          const tracked = deps.trackHandler(result, {
-            segmentId: parallelId,
-            segmentType: "parallel",
-          });
-          observeStreamedHandler(
-            tracked,
-            parallelId,
-            "parallel",
-            context.pathname,
-            routeKey,
-            params,
-          );
-          component = tracked as ReactNode;
+      } else {
+        // Slot-keyed pushes — see resolveParallelSegmentsWithRevalidation.
+        (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+          parallelId;
+        handlerRan = true;
+        if (hasLoadingFallback) {
+          const result =
+            typeof handler === "function" ? handler(context) : handler;
+          if (result instanceof Promise) {
+            const tracked = deps.trackHandler(result, {
+              segmentId: parallelId,
+              segmentType: "parallel",
+            });
+            observeStreamedHandler(
+              tracked,
+              parallelId,
+              "parallel",
+              context.pathname,
+              routeKey,
+              params,
+            );
+            component = tracked as ReactNode;
+          } else {
+            component = result as ReactNode;
+          }
         } else {
-          component = result as ReactNode;
+          component =
+            typeof handler === "function" ? await handler(context) : handler;
         }
-      } else {
-        component =
-          typeof handler === "function" ? await handler(context) : handler;
       }
     }
 
@@ -1264,6 +1297,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       transition: parallelEntry.transition,
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath

package/src/router/substitute-pattern-params.ts

@@ -0,0 +1,56 @@
+import { encodePathSegment } from "./url-params.js";
+
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`. Two-pass: optional params (`:name?`) first so absent values
+ * collapse cleanly, then required params (throws on missing). Constraint
+ * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was
+ * actually omitted.
+ *
+ * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
+ * helper), and `useReverse()` (client hook). The behavior must stay
+ * identical across all three call sites.
+ */
+export function substitutePatternParams(
+  pattern: string,
+  params: Record<string, string | undefined>,
+  routeName: string,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      // The matcher omits absent optional params (so `value` is `undefined`
+      // here), but caller-supplied params or `getParams()` shapes may still
+      // pass `""` explicitly. Treat both as the absent form.
+      if (value === undefined || value === "") {
+        hadOmittedOptional = true;
+        return "";
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}

package/src/router/trie-matching.ts

@@ -6,6 +6,7 @@
  */
 
 import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -14,7 +15,9 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
+  /** Optional param names declared on the route. Absent params are omitted
+   * from `params` (read as `undefined`), matching the
+   * `ExtractParams<"/:locale?/...">` type. */
   optionalParams?: string[];
   /** Ancestry shortCodes for layout pruning */
   ancestry: string[];
@@ -173,20 +176,25 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues
+  // Build named params by zipping leaf.pa with positional paramValues.
+  // Params are URL-decoded at this boundary so ctx.params holds the values
+  // apps expect (matching Express/React Router) and round-trip cleanly
+  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
-      params[leaf.pa[i]] = paramValues[i];
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
     }
   }
 
   // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
-    params[(leaf as TrieLeaf & { pn: string }).pn] = wildcardValue;
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints
+  // Validate constraints against decoded values so constraint lists can be
+  // written in decoded form (e.g. ["en-GB", "en US"]).
   if (leaf.cv) {
     for (const paramName in leaf.cv) {
       const allowed = leaf.cv[paramName]!;
@@ -197,14 +205,11 @@ function validateAndBuild(
     }
   }
 
-  // Fill in empty strings for optional params that weren't matched
-  if (leaf.op) {
-    for (const name of leaf.op) {
-      if (!(name in params)) {
-        params[name] = "";
-      }
-    }
-  }
+  // Optional params that weren't matched are left absent from `params` so
+  // `ctx.params.locale` reads as `undefined`, matching the
+  // `ExtractParams<"/:locale?/...">` type (`{ locale?: string }`). Both
+  // internal consumers — the constraint check above and `reverse()` —
+  // already treat missing/undefined as the absent form.
 
   // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;

package/src/router/url-params.ts

@@ -0,0 +1,49 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+// encodeURIComponent over-encodes for path segments. After running it,
+// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
+// keeps human-readable characters that are legal in a path segment.
+// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
+// encoded.
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}

package/src/router.ts

@@ -22,8 +22,7 @@ import type { UrlPatterns } from "./urls.js";
 import type { UrlBuilder } from "./urls/pattern-types.js";
 import { urls } from "./urls.js";
 import {
-  EntryData,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
   RSCRouterContext,
   type MetricsStore,