@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.dc2bd2b4

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

@@ -28,11 +28,12 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
   track,
-  RSCRouterContext,
+  RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
@@ -224,7 +225,10 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       belongsToRoute: false,
       layoutName: entry.id,
@@ -359,7 +363,10 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component: component ?? null,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       belongsToRoute: true,
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
@@ -443,7 +450,10 @@ export async function resolveOrphanLayout<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+    ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
@@ -515,6 +525,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,
@@ -557,7 +575,10 @@ export async function resolveParallelEntry<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
       belongsToRoute,
@@ -624,7 +645,7 @@ export async function resolveAllSegments<TEnv>(
     // can guard non-cacheable variable reads. Also guards response-level
     // side effects (headers.set). Persists for all descendant entries.
     if (entry.type === "cache") {
-      const store = RSCRouterContext.getStore();
+      const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
     }
     const doneEntry = track(`segment:${entry.id}`, 1);

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

@@ -39,11 +39,12 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
   track,
-  RSCRouterContext,
+  RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
@@ -89,6 +90,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
 // ---------------------------------------------------------------------------
@@ -448,44 +470,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 = {
@@ -503,7 +511,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -519,8 +527,9 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -529,8 +538,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 =
@@ -541,29 +553,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;
       }
     }
 
@@ -574,9 +594,13 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath
@@ -631,6 +655,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);
@@ -707,6 +732,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;
@@ -781,13 +807,17 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     index: 0,
     component: resolvedComponent,
     loading: entry.loading === false ? null : entry.loading,
-    transition: entry.transition,
+    transition: applyViewTransitionDefault(
+      entry.transition,
+      deps.viewTransitionDefault,
+    ),
     params,
     belongsToRoute,
     ...(entry.type === "layout" || entry.type === "cache"
       ? { layoutName: entry.id }
       : {}),
     ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+    _handlerRan: handlerRan,
   };
 
   return { segment, matchedId };
@@ -868,7 +898,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         true,
         deps,
         actionContext,
@@ -953,7 +982,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         false,
         deps,
         actionContext,
@@ -980,7 +1008,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   prevUrl: URL,
   nextUrl: URL,
   routeKey: string,
-  loaderPromises: Map<string, Promise<any>>,
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
@@ -1117,7 +1144,10 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+    ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
@@ -1166,21 +1196,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,
@@ -1197,7 +1226,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1213,8 +1242,9 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -1223,6 +1253,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     );
 
     let component: ReactNode | undefined;
+    let handlerRan = false;
     if (shouldResolve) {
       component = await tryStaticSlot(parallelEntry, slot, parallelId);
     }
@@ -1234,29 +1265,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;
       }
     }
 
@@ -1267,9 +1304,13 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath
@@ -1328,7 +1369,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
     if (entry.type === "cache") {
-      const store = RSCRouterContext.getStore();
+      const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
     }
     const doneEntry = track(`segment:${entry.id}`, 1);

package/src/router/segment-resolution/view-transition-default.ts

@@ -0,0 +1,36 @@
+/**
+ * View-transition boundary default resolution.
+ *
+ * Kept in its own module (rather than helpers.ts) because several resolution
+ * tests mock helpers.ts with an explicit export list; a shared util here is
+ * never mocked, so the fresh and revalidation paths always get the real
+ * implementation.
+ */
+
+import type { EntryData } from "../../server/context";
+
+/**
+ * Resolve the effective `viewTransition` for a segment's transition config.
+ *
+ * The per-segment value (set via the transition() DSL) always wins. When it is
+ * unset, the router-level createRouter({ viewTransition }) default is stamped
+ * in so the render gate reads the boundary decision off the segment — server
+ * and client, via the serialized segment — without the router option being
+ * threaded to the client. Only `false` is ever stamped; an unset (or "auto")
+ * value is left untouched because it already means "wrap" at the gate, which
+ * also avoids needless object allocation and payload growth. Used by both the
+ * fresh and revalidation resolution paths.
+ */
+export function applyViewTransitionDefault(
+  transition: EntryData["transition"],
+  viewTransitionDefault: "auto" | false | undefined,
+): EntryData["transition"] {
+  if (!transition) return transition;
+  if (
+    transition.viewTransition === undefined &&
+    viewTransitionDefault === false
+  ) {
+    return { ...transition, viewTransition: false };
+  }
+  return transition;
+}

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;
+}