@antzsoft/chat-core 1.0.3 → 1.0.5

package/docs/integration-guide.html

@@ -130,6 +130,11 @@ li{margin-bottom:4px;color:#c8d0e0}
     <p id="nav-platform-label">Integration Guide</p>
   </div>
 
+  <div class="section-label">What's New</div>
+  <ul>
+    <li><a href="#whats-new">v1.0.5 Release Notes</a></li>
+  </ul>
+
   <div class="section-label">Getting Started</div>
   <ul>
     <li><a href="#overview">Overview</a></li>
@@ -159,7 +164,7 @@ li{margin-bottom:4px;color:#c8d0e0}
 
   <div class="section-label">Messaging</div>
   <ul>
-    <li><a href="#step-load">8. Load Messages</a></li>
+    <li><a href="#step-load">8. Load Messages &amp; Jump to Unread</a></li>
     <li><a href="#step-send">9. Send a Message</a></li>
     <li><a href="#step-realtime">10. Real-time Events</a></li>
     <li><a href="#step-typing">11. Typing Indicators</a></li>
@@ -208,6 +213,190 @@ li{margin-bottom:4px;color:#c8d0e0}
   </button>
 </div>
 
+<!-- ─── WHAT'S NEW ────────────────────────────────────────────────────── -->
+<section id="whats-new">
+  <h2>What's New</h2>
+  <p style="color:var(--muted);font-size:13px;margin-bottom:20px">Version history and release notes. Click a version to expand.</p>
+
+  <!-- ── v1.0.5 (current) ── -->
+  <div class="wn-version" id="wn-105">
+    <div class="wn-header" onclick="toggleVersion('wn-105')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.0.5</span>
+        <span class="wn-badge current">Current</span>
+        <span class="wn-date">May 2026</span>
+      </div>
+      <span class="wn-chevron">▲</span>
+    </div>
+    <div class="wn-body">
+
+      <div class="wn-item" id="wn-105-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title"><code>externalId</code> on all user responses</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>All API methods that return a user object now include an <code>externalId</code> field — this is the Antz User ID. Maps chat users directly back to your own system without a separate lookup.</p>
+          <p><strong>Usage:</strong> <code>user.externalId</code> is available on every <code>User</code> object — from <code>usersApi</code>, conversation participants, and message senders. No code change needed.</p>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> (participant objects) · Users API reference</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-2')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Single unified User List API</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>One <code>usersApi.list()</code> call now handles listing, searching, and pagination. Previous separate endpoints are consolidated.</p>
+          <pre><code><span class="fn">usersApi</span>.<span class="fn">list</span>()                                  <span class="cm">// all users</span>
+<span class="fn">usersApi</span>.<span class="fn">list</span>({ <span class="at">query</span>: <span class="str">'john'</span> })                  <span class="cm">// search by name / username / email</span>
+<span class="fn">usersApi</span>.<span class="fn">list</span>({ <span class="at">page</span>: <span class="num">1</span>, <span class="at">limit</span>: <span class="num">20</span> })              <span class="cm">// paginated</span></code></pre>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> (user list examples) · Users API reference</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-3')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Single unified Conversation List API</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>conversationsApi.list()</code> now handles listing, filtering, searching, and pagination in one call. All filters run server-side before pagination.</p>
+          <pre><code><span class="fn">conversationsApi</span>.<span class="fn">list</span>()                                          <span class="cm">// all</span>
+<span class="fn">conversationsApi</span>.<span class="fn">list</span>({ <span class="at">type</span>: <span class="str">'group'</span>, <span class="at">hasUnread</span>: <span class="kw">true</span> })         <span class="cm">// filter</span>
+<span class="fn">conversationsApi</span>.<span class="fn">list</span>({ <span class="at">search</span>: <span class="str">'design'</span>, <span class="at">page</span>: <span class="num">1</span>, <span class="at">limit</span>: <span class="num">20</span> })  <span class="cm">// search + page</span></code></pre>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> for the full filter reference</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-4">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-4')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Attachment last-message content preview</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When the last message in a conversation was an attachment, the conversation list showed no content preview. Fixed — the server now returns a formatted preview string (e.g. <em>"📎 photo.jpg"</em>).</p>
+          <p><strong>Action required:</strong> Display <code>conversation.lastMessage.content.text</code> directly. Remove any workarounds that were falling back to a placeholder for attachment messages.</p>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6</a> (conversation object) · <a href="#step-realtime">Step 10 — Real-time Events</a> (<code>conversation_updated</code>)</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-5">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-5')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Avatar upload via <code>AntzChatClient</code></span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>client.auth.uploadAvatar()</code> and <code>client.auth.syncAvatar()</code> were not correctly storing the avatar in all storage configurations. Fixed.</p>
+          <p><strong>Action required:</strong> Remove any workarounds for failed avatar uploads. Both methods now work correctly.</p>
+          <p class="wn-ref">→ <a href="#step1">Step 1 — Avatar section</a> for usage of <code>uploadAvatar()</code> and <code>syncAvatar()</code></p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-6">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-6')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title"><code>client.connect()</code> on React Native</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>chatClient.connect()</code> now correctly initialises and establishes the Socket.IO connection on React Native (Expo and bare). Previously the socket could fail to connect silently in certain RN configurations.</p>
+          <p><strong>Action required:</strong> Verify <code>await chatClient.connect()</code> transitions <code>onSocketStatus</code> to <code>'connected'</code>. No API change — same call, now reliable.</p>
+          <p class="wn-ref">→ <a href="#step-socket">Step 3 — Connect Socket</a> for the full RN root provider setup</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-7">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-7')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Group icon — create &amp; update</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Group conversations now support a custom icon. Admins can set or replace it at any time. The icon is stored server-side and a fresh signed URL is returned on every conversation response.</p>
+          <pre><code><span class="cm">// Upload icon — admin only</span>
+<span class="kw">const</span> updated = <span class="kw">await</span> client.<span class="fn">uploadIcon</span>(groupId, {
+  <span class="at">uri</span>: file.uri, <span class="at">name</span>: <span class="str">'icon.jpg'</span>, <span class="at">type</span>: <span class="str">'image/jpeg'</span>, <span class="at">size</span>: file.size,
+});
+<span class="cm">// updated.iconUrl → fresh signed URL</span></code></pre>
+          <p>Non-admins receive <code>403 Forbidden</code>. The URL is never stored in the DB — regenerated from <code>iconMeta.storageKey</code> on every response. Replacing an icon automatically deletes the previous one.</p>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> (group icon section) for the full upload pipeline</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-105-8">
+        <div class="wn-item-header" onclick="toggleItem('wn-105-8')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Scroll to first unread message</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Open a conversation directly at the first unread message with an "↑ Unread messages" divider. Uses <code>getLastRead()</code> combined with <code>list()</code> <code>direction: 'after'</code>.</p>
+          <pre><code><span class="cm">// 1. Get last-read pointer</span>
+<span class="kw">const</span> { lastReadMessageId, lastReadAt } = <span class="kw">await</span> messagesApi.<span class="fn">getLastRead</span>(conversationId);
+
+<span class="cm">// 2. Fetch unread messages (everything after the last-read)</span>
+<span class="kw">const</span> { data: unread, meta } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(conversationId, {
+  <span class="at">cursor</span>: lastReadMessageId, <span class="at">direction</span>: <span class="str">'after'</span>, <span class="at">limit</span>: <span class="num">50</span>,
+});
+
+<span class="cm">// 3. Scroll to first unread</span>
+<span class="kw">if</span> (unread.length) <span class="fn">scrollToMessage</span>(unread[<span class="num">0</span>].id);
+<span class="cm">// meta.hasMore = true → more than 50 unread</span>
+
+<span class="cm">// 4. Render divider above first unread message</span>
+<span class="kw">const</span> isFirstUnread = lastRead && prevMessage?.id === lastRead.messageId;</code></pre>
+          <p class="wn-ref">→ <a href="#step-load">Step 8 — Jump to first unread</a> for full code · <a href="#step-read">Step 12 — Read Receipts &amp; Last Seen</a> for the complete last-read reference</p>
+        </div>
+      </div>
+
+    </div><!-- /.wn-body -->
+  </div><!-- /.wn-version -->
+
+</section>
+
+<style>
+/* ── What's New ── */
+.wn-version{border:1px solid var(--border);border-radius:var(--radius);margin-bottom:12px;overflow:hidden}
+.wn-header{display:flex;align-items:center;justify-content:space-between;padding:14px 18px;cursor:pointer;background:var(--surface);user-select:none}
+.wn-header:hover{background:var(--surface2)}
+.wn-title{display:flex;align-items:center;gap:10px}
+.wn-ver{font-weight:800;font-size:15px;color:#fff}
+.wn-badge{font-size:10px;font-weight:700;padding:2px 8px;border-radius:20px;letter-spacing:.4px}
+.wn-badge.current{background:rgba(52,211,153,.15);color:var(--green);border:1px solid rgba(52,211,153,.3)}
+.wn-date{font-size:12px;color:var(--muted)}
+.wn-chevron{font-size:11px;color:var(--muted);transition:transform .2s}
+.wn-version:not(.open) .wn-chevron{transform:rotate(180deg)}
+.wn-body{display:none;padding:4px 0 8px}
+.wn-version.open .wn-body{display:block}
+
+.wn-item{border-top:1px solid var(--border)}
+.wn-item-header{display:flex;align-items:center;gap:10px;padding:11px 18px;cursor:pointer;user-select:none}
+.wn-item-header:hover{background:var(--surface2)}
+.wn-item-title{flex:1;font-size:13.5px;color:var(--text)}
+.wn-item-title code{font-family:var(--font-mono);font-size:12px;color:var(--accent2);background:rgba(167,139,250,.12);padding:1px 5px;border-radius:3px}
+.wn-chevron-sm{font-size:10px;color:var(--muted);transition:transform .2s}
+.wn-item.open .wn-chevron-sm{transform:rotate(180deg)}
+.wn-item-body{display:none;padding:4px 18px 14px 18px}
+.wn-item.open .wn-item-body{display:block}
+.wn-item-body p{font-size:13px;color:#c8d0e0;margin-bottom:8px}
+.wn-item-body pre{margin:8px 0 10px}
+.wn-ref{font-size:12px !important;color:var(--muted) !important}
+.wn-ref a{color:var(--accent);text-decoration:none}
+.wn-ref a:hover{text-decoration:underline}
+
+.wn-tag{font-size:10px;font-weight:700;padding:2px 7px;border-radius:20px;letter-spacing:.4px;white-space:nowrap}
+.wn-tag.new{background:rgba(108,140,255,.15);color:var(--accent);border:1px solid rgba(108,140,255,.3)}
+.wn-tag.fix{background:rgba(251,191,36,.12);color:var(--yellow);border:1px solid rgba(251,191,36,.25)}
+.wn-tag.break{background:rgba(248,113,113,.12);color:var(--red);border:1px solid rgba(248,113,113,.25)}
+</style>
+
 <!-- ─── OVERVIEW ──────────────────────────────────────────────────────── -->
 <section id="overview">
   <h2>Overview</h2>
@@ -842,6 +1031,39 @@ chatClient.<span class="fn">disconnect</span>();
   <span class="at">name</span>: <span class="str">'Design Team'</span>, <span class="at">participantIds</span>: [<span class="str">'user-1'</span>, <span class="str">'user-2'</span>],
 });
 
+<span class="cm">// ── Group icon (admin only) ───────────────────────────────────────────────────</span>
+<span class="cm">// Always upload AFTER createGroup — the group must exist first.</span>
+<span class="cm">// Uses the SAME presigned URL pipeline as message attachments.</span>
+<span class="cm">// platformUploadFn is handled automatically — you never pass it explicitly.</span>
+
+<span class="cm">// Headless (AntzChatClient) — one call, mirrors client.uploadFiles()</span>
+<span class="kw">const</span> updated = <span class="kw">await</span> client.<span class="fn">uploadIcon</span>(group.id, {
+  <span class="at">uri</span>: <span class="str">'blob:http://...'</span>,  <span class="cm">// URL.createObjectURL(file) on web, file URI on RN</span>
+  <span class="at">name</span>: <span class="str">'icon.jpg'</span>,
+  <span class="at">type</span>: <span class="str">'image/jpeg'</span>,
+  <span class="at">size</span>: file.size,
+});
+<span class="cm">// updated.iconUrl → fresh signed URL, regenerated on every API response</span>
+
+<span class="cm">// What client.uploadIcon() does internally:</span>
+<span class="cm">// Step 1 — client.uploadFiles([file], conversationId)</span>
+<span class="cm">//   → POST /storage/presigned-url       creates temp chat_files record</span>
+<span class="cm">//   → platformUploadFn()                 client uploads binary direct to S3/Azure/local</span>
+<span class="cm">//   → POST /storage/confirm/:fileId      marks chat_files active, returns fileId</span>
+<span class="cm">// Step 2 — conversationsApi.uploadIcon(conversationId, fileId)</span>
+<span class="cm">//   → PUT /conversations/:id/icon { fileId }</span>
+<span class="cm">//      Server: validateAdmin() → verify file → copy storageKey into iconMeta</span>
+<span class="cm">//              → delete chat_files record → return conversation with fresh iconUrl</span>
+
+<span class="cm">// iconUrl behaviour:</span>
+<span class="cm">// - Never stored in DB — regenerated from iconMeta.storageKey on every response</span>
+<span class="cm">// - Previous icon deleted from storage automatically when replaced</span>
+<span class="cm">// - iconMeta = { storageKey, provider, bucket, mimeType, size } embedded in conversation doc</span>
+<span class="cm">// - Non-admins get 403 Forbidden at server level</span>
+
+<span class="cm">// Web/RN SDK components (GroupInfoPanel, NewChatModal, ChatHeader) handle this automatically.</span>
+<span class="cm">// Camera button shown only to admins. No code needed in your app.</span>
+
 <span class="cm">// Participants</span>
 <span class="kw">const</span> members = <span class="kw">await</span> conversationsApi.<span class="fn">getMembers</span>(conversationId);
 <span class="kw">await</span> conversationsApi.<span class="fn">addParticipants</span>(conversationId, [<span class="str">'user-3'</span>]);
@@ -857,33 +1079,89 @@ chatClient.<span class="fn">disconnect</span>();
 
 <!-- ─── STEP 7: ROOMS ──────────────────────────────────────────────────── -->
 <section id="step-rooms">
-  <h2><span class="step">STEP 7</span> Join &amp; Leave a Room</h2>
-  <p>Joining a room subscribes your socket to real-time events for that conversation. Both <code>joinRoom</code> and <code>leaveRoom</code> are fire-and-forget — they silently no-op if the socket isn't connected.</p>
+  <h2><span class="step">STEP 7</span> Rooms — Auto-join, <code>joinRoom</code>, and <code>new_message</code></h2>
+
+  <h4>Auto-join on connect</h4>
+  <p>
+    <strong>On every socket connection, the server automatically joins the user into all their existing conversation rooms.</strong>
+    No client action is needed. The moment the socket connects, the user is already subscribed to real-time events
+    (<code>new_message</code>, <code>typing_indicator</code>, <code>read_receipt</code>, etc.) for every conversation they belong to.
+  </p>
+  <div class="callout info">
+    <strong>You do not need to call <code>joinRoom</code> when opening a chat screen.</strong>
+    The user is already in the room. Calling <code>joinRoom</code> on an already-joined room is safe (idempotent)
+    but triggers an unnecessary DB access check — avoid it in hot paths.
+  </div>
+
+  <h4>When to call <code>joinRoom</code></h4>
+  <p>
+    There is only one real use case — when the <strong>user is added to a conversation while their socket is already connected</strong>
+    (either someone created a new group and added them, or they were added to an existing group at runtime).
+    The server does <strong>not</strong> auto-join the user's socket to the new room — it only emits <code>conversation_created</code>
+    to the user's personal room. Without calling <code>joinRoom</code>, the socket will not receive any
+    <code>new_message</code>, <code>typing_indicator</code>, or other room events for that conversation.
+  </p>
+
+  <pre><code><span class="cm">// Fires when you're added to a new or existing conversation at runtime</span>
+client.socket.<span class="fn">on</span>(<span class="str">'conversation_created'</span>, (conv) => {
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id);
+});</code></pre>
+
+  <p><code>leaveRoom</code> is only needed if you want to intentionally stop receiving events for a room the user is still a member of (e.g. archiving client-side). It is not needed when navigating away from a screen.</p>
+
+  <h4>Where to listen to <code>new_message</code></h4>
+  <p>
+    Because the user is auto-joined to all rooms, <code>new_message</code> fires for <em>any</em> conversation — not just the one currently open.
+    Register <strong>one listener at app root level</strong>, right after <code>client.connect()</code>.
+    Never add it inside a screen or component. Use <code>message.conversationId</code> to route the message to the right place.
+  </p>
 
   <div data-p="rn web">
-    <pre><code><span class="kw">import</span> { socketEmit, onSocketStatus } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+    <pre><code><span class="cm">// Register once at app root — covers all conversations</span>
+client.socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, (event: <span class="tp">NewMessageEvent</span>) => {
+  <span class="kw">const</span> { message } = event;
 
-<span class="fn">useEffect</span>(() => {
-  socketEmit.<span class="fn">joinRoom</span>(conversationId);
+  <span class="cm">// Update the open chat view if this conversation is active</span>
+  <span class="kw">if</span> (message.conversationId === activeConversationId) {
+    <span class="fn">appendMessageToView</span>(message);
+  }
 
-  <span class="cm">// Re-join if socket reconnects while this screen is open (e.g. after foreground)</span>
-  <span class="kw">const</span> unsub = <span class="fn">onSocketStatus</span>((s) => {
-    <span class="kw">if</span> (s === <span class="str">'connected'</span>) socketEmit.<span class="fn">joinRoom</span>(conversationId);
+  <span class="cm">// Always update conversation list (last message + unread badge)</span>
+  <span class="fn">updateConversationList</span>(message.conversationId, {
+    lastMessage: message,
+    <span class="cm">// Don't increment unread if the user sent it or is currently viewing that chat</span>
+    incrementUnread: message.conversationId !== activeConversationId
+                     &amp;&amp; message.senderId !== currentUserId,
   });
+});
 
-  <span class="kw">return</span> () => { socketEmit.<span class="fn">leaveRoom</span>(conversationId); unsub(); };
-}, [conversationId]);</code></pre>
+<span class="cm">// Only case where joinRoom is needed</span>
+client.socket.<span class="fn">on</span>(<span class="str">'conversation_created'</span>, (conv) => {
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id);
+});</code></pre>
   </div>
   <div data-p="node">
-    <pre><code><span class="kw">import</span> { socketEmit } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+    <pre><code><span class="cm">// Bot / headless — same pattern, one listener at startup</span>
+client.socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, (event: <span class="tp">NewMessageEvent</span>) => {
+  <span class="kw">const</span> { message } = event;
+  console.<span class="fn">log</span>(<span class="str">`[</span>${message.conversationId}<span class="str">]`</span>, message.content.text);
+  client.socket.emit.<span class="fn">markRead</span>(message.conversationId, message.id);
+});
 
-socketEmit.<span class="fn">joinRoom</span>(conversationId);
-<span class="cm">// When done:</span>
-socketEmit.<span class="fn">leaveRoom</span>(conversationId);</code></pre>
+client.socket.<span class="fn">on</span>(<span class="str">'conversation_created'</span>, (conv) => {
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id);
+});</code></pre>
   </div>
+
   <div class="callout warn">
-    <strong>Room subscriptions don't survive reconnects.</strong>
-    The server forgets which rooms you were in if the socket disconnects. Always re-join after reconnect (the <code>onSocketStatus</code> pattern above handles this for React apps).
+    <strong>Summary of rules:</strong>
+    <ul>
+      <li>All existing rooms are auto-joined on socket connect — no <code>joinRoom</code> needed on screen open.</li>
+      <li>Call <code>joinRoom</code> only after a <code>conversation_created</code> event.</li>
+      <li>Add the <code>new_message</code> listener once at app root, never per screen.</li>
+      <li>Use <code>message.conversationId</code> to route to the right view or badge update.</li>
+      <li>Track <code>activeConversationId</code> to decide whether to increment the unread count.</li>
+    </ul>
   </div>
 </section>
 
@@ -892,10 +1170,10 @@ socketEmit.<span class="fn">leaveRoom</span>(conversationId);</code></pre>
 <!-- ─── STEP 8: LOAD MESSAGES ─────────────────────────────────────────── -->
 <section id="step-load">
   <h2><span class="step">STEP 8</span> Load Messages</h2>
-  <p>Cursor-paginated. Load latest on open, fetch older as user scrolls up.</p>
+  <p>Cursor-paginated. Load latest on open, fetch older as user scrolls up. The <code>direction</code> param controls which side of the cursor to fetch — <code>'before'</code> for older messages (scroll up), <code>'after'</code> for newer messages (scroll down or jump-to-unread).</p>
   <pre><code><span class="kw">import</span> { messagesApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
 
-<span class="cm">// Initial load</span>
+<span class="cm">// Initial load — latest messages (no cursor = most recent first)</span>
 <span class="kw">const</span> { data: messages, meta } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(conversationId, { <span class="at">limit</span>: <span class="num">30</span> });
 
 <span class="cm">// Load older (scroll up)</span>
@@ -903,6 +1181,79 @@ socketEmit.<span class="fn">leaveRoom</span>(conversationId);</code></pre>
   <span class="at">cursor</span>: meta.nextCursor, <span class="at">direction</span>: <span class="str">'before'</span>, <span class="at">limit</span>: <span class="num">30</span>,
 });
 <span class="cm">// meta.hasMore — false when you've reached the beginning</span></code></pre>
+
+  <hr class="divider" style="margin:28px 0"/>
+
+  <h3>Jump to first unread message</h3>
+  <p>When a conversation has unread messages, you can open the chat directly at the first unread message instead of scrolling to the bottom. This gives users an immediate visual anchor — a <strong>"N unread messages"</strong> divider — right above the first message they haven't read.</p>
+
+  <div class="callout info">
+    <strong>How it works</strong>
+    <code>getLastRead()</code> returns <code>lastReadMessageId</code> — the last message the user read.
+    Fetching with <code>direction: 'after'</code> and that ID as the cursor returns all messages <em>after</em> it — those are the unread ones.
+    The first item in that response is the message to scroll to. <code>meta.hasMore</code> tells you if there are more than <code>limit</code> unread messages.
+  </div>
+
+  <pre><code><span class="kw">import</span> { messagesApi, useChatStore } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="cm">// Step 1 — get the user's last-read pointer for this conversation</span>
+<span class="kw">const</span> { lastReadMessageId, lastReadAt } = <span class="kw">await</span> messagesApi.<span class="fn">getLastRead</span>(conversationId);
+
+<span class="kw">if</span> (lastReadMessageId) {
+  <span class="cm">// Seed the store so the unread divider renders correctly</span>
+  useChatStore.<span class="fn">getState</span>().<span class="fn">setLastRead</span>(conversationId, lastReadMessageId, lastReadAt!);
+
+  <span class="cm">// Step 2 — fetch messages AFTER the last-read message (these are unread)</span>
+  <span class="kw">const</span> { data: unreadMessages, meta } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(conversationId, {
+    <span class="at">cursor</span>: lastReadMessageId,
+    <span class="at">direction</span>: <span class="str">'after'</span>,
+    <span class="at">limit</span>: <span class="num">50</span>,
+  });
+
+  <span class="cm">// unreadMessages[0] is the first unread — scroll to it</span>
+  <span class="cm">// meta.hasMore = true means there are more than 50 unread messages</span>
+
+  <span class="kw">if</span> (unreadMessages.length > <span class="num">0</span>) {
+    <span class="fn">scrollToMessage</span>(unreadMessages[<span class="num">0</span>].id);  <span class="cm">// scroll FlatList / ScrollView to this item</span>
+  }
+} <span class="kw">else</span> {
+  <span class="cm">// No prior read state — load latest messages as normal</span>
+  <span class="kw">const</span> { data: messages } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(conversationId, { <span class="at">limit</span>: <span class="num">30</span> });
+}</code></pre>
+
+  <div data-p="rn web">
+    <h4>Rendering the "unread" divider</h4>
+    <p>Use <code>useChatStore.lastRead[conversationId]</code> to insert a divider row above the first unread message in your list:</p>
+    <pre><code><span class="kw">const</span> lastRead = <span class="fn">useChatStore</span>(s => s.lastRead[conversationId]);
+
+<span class="kw">function</span> <span class="fn">MessageRow</span>({ message, prevMessage }) {
+  <span class="cm">// Insert divider between lastRead message and the next one</span>
+  <span class="kw">const</span> isFirstUnread = lastRead && prevMessage?.id === lastRead.messageId;
+
+  <span class="kw">return</span> (
+    &lt;&gt;
+      {isFirstUnread && (
+        &lt;<span class="fn">View</span> style={styles.unreadDivider}&gt;
+          &lt;<span class="fn">Text</span>&gt;↑ Unread messages&lt;/<span class="fn">Text</span>&gt;
+        &lt;/<span class="fn">View</span>&gt;
+      )}
+      &lt;<span class="fn">MessageBubble</span> message={message} /&gt;
+    &lt;/&gt;
+  );
+}</code></pre>
+  </div>
+
+  <h4>Full pattern summary</h4>
+  <table>
+    <thead><tr><th>Step</th><th>Call</th><th>Purpose</th></tr></thead>
+    <tbody>
+      <tr><td>1</td><td><code>messagesApi.getLastRead(conversationId)</code></td><td>Get the last-read message ID and seed the store</td></tr>
+      <tr><td>2</td><td><code>messagesApi.list(conversationId, { cursor: lastReadMessageId, direction: 'after' })</code></td><td>Fetch all unread messages after that pointer</td></tr>
+      <tr><td>3</td><td>Scroll to <code>unreadMessages[0].id</code></td><td>Jump the list to the first unread message</td></tr>
+      <tr><td>4</td><td>Render divider when <code>prevMessage.id === lastRead.messageId</code></td><td>Show "↑ Unread messages" label above the first unread</td></tr>
+      <tr><td>5</td><td><code>socketEmit.markRead(conversationId)</code> on screen focus</td><td>Tell server the user has read the conversation</td></tr>
+    </tbody>
+  </table>
 </section>
 
 <!-- ─── STEP 9: SEND ───────────────────────────────────────────────────── -->
@@ -970,18 +1321,113 @@ socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, (e
   </div>
   <h4>All socket events</h4>
   <table>
-    <thead><tr><th>Event</th><th>When fired</th></tr></thead>
+    <thead><tr><th>Event</th><th>When fired</th><th>Where to listen / unlisten</th></tr></thead>
     <tbody>
-      <tr><td><code>'new_message'</code></td><td>New message in a joined room</td></tr>
-      <tr><td><code>'message_updated'</code></td><td>A message was edited</td></tr>
-      <tr><td><code>'message_deleted'</code></td><td>Deleted for everyone</td></tr>
-      <tr><td><code>'message_deleted_for_me'</code></td><td>Deleted for current user only</td></tr>
-      <tr><td><code>'reaction_updated'</code></td><td>Emoji reaction added/removed</td></tr>
-      <tr><td><code>'typing'</code></td><td>User started/stopped typing</td></tr>
-      <tr><td><code>'user_online'</code> / <code>'user_offline'</code></td><td>User went online/offline — auto-updates <code>useChatStore.lastSeen</code></td></tr>
-      <tr><td><code>'read_receipt'</code></td><td>Messages marked as read — auto-updates <code>useChatStore.lastRead</code></td></tr>
-      <tr><td><code>'message_ack'</code></td><td>Your sent message acknowledged (tempId → real ID)</td></tr>
-      <tr><td><code>'message_delivered'</code></td><td>Message delivered to recipient</td></tr>
+      <tr>
+        <td><code>'new_message'</code></td>
+        <td>New message in any of the user's conversations — all rooms are auto-joined on connect</td>
+        <td><strong>App root</strong> after <code>client.connect()</code>. Never remove this listener — it must stay alive for the full app session to keep the conversation list and unread badges up to date.</td>
+      </tr>
+      <tr>
+        <td><code>'message_updated'</code></td>
+        <td>A message was edited</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount (<code>socket.off</code>).</td>
+      </tr>
+      <tr>
+        <td><code>'message_deleted'</code></td>
+        <td>Deleted for everyone</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'message_deleted_for_me'</code></td>
+        <td>Deleted for current user only (fired only to that user's socket)</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'reaction_updated'</code></td>
+        <td>Emoji reaction added/removed</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'message_pin_updated'</code></td>
+        <td>A message was pinned or unpinned</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'typing_indicator'</code></td>
+        <td>User started/stopped typing (payload: <code>{ conversationId, userId, displayName, isTyping }</code>)</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'user_online'</code></td>
+        <td>A participant came online</td>
+        <td><strong>App root</strong> — drives online indicators everywhere. Keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'user_offline'</code></td>
+        <td>A participant went offline</td>
+        <td><strong>App root</strong> — drives online indicators and last-seen everywhere. Keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'user_status'</code></td>
+        <td>Global presence broadcast (online/offline/away) to all connected clients</td>
+        <td><strong>App root</strong> — keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'online_users'</code></td>
+        <td>Full list of online user IDs — sent on initial room join</td>
+        <td><strong>App root</strong> — keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'read_receipt'</code></td>
+        <td>Messages marked as read by a participant</td>
+        <td><strong>Chat detail screen</strong> (to update tick marks) + <strong>app root</strong> (to clear your own unread count when read on another device).</td>
+      </tr>
+      <tr>
+        <td><code>'unread_count_changed'</code></td>
+        <td>Your unread count changed — sent to all your devices simultaneously</td>
+        <td><strong>App root / conversation list screen</strong> — keep alive as long as the list is rendered.</td>
+      </tr>
+      <tr>
+        <td><code>'message_ack'</code></td>
+        <td>Server acknowledged your sent message (tempId → real ID)</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'message_delivered'</code></td>
+        <td>A single message you sent was delivered to all active recipients</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'messages_delivered'</code></td>
+        <td>Batch delivery catch-up when a recipient comes online</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'conversation_created'</code></td>
+        <td>A new conversation was created (or you were added to one)</td>
+        <td><strong>App root</strong> — call <code>joinRoom</code> here for the new conversation. Keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'conversation_updated'</code></td>
+        <td>A conversation's last message or metadata changed</td>
+        <td><strong>App root</strong> — keep for full session. The server emits this for every message across all conversations; a global listener keeps the in-memory conversation list and unread badge always in sync.</td>
+      </tr>
+      <tr>
+        <td><code>'conversation_deleted'</code></td>
+        <td>A conversation was deleted</td>
+        <td><strong>App root / conversation list screen</strong> — remove the conversation from state and navigate away if it was open.</td>
+      </tr>
+      <tr>
+        <td><code>'participant_joined'</code></td>
+        <td>A new participant was added to a group conversation</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'participant_left'</code></td>
+        <td>A participant left or was removed from a group conversation</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
     </tbody>
   </table>
 </section>
@@ -1059,7 +1505,7 @@ socketEmit.<span class="fn">markRead</span>(conversationId);              <span
   <hr class="divider" style="margin:28px 0"/>
 
   <h3>Last-read pointer — where the user left off</h3>
-  <p>The store keeps a <strong>last-read pointer</strong> per conversation: the ID and timestamp of the last message the current user read. This is useful for scroll-to-unread and "unread from here" badges.</p>
+  <p>The store keeps a <strong>last-read pointer</strong> per conversation: the ID and timestamp of the last message the current user read. This is used for scroll-to-first-unread, "unread from here" dividers, and unread count badges. See <a href="#step-load">Step 8 — Jump to first unread</a> for the complete implementation pattern.</p>
 
   <div class="callout tip">
     <strong>Automatic after connect</strong>
@@ -1910,19 +2356,114 @@ socket?.<span class="fn">on</span>(<span class="str">'unread_count_changed'</spa
   <span class="cm">// unreadCount is 0 — the conversation was just read.</span>
 });</code></pre>
 
-  <h3>Platform-specific badge updates</h3>
+  <h3>Chat icon badge — the key insight</h3>
+  <p>
+    If you use <code>@antzsoft/chat-web-sdk</code> or <code>@antzsoft/chat-rn-sdk</code>,
+    <strong>you do not need to listen to socket events manually</strong>.
+    <code>useConversations()</code> is already subscribed internally — every
+    <code>conversation_updated</code> and <code>unread_count_changed</code> event
+    automatically updates the hook's data. Just sum the counts:
+  </p>
 
-  <div data-p="rn">
-    <pre><code><span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
-<span class="kw">import</span> { AppState } <span class="kw">from</span> <span class="str">'react-native'</span>;
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { useConversations } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">function</span> <span class="fn">ChatIconButton</span>({ onClick }: { onClick: () => <span class="tp">void</span> }) {
+  <span class="kw">const</span> { conversations } = <span class="fn">useConversations</span>();
+
+  <span class="cm">// Recalculates automatically on every socket update — no extra listener needed</span>
+  <span class="kw">const</span> totalUnread = conversations.<span class="fn">reduce</span>(
+    (sum, c) => sum + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>
+  );
+
+  <span class="kw">return</span> (
+    &lt;button onClick={onClick} style={{ position: <span class="str">'relative'</span> }}&gt;
+      💬
+      {totalUnread &gt; <span class="num">0</span> &amp;&amp; (
+        &lt;span style={{
+          position: <span class="str">'absolute'</span>, top: <span class="num">-6</span>, right: <span class="num">-6</span>,
+          backgroundColor: <span class="str">'#e53935'</span>, color: <span class="str">'#fff'</span>,
+          borderRadius: <span class="str">'50%'</span>, minWidth: <span class="num">18</span>, height: <span class="num">18</span>,
+          fontSize: <span class="num">11</span>, fontWeight: <span class="num">700</span>,
+          display: <span class="str">'flex'</span>, alignItems: <span class="str">'center'</span>, justifyContent: <span class="str">'center'</span>,
+          padding: <span class="str">'0 4px'</span>,
+        }}&gt;
+          {totalUnread &gt; <span class="num">99</span> ? <span class="str">'99+'</span> : totalUnread}
+        &lt;/span&gt;
+      )}
+    &lt;/button&gt;
+  );
+}
 
-<span class="cm">// Keep badge in sync while app is active</span>
+<span class="cm">// Update browser tab title too</span>
 <span class="fn">useEffect</span>(() => {
   <span class="kw">const</span> total = conversations.<span class="fn">reduce</span>((s, c) => s + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>);
-  Notifications.<span class="fn">setBadgeCountAsync</span>(total);
-}, [conversations]);
+  document.title = total &gt; <span class="num">0</span> ? <span class="str">`(${total}) Antz Chat`</span> : <span class="str">'Antz Chat'</span>;
+}, [conversations]);</code></pre>
+  </div>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { useConversations } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+<span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
+
+<span class="kw">function</span> <span class="fn">ChatTabIcon</span>({ color }: { color: <span class="tp">string</span> }) {
+  <span class="kw">const</span> { conversations } = <span class="fn">useConversations</span>();
+
+  <span class="cm">// Recalculates automatically on every socket update — no extra listener needed</span>
+  <span class="kw">const</span> totalUnread = conversations.<span class="fn">reduce</span>(
+    (sum, c) => sum + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>
+  );
+
+  <span class="cm">// Sync OS app icon badge</span>
+  <span class="fn">useEffect</span>(() => {
+    Notifications.<span class="fn">setBadgeCountAsync</span>(totalUnread);
+  }, [totalUnread]);
 
-<span class="cm">// Refresh when app comes to foreground (socket may have been down)</span>
+  <span class="kw">return</span> (
+    &lt;View&gt;
+      &lt;Ionicons name=<span class="str">"chatbubbles-outline"</span> size={<span class="num">24</span>} color={color} /&gt;
+      {totalUnread &gt; <span class="num">0</span> &amp;&amp; (
+        &lt;View style={{
+          position: <span class="str">'absolute'</span>, top: <span class="num">-4</span>, right: <span class="num">-6</span>,
+          backgroundColor: <span class="str">'#e53935'</span>, borderRadius: <span class="num">9</span>,
+          minWidth: <span class="num">18</span>, height: <span class="num">18</span>, alignItems: <span class="str">'center'</span>,
+          justifyContent: <span class="str">'center'</span>, paddingHorizontal: <span class="num">4</span>,
+        }}&gt;
+          &lt;Text style={{ color: <span class="str">'#fff'</span>, fontSize: <span class="num">10</span>, fontWeight: <span class="str">'700'</span> }}&gt;
+            {totalUnread &gt; <span class="num">99</span> ? <span class="str">'99+'</span> : String(totalUnread)}
+          &lt;/Text&gt;
+        &lt;/View&gt;
+      )}
+    &lt;/View&gt;
+  );
+}
+
+<span class="cm">// Wire into Tab.Navigator</span>
+&lt;Tab.Screen
+  name=<span class="str">"Chat"</span>
+  component={ChatScreen}
+  options={{ tabBarIcon: ({ color }) =&gt; &lt;ChatTabIcon color={color} /&gt; }}
+/&gt;</code></pre>
+  </div>
+
+  <p style="margin:16px 0 8px;color:#c8d0e0;font-size:14px">
+    The full update chain — no polling, no manual socket code:
+  </p>
+  <pre style="background:var(--code-bg);padding:12px 16px;border-radius:8px;font-size:12px;color:#8892b0;border:1px solid var(--border)">New message sent
+  → server emits conversation_updated (DB-accurate unreadCount per participant)
+  → SocketProvider updates useConversations() React Query cache
+  → totalUnread recalculates → badge re-renders
+
+User reads conversation
+  → server emits unread_count_changed to ALL devices of that user simultaneously
+  → useConversations() cache updated → badge clears on every device at once</pre>
+
+  <h3>Platform-specific: foreground resume + tab title</h3>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AppState } <span class="kw">from</span> <span class="str">'react-native'</span>;
+
+<span class="cm">// Refresh when app comes to foreground (socket may have been down while backgrounded)</span>
 <span class="fn">useEffect</span>(() => {
   <span class="kw">const</span> sub = AppState.<span class="fn">addEventListener</span>(<span class="str">'change'</span>, <span class="kw">async</span> (state) => {
     <span class="kw">if</span> (state === <span class="str">'active'</span>) {
@@ -1935,13 +2476,7 @@ socket?.<span class="fn">on</span>(<span class="str">'unread_count_changed'</spa
   </div>
 
   <div data-p="web">
-    <pre><code><span class="cm">// Browser tab title badge</span>
-<span class="fn">useEffect</span>(() => {
-  <span class="kw">const</span> total = conversations.<span class="fn">reduce</span>((s, c) => s + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>);
-  document.title = total > <span class="num">0</span> ? <span class="str">`(${total}) Antz Chat`</span> : <span class="str">'Antz Chat'</span>;
-}, [conversations]);
-
-<span class="cm">// Refresh when tab becomes visible (socket may have been down)</span>
+    <pre><code><span class="cm">// Refresh when tab becomes visible (socket may have been down)</span>
 <span class="fn">useEffect</span>(() => {
   <span class="kw">function</span> <span class="fn">onVisible</span>() {
     <span class="kw">if</span> (document.visibilityState === <span class="str">'visible'</span>) {
@@ -2042,6 +2577,14 @@ document.getElementById('nav-platform-label').textContent =
   savedP === 'rn' ? 'React Native' : savedP === 'web' ? 'React / Next.js' : 'Node.js';
 applyGating();
 
+// ── What's New toggles ───────────────────────────────────────────────────
+function toggleVersion(id) {
+  document.getElementById(id).classList.toggle('open');
+}
+function toggleItem(id) {
+  document.getElementById(id).classList.toggle('open');
+}
+
 // ── Progress bar ──────────────────────────────────────────────────────────
 window.addEventListener('scroll', () => {
   const el = document.getElementById('prog');