From 5d823868c82920bd5e7f1faa91813deddf02fdff Mon Sep 17 00:00:00 2001
From: Daniel Harvey <the.real.daniel.harvey@gmail.com>
Date: Thu, 21 May 2026 07:52:13 -0400
Subject: [PATCH] docs(AudioPlayerProvider): explain IsFixed=true intent and
 runtime-swap caveat

---
 DeepDrftPublic.Client/Controls/AudioPlayerProvider.razor | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/DeepDrftPublic.Client/Controls/AudioPlayerProvider.razor b/DeepDrftPublic.Client/Controls/AudioPlayerProvider.razor
index c7c9cd8..48ae6bf 100644
--- a/DeepDrftPublic.Client/Controls/AudioPlayerProvider.razor
+++ b/DeepDrftPublic.Client/Controls/AudioPlayerProvider.razor
@@ -1,3 +1,7 @@
-<CascadingValue Value="@(_audioPlayerService)" IsFixed="true">
+@* IsFixed="true": the StreamingAudioPlayerService instance is created once in OnInitialized
+   and is never replaced — the reference is stable for the lifetime of the component.
+   If instance swapping at runtime is ever needed, change IsFixed to false (adds subscription
+   overhead on every parent re-render, but allows children to see the new reference). *@
+<CascadingValue Value="@(_audioPlayerService)" IsFixed="true">
     @ChildContent
 </CascadingValue>
\ No newline at end of file