Skip to content

Commit a12b3e6

Browse files
authored
test(ppr): pin the outlined-bake guarantee — ready Suspense content bakes into the shell; masked holes postpone (closes #702) (#703)
Investigation outcome (issue #702): the suspected defect does NOT exist. Control experiments proved the capture already bakes outlined-but-ready content through the real abort path (6.2MB prelude, postponed=null on a bare ppr route; 6.2MB + 1.5KB postponed beside a masked slot hole), and ready fizz work cannot lose the abort race structurally: React's tracked-postpones pings run on scheduleMicrotask while the post-quiesce hops and abort ride setTimeout, so every runnable task drains before the first hop fires. A counted-abort gate would be a no-op for ready work and would BREAK the physics-hole doctrine (parked unmasked I/O must postpone). The original red reproducer was doctrine-inconsistent, not a bug repro: under route-level loading(), LoaderBoundary use()es the masked loader ABOVE the entire route subtree, so the whole body IS the hole — its 30k rows were unreachable at capture (4.5KB prelude), not ready-but-unflushed. React postpones whole Suspense boundaries, so bytes inside a postponed boundary can never ride the prelude. What this PR pins, on the reshaped /shell-cache/outlined fixture (10k-row outlined section BESIDE a masked @outlinedBadge slot hole, never under it): - every outlined row lands in the stored prelude (byte-provenance via splitPrelude, rows 0 and 9999 before the first </html>); - the masked hole still postpones (badge fallback frozen in the prelude, digit-anchored value only in the resumed tail, seq advances per HIT while the prelude stays byte-identical); - dev + production describes both run it. Also documents the microtask-atomicity invariant on the abort hop loop in ssr/index.tsx (comment-only src change) so a work-quiet/counted gate is not re-attempted, and the fixture carries the doctrine clarification: content that must bake belongs beside the hole (slot/layout chrome), not under route-level loading(). Battery: router unit 5052; shell suites 33 dev / 34 production; prerender-ppr 4+4 (producer B composition); cloudflare ppr battery 27 passed (3 pre-existing producer-B dev-boot flakes, untouched files); typecheck/lint/format green.
1 parent f63db7c commit a12b3e6

5 files changed

Lines changed: 189 additions & 1 deletion

File tree

‎packages/rangojs-router/e2e/shell-cache.test.ts‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,10 @@ const LOADER_DELAY_MS = 400;
3939
// outer value resolves fast, the nested pendingData promise settles ~300ms later.
4040
const STREAM_INNER_DELAY_MS = 300;
4141

42+
// Last row index of the /shell-cache/outlined fixture's big section
43+
// (OUTLINED_ROW_COUNT - 1 in test-app/src/urls/shell-cache.tsx).
44+
const OUTLINED_LAST_ROW = 9999;
45+
4246
// The shell cache only engages for HTML document GETs; mayNeedSSR treats a request
4347
// whose Accept omits text/html as RSC and bypasses. Playwright's raw request.get
4448
// defaults to Accept: * / *, so document probes must ask for HTML the way a browser
@@ -904,6 +908,68 @@ function runShellCacheSpec(f: Fixture): void {
904908
expect(second.html).toContain("Exec matrix static chrome");
905909
expect(second.html).toContain("exec badge");
906910
});
911+
912+
// Issue #702: fizz OUTLINES any Suspense boundary over ~500 bytes (fallback
913+
// written inline first, content as a queued task; past progressiveChunkSize
914+
// the completed content is outline-DEFERRED at flush into an out-of-band
915+
// segment + $RC — all prelude bytes). This pins that outlined-but-READY
916+
// content bakes into the STORED shell: fizz's runnable work is microtask-
917+
// atomic relative to the capture's macrotask abort schedule (tracked-
918+
// postpones pings run on scheduleMicrotask; the quiesce hops and abort on
919+
// setTimeout), so ready content of any size flushes before the abort lands.
920+
//
921+
// Structural scar tissue (why the hole is a SLOT): the original reproducer
922+
// put the section under a route-level loading() + loader. That shape can
923+
// NEVER bake the section — LoaderResolver use()es the masked loader promise
924+
// ABOVE the whole route subtree, so at capture nothing below it renders,
925+
// and React postpones whole Suspense boundaries (the fallback owns the
926+
// boundary's DOM slot), so bytes inside the postponed boundary cannot ride
927+
// the prelude. Under loading(), the entire route body IS the hole by
928+
// doctrine; content that must bake belongs BESIDE the hole (slot/layout
929+
// chrome) — the layout-with-loaders playbook.
930+
test("large sync Suspense section bakes into the shell — outlined content flushes before the capture abort", async ({
931+
request,
932+
}) => {
933+
const url = f.url("/shell-cache/outlined?probe=outlined");
934+
await warmToHit(request, url);
935+
936+
// Byte PROVENANCE is the discriminator: the stored prelude ends at the
937+
// first </html> (splitPrelude); the resumed tail (holes + $RC + hydration
938+
// payload) streams after it. Baked = every row inside the prelude; the
939+
// broken shape baked only the fallback and re-streamed the section per
940+
// request (measured on a real storefront: ~2.7MB re-rendered per HIT).
941+
const res = await request.get(url, { headers: HTML_HEADERS });
942+
expect(res.status()).toBe(200);
943+
expect(res.headers()["x-rango-shell"]).toBe("HIT");
944+
const html = await res.text();
945+
const { prelude, resumed } = splitPrelude(html);
946+
947+
expect(prelude).toContain("Outlined row 0<");
948+
expect(prelude).toContain(`Outlined row ${OUTLINED_LAST_ROW}<`);
949+
expect(prelude).toContain('data-testid="outlined-static"');
950+
951+
// The masked slot hole still postpones: the fallback is frozen into the
952+
// prelude, the live value (`outlined-badge-<seq>`, digit-anchored so the
953+
// fallback's own testid can't match) exists only in the per-request
954+
// resumed tail — masked-loader content must never bake.
955+
expect(prelude).toContain("outlined badge pending...");
956+
expect(prelude).not.toMatch(/outlined-badge-\d/);
957+
expect(resumed).toMatch(/outlined-badge-\d/);
958+
959+
// The hole is LIVE: a second HIT serves the identical frozen prelude while
960+
// the badge seq advances (the loader re-ran for this request).
961+
const res2 = await request.get(url, { headers: HTML_HEADERS });
962+
expect(res2.headers()["x-rango-shell"]).toBe("HIT");
963+
const html2 = await res2.text();
964+
const second = splitPrelude(html2);
965+
expect(second.prelude).toBe(prelude);
966+
const seqOf = (body: string): number => {
967+
const m = /outlined-badge-(\d+)/.exec(body);
968+
expect(m, "resumed badge value present").toBeTruthy();
969+
return Number(m![1]);
970+
};
971+
expect(seqOf(second.resumed)).toBeGreaterThan(seqOf(resumed));
972+
});
907973
}
908974

909975
test.describe("shell-cache (dev)", () => {

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,7 @@ export const NamedRoutes = {
333333
shellCacheLayoutLoaderBare: "/shell-cache/layout-loader-bare",
334334
shellCacheNoHole: "/shell-cache/no-hole",
335335
shellCacheNonceToken: "/shell-cache/nonce-token",
336+
shellCacheOutlined: "/shell-cache/outlined",
336337
shellCacheSettled: "/shell-cache/settled",
337338
shellCacheSlotHole: "/shell-cache/slot-hole",
338339
shellCacheSlotUse: "/shell-cache/slot-use",

‎packages/rangojs-router/e2e/test-app/src/urls/shell-cache.defs.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,3 +290,27 @@ export const ShellExecLoader = createLoader(
290290
return { ...shellExecCounters };
291291
},
292292
);
293+
294+
/**
295+
* Render counter for the /shell-cache/outlined fixture. Fizz OUTLINES any
296+
* Suspense boundary over ~500 bytes (fallback written inline first, content
297+
* as a queued task, outline-deferred at flush), so the big section exercises
298+
* the outlined render + flush path end to end. Baked correctly, the section
299+
* renders only during capture; the count riding inside the stored prelude is
300+
* a capture-time snapshot by construction.
301+
*/
302+
export const outlinedRenderCounter: { count: number } = { count: 0 };
303+
304+
// Slot loader for the /shell-cache/outlined fixture's masked hole. Dedicated
305+
// (not ShellBadgeLoader) so its seq is isolated from the slot-hole suite; the
306+
// value advancing across HITs pins that the hole stays LIVE while the outlined
307+
// section beside it is served from the frozen prelude.
308+
let outlinedBadgeSeq = 0;
309+
310+
export const ShellOutlinedBadgeLoader = createLoader(
311+
async (): Promise<string> => {
312+
await new Promise((resolve) => setTimeout(resolve, SHELL_BADGE_DELAY_MS));
313+
outlinedBadgeSeq += 1;
314+
return `outlined-badge-${outlinedBadgeSeq}`;
315+
},
316+
);

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

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { Suspense } from "react";
12
import { urls, Meta, Breadcrumbs, nonce } from "@rangojs/router";
23
import type { HandlerContext } from "@rangojs/router";
34
import { Link, Outlet, ParallelOutlet } from "@rangojs/router/client";
@@ -11,13 +12,15 @@ import {
1112
ShellIdentityLoader,
1213
ShellSettledLoader,
1314
ShellExecLoader,
15+
ShellOutlinedBadgeLoader,
1416
shellExecCounters,
1517
ShellHandles,
1618
makeBakedHandlePush,
1719
makeNestedHandlePush,
1820
makeNestedFastHandlePush,
1921
makePhysicsPromise,
2022
getDriftStamp,
23+
outlinedRenderCounter,
2124
} from "./shell-cache.defs.js";
2225
import { ShellBadge } from "../components/ShellBadge.js";
2326
import { ShellSettledValue } from "../components/ShellSettledValue.js";
@@ -94,6 +97,68 @@ function ShellCachePricePage() {
9497
return <ShellCachePrice loader={ShellPriceLoader} />;
9598
}
9699

100+
// Large SYNCHRONOUS Suspense-wrapped section: fizz outlines any boundary over
101+
// ~500 bytes (fallback inline first, content as a queued task) and, past
102+
// progressiveChunkSize, outline-DEFERS it at flush (placeholder + out-of-band
103+
// segment + $RC — all inside the stored prelude). Big enough that the section
104+
// dominates the capture's fizz work: a capture abort that raced ready-but-
105+
// queued render work would truncate it. Fizz's runnable work is microtask-
106+
// atomic relative to the capture's macrotask abort schedule (tracked-postpones
107+
// pings are scheduleMicrotask; the abort hops are setTimeout), so ready
108+
// content of ANY size flushes before the abort can land — issue #702.
109+
const OUTLINED_ROW_COUNT = 10000;
110+
111+
function OutlinedRows() {
112+
outlinedRenderCounter.count += 1;
113+
const renderCount = outlinedRenderCounter.count;
114+
return (
115+
<div data-testid="outlined-content">
116+
<span data-testid="outlined-render-count">{renderCount}</span>
117+
{Array.from({ length: OUTLINED_ROW_COUNT }, (_, i) => (
118+
<a
119+
key={i}
120+
href={`/shell-cache/outlined#row-${i}`}
121+
className="outlined-fixture-row transition-all duration-150 ease-in-out text-sm tracking-normal font-light border-neutral-200 hover:text-emphasis"
122+
>
123+
{`Outlined row ${i}`}
124+
</a>
125+
))}
126+
</div>
127+
);
128+
}
129+
130+
function ShellOutlinedPage() {
131+
return (
132+
<div>
133+
<p data-testid="outlined-static">Outlined page static</p>
134+
<Suspense
135+
fallback={<div data-testid="outlined-fallback">Loading section...</div>}
136+
>
137+
<OutlinedRows />
138+
</Suspense>
139+
</div>
140+
);
141+
}
142+
143+
// Chrome layout for the outlined fixture: the masked hole is a SIBLING slot
144+
// (@outlinedBadge, own loader + loading()), never an ANCESTOR of the section.
145+
// Structural scar tissue (issue #702): a route-level loading() can NOT host
146+
// this fixture — LoaderBoundary's LoaderResolver use()es the masked loader
147+
// promise ABOVE the route subtree, so during capture nothing below it ever
148+
// renders, and React postpones at Suspense-boundary granularity (the fallback
149+
// occupies the boundary's DOM slot), so content inside the postponed boundary
150+
// can never ride the prelude. Under loading(), the WHOLE route body is the
151+
// hole by construction; static material that must bake belongs beside the
152+
// hole (a slot, layout chrome) — the layout-with-loaders playbook.
153+
function ShellOutlinedChromeLayout() {
154+
return (
155+
<main data-testid="shell-outlined-page">
156+
<ParallelOutlet name="@outlinedBadge" />
157+
<Outlet />
158+
</main>
159+
);
160+
}
161+
97162
// Loader-carried-promise page, reused by BOTH /shell-cache/stream (WITH
98163
// loading(): the LIVE lane — the whole loader value is the hole) and
99164
// /shell-cache/no-hole (NO loading(): the BAKE lane — the outer label bakes
@@ -421,6 +486,33 @@ export const shellCachePatterns = urls(
421486
]),
422487
],
423488
),
489+
// Outlined-boundary fixture (issue #702): a big sync Suspense section
490+
// beside a masked SLOT hole. The hole is a sibling (slot with its own
491+
// loader + loading()), never an ancestor — see ShellOutlinedChromeLayout
492+
// for why a route-level loading() cannot host this shape. Pins that
493+
// outlined-but-ready content bakes into the STORED prelude (green = every
494+
// row before the first </html>) while the masked hole still postpones
495+
// (badge fallback frozen in the prelude, value fresh in the resumed tail
496+
// on every HIT).
497+
layout(ShellOutlinedChromeLayout, () => [
498+
parallel({
499+
"@outlinedBadge": {
500+
handler: () => <ShellBadge loader={ShellOutlinedBadgeLoader} />,
501+
use: () => [
502+
loader(ShellOutlinedBadgeLoader),
503+
loading(
504+
<span data-testid="outlined-badge-fallback">
505+
outlined badge pending...
506+
</span>,
507+
),
508+
],
509+
},
510+
}),
511+
path("/shell-cache/outlined", ShellOutlinedPage, {
512+
name: "shellCacheOutlined",
513+
ppr: { ttl: 300, swr: 120 },
514+
}),
515+
]),
424516
// Settled-marker regression (storefront PDP #438): bake-lane loader whose
425517
// nested promise is already resolved at container return — the snapshot
426518
// pins its value; the HIT overlay must rehydrate a Promise for use().

‎packages/rangojs-router/src/ssr/index.tsx‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -624,7 +624,12 @@ export function createShellCaptureHandler<TEnv = unknown>(
624624
// the now-complete shell and mark the still-pending boundaries as POSTPONED
625625
// rather than errored. Deterministic (the byte set is already frozen and
626626
// the payload is settled), so a fixed count of turns suffices — no
627-
// wall-clock.
627+
// wall-clock. Ready-but-queued fizz render work (however large — a multi-MB
628+
// outlined boundary) can never lose this race: tracked-postpones pings run
629+
// on scheduleMicrotask, so every runnable task drains before the FIRST
630+
// setTimeout hop fires; only tasks parked on genuinely pending promises
631+
// (masked loaders, real per-request I/O) remain, and those are exactly the
632+
// holes that must postpone (issue #702).
628633
for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
629634
await macrotask();
630635
}

0 commit comments

Comments
 (0)