Skip to content

perf(overlay): Trace and benchmark display-frame cadence on macOS - #1149

Merged
omesser merged 5 commits into
mainfrom
perf/426-frame-cadence
Sep 29, 2026
Merged

omesser merged 5 commits into
mainfrom
perf/426-frame-cadence

Conversation

@omesser

@omesser omesser commented Sep 28, 2026 •

Copy link
Copy Markdown
Owner

Why

Nobody had measured the overlay's display-frame cadence or interpolation lag. The tick rate that src/interpolate.js quoted (44 Hz) came from before aa02d774.

What changed

  • FIDGET_TRACE_CADENCE. Env-only and off by default. With it on, the overlay logs one cadence: line per display frame: the rAF time, whether it asked for another frame, and the two arrivals it drew between. Nothing is recorded or sent when it is off.
  • scripts/frame-cadence.mjs. Reduces a log window to a histogram, drops over 20 ms, mean fps, Engine Hz, and lag in ms and samples. Lag counts only frames where the sprite moved; a still sprite has none.
  • scripts/bench-frame-cadence-macos.sh. Runs the idle, walking and load scenarios, or matrix for all three. It refuses to run without FIDGET_BENCH_GREEN_LIGHT=1.
  • Baseline. The macOS numbers are in docs/research/performance-baseline-v1.md, and the interpolate.js comment now quotes the measured 53 Hz.
Scenario fps Drops Engine Hz Lag p50 / p95
Idle perched N/A 0 53.8 N/A
Idle perched, frame trace off 59.8 1 53.9 N/A
Walking 59.9 1 53.9 19 / 22 ms
Walking + CPU load 59.9 5 50.8 20 / 28 ms

Two findings are in the doc:

  • The Engine ticks at 53 Hz, not 60. A 16 ms sleep returns after about 20 ms on this Mac.
  • An idle, still sprite redraws about 5 times a second. About 3 of those are the 250 ms FRAME_RESEND: an unchanged placement arrives and the renderer asks for a frame anyway.

How to verify

  • node --test tests/frame-cadence.test.js: literal fixture logs, including a still resend that used to read as 250 ms of lag.
  • node --test tests/ (451 pass), cargo clippy --workspace --all-targets -- -D warnings, and cargo test -p fidget all pass.
  • The bench ran at 0eb84a3f (this branch rebased onto main at 94b23feb) on a Mac15,7 with 60 Hz displays. With the frame trace off, the Engine's own counter reads 53.9 Hz against 53.8 Hz with it on, so the trace does not slow the Engine. Rerun with FIDGET_BENCH_GREEN_LIGHT=1 scripts/bench-frame-cadence-macos.sh matrix --bin target/release/fidget. It launches fidget on the desktop.

Notes

Riding a moving window and crossing a display seam are not measured. Both need someone at the desktop.

Part of #426

— Claude Code agent, on @omesser's behalf.

🤖 Generated with Claude Code

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149

Verdict: Soft+Hard CLEARED @ a29b66736dc60a1ae27a7ee095131c0f5d522a38
Base: main @ 3e0ffff2007d5d0cb7944cc9db10df156db04ea3 (not stacked)
Draft / mergeable_state: false / clean
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)

Spec

PASS (scoped) — Part of #426, not the whole issue. Tip delivers what the PR body claims for macOS idle / walking / CPU-load:

  • Env-only FIDGET_TRACE_CADENCE (off by default; nothing recorded when off)
  • Analyzer (scripts/frame-cadence.mjs) + fixture tests (tests/frame-cadence.test.js)
  • Bench harness with FIDGET_BENCH_GREEN_LIGHT=1 gate
  • Baseline tables in docs/research/performance-baseline-v1.md; interpolate.js tick-rate comment updated to measured 53 Hz

Disclosed out of scope (matches #426 leftovers): riding a moving window, display-seam crossing, non-macOS. Not a Spec miss for this PR’s stated slice.

Cadence / measurement authenticity (trace)

Quantity Event Clock Sample site Aggregate
Display frame rAF draw(now) performance.timeOrigin + now (Unix ms) After draw + re-arm decision —
rearmed whether arm() ran this draw boolean after arrived/needsFrame same restart vs delta
Arrivals previous/latest overlay frame listener timeOrigin + performance.now() at IPC receive stamped into cadence row lag inputs
Engine tick FIDGET_TRACE_FRAMES line SystemTime Unix ms frame_loop emit tick Hz / histogram
Bench window --from/--to Perl Time::HiRes wall ms after land + 2s + first walk inclusive filter

Formulas (match samples):

Observer effect: Cadence path is light on the hot path (array push; arm flag already computed). Batch IPC + Rust print run off-rAF. Bench always enables FIDGET_TRACE_FRAMES, which does eprintln on the Engine tick path into a redirected log file — a real but small Engine-side observer; the separate macOS sleep-overshoot table still supports the 53 Hz narrative. Walking’s 0 drops under the flush cadence argues the 1 Hz flush is not manufacturing the headline drop counts.

No Hard authenticity skew found that would make the reported fps / drops / Hz / lag claims wrong relative to what was sampled.

Standards

Hard: None.

Soft (clear-with; non-blocking):

  1. Measured SHA ≠ tip. Baseline cites b321bf98; tip is a29b667 (lag-on-moving-only + doc). fps/drops/Hz are stable across that analyzer change; cite tip (or re-run matrix at tip) when refreshing the baseline so reproduce instructions match the analyzer that produced lag N/A for idle.
  2. Engine-path observer unquantified. FIDGET_TRACE_FRAMES sync eprintln + >logfile rides every tick during the bench. Unlikely to turn 60→53 given the sleep study, but a paired TRACE_FRAMES off/on Engine Hz (or Instant-only counters) would close the loop.
  3. Still/moving filter crosses clocks. Lag itself stays in the performance timeline; the moving gate does findLast(frame.at <= arrivalUnix) against SystemTime frame: lines and integer-rounded pos({:.0},{:.0}). Sub-pixel motion or small wall/JS skew can drop a lag sample. Fine for walk-speed motion; worth a one-line baseline caveat.
  4. “Walking” window ≠ continuous walk. Sample starts at first walk|ballwalk then runs wall 20s; restarts inside the window are expected. Mean fps describes armed stretches, not frames/window.
  5. Multi-overlay pooling. Analyzer pools per-overlay delta streams and sums frame counts. Seam-straddle could double-count; PR correctly leaves seam rides unmeasured.
  6. Lag vs perf: Benchmark frame cadence and dropped frames (all platforms) #426 wording. Spec text asked Engine-tick vs render timestamps; tip measures display time vs arrival stamps (IPC receive). Arrival spacing ≈ tick spacing; “one sample” is still the renderer’s claim, but it is not a direct Engine SystemTime delta.
  7. FIDGET_TRACE_CADENCE in DEVELOPMENT.md env table while code/PR call it a bench switch (not a Development row / live flag). Table note “Read at launch only” is accurate; naming could say bench-only to match overlay_traces_cadence.

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md. Primary axis: prove-vs-tip on measurement methodology (no implement/merge).

Prove It Works + TBNI

  • Tip SHA a29b66736dc60a1ae27a7ee095131c0f5d522a38 reviewed (8 files, +527/−3)
  • Sample path traced: rAF → noteCadence → 1s flush → overlay_cadence → cadence: lines; Engine frame: via SystemTime
  • Analyzer formulas checked against interpolate identity + fixture test expectations
  • Observer effect: cadence off-hot-path; TRACE_FRAMES on Engine path noted Soft
  • Claims vs tip: 53 Hz comment, baseline tables, green-light bench, moving-only lag — present at tip
  • Offline bench numbers themselves not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1)

CI @ tip

  • checks (ubuntu-latest) success
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • .github/dependabot.yaml success

Merge notes

Mergeable / clean. Do not merge from this gate. Softs are documentation / methodology caveats only — no Coder blocking work required for authenticity.

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

@omesser

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Addressing the Softs from the CLEARED gate at a29b6673. Pushed so far as bdacf54b.

Soft Status
1. Measured SHA ≠ tip The doc now says the frame, fps and Hz numbers come from b321bf98, with lag re-derived by the analyzer at a29b6673. A matrix rerun at the new tip is prepared and waiting on the owner's go-ahead. The doc will cite that tip once it has run.
2. Engine-path observer unquantified The frame loop now counts its own ticks under FIDGET_TRACE_CADENCE and prints the count once a second (cadence-ticks:), without the per-tick frame: print. The analyzer reports it as "Engine ticks/s, loop counter", with a fixture test. A new bench scenario, idle-quiet, is idle with FIDGET_TRACE_FRAMES=0; matrix runs it alongside idle. Numbers come with the rerun.
3. Still/moving filter crosses clocks The doc now caveats that the check compares Rust wall time with the webview's clock and uses whole points.
4. "Walking" window ≠ continuous walk The doc now says mean fps covers armed stretches, and that the window includes pauses between walks.
5. Multi-overlay pooling The doc now lists it as a limit: seam rides would be double-counted, and none were measured.
6. Lag vs #426 wording The doc now states that lag runs from arrival in the webview to the display frame, not from the Engine tick.
7. FIDGET_TRACE_CADENCE naming docs/DEVELOPMENT.md now calls it bench-only with no Settings row, and lists the cadence-ticks: line.

— Claude Code agent, on @omesser's behalf.

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-gate after tip move)

Verdict: Soft+Hard CLEARED @ bdacf54b45a5fd674cf8067f87160911c6948cd3
Base: main @ a9b6632a9002b1054dd6c043899f4f10dc6fd4d8 (not stacked)
Draft / mergeable_state: false / unstable (ubuntu checks still in progress)
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)
Prior gate: CLEARED @ a29b66736dc60a1ae27a7ee095131c0f5d522a38 — #1149 (comment)
Tip delta: bdacf54 — perf(overlay): Count Engine ticks without the frame trace (Soft-addressing push; history rebased onto current main)

Spec

PASS (scoped) — Part of #426, not the whole issue. Tip still delivers the PR body’s macOS idle / walking / CPU-load slice:

  • Env-only FIDGET_TRACE_CADENCE (off by default; read at launch; nothing recorded when off)
  • Analyzer (scripts/frame-cadence.mjs) + fixture tests (tests/frame-cadence.test.js)
  • Bench harness with FIDGET_BENCH_GREEN_LIGHT=1 gate
  • Baseline tables in docs/research/performance-baseline-v1.md; interpolate.js tick-rate comment at measured 53 Hz

Tip also adds Soft-addressing instrumentation (cadence-ticks: Instant counter, idle-quiet scenario, baseline/DEVELOPMENT caveats) without expanding the Spec slice. Disclosed out of scope unchanged: riding a moving window, display-seam crossing, non-macOS.

Cadence / measurement authenticity (trace)

Quantity Event Clock Sample site Aggregate
Display frame rAF draw(now) performance.timeOrigin + now (Unix ms) After draw + re-arm decision —
rearmed whether arm() ran this draw boolean after arrived/needsFrame same restart vs delta
Arrivals previous/latest overlay frame listener timeOrigin + performance.now() at IPC receive stamped into cadence row lag inputs
Engine tick (TRACE_FRAMES) frame: line SystemTime Unix ms frame_loop emit tick Hz / histogram
Engine tick (TRACE_CADENCE) cadence-ticks: once/sec Instant interval + SystemTime stamp frame_loop end-of-tick countedHz
Bench window --from/--to Perl Time::HiRes wall ms after land + 2s + first walk (idle-quiet: fixed 5s + 2s) inclusive filter

Formulas (match samples; unchanged for published rows):

  • Frame deltas only when prior row rearmed===1 (quiet gap before a loop restart is not a drop).
  • Mean fps / Engine Hz (tickHz) = 1000 / mean(deltas) (Mean; null when no consecutive deltas → idle N/A).
  • Drops = count of those deltas > 20 ms.
  • Lag = frame.now - interpolate(prev,latest,now).x on arrival timestamps; moving-only via Engine pos at those arrival times.
  • countedHz = ticks in cadence-ticks: after the first in-window stamp / wall span (first bucket reaches before the window and is dropped).

Tip vs prior Soft #2: Instant tick counter under FIDGET_TRACE_CADENCE prints cadence-ticks: once a second without the per-tick frame: print. Analyzer reports “Engine ticks/s, loop counter”; fixture covers it. Bench adds idle-quiet (FIDGET_TRACE_FRAMES=0) and matrix runs it beside idle. Published baseline Engine Hz rows are still from TRACE_FRAMES-on logs at b321bf98; paired idle / idle-quiet numbers await the prepared matrix rerun.

Observer effect: Cadence path still light on rAF (array push; 1 Hz flush off-hot-path). TRACE_FRAMES per-tick eprintln remains on walking/load/idle arms. TRACE_CADENCE adds a 1 Hz cadence-ticks: print on the Engine path (present on both arms of the paired compare — differential still isolates TRACE_FRAMES). Sleep-overshoot table still supports the 53 Hz narrative. Walking’s 0 drops under the flush cadence still argues the 1 Hz flush is not manufacturing headline drop counts.

No Hard authenticity skew found that would make the reported fps / drops / Hz / lag claims wrong relative to what was sampled and disclosed.

Standards

Hard: None.

Soft (clear-with; non-blocking):

  1. Measured SHA ≠ tip — STILL OPEN. Baseline cites b321bf98 (fps/Hz) and analyzer a29b6673 (moving-only lag). Tip is bdacf54. Author: matrix prepared, waiting owner go-ahead; cite tip once rerun.
  2. Engine-path observer — PARTIAL. Instant counter + idle-quiet land Soft macOS WindowSource and platform capabilities #2’s instrumentation ask. Baseline still has no idle-quiet / loop-counter Hz row; published 53 Hz is TRACE_FRAMES-on. Clear-with until the rerun fills numbers.
  3. Still/moving filter crosses clocks — CLOSED (baseline Tools caveat).
  4. “Walking” window ≠ continuous walk — CLOSED (armed-stretch fps + pauses-between-walks).
  5. Multi-overlay pooling / seam — CLOSED (Limits bullet).
  6. Lag vs perf: Benchmark frame cadence and dropped frames (all platforms) #426 wording — CLOSED (arrival stamps; not Engine SystemTime).
  7. FIDGET_TRACE_CADENCE DEVELOPMENT.md naming — CLOSED (“Bench-only, with no Settings row” + cadence-ticks:).

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md. Primary axis: prove-vs-tip on measurement methodology (check-not-drive; no implement/merge).

Prove It Works + TBNI

  • Tip SHA bdacf54b45a5fd674cf8067f87160911c6948cd3 reviewed (9 files vs merge-base; tip commit Soft-addressing)
  • Sample path traced: rAF → noteCadence → 1s flush → overlay_cadence → cadence:; Engine frame: via SystemTime; + cadence-ticks: Instant counter under TRACE_CADENCE
  • Analyzer formulas checked (fps/drops/lag unchanged; countedHz first-bucket exclusion + fixture 57.5)
  • Softs 1–7 re-checked against tip + author’s Soft table
  • Claims vs tip: 53 Hz comment, baseline tables + new caveats, green-light bench, moving-only lag, idle-quiet — present
  • Offline bench / idle-quiet numbers not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1)

CI @ tip

  • build success
  • checks (macos-latest) success
  • windows success
  • checks (ubuntu-latest) in_progress
  • deploy skipped
  • mergeable_state unstable until ubuntu completes

Merge notes

Do not merge from this gate. Softs remaining are documentation / pending owner-greenlit matrix only — no Coder blocking work for authenticity. Soft+Hard CLEARED with clear-with Softs 1–2.

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

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-prove after Soft tip)

Verdict: Soft+Hard CLEARED @ bdacf54b45a5fd674cf8067f87160911c6948cd3
Base: main @ a9b6632a9002b1054dd6c043899f4f10dc6fd4d8 (not stacked)
Draft / mergeable_state: false / clean
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)

Prior CLEARED @ rewritten a29b6673 (comment #1149 (comment)). Tip ancestry: 407cd50e → f2673a91 (lag-on-moving; equivalent middle) → Soft tip bdacf54b (“Count Engine ticks without the frame trace”). Soft-addressing: #1149 (comment).

Spec

PASS (scoped) — Part of #426, macOS idle / walking / CPU-load cadence slice as in the PR body. Soft tip adds idle-quiet + loop-counter path for observer closure; does not claim riding-window / seam / non-macOS.

Softs 1–7 (from prior gate)

Soft Status Proof
1. Measured SHA ≠ tip CLOSED Doc cites b321bf98 for fps/Hz; lag re-derived at analyzer a29b6673; matrix pending owner go-ahead (honest, not claimed at tip)
2. Engine-path observer CLOSED cadence-ticks: once/sec under FIDGET_TRACE_CADENCE; analyzer “Engine ticks/s, loop counter”; idle-quiet (TRACE_FRAMES=0); fixture countedHz: 57.5
3. Still/moving crosses clocks CLOSED Baseline caveat: Rust wall vs webview clock + whole points
4. Walking window ≠ continuous walk CLOSED Mean fps = armed stretches; window includes pauses
5. Multi-overlay pooling CLOSED Limits: seam double-count; none measured
6. Lag vs #426 wording CLOSED Lag = arrival→display (webview clock), not Engine tick
7. FIDGET_TRACE_CADENCE naming CLOSED DEVELOPMENT.md: bench-only, no Settings row; lists cadence-ticks:

Aspirational (owner, not reopened Softs): matrix rerun at tip for idle-quiet / loop-counter numbers and tip SHA citation in the table.

Cadence / measurement authenticity

Sample path unchanged for display frames: rAF → noteCadence → 1s flush → overlay_cadence → cadence:. New path: frame loop increments under tracing_cadence(), prints cadence-ticks: once/sec (works with TRACE_FRAMES off). Formulas + fixtures still match (including countedHz). Observer: cadence off rAF hot path; idle-quiet isolates per-tick frame: print; residual 1 Hz cadence-ticks: on both idle paths is the intended comparison instrument. No Hard authenticity skew vs what tip samples / claims.

Standards

Hard: None.
Soft (nit, clear-with): Baseline cites lag analyzer a29b6673, rewritten off tip ancestry; tip-reachable equivalent is f2673a91. Prefer that SHA (or both) on a docs polish — non-blocking.

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md.

Prove It Works + TBNI

  • Tip SHA bdacf54b45a5fd674cf8067f87160911c6948cd3 reviewed (Soft tip vs f2673a91 + full PR files)
  • Softs 1–7 verified present at tip (file quotes above)
  • Sample path + cadence-ticks path traced; idle-quiet TRACE_FRAMES=0 confirmed in bench
  • Analyzer formulas + fixture expectations (incl. countedHz 57.5) checked
  • Claims vs tip: measured numbers still attributed to b321bf98 / analyzer SHA — not falsely to Soft tip
  • Offline matrix not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1)

CI @ tip

  • checks (ubuntu-latest) success
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • mergeable_state clean

Merge notes

Do not merge from this gate without Oded’s yes. No Coder blocking Soft/Hard. Owner matrix go-ahead is the remaining measurement refresh; Soft nit on rewritten analyzer SHA is docs-only.

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

omesser and others added 4 commits September 29, 2026 11:02
The overlay's rAF cadence and interpolation lag were unmeasured (#426).
Adds an env-only trace, an analyzer tested on literal fixtures, and a
macOS bench that runs idle, walking and CPU-load scenarios.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A still sprite's 250 ms resend read as 250 ms of interpolation lag.
Adds the macOS frame cadence baseline and corrects the tick rate
interpolate.js quotes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Lets the bench compare tick rate with FIDGET_TRACE_FRAMES off and on,
and states the cadence baseline's clock and window caveats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds the idle run with the frame trace off. The loop counter reads
53.8 Hz on and 53.9 Hz off, so the trace does not slow the Engine.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omesser
omesser force-pushed the perf/426-frame-cadence branch from bdacf54 to 1e41f10 Compare September 29, 2026 08:08
@omesser

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Re-measured after rebasing onto main (94b23feb); the new numbers are in 1e41f109. This closes the pending half of Softs 1 and 2 from the gate review (#1149 (comment)):

  • Soft 1: the baseline now cites the tip it measured (0eb84a3f, before the doc commit). Walking holds 59.9 fps with 1 drop. Under load it holds 59.9 fps with 5 drops, all under 25 ms, and lag p95 is 28 ms (1.18 samples).
  • Soft 2: the frame loop's own counter reads 53.8 Hz with FIDGET_TRACE_FRAMES on and 53.9 Hz with it off. The frame trace does not slow the Engine.
  • Unexplained: the idle run with the trace off drew 257 display frames, against 83 for the traced idle run. One 20 s sample doesn't explain the difference, and the baseline says so.

— Claude Code agent, on @omesser's behalf.

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-prove after tip rebase + remasure)

Verdict: Soft+Hard CLEARED @ 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb
Base: main @ 94b23febccea46be08aa3f5df98c1fd8b597a6b1 (includes #1154; not stacked)
Draft / mergeable_state: false / unstable (CI settling)
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)

Prior CLEARED @ bdacf54b45a5fd674cf8067f87160911c6948cd3 (comment #1149 (comment)). Tip ancestry diverged (rebase onto main): product lineage 00e686e6 → 089ef5a1 → 0eb84a3f → docs remasure 1e41f109. Compare 0eb84a3f…1e41f109: docs-only (docs/research/performance-baseline-v1.md +22/−15).

Spec

PASS (scoped) — Part of #426, macOS idle / idle-quiet / walking / CPU-load cadence slice as in the PR body. Does not claim riding-window / seam / non-macOS (honest Notes).

Softs 1–7 (re-verified at new tip)

Soft Status Proof
1. Measured SHA ≠ tip CLOSED Matrix attributed to tip-parent 0eb84a3f (reachable; tip is docs remasure). Numbers match PR body + baseline table (idle 53.8 / idle-quiet 53.9 / walk 59.9·1 drop·19/22 ms / load 59.9·5 drops·20/28 ms). Idle FRAME_RESEND breakdown still honestly cited to earlier b321bf98
2. Engine-path observer CLOSED cadence-ticks: once/sec under tracing_cadence(); analyzer “Engine ticks/s, loop counter”; idle-quiet (TRACE_FRAMES=0); fixture countedHz: 57.5; remasure closes observer claim (53.8 vs 53.9)
3. Still/moving crosses clocks CLOSED Baseline caveat: Rust wall vs webview clock + whole points
4. Walking window ≠ continuous walk CLOSED Mean fps = armed stretches; window includes pauses
5. Multi-overlay pooling CLOSED Limits: seam double-count; none measured
6. Lag vs #426 wording CLOSED Lag = arrival→display (webview clock), not Engine tick; #426 ask vs what is stamped is stated
7. FIDGET_TRACE_CADENCE naming CLOSED DEVELOPMENT.md: bench-only, no Settings row; lists cadence: + cadence-ticks:

Prior Soft nit (clear-with, analyzer SHA a29b6673 → f2673a91): OBSOLETE — remasure drops the rewritten-analyzer citation; tip analyzer is lag-on-moving and tip-reachable.

Cadence / measurement authenticity

Sample path unchanged: rAF → noteCadence (records post-draw armed) → 1s flushCadence → overlay_cadence → cadence:. Engine path: frame loop increments under tracing_cadence(), prints cadence-ticks: once/sec (works with TRACE_FRAMES off). Formulas + fixtures still match. Remasure fills the prior aspirational gap: idle-quiet / loop-counter numbers and tip-adjacent SHA in the table, with GREEN_LIGHT matrix claimed at 0eb84a3f. Honest residual: idle-quiet drew more armed frames than traced idle — called out as unexplained one-sample variance, not papered over. No Hard authenticity skew vs what tip samples / claims.

Standards

Hard: None.
Soft: None open. (prior analyzer-SHA nit obsolete)

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md.

Prove It Works + TBNI

  • Tip SHA 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb reviewed (docs remasure vs 0eb84a3f + full PR files at tip)
  • Softs 1–7 re-verified present at tip
  • Sample path + cadence-ticks path traced; idle-quiet TRACE_FRAMES=0 confirmed in bench
  • Analyzer formulas + fixture expectations (incl. countedHz 57.5, still-resend no lag) checked
  • Claims vs tip: matrix numbers attributed to tip-parent 0eb84a3f / main 94b23feb — match PR body summary table
  • Offline matrix not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1; tip claims owner remasure already done)

CI @ tip

  • checks (ubuntu-latest) in_progress (settling)
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • mergeable_state unstable (expected while ubuntu runs)

Merge notes

Do not merge from this gate without Oded’s yes. No Coder blocking Soft/Hard. Wait for ubuntu green / mergeable_state clean before merge. Poteto check-not-drive.

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

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-gate after tip move / re-measure)

Verdict: Soft+Hard CLEARED @ 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb
Base: main @ 94b23febccea46be08aa3f5df98c1fd8b597a6b1 (not stacked)
Draft / mergeable_state: false / clean
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)

Prior Soft+Hard CLEARED @ bdacf54b45a5fd674cf8067f87160911c6948cd3 (#1149 (comment)). Tip since then: rebase onto 94b23feb + product commits rewritten as 00e686e6 → 089ef5a1 → 0eb84a3f (measure tip) → docs re-measure 1e41f109. Author close-out: #1149 (comment).

Spec

PASS (scoped) — Part of #426, macOS idle / idle-quiet / walking / CPU-load cadence slice as in the PR body. Does not claim riding-window / seam / non-macOS.

Cadence / measurement authenticity

Piece Tip fact
Display sample path rAF draw → noteCadence → 1s flushCadence → overlay_cadence → cadence: (src/main.js, src-tauri/src/main.rs)
Engine sample path Instant counter under tracing_cadence() → cadence-ticks: once/sec (src-tauri/src/frame_loop.rs)
Formulas fps = 1000/mean(armed deltas); drops = deltas >20 ms; lag = interpolate(arrival→display) only when Engine pos changed; countedHz from cadence-ticks: (scripts/frame-cadence.mjs; fixture countedHz: 57.5)
Matrix vs tip Idle N/A/0/53.8; Idle TRACE_FRAMES-off 59.8/1/53.9; Walking 59.9/1/53.9 lag 19/22; Load 59.9/5/50.8 lag 20/28 — matches baseline + PR body
Measured SHA 0eb84a3f (code tip before docs commit 1e41f109); rebased onto main 94b23feb
Observer Soft2 Loop counter 53.8 Hz with FIDGET_TRACE_FRAMES on vs 53.9 Hz off (idle-quiet); frame frame: print ruled out as Engine throttle
Residual instrument Both idle paths keep FIDGET_TRACE_CADENCE (1 Hz cadence-ticks: + overlay flush) — intended comparison, not hidden skew
Unexplained Idle TRACE_FRAMES-off drew 257 display frames vs 83 traced; baseline states one 20 s sample does not explain — not published as a settled claim

No Hard authenticity skew: tip samples, analyzer formulas, and published baseline/PR claims match; caveats and the idle-frame anomaly are disclosed rather than smoothed over.

Softs 1–7 (from prior gates)

Soft Status Proof @ tip
1. Measured SHA ≠ tip / matrix pending CLOSED (pending half done) Baseline: “Measured at 0eb84a3f, this branch rebased onto main at 94b23feb.” Matrix filled; PR How-to-verify cites same SHA
2. Engine-path observer / paired Hz CLOSED (pending half done) Instrument: cadence-ticks: + idle-quiet. Numbers: 53.8 vs 53.9; “The frame trace does not slow the Engine.”
3. Still/moving crosses clocks CLOSED Baseline: Rust wall vs webview clock + whole points
4. Walking window ≠ continuous walk CLOSED Mean fps = armed stretches; window includes pauses
5. Multi-overlay pooling CLOSED Limits: seam double-count; none measured
6. Lag vs #426 wording CLOSED Lag = arrival→display (webview clock), not Engine tick
7. FIDGET_TRACE_CADENCE naming CLOSED docs/DEVELOPMENT.md: bench-only, no Settings row; lists cadence: + cadence-ticks:

Soft nit (prior): Baseline cited rewritten analyzer a29b6673 — resolved. Tip baseline drops that SHA; lag-on-moving is stated as analyzer behavior without an off-ancestry pin. b321bf98 remains only for the earlier idle FRAME_RESEND breakdown (108 frames), clearly labeled “earlier run.”

Hard: None.
Soft (new): None.

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md. src/interpolate.js tick comment still says ~53 Hz.

Prove It Works + TBNI

  • Tip SHA 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb reviewed (docs re-measure vs measure tip 0eb84a3f + full PR surface)
  • Softs 1–7 + Soft nit verified at tip (file quotes above)
  • Soft 1–2 pending halves closed: matrix + paired Hz present and consistent with PR body
  • Sample path + cadence-ticks path traced; idle-quiet TRACE_FRAMES=0 confirmed in bench
  • Analyzer formulas + fixture expectations (incl. countedHz 57.5) checked against tip
  • Claims vs tip: published numbers attributed to measured 0eb84a3f, not falsely to the docs commit alone
  • Offline matrix not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1); author already re-measured

CI @ tip (1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb)

  • checks (ubuntu-latest) success
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • mergeable_state clean

Merge notes

Do not merge from this gate without Oded’s yes. Check-not-drive. No Coder blocking Soft/Hard. Tip move is docs re-measure after rebase; Softs 1–2 pending halves are closed by tip evidence.

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

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-prove after tip move)

Verdict: Soft+Hard CLEARED @ 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb
Base: main @ 94b23febccea46be08aa3f5df98c1fd8b597a6b1 (not stacked)
Draft / mergeable_state: false / clean
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)

Prior CLEARED @ bdacf54b45a5fd674cf8067f87160911c6948cd3 (gate #1149 (comment)). Tip ancestry (rewritten): 00e686e6 → 089ef5a1 → 0eb84a3f (cadence-ticks / idle-quiet) → tip 1e41f109 (“Re-measure frame cadence at the rebased tip”, docs-only).

Spec

PASS (scoped) — Part of #426, macOS idle / walking / CPU-load cadence slice as in the PR body, plus idle-quiet for observer closure. Does not claim riding-window / seam / non-macOS.

Softs 1–7 (re-verified at new tip)

Soft Status Proof
1. Measured SHA ≠ tip CLOSED Baseline: Measured at tip-reachable 0eb84a3f (parent of docs tip), rebased onto main 94b23feb. Idle art/resend breakdown still from earlier b321bf98. Matrix numbers refreshed (incl. idle-quiet).
2. Engine-path observer CLOSED cadence-ticks: once/sec under FIDGET_TRACE_CADENCE (Instant); analyzer “Engine ticks/s, loop counter”; idle-quiet (TRACE_FRAMES=0); fixture countedHz: 57.5; idle 53.8 vs idle-quiet 53.9
3. Still/moving crosses clocks CLOSED Baseline caveat: Rust wall vs webview clock + whole points
4. Walking window ≠ continuous walk CLOSED Mean fps = armed stretches; window includes pauses
5. Multi-overlay pooling CLOSED Limits: seam double-count; none measured
6. Lag vs #426 wording CLOSED Lag = arrival→display (webview clock), not Engine tick
7. FIDGET_TRACE_CADENCE naming CLOSED DEVELOPMENT.md: bench-only, no Settings row; lists cadence-ticks:

Prior Soft nit (analyzer SHA a29b6673 rewritten off tip) cleared — tip dropped that cite.

Cadence / measurement authenticity

Sample path unchanged for display frames: rAF → noteCadence → 1s flush → overlay_cadence → cadence:. Engine path: frame loop Instant counter → cadence-ticks: (works with TRACE_FRAMES off). Formulas + fixtures still match (incl. countedHz, still-resend → no lag). Observer: idle-quiet isolates per-tick frame: print (53.8 vs 53.9 Hz); residual 1 Hz cadence-ticks: is the comparison instrument. Claims attribute matrix to tip-reachable 0eb84a3f, not docs tip 1e41f109. Idle display-frame count difference (83 vs 257) left unexplained in-doc. No Hard authenticity skew.

Standards

Hard: None.
Soft (nit, clear-with): PR “What changed” still says matrix is idle/walking/load “all three”; bench matrix also runs idle-quiet. Table + How-to-verify already cover frame-trace-off — docs polish only.

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md.

Prove It Works + TBNI

  • Tip SHA 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb reviewed (docs tip vs parent 0eb84a3f + full PR three-dot files)
  • Softs 1–7 verified present at tip (file quotes above)
  • Sample path + cadence-ticks Instant path traced; idle-quiet TRACE_FRAMES=0 confirmed in bench
  • Analyzer formulas + fixture expectations (incl. countedHz 57.5) checked
  • Claims vs tip: matrix attributed to tip-reachable 0eb84a3f; tip itself docs-only; idle breakdown still b321bf98
  • Offline matrix not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1; numbers taken from tip docs / PR body)

CI @ tip

  • checks (ubuntu-latest) success
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • mergeable_state clean

Merge notes

Do not merge from this gate without Oded’s yes. No Coder blocking Soft/Hard / no Coder handoff. Soft nit is PR-body wording only.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

omesser commented Sep 29, 2026

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-prove after tip move)

Verdict: Soft+Hard CLEARED @ 4bd21c5d2c74776afbb6ff196a3aee452d89b7df
Base: main @ 94b23febccea46be08aa3f5df98c1fd8b597a6b1 (not stacked)
Draft / mergeable_state: false / clean
Primary axis: cadence/methodology authenticity (idle-redraw recount + observer-effect coherence)

Prior Soft+Hard CLEARED @ 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb — #1149 (comment)

Tip delta: 4bd21c5d — docs(research): Recount the idle redraws from the re-measured run (docs-only; parent is prior CLEARED 1e41f109; +5/−3 in docs/research/performance-baseline-v1.md only).

Spec

PASS (scoped) — Part of #426, macOS idle / idle-quiet / walking / CPU-load cadence slice as in the PR body. Does not claim riding-window / seam / non-macOS.

Softs 1–7 (re-verified at new tip)

Soft Status Proof
1. Measured SHA ≠ tip CLOSED Matrix still attributed to tip-reachable 0eb84a3f (ancestor of docs tip), rebased onto main 94b23feb. Tip itself is docs recount of that run’s 83 idle frames.
2. Engine-path observer CLOSED cadence-ticks: + idle-quiet; 53.8 vs 53.9; unchanged by tip.
3. Still/moving crosses clocks CLOSED Baseline caveat stands; recount reuses the same clock-cross match and says so.
4. Walking window ≠ continuous walk CLOSED Armed-stretch fps + pauses — unchanged.
5. Multi-overlay pooling CLOSED Limits bullet — unchanged.
6. Lag vs #426 wording CLOSED Arrival→display — unchanged.
7. FIDGET_TRACE_CADENCE naming CLOSED DEVELOPMENT.md bench-only — unchanged.

New Softs from authenticity review of the recount

Soft Status Note
A. PR body still says “~5 times a second” / “About 3 of those are FRAME_RESEND” clear-with Tip baseline now says ~4/s from the remasured 83 (22 art / 61 resend). Summary table + How-to-verify still match matrix; finding prose in the PR body is stale.
B. Prior Soft nit: PR “all three” vs matrix also idle-quiet clear-with (stood) Unchanged by tip.
C. 22/61 art-vs-resend split is offline classification clear-with scripts/frame-cadence.mjs does not emit this breakdown; tip discloses the match rule (Engine state at/before latest arrival; same clocks as the moving gate). Totals 22+61=83 match the published idle row; ~3 resends/s fits the 250 ms FRAME_RESEND period. Not a checked-in analyzer artifact — disclosed inference, not invention.

Hard: None.

Cadence authenticity summary

  • Tip surface: docs-only; no sample-path / formula / fixture change vs CLEARED 1e41f109.
  • Event→clock→sample→aggregate for fps / drops / Engine Hz / lag: unchanged and still non-skewing (rAF noteCadence → 1s flush; Instant cadence-ticks:; moving-only lag; armed-stretch deltas).
  • Measured SHA: matrix @ tip-reachable 0eb84a3f; tip 4bd21c5d recounts that run’s idle 83 — honest attribution.
  • Idle redraw recount: drops the earlier b321bf98 (108-frame) breakdown; uses remasured 83 → 22 new art + 61 FRAME_RESEND → “about 4 times a second.” Arithmetic and rate coherent; method disclosed.
  • Observer-effect story: idle-quiet 257 vs traced idle 83 remains unexplained one-sample variance in-doc — tip does not paper it over or invent a cause. Residual shared instrument (FIDGET_TRACE_CADENCE) still the intended compare.

No Hard authenticity skew vs what tip samples / claims.

Prove It Works + TBNI

  • Tip SHA 4bd21c5d2c74776afbb6ff196a3aee452d89b7df confirmed (head still matches; parent 1e41f109)
  • Tip patch vs prior CLEARED: docs-only (performance-baseline-v1.md)
  • Softs 1–7 re-verified CLOSED at tip
  • Recount arithmetic 22+61=83; rate ~4/s; method + clock-cross disclosed
  • Observer residual (257 vs 83) still honest / unexplained
  • PR-body “~5/s” + “all three” Softs noted clear-with
  • Offline matrix / remasure logs not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1)

CI @ tip (4bd21c5d2c74776afbb6ff196a3aee452d89b7df)

  • checks (ubuntu-latest) success
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • mergeable_state clean

Merge notes

Do not merge from this gate without Oded’s yes. Check-not-drive. No Coder blocking Soft/Hard — clear-with Softs are PR-body polish / offline-split disclosure only.

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

omesser commented Sep 29, 2026 •

Copy link
Copy Markdown
Owner Author

Soft+Hard Standards+Spec gate — PR #1149 (re-prove after tip move)

Verdict: Soft+Hard CLEARED @ 4bd21c5d2c74776afbb6ff196a3aee452d89b7df
Base: main @ 94b23febccea46be08aa3f5df98c1fd8b597a6b1 (not stacked)
Draft / mergeable_state: false / clean
Primary axis: measurement authenticity / observer effect (frame cadence, drops, Engine Hz, interpolation lag)

Prior CLEARED @ 1e41f109f6c68e1ccab98c4cac13dde0f83e8ecb (gate #1149 (comment)). Tip ancestry: 0eb84a3f (cadence-ticks / idle-quiet) → 1e41f109 (re-measure docs) → tip 4bd21c5d (“Recount the idle redraws from the re-measured run”, docs-only, parent exact).

Spec

PASS (scoped) — Part of #426, macOS idle / walking / CPU-load cadence slice as in the PR body, plus idle-quiet for observer closure. Does not claim riding-window / seam / non-macOS.

Softs 1–7 (re-verified at new tip)

Soft Status Proof
1. Measured SHA ≠ tip CLOSED Baseline: Measured at tip-reachable 0eb84a3f (ancestor of docs tip). Idle art/resend now from the re-measured 83-frame idle run (22 art / 61 resend, “~4/s”); no b321bf98. 22+61=83; 83/20s≈4.15.
2. Engine-path observer CLOSED Unchanged vs prior tip: cadence-ticks: Instant under FIDGET_TRACE_CADENCE; idle-quiet (TRACE_FRAMES=0); matrix runs four scenarios
3. Still/moving crosses clocks CLOSED Baseline caveat; tip match note reuses same clocks as moving gate
4. Walking window ≠ continuous walk CLOSED Mean fps = armed stretches; window includes pauses
5. Multi-overlay pooling CLOSED Limits: seam double-count; none measured
6. Lag vs #426 wording CLOSED Lag = arrival→display (webview clock), not Engine tick
7. FIDGET_TRACE_CADENCE naming CLOSED DEVELOPMENT.md: bench-only, no Settings row; lists cadence-ticks:

Cadence / measurement authenticity

Docs tip only recounts idle display frames already attributed to the 0eb84a3f matrix idle sample. Match method (Engine state at/before latest arrival; new art when state/placement/anim differs; else resend) is disclosed and shares the existing cross-clock caveat — not a hidden skew. Softs 2–7 sample/analyze path unchanged. No Hard authenticity skew.

Standards

Hard: None.
Soft (nit, clear-with):

  1. PR “What changed” still says matrix is idle/walking/load “all three”; bench matrix also runs idle-quiet.
  2. PR findings still say idle redraws “about 5 times a second”; tip baseline correctly says “~4/s” (22/61). Docs tip fixed the baseline; PR body not updated.

Applied AGENTS.md + docs/agents/comments.md + docs/agents/writing.md.

Prove It Works + TBNI

  • Tip SHA 4bd21c5d2c74776afbb6ff196a3aee452d89b7df reviewed (docs tip vs parent 1e41f109 + Soft 1 recount)
  • Softs 1–7 verified present at tip (code Softs 2–7 unchanged; Soft 1 recount re-checked)
  • Idle recount authenticity: 22+61=83; ~4.15/s ≈ “~4/s”; no stale b321bf98
  • Claims vs tip: matrix attributed to tip-reachable 0eb84a3f; tip itself docs-only
  • Offline matrix not re-run here (needs Mac desktop + FIDGET_BENCH_GREEN_LIGHT=1; numbers taken from tip docs / prior measure)

CI @ tip

  • checks (ubuntu-latest) success
  • checks (macos-latest) success
  • windows success
  • build success
  • deploy skipped
  • mergeable_state clean

Merge notes

Do not merge from this gate without Oded’s yes. No Coder blocking Soft/Hard / no Coder handoff. Soft nits are PR-body wording only.

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

@omesser
omesser merged commit 5dfa467 into main Sep 29, 2026
5 checks passed
@omesser
omesser deleted the perf/426-frame-cadence branch September 29, 2026 10:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant