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>

tests/test_clips.py

@@ -143,3 +143,16 @@ def test_ring_move_to_dict_serializes_steps(tmp_path):
     assert d["steps"][0]["file"] == "transitions/abyss-cosmos.mp4"
     assert d["steps"][0]["reversed"] is False
     assert d["steps"][0]["to_index"] == 0
+    assert d["fast"] is False
+    assert d["steps"][0]["blended"] is False
+
+
+def test_ring_move_to_dict_marks_fast_blended_pass(tmp_path):
+    p = tmp_path / "manifest.json"
+    p.write_text(json.dumps(_ring_manifest_dict()))
+    ring = load_ring(p)
+    move = advance_ring(ring, from_index=0, delta=4, fast_spin_threshold=3)
+    d = ring_move_to_dict(move, ring)
+    assert d["fast"] is True
+    assert len(d["steps"]) == 1
+    assert d["steps"][0]["blended"] is True

tests/test_player_ring.py

@@ -136,3 +136,73 @@ def test_degenerate_single_scale_ring_is_a_noop():
     assert move.to_index == 0
     assert move.steps == ()
     assert move.wrapped is False
+
+
+# --- fast-spin: a faster blended pass past a speed threshold (scales design §3) ---
+#
+# A fast encoder spin batches many detents into one advance() call, so |delta| is
+# the input adapter's proxy for spin speed. Past a configured threshold the move
+# collapses to a SINGLE blended pass (the arrival-edge clip, played fast) instead
+# of chaining N full transitions. The policy is opt-in (default off) because the
+# pure function cannot know wall-clock spin speed — the input layer enables it.
+
+
+def test_fast_spin_disabled_by_default_chains_every_detent():
+    r = _ring()
+    move = advance_ring(r, from_index=0, delta=5)
+    assert move.fast is False
+    assert len(move.steps) == 5
+    assert all(not s.blended for s in move.steps)
+
+
+def test_fast_spin_below_threshold_still_chains():
+    r = _ring()
+    move = advance_ring(r, from_index=0, delta=2, fast_spin_threshold=3)
+    assert move.fast is False
+    assert len(move.steps) == 2
+    assert move.steps[0].edge == 0 and move.steps[1].edge == 1
+
+
+def test_fast_spin_at_or_above_threshold_collapses_to_one_blended_step():
+    r = _ring()
+    # 4 inward detents from cosmos(0): 0->1->2->0->1, lands on forest(1),
+    # crosses the abyss->cosmos seam, last edge crossed is edge 0 (forward).
+    move = advance_ring(r, from_index=0, delta=4, fast_spin_threshold=3)
+    assert move.fast is True
+    assert move.to_index == 1
+    assert move.wrapped is True
+    assert move.steps == (
+        TransitionStep(
+            edge=0, reversed=False, file="t/cosmos-forest.mp4", to_index=1, blended=True
+        ),
+    )
+
+
+def test_fast_spin_outward_blended_step_is_reversed():
+    r = _ring()
+    # 4 outward detents from cosmos(0): 0->2->1->0->2, lands on abyss(2);
+    # outward arrival crosses edge 2 (abyss->cosmos) reversed.
+    move = advance_ring(r, from_index=0, delta=-4, fast_spin_threshold=3)
+    assert move.fast is True
+    assert move.to_index == 2
+    assert move.wrapped is True
+    assert move.steps == (
+        TransitionStep(
+            edge=2, reversed=True, file="t/abyss-cosmos.mp4", to_index=2, blended=True
+        ),
+    )
+
+
+def test_fast_spin_threshold_below_two_is_ignored():
+    # A threshold of 0 or 1 would blend even single deliberate steps — treat as off.
+    r = _ring()
+    move = advance_ring(r, from_index=0, delta=3, fast_spin_threshold=1)
+    assert move.fast is False
+    assert len(move.steps) == 3
+
+
+def test_fast_spin_noop_on_degenerate_ring():
+    r = ScaleRing(scales=(Scale("solo", "solo"),), transitions=())
+    move = advance_ring(r, from_index=0, delta=9, fast_spin_threshold=3)
+    assert move.fast is False
+    assert move.steps == ()

tests/test_simulator_api.py

@@ -162,6 +162,24 @@ def test_ring_advance_outward_reverses_edge(ring_client):
     assert data["steps"][0]["reversed"] is True
 
 
+def test_ring_advance_small_delta_chains_not_fast(ring_client):
+    # 2 detents is below the simulator's fast-spin threshold (3) -> full chain.
+    resp = ring_client.post("/api/ring/advance", json={"from_index": 0, "delta": 2})
+    data = resp.json()
+    assert data["fast"] is False
+    assert len(data["steps"]) == 2
+
+
+def test_ring_advance_fast_spin_collapses_to_one_blended_pass(ring_client):
+    # A fast spin (4 detents batched) crosses the threshold -> one blended pass.
+    resp = ring_client.post("/api/ring/advance", json={"from_index": 0, "delta": 4})
+    data = resp.json()
+    assert data["fast"] is True
+    assert len(data["steps"]) == 1
+    assert data["steps"][0]["blended"] is True
+    assert data["to_index"] == 1
+
+
 def test_ring_404_when_no_ring_in_manifest(client):
     assert client.get("/api/ring").status_code == 404
     assert client.post("/api/ring/advance", json={"from_index": 0, "delta": 1}).status_code == 404