@kesha-antonov/react-native-chat 5.0.1 → 6.0.1

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@kesha-antonov/react-native-chat"><img alt="npm version" src="https://badge.fury.io/js/@kesha-antonov%2Freact-native-chat.svg"/></a>
   <a href="https://www.npmjs.com/package/@kesha-antonov/react-native-chat"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@kesha-antonov%2Freact-native-chat.svg"/></a>
-  <a href="https://npm-stat.com/charts.html?package=%40kesha-antonov%2Freact-native-chat&from=2015-01-01"><img alt="total npm downloads" src="https://img.shields.io/badge/total%20downloads-466-blue.svg"/></a>
+  <a href="https://npm-stat.com/charts.html?package=%40kesha-antonov%2Freact-native-chat&from=2015-01-01"><img alt="total npm downloads" src="https://img.shields.io/badge/total%20downloads-47.3k-blue.svg"/></a>
   <a href="https://www.npmjs.com/package/@kesha-antonov/react-native-chat"><img alt="npm downloads (last 18 months)" src="https://img.shields.io/npm/dt/@kesha-antonov%2Freact-native-chat.svg?label=18-months%20downloads"/></a>
   <a href="https://github.com/kesha-antonov/react-native-chat/actions/workflows/main.yml"><img src="https://github.com/kesha-antonov/react-native-chat/actions/workflows/main.yml/badge.svg" alt="build"></a>
   <img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Web-lightgrey.svg" alt="platforms">
@@ -16,7 +16,7 @@
 </p>
 
 <p align="center">
-  <img width="300" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/streaming-demo.gif" alt="Streaming AI reply rendering markdown token by token" />
+  <img width="300" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/showcase.gif" alt="Chat list, photo viewer, reactions, swipe-to-reply, emoji keyboard, photo attachments, a voice note, a streamed AI reply and swipe-to-archive" />
 </p>
 
 <p align="center">
@@ -44,6 +44,17 @@
   <sub>Using it in production? A ⭐ helps other developers find the library.</sub>
 </p>
 
+<!-- cryptoc-promo:start -->
+<hr />
+
+<h2 align="center">Sponsors</h2>
+
+<p align="center">
+  <a href="https://getstream.io/chat/sdk/react-native/?utm_source=github&utm_medium=sponsor&utm_campaign=keshaantonov&utm_term=react-native-chat"><img width="100" height="100" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/getstream-sponsor-logo.png" alt="Stream" /></a>
+  <br />
+  <a href="https://getstream.io/chat/sdk/react-native/?utm_source=github&utm_medium=sponsor&utm_campaign=keshaantonov&utm_term=react-native-chat"><strong>Stream</strong></a> - React Native Chat SDK
+</p>
+
 <hr />
 
 <table align="center">
@@ -55,8 +66,10 @@
   <br />
   <sub>Scan to install</sub>
   <br /><br />
+  <!-- App Store button hidden for now
   <a href="https://apps.apple.com/app/cryptoc/id1333169178"><img height="40" src="https://cryptoc-app.web.app/img/appstore.svg?v=2" alt="Download on the App Store" /></a>
   <br />
+  -->
   <a href="https://play.google.com/store/apps/details?id=co.ssoul.CryptoC"><img height="59" src="https://cryptoc-app.web.app/img/googleplay.png?v=2" alt="Get it on Google Play" /></a>
 </td>
 <td valign="top">
@@ -78,6 +91,7 @@
 </table>
 
 <hr />
+<!-- cryptoc-promo:end -->
 
 ## Quick start
 
@@ -113,14 +127,23 @@ That is the whole setup - everything below is optional.
 
 ## ✨ Features
 
+- 💬 **[Chat list](#chat-list)** - the list of chats with search, selection actions, archive, swipe to archive and draggable pinned chats; plug in your backend
 - 🌗 **[Dark mode & theming](#theming--dark-mode)** - full light/dark token system, switchable at runtime
 - 🤖 **[Streaming AI messages](#streaming-ai-messages)** - token-by-token replies with a typing caret and stop control
 - 😀 **[Emoji reactions](#emoji-reactions)** - long-press picker and reaction pills
+- ⌨️ **[Emoji keyboard](#emoji-keyboard-and-attachment-menu)** - a full emoji panel in the keyboard's place, with search, recents and skin tones
+- 📎 **[Attachment menu](#emoji-keyboard-and-attachment-menu)** - photo grid with numbered selection and a caption, files and location
 - 🎥 **[Video & audio messages](#-whats-new-vs-react-native-gifted-chat)** - real inline playback, with a tappable fallback
-- 🎙️ **[Voice & video recording](#-whats-new-vs-react-native-gifted-chat)** - Telegram-style hold-to-record notes (opt-in)
+- 🖼️ **[Photo viewer](#message-bubbles--content)** - tap a photo, then swipe through every photo in the chat; pinch or double-tap to zoom
+- 🎙️ **[Voice & video recording](#-whats-new-vs-react-native-gifted-chat)** - hold-to-record voice and round video notes, on once their peers are installed
+- 👋 **[Empty chat greeting](#messages--message-container)** - a "No messages here yet..." card with a tap-to-send 👋
+- 😍 **[Big emoji](#theming--dark-mode)** - emoji-only messages drop the bubble and draw large
+- 🔵 **[Unread bar](#messages--message-container)** - "Unread Messages" above the first unread message, opened scrolled to it
+- 🔗 **[Link previews](#message-bubbles--content)** - a web page block under the text
+- ☑️ **[Multi-select](#message-bubbles--content)** - "Select" in the long-press menu: check circles, Copy / Forward / Delete bar
 - 📍 **[Location messages](#-whats-new-vs-react-native-gifted-chat)** - map card that opens the system maps app
 - ↩️ **[Swipe to reply](#reply-to-messages)** - reply preview and message threading
-- 📋 **[Long-press actions](#message-actions-long-press-context-menu)** - themed context menu anchored to the bubble
+- 📋 **[Long-press actions](#message-actions-long-press-context-menu)** - a context menu beside the finger, with a reactions bar
 - ⚡ **[Quick replies](#quick-replies)** - bot-style reply buttons
 - 🔗 **[Smart link parsing](#smart-link-parsing)** - URLs, emails, phones, hashtags, mentions
 - 👤 **[Avatars](#avatars)** - user initials or custom images
@@ -138,11 +161,23 @@ That is the whole setup - everything below is optional.
 Actively maintained, New Architecture ready, built for the latest Reanimated / Gesture Handler.
 
 <p align="center">
-  <img width="200" src="https://github.com/user-attachments/assets/c9da88f5-0b20-471c-8cd7-373bdb767517" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img width="200" src="https://github.com/user-attachments/assets/f72b17f1-6c2e-43b5-87e7-477011aa3b07" />
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img width="200" src="https://github.com/user-attachments/assets/86711e73-ee3c-4527-b38d-e4dab47a44fe" />
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/chat-list-light.png" alt="Chat list with unread badges, pins, mutes and swipe-to-archive" />
+  &nbsp;&nbsp;
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/group-chat-light.png" alt="Group chat with names, avatars, a photo, a file, a reply and reactions" />
+  &nbsp;&nbsp;
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/group-chat-dark.png" alt="The same group chat in the dark theme" />
+</p>
+
+<p align="center">
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/emoji-keyboard.png" alt="Built-in emoji keyboard in place of the system keyboard" />
+  &nbsp;&nbsp;
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/attachment-sheet.png" alt="Attachment menu with the photo grid, two photos picked and a caption field" />
+  &nbsp;&nbsp;
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/link-preview-big-emoji.png" alt="Link preview cards and an emoji-only message shown large" />
+</p>
+
+<p align="center">
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/chat-list-dark.png" alt="Chat list in the dark theme" />
 </p>
 
 ---
@@ -157,16 +192,19 @@ Kept in sync with upstream [`react-native-gifted-chat`](https://github.com/Farid
 | Added in this fork | react-native-gifted-chat | @kesha-antonov/react-native-chat |
 | --- | :---: | :---: |
 | Active maintenance | 💤 sporadic | ✅ active |
-| Modern default UI (Telegram-inspired) | dated 2020 look | ✅ modern, fully overridable |
+| Modern default UI (modern messenger look) | dated 2020 look | ✅ wallpaper, tails, inline time, fully overridable |
 | Light/Dark **theme system** | per-component color props | ✅ `theme` / `darkTheme` tokens, runtime switch |
 | Streaming (AI) messages | ❌ | ✅ token-by-token + typing cursor |
 | Emoji reactions | ❌ | ✅ long-press picker + reaction pills |
+| Emoji keyboard | ❌ | ✅ built in: tabs, search, recents, skin tones |
+| Attachment menu | ❌ (`actions` sheet) | ✅ built in: photo grid + caption, files, location |
+| File messages | ❌ | ✅ `IMessage.file` document bubble |
 | Swipe-to-reply + reply preview | ❌ | ✅ built in |
 | **Video / audio messages** | "not implemented, render your own" | ✅ inline players + tappable fallback |
-| **Voice notes** (hold-to-record + waveform) | ❌ | ✅ optional, Telegram-style |
-| **Video messages** (round camera notes) | ❌ | ✅ optional, Telegram-style |
+| **Voice notes** (hold-to-record + waveform) | ❌ | ✅ optional |
+| **Video messages** (round camera notes) | ❌ | ✅ optional |
 | **Location messages** | ❌ ignored | ✅ map card → opens system maps |
-| Bubble tails + tighter message grouping | flat bubbles | ✅ |
+| Bubble tails, inline time + run grouping | flat bubbles | ✅ |
 
 </details>
 
@@ -189,12 +227,14 @@ Kept in sync with upstream [`react-native-gifted-chat`](https://github.com/Farid
 ### Voice, video and location
 
 <details>
-<summary><strong>Opt-in recording and media playback</strong></summary>
+<summary><strong>Recording and media playback</strong></summary>
+
+Voice notes (`expo-audio`) and round video notes (`react-native-vision-camera`) turn on by themselves once their peers are installed: the mic button records on hold, and a tap switches it to the camera. Pass `false` to turn either off.
 
 ```jsx
 <Chat
-  audioRecording={{ isEnabled: true }}   // hold the mic to record a voice note (needs expo-audio)
-  videoRecording={{ isEnabled: true }}   // record a video message (needs expo-image-picker)
+  videoRecording={{ maxDuration: 30 }}   // optional: configure; `false` turns round notes off
+  mediaPlayback={{ playbackRate: 1.5 }}  // optional: start notes at 1.5x, auto-play the next note
   // location messages render automatically for any IMessage with a `location`
   {...props}
 />
@@ -203,8 +243,82 @@ Kept in sync with upstream [`react-native-gifted-chat`](https://github.com/Farid
 ```bash
 # Optional inline media playback + recording:
 npx expo install expo-video expo-audio expo-image-picker
+# Optional: round video notes and the voice-note waveform
+# (vision-camera 5+, which runs on Nitro and needs its two Nitro packages too)
+npx expo install react-native-vision-camera react-native-nitro-modules react-native-nitro-image react-native-audio-api react-native-svg expo-haptics
+# Optional: trim paused voice takes, blur behind the round-video camera
+npx expo install expo-file-system expo-blur
+```
+
+Recording and playback work like this:
+
+- **Hold** the record button to record, release to send. With both voice and video enabled, a **tap** switches it between mic and camera, and the choice is remembered. With only video, the camera sits in the record button's place.
+- **Slide left** to cancel: all the way across cancels at once; releasing past about half the way cancels too. **Slide up** to lock and keep recording hands-free. The two exclude each other: no lock once the cancel slide is under way. "Slide up to lock" is shown for the first few takes.
+- **Locked**, the bar shows a `m:ss,t` timer and a CANCEL button, and the lock turns into a **pause** button.
+- A paused **voice** take turns into a preview: its waveform with play, to send or delete. The mic above send **resumes** recording onto its end, and the handles at either end of the waveform **trim** it. Resuming needs `react-native-audio-api`; trimming also needs `expo-file-system`, and a trimmed take is sent as a WAV.
+- A paused **round video** take holds the recording open: the circle shows the frame it paused on (Android; iOS keeps the live camera, dimmed), the bar offers delete and send, and the camera above send **resumes** into the same video. Round takes can't be trimmed.
+- A round note records on the first hold, with the camera drawn over a blurred chat (when `expo-blur` is installed). Switch camera and flash work while recording (the screen lights up for the front camera, the torch for the back one), and you can pinch to zoom. At its 60s limit the take stops into a looping preview (tap to hear it) instead of sending.
+- Haptic ticks on start, stop, lock and mode switch when `expo-haptics` is installed.
+- Starting a recording pauses any note that is playing.
+- Only one note plays at a time. When a voice or round video note plays to its end, the next newer one in the chat starts.
+- While a note plays or is paused, a "now playing" bar at the top of the chat has play/pause, the sender, the speed (1x / 1.5x / 2x; long-press for more, shared by every note) and close; a tap on the title scrolls to the note.
+- Round notes rest in the list on their first frame with a play button (or loop silently with `isRoundVideoAutoplayEnabled`). A tap plays one from the start with sound and grows it, hiding the sender's avatar; a tap pauses it, and a paused note can be scrubbed by dragging around its ring. Its length, in a pill at its bottom-left, counts down while it plays, and playing bars replace its unread dot once it is heard.
+- Set `isMediaUnread` on a message for the unread dot; `mediaPlayback.onMediaRead` reports when an incoming one is played.
+
+</details>
+
+### Emoji keyboard and attachment menu
+
+<details>
+<summary><strong>Built in, on by default</strong></summary>
+
+The composer's emoji button opens the built-in emoji keyboard in the system keyboard's place - at the last keyboard height, so switching between the two keeps the composer still. It has the category tabs, search (scroll the grid up to reveal it), recents by use count, a skin-tone popup on long-press and a repeating backspace. A tap inserts at the caret whether or not you control `text`.
+
+The paperclip opens the built-in attachment menu: your newest photos in a 3-column grid (with `expo-media-library`), numbered as you pick them, a caption and a "Send N" button; File and Location tabs; a camera tile. Picks arrive in `onSend` as ordinary messages - `image`, `video`, `file` (`{ uri, name, size?, mimeType? }`) or `location` - so there is nothing to wire.
+
+```bash
+# Each tab shows only when its package is installed:
+npx expo install expo-media-library expo-image-picker expo-document-picker expo-location
+# Optional: keep emoji recents across launches, share received files, fast ph:// thumbnails
+npx expo install @react-native-async-storage/async-storage expo-sharing expo-image
+```
+
+```tsx
+<Chat
+  emojiKeyboard={{ columns: 8, recents: { storageKey: 'my-app/emoji' } }}
+  attachments={{
+    tabs: ['gallery', 'file'],
+    // Upload first, then send what your backend returns (or `null` to send nothing).
+    onPick: async (picked, { caption }) => upload(picked, caption),
+  }}
+  {...props}
+/>
+```
+
+Hide either with `emojiKeyboard={false}` / `attachments={false}`. `onPressEmoji` replaces the emoji keyboard and `actions` / `onPressActionButton` / `renderActions` replace the attachment menu, as before.
+
+**Permissions.** iOS kills an app that asks for a permission without a usage string. In Expo, list the plugins with your own strings (the defaults are generic):
+
+```json
+"plugins": [
+  ["expo-image-picker", { "photosPermission": "...", "cameraPermission": "..." }],
+  ["expo-media-library", { "photosPermission": "...", "savePhotosPermission": "...", "granularPermissions": ["photo", "video"] }],
+  ["expo-location", { "locationWhenInUsePermission": "..." }],
+  "expo-document-picker",
+  "expo-sharing"
+]
 ```
 
+In a bare app add the keys yourself, then rebuild the native app:
+
+| Package | iOS `Info.plist` | Android manifest |
+|---|---|---|
+| `expo-media-library` | `NSPhotoLibraryUsageDescription` (`NSPhotoLibraryAddUsageDescription` to save) | `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO` (`READ_EXTERNAL_STORAGE` below Android 13) |
+| `expo-image-picker` | `NSPhotoLibraryUsageDescription`, `NSCameraUsageDescription` (`NSMicrophoneUsageDescription` for video) | `CAMERA` (and `RECORD_AUDIO` for video) |
+| `expo-location` | `NSLocationWhenInUseUsageDescription` | `ACCESS_COARSE_LOCATION`, `ACCESS_FINE_LOCATION` |
+| `expo-document-picker` | none (iCloud documents need the iCloud entitlement) | none |
+| `expo-sharing` | none | none |
+
 </details>
 
 ### Custom icons (e.g. Lucide)
@@ -260,6 +374,7 @@ Overridable names: `send`, `mic`, `camera`, `play`, `pause`, `check`, `checkAll`
 - [Data Structure](#-data-structure)
 - [Props Reference](#-props-reference)
 - [Guides](#-guides)
+  - [Chat List](#chat-list)
   - [Reply to Messages](#reply-to-messages)
   - [Maintaining Scroll Position (AI Chatbots)](#maintaining-scroll-position-ai-chatbots)
   - [Streaming (AI) Messages](#streaming-ai-messages)
@@ -270,6 +385,7 @@ Overridable names: `send`, `mic`, `camera`, `play`, `pause`, `check`, `checkAll`
   - [Localization (i18n)](#localization-i18n)
   - [Message Status](#message-status)
   - [TypeScript](#typescript)
+  - [Building blocks](#building-blocks)
 - [Platform Notes](#-platform-notes)
 - [Performance](#-performance)
 - [Testing](#-testing)
@@ -283,9 +399,11 @@ Overridable names: `send`, `mic`, `camera`, `play`, `pause`, `check`, `checkAll`
 
 ## 📋 Requirements
 
-| React Native | iOS | Android | Expo | TypeScript |
-|---|---|---|---|---|
-| >= 0.70.0 | >= 13.4 | API 21+ (5.0) | SDK 50+ | >= 5.0 (optional) |
+| React Native | React | iOS | Android | Expo | TypeScript |
+|---|---|---|---|---|---|
+| >= 0.82.0 | >= 19 | >= 15.1 | API 24+ (7.0) | SDK 55+ | >= 5.0 (optional) |
+
+The floor comes from `react-native-gesture-handler` 3, which the library is built on (3.0+ is required; it supports React Native 0.82 and newer). The example app runs Expo SDK 58 with React Native 0.88.
 
 ---
 
@@ -302,26 +420,51 @@ npx expo install @kesha-antonov/react-native-chat react-native-reanimated react-
 <details>
 <summary><strong>Three steps</strong></summary>
 
-**1.** Install the packages:
+**1.** Install the packages. Reanimated 4 also needs `react-native-worklets`; leave it out on Reanimated 3:
 
 ```bash
-yarn add @kesha-antonov/react-native-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
+yarn add @kesha-antonov/react-native-chat react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
 ```
 
 ```bash
-npm install --save @kesha-antonov/react-native-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
+npm install --save @kesha-antonov/react-native-chat react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
 ```
 
-**2.** Install iOS pods:
+**2.** Add the worklets Babel plugin as the last entry in `babel.config.js` - `react-native-worklets/plugin` on Reanimated 4, `react-native-reanimated/plugin` on Reanimated 3 - following the [react-native-reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/).
+
+**3.** Install iOS pods, then **rebuild the native app** (`npx react-native run-ios` / `run-android`) and restart Metro with `--reset-cache`. every peer above ships native code, so reloading the JS bundle alone is not enough:
 
 ```bash
 npx pod-install
 ```
 
-**3.** Add Reanimated's Babel plugin, following the [react-native-reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#step-2-add-reanimateds-babel-plugin).
-
 </details>
 
+### Optional peers
+
+Every feature below turns itself on when its package is installed and stays hidden when it is not - there is nothing to configure. `getChatCapabilities()` reports what the current install can do, e.g. to build UI that matches the chat's. In development, a feature that was asked for but cannot work (say `audioRecording={{ isEnabled: true }}` without `expo-audio`) logs one hint.
+
+| Package | Feature | `getChatCapabilities()` key |
+|---|---|---|
+| `expo-clipboard` or `@react-native-clipboard/clipboard` | "Copy" in the long-press menu | `clipboard` |
+| `expo-haptics` | Haptic ticks (long-press, swipe-to-reply, recording) | `haptics` |
+| `expo-blur` | Blurred backdrop behind the menu and the round video recorder | `blur` |
+| `react-native-svg` | Lucide icons and vector rings | `svg` |
+| `expo-audio` | Voice playback and hold-to-record voice notes | `audioPlayback`, `voiceRecording` |
+| `react-native-audio-api` | Voice waveforms, resume and trim | `waveform` |
+| `expo-video` | Inline video and round video notes | `videoPlayback` |
+| `react-native-vision-camera` 5 | In-chat round video capture | `roundVideoCapture` |
+| `expo-image-picker` | System camera fallback for video notes | `videoRecording` |
+| `react-native-streamdown` | Rich streaming markdown | `markdown` |
+| `@lodev09/react-native-true-sheet` | Native attachment sheet | `nativeSheet` |
+| `expo-media-library` | The attachment menu's photo grid | `mediaLibrary` |
+| `expo-image-picker` | The attachment menu's system photo picker and camera | `imagePicker` |
+| `expo-document-picker` | The attachment menu's File tab | `documentPicker` |
+| `expo-location` | The attachment menu's Location tab | `location` |
+| `expo-sharing` | Opening a received file in the share sheet (otherwise `Linking`) | `sharing` |
+| `@react-native-async-storage/async-storage` | Emoji recents and skin tones kept across launches | `persistentEmojiRecents` |
+| `expo-image` | Gallery thumbnails straight from the photo library | - |
+
 ---
 
 ## 🔄 Migrating from react-native-gifted-chat
@@ -370,14 +513,37 @@ interface IMessage {
   createdAt: Date | number
   user: User
   image?: string
+  /** Tiny stand-in drawn blurred under `image` until it loads: a small image uri, or a blurhash with expo-image */
+  imagePlaceholder?: string
   video?: string
+  /** Render `video` as a round video note */
+  videoNote?: boolean
   audio?: string
+  /** Length of `audio` / `video` in seconds */
+  duration?: number
+  /** The voice or round note has not been played by its recipient yet (unread dot) */
+  isMediaUnread?: boolean
+  /** View-once voice or round note: plays a single time, then `mediaPlayback.onViewOnceEnd` fires */
+  isViewOnce?: boolean
+  /** Transcribed text of a voice or round note, shown under it via the transcribe button */
+  transcription?: string
   system?: boolean
   sent?: boolean
   received?: boolean
   pending?: boolean
+  /** Sending failed: a red badge replaces the checks */
+  isFailed?: boolean
+  /** The message was edited: its time reads "edited 14:05" */
+  isEdited?: boolean
+  editedAt?: Date | number
   /** True while the text is still streaming in (shows a typing cursor) */
   streaming?: boolean
+  /** Media uploading or downloading: a progress ring with a cancel ✕ ({ type: 'upload' | 'download', progress?, totalBytes? }) */
+  transfer?: MediaTransfer
+  /** Media not fetched by itself: a download arrow, which calls `mediaTransfer.onDownload` */
+  isDownloadRequired?: boolean
+  /** A voice note's waveform from the server (0..1, or 0..31 integers), drawn before the audio downloads */
+  waveform?: number[]
   quickReplies?: QuickReplies
   replyMessage?: ReplyMessage
   reactions?: MessageReaction[]
@@ -385,6 +551,24 @@ interface IMessage {
     latitude: number
     longitude: number
   }
+  /** A document: a file bubble (icon, name, size); a tap opens it */
+  file?: {
+    uri: string
+    name: string
+    size?: number
+    mimeType?: string
+  }
+  /** A web page preview under the text (or fetched via `fetchLinkPreview`); `null` hides it */
+  linkPreview?: {
+    url?: string
+    siteName?: string
+    title?: string
+    description?: string
+    image?: string
+    imageWidth?: number
+    imageHeight?: number
+    imageSize?: 'large' | 'small'
+  } | null
 }
 
 interface ReplyMessage {
@@ -426,14 +610,15 @@ Every group below is collapsed - open the one you need.
 - **`messageIdGenerator`** _(Function)_ - Generate an id for new messages. Defaults to a simple random string generator.
 - **`locale`** _(String)_ - Locale to localize the dates. You need first to import the locale you need (ie. `require('dayjs/locale/de')` or `import 'dayjs/locale/fr'`)
 - **`colorScheme`** _('light' | 'dark')_ - Force color scheme (light/dark mode). When set to `'light'` or `'dark'`, it overrides the system color scheme. When `undefined`, it uses the system color scheme. Default is `undefined`.
-- **`theme`** _(Object)_ - Override the default light theme tokens (`colors` / `radii` / `spacing` / `typography` / `avatar` / `sendButton` / `composer` / `voice`). Deep-merged over `defaultLightTheme`; any subset is allowed. See [Theming & Dark Mode](#theming--dark-mode).
+- **`theme`** _(Object)_ - Override the default light theme tokens (`colors` / `radii` / `spacing` / `typography` / `avatar` / `sendButton` / `composer` / `voice` / `bubble` / `wallpaper` / `nameColors`). Deep-merged over `defaultLightTheme`; any subset is allowed. See [Theming & Dark Mode](#theming--dark-mode).
+- **`renderWallpaper`** _(Function | null)_ - The chat background. By default `Chat` draws a swirl gradient from `theme.wallpaper`, turning one step per message you send. Return your own element (an image, `ChatWallpaper` with other props...) to replace it, or pass `null` for the plain `theme.colors.background`.
 - **`darkTheme`** _(Object)_ - Same as `theme`, applied when the resolved color scheme is dark (deep-merged over `defaultDarkTheme`).
 - **`icons`** _(Object)_ - Icon override registry. Supply a render function for any built-in icon to replace it (e.g. with `lucide-react-native`). See [Custom icons](#custom-icons-eg-lucide).
 - **`labels`** _(Object)_ - Override any UI string. See [Localization (i18n)](#localization-i18n).
 
 ### Refs
 
-- **`messagesContainerRef`** _(FlatList ref)_ - Ref to the flatlist
+- **`messagesContainerRef`** _(`LegendListRef`)_ - Ref to the message list, a [Legend List](https://legendapp.com/open-source/list/) ref: `scrollToEnd`, `scrollToKey` (keys are message `_id`s as strings), `scrollToIndex`, `getState`. Indexes count from the oldest message
 - **`textInputRef`** _(TextInput ref)_ - Ref to the text input
 
 </details>
@@ -449,7 +634,7 @@ Every group below is collapsed - open the one you need.
 - **`enableKeyboardProvider`** _(Bool)_ - Render the built-in `KeyboardProvider`; default is `true`. You do **not** need to turn this off just because your app mounts its own provider - that case is detected and reused. Set it to `false` only to opt out completely, e.g. when the provider's edge-to-edge behavior causes layout shift or a header jump on Android/Expo.
 - **`enableGestureHandlerRootView`** _(Bool)_ - Render the `GestureHandlerRootView` Chat mounts around itself; default is `true`. Unlike `KeyboardProvider`, an existing one can't be auto-detected - `react-native-gesture-handler` doesn't expose that publicly - so set this to `false` yourself if your app (or a library it uses, e.g. a bottom sheet) already mounts one at the root. Nesting a second one changes the native view hierarchy around the composer, which has been observed to make a rare Fabric/Yoga layout assertion on iOS more likely, especially when Chat is mounted and unmounted while the keyboard is open ([#17](https://github.com/kesha-antonov/react-native-chat/issues/17)).
 - **`keyboardAvoidingViewProps`** _(Object)_ - Props to be passed to the [`KeyboardAvoidingView`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/components/keyboard-avoiding-view). See **keyboardVerticalOffset** below for proper keyboard handling.
-- **`isAlignedTop`** _(`boolean | 'auto'`)_ - Where the bubbles sit **while the whole conversation fits on screen**; once it is taller than the list this has no effect. `false` (default) keeps the usual bottom-anchored chat, `true` pins the messages to the top, and `'auto'` pins them to the top while the keyboard is closed and re-anchors them to the bottom while it is open - so a short conversation starts under the header and moves above the keyboard when the composer is focused ([#2736](https://github.com/FaridSafi/react-native-gifted-chat/issues/2736)). Works with either `isInverted` setting; ignored when `isFlashListEnabled` is set, since FlashList positions its own items.
+- **`isAlignedTop`** _(`boolean | 'auto'`)_ - Where the bubbles sit **while the whole conversation fits on screen**; once it is taller than the list this has no effect. `false` (default) keeps the usual bottom-anchored chat, `true` pins the messages to the top, and `'auto'` pins them to the top while the keyboard is closed and re-anchors them to the bottom while it is open - so a short conversation starts under the header and moves above the keyboard when the composer is focused ([#2736](https://github.com/FaridSafi/react-native-gifted-chat/issues/2736)). Works with either `isInverted` setting.
 - **`isInverted`** _(Bool)_ - Reverses display order of `messages`; default is `true`
 
 #### Understanding `keyboardVerticalOffset`
@@ -477,6 +662,7 @@ If you do, sanity-check it on device: a toolbar behind the keyboard means the va
 
 - **`text`** _(String)_ - Input text; default is `undefined`, but if specified, it will override Chat's internal state. Useful for managing text state outside of Chat (e.g. with Redux). Don't forget to implement `textInputProps.onChangeText` to update the text state.
 - **`initialText`** _(String)_ - Initial text to display in the input field
+- **`onDraftChange`** _(Function)_ - `(draft: string) => void`, the user's unsent text as it changes (`''` once sent). Editing a message sets the draft aside and brings it back afterwards, without reporting the edited text. Save it with the chat and pass it back as `initialText`
 - **`isSendButtonAlwaysVisible`** _(Bool)_ - Always show send button in input text composer; default `false`, show only when text input is not empty
 - **`isTextOptional`** _(Bool)_ - Allow sending messages without text (useful for media-only messages); default `false`. Use with `isSendButtonAlwaysVisible` for media attachments.
 - **`isMultiline`** _(Bool)_ - Whether the composer accepts multiple lines; default `true`. With `true` the return key inserts a newline and you send with the send button. Set `false` for a single-line composer whose **return key sends the message** (the keyboard's return key becomes "send" and stays open afterwards).
@@ -485,16 +671,19 @@ If you do, sanity-check it on device: a toolbar behind the keyboard means the va
 - **`renderSend`** _(Component | Function)_ - Custom send button; you can pass children to the original `Send` component quite easily, for example, to use a custom icon ([example](https://github.com/kesha-antonov/react-native-chat/pull/487))
 - **`renderActions`** _(Component | Function)_ - Custom action button on the left of the message composer
 - **`renderAccessory`** _(Component | Function)_ - Custom second line of actions below the message composer
-- **`onPressEmoji`** _(Function)_ - Callback for the optional emoji button on the left of the composer field. When omitted, the emoji button is hidden.
-- **`audioRecording`** _(Object)_ - Enable Telegram-style hold-to-record voice notes. `{ isEnabled, minDurationMs?, onError? }`. Requires the optional `expo-audio` peer (and `react-native-audio-api` for the playback waveform); the mic button is hidden when it is absent.
-- **`videoRecording`** _(Object)_ - Enable record-and-send video messages. `{ isEnabled, maxDuration?, onError? }`. Uses `react-native-vision-camera` for round camera notes, falling back to `expo-image-picker`'s system camera.
+- **`emojiKeyboard`** _(Bool | Object)_ - The built-in emoji keyboard behind the composer's emoji button, on by default. It opens in the system keyboard's place at the last keyboard height (200 + the bottom inset before a keyboard was seen) and inserts at the caret, whether or not you control `text`. `false` hides the emoji button. An object configures it: `{ isEnabled?, columns?, categories?, recents?, isSearchEnabled?, renderEmojiKeyboard? }` - `columns` fixes the column count (default: as many 45pt columns as fit); `categories` picks and orders the tabs (`'smileys' | 'animals' | 'food' | 'activities' | 'travel' | 'objects' | 'symbols' | 'flags'`); `recents` is `false` or `{ isEnabled?, storageKey?, isPersisted? }` (persisted through `@react-native-async-storage/async-storage` when installed); `isSearchEnabled` (default `true`); `renderEmojiKeyboard({ onSelect, onBackspace, onClose, height, bottomInset })` draws your own keyboard in the panel. Colors and sizes live in `theme.emojiKeyboard`.
+- **`onPressEmoji`** _(Function)_ - Called when the emoji button is pressed, instead of opening the built-in emoji keyboard. Passing it shows the button even with `emojiKeyboard={false}`.
+- **`audioRecording`** _(Bool | Object)_ - Hold-to-record voice notes, **on by default when `expo-audio` is installed**; `false` (or `{ isEnabled: false }`) turns them off. An object configures them: `{ isEnabled?, minDurationMs?, maxDurationMs?, isViewOnceEnabled?, onPermissionDenied?, onTooShort?, onError? }`. `isViewOnceEnabled` shows a view-once toggle above the pause button while a take is locked or paused; a take sent with it on reaches `onSend` with `isViewOnce: true`. `minDurationMs` (default 700) drops takes that long or shorter and calls `onTooShort`; `maxDurationMs` (default 600000) sends the take when reached. Requires the optional `expo-audio` peer (and `react-native-audio-api` for the playback waveform); the mic button is hidden when it is absent. A paused take can be resumed when `react-native-audio-api` is installed with FFmpeg (the M4A recordings are joined without re-encoding), and trimmed when `expo-file-system` is installed too; a trimmed take reaches `onSend` as a 16-bit mono WAV at 24kHz, an untrimmed one as the recorder's M4A.
+- **`videoRecording`** _(Bool | Object)_ - Round video notes, **on by default when `react-native-vision-camera` is installed**; `false` (or `{ isEnabled: false }`) turns them off. `true` / `{ isEnabled: true }` also offers the system-camera fallback below when vision-camera is missing. An object configures them: `{ isEnabled?, maxDuration?, minDurationMs?, isViewOnceEnabled?, onPermissionDenied?, onTooShort?, onError? }`. `maxDuration` is in seconds (default 60); `minDurationMs` (default 800) drops shorter takes and calls `onTooShort`; `isViewOnceEnabled` works as in `audioRecording`, for round notes recorded with vision-camera. With `react-native-vision-camera` 5 or newer linked (plus its `react-native-nitro-modules` and `react-native-nitro-image` peers; it has no Expo config plugin, so add `NSCameraUsageDescription`/`NSMicrophoneUsageDescription` and the `CAMERA`/`RECORD_AUDIO` permissions yourself), the record button records a note on the first hold - shared with voice notes when both are enabled, on its own otherwise. Reaching `maxDuration` stops into a preview (sends directly without `expo-video`). Without vision-camera it falls back to `expo-image-picker`'s system camera, which sends a plain (non-round) video.
+- **`mediaPlayback`** _(Object)_ - How voice and round video notes play. `{ isAutoPlayNextEnabled?, playbackRate?, onPlaybackRateChange?, isRoundVideoAutoplayEnabled?, isNowPlayingBarEnabled?, isFloatingRoundNoteEnabled?, onMediaRead?, isNearEar?, onTranscribe?, onViewOnceEnd? }`. `isNowPlayingBarEnabled` (default `true`) shows a "now playing" bar at the top of the chat while a note plays or is paused. `isFloatingRoundNoteEnabled` (default `true`) keeps a round note that is playing or paused going in a small draggable circle over the list once its row scrolls out of view; set it to `false` to stop the note with its row instead. `isAutoPlayNextEnabled` (default `true`) starts the next newer voice or round note in the chat when one plays to its end. The playback speed is shared by every note; `playbackRate` sets it, and `onPlaybackRateChange` reports changes so the app can keep the speed across launches. `isRoundVideoAutoplayEnabled` (default `false`) loops round notes silently in the list instead of holding their first frame. `onMediaRead(message)` is called when an incoming note with `isMediaUnread` starts playing, so the app can mark it listened. `isNearEar` is raise to listen: feed it from the app's proximity sensor, and while it is `true` the current voice or round note plays through the earpiece (restarting if it was under a second in); when it goes back to `false` the note pauses and the speaker route returns. `onTranscribe(message)` shows a transcribe button on voice notes and beside round notes; tapping it calls this, shows a loading outline until the app sets `message.transcription`, then opens the text under the waveform, or in a bubble under the round note (tap again to collapse or expand). `onViewOnceEnd(message)` is called once a view-once note (`isViewOnce`) has played to its end or been stopped after starting, so the app can remove it. A view-once round note carries the "1" marker on its play button, never autoplays or floats, and cannot be scrubbed.
 - **`textInputProps`** _(Object)_ - props to be passed to the [`<TextInput>`](https://reactnative.dev/docs/textinput).
 
 > **Composer height** - there are no height props. The composer starts one line tall and grows with its content. Constrain it through `textInputProps.style` (e.g. `{ maxHeight: 120 }`), which is applied after the measured height and wins.
 
 ### Actions & Action Sheet
 
-- **`actions`** _(Array)_ - Action options for the composer "+" button. Array of `{ title, action }`; add `icon` (and optional `color`) to an action to render a Telegram-style attachment **grid** (tiles) instead of a list. Opens the built-in themed `AttachmentSheet` - no extra dependency.
+- **`attachments`** _(Bool | Object)_ - The built-in attachment menu behind the composer's paperclip, on by default; the paperclip shows when at least one tab's peer is installed. Tabs: `gallery` (an in-sheet grid with `expo-media-library`, the system picker with `expo-image-picker` otherwise), `camera` (`expo-image-picker`; a tab of its own only without the grid, which has a camera tile), `file` (`expo-document-picker`) and `location` (`expo-location`). Picks are sent through `onSend`: one `image` / `video` message per photo or video with the caption on the first, a `file` message per document, a `location` message. `false` hides the paperclip. An object configures it: `{ isEnabled?, tabs?, onPick?, renderAttachmentMenu? }` - `tabs` picks and orders them; `onPick(attachments, { caption })` intercepts the picks (`PickedAttachment[]`) and returns the messages to send, `null` to send nothing, or nothing for the default; `renderAttachmentMenu({ visible, onClose, tabs, onSend })` draws your own menu. Colors live in `theme.attachments`. `actions`, `onPressActionButton` and `renderActions` take precedence. See [Emoji keyboard and attachment menu](#emoji-keyboard-and-attachment-menu) for the permissions each peer needs.
+- **`actions`** _(Array)_ - Action options for the composer "+" button. Array of `{ title, action }`; add `icon` (and optional `color`) to an action to render an attachment **grid** (tiles) instead of a list. Opens the built-in themed `AttachmentSheet` - no extra dependency.
 - **`onPressActionButton`** _(Function)_ - Callback when the "+" button is pressed (if set, the built-in `AttachmentSheet` is not shown)
 - **`actionSheet`** _(Function)_ - Escape hatch for a custom system action sheet. **The bundled `@expo/react-native-action-sheet` dependency was removed**, so `context.actionSheet()` defaults to a no-op; pass your own implementation (with `ActionSheetProvider` in your tree) if you relied on it.
 - **`actionSheetOptionTintColor`** _(String)_ - Tint color for action labels in the attachment sheet
@@ -508,25 +697,42 @@ If you do, sanity-check it on device: a toolbar behind the keyboard means the va
 
 - **`messagesContainerStyle`** _(Object)_ - Custom style for the messages container
 - **`renderMessage`** _(Component | Function)_ - Custom message container
-- **`renderLoading`** _(Component | Function)_ - Render a loading view when initializing
-- **`renderChatEmpty`** _(Component | Function)_ - Custom component to render in the ListView when messages are empty
+- **`renderLoading`** _(Component | Function)_ - Render a loading view while the chat measures its layout on mount
+- **`isLoading`** _(Boolean)_ - The history is loading. Over an empty list the chat shows a spinner in a service-colored circle (a 28 arc in a 36 circle, growing in from 0.3 over 150ms) in place of the empty-chat card. Messages already passed stay visible, without the spinner
+- **`mediaTransfer`** _(Object)_ - Handlers for the media transfer buttons. `{ onDownload?, onCancel? }`. A message with `transfer: { type, progress?, totalBytes? }` draws the progress ring with a cancel ✕ over its photo, video, file, voice or round note (with "1.2 MB / 4.5 MB" when `totalBytes` or the file size is known); tapping it calls `onCancel(message)`. A message with `isDownloadRequired` draws the download arrow; tapping it calls `onDownload(message)`. Without `onDownload`, a voice note or photo then fetches itself. Remote voice notes, photos and round notes that need no app handling show the same ring while they load, from the request's own progress
+- **`renderChatEmpty`** _(Function | null)_ - What to show while there are no messages. By default a greeting card: "No messages here yet...", a line of help and a big 👋 that sends itself when tapped, centered over the wallpaper. Return your own element to replace it, or pass `null` for nothing. The card is exported as `ChatEmpty`.
+- **`emptyChatGreeting`** _(String | null)_ - The greeting on the empty-chat card, sent as a message when tapped; default `'👋'`. `null` keeps just the title.
+- **`firstUnreadMessageId`** _(String | Number | null)_ - The first message the user has not read. A full-width "Unread Messages" bar is drawn above it and the chat opens scrolled so the bar is at the top. Keep it fixed while the chat is open (the bar stays until you leave), e.g. computed once from the unread count when the screen mounts.
+- **`renderUnreadSeparator`** _(Function | null)_ - Custom "Unread Messages" bar, or `null` to only scroll to the first unread message. The default is exported as `UnreadSeparator`.
 - **`renderChatFooter`** _(Component | Function)_ - Custom component to render below the MessagesContainer (separate from the ListView)
-- **`listProps`** _(Object)_ - Extra props to be passed to the messages [`<FlatList>`](https://reactnative.dev/docs/flatlist). Supports all FlatList props including `maintainVisibleContentPosition` for keeping scroll position when new messages arrive (useful for AI chatbots).
-- **`isFlashListEnabled`** _(Bool)_ - Render messages with [`@shopify/flash-list`](https://shopify.github.io/flash-list/) v2 instead of `FlatList`; default is `false`. See [FlashList](#flashlist-opt-in).
+- **`listProps`** _(Object)_ - Extra props for the message list, an [`AnimatedLegendList`](https://legendapp.com/open-source/list/api/props/) (e.g. `drawDistance`, `maintainScrollAtEnd`, `onViewableItemsChanged`). The list renders oldest first, not inverted, so `onEndReached` fires at the newest message.
 
 ### Message Bubbles & Content
 
 - **`renderBubble`** _(Component | Function(`props: BubbleProps`))_ - Custom message bubble. Receives [BubbleProps](src/Bubble/types.ts) as parameter.
 - **`renderMessageText`** _(Component | Function)_ - Custom message text
-- **`renderMessageImage`** _(Component | Function)_ - Custom message image
+- **`renderMessageImage`** _(Component | Function)_ - Custom message image. The built-in one opens the photo viewer on tap: it pages through every photo in the chat, oldest first, with a "3 of 12" counter, the caption, sender and date; pinch or double-tap zooms, and a swipe up or down closes it
 - **`renderMessageVideo`** _(Component | Function)_ - Custom message video
 - **`renderMessageAudio`** _(Component | Function)_ - Custom message audio
 - **`renderMessageLocation`** _(Component | Function)_ - Custom renderer for `IMessage.location`; defaults to a map card that opens the system maps app on tap
-- **`messageActions`** _(Array | Function(`message`))_ - Telegram-style long-press context menu. Each item is `{ label, icon?, onPress, destructive? }`. See [Message actions](#message-actions-long-press-context-menu).
+- **`renderMessageFile`** _(Component | Function)_ - Custom renderer for `IMessage.file`; defaults to a document bubble (a circle with the extension, the name, the size) that opens the file in the share sheet (`expo-sharing`) or through `Linking` on tap
+- **`messageActions`** _(Array | Function(`message`, `defaults`))_ - Long-press context menu actions. Each item is `{ key?, label, icon?, onPress, destructive? }`. An array **replaces** the built-in actions; a function receives the message and the built-in actions for it and returns what to show, so you can extend, filter or reorder them. See [Message actions](#message-actions-long-press-context-menu).
+- **`defaultMessageActions`** _(Bool | `MessageActionKey[]`)_ - The built-in actions, in this order: `reply`, `copy`, `forward`, `pin`, `edit`, `select`, `delete`. Default `true` (all that can work); an array picks and orders them; `false` turns them off. Each shows only when it can work: Reply when `reply.isEnabled` is not `false`; Copy for messages with text when `expo-clipboard` or `@react-native-clipboard/clipboard` is installed; Edit on your own text messages when `onEditMessage` is set; Forward / Pin / Delete when their callbacks are set; Select when a selection can be acted on (a clipboard, Forward or Delete). They are also off when `onLongPressMessage` is set and `messageActions` is not, so an app that handles long-press itself keeps doing so.
+- **`onEditMessage`** _(Function(`message`, `text`))_ - Turns on the "Edit" action for your own text messages. Edit puts the text in the composer under an "Editing" banner; sending then calls this instead of `onSend`. Closing the banner cancels the edit.
+- **`onDeleteMessage`** _(Function(`message`))_ - Turns on the "Delete" action (not red).
+- **`onForwardMessage`** _(Function(`message`))_ - Turns on the "Forward" action.
+- **`onForwardMessages`** _(Function(`messages`))_ - Forwards the messages checked in selection mode, oldest first (also turns on "Forward"). Without it the selection bar's Forward calls `onForwardMessage` once per message.
+- **`onDeleteMessages`** _(Function(`messages`))_ - Deletes the messages checked in selection mode, oldest first (also turns on "Delete"). Without it the selection bar's Delete calls `onDeleteMessage` once per message.
+- **`onSelectionChange`** _(Function(`messages`))_ - Multi-select: "Select" in the long-press menu checks the message, a tap checks or unchecks others (check circles on the left, a tinted row), and a bar replaces the composer with the count, Copy (texts joined oldest first), Forward and Delete. Called on every change with the checked messages; with `[]` once it ends (the X, Android's back, or the last message unchecked).
+- **`renderSelectionBar`** _(Function(`{ count, actions, onClose, messages }`) | null)_ - Custom bar in the composer's place while selecting, or `null` to keep the composer and drive the selection from your own header through `onSelectionChange`.
+- **`fetchLinkPreview`** _(Function(`url`) => Promise<`LinkPreview` | null>)_ - A web page preview (accent bar, site name, bold title, description, picture full width or as a 48dp thumbnail) is drawn under the text for any message with `linkPreview` data. For messages without it, this fetches one for the first link in the text, e.g. from your server's Open Graph endpoint; each URL is fetched once per app run. `IMessage.linkPreview: null` turns it off for one message.
+- **`renderLinkPreview`** _(Function(`{ preview, currentMessage, position, maxWidth, onPress }`) | null)_ - Custom link preview, or `null` to draw none. The default is exported as `LinkPreviewCard`.
+- **`onPressLinkPreview`** _(Function(`preview`, `message`))_ - Called when a link preview is tapped, instead of opening its URL.
+- **`onPinMessage`** _(Function(`message`))_ - Turns on the "Pin" action; it reads "Unpin" on a message with `isPinned: true`. Toggle `isPinned` in the handler.
 - **`renderCustomView`** _(Component | Function)_ - Custom view inside the bubble
 - **`isCustomViewBottom`** _(Bool)_ - Determine whether renderCustomView is displayed before or after the text, image and video views; default is `false`
 - **`onPressMessage`** _(Function(`context`, `message`))_ - Callback when a message bubble is pressed
-- **`onLongPressMessage`** _(Function(`context`, `message`))_ - Callback when a message bubble is long-pressed; you can use this to show action sheets (e.g., copy, delete, reply)
+- **`onLongPressMessage`** _(Function(`context`, `message`))_ - Callback when a message bubble is long-pressed; you can use this to show action sheets (e.g., copy, delete, reply). Setting it (without `messageActions`) turns the built-in long-press menu off
 - **`isMessageGestureEnabled`** _(Bool | Function(`message`))_ - Whether the bubble itself is part of the row's tap / long-press surface that `reactions` and `messageActions` rely on; default is `true`. Pass `false`, or a predicate, for messages that render natively interactive content - the row beside the bubble stays pressable either way. See [Interactive content inside bubbles](#interactive-content-inside-bubbles-video-players-maps).
 - **`imageProps`** _(Object)_ - Extra props to be passed to the [`<Image>`](https://reactnative.dev/docs/image) component created by the default `renderMessageImage`
 - **`imageStyle`** _(Object)_ - Custom style for message images
@@ -597,6 +803,10 @@ See the full example in [LinksExample](example/components/chat-examples/LinksExa
 
 ### Avatars
 
+Avatars and sender names show in group chats only: a one-to-one chat has neither.
+
+- **`isGroupChat`** _(Bool)_ - Whether this is a group chat; default is auto-detected (more than one other sender in `messages` means a group)
+- **`isAvatarVisible`** _(Bool)_ - Show avatars beside incoming messages; default `true` in group chats, `false` in one-to-one chats, and `true` whenever `renderAvatar` is a function. Pass `true` to keep avatars in one-to-one chats
 - **`renderAvatar`** _(Component | Function)_ - Custom message avatar; set to `null` to not render any avatar for the message
 - **`isUserAvatarVisible`** _(Bool)_ - Whether to render an avatar for the current user; default is `false`, only show avatars for other users
 - **`isAvatarVisibleForEveryMessage`** _(Bool)_ - When false, avatars will only be displayed when a consecutive message is from the same user on the same day; default is `false`
@@ -606,7 +816,7 @@ See the full example in [LinksExample](example/components/chat-examples/LinksExa
 
 ### Username
 
-- **`isUsernameVisible`** _(Bool)_ - Indicate whether to show the user's username inside the message bubble; default is `false`
+- **`isUsernameVisible`** _(Bool)_ - Show the sender's name on the first message of each run of incoming messages; default `true` in group chats and `false` in one-to-one chats (see `isGroupChat`)
 - **`renderUsername`** _(Component | Function)_ - Custom Username container
 
 ### Date & Time
@@ -645,13 +855,13 @@ See the full example in [LinksExample](example/components/chat-examples/LinksExa
 - **`loadEarlierMessagesProps`** _(Object)_ - Props to pass to the LoadEarlierMessages component. The button is only visible when `isAvailable` is `true`:
   - `isAvailable` - Controls button visibility (default: false)
   - `onPress` - Callback when button is pressed
-  - `isLoading` - Display loading indicator (default: false)
-  - `isInfiniteScrollEnabled` - Enable infinite scroll up when reaching the top of messages container, automatically calls `onPress` (not yet supported for web)
+  - `isLoading` - Shows a loading cell, a spinner in a 36 service circle, in place of the button (default: false)
+  - `isInfiniteScrollEnabled` - Enable infinite scroll up when reaching the top of messages container, automatically calls `onPress` (not yet supported for web). The list then ends in the loading cell instead of a button while `isAvailable`
   - `label` - Override the default "Load earlier messages" text
   - `containerStyle` / `wrapperStyle` / `textStyle` - Custom styles for the button
   - `activityIndicatorStyle` - Custom style for the loading indicator
-  - `activityIndicatorColor` - Color of the loading indicator (default: 'white')
-  - `activityIndicatorSize` - Size of the loading indicator (default: 'small')
+  - `activityIndicatorColor` - Color of the spinner's arc (default: the date pill's text color)
+  - `activityIndicatorSize` - Deprecated and ignored: the spinner is a fixed 28 arc
 - **`renderLoadEarlier`** _(Component | Function)_ - Custom "Load earlier messages" button
 
 ### Typing Indicator
@@ -660,6 +870,7 @@ See the full example in [LinksExample](example/components/chat-examples/LinksExa
 - **`renderTypingIndicator`** _(Component | Function)_ - Custom typing indicator component
 - **`typingIndicatorStyle`** _(StyleProp<ViewStyle>)_ - Custom style for the TypingIndicator component.
 - **`renderFooter`** _(Component | Function)_ - Custom footer component on the ListView, e.g. `'User is typing...'`; see [CustomizedRenderingExample.tsx](example/components/chat-examples/CustomizedRenderingExample.tsx) for an example. Overrides default typing indicator that triggers when `isTyping` is true.
+- **`TypingStatus`** _(Component)_ - The messenger way to show it: in your chat header, three dots that swell in turn before "typing" (waves for a recording, arrows for an upload). `<TypingStatus users={typingUsers} action='recordingVoice' isGroup color={accent} />` reads "typing", "Anna is typing", "Anna and Max are typing", "recording a voice message"... `ChatList` rows use it for `typingUsers` / `typingAction`, and `getTypingText` gives the text alone
 
 ### Quick Replies
 
@@ -674,9 +885,12 @@ See the [quick replies example in messages.ts](example/example-expo/data/message
 
 ### Scroll to Bottom
 
-- **`isScrollToBottomEnabled`** _(Bool)_ - Enables the scroll to bottom Component (Default is false)
+The button comes up after you scroll back towards the newest message by `scrollToBottomOffset`, or when a message arrives while you are away from the newest one, and goes away at the newest message (or after scrolling away again by the same distance, when scrolling brought it up). Messages that arrive while you are away are counted in a badge, which counts down as each one scrolls into view.
+
+- **`isScrollToBottomEnabled`** _(Bool)_ - Show the scroll-to-bottom button; default `true`. Passing `true` explicitly also keeps the older behaviour of a non-inverted list scrolling to its end on layout
+- **`isScrollToBottomBadgeEnabled`** _(Bool)_ - Count new messages in a badge on the button; default `true`
 - **`scrollToBottomComponent`** _(Function)_ - Custom Scroll To Bottom Component container
-- **`scrollToBottomOffset`** _(Integer)_ - Custom Height Offset upon which to begin showing Scroll To Bottom Component (Default is 200)
+- **`scrollToBottomOffset`** _(Integer)_ - How far to scroll before the button shows or hides; default `100`
 - **`scrollToBottomStyle`** _(Object)_ - Custom style for Scroll To Bottom wrapper (position, bottom, right, etc.)
 - **`scrollToBottomContentStyle`** _(Object)_ - Custom style for Scroll To Bottom content (size, background, shadow, etc.)
 
@@ -686,6 +900,76 @@ See the [quick replies example in messages.ts](example/example-expo/data/message
 
 ## 🧩 Guides
 
+### Chat List
+
+Most apps are a list of chats plus the chats themselves. `ChatList` is the list: map your backend's conversations to `ChatListItem` and wire the callbacks, and you get a messenger's main screen:
+
+- a header with search, and a selection bar (pin, mute, archive, delete) after a long-press
+- an "Archived Chats" folder, and swipe to archive
+- pinned chats first, which you drag into a new order (with reorder handles while selecting)
+- unread counters, typing and drafts, a loading placeholder and a new-chat button
+
+```tsx
+import { Chat, ChatList, ChatListItem } from '@kesha-antonov/react-native-chat'
+
+const chats: ChatListItem[] = conversations.map(c => ({
+  id: c.id,
+  title: c.name,
+  avatar: c.photoUrl,
+  kind: c.isGroup ? 'group' : 'private',
+  lastMessage: c.lastMessage,        // an IMessage: preview, time and your sent/read checks
+  unreadCount: c.unread,
+  isPinned: c.pinned,                // pinned chats show first, in the order you pass them
+  isMuted: c.muted,
+  isArchived: c.archived,
+  isOnline: c.online,                // green dot on the avatar
+  isVerified: c.verified,            // check badge after the name
+  typingUsers: c.typing,             // User[]
+  typingAction: c.action,            // 'typing' | 'recordingVoice' | 'sendingPhoto' | ...
+  draft: drafts[c.id],
+}))
+
+<ChatList
+  chats={chats}
+  user={me}
+  isLoading={!loaded}
+  onPressChat={chat => navigation.navigate('Chat', { id: chat.id })}
+  onPressNewChat={() => navigation.navigate('NewChat')}
+  onPinChats={(selected, isPinned) => api.pin(selected.map(c => c.id), isPinned)}
+  onMuteChats={(selected, isMuted) => api.mute(selected.map(c => c.id), isMuted)}
+  onArchiveChats={(selected, isArchived) => api.archive(selected.map(c => c.id), isArchived)}
+  onDeleteChats={selected => api.delete(selected.map(c => c.id))}
+  onReorderPinnedChats={ids => api.setPinnedOrder(ids)}
+/>
+```
+
+Each action appears only when its callback is passed. The list is controlled: update `chats` from your backend and it follows. For a prototype, `useChatList` keeps the chats in local state and returns the handlers:
+
+```tsx
+const list = useChatList(initialChats)
+<ChatList chats={list.chats} user={me} {...list.handlers} onPressChat={openChat} />
+// later: list.receiveMessage(chatId, message), list.markRead(chatId), list.upsertChat(chat)
+```
+
+| Prop | What it does |
+| --- | --- |
+| `chats` | Every chat, archived ones included |
+| `user` | You: "You:" in groups and the checks on your own last messages |
+| `onPressChat` / `onLongPressChat` | A tap; a long-press (default: select) |
+| `onPinChats` / `onMuteChats` / `onArchiveChats` / `onDeleteChats` | Selection actions; archive also by swiping a row |
+| `onReorderPinnedChats` | Turns on dragging pinned chats; receives the new order of ids |
+| `onPressNewChat` | Shows the new-chat button |
+| `isLoading` | The loading placeholder |
+| `isSortEnabled` | Pinned first, then by newest message (default `true`) |
+| `isDeleteConfirmed` / `isSwipeEnabled` | Ask before deleting; swipe to archive (both default `true`) |
+| `isHeaderVisible` / `title` / `renderHeaderRight` / `isTopInsetApplied` | The built-in header (hide it to use your navigator's) |
+| `isSearchEnabled` / `filterChat` / `onSearchChange` | Search; a custom match; a server-side search |
+| `isArchiveOpen` / `onArchiveOpenChange` | Control which list shows |
+| `renderChat` / `renderEmpty` / `listProps` / `style` | A custom row (`ChatListCell` is the built-in one), the empty text, FlatList props (`onEndReached`, `refreshControl`...) |
+| `theme` / `darkTheme` / `colorScheme` / `locale` / `labels` / `icons` | As on `Chat`; the list's colors are `theme.chatList` |
+
+`ChatListCell`, `ChatListAvatar`, `ChatListShimmer`, `sortChats`, `getChatPreview` and `formatChatListDate` are exported for building your own row or screen.
+
 ### Reply to Messages
 
 <details>
@@ -709,13 +993,20 @@ Swipe on a message to reply to it, showing a reply preview in the input toolbar
 />
 ```
 
+Replying works out of the box: long-press a message and pick **Reply**, or swipe it left. The swipe takes over from the list after 0.4cm (about 25pt) of mostly sideways travel, the row follows the finger up to 80pt, a reply arrow fades in from 20pt and fills by 50pt, where a light haptic ticks; letting go past 50pt starts the reply, and the row slides back over 180ms. Turn the swipe off with `reply={{ swipe: { isEnabled: false } }}`, or all replying with `reply={{ isEnabled: false }}`.
+
+Tapping a quote inside a bubble scrolls to the quoted message and highlights its row for a second, then fades it out over 300ms. The scroll-to-bottom button then comes up, and its first tap takes you back to the message you tapped the quote in. Pass `reply.onPress(replyMessage, message)` to do something else.
+
 #### Reply Props (Grouped)
 
 ```typescript
 interface ReplyProps<TMessage> {
+  isEnabled?: boolean                // The menu's Reply and swipe-to-reply; default true
+  onReply?: (message: TMessage) => void  // A reply started (menu or swipe); use with a controlled `message`
+
   // Swipe gesture configuration
   swipe?: {
-    isEnabled?: boolean              // Enable swipe-to-reply; default false
+    isEnabled?: boolean              // Swipe-to-reply; default true (false to turn it off)
     direction?: 'left' | 'right'     // Swipe direction; default 'left'
     onSwipe?: (message: TMessage) => void  // Callback when swiped
     renderAction?: (                 // Custom swipe action component
@@ -747,7 +1038,7 @@ interface ReplyProps<TMessage> {
   // Callbacks and state
   message?: ReplyMessage             // Controlled reply state
   onClear?: () => void               // Called when reply cleared
-  onPress?: (message: TMessage) => void  // Called when reply preview tapped
+  onPress?: (message: ReplyMessage) => void  // Quote tapped; default jumps to the quoted message and flashes it
 
   // Custom renderers
   renderPreview?: (props: ReplyPreviewProps) => React.ReactNode
@@ -807,41 +1098,11 @@ The reply preview animates automatically - it expands from zero height with a fa
 <details>
 <summary><strong>Keep the reading position while long answers stream in</strong></summary>
 
-For AI chat interfaces where long responses arrive and you don't want to disrupt the user's reading position, use [`maintainVisibleContentPosition`](https://reactnative.dev/docs/scrollview#maintainvisiblecontentposition) via `listProps`:
+The list follows new content only while it is at the newest message. Scrolled up, the reading position stays put while a long answer streams in or new messages arrive, and the scroll-to-bottom button counts them. Both are Legend List behaviours (`maintainScrollAtEnd`, `maintainVisibleContentPosition`) that the chat turns on; override them through `listProps`:
 
 ```tsx
-// Basic usage - always maintain scroll position
-<Chat
-  listProps={{
-    maintainVisibleContentPosition: {
-      minIndexForVisible: 0,
-    },
-  }}
-/>
-
-// With auto-scroll threshold - auto-scroll if within 10 pixels of newest content
-<Chat
-  listProps={{
-    maintainVisibleContentPosition: {
-      minIndexForVisible: 0,
-      autoscrollToTopThreshold: 10,
-    },
-  }}
-/>
-
-// Conditionally enable based on scroll state (recommended for chatbots)
-const [isScrolledUp, setIsScrolledUp] = useState(false)
-
-<Chat
-  listProps={{
-    onScroll: (event) => {
-      setIsScrolledUp(event.contentOffset.y > 50)
-    },
-    maintainVisibleContentPosition: isScrolledUp
-      ? { minIndexForVisible: 0, autoscrollToTopThreshold: 10 }
-      : undefined,
-  }}
-/>
+// Never follow new content, even at the newest message
+<Chat listProps={{ maintainScrollAtEnd: false }} />
 ```
 
 </details>
@@ -857,14 +1118,14 @@ Render AI assistant replies token-by-token. Incoming chunks are batched with `re
 <details>
 <summary><strong>useStreamingMessages, stop control and a full example</strong></summary>
 
-The reply above streams in token-by-token (note the caret `▋`) and renders as **markdown** - bold, italics, lists, inline and fenced code - while the composer's send button turns into a **Stop** control mid-stream. See [Markdown rendering for AI replies](#markdown-rendering-for-ai-replies) to enable markdown.
+The reply above streams in token-by-token (note the caret `▋`) and renders as **markdown** - bold, italics, lists, inline and fenced code - while the app swaps the send button for a **Stop** control mid-stream (with `renderSend`, below). See [Markdown rendering for AI replies](#markdown-rendering-for-ai-replies) to enable markdown.
 
 - **`IMessage.streaming`** - flag a message as streaming (shows the caret)
 - **`useStreamingMessages(...)`** - owns the message list, rAF-batches `push()`, and supports stop via `AbortController`. It returns `{ messages, setMessages, append, startStream, isStreaming, stop }`; `setMessages` is there for anything the hook does not cover, so you can patch a message with a plain `map`.
 
 ```tsx
 import { useCallback } from 'react'
-import { Chat, IMessage, useStreamingMessages } from '@kesha-antonov/react-native-chat'
+import { Chat, IMessage, Send, SendProps, useStreamingMessages } from '@kesha-antonov/react-native-chat'
 
 function Bot () {
   const { messages, append, startStream, isStreaming, stop } = useStreamingMessages<IMessage>()
@@ -880,7 +1141,14 @@ function Bot () {
     })
   }, [append, startStream])
 
-  return <Chat messages={messages} onSend={onSend} user={{ _id: 1 }} />
+  // While a reply streams, the send button becomes a Stop button.
+  const renderSend = useCallback(
+    (sendProps: SendProps<IMessage>) =>
+      isStreaming ? <MyStopButton onPress={stop} /> : <Send {...sendProps} />,
+    [isStreaming, stop]
+  )
+
+  return <Chat messages={messages} onSend={onSend} user={{ _id: 1 }} renderSend={renderSend} />
 }
 ```
 
@@ -912,30 +1180,36 @@ There are two renderers and you get the best available one automatically:
   npx expo install react-native-streamdown react-native-enriched-markdown remend katex
   ```
 
-  It also requires `react-native-worklets >= 0.8.3` (i.e. `react-native-reanimated >= 4.3`), and `react-native-enriched-markdown` is a native module, so a dev build / prebuild is required (it does not work in Expo Go). Pass through Streamdown's own theming/rules via `markdownProps`:
+  It also requires `react-native-worklets >= 0.8.3` (i.e. `react-native-reanimated >= 4.3`), and `react-native-enriched-markdown` is a native module, so a dev build / prebuild is required (it does not work in Expo Go). 0.3 processes the markdown on a worklet runtime, which needs react-native-worklets' **Bundle Mode**: pass `bundleMode: true` and `importForwarding: { moduleNames: ['remend'] }` to `react-native-worklets/plugin` in `babel.config.js`, and wrap `metro.config.js` in `getBundleModeMetroConfig` from `react-native-worklets/bundleMode` (the example app does both). Until Bundle Mode is on, the chat keeps the built-in renderer and logs a one-time dev hint, since 0.3 throws on its first render without it. Version 0.3+ (`StreamdownText`) and the older `Streamdown` export are both recognised. The bubble's text color, size and link color are mapped onto its `markdownStyle`, so replies match the chat theme in light and dark. Anything in `markdownProps` is forwarded to `StreamdownText`; a `markdownStyle` there is merged per element over the derived one:
 
   ```tsx
-  <Chat messageTextProps={{ markdown: true, markdownProps: { /* ... */ } }} {...props} />
+  <Chat
+    messageTextProps={{
+      markdown: true,
+      markdownProps: { markdownStyle: { codeBlock: { backgroundColor: '#0d1117' } } },
+    }}
+    {...props}
+  />
   ```
 
 </details>
 
 ### Emoji Reactions
 
-Long-press a message to open a quick emoji picker; selected reactions render as pills below the bubble and toggle on tap. The quick picker ships in the core with no extra dependencies; a full emoji browser is optional via the `renderReactionPicker` override.
+Long-press a message to open a quick emoji picker; selected reactions render as pills in the bubble and toggle on tap. The bar's chevron opens the built-in full emoji grid (search, tabs, recents) in place; both ship in the core with no extra dependencies, and `renderExpandedPicker` / `renderReactionPicker` replace them.
 
 <p align="center">
-  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/reactions-picker.png" />
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/reactions-picker.png" alt="Long-press menu with the quick reactions bar" />
   &nbsp;&nbsp;
-  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/reactions-pills.png" />
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/reactions-pills.png" alt="A reaction pill under the message" />
   &nbsp;&nbsp;
-  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/reactions-emoji-browser.png" />
+  <img width="200" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/reactions-emoji-browser.png" alt="The expanded reactions grid with search and tabs" />
 </p>
 
 <details>
 <summary><strong>Wiring up the toggle, and the full prop list</strong></summary>
 
-Store reactions on each message as a `reactions` array, then enable the feature and handle the toggle. Reaction state is owned by you, so it works with any backend:
+Store reactions on each message as a `reactions` array and pass `reactions.onReactionPress` - that alone turns reactions on. `Chat.toggleReaction(messages, messageId, emoji, userId)` is the reducer, so the handler is one line. Reaction state is owned by you, so it works with any backend:
 
 ```tsx
 interface IChatMessage extends IMessage {
@@ -945,27 +1219,7 @@ interface IChatMessage extends IMessage {
 const CURRENT_USER_ID = 1
 
 const handleReactionPress = useCallback((message: IChatMessage, emoji: string) => {
-  setMessages(prev =>
-    prev.map(m => {
-      if (m._id !== message._id)
-        return m
-
-      const existing = (m.reactions ?? []).find(r => r.emoji === emoji)
-      if (!existing)
-        return { ...m, reactions: [...(m.reactions ?? []), { emoji, userIds: [CURRENT_USER_ID] }] }
-
-      const userIds = existing.userIds.includes(CURRENT_USER_ID)
-        ? existing.userIds.filter(id => id !== CURRENT_USER_ID)
-        : [...existing.userIds, CURRENT_USER_ID]
-
-      return {
-        ...m,
-        reactions: userIds.length === 0
-          ? (m.reactions ?? []).filter(r => r.emoji !== emoji)
-          : (m.reactions ?? []).map(r => (r.emoji === emoji ? { ...r, userIds } : r)),
-      }
-    })
-  )
+  setMessages(prev => Chat.toggleReaction(prev, message._id, emoji, CURRENT_USER_ID))
 }, [])
 
 <Chat
@@ -973,7 +1227,6 @@ const handleReactionPress = useCallback((message: IChatMessage, emoji: string) =
   onSend={onSend}
   user={{ _id: CURRENT_USER_ID }}
   reactions={{
-    isEnabled: true,
     onReactionPress: handleReactionPress,
     // Optional: provide a richer picker (e.g. a full emoji browser).
     // See example/components/chat-examples/ReactionsExample.tsx
@@ -982,13 +1235,20 @@ const handleReactionPress = useCallback((message: IChatMessage, emoji: string) =
 />
 ```
 
+`Chat.toggleReaction` (also exported as `toggleReaction`) returns a new array and leaves other messages untouched. A user can leave up to three different reactions on a message by default, as in Telegram - a fourth replaces their oldest; pass `{ maxPerUser: 1 }` as a fifth argument for one reaction each, or any other limit (`Infinity` for none).
+
+For a prototype, `useChatMessages({ initialMessages, user })` keeps the messages in local state and returns `chatProps` wired to sending, reactions, editing and deleting: `<Chat {...chatProps} />`.
+
 #### Reactions Props (Grouped)
 
-- **`isEnabled`** _(Bool)_ - Enable emoji reactions (default `false`)
+- **`isEnabled`** _(Bool)_ - Enable emoji reactions; default is on whenever `onReactionPress` is passed
 - **`emojis`** _(String[])_ - Emojis shown in the quick picker (default `['👍', '❤️', '😂', '😮', '😢', '👎']`)
-- **`onReactionPress`** _(Function)_ - `(message, emoji) => void` called when an emoji is selected or a pill is tapped. Toggle logic is left to you
+- **`onReactionPress`** _(Function)_ - `(message, emoji) => void` called when an emoji is selected or a pill is tapped. Apply it with `Chat.toggleReaction`
+- **`getUser`** _(Function)_ - `(userId) => User | undefined`, who reacted. As in Telegram, a pill shows up to three reactors' avatars instead of a count in a one-to-one chat, and in a group while the message has three reactions or fewer, when every reactor is known. Defaults to the senders of the loaded messages (and you)
 - **`renderReactions`** _(Function)_ - Override the reactions-display component rendered below the bubble
-- **`renderReactionPicker`** _(Function)_ - Override the picker shown on long-press (use for a full emoji browser)
+- **`renderReactionPicker`** _(Function)_ - Override the picker shown on long-press (use for a full emoji browser). It receives [`ReactionPickerProps`](src/Reactions/types.ts): `visible`, `message`, `emojis`, `onSelect`, `onDismiss`, `position`, the bubble's on-screen box (`pageX`, `pageY`, `bubbleWidth`, `bubbleHeight`), the two picker styles and:
+  - **`messagePreview`** _(ReactNode, optional)_ - A copy of the pressed bubble to draw lifted above your backdrop at the bubble's box. While it is mounted the original bubble is hidden, so the message seems to rise out of the list; if you never render it, the original simply stays put. The easiest way to get the built-in look is to render the exported `ContextMenu` with `items={[]}` (see [Message actions](#message-actions-long-press-context-menu) for its props)
+- **`renderExpandedPicker`** _(Function(`{ onSelect }`) | null, optional)_ - The expand button. The reactions bar (in the quick picker and above the context menu) ends in a chevron that grows the bar in place into a panel holding what this returns. Defaults to the built-in emoji grid (8 columns, search, tabs, recents); pass your own, or `null` to drop the button. Call `onSelect(emoji)` with the pick; the overlay closes and `onReactionPress` is called. Also passed to a custom `renderReactionPicker`
 - **`containerStyle`**, **`reactionStyle`**, **`reactionActiveStyle`**, **`reactionTextStyle`**, **`reactionCountStyle`** - Styles for the reaction pills
 - **`pickerContainerStyle`**, **`pickerEmojiStyle`** - Styles for the quick picker
 
@@ -1027,9 +1287,34 @@ For full control, pass custom `matchers` (`{ type, pattern, getLinkUrl?, getLink
 ### Message actions (long-press context menu)
 
 <details>
-<summary><strong>Telegram-style floating menu</strong></summary>
+<summary><strong>Floating menu</strong></summary>
+
+Long-press a message to open a context menu beside your finger. It opens by default with these actions: **Reply**, **Copy** (with `expo-clipboard` or `@react-native-clipboard/clipboard` installed), **Forward**, **Pin / Unpin**, **Edit** (your own text messages), **Select** and **Delete** - Forward, Pin, Edit and Delete appear once you pass `onForwardMessage`, `onPinMessage`, `onEditMessage` and `onDeleteMessage`. **Select** starts multi-select: check circles beside the messages and a Copy / Forward / Delete bar in the composer's place (see `onSelectionChange`). When reactions are enabled, a reactions row is shown on top of the menu automatically.
+
+```tsx
+<Chat
+  messages={messages}
+  onSend={onSend}
+  user={user}
+  onEditMessage={(message, text) => setMessages(prev => prev.map(m => m._id === message._id ? { ...m, text } : m))}
+  onDeleteMessage={message => setMessages(prev => prev.filter(m => m._id !== message._id))}
+/>
+```
+
+To change the set, pass `messageActions`. A function receives the built-in actions for the message (each with its `key`), so you can add, drop or reorder; an array replaces them. `defaultMessageActions` picks the built-ins by key, or turns them off with `false`.
+
+```tsx
+<Chat
+  messageActions={(message, defaults) => [
+    ...defaults.filter(action => action.key !== 'forward'),
+    { label: 'Report', icon: ({ color, size }) => <Flag color={color} size={size} />, onPress: () => report(message) },
+  ]}
+/>
+```
+
+After 0.4s the menu opens with a haptic (if `expo-haptics` is installed). The message neither shrinks nor lifts - the chat dims under a black 0.2 scrim and the pressed message stays lit where it is. The menu - a 200-wide card of 48pt rows with icons, in `theme.contextMenu` colors - opens with its right edge just left of your finger and its top at it, unrolling from the top while each row drops into place. The reactions bar above it pops out from its right end with a slight overshoot, with a "thought bubble" tail; reactions you already picked sit smaller in a circle, and the chevron at its end grows the bar into the emoji panel. A picked reaction grows and flies into the message's reaction pill; an action runs once the menu has closed; a tap on the backdrop closes it all. Every animation runs on Reanimated and follows the system Reduce Motion setting. The reaction-only picker (`reactions` without `messageActions`) is the same overlay without actions.
 
-Long-press a message to open a floating, themed context menu anchored to the bubble. Provide the actions via `messageActions` - an array, or a function of the message - each `{ label, icon?, onPress, destructive? }`. When reactions are enabled, a reactions row is shown on top of the menu automatically.
+A fully custom menu - each item is `{ key?, label, icon?, onPress, destructive? }`:
 
 ```tsx
 import { setStringAsync } from 'expo-clipboard'
@@ -1038,11 +1323,18 @@ import { Copy, Trash2 } from 'lucide-react-native' // optional icons
 <Chat
   messageActions={message => [
     { label: 'Copy', icon: ({ color, size }) => <Copy color={color} size={size} />, onPress: () => setStringAsync(message.text) },
-    { label: 'Delete', destructive: true, onPress: () => deleteMessage(message) },
+    { label: 'Delete', icon: ({ color, size }) => <Trash2 color={color} size={size} />, destructive: true, onPress: () => deleteMessage(message) },
   ]}
 />
 ```
 
+`ContextMenu` is exported for custom pickers and menus. Beyond `visible`, `items`, `onDismiss` (called once its exit has played), `position` and the bubble's box (`pageX`, `pageY`, `bubbleWidth`, `bubbleHeight`), it takes these optional props:
+
+- **`reactions`** _(Object)_ - `{ emojis, onSelect, selected?, containerStyle?, emojiStyle?, renderAccessory?, renderExpandedPicker? }`. `selected` lists the reactions the user already picked (drawn smaller, in a circle); `renderAccessory` adds content at the end of the bar; `renderExpandedPicker` adds the expand button and the panel it opens (see `reactions.renderExpandedPicker` above)
+- **`touchX`**, **`touchY`** _(Number)_ - Where the finger was, in window coordinates; the menu opens beside it (beside the bubble's middle without them)
+- **`messagePreview`** _(ReactNode)_ - The copy of the message drawn above the scrim in place; pass the one a custom picker receives
+- **`children`** _(ReactNode)_ - Drawn above everything else in the overlay, e.g. a full emoji sheet
+
 > **Note:** This library no longer depends on `@expo/react-native-action-sheet`. Prefer `messageActions` above. If you specifically want a native action sheet, install it yourself, wrap your tree in `ActionSheetProvider`, and either call `useActionSheet()` in your own `onLongPressMessage` or pass an `actionSheet` prop - the `actionSheet` prop / `context.actionSheet()` escape hatch still works when you provide an implementation. The composer "+" actions use the built-in themed `AttachmentSheet` and need no setup.
 
 </details>
@@ -1052,7 +1344,7 @@ import { Copy, Trash2 } from 'lucide-react-native' // optional icons
 <details>
 <summary><strong>Keeping native controls tappable</strong></summary>
 
-When `reactions` or `messageActions` are enabled, the long-press surface spans the **whole message row** - the bubble *and* the empty space beside it, the way Telegram behaves on Android. (A tap gesture is added on top only when `onPressMessage` is set.) Those recognizers do not cancel touches on native subviews, so a `react-native-video` / `expo-video` player rendered through `renderMessageVideo` keeps its native `controls` interactive.
+When `reactions` or `messageActions` are enabled, the long-press surface spans the **whole message row** - the bubble *and* the empty space beside it. (A tap gesture is added on top only when `onPressMessage` is set.) Those recognizers do not cancel touches on native subviews, so a `react-native-video` / `expo-video` player rendered through `renderMessageVideo` keeps its native `controls` interactive.
 
 If a message must own every touch that lands on it, set `isMessageGestureEnabled` to `false` for it. The gesture surface then drops *behind* the bubble: the bubble's content takes its touches, and long-pressing the row next to the bubble still opens the picker - so reactions are never lost for that message.
 
@@ -1072,21 +1364,31 @@ If a message must own every touch that lands on it, set `isMessageGestureEnabled
 <details>
 <summary><strong>Token groups, runtime switching and themed components</strong></summary>
 
-The chat ships with a modern default look and a full token-based theme. Override any subset of tokens via `theme` (light) and `darkTheme` (dark); your overrides are deep-merged over `defaultLightTheme` / `defaultDarkTheme`, and the resolved theme switches at runtime with the color scheme (system, or forced via `colorScheme`). Explicit per-component style props still win over the theme.
+The default look is a modern messenger style: a classic day theme (pale green outgoing bubbles over a green swirl wallpaper) and a dark blue night theme (a purple-to-blue outgoing gradient fixed to the screen). Every value is a token. Override any subset via `theme` (light) and `darkTheme` (dark); your overrides are deep-merged over `defaultLightTheme` / `defaultDarkTheme`, and the resolved theme switches at runtime with the color scheme (system, or forced via `colorScheme`). Explicit per-component style props still win over the theme.
 
 ```tsx
 <Chat
   theme={{
-    colors: { accent: '#3390EC', outgoingBubble: '#EFFEDE' },
+    colors: { accent: '#3390EC', outgoingBubble: '#3390EC', outgoingText: '#FFFFFF' },
     radii: { bubble: 18 },
+    wallpaper: { colors: ['#7FA381', '#FFF5C5', '#336F55', '#FBE37D'] },
   }}
-  darkTheme={{ colors: { background: '#0E1621', incomingBubble: '#182533' } }}
+  darkTheme={{ bubble: { outgoingGradient: ['#5B3FA8', '#2F6FD6'] } }}
   // colorScheme="dark"   // optional: force a scheme instead of following the system
   {...props}
 />
 ```
 
-Token groups: `colors`, `radii`, `spacing`, `typography`, `avatar`, `sendButton`, `composer`, `voice`. Build your own theme-aware components with the exported hooks:
+Token groups: `colors`, `radii`, `spacing`, `typography`, `avatar`, `sendButton`, `composer`, `voice`, plus:
+
+- **`bubble`** - `hasTail` (a curled tail on the last bubble of a run; drawn with `react-native-svg` when installed), `isTimeInline` (the time on the last line of text when it fits; `false` gives it a row), `outgoingGradient` (stops, top to bottom, or `null` for the solid `colors.outgoingBubble`), `outgoingGradientMode` (`'screen'`: one gradient across the list, each bubble shows its slice as it scrolls; `'bubble'`: each bubble carries the whole gradient), `maxWidthInset` (the text column is `min(width, height) - maxWidthInset`, 80 by default), `bigEmojiMaxCount` (a message of up to this many emoji and nothing else drops its bubble and draws them large, with the time in a service pill; 20 by default, `0` turns it off), `bigEmojiSizes` (font size by emoji count, `40.8, 40.8, 33.6, 26.4, 22.8`).
+- **`wallpaper`** - `isEnabled`, `colors` (three or four, for the swirl gradient), `isAnimated` (one step per outgoing message), `pattern` (an image tiled over the gradient; no pattern is bundled), `patternOpacity`, `patternColor`. Off, the chat shows `colors.background`. Replace it entirely with the `renderWallpaper` prop, or draw it elsewhere with the exported `ChatWallpaper` component.
+- **`nameColors`** - the seven sender-name colors, picked per user id. Empty uses `colors.senderName`.
+- **`avatar.palette` / `avatar.paletteEnd`** - initials avatar gradient stops, picked per user id. An empty `paletteEnd` draws flat colors.
+
+A few behaviours follow from the tokens: setting `colors.outgoingBubble` turns the gradient off, setting `colors.senderName` empties `nameColors`, and setting `avatar.palette` without `paletteEnd` draws flat avatars - so an app that picks its own colors keeps seeing them. Bubbles in a run (same sender, at most five minutes apart, `utils.isSameGroup`) share one tail and one name, 2pt apart (`spacing.withinGroup`), with 6pt between runs (`spacing.betweenGroups`).
+
+Build your own theme-aware components with the exported hooks:
 
 ```tsx
 import { useTheme, useThemedStyles } from '@kesha-antonov/react-native-chat'
@@ -1101,7 +1403,9 @@ const MyBadge = () => {
 }
 ```
 
-Also exported: `defaultLightTheme`, `defaultDarkTheme`, and the `ChatTheme` / `PartialChatTheme` types.
+Also exported: `defaultLightTheme`, `defaultDarkTheme`, `ChatWallpaper`, and the `ChatTheme` / `PartialChatTheme` types.
+
+The built-in panels have their own token groups: `emojiKeyboard`, `contextMenu`, `attachments` and `chatList`. The full set of tokens and their default values is the `ChatTheme` type and `defaultLightTheme` / `defaultDarkTheme`.
 
 </details>
 
@@ -1120,6 +1424,8 @@ All built-in UI strings (composer placeholder, send/cancel, load earlier, today,
 />
 ```
 
+Right-to-left layout follows the locale (Arabic, Hebrew, Persian, Urdu and a few others). `forceRTL` overrides the guess: `true` for an RTL language not in that set, `false` to keep a left-to-right layout.
+
 Exported helpers: `ChatLabels` (type), `defaultLabels`, `translations`, `resolveLabels`, and the `useLabels` hook for reading the resolved labels in custom components.
 
 </details>
@@ -1129,7 +1435,7 @@ Exported helpers: `ChatLabels` (type), `defaultLabels`, `translations`, `resolve
 <details>
 <summary><strong>Tick indicators for sent / delivered / read</strong></summary>
 
-Set `sent`, `received`, or `pending` on a message to show its delivery status. By default these render as tick indicators next to the timestamp (`✓` sent, `✓✓` received, `🕓` pending):
+Set `sent`, `received`, `pending` or `isFailed` on a message to show its delivery status. The status is yours to set: add a message with `pending: true` in `onSend`, then set `sent` and `received` as your backend confirms. Every outgoing message shows it, voice notes, round notes, files and photos included. They render beside the time: one check once sent, two once received (read), a spinning clock while pending, a red badge when sending failed. `isEdited` or `editedAt` prefix the time with "edited":
 
 ```tsx
 const message: IMessage = {
@@ -1176,6 +1482,25 @@ interface MyMessage extends IMessage {
 
 </details>
 
+### Building blocks
+
+<details>
+<summary><strong>Lower-level components and helpers</strong></summary>
+
+`Chat` is assembled from exported parts, so you can reuse them in your own screens or render props:
+
+- **Rows and bubbles**: `Message`, `Bubble`, `MessageText`, `MessageImage`, `MessageVideo`, `MessageAudio`, `MessageFile`, `MessageLocation`, `MessageReply`, `SystemMessage`, `Day`, `Time`, `Avatar`, `ChatAvatar`, `UnreadSeparator`, `ChatEmpty`, `LinkPreviewCard`, `MediaCard`
+- **Composer**: `InputToolbar`, `Composer`, `Send`, `Actions`, `ReplyPreview`, `EmojiGrid`, `AttachmentMenu`, `AttachmentSheet`
+- **Voice and video**: `VoiceMessageInput`, `WaveformPlayer`, `VideoRecordButton`, `VideoNoteRecorder`, with `isVoiceRecordingAvailable`, `isWaveformAvailable`, `isVideoRecordingAvailable`, `isVisionCameraAvailable`
+- **Menus and status**: `ContextMenu`, `TypingStatus` (`getTypingText`), `StreamingCursor`, `MarkdownMessageText` (`isMarkdownAvailable`), `BasicMarkdown`
+- **Lists**: `MessagesContainer`, `ChatList`, `ChatListCell`, `ChatListAvatar`, `ChatListShimmer`
+- **Hooks**: `useTheme`, `useThemedStyles`, `useColorScheme`, `useIcons`, `useLabels`, `useIsRTL`, `useChatContext`, `useStreamingMessages`, `useChatMessages`, `useChatList`
+- **Helpers**: `toggleReaction`, `getChatCapabilities`, `buildAttachmentMessages`, `getAttachmentTabs`, `formatFileSize`, `findFirstUrl`, `countEmojiOnly`, `isRTLLocale`, `mirrorPosition`, `formatChatListDate`, `getChatPreview`, `sortChats`, `matchesChatQuery`, `DEFAULT_MESSAGE_ACTION_KEYS`, `EMOJI_CATEGORY_KEYS`, `DEFAULT_RECENT_EMOJIS`
+
+Components rendered outside `Chat` need a `GestureHandlerRootView` above them.
+
+</details>
+
 ---
 
 ## 📱 Platform Notes
@@ -1271,74 +1596,34 @@ Three things to know:
 
 ## ⚡ Performance
 
-The chat is built for long lists. The one habit that matters most: **memoize your render props and config**, because each message row is `React.memo`'d with a comparator that deep-compares the message and reference-compares everything else - so an inline function or object re-renders that row on every parent render.
+A message re-renders only when something it shows changes. Each row subscribes to its own message by id, so a send, a status tick, a reaction or a streamed token renders that one row (plus a neighbour only when the bubbles' grouping changes) and leaves the list and the composer alone. Everything the rows share - render props, styles, actions, labels - reaches them through context, kept stable between renders:
 
-```jsx
-// ❌ New reference every render - the row can't skip
-<Chat renderBubble={props => <MyBubble {...props} />} reactions={{ isEnabled: true, onReactionPress }} />
+- **Event handlers can be inline.** `onPressMessage={() => ...}`, `reply={{ onPress: ... }}`, an action's `onPress`: they are called through a stable proxy that always reaches your latest handler.
+- **Style and config objects can be inline.** `timeTextStyle={{ left: { color } }}`, `reactions={{ isEnabled: true }}` are compared by content.
+- **Memoize render functions.** A new `renderBubble` may draw something new, so a new reference re-renders every row - wrap it in `useCallback`.
 
-// ✅ Stable references - unchanged rows skip re-renders
+```jsx
+// ✅ Handlers and objects inline; the render function memoized
 const renderBubble = useCallback(props => <MyBubble {...props} />, [])
-const reactions = useMemo(() => ({ isEnabled: true, onReactionPress }), [onReactionPress])
 
-<Chat renderBubble={renderBubble} reactions={reactions} />
+<Chat renderBubble={renderBubble} onPressMessage={message => open(message)} timeTextStyle={{ left: { color: 'gray' } }} />
 ```
 
 <details>
-<summary><strong>Immutability, context props and virtualization tuning</strong></summary>
+<summary><strong>Messages, neighbours, context props and virtualization tuning</strong></summary>
 
-The memoization advice applies to all render props (`renderBubble`, `renderMessageText`, `renderAvatar`, ...), the `reactions` / `audioRecording` / `videoRecording` / `messageActions` config objects, and any style objects.
+**Keep messages immutable.** Update a message by replacing its object (e.g. `Chat.append(...)`, or `messages.map(m => m._id === id ? { ...m, sent: true } : m)`), never by mutating it in place. A store that rebuilds every message object on each update still only re-renders what changed - unchanged messages are compared by content.
 
-**Keep messages immutable.** Update messages by creating new arrays/objects (e.g. `Chat.append(...)`), never by mutating an existing message in place - the row comparator relies on value changes to detect updates.
+**Neighbours are for grouping.** `previousMessage` / `nextMessage` handed to `renderMessage`, `renderBubble` or `renderAvatar` are kept current for what decides grouping (sender, day, time apart, whether there is one). A row does not re-render because a neighbour's text, status or reactions changed, so do not draw those from a neighbour.
 
 **Theme, icons and labels don't need drilling.** `theme` / `darkTheme`, `icons`, and `labels` are read from context (`useTheme`, `useIcons`, `useLabels`), so passing them once on `<Chat>` is enough; they don't cause per-row churn.
 
-**Tune virtualization if needed.** Sensible `FlatList` defaults ship out of the box (`removeClippedSubviews` on Android, `initialNumToRender`, `maxToRenderPerBatch`, `windowSize`, `updateCellsBatchingPeriod`). `windowSize` is measured in screen-heights (not messages); the default keeps a few screens of content mounted around the viewport. Override any of them via `listProps`:
-
-```jsx
-<Chat listProps={{ windowSize: 7, removeClippedSubviews: true }} {...props} />
-```
-
-</details>
-
-### FlashList (opt-in)
-
-<details>
-<summary><strong>Recycling rows on very long histories</strong></summary>
-
-On long histories `FlatList` can log `VirtualizedList: You have a large list that is slow to update`. [FlashList](https://shopify.github.io/flash-list/) v2 recycles rows instead of keeping them mounted, which removes that class of stall. It is supported as an **optional** dependency - install it yourself and flip one prop:
-
-```bash
-yarn add @shopify/flash-list
-```
-
-```jsx
-<Chat messages={messages} user={user} isFlashListEnabled />
-```
-
-Everything else keeps working: `isInverted`, the floating day header, `loadEarlierMessagesProps` infinite scroll, the scroll-to-bottom button, and `listProps` (spread last, so it overrides the defaults below).
-
-The chat sets FlashList's `maintainVisibleContentPosition` for you - `startRenderingFromBottom` when `isInverted={false}`, plus `autoscrollToBottomThreshold: 0.2` so new messages follow the viewport only when you are already at the bottom. Override it through `listProps` if you want different thresholds:
+**Tune virtualization if needed.** The list is [Legend List](https://legendapp.com/open-source/list/), which keeps only what is near the viewport mounted. `drawDistance` (in pixels) sets how far beyond the screen it renders; raise it if fast flings show blank space, lower it to mount less. Leave `recycleItems` off: message rows hold state (players, animations) that must not move to another message.
 
 ```jsx
-<Chat
-  isFlashListEnabled
-  listProps={{
-    maintainVisibleContentPosition: {
-      autoscrollToBottomThreshold: 0.1,
-      animateAutoScrollToBottom: false,
-    },
-  }}
-  {...props}
-/>
+<Chat listProps={{ drawDistance: 500 }} {...props} />
 ```
 
-Notes:
-
-- FlashList v2 requires the **New Architecture**. On the old architecture it falls back to a slower JS path.
-- `FlatList`-only knobs (`windowSize`, `maxToRenderPerBatch`, `initialNumToRender`, `updateCellsBatchingPeriod`, `removeClippedSubviews`) are not forwarded to FlashList - it sizes its own render window.
-- If `@shopify/flash-list` is not installed, the prop is ignored, a warning is logged, and `FlatList` is used.
-
 </details>
 
 ---
@@ -1376,7 +1661,7 @@ fireEvent(loadingWrapper, 'layout', {
 <details>
 <summary><strong>Running the demo locally</strong></summary>
 
-The repository includes a comprehensive example app demonstrating all features - basic chat, custom bubbles and avatars, swipe-to-reply, quick replies, typing indicators, attachment actions, link parsing with custom matchers, and web compatibility.
+The repository includes an example app with two parts. The **Chats** tab is a small messenger built on the defaults: a chat list (unread badges, pinned and muted chats, "typing…" previews, swipe to archive, long-press selection, a compose button) where each chat is a bare `<Chat>` with seeded history, and sending moves the chat to the top and gets a simulated reply. The **Explore** tab has one screen per feature or customization: streaming AI replies, reactions, the long-press menu, media and voice, theming, localization, links, custom rendering, a Slack-style layout, and more.
 
 ```bash
 git clone https://github.com/kesha-antonov/react-native-chat.git
@@ -1394,6 +1679,28 @@ npx expo start --web   # Web
 
 ## ❓ Troubleshooting
 
+<details>
+<summary><strong>"Cannot read property 'Chat' of undefined"</strong></summary>
+
+This means the package threw while it was being loaded, so the import came back empty. The real cause is the **first** error in the Metro log or red box, logged before this one - almost always a native peer that is missing or out of sync with the installed app:
+
+- `react-native-reanimated`, `react-native-worklets`, `react-native-gesture-handler` and `react-native-keyboard-controller` are native modules. After installing or upgrading any of them, rebuild the app (`npx expo run:ios`, `npx expo prebuild`, or `pod install` + a native build) - reloading the JS bundle is not enough.
+- In Expo, install them with `npx expo install` so the versions match your SDK. A plain `npm install` pulls the latest releases, which Expo Go and an existing dev build may not include, and Reanimated throws a version-mismatch error on import.
+- In bare React Native, check the worklets Babel plugin is in `babel.config.js` (see [Bare React Native Projects](#bare-react-native-projects)), then restart Metro with `--reset-cache`.
+
+</details>
+
+<details>
+<summary><strong>The whole message list is blurred on iOS 26</strong></summary>
+
+The chat sits under a transparent navigation header - Expo Router 58's default is a transparent Liquid Glass header the screen scrolls under. iOS 26 then blurs scroll content beneath the header with a scroll edge effect, so the messages under the header are blurred. Give the chat screen an opaque header:
+
+```tsx
+<Stack.Screen name='chat' options={{ headerTransparent: false }} />
+```
+
+</details>
+
 <details>
 <summary><strong>TextInput is hidden on Android</strong></summary>