Skip to content

Commit 55e2022

Browse files
ryansolidClaude via Cursorcursoragent
authored
chore(size): measurement and governance for the size-reduction effort (#3673)
Category A of documentation/plans/size-reduction-audit.md. - Freeze the three floor caps (core floor, hello world, hydrating no-stores) in scripts/size/floor-caps.json. A PR-only CI step fails when a cap is raised relative to the base branch unless the PR body carries a `Size-Exception:` line, so `next` cannot ratchet the floor upward while the reduction work is in flight. - Add two server-component page scenarios (base and live) that exercise the actual client surface of an SC page: hydrate + dynamic() + frames client + server-function reference (+ live/GET/action/isPending/latest). The lazily imported seroval codec is aliased to a stub so size-limit's no-splitting build does not inline it. - Add scripts/size/attribute.mjs: per-package byte attribution for every scenario via esbuild's metafile, run after size-limit in `npm run size`. - Record the audit, baselines, findings, and the agreed categorical plan. - Re-baseline the page caps to `next` @ 3af4696. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 3af4696 commit 55e2022

12 files changed

Lines changed: 677 additions & 13 deletions

File tree

‎.github/workflows/size.yml‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ name: Size
1212
# (absolute limits, no base ref), and PR-only triggering let the
1313
# +createStore scenario sit failing at a release commit unnoticed — direct
1414
# pushes never measured. The compare job stays PR-only; it needs a PR
15-
# context (base branch, comment target).
15+
# context (base branch, comment target). The floor-cap freeze step in check
16+
# is PR-only for the same reason (it diffs against the base branch).
1617
on:
1718
push:
1819
branches: [next]
@@ -46,8 +47,22 @@ jobs:
4647
- run: pnpm build
4748
- run: npm ci --no-audit --no-fund
4849
working-directory: scripts/size
50+
# size-limit gates every scenario against its cap, then attribute.mjs
51+
# prints per-package minified bytes for each so a bump is attributed
52+
# in the same log that reports it.
4953
- run: npm run size
5054
working-directory: scripts/size
55+
# The three floor caps (scripts/size/floor-caps.json) are frozen: a PR
56+
# may lower them, never raise them, unless its body carries a
57+
# `Size-Exception:` line. Compared against the PR's base branch, so
58+
# PR events only.
59+
- if: github.event_name == 'pull_request'
60+
run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
61+
- if: github.event_name == 'pull_request'
62+
run: npm run check-floor-caps -- "origin/${{ github.base_ref }}"
63+
working-directory: scripts/size
64+
env:
65+
SIZE_EXCEPTION: ${{ github.event.pull_request.body }}
5166

5267
# Best-effort base-vs-head delta comment. Requires the base branch to also
5368
# carry scripts/size/, so it is informational and never blocks: continue-on-error

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

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

‎scripts/size/.size-limit.js‎

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,32 @@ const alias = {
1515
};
1616
const modifyEsbuildConfig = config => ({ ...config, alias });
1717

18+
// The three floor caps are FROZEN (size-reduction effort, 2026-09-26 —
19+
// documentation/plans/size-reduction-audit.md §A): they live in
20+
// floor-caps.json, and check-floor-caps.mjs fails a PR that raises one
21+
// without a `Size-Exception:` line in its body. Lowering is always allowed.
22+
// The dated notes on each scenario below remain the ledger of how the
23+
// floor got here.
24+
const floorCaps = require("./floor-caps.json");
25+
26+
// Server-component PAGES (audit §1): everything such a page ships eagerly,
27+
// nothing external — the frames client and the server-function transport
28+
// resolve to their dists alongside solid-js/web/signals. The seroval codec
29+
// is a dynamic import in both clients and a separate chunk in production;
30+
// size-limit does not split, so the specifiers resolve to lazy-codec.js (the
31+
// import site stays, the chunk's ~5 KB brotli does not inline). The
32+
// "frames: eager client consumer" scenario measures the package; these
33+
// measure the page. Subpath aliases first (prefix matching, see above).
34+
const pageAlias = {
35+
"@solidjs/web/server-functions/client": "../../packages/web/server-functions/dist/client.js",
36+
"@solidjs/web/server-functions": "../../packages/web/server-functions/dist/client.js",
37+
"@solidjs/web/frames": "../../packages/web/frames/dist/client.js",
38+
"@solidjs/web/serialization/decode": "./lazy-codec.js",
39+
"@solidjs/web/serialization": "./lazy-codec.js",
40+
...alias
41+
};
42+
const pageEsbuildConfig = config => ({ ...config, alias: pageAlias });
43+
1844
// Observe tier (documentation/plans/observe-tier-plan.md): the artifacts the
1945
// `observe` export condition selects — wiring kept (attribution hook sites,
2046
// owner labels, edge counters, the diagnostics channel), checks folded. Its
@@ -384,7 +410,7 @@ module.exports = [
384410
// 38 B, the rest is the flag's parking (with the drain entry), tail and
385411
// commit sites. Every scenario below moves by +52..+113 B brotli (the
386412
// same retained core).
387-
limit: "9.94 KB",
413+
limit: floorCaps["signals: core floor (createSignal/Memo/Effect/Root/flush)"],
388414
modifyEsbuildConfig
389415
},
390416
{
@@ -1084,7 +1110,7 @@ module.exports = [
10841110
// A lane frame is the run's (#3662, 2026-09-26): 12.67 -> 12.78 KB,
10851111
// measured at 12,725 B against `next`'s 12,619 (+106 B). Core-retained ripple of the
10861112
// lane-frame sites — see the core floor note.
1087-
limit: "12.78 KB",
1113+
limit: floorCaps["app: render + one signal (the simple-app floor)"],
10881114
modifyEsbuildConfig
10891115
},
10901116
{
@@ -1356,7 +1382,7 @@ module.exports = [
13561382
// A lane frame is the run's (#3662, 2026-09-26): 21.32 -> 21.43 KB,
13571383
// measured at 21,418 B against `next`'s 21,305 (+113 B). Core-retained ripple of the
13581384
// lane-frame sites — see the core floor note.
1359-
limit: "21.43 KB",
1385+
limit: floorCaps["app: hydrating (no stores) with Show/For/Loading/Errored/lazy"],
13601386
modifyEsbuildConfig
13611387
},
13621388
{
@@ -2545,5 +2571,34 @@ module.exports = [
25452571
path: "../../packages/web/frames/dist/client.js",
25462572
limit: "12.42 KB",
25472573
modifyEsbuildConfig: framesEsbuildConfig
2574+
},
2575+
{
2576+
name: "page: base server components (hydrating + dynamic + frames + sf reference)",
2577+
// Size-reduction audit baseline (2026-09-26, next @ 3af4696fb): the
2578+
// whole eager graph of a server-component page with no client stores.
2579+
// Per-package (minified, attribute.mjs): signals 64.8K, frames client
2580+
// 31.8K, web 20.2K, solid-js 15.8K, sf client 12.7K. Two of those are known
2581+
// eager costs the audit's packaging tier removes — the frames client
2582+
// installing the container-trace materializer at load (the store engine,
2583+
// ~7.1 KB brotli of this number) and dynamic()'s string-tag branch
2584+
// retaining the spread attribute runtime (~4.3 KB). This cap is a
2585+
// baseline to cut from, not headroom to grow into.
2586+
// Rebased onto `next` @ 3af4696fb (2026-09-26): 46,757 -> 46,852 B
2587+
// (+95 B) — #3671's async dynamic() landing serialization/adoption in
2588+
// web and solid-js, and #3670's draft-visibility twin in the store.
2589+
path: "sc-base-app.js",
2590+
limit: "46.86 KB",
2591+
modifyEsbuildConfig: pageEsbuildConfig
2592+
},
2593+
{
2594+
name: "page: live server components (base + live/GET + action + isPending/latest)",
2595+
// Same baseline for the live page: the base page plus the sf client's
2596+
// live loop and GET, `action`, and the verdict (isPending/latest, which
2597+
// the router retains on every real page anyway). Still no client stores.
2598+
// Rebased onto `next` @ 3af4696fb (2026-09-26): 51,103 -> 51,156 B
2599+
// (+53 B), same two commits as the base page.
2600+
path: "sc-live-app.js",
2601+
limit: "51.16 KB",
2602+
modifyEsbuildConfig: pageEsbuildConfig
25482603
}
25492604
];

‎scripts/size/README.md‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,47 @@
22

33
Tree-shaken import-cost tracking: `.size-limit.js` defines scenario entries
44
(signals floor, +createStore, +isPending/latest, the render+one-signal simple
5-
app, a representative CSR app, and a hydrating pair — with and without store
6-
primitives — that keeps the store engine pay-for-use under `hydrate()`) with
7-
hard gzip-limits. CI fails when a scenario
8-
exceeds its limit — that means tree-shaking regressed, or a deliberate feature
9-
landed and the limit should be bumped in the same PR with a reason. The
10-
simple-app scenario is pinned at 10 KB on purpose.
5+
app, a representative CSR app, a hydrating pair — with and without store
6+
primitives — that keeps the store engine pay-for-use under `hydrate()`, the
7+
frames client as a package, and two server-component PAGES: base and live)
8+
with hard brotli limits. CI fails when a scenario exceeds its limit — that
9+
means tree-shaking regressed, or a deliberate feature landed and the limit
10+
should be bumped in the same PR with a reason.
11+
12+
## Frozen floor caps
13+
14+
The three floor scenarios — the signals floor, the simple app, and the
15+
hydrating app without stores — have their caps in `floor-caps.json`, not in
16+
`.size-limit.js`. They are **frozen**: a PR may lower them, never raise them.
17+
`check-floor-caps.mjs` diffs the file against the PR's base branch in CI and
18+
fails on a raise unless the PR body contains a line starting with
19+
`Size-Exception:` naming why the maintainer accepted the cost. Ten weeks of
20+
individually justified 10–300 B bumps took the signals floor from 7.1 to
21+
9.9 KB; the freeze makes the next one a decision, not a paragraph. See
22+
`documentation/plans/size-reduction-audit.md`.
23+
24+
## Attribution
25+
26+
`npm run size` runs size-limit and then `attribute.mjs`, which bundles every
27+
scenario the same way with an esbuild metafile and prints the minified bytes
28+
each package contributed (`signals`, `solid`, `web`, `web/frames`,
29+
`web/server-functions`, …). Minified bytes are the attributable unit; brotli
30+
compresses across module boundaries. `node attribute.mjs --modules [name]`
31+
lists the individual dist modules of matching scenarios.
32+
33+
## Layout
1134

1235
This directory is deliberately **outside the pnpm workspace**, with its own
1336
npm lockfile. Its tooling must never enter the workspace dependency graph:
1437
changing that graph re-keys pnpm peer instances (vitest,
1538
@codspeed/vitest-plugin), which relocates the benchmark harness and shows up
1639
as phantom CodSpeed regressions. Nothing here is published (`private: true`).
1740

41+
The page scenarios alias the seroval codec to `lazy-codec.js`: both clients
42+
load it through a dynamic import (a separate chunk in production) and
43+
size-limit does not split, so the stub keeps the import site without inlining
44+
the chunk. `lazy-page.js` plays the same role for `lazy()`.
45+
1846
Run locally: `cd scripts/size && npm ci && npm run size` (build the repo
1947
first). The retained-module-graph test in
2048
`packages/signals/tests/treeshake.test.ts` is the companion diagnostic

‎scripts/size/attribute.mjs‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
// Per-package attribution for every scenario in .size-limit.js.
2+
//
3+
// size-limit answers "did the cap hold"; this answers "which package moved".
4+
// Each scenario is bundled the way size-limit bundles it (same entry, same
5+
// alias/external through modifyEsbuildConfig, no code splitting) with an
6+
// esbuild metafile, and the minified bytes each input contributed to the
7+
// output are summed per package. Minified bytes are the attributable unit —
8+
// brotli compresses across module boundaries, so the compressed total is
9+
// reported for the bundle only. Runs after size-limit in `npm run size`.
10+
//
11+
// Usage: node attribute.mjs [--modules] [scenario-substring ...]
12+
// --modules also list the individual dist modules over 200 minified bytes
13+
14+
import { createRequire } from "node:module";
15+
import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
16+
import { tmpdir } from "node:os";
17+
import { join, dirname } from "node:path";
18+
import { fileURLToPath } from "node:url";
19+
import { brotliCompressSync, constants } from "node:zlib";
20+
import { build } from "esbuild";
21+
22+
const here = dirname(fileURLToPath(import.meta.url));
23+
const checks = createRequire(import.meta.url)("./.size-limit.js");
24+
25+
const args = process.argv.slice(2);
26+
const listModules = args.includes("--modules");
27+
const filters = args.filter(a => !a.startsWith("--"));
28+
29+
// Maps an esbuild input path to the package that shipped it. Anything not
30+
// under packages/ (the scenario file itself, node_modules deps such as
31+
// seroval) is grouped as "other".
32+
function packageOf(input) {
33+
const m = input.match(/packages\/([^/]+)\/(?:([^/]+)\/)?dist\//);
34+
if (!m) return "other";
35+
const [, pkg, sub] = m;
36+
// packages/web/frames/dist → web/frames; packages/web/dist → web
37+
return sub && sub !== "dist" ? `${pkg}/${sub}` : pkg;
38+
}
39+
40+
function moduleOf(input) {
41+
return input.replace(/^.*packages\//, "").replace(/\/dist\/(prod\/)?/, ":");
42+
}
43+
44+
const brotli = buf =>
45+
brotliCompressSync(buf, { params: { [constants.BROTLI_PARAM_QUALITY]: 11 } }).length;
46+
47+
const scratch = mkdtempSync(join(tmpdir(), "solid-size-attr-"));
48+
try {
49+
for (const check of checks) {
50+
if (filters.length && !filters.some(f => check.name.includes(f))) continue;
51+
// Mirror size-limit's `import` option: an entry that imports the named
52+
// bindings from `path` and keeps them alive with a console.log.
53+
let entry = join(here, check.path);
54+
if (check.import) {
55+
const list = check.import.replace(/[{}]/g, "").trim();
56+
entry = join(scratch, `${check.name.replace(/\W+/g, "-")}.js`);
57+
writeFileSync(
58+
entry,
59+
`import ${check.import} from ${JSON.stringify(join(here, check.path))};\nconsole.log(${list});\n`
60+
);
61+
}
62+
let config = {
63+
absWorkingDir: here,
64+
bundle: true,
65+
entryPoints: [entry],
66+
metafile: true,
67+
minify: true,
68+
treeShaking: true,
69+
write: false,
70+
logLevel: "silent"
71+
};
72+
if (check.modifyEsbuildConfig) config = check.modifyEsbuildConfig(config);
73+
const result = await build(config);
74+
const output =
75+
Object.values(result.metafile.outputs).find(o => o.entryPoint) ??
76+
Object.values(result.metafile.outputs)[0];
77+
const bytes = result.outputFiles.reduce((s, f) => s + f.contents.length, 0);
78+
const br = result.outputFiles.reduce((s, f) => s + brotli(f.contents), 0);
79+
80+
const byPackage = new Map();
81+
const byModule = [];
82+
for (const [input, { bytesInOutput }] of Object.entries(output.inputs)) {
83+
const pkg = packageOf(input);
84+
byPackage.set(pkg, (byPackage.get(pkg) ?? 0) + bytesInOutput);
85+
if (bytesInOutput > 200 && pkg !== "other") byModule.push([moduleOf(input), bytesInOutput]);
86+
}
87+
const packages = [...byPackage].sort((a, b) => b[1] - a[1]);
88+
89+
console.log(`\n${check.name}`);
90+
console.log(` minified ${bytes} B brotli ${br} B`);
91+
console.log(" " + packages.map(([p, b]) => `${p}=${b}`).join(" "));
92+
if (listModules)
93+
for (const [m, b] of byModule.sort((a, b) => b[1] - a[1]))
94+
console.log(` ${String(b).padStart(7)} ${m}`);
95+
}
96+
} finally {
97+
rmSync(scratch, { recursive: true, force: true });
98+
}

‎scripts/size/check-floor-caps.mjs‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
// The floor caps are frozen: a PR may lower them, never raise them, unless it
2+
// carries an explicit exception. size-limit enforces the caps themselves;
3+
// this enforces that the caps did not move.
4+
//
5+
// Why a separate check: for ten weeks the floor scenarios grew through
6+
// individually justified 10–300 B bumps (7.1 → 9.8 KB brotli on the signals
7+
// floor), each recorded in .size-limit.js and none resisted. Moving the three
8+
// floor caps into floor-caps.json and diffing that file against the base
9+
// branch turns a bump from a paragraph into a decision the reviewer sees.
10+
//
11+
// Usage: node check-floor-caps.mjs <base-ref>
12+
// Compares floor-caps.json at HEAD with the same file at <base-ref>. Exits
13+
// non-zero if any cap increased, unless SIZE_EXCEPTION (the PR body, in CI)
14+
// contains a line starting with "Size-Exception:" that names the reason.
15+
// A cap absent at the base (a new floor scenario) is allowed.
16+
17+
import { readFileSync } from "node:fs";
18+
import { execFileSync } from "node:child_process";
19+
import { dirname, join, relative } from "node:path";
20+
import { fileURLToPath } from "node:url";
21+
22+
const here = dirname(fileURLToPath(import.meta.url));
23+
const base = process.argv[2];
24+
if (!base) {
25+
console.error("usage: node check-floor-caps.mjs <base-ref>");
26+
process.exit(2);
27+
}
28+
29+
// size-limit's units are decimal (1 KB = 1000 B).
30+
const toBytes = s => {
31+
const m = String(s)
32+
.trim()
33+
.match(/^([\d.]+)\s*(B|KB|MB)?$/i);
34+
if (!m) throw new Error(`unparseable cap "${s}"`);
35+
const n = parseFloat(m[1]);
36+
const unit = (m[2] ?? "B").toUpperCase();
37+
return unit === "MB" ? n * 1e6 : unit === "KB" ? n * 1e3 : n;
38+
};
39+
40+
const head = JSON.parse(readFileSync(join(here, "floor-caps.json"), "utf8"));
41+
const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
42+
cwd: here,
43+
encoding: "utf8"
44+
}).trim();
45+
const relPath = relative(repoRoot, join(here, "floor-caps.json"));
46+
let baseCaps = {};
47+
try {
48+
baseCaps = JSON.parse(
49+
execFileSync("git", ["show", `${base}:${relPath}`], { cwd: repoRoot, encoding: "utf8" })
50+
);
51+
} catch {
52+
console.log(`floor-caps: ${relPath} absent at ${base}; nothing to compare.`);
53+
process.exit(0);
54+
}
55+
56+
const exception = /^\s*Size-Exception:\s*\S/m.test(process.env.SIZE_EXCEPTION ?? "");
57+
let raised = [];
58+
for (const [name, cap] of Object.entries(head)) {
59+
if (!(name in baseCaps)) continue;
60+
const before = toBytes(baseCaps[name]);
61+
const after = toBytes(cap);
62+
if (after > before) raised.push(` ${name}: ${baseCaps[name]} -> ${cap}`);
63+
}
64+
65+
if (raised.length === 0) {
66+
console.log("floor-caps: no cap raised.");
67+
} else if (exception) {
68+
console.log("floor-caps: cap(s) raised under an explicit Size-Exception:\n" + raised.join("\n"));
69+
} else {
70+
console.error(
71+
"floor-caps: a frozen floor cap was raised without an exception:\n" +
72+
raised.join("\n") +
73+
"\n\nRelocate the retained bytes out of the floor instead (the winning move is a\n" +
74+
"pay-for-use module; see .cursor/rules/signals.mdc), or — if the maintainer has\n" +
75+
"accepted the cost — add a line to the PR body:\n\n" +
76+
" Size-Exception: <why this floor cost is accepted>\n"
77+
);
78+
process.exit(1);
79+
}

‎scripts/size/floor-caps.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"signals: core floor (createSignal/Memo/Effect/Root/flush)": "9.94 KB",
3+
"app: render + one signal (the simple-app floor)": "12.78 KB",
4+
"app: hydrating (no stores) with Show/For/Loading/Errored/lazy": "21.43 KB"
5+
}

‎scripts/size/lazy-codec.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// Stands in for `@solidjs/web/serialization` and `/decode` in the page
2+
// scenarios. The frames client loads the seroval codec through a dynamic
3+
// import (its `prepareData` hook), so in production it is a separate chunk
4+
// fetched on the first `data` record. size-limit bundles without code
5+
// splitting and would inline that chunk (~5 KB brotli of seroval) into the
6+
// eager number; aliasing the specifiers here keeps the import site and
7+
// leaves the codec's own cost to the serialization tests.
8+
export function createJSONDeserializer() {}
9+
export function createJSONDataTable() {}
10+
export function serializeJSON() {}

‎scripts/size/package-lock.json‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)