Skip to content

perf: Benchmark frame cadence and dropped frames (all platforms) #426

Open

Description

@cursor

Out of V1: needs a bare-metal Linux machine with a GPU or multiple monitors, which isn't available. Don't pick this up or re-test it until one is.

Objective

Measure frame-to-frame timing (rAF callback deltas) and detect dropped frames (>16.67ms gaps). Validate interpolation smoothness claim from src/interpolate.js.

Tools

  • Browser DevTools (Performance tab, record rAF timestamps)
  • Custom logging: Add console.log(performance.now()) to draw() in src/main.js:250
  • Analyze: Plot histogram of frame deltas, count drops
  • Optional: High-speed camera recording (240fps) to visually validate smoothness

Scenarios

  1. Idle perched: Sprite still
  2. Walking: Sprite walking
  3. Riding moving window: Drag window with sprite on it
  4. CPU load: Compile large project in background while buddy runs
  5. Multi-monitor: Sprite crossing seam between displays

Metrics to Capture

  • Frame cadence: Histogram of rAF callback deltas (ms)
  • Dropped frames: Count of deltas >20ms (missed vsync)
  • Interpolation lag: Measure actual lag between Engine tick and webview render (compare timestamps)
  • Frame rate (fps): Average from rAF timestamps

Expected Results

  • Hypothesis (from interpolate.js): Engine ticks at ~44Hz (16-38ms deltas), webview renders at 60Hz, interpolation smooths motion
  • Idle/walking: Should see consistent 16.67ms rAF deltas (60fps)
  • CPU load: May see occasional drops (but interpolation should hide small gaps)
  • Multi-monitor: No drops expected (each overlay is independent)

Acceptance Criteria

  • Histogram of frame deltas for each scenario (plot or table)
  • Count of dropped frames (>20ms gaps)
  • Confirm 60fps rAF rate (or report actual rate)
  • Validate interpolation lag is 1 sample (1 Engine tick behind)
  • Results documented, compare to design claim

Related


— Cursor agent, on @omesser's behalf.

Activity

  1. added this to the V1 milestone on Sep 6, 2026
  2. added
    p2Eventually: real, but nothing waits on it
    on Sep 9, 2026
  3. moved this from 👷 Todo to 🙋 Human Triage in Fidgeton Sep 17, 2026
  4. omesser commented on Sep 29, 2026

    @omesser
    Owner

    Progress — #1149 merged to main

    Merge: 5dfa46763be05269bf4db2e29aa5171106605b71.

    Shipped (macOS only)

    On main now:

    • Env-only FIDGET_TRACE_CADENCE (off by default)
    • Analyzer scripts/frame-cadence.mjs + fixture tests
    • Gated bench scripts/bench-frame-cadence-macos.sh (idle / walking / load / matrix)
    • Baseline tables in docs/research/performance-baseline-v1.md
    • interpolate.js comment corrected to the measured 53 Hz Engine rate (was 44 Hz)

    Acceptance progress against this issue:

    Criterion Status
    Histogram / table of frame deltas Done for macOS idle / idle-quiet / walking / CPU-load
    Dropped-frame count (>20 ms) Done for those scenarios
    Confirm 60 fps rAF (or report actual) Done — ~59.8–59.9 fps walking; idle redraw story documented
    Interpolation lag vs Engine tick Done for moving sprites (e.g. walking lag p50/p95 ~19/22 ms)
    Results documented vs design claim Done for the measured macOS set

    Still open on this issue

    • Scenarios riding a moving window and crossing a display seam (PR notes both need someone at the desktop)
    • Linux and Windows frame-cadence baselines (issue title is all platforms; only macOS landed)

    Findings already spun out (separate jobs, leave this open):

    • #1155 — skip redraw on unchanged 250 ms resend
    • #1156 — Engine ticks at 53 Hz vs 16 ms target

    Leaving #426 open until the remaining scenarios/platforms are measured (or explicitly deferred).

    — Cursor agent (Coder), on @omesser's behalf.

  5. omesser commented on Sep 30, 2026

    @omesser
    Owner

    Progress — #1166 / #1155 merged to main

    Merge: 3145d50f806976d9a865b202218308d886caa1c9. Issue #1155 closed as completed.

    Shipped

    Idle perched no longer pays a display frame for each 250 ms FRAME_RESEND of an unchanged placement. Overlay frame listener compares serialized placement to last told and skips arm() on a byte-identical resend; late listeners still get the first placement. Covered by tests/frame-resend.test.js and a still-stretch bench on tip 84ba6ba4 (12 animation-frame changes = 12 display frames, 0 re-arms).

    That closes the idle-resend finding called out after #1149. It does not finish this umbrella: Windows/Linux benches, riding a moving window, multi-monitor seam, and a deterministic idle scenario (StaticDirector can pick patrol, so whole-window totals are not comparable with #1149) remain open.

    Leaving #426 open.

    — Cursor agent (Coder), on @omesser's behalf.

  6. omesser commented on Oct 1, 2026

    @omesser
    Owner

    Progress — #1203 on main (leave open)

    Merge: d85fa2a12a501187f1d1da843bc86c0366601025.

    Newly on main

    • Linux release cadence tables from scripts/bench-frame-cadence-macos.sh (script now exports XAUTHORITY before replacing HOME) in docs/research/performance-baseline-v1.md.
    • macOS idle / walking / load tables were already on main from earlier PRs.

    Still open (acceptance)

    • Riding a moving window
    • Multi-monitor seam crossing
    • Windows benches (if still desired for this umbrella)

    Leaving open.

    — Cursor agent (Coder), on @omesser's behalf.

  7. omesser commented on Oct 2, 2026

    @omesser
    Owner

    Slice in #1263. The issue stays open.

    Measured. macOS cadence tables and the Linux release idle, walking, and load tables were already on main. This slice adds one Linux ride from the release binary at 543dad19 on the cloud VM (DISPLAY=:1, one 1920x1200 screen at 60 Hz). An xterm glided 2 px about every 20 ms for 20 s. The window held 392 hold# frames, all at y=806, x from 769 to 1177, 262 distinct positions. scripts/frame-cadence.mjs reported 546 display frames, 62.2 fps on armed stretches, 1 drop over 20 ms, engine counter 62.1 Hz, lag p50 17 ms (1 sample), lag p95 114 ms (1.07 samples).

    Harness, no Windows numbers. scripts/bench-frame-cadence-windows.ps1 runs idle, idle-quiet, walking, load, and matrix. It requires FIDGET_BENCH_GREEN_LIGHT=1 and OS=Windows_NT, and it prints the same analyzer report. No Windows machine ran it, so the baseline has no Windows histogram.

    Still open. Crossing a display seam is unmeasured. This VM has one screen. The acceptance checkboxes need that seam and a Windows operator capture before the issue can close.

    — Cursor agent, on @omesser's behalf.

  8. omesser commented on Oct 2, 2026

    @omesser
    Owner

    Progress — #1263 merged to main

    Merge: 241c033ac2ec0b2459a88a610985904f2823cdb4.

    Newly on main

    • scripts/bench-frame-cadence-windows.ps1 — gated Windows harness (idle / idle-quiet / walking / load / matrix), green-light + Windows_NT required, same scripts/frame-cadence.mjs report path as macOS/Linux.
    • Linux riding table in docs/research/performance-baseline-v1.md from release binary at 543dad19 (392 hold# frames, 546 display frames, 62.2 fps armed, 1 drop >20 ms, lag p50 17 ms / 1 sample).

    macOS idle/walking/load and Linux idle/walking/load tables were already on main from earlier PRs.

    Still open (acceptance)

    • Windows histograms — harness only; no Windows machine ran the script, so no Windows numbers in the baseline.
    • Multi-monitor seam — unmeasured (capture VM is one screen).

    Leaving #426 open. Parent #423 stays closed (umbrella already completed).

    — Cursor agent (Coder), on @omesser's behalf.

  9. omesser commented on Oct 3, 2026

    @omesser
    Owner

    Progress — #1311 Soft-gated (leave open)

    Windows open item from this issue: operator capture on DESKTOP-UQIE144 (MS-7D25), release fidget.exe at b0f57a78.

    Measured

    FIDGET_BENCH_GREEN_LIGHT=1 scripts\bench-frame-cadence-windows.ps1 matrix -Seconds 20 -Bin target\release\fidget.exe. Header: Windows 11 Pro for Workstations, refresh 59, 20 cpus, git_rev=b0f57a78.

    Scenario Display frames Mean fps (armed) Drops >20 ms Engine Hz Lag p50 / p95 (moving)
    Idle, still Character 20 N/A 0 61.2 N/A
    Idle-quiet 23 59.9 0 61.1 N/A
    Walking 1199 60 0 62.5 16 ms / 17.1 ms (1 sample)
    Walking + load 1199 60 0 62.5 16 ms / 16.4 ms (1 sample)

    Tables and histograms land in docs/research/performance-baseline-v1.md via #1311.

    Still open

    • Multi-monitor seam — still unmeasured.

    Leaving #426 open until the seam is measured or deferred.

    — Cursor agent (Coder), on @omesser's behalf.

  10. 9 remaining items

  11. moved this from In Progress to Done in Fidgeton Oct 4, 2026
  12. reopened this on Oct 4, 2026
  13. omesser commented on Oct 4, 2026

    @omesser
    Owner

    Progress — #1312 merged to main (reopened)

    Merge: 2c3b54b8d1542b132b52510184a72296c985d7b9.

    GitHub auto-closed this via the PR’s Development closing link when #1312 merged. The PR body said it does not close #426 (docs Soft-FIX only). Reopening.

    Newly on main

    Wording Soft-FIX in docs/research/performance-baseline-v1.md (tip 4cf03cfc):

    • Windows tables credited as printout values placed in Linux columns
    • “Zero gaps over 20 ms” scoped to armed display; walking/load engine ticks named
    • macOS section points at the Windows dual-monitor seam ride; Linux seam still unmeasured
    • 1850 display frames clarified as pooled overlay count (two series)

    No new measurements.

    Still open (acceptance)

    • Linux display seam — still unmeasured
    • Acceptance checkboxes above still unchecked pending that (or an explicit defer)

    Leaving #426 open. Parent #423 stays closed.

    — Cursor agent (Coder), on @omesser's behalf.

  14. self-assigned this
    on Oct 10, 2026
  15. moved this from Todo to In Progress in Fidgeton Oct 10, 2026
  16. moved this from In Progress to Done in Fidgeton Oct 10, 2026
  17. omesser commented on Oct 10, 2026

    @omesser
    Owner

    Progress: #1478 merged to main (reopened)

    Merge: bd37844f77f3b2dd316de22bcb3d5fba593e58c8.

    GitHub auto-closed this when #1478 merged, because the PR body's sentence "This does not close #426" contains the closing phrase "close #426". The PR says it does not finish this issue, so I'm reopening it.

    Newly on main

    • summarizeTimestamps turns frame timestamps into a histogram, a drop count, and an average fps, with DROP_MS as the single 20 ms threshold (covered by tests/frame-cadence.test.js).
    • scripts/bench-frame-cadence-macos.sh now waits on process.log and copies the trace out before deleting the scratch home, so a release binary feeds the bench.
    • docs/research/macos-idle-frame-cadence.md: one idle perched minute on macOS. Consecutive callbacks averaged 1.6 fps with 93 gaps over 20 ms, because a perched sprite doesn't request 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.

    Still open (acceptance)

    Leaving #426 open. Parent #423 stays closed.

    — Cursor agent (Coder), on @omesser's behalf.

  18. removed their assignment
    on Oct 10, 2026
  19. removed this from the V1 milestone on Oct 23, 2026
  20. omesser commented on Oct 23, 2026

    @omesser
    Owner

    Moved off V1 at Oded's request: needs a bare-metal Linux machine with multiple monitors, which isn't available. Back to a milestone once one is.

    The macOS, Windows (including the dual-display seam ride) and single-display Linux rows are on main. The only item left is the Linux display seam, and the box VM has one output per display, so it can't be measured there.

    — Cursor agent (Architect), on @omesser's behalf.

  21. omesser commented on Oct 23, 2026

    @omesser
    Owner

    Post-merge check after #1798, which marked this issue out of V1. Acceptance items checked against docs/research/performance-baseline-v1.md on main (350dcece):

    • Histogram per scenario: not ticked. Linux idle, walking, load and the window ride, plus the Windows matrix and the Windows seam ride, have histograms (L157-L159, L175, L190-L192, L206). A Linux display seam isn't measured, which needs a Linux machine with two monitors.
    • Dropped frames over 20 ms: met. Every measured table has a drops column, e.g. L151-L154 and L204.
    • 60 fps rAF rate: met. Confirmed on macOS (L683), with actual rates reported for Linux and Windows.
    • Interpolation lag is 1 sample: met (L684). Lag p50 is one sample in every moving table.
    • Results documented, compared to the design claim: met (L685), and the src/interpolate.js comment was updated.

    Ticked those four. Left open with no milestone: the Linux seam is the only thing left, and it waits for multi-monitor Linux hardware.

    — Cursor agent (P. Coder), on @omesser's behalf.

  22. moved this from Todo to Ice Box in Fidgeton Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    p2Eventually: real, but nothing waits on itperformanceCPU/GPU/memory/idle cost and benchmarkingready-for-agentFully specified, ready for an AFK agent

    Projects

    • Status
      Ice Box

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions