From 1c2c942e4bdd6764a30b3616fd46ce27855e7ee2 Mon Sep 17 00:00:00 2001 From: Christoffer Martinsson Date: Thu, 11 Dec 2025 16:11:45 +0100 Subject: [PATCH] Document state management architecture principles Add critical guidelines for deriving player state from MPV rather than maintaining duplicate state. Documents the single source of truth pattern to prevent state synchronization bugs. --- CLAUDE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index c94857a..69e504e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,6 +14,29 @@ A high-performance Rust-based TUI player for playing music and video files. Buil ## Architecture +### State Management + +**CRITICAL:** Player state must be derived from MPV, not maintained separately. + +**Single Source of Truth:** MPV properties via IPC +- `idle-active` (bool) - No file loaded or file ended +- `pause` (bool) - Playback is paused + +**Derive PlayerState:** +```rust +if player.is_idle → PlayerState::Stopped +if !player.is_idle && player.is_paused → PlayerState::Paused +if !player.is_idle && !player.is_paused → PlayerState::Playing +``` + +**Rationale:** +- Eliminates state synchronization bugs +- MPV is always the authoritative source +- No need to update state in multiple places +- Simpler auto-play logic + +**Anti-pattern:** DO NOT maintain `state.player_state` that can desync from MPV + ### Cache-Only Operation **CRITICAL:** Left panel shows ONLY cached data. Never browse filesystem directly during operation.