perf(harness): add 2D-highway frame-time measurement + capture the R3c gate (H0)

[byrongamatos]

The frame-time gate for the highway.js split (R3c). The harness measured server latency + boot + heap but never frame time, and the R0 numbers were against an empty library — so there was nothing to gate the renderer split against. This adds it.

What

scripts/perf-baseline.mjs --song "<filename in DLC_DIR>" measures the 2D highway's per-frame draw cost:

• wraps requestAnimationFrame before any page script runs,
• tags the frames the highway actually painted (via highway.addDrawHook),
• starts playback (confirms the clock advances so it isn't measuring the paused-throttle path),
• reports draw-frame p50/p95/p99 over --frames s across --runs runs.

Tagging is load-bearing: roughly half the rAF callbacks belong to other cheap ~0.1 ms loops, and averaging them in would mask a renderer regression behind no-op frames.

Baseline captured (the gate)

On the Arcturus feedpak (docs/perf-baseline.md):

run	draw frames	p50	p95	p99
1	53/106	2.2	3.2	3.6
2	50/100	2.2	2.9	3.2
3	53/106	2.1	2.7	3.5

p50 ≈ 2.2 ms · p95 spread 2.7–3.2 ms. The upcoming H-container lift turns each closure-slot read into an H.<slot> property load; this is the number that proves it doesn't cost the hot loop.

Maintainer/CI-only tooling; the existing no---song run is unchanged. npm run lint clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added a new performance baseline section covering 2D highway draw-cost measurements, including the command to run, results from multiple trials, and guidance on interpreting p50/p95/p99 timings.

• Tests

  • Enhanced the performance harness with a --song mode that reports per-frame draw-cost percentiles (p50/p95/p99), maximum timing, and p95 spread.
  • Added support for configurable frame and run counts, and improved messaging when the seeded input isn’t provided.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6207aab7-4b3c-4595-9640-fd60dacedeb3

📥 Commits

Reviewing files that changed from the base of the PR and between 3b862ba and 4b8ec44.

📒 Files selected for processing (3)

• CHANGELOG.md
• docs/perf-baseline.md
• scripts/perf-baseline.mjs

✅ Files skipped from review due to trivial changes (2)

• CHANGELOG.md
• docs/perf-baseline.md

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/perf-baseline.mjs

---

📝 Walkthrough

Walkthrough

The performance harness now supports optional song-based 2D highway draw-cost measurement with repeated-run percentile reporting. Baseline documentation and the changelog describe the capture procedure, results, and new mode.

Changes

2D highway draw-cost measurement

Layer / File(s)	Summary
Song-gated draw-cost harness scripts/perf-baseline.mjs	Adds song, frame-duration, and run-count options; measures highway-painted animation frames in Playwright; aggregates p50/p95/p99/max timings and p95 spread; and reports failures.
Baseline documentation and release note docs/perf-baseline.md, CHANGELOG.md	Documents the R3c metric, counting method, capture command, and three-run results, and records the new performance harness mode.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PerfBaseline as perf-baseline.mjs
  participant PlaywrightBrowser as Playwright browser
  participant Highway as 2D highway
  PerfBaseline->>PlaywrightBrowser: Launch song measurement with --song
  PlaywrightBrowser->>PlaywrightBrowser: Wrap requestAnimationFrame
  PlaywrightBrowser->>Highway: Play song and register highway.addDrawHook
  Highway-->>PlaywrightBrowser: Mark frames that drew
  PlaywrightBrowser-->>PerfBaseline: Return drew-frame timings
  PerfBaseline->>PerfBaseline: Aggregate percentile metrics across runs

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding 2D highway frame-time measurement and the gate baseline.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/r3-h0-frametime

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/perf-baseline.md`:
- Around line 49-52: Update the fenced code block near the performance baseline
command to specify the Bash language by changing the opening fence to ```bash,
while preserving the command contents.
- Around line 40-64: Add an [Unreleased] section to CHANGELOG.md documenting the
new performance baseline in docs/perf-baseline.md and the added --song mode in
scripts/perf-baseline.mjs, briefly noting their purpose and measured results.

In `@scripts/perf-baseline.mjs`:
- Around line 86-119: Ensure frameTimeOnce always closes the browser page by
wrapping its setup, measurement, and return logic in a try/finally block, moving
page.close() into finally. Preserve the existing error propagation and
successful result from frameTimeOnce.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 788d9145-eb65-47b0-9292-afd071cfb911

📥 Commits

Reviewing files that changed from the base of the PR and between cbc6545 and 3b862ba.

📒 Files selected for processing (2)

• docs/perf-baseline.md
• scripts/perf-baseline.mjs