fix(solid): lazy() drops a loader promise made under hydration tracing (#4013)

[ryansolid]

Requested by Ryan · project thread

Summary

Fixes #4013.

Before: when hydration adopts a server value, it still runs the client compute once as a trace, with the global Promise swapped for the never-settling MockPromise. A lazy() loader that builds its promise from the global Promise (Vite's __vitePreload does) got the stub back, and lazy() cached it for good. Every later .preload() or render then waited forever.

After: lazy() and lazyModule() don't cache a loader promise made while a trace is running, so the next real call loads the module.

How: subFetch keeps an internal tracing depth counter. load() in lazy() and lazyModule() skips caching while tracing is non-zero. A real import() started during the trace still lands through its then(), and the module registry dedupes the next call. lazyModule() had the same caching pattern, so it gets the same guard.

Public API changes

None.

Size

Measured against next @ c9027a9:

• "compiled hydrating": 31,610 → 31,622 B brotli (+12 B, +34 B minified). The cap goes 31.62 → 31.64 KB.
• "hydrating + every store primitive family": 29,440 → 29,506 B brotli (+66 B, +34 B minified). The cap goes 29.50 → 29.52 KB.

Both caps carry Size-Exception notes in scripts/size/scenarios.js, accepted by the maintainer on 2026-10-13. Floor caps are unchanged.

I also tried a smaller variant that compares the global Promise to a captured native one. It grew the compiled CSR scenario by 53 B, so this PR keeps the counter.

How did you test this change?

• packages/solid/test/client-hydration.spec.ts: lazy().preload() and lazyModule() under an adoption trace. Both time out on unmodified next.
• packages/web/test/hydration/lazy-preload-trace-4013.spec.tsx: real hydrate() against a serialized memo that awaits Lazy.preload(). It times out before the fix and passes after.
• Results:
  • solid-js: 858 passed.
  • @solidjs/web client: 1389 passed.
  • @solidjs/web hydrate: 494 passed, plus 16 expected failures.
  • @solidjs/web server: 1651 passed, with 1 failure that also fails on unmodified next (server-functions-adapter-request.spec.tsx, rebuild failure case).
  • Types clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NcUAu8BQ6Xsf8XRBhr9V1w

---

Generated by Claude Code

[github-actions]

Size (brotli, eager entry chunk)

scenario	head	vs base	minified vs base	minified vs recorded	cap		lazy chunks (not counted)
signals: core floor (createSignal/Memo/Effect/Root/flush)	7.47 KB	0 B	0 B	0 B	7.48 KB	✅
signals: + createStore	14.93 KB	0 B	0 B	0 B	14.94 KB	✅
signals: + isPending/latest	9.75 KB	0 B	0 B	0 B	9.77 KB	✅
app: render + one signal (the simple-app floor)	9.97 KB	0 B	0 B	0 B	9.98 KB	✅
app: hydrating (no stores) with Show/For/Loading/Errored/lazy	17.89 KB	−3 B (−0.0%)	+34 B	−43 B	17.93 KB	✅	lazy-page.js 0.04 KB
app: hydrating + every store primitive family	29.51 KB	+66 B (+0.2%)	+34 B	0 B	29.52 KB	✅	lazy-page.js 0.04 KB
app: CSR with Show/For/Loading/Errored/lazy	13.05 KB	0 B	0 B	0 B	13.07 KB	✅	lazy-page.js 0.04 KB
app: CSR, observe tier (same app on the observe artifacts)	14.62 KB	0 B	0 B	0 B	14.64 KB	✅	lazy-page.js 0.04 KB
app: CSR, observe tier + attribution engine enabled	28.98 KB	0 B	0 B	0 B	29.00 KB	✅	lazy-page.js 0.04 KB
app: compiled floor (one template, one text hole, one delegated click)	10.15 KB	0 B	0 B	0 B	10.17 KB	✅
app: compiled CSR (JSX todo app: spread/merge/omit, events, class/style, keyed For, Show, Loading + lazy, store)	25.74 KB	0 B	0 B	0 B	25.75 KB	✅	stats.js 0.18 KB
app: compiled hydrating (the same JSX todo app through hydrate(), compiled hydratable)	31.62 KB	+12 B (+0.0%)	+34 B	0 B	31.64 KB	✅	stats.js 0.20 KB
frames: eager client consumer (frames client + transport, lazy codec)	11.43 KB	0 B	0 B	0 B	11.43 KB	✅
page: base server components (hydrating + dynamic + frames + sf reference)	34.08 KB	−89 B (−0.3%)	+46 B	−1580 B	34.33 KB	✅	assets.js 0.78 KB, bind.js 1.83 KB, decode.js 6.23 KB, lazy-page.js 0.04 KB, regions.js 0.80 KB, trace.js 8.99 KB, wire.js 0.93 KB
page: live server components (base + live/GET + action + isPending/latest)	37.87 KB	−1 B (−0.0%)	+34 B	−1648 B	38.15 KB	✅	assets.js 0.78 KB, bind.js 1.83 KB, decode.js 6.23 KB, lazy-page.js 0.04 KB, regions.js 0.80 KB, trace.js 8.99 KB, wire.js 0.93 KB
page: compiled base server components (the base page as JSX: templates with class/style/attributes/events, For/Show; no spread)	34.92 KB	−29 B (−0.1%)	+34 B	−2670 B	35.66 KB	✅	assets.js 0.78 KB, bind.js 1.83 KB, decode.js 6.23 KB, regions.js 0.80 KB, sc-comments.js 0.20 KB, trace.js 8.95 KB, wire.js 0.93 KB
page: compiled live server components (the compiled base page + live/GET + action + isPending/latest)	40.59 KB	+39 B (+0.1%)	+34 B	−2663 B	41.21 KB	✅	eager (counted): web.js 21.54 KB; assets.js 0.78 KB, bind.js 1.84 KB, decode.js 6.23 KB, regions.js 0.79 KB, sc-comments.js 0.19 KB, trace.js 8.93 KB, wire.js 0.93 KB
page: base + router (base page + @solidjs/router: createRouter, two routes, preload, useNavigate)	41.44 KB	−46 B (−0.1%)	+34 B	−1585 B	41.79 KB	✅	assets.js 0.78 KB, bind.js 1.85 KB, decode.js 6.23 KB, lazy-page.js 0.04 KB, regions.js 0.80 KB, server.js 1.02 KB, serverForms.js 3.58 KB, trace.js 8.98 KB, wire.js 0.94 KB
page: live + router (live page + @solidjs/router: createRouter, two routes, preload, useNavigate)	47.27 KB	+62 B (+0.1%)	+34 B	−1578 B	47.49 KB	✅	eager (counted): client.js 27.75 KB; assets.js 0.78 KB, bind.js 1.84 KB, decode.js 6.23 KB, lazy-page.js 0.04 KB, regions.js 0.81 KB, server.js 1.02 KB, serverForms.js 3.30 KB, trace.js 8.96 KB, wire.js 0.94 KB
server: floor (getRequestEvent + isServer)	1.33 KB	0 B	0 B	0 B	1.34 KB	✅
server: renderToString (the server-render floor)	20.47 KB	0 B	0 B	0 B	20.48 KB	✅

_{Bundled with Rolldown (what Vite ships), brotli q11, decimal KB. A scenario fails only when it is over its brotli cap and its minified size is more than 20 B over the minified recorded with the cap; over the cap within that allowance is brotli layout noise and passes with a warning. Caps and their recorded minified in scripts/size/scenarios.js; the floor and page caps in floor-caps.json are frozen (lower only, or Size-Exception: in the PR body). npm run ratchet lowers caps per RC; it never raises one (scripts/size/README.md).}

[coveralls]

Coverage Report for CI Build 38440116839

Coverage increased (+0.09%) to 77.515%

Details

• Coverage increased (+0.09%) from the base build.
• Patch coverage: 5 of 5 lines across 2 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1326
Covered Lines:	1084
Line Coverage:	81.75%
Relevant Branches:	1040
Covered Branches:	750
Branch Coverage:	72.12%
Branches in Coverage %:	Yes
Coverage Strength:	27.35 hits per line

---

💛 - Coveralls

[ryansolid]

The red Size / check here is "app: compiled hydrating". That scenario is already 31 B over its brotli cap on next (the Size runs for the last three pushes to next are red), and a cap fix for it is being handled separately.

714e79a shrinks this PR's own cost from +56 B to +34 B minified on hydrating scenarios, and CSR stays byte-identical. The guard is now if (tracing) p = undefined, so no load started during a trace is cached, not only the mock stub. A real import() started then still resolves, and the next call reuses the browser's loaded module. 34 B is still above the gate's 20 B minified allowance. Once the cap on next is fixed, this PR needs a recorded +34 B or a trim elsewhere.

— Claude via Claude Code

---

Generated by Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: ee4b6e5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
solid-js	Patch
@solidjs/diagnostics	Patch
@solidjs/element	Patch
@solidjs/h	Patch
@solidjs/html	Patch
test-integration	Patch
@solidjs/universal	Patch
@solidjs/web	Patch
board-example	Patch
todos-server-example	Patch
@solidjs/babel-plugin	Patch
@solidjs/compiler	Patch
@solidjs/signals	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed]

Merging this PR will not alter performance

⚠️ 2 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• readAllowed
• propagation:diamond

✅ 195 untouched benchmarks

---

_{Comparing claude/project-thread-w8qjvi (ee4b6e5) with next (c9027a9)}

[ryansolid]

CodSpeed flags "createStore setter: delete + set one root key" and "mount 4000 rows › memo + sync render effect only" on 714e79a. Both are @solidjs/signals benchmarks, and this PR changes only solid-js's client lazy() and hydration files, so the signals benchmarks run identical code to next. The previous commit here showed no change, the compiler-only #4021 flagged the same two benchmarks, and CodSpeed reports that the compared runs used different runtime environments. I'm re-running the workflow once to confirm.

— Claude via Claude Code

---

Generated by Claude Code