feat(ring): fast-spin blended pass past a speed threshold (scales design §3)

A multi-detent encoder spin previously chained one full transition per scale
crossed (e.g. +5 ≈ 5 placeholder morphs ≈ 12-15s), which feels sluggish for a
fast spin. Design §3 anticipates this: "transitions chain, or past a speed
threshold a faster blended pass is used."

`player.ring.advance_ring` gains an opt-in `fast_spin_threshold` (canonical
default `DEFAULT_FAST_SPIN_THRESHOLD = 3`). A spin batches its detents into one
advance() call, so `abs(delta)` is the input layer's proxy for spin speed; at or
above the threshold the move collapses to a single blended pass — one
`TransitionStep` (the arrival edge, marked `blended`, landing straight on the
destination, `RingMove.fast=True`) instead of the full chain. Landing index,
seam-crossing (`wrapped`), and arrival edge/direction are exactly the full
chain's; only the in-between transitions are dropped.

The policy is opt-in (default off) because the pure function cannot observe
wall-clock spin speed — the simulator/firmware, which can, enables it. This keeps
all existing complete-chain behavior and tests intact. The simulator passes the
default threshold and plays the blended step at 2.5× (FAST_BLEND_RATE); a
dedicated fast-blend clip can replace the accelerated arrival-edge placeholder
when real transition media exists.

- player/ring.py: TransitionStep.blended, RingMove.fast, threshold param + policy
- simulator/clips.py: serialize fast/blended in ring_move_to_dict
- simulator/app.py: apply DEFAULT_FAST_SPIN_THRESHOLD at /api/ring/advance
- simulator/static/app.js: play a blended step at FAST_BLEND_RATE
- docs: scales design §3, USER_GUIDE, ROADMAP slice-3 note

Tests: +9 (ring policy, serializer, API). Suite 224 passed / 2 skipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

player/ring.py

@@ -21,6 +21,15 @@ Ordering convention:
     small->large wrap seam. One transition clip per edge plays FORWARD when
     zooming inward and REVERSED when zooming outward, so N scales need only N
     transition clips.
+
+Fast spin (§3, "transitions chain, or past a speed threshold a faster blended
+pass is used"): a quick encoder spin batches many detents into one advance, so
+`abs(delta)` is the input adapter's proxy for spin speed. Past an opt-in
+`fast_spin_threshold` the move collapses to a SINGLE blended pass (the
+arrival-edge clip, played fast) rather than chaining N full transitions, so a
+fast spin stays responsive instead of grinding through every morph. The policy
+is opt-in (default off) because this pure function cannot observe wall-clock
+spin speed — the input layer (simulator/firmware), which can, enables it.
 """
 
 from __future__ import annotations
@@ -28,6 +37,13 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 
+# Default spin-speed cutoff for the input layer (simulator/firmware) to enable
+# the fast-spin blended pass: 3+ detents batched into one advance() is a fast
+# spin crossing several scales; 1-2 are deliberate single steps that chain. Tune
+# by eye — it is a UX policy, not canonical ring structure.
+DEFAULT_FAST_SPIN_THRESHOLD = 3
+
+
 class RingError(ValueError):
     """Raised when a ScaleRing is structurally invalid."""
 
@@ -83,23 +99,34 @@ class ScaleRing:
 @dataclass(frozen=True)
 class TransitionStep:
     """One transition to play during a move: which edge clip, in which direction,
-    and the scale index it lands on."""
+    and the scale index it lands on.
+
+    `blended` marks the single collapsed step of a fast-spin pass (see
+    `advance_ring`'s `fast_spin_threshold`): the renderer plays it as one quick
+    accelerated morph straight to the destination instead of a full transition.
+    """
 
     edge: int
     reversed: bool
     file: str
     to_index: int
+    blended: bool = False
 
 
 @dataclass(frozen=True)
 class RingMove:
     """The result of advancing the encoder: where you end up and the ordered
-    transitions to play getting there (chained for a multi-detent spin)."""
+    transitions to play getting there (chained for a multi-detent spin).
+
+    `fast` is True when the move was collapsed to a single blended pass because
+    the spin crossed the speed threshold (see `advance_ring`).
+    """
 
     from_index: int
     to_index: int
     steps: tuple[TransitionStep, ...]
     wrapped: bool
+    fast: bool = False
 
 
 def scale_at(ring: ScaleRing, index: int) -> Scale:
@@ -107,13 +134,25 @@ def scale_at(ring: ScaleRing, index: int) -> Scale:
     return ring.scales[index % len(ring)]
 
 
-def advance_ring(ring: ScaleRing, from_index: int, delta: int) -> RingMove:
+def advance_ring(
+    ring: ScaleRing,
+    from_index: int,
+    delta: int,
+    *,
+    fast_spin_threshold: int = 0,
+) -> RingMove:
     """Walk the endless encoder `delta` detents from `from_index` (signed).
 
     Returns a `RingMove` with the landing index and the ordered `TransitionStep`s
     to play. Inward steps (+) play edge i forward; outward steps (-) play the
     crossed edge reversed. `wrapped` is True if any step crossed the small<->large
     seam. A degenerate single-scale ring (or delta 0) is a no-op.
+
+    `fast_spin_threshold` (opt-in, default off): when >= 2 and `abs(delta)` meets
+    it, the spin is treated as fast and the move collapses to a single blended
+    pass — one `TransitionStep` (the arrival edge, marked `blended`) landing
+    straight on the destination, with `RingMove.fast=True` — instead of chaining
+    every transition. See the module docstring (§3).
     """
     n = len(ring)
     start = from_index % n
@@ -147,6 +186,26 @@ def advance_ring(ring: ScaleRing, from_index: int, delta: int) -> RingMove:
         )
         index = nxt
 
+    # Fast spin: collapse the whole chain to a single blended arrival pass. The
+    # landing index, seam-crossing, and arrival edge/direction are exactly those
+    # of the full chain — only the in-between transitions are dropped.
+    if fast_spin_threshold >= 2 and abs(delta) >= fast_spin_threshold:
+        arrival = steps[-1]
+        blended = TransitionStep(
+            edge=arrival.edge,
+            reversed=arrival.reversed,
+            file=arrival.file,
+            to_index=arrival.to_index,
+            blended=True,
+        )
+        return RingMove(
+            from_index=start,
+            to_index=index,
+            steps=(blended,),
+            wrapped=wrapped,
+            fast=True,
+        )
+
     return RingMove(
         from_index=start, to_index=index, steps=tuple(steps), wrapped=wrapped
     )