Repository navigation
perf: Record macOS frame cadence for an idle overlay - #1478
Merged
Merged
Conversation
summarizeTimestamps turns frame times into a histogram, a drop count, and an average fps. The test places the over-threshold gap from DROP_MS.
Release process_log::init keeps stderr off the terminal, so the bench was stopping the app before a landed frame showed up. It now waits on process.log and copies the trace out before deleting the scratch home.
One perched minute on this Mac. The overlay does not stay at 60 fps while the sprite is still, and a still sprite has no interpolation lag to measure.
omesser
commented
Oct 10, 2026
omesser
left a comment
Owner
Author
There was a problem hiding this comment.
Soft CLEARED
Tip: 62bfafd6
What changed
- Frame summary:
summarizeTimestampsturns timestamps into a histogram, a drop count and an average fps.DROP_MSis the one 20 ms threshold and the tests read it. - Release log:
unwrapProcessLogstrips the epoch prefix, and the bench harvestsprocess.loginto the run log before the scratch home is deleted. It waits on that file too, so a release run no longer kills the app before the trace lands. - Research note: one idle minute on a Mac, with a 1.6 fps callback rate explained by the loop stopping on a perched sprite.
What is wrong
Nothing blocking.
Soft-FIX
None.
Non-blocking
- Bash glue:
harvest_process_logandlog_hashave no test. They are macOS bench plumbing, and the research note is their live evidence.
Verified: node --test tests/frame-cadence.test.js passes 10 of 10, bash -n and shellcheck are clean, and the note's histogram counts add up to its 94 gaps and 93 drops. I did not rerun the Mac sample.
— Cursor agent (Architect), on @omesser's behalf.
This was referenced Oct 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
An idle overlay was supposed to show whether animation frames hold 60 fps and whether interpolation sits one Engine tick behind. This machine had no such sample. A release binary also never fed the bench, because
process_log::initkeeps stderr inprocess.log.What changed
summarizeTimestampsturns frame timestamps into a histogram, a drop count, and an average fps.DROP_MSis the only 20 ms threshold, and the tests read that constant. The bench waits onprocess.logand copies it out before deleting the scratch home.The idle minute is
docs/research/macos-idle-frame-cadence.md. Consecutive callbacks averaged 1.6 fps, with 93 gaps over 20 ms, because a perched sprite does not ask for the next frame. One armed gap was over 20 ms. Still Engine ticks averaged 21.6 ms (46.4 Hz). Interpolation lag is empty, because the sprite never moved.Walking, CPU load, riding a window, and a seam crossing were not run. Linux and Windows were not measured.
How to verify
node --test tests/frame-cadence.test.jscovers the timestamp summary and the process-log prefix.cargo test --workspace --all-targetspassed (0 failed).node --test tests/*.test.jspassed (603 tests, 0 failed).The GUI sample is the research note. Rerun it with
FIDGET_BENCH_GREEN_LIGHT=1 scripts/bench-frame-cadence-macos.sh idle --seconds 60 --bin target/release/fidget.Notes
This does not close #426. Riding and a seam crossing need a drag. A still sprite cannot confirm the one-tick lag claim.
— Grok Build, on @omesser's behalf.