notedeck

commit 969b31513131bd7790a8b5c1b528433b3bb13ac7
parent cd2f96a81e43f0e54231d1f8dfb2211ed4258c11
Author: alltheseas <alltheseas@users.noreply.github.com>
Date:   Fri,  2 Jan 2026 17:31:32 -0600

docs: add Concurrency & Thread Safety section

Document the codebase's approach to thread safety:
- Mutex avoidance in UI paths (use Rc<RefCell<>> instead)
- Preference for tokio::sync::RwLock over Mutex when needed
- Promise pattern for non-blocking async result polling

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Diffstat:
M
AGENTS.md
 | 
6
++++++

1 file changed, 6 insertions(+), 0 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -26,6 +26,12 @@ This document captures the current architecture, coding conventions, and design 
 - **`NotedeckApp` enum** (`crates/notedeck_chrome/src/app.rs`) defines the shipping app roster (Columns/Damus, Dave, others) and provides constructors for wiring new apps.
 - **Preview system & theming** (`crates/notedeck_chrome/src/preview.rs`, `crates/notedeck_chrome/src/theme.rs`) centralize look-and-feel, font loading, and debug previews.
 
+### Concurrency & Thread Safety
+
+- **No Mutexes in UI paths**: The render loop must never block. All UI code operates on owned data or uses `Rc<RefCell<>>` for single-threaded interior mutability.
+- **Cross-thread sharing**: When truly needed, prefer `Arc<tokio::sync::RwLock<>>` over `Arc<Mutex<>>`. The codebase has only 3 Mutex instances total (image cache size tracking, JobPool internals, test-only code).
+- **Promise pattern**: Wrap async work in `poll_promise::Promise`, check with `promise.ready()` or `promise.ready_mut()` each frame—no blocking.
+
 ### Nostr Data & Networking
 
 - **Database**: `nostrdb::Ndb` is the primary storage/query engine. Transactions are short-lived (`Transaction::new`) and most reads flow through caches.