bench-records

name	bench-records
description	Archive benchmark runs into benchmark/grapheme/_records and regenerate the HTML report. Use when adding or refreshing a perf record for Node.js, Bun, Chrome, Firefox, or Safari, or when asked to update the benchmark report.

Benchmark records

benchmark/grapheme/_records/ archives verbatim mitata outputs; report.mjs parses them into report.generated.html (committed alongside the records).

File naming

YYYYMMDD-{cpu}-{os}-{runtime}_{version}.txt, all lowercase snake_case, e.g. 20260707-apple_m4_pro-macos_26.5-nodejs_26.4.0.txt. One file per (date, platform, runtime); a same-day re-run replaces the file.

Capturing

A record must be the verbatim, complete mitata output: the clk:/cpu:/runtime: header, every benchmark group, and every summary block. Never trim, reformat, or reconstruct — the report parser and humans both read it raw, and the case names contain invisible Unicode that is easy to corrupt.

• Node: yarn perf:grapheme, capture stdout (non-TTY output is already plain text).
• Bun: bun --bun run perf:grapheme (--bun is required, otherwise Bun shells out to Node).
• Chrome (automatable): start yarn perf:grapheme:browser in the background (vite dev server). With the chrome-devtools MCP: navigate to the served URL, click the "Execute benchmark" button, wait until the button is re-enabled (the worker posts done), then read the #output element's innerText via evaluate_script. The MCP can only write files inside the workspace — save to a repo-relative temp path first, then move into _records/.
• Safari / Firefox (manual): the user runs the same vite page themselves and pastes the output. Write the pasted text to the record file exactly as given; when editing an existing record, watch for accidentally duplicating a summary block (it happened once).

After writing a record

1. Sanity-parse it: expect 6 benchmark groups, and every competitor present in each summary block.
2. Regenerate the report: node benchmark/grapheme/_records/report.mjs — prints record/platform counts and rewrites report.generated.html.
3. Tell the user the per-competitor speedup ranges from the new record (e.g. "Intl.Segmenter 1.9–2.5x").
4. The user commits records themselves — never run git commit.

Measurement-quality flags

• Safari coarse-timer clamping: 0.00 ps minimums or 1.00 ms maximums mean the reduced-precision timer quantized the samples; affected rows (often the short ASCII case) can read ~2x off. Archive as provided, but flag it — a re-run with the tab focused usually fixes it.
• Browser runs are sensitive to background-tab throttling; ask for a focused, foreground run when numbers look inconsistent with the platform's other rows.
• README performance claims are qualitative ranges; a single noisy record rarely requires editing README.md.