docs: reflect write-once cell refactor from whatsapp-rust#1227

advanced/signal-protocol.mdx

@@ -661,7 +661,7 @@ This mechanism ensures that group messages from newly-paired companion devices a
 // src/message.rs — simplified flow
 async fn handle_unknown_device_sync(&self, info: &Arc<MessageInfo>) {
     let user_jid = info.source.sender.to_non_ad();
-    if !self.pending_device_sync.add(user_jid.clone()).await {
+    if !self.pending_device_sync.add(&user_jid) {
         return; // already queued, dedup
     }
     if info.is_offline {

api/chatstate.mdx

@@ -143,7 +143,7 @@ client.register_chatstate_handler(Arc::new(|event: ChatStateEvent| {
         }
         _ => {}
     }
-})).await;
+}));
 ```
 
 ### ReceivedChatState
@@ -412,4 +412,4 @@ tokio::time::sleep(Duration::from_secs(3)).await;
 
 client.chatstate().send_paused(&recipient).await?;
 println!("Recording stopped (would send audio here)");
-```
+```

api/client.mdx

@@ -1808,13 +1808,14 @@ See [ChannelEventHandler](/concepts/events#channeleventhandler) for details.
 ### register_chatstate_handler
 
 ```rust
-pub async fn register_chatstate_handler(
-    &self,
-    handler: Arc<dyn Fn(ChatStateEvent) + Send + Sync>,
-)
+pub fn register_chatstate_handler(&self, handler: Arc<dyn Fn(ChatStateEvent) + Send + Sync>)
 ```
 
-Registers a handler for chat state events (typing indicators). The handler is wrapped in `Arc` for thread-safe sharing across the event dispatching system.
+Registers a handler for chat state events (typing indicators). The handler is wrapped in `Arc` for thread-safe sharing across the event dispatching system. Registration is copy-on-write, so dispatch never blocks a concurrent registration and the zero-handler default path takes no lock at all.
+
+<Warning>
+**Breaking change (as of PR #1227):** `register_chatstate_handler` is no longer `async`. Drop the `.await` at call sites: `client.register_chatstate_handler(handler)`.
+</Warning>
 
 ### set_raw_node_forwarding
 

concepts/architecture.mdx

@@ -148,14 +148,14 @@ See [custom backends](/guides/custom-backends) for implementing your own runtime
 
 **Location:** `src/client.rs`
 
-**Purpose:** Orchestrates connection lifecycle, event bus, and high-level operations. Uses `async-lock` (runtime-agnostic) for all internal synchronization instead of Tokio-specific primitives.
+**Purpose:** Orchestrates connection lifecycle, event bus, and high-level operations. Uses `async-lock` (runtime-agnostic) instead of Tokio-specific primitives for state whose critical section awaits; state whose critical section never awaits (a clone, a store, a set op) uses a `std::sync` lock instead, and state that is built once and never replaced uses `std::sync::OnceLock` — holding either kind across an `.await` on the send path is a compile error rather than a review question ([#1227](https://github.com/oxidezap/whatsapp-rust/pull/1227)).
 
 ```rust
 pub struct Client {
     pub(crate) core: wacore::client::CoreClient,
     pub(crate) persistence_manager: Arc<PersistenceManager>,
     pub(crate) media_conn: Arc<RwLock<Option<MediaConn>>>,
-    pub(crate) noise_socket: Arc<Mutex<Option<Arc<NoiseSocket>>>>,
+    pub(crate) noise_socket: Arc<std::sync::Mutex<Option<Arc<NoiseSocket>>>>,
     // ... connection state, caches, locks
 }
 ```
@@ -513,7 +513,7 @@ When online (not during offline sync), unknown devices trigger an immediate back
 ```rust
 // src/pending_device_sync.rs
 pub(crate) struct PendingDeviceSync {
-    pending: async_lock::Mutex<HashSet<Jid>>,
+    pending: std::sync::Mutex<HashSet<Jid>>,
 }
 ```