@rangojs/router 0.0.0-experimental.90 → 0.0.0-experimental.91

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.90",
+  version: "0.0.0-experimental.91",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.90",
+  "version": "0.0.0-experimental.91",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,6 +132,15 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
   "dependencies": {
     "@vitejs/plugin-rsc": "^0.5.23",
     "debug": "^4.4.1",
@@ -143,12 +152,12 @@
     "@playwright/test": "^1.49.1",
     "@types/debug": "^4.1.12",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
@@ -166,13 +175,5 @@
     "vite": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
   }
-}
+}

package/src/router/revalidation.ts

@@ -59,6 +59,14 @@ interface EvaluateRevalidationOptions<TEnv> {
   stale?: boolean;
   /** Trace source hint for the revalidation trace */
   traceSource?: RevalidationTraceEntry["source"];
+  /**
+   * Override the segment-type-derived default. When set, the value is used as
+   * the seed `defaultShouldRevalidate` passed to user revalidate fns and the
+   * reason flows into the trace. Callers use this when client-knowledge
+   * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
+   * instead of the params/method-based heuristic.
+   */
+  defaultOverride?: { value: boolean; reason: string };
 }
 
 /**
@@ -81,6 +89,7 @@ export async function evaluateRevalidation<TEnv>(
     actionContext,
     stale,
     traceSource,
+    defaultOverride,
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
@@ -110,7 +119,12 @@ export async function evaluateRevalidation<TEnv>(
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
-  if (request.method === "POST") {
+  if (defaultOverride) {
+    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
+    // Skip the type-derived heuristic — caller knows better in this context.
+    defaultShouldRevalidate = defaultOverride.value;
+    defaultReason = defaultOverride.reason;
+  } else if (request.method === "POST") {
     // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
       // Route segment always revalidates on actions

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
 // ---------------------------------------------------------------------------
@@ -448,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 = {
@@ -503,7 +510,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -519,8 +526,9 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -868,7 +876,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         true,
         deps,
         actionContext,
@@ -953,7 +960,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         false,
         deps,
         actionContext,
@@ -980,7 +986,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   prevUrl: URL,
   nextUrl: URL,
   routeKey: string,
-  loaderPromises: Map<string, Promise<any>>,
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
@@ -1166,21 +1171,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 +1201,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1213,8 +1217,9 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,