From 5865c166249ccf3873cbe4f761a93030b9146e3f Mon Sep 17 00:00:00 2001
From: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Date: Wed, 13 May 2026 18:07:54 +0100
Subject: [PATCH] docs(player): explain set_stream_error(false) message swallow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clearing the error flag also drops any pending stream_error_message.
A fast record_stream_error -> set_stream_error(false) -> polling-tick
sequence will silently swallow the toast — that is the intent (a
recovered error is not user-actionable), but it surprises future
readers, so document it inline.
---
 crates/qbz-player/src/player/mod.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/crates/qbz-player/src/player/mod.rs b/crates/qbz-player/src/player/mod.rs
index 0d4c24190..7bfad7cf4 100644
--- a/crates/qbz-player/src/player/mod.rs
+++ b/crates/qbz-player/src/player/mod.rs
@@ -956,6 +956,13 @@ impl SharedState {
         }
     }
 
+    /// Clearing (`error = false`) also drops any pending
+    /// `stream_error_message`. This is intentional: if init recovers before
+    /// the Tauri polling loop drains the message, we'd rather swallow the
+    /// toast than surface a notification for a transient failure the user
+    /// never perceived. The trade-off is that a fast record→clear→drain
+    /// sequence loses the message — accepted because a recovered error is
+    /// not a user-actionable event.
     pub fn set_stream_error(&self, error: bool) {
         self.stream_error.store(error, Ordering::SeqCst);
         if !error {