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

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

package/src/router/telemetry.ts

@@ -90,6 +90,34 @@ export interface HandlerErrorEvent extends BaseEvent {
   params?: Record<string, string>;
 }
 
+/**
+ * Per-segment (or coarse route-level) cache status carried on the
+ * cache.decision telemetry event and the X-Rango-Cache debug header.
+ *
+ * v1 is COARSE: the router's pipeline tracks cache decisions at the
+ * route/entry level (cacheHit/cacheSource/shouldRevalidate), not per
+ * individual segment. The `segments` array therefore contains a single
+ * route-level entry keyed by the route key. The shape is forward-compatible
+ * with genuine per-segment status if the pipeline later exposes it.
+ */
+export type CacheSegmentStatus =
+  | "hit"
+  | "miss"
+  | "stale"
+  | "prerendered"
+  | "passthrough";
+
+export interface CacheSegmentSignal {
+  /** Segment id (v1: the route key, since status is route-level). */
+  id: string;
+  /** Segment type (v1: "route" for the coarse route-level entry). */
+  type: string;
+  /** Resolved cache status for this segment. */
+  cacheStatus: CacheSegmentStatus;
+  /** Whether stale-while-revalidate was triggered for this segment. */
+  shouldRevalidate?: boolean;
+}
+
 export interface CacheDecisionEvent extends BaseEvent {
   type: "cache.decision";
   pathname: string;
@@ -98,6 +126,12 @@ export interface CacheDecisionEvent extends BaseEvent {
   /** Whether stale-while-revalidate was triggered */
   shouldRevalidate: boolean;
   source?: "runtime" | "prerender";
+  /**
+   * Optional per-segment (v1: coarse route-level) cache status. Present only
+   * when telemetry or the debug cache signal is enabled. Optional so existing
+   * sinks are unaffected.
+   */
+  segments?: CacheSegmentSignal[];
 }
 
 export interface RevalidationDecisionEvent extends BaseEvent {
@@ -140,6 +174,71 @@ export type TelemetryEvent =
   | RequestTimeoutEvent
   | OriginCheckRejectedEvent;
 
+// ---------------------------------------------------------------------------
+// Cache signal derivation (coarse, route-level)
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the coarse, route-level cache status from pipeline cache state.
+ *
+ * v1 mapping (route-level — see CacheSegmentSignal):
+ *   - prerender hit                         -> "prerendered"
+ *   - runtime hit + shouldRevalidate (SWR)  -> "stale"
+ *   - runtime hit                           -> "hit"
+ *   - no hit                                -> "miss"
+ *
+ * Note: "passthrough" is a build-time prerender concept (a route opts out of
+ * being prerendered for some params). At runtime a passthrough route renders
+ * fresh and is indistinguishable from a normal miss in the pipeline state, so
+ * v1 reports it as "miss". The "passthrough" status remains in the type union
+ * for forward compatibility.
+ */
+export function deriveCacheStatus(state: {
+  cacheHit: boolean;
+  cacheSource?: "runtime" | "prerender";
+  shouldRevalidate?: boolean;
+}): CacheSegmentStatus {
+  if (state.cacheHit) {
+    if (state.cacheSource === "prerender") return "prerendered";
+    if (state.shouldRevalidate) return "stale";
+    return "hit";
+  }
+  return "miss";
+}
+
+/**
+ * Build the coarse route-level cache signal array (a single entry keyed by
+ * the route key). Used for both the cache.decision telemetry event and the
+ * X-Rango-Cache debug header.
+ */
+export function buildCacheSignalSegments(
+  routeKey: string,
+  state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+  },
+): CacheSegmentSignal[] {
+  return [
+    {
+      id: routeKey,
+      type: "route",
+      cacheStatus: deriveCacheStatus(state),
+      shouldRevalidate: !!state.shouldRevalidate,
+    },
+  ];
+}
+
+/**
+ * Serialize cache signal segments into the X-Rango-Cache header value:
+ * `<segId>=<status>, <segId2>=<status2>`.
+ */
+export function formatCacheSignalHeader(
+  segments: CacheSegmentSignal[],
+): string {
+  return segments.map((s) => `${s.id}=${s.cacheStatus}`).join(", ");
+}
+
 // ---------------------------------------------------------------------------
 // Sink interface
 // ---------------------------------------------------------------------------