feat(loaders): streaming loader data with implicitly-suspending useLoader - #813

The gated demo exposed a flaw in the first spike commit: LoaderResolver
derived per-loader promises by splitting the aggregate
(aggregate.then(r => r[i])), but Promise.all resolves at the SLOWEST
loader, so every derived promise inherited the slowest timing — a 400ms
loader's content held until its 2000ms sibling resolved and loading()
routes lost per-loader granularity entirely (measured: whole gated page
at +2032ms; after the fix the route reveals at +413ms and the slow card
fills at +2014ms).

loading() segments now pass per-loader streams built from the individual
loader.loaderData refs at the producer (segment-system), the same channel
the no-loading() branch uses. LoaderResolver pass-through engages only
when streams are provided; without them the pre-spike resolve-above
behavior is restored — parallel/intercept slots (aggregate-only on
ResolvedSegment) and zero-loader boundaries take that path again, which
also restores the fresh-promise suspension that makes SSR emit the
loading() fallback for content-suspending routes.

/suspense-demo — no loading(), three loaders (400/1200/2000ms): the hero
paints immediately and each card suspends on its own useLoader read
inside its own Suspense boundary, filling as its loader streams in.
Verified in-browser on soft nav: cards painted 800ms apart, matching the
loader stagger exactly. On main this route shape blocks the whole tree
build on the slowest loader.

/suspense-demo/gated — the contrast: route-level loading() holds the
page until the unwrapped 400ms read resolves, then the wrapped 2000ms
report keeps filling behind its local skeleton (painted 1600ms after
stats, verified in-browser). loading() is plain JSX deliberately — a
client-component fallback that suspends cold is a known SSR-emission
divergence on this branch.

/suspense-demo/ppr — ppr + loading(). The renderable loading() puts all
three loaders in the LIVE lane (entryLoadingMasksLoaders): the capture
masks them with never-resolving promises, and with read-site suspension
each masked stream postpones at its card's OWN consumer Suspense
boundary — the frozen shell holds the hero plus three skeletons as three
separate holes (finer than main's single LoaderBoundary hole). Verified
against the dev shell store: x-rango-shell HIT, byte-level timing shows
the cached shell's first bytes at ~40ms with holes filling live at
~400/1200/2000ms per loader, and loaders re-run fresh on every HIT
(servedAt advances per request — nothing bakes).

CONTRACT CHANGE, paired with read-site useLoader suspension: the
loading()-keyed lane trigger is gone. At shell capture every route loader
is masked (never executes); its pending stream suspends the consumer's
own Suspense boundary and prerender postpones it as a hole — holes form
at inline boundary granularity with no loading() required. Baking route
data into a shell is expressed via cache()/"use cache", not by omitting
loading(). loading() is now pure UX sugar (a route-level boundary), still
useful for async RSC route components whose suspension is above their own
JSX.

The bake-at-capture path (execute + nested-thenable mask + snapshot
pinning + HIT seed overlay) is bypassed: no records register, the overlay
is a no-op, every HIT runs loaders fresh. A masked reader with NO
boundary above it root-postpones and the <body> sanity gate refuses the
shell (runtime render + the existing eternal-MISS warning) — the intended
degrade for boundary-less ppr routes.

Demonstrated on cloudflare-basic /suspense-demo/ppr with NO loading():
MISS captures a shell whose first HIT bytes land ~10ms carrying hero +
three skeletons, holes fill live at ~400/1200/2000ms per loader, servedAt
advances every request (nothing bakes). Dropping loading() WITHOUT this
flip was measured first: loaders executed at capture and card values
froze into the shared shell, plus a hydration mismatch between the frozen
markup and the fresh hydration payload — the footgun this contract
removes.

Unit pins updated to the new contract: loader-mask-capture (no-loading()
entry now masks, loader never called), shell-capture-barrier-isolation
(capture never executes route loaders; barrier isolation still pinned via
handler pushes and own-property lifecycle). E2e bake-lane fixtures
(ppr-bake, /ppr-shell/no-hole negative, loader-container-bake pins,
consumption-lane rows involving DSL-loader baking) are known-divergent —
to be updated with the semantic matrix when this contract is adopted.

…Suspense only

/suspense-demo/ppr now has NO loading(): under the live-at-capture
contract the three inline consumer Suspense boundaries are the holes.
Shell HIT first bytes ~10ms with hero + three skeletons, live fills at
~400/1200/2000ms, fresh servedAt per request.

Also fixes a hydration hazard in the demo cards: paintedAt rendered
performance.now() during SSR, which can never match the client and
guaranteed a hydration text mismatch on every route. The stamp is now
client-only (useEffect), SSR renders a stable placeholder.

The route-level loading() boundary made every same-route re-render swap
the whole product page for the skeleton — visibly on ?tab= navigations,
where the handler re-runs to render the other tab while BOTH loaders and
the route predicate are revalidate-false (nothing refetches; only the
content promise is fresh). Without loading() the commit holds the
current content until the new tab's content is ready — no flash. This is
the recommended shape under read-site useLoader suspension: inline
Suspense at actual data reads, transition() for animated holds,
route-level loading() reserved for a deliberate first-paint skeleton.

…oute"

This reverts commit e6a074d.

<Outlet fallback={...}> wraps the outlet position in a plain Suspense
boundary: the layout that renders the hole declares its placeholder, with
no DSL wiring and no segment-resolution threading. Works for the default
outlet and named slots; an explicit prop wins over the child segment's
loading() at the outlet wrap, while a child's own loading() boundary
still sits closer to its suspension and wins for its content.

Under read-site useLoader suspension this is the natural home for
pending UI — the doctrine is use(whatWeWaitFor) at consumption sites
with boundaries where waiting should show, and the outlet is the
layout's boundary. Handler awaits remain pipeline-blocking by contract
(redirect/404/meta authority): this fallback covers loader latency and
streamed content, not handler latency — measured on main, no pending UI
has ever covered handler awaits (2s blank then a 41ms skeleton cameo on
the document lane).

vite-rsc-demo's ShopLayout adopts it as the demo usage; the product
route keeps its loading({ssr:true}) canary unchanged.

Experimental (this branch): ParallelOutlet parity, unit coverage, and
docs land when the API graduates.

…apture contract

Mirrors the test-app pin rework: /ppr-shell/no-hole and /settled pin
eternal-MISS (boundary-less readers, capture refuses, axis 1 fresh);
/ppr-shell/bake-slow pins the LIVE advancing label (no pin-first).

Fixture updates to the new-contract shape, preserving each test's
intent: /ppr-shell/inline-action gains loading() (the page hole the
bound action streams through — the bake lane can no longer produce its
shell; MISS/HIT/partial-replay all green); cache-lab wraps the pulse
reader in its own Suspense (products still bake via the handler,
pulse holes live — all four cache-lab tests green).

Full production suite: 419 passed; the 2 remaining failures are
pre-existing on main (verified by base runs: default-prefetch-none
offscreen-intersection fails 3/3 on main; location-state
history-restore flakes ~50% on main with a hidden-boundary restore
window) — tracked separately, not part of this branch.

CI on 3bf4bf6 surfaced the two fixture mirrors the local sweep missed:

- test-app /inline-bound-action gains loading() (the page hole the bound
  action streams through) — same shape as the cloudflare-basic twin;
  dev + production suites 3/3 each locally.
- vercel-basic CacheLabPage wraps its pulse reader in Suspense — same
  shape as the cloudflare-basic cache-lab; full suite 24/24 locally.

With these, the only remaining red CI job is cloudflare-basic
production shard 1's default-prefetch-none offscreen-intersection
test, which is pre-existing: main's own CI fails on exactly that job
(runs 30143307549/30065784608 on 486c400), and the test fails 3/3 on
a local main checkout.