Skip to content

Commit e4fa7c6

Browse files
ryansolidClaude via Cursorcursoragent
committed
docs(size): B/C/G measured, page caps frozen, target reframed
Follow-up to #3673 (documentation/plans/size-reduction-audit.md). - B.1 (enableHydration store adapters) measured and rejected: -789 B on the hydrating no-store app, +1,739 B on a CSR app with createStore. Tree-shaking cannot express "retained only when both X and Y are referenced", so one deployment class pays either way. - B.4 (sf `live` split) is already the case: `live` shakes off the base page today through the LIVE_WIRE option seam; residue < 0.3 KB. - C re-scoped: `preserveModules` alone does not enable route splitting. Chunk assignment is per module and each package is effectively one module (solid-js client/hydration.js 114 KB, web client.js 104 KB unminified); measured with a synthetic entry + lazy route (21,795 vs 21,825 B). - G measured (new: size-reduction-g-rulings.md): every mainline hold rule site in recompute (21) and the scheduler (10) stubbed and re-measured. All together -824 B; largest single ruling 127 B; model-level ceiling -1.2 KB. The -1.5 to -2.5 KB estimate was wrong by 2-3x. G closed, no rulings. - Target reframed: the size every real app ships. Hello world is informational (its cap stays frozen as governance). Next: I, the density audit — the code everyone ships, made smaller with the same semantics. - The two server-component page caps join the frozen set in floor-caps.json. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 55e2022 commit e4fa7c6

6 files changed

Lines changed: 256 additions & 34 deletions

File tree

‎.github/workflows/size.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ jobs:
5252
# in the same log that reports it.
5353
- run: npm run size
5454
working-directory: scripts/size
55-
# The three floor caps (scripts/size/floor-caps.json) are frozen: a PR
55+
# The floor and page caps (scripts/size/floor-caps.json) are frozen: a PR
5656
# may lower them, never raise them, unless its body carries a
5757
# `Size-Exception:` line. Compared against the PR's base branch, so
5858
# PR events only.

‎documentation/plans/size-reduction-audit.md‎

Lines changed: 117 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ reproducible from this document.
88
Targets stated for this effort: hello world well under 10 KB; a server-component page ≤ 30–40 KB
99
on the upper end. Today: **12.6 / 47.3 / 46.5–53.5 KB**.
1010

11+
**Reframed 2026-09-26 (evening), after G was measured.** The target is the size every real app
12+
ships, not any single scenario. Every real app has async, hydration and (on the server-component
13+
path) the frames client; hello world is a vanity number and is now informational — its cap stays
14+
frozen as governance, not as a goal. Pay-for-use and tree-shaking work (B, C, E) moves bytes
15+
between chunks or out of apps that skip a feature; under this framing it is second-order. The
16+
first-order work is making the code everyone ships smaller with the same semantics: §4.I, the
17+
density audit, comes next.
18+
1119
## 1. Baseline
1220

1321
| Scenario | min | br | signals | solid-js | web | frames | sf |
@@ -169,17 +177,47 @@ Causes, each an "install everything on enable" pattern:
169177
preloads the materializer module (through the same manifest path `lazy()` chunks use) and the
170178
frames client awaits it before that scope's claim; when it didn't, nothing loads.
171179
- `solid-js` `enableHydration()` installs `_hydrateStoreLike` → `hydrateStoreLikeFn`,
172-
`hydrateStoreFromAsyncIterable`, `createShadowDraft`, `applyPatches` (~3.5K min, ~1.2 KB br)
173-
in every hydrating app, store or not. The wrappers that need it (`createStore` etc.) should
174-
import the adapter directly instead of reaching it through a slot the enabler fills.
180+
`hydrateStoreFromAsyncIterable`, `createShadowDraft`, `applyPatches` (~7.9K min un-mangled)
181+
in every hydrating app, store or not. **Measured and rejected (B.1, 2026-09-26).** Moving the
182+
reference into the wrappers (`createStore` etc.) saves **789 B** br on the hydrating no-store
183+
app — not the 1.2 KB estimated, since inside a hydrating bundle much of the adapter compresses
184+
against the signal-hydration code it resembles — and costs **+1,739 B** br on a CSR app that
185+
imports `createStore`: the adapter drags the generic hydration infrastructure it shares with
186+
signal hydration (`readSerializedOrCompute`, `wrapFirstYield`, `adoptedAnswerStream`,
187+
`quietAnswer`, `subFetch`, `MockPromise`, `withHydrationGate`, live-scope helpers, ~5.5K
188+
min) into a bundle that had none of it. Tree-shaking cannot express "retained only when
189+
`enableHydration` _and_ a store primitive are both referenced", so one deployment class pays
190+
either way; factoring the generic helpers behind their own slots would make the trade
191+
roughly symmetric (≈ −0.8 / +0.8) at the cost of threading a dozen helpers through slots — a
192+
zero-sum move. Only a separate import for the derived store form would make the conjunction
193+
expressible, and that is an API change. The hydrating no-store app does not pay for the
194+
store _engine_ (nothing from `signals/store/*` is retained); the 0.8 KB adapter is the only
195+
dead-by-construction piece, and it stays.
175196
- `solid-js` and `@solidjs/web` are flat single-file dists; route-level splitting through them
176197
fails (a lazy route's `createStore` colors the engine into the main chunk). `preserveModules`
177198
for both, as signals already does. This does not move the single-entry harness numbers
178199
(brotli layout shifts a little) but fixes real apps' route splits; the previous audit measured
179-
~9–10 KB br on the room example's `/`.
200+
~9–10 KB br on the room example's `/`. **Measured 2026-09-26: `preserveModules` alone does
201+
not fix it.** Chunk assignment is per _module_ in both esbuild and Rollup, and each package is
202+
effectively one module: a per-module build of `solid-js` yields `client/hydration.js` at
203+
114 KB unminified carrying the signal, store, boundary and root wrappers together
204+
(`flow.js` 14K, `component.js` 6K, `core.js` 6K, `index.js` 4K are the rest); `@solidjs/web`
205+
yields `client.js` at 104 KB (the entire DOM/attribute runtime) plus `index.js` 32K. A
206+
synthetic entry + lazy route that uses `createStore`, split with esbuild: flat dists put
207+
the store engine in the shared chunk (main route 21,795 B br); the per-module tree does the
208+
same (21,825 B). The store wrappers must live in their own module before route splitting
209+
can work — see §C.
180210
- `configureServerFunctionsClient` is installed by the frames client (needed — same instance),
181-
fine; but the sf client's `live` loop + ledger/resume path is carried by consumers that never
182-
call `live` (previous audit noted it as a split candidate; ~1 KB br).
211+
fine. The sf client's `live` loop + ledger/resume path was listed as carried by consumers that
212+
never call `live` (~1 KB br). **Measured 2026-09-26: not so.** `live`, `EventStreamReader`
213+
and the digests (~10.7K min un-mangled) already shake out of the base page; `live` reaches
214+
the shared reader through an `options[LIVE_WIRE]` seam, and the reader's residue on the base
215+
page is a few presence checks (< 0.3 KB br). `GET` (1.8K min) IS pinned on every page with a
216+
server reference — by design, through the late-bound RPC seam routers read instead of
217+
importing the transport — and a real page always has the router, so it is spoken for. What
218+
remains in the sf client for pay-for-use is the rich-argument request encoding
219+
(`getHeadersAndBody`/`extractBody`/`isJSONSafe`/`stableString`, ~5K min), which is §E's sf
220+
item.
183221

184222
### F5. `dynamic()` retains the element runtime — 4.3 KB br
185223

@@ -244,20 +282,25 @@ every real baseline; a signals-free frames client is out.
244282
`scripts/size` (the codec aliased to a stub, as it is a lazy chunk in production).
245283
- `attribute.mjs`: per-package minified bytes for every scenario, run after size-limit.
246284
- The three floor caps frozen in `floor-caps.json`; `check-floor-caps.mjs` fails a PR that
247-
raises one without a `Size-Exception:` line. Lowering is always allowed.
285+
raises one without a `Size-Exception:` line. Lowering is always allowed. The two page caps
286+
joined the freeze the same day (#3673 follow-up): the SC goal is the one the measured wins
287+
cover, so it gets the same protection against `next` growing under it.
248288
- Win: 0 bytes. This is the mitigation for `next` moving under the effort: growth becomes a
249289
per-PR decision the reviewer sees, not a paragraph in a 2,500-line config.
250290

251291
### B. Eager installs → pay-for-use (no semantics)
252292

253-
1. `enableHydration()` store adapters — the wrappers import the adapter directly; the enabler
254-
stops filling the slot. **−1.2 KB** every hydrating page.
293+
1. ~~`enableHydration()` store adapters — the wrappers import the adapter directly; the enabler
294+
stops filling the slot.~~ **Rejected after measurement** (F4): −0.8 KB on hydrating no-store
295+
pages, +1.7 KB on CSR pages with stores. Not shipped; the 0.8 KB stays in the hydrating
296+
floor and the §5 table below already excludes it (the SC pages never counted it).
255297
2. Frames materializer — loaded only when the server serialized a container trace (§D).
256298
**−7.1 KB** on SC pages without client stores.
257299
3. `dynamic()` element runtime — loaded only when the server rendered a string-tag `dynamic`
258300
(§D). **−4.3 KB** on every SC page.
259-
4. sf client `live` loop + ledger/resume split behind the `live` import. **~−1 KB** on the base
260-
page.
301+
4. ~~sf client `live` loop + ledger/resume split behind the `live` import.~~ **Already the
302+
case** (F4): `live` shakes out of the base page today; residue < 0.3 KB. Nothing to ship.
303+
The sf pay-for-use work is §E's rich-argument encoding split.
261304

262305
### C. Module layout (no semantics)
263306

@@ -285,38 +328,87 @@ of the scope that needs it. Build once, used three times.
285328
### F. Core floor without semantic change
286329

287330
Re-measure the stage-3 perf trade with CodSpeed; relocate cold arms behind existing slots.
288-
**−0.5 to −1 KB**, every scenario.
331+
**−0.5 to −1 KB**, every scenario. The relocation half is now measured
332+
(`size-reduction-g-rulings.md`, F1–F5): the async-iterable consumer (−322 B), the store sweep
333+
(−82), companions resync (−37), dormant sweep (−29), lane hook sites (−24) — **~−0.5 KB**
334+
together, each a small `packages/signals` PR behind an existing-style install hook. The
335+
perf-trade half remains an estimate.
289336

290337
### G. Core floor with behavior leniency (needs rulings)
291338

292-
The ~15 mainline implicit hold rules (F1, "behavior leniency"). Deliverable first: the ruling table (bytes,
293-
motivating issue, oracle cells). Then each accepted removal as its own PR — rule, tests and
294-
oracle cells together. **−1.5 to −2.5 KB**, every scenario.
339+
~~The ~15 mainline implicit hold rules (F1, "behavior leniency"). **−1.5 to −2.5 KB**.~~
340+
**Measured 2026-09-26 — see `size-reduction-g-rulings.md`.** Every rule site in `recompute`
341+
(21) and the scheduler (10) was stubbed and the floor re-measured: all of them together are
342+
**−824 B**; the largest single ruling (#3404 zombie children) is 127 B. The −1.5–2.5 estimate
343+
came from the growth ledger and was wrong by 2–3×: the ledger counted what each fix added,
344+
most of which is shared machinery later fixes also use. Even the model-level ceiling — no
345+
implicit holds anywhere, transactions only through `action` — measures **−1.2 KB**, because
346+
the machinery stays reachable from `runEffect`/`owner`/`heap` and the explicit paths. The
347+
bytes are the model (`GlobalQueue` 11.5K, `recompute` 7.5K, `handleAsync` 6K un-mangled), not
348+
the rules. **Recommendation: no rulings; take F's relocations instead.**
295349

296350
### H. Stores (follows G)
297351

298-
The store's `.v`/`.pb` arms that mirror whatever G removes. **−2 to −3 KB** for store users.
352+
~~The store's `.v`/`.pb` arms that mirror whatever G removes. **−2 to −3 KB** for store users.~~
353+
Falls with G: the store arms mirror rules whose removal is now measured at a few hundred bytes
354+
in core; their store twins will be the same order. Not pursued unless measured otherwise.
355+
356+
### I. Density — the code everyone ships, made smaller (no semantics)
357+
358+
Same rigor as G, aimed at "what does each package spend its bytes on" rather than "what could be
359+
shaken". Per package (signals 64.8K, frames client 31.8K, web 20.2K, solid 15.8K, sf 12.7K min
360+
on the base SC page), measured:
361+
362+
1. The stage-3 perf trade — hot paths inlined/specialized for CodSpeed (~15% of rc growth);
363+
re-measure which still pay, un-inline the rest.
364+
2. Property mangling headroom in `solid-js` and `@solidjs/web` (signals mangles `_` props with a
365+
shared name cache; the other two do not).
366+
3. The frames client and sf transport as implementations — duplicated helpers, generality with
367+
no consumer, prod-retained diagnostics. The largest unaudited surface on the page.
368+
4. Prod-retained strings and dev residue across all four packages.
369+
5. Model consolidation in signals (`GlobalQueue` + `recompute` + `handleAsync` + `read` ≈ 33K of
370+
68K un-mangled): fewer concepts with the same observable semantics. A redesign, not a size
371+
PR — decided after 1–4 are measured.
372+
373+
Considered and declined the same evening: an async engine behind a dynamic-import seam (hybrid:
374+
static install from any async-implying import, `import()` fallback from the first thenable).
375+
Measured −2.1 KB on the floor as a lower bound and it would reach hello world 10 with no API or
376+
semantic change for any realistic app — but it only helps apps with no async, which are
377+
benchmarks. Recorded in `size-reduction-g-rulings.md`; not pursued.
299378

300379
## 5. Expected landing (brotli, KB)
301380

302-
| | today | after B+C+D | + E | + F | + G+H |
303-
| ------------------------- | ----: | ----------: | ---: | ----: | ----------: |
304-
| hello world | 12.7 | 12.7 | 12.7 | ~11.8 | **~9.5–10** |
305-
| page: base SC | 46.8 | ~34.5 | ~30 | ~29 | **~27** |
306-
| page: live SC (no stores) | 51.1 | ~39.5 | ~36 | ~35 | **~33** |
307-
| live SC + client stores | ~54 | ~48 | ~45 | ~44 | **~39** |
381+
| | today | after B+C+D | + E | + F | + G+H |
382+
| ------------------------- | ----: | ----------: | ---: | ----: | -------------: |
383+
| hello world | 12.7 | 12.7 | 12.7 | ~11.5 | **~10.6–11.1** |
384+
| page: base SC | 46.9 | ~35.3 | ~31 | ~30 | **~28** |
385+
| page: live SC (no stores) | 51.2 | ~40.4 | ~37 | ~36 | **~34** |
386+
| live SC + client stores | ~54 | ~49 | ~46 | ~45 | **~40** |
308387

309388
Goals: hello world 10, SC pages 30–40. Both SC pages reach the band on packaging alone; the
310-
page with client stores sits at the top of it; hello world reaches 10 only with G.
389+
page with client stores sits at the top of it. **Hello world does not reach 10 under the fixed
390+
API** (G measured, 2026-09-26): the floor is 9.9 of hello world's 12.7, and every semantic
391+
lever together — rulings, relocations, the model-level ceiling — is worth ~1.1–1.2 KB, the
392+
perf-trade re-measure perhaps another 0.5–1; that lands at ~10.6–11.1. The one lever that
393+
reaches 10 is keeping `handleAsync` and the transaction entry it drives off the plain
394+
`createSignal`/`createMemo` path — a packaging/API decision recorded as out of scope in §2.
395+
(Table
396+
re-based 2026-09-26 without B.1 and on the `next` @ 3af4696fb baselines; B.1 was −0.8 on the
397+
hydrating column of the SC pages, so B+C+D lands ~0.8 higher than first estimated.)
311398

312399
## 6. Order and risk
313400

314401
1. A — one PR, no runtime change, lands before any cutting.
315-
2. B.1 and B.4 (isolated modules, low conflict).
402+
2. ~~B.1 and B.4~~ — both measured 2026-09-26: B.1 rejected (zero-sum across deployment
403+
classes), B.4 already the case. See F4. Category B is B.2 and B.3, both behind C and D.
316404
3. C, then D, then B.2 and B.3 on top of D. D touches SSR and the frames client where Stage 8
317405
is active: one focused PR, timed with that work.
318406
4. E in parallel once D exists.
319-
5. F any time; G's ruling table in parallel; G+H implementation after the rulings.
407+
5. ~~F any time; G's ruling table in parallel; G+H implementation after the rulings.~~ G
408+
measured and closed (`size-reduction-g-rulings.md`); H falls with it. F's relocations fold
409+
into whatever later touches `flush`; not a separate effort.
410+
6. **I (density audit) is next** — before D/C/E, since it decides whether "smaller for
411+
everyone" has 5 KB in it or 15, and that decides how much of B–E is worth building.
320412

321413
Every category ships to `next` as its own small PR, rebased daily; no long-lived branch. Each PR
322414
reports before/after on the same base commit, and `next`'s number is recorded at each landing so

0 commit comments

Comments
 (0)