Skip to main content

sonos_cli/tui/
hooks.rs

1//! TUI hooks system — co-located widget state, SDK subscriptions, and animation.
2//!
3//! Modeled after React hooks but adapted for Rust's ownership model and
4//! ratatui's immediate-mode rendering. Three primitives:
5//!
6//! - `use_state<V>(key, default)` — Persistent local state across renders
7//! - `use_watch(property_handle)` — Subscribe to SDK property, return current value
8//! - `use_animation(key, active)` — Request periodic re-renders when active
9//!
10//! ## Calling Convention
11//!
12//! `use_state` returns `&mut V` which borrows `&mut self` on `Hooks`.
13//! To avoid borrow conflicts, call hooks in this order:
14//!
15//! 1. `use_watch` — returns owned `Option<V>`, borrow released immediately
16//! 2. `use_animation` — `&mut self` borrow released immediately
17//! 3. `use_state` — must be called last or in a scoped block
18//!
19//! ## Frame Lifecycle
20//!
21//! ```text
22//! hooks.begin_frame()     // reset access tracking
23//! terminal.draw(...)      // widgets call hooks
24//! hooks.end_frame()       // evict unaccessed state + handles
25//! ```
26
27use std::any::{Any, TypeId};
28use std::collections::{HashMap, HashSet};
29
30use sonos_sdk::property::{GroupFetchable, GroupPropertyHandle, PropertyHandle};
31use sonos_state::property::SonosProperty;
32
33use crate::tui::app::App;
34
35// ============================================================================
36// RenderContext
37// ============================================================================
38
39/// Render context passed to all render functions.
40///
41/// Wraps `&App` (read) and `&mut Hooks` (write), satisfying the borrow checker
42/// by separating immutable app data from mutable hook state.
43pub struct RenderContext<'a> {
44    pub app: &'a App,
45    pub hooks: &'a mut Hooks,
46}
47
48// ============================================================================
49// HookKey — state identity
50// ============================================================================
51
52/// Composite key for `use_state`: combines value type with a string name.
53///
54/// Two hooks with the same string key but different value types get separate
55/// storage slots (keyed by `TypeId`).
56#[derive(Hash, Eq, PartialEq, Clone, Debug)]
57struct HookKey {
58    type_id: TypeId,
59    name: String,
60}
61
62impl HookKey {
63    fn new<V: 'static>(name: &str) -> Self {
64        Self {
65            type_id: TypeId::of::<V>(),
66            name: name.to_string(),
67        }
68    }
69}
70
71// ============================================================================
72// ProgressState — moved from app.rs to co-locate with hooks
73// ============================================================================
74
75/// Client-side progress interpolation state for a single group.
76///
77/// Stores a snapshot of position + wall-clock timestamp. While playing,
78/// `interpolated_position_ms()` advances the position based on elapsed time,
79/// capped at 10s to limit drift from system sleep/stalls.
80#[derive(Clone, Debug)]
81pub struct ProgressState {
82    pub last_position_ms: u64,
83    pub last_duration_ms: u64,
84    pub wall_clock_at_last_update: std::time::Instant,
85    pub is_playing: bool,
86}
87
88impl Default for ProgressState {
89    fn default() -> Self {
90        Self {
91            last_position_ms: 0,
92            last_duration_ms: 0,
93            wall_clock_at_last_update: std::time::Instant::now(),
94            is_playing: false,
95        }
96    }
97}
98
99impl ProgressState {
100    /// Update from SDK position and playback data.
101    pub fn update(&mut self, position_ms: u64, duration_ms: u64, is_playing: bool) {
102        // Freeze at interpolated position on pause transition
103        if self.is_playing && !is_playing {
104            self.last_position_ms = self.interpolated_position_ms();
105        }
106
107        self.last_position_ms = position_ms;
108        self.last_duration_ms = duration_ms;
109        self.is_playing = is_playing;
110        self.wall_clock_at_last_update = std::time::Instant::now();
111    }
112
113    /// Compute interpolated position in milliseconds.
114    ///
115    /// Caps interpolation at 10s ahead to limit drift from system sleep/stalls.
116    pub fn interpolated_position_ms(&self) -> u64 {
117        if !self.is_playing {
118            return self.last_position_ms;
119        }
120        let elapsed = self.wall_clock_at_last_update.elapsed().as_millis() as u64;
121        let capped_elapsed = elapsed.min(10_000);
122        (self.last_position_ms + capped_elapsed).min(self.last_duration_ms)
123    }
124}
125
126// ============================================================================
127// Hooks
128// ============================================================================
129
130/// General-purpose hooks system for TUI widget state management.
131///
132/// Stores persistent state, SDK watch handles, and animation registrations.
133/// Uses mark-and-sweep to automatically clean up state when widgets stop
134/// rendering (e.g., screen transitions).
135pub struct Hooks {
136    // use_state storage — keyed by (TypeId, name)
137    states: HashMap<HookKey, Box<dyn Any>>,
138
139    // use_watch storage — type-erased WatchHandle<P>, keyed by "speaker_id:property_key"
140    watches: HashMap<String, Box<dyn Any>>,
141
142    // use_animation — keys of active animations
143    animations: HashSet<String>,
144
145    // Mark-and-sweep: keys accessed during current frame
146    accessed_states: HashSet<HookKey>,
147    accessed_watches: HashSet<String>,
148    accessed_animations: HashSet<String>,
149}
150
151impl Default for Hooks {
152    fn default() -> Self {
153        Self::new()
154    }
155}
156
157impl Hooks {
158    pub fn new() -> Self {
159        Self {
160            states: HashMap::new(),
161            watches: HashMap::new(),
162            animations: HashSet::new(),
163            accessed_states: HashSet::new(),
164            accessed_watches: HashSet::new(),
165            accessed_animations: HashSet::new(),
166        }
167    }
168
169    // -----------------------------------------------------------------------
170    // Frame lifecycle
171    // -----------------------------------------------------------------------
172
173    /// Reset access tracking before a render frame.
174    pub fn begin_frame(&mut self) {
175        self.accessed_states.clear();
176        self.accessed_watches.clear();
177        self.accessed_animations.clear();
178    }
179
180    /// Evict unaccessed state and drop unaccessed watch handles.
181    pub fn end_frame(&mut self) {
182        // Evict unaccessed states
183        self.states
184            .retain(|key, _| self.accessed_states.contains(key));
185
186        // Drop unaccessed watch handles (starts grace periods)
187        self.watches
188            .retain(|key, _| self.accessed_watches.contains(key));
189
190        // Remove unaccessed animations
191        self.animations
192            .retain(|key| self.accessed_animations.contains(key));
193    }
194
195    // -----------------------------------------------------------------------
196    // use_state
197    // -----------------------------------------------------------------------
198
199    /// Get or create persistent local state.
200    ///
201    /// On first call for a given key, creates the state using `default()`.
202    /// On subsequent calls, returns the existing state.
203    ///
204    /// **Must be called last** — the returned `&mut V` borrows `&mut self`,
205    /// preventing other hook calls until the reference is dropped.
206    pub fn use_state<V: 'static>(&mut self, key: &str, default: impl FnOnce() -> V) -> &mut V {
207        let hook_key = HookKey::new::<V>(key);
208        self.accessed_states.insert(hook_key.clone());
209
210        self.states
211            .entry(hook_key)
212            .or_insert_with(|| Box::new(default()))
213            .downcast_mut::<V>()
214            .expect("use_state: type mismatch for key (same key used with different types)")
215    }
216
217    // -----------------------------------------------------------------------
218    // use_watch
219    // -----------------------------------------------------------------------
220
221    /// Subscribe to an SDK speaker property, returning the current value.
222    ///
223    /// Each frame, creates a fresh `WatchHandle` via `prop.watch()` to get
224    /// an up-to-date snapshot. The old handle is replaced (dropped → grace
225    /// period starts → new handle re-acquires → grace period cancelled).
226    /// This is the SDK's intended pattern: "Re-watch each frame to refresh
227    /// the snapshot."
228    ///
229    /// Falls back to `prop.get()` if `watch()` fails.
230    pub fn use_watch<P>(&mut self, prop: &PropertyHandle<P>) -> Option<P>
231    where
232        P: SonosProperty + Clone + 'static,
233    {
234        let key = format!("{}:{}", prop.speaker_id(), P::KEY);
235        self.accessed_watches.insert(key.clone());
236
237        // Create a fresh watch handle each frame to get updated values.
238        // WatchHandle is a snapshot — value is set at creation and never updates.
239        // Replacing the old handle drops it (grace period starts), then the new
240        // handle re-acquires the subscription (grace period cancelled).
241        match prop.watch() {
242            Ok(wh) => {
243                let val = wh.value().cloned();
244                self.watches.insert(key, Box::new(wh));
245                val
246            }
247            Err(e) => {
248                tracing::warn!(
249                    "use_watch failed for {}: {e}, falling back to get()",
250                    P::KEY
251                );
252                prop.get()
253            }
254        }
255    }
256
257    /// Subscribe to an SDK group property, returning the current value.
258    ///
259    /// Same as `use_watch` but for group-scoped properties (e.g., group volume).
260    #[allow(dead_code)]
261    pub fn use_watch_group<P>(&mut self, prop: &GroupPropertyHandle<P>) -> Option<P>
262    where
263        P: SonosProperty + Clone + 'static,
264    {
265        let key = format!("group:{}:{}", prop.group_id(), P::KEY);
266        self.accessed_watches.insert(key.clone());
267
268        match prop.watch() {
269            Ok(wh) => {
270                let val = wh.value().cloned();
271                self.watches.insert(key, Box::new(wh));
272                val
273            }
274            Err(e) => {
275                tracing::warn!(
276                    "use_watch_group failed for {}: {e}, falling back to get()",
277                    P::KEY
278                );
279                prop.get()
280            }
281        }
282    }
283
284    /// Subscribe to a fetchable group property, fetching on first access if empty.
285    ///
286    /// Like `use_watch_group` but performs a one-time fetch when the cache has
287    /// no value yet, so the UI doesn't show a blank until the first UPnP event.
288    pub fn use_watch_group_or_fetch<P>(&mut self, prop: &GroupPropertyHandle<P>) -> Option<P>
289    where
290        P: SonosProperty + GroupFetchable + Clone + 'static,
291    {
292        let key = format!("group:{}:{}", prop.group_id(), P::KEY);
293        self.accessed_watches.insert(key.clone());
294
295        match prop.watch_or_fetch() {
296            Ok(wh) => {
297                let val = wh.value().cloned();
298                self.watches.insert(key, Box::new(wh));
299                val
300            }
301            Err(e) => {
302                tracing::warn!(
303                    "use_watch_group_or_fetch failed for {}: {e}, falling back to get()",
304                    P::KEY
305                );
306                prop.get()
307            }
308        }
309    }
310
311    // -----------------------------------------------------------------------
312    // use_animation
313    // -----------------------------------------------------------------------
314
315    /// Register an animation tick request.
316    ///
317    /// When `active` is true, the event loop's global animation timer will
318    /// mark the app as dirty every ~250ms, triggering re-renders for smooth
319    /// progress bar animation.
320    pub fn use_animation(&mut self, key: &str, active: bool) {
321        let key = key.to_string();
322        self.accessed_animations.insert(key.clone());
323        if active {
324            self.animations.insert(key);
325        } else {
326            self.animations.remove(&key);
327        }
328    }
329
330    /// Check if any widget has registered an active animation.
331    ///
332    /// Called by the event loop between frames to decide whether to tick
333    /// the animation timer.
334    pub fn has_active_animations(&self) -> bool {
335        !self.animations.is_empty()
336    }
337}
338
339// ============================================================================
340// Tests
341// ============================================================================
342
343#[cfg(test)]
344mod tests {
345    use super::*;
346
347    #[test]
348    fn use_state_creates_default_on_first_call() {
349        let mut hooks = Hooks::new();
350        hooks.begin_frame();
351
352        let val = hooks.use_state::<u32>("counter", || 42);
353        assert_eq!(*val, 42);
354    }
355
356    #[test]
357    fn use_state_persists_across_frames() {
358        let mut hooks = Hooks::new();
359
360        // Frame 1: create state
361        hooks.begin_frame();
362        *hooks.use_state::<u32>("counter", || 0) = 10;
363        hooks.end_frame();
364
365        // Frame 2: state persists
366        hooks.begin_frame();
367        let val = hooks.use_state::<u32>("counter", || 0);
368        assert_eq!(*val, 10);
369        hooks.end_frame();
370    }
371
372    #[test]
373    fn use_state_evicts_on_unaccessed_frame() {
374        let mut hooks = Hooks::new();
375
376        // Frame 1: create state
377        hooks.begin_frame();
378        *hooks.use_state::<u32>("counter", || 42) = 100;
379        hooks.end_frame();
380
381        // Frame 2: state NOT accessed → evicted
382        hooks.begin_frame();
383        hooks.end_frame();
384
385        // Frame 3: recreated from default
386        hooks.begin_frame();
387        let val = hooks.use_state::<u32>("counter", || 42);
388        assert_eq!(*val, 42); // default, not 100
389    }
390
391    #[test]
392    fn use_state_different_types_same_name_are_separate() {
393        let mut hooks = Hooks::new();
394        hooks.begin_frame();
395
396        *hooks.use_state::<u32>("val", || 1) = 10;
397        // Borrow on hooks released after this line since u32 is Copy
398
399        let s = hooks.use_state::<String>("val", || "hello".to_string());
400        assert_eq!(s, "hello"); // separate slot, not confused with u32
401    }
402
403    #[test]
404    fn use_animation_registers_and_deregisters() {
405        let mut hooks = Hooks::new();
406        hooks.begin_frame();
407
408        assert!(!hooks.has_active_animations());
409
410        hooks.use_animation("progress", true);
411        assert!(hooks.has_active_animations());
412
413        hooks.use_animation("progress", false);
414        assert!(!hooks.has_active_animations());
415    }
416
417    #[test]
418    fn use_animation_evicts_on_unaccessed_frame() {
419        let mut hooks = Hooks::new();
420
421        // Frame 1: register animation
422        hooks.begin_frame();
423        hooks.use_animation("progress", true);
424        hooks.end_frame();
425        assert!(hooks.has_active_animations());
426
427        // Frame 2: animation NOT accessed → evicted
428        hooks.begin_frame();
429        hooks.end_frame();
430        assert!(!hooks.has_active_animations());
431    }
432
433    #[test]
434    fn progress_state_interpolation() {
435        let mut ps = ProgressState {
436            last_position_ms: 1000,
437            last_duration_ms: 5000,
438            is_playing: false,
439            ..Default::default()
440        };
441
442        // Not playing → returns last position
443        assert_eq!(ps.interpolated_position_ms(), 1000);
444
445        // Playing → interpolates forward
446        ps.is_playing = true;
447        ps.wall_clock_at_last_update = std::time::Instant::now();
448        // Position should be >= 1000 (at least the base)
449        assert!(ps.interpolated_position_ms() >= 1000);
450    }
451
452    #[test]
453    fn progress_state_caps_at_duration() {
454        let ps = ProgressState {
455            last_position_ms: 4900,
456            last_duration_ms: 5000,
457            is_playing: true,
458            // Simulate old timestamp (10+ seconds ago)
459            wall_clock_at_last_update: std::time::Instant::now()
460                - std::time::Duration::from_secs(20),
461        };
462
463        // Should cap at duration, not overflow
464        assert_eq!(ps.interpolated_position_ms(), 5000);
465    }
466
467    #[test]
468    fn mark_and_sweep_preserves_accessed_drops_rest() {
469        let mut hooks = Hooks::new();
470
471        // Frame 1: create multiple states
472        hooks.begin_frame();
473        *hooks.use_state::<u32>("keep", || 1) = 10;
474        // Release borrow
475        let _ = hooks.use_state::<u32>("drop_me", || 2);
476        hooks.use_animation("keep_anim", true);
477        hooks.use_animation("drop_anim", true);
478        hooks.end_frame();
479
480        // Frame 2: only access "keep" variants
481        hooks.begin_frame();
482        let val = hooks.use_state::<u32>("keep", || 99);
483        assert_eq!(*val, 10); // persisted
484        hooks.use_animation("keep_anim", true);
485        hooks.end_frame();
486
487        // Frame 3: verify "drop_me" was evicted
488        hooks.begin_frame();
489        let val = hooks.use_state::<u32>("drop_me", || 99);
490        assert_eq!(*val, 99); // recreated from default
491        hooks.end_frame();
492
493        // And "drop_anim" should be gone
494        // (only "keep_anim" should remain)
495    }
496}