Skip to content

Commit b10c824

Browse files
ryansolidClaude via Cursorcursoragent
authored
docs(perf): Props Composition Lane — the yak tracker hand-off (#3389) (#3702)
Journal section for #3389 (2026-09-12 → 2026-09-28): instruments (yak-bench, browser CPU attribution), the thirteen experiments with their PRs and numbers, the rc.10 client profile that closed the hydration item, the two 2026-09-28 client probes (spread walk classify-once: ±1%; plain-only view materialization: +12–14% on chains) and the rulings that fall out — server views / client copies, walk and representation are not the client lever, cold tier, perf vs size — plus the open targets in order, first among them per-row node count in the reactive core. benchmarking-strategy lists yak-bench under Tier 2. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent d0e487b commit b10c824

2 files changed

Lines changed: 289 additions & 0 deletions

File tree

‎documentation/benchmarking-strategy.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,12 @@ for Tier 1:
231231
- `js-reactivity-benchmark` for Node-side reactivity regressions.
232232
- DBMon / Sierpinski / per-app demos for paint/layout-sensitive
233233
scenarios — used ad hoc.
234+
- `yak-bench` (`ryansolid/yak-bench`) for props composition and SSR
235+
element shapes: a CSS-in-JS library's runtime built against Solid
236+
primitives vs its hand-rolled versions vs React, SSR and Chromium
237+
hydrate/mount, with `SOLID_DIR` A/Bs of a local checkout. Instruments
238+
and rulings in the
239+
[Props Composition Lane](./performance-experiments.md#props-composition-lane-2026-09-12--2026-09-28-the-yak-tracker).
234240

235241
### Roadmap (Tier 2 first, Tier 1 on demand)
236242

‎documentation/performance-experiments.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7512,3 +7512,286 @@ code the shared predicates (S4, S5, S7 fixed; S6 ruled and deferred in
75127512
#3526 at +402 B) and it added the `memoUntracked`/`effectUntracked`
75137513
reader kinds to the 851-cell posture matrix. Relevant here because
75147514
disposal and companion cleanup are the paths it touched most recently.
7515+
7516+
## Props Composition Lane (2026-09-12 → 2026-09-28): the yak tracker
7517+
7518+
Tracker: solidjs/solid#3389, closed 2026-09-28. The trigger was
7519+
DigitecGalaxus/next-yak#644, a rewrite of the `@yak/solid` `styled()`
7520+
runtime that made it 12× faster on SSR and ~2× on hydrate/mount by
7521+
re-implementing, by hand, the primitives it should have been calling:
7522+
`ssrElement`, `merge`/`omit`, `dynamic()`, a theme merge, a server memo.
7523+
The goal, set on day one and never changed: **a library calling the Solid
7524+
primitive lands within noise of the hand-rolled version in yak's own
7525+
harness.** Reached on rc.10; the remaining question — how far the same
7526+
shapes sit from React — is answered below with an attribution, and the
7527+
answer is the reactive core, not props plumbing.
7528+
7529+
This section is the hand-off. Every number is from a committed results
7530+
file in the harness, a PR, or a comment on the tracker.
7531+
7532+
### Instruments
7533+
7534+
- **yak-bench** — `ryansolid/yak-bench`, local `~/Development/yak-bench`.
7535+
The 14 `css-in-js-bench` workloads plus `polymorphic-chain` (a pure-Solid
7536+
Kobalte-shaped chain, no CSS-in-JS: three component layers of
7537+
`merge`/`omit`/spread over `dynamic()`), each lane an esbuild of a
7538+
`@yak/solid` revision or overlay (`scripts/config.mjs`: `VARIANTS`,
7539+
`ALL_LANES`; the `mprim` overlay is "every hand-rolled piece → Solid
7540+
primitives" behind `__PRIM_{SSR,MEMO,PROPS,THEME}__` defines) with
7541+
`next-yak`/React as the reference lane. `node scripts/build-lanes.mjs`
7542+
(`LANES=…`), `node scripts/verify.mjs` (SSR output byte-identity modulo
7543+
separators — the correctness gate), `node scripts/bench-ssr.mjs`,
7544+
`PLAYWRIGHT_BROWSERS_PATH=$HOME/Library/Caches/ms-playwright node
7545+
scripts/bench-browser.mjs --measure=hydrate,mount --case=…` (Chromium,
7546+
`CPU_THROTTLE` 4 by default, fresh page per sample, `SAMPLES_HYDRATE` /
7547+
`SAMPLES_MOUNT`, lanes round-robin per sample). `TAG=<name>` keeps
7548+
builds and reports apart (`dist/<TAG>`, `result/*-latest-<TAG>.md`);
7549+
`SOLID_DIR=<checkout>` bundles that checkout's `packages/*/dist` and
7550+
compiles with its Babel plugin, so a Solid A/B is two `TAG`s built from
7551+
two trees. `TAG` leaks into later shell commands — unset it. Results:
7552+
`result/ssr-latest-rc10-{1,2}.md`, `result/ssr-latest-rc10-flags.md`,
7553+
`result/browser-latest-rc10-client*.md`, `result/browser-latest-sw*.md`
7554+
(the 2026-09-28 A/Bs below; uncommitted at hand-off).
7555+
- **Browser CPU attribution.** Build a lane unminified (`TAG=prof
7556+
MINIFY=0`), capture with Playwright CDP `Profiler` at 50 µs sampling,
7557+
map frames through the bundle's sourcemap (`@jridgewell/trace-mapping`),
7558+
and count only samples whose stack passes through the lane's
7559+
`browser-entry.tsx` hydrate/mount call (React's through
7560+
`performWorkUntilDeadline` / `commitRoot`); `(program)` and GC samples
7561+
count when both neighbouring JS samples are in-window. Scripts
7562+
`hydrate-prof.mjs`, `attr-browser.mjs` (ms/page by category),
7563+
`callers.mjs` (inclusive time of a function by caller chain),
7564+
`self.mjs` (node `--cpu-prof` self time) live in `/tmp/cprof/` — **not
7565+
under version control**; move them into `yak-bench/scripts/` before
7566+
they are lost.
7567+
- **In-repo tier-1** (`packages/web/test/*.bench.tsx`, jsdom):
7568+
`polymorphic-chain.bench.tsx` (compiled floor vs chain, mount+clear 1k
7569+
and update 10th), `spread-enumerate.bench.tsx`,
7570+
`spread-array-form.bench.tsx` (added 2026-09-28 on branch
7571+
`perf/spread-walk`: create / runtime-only against a stub node / update,
7572+
for the array form, the object form and a plain copy, with floors).
7573+
Direction only — see the cold-tier ruling below.
7574+
7575+
### Experiments, in order
7576+
7577+
Each entry: what → where → measured → verdict. SSR ratios are
7578+
instances/s, browser ratios ms; `>1` is Solid's favour unless stated.
7579+
7580+
**1. `spread()` → one render effect per element** (#3419; compilers emit
7581+
the array form for element spreads, #3423 / #3424). Three reactive nodes
7582+
per element became one without children, two with; `ref` folded into the
7583+
attribute effect; sources as an array so a function source is read
7584+
inline (no memo, no hydration id). Browser hydrate on the styled-element
7585+
shape 1.47× behind yak's hand path → 1.00×.
7586+
7587+
**2. `dynamic(source, { static })` + `isStatic(o, key)`** (#3471; #3386
7588+
parts in #3396 / #3436). No factory + instance memo for a tag that cannot
7589+
change; the library decides per instance from the prop's descriptor,
7590+
which is the compiler's own static/dynamic classification (`as="a"` is a
7591+
data property, `as={expr}` a getter), seen through merge/omit layers.
7592+
7593+
**3. Lazy `merge`/`omit` views** (#3454, protocol behind
7594+
`solid-js/internal` #3470, table-on-enumeration-or-16-reads #3475, omit
7595+
holds the merge _record_ #3497; #3487 closed unmerged — no fold form of
7596+
the hidden-key list beat `slice()`+`push` on instruction count). A view is
7597+
a record + one Proxy, O(1) per layer; consumers (`spread`, `ssrElement`, a
7598+
nested merge) walk the records, never the traps. Kobalte-shaped depth-7
7599+
chain build+consume +62%; yak-bench composition cases 0.8× → 0.95–0.99×
7600+
of yak's hand-rolled runtime; SSR chain 8.2× → 5.8× the compiled floor.
7601+
The `#3448` ruling — always a view, never a copy — is the one item 12
7602+
below re-tests on the client.
7603+
7604+
**4. `ssrElement(tag, sources[], children, needsId, skip?)`** (#3418,
7605+
#3486 plain-children concat in place, #3562 trailing `attrs` markup + per-
7606+
tag record cache). Single walk, later wins, winner read once; element
7607+
path vs a hand writer 22 → 9 ns/element. Fully static shapes stay ~3×
7608+
behind yak because yak string-concats them at definition time — not our
7609+
gap.
7610+
7611+
**5. Hydration claim trims** (#3513: `gatherHydratable` frame gate,
7612+
one-pass claim copy in `insert()`, `clearSnapshots` assign-not-delete).
7613+
Net ~3% of hydrate on `tabs`, under the 2.1 ms estimate; the rest of
7614+
`gatherHydratable` is the registry itself.
7615+
7616+
**6. The props literal** (#3511 → #3514 plain keys, #3550 `hoistProps`:
7617+
one hoisted per-site constructor, shared getter descriptors, fast-mode
7618+
instance; the contract that a getter is defined for a read through its
7619+
own object, dev-enforced; `omit()`'s no-Proxy path re-homes). yak-bench
7620+
SSR geomean 1.12×, composition 1.15–1.31×, Octane flat. Client half of
7621+
the same spike: **time-neutral** (1.00× geomean hydrate and mount, six
7622+
component-heavy cases) — the composition-case client gap was never the
7623+
literal.
7624+
7625+
**7. Theme merge** — `merge({ theme }, props)` measured at parity with
7626+
yak's shared-handler view (`__PRIM_THEME__` 1.03× geomean); yak-side
7627+
deletion is theirs.
7628+
7629+
**8. rc.10 re-run, published packages, stock native compiler**
7630+
(2026-09-26/27, `result/ssr-latest-rc10-{1,2}.md`). yak+#658 vs `mprim`
7631+
geomean 1.06× / 1.01× over two rounds — parity; `tabs` 0.67–0.68× and
7632+
`multifile-composition` 0.68–0.73× (ours by 1.4–1.5×); the four
7633+
computed-class micro-cases yak's by 1.17–1.38×. One primitive at a time
7634+
(`ssr-latest-rc10-flags.md`): the props view is the only swap that wins
7635+
for yak (0.97× geomean, +49% on their composition cases); `ssrElement`
7636+
(1.07×), the theme merge (1.06×) and the server memo (1.04×) are Solid's
7637+
remaining 4–7% each. Filed downstream as DigitecGalaxus/next-yak#658
7638+
(descriptor re-home) and #659 (props views + `spread()` array form on
7639+
tag targets; `tabs` 1.48–1.51× over #658).
7640+
7641+
**9. rc.10 client profile — the hydration item closed as not a hydration
7642+
problem** (2026-09-28, tracker comment). Harness at 4×: hydrate `tabs`
7643+
0.50× React, `multifile-composition` 0.48×, `polymorphic-chain` 0.58×;
7644+
mount 0.70× / 0.65× / 0.69×; Solid's hydrate slower than its own mount
7645+
(57 vs 42 ms on `tabs`), React's equal. Unthrottled ms/page on `tabs`
7646+
(Solid hydrate 18.1 / mount 15.2, React 6.6 / 9.0):
7647+
7648+
| | Solid hydrate | Solid mount | React hydrate |
7649+
| --------------------------------------------- | ------------: | ----------: | ------------: |
7650+
| `merge`/`omit` views + `spread()` source walk | 3.5 | 3.2 | 0.5 |
7651+
| graph construction + effects + scheduler | 2.6 | 2.5 | fiber ≈ 4.0 |
7652+
| hydration claim machinery | 3.4 | 0.1 | ≈ 0.3 |
7653+
| GC | 1.6 | 1.4 | 1.2 |
7654+
| attributes + DOM writes | 1.1 | 2.6 | — |
7655+
| yak runtime + case code + component layer | 3.4 | 3.2 | 0.9 |
7656+
7657+
The claim machinery (registry 0.69, `getNextElement` 0.57, `isHydrating`
7658+
0.42, `claimChildNodes` 0.34, per-node probes ≈ 1.0) is exactly the
7659+
hydrate-over-mount excess; removing all of it leaves 14.7 ms against
7660+
React's 6.6. Local trims ≤ 1 ms/page. No registry redesign filed.
7661+
7662+
**10. `btn-variant` client parity** — yak's hand path 16–22% ahead of
7663+
`mprim`; not the baked-class template but `omit()` + the array-form
7664+
`spread()` per element (+1.4 µs: view construction/reads 0.66 ms/1000,
7665+
walk 0.5, GC 0.25, vs a 4-descriptor copy at 0.35). #659 carried the same
7666+
+12–15% on its dynamic-prop tag cases; amended (85a43b6) to copy on the
7667+
fixed-key client tag path. Back to 1.00×.
7668+
7669+
**11. `spread()` array-form walk, classify once** (2026-09-28, branch
7670+
`perf/spread-walk`, worktree `~/Development/solid-spread-walk`, staged,
7671+
not merged). Non-function sources classified at spread creation; a list
7672+
with no function source skips the per-run resolve pass; universal
7673+
parity; +40 lines. Tier-1: array-form rerun −7%, create unchanged;
7674+
runtime-only floors 0.36 µs/element empty, 0.54 with three static keys,
7675+
0.67 object omit, 0.95 array `[omit, extras]`. **Browser lanes: within
7676+
±1% on every cell** (`browser-latest-sw{base,fixA}*.md`, alternated ×2).
7677+
A first-run one-pass walk (`sourceOwners`, no Map) for object-form views
7678+
gave −2 to −4% hydrate on the view-heavy lane and was not kept: it made
7679+
the first run enumerable-only and reruns all-own-keys (see open target
7680+
4). Verdict: **the walk is not the lever.**
7681+
7682+
**12. Client materialization of plain-only views** (2026-09-28, patch
7683+
`/tmp/sw-materialize-prototype.patch`, not merged). `merge`/`omit` with
7684+
every source a plain object → a flat object on the client: data
7685+
properties by value (static by the `isStatic` contract), accessors
7686+
re-homed with `bind`, merged key order, server untouched. Sound — the
7687+
whole web client, hydrate, universal and solid suites pass with it on;
7688+
a props object is a read-only derivation, so a view and a copy answer
7689+
every legitimate question identically. Browser lanes vs the item-11
7690+
build, alternated ×2:
7691+
7692+
| case | lane | hydrate | mount |
7693+
| ------------------- | ----- | ------------------ | ------------------ |
7694+
| `polymorphic-chain` | mprim | 45.6 → 52.3 (+14%) | 37.7 → 42.1 (+12%) |
7695+
| `polymorphic-chain` | #659 | 45.5 → 52.0 (+14%) | 37.6 → 42.3 (+12%) |
7696+
| `tabs` | mprim | 55.0 → 56.6 (+3%) | 43.9 → 47.0 (+7%) |
7697+
| `tabs` | #659 | 53.0 → 55.3 (+4%) | 42.4 → 44.1 (+4%) |
7698+
| `btn-variant` | mprim | 31.6 → 30.0 (−5%) | 25.7 → 24.0 (−7%) |
7699+
| `btn-variant` | #659 | 27.4 → 27.3 | 21.5 → 21.3 |
7700+
7701+
Omit-only variant (`merge` stays a view): neutral to +2% everywhere, and
7702+
the single-layer win vanishes — it exists only when the whole path to
7703+
the spread is plain. A copy is O(keys) per layer (a descriptor read per
7704+
key, a bound getter and a `defineProperty` per accessor) against a view's
7705+
O(1); the chain is ~6 layers × ~13 keys per row. Verdict: **the
7706+
representation is not the lever either; `#3448` holds on the client.**
7707+
7708+
**13. Where the `polymorphic-chain` client mount goes** (mprim, rc.10,
7709+
11.6 ms in-window of 26.6 profiled, 400 rows, unthrottled): views 2.14
7710+
ms (18.5%; of which the bottom spread's resolved-table build is 0.83 —
7711+
`collectTable` through three omit filters over ~24 leaf keys), graph
7712+
construction 1.65 (`recompute` 0.45, `setupComputedNode` 0.39, `read`
7713+
0.23, `createMemo` 0.18), GC 1.29, spread/attributes 1.24, web other
7714+
1.19, case components 0.89, core other 0.69, DOM natives 0.69,
7715+
effects/scheduler 0.57. No function above 4%. Per row: ~7 µs of graph
7716+
work for ~7–8 computation nodes (spread effect, `dynamic()` memo, `Show`
7717+
memo + render effect, children insert, text insert, icon insert). React
7718+
pays no nodes; its per-row cost is fibers and object spreads.
7719+
7720+
### Standing rulings and lessons
7721+
7722+
- **Server: always views.** One walk into `ssrElement`, no copies, no
7723+
table on first read. **Client: a small fixed-key plain set consumed by
7724+
one `spread` is cheaper copied** (+1.4 µs/element the other way); views
7725+
pay off once props are proxied or chained, and materializing plain-only
7726+
views at construction loses 12–14% on a chain. The platform cannot pick
7727+
per layer because a layer cannot know its depth at construction.
7728+
- **The props-plumbing walk and representation are not the client lever**
7729+
(items 11–13). The residue vs React is per-row node count and per-node
7730+
cost in the reactive core, spread thin: no function above 4%.
7731+
- **Cold tier.** A page load runs the runtime in the interpreter and
7732+
baseline tiers; the same code measures ~4× cheaper per call in an
7733+
optimized tier-1 bench. Tier-1 gives direction; the browser lanes are
7734+
the acceptance, alternated (A B A B), with medians and the React lane
7735+
in the same run.
7736+
- **Perf vs size.** Fast paths (a specialized walk, a cached shape, a
7737+
shortcut for a static case) are the class that balloons; each earned its
7738+
number here and together they are the growth. Fewer nodes per row via
7739+
the compiler (a proven-static child needs no effect) and removals are
7740+
size-neutral or negative. A perf change carries its gzip delta and is
7741+
in only if the lane gain clears the maintainer's bar.
7742+
- **Read the fixture, again.** The `btn-variant` client gap was `omit()` +
7743+
array-form spread in yak's runtime, not the template; #659's "tag cases
7744+
noise" was SSR-only. The harness measures the fixture first.
7745+
- **`merge()`'s function-source memo takes a hydration id.** A client path
7746+
for an element the server writes by hand must use `spread()`'s array
7747+
form (inline function source, no owner) — documented, and an easy trap
7748+
for anyone porting a hand-written SSR path.
7749+
- **CodSpeed.** A regression counts when the flagged frames are ours and
7750+
scale with the input; harness-frame self time constant across sizes is
7751+
attribution (#3497, #3562).
7752+
- Working with the yak repo: pnpm `minimumReleaseAge` blocks `pnpm run` —
7753+
call `node_modules/.bin/*` directly or set it to 0 temporarily and
7754+
restore before committing; push via a fork remote.
7755+
7756+
### Open targets, in order
7757+
7758+
1. **Client per-row node count on composition shapes.** The residue (item
7759+
13). Measure first: nodes per row by kind on `polymorphic-chain` and
7760+
`tabs`, and cold-tier cost per node kind (creation, first run, first
7761+
flush). Candidates, all size-neutral or negative: a child expression
7762+
the compiler can prove static emits a direct insert, no effect; a
7763+
spread and its children insert sharing one node; `Show` building two
7764+
memos where one suffices (Octane board open target 5 — same item);
7765+
what `createEffectNode` / `setupComputedNode` allocate and link on
7766+
creation. This is a core arc, not a yak-parity one.
7767+
2. **Hydrate trims, bundled, ≤ 1 ms/page (~5%)**: `isHydrating`'s
7768+
`isConnected` per attribute → once per element in `assign`;
7769+
`getNextElement`'s key string + Map get/delete + WeakSet add; the
7770+
per-node probes (`hydratedCreateMemo` → `readSerializedOrCompute`,
7771+
`sharedConfig.has` against an empty `_$HY.r`). Only if item 1 leaves
7772+
hydrate still ≥ 5% over mount.
7773+
3. **Server floors, kept deliberately** (SSR vs React on
7774+
`polymorphic-chain` ~0.47×; `tabs` / `multifile-composition` at
7775+
parity): the owner protocol per server memo (~22 ns/instance; it is
7776+
what gives the compute `getOwner()` / `onCleanup` and retry-stable
7777+
ids), the generic-proxy floor of a one-key `merge` (~12 ns),
7778+
`ssrElement` vs a definition-time writer on the tiny `dyn-*` cases
7779+
(1.46×). Reopen only as their own items.
7780+
4. **Key-coverage inconsistency through a view.** `spread` over a
7781+
merge/omit view walks the resolved table, built with `Reflect.ownKeys`
7782+
(all own keys), while `assign` over a plain object, `spread` over a
7783+
plain source and the server's `sourceOwners` use enumerable string
7784+
keys — a non-enumerable own property on a leaf reaches the element
7785+
only through a view, and only on the client. Tiny, but it blocked the
7786+
item-11 one-pass and it is a server/client divergence. Fix: filter by
7787+
enumerability in the web/universal table walk, or build the table from
7788+
`leafKeys`.
7789+
5. **Docs**: the server-views / client-copy guidance for libraries in the
7790+
`merge` / `omit` JSDoc and the hydration-id note on `merge()`'s
7791+
function source.
7792+
6. **`perf/spread-walk` (item 11)**: ±0 in the browser, −7% on one tier-1
7793+
rerun micro, +40 lines. Drop under the size rule unless wanted; keep
7794+
the bench file either way.
7795+
7. Yak side: watch DigitecGalaxus/next-yak#658 / #659; the component-
7796+
target `merge()` view on the client is ~5% behind a copy on their
7797+
composition cases for a 1.5× SSR win — their trade.

0 commit comments

Comments
 (0)