Skip to content

Commit e35ac96

Browse files
ryansolidClaude via Cursor
andcommitted
frames: C5 follow-up — inline styles hold on the assets tier too
The ruling "inline styles are not reveal-gating" predated the tier. With the tier absent, a segment whose assets record carried inline styles revealed at once and its <style> landed one chunk load later, at the install's flush — a bounded unstyled window, which is exactly the FOUC the reveal-readiness term exists to prevent. The term in #segmentReady now reads (assets.styles || assets.inlineStyles) && !tierReady("assets")?.gate(assets.styles || [], this) so while the tier is absent such a segment holds like a stylesheet-gated one (the server's fallback stays; the install's flush lands the style in the assets walk, then reveals the segment); once the tier is resident inline styles still never gate — they apply at the record's arrival, ahead of the segments in the same flush, as before. The assets walk stays a separate pass before the segments. Measured first on the edited dist copy through scripts/size's bundler: +22 min / +14 br on frames eager (the explicit two-branch form was +50; widening the tier's `gate` to accept undefined was +18 but changed its signature — not taken). The real build matched to the byte: frames eager 41,077 / 13,346 (cap 13.35 KB, within; recorded minified left at 41,055), page base 120,124 / 37,969 (+22 / −1), page live 131,995 / 41,650 (+22 / −1), every non-SC scenario 0 / 0. No cap raised. Pins — test/consistency/tier-assets-ready.spec.tsx (7 → 9): tier absent, an inline-only segment holds (loader called once, fallback on screen, no <p>, no <style>) and the install lands the style before the content (one MutationObserver over head and boundary records the order); tier resident, the segment's three records in one frame.apply reveal synchronously with the style, style first; the mixed-stream pin now holds the inline-only segment beside the style-gated one. A mutant with the previous term fails 2 of 9. Co-authored-by: Claude via Cursor <[email protected]>
1 parent f19cdc3 commit e35ac96

7 files changed

Lines changed: 205 additions & 57 deletions

File tree

‎.changeset/frames-assets-tier.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"@solidjs/web": patch
33
---
44

5-
frames: the assets tier (frames savings pass C5) — the head mirror a segment's `assets` record drives (the stylesheet gate, module and typed preloads, inline styles) leaves the eager frames client for the lazy chunk `@solidjs/web/frames/assets`, loaded through the tier mechanism. A style-gated segment is not ready while the tier is not resident: the server's fallback stays on screen and the reveal happens at max(tier load, stylesheet load) — no segment reveals unstyled. A segment without stylesheets never waits on the tier; inline styles, modules and preloads apply when it is resident (at the record's arrival, or at the install). New export path `@solidjs/web/frames/assets` (`@experimental`); `InstallOptions.tiers` loaders resolve `TierModule` (a module with or without `install()`).
5+
frames: the assets tier (frames savings pass C5) — the head mirror a segment's `assets` record drives (the stylesheet gate, module and typed preloads, inline styles) leaves the eager frames client for the lazy chunk `@solidjs/web/frames/assets`, loaded through the tier mechanism. A segment whose assets record carries stylesheets or inline styles is not ready while the tier is not resident: the server's fallback stays on screen and the reveal happens at max(tier load, stylesheet load) — no segment reveals unstyled. Once the tier is resident only stylesheets gate; inline styles, modules and preloads apply at the record's arrival, and a segment with none of these never waits on the tier. New export path `@solidjs/web/frames/assets` (`@experimental`); `InstallOptions.tiers` loaders resolve `TierModule` (a module with or without `install()`).

‎documentation/plans/frames-savings-pass.md‎

Lines changed: 26 additions & 26 deletions
Large diffs are not rendered by default.

‎packages/web/frames/src/assets-tier.ts‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,13 @@
1313
* styles). The eager client keeps the record itself (`chunkToRecords`'
1414
* `assets` case, the host's `seg::assets` accumulate), the pass's walk over
1515
* the store, and the reveal's READINESS TERM: a segment whose assets record
16-
* names stylesheets while this tier is not resident is not ready — the
17-
* server's `<Loading>` fallback stays on screen; the reveal happens at
18-
* max(tier load, stylesheet load) (frames savings pass §1, "assets": no
19-
* FOUC, no blank). A segment without stylesheets never waits on this tier:
20-
* modules, preloads and inline styles are not reveal-gating and apply when
21-
* the tier is resident — at the record's arrival, or at the install's flush.
16+
* carries stylesheets or inline styles while this tier is not resident is
17+
* not ready — the server's `<Loading>` fallback stays on screen; the reveal
18+
* happens at max(tier load, stylesheet load) (frames savings pass §1,
19+
* "assets": no FOUC, no blank). Once the tier is resident only stylesheets
20+
* gate: inline styles apply at the record's arrival (the walk runs ahead of
21+
* the segments in the same flush), modules and preloads likewise, and a
22+
* segment with none of these never waits on the tier.
2223
*
2324
* The module's exports ARE its dispatch: `prepareTier` stamps the load with
2425
* the module once it has resolved (`tierLoads.assets.r`), and the eager

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,11 +79,11 @@ tierLoaders.trace = () => import("@solidjs/web/frames/trace");
7979
// assets` (assets-tier.ts), loaded through the tier mechanism: the server
8080
// announces `assets` wherever it emits an assets chunk, and a record met
8181
// while the tier is absent starts the load from the readiness check. A
82-
// style-gated segment is NOT READY until the tier is resident and its
83-
// sheets have settled (the reveal-readiness term in frame-client.ts's
84-
// #segmentReady): the server's fallback stays on screen, no segment
85-
// reveals unstyled. The module's exports are the dispatch (`gate`,
86-
// `apply`); no install.
82+
// segment with stylesheets or inline styles is NOT READY until the tier is
83+
// resident, and one with stylesheets not until they have settled (the
84+
// reveal-readiness term in frame-client.ts's #segmentReady): the server's
85+
// fallback stays on screen, no segment reveals unstyled. The module's
86+
// exports are the dispatch (`gate`, `apply`); no install.
8787
tierLoaders.assets = () => import("@solidjs/web/frames/assets");
8888

8989
// Build-time literal (see diagnostics.ts): dev-only guidance folds out of prod.

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

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2402,11 +2402,20 @@ class FrameImpl {
24022402
// when other prerequisites are missing, so loading overlaps the rest of
24032403
// the stream, and re-flushes this frame when one settles. The reveal is
24042404
// at max(tier load, stylesheet load); no segment reveals unstyled. A
2405-
// segment that names no stylesheet never consults the tier: inline
2406-
// styles, modules and preloads do not gate (they apply in the assets
2407-
// walk, at arrival or at the install).
2405+
// segment whose record carries INLINE styles holds the same way while
2406+
// the tier is absent — its `<style>` lands in the assets walk, which the
2407+
// tier performs, so revealing before the install would be the unstyled
2408+
// window the term exists to prevent; once the tier is resident inline
2409+
// styles never gate (the walk applied them at the record's arrival, in
2410+
// the same flush, ahead of the segments). A segment with neither never
2411+
// consults the tier: modules and preloads do not gate.
24082412
const assets = this.#store[`seg:${name}:assets`];
2409-
if (assets && assets.styles && !tierReady("assets")?.gate(assets.styles, this)) return false;
2413+
if (
2414+
assets &&
2415+
(assets.styles || assets.inlineStyles) &&
2416+
!tierReady("assets")?.gate(assets.styles || [], this)
2417+
)
2418+
return false;
24102419
// Structural prerequisite: the placeholder must exist in the range.
24112420
return !!this.#findPlaceholder(name, root);
24122421
}
@@ -2422,7 +2431,8 @@ class FrameImpl {
24222431
// The segment's inline styles rode its assets record and landed in the
24232432
// head at the record's arrival (the assets walk in #flush, ahead of the
24242433
// segments), so they precede the content as the document face orders
2425-
// them; with the assets tier absent then, they land at its install.
2434+
// them; with the assets tier absent then, the segment held (#segmentReady)
2435+
// and they land at the install's flush, still ahead of this reveal.
24262436
const content = this.#store[`seg:${name}`];
24272437
const closing = rangeClose(tpl, placeholderId(name));
24282438
if ("_SOLID_DEV_" && !closing) {

‎packages/web/test/consistency/tier-assets-ready.spec.tsx‎

Lines changed: 140 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,17 @@
1818
* re-evaluates: the tier's gate requests the sheets, and the reveal is
1919
* at max(tier load, stylesheet load). No frame between the fallback and
2020
* the styled content.
21-
* - A segment WITHOUT stylesheets never waits on the tier: it reveals
22-
* with the tier absent, and a stream with no asset records never loads
23-
* it. Inline styles, modules and typed preloads are not reveal-gating:
24-
* they buffer in the store and apply at the install's flush.
21+
* - A segment whose record carries INLINE styles holds the same way while
22+
* the tier is absent: its `<style>` is the tier's to land (the assets
23+
* walk), so revealing before the install would be the very unstyled
24+
* window. The install's flush lands the style and reveals the segment,
25+
* in that order. Once the tier is resident inline styles never gate: the
26+
* style lands at the record's arrival and the segment reveals in the
27+
* same flush, style first.
28+
* - A segment with neither never waits on the tier: it reveals with the
29+
* tier absent, and a stream with no asset records never loads it.
30+
* Modules and typed preloads are not reveal-gating: they buffer in the
31+
* store and apply at the install's flush.
2532
* - Announced: `X-Frame-Tiers: assets` starts the import before the body
2633
* is read; `tiers: ["assets"]` in-band (the sink stamps the first assets
2734
* chunk after the head) at the chunk; `_$HY.r["sc:tiers"]` at
@@ -36,7 +43,7 @@ import { afterEach, describe, expect, test, vi } from "vitest";
3643
import { createRoot, Loading } from "solid-js";
3744
import { dynamic } from "@solidjs/web";
3845
import { applyFrameResponse, installServerComponents } from "../../frames/src/client.js";
39-
import { createFrame, tierLoads } from "../../frames/src/frame-client.js";
46+
import { createFrame, prepareTier, tierLoads } from "../../frames/src/frame-client.js";
4047
import { createServerReference } from "../../server-functions/src/client.js";
4148
import { createChunk } from "../../server-functions/src/shared.js";
4249
import {
@@ -92,6 +99,28 @@ const styles = () => [...document.head.querySelectorAll<HTMLStyleElement>("style
9299
const load = (href: string) =>
93100
document.head.querySelector(`link[href="${href}"]`)!.dispatchEvent(new Event("load"));
94101

102+
/**
103+
* One observer over the head and a boundary: the order its records come in
104+
* is the order of the mutations across both. `order()` is the index of the
105+
* first head mutation and of the one that inserted the node with `text`.
106+
*/
107+
function observeOrder(boundary: Element) {
108+
const records: MutationRecord[] = [];
109+
const observer = new MutationObserver(rs => records.push(...rs));
110+
observer.observe(document.head, { childList: true });
111+
observer.observe(boundary, { childList: true, subtree: true });
112+
return (text: string) => {
113+
records.push(...observer.takeRecords());
114+
observer.disconnect();
115+
return {
116+
head: records.findIndex(r => r.target === document.head),
117+
content: records.findIndex(r =>
118+
[...r.addedNodes].some(n => (n as Element).textContent === text)
119+
)
120+
};
121+
};
122+
}
123+
95124
let page: Page | undefined;
96125
const disposers: (() => void)[] = [];
97126
afterEach(async () => {
@@ -232,8 +261,100 @@ describe("the FOUC guard — a style-gated segment before the tier", () => {
232261
});
233262
});
234263

264+
describe("inline styles — held while the tier is absent, never gating once it is resident", () => {
265+
test("tier absent: an inline-only segment holds like a style-gated one; the install lands its style, then reveals it", async () => {
266+
const gate = gatedAssets();
267+
const WIRE = "tier-assets/inline-held";
268+
const { host } = makeHost();
269+
installServerComponents(host, { tiers: gate.tiers });
270+
const boundary = document.createElement("div");
271+
document.body.appendChild(boundary);
272+
const frame = createFrame(boundary, { id: WIRE, host });
273+
disposers.push(() => frame.dispose());
274+
const held = heldResponse(WIRE);
275+
const done = applyFrameResponse(held.response, host, { as: WIRE, version: 1 });
276+
held.send({ type: "start", id: WIRE, version: 1 });
277+
held.send({ type: "html", id: WIRE, version: 1, html: shell("inline") });
278+
held.send({ type: "reveal", id: WIRE, version: 1, keys: ["inline"], fallback: true });
279+
held.send({
280+
type: "assets",
281+
id: WIRE,
282+
version: 1,
283+
key: "inline",
284+
inlineStyles: [{ id: "inline-only", content: "p{}" }]
285+
});
286+
held.send({ type: "fragment", id: WIRE, version: 1, key: "inline", html: "<p>inline</p>" });
287+
held.send({ type: "reveal", id: WIRE, version: 1, keys: ["inline"], waitForStyles: false });
288+
held.send({ type: "complete", id: WIRE, version: 1 });
289+
held.close();
290+
await done;
291+
// Un-announced: the readiness check met the record with the tier
292+
// absent — it started the load and HELD. The fallback is on screen, the
293+
// content is not, and the style has not landed (it is the tier's to land).
294+
expect(gate.loader).toHaveBeenCalledTimes(1);
295+
expect(resident()).toBe(false);
296+
expect(boundary.querySelector(".fallback")!.textContent).toBe("inline-loading");
297+
expect(boundary.querySelector("p")).toBeNull();
298+
expect(styles()).toEqual([]);
299+
// The install's flush: the walk lands the style, then the segment
300+
// reveals — one observer over both targets sees the mutations in order.
301+
const order = observeOrder(boundary);
302+
await gate.release();
303+
await pump();
304+
expect(styles().map(s => s.getAttribute("data-asset"))).toEqual(["inline-only"]);
305+
expect(boundary.querySelector(".fallback")).toBeNull();
306+
expect(boundary.querySelector("p")!.textContent).toBe("inline");
307+
const at = order("inline");
308+
expect(at.head).toBeGreaterThanOrEqual(0);
309+
expect(at.content).toBeGreaterThan(at.head);
310+
});
311+
312+
test("tier resident: an inline-only segment reveals at the record's arrival, its style landing first in the same flush", async () => {
313+
const gate = gatedAssets();
314+
const WIRE = "tier-assets/inline-resident";
315+
const { host } = makeHost();
316+
installServerComponents(host, { tiers: gate.tiers });
317+
// Warm the tier ahead of the stream.
318+
prepareTier("assets");
319+
await gate.release();
320+
await pump();
321+
expect(resident()).toBe(true);
322+
const boundary = document.createElement("div");
323+
document.body.appendChild(boundary);
324+
const frame = createFrame(boundary, { id: WIRE, host });
325+
disposers.push(() => frame.dispose());
326+
// The shell with the server's fallback showing.
327+
frame.apply({
328+
version: 1,
329+
r: { "": { kind: "html", value: shell("inline") }, "seg:inline:fallback": true }
330+
});
331+
expect(boundary.querySelector(".fallback")!.textContent).toBe("inline-loading");
332+
expect(styles()).toEqual([]);
333+
// The segment's three records in ONE apply — one flush: the walk lands
334+
// the style, then the reveal, with no readiness wait on the tier.
335+
const order = observeOrder(boundary);
336+
frame.apply({
337+
version: 1,
338+
r: {
339+
"seg:inline:assets": { inlineStyles: [{ id: "inline-only", content: "p{}" }] },
340+
"seg:inline": { kind: "html", value: "<p>inline</p>" },
341+
"seg:inline:reveal": true
342+
}
343+
});
344+
// Synchronously, before any task: asked no second time; revealed with
345+
// the style, style first.
346+
expect(gate.loader).toHaveBeenCalledTimes(1);
347+
expect(styles().map(s => s.getAttribute("data-asset"))).toEqual(["inline-only"]);
348+
expect(boundary.querySelector(".fallback")).toBeNull();
349+
expect(boundary.querySelector("p")!.textContent).toBe("inline");
350+
const at = order("inline");
351+
expect(at.head).toBeGreaterThanOrEqual(0);
352+
expect(at.content).toBeGreaterThan(at.head);
353+
});
354+
});
355+
235356
describe("what never waits on the tier", () => {
236-
test("a segment without stylesheets reveals at once with the tier absent; one with inline styles alone reveals too, its style landing at the install", async () => {
357+
test("a segment without stylesheets or inline styles reveals at once with the tier absent; styled and inline-only ones hold, revealing at the install (inline) and the sheet's load (styled)", async () => {
237358
const gate = gatedAssets();
238359
const WIRE = "tier-assets/unstyled";
239360
const { host } = makeHost();
@@ -283,20 +404,26 @@ describe("what never waits on the tier", () => {
283404
await done;
284405
expect(resident()).toBe(false);
285406
const text = () => [...boundary.querySelectorAll("p")].map(p => p.textContent);
286-
// The unstyled segments revealed (the grouped reveal's `waitForStyles`
287-
// is the server's note; the client reads each segment's record); the
288-
// style-gated one is held on the tier.
289-
expect(text()).toEqual(["plain", "inline"]);
407+
// The plain segment revealed (the grouped reveal's `waitForStyles` is
408+
// the server's note; the client reads each segment's record); the
409+
// style-gated one and the inline-only one are held on the tier — the
410+
// inline style buffers, not applied, and its segment does not show.
411+
expect(text()).toEqual(["plain"]);
290412
expect(boundary.querySelector("template#pl-styled")).not.toBeNull();
291-
expect(boundary.querySelector(".fallback")!.textContent).toBe("styled-loading");
292-
// Not reveal-gating, not applied either: the inline style buffers.
413+
expect(boundary.querySelector("template#pl-inline")).not.toBeNull();
414+
expect([...boundary.querySelectorAll(".fallback")].map(f => f.textContent)).toEqual([
415+
"styled-loading",
416+
"inline-loading"
417+
]);
293418
expect(styles()).toEqual([]);
294419
await gate.release();
295420
await pump();
296-
// The install: the inline style lands (once), the sheet is requested.
421+
// The install: the inline style lands (once) and its segment reveals;
422+
// the sheet is requested and the styled segment still holds on it.
297423
expect(styles().map(s => s.getAttribute("data-asset"))).toEqual(["inline-only"]);
298424
expect(links().map(l => l.getAttribute("href"))).toEqual(["/s.css"]);
299425
expect(text()).toEqual(["plain", "inline"]);
426+
expect(boundary.querySelector(".fallback")!.textContent).toBe("styled-loading");
300427
load("/s.css");
301428
await pump();
302429
expect(text()).toEqual(["styled", "plain", "inline"]);

‎scripts/size/scenarios.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3457,6 +3457,12 @@ module.exports = [
34573457
// costs +508 / +131. Back under the cap for the first time since Phase A:
34583458
// cap 13.79 KB -> 13.35 KB (measured + 10 B at the 0.01 KB step — the
34593459
// ratchet); recorded minified 42,968 -> 41,055 B.
3460+
// C5 follow-up (2026-10-06): the readiness term holds a segment whose
3461+
// record carries INLINE styles too while the tier is absent (its
3462+
// `<style>` is the tier's to land — revealing before the install was the
3463+
// unstyled window the term exists to prevent). Measured on the edited
3464+
// dist first: +22 min / +14 br; built the same, 13,346 B (41,077 B
3465+
// minified). Within the 13.35 KB cap; recorded minified left at 41,055.
34603466
limit: "13.35 KB",
34613467
capMinified: 41055,
34623468
alias: framesAlias,
@@ -3648,7 +3654,9 @@ module.exports = [
36483654
// (120,102 B minified): -628 / -1,926 against the C3 head, -6,912 /
36493655
// -25,655 against `next` @ 9d89df731. The head mirror leaves for the lazy
36503656
// `assets.js` chunk (783 B brotli, reported, not counted). Cap 38.61 ->
3651-
// 37.98 KB (the ratchet); recorded minified 122,028 -> 120,102 B.
3657+
// 37.98 KB (the ratchet); recorded minified 122,028 -> 120,102 B. The C5
3658+
// follow-up (inline styles hold while the tier is absent): 37,969 B
3659+
// (120,124 B minified), +22 min / -1 br.
36523660
limit: floorCaps["page: base server components (hydrating + dynamic + frames + sf reference)"],
36533661
capMinified:
36543662
floorMinified["page: base server components (hydrating + dynamic + frames + sf reference)"],
@@ -3783,6 +3791,8 @@ module.exports = [
37833791
// (131,973 B minified): -496 / -1,926 against the C3 head, -6,944 /
37843792
// -25,747 against `next` @ 9d89df731; the same cut as the base page. Cap
37853793
// 42.16 -> 41.67 KB (the ratchet); recorded minified 133,899 -> 131,973 B.
3794+
// The C5 follow-up (inline styles hold while the tier is absent):
3795+
// 41,650 B (131,995 B minified), +22 min / -1 br.
37863796
limit: floorCaps["page: live server components (base + live/GET + action + isPending/latest)"],
37873797
capMinified:
37883798
floorMinified["page: live server components (base + live/GET + action + isPending/latest)"],

0 commit comments

Comments
 (0)