npm - @antzsoft/chat-core - Versions diffs - 1.0.2 → 1.0.3 - Mend

@antzsoft/chat-core 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +454 -39
package/dist/chat.store-PY3YVYGN.js +7 -0
package/dist/chat.store-PY3YVYGN.js.map +1 -0
package/dist/chunk-TB52RCSF.js +54 -0
package/dist/chunk-TB52RCSF.js.map +1 -0
package/dist/index.cjs +173 -57
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +155 -12
package/dist/index.d.ts +155 -12
package/dist/index.js +108 -55
package/dist/index.js.map +1 -1
package/docs/integration-guide.html +2076 -0
package/package.json +3 -2

package/docs/integration-guide.html ADDED Viewed

@@ -0,0 +1,2076 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+<title>@antzsoft/chat-core — Integration Guide</title>
+<style>
+:root {
+  --bg:#0f1117; --surface:#1a1d27; --surface2:#22263a; --border:#2e3250;
+  --accent:#6c8cff; --accent2:#a78bfa; --green:#34d399; --yellow:#fbbf24;
+  --red:#f87171; --text:#e2e8f0; --muted:#8892b0; --code-bg:#0d1117;
+  --radius:8px;
+  --font-mono:'JetBrains Mono','Fira Code',monospace;
+  --font-sans:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;
+}
+*{box-sizing:border-box;margin:0;padding:0}
+html{scroll-behavior:smooth}
+body{background:var(--bg);color:var(--text);font-family:var(--font-sans);font-size:15px;line-height:1.7;display:flex;min-height:100vh}
+/* ── Sidebar ── */
+nav{width:260px;min-width:260px;background:var(--surface);border-right:1px solid var(--border);position:fixed;top:0;left:0;bottom:0;overflow-y:auto;padding:24px 0;z-index:100}
+nav .logo{padding:0 20px 16px;border-bottom:1px solid var(--border);margin-bottom:12px}
+nav .logo h2{font-size:14px;color:var(--accent);font-weight:700;letter-spacing:.5px}
+nav .logo p{font-size:11px;color:var(--muted);margin-top:2px}
+nav ul{list-style:none}
+nav ul li a{display:block;padding:5px 20px;color:var(--muted);text-decoration:none;font-size:12.5px;border-left:2px solid transparent;transition:all .15s}
+nav ul li a:hover,nav ul li a.active{color:var(--text);border-left-color:var(--accent);background:rgba(108,140,255,.06)}
+nav .section-label{padding:12px 20px 3px;font-size:10px;font-weight:700;letter-spacing:1.2px;color:var(--muted);text-transform:uppercase}
+nav li[data-nav]{display:none}
+nav li[data-nav].show{display:block}
+/* ── Main ── */
+main{margin-left:260px;flex:1;max-width:920px;padding:40px 52px 80px}
+/* ── Typography ── */
+h1{font-size:30px;font-weight:800;color:#fff;margin-bottom:10px}
+h1 span{color:var(--accent)}
+h2{font-size:21px;font-weight:700;color:#fff;margin:52px 0 14px;padding-bottom:10px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:10px}
+h2 .step{background:var(--accent);color:#fff;font-size:11px;font-weight:800;padding:2px 8px;border-radius:20px;letter-spacing:.5px}
+h3{font-size:15px;font-weight:700;color:var(--accent2);margin:24px 0 8px}
+h4{font-size:13px;font-weight:700;color:var(--muted);margin:18px 0 6px;text-transform:uppercase;letter-spacing:.5px}
+p{margin-bottom:10px;color:#c8d0e0}
+strong{color:var(--text)}
+/* ── Platform switcher ── */
+.platform-bar{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius);padding:4px;display:flex;gap:4px;margin-bottom:32px;width:fit-content}
+.platform-btn{padding:8px 20px;border-radius:6px;border:none;background:transparent;color:var(--muted);font-size:13px;font-weight:600;cursor:pointer;transition:all .15s;white-space:nowrap}
+.platform-btn:hover{color:var(--text)}
+.platform-btn.active{background:var(--accent);color:#fff}
+.platform-btn .icon{margin-right:6px;font-size:14px}
+/* ── Auth mode switcher ── */
+.mode-bar{background:var(--surface2);border:1px solid var(--border);border-radius:var(--radius);padding:16px 20px;margin-bottom:32px}
+.mode-bar .ml{font-size:10px;font-weight:700;letter-spacing:1px;text-transform:uppercase;color:var(--muted);margin-bottom:10px}
+.mode-opts{display:flex;gap:10px}
+.mode-opt{flex:1;border:2px solid var(--border);border-radius:var(--radius);padding:12px 16px;cursor:pointer;transition:all .15s;background:var(--surface)}
+.mode-opt:hover{border-color:var(--accent)}
+.mode-opt.sel{border-color:var(--accent);background:rgba(108,140,255,.08)}
+.mode-opt .mt{font-weight:700;font-size:13px;color:var(--text);margin-bottom:3px;display:flex;align-items:center;gap:7px}
+.mode-opt .dot{width:8px;height:8px;border-radius:50%;border:2px solid var(--muted);display:inline-block;flex-shrink:0;transition:all .15s}
+.mode-opt.sel .dot{background:var(--accent);border-color:var(--accent)}
+.mode-opt .md{font-size:12px;color:var(--muted);line-height:1.4}
+.mode-note{margin-top:12px;font-size:12px;color:var(--muted);padding-top:12px;border-top:1px solid var(--border)}
+.mode-note strong{color:var(--green)}
+/* ── Platform / auth-mode gating ── */
+[data-p]{display:none}
+[data-p].pshow{display:block}
+[data-m]{display:none}
+[data-m].mshow{display:block}
+[data-pm]{display:none}
+[data-pm].pmshow{display:block}
+/* ── Code ── */
+pre{background:var(--code-bg);border:1px solid var(--border);border-radius:var(--radius);padding:18px 22px;overflow-x:auto;margin:10px 0 18px;position:relative}
+pre code{font-family:var(--font-mono);font-size:12.5px;line-height:1.75;color:#cdd6f4}
+.kw{color:#cba6f7}.fn{color:#89b4fa}.str{color:#a6e3a1}.num{color:#fab387}
+.cm{color:#585b70;font-style:italic}.tp{color:#f9e2af}.at{color:#89dceb}
+/* ── Callouts ── */
+.callout{border-radius:var(--radius);padding:13px 17px;margin:14px 0;border-left:3px solid;font-size:13.5px}
+.callout.info{background:rgba(108,140,255,.08);border-color:var(--accent);color:#aab4d4}
+.callout.warn{background:rgba(251,191,36,.07);border-color:var(--yellow);color:#d4c08a}
+.callout.tip{background:rgba(52,211,153,.07);border-color:var(--green);color:#8acdb0}
+.callout.danger{background:rgba(248,113,113,.07);border-color:var(--red);color:#d4908a}
+.callout strong{color:inherit;display:block;margin-bottom:3px}
+/* ── Tables ── */
+table{width:100%;border-collapse:collapse;margin:14px 0 20px;font-size:13px}
+th{background:var(--surface2);color:var(--muted);font-weight:700;text-align:left;padding:9px 13px;font-size:10px;text-transform:uppercase;letter-spacing:.5px}
+td{padding:9px 13px;border-bottom:1px solid var(--border);color:#c8d0e0;vertical-align:top}
+tr:last-child td{border-bottom:none}
+td code,th code{font-family:var(--font-mono);font-size:11.5px;color:var(--accent2);background:rgba(167,139,250,.1);padding:1px 5px;border-radius:3px}
+p code,li code{font-family:var(--font-mono);font-size:12px;color:var(--accent2);background:rgba(167,139,250,.12);padding:1px 5px;border-radius:3px}
+/* ── Flow ── */
+.flow{display:flex;align-items:center;flex-wrap:wrap;gap:0;margin:16px 0;font-size:11.5px}
+.flow-step{background:var(--surface2);border:1px solid var(--border);border-radius:var(--radius);padding:9px 14px;text-align:center;min-width:110px}
+.flow-step .num{font-size:9px;color:var(--accent);font-weight:700;display:block}
+.flow-step .label{color:var(--text);font-weight:600;font-size:11.5px}
+.flow-arrow{color:var(--muted);padding:0 6px;font-size:16px}
+/* ── Misc ── */
+ul,ol{padding-left:20px;margin-bottom:12px}
+li{margin-bottom:4px;color:#c8d0e0}
+.divider{border:none;border-top:1px solid var(--border);margin:44px 0}
+.toc-progress{height:2px;background:var(--accent);position:fixed;top:0;left:0;z-index:200;transition:width .1s}
+::-webkit-scrollbar{width:5px;height:5px}
+::-webkit-scrollbar-track{background:transparent}
+::-webkit-scrollbar-thumb{background:var(--border);border-radius:3px}
+/* ── Hero badges ── */
+.hero{background:linear-gradient(135deg,rgba(108,140,255,.12) 0%,rgba(167,139,250,.08) 100%);border:1px solid var(--border);border-radius:var(--radius);padding:28px 32px;margin-bottom:24px}
+.hero .sub{color:var(--muted);font-size:15px;margin-top:6px}
+.badges{display:flex;gap:7px;flex-wrap:wrap;margin-top:14px}
+.badge{font-size:10.5px;font-weight:600;padding:3px 9px;border-radius:20px;border:1px solid}
+.badge.blue{color:var(--accent);border-color:rgba(108,140,255,.4);background:rgba(108,140,255,.1)}
+.badge.purple{color:var(--accent2);border-color:rgba(167,139,250,.4);background:rgba(167,139,250,.1)}
+.badge.green{color:var(--green);border-color:rgba(52,211,153,.4);background:rgba(52,211,153,.1)}
+.badge.orange{color:var(--yellow);border-color:rgba(251,191,36,.4);background:rgba(251,191,36,.1)}
+</style>
+</head>
+<body>
+<div class="toc-progress" id="prog"></div>
+<!-- ══ SIDEBAR ══════════════════════════════════════════════════════════ -->
+<nav>
+  <div class="logo">
+    <h2>@antzsoft/chat-core</h2>
+    <p id="nav-platform-label">Integration Guide</p>
+  </div>
+  <div class="section-label">Getting Started</div>
+  <ul>
+    <li><a href="#overview">Overview</a></li>
+    <li><a href="#install">Installation</a></li>
+    <li><a href="#lifecycle">Lifecycle Map</a></li>
+  </ul>
+  <div class="section-label">Setup</div>
+  <ul>
+    <li><a href="#step1">1. Create the Client</a></li>
+  </ul>
+  <div class="section-label">Auth &amp; Connection</div>
+  <ul>
+    <li data-nav="builtin"><a href="#step-auth-builtin">2. Login / Register</a></li>
+    <li data-nav="external"><a href="#step-auth-external">2. Connect Auth</a></li>
+    <li><a href="#step-socket">3. Connect Socket</a></li>
+    <li><a href="#step-status">4. Socket Status</a></li>
+    <li><a href="#step-disconnect">5. Disconnect</a></li>
+  </ul>
+  <div class="section-label">Conversations</div>
+  <ul>
+    <li><a href="#step-convs">6. Conversations</a></li>
+    <li><a href="#step-rooms">7. Join &amp; Leave Room</a></li>
+  </ul>
+  <div class="section-label">Messaging</div>
+  <ul>
+    <li><a href="#step-load">8. Load Messages</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>
+    <li><a href="#step-read">12. Read Receipts &amp; Last Seen</a></li>
+    <li><a href="#step-edit">13. Edit &amp; Delete</a></li>
+    <li><a href="#step-search">14. Search Messages</a></li>
+    <li><a href="#step-reactions">15. Reactions, Pin, Star</a></li>
+  </ul>
+  <div class="section-label">Files &amp; Advanced</div>
+  <ul>
+    <li><a href="#step-upload">16. Upload Files</a></li>
+    <li data-nav="rn-web"><a href="#step-push">17. Push Notifications</a></li>
+    <li><a href="#step-prefs">17.5 Notification Preferences</a></li>
+    <li><a href="#step-example">18. Full Example</a></li>
+    <li><a href="#step-unread">19. Unread Counts</a></li>
+  </ul>
+</nav>
+<!-- ══ MAIN ═════════════════════════════════════════════════════════════ -->
+<main>
+<!-- Hero -->
+<div class="hero">
+  <h1><span>@antzsoft/chat-core</span></h1>
+  <p class="sub">Integration guide — React Native · React / Next.js · Node.js</p>
+  <div class="badges">
+    <span class="badge blue">TypeScript</span>
+    <span class="badge purple">Socket.IO</span>
+    <span class="badge green">React Native</span>
+    <span class="badge blue">React / Next.js</span>
+    <span class="badge orange">Node.js</span>
+  </div>
+</div>
+<!-- Platform Switcher -->
+<div class="platform-bar" id="platform-bar">
+  <button class="platform-btn active" data-platform="rn" onclick="setPlatform('rn')">
+    <span class="icon">📱</span>React Native
+  </button>
+  <button class="platform-btn" data-platform="web" onclick="setPlatform('web')">
+    <span class="icon">🌐</span>React / Next.js
+  </button>
+  <button class="platform-btn" data-platform="node" onclick="setPlatform('node')">
+    <span class="icon">⚙️</span>Node.js
+  </button>
+</div>
+<!-- ─── OVERVIEW ──────────────────────────────────────────────────────── -->
+<section id="overview">
+  <h2>Overview</h2>
+  <p><code>@antzsoft/chat-core</code> is a platform-agnostic headless SDK — no UI, just the API, socket, auth, and state. You build the UI on top.</p>
+  <table>
+    <thead><tr><th>Layer</th><th>What it gives you</th><th>Import</th></tr></thead>
+    <tbody>
+      <tr><td><strong>Client</strong></td><td>Create once, reuse everywhere</td><td><code>AntzChatClient</code></td></tr>
+      <tr>
+        <td><strong>API modules</strong></td>
+        <td>
+          <span data-pm="rn-builtin web-builtin node-builtin"><code>authApi</code>, <code>messagesApi</code>, <code>conversationsApi</code>, <code>usersApi</code>, <code>storageApi</code>, <code>devicesApi</code></span>
+          <span data-pm="rn-external web-external node-external"><code>messagesApi</code>, <code>conversationsApi</code>, <code>usersApi</code>, <code>storageApi</code>, <code>devicesApi</code> — <code>authApi</code> not used (your auth system handles login)</span>
+        </td>
+        <td>named exports</td>
+      </tr>
+      <tr><td><strong>Socket layer</strong></td><td><code>connectSocket</code>, <code>socketEmit</code>, <code>onSocketStatus</code>, raw events</td><td>named exports</td></tr>
+    </tbody>
+  </table>
+</section>
+<!-- ─── INSTALL ───────────────────────────────────────────────────────── -->
+<section id="install">
+  <h2>Installation</h2>
+  <pre><code>npm install @antzsoft/chat-core</code></pre>
+  <p><code>axios</code>, <code>socket.io-client</code>, and <code>zustand</code> are bundled — npm installs them automatically.</p>
+  <!-- RN extra -->
+  <div data-p="rn">
+    <p>On React Native you also need the storage adapter (requires native linking):</p>
+    <pre><code><span class="cm"># Expo</span>
+npx expo install @react-native-async-storage/async-storage
+<span class="cm"># Bare React Native</span>
+npm install @react-native-async-storage/async-storage
+npx pod-install</code></pre>
+    <div class="callout info">
+      <strong>Why separately?</strong>
+      <code>AsyncStorage</code> contains native iOS/Android code compiled into your app binary — it can't be pre-bundled inside an npm package. The SDK accepts any storage object so it stays platform-agnostic.
+    </div>
+  </div>
+  <!-- Web extra -->
+  <div data-p="web">
+    <p>No extra packages needed. The SDK uses <code>localStorage</code> for persistence on web — it's available natively in all browsers.</p>
+  </div>
+  <!-- Node extra -->
+  <div data-p="node">
+    <p>No extra packages needed. Pass an in-memory store or a file-backed adapter for <code>persistStorage</code>.</p>
+  </div>
+</section>
+<!-- ─── AUTH MODES ────────────────────────────────────────────────────── -->
+<section id="lifecycle">
+  <h2>Auth Mode &amp; Lifecycle</h2>
+  <p>Pick your auth mode first — it affects client setup and Step 2. Everything from Step 3 (Connect Socket) is identical across modes.</p>
+  <!-- Mode switcher -->
+  <div class="mode-bar">
+    <div class="ml">Choose your auth mode</div>
+    <div class="mode-opts">
+      <div class="mode-opt sel" onclick="setMode('builtin')">
+        <div class="mt"><span class="dot"></span> Built-in Auth</div>
+        <div class="md">Antz Chat server handles login. Use <code>authApi.login()</code>.</div>
+      </div>
+      <div class="mode-opt" onclick="setMode('external')">
+        <div class="mt"><span class="dot"></span> External Auth</div>
+        <div class="md">Firebase, Auth0, your own backend. You provide the token.</div>
+      </div>
+    </div>
+    <div class="mode-note"><strong>Steps 3–18 are identical for both modes.</strong> Only client config and Step 2 differ.</div>
+  </div>
+  <h3>Lifecycle — <span data-m="builtin">Built-in Auth</span><span data-m="external">External Auth</span></h3>
+  <div data-m="builtin">
+    <div class="flow">
+      <div class="flow-step"><span class="num">1</span><span class="label">Create Client</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">2</span><span class="label">authApi.login()</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">3</span><span class="label">Connect Socket</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">4</span><span class="label">Join Room</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">5</span><span class="label">Send / Receive</span></div>
+    </div>
+    <div class="flow" style="margin-top:6px">
+      <div class="flow-step"><span class="num">↓</span><span class="label">Leave Room</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">↓</span><span class="label">Disconnect</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">↓</span><span class="label">authApi.logout()</span></div>
+    </div>
+  </div>
+  <div data-m="external">
+    <div class="flow">
+      <div class="flow-step"><span class="num">1</span><span class="label">Create Client<br/><small style="color:var(--muted);font-weight:400">with authProvider</small></span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">2</span><span class="label">Your login<br/><small style="color:var(--muted);font-weight:400">store token</small></span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">3</span><span class="label">Connect Socket</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">4</span><span class="label">Join Room</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">5</span><span class="label">Send / Receive</span></div>
+    </div>
+    <div class="flow" style="margin-top:6px">
+      <div class="flow-step"><span class="num">↓</span><span class="label">Leave Room</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">↓</span><span class="label">Disconnect</span></div><div class="flow-arrow">→</div>
+      <div class="flow-step"><span class="num">↓</span><span class="label">Your logout</span></div>
+    </div>
+  </div>
+</section>
+<hr class="divider"/>
+<!-- ─── STEP 1: CREATE CLIENT ─────────────────────────────────────────── -->
+<section id="step1">
+  <h2><span class="step">STEP 1</span> Create the Client</h2>
+  <p>Create <strong>one</strong> <code>AntzChatClient</code> instance for the lifetime of your app — module level, outside any component or request handler.</p>
+  <!-- persistStorage explainer -->
+  <h3>persistStorage — why you provide it</h3>
+  <p>The SDK stores auth tokens across restarts. It can't pick storage itself (runs on RN, web, and Node), so you pass whichever adapter fits your platform.</p>
+  <div data-p="rn">
+    <pre><code><span class="cm">// AsyncStorage already matches the PersistStorage interface — pass directly</span>
+<span class="kw">import</span> AsyncStorage <span class="kw">from</span> <span class="str">'@react-native-async-storage/async-storage'</span>;
+<span class="at">persistStorage</span>: AsyncStorage</code></pre>
+  </div>
+  <div data-p="web">
+    <pre><code><span class="cm">// Use localStorage — it already matches PersistStorage</span>
+<span class="at">persistStorage</span>: localStorage</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="cm">// In-memory store for Node.js (tokens lost on restart)</span>
+<span class="kw">const</span> _store: Record&lt;<span class="tp">string</span>, <span class="tp">string</span>&gt; = {};
+<span class="kw">const</span> <span class="at">memStorage</span> = {
+  <span class="fn">getItem</span>: (key: <span class="tp">string</span>) => _store[key] ?? <span class="kw">null</span>,
+  <span class="fn">setItem</span>: (key: <span class="tp">string</span>, val: <span class="tp">string</span>) => { _store[key] = val; },
+  <span class="fn">removeItem</span>: (key: <span class="tp">string</span>) => { <span class="kw">delete</span> _store[key]; },
+};</code></pre>
+  </div>
+  <!-- platformUploadFn explainer -->
+  <h3>platformUploadFn — why you provide it</h3>
+  <p>The SDK orchestrates file uploads (presigned URL → binary upload → confirm) but the binary upload step differs per platform. You provide the function; the SDK calls it.</p>
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { <span class="tp">PlatformUploadFn</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">export const</span> <span class="at">rnUploadFn</span>: <span class="tp">PlatformUploadFn</span> = <span class="kw">async</span> (presigned, file, onProgress) => {
+  <span class="kw">let</span> body: <span class="tp">Blob</span> | <span class="tp">FormData</span>;
+  <span class="kw">if</span> (presigned.method === <span class="str">'PUT'</span>) {
+    <span class="kw">const</span> res = <span class="kw">await</span> <span class="fn">fetch</span>(file.uri);
+    body = <span class="kw">await</span> res.<span class="fn">blob</span>();
+  } <span class="kw">else</span> {
+    <span class="kw">const</span> form = <span class="kw">new</span> <span class="fn">FormData</span>();
+    <span class="kw">if</span> (presigned.fields) Object.<span class="fn">entries</span>(presigned.fields).<span class="fn">forEach</span>(([k,v]) => form.<span class="fn">append</span>(k,v <span class="kw">as</span> <span class="tp">string</span>));
+    form.<span class="fn">append</span>(<span class="str">'file'</span>, { <span class="at">uri</span>: file.uri, <span class="at">type</span>: file.type, <span class="at">name</span>: file.name } <span class="kw">as any</span>);
+    body = form;
+  }
+  <span class="kw">await</span> <span class="fn">fetch</span>(presigned.uploadUrl, { <span class="at">method</span>: presigned.method, <span class="at">headers</span>: presigned.headers, body });
+  onProgress?.(<span class="num">100</span>);
+};</code></pre>
+  </div>
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { <span class="tp">PlatformUploadFn</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">export const</span> <span class="at">webUploadFn</span>: <span class="tp">PlatformUploadFn</span> = (presigned, file, onProgress) =>
+  <span class="kw">new</span> <span class="fn">Promise</span>((resolve, reject) => {
+    <span class="kw">const</span> xhr = <span class="kw">new</span> <span class="fn">XMLHttpRequest</span>();
+    xhr.upload.onprogress = (e) => { <span class="kw">if</span> (e.lengthComputable) onProgress?.(Math.<span class="fn">round</span>(e.loaded/e.total*<span class="num">100</span>)); };
+    xhr.<span class="fn">open</span>(presigned.method, presigned.uploadUrl);
+    Object.<span class="fn">entries</span>(presigned.headers ?? {}).<span class="fn">forEach</span>(([k,v]) => xhr.<span class="fn">setRequestHeader</span>(k, v));
+    xhr.onload = () => xhr.status &lt; <span class="num">300</span> ? <span class="fn">resolve</span>() : <span class="fn">reject</span>(<span class="kw">new</span> <span class="fn">Error</span>(`Upload failed: ${xhr.status}`));
+    xhr.onerror = () => <span class="fn">reject</span>(<span class="kw">new</span> <span class="fn">Error</span>(<span class="str">'Upload network error'</span>));
+    <span class="kw">if</span> (presigned.method === <span class="str">'PUT'</span>) {
+      xhr.<span class="fn">send</span>(file <span class="kw">as any</span>);
+    } <span class="kw">else</span> {
+      <span class="kw">const</span> form = <span class="kw">new</span> <span class="fn">FormData</span>();
+      <span class="kw">if</span> (presigned.fields) Object.<span class="fn">entries</span>(presigned.fields).<span class="fn">forEach</span>(([k,v]) => form.<span class="fn">append</span>(k,v));
+      form.<span class="fn">append</span>(<span class="str">'file'</span>, file <span class="kw">as any</span>);
+      xhr.<span class="fn">send</span>(form);
+    }
+  });</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { createReadStream } <span class="kw">from</span> <span class="str">'fs'</span>;
+<span class="kw">import</span> { <span class="tp">PlatformUploadFn</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">export const</span> <span class="at">nodeUploadFn</span>: <span class="tp">PlatformUploadFn</span> = <span class="kw">async</span> (presigned, file, onProgress) => {
+  <span class="kw">const</span> res = <span class="kw">await</span> <span class="fn">fetch</span>(presigned.uploadUrl, {
+    <span class="at">method</span>: presigned.method,
+    <span class="at">headers</span>: { <span class="str">'Content-Type'</span>: file.type, ...presigned.headers },
+    <span class="at">body</span>: <span class="fn">createReadStream</span>(file.uri) <span class="kw">as any</span>,
+  });
+  <span class="kw">if</span> (!res.ok) <span class="kw">throw new</span> <span class="fn">Error</span>(`Upload failed: ${res.status}`);
+  onProgress?.(<span class="num">100</span>);
+};</code></pre>
+  </div>
+  <!-- Client config -->
+  <div data-m="builtin">
+    <h3>Client config — Built-in Auth</h3>
+    <div data-p="rn">
+      <pre><code><span class="cm">// src/chat/client.ts</span>
+<span class="kw">import</span> { <span class="tp">AntzChatClient</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> AsyncStorage <span class="kw">from</span> <span class="str">'@react-native-async-storage/async-storage'</span>;
+<span class="kw">import</span> { rnUploadFn } <span class="kw">from</span> <span class="str">'./rnUploadFn'</span>;
+<span class="kw">export const</span> <span class="at">chatClient</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.your-server.com/chat-api/api/v1'</span>,
+  <span class="at">tenantId</span>: <span class="str">'your-tenant-id'</span>,
+  <span class="at">persistStorage</span>: AsyncStorage,
+  <span class="at">platformUploadFn</span>: rnUploadFn,
+});</code></pre>
+    </div>
+    <div data-p="web">
+      <pre><code><span class="cm">// src/chat/client.ts</span>
+<span class="kw">import</span> { <span class="tp">AntzChatClient</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { webUploadFn } <span class="kw">from</span> <span class="str">'./webUploadFn'</span>;
+<span class="kw">export const</span> <span class="at">chatClient</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.your-server.com/chat-api/api/v1'</span>,
+  <span class="at">tenantId</span>: <span class="str">'your-tenant-id'</span>,
+  <span class="at">persistStorage</span>: localStorage,
+  <span class="at">platformUploadFn</span>: webUploadFn,
+});</code></pre>
+    </div>
+    <div data-p="node">
+      <pre><code><span class="kw">import</span> { <span class="tp">AntzChatClient</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { nodeUploadFn, memStorage } <span class="kw">from</span> <span class="str">'./nodeAdapters'</span>;
+<span class="kw">export const</span> <span class="at">chatClient</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.your-server.com/chat-api/api/v1'</span>,
+  <span class="at">tenantId</span>: <span class="str">'your-tenant-id'</span>,
+  <span class="at">persistStorage</span>: memStorage,
+  <span class="at">platformUploadFn</span>: nodeUploadFn,
+});</code></pre>
+    </div>
+  </div>
+  <div data-m="external">
+    <h3>Client config — External Auth</h3>
+    <div data-p="rn">
+      <pre><code><span class="kw">import</span> { <span class="tp">AntzChatClient</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> AsyncStorage <span class="kw">from</span> <span class="str">'@react-native-async-storage/async-storage'</span>;
+<span class="kw">import</span> { rnUploadFn } <span class="kw">from</span> <span class="str">'./rnUploadFn'</span>;
+<span class="kw">export const</span> <span class="at">chatClient</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.your-server.com/chat-api/api/v1'</span>,
+  <span class="at">tenantId</span>: <span class="str">'your-tenant-id'</span>,
+  <span class="at">userId</span>: <span class="str">'external-user-id'</span>,
+  <span class="at">persistStorage</span>: AsyncStorage,
+  <span class="at">platformUploadFn</span>: rnUploadFn,
+  <span class="cm">// Called every time SDK needs a token. Always read from storage — never hardcode.</span>
+  <span class="at">authProvider</span>: <span class="kw">async</span> () => AsyncStorage.<span class="fn">getItem</span>(<span class="str">'access_token'</span>),
+  <span class="at">avatar</span>: { <span class="at">url</span>: <span class="str">'https://cdn.example.com/avatar.jpg'</span> }, <span class="cm">// or { base64: '...' }</span>
+});</code></pre>
+    </div>
+    <div data-p="web">
+      <pre><code><span class="kw">import</span> { <span class="tp">AntzChatClient</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { webUploadFn } <span class="kw">from</span> <span class="str">'./webUploadFn'</span>;
+<span class="kw">export const</span> <span class="at">chatClient</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.your-server.com/chat-api/api/v1'</span>,
+  <span class="at">tenantId</span>: <span class="str">'your-tenant-id'</span>,
+  <span class="at">userId</span>: <span class="str">'external-user-id'</span>,
+  <span class="at">persistStorage</span>: localStorage,
+  <span class="at">platformUploadFn</span>: webUploadFn,
+  <span class="at">authProvider</span>: <span class="kw">async</span> () => localStorage.<span class="fn">getItem</span>(<span class="str">'access_token'</span>),
+  <span class="cm">// Avatar — pass url OR base64, not both</span>
+  <span class="at">avatar</span>: { <span class="at">url</span>: <span class="str">'https://cdn.example.com/avatar.jpg'</span> },
+  <span class="cm">// avatar: { base64: 'data:image/png;base64,iVBORw0K...' },</span>
+});</code></pre>
+    </div>
+    <div data-p="node">
+      <pre><code><span class="kw">import</span> { <span class="tp">AntzChatClient</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { nodeUploadFn, memStorage } <span class="kw">from</span> <span class="str">'./nodeAdapters'</span>;
+<span class="kw">let</span> <span class="at">_token</span> = <span class="str">''</span>;
+<span class="kw">export const</span> <span class="fn">setToken</span> = (t: <span class="tp">string</span>) => { _token = t; };
+<span class="kw">export const</span> <span class="at">chatClient</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.your-server.com/chat-api/api/v1'</span>,
+  <span class="at">tenantId</span>: <span class="str">'your-tenant-id'</span>,
+  <span class="at">userId</span>: <span class="str">'external-user-id'</span>,
+  <span class="at">persistStorage</span>: memStorage,
+  <span class="at">platformUploadFn</span>: nodeUploadFn,
+  <span class="at">authProvider</span>: <span class="kw">async</span> () => _token,
+  <span class="cm">// Avatar — pass url OR base64, not both</span>
+  <span class="at">avatar</span>: { <span class="at">url</span>: <span class="str">'https://cdn.example.com/avatar.jpg'</span> },
+  <span class="cm">// avatar: { base64: 'data:image/png;base64,iVBORw0K...' },</span>
+});</code></pre>
+    </div>
+    <div class="callout warn">
+      <strong>authProvider vs authToken</strong>
+      Always use <code>authProvider</code> for real apps. <code>authToken</code> is a static string — once set, the SDK cannot refresh it when it expires. <code>authProvider</code> is called on every connect, so your storage always delivers the latest token.
+    </div>
+  </div>
+  <h3>Full config reference</h3>
+  <table>
+    <thead><tr><th>Option</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td><code>apiUrl</code></td><td><code>string</code></td><td>Yes</td><td>Full REST API base URL including <code>/api/v1</code></td></tr>
+      <tr><td><code>socketUrl</code></td><td><code>string</code></td><td>No</td><td>Auto-derived from <code>apiUrl</code> by stripping <code>/api/v1</code></td></tr>
+      <tr><td><code>tenantId</code></td><td><code>string</code></td><td>Yes</td><td>Sent as <code>X-Tenant-ID</code> on every request and socket handshake</td></tr>
+      <tr><td><code>persistStorage</code></td><td><code>PersistStorage</code></td><td>Yes</td><td>AsyncStorage (RN) · localStorage (web) · custom (Node)</td></tr>
+      <tr><td><code>platformUploadFn</code></td><td><code>PlatformUploadFn</code></td><td>Yes</td><td>Binary uploader — fetch/XHR/stream depending on platform</td></tr>
+      <tr><td><code>authProvider</code></td><td><code>() =&gt; Promise&lt;string&gt;</code></td><td>External auth</td><td>Token getter called on every connect/reconnect</td></tr>
+      <tr><td><code>userId</code></td><td><code>string</code></td><td>External auth</td><td>Your system's user ID</td></tr>
+      <tr><td><code>avatar.url</code></td><td><code>string</code></td><td>No</td><td>Avatar URL — pass <code>url</code> OR <code>base64</code>, not both</td></tr>
+      <tr><td><code>avatar.base64</code></td><td><code>string</code></td><td>No</td><td>Raw base64 avatar string</td></tr>
+      <tr><td><code>encryptionMode</code></td><td><code>'none'|'server'</code></td><td>No</td><td>Defaults to <code>'none'</code></td></tr>
+      <tr><td><code>upload</code></td><td><code>UploadConfig</code></td><td>No</td><td>File size limits, allowed types, progress callback</td></tr>
+    </tbody>
+  </table>
+  <h3>Avatar</h3>
+  <p>There are three ways to set or update a user's avatar. All methods store the image in the chat server's own storage (local/S3/Azure) with SHA-256 hash deduplication — re-uploading the same image is always a no-op.</p>
+  <table>
+    <thead><tr><th>Method</th><th>When to use</th></tr></thead>
+    <tbody>
+      <tr><td><code>AntzChatConfig.avatar</code></td><td>Avatar known at init time and won't change during the session</td></tr>
+      <tr><td><code>client.auth.syncAvatar({ url })</code></td><td>Avatar URL changes after init (e.g. user updates profile in your external system) — works in any auth mode</td></tr>
+      <tr><td><code>client.auth.uploadAvatar(file)</code></td><td>User picks a file from their device — builtin auth mode only</td></tr>
+    </tbody>
+  </table>
+  <h4>1. Config — on init</h4>
+  <pre><code><span class="kw">const</span> <span class="at">client</span> = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="cm">// ... other options</span>
+  <span class="at">avatar</span>: { <span class="at">url</span>: <span class="str">'https://cdn.example.com/avatar.jpg'</span> },
+  <span class="cm">// OR: avatar: { base64: 'data:image/jpeg;base64,...' },</span>
+});</code></pre>
+  <h4>2. <code>syncAvatar()</code> — post-init update (any mode)</h4>
+  <p>Call any time after init when the avatar changes. The return value is the new signed URL for the stored image.</p>
+  <pre><code><span class="cm">// From a URL</span>
+<span class="kw">const</span> { <span class="at">avatarUrl</span> } = <span class="kw">await</span> client.auth.<span class="fn">syncAvatar</span>({ <span class="at">url</span>: <span class="str">'https://cdn.example.com/new-avatar.jpg'</span> });
+<span class="cm">// From base64</span>
+<span class="kw">const</span> { <span class="at">avatarUrl</span> } = <span class="kw">await</span> client.auth.<span class="fn">syncAvatar</span>({ <span class="at">base64</span>: <span class="str">'data:image/jpeg;base64,...'</span> });</code></pre>
+  <h4>3. <code>uploadAvatar()</code> — file upload (builtin mode only)</h4>
+  <pre><code><span class="kw">const</span> <span class="at">file</span> = input.files[<span class="num">0</span>]; <span class="cm">// File from &lt;input type="file"&gt;</span>
+<span class="kw">const</span> { <span class="at">avatarUrl</span> } = <span class="kw">await</span> client.auth.<span class="fn">uploadAvatar</span>(file);</code></pre>
+  <p>Supported formats: JPEG, PNG, GIF, WebP. Default max size: <strong>5 MB</strong> (configurable via <code>AVATAR_MAX_SIZE</code> env var on the server).</p>
+</section>
+<hr class="divider"/>
+<!-- ─── STEP 2: AUTH ───────────────────────────────────────────────────── -->
+<section id="step-auth-builtin" data-m="builtin">
+  <h2><span class="step">STEP 2</span> Login / Register</h2>
+  <p>Call <code>authApi.login()</code> — the SDK authenticates and stores tokens automatically. Then call <code>chatClient.connect()</code>.</p>
+  <h3>Login</h3>
+  <pre><code><span class="kw">import</span> { authApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { chatClient } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">async function</span> <span class="fn">login</span>(email: <span class="tp">string</span>, password: <span class="tp">string</span>) {
+  <span class="kw">const</span> { user, tokens } = <span class="kw">await</span> authApi.<span class="fn">login</span>({ email, password });
+  <span class="cm">// Tokens stored automatically. Save user to your own app state.</span>
+  yourAppState.<span class="fn">setUser</span>(user);
+  <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+}</code></pre>
+  <h3>Register</h3>
+  <pre><code><span class="kw">const</span> { user } = <span class="kw">await</span> authApi.<span class="fn">register</span>({
+  <span class="at">email</span>: <span class="str">'user@example.com'</span>, <span class="at">password</span>: <span class="str">'secret'</span>,
+  <span class="at">username</span>: <span class="str">'johndoe'</span>, <span class="at">firstName</span>: <span class="str">'John'</span>, <span class="at">lastName</span>: <span class="str">'Doe'</span>,
+});</code></pre>
+  <h3>Logout</h3>
+  <pre><code><span class="kw">import</span> { chatClient } <span class="kw">from</span> <span class="str">'./client'</span>;
+chatClient.<span class="fn">disconnect</span>();                      <span class="cm">// socket first</span>
+<span class="kw">await</span> authApi.<span class="fn">logout</span>(tokens.refreshToken);   <span class="cm">// then invalidate session</span>
+<span class="cm">// or authApi.logoutAll() — all devices</span></code></pre>
+</section>
+<section id="step-auth-external" data-m="external">
+  <h2><span class="step">STEP 2</span> Connect Your Auth</h2>
+  <p>You handle login. Store the token first, then call <code>chatClient.connect()</code>. The SDK reads it via <code>authProvider</code>.</p>
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> AsyncStorage <span class="kw">from</span> <span class="str">'@react-native-async-storage/async-storage'</span>;
+<span class="kw">import</span> { chatClient } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">async function</span> <span class="fn">login</span>(email: <span class="tp">string</span>, password: <span class="tp">string</span>) {
+  <span class="kw">const</span> token = <span class="kw">await</span> yourAuthSystem.<span class="fn">signIn</span>(email, password);
+  <span class="kw">await</span> AsyncStorage.<span class="fn">setItem</span>(<span class="str">'access_token'</span>, token);
+  <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+}
+<span class="cm">// Logout</span>
+chatClient.<span class="fn">disconnect</span>();
+<span class="kw">await</span> AsyncStorage.<span class="fn">removeItem</span>(<span class="str">'access_token'</span>);</code></pre>
+  </div>
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { chatClient } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">async function</span> <span class="fn">login</span>(email: <span class="tp">string</span>, password: <span class="tp">string</span>) {
+  <span class="kw">const</span> token = <span class="kw">await</span> yourAuthSystem.<span class="fn">signIn</span>(email, password);
+  localStorage.<span class="fn">setItem</span>(<span class="str">'access_token'</span>, token);
+  <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+}
+<span class="cm">// Logout</span>
+chatClient.<span class="fn">disconnect</span>();
+localStorage.<span class="fn">removeItem</span>(<span class="str">'access_token'</span>);</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { chatClient, setToken } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">async function</span> <span class="fn">init</span>(token: <span class="tp">string</span>) {
+  <span class="fn">setToken</span>(token);         <span class="cm">// authProvider reads this</span>
+  <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+}</code></pre>
+  </div>
+</section>
+<!-- ─── STEP 3: SOCKET ─────────────────────────────────────────────────── -->
+<section id="step-socket">
+  <h2><span class="step">STEP 3</span> Connect the Socket</h2>
+  <p><code>chatClient.connect()</code> handles everything — it reads the token via <code>authProvider</code> and opens the socket. No need to pass the token again.</p>
+  <!-- RN: root provider with AppState -->
+  <div data-p="rn">
+    <h3>Root provider — session restore + foreground handling</h3>
+    <p>Tokens are 15 minutes. Always refresh before reconnecting on foreground.</p>
+    <pre><code><span class="kw">import</span> React, { useEffect } <span class="kw">from</span> <span class="str">'react'</span>;
+<span class="kw">import</span> { AppState } <span class="kw">from</span> <span class="str">'react-native'</span>;
+<span class="kw">import</span> AsyncStorage <span class="kw">from</span> <span class="str">'@react-native-async-storage/async-storage'</span>;
+<span class="kw">import</span> { refreshSocketAuth, onSocketStatus } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { chatClient } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">export function</span> <span class="fn">ChatProvider</span>({ children }: { children: React.ReactNode }) {
+  <span class="fn">useEffect</span>(() => {
+    <span class="kw">let</span> unsub: (() => <span class="tp">void</span>) | <span class="tp">undefined</span>;
+    <span class="kw">async function</span> <span class="fn">init</span>() {
+      <span class="kw">const</span> token = <span class="kw">await</span> AsyncStorage.<span class="fn">getItem</span>(<span class="str">'access_token'</span>);
+      <span class="kw">if</span> (!token) <span class="kw">return</span>;
+      <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+      unsub = <span class="fn">onSocketStatus</span>(s => console.<span class="fn">log</span>(<span class="str">'socket:'</span>, s));
+    }
+    <span class="kw">async function</span> <span class="fn">onForeground</span>() {
+      <span class="kw">try</span> {
+        <span class="kw">const</span> newToken = <span class="kw">await</span> yourAuthSystem.<span class="fn">refreshToken</span>();
+        <span class="kw">await</span> AsyncStorage.<span class="fn">setItem</span>(<span class="str">'access_token'</span>, newToken);
+        <span class="fn">refreshSocketAuth</span>(); <span class="cm">// re-reads authProvider → updates socket.auth</span>
+        chatClient.<span class="fn">connect</span>();
+      } <span class="kw">catch</span> { <span class="cm">/* token refresh failed — user needs to re-login */</span> }
+    }
+    <span class="kw">const</span> sub = AppState.<span class="fn">addEventListener</span>(<span class="str">'change'</span>, s => {
+      <span class="kw">if</span> (s === <span class="str">'background'</span>) chatClient.<span class="fn">disconnect</span>();
+      <span class="kw">if</span> (s === <span class="str">'active'</span>)     <span class="fn">onForeground</span>();
+    });
+    <span class="fn">init</span>();
+    <span class="kw">return</span> () => { unsub?.(); sub.<span class="fn">remove</span>(); };
+  }, []);
+  <span class="kw">return</span> &lt;&gt;{children}&lt;/&gt;;
+}</code></pre>
+  </div>
+  <!-- Web: visibility + localStorage -->
+  <div data-p="web">
+    <h3>Root provider — session restore + tab visibility</h3>
+    <pre><code><span class="kw">import</span> { useEffect } <span class="kw">from</span> <span class="str">'react'</span>;
+<span class="kw">import</span> { refreshSocketAuth, onSocketStatus } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { chatClient } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">export function</span> <span class="fn">ChatProvider</span>({ children }: { children: React.ReactNode }) {
+  <span class="fn">useEffect</span>(() => {
+    <span class="kw">const</span> token = localStorage.<span class="fn">getItem</span>(<span class="str">'access_token'</span>);
+    <span class="kw">if</span> (token) chatClient.<span class="fn">connect</span>();
+    <span class="kw">const</span> <span class="fn">onVisibility</span> = <span class="kw">async</span> () => {
+      <span class="kw">if</span> (document.visibilityState === <span class="str">'hidden'</span>) { chatClient.<span class="fn">disconnect</span>(); <span class="kw">return</span>; }
+      <span class="kw">try</span> {
+        <span class="kw">const</span> newToken = <span class="kw">await</span> yourAuthSystem.<span class="fn">refreshToken</span>();
+        localStorage.<span class="fn">setItem</span>(<span class="str">'access_token'</span>, newToken);
+        <span class="fn">refreshSocketAuth</span>();
+        chatClient.<span class="fn">connect</span>();
+      } <span class="kw">catch</span> {}
+    };
+    document.<span class="fn">addEventListener</span>(<span class="str">'visibilitychange'</span>, onVisibility);
+    <span class="kw">const</span> unsub = <span class="fn">onSocketStatus</span>(s => console.<span class="fn">log</span>(<span class="str">'socket:'</span>, s));
+    <span class="kw">return</span> () => { document.<span class="fn">removeEventListener</span>(<span class="str">'visibilitychange'</span>, onVisibility); unsub(); };
+  }, []);
+  <span class="kw">return</span> &lt;&gt;{children}&lt;/&gt;;
+}</code></pre>
+  </div>
+  <!-- Node.js: simple connect -->
+  <div data-p="node">
+    <h3>Connect in your server startup</h3>
+    <pre><code><span class="kw">import</span> { chatClient, setToken } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">async function</span> <span class="fn">bootstrap</span>() {
+  <span class="fn">setToken</span>(process.env.CHAT_TOKEN!);
+  <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+  console.<span class="fn">log</span>(<span class="str">'Chat socket connected'</span>);
+}</code></pre>
+    <div class="callout info">
+      <strong>Token refresh in Node</strong> — call <code>setToken(newToken)</code> then <code>refreshSocketAuth()</code> from <code>@antzsoft/chat-core</code> whenever your token refreshes.
+    </div>
+  </div>
+  <div class="callout info">
+    <strong>Auto-reconnect is built in.</strong>
+    Network drops retry automatically (up to 10 attempts, 1–5 s backoff). Auto-reconnect reuses the token from the original connect call — it does NOT call <code>authProvider</code> again. That's why foreground needs <code>refreshSocketAuth()</code> explicitly.
+  </div>
+  <h3>Token refresh mid-session (without going to background)</h3>
+  <p>Wire this into your HTTP interceptor — wherever you refresh the access token, call <code>refreshSocketAuth()</code> immediately after updating storage.</p>
+  <pre><code><span class="kw">import</span> { refreshSocketAuth } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> newToken = <span class="kw">await</span> yourAuthSystem.<span class="fn">refreshToken</span>();
+<span class="cm">// Update storage first (authProvider reads from here)</span>
+<span class="cm">// RN: await AsyncStorage.setItem('access_token', newToken)</span>
+<span class="cm">// Web: localStorage.setItem('access_token', newToken)</span>
+<span class="fn">refreshSocketAuth</span>(); <span class="cm">// SDK re-reads authProvider → updates socket.auth in place</span></code></pre>
+</section>
+<!-- ─── STEP 4: STATUS ─────────────────────────────────────────────────── -->
+<section id="step-status">
+  <h2><span class="step">STEP 4</span> Monitor Socket Status</h2>
+  <div data-p="rn web">
+    <pre><code><span class="kw">import</span> { onSocketStatus, getSocketStatus, <span class="tp">SocketStatus</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> [status, setStatus] = <span class="fn">useState</span>&lt;<span class="tp">SocketStatus</span>&gt;(<span class="fn">getSocketStatus</span>());
+<span class="fn">useEffect</span>(() => <span class="fn">onSocketStatus</span>(setStatus), []);</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { onSocketStatus, getSocketStatus } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="fn">onSocketStatus</span>((status) => console.<span class="fn">log</span>(<span class="str">'socket:'</span>, status));
+console.<span class="fn">log</span>(<span class="fn">getSocketStatus</span>()); <span class="cm">// 'connected' | 'disconnected' | 'reconnecting' | 'error'</span></code></pre>
+  </div>
+  <table>
+    <thead><tr><th>Status</th><th>Meaning</th></tr></thead>
+    <tbody>
+      <tr><td><code>'disconnected'</code></td><td>Not connected, no active attempt</td></tr>
+      <tr><td><code>'connecting'</code></td><td>Initial connection in progress</td></tr>
+      <tr><td><code>'connected'</code></td><td>Fully connected, events flowing</td></tr>
+      <tr><td><code>'reconnecting'</code></td><td>Lost connection, retrying automatically</td></tr>
+      <tr><td><code>'error'</code></td><td>Connection rejected — check token / server</td></tr>
+    </tbody>
+  </table>
+</section>
+<!-- ─── STEP 5: DISCONNECT ────────────────────────────────────────────── -->
+<section id="step-disconnect">
+  <h2><span class="step">STEP 5</span> Disconnect</h2>
+  <p>Background/tab-hidden handling is already in <code>ChatProvider</code> above. The only other place you need to disconnect is on logout.</p>
+  <pre><code><span class="cm">// Always disconnect before clearing the session</span>
+chatClient.<span class="fn">disconnect</span>();
+<span class="cm">// then clear your token / call your auth system logout</span></code></pre>
+  <div class="callout warn">
+    <strong>Disconnect before clearing the token.</strong>
+    If you clear the token first and the socket auto-reconnects, it will reconnect with no token and get rejected by the server.
+  </div>
+</section>
+<hr class="divider"/>
+<!-- ─── STEP 6: CONVERSATIONS ─────────────────────────────────────────── -->
+<section id="step-convs">
+  <h2><span class="step">STEP 6</span> List &amp; Manage Conversations</h2>
+  <h3>Listing &amp; Filtering</h3>
+  <p><code>conversationsApi.list()</code> accepts a <code>ConversationListParams</code> object. All filters are applied server-side before pagination — totals and page counts always reflect the filtered set.</p>
+  <table>
+    <tr><th>Filter</th><th>Type</th><th>Description</th></tr>
+    <tr><td><code>page</code></td><td><code>number</code></td><td>Page number — omit (along with <code>limit</code>) to return all results</td></tr>
+    <tr><td><code>limit</code></td><td><code>number</code></td><td>Results per page — omit (along with <code>page</code>) to return all results</td></tr>
+    <tr><td><code>type</code></td><td><code>'direct' | 'group'</code></td><td>Filter by conversation type</td></tr>
+    <tr><td><code>isPinned</code></td><td><code>boolean</code></td><td><code>true</code> = only pinned, <code>false</code> = only unpinned</td></tr>
+    <tr><td><code>isMuted</code></td><td><code>boolean</code></td><td><code>true</code> = only muted, <code>false</code> = only unmuted</td></tr>
+    <tr><td><code>hasUnread</code></td><td><code>boolean</code></td><td>Only conversations with at least 1 unread message</td></tr>
+    <tr><td><code>search</code></td><td><code>string</code></td><td>Server-side text search on group name &amp; description</td></tr>
+    <tr><td><code>role</code></td><td><code>'admin' | 'member'</code></td><td>Current user's role in the conversation</td></tr>
+    <tr><td><code>hasAttachments</code></td><td><code>boolean</code></td><td>Last message has attachments</td></tr>
+    <tr><td><code>attachmentType</code></td><td><code>'image' | 'video' | 'document' | 'audio'</code></td><td>Last message attachment type</td></tr>
+    <tr><td><code>notificationsEnabled</code></td><td><code>boolean</code></td><td>Notification setting for the current user</td></tr>
+  </table>
+  <div class="callout info"><strong>Pagination is optional</strong> Omit <code>page</code> and <code>limit</code> to receive all matching conversations in one response. Pass both to opt into offset pagination. All filters run as MongoDB aggregation stages before <code>$skip</code> / <code>$limit</code> — the <code>hasUnread</code> filter uses a <code>$lookup</code> join inside the pipeline, no post-filter workarounds.</div>
+  <pre><code><span class="kw">import</span> { conversationsApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// All conversations (omit page + limit)</span>
+<span class="kw">const</span> { data } = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>();
+<span class="cm">// Paginated (opt in by passing page + limit)</span>
+<span class="kw">const</span> { data, meta } = <span class="kw">await</span> conversationsApi.<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">// Filter by type</span>
+<span class="kw">const</span> groups = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({ <span class="at">type</span>: <span class="str">'group'</span> });
+<span class="kw">const</span> dms    = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({ <span class="at">type</span>: <span class="str">'direct'</span> });
+<span class="cm">// Pinned / muted / unread</span>
+<span class="kw">const</span> pinned = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({ <span class="at">isPinned</span>: <span class="kw">true</span> });
+<span class="kw">const</span> muted  = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({ <span class="at">isMuted</span>: <span class="kw">true</span> });
+<span class="kw">const</span> unread = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({ <span class="at">hasUnread</span>: <span class="kw">true</span> });
+<span class="cm">// Text search (server-side MongoDB text index on name + description)</span>
+<span class="kw">const</span> found = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({ <span class="at">search</span>: <span class="str">'design'</span> });
+<span class="cm">// Admin-only conversations + combined filters</span>
+<span class="kw">const</span> urgent = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>({
+  <span class="at">type</span>: <span class="str">'group'</span>, <span class="at">isPinned</span>: <span class="kw">true</span>, <span class="at">hasUnread</span>: <span class="kw">true</span>,
+});
+<span class="cm">// Get single</span>
+<span class="kw">const</span> conv = <span class="kw">await</span> conversationsApi.<span class="fn">get</span>(conversationId);
+<span class="cm">// List all users (no page/limit = server returns everything)</span>
+<span class="kw">const</span> { data: users } = <span class="kw">await</span> usersApi.<span class="fn">list</span>();
+<span class="cm">// Search users by name / username / email</span>
+<span class="kw">const</span> { data: results } = <span class="kw">await</span> usersApi.<span class="fn">list</span>({ <span class="at">query</span>: <span class="str">'john'</span> });
+<span class="cm">// Create DM — returns existing if already exists</span>
+<span class="kw">const</span> dm = <span class="kw">await</span> conversationsApi.<span class="fn">createDirect</span>({ <span class="at">userId</span>: <span class="str">'target-user-id'</span> });
+<span class="cm">// Create group</span>
+<span class="kw">const</span> group = <span class="kw">await</span> conversationsApi.<span class="fn">createGroup</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">// 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>]);
+<span class="kw">await</span> conversationsApi.<span class="fn">removeParticipant</span>(conversationId, <span class="str">'user-2'</span>);
+<span class="kw">await</span> conversationsApi.<span class="fn">updateParticipantRole</span>(conversationId, <span class="str">'user-1'</span>, <span class="str">'admin'</span>);
+<span class="cm">// Pin · Mute · Leave · Delete</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">pin</span>(conversationId);
+<span class="kw">await</span> conversationsApi.<span class="fn">mute</span>(conversationId, <span class="str">'2025-12-31T23:59:59Z'</span>); <span class="cm">// omit date = indefinite</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(conversationId);
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(conversationId); <span class="cm">// admin only</span></code></pre>
+</section>
+<!-- ─── 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>
+  <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>;
+<span class="fn">useEffect</span>(() => {
+  socketEmit.<span class="fn">joinRoom</span>(conversationId);
+  <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="kw">return</span> () => { socketEmit.<span class="fn">leaveRoom</span>(conversationId); unsub(); };
+}, [conversationId]);</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>;
+socketEmit.<span class="fn">joinRoom</span>(conversationId);
+<span class="cm">// When done:</span>
+socketEmit.<span class="fn">leaveRoom</span>(conversationId);</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).
+  </div>
+</section>
+<hr class="divider"/>
+<!-- ─── 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>
+  <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="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>
+<span class="kw">const</span> { data: older } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(conversationId, {
+  <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>
+</section>
+<!-- ─── STEP 9: SEND ───────────────────────────────────────────────────── -->
+<section id="step-send">
+  <h2><span class="step">STEP 9</span> Send a Message</h2>
+  <pre><code><span class="kw">import</span> { socketEmit } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { v4 <span class="kw">as</span> uuid } <span class="kw">from</span> <span class="str">'uuid'</span>;
+<span class="cm">// Text</span>
+<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">text</span>: <span class="str">'Hello!'</span>, <span class="at">tempId</span>: <span class="fn">uuid</span>() });
+<span class="cm">// Reply</span>
+<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">text</span>: <span class="str">'Agreed'</span>, <span class="at">tempId</span>: <span class="fn">uuid</span>(), <span class="at">replyTo</span>: messageId });
+<span class="cm">// With attachments — upload first (Step 16), then send fileIds</span>
+<span class="kw">const</span> { successful } = <span class="kw">await</span> chatClient.<span class="fn">uploadFiles</span>(files, conversationId);
+<span class="kw">const</span> attachments = successful.<span class="fn">map</span>(f => ({
+  <span class="at">fileId</span>: f.id, <span class="at">type</span>: f.type, <span class="at">url</span>: f.url, <span class="at">filename</span>: f.filename, <span class="at">mimeType</span>: f.mimeType, <span class="at">size</span>: f.size,
+}));
+<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(), attachments });</code></pre>
+</section>
+<!-- ─── STEP 10: REAL-TIME ─────────────────────────────────────────────── -->
+<section id="step-realtime">
+  <h2><span class="step">STEP 10</span> Real-time Events</h2>
+  <div data-p="rn web">
+    <pre><code><span class="kw">import</span> { tryGetSocket } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="fn">useEffect</span>(() => {
+  <span class="kw">const</span> socket = <span class="fn">tryGetSocket</span>();
+  <span class="kw">if</span> (!socket) <span class="kw">return</span>;
+  <span class="kw">const</span> <span class="fn">onNew</span> = ({ message, tempId }: <span class="tp">NewMessageEvent</span>) =>
+    <span class="fn">setMessages</span>(prev => {
+      <span class="kw">const</span> idx = prev.<span class="fn">findIndex</span>(m => m.id === tempId);
+      <span class="kw">if</span> (idx !== -<span class="num">1</span>) { <span class="kw">const</span> n = [...prev]; n[idx] = message; <span class="kw">return</span> n; }
+      <span class="kw">return</span> [...prev, message];
+    });
+  <span class="kw">const</span> <span class="fn">onUpdated</span> = ({ messageId, text, editedAt }: <span class="tp">MessageUpdatedEvent</span>) =>
+    <span class="fn">setMessages</span>(prev => prev.<span class="fn">map</span>(m =>
+      m.id === messageId ? { ...m, content: { ...m.content, text }, <span class="at">isEdited</span>: <span class="kw">true</span>, editedAt } : m
+    ));
+  <span class="kw">const</span> <span class="fn">onDeleted</span> = ({ messageId }: <span class="tp">MessageDeletedEvent</span>) =>
+    <span class="fn">setMessages</span>(prev => prev.<span class="fn">filter</span>(m => m.id !== messageId));
+  socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, onNew);
+  socket.<span class="fn">on</span>(<span class="str">'message_updated'</span>, onUpdated);
+  socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, onDeleted);
+  <span class="kw">return</span> () => {
+    socket.<span class="fn">off</span>(<span class="str">'new_message'</span>, onNew);
+    socket.<span class="fn">off</span>(<span class="str">'message_updated'</span>, onUpdated);
+    socket.<span class="fn">off</span>(<span class="str">'message_deleted'</span>, onDeleted);
+  };
+}, [conversationId]);</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { getSocket } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> socket = <span class="fn">getSocket</span>();
+socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, ({ message }) => console.<span class="fn">log</span>(<span class="str">'new:'</span>, message));
+socket.<span class="fn">on</span>(<span class="str">'message_updated'</span>, (e) => console.<span class="fn">log</span>(<span class="str">'updated:'</span>, e));
+socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, (e) => console.<span class="fn">log</span>(<span class="str">'deleted:'</span>, e));</code></pre>
+  </div>
+  <h4>All socket events</h4>
+  <table>
+    <thead><tr><th>Event</th><th>When fired</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>
+    </tbody>
+  </table>
+</section>
+<!-- ─── STEP 11: TYPING ───────────────────────────────────────────────── -->
+<section id="step-typing">
+  <h2><span class="step">STEP 11</span> Typing Indicators</h2>
+  <div data-p="rn web">
+    <pre><code><span class="kw">const</span> timer = <span class="fn">useRef</span>&lt;<span class="tp">ReturnType</span>&lt;<span class="kw">typeof</span> setTimeout&gt;&gt;();
+<span class="kw">function</span> <span class="fn">onChangeText</span>(val: <span class="tp">string</span>) {
+  <span class="fn">setValue</span>(val);
+  socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">true</span>);
+  <span class="fn">clearTimeout</span>(timer.current);
+  timer.current = <span class="fn">setTimeout</span>(() => socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">false</span>), <span class="num">3000</span>);
+}
+<span class="cm">// Listen for others typing</span>
+socket.<span class="fn">on</span>(<span class="str">'typing'</span>, ({ conversationId, userId, displayName, isTyping }) => {
+  isTyping ? <span class="fn">addTypingUser</span>(conversationId, { userId, displayName })
+           : <span class="fn">removeTypingUser</span>(conversationId, userId);
+});</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code>socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">true</span>);
+<span class="kw">setTimeout</span>(() => socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">false</span>), <span class="num">3000</span>);</code></pre>
+  </div>
+</section>
+<!-- ─── STEP 12: READ RECEIPTS & LAST SEEN ────────────────────────────── -->
+<section id="step-read">
+  <h2><span class="step">STEP 12</span> Read Receipts &amp; Last Seen</h2>
+  <p>There are three related concepts here:</p>
+  <table>
+    <thead><tr><th>Concept</th><th>What it is</th><th>Where it lives</th></tr></thead>
+    <tbody>
+      <tr><td><strong>Mark as read</strong></td><td>Tell the server the current user has read messages</td><td><code>socketEmit.markRead()</code></td></tr>
+      <tr><td><strong>Last-read pointer</strong></td><td>Which message the current user last read in a conversation</td><td><code>useChatStore.lastRead[conversationId]</code></td></tr>
+      <tr><td><strong>Last seen</strong></td><td>When another user was last online</td><td><code>useChatStore.lastSeen[userId]</code></td></tr>
+    </tbody>
+  </table>
+  <h3>Marking as read</h3>
+  <p>Call this when the user opens or focuses a conversation. The server broadcasts a <code>read_receipt</code> event to all participants so their UIs can update.</p>
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { useFocusEffect } <span class="kw">from</span> <span class="str">'@react-navigation/native'</span>;
+<span class="kw">import</span> { socketEmit } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Mark the whole conversation read every time this screen comes into focus</span>
+<span class="fn">useFocusEffect</span>(<span class="fn">useCallback</span>(() => {
+  socketEmit.<span class="fn">markRead</span>(conversationId);
+}, [conversationId]));
+<span class="cm">// Mark up to a specific message (e.g. last visible in the list)</span>
+socketEmit.<span class="fn">markRead</span>(conversationId, messageId);</code></pre>
+  </div>
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { socketEmit } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Mark read when the conversation becomes visible</span>
+socketEmit.<span class="fn">markRead</span>(conversationId);
+<span class="cm">// Mark up to a specific message</span>
+socketEmit.<span class="fn">markRead</span>(conversationId, messageId);</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { socketEmit, messagesApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+socketEmit.<span class="fn">markRead</span>(conversationId);              <span class="cm">// fire-and-forget via socket</span>
+<span class="kw">await</span> messagesApi.<span class="fn">markAsRead</span>(conversationId);     <span class="cm">// REST alternative (awaitable)</span></code></pre>
+  </div>
+  <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>
+  <div class="callout tip">
+    <strong>Automatic after connect</strong>
+    Once the socket is connected, <code>read_receipt</code> events automatically update <code>useChatStore.lastRead</code>. You only need to seed it manually on the very first load (before any socket event has arrived).
+  </div>
+  <pre><code><span class="kw">import</span> { messagesApi, useChatStore, <span class="tp">LastReadEntry</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Step 1 — seed the store when the conversation screen opens</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 && lastReadAt) {
+  useChatStore.<span class="fn">getState</span>().<span class="fn">setLastRead</span>(conversationId, lastReadMessageId, lastReadAt);
+}
+<span class="cm">// Step 2 — read reactively anywhere in your UI</span>
+<span class="kw">const</span> lastRead: <span class="tp">LastReadEntry</span> | <span class="tp">undefined</span> = useChatStore(s => s.lastRead[conversationId]);
+<span class="cm">// lastRead.messageId — scroll to this on open</span>
+<span class="cm">// lastRead.readAt    — ISO timestamp</span></code></pre>
+  <div data-p="rn web">
+    <pre><code><span class="cm">// Practical example: show "New messages" divider above unread messages</span>
+<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="kw">const</span> isFirstUnread =
+    lastRead &&
+    prevMessage?.id === lastRead.messageId; <span class="cm">// this message is right after the last-read one</span>
+  <span class="kw">return</span> (
+    &lt;&gt;
+      {isFirstUnread && &lt;<span class="fn">UnreadDivider</span> /&gt;}
+      &lt;<span class="fn">Bubble</span> message={message} /&gt;
+    &lt;/&gt;
+  );
+}</code></pre>
+  </div>
+  <hr class="divider" style="margin:28px 0"/>
+  <h3>Last seen — when another user was online</h3>
+  <p>Each user's last-seen timestamp is stored in <code>useChatStore.lastSeen[userId]</code>. The socket keeps it live: when a user disconnects, a <code>user_offline</code> event fires and the store updates automatically.</p>
+  <div class="callout tip">
+    <strong>Automatic after connect</strong>
+    <code>user_offline</code> events auto-update <code>useChatStore.lastSeen</code>. Seed the initial value from the API on first load.
+  </div>
+  <pre><code><span class="kw">import</span> { usersApi, useChatStore } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Seed on first render (e.g. when opening a DM or a user profile)</span>
+<span class="kw">const</span> { lastSeenAt } = <span class="kw">await</span> usersApi.<span class="fn">getLastSeen</span>(userId);
+<span class="kw">if</span> (lastSeenAt) useChatStore.<span class="fn">getState</span>().<span class="fn">setLastSeen</span>(userId, lastSeenAt);
+<span class="cm">// Read reactively — updates whenever user_offline fires</span>
+<span class="kw">const</span> lastSeenAt = <span class="fn">useChatStore</span>(s => s.lastSeen[userId]);   <span class="cm">// ISO string | undefined</span>
+<span class="kw">const</span> isOnline   = <span class="fn">useChatStore</span>(s => s.onlineUsers.<span class="fn">includes</span>(userId));</code></pre>
+  <div data-p="rn web">
+    <pre><code><span class="cm">// "Last seen 5 minutes ago" — format the ISO string however you like</span>
+<span class="kw">function</span> <span class="fn">LastSeenLabel</span>({ userId }: { userId: <span class="tp">string</span> }) {
+  <span class="kw">const</span> isOnline   = <span class="fn">useChatStore</span>(s => s.onlineUsers.<span class="fn">includes</span>(userId));
+  <span class="kw">const</span> lastSeenAt = <span class="fn">useChatStore</span>(s => s.lastSeen[userId]);
+  <span class="kw">if</span> (isOnline) <span class="kw">return</span> &lt;<span class="fn">Text</span>&gt;Online&lt;/<span class="fn">Text</span>&gt;;
+  <span class="kw">if</span> (lastSeenAt) <span class="kw">return</span> &lt;<span class="fn">Text</span>&gt;Last seen {<span class="fn">formatRelative</span>(<span class="kw">new</span> <span class="fn">Date</span>(lastSeenAt))}&lt;/<span class="fn">Text</span>&gt;;
+  <span class="kw">return</span> &lt;<span class="fn">Text</span>&gt;Offline&lt;/<span class="fn">Text</span>&gt;;
+}</code></pre>
+  </div>
+  <hr class="divider" style="margin:28px 0"/>
+  <h3>Listening to others' read receipts</h3>
+  <p>You don't need to manually subscribe to <code>read_receipt</code> for your own last-read tracking — the store handles that. But you may want to listen to update <em>message-level</em> read indicators (e.g. double-tick UI):</p>
+  <pre><code><span class="kw">import</span> { tryGetSocket } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> socket = <span class="fn">tryGetSocket</span>();
+socket?.<span class="fn">on</span>(<span class="str">'read_receipt'</span>, ({ conversationId, messageId, userId, fullyReadMessageIds }) => {
+  <span class="cm">// fullyReadMessageIds — messages everyone in the conversation has now read</span>
+  <span class="cm">// Show double-tick / "seen by all" indicator for these</span>
+  <span class="fn">markFullyRead</span>(fullyReadMessageIds ?? []);
+});</code></pre>
+  <h4>Summary — what is automatic vs. what you do</h4>
+  <table>
+    <thead><tr><th>Action</th><th>Automatic?</th><th>What you do</th></tr></thead>
+    <tbody>
+      <tr><td>Store <code>lastRead</code> updated on <code>read_receipt</code></td><td>✅ Yes</td><td>Nothing — wired inside <code>connectSocket</code></td></tr>
+      <tr><td>Store <code>lastSeen</code> updated on <code>user_offline</code></td><td>✅ Yes</td><td>Nothing — wired inside <code>connectSocket</code></td></tr>
+      <tr><td>Initial <code>lastRead</code> value on screen open</td><td>❌ Manual</td><td>Call <code>messagesApi.getLastRead(conversationId)</code>, push to store</td></tr>
+      <tr><td>Initial <code>lastSeen</code> value on profile/DM open</td><td>❌ Manual</td><td>Call <code>usersApi.getLastSeen(userId)</code>, push to store</td></tr>
+      <tr><td>Tell the server the user read messages</td><td>❌ Manual</td><td>Call <code>socketEmit.markRead(conversationId)</code> on focus</td></tr>
+    </tbody>
+  </table>
+</section>
+<!-- ─── STEP 13: EDIT & DELETE ────────────────────────────────────────── -->
+<section id="step-edit">
+  <h2><span class="step">STEP 13</span> Edit &amp; Delete Messages</h2>
+  <h3>Edit</h3>
+  <pre><code><span class="kw">await</span> socketEmit.<span class="fn">updateMessage</span>(messageId, <span class="str">'Updated text'</span>);
+<span class="cm">// REST fallback: await messagesApi.update(messageId, 'Updated text')</span></code></pre>
+  <div class="callout info">
+    <strong>Edit window</strong> — check <code>conversation.settings.messageConfig.editWindowSeconds</code>:
+    <pre style="margin-top:8px"><code><span class="kw">function</span> <span class="fn">canEdit</span>(msg: <span class="tp">Message</span>, conv: <span class="tp">Conversation</span>, userId: <span class="tp">string</span>) {
+  <span class="kw">if</span> (msg.senderId !== userId) <span class="kw">return false</span>;
+  <span class="kw">const</span> w = conv.settings?.messageConfig?.editWindowSeconds;
+  <span class="kw">return</span> !w || (Date.<span class="fn">now</span>() - <span class="kw">new</span> <span class="fn">Date</span>(msg.sentAt).<span class="fn">getTime</span>()) &lt; w * <span class="num">1000</span>;
+}</code></pre>
+  </div>
+  <h3>Delete — when to show which option</h3>
+  <table>
+    <thead><tr><th>Action</th><th>Show when</th><th>What it does</th></tr></thead>
+    <tbody>
+      <tr><td><strong>Delete for everyone</strong></td><td>Your message within the delete window, OR you're a group admin</td><td>Removes for all — others receive <code>message_deleted</code> event</td></tr>
+      <tr><td><strong>Delete for me</strong></td><td>Always — any message, any conversation type</td><td>Hides locally only — you receive <code>message_deleted_for_me</code></td></tr>
+    </tbody>
+  </table>
+  <div class="callout info">
+    <strong>Default delete window</strong> — if <code>conversation.settings.messageConfig.deleteWindowSeconds</code> is not set, the server defaults to <strong>1800 seconds (30 minutes)</strong>. Your UI helper must use the same fallback, otherwise you may show "Delete for everyone" after the window has already expired on the server and get a <code>403 Forbidden</code> response.
+  </div>
+  <div class="callout info">
+    <strong>DMs have no admins</strong> — in a direct message conversation <code>conv.type === 'direct'</code>, participants have no <code>admin</code> role. <code>isAdmin</code> will always be <code>false</code>, so "Delete for everyone" is only available to the message sender within the window. Do not show an admin-based delete option in DMs.
+  </div>
+  <pre><code><span class="kw">const</span> DEFAULT_DELETE_WINDOW_SEC = <span class="num">1800</span>; <span class="cm">// matches server default</span>
+<span class="kw">function</span> <span class="fn">getDeleteOptions</span>(msg: <span class="tp">Message</span>, conv: <span class="tp">Conversation</span>, userId: <span class="tp">string</span>) {
+  <span class="kw">const</span> isMine    = msg.senderId === userId;
+  <span class="kw">const</span> isAdmin   = conv.type !== <span class="str">'direct'</span> &&
+                    conv.participants.<span class="fn">find</span>(p => p.userId === userId)?.role === <span class="str">'admin'</span>;
+  <span class="kw">const</span> w         = conv.settings?.messageConfig?.deleteWindowSeconds ?? DEFAULT_DELETE_WINDOW_SEC;
+  <span class="kw">const</span> inWindow  = (Date.<span class="fn">now</span>() - <span class="kw">new</span> <span class="fn">Date</span>(msg.sentAt).<span class="fn">getTime</span>()) &lt; w * <span class="num">1000</span>;
+  <span class="kw">return</span> { <span class="at">canDeleteForEveryone</span>: (isMine && inWindow) || isAdmin, <span class="at">canDeleteForMe</span>: <span class="kw">true</span> };
+}
+<span class="kw">await</span> socketEmit.<span class="fn">deleteMessage</span>(messageId);        <span class="cm">// for everyone</span>
+<span class="kw">await</span> socketEmit.<span class="fn">deleteMessageForMe</span>(messageId);   <span class="cm">// for me only</span>
+<span class="cm">// REST: messagesApi.delete(id) / messagesApi.deleteForMe(id)</span></code></pre>
+</section>
+<!-- ─── STEP 14: SEARCH ───────────────────────────────────────────────── -->
+<section id="step-search">
+  <h2><span class="step">STEP 14</span> Search Messages</h2>
+  <pre><code><span class="kw">const</span> { data, meta } = <span class="kw">await</span> messagesApi.<span class="fn">search</span>({
+  <span class="at">query</span>: <span class="str">'meeting notes'</span>,
+  <span class="at">conversationId</span>: conversationId, <span class="cm">// omit to search all conversations</span>
+  <span class="at">page</span>: <span class="num">1</span>, <span class="at">limit</span>: <span class="num">20</span>,
+});
+<span class="cm">// meta.hasNextPage — paginate with page: 2, 3...</span>
+<span class="cm">// Get a single message by ID</span>
+<span class="kw">const</span> msg = <span class="kw">await</span> messagesApi.<span class="fn">get</span>(messageId);</code></pre>
+</section>
+<!-- ─── STEP 15: REACTIONS ────────────────────────────────────────────── -->
+<section id="step-reactions">
+  <h2><span class="step">STEP 15</span> Reactions, Pin &amp; Star</h2>
+  <pre><code><span class="cm">// Reactions — message.reactions is { emoji, userIds, count }[]</span>
+<span class="kw">await</span> socketEmit.<span class="fn">addReaction</span>(messageId, <span class="str">'👍'</span>);
+<span class="kw">await</span> socketEmit.<span class="fn">removeReaction</span>(messageId, <span class="str">'👍'</span>);
+<span class="cm">// Check if you reacted: message.reactions.find(r => r.emoji === '👍')?.userIds.includes(userId)</span>
+<span class="cm">// Pin / Unpin</span>
+<span class="kw">await</span> socketEmit.<span class="fn">pinMessage</span>(messageId);
+<span class="kw">await</span> socketEmit.<span class="fn">unpinMessage</span>(messageId);
+<span class="kw">const</span> pinned = <span class="kw">await</span> messagesApi.<span class="fn">getPinned</span>(conversationId); <span class="cm">// Message[]</span>
+<span class="cm">// Star / Unstar (personal — not visible to others)</span>
+<span class="kw">await</span> messagesApi.<span class="fn">star</span>(messageId);
+<span class="kw">await</span> messagesApi.<span class="fn">unstar</span>(messageId);
+<span class="kw">const</span> { data: starred } = <span class="kw">await</span> messagesApi.<span class="fn">getStarred</span>({ <span class="at">limit</span>: <span class="num">20</span>, conversationId });</code></pre>
+</section>
+<hr class="divider"/>
+<!-- ─── STEP 16: UPLOAD ───────────────────────────────────────────────── -->
+<section id="step-upload">
+  <h2><span class="step">STEP 16</span> Upload Files</h2>
+  <p>The SDK handles the full flow: presigned URL request → binary upload via your <code>platformUploadFn</code> → server confirmation. You get back <code>fileId</code>s to attach to messages.</p>
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> * <span class="kw">as</span> ImagePicker <span class="kw">from</span> <span class="str">'expo-image-picker'</span>;
+<span class="kw">const</span> result = <span class="kw">await</span> ImagePicker.<span class="fn">launchImageLibraryAsync</span>({ <span class="at">allowsMultipleSelection</span>: <span class="kw">true</span> });
+<span class="kw">if</span> (result.canceled) <span class="kw">return</span>;
+<span class="kw">const</span> files = result.assets.<span class="fn">map</span>(a => ({
+  <span class="at">uri</span>: a.uri, <span class="at">name</span>: a.fileName ?? <span class="str">'file'</span>,
+  <span class="at">type</span>: a.mimeType ?? <span class="str">'application/octet-stream'</span>, <span class="at">size</span>: a.fileSize ?? <span class="num">0</span>,
+}));
+<span class="kw">const</span> { successful, failed } = <span class="kw">await</span> chatClient.<span class="fn">uploadFiles</span>(files, conversationId);
+<span class="kw">if</span> (failed.length) console.<span class="fn">warn</span>(<span class="str">'Failed:'</span>, failed);</code></pre>
+  </div>
+  <div data-p="web">
+    <pre><code><span class="cm">// From a file input element</span>
+<span class="kw">const</span> files = [...inputEl.files].<span class="fn">map</span>(f => ({
+  <span class="at">uri</span>: URL.<span class="fn">createObjectURL</span>(f), <span class="at">name</span>: f.name, <span class="at">type</span>: f.type, <span class="at">size</span>: f.size,
+}));
+<span class="kw">const</span> { successful, failed } = <span class="kw">await</span> chatClient.<span class="fn">uploadFiles</span>(files, conversationId);
+<span class="kw">if</span> (failed.length) console.<span class="fn">warn</span>(<span class="str">'Failed:'</span>, failed);</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="cm">// From a file path on disk</span>
+<span class="kw">import</span> { statSync } <span class="kw">from</span> <span class="str">'fs'</span>;
+<span class="kw">import</span> { lookup } <span class="kw">from</span> <span class="str">'mime-types'</span>;
+<span class="kw">const</span> filePath = <span class="str">'/tmp/report.pdf'</span>;
+<span class="kw">const</span> files = [{
+  <span class="at">uri</span>: filePath,
+  <span class="at">name</span>: <span class="str">'report.pdf'</span>,
+  <span class="at">type</span>: <span class="fn">lookup</span>(filePath) || <span class="str">'application/octet-stream'</span>,
+  <span class="at">size</span>: <span class="fn">statSync</span>(filePath).size,
+}];
+<span class="kw">const</span> { successful, failed } = <span class="kw">await</span> chatClient.<span class="fn">uploadFiles</span>(files, conversationId);</code></pre>
+  </div>
+  <p>Then send with attachments:</p>
+  <pre><code><span class="kw">const</span> attachments = successful.<span class="fn">map</span>(f => ({
+  <span class="at">fileId</span>: f.id, <span class="at">type</span>: f.type, <span class="at">url</span>: f.url,
+  <span class="at">filename</span>: f.filename, <span class="at">mimeType</span>: f.mimeType, <span class="at">size</span>: f.size,
+}));
+<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(), attachments });</code></pre>
+  <h3>Upload limits — configure in client.ts</h3>
+  <pre><code><span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="cm">// ...</span>
+  <span class="at">upload</span>: {
+    <span class="at">onProgress</span>: (pct) => <span class="fn">setProgress</span>(pct),  <span class="cm">// 0–100 aggregate</span>
+    <span class="at">onUploadError</span>: (file, err) => console.<span class="fn">error</span>(file.name, err),
+    <span class="at">maxFileSizeMB</span>: <span class="num">50</span>,
+    <span class="at">maxFilesPerMessage</span>: <span class="num">10</span>,
+    <span class="at">allowedTypes</span>: [<span class="str">'image'</span>, <span class="str">'video'</span>, <span class="str">'document'</span>],
+  },
+});</code></pre>
+</section>
+<!-- ─── STEP 17: PUSH (RN + WEB only) ────────────────────────────────── -->
+<section id="step-push" data-p="rn web">
+  <h2><span class="step">STEP 17</span> Push Notifications</h2>
+  <p>
+    The server stores one device token document per physical device in <code>chat_device_tokens</code>.
+    Tokens are separate from the user profile — a single user can have multiple active tokens
+    (phone + tablet + browser). The server looks up all active tokens for a user and delivers
+    push notifications to every registered device when a message or event arrives while they are offline.
+  </p>
+  <h3>How registration works</h3>
+  <p>
+    Every call to <code>devicesApi.register()</code> is an <strong>upsert</strong> keyed on <code>deviceId</code>.
+    If the same <code>deviceId</code> is registered again (app restart, token rotation), the existing record is
+    updated — no duplicate is created. This means it is safe — and correct — to call <code>register()</code>
+    on every app launch.
+  </p>
+  <h3>The <code>deviceId</code> rule — read this first</h3>
+  <p>
+    <code>deviceId</code> must be a <strong>stable UUID that persists across app restarts</strong>.
+    Generate it once on first install and store it in <code>AsyncStorage</code> / <code>SecureStore</code> (mobile)
+    or <code>localStorage</code> (web). Never regenerate it on each launch — if you lose the <code>deviceId</code>
+    the old token record becomes an orphan in the server's DB and the user will receive duplicate notifications
+    until the stale token expires.
+  </p>
+  <!-- ── React Native (Expo) ─────────────────────────────────────────────── -->
+  <div data-p="rn">
+    <h3>React Native — Expo push (iOS &amp; Android)</h3>
+    <h4>When to call</h4>
+    <p>
+      Call <code>registerPushToken()</code> <strong>on every app launch, right after authentication</strong>.
+      Expo can silently rotate the push token after an OS upgrade, app reinstall, or when the device
+      transfers APNs registration. Calling on every launch ensures the server always has the current token
+      — if the token hasn't changed the upsert is a no-op (only <code>lastUsedAt</code> is bumped).
+    </p>
+    <pre><code><span class="kw">import</span> { devicesApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</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">import</span> * <span class="kw">as</span> Device <span class="kw">from</span> <span class="str">'expo-device'</span>;
+<span class="kw">import</span> * <span class="kw">as</span> SecureStore <span class="kw">from</span> <span class="str">'expo-secure-store'</span>;
+<span class="kw">import</span> * <span class="kw">as</span> Crypto <span class="kw">from</span> <span class="str">'expo-crypto'</span>;
+<span class="cm">// Generated once on first install, stored securely, never changes.</span>
+<span class="kw">async function</span> <span class="fn">getStableDeviceId</span>(): <span class="tp">Promise</span>&lt;<span class="tp">string</span>&gt; {
+  <span class="kw">const</span> existing = <span class="kw">await</span> SecureStore.<span class="fn">getItemAsync</span>(<span class="str">'chat-device-id'</span>);
+  <span class="kw">if</span> (existing) <span class="kw">return</span> existing;
+  <span class="kw">const</span> id = Crypto.<span class="fn">randomUUID</span>();
+  <span class="kw">await</span> SecureStore.<span class="fn">setItemAsync</span>(<span class="str">'chat-device-id'</span>, id);
+  <span class="kw">return</span> id;
+}
+<span class="cm">// Call after login on every app launch.</span>
+<span class="kw">async function</span> <span class="fn">registerPushToken</span>(): <span class="tp">Promise</span>&lt;<span class="tp">void</span>&gt; {
+  <span class="kw">if</span> (!Device.isDevice) <span class="kw">return</span>; <span class="cm">// simulators cannot receive push</span>
+  <span class="kw">const</span> { status: existing } = <span class="kw">await</span> Notifications.<span class="fn">getPermissionsAsync</span>();
+  <span class="kw">const</span> { status } = existing !== <span class="str">'granted'</span>
+    ? <span class="kw">await</span> Notifications.<span class="fn">requestPermissionsAsync</span>()
+    : { status: existing };
+  <span class="kw">if</span> (status !== <span class="str">'granted'</span>) <span class="kw">return</span>; <span class="cm">// user denied — do not register</span>
+  <span class="kw">const</span> { data: token } = <span class="kw">await</span> Notifications.<span class="fn">getExpoPushTokenAsync</span>();
+  <span class="kw">const</span> deviceId = <span class="kw">await</span> <span class="fn">getStableDeviceId</span>();
+  <span class="kw">await</span> devicesApi.<span class="fn">register</span>({
+    deviceId,
+    platform: Device.osName === <span class="str">'iOS'</span> ? <span class="str">'ios'</span> : <span class="str">'android'</span>,
+    provider: <span class="str">'expo'</span>,
+    token,
+    userAgent: <span class="str">`${Device.modelName} / ${Device.osName} ${Device.osVersion}`</span>,
+  });
+}
+<span class="cm">// On logout — deactivates this device so push stops immediately.</span>
+<span class="kw">async function</span> <span class="fn">unregisterPushToken</span>(): <span class="tp">Promise</span>&lt;<span class="tp">void</span>&gt; {
+  <span class="kw">const</span> deviceId = <span class="kw">await</span> SecureStore.<span class="fn">getItemAsync</span>(<span class="str">'chat-device-id'</span>);
+  <span class="kw">if</span> (deviceId) <span class="kw">await</span> devicesApi.<span class="fn">remove</span>(deviceId);
+}
+<span class="cm">// ── Usage ──────────────────────────────────────────────────────────────
+// In your auth flow — call both after every successful login:</span>
+<span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+<span class="kw">await</span> <span class="fn">registerPushToken</span>(); <span class="cm">// safe to call on every launch</span>
+<span class="cm">// On logout:</span>
+<span class="kw">await</span> <span class="fn">unregisterPushToken</span>();
+<span class="kw">await</span> chatClient.<span class="fn">disconnect</span>();</code></pre>
+    <h4>FCM (Firebase) — Android / direct FCM without Expo</h4>
+    <pre><code><span class="kw">import</span> messaging <span class="kw">from</span> <span class="str">'@react-native-firebase/messaging'</span>;
+<span class="kw">async function</span> <span class="fn">registerFCMToken</span>(): <span class="tp">Promise</span>&lt;<span class="tp">void</span>&gt; {
+  <span class="kw">const</span> granted = <span class="kw">await</span> messaging().<span class="fn">requestPermission</span>();
+  <span class="kw">if</span> (!granted) <span class="kw">return</span>;
+  <span class="kw">const</span> token = <span class="kw">await</span> messaging().<span class="fn">getToken</span>();
+  <span class="kw">const</span> deviceId = <span class="kw">await</span> <span class="fn">getStableDeviceId</span>();
+  <span class="kw">await</span> devicesApi.<span class="fn">register</span>({
+    deviceId,
+    platform: <span class="str">'android'</span>,
+    provider: <span class="str">'fcm'</span>,
+    token,
+  });
+  <span class="cm">// FCM tokens can rotate — re-register whenever Firebase issues a new one.</span>
+  messaging().<span class="fn">onTokenRefresh</span>(<span class="kw">async</span> (newToken) => {
+    <span class="kw">await</span> devicesApi.<span class="fn">register</span>({ deviceId, platform: <span class="str">'android'</span>, provider: <span class="str">'fcm'</span>, token: newToken });
+  });
+}</code></pre>
+    <h4>Token lifecycle summary — mobile</h4>
+    <table style="width:100%;border-collapse:collapse;font-size:13px;margin:12px 0">
+      <thead><tr style="border-bottom:1px solid var(--border)">
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">Event</th>
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">Action</th>
+      </tr></thead>
+      <tbody>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">App launch after login</td><td style="padding:6px 10px">Call <code>register()</code> — upsert handles token rotation automatically</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">User logs out</td><td style="padding:6px 10px">Call <code>remove(deviceId)</code> — server sets token <code>isActive: false</code></td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">User revokes permission in OS settings</td><td style="padding:6px 10px">Call <code>remove(deviceId)</code> in your permission-change handler</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">App reinstall / token rotation</td><td style="padding:6px 10px">Handled automatically — next launch calls <code>register()</code> with the new token</td></tr>
+        <tr><td style="padding:6px 10px">Notification engine gets <code>DeviceNotRegistered</code> from Expo/FCM</td><td style="padding:6px 10px">Engine automatically marks the token inactive — no action needed in app</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <!-- ── Web (VAPID) ────────────────────────────────────────────────────── -->
+  <div data-p="web">
+    <h3>Web — VAPID / Web Push</h3>
+    <h4>When to call</h4>
+    <p>
+      Web push subscriptions are <strong>persistent</strong> — the browser stores them across page loads.
+      Call <code>register()</code> in two situations:
+    </p>
+    <ul style="margin:0 0 12px 20px;color:#c8d0e0;font-size:14px;line-height:2">
+      <li><strong>On app init (after login)</strong> — if a subscription already exists, re-register it to refresh <code>lastUsedAt</code> and catch any endpoint rotation the browser did silently.</li>
+      <li><strong>When the user explicitly enables notifications</strong> — request permission, create a new subscription, then register.</li>
+    </ul>
+    <p>
+      Unlike mobile, do <strong>not</strong> call <code>pushManager.subscribe()</code> on every page load —
+      that would prompt the user repeatedly. Only call it when no subscription exists yet.
+    </p>
+    <pre><code><span class="kw">import</span> { devicesApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> VAPID_PUBLIC_KEY = <span class="str">'YOUR_VAPID_PUBLIC_KEY'</span>; <span class="cm">// from server env</span>
+<span class="cm">// Generated once, stored in localStorage, never regenerated.</span>
+<span class="kw">function</span> <span class="fn">getStableDeviceId</span>(): <span class="tp">string</span> {
+  <span class="kw">let</span> id = localStorage.<span class="fn">getItem</span>(<span class="str">'chat-device-id'</span>);
+  <span class="kw">if</span> (!id) { id = crypto.<span class="fn">randomUUID</span>(); localStorage.<span class="fn">setItem</span>(<span class="str">'chat-device-id'</span>, id); }
+  <span class="kw">return</span> id;
+}
+<span class="kw">function</span> <span class="fn">subToPayload</span>(sub: PushSubscription, deviceId: <span class="tp">string</span>) {
+  <span class="kw">const</span> <span class="fn">b64</span> = (buf: ArrayBuffer | null) =>
+    buf ? <span class="fn">btoa</span>(String.<span class="fn">fromCharCode</span>(...<span class="kw">new</span> <span class="fn">Uint8Array</span>(buf))) : <span class="str">''</span>;
+  <span class="kw">return</span> {
+    deviceId,
+    platform: <span class="str">'web'</span> <span class="kw">as const</span>,
+    provider: <span class="str">'web-push'</span> <span class="kw">as const</span>,
+    endpoint: sub.endpoint,
+    p256dh:   <span class="fn">b64</span>(sub.<span class="fn">getKey</span>(<span class="str">'p256dh'</span>)),
+    auth:     <span class="fn">b64</span>(sub.<span class="fn">getKey</span>(<span class="str">'auth'</span>)),
+    userAgent: navigator.userAgent,
+  };
+}
+<span class="cm">// Call on every app init after login.
+// Re-registers any existing subscription (upsert — no duplicate created).
+// Silently skips if push is not supported or not yet permitted.</span>
+<span class="kw">async function</span> <span class="fn">syncPushSubscription</span>(): <span class="tp">Promise</span>&lt;<span class="tp">void</span>&gt; {
+  <span class="kw">if</span> (!(<span class="str">'serviceWorker'</span> <span class="kw">in</span> navigator) || !(<span class="str">'PushManager'</span> <span class="kw">in</span> window)) <span class="kw">return</span>;
+  <span class="kw">if</span> (Notification.permission !== <span class="str">'granted'</span>) <span class="kw">return</span>;
+  <span class="kw">const</span> reg = <span class="kw">await</span> navigator.serviceWorker.<span class="fn">ready</span>;
+  <span class="kw">const</span> existing = <span class="kw">await</span> reg.pushManager.<span class="fn">getSubscription</span>();
+  <span class="kw">if</span> (!existing) <span class="kw">return</span>; <span class="cm">// no subscription yet — user hasn't enabled push</span>
+  <span class="kw">await</span> devicesApi.<span class="fn">register</span>(<span class="fn">subToPayload</span>(existing, <span class="fn">getStableDeviceId</span>()));
+}
+<span class="cm">// Call when the user clicks "Enable notifications" in your UI.</span>
+<span class="kw">async function</span> <span class="fn">enablePushNotifications</span>(): <span class="tp">Promise</span>&lt;<span class="tp">void</span>&gt; {
+  <span class="kw">if</span> (!(<span class="str">'serviceWorker'</span> <span class="kw">in</span> navigator)) <span class="kw">return</span>;
+  <span class="kw">const</span> permission = <span class="kw">await</span> Notification.<span class="fn">requestPermission</span>();
+  <span class="kw">if</span> (permission !== <span class="str">'granted'</span>) <span class="kw">return</span>;
+  <span class="kw">const</span> reg = <span class="kw">await</span> navigator.serviceWorker.<span class="fn">ready</span>;
+  <span class="kw">const</span> sub = <span class="kw">await</span> reg.pushManager.<span class="fn">subscribe</span>({
+    userVisibleOnly: <span class="kw">true</span>,
+    applicationServerKey: VAPID_PUBLIC_KEY,
+  });
+  <span class="kw">await</span> devicesApi.<span class="fn">register</span>(<span class="fn">subToPayload</span>(sub, <span class="fn">getStableDeviceId</span>()));
+}
+<span class="cm">// Call when the user clicks "Disable notifications" or on logout.</span>
+<span class="kw">async function</span> <span class="fn">disablePushNotifications</span>(): <span class="tp">Promise</span>&lt;<span class="tp">void</span>&gt; {
+  <span class="kw">const</span> reg = <span class="kw">await</span> navigator.serviceWorker.<span class="fn">ready</span>;
+  <span class="kw">const</span> sub = <span class="kw">await</span> reg.pushManager.<span class="fn">getSubscription</span>();
+  <span class="kw">if</span> (sub) <span class="kw">await</span> sub.<span class="fn">unsubscribe</span>(); <span class="cm">// tells browser to drop the subscription</span>
+  <span class="kw">await</span> devicesApi.<span class="fn">remove</span>(<span class="fn">getStableDeviceId</span>()); <span class="cm">// tells server to stop pushing</span>
+}
+<span class="cm">// ── Usage ──────────────────────────────────────────────────────────────
+// In your app init / auth provider — after every login:</span>
+<span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+<span class="kw">await</span> <span class="fn">syncPushSubscription</span>(); <span class="cm">// re-registers existing subscription if any</span>
+<span class="cm">// When user clicks "Enable notifications":</span>
+<span class="kw">await</span> <span class="fn">enablePushNotifications</span>();
+<span class="cm">// On logout or "Disable notifications":</span>
+<span class="kw">await</span> <span class="fn">disablePushNotifications</span>();</code></pre>
+    <h4>Service worker — handle incoming push</h4>
+    <p>You need a service worker file to receive push events when the tab is closed.</p>
+    <pre><code><span class="cm">// public/sw.js</span>
+self.<span class="fn">addEventListener</span>(<span class="str">'push'</span>, (event) => {
+  <span class="kw">const</span> data = event.data?.<span class="fn">json</span>() ?? {};
+  event.<span class="fn">waitUntil</span>(
+    self.registration.<span class="fn">showNotification</span>(data.title ?? <span class="str">'New message'</span>, {
+      body:  data.body,
+      icon:  <span class="str">'/icon-192.png'</span>,
+      badge: <span class="str">'/badge-72.png'</span>,
+      data:  data.data, <span class="cm">// contains event, conversation_id, message_id, etc.</span>
+    })
+  );
+});
+self.<span class="fn">addEventListener</span>(<span class="str">'notificationclick'</span>, (event) => {
+  event.<span class="fn">notification</span>.<span class="fn">close</span>();
+  <span class="kw">const</span> { conversation_id } = event.notification.data ?? {};
+  <span class="kw">if</span> (conversation_id) {
+    event.<span class="fn">waitUntil</span>(clients.<span class="fn">openWindow</span>(<span class="str">`/chat/${conversation_id}`</span>));
+  }
+});</code></pre>
+    <h4>Token lifecycle summary — web</h4>
+    <table style="width:100%;border-collapse:collapse;font-size:13px;margin:12px 0">
+      <thead><tr style="border-bottom:1px solid var(--border)">
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">Event</th>
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">Action</th>
+      </tr></thead>
+      <tbody>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">App init after login (subscription already exists)</td><td style="padding:6px 10px">Call <code>syncPushSubscription()</code> — upserts existing subscription</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">User clicks "Enable notifications"</td><td style="padding:6px 10px">Call <code>enablePushNotifications()</code> — requests permission, subscribes, registers</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">User logs out</td><td style="padding:6px 10px">Call <code>disablePushNotifications()</code> — unsubscribes browser + deactivates server token</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">User clicks "Disable notifications" in your UI</td><td style="padding:6px 10px">Same — <code>disablePushNotifications()</code></td></tr>
+        <tr><td style="padding:6px 10px">Browser silently rotates the endpoint</td><td style="padding:6px 10px">Handled — next <code>syncPushSubscription()</code> on login updates it via upsert</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <!-- ── Hook usage (both platforms) ───────────────────────────────────── -->
+  <h3>Using the <code>useDeviceToken</code> hook</h3>
+  <p>Both SDKs export <code>useDeviceToken</code> for use in React components when you need manual control:</p>
+  <pre><code><span class="kw">import</span> { useDeviceToken } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>; <span class="cm">// or chat-rn-sdk</span>
+<span class="kw">function</span> <span class="fn">NotificationSettings</span>() {
+  <span class="kw">const</span> { register, remove } = <span class="fn">useDeviceToken</span>();
+  <span class="kw">return</span> (
+    &lt;div&gt;
+      &lt;button onClick={enablePushNotifications}&gt;Enable notifications&lt;/button&gt;
+      &lt;button onClick={disablePushNotifications}&gt;Disable notifications&lt;/button&gt;
+    &lt;/div&gt;
+  );
+}</code></pre>
+  <h3>Multiple devices per user</h3>
+  <p>
+    Each registered <code>deviceId</code> is a separate record in the server. A user logged in on a phone,
+    tablet, and browser will have three active token records — the server sends push to all of them
+    simultaneously when a notification is triggered. Removing a token only deactivates that specific
+    device; other devices continue to receive notifications.
+  </p>
+</section>
+<!-- ─── STEP 17.5: NOTIFICATION PREFERENCES ──────────────────────────── -->
+<section id="step-prefs" data-p="rn web node">
+  <h2><span class="step">STEP 17.5</span> Notification Preferences</h2>
+  <p>
+    User notification preferences are stored server-side in <code>chat_user_prefs</code>.
+    A record with all defaults is created automatically when a push token is first registered —
+    so this API is always available after push setup.
+  </p>
+  <p>
+    All fields are optional on update — only send what changed.
+    Future preference fields go into the same collection and the same API; no new endpoints needed.
+  </p>
+  <h3>API</h3>
+  <pre><code><span class="kw">import</span> { usersApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import type</span> { <span class="tp">UserPreferences</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Read current preferences (null if no record yet — all defaults apply)</span>
+<span class="kw">const</span> prefs = <span class="kw">await</span> usersApi.<span class="fn">getPreferences</span>();
+<span class="cm">// Partial updates — only send what changed</span>
+<span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({ <span class="at">notifyOnReaction</span>: <span class="kw">false</span> });
+<span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({ <span class="at">messagePreview</span>: <span class="kw">false</span> }); <span class="cm">// privacy mode</span>
+<span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({ <span class="at">notificationsEnabled</span>: <span class="kw">false</span> }); <span class="cm">// master off</span>
+<span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({
+  <span class="at">quietHours</span>: { <span class="at">enabled</span>: <span class="kw">true</span>, <span class="at">start</span>: <span class="str">'23:00'</span>, <span class="at">end</span>: <span class="str">'07:00'</span>, <span class="at">timezone</span>: <span class="str">'Asia/Kolkata'</span> },
+});</code></pre>
+  <h3>Preferences reference</h3>
+  <table style="width:100%;border-collapse:collapse;font-size:13px;margin:12px 0">
+    <thead><tr style="border-bottom:1px solid var(--border)">
+      <th style="text-align:left;padding:6px 10px;color:var(--muted)">Field</th>
+      <th style="text-align:left;padding:6px 10px;color:var(--muted)">Default</th>
+      <th style="text-align:left;padding:6px 10px;color:var(--muted)">Description</th>
+    </tr></thead>
+    <tbody>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>notificationsEnabled</code></td><td style="padding:6px 10px"><code>true</code></td><td style="padding:6px 10px">Master switch — <code>false</code> disables all push</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>soundEnabled</code></td><td style="padding:6px 10px"><code>true</code></td><td style="padding:6px 10px">Play sound with notifications</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>messagePreview</code></td><td style="padding:6px 10px"><code>true</code></td><td style="padding:6px 10px">Show message text in body. <code>false</code> = "New message" only (privacy mode)</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>notifyOnMention</code></td><td style="padding:6px 10px"><code>true</code></td><td style="padding:6px 10px">Notify when @mentioned in a group</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>notifyOnReaction</code></td><td style="padding:6px 10px"><code>true</code></td><td style="padding:6px 10px">Notify when someone reacts to your message</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>notifyOnGroupInvite</code></td><td style="padding:6px 10px"><code>true</code></td><td style="padding:6px 10px">Notify when added to a group</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>quietHours.enabled</code></td><td style="padding:6px 10px"><code>false</code></td><td style="padding:6px 10px">Enable quiet hours window</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>quietHours.start</code></td><td style="padding:6px 10px"><code>"22:00"</code></td><td style="padding:6px 10px">Start of quiet window (HH:MM)</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>quietHours.end</code></td><td style="padding:6px 10px"><code>"08:00"</code></td><td style="padding:6px 10px">End of quiet window (HH:MM)</td></tr>
+      <tr><td style="padding:6px 10px"><code>quietHours.timezone</code></td><td style="padding:6px 10px"><code>"UTC"</code></td><td style="padding:6px 10px">IANA timezone — e.g. <code>"Asia/Kolkata"</code></td></tr>
+    </tbody>
+  </table>
+  <h3>Settings UI</h3>
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { useState, useEffect } <span class="kw">from</span> <span class="str">'react'</span>;
+<span class="kw">import</span> { Switch, Text, View } <span class="kw">from</span> <span class="str">'react-native'</span>;
+<span class="kw">import</span> { usersApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">export function</span> <span class="fn">NotificationSettingsScreen</span>() {
+  <span class="kw">const</span> [prefs, setPrefs] = <span class="fn">useState</span>(<span class="kw">null</span>);
+  <span class="fn">useEffect</span>(() => { usersApi.<span class="fn">getPreferences</span>().<span class="fn">then</span>(setPrefs); }, []);
+  <span class="kw">async function</span> <span class="fn">toggle</span>(field, value) {
+    <span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({ [field]: value });
+    <span class="fn">setPrefs</span>(prev => ({ ...prev, [field]: value }));
+  }
+  <span class="kw">if</span> (!prefs) <span class="kw">return null</span>;
+  <span class="kw">return</span> (
+    &lt;View&gt;
+      {[
+        [<span class="str">'notificationsEnabled'</span>, <span class="str">'Enable notifications'</span>],
+        [<span class="str">'messagePreview'</span>,       <span class="str">'Show message preview'</span>],
+        [<span class="str">'notifyOnMention'</span>,      <span class="str">'Mentions'</span>],
+        [<span class="str">'notifyOnReaction'</span>,     <span class="str">'Reactions'</span>],
+        [<span class="str">'notifyOnGroupInvite'</span>,  <span class="str">'Group invites'</span>],
+      ].<span class="fn">map</span>(([field, label]) => (
+        &lt;View key={field} style={{ flexDirection: <span class="str">'row'</span>, justifyContent: <span class="str">'space-between'</span>, padding: <span class="num">12</span> }}&gt;
+          &lt;Text&gt;{label}&lt;/Text&gt;
+          &lt;Switch value={prefs[field] ?? <span class="kw">true</span>} onValueChange={v => <span class="fn">toggle</span>(field, v)} /&gt;
+        &lt;/View&gt;
+      ))}
+    &lt;/View&gt;
+  );
+}</code></pre>
+  </div>
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { useState, useEffect } <span class="kw">from</span> <span class="str">'react'</span>;
+<span class="kw">import</span> { usersApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">function</span> <span class="fn">NotificationSettings</span>() {
+  <span class="kw">const</span> [prefs, setPrefs] = <span class="fn">useState</span>(<span class="kw">null</span>);
+  <span class="fn">useEffect</span>(() => { usersApi.<span class="fn">getPreferences</span>().<span class="fn">then</span>(setPrefs); }, []);
+  <span class="kw">async function</span> <span class="fn">toggle</span>(field, value) {
+    <span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({ [field]: value });
+    <span class="fn">setPrefs</span>(prev => ({ ...prev, [field]: value }));
+  }
+  <span class="kw">if</span> (!prefs) <span class="kw">return null</span>;
+  <span class="kw">return</span> (
+    &lt;div&gt;
+      {[
+        [<span class="str">'notificationsEnabled'</span>, <span class="str">'Enable notifications'</span>],
+        [<span class="str">'messagePreview'</span>,       <span class="str">'Show message preview'</span>],
+        [<span class="str">'notifyOnMention'</span>,      <span class="str">'Mentions'</span>],
+        [<span class="str">'notifyOnReaction'</span>,     <span class="str">'Reactions'</span>],
+        [<span class="str">'notifyOnGroupInvite'</span>,  <span class="str">'Group invites'</span>],
+      ].<span class="fn">map</span>(([field, label]) => (
+        &lt;label key={field} style={{ display: <span class="str">'flex'</span>, gap: <span class="num">8</span>, alignItems: <span class="str">'center'</span> }}&gt;
+          &lt;input type=<span class="str">"checkbox"</span> checked={prefs[field] ?? <span class="kw">true</span>}
+            onChange={e => <span class="fn">toggle</span>(field, e.target.checked)} /&gt;
+          {label}
+        &lt;/label&gt;
+      ))}
+    &lt;/div&gt;
+  );
+}</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { usersApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Read preferences</span>
+<span class="kw">const</span> prefs = <span class="kw">await</span> usersApi.<span class="fn">getPreferences</span>();
+<span class="cm">// Update — e.g. disable all notifications for a bot user</span>
+<span class="kw">await</span> usersApi.<span class="fn">updatePreferences</span>({ <span class="at">notificationsEnabled</span>: <span class="kw">false</span> });</code></pre>
+  </div>
+  <h3>Adding future preferences</h3>
+  <p>
+    Add the new field to the server schema (<code>user-prefs.schema.ts</code>) and the
+    <code>UserPreferences</code> type in <code>@antzsoft/chat-core</code>.
+    The same <code>updatePreferences()</code> / <code>getPreferences()</code> calls handle it —
+    no new API endpoints, no new collections.
+  </p>
+</section>
+<!-- ─── STEP 18: FULL EXAMPLE ─────────────────────────────────────────── -->
+<section id="step-example">
+  <h2><span class="step">STEP 18</span> Full Example</h2>
+  <div data-p="rn web">
+    <pre><code><span class="cm">// src/screens/ConversationScreen.tsx</span>
+<span class="kw">import</span> React, { useEffect, useState, useCallback, useRef } <span class="kw">from</span> <span class="str">'react'</span>;
+<span class="kw">import</span> { FlatList, TextInput, Pressable, Text, View } <span class="kw">from</span> <span class="str">'react-native'</span>;
+<span class="kw">import</span> { useFocusEffect } <span class="kw">from</span> <span class="str">'@react-navigation/native'</span>;
+<span class="kw">import</span> { v4 <span class="kw">as</span> uuid } <span class="kw">from</span> <span class="str">'uuid'</span>;
+<span class="kw">import</span> {
+  messagesApi, socketEmit, tryGetSocket, onSocketStatus,
+  <span class="tp">Message</span>, <span class="tp">NewMessageEvent</span>, <span class="tp">MessageUpdatedEvent</span>, <span class="tp">MessageDeletedEvent</span>,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">export function</span> <span class="fn">ConversationScreen</span>({ route }: <span class="kw">any</span>) {
+  <span class="kw">const</span> { conversationId } = route.params;
+  <span class="kw">const</span> [messages, setMessages] = <span class="fn">useState</span>&lt;<span class="tp">Message</span>[]&gt;([]);
+  <span class="kw">const</span> [text, setText]         = <span class="fn">useState</span>(<span class="str">''</span>);
+  <span class="kw">const</span> [cursor, setCursor]     = <span class="fn">useState</span>&lt;<span class="tp">string</span>|<span class="tp">undefined</span>&gt;();
+  <span class="kw">const</span> [hasMore, setHasMore]   = <span class="fn">useState</span>(<span class="kw">true</span>);
+  <span class="kw">const</span> timer                   = <span class="fn">useRef</span>&lt;<span class="tp">ReturnType</span>&lt;<span class="kw">typeof</span> setTimeout&gt;&gt;();
+  <span class="cm">// 1. Join room + re-join on reconnect</span>
+  <span class="fn">useEffect</span>(() => {
+    socketEmit.<span class="fn">joinRoom</span>(conversationId);
+    <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="kw">return</span> () => { socketEmit.<span class="fn">leaveRoom</span>(conversationId); unsub(); };
+  }, [conversationId]);
+  <span class="cm">// 2. Load messages</span>
+  <span class="fn">useEffect</span>(() => {
+    <span class="kw">async function</span> <span class="fn">load</span>() {
+      <span class="kw">const</span> { data, 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="fn">setMessages</span>(data); <span class="fn">setCursor</span>(meta.nextCursor); <span class="fn">setHasMore</span>(meta.hasMore);
+    }
+    <span class="fn">load</span>();
+  }, [conversationId]);
+  <span class="cm">// 3. Real-time listeners</span>
+  <span class="fn">useEffect</span>(() => {
+    <span class="kw">const</span> socket = <span class="fn">tryGetSocket</span>();
+    <span class="kw">if</span> (!socket) <span class="kw">return</span>;
+    <span class="kw">const</span> <span class="fn">onNew</span> = ({ message, tempId }: <span class="tp">NewMessageEvent</span>) =>
+      <span class="fn">setMessages</span>(prev => { <span class="kw">const</span> i = prev.<span class="fn">findIndex</span>(m => m.id === tempId); <span class="kw">if</span> (i !== -<span class="num">1</span>) { <span class="kw">const</span> n=[...prev]; n[i]=message; <span class="kw">return</span> n; } <span class="kw">return</span> [...prev,message]; });
+    <span class="kw">const</span> <span class="fn">onUpd</span> = ({ messageId, text: t, editedAt }: <span class="tp">MessageUpdatedEvent</span>) =>
+      <span class="fn">setMessages</span>(prev => prev.<span class="fn">map</span>(m => m.id===messageId ? {...m,content:{...m.content,text:t},isEdited:<span class="kw">true</span>,editedAt} : m));
+    <span class="kw">const</span> <span class="fn">onDel</span> = ({ messageId }: <span class="tp">MessageDeletedEvent</span>) =>
+      <span class="fn">setMessages</span>(prev => prev.<span class="fn">filter</span>(m => m.id !== messageId));
+    socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, onNew); socket.<span class="fn">on</span>(<span class="str">'message_updated'</span>, onUpd); socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, onDel);
+    <span class="kw">return</span> () => { socket.<span class="fn">off</span>(<span class="str">'new_message'</span>, onNew); socket.<span class="fn">off</span>(<span class="str">'message_updated'</span>, onUpd); socket.<span class="fn">off</span>(<span class="str">'message_deleted'</span>, onDel); };
+  }, [conversationId]);
+  <span class="cm">// 4. Mark read on focus</span>
+  <span class="fn">useFocusEffect</span>(<span class="fn">useCallback</span>(() => { socketEmit.<span class="fn">markRead</span>(conversationId); }, [conversationId]));
+  <span class="kw">const</span> <span class="fn">send</span> = <span class="kw">async</span> () => {
+    <span class="kw">if</span> (!text.trim()) <span class="kw">return</span>;
+    <span class="fn">setText</span>(<span class="str">''</span>); socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">false</span>);
+    <span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">text</span>: text.trim(), <span class="at">tempId</span>: <span class="fn">uuid</span>() });
+  };
+  <span class="kw">const</span> <span class="fn">onChangeText</span> = (val: <span class="tp">string</span>) => {
+    <span class="fn">setText</span>(val); socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">true</span>);
+    <span class="fn">clearTimeout</span>(timer.current);
+    timer.current = <span class="fn">setTimeout</span>(() => socketEmit.<span class="fn">typing</span>(conversationId, <span class="kw">false</span>), <span class="num">3000</span>);
+  };
+  <span class="kw">const</span> <span class="fn">loadMore</span> = <span class="kw">async</span> () => {
+    <span class="kw">if</span> (!hasMore) <span class="kw">return</span>;
+    <span class="kw">const</span> { data, meta } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(conversationId, { cursor, <span class="at">direction</span>:<span class="str">'before'</span>, <span class="at">limit</span>:<span class="num">30</span> });
+    <span class="fn">setMessages</span>(p => [...data, ...p]); <span class="fn">setCursor</span>(meta.nextCursor); <span class="fn">setHasMore</span>(meta.hasMore);
+  };
+  <span class="kw">return</span> (
+    &lt;View style={{ flex: <span class="num">1</span> }}&gt;
+      &lt;FlatList data={messages} keyExtractor={m => m.id}
+        onStartReached={loadMore}
+        renderItem={({ item }) => &lt;Text&gt;{item.content.text}&lt;/Text&gt;} /&gt;
+      &lt;TextInput value={text} onChangeText={onChangeText}/&gt;
+      &lt;Pressable onPress={send}&gt;&lt;Text&gt;Send&lt;/Text&gt;&lt;/Pressable&gt;
+    &lt;/View&gt;
+  );
+}</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { chatClient, setToken } <span class="kw">from</span> <span class="str">'./client'</span>;
+<span class="kw">import</span> { messagesApi, conversationsApi, socketEmit, getSocket } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { v4 <span class="kw">as</span> uuid } <span class="kw">from</span> <span class="str">'uuid'</span>;
+<span class="kw">async function</span> <span class="fn">main</span>() {
+  <span class="fn">setToken</span>(process.env.CHAT_TOKEN!);
+  <span class="kw">await</span> chatClient.<span class="fn">connect</span>();
+  <span class="kw">const</span> socket = <span class="fn">getSocket</span>();
+  <span class="cm">// Join a room and listen</span>
+  socketEmit.<span class="fn">joinRoom</span>(<span class="str">'conv-abc'</span>);
+  socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, ({ message }) => console.<span class="fn">log</span>(<span class="str">'new:'</span>, message.content.text));
+  <span class="cm">// Send a message</span>
+  <span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ <span class="at">conversationId</span>: <span class="str">'conv-abc'</span>, <span class="at">text</span>: <span class="str">'Hello from Node!'</span>, <span class="at">tempId</span>: <span class="fn">uuid</span>() });
+  <span class="cm">// Load recent messages</span>
+  <span class="kw">const</span> { data } = <span class="kw">await</span> messagesApi.<span class="fn">list</span>(<span class="str">'conv-abc'</span>, { <span class="at">limit</span>: <span class="num">20</span> });
+  console.<span class="fn">log</span>(<span class="str">'recent:'</span>, data.<span class="fn">map</span>(m => m.content.text));
+}
+<span class="fn">main</span>();</code></pre>
+  </div>
+</section>
+<!-- ─── STEP 19: UNREAD COUNTS ────────────────────────────────────────── -->
+<section id="step-unread" data-p="rn web node">
+  <h2><span class="step">STEP 19</span> Unread Message Counts</h2>
+  <p>
+    Unread counts come from two sources that work together:
+  </p>
+  <ul style="margin:0 0 16px 20px;color:#c8d0e0;font-size:14px;line-height:2">
+    <li><strong>REST API</strong> — accurate count from the database. Call this on app start, foreground resume, and socket reconnect.</li>
+    <li><strong>Socket events</strong> — real-time increments and resets while connected. The SDK handles these automatically; you only need to listen manually for side effects like badge counts.</li>
+  </ul>
+  <h3>REST APIs</h3>
+  <pre><code><span class="kw">import</span> { conversationsApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import type</span> { <span class="tp">UnreadSummary</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="cm">// Total unread + per-conversation breakdown
+// Use on cold start, foreground resume, and after socket reconnect</span>
+<span class="kw">const</span> summary: <span class="tp">UnreadSummary</span> = <span class="kw">await</span> conversationsApi.<span class="fn">getUnreadSummary</span>();
+<span class="cm">// summary.totalUnread      → 5
+// summary.byConversation   → [{ conversationId: '...', unreadCount: 3 }, ...]</span>
+<span class="cm">// Unread count for one specific conversation
+// Use after a push notification opens a specific chat</span>
+<span class="kw">const</span> { unreadCount } = <span class="kw">await</span> conversationsApi.<span class="fn">getUnreadCount</span>(conversationId);</code></pre>
+  <h3>When to use REST vs socket</h3>
+  <table style="width:100%;border-collapse:collapse;font-size:13px;margin:12px 0">
+    <thead><tr style="border-bottom:1px solid var(--border)">
+      <th style="text-align:left;padding:6px 10px;color:var(--muted)">Situation</th>
+      <th style="text-align:left;padding:6px 10px;color:var(--muted)">What to do</th>
+    </tr></thead>
+    <tbody>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">App cold start</td><td style="padding:6px 10px">Call <code>getUnreadSummary()</code> — hydrate before socket connects</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">App comes to foreground</td><td style="padding:6px 10px">Call <code>getUnreadSummary()</code> — catch up on messages received while backgrounded</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">Socket reconnects after drop</td><td style="padding:6px 10px">Call <code>getUnreadSummary()</code> — reconcile any drift during outage</td></tr>
+      <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px">Push notification opens a specific chat</td><td style="padding:6px 10px">Call <code>getUnreadCount(conversationId)</code> — refresh just that one</td></tr>
+      <tr><td style="padding:6px 10px">User is actively chatting (socket connected)</td><td style="padding:6px 10px">Use <code>conversation.unreadCount</code> from the list — socket keeps it live</td></tr>
+    </tbody>
+  </table>
+  <h3>Socket events (handled automatically by the SDK)</h3>
+  <p>
+    Both events go to the user's <strong>private room</strong> — all devices of the same user receive them simultaneously.
+    Reading on your phone automatically clears the badge on your browser tab.
+  </p>
+  <pre><code><span class="kw">import</span> { tryGetSocket } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> socket = <span class="fn">tryGetSocket</span>();
+<span class="cm">// Fires when a new message arrives in any of the user's conversations.
+// unreadCount is calculated server-side — always accurate, never optimistic.</span>
+socket?.<span class="fn">on</span>(<span class="str">'conversation_updated'</span>, ({ conversationId, unreadCount }) => {
+  <span class="cm">// SDK handles this automatically — useConversations() updates in real-time.</span>
+  <span class="cm">// Only listen here if you need a side effect (e.g. app badge).</span>
+});
+<span class="cm">// Fires when the user marks any conversation as read — on ALL their devices.
+// This is how reading on mobile clears the browser badge automatically.</span>
+socket?.<span class="fn">on</span>(<span class="str">'unread_count_changed'</span>, ({ conversationId, unreadCount }) => {
+  <span class="cm">// unreadCount is 0 — the conversation was just read.</span>
+});</code></pre>
+  <h3>Platform-specific badge updates</h3>
+  <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>;
+<span class="cm">// Keep badge in sync while app is active</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]);
+<span class="cm">// Refresh when app comes to foreground (socket may have been down)</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>) {
+      <span class="kw">const</span> { totalUnread } = <span class="kw">await</span> conversationsApi.<span class="fn">getUnreadSummary</span>();
+      Notifications.<span class="fn">setBadgeCountAsync</span>(totalUnread);
+    }
+  });
+  <span class="kw">return</span> () => sub.<span class="fn">remove</span>();
+}, []);</code></pre>
+  </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>
+<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>) {
+      conversationsApi.<span class="fn">getUnreadSummary</span>().<span class="fn">then</span>(({ totalUnread }) => {
+        document.title = totalUnread > <span class="num">0</span> ? <span class="str">`(${totalUnread}) Antz Chat`</span> : <span class="str">'Antz Chat'</span>;
+      });
+    }
+  }
+  document.<span class="fn">addEventListener</span>(<span class="str">'visibilitychange'</span>, onVisible);
+  <span class="kw">return</span> () => document.<span class="fn">removeEventListener</span>(<span class="str">'visibilitychange'</span>, onVisible);
+}, []);</code></pre>
+  </div>
+  <div data-p="node">
+    <pre><code><span class="cm">// Bot / server-side — check unread counts on startup</span>
+<span class="kw">const</span> summary = <span class="kw">await</span> conversationsApi.<span class="fn">getUnreadSummary</span>();
+console.<span class="fn">log</span>(<span class="str">`${summary.totalUnread} unread messages across ${summary.byConversation.length} conversations`</span>);</code></pre>
+  </div>
+</section>
+</main>
+<script>
+// ── State ────────────────────────────────────────────────────────────────
+let _platform = 'rn';
+let _mode = 'builtin';
+// ── Platform switch ──────────────────────────────────────────────────────
+function setPlatform(p) {
+  _platform = p;
+  document.querySelectorAll('.platform-btn').forEach(b => b.classList.toggle('active', b.dataset.platform === p));
+  document.getElementById('nav-platform-label').textContent =
+    p === 'rn' ? 'React Native' : p === 'web' ? 'React / Next.js' : 'Node.js';
+  applyGating();
+  localStorage.setItem('antz-platform', p);
+}
+// ── Mode switch ───────────────────────────────────────────────────────────
+function setMode(m) {
+  _mode = m;
+  document.querySelectorAll('.mode-opt').forEach(el => {
+    el.classList.toggle('sel', el.onclick?.toString().includes(`'${m}'`));
+  });
+  applyGating();
+  localStorage.setItem('antz-mode', m);
+}
+// ── Apply all gating ──────────────────────────────────────────────────────
+function applyGating() {
+  const p = _platform, m = _mode, pm = `${p}-${m}`;
+  // [data-p] — platform only
+  document.querySelectorAll('[data-p]').forEach(el => {
+    const ps = el.dataset.p.split(' ');
+    el.classList.toggle('pshow', ps.includes(p));
+  });
+  // [data-m] — mode only
+  document.querySelectorAll('[data-m]').forEach(el => {
+    el.classList.toggle('mshow', el.dataset.m === m);
+  });
+  // [data-pm] — platform+mode combo
+  document.querySelectorAll('[data-pm]').forEach(el => {
+    const pms = el.dataset.pm.split(' ');
+    el.classList.toggle('pmshow', pms.includes(pm));
+  });
+  // Sidebar nav items
+  document.querySelectorAll('li[data-nav]').forEach(el => {
+    const tag = el.dataset.nav;
+    let show = false;
+    if (tag === 'builtin') show = m === 'builtin';
+    else if (tag === 'external') show = m === 'external';
+    else if (tag === 'rn-web') show = p !== 'node';
+    el.classList.toggle('show', show);
+  });
+  // Push step — hide for node
+  const pushSection = document.getElementById('step-push');
+  if (pushSection) pushSection.style.display = p === 'node' ? 'none' : '';
+}
+// ── Init ──────────────────────────────────────────────────────────────────
+const savedP = localStorage.getItem('antz-platform') || 'rn';
+const savedM = localStorage.getItem('antz-mode') || 'external';
+// Fix mode-opt sel class based on saved value
+document.querySelectorAll('.mode-opt').forEach(el => {
+  const isSel = el.onclick?.toString().includes(`'${savedM}'`);
+  el.classList.toggle('sel', isSel);
+});
+_platform = savedP;
+_mode = savedM;
+document.querySelectorAll('.platform-btn').forEach(b => b.classList.toggle('active', b.dataset.platform === savedP));
+document.getElementById('nav-platform-label').textContent =
+  savedP === 'rn' ? 'React Native' : savedP === 'web' ? 'React / Next.js' : 'Node.js';
+applyGating();
+// ── Progress bar ──────────────────────────────────────────────────────────
+window.addEventListener('scroll', () => {
+  const el = document.getElementById('prog');
+  el.style.width = (window.scrollY / (document.body.scrollHeight - window.innerHeight) * 100) + '%';
+});
+// ── Sidebar active link ───────────────────────────────────────────────────
+new IntersectionObserver(entries => {
+  entries.forEach(e => {
+    if (e.isIntersecting) {
+      document.querySelectorAll('nav a').forEach(l => l.classList.remove('active'));
+      const a = document.querySelector(`nav a[href="#${e.target.id}"]`);
+      if (a) a.classList.add('active');
+    }
+  });
+}, { rootMargin: '-20% 0px -70% 0px' }).observe(...Array.from(document.querySelectorAll('section[id]')));
+// Fix: observe all sections
+document.querySelectorAll('section[id]').forEach(s => {
+  new IntersectionObserver(entries => {
+    entries.forEach(e => {
+      if (e.isIntersecting) {
+        document.querySelectorAll('nav a').forEach(l => l.classList.remove('active'));
+        const a = document.querySelector(`nav a[href="#${e.target.id}"]`);
+        if (a) a.classList.add('active');
+      }
+    });
+  }, { rootMargin: '-20% 0px -70% 0px' }).observe(s);
+});
+</script>
+</body>
+</html>