From 7819c2e3a037648428c12abb8d047f49392dbb4b Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 18 Jul 2026 02:24:19 +0200
Subject: [PATCH] docs(nav): note the render-time ref is the intentional
 latest-value pattern

---
 frontend/src/components/NavigationProvider.tsx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/frontend/src/components/NavigationProvider.tsx b/frontend/src/components/NavigationProvider.tsx
index b09d7f1..9f93b22 100644
--- a/frontend/src/components/NavigationProvider.tsx
+++ b/frontend/src/components/NavigationProvider.tsx
@@ -95,6 +95,9 @@ export function NavigationProvider({ children }: { children: ReactNode }) {
 
   // Refs so the STABLE action callbacks can read the latest state without depending on it — a dep
   // would recreate them on every navigation and re-render every actions consumer (e.g. VideoCard).
+  // Written during render (the sanctioned "latest value" pattern): the ref is only READ in event
+  // handlers after commit, and this provider never suspends or renders in a transition, so no
+  // discarded render can leave it stale.
   const pageRef = useRef(page);
   pageRef.current = page;
   const channelViewRef = useRef(channelView);