Skip to content

Commit 09550a7

Browse files
authored
fix(router): floor the new-segment seed so revalidate() cannot blank an unrendered parallel slot (#814)
A parallel() slot carrying revalidate(() => false) never appeared when the route owning it was reached by soft navigation, while a direct load of the same URL rendered it fine. Reported against tests/vite-rsc-demo: land on /shop/product/:slug, click through to /shop, and the category sidebar stays blank until a full reload. Whether the slot showed up depended on the order the user happened to navigate in. The slot id is absent from the partial request's client-segment set because the product page never rendered it. resolveParallelSegmentsWithRevalidation seeds that case "new-segment" (render it), then passes the seed to evaluateRevalidation, where the user's hard `false` overrode it — emitting component:null for a slot the client had nothing cached to fall back on. The three sibling resolvers (loaders, layout/route entries, orphan layouts) never had this bug because they express the same invariant as an unconditional early return that never consults user predicates. The parallel path cannot copy that shape: #482 deliberately made it consult predicates for an unknown slot so a "skip-parent-chain" seed could still be raised, and because evaluateRevalidation re-throws a Response from a predicate as control flow, an early return would silently drop revalidate(() => { throw redirect(...) }). So the seed is floored rather than short-circuited. defaultOverride gains an optional `floor`; evaluateRevalidation applies it at all three exits through a new local decide(), so predicates still run and may only raise the decision. Applying it inside evaluateRevalidation rather than clamping the returned boolean at the call site keeps the revalidation trace to one entry per segment — an outer clamp pushed a second, contradicting entry, and flushRevalidationTrace buckets by finalShouldRevalidate with no dedup by segmentId, so the slot was counted as both revalidated and skipped and `total` was inflated. revalidate() now means "render once, then never refetch" rather than "sometimes never appear at all". Once the slot is on the client the seed is unfloored and a `false` is honored exactly as before, as are a `true` and a thrown Response in every case. Regression tests proven red before green: parallel-revalidate-fns-invocation.test.ts gains six tests covering the floored seeds (belongsToRoute, isNewParent, orphan force-render, and soft {defaultShouldRevalidate: false}, which exits by a different path than a hard false) plus the two cases that must NOT floor — client already has the slot, and the skip-parent-chain seed — without which "floor to true" could widen into "parallel slots always render". revalidation-trace-pipeline.test.ts gains two tests pinning one trace entry per decision, verified to fail against the double-push shape. Dev and production e2e in three apps: the router test-app and cloudflare-basic (workerd) via a reduced fixture, and vite-rsc-demo driving the reported /shop routes with no new fixture; each has a direct-load control so a broken fixture is distinguishable from a broken soft nav. The client-knowledge seed invariant, previously implicit in five differently shaped code blocks with no name, is now stated in docs/internal/execution-model.md with a table of which resolver uses which shape and why the parallel path diverges. skills/parallel/SKILL.md covers the consumer half. Not done: a general floor adopted by the sibling resolvers. Each would have to start calling evaluateRevalidation unconditionally, invoking user predicates on paths that never have — reversing #482's deliberate sibling audit. No userland test through @rangojs/router/testing either: dispatch is RSC-free by design and rejects partial requests to component routes, and renderRoute is client-only, so no primitive can reach a partial component-route render. Also carries an unrelated test fix. default-prefetch-none's intersection test asserted one /assets/runtime-*.js fetch, but #809 folded the prefetch runtime into the eager router chunk precisely so that fetch would stop happening, making the production assertion unsatisfiable. #809 updated build-test-app.setup.ts and the manual-chunks unit tests but not this assertion, and its merge-time run skipped cloudflare-basic-e2e via path filtering, so it landed unnoticed; main's scheduled runs had been red on it since 2026-07-24. The count is mode-dependent — dev still serves browser/prefetch/runtime.ts as its own unbundled module — so it is flipped to a mode-aware check rather than deleted, turning a stale expectation into a guard for the invariant #809 established.
1 parent 9418275 commit 09550a7

16 files changed

Lines changed: 783 additions & 14 deletions

‎packages/rangojs-router/docs/internal/execution-model.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -660,6 +660,27 @@ should not be treated as equivalent.
660660
outer entry. The consumer-facing ladder is documented in
661661
`skills/rango/SKILL.md` ("Passing data down the tree").
662662

663+
- **First-render guarantee (client-knowledge seed).** A segment absent from the
664+
request's client-segment set (`_rsc_segments`) always renders. The client has
665+
no cached copy of it, so a `false` decision would emit `component: null` and
666+
leave a hole rather than keep anything on screen. Predicates may raise that
667+
decision, never lower it. All four resolvers in
668+
`router/segment-resolution/revalidation.ts` honour it, in two shapes:
669+
670+
| Resolver | Shape |
671+
| ---------------------------------------------------------- | ------------------------------------------------------------ |
672+
| loaders, layout/route entries, orphan-layout entries | early return `true`; user predicates never run |
673+
| parallel slots (`resolveParallelSegmentsWithRevalidation`) | `defaultOverride.floor` — predicates run, but can only raise |
674+
675+
The parallel path differs deliberately. PR #482 made it consult predicates
676+
even for an unknown slot, so a `skip-parent-chain` seed (`false`) could still
677+
be raised to `true`, and so a predicate that throws a `Response`
678+
(`throw redirect(...)`) still performs control flow. Flooring instead of
679+
early-returning keeps both of those while restoring the guarantee. Regressing
680+
it blanks the slot on the navigation that first introduces it while a direct
681+
load looks fine — pinned by `parallel-revalidate-fns-invocation.test.ts`
682+
("new-segment floor") and three dev+production e2e specs.
683+
663684
- During partial action revalidation:
664685
- only revalidated segments recompute
665686
- non-revalidated ancestors do not rerun just to rebuild `ctx.set()` state
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
import { expect, test } from "@playwright/test";
2+
import { useFixture } from "./fixture";
3+
import {
4+
waitForHydration,
5+
expectNoPageError,
6+
expectNoReload,
7+
testId,
8+
} from "./helper";
9+
10+
/**
11+
* revalidate(() => false) on a parallel() slot must not blank the slot on the
12+
* soft navigation that first introduces it. Node dev-server + preview coverage;
13+
* the workerd twin is tests/cloudflare-basic/e2e/parallel-new-slot-reval.test.ts
14+
* and the originally-reported app case is
15+
* tests/vite-rsc-demo/e2e/shop-sidebar-new-slot.test.ts.
16+
*
17+
* Why it happens: src/router/segment-resolution/revalidation.ts (the floored
18+
* `defaultOverride` seed). Fixture: src/urls/parallel-new-slot-reval.tsx.
19+
*/
20+
function defineSpec(label: string, mode: "dev" | "build") {
21+
test.describe(`parallel-new-slot-reval (${label})`, () => {
22+
const f = useFixture({
23+
root: "./e2e/test-app",
24+
mode,
25+
});
26+
27+
test("direct load renders the opted-out slot", async ({ page }) => {
28+
using _ = expectNoPageError(page);
29+
30+
// Control: the slot renders on a document request. If this fails, the
31+
// fixture is broken rather than the soft-nav path.
32+
await page.goto(f.url("/parallel-new-slot-reval/with-slot"));
33+
await waitForHydration(page);
34+
35+
await expect(testId(page, "new-slot-reval-with-slot")).toBeVisible();
36+
await expect(testId(page, "new-slot-reval-panel")).toBeVisible();
37+
});
38+
39+
test("soft nav from a sibling without the slot still renders it", async ({
40+
page,
41+
}) => {
42+
using _ = expectNoPageError(page);
43+
44+
// Land on the sibling that has no @panel — the slot id never enters the
45+
// client's segment set.
46+
await page.goto(f.url("/parallel-new-slot-reval/no-slot"));
47+
await waitForHydration(page);
48+
await using __ = await expectNoReload(page);
49+
50+
await expect(testId(page, "new-slot-reval-no-slot")).toBeVisible();
51+
await expect(testId(page, "new-slot-reval-panel")).toHaveCount(0);
52+
53+
// Soft-navigate to the route that owns the slot. Pre-fix the panel
54+
// stayed blank here.
55+
await testId(page, "new-slot-reval-link-to-with-slot").click();
56+
await expect(testId(page, "new-slot-reval-with-slot")).toBeVisible();
57+
await expect(testId(page, "new-slot-reval-panel")).toHaveText("PANEL");
58+
});
59+
60+
test("slot renders again on re-entry, once the client already knows it", async ({
61+
page,
62+
}) => {
63+
using _ = expectNoPageError(page);
64+
65+
await page.goto(f.url("/parallel-new-slot-reval/no-slot"));
66+
await waitForHydration(page);
67+
await using __ = await expectNoReload(page);
68+
69+
// First entry takes the floored path (slot unknown to the client).
70+
await testId(page, "new-slot-reval-link-to-with-slot").click();
71+
await expect(testId(page, "new-slot-reval-panel")).toHaveText("PANEL");
72+
73+
await testId(page, "new-slot-reval-link-to-no-slot").click();
74+
await expect(testId(page, "new-slot-reval-no-slot")).toBeVisible();
75+
76+
// Re-entry takes the other branch — no floor, the user's `false` is
77+
// honored and the client keeps its copy. Panel must still be on screen.
78+
await testId(page, "new-slot-reval-link-to-with-slot").click();
79+
await expect(testId(page, "new-slot-reval-panel")).toHaveText("PANEL");
80+
});
81+
});
82+
}
83+
84+
defineSpec("dev", "dev");
85+
defineSpec("production", "build");

‎packages/rangojs-router/e2e/test-app/src/router.named-routes.gen.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,8 @@ export const NamedRoutes = {
254254
"parallelMeta.product": "/parallel-meta/:slug",
255255
"parallelMetaStale.index": "/parallel-meta-stale",
256256
"parallelMetaStale.item": "/parallel-meta-stale/:item",
257+
"parallelNewSlotReval.noSlot": "/parallel-new-slot-reval/no-slot",
258+
"parallelNewSlotReval.withSlot": "/parallel-new-slot-reval/with-slot",
257259
"parallelRevalAfterAction.revalAfterActionPageA": "/parallel-reval-after-action/page-a",
258260
"parallelRevalAfterAction.revalAfterActionPageB": "/parallel-reval-after-action/page-b",
259261
"paramsAfterAction.error": "/params-after-action/error/:postId/section/:section",

‎packages/rangojs-router/e2e/test-app/src/urls.tsx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ import { colocatedLoaderPrerenderPatterns } from "./urls/colocated-loader-preren
104104
import { colocatedFastRefreshPatterns } from "./urls/colocated-fast-refresh.js";
105105
import { parallelLoaderRevalPatterns } from "./urls/parallel-loader-reval.js";
106106
import { parallelRevalAfterActionPatterns } from "./urls/parallel-reval-after-action.js";
107+
import { parallelNewSlotRevalPatterns } from "./urls/parallel-new-slot-reval.js";
107108
import { IncludeMwLayout } from "./components/layouts/IncludeMwLayout.js";
108109
import { ShopPlayground } from "./components/ShopPlayground.js";
109110
import {
@@ -1004,6 +1005,12 @@ export const urlpatterns = urls(
10041005
name: "parallelRevalAfterAction",
10051006
}),
10061007

1008+
// Regression: revalidate(() => false) on a route-scoped parallel slot
1009+
// must not blank the slot on the soft nav that first introduces it
1010+
include("/", parallelNewSlotRevalPatterns, {
1011+
name: "parallelNewSlotReval",
1012+
}),
1013+
10071014
// Skip test patterns (prerender + static skip/error handling)
10081015
include("/build-skip", buildSkipPatterns, { name: "buildSkip" }),
10091016

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
import { urls } from "@rangojs/router";
2+
import { Link, Outlet, ParallelOutlet } from "@rangojs/router/client";
3+
4+
/**
5+
* Regression fixture for the floored "new-segment" seed — see the
6+
* `defaultOverride` floor in src/router/segment-resolution/revalidation.ts.
7+
*
8+
* /with-slot owns a ROUTE-scoped @panel carrying revalidate(() => false);
9+
* /no-slot is a sibling under the same layout without it. Arriving from
10+
* /no-slot is the only way to reach /with-slot with @panel absent from the
11+
* request's client segment set, which is what used to blank the slot.
12+
*/
13+
export const parallelNewSlotRevalPatterns = urls(
14+
({ path, layout, parallel, revalidate }) => [
15+
layout(
16+
() => (
17+
<div data-testid="new-slot-reval-layout">
18+
<Outlet />
19+
</div>
20+
),
21+
() => [
22+
path(
23+
"/parallel-new-slot-reval/with-slot",
24+
() => (
25+
<div data-testid="new-slot-reval-with-slot">
26+
<h1>With slot</h1>
27+
{/* Route-scoped slot: the outlet lives in the route's own
28+
subtree, mirroring tests/vite-rsc-demo's ShopIndexRoute. */}
29+
<ParallelOutlet name="@panel" />
30+
<Link
31+
to="/parallel-new-slot-reval/no-slot"
32+
data-testid="new-slot-reval-link-to-no-slot"
33+
>
34+
Go to no-slot
35+
</Link>
36+
</div>
37+
),
38+
{ name: "withSlot" },
39+
() => [
40+
parallel(
41+
{
42+
"@panel": () => (
43+
<div data-testid="new-slot-reval-panel">PANEL</div>
44+
),
45+
},
46+
// The exact opt-out that used to blank the slot.
47+
() => [revalidate(() => false)],
48+
),
49+
],
50+
),
51+
52+
path(
53+
"/parallel-new-slot-reval/no-slot",
54+
() => (
55+
<div data-testid="new-slot-reval-no-slot">
56+
<h1>No slot</h1>
57+
<Link
58+
to="/parallel-new-slot-reval/with-slot"
59+
data-testid="new-slot-reval-link-to-with-slot"
60+
>
61+
Go to with-slot
62+
</Link>
63+
</div>
64+
),
65+
{ name: "noSlot" },
66+
),
67+
],
68+
),
69+
],
70+
);

‎packages/rangojs-router/skills/parallel/SKILL.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -374,6 +374,16 @@ A `revalidate()` callback may return a hard `boolean`, a soft
374374
for the full contract — it's the same across `loader()`, `path()`,
375375
`layout()`, `parallel()`, and `intercept()`.
376376

377+
`revalidate()` decides whether to _re_-render a slot, never whether to render
378+
it the first time. A slot the browser has not rendered yet has nothing cached
379+
to keep showing, so returning `false` for it would just leave a hole. On that
380+
first render the decision is clamped to `true` and your callback's `false` is
381+
ignored; from the second visit onward it is honored and the browser keeps the
382+
copy it already has. This is what makes `revalidate(() => false)` mean "render
383+
once, then never refetch" rather than "sometimes never appear at all" — before
384+
the clamp, landing on a sibling route and navigating in left the slot blank
385+
until a full reload.
386+
377387
### Revalidation Contracts for Parallel Dependencies
378388

379389
Prefer named revalidation contracts shared by both the upstream producer and

0 commit comments

Comments
 (0)