"""Scale-ring navigation: the endless-encoder closed loop of nature scales (§3). Design: docs/superpowers/specs/2026-06-07-scales-library-and-right-axis-pipeline- design.md §3 (scale navigation & zoom transitions). The scales-of-nature library is navigated as a CLOSED RING, not a line. A dedicated endless rotary encoder — relative, vs the absolute 0..4 experience knobs — walks the ring one step per detent; diving past the smallest scale wraps around to the largest (the infinite-zoom payoff). Between each adjacent pair of scales a short pre-baked AI zoom/warp transition plays. This is the canonical navigation engine (Python-canonical, shared with the Pi player/firmware); the simulator browser only renders what `advance_ring` returns. Ordering convention: - index 0 = the LARGEST scale (cosmos); increasing index zooms INWARD toward the smallest. - +1 detent zooms in, -1 zooms out; BOTH wrap (past the smallest wraps to the largest, and vice versa). - edge i connects scales[i] -> scales[(i+1) % N]; the last edge is the 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 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.""" @dataclass(frozen=True) class Scale: """A node on the ring: a scale of nature and the clip(s) it can play. A scale carries a rotating POOL of vetted clips (content-pipeline design §11.1): when the viewer lands on the scale, the player picks one member at random (`pick_clip_id`). `clip_id` is the PRIMARY member (the deterministic default / pool[0]); `pool` is the full set. A scale written with only `clip_id` and no `pool` is a pool of one — exactly the Increment-1 behavior, so old manifests are unchanged. """ id: str clip_id: str pool: tuple[str, ...] = () @property def members(self) -> tuple[str, ...]: """The clip ids this scale can play — the pool, or just `clip_id` when no pool was authored (a pool of one).""" return self.pool if self.pool else (self.clip_id,) @dataclass(frozen=True) class Transition: """A pre-baked zoom/warp morph along ONE ring edge. `file` plays FORWARD when zooming inward (scales[i] -> scales[i+1] in ring order); the renderer reverses it for the outward direction, so one clip covers both directions of an edge. """ file: str model: str = "" @dataclass(frozen=True) class ScaleRing: """A closed ring of scales joined by per-edge transitions. Invariant: a ring of N>=2 scales has exactly N transitions (one per edge, including the small->large wrap seam). A degenerate single-scale ring has no edges. An empty ring is rejected. """ scales: tuple[Scale, ...] transitions: tuple[Transition, ...] def __post_init__(self) -> None: n = len(self.scales) if n == 0: raise RingError("a ScaleRing needs at least one scale") expected = 0 if n == 1 else n if len(self.transitions) != expected: raise RingError( f"a {n}-scale ring needs {expected} transitions, " f"got {len(self.transitions)}" ) def __len__(self) -> int: return len(self.scales) @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. `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). `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: """The scale at `index`, taken modulo the ring length (wraps both ways).""" return ring.scales[index % len(ring)] def pick_clip_id(scale: Scale, r: float) -> str: """Pick one clip id from a scale's rotating pool, given an injected uniform `r` in [0, 1) (content-pipeline design §11.1). Randomness is INJECTED so this stays a pure function — testable and shared with the Pi player; the impure draw (`random.random()`) happens once at the API/runtime boundary. `r` is clamped into [0, 1) so an off-by-epsilon caller never indexes out of range; a pool of one always returns its single member. """ members = scale.members r = min(max(r, 0.0), 0.999999) return members[int(r * len(members))] 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 if n == 1 or delta == 0: return RingMove(from_index=start, to_index=start, steps=(), wrapped=False) direction = 1 if delta > 0 else -1 steps: list[TransitionStep] = [] wrapped = False index = start for _ in range(abs(delta)): if direction > 0: # zoom inward: edge `index` forward, land at index+1 (mod n) edge = index nxt = (index + 1) % n reversed_ = False else: # zoom outward: cross edge `index-1` reversed, land at index-1 (mod n) edge = (index - 1) % n nxt = (index - 1) % n reversed_ = True if edge == n - 1: wrapped = True steps.append( TransitionStep( edge=edge, reversed=reversed_, file=ring.transitions[edge].file, to_index=nxt, ) ) 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 )