Skip to content

Commit c59aa65

Browse files
ryansolidClaude via Cursor
andcommitted
fix(solid): hybrid memo/signal handoff waits for the landing and opens no pending window (#3574 shape)
The memo-shaped hybrid takeover in hydrateSignalLike (#2993) — createMemo(async function*…, { ssrSource: "hybrid" }) and function-form createSignal — flipped its gate at CREATION: the client generator re-ran immediately as a fresh flight, ahead of the still-pending server answer, superseding the server flight (the #3499 shape #3551 fixed for stores) and reading pending from creation until the client's first yield. Over a streamed <Loading> that reproduced #3574 exactly: the boundary resuming to claim its fragment saw a pending source, selected its fallback, and tried to claim it against the resolved server content — `Hydration key miss for "210"`, the `_hk=2000` span replaced instead of claimed, and `shown = ["loading","true:0","loading","true:0","true:10"]`. The handoff now follows the store's rules 1–5 on the store's helpers: adoptedAnswerStream lands the pending answer as a one-yield stream whose second pull flips the gate (rule 1 — the server flight is not superseded before it lands); the handoff run is wrapFirstYield over the client generator with the node's `prev` — the adopted answer — as the quiet value for steps 0 and 1 (rule 5; the duplicate lands as an equal write; wrapFirstYield gains an optional `quiet` parameter, one helper for both adapters); a rejected server answer is adopted and transfers authority without a handoff run (rule 3); a dependency change before the landing supersedes the answer (rule 4). Sync and promise-shaped hybrid computes keep their creation flip and adopt-the-serialized-value semantics unchanged. Tests: web server→artifact→hydrate pair for the memo-shaped #3574 fixture (createMemo and createSignal(fn), generator and promise sources, streamed and loaded), and a solid handoff spec pinning rules 1–5 for both families (client generator starts counted before/after the landing, fresh boundary + isPending during the handoff, rejection paths, rule-4 supersession, client-only mount unchanged). Size: hydrating (no stores) 20,781 -> 20,843 B (+62), cap 20.80 -> 20.85 KB; hydrating + every store family 30,985 -> 31,134 B (+149), cap 31.1 -> 31.15 KB. Refs #3574 #3593 #3551 #2993 Co-authored-by: Claude via Cursor <[email protected]>
1 parent cf61b8e commit c59aa65

12 files changed

Lines changed: 1315 additions & 41 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"solid-js": patch
3+
---
4+
5+
Hybrid memo/signal handoff waits for the server answer to land and opens no pending window. An `ssrSource: "hybrid"` `createMemo` or function-form `createSignal` over an async generator re-ran the client generator at creation — a fresh flight ahead of the still-pending server answer, superseding it and reading pending from creation until the client's first yield — so a streamed `<Loading>` resuming to claim its fragment after the answer landed selected its fallback against resolved server content: a "Hydration key miss" warning and a flash of the fallback over the streamed content (the #3574 failure, on the value-shaped takeover). The handoff now follows the store's rules (#3551, #3593): it waits for the adopted answer to land, lands that answer as the handoff stream's synchronous first step, discards the client's duplicate first yield, adopts a rejected server answer, and is superseded by a dependency change before the landing. The node reads settled through the handoff, and `isPending` is false for it, until the client generator produces something new. Sync and promise-shaped hybrid computes are unchanged.

‎documentation/solid-2.0/05-async-data.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ Because async lives in ordinary computations, SSR/hydration policy is a per-prim
189189
**`ssrSource`** is the hydration policy: what initial value the client uses, and whether the compute re-runs.
190190

191191
- `"server"` _(default)_ — the client uses the serialized server value as its initial state. The compute does **not** re-run for the initial value; the serialized result is authoritative. Choose this when the compute is deterministic from server-available inputs — the common data-fetch case, where it means no duplicate fetch on load.
192-
- `"hybrid"` — the client seeds from the serialized server value, then re-runs the compute to take over. Choose this for computes that mix server data with client-only signals (window size, user locale). For function-form stores the takeover is the tail of the initial load, not a refetch: the store reads settled through it — `isPending` is `false`, and a `<Loading>` created in that window shows content — until the re-run produces something new.
192+
- `"hybrid"` — the client seeds from the serialized server value, then re-runs the compute to take over. Choose this for computes that mix server data with client-only signals (window size, user locale). For function-form stores, and for memos and function-form signals over an async generator, the takeover is the tail of the initial load, not a refetch: it waits for the server answer to land, and the node reads settled through it — `isPending` is `false`, and a `<Loading>` created in that window shows content — until the re-run produces something new.
193193
- `"client"` — skip the server value entirely. On the server the compute never runs (an owner is still created so hydration ids stay aligned); on the client it is deferred until hydration completes, then runs as if first-mounted. Choose this for client-only state where serialization is meaningless. What the server renders in the compute's place is the author's choice of channel:
194194
- **Bare (structural)** — with no declaration, the source is a hole the server can never fill. Reads suspend _finally_: the nearest `Loading` boundary flushes its fallback into the HTML and hands the position to the client, which renders the content fresh after hydration. Read outside a `Loading` boundary this is a render error (the stream would otherwise hang), so bare client sources must sit under a boundary.
195195
- **Declared (`loadingValue` / `seedLoadingValue`, above)** — the server renders the declared first paint instead of suspending; the client serves the same value while hydrating, then runs the compute. `loadingValue: undefined` is a valid declaration — put the `undefined` in the type and branch on it; store-family sources declare `seedLoadingValue: true` (the seed is what the pre-compute window renders).

‎packages/solid/src/client/hydration.ts‎

Lines changed: 113 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -437,9 +437,9 @@ function readSerializedOrCompute(compute: (prev: any) => any, prev: any, options
437437
// hydration is `done`, always compute.
438438
if (sharedConfig.done || !sharedConfig.has!(o.id!)) return compute(prev);
439439
// Divergence arming is a "server"/default-mode contract only: the hybrid
440-
// signal-like wrapper runs this path under withHydrationGate, whose
441-
// synchronous flip guarantees one internal re-entry that is not user
442-
// divergence — and hybrid's sync/promise flavor deliberately latches
440+
// signal-like wrapper runs this path behind a gate whose creation flip (for
441+
// the sync/promise shapes) guarantees one internal re-entry that is not
442+
// user divergence — and hybrid's sync/promise flavor deliberately latches
443443
// (re-running its compute at done would clobber the adopted value).
444444
if (latchedOnce.has(o)) {
445445
if (options?.ssrSource !== "hybrid") armLiveTakeover();
@@ -642,10 +642,16 @@ function createShadowDraft(realDraft: any, shallow?: boolean) {
642642
* before. Without the quiet step the store read pending from the handoff
643643
* until that yield, and any consumer created in between — a streamed
644644
* `<Loading>` resuming to claim its fragment — selected its fallback against
645-
* resolved server content (#3574). A bare `yield` commits the draft as-is,
646-
* so step 0's `undefined` keeps the adopted answer.
645+
* resolved server content (#3574).
646+
*
647+
* `quiet` is what steps 0 and 1 yield — the adopted answer in the node's own
648+
* terms. A store yields `undefined`: a bare `yield` commits the draft as-is,
649+
* and the duplicate's writes went to the shadow draft (`activate` switches
650+
* the proxy to the real draft once they have). A signal-shaped node
651+
* (hydrateSignalLike) yields the adopted value itself — its `prev` — so the
652+
* duplicate lands as an equal write, a no-op at the node.
647653
*/
648-
function wrapFirstYield(iterable: any, activate: () => void) {
654+
function wrapFirstYield(iterable: any, activate?: () => void, quiet?: any) {
649655
const srcIt = iterable[Symbol.asyncIterator]();
650656
let step = 0;
651657
return {
@@ -654,15 +660,15 @@ function wrapFirstYield(iterable: any, activate: () => void) {
654660
next() {
655661
if (step === 0) {
656662
step = 1;
657-
return syncThenable({ done: false, value: undefined });
663+
return syncThenable({ done: false, value: quiet });
658664
}
659665
const p = srcIt.next();
660666
if (step === 1) {
661667
step = 2;
662-
// The source's first yield: its writes went to the shadow draft.
668+
// The source's first yield, the duplicate.
663669
return p.then((r: any) => {
664-
activate();
665-
return r.done ? r : { done: false, value: undefined };
670+
activate?.();
671+
return r.done ? r : { done: false, value: quiet };
666672
});
667673
}
668674
return p;
@@ -703,13 +709,14 @@ function quietAnswer(thenable: any) {
703709
}
704710

705711
/**
706-
* A hybrid store's still-pending server answer, adopted as a ONE-yield stream
707-
* (#3498). The hybrid contract is that the server consumes exactly one yield
708-
* and the client continues the iteration — this is that first yield, and
709-
* the engine's pull for the next one is the handoff.
712+
* A hybrid node's still-pending server answer, adopted as a ONE-yield stream
713+
* (#3498; store and signal-shaped alike). The hybrid contract is that the
714+
* server consumes exactly one yield and the client continues the iteration —
715+
* this is that first yield, and the engine's pull for the next one is the
716+
* handoff.
710717
*
711718
* Why a stream and not the thenable itself: the handoff must run only once
712-
* the answer has actually LANDED in the store. This relies on the engine's
719+
* the answer has actually LANDED in the node. This relies on the engine's
713720
* flight contract — latest-run-wins supersession (PJ-R26 in the signals
714721
* RULES-INDEX; flight-identity cancellation, #3122): `handleAsync` pulls a
715722
* stream's next step only from the previous step's commit (`asyncWrite`'s
@@ -1126,11 +1133,12 @@ export function materializeContainerTrace(marker: {
11261133
// --- Hydration-aware implementations ---
11271134

11281135
// The shared pre-hydration gate lifecycle for the ssrSource branches
1129-
// (signal × client/hybrid, store × client): create the node with a compute
1130-
// that branches on the gate, then flip it — the flip's recompute is the
1131-
// node's first real run. `ownedWrite` because the write happens inside the
1132-
// node's own creation scope. (The hybrid STORE branch flips its own gate at
1133-
// the adopted answer's landing instead — see hydrateStoreLikeFn, #3498.)
1136+
// (signal × client, store × client): create the node with a compute that
1137+
// branches on the gate, then flip it — the flip's recompute is the node's
1138+
// first real run. `ownedWrite` because the write happens inside the node's
1139+
// own creation scope. (The hybrid branches flip their own gate at the
1140+
// adopted answer's landing instead — see hydrateStoreLikeFn, #3498, and
1141+
// hydrateSignalLike's hybrid branch.)
11341142
function withHydrationGate(create: (hydrated: () => boolean) => any) {
11351143
const [hydrated, setHydrated] = coreSignal(false, { ownedWrite: true });
11361144
const result = create(hydrated);
@@ -1160,33 +1168,94 @@ function hydrateSignalLike(coreFn: Function, fn: any, options?: any) {
11601168
);
11611169
}
11621170

1163-
// Hybrid async-iterable takeover (#2993). The server consumes exactly one
1171+
// Hybrid async-iterable handoff (#2993). The server consumes exactly one
11641172
// yield from its iterator and serializes it as a plain promise — the
1165-
// contract is that the CLIENT continues the iteration. Stores get that
1166-
// through hydrateStoreLikeFn's shadow-draft re-run; without this branch a
1167-
// signal-shaped node would adopt the first yield and latch there forever
1168-
// (readSerializedOrCompute only re-runs the compute on invalidation).
1169-
// Value semantics make the takeover simpler than the store's: re-run the
1170-
// generator plainly — its first yield reproduces the value the server
1171-
// rendered (hybrid's determinism contract, same assumption the store path
1172-
// makes), so nothing needs discarding; equal values dedupe at the node.
1173-
// The takeover only ARMS when the adoption pass saw an async-iterable
1173+
// contract is that the CLIENT continues the iteration. Without this branch
1174+
// a signal-shaped node would adopt the first yield and latch there forever
1175+
// (readSerializedOrCompute only re-runs the compute on invalidation). The
1176+
// handoff follows the store's rules 1–5 (see the rule block in
1177+
// hydrateStoreLikeFn): it waits for the adopted answer to LAND (rule 1 —
1178+
// the gate flips at the landing, never at creation: a creation flip ran
1179+
// the client generator as a fresh flight ahead of the pending server
1180+
// answer, superseding it and reading pending from creation until the
1181+
// client's first yield — #3574's key miss on a streamed <Loading>, with a
1182+
// wider window than the store's); only the handoff run's first yield is
1183+
// the duplicate (rule 2); a rejected answer is adopted (rule 3); a
1184+
// dependency change before the landing supersedes it (rule 4); and the
1185+
// handoff opens no pending window (rule 5). Value semantics make the run
1186+
// simpler than the store's — no shadow draft: the adopted answer is the
1187+
// node's `prev`, so wrapFirstYield yields it as the quiet steps and the
1188+
// duplicate lands as an equal write.
1189+
//
1190+
// The handoff only ARMS when the adoption pass saw an async-iterable
11741191
// compute: sync and promise-shaped hybrid computes keep their documented
11751192
// adopt-the-serialized-value semantics (re-running those would clobber the
1176-
// server value / trigger a client refetch).
1193+
// server value / trigger a client refetch) — for those the gate flips at
1194+
// creation and the flip's recompute re-adopts, as withHydrationGate always
1195+
// did here.
11771196
if (ssrSource === "hybrid" && sharedConfig.has!(peekNextChildId(getOwner()!))) {
1178-
let takeover = false;
1197+
// undefined until the trace has completed once: a sync NotReady from the
1198+
// trace (the compute read a pending sibling before returning) leaves the
1199+
// shape unknown, and the retry decides.
1200+
let takeover: boolean | undefined;
11791201
const detect = (prev: any) => {
11801202
const r = fn(prev);
11811203
takeover = isAsyncIterable(r);
11821204
return r;
11831205
};
1184-
return withHydrationGate(hydrated =>
1185-
coreFn((prev: any) => {
1186-
if (hydrated() && takeover) return fn(prev);
1187-
return readSerializedOrCompute(detect, prev, options);
1188-
}, options)
1189-
);
1206+
const [hydrated, setHydrated] = coreSignal(false, { ownedWrite: true });
1207+
let live = false;
1208+
const flip = () => {
1209+
if (!live) setHydrated(true);
1210+
};
1211+
let adopted = false;
1212+
let creating = true;
1213+
let landedOnCreate = false;
1214+
const result = coreFn((prev: any) => {
1215+
if (live) return fn(prev);
1216+
if (hydrated()) {
1217+
if (!takeover) return readSerializedOrCompute(detect, prev, options);
1218+
// The handoff run (rule 5: quiet through its duplicate).
1219+
live = true;
1220+
const r = fn(prev);
1221+
return isAsyncIterable(r) ? wrapFirstYield(r, undefined, prev) : r;
1222+
}
1223+
if (adopted) {
1224+
// Rule 4: the gate is down and an adoption already returned, so a
1225+
// dependency changed. The recompute released the adopted flight, so
1226+
// the server's late landing is dropped and its flip never comes.
1227+
live = true;
1228+
return fn(prev);
1229+
}
1230+
// Adoption; the trace inside detects the compute's shape. Re-entered
1231+
// only by a NotReady retry of the trace (nothing adopted yet).
1232+
let answer: any;
1233+
try {
1234+
answer = readSerializedOrCompute(detect, prev, options);
1235+
} catch (e) {
1236+
// The trace completed (an async-iterable compute cannot throw
1237+
// synchronously), so this is the settled rejection — the adopted
1238+
// answer (rule 3): authority transfers without a handoff run.
1239+
if (takeover) live = true;
1240+
throw e;
1241+
}
1242+
if (!takeover) return answer;
1243+
adopted = true;
1244+
if (answer != null && typeof answer.then === "function")
1245+
return adoptedAnswerStream(answer, flip, () => (live = true));
1246+
// Settled, landing synchronously in this run: flip after construction
1247+
// (creation) or on a microtask (a retry inside a flush).
1248+
if (creating) landedOnCreate = true;
1249+
else queueMicrotask(flip);
1250+
return answer;
1251+
}, options);
1252+
creating = false;
1253+
// The creation flip: the handoff for a synchronously landed answer, or
1254+
// the non-handoff shapes' one re-adopting recompute (as before). An
1255+
// untraced node (NotReady) has no shape yet; for a non-handoff shape the
1256+
// retry's adoption is already the run the flip would have produced.
1257+
if (landedOnCreate || takeover === false) flip();
1258+
return result;
11901259
}
11911260

11921261
// "server", "hybrid", or undefined — use serialized value from server
@@ -1293,6 +1362,12 @@ function hydrateStoreLikeFn(
12931362
// give the run the contract's shape, so the store reads settled until the
12941363
// client source produces something new. Maintainer ruling: isPending does
12951364
// not read true over the initial load; the handoff is its tail.
1365+
//
1366+
// The signal-shaped hybrid handoff (hydrateSignalLike: createMemo,
1367+
// function-form createSignal, createOptimistic over an async generator)
1368+
// follows the same rules 1–5 on the same helpers — adoptedAnswerStream
1369+
// for the landing, wrapFirstYield for the quiet run — with the node's
1370+
// `prev` as the adopted answer in place of the draft.
12961371
const id = peekNextChildId(getOwner()!);
12971372
// Nothing serialized: no answer to wait for and nothing for a first
12981373
// yield to duplicate — the client is authoritative from its first run.

0 commit comments

Comments
 (0)