fix(scroll): advance whole pixels per frame, not per wall-clock second (#545)

* fix(scroll): advance whole pixels per frame, not per wall-clock second

Smooth motion is not a frame-rate property, and measuring it as one is why
this survived three rounds of fixes. odds-ticker's frame timing is excellent
-- 100.0 fps, 10.00ms median, 0% stalls, worst in-scroll frame 19.95ms -- and
it still visibly stuttered.

What the eye judges is whether the strip advances the same number of whole
pixels on every presented frame. update_scroll_position derived position from
scroll_speed * delta_time and get_visible_portion truncated it with int(), so
jitter in delta_time decided which side of a pixel boundary the position
landed on. The live windows show why that matters: a rock-steady 100.0 fps
whose individual frames still range 5.6ms to 15.2ms, which at 100 px/s is
0.57px to 1.44px of movement.

Run the measured frame times through the real helper and 5.8% of frames
advance 0 or 2 pixels instead of 1 -- about six hitches a second. A frame that
moves nothing followed by one that jumps two is exactly what micro-stutter
looks like.

It is worst at a crisp speed, which is the part that stings: at 100 px/s on a
100Hz panel the accumulator sits exactly on integer boundaries, so
sub-millisecond jitter flips it either way and the motion beats at around
50Hz. Snapping to the crisp ladder fixes the average and the wall clock then
throws away the per-frame uniformity the ladder was bought for.

So when scroll_config snaps to a crisp speed it now also puts the helper in
fixed-step mode: each presented frame advances exactly pixels_per_frame and no
clock is consulted. 100% of frames move by the same amount, whatever the
jitter.

This is only correct because SwapOnVSync blocks until the panel has taken the
frame, which makes the frame count a truer clock than time.time(). Before the
swap was locked to vsync it would have run at whatever speed the loop spun at.
Related: frame-based mode used to step discretely and was converted to
elapsed-time accumulation earlier in this series, because its threshold
comparison flipped on jitter. That was right for the code as it stood -- but
it treated the symptom, replacing a broken discrete step with a smooth-looking
accumulator instead of asking why a wall clock was involved at all.

Non-crisp speeds keep pacing off time, and set_scroll_speed() clears the fixed
step so a legacy caller changing speed is not silently ignored.

Trade-off worth naming: speed is now tied to the presentation rate rather than
to real time. If the loop cannot keep up with the panel the scroll runs slow
rather than jumping to catch up. That is the better failure -- uniform motion
at a slightly wrong speed beats correct average speed with a hitch six times a
second -- and a loop that cannot hit the resolved rate is a measurement
problem for the crisp ladder, not something to paper over with uneven steps.

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

* test(scroll): make the time-based pin actually pin something

Review caught that test_time_based_stepping_is_what_it_replaces could pass
against perfectly uniform motion, and it was right.

update_scroll_position sets last_update_time on its way through, so the very
first call sees a delta_time of zero and moves nothing in time-based mode.
_advances counted that synthetic frame, which put a guaranteed zero in every
histogram -- enough on its own to satisfy "uneven > 0". The test asserting the
defect exists would have passed after the defect was gone.

The first call is now primed and discarded, and the assertion is a proportion
rather than "more than zero": against these frame times the old path misses
roughly one frame in twenty, so 1% is well below the real rate and far above
anything a stray frame could produce.

Re-measured with the artefact removed, the numbers in the PR description are
unchanged: 5.85% of frames uneven before (114 zero-advance and 120 double
frames in 4000), 0.00% after.

Also fills in the docstrings the review flagged: everything in the new test
file, plus three pre-existing one-liners in scroll_config that the diff
touched.

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

src/common/scroll_config.py

@@ -86,6 +86,7 @@ class CrispSpeed:
 
     @property
     def frames_per_second(self) -> float:
+        """Distinct frames per second: the refresh divided by the hold."""
         return self.refresh_hz / self.frame_hold
 
     @property
@@ -100,6 +101,7 @@ class CrispSpeed:
         return "smooth"
 
     def describe(self) -> str:
+        """This speed as a line for the speed ladder, aligned for a column."""
         return (
             f"{self.pixels_per_second:6.1f} px/s  "
             f"({self.pixels_per_frame}px every {self.frame_hold} refresh"
@@ -202,6 +204,7 @@ class ScrollSettings:
         return self.crisp.frame_hold if self.crisp else 1
 
     def describe(self) -> str:
+        """One log line: the speed applied, and which config key produced it."""
         text = f"{self.pixels_per_second:.1f} px/s (from {self.source})"
         if self.pixels_per_frame is not None:
             text += f" = {self.pixels_per_frame:.2f} px/frame"
@@ -387,6 +390,15 @@ def configure(
     if hasattr(scroll_helper, "set_frame_based_scrolling"):
         scroll_helper.set_frame_based_scrolling(False)
     scroll_helper.set_scroll_speed(applied)
+
+    # A crisp speed is a whole number of pixels per presented frame, so step by
+    # that number rather than by speed * elapsed time. Snapping alone only
+    # fixes the average: the wall clock puts the accumulator back on an integer
+    # boundary every frame, where jitter of a fraction of a millisecond decides
+    # whether the pixel moves. That is what the ladder was bought to prevent.
+    if hasattr(scroll_helper, "set_pixels_per_frame"):
+        scroll_helper.set_pixels_per_frame(
+            choice.pixels_per_frame if choice else None)
     if choice and hasattr(scroll_helper, "set_target_fps"):
         scroll_helper.set_target_fps(choice.frames_per_second)
     elif settings.target_fps and hasattr(scroll_helper, "set_target_fps"):

src/common/scroll_helper.py

@@ -135,7 +135,10 @@ class ScrollHelper:
         self._last_integer_position = 0  # Cache for integer position to avoid repeated calculations
         
         # Frame-based scrolling settings
-        self.frame_based_scrolling = False  # If True, use scroll_delay to throttle and move scroll_speed pixels
+        self.frame_based_scrolling = False
+        #: Whole pixels to advance per presented frame, or None to pace
+        #: off elapsed time. See set_pixels_per_frame.
+        self.fixed_pixels_per_frame = None  # If True, use scroll_delay to throttle and move scroll_speed pixels
         self.last_step_time = 0.0  # Track last step time for frame-based throttling
         
         # Time tracking for scroll updates
@@ -295,7 +298,13 @@ class ScrollHelper:
             self.last_progress_log_time = current_time
         
         # Update scroll position
-        if self.frame_based_scrolling:
+        if self.fixed_pixels_per_frame:
+            # One presented frame, one fixed whole-pixel step. No clock is
+            # consulted, so no jitter reaches the position and every frame
+            # moves the eye by the same amount. See set_pixels_per_frame.
+            pixels_to_move = self.fixed_pixels_per_frame
+            self.last_step_time = current_time
+        elif self.frame_based_scrolling:
             # Frame-based: move fixed amount when scroll_delay has passed
             # This matches stock ticker behavior: move pixels, then wait scroll_delay
             # Initialize last_step_time on first call to prevent huge initial jump
@@ -979,6 +988,13 @@ class ScrollHelper:
         Args:
             speed: Scroll speed (interpretation depends on frame_based_scrolling mode)
         """
+        # A speed set directly is a request to pace off that speed, so drop any
+        # fixed per-frame step left by an earlier configure(). scroll_config
+        # calls this first and set_pixels_per_frame second, so the crisp path
+        # is unaffected; what this protects is a legacy caller changing speed
+        # on a helper that scroll_config had already put in fixed-step mode,
+        # where the new speed would otherwise be silently ignored.
+        self.fixed_pixels_per_frame = None
         if self.frame_based_scrolling:
             # In frame-based mode, clamp to reasonable pixels per frame (0.1-5)
             # Higher values cause visible jumps - 1-2 pixels/frame is ideal for smoothness
@@ -999,6 +1015,35 @@ class ScrollHelper:
         self.scroll_delay = max(0.001, min(1.0, delay))
         self.logger.debug(f"Scroll delay set to: {self.scroll_delay}")
     
+    def set_pixels_per_frame(self, pixels) -> None:
+        """Advance exactly `pixels` per presented frame, ignoring the clock.
+
+        Pass None to go back to pacing off elapsed time.
+
+        Smooth motion is not a frame-rate property. The strip has to advance
+        the same number of WHOLE pixels every frame, and deriving that from a
+        wall clock cannot deliver it: the position accumulates
+        ``speed * delta_time`` and is then truncated to a pixel, so any jitter
+        in delta_time lands either side of an integer boundary. Measured on
+        hardware at a rock-steady 100.0 fps, individual frames still ranged
+        5.6ms to 15.2ms -- 0.57px to 1.44px of movement -- and 53% of frames
+        advanced by something other than one pixel: about half moved nothing
+        at all and then jumped two. That is the micro-stutter, and it survived
+        every frame-timing fix because frame timing was never the problem.
+
+        It is worst precisely at a crisp speed. At 100 px/s on a 100Hz panel
+        the accumulator sits exactly on integer boundaries, so sub-millisecond
+        jitter flips it either way and the motion beats at around 50Hz.
+
+        Stepping per frame is only correct because SwapOnVSync blocks until
+        the panel has taken the frame, which makes the frame count a truer
+        clock than time.time(). Before the swap was locked to vsync this would
+        have run at whatever speed the loop happened to spin at.
+        """
+        self.fixed_pixels_per_frame = int(pixels) if pixels else None
+        self.logger.debug("Fixed step set to: %s px/frame",
+                          self.fixed_pixels_per_frame)
+
     def set_target_fps(self, fps: float) -> None:
         """
         Set the target frames per second for scrolling.