fix(ppr): dev-stability — producer-B first-request-HIT race (#719) + settled-fast hidden-artifact scoping (#718) - #727

Two dev-mode PPR stability fixes for the shell/prerender path, kept as separate commits.

Problem 1 — #719: first-request-HIT contract broke on fast machines

A Prerender+ppr route promises the browser can't tell it was baked: the FIRST request must serve x-rango-shell: HIT with the frozen prelude. In dev that contract was probabilistic. On a fast machine the very first document request served x-rango-shell: MISS (axis-1, the live path) while a later request HIT — so a consumer refreshing a just-started dev server saw a shell miss, then a hit, with no error. It read as "consistent locally, 0-flake on CI" precisely because slow CI arrives after the boot infra has settled, and the tests' warmToHit helper masked it by warming before asserting.

Root cause

The dev /__rsc_shell endpoint boots its capture realm lazily on the first hit: the temp Node server (Cloudflare preset), the registry import, and — on either preset — a Vite dependency re-optimization that the first import of the shell-capture graph can trigger. All three are transient (a retry seconds later succeeds). The read-through (fetchDevShellEntry) fired ONCE and mapped any non-2xx to a hard MISS, so the boot window was conceded as a permanent first-request miss. Fast machines lose that race deterministically because the document request beats the boot infra.

Fix

The endpoint tags only the transient not-ready branches with x-rango-shell-dev: NOT-READY (HTTP 503) — a dep re-optimization catch (ERR_OUTDATED_OPTIMIZED_DEP, or its message when .code is stripped across the workerd RPC boundary), missing runners, and an empty registry. The read-through re-polls ONLY that signal: a bounded await of readiness, 10s deadline / 150ms interval. Every genuine outcome resolves on the first attempt.

Before vs. after (read-through)

// before — one shot, any non-2xx => permanent MISS
const res = await fetch(`${devUrl}/__rsc_shell?${params}`, { signal });
if (!res.ok) return undefined;
return (await res.json()) as BuildShellEntry;

// after — re-poll ONLY the NOT-READY boot-race signal, bounded
for (;;) {
  const res = await fetch(shellUrl, { signal });
  if (res.status === 503 &&
      res.headers.get("x-rango-shell-dev") === "NOT-READY" &&
      Date.now() < readinessDeadline) {
    await sleep(150); continue;
  }
  if (!res.ok) return undefined;         // genuine 404/fault: first attempt
  return (await res.json()) as BuildShellEntry;
}

Zero cost off the boot-race path

Only the last row pays anything, and only until the boot infra settles (normally inside the first poll). A non-baked or already-warm route never stalls the foreground.

Problem 2 — #718: a hidden fizz artifact tripped a strict-mode locator

The *-settled-fast assertions in the shell/ppr settled-value tests intermittently strict-mode-collided on two matching nodes. Not a product bug.

Root cause

When the nested-promise Flight payload fills the dehydrated boundary before the trailing $RC("B:0","S:0") completeSegment script runs — a streaming window that #706's byte-copy fragment splice widens (the baked payload now finishes well ahead of the resume) — React client-renders the boundary in place and $RC leaves fizz's hidden segment container (<div hidden id="S:0">) orphaned as a direct child of <body>. It carries the hidden attribute (invisible, zero layout, out of the a11y tree) but holds a second -settled-fast node, so a bare getByTestId matched both.

Fix

Scope the -label/-fast assertions under the visible settled container (data-testid="shell-settled" in the test-app, ppr-settled in cloudflare-basic); the orphan lives outside it, so the strict-mode locator selects only the in-place copy.

// before — bare testid, strict-mode-collides with the hidden orphan
await expect(page.getByTestId("shell-settled-fast")).toHaveText(/Settled fast \d+/);
// after — scoped to the visible container
const settled = page.getByTestId("shell-settled");
await expect(settled.getByTestId("shell-settled-fast")).toHaveText(/Settled fast \d+/);

Red then green

• Producer B: build-time shell dev tests MISS-then-retry consistently on local runs (dev-boot prerender-phase race?) #719: shell-build-manifest.test.ts — the new re-polls a NOT-READY boot-race signal, then serves once ready test is red on the old one-shot read-through (503 NOT-READY mapped straight to MISS, no first-request HIT), green with the bounded re-poll. The two guard tests pin the zero-cost contract: does NOT re-poll a genuine 404 negative and concedes a MISS when NOT-READY never clears (readiness wait is bounded).
• Flaky: settled-marker fixture intermittently duplicates the *-settled-fast DOM element on a HIT (both apps) #718: reproduced the strict-mode collision 6/6 by widening the $RC delay (forcing the client-render-before-resume window); 1/1 green after the container scope. Confirmed the orphan is once-on-wire (hidden, out of a11y tree).

Release requirement

The endpoint half lives in the Vite plugin, so pnpm build-router is required for dist/vite to reflect src before the plugin serves the NOT-READY signal in a consumer app. (dist is gitignored; the published package carries the built plugin.)

Code-change summary

Commit 1 (#719):

• src/rsc/shell-build-manifest.ts — bounded re-poll loop in fetchDevShellEntry + the DEV_SHELL_NOT_READY / *_DEADLINE_MS / *_POLL_MS constants and the boot-race readiness doc block.
• src/vite/router-discovery.ts — sendNotReady + isReoptimizing on the /__rsc_shell handler; the transient branches now emit NOT-READY.
• src/rsc/__tests__/shell-build-manifest.test.ts — 3 new tests.

Commit 2 (#718):

• e2e/test-app/src/components/ShellSettledValue.tsx — data-testid="shell-settled" container.
• e2e/shell-cache.test.ts, tests/cloudflare-basic/e2e/ppr-shell.test.ts — scoped assertions.

Test plan

• typecheck (root turbo): 16/16 pass.
• unit (packages/rangojs-router vitest): 5144 pass / 6 todo, incl. the 3 new shell-build-manifest readiness tests.
• lint (oxlint --deny-warnings): 0 warnings/errors. format (oxfmt --check): clean.
• pnpm build-router: dist rebuilt so the plugin serves NOT-READY (verified the fold helpers landed in dist/vite/index.js).
• e2e (all green, CI=true so canonical ports):
  • rangojs-router --project=dev --no-deps (prerender-ppr, shell-cache, shell-secure, shell-cache-action): 45 passed.
  • rangojs-router --project=production --no-deps: 45 passed.
  • cloudflare-basic --project=dev (ppr-shell, ppr-tag-eviction): 31 passed.
  • cloudflare-basic --project=production (pulls the unfiltered dev dependency): 333 passed, 2 skipped.

Simplify

Ran the /simplify protocol on the diff; two survivors applied, both in src/vite/router-discovery.ts:

1. Fold the reoptimize-guard. The if (isReoptimizing(err)) { sendNotReady(...); return; } block was pasted at 3 catch sites, and the two entry-import catches were byte-identical (reoptimize then NOT-READY, else 500). Folded into handledAsReoptimizing(err): boolean (shared by all 3) + handleShellImportError(err) (the two import sites). The capture-error site keeps its distinct console.warn + 404 fallback — only the shared guard was hoisted.
2. Altitude comment on isReoptimizing. Noted WHY the message-regex fallback exists alongside the structured .code === "ERR_OUTDATED_OPTIMIZED_DEP" check: .code is stripped when the error serializes across the module-runner/workerd RPC boundary (the message survives), so under the Cloudflare preset .code alone would miss it.

Skipped (with rationale):

• Dev /__rsc_shell endpoint should own a TOTAL response deadline (client fetch bound becomes a plain liveness backstop) #720 (endpoint owns a total response deadline) — the acknowledged server-side follow-up, not in scope here. This PR is the client half (NOT-READY signal + bounded re-poll); Dev /__rsc_shell endpoint should own a TOTAL response deadline (client fetch bound becomes a plain liveness backstop) #720 would move the wait server-side (the endpoint awaits its own readiness up to a bound and always responds within a known envelope), collapsing the 150ms poll into one held request and reducing devShellFetchTimeoutMs to a fixed liveness backstop. Cross-check note added to the issue.
• Other /simplify candidates were cosmetic-only or would have obscured the intent of the readiness doc block; left as-is.