Skip to content

Commit af55363

Browse files
ryansolidClaude via Cursor
andcommitted
fix(web/frames): classify an adopted occurrence only after every delivered record has drained (C18)
Frames-rulings 3.5 (proposed): "an occurrence is classified only after every delivered record has drained" — pending is the drain's state, not the parser's. `adoptBoundary.recordsPending` gains a third term: `_$HY.r` holds a slot/region record for the boundary not yet in `appliedRecords`. Before: two records drained after the parser finished classified each other — `drainRecords` applies one record per `host.apply`, each a synchronous `#flush` → `#syncSlots`; the first apply's sync found the second occurrence recordless with `readyState` no longer "loading", classified it direct-insert and evaluated its render prop argless: `TypeError` → REACTIVITY_HALTED. Same window via a live-hole op and the live pump's catch-up read (contract C18 / R9). Pins: harness/replay C18 ×3 flipped from test.fails to test; c18-classify-after-drain.spec.tsx pins the consequence with a real fill (record drain; live op in the window; control). Co-authored-by: Claude via Cursor <[email protected]>
1 parent b987c41 commit af55363

5 files changed

Lines changed: 363 additions & 75 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/web": patch
3+
---
4+
5+
Frames client: a recordless adopted occurrence is classified only after every delivered document record has drained (frames-rulings 3.5, proposed; consistency contract C18 / red R9). `adoptBoundary.recordsPending` gains a third term — `_$HY.r` still holds a slot or region record for the boundary that `drainRecords` has not applied — so "pending" is the drain's state, not only the parser's. Before, two records drained after the parser finished classified each other: the deferred drain applies one record per `host.apply`, each a synchronous frame sync, and that first sync found the second occurrence recordless with `document.readyState` no longer "loading", classified it direct-insert, and evaluated its render prop as a zero-arg accessor — a `TypeError` on the props read halted the reactive system. The same window was reachable from a live-hole op and from the live pump's catch-up read. Now such a sync defers the occurrence and the drain's next apply mounts it with its args.

‎packages/web/frames/src/client.ts‎

Lines changed: 50 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1331,6 +1331,11 @@ function adoptBoundary(
13311331
// recordless occurrence it deferred (#2968 — the frame's recordsPending/
13321332
// drainRecords seam below).
13331333
const appliedRecords = new Set<string>();
1334+
// The document keys this boundary's records under the wire name: slot
1335+
// records as `sc:slot:<id>:<occurrence>`, nested regions as
1336+
// `sc:region:<id>.<occurrence>.<key>`.
1337+
const slotPrefix = `sc:slot:${id}:`;
1338+
const regionPrefix = `sc:region:${id}.`;
13341339
// Deferred fragments in the adopted markup (#2978): a <Loading> that
13351340
// suspended inside the server component during document SSR left a `pl-*`
13361341
// placeholder here, but its producer ran on the SERVER — no client
@@ -1361,7 +1366,9 @@ function adoptBoundary(
13611366
// drain normally starts the pump; attempted on every re-drain anyway —
13621367
// idempotent, and a defensive catch for a record that lands late.
13631368
pumpLiveChannel();
1364-
const slotPrefix = `sc:slot:${id}:`;
1369+
// Each record is marked applied BEFORE its `host.apply`: that apply
1370+
// syncs the frame, and the sync's `recordsPending` must read the other
1371+
// delivered records as still pending while this one is no longer (3.5).
13651372
for (const key of Object.keys(hy.r)) {
13661373
if (appliedRecords.has(key)) continue;
13671374
if (key.startsWith(slotPrefix)) {
@@ -1375,19 +1382,17 @@ function adoptBoundary(
13751382
key: key.slice(slotPrefix.length),
13761383
args: hy.r[key]
13771384
});
1378-
} else if (key.startsWith("sc:region:")) {
1385+
} else if (key.startsWith(regionPrefix)) {
1386+
appliedRecords.add(key);
1387+
// Async-occluded regions arrive as promises (the producer held
1388+
// the stream on them); regions keep their producer-relative ids
1389+
// (the records reference them by those), and the store warms per
1390+
// id either way, so a late apply still lands before the region
1391+
// binds on expand.
13791392
const childId = key.slice("sc:region:".length);
1380-
if (childId.startsWith(id + ".")) {
1381-
appliedRecords.add(key);
1382-
// Async-occluded regions arrive as promises (the producer held
1383-
// the stream on them); regions keep their producer-relative ids
1384-
// (the records reference them by those), and the store warms per
1385-
// id either way, so a late apply still lands before the region
1386-
// binds on expand.
1387-
const val = hy.r[key];
1388-
const apply = (html: any) => host.apply({ type: "html", id: childId, version: 0, html });
1389-
val && typeof val.then === "function" ? val.then(apply) : apply(val);
1390-
}
1393+
const val = hy.r[key];
1394+
const apply = (html: any) => host.apply({ type: "html", id: childId, version: 0, html });
1395+
val && typeof val.then === "function" ? val.then(apply) : apply(val);
13911396
}
13921397
}
13931398
};
@@ -1473,23 +1478,44 @@ function adoptBoundary(
14731478
ownerScope: boundaryScope(owner),
14741479
reveal: revealSeam(owner),
14751480
onApply: settle,
1476-
// May the document still run scripts that assign records? While the
1477-
// parser is running the answer is yes, and a held fragment's replay can
1478-
// still deliver one — so a recordless occurrence defers instead of
1479-
// misclassifying as content (the runtime re-checks until this flips
1480-
// false). Deliberately NOT boundaryMayArrive(): its `!_$HY.done` term
1481-
// answers a different question (can this boundary's ELEMENT still
1482-
// appear), and holding classification until client hydration completes
1483-
// pushes the adopted mount past the hydrate window — the claim then
1484-
// adopts markup the client's state has already moved past (the
1485-
// adopted-slot-live spec pins the working ordering).
1481+
// Is a record for this boundary still to come — or here and not yet
1482+
// applied? While the parser is running the document can still run a
1483+
// data script, a held fragment's replay can still deliver one, and a
1484+
// record whose script already ran sits in `_$HY.r` until the drain
1485+
// moves it into the store — so a recordless occurrence defers instead
1486+
// of misclassifying as content (the runtime re-checks until this flips
1487+
// false). The third term is frames-rulings 3.5 (contract C18/R9): an
1488+
// occurrence is classified only after every delivered record has
1489+
// drained — "pending" is the drain's state, not the parser's. Without
1490+
// it, two records drained after the parser finished classify each
1491+
// other: the first apply's sync finds the second recordless with the
1492+
// parser done, evaluates its render prop argless, and the `TypeError`
1493+
// halts the reactive system. Deliberately NOT boundaryMayArrive(): its
1494+
// `!_$HY.done` term answers a different question (can this boundary's
1495+
// ELEMENT still appear), and holding classification until client
1496+
// hydration completes pushes the adopted mount past the hydrate window
1497+
// — the claim then adopts markup the client's state has already moved
1498+
// past (the adopted-slot-live spec pins the working ordering).
14861499
// Spread-cast: the published FrameOptions predates this seam; a runtime
14871500
// without it simply never calls the hooks (drop once the pin catches up).
14881501
...({
14891502
recordsPending: () => {
14901503
if (document.readyState === "loading") return true;
14911504
const hy = (globalThis as any)._$HY;
1492-
return !!(hy && hy.fr && hy.fr.pending());
1505+
if (!hy) return false;
1506+
if (hy.fr && hy.fr.pending()) return true;
1507+
// Delivered and undrained: a record for this boundary whose data
1508+
// script ran (`_$HY.r` has the key) that the drain has not moved
1509+
// into the store yet. "Recordless" reads the store, and the parser's
1510+
// state says nothing about this gap — the record sits one loop
1511+
// iteration from applying while a sync runs.
1512+
for (const key in hy.r)
1513+
if (
1514+
!appliedRecords.has(key) &&
1515+
(key.startsWith(slotPrefix) || key.startsWith(regionPrefix))
1516+
)
1517+
return true;
1518+
return false;
14931519
},
14941520
drainRecords,
14951521
// The identity split binds the frame to the call ADDRESS (id + args

‎packages/web/frames/src/frame-client.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -347,7 +347,10 @@ export interface FrameOptions {
347347
* occurrence is ambiguous while this returns true: the frame defers its
348348
* mount one macrotask (all currently parsed scripts run first), calls
349349
* `drainRecords`, and classifies with whatever is then resolvable. Return
350-
* false once the document can run no further data scripts.
350+
* false once the document can run no further data scripts AND every
351+
* record it has already delivered has been drained (frames-rulings 3.5):
352+
* a record that executed but has not been applied yet is pending too — a
353+
* sync in that window must defer, not classify.
351354
*/
352355
recordsPending?(): boolean;
353356
/** Re-absorb the document's arrived-by-now records (idempotent per key). */
@@ -1312,7 +1315,11 @@ class FrameImpl {
13121315
// bounded by the same contract as everything else here:
13131316
// recordsPending flips false when the document completes with no
13141317
// fragment left to reveal (truncation included — the ledger rejects
1315-
// stragglers). Deferral is invisible on screen: an adopted
1318+
// stragglers) and no delivered record left undrained (frames-
1319+
// rulings 3.5: the drain itself syncs once per record it applies,
1320+
// and that sync must not classify the records still in its loop —
1321+
// nor may a live op's sync in the same window). Deferral is
1322+
// invisible on screen: an adopted
13161323
// occurrence's server-rendered interior is already in the DOM; the
13171324
// mount is the hydration attach. Full syncs only: a scoped segment
13181325
// fill renders into a detached fragment a later full sync can't
Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
/**
2+
* @jsxImportSource @solidjs/web
3+
* @vitest-environment jsdom
4+
*
5+
* C18 — classification waits for the drain.
6+
*
7+
* "A recordless adopted occurrence is classified (direct-insert vs invoked)
8+
* only after every record the document already holds for the boundary has
9+
* been applied: no sync that runs between the parser's end and the deferred
10+
* drain — the drain's own first `host.apply`, a live op, the live pump's
11+
* catch-up read — may evaluate a render prop as a zero-arg accessor."
12+
*
13+
* Ruling (frames-rulings 3.5, proposed): "an occurrence is classified only
14+
* after every delivered record has drained" — "pending" is the DRAIN's
15+
* state, not the parser's. The #2968 defer's bound was `recordsPending()` =
16+
* parser running or a fragment pending; a record whose data script already
17+
* ran sat in `_$HY.r` until the deferred `drainRecords` moved it into the
18+
* store, and nothing read that gap (contract §Red R9).
19+
*
20+
* Mechanism meant to carry it: frames/src/client.ts
21+
* `adoptBoundary.recordsPending`'s third term — `_$HY.r` holds a key under
22+
* the boundary's `sc:slot:<id>:` / `sc:region:<id>.` prefix that is not yet
23+
* in `appliedRecords` — read by frames/src/frame-client.ts `#syncSlots`'
24+
* defer arm. `drainRecords` marks a key applied BEFORE its `host.apply`, so
25+
* the sync that apply runs sees the other delivered records as pending and
26+
* its own as drained.
27+
*
28+
* Observation: the fills here are REAL — `p => <li>{p.text}{tick()}</li>`,
29+
* the props read unguarded (plus one untracked identification read, as a
30+
* fill's top-level read is otherwise a STRICT_READ diagnostic). Classified
31+
* direct-insert, the render prop is evaluated as a zero-arg accessor inside
32+
* the insert effect: `p.text` is a `TypeError` and the reactive system
33+
* halts (`REACTIVITY_HALTED`). The pin
34+
* asserts the opposite: every occurrence invoked once with its args, the
35+
* server `<li>` claimed in place, no error, and the page still reactive
36+
* after the `tick` bump. The harness's replay pins (`harness/replay.spec.tsx`
37+
* C18 ×3) hold the same three orders through the oracle's tolerant fill;
38+
* this file pins the consequence for a real one.
39+
*/
40+
import { afterEach, describe, expect, test, vi } from "vitest";
41+
import { createSignal, flush, untrack } from "solid-js";
42+
import { hydrate } from "@solidjs/web";
43+
import {
44+
bootPage,
45+
fillHtml2,
46+
frameHtml,
47+
freshFid,
48+
holeHtml,
49+
microtasks,
50+
quiesce,
51+
slotRange,
52+
type Page
53+
} from "./support.js";
54+
55+
let page: Page | undefined;
56+
afterEach(async () => {
57+
await page?.cleanup();
58+
page = undefined;
59+
});
60+
61+
/** The server render of `p => <li>{p.text}{tick()}</li>` at tick 0. */
62+
const liveFillHtml = (fid: string, occ: string, text: string) => fillHtml2(fid, occ, text, "0");
63+
64+
/**
65+
* The parser's clock: `document.readyState` reads "loading" until `done()`
66+
* — the records the document still owes execute while it is running, and
67+
* the response's tail (the last data script, then the end) parses in one
68+
* go before any timer fires, so the restore is synchronous with the last
69+
* record.
70+
*/
71+
function parserRunning() {
72+
const spy = vi.spyOn(document, "readyState", "get").mockReturnValue("loading");
73+
return () => spy.mockRestore();
74+
}
75+
76+
describe("C18 — classification waits for the drain", () => {
77+
// Arm (a): the drain's own first apply. Two render-prop occurrences; both
78+
// records owed when the boundary adopts (the #2968 defer arms); both
79+
// execute, the parser finishes, THEN the deferred drain fires. Its first
80+
// `host.apply` syncs the frame while the second record is still one loop
81+
// iteration away in `_$HY.r`: that sync must defer item#1, not classify
82+
// it — the loop's next apply mounts it with its args.
83+
test("(a) two records drained after the parser finished: each occurrence claims with its args; nothing is evaluated argless", async () => {
84+
const fid = freshFid("c18a");
85+
const parserDone = parserRunning();
86+
page = bootPage(
87+
frameHtml(
88+
fid,
89+
`<ul>${slotRange("item#0", liveFillHtml(fid, "item#0", "p0"))}${slotRange(
90+
"item#1",
91+
liveFillHtml(fid, "item#1", "p1")
92+
)}</ul>`
93+
)
94+
);
95+
const serverLis = [...page.container.querySelectorAll("li")];
96+
const Comp = (globalThis as any)._$SC.r(fid);
97+
const [tick, setTick] = createSignal(0);
98+
const invoked: string[] = [];
99+
const dispose = hydrate(
100+
() => (
101+
<Comp
102+
item={(p: { text: string }) => {
103+
invoked.push(untrack(() => p.text));
104+
return (
105+
<li>
106+
{p.text}
107+
{tick()}
108+
</li>
109+
);
110+
}}
111+
/>
112+
),
113+
page.container
114+
);
115+
// Adopted with the parser running: both occurrences deferred, nothing
116+
// invoked, the server markup untouched.
117+
expect(invoked).toEqual([]);
118+
expect(page.container.textContent).toBe("p0" + "0" + "p1" + "0");
119+
120+
// The document's tail: both data scripts, then the end of the response
121+
// — before the deferred drain's macrotask.
122+
page.slotRecord(fid, "item#0", { text: "p0" });
123+
page.slotRecord(fid, "item#1", { text: "p1" });
124+
parserDone();
125+
expect(invoked).toEqual([]);
126+
127+
await quiesce();
128+
await quiesce();
129+
expect(invoked.sort()).toEqual(["p0", "p1"]);
130+
expect([...page.container.querySelectorAll("li")]).toEqual(serverLis);
131+
expect(page.container.textContent).toBe("p0" + "0" + "p1" + "0");
132+
setTick(1);
133+
flush();
134+
expect(page.container.textContent).toBe("p0" + "1" + "p1" + "1");
135+
expect(page.warnings).toEqual([]);
136+
expect(page.errors).toEqual([]);
137+
dispose();
138+
});
139+
140+
// Arm (b): a sync the drain did not trigger, in the same window. One
141+
// occurrence and a live hole; the record executes and the parser finishes
142+
// while the defer is armed; a live hole op then lands — the pump's read is
143+
// a microtask, the drain a macrotask — and its `host.apply` syncs the frame
144+
// over the undrained record. That sync must defer the occurrence; the
145+
// drain's apply mounts it. (The pump's catch-up read over ops logged
146+
// before adoption is the same sync from the other side of adoption —
147+
// `harness/replay.spec.tsx`'s third C18 pin.)
148+
test("(b) a live op syncs the frame between the parser's end and the drain: the occurrence defers, then claims with its args", async () => {
149+
const fid = freshFid("c18b");
150+
const parserDone = parserRunning();
151+
page = bootPage(
152+
frameHtml(
153+
fid,
154+
`<ul>${slotRange("item#0", liveFillHtml(fid, "item#0", "p0"))}</ul><p>${holeHtml(
155+
18,
156+
"hole-v0"
157+
)}</p>`
158+
)
159+
);
160+
const serverLi = page.container.querySelector("li")!;
161+
const Comp = (globalThis as any)._$SC.r(fid);
162+
const [tick, setTick] = createSignal(0);
163+
const invoked: string[] = [];
164+
const dispose = hydrate(
165+
() => (
166+
<Comp
167+
item={(p: { text: string }) => {
168+
invoked.push(untrack(() => p.text));
169+
return (
170+
<li>
171+
{p.text}
172+
{tick()}
173+
</li>
174+
);
175+
}}
176+
/>
177+
),
178+
page.container
179+
);
180+
expect(invoked).toEqual([]);
181+
182+
page.slotRecord(fid, "item#0", { text: "p0" });
183+
parserDone();
184+
// The live op's sync lands on the pump's microtask read — before the
185+
// deferred drain's macrotask.
186+
page.live.push({ type: "hole", key: "lh:18", html: "hole-v1" });
187+
await microtasks(4);
188+
expect(page.container.querySelector("p")!.textContent).toBe("hole-v1");
189+
expect(invoked).toEqual([]);
190+
191+
await quiesce();
192+
await quiesce();
193+
expect(invoked).toEqual(["p0"]);
194+
expect(page.container.querySelector("li")).toBe(serverLi);
195+
expect(page.container.textContent).toBe("p0" + "0" + "hole-v1");
196+
setTick(1);
197+
flush();
198+
expect(page.container.textContent).toBe("p0" + "1" + "hole-v1");
199+
expect(page.warnings).toEqual([]);
200+
expect(page.errors).toEqual([]);
201+
dispose();
202+
});
203+
204+
// Control: a tick between the two records — the drain runs while the
205+
// parser is still owed the second, every sync reads `recordsPending()`
206+
// true through the parser's term alone. Green before and after 3.5.
207+
test("control: a drain per record while the parser is still running classifies nothing early", async () => {
208+
const fid = freshFid("c18c");
209+
const parserDone = parserRunning();
210+
page = bootPage(
211+
frameHtml(
212+
fid,
213+
`<ul>${slotRange("item#0", liveFillHtml(fid, "item#0", "p0"))}${slotRange(
214+
"item#1",
215+
liveFillHtml(fid, "item#1", "p1")
216+
)}</ul>`
217+
)
218+
);
219+
const Comp = (globalThis as any)._$SC.r(fid);
220+
const [tick, setTick] = createSignal(0);
221+
const invoked: string[] = [];
222+
const dispose = hydrate(
223+
() => (
224+
<Comp
225+
item={(p: { text: string }) => {
226+
invoked.push(untrack(() => p.text));
227+
return (
228+
<li>
229+
{p.text}
230+
{tick()}
231+
</li>
232+
);
233+
}}
234+
/>
235+
),
236+
page.container
237+
);
238+
page.slotRecord(fid, "item#0", { text: "p0" });
239+
await quiesce();
240+
expect(invoked).toEqual(["p0"]);
241+
page.slotRecord(fid, "item#1", { text: "p1" });
242+
parserDone();
243+
await quiesce();
244+
await quiesce();
245+
expect(invoked).toEqual(["p0", "p1"]);
246+
setTick(1);
247+
flush();
248+
expect(page.container.textContent).toBe("p0" + "1" + "p1" + "1");
249+
expect(page.warnings).toEqual([]);
250+
expect(page.errors).toEqual([]);
251+
dispose();
252+
});
253+
});

0 commit comments

Comments
 (0)