movius-chats 1.13.0 → 1.14.0

package/README.md

@@ -4,9 +4,9 @@
 
 A production-ready React Native chat UI library providing message bubbles, WhatsApp-style media grids, audio playback, voice recording, typing indicators, message replies, full-screen media gallery, and comprehensive theming—all wrapped in a single, powerful `ChatScreen` component. Works with both bare React Native and Expo.
 
-**npm:** [`movius-chats`](https://www.npmjs.com/package/movius-chats)  
-**Repo:** [github.com/David-Atueyi/Movius-Chats](https://github.com/David-Atueyi/Movius-Chats)  
-**Version:** 1.6.0 | **License:** ISC
+**npm:** [`movius-chats`](https://www.npmjs.com/package/movius-chats)
+**Repo:** [github.com/David-Atueyi/Movius-Chats](https://github.com/David-Atueyi/Movius-Chats)
+**Version:** 1.14.0 | **License:** ISC
 
 ---
 
@@ -18,6 +18,7 @@ A production-ready React Native chat UI library providing message bubbles, Whats
 4. [Quick start](#quick-start)
 5. [Core concepts](#core-concepts)
    - [Message data model](#message-data-model)
+   - [Audio items and bubble splitting](#audio-items-and-bubble-splitting)
    - [Message list order](#message-list-order)
    - [Context system](#context-system)
 6. [API reference](#api-reference)
@@ -67,6 +68,8 @@ A production-ready React Native chat UI library providing message bubbles, Whats
 - **Video autoplay control** (disabled in gallery by default)
 - **Video thumbnails** with play icon overlay
 - **Video playback** within the gallery with native controls
+- **Mixed media + audio in one message** — images/videos render in the grid, with an attached audio note rendered underneath in the same bubble
+- **Multiple audio clips in one message automatically split** into a primary inline audio bubble plus standalone bubbles for each additional clip, all sharing the same timestamp/status
 
 ### Audio & Voice
 
@@ -82,6 +85,7 @@ A production-ready React Native chat UI library providing message bubbles, Whats
   - Playback speed control (1.0x → 1.5x → 2.0x cycling)
   - Play/pause controls with status indicators
   - Sender avatar or current playback speed in the UI
+  - Natural compact sizing — audio never gets boxed into the image/video grid
 - **Audio context** ensuring only one audio plays at a time
 - **Microphone permission handling** (Android + iOS)
 
@@ -139,22 +143,23 @@ A production-ready React Native chat UI library providing message bubbles, Whats
 
 ## 📦 What is Included
 
-| Feature                      | Implementation                                                       |
-| ---------------------------- | -------------------------------------------------------------------- |
-| **Text rendering**           | `react-native-parsed-text` (URLs, emails, phone numbers tappable)    |
-| **Image / video albums**     | `MediaGrid` — 1/2/3/4+ smart layout, 320px height                    |
-| **Full-screen media viewer** | `MediaViewer` — swipe navigation, counter, selective video autoplay  |
-| **Audio playback**           | `react-native-video` (hidden player) + custom waveform visualization |
-| **Variable playback speed**  | 1.0x → 1.5x → 2.0x cycling during playback                           |
-| **Voice recording**          | `react-native-audio-record` (optional peer) with gesture controls    |
-| **File attachments**         | Tappable rows with custom handler + default URL opener               |
-| **Typing indicators**        | Avatar stacking with "+N" badge for multiple typers                  |
-| **Input bar**                | Growing TextField, emoji/clip/camera/send/mic buttons                |
-| **Status indicators**        | Sent/delivered/read animated checkmarks                              |
-| **Message replies**          | Swipe-to-reply, inline display, edit tracking                        |
-| **Message actions**          | Long-press menus with copy, forward, delete, edit                    |
-| **Selection mode**           | Multi-select with batch operations                                   |
-| **Theming**                  | Comprehensive dual-sided (sent/received) color system                |
+| Feature                          | Implementation                                                               |
+| -------------------------------- | ---------------------------------------------------------------------------- |
+| **Text rendering**               | `react-native-parsed-text` (URLs, emails, phone numbers tappable)            |
+| **Image / video albums**         | `MediaGrid` — 1/2/3/4+ smart layout, 320px height, images/videos only        |
+| **Full-screen media viewer**     | `MediaViewer` — swipe navigation, counter, selective video autoplay          |
+| **Audio playback**               | `react-native-video` (hidden player) + custom waveform visualization         |
+| **Multi-audio bubble splitting** | Extra audio items in one message split into standalone bubbles automatically |
+| **Variable playback speed**      | 1.0x → 1.5x → 2.0x cycling during playback                                   |
+| **Voice recording**              | `react-native-audio-record` (optional peer) with gesture controls            |
+| **File attachments**             | Tappable rows with custom handler + default URL opener                       |
+| **Typing indicators**            | Avatar stacking with "+N" badge for multiple typers                          |
+| **Input bar**                    | Growing TextField, emoji/clip/camera/send/mic buttons                        |
+| **Status indicators**            | Sent/delivered/read animated checkmarks                                      |
+| **Message replies**              | Swipe-to-reply, inline display, edit tracking                                |
+| **Message actions**              | Long-press menus with copy, forward, delete, edit                            |
+| **Selection mode**               | Multi-select with batch operations                                           |
+| **Theming**                      | Comprehensive dual-sided (sent/received) color system                        |
 
 ---
 
@@ -165,41 +170,87 @@ A production-ready React Native chat UI library providing message bubbles, Whats
 - **React Native 0.60+**
 - **Node 14+**
 
-### Step 1: Install the package
+### 1. Install movius-chats
 
 ```bash
-npm install movius-chats
-# or
 yarn add movius-chats
+# or: npm install movius-chats
+# or: bun add movius-chats
 ```
 
-### Step 2: Install peer dependencies
+### 2. Install peers
 
 ```bash
-npm install react react-native react-native-gesture-handler react-native-reanimated
+yarn add react-native-reanimated react-native-video react-native-svg react-native-gesture-handler
 ```
 
-### Step 3: Install optional dependencies (feature-specific)
+`react-native-video` and `react-native-svg` are also pulled in as movius-chats dependencies, but your app should list compatible versions and link native code.
+
+| Peer                                | Version | Required | Purpose                        |
+| ----------------------------------- | ------- | -------- | ------------------------------ |
+| `react`                             | ≥16.8   | Yes      | React hooks, context           |
+| `react-native`                      | \*      | Yes      | Core framework                 |
+| `react-native-gesture-handler`      | ≥2.0    | Yes      | Swipe & long-press gestures    |
+| `react-native-reanimated`           | \*      | Yes      | Gesture animations             |
+| `react-native-audio-record`         | \*      | Optional | Voice recording capture        |
+| `react-native-fs`                   | \*      | Optional | File system access (recording) |
+| `@react-native-clipboard/clipboard` | \*      | Optional | Copy to clipboard              |
 
-For **voice recording:**
+If the optional voice-recording peers are missing, the UI still renders; starting a recording logs an install hint instead of crashing.
 
-```bash
-npm install react-native-audio-record react-native-fs
+**There is no `react-native-sound`, `expo-av`, `expo-file-system`, or other Expo package in this library.**
+
+### 3. Reanimated (Babel)
+
+Put this plugin **last** in `babel.config.js`:
+
+```js
+module.exports = {
+  presets: ['module:metro-react-native-babel-preset'],
+  plugins: [
+    // ...other plugins
+    'react-native-reanimated/plugin',
+  ],
+};
 ```
 
-For **clipboard support (copy message):**
+### 4. Voice recording (optional)
 
 ```bash
-npm install @react-native-clipboard/clipboard
+yarn add react-native-audio-record react-native-fs
+```
+
+**iOS** — add to `Info.plist`:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>This app needs the microphone to record voice messages.</string>
+<key>NSCameraUsageDescription</key>
+<string>This app needs camera access to take photos.</string>
+<key>NSPhotoLibraryUsageDescription</key>
+<string>This app needs photo library access.</string>
+```
+
+**Android** — add to `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+<uses-permission android:name="android.permission.CAMERA" />
 ```
 
-For **file attachments** (already in React Native):
+(`RECORD_AUDIO` is often added automatically by `react-native-audio-record`.)
+
+Then rebuild native apps:
 
 ```bash
-# No additional packages needed; uses Linking API
+cd ios && pod install && cd ..
+npx react-native run-ios
+npx react-native run-android
 ```
 
-### Step 4: Link native modules
+### 5. Native linking
 
 **Bare React Native:**
 
@@ -217,82 +268,64 @@ android.useAndroidX=true
 android.enableJetifier=true
 ```
 
-### Step 5: Configure permissions
-
-**Android** (`AndroidManifest.xml`):
+### 6. Android keyboard
 
-```xml
-<uses-permission android:name="android.permission.RECORD_AUDIO" />
-<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
-<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
-<uses-permission android:name="android.permission.CAMERA" />
-```
-
-**iOS** (`Info.plist`):
+In `android/app/src/main/AndroidManifest.xml` on your main activity:
 
 ```xml
-<key>NSMicrophoneUsageDescription</key>
-<string>This app needs microphone access to record voice messages.</string>
-<key>NSCameraUsageDescription</key>
-<string>This app needs camera access to take photos.</string>
-<key>NSPhotoLibraryUsageDescription</key>
-<string>This app needs photo library access.</string>
+android:windowSoftInputMode="adjustResize"
 ```
 
 ---
 
 ## Quick Start
 
-### Basic Usage
-
 ```tsx
 import React, { useState } from 'react';
-import { ChatScreen } from 'movius-chats';
-import type { Message } from 'movius-chats';
+import { Platform, SafeAreaView, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import ChatScreen from 'movius-chats';
+import type { Message } from 'movius-chats/lib/typescript/types';
 
-export const MyChatApp = () => {
-  const [messages, setMessages] = useState<Message[]>([
-    {
-      id: '1',
-      text: 'Hey! How are you?',
-      senderId: 'user-2',
-      time: '10:30 AM',
-      status: 'read',
-      senderName: 'Alice',
-      senderAvatar: 'https://example.com/avatar-alice.jpg',
-    },
-    {
-      id: '2',
-      text: "I'm doing great! How about you?",
-      senderId: 'user-1',
-      time: '10:31 AM',
-      status: 'delivered',
-    },
-  ]);
-
-  const currentUserId = 'user-1';
-
-  const handleSendMessage = (messageText: string) => {
-    const newMessage: Message = {
-      id: String(Date.now()),
-      text: messageText,
-      senderId: currentUserId,
-      time: new Date().toLocaleTimeString(),
-      status: 'sent',
-    };
-    setMessages((prev) => [...prev, newMessage]);
-  };
+export default function ChatDetailScreen() {
+  const insets = useSafeAreaInsets();
+  const currentUserId = '1';
+  const [messages, setMessages] = useState<Message[]>([]);
 
   return (
-    <ChatScreen
-      messages={messages}
-      currentUserId={currentUserId}
-      onSendMessage={handleSendMessage}
-    />
+    <SafeAreaView style={{ flex: 1 }}>
+      <View style={{ flex: 1 }}>
+        <ChatScreen
+          messages={messages}
+          currentUserId={currentUserId}
+          onSendMessage={({ text, senderId }) => {
+            setMessages((prev) => [
+              {
+                id: String(Date.now()),
+                text,
+                senderId,
+                time: new Date().toLocaleTimeString([], {
+                  hour: '2-digit',
+                  minute: '2-digit',
+                }),
+                status: 'sent',
+              },
+              ...prev,
+            ]);
+          }}
+          keyboardVerticalOffset={Platform.OS === 'ios' ? insets.top : 0}
+          showBubbleTail
+          showMessageStatus
+          showVoiceRecordButton
+        />
+      </View>
+    </SafeAreaView>
   );
-};
+}
 ```
 
+Wrap the screen in `flex: 1`. Load custom fonts in **your** app before passing `theme.fontFamily`.
+
 ---
 
 ## Core Concepts
@@ -305,24 +338,23 @@ Every message in movius-chats follows this **unified interface**:
 export interface Message {
   id: string; // Unique message identifier
   text?: string; // Text content
-  image?: string; // Single image URI (legacy)
-  video?: string; // Single video URI (legacy)
-  audio?: string; // Audio file URI
   senderId: string; // ID of message sender
   time: string; // Timestamp (e.g., "10:30 AM")
   status: 'read' | 'delivered' | 'sent'; // Message status
   senderName?: string; // Sender display name
   senderAvatar?: string; // Sender avatar URI
-  mediaItems?: MessageMediaItem[]; // Array of images, videos, or audio
+  mediaItems?: MessageMediaItem[]; // Images, videos, and/or audio — preferred way to attach media
   fileAttachments?: MessageFileAttachment[]; // Array of file attachments
   replyTo?: MessageReply; // Reply context
   edited?: boolean; // Whether message was edited
 }
 
-// Media item in album
+// Media item — image, video, or audio, all in one array
 export interface MessageMediaItem {
   uri: string;
   kind: 'image' | 'video' | 'audio';
+  name?: string; // optional — filename, used when uploading
+  type?: string; // optional — MIME type, used when uploading
 }
 
 // File attachment
@@ -342,6 +374,56 @@ export interface MessageReply {
 }
 ```
 
+### Audio items and bubble splitting
+
+A message's `mediaItems` array can contain any mix of `image`, `video`, and `audio` items. Rendering follows these rules:
+
+- **All `image`/`video` items** render together in the media grid (1/2/3/4+ layout), exactly as before.
+- **The first `audio` item** in `mediaItems` renders attached to the same bubble, directly under the media grid and/or text — this is what a voice note, or an image with an attached audio caption, looks like.
+- **Any additional `audio` items** beyond the first automatically split into their own standalone bubbles, rendered immediately after the main bubble. Each split bubble inherits the same `time` and `status` as the parent message, so timestamps and read/delivered/sent checkmarks stay consistent across the whole group.
+- **Audio never renders inside the image/video grid.** It always uses its own compact waveform UI (~240–280px wide) rather than being stretched into a 320px grid cell.
+
+**Examples:**
+
+```tsx
+// Single audio message
+{
+  id: '123',
+  mediaItems: [{ uri: 'file:///path/to/audio.m4a', kind: 'audio' }],
+  senderId: 'user-1',
+  time: '10:45 AM',
+  status: 'sent',
+}
+
+// Images with an attached audio note — one bubble: grid on top, waveform below
+{
+  id: '124',
+  mediaItems: [
+    { uri: 'https://example.com/photo1.jpg', kind: 'image' },
+    { uri: 'https://example.com/photo2.jpg', kind: 'image' },
+    { uri: 'file:///path/to/note.wav', kind: 'audio' },
+  ],
+  senderId: 'user-1',
+  time: '10:46 AM',
+  status: 'sent',
+}
+
+// Multiple audio clips — first attaches inline, rest split into their own bubbles
+{
+  id: '125',
+  mediaItems: [
+    { uri: 'file:///path/to/clip1.wav', kind: 'audio' },
+    { uri: 'file:///path/to/clip2.wav', kind: 'audio' },
+    { uri: 'file:///path/to/clip3.wav', kind: 'audio' },
+  ],
+  senderId: 'user-1',
+  time: '10:47 AM',
+  status: 'sent',
+}
+```
+
+This means: sending images + one voice note produces a single bubble with the grid on top and the waveform underneath. Sending several voice notes together produces one bubble for the first clip plus a separate standalone bubble for each additional clip — visually indistinguishable from sending them as separate messages, but grouped under one logical `Message`.
+
 ### Message List Order
 
 By default, messages are displayed **newest-first** (reverse chronological). The component expects:
@@ -388,17 +470,18 @@ interface ChatScreenProps {
   // Data
   messages: Message[]; // Message array (newest first)
   currentUserId: string; // Current user's ID
-  typingUsers?: Array<{ id: string; name: string }>; // Who's typing
+  typingUsers?: Array<{ id: string; avatar: string; name: string }>; // Who's typing
 
   // Callbacks
-  onSendMessage: (text: string) => void;
+  onSendMessage: (message: Omit<Message, 'id' | 'time' | 'status'>) => void;
   onAttachmentPress?: () => void;
   onCameraPress?: () => void;
-  onAudioRecordEnd?: (result: RecordingResult) => void;
+  onAudioRecordEnd?: (result?: RecordingResult) => void;
   onAudioRecordStart?: () => void;
   onMessageLongPress?: (message: Message) => void;
   onTypingStart?: () => void;
   onTypingEnd?: () => void;
+  onFileAttachmentPress?: (file: MessageFileAttachment) => void;
   onEndReached?: (info: { distanceFromEnd: number }) => void;
   onEndReachedThreshold?: number; // Default: 0.5
   isLoadingMoreMessages?: boolean;
@@ -410,42 +493,91 @@ interface ChatScreenProps {
   loadingMoreIndicatorSize?: number | 'small' | 'large';
 
   // UI Options
-  showAvatars?: boolean; // Default: true
-  showUserNames?: boolean; // Default: true
-  showBubbleTail?: boolean; // Default: true
-  renderCustomInput?: (props: InputProps) => React.ReactNode;
+  showAvatars?: boolean;
+  showUserNames?: boolean;
+  showBubbleTail?: boolean;
+  showMessageStatus?: boolean;
+  showEmojiButton?: boolean;
+  showAttachmentsButton?: boolean;
+  showCameraButton?: boolean;
+  showVoiceRecordButton?: boolean;
+  renderCustomInput?: () => React.ReactNode;
 
   // Custom Icons (optional)
-  CustomEmojiIcon?: React.ComponentType;
-  CustomAttachmentIcon?: React.ComponentType;
-  CustomCameraIcon?: React.ComponentType;
-  CustomMicrophoneIcon?: React.ComponentType;
-  CustomSendIcon?: React.ComponentType;
-  CustomFileIcon?: React.ComponentType;
-  CustomImagePreview?: React.ComponentType;
-  CustomVideoPreview?: React.ComponentType;
-
-  // Feature Configs
-  messageActionsConfig?: MessageActionsConfig;
+  CustomEmojiIcon?: () => React.ReactNode;
+  CustomAttachmentIcon?: () => React.ReactNode;
+  CustomCameraIcon?: () => React.ReactNode;
+  CustomMicrophoneIcon?: () => React.ReactNode;
+  CustomSendIcon?: () => React.ReactNode;
+  CustomFileIcon?: React.ComponentType<{ style?: any }>;
+  CustomImagePreview?: React.ComponentType<{ uri: string }>;
+  CustomVideoPreview?: React.ComponentType<{ uri: string }>;
+  CustomPlayIcon?: () => React.ReactNode;
+  CustomPauseIcon?: () => React.ReactNode;
+  CustomVoiceRecorder?: (state: VoiceRecorderExposedState) => React.ReactNode;
+
+  // Reply
+  onReplyMessage?: (message: Message) => void;
   replyProps?: ReplyConfig;
-  voiceRecorderConfig?: VoiceRecorderConfig;
-  recordingUIProps?: RecordingUIProps;
+  replyUI?: ReplyUIProps;
+  replyStyle?: ReplyStyleOverrides;
+  renderReplyPreview?: (
+    message: Message,
+    cancel: () => void
+  ) => React.ReactNode;
+  renderInlineReply?: (
+    reply: MessageReply,
+    isCurrentUser: boolean
+  ) => React.ReactNode;
+
+  // Long-press message actions
+  messageActionProps?: MessageActionFlags;
+  messageActionUI?: MessageActionUIProps;
+  messageActionLabels?: MessageActionLabels;
+  messageActionIcons?: MessageActionIconComponents;
+  renderMessageActions?: (
+    message: Message,
+    close: () => void,
+    anchor?: MessageActionAnchor
+  ) => React.ReactNode;
+  onCopyMessage?: (message: Message) => void;
+  onEditMessage?: (message: Message, newText: string) => void;
+  onDeleteMessage?: (message: Message) => void;
+  onForwardMessage?: (message: Message) => void;
+
+  // Multi-select mode
+  selectionUI?: SelectionUIProps;
+  onSelectionChange?: (selectedIds: string[]) => void;
+  onDeleteSelected?: (messages: Message[]) => void;
+  onForwardSelected?: (messages: Message[]) => void;
+  onCopySelected?: (messages: Message[]) => void;
+
+  // "edited" indicator
+  editedLabel?: string;
+  editedTextStyle?: TextStyle;
+
+  keyboardVerticalOffset?: number;
+  disableKeyboardAvoiding?: boolean;
+
+  // Composer preview
+  placeholder?: string;
+  previewData?: PreviewAttachment;
+  previewItems?: PreviewAttachment[];
+  closePreview?: () => void;
+  onRemovePreviewItem?: (uri: string) => void;
 
   // Theming
   theme?: ChatScreenTheme;
-
-  // Selection
-  selectionUI?: SelectionUIProps;
 }
 ```
 
 ### Message Interface
 
-See [Message Data Model](#message-data-model) section above for full details.
+See [Message Data Model](#message-data-model) and [Audio items and bubble splitting](#audio-items-and-bubble-splitting) above for full details.
 
 ### Loading More Messages
 
-When the user reaches the top of the message list while older messages are being fetched, the component can show a loading indicator. This is controlled by the pagination props above.
+When the user reaches the top of the message list while older messages are being fetched, the component can show a loading indicator:
 
 ```tsx
 <ChatScreen
@@ -466,63 +598,121 @@ When the user reaches the top of the message list while older messages are being
 
 ```tsx
 interface ChatScreenTheme {
+  fontFamily?: string;
+
   colors?: {
     // Sent messages
-    sentBubbleBackground?: string;
-    sentTextColor?: string;
+    sentBubbleBackgroundColor?: string;
+    sentMessageTextColor?: string;
     sentTimestampColor?: string;
-    sentStatusIconColor?: string;
+    sentMessageTailColor?: string;
+    sentIconColor?: string;
+    deliveredIconColor?: string;
+    readIconColor?: string;
     sentAudioWaveformColor?: string;
     sentAudioWaveformActiveColor?: string;
+    sentAudioTimestampColor?: string;
+    sentAudioPlayIconColor?: string;
+    sentAudioPauseIconColor?: string;
+    sentAudioPlayButtonBackground?: string;
+    sentAudioSpeedTextColor?: string;
     sentFileAttachmentBackground?: string;
     sentFileAttachmentTextColor?: string;
+    sentFileAttachmentSubtitleColor?: string;
     sentMediaTimestampBackground?: string;
 
     // Received messages
-    receivedBubbleBackground?: string;
-    receivedTextColor?: string;
+    receivedBubbleBackgroundColor?: string;
+    receivedMessageTextColor?: string;
     receivedTimestampColor?: string;
+    receivedMessageTailColor?: string;
     receivedAudioWaveformColor?: string;
     receivedAudioWaveformActiveColor?: string;
+    receivedAudioTimestampColor?: string;
+    receivedAudioPlayIconColor?: string;
+    receivedAudioPauseIconColor?: string;
+    receivedAudioPlayButtonBackground?: string;
+    receivedAudioSpeedTextColor?: string;
     receivedFileAttachmentBackground?: string;
     receivedFileAttachmentTextColor?: string;
+    receivedFileAttachmentSubtitleColor?: string;
     receivedMediaTimestampBackground?: string;
 
-    // UI elements
-    inputBarBackground?: string;
-    inputPlaceholderTextColor?: string;
+    // Shared / UI
+    videoPlayIconColor?: string;
     inputTextColor?: string;
-    typingIndicatorDotColor?: string;
+    inputsIconsColor?: string;
+    sendIconsColor?: string;
+    placeholderTextColor?: string;
+  };
+
+  sizes?: {
+    inputIconSize?: string | number;
   };
 
-  // Fonts & Sizes
-  fontFamily?: string; // Default: system font
-  fontSize?: {
-    message?: number; // Default: 16
-    timestamp?: number; // Default: 12
-    typing?: number; // Default: 14
+  bubbleStyle?: {
+    sent?: ViewStyle;
+    received?: ViewStyle;
+    avatarTextStyle?: TextStyle;
+    userNameStyle?: TextStyle;
+    avatarImageStyle?: ImageStyle;
+    typingContainerStyle?: ViewStyle;
+    additionalTypingUsersContainerStyle?: ViewStyle;
+    additionalTypingUsersTextStyle?: TextStyle;
+    typingTextStyle?: TextStyle;
   };
 
-  // Styling overrides
   messageStyle?: {
-    sentBubbleStyle?: ViewStyle;
-    receivedBubbleStyle?: ViewStyle;
+    sentTextStyle?: TextStyle;
+    receivedTextStyle?: TextStyle;
+    sentFileAttachmentStyle?: ViewStyle;
+    receivedFileAttachmentStyle?: ViewStyle;
+    sentFileAttachmentTextStyle?: TextStyle;
+    receivedFileAttachmentTextStyle?: TextStyle;
+    sentFileAttachmentSubtitleStyle?: TextStyle;
+    receivedFileAttachmentSubtitleStyle?: TextStyle;
     sentMediaTimestampContainerStyle?: ViewStyle;
     receivedMediaTimestampContainerStyle?: ViewStyle;
+    progressBarStyle?: ViewStyle;
+    activeProgressBarStyle?: ViewStyle;
+    audioDurationStyle?: TextStyle;
+    audioSpeedButtonStyle?: ViewStyle;
+    audioSpeedTextStyle?: TextStyle;
+    editedTextStyle?: TextStyle;
+  };
+
+  inputStyles?: {
+    inputSectionContainerStyle?: ViewStyle;
+    inputContainerStyle?: ViewStyle;
+    sendButtonStyle?: ViewStyle;
+  };
+
+  filePreviewStyle?: {
+    root?: ViewStyle;
+    container?: ViewStyle;
+    iconContainer?: ViewStyle;
+    nameContainer?: ViewStyle;
+    text?: TextStyle;
   };
 
-  // Media grid
-  mediaGrid?: {
-    height?: number; // Default: 320
-    borderRadius?: number; // Default: 12
+  voiceRecorder?: {
+    ui?: RecordingUIProps;
+    styles?: VoiceRecorderStyleOverrides;
+    config?: VoiceRecorderConfig;
   };
 
-  // Input bar
-  inputBar?: {
-    maxHeight?: number; // Default: 118
-    minHeight?: number; // Default: 32-50
-    iconSize?: number; // Default: computed
+  reply?: {
+    ui?: ReplyUIProps;
+    styles?: ReplyStyleOverrides;
   };
+
+  messageActions?: {
+    ui?: MessageActionUIProps;
+    labels?: MessageActionLabels;
+    icons?: MessageActionIconComponents;
+  };
+
+  selection?: SelectionUIProps;
 }
 ```
 
@@ -532,7 +722,7 @@ interface ChatScreenTheme {
 
 ### Voice Recording
 
-Voice messages combine **gesture-based capture** with **multiple recording modes**:
+Voice messages combine **gesture-based capture** with **multiple recording modes**. Requires **`react-native-audio-record`** and **`react-native-fs`** in the host app, plus a **native rebuild**.
 
 #### Recording Modes
 
@@ -541,30 +731,44 @@ Voice messages combine **gesture-based capture** with **multiple recording modes
 3. **Slide-to-Cancel** — Swipe left while recording to cancel
 4. **Lock Recording** — Tap lock icon to record hands-free
 
+#### Gestures
+
+| Action                    | Result                                                                       |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| **Tap** mic               | Normal bar: trash, timer, waveform, play/pause preview, send                 |
+| **Long-press** mic        | Hold mode: "slide to cancel", lock column above send                         |
+| Slide **left**            | Cancel (file deleted via `react-native-fs`)                                  |
+| Slide **up** to lock      | Switches to normal bar (`lockSlideDistance` in `theme.voiceRecorder.config`) |
+| **Release** without slide | Auto-send (`onAudioRecordEnd`)                                               |
+
 #### Configuration
 
 ```tsx
 <ChatScreen
-  voiceRecorderConfig={{
-    maxDuration: 300, // 5 minutes max (seconds)
-    enableSlideToCancel: true, // Show slide-to-cancel hint
-    enableLockRecording: true, // Show lock option
-    enableWaveform: true, // Show waveform during recording
-  }}
-  recordingUIProps={{
-    timerColor: '#FFFFFF',
-    waveformColor: '#E9EDEF',
-    recordingBackground: '#0B141A',
-    lockPillBackground: '#1F2937',
-    lockIconColor: '#FFFFFF',
-    chevronIconColor: '#8696A0',
-    cancelTextColor: '#F15C6D',
-    waveformBarCount: 32,
+  theme={{
+    voiceRecorder: {
+      config: {
+        maxDuration: 300, // 5 minutes max (seconds)
+        enableSlideToCancel: true, // Show slide-to-cancel hint
+        enableLockRecording: true, // Show lock option
+        enableWaveform: true, // Show waveform during recording
+      },
+      ui: {
+        timerColor: '#FFFFFF',
+        waveformColor: '#E9EDEF',
+        recordingBackground: '#0B141A',
+        lockPillBackground: '#1F2937',
+        lockIconColor: '#FFFFFF',
+        chevronIconColor: '#8696A0',
+        cancelTextColor: '#F15C6D',
+        waveformBarCount: 32,
+      },
+    },
   }}
   onAudioRecordEnd={(result) => {
+    if (!result) return;
     console.log('Recording saved to:', result.uri);
-    console.log('Duration:', result.duration, 'ms');
-    // Upload to server, add to message, etc.
+    console.log('Duration:', result.duration, 'sec');
   }}
 />
 ```
@@ -573,19 +777,68 @@ Voice messages combine **gesture-based capture** with **multiple recording modes
 
 ```tsx
 interface RecordingResult {
-  uri: string; // File system path
-  duration: number; // Milliseconds
+  uri: string; // File system path (always file://...)
+  duration: number; // Seconds
+  mimeType?: string; // e.g. 'audio/wav'
   size?: number; // Bytes
-  mimeType?: string; // e.g., 'audio/m4a'
+  name?: string; // e.g. 'movius_rec_1783269276396.wav'
 }
 ```
 
+`name` and `mimeType` are populated automatically by the built-in recorder — pass them straight through when building your `mediaItems` entry so your upload logic has the correct filename and MIME type instead of guessing.
+
+#### Wiring
+
+```tsx
+<ChatScreen
+  showVoiceRecordButton
+  onAudioRecordEnd={(result) => {
+    if (!result) return;
+    setMessages((prev) => [
+      {
+        id: String(Date.now()),
+        senderId: currentUserId,
+        mediaItems: [
+          {
+            uri: result.uri,
+            kind: 'audio',
+            name: result.name, // ✅ pass through for upload
+            type: result.mimeType, // ✅ pass through for upload
+          },
+        ],
+        time: '10:56 PM',
+        status: 'sent',
+        senderAvatar: myAvatarUri,
+        senderName: myDisplayName,
+      },
+      ...prev,
+    ]);
+  }}
+/>
+```
+
+#### Custom recorder UI
+
+```tsx
+<ChatScreen
+  CustomVoiceRecorder={(state) => (
+    <MyRecorder
+      duration={state.duration}
+      onStop={state.stopRecording}
+      onCancel={state.cancelRecording}
+    />
+  )}
+/>
+```
+
+---
+
 ### Audio Message Playback
 
-Play audio messages with professional waveform visualization and playback speed control:
+Audio is sent through `mediaItems` with `kind: 'audio'` — not a separate top-level field. See [Audio items and bubble splitting](#audio-items-and-bubble-splitting) for the full rendering rules.
 
 ```tsx
-// Add audio to a message
+// Single audio message
 const audioMessage: Message = {
   id: '123',
   mediaItems: [{ uri: 'file:///path/to/audio.m4a', kind: 'audio' }],
@@ -594,6 +847,32 @@ const audioMessage: Message = {
   status: 'sent',
   senderAvatar: 'https://...',
 };
+
+// Image(s) with an attached audio note — one bubble, grid on top, waveform below
+const imageWithAudio: Message = {
+  id: '124',
+  mediaItems: [
+    { uri: 'https://example.com/photo1.jpg', kind: 'image' },
+    { uri: 'https://example.com/photo2.jpg', kind: 'image' },
+    { uri: 'file:///path/to/note.wav', kind: 'audio' },
+  ],
+  senderId: 'user-1',
+  time: '10:46 AM',
+  status: 'sent',
+};
+
+// Multiple audio clips — first attaches inline, rest split into standalone bubbles
+const multipleAudioClips: Message = {
+  id: '125',
+  mediaItems: [
+    { uri: 'file:///path/to/clip1.wav', kind: 'audio' },
+    { uri: 'file:///path/to/clip2.wav', kind: 'audio' },
+    { uri: 'file:///path/to/clip3.wav', kind: 'audio' },
+  ],
+  senderId: 'user-1',
+  time: '10:47 AM',
+  status: 'sent',
+};
 ```
 
 **Features:**
@@ -602,8 +881,29 @@ const audioMessage: Message = {
 - **Playback speed cycling:** 1.0x → 1.5x → 2.0x → 1.0x
 - **Sender avatar** displayed or current speed overlay
 - **Pause/resume** during playback
-- **Automatic pause** when another audio starts
-- **Duration display** in bottom-right of bubble
+- **Automatic pause** when another audio starts (only one plays at a time, via `AudioContext`)
+- **Duration display** under the waveform
+- **Natural sizing** — audio bubbles size to fit the compact waveform UI, never stretched into the image/video grid box
+- **Multiple audio auto-splitting** — extra audio items beyond the first in one message become their own standalone bubbles, inheriting the parent message's `time` and `status`
+
+WhatsApp-style row inside each audio bubble:
+
+| Side         | Layout (left → right)                        |
+| ------------ | -------------------------------------------- |
+| **Sent**     | Avatar or speed pill → play/pause → waveform |
+| **Received** | play/pause → waveform → avatar or speed pill |
+
+| State           | Avatar slot                                             |
+| --------------- | ------------------------------------------------------- |
+| Idle / finished | `senderAvatar` or first letter of `senderName`          |
+| Playing         | Pill showing **1x**, **1.5x**, or **2x** (tap to cycle) |
+| Ended           | Avatar again                                            |
+
+- Waveform bars with scrubber dot; tap or drag to seek
+- Play/pause is icon-only (no filled circle)
+- Video in the gallery pauses other audio
+
+---
 
 ### Media Grids & Gallery
 
@@ -624,12 +924,13 @@ const albumMessage: Message = {
 ```
 
 **Smart Layouts:**
-| Count | Layout |
-|-------|--------|
-| 1 | Full-width square |
-| 2 | 50/50 side-by-side |
-| 3 | Large left + 2 stacked right |
-| 4+ | 2×2 grid |
+
+| Count | Layout                       | Height |
+| ----- | ---------------------------- | ------ |
+| 1     | Full-width square            | 320px  |
+| 2     | 50/50 side-by-side           | 320px  |
+| 3     | Large left + 2 stacked right | 320px  |
+| 4+    | 2×2 grid, `+N` on last cell  | 320px  |
 
 **Gallery Features:**
 
@@ -640,12 +941,17 @@ const albumMessage: Message = {
 - Close button (X icon)
 - Full-screen immersive viewing
 
+**Audio is never included in the grid or gallery.** Only `image`/`video` items are eligible for grid layout and full-screen viewing — audio items are filtered out and rendered via the standalone `AudioPlayer` UI instead (see [Audio items and bubble splitting](#audio-items-and-bubble-splitting)).
+
+**Legacy single fields:** Legacy `image`, `video`, and `audio` fields on `Message` are normalized into `mediaItems` internally via `collectMediaItems()`. **New integrations should use `mediaItems` directly** rather than the legacy fields — they're kept only for backward compatibility with older message data and will not receive new features (e.g. the multi-audio splitting behavior only applies to items in `mediaItems`).
+
+---
+
 ### Message Replies
 
 Enable conversations within conversations:
 
 ```tsx
-// Reply configuration
 <ChatScreen
   replyProps={{
     enableReply: true,
@@ -686,18 +992,19 @@ const repliedMessage: Message = {
 - Edit indication ("Edited" chip in reply context)
 - Customizable colors and backgrounds
 
-### Typing Indicators
+---
 
-Show who's currently typing:
+### Typing Indicators
 
 ```tsx
 <ChatScreen
   typingUsers={[
-    { id: 'alice', name: 'Alice' },
-    { id: 'bob', name: 'Bob' },
+    { id: 'alice', avatar: 'https://...', name: 'Alice' },
+    { id: 'bob', avatar: 'https://...', name: 'Bob' },
     // If 3+ users, shows "Alice, Bob, +2 more"
   ]}
-  // ... other props
+  onTypingStart={() => console.log('Typing started')}
+  onTypingEnd={() => console.log('Typing ended')}
 />
 ```
 
@@ -707,11 +1014,11 @@ Show who's currently typing:
 - Up to 2 avatars displayed inline
 - "+N more" badge if 3+ users
 - Customizable dot color
-- Auto-dismisses when onTypingEnd called
+- Auto-dismisses when `onTypingEnd` called
 
-### File Attachments
+---
 
-Handle any file type with custom handlers:
+### File Attachments
 
 ```tsx
 const fileMessage: Message = {
@@ -739,51 +1046,52 @@ const fileMessage: Message = {
 
 ```tsx
 <ChatScreen
-  onAttachmentPress={() => {
-    // Custom file picker/handler
+  onFileAttachmentPress={async (file) => {
+    const uri = file.uri.startsWith('file://')
+      ? file.uri
+      : `file://${file.uri}`;
+    await Linking.openURL(uri);
+    // or use react-native-share, react-native-blob-util, etc.
   }}
-  // ... other props
 />
 ```
 
-### Message Selection & Actions
+---
 
-Enable multi-select and bulk operations:
+### Message Selection & Actions
 
 ```tsx
 <ChatScreen
   onMessageLongPress={(message) => {
-    // Long-press opens action menu with options:
-    // - Copy
-    // - Forward
-    // - Reply
-    // - Edit
-    // - Delete
-    // Customizable via messageActionsConfig
+    // Long-press opens action menu with copy/forward/reply/edit/delete
   }}
-  messageActionsConfig={{
-    actions: [
-      'copy', // Copy text to clipboard
-      'forward', // Forward message
-      'reply', // Reply to message
-      'edit', // Edit message content
-      'delete', // Delete message
-    ],
-    // Custom labels
-    labels: {
-      copy: 'Copy Text',
-      forward: 'Share',
-      delete: 'Remove',
-    },
-    // Custom icons (SVG/images)
-    icons: {
-      copy: <CustomCopyIcon />,
-    },
+  messageActionProps={{
+    enableReply: true,
+    enableCopy: true,
+    enableEdit: true,
+    enableDelete: true,
+    enableForward: true,
+    enableSelect: true,
+  }}
+  messageActionLabels={{
+    copy: 'Copy Text',
+    forward: 'Share',
+    delete: 'Remove',
+  }}
+  messageActionIcons={{
+    copy: CustomCopyIcon,
   }}
   selectionUI={{
-    checkboxSize: 24,
-    checkboxColor: '#22c55e',
-    selectedBackground: 'rgba(34, 197, 94, 0.1)',
+    rowBackgroundColor: 'rgba(34, 197, 94, 0.1)',
+  }}
+  onDeleteSelected={(messages) => {
+    /* ... */
+  }}
+  onForwardSelected={(messages) => {
+    /* ... */
+  }}
+  onCopySelected={(messages) => {
+    /* ... */
   }}
 />
 ```
@@ -801,18 +1109,18 @@ Enable multi-select and bulk operations:
   theme={{
     colors: {
       // Sent messages (right-aligned, typically green)
-      sentBubbleBackground: '#22c55e',
-      sentTextColor: '#FFFFFF',
+      sentBubbleBackgroundColor: '#22c55e',
+      sentMessageTextColor: '#FFFFFF',
       sentTimestampColor: 'rgba(255, 255, 255, 0.7)',
-      sentStatusIconColor: '#FFFFFF',
+      sentIconColor: '#FFFFFF',
       sentAudioWaveformColor: 'rgba(255, 255, 255, 0.3)',
       sentAudioWaveformActiveColor: 'rgba(255, 255, 255, 0.95)',
       sentFileAttachmentBackground: 'rgba(255, 255, 255, 0.15)',
       sentFileAttachmentTextColor: '#FFFFFF',
 
       // Received messages (left-aligned, typically gray)
-      receivedBubbleBackground: '#E5E7EB',
-      receivedTextColor: '#1F2937',
+      receivedBubbleBackgroundColor: '#E5E7EB',
+      receivedMessageTextColor: '#1F2937',
       receivedTimestampColor: 'rgba(107, 114, 128, 0.85)',
       receivedAudioWaveformColor: 'rgba(0, 0, 0, 0.2)',
       receivedAudioWaveformActiveColor: 'rgba(0, 0, 0, 0.6)',
@@ -820,10 +1128,10 @@ Enable multi-select and bulk operations:
       receivedFileAttachmentTextColor: '#1F2937',
 
       // Input & UI
-      inputBarBackground: '#FFFFFF',
       inputTextColor: '#1F2937',
-      inputPlaceholderTextColor: '#9CA3AF',
-      typingIndicatorDotColor: '#9CA3AF',
+      placeholderTextColor: '#9CA3AF',
+      inputsIconsColor: '#6B7280',
+      sendIconsColor: '#FFFFFF',
     },
   }}
 />
@@ -834,12 +1142,7 @@ Enable multi-select and bulk operations:
 ```tsx
 <ChatScreen
   theme={{
-    fontFamily: 'Segoe UI', // Custom font
-    fontSize: {
-      message: 16,
-      timestamp: 12,
-      typing: 14,
-    },
+    fontFamily: 'Inter-Regular', // Custom font — load it in your app first
   }}
 />
 ```
@@ -849,38 +1152,26 @@ Enable multi-select and bulk operations:
 ```tsx
 <ChatScreen
   theme={{
-    messageStyle: {
-      sentBubbleStyle: {
+    bubbleStyle: {
+      sent: {
         borderRadius: 16,
         shadowColor: '#000',
         shadowOffset: { width: 0, height: 2 },
         shadowOpacity: 0.1,
         shadowRadius: 4,
         elevation: 3,
-        paddingHorizontal: 12,
-        paddingVertical: 8,
       },
-      receivedBubbleStyle: {
+      received: {
         borderRadius: 16,
-        paddingHorizontal: 12,
-        paddingVertical: 8,
       },
     },
-    mediaGrid: {
-      height: 320,
-      borderRadius: 12,
-    },
   }}
 />
 ```
 
 ### Custom Components & Icons
 
-Override built-in UI icons:
-
 ```tsx
-import { CustomIcon } from './CustomIcon';
-
 <ChatScreen
   // Input bar icons
   CustomEmojiIcon={EmojiIcon}
@@ -892,11 +1183,29 @@ import { CustomIcon } from './CustomIcon';
   // Media previews
   CustomImagePreview={CustomImagePreview}
   CustomVideoPreview={CustomVideoPreview}
+  // Audio playback
+  CustomPlayIcon={PlayIcon}
+  CustomPauseIcon={PauseIcon}
   // Custom input
-  renderCustomInput={(props) => <YourCustomInput {...props} />}
-/>;
+  renderCustomInput={() => <YourCustomInput />}
+/>
 ```
 
+| Prop                                        | Replaces                                              |
+| ------------------------------------------- | ----------------------------------------------------- |
+| `renderCustomInput`                         | Entire input + recorder (you handle preview yourself) |
+| `renderCustomTyping`                        | "Typing…" content                                     |
+| `renderCustomVideoBubbleError`              | Inline video error in grid                            |
+| `CustomVoiceRecorder`                       | Built-in recorder bars                                |
+| `CustomEmojiIcon`                           | Emoji button                                          |
+| `CustomAttachmentIcon`                      | Paperclip                                             |
+| `CustomCameraIcon`                          | Camera                                                |
+| `CustomSendIcon`                            | Send                                                  |
+| `CustomMicrophoneIcon`                      | Mic                                                   |
+| `CustomPlayIcon` / `CustomPauseIcon`        | Audio (and related) playback                          |
+| `CustomFileIcon`                            | Document chip icon                                    |
+| `CustomImagePreview` / `CustomVideoPreview` | Composer thumbnails                                   |
+
 ### Component Overrides
 
 The library exposes individual components for advanced customization:
@@ -904,11 +1213,16 @@ The library exposes individual components for advanced customization:
 ```tsx
 import {
   ChatBubble,
-  ChatInput,
-  MediaViewer,
   AudioPlayer,
-  TypingIndicator,
   VoiceRecorder,
+  VoiceRecordingGesture,
+  VoiceRecorderFlow,
+  LongPressOverlay,
+  MessageActionsPopover,
+  MessageActionsSheet,
+  InlineReply,
+  ReplyPreview,
+  SwipeableMessage,
 } from 'movius-chats';
 
 // Use individually or extend
@@ -919,95 +1233,71 @@ const CustomChatBubble = (props) => <ChatBubble {...props} staticMode={true} />;
 
 ## Project Structure
 
-```
 movius-chats/
 ├── src/
-│   ├── index.tsx                      # Main ChatScreen export
-│   ├── types/
-│   │   └── index.ts                   # TypeScript interfaces
-│   ├── context/
-│   │   ├── ChatContext.tsx            # Main chat state & props
-│   │   └── AudioContext.tsx           # Audio playback coordination
-│   ├── hooks/
-│   │   ├── useKeyboardInset.ts        # iOS/Android keyboard height
-│   │   └── useVoiceRecorder.ts        # Voice recording hook
-│   ├── components/
-│   │   ├── ChatBubble/
-│   │   │   ├── ChatBubble.tsx         # Main bubble component
-│   │   │   ├── MessageContent.tsx     # Message text/media content
-│   │   │   ├── MessageStatus.tsx      # Status checkmarks
-│   │   │   ├── MediaGrid.tsx          # 1/2/3/4+ grid layouts
-│   │   │   └── types.ts
-│   │   ├── ChatInput/
-│   │   │   ├── ChatInput.tsx          # Input bar with buttons
-│   │   │   ├── FilePreview.tsx        # Selected file preview
-│   │   │   └── TruncateFileName.ts
-│   │   ├── AudioPlayer/
-│   │   │   ├── AudioPlayer.tsx        # Audio playback UI
-│   │   │   └── types.ts
-│   │   ├── MediaViewer/
-│   │   │   └── MediaViewer.tsx        # Full-screen gallery
-│   │   ├── MessageActions/
-│   │   │   ├── index.ts
-│   │   │   ├── LongPressOverlay.tsx   # Action menu overlay
-│   │   │   ├── MessageActionsPopover.tsx  # Tablet UI
-│   │   │   └── MessageActionsSheet.tsx    # Mobile bottom sheet
-│   │   ├── Reply/
-│   │   │   ├── index.ts
-│   │   │   ├── SwipeableMessage.tsx   # Swipe gesture handler
-│   │   │   ├── ReplyPreview.tsx       # Input bar reply preview
-│   │   │   └── InlineReply.tsx        # Bubble reply display
-│   │   ├── TypingComponent/
-│   │   │   └── TypingIndicator.tsx    # Animated typing dots
-│   │   └── VoiceRecorder/
-│   │       ├── VoiceRecorder.tsx      # Base recorder UI
-│   │       ├── VoiceRecordingGesture.tsx  # Gesture handlers
-│   │       └── VoiceRecorderFlow/     # Recording modes & UI
-│   ├── utils/
-│   │   ├── bubbleTheme.ts             # Color helpers for sent/received
-│   │   ├── messageMedia.ts            # Media collection utilities
-│   │   ├── messageActions.ts          # Action merging & defaults
-│   │   ├── replyTheme.ts              # Reply styling helpers
-│   │   ├── theme.ts                   # Font & icon size helpers
-│   │   └── datefunc.ts                # Duration formatting
-│   └── assets/
-│       └── Icons/
-│           ├── ArrowBack2RoundedIcon.tsx
-│           ├── CameraIcon.tsx
-│           ├── CheckAllIcon.tsx
-│           ├── CheckIcon.tsx
-│           ├── ChevronUpIcon.tsx
-│           ├── ClosePreviewIcon.tsx
-│           ├── CopyIcon.tsx
-│           ├── EditIcon.tsx
-│           ├── EmojiFunnySquareIcon.tsx
-│           ├── FileIcon.tsx
-│           ├── ForwardIcon.tsx
-│           ├── LoadingIcon.tsx
-│           ├── LockIcon.tsx
-│           ├── MicrophoneIcon.tsx
-│           ├── PaperClipIcon.tsx
-│           ├── PaperPlaneIcon.tsx
-│           ├── PauseIcon.tsx
-│           ├── PlayIcon.tsx
-│           ├── ReplyIcon.tsx
-│           ├── SelectIcon.tsx
-│           ├── TrashIcon.tsx
-│           └── XIcon.tsx
+│ ├── index.tsx # Main ChatScreen export
+│ ├── types/
+│ │ └── index.ts # TypeScript interfaces
+│ ├── context/
+│ │ ├── ChatContext.tsx # Main chat state & props
+│ │ └── AudioContext.tsx # Audio playback coordination
+│ ├── hooks/
+│ │ ├── useKeyboardInset.ts # iOS/Android keyboard height
+│ │ └── useVoiceRecorder.ts # Voice recording hook
+│ ├── components/
+│ │ ├── ChatBubble/
+│ │ │ ├── ChatBubble.tsx # Main bubble + audio-split rendering
+│ │ │ ├── MessageContent.tsx # Text/grid/primary-audio content
+│ │ │ ├── MessageStatus.tsx # Status checkmarks
+│ │ │ ├── MediaGrid.tsx # 1/2/3/4+ grid layouts (image/video only)
+│ │ │ └── types.ts
+│ │ ├── ChatInput/
+│ │ │ ├── ChatInput.tsx # Input bar with buttons
+│ │ │ ├── FilePreview.tsx # Selected file preview
+│ │ │ └── TruncateFileName.ts
+│ │ ├── AudioPlayer/
+│ │ │ ├── AudioPlayer.tsx # Audio playback UI
+│ │ │ └── types.ts
+│ │ ├── MediaViewer/
+│ │ │ └── MediaViewer.tsx # Full-screen gallery (image/video only)
+│ │ ├── MessageActions/
+│ │ │ ├── index.ts
+│ │ │ ├── LongPressOverlay.tsx # Action menu overlay
+│ │ │ ├── MessageActionsPopover.tsx # Tablet UI
+│ │ │ └── MessageActionsSheet.tsx # Mobile bottom sheet
+│ │ ├── Reply/
+│ │ │ ├── index.ts
+│ │ │ ├── SwipeableMessage.tsx # Swipe gesture handler
+│ │ │ ├── ReplyPreview.tsx # Input bar reply preview
+│ │ │ └── InlineReply.tsx # Bubble reply display
+│ │ ├── TypingComponent/
+│ │ │ └── TypingIndicator.tsx # Animated typing dots
+│ │ └── VoiceRecorder/
+│ │ ├── VoiceRecorder.tsx # Base recorder UI
+│ │ ├── VoiceRecordingGesture.tsx # Gesture handlers
+│ │ └── VoiceRecorderFlow/ # Recording modes & UI
+│ ├── utils/
+│ │ ├── bubbleTheme.ts # Color helpers for sent/received
+│ │ ├── messageMedia.ts # Media collection + audio-split utilities
+│ │ ├── messageActions.ts # Action merging & defaults
+│ │ ├── replyTheme.ts # Reply styling helpers
+│ │ ├── theme.ts # Font & icon size helpers
+│ │ └── datefunc.ts # Duration formatting
+│ └── assets/
+│ └── Icons/ # Built-in SVG icons
 ├── lib/
-│   ├── commonjs/          # CommonJS build output
-│   ├── module/            # ES Module build output
-│   └── typescript/        # TypeScript declarations
+│ ├── commonjs/ # CommonJS build output
+│ ├── module/ # ES Module build output
+│ └── typescript/ # TypeScript declarations
 ├── scripts/
-│   └── patchSound.js      # Audio module patching
-├── babel.config.js        # Babel configuration
-├── rollup.config.mjs      # Rollup bundler config
-├── tsconfig.json          # TypeScript config
-├── tsconfig.types.json    # TypeScript types config
-├── tsconfig.build.json    # TypeScript build config
+│ └── patchSound.js # Audio module patching
+├── babel.config.js
+├── rollup.config.mjs
+├── tsconfig.json
+├── tsconfig.types.json
+├── tsconfig.build.json
 ├── package.json
 └── README.md
-```
 
 ---
 
@@ -1045,31 +1335,26 @@ movius-chats/
 
 ## Keyboard Behavior
 
-The library handles platform-specific keyboard behavior automatically:
-
-### iOS
-
-- Soft keyboard slides up from bottom
-- Input bar adjusts position via `KeyboardAvoidingView`
-- Default offset: based on notch/safe area
+| Platform    | Behavior                                                                                          |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| **Android** | `useKeyboardInset` sets `marginBottom` on the input row (= keyboard height)                       |
+| **iOS**     | Same inset **plus** `KeyboardAvoidingView` with `behavior="padding"` and `keyboardVerticalOffset` |
 
-### Android
+If your navigator already avoids the keyboard:
 
-- Keyboard dismisses text field focus automatically
-- Input bar uses `KeyboardAvoidingView`
-- Respects `android:windowSoftInputMode` setting
+```tsx
+<ChatScreen disableKeyboardAvoiding />
+```
 
 ### Customization
 
 ```tsx
-// useKeyboardInset hook provides current inset
+// useKeyboardInset hook provides current inset (internal — usually not needed directly)
 const { keyboardHeight } = useKeyboardInset();
 
-// Manual control via ChatInput props
+// Manual control via renderCustomInput
 <ChatScreen
-  renderCustomInput={(props) => (
-    <YourInput keyboardOffset={customOffset} {...props} />
-  )}
+  renderCustomInput={() => <YourInput keyboardOffset={customOffset} />}
 />;
 ```
 
@@ -1080,21 +1365,28 @@ const { keyboardHeight } = useKeyboardInset();
 Full TypeScript support with exported types:
 
 ```tsx
-import {
-  ChatScreen,
+import ChatScreen from 'movius-chats';
+
+import type {
   Message,
   MessageMediaItem,
   MessageFileAttachment,
   MessageReply,
+  PreviewAttachment,
   RecordingResult,
   ChatScreenProps,
-  ChatScreenTheme,
+  VoiceRecorderExposedState,
   VoiceRecorderConfig,
-  MessageActionsConfig,
+  VoiceRecorderStyleOverrides,
+  RecordingUIProps,
+  MessageActionFlags,
+  MessageActionUIProps,
+  MessageActionLabels,
   ReplyConfig,
-} from 'movius-chats';
+  ReplyUIProps,
+  SelectionUIProps,
+} from 'movius-chats/lib/typescript/types';
 
-// Use types in your code
 const message: Message = {
   id: '1',
   text: 'Hello',
@@ -1106,12 +1398,7 @@ const message: Message = {
 type Props = ChatScreenProps;
 ```
 
-### Type Definitions
-
-All types are exported from `lib/typescript/index.d.ts` and available in:
-
-- `lib/commonjs/index.d.ts` (CommonJS version)
-- `lib/module/index.d.ts` (ES Module version)
+Source types while developing against the repo: `movius-chats/src/types` (field `"react-native": "src"` in `package.json`).
 
 ---
 
@@ -1120,41 +1407,40 @@ All types are exported from `lib/typescript/index.d.ts` and available in:
 ### Custom Message Actions
 
 ```tsx
-import {
-  mergeMessageActionLabels,
-  mergeMessageActionIcons,
-} from 'movius-chats';
-
 <ChatScreen
-  messageActionsConfig={{
-    actions: ['copy', 'reply', 'customAction', 'delete'],
-    labels: mergeMessageActionLabels({
-      customAction: 'Pin Message',
-      delete: 'Remove',
-    }),
-    icons: mergeMessageActionIcons({
-      customAction: <PinIcon />,
-    }),
+  messageActionProps={{
+    enableReply: true,
+    enableCopy: true,
+    enableEdit: true,
+    enableDelete: true,
+    enableForward: true,
+    enableSelect: false,
   }}
-  onMessageActionTap={(action, message) => {
-    if (action === 'customAction') {
-      // Handle custom action
-    }
+  messageActionLabels={{
+    delete: 'Remove',
   }}
-/>;
+  onCopyMessage={(message) => {
+    /* ... */
+  }}
+  onDeleteMessage={(message) => {
+    /* ... */
+  }}
+  onForwardMessage={(message) => {
+    /* ... */
+  }}
+/>
 ```
 
 ### Static Message Display (Read-Only)
 
 ```tsx
-// Disable all interactivity
 import { ChatBubble } from 'movius-chats';
 
 <ChatBubble
   message={message}
   isCurrentUser={false}
+  isFirstInSequence
   staticMode={true}
-  onLongPress={() => {}}
 />;
 ```
 
@@ -1163,9 +1449,9 @@ import { ChatBubble } from 'movius-chats';
 ```tsx
 <ChatScreen
   typingUsers={[
-    { id: 'alice', name: 'Alice' },
-    { id: 'bob', name: 'Bob' },
-    { id: 'charlie', name: 'Charlie' },
+    { id: 'alice', avatar: 'https://...', name: 'Alice' },
+    { id: 'bob', avatar: 'https://...', name: 'Bob' },
+    { id: 'charlie', avatar: 'https://...', name: 'Charlie' },
   ]}
   onTypingStart={() => console.log('Typing started')}
   onTypingEnd={() => console.log('Typing ended')}
@@ -1175,15 +1461,14 @@ import { ChatBubble } from 'movius-chats';
 ### Custom Theme Colors (Dark Mode)
 
 ```tsx
-const darkTheme: ChatScreenTheme = {
+const darkTheme = {
   colors: {
-    sentBubbleBackground: '#128C7E',    // WhatsApp green
-    sentTextColor: '#FFFFFF',
-    receivedBubbleBackground: '#1F2937', // Dark gray
-    receivedTextColor: '#F3F4F6',
-    inputBarBackground: '#0F172A',
+    sentBubbleBackgroundColor: '#128C7E',    // WhatsApp green
+    sentMessageTextColor: '#FFFFFF',
+    receivedBubbleBackgroundColor: '#1F2937', // Dark gray
+    receivedMessageTextColor: '#F3F4F6',
     inputTextColor: '#F3F4F6',
-    inputPlaceholderTextColor: '#6B7280',
+    placeholderTextColor: '#6B7280',
   },
   fontFamily: 'Roboto',
 };
@@ -1193,258 +1478,45 @@ const darkTheme: ChatScreenTheme = {
 
 ### Handling Large Message Lists
 
-For performance with 1000+ messages:
+For performance with large lists:
 
 ```tsx
-// 1. Use virtualization (FlatList is already virtualized)
-// 2. Minimize re-renders with useMemo
-// 3. Lazy-load older messages
+// 1. The list is already virtualized via FlatList
+// 2. Paginate older messages with onEndReached
+// 3. Cache the most recent page locally for instant reopen (e.g. MMKV)
 
 const [messages, setMessages] = useState<Message[]>([
-  // Latest 50 messages
+  // Latest page of messages
 ]);
 
-const handleScroll = (offset: number) => {
-  if (offset > 500) {
-    // Load older messages from backend
-    loadMoreMessages();
-  }
-};
+<ChatScreen
+  messages={messages}
+  onEndReached={loadOlderMessages}
+  isLoadingMoreMessages={isFetchingOlder}
+/>;
 ```
 
 ---
 
 ## Troubleshooting
 
-### Issue: Voice recording not working
-
-**Symptoms:** Recording button doesn't respond or crashes
-
-**Solutions:**
-
-1. **Check permissions:**
-
-   ```tsx
-   import { PermissionsAndroid } from 'react-native';
-   const granted = await PermissionsAndroid.request(
-     PermissionsAndroid.PERMISSIONS.RECORD_AUDIO
-   );
-   ```
-
-2. **Install audio dependencies:**
-
-   ```bash
-   npm install react-native-audio-record react-native-fs
-   ```
-
-3. **Verify native linking (Android):**
-   ```bash
-   cd android && ./gradlew clean && cd ..
-   npx react-native run-android
-   ```
-
-### Issue: Media gallery doesn't display
-
-**Symptoms:** Images/videos not showing in gallery
-
-**Solutions:**
-
-1. **Verify URIs are valid:**
-
-   ```tsx
-   const mediaItems = [
-     { uri: 'file:///path/to/image.jpg', kind: 'image' },
-     // Not 'file:///path/to/image.jpg/' (no trailing slash)
-   ];
-   ```
-
-2. **Check MediaGrid height:**
-
-   ```tsx
-   theme={{
-     mediaGrid: { height: 320 }
-   }}
-   ```
-
-3. **Grant file permissions:**
-   - **Android:** Add `READ_EXTERNAL_STORAGE` permission
-   - **iOS:** Add `NSPhotoLibraryUsageDescription` to Info.plist
-
-### Issue: Audio playback cutting off
-
-**Symptoms:** Audio stops playing prematurely or doesn't play at all
-
-**Solutions:**
-
-1. **Check audio format:** Use supported formats (MP3, M4A, AAC)
-2. **Verify URI is accessible:**
-
-   ```tsx
-   // Correct
-   {
-     mediaItems: [{ uri: 'file:///documents/voice.m4a', kind: 'audio' }],
-   }
-
-   // Wrong
-   {
-     mediaItems: [{ uri: 'file://documents/voice.m4a', kind: 'audio' }],
-   } // Missing /
-   ```
-
-3. **Clear audio cache:**
-   ```tsx
-   const { clearAudioCache } = useAudio();
-   clearAudioCache();
-   ```
-
-### Issue: Keyboard overlaps input
-
-**Symptoms:** Chat input hidden when keyboard appears
-
-**Solutions:**
-
-1. **Verify KeyboardAvoidingView:**
-
-   ```tsx
-   // Already built-in, check if overridden
-   <KeyboardAvoidingView
-     behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
-   >
-     <ChatScreen ... />
-   </KeyboardAvoidingView>
-   ```
-
-2. **Adjust offset:**
-
-   ```tsx
-   <KeyboardAvoidingView keyboardVerticalOffset={100}>...</KeyboardAvoidingView>
-   ```
-
-3. **Check AndroidManifest.xml:**
-   ```xml
-   <activity
-     android:windowSoftInputMode="adjustResize"
-   />
-   ```
-
-### Issue: Memory leaks
-
-**Symptoms:** App crashes with large message lists, performance degrades
-
-**Solutions:**
-
-1. **Cleanup contexts:**
-
-   ```tsx
-   useEffect(() => {
-     return () => {
-       clearMediaViewerGallery?.();
-       // Cleanup
-     };
-   }, []);
-   ```
-
-2. **Use FlatList optimizations:**
-
-   ```tsx
-   <FlatList
-     removeClippedSubviews={true}
-     maxToRenderPerBatch={10}
-     windowSize={21}
-     updateCellsBatchingPeriod={50}
-   />
-   ```
-
-3. **Avoid inline function callbacks:**
-
-   ```tsx
-   // Bad
-   onSendMessage={(text) => { ... }}
-
-   // Good
-   const handleSend = useCallback((text) => { ... }, []);
-   <ChatScreen onSendMessage={handleSend} />
-   ```
-
-### Issue: TypeScript errors
-
-**Symptoms:** Type checking fails, missing types
-
-**Solutions:**
-
-1. **Regenerate types:**
-
-   ```bash
-   npm run build:types
-   ```
-
-2. **Check tsconfig.json:**
-
-   ```json
-   {
-     "compilerOptions": {
-       "strict": true,
-       "skipLibCheck": true
-     }
-   }
-   ```
-
-3. **Update type definitions:**
-   ```bash
-   npm install --save-dev @types/react-native@latest
-   ```
-
-### Issue: Android build fails
-
-**Symptoms:** Gradle/NDK errors during build
-
-**Solutions:**
-
-1. **Enable AndroidX:**
-
-   ```properties
-   # android/gradle.properties
-   android.useAndroidX=true
-   android.enableJetifier=true
-   ```
-
-2. **Update Gradle:**
-
-   ```properties
-   # android/gradle/wrapper/gradle-wrapper.properties
-   distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-all.zip
-   ```
-
-3. **Clean build:**
-   ```bash
-   cd android
-   ./gradlew clean
-   cd ..
-   npx react-native run-android
-   ```
-
-### Issue: Reply gestures not working
-
-**Symptoms:** Swipe-to-reply doesn't trigger
-
-**Solutions:**
-
-1. **Enable reply config:**
-
-   ```tsx
-   replyProps={{
-     enableReply: true,
-     swipeThreshold: 60,  // Pixels to swipe
-   }}
-   ```
-
-2. **Check gesture handler:**
-
-   ```bash
-   npm install react-native-gesture-handler@latest
-   ```
-
-3. **Verify RectButton nesting** (GestureHandler requirement)
+| Problem                                                   | What to do                                                                                                                                                                                      |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot read property 'init' of null`                     | Install `react-native-audio-record`, run `pod install`, **rebuild** the app                                                                                                                     |
+| Recording never starts                                    | Mic permission; iOS `NSMicrophoneUsageDescription`; Android `RECORD_AUDIO`                                                                                                                      |
+| No audio playback                                         | Ensure `react-native-video` is linked; URI must be `file://` or `http(s)://`                                                                                                                    |
+| Audio message shows a large empty box above the waveform  | Audio items no longer render inside the image/video grid box — always uses a compact standalone UI. If seeing this, confirm you're not passing audio through the legacy `image`/`video` fields. |
+| Multiple audio clips squished into one grid cell          | Fixed — any audio beyond the first in `mediaItems` splits into its own standalone bubble below the main one automatically.                                                                      |
+| Standalone split audio bubble missing timestamp/checkmark | Split audio bubbles inherit `time` and `status` from the parent message automatically — no action needed.                                                                                       |
+| `NoSuchMethodError` `DefaultLoadControl` (Android)        | Force `androidx.media3` to a consistent version (matching what `react-native-video` expects) in the app `android/build.gradle` `resolutionStrategy`, then clean-rebuild.                        |
+| Reanimated error                                          | `react-native-reanimated/plugin` must be **last** in Babel plugins                                                                                                                              |
+| Font not applied                                          | Register font in the **host** app; pass exact `fontFamily` string                                                                                                                               |
+| `inputIconSize` ignored on send/mic                       | By design                                                                                                                                                                                       |
+| Keyboard covers input (Android)                           | `android:windowSoftInputMode="adjustResize"`; parent `flex: 1`                                                                                                                                  |
+| × clears all previews                                     | Implement `onRemovePreviewItem`                                                                                                                                                                 |
+| Wrong audio avatar                                        | Set `senderAvatar` and `senderName` on the `Message`                                                                                                                                            |
+| Messages upside down                                      | Newest message must be at `messages[0]`                                                                                                                                                         |
+| Reply gestures not working                                | Ensure `replyProps.enableReply` is `true`, `react-native-gesture-handler` is up to date, and `GestureHandlerRootView` wraps your app                                                            |
 
 ---
 
@@ -1461,26 +1533,14 @@ Contributions welcome! Please:
 ### Development Setup
 
 ```bash
-# Clone repo
 git clone https://github.com/David-Atueyi/Movius-Chats.git
 cd Movius-Chats
 
-# Install dependencies
 npm install
-
-# Run tests
 npm run test
-
-# Type check
 npm run typescript
-
-# Lint
 npm run lint
-
-# Build
 npm run build
-
-# View types
 npm run build:types
 ```
 
@@ -1513,559 +1573,3 @@ ISC License — see [LICENSE](LICENSE) file for details.
 ---
 
 **Built with ❤️ for React Native developers.**
-|---------|----------|
-| `react` ≥ 16.8 | Yes |
-| `react-native` | Yes |
-| `react-native-reanimated` | Yes (voice recorder animations) |
-
-### Optional peers (voice recording only)
-
-| Package                     | Use                              |
-| --------------------------- | -------------------------------- |
-| `react-native-audio-record` | Record microphone                |
-| `react-native-fs`           | Delete cancelled recording files |
-
-If these are missing, the UI still renders; starting a recording logs an install hint.
-
-**There is no `react-native-sound`, `expo-av`, `expo-file-system`, or other Expo package in this library.**
-
----
-
-## Installation
-
-### 1. Install movius-chats
-
-```bash
-yarn add movius-chats
-# or: npm install movius-chats
-# or: bun add movius-chats
-```
-
-### 2. Install peers
-
-```bash
-yarn add react-native-reanimated react-native-video react-native-svg
-```
-
-`react-native-video` and `react-native-svg` are also pulled in as movius-chats dependencies, but your app should list compatible versions and link native code.
-
-### 3. Reanimated (Babel)
-
-Put this plugin **last** in `babel.config.js`:
-
-```js
-module.exports = {
-  presets: ['module:metro-react-native-babel-preset'],
-  plugins: [
-    // ...other plugins
-    'react-native-reanimated/plugin',
-  ],
-};
-```
-
-### 4. Voice recording (optional)
-
-```bash
-yarn add react-native-audio-record react-native-fs
-```
-
-**iOS** — add to `Info.plist`:
-
-```xml
-<key>NSMicrophoneUsageDescription</key>
-<string>This app needs the microphone to record voice messages.</string>
-```
-
-**Android** — ensure `RECORD_AUDIO` is in `AndroidManifest.xml` (often added by the audio-record library).
-
-Then rebuild native apps:
-
-```bash
-cd ios && pod install && cd ..
-npx react-native run-ios
-npx react-native run-android
-```
-
-### 5. Android keyboard
-
-In `android/app/src/main/AndroidManifest.xml` on your main activity:
-
-```xml
-android:windowSoftInputMode="adjustResize"
-```
-
----
-
-## Quick start
-
-```tsx
-import React, { useState } from 'react';
-import { Platform, SafeAreaView, View } from 'react-native';
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import ChatScreen from 'movius-chats';
-import type { Message } from 'movius-chats/lib/typescript/types';
-
-export default function ChatDetailScreen() {
-  const insets = useSafeAreaInsets();
-  const currentUserId = '1';
-  const [messages, setMessages] = useState<Message[]>([]);
-
-  return (
-    <SafeAreaView style={{ flex: 1 }}>
-      <View style={{ flex: 1 }}>
-        <ChatScreen
-          messages={messages}
-          currentUserId={currentUserId}
-          onSendMessage={({ text, senderId }) => {
-            setMessages((prev) => [
-              {
-                id: String(Date.now()),
-                text,
-                senderId,
-                time: new Date().toLocaleTimeString([], {
-                  hour: '2-digit',
-                  minute: '2-digit',
-                }),
-                status: 'sent',
-              },
-              ...prev,
-            ]);
-          }}
-          keyboardVerticalOffset={Platform.OS === 'ios' ? insets.top : 0}
-          showBubbleTail
-          showMessageStatus
-          showVoiceRecordButton
-        />
-      </View>
-    </SafeAreaView>
-  );
-}
-```
-
-Wrap the screen in `flex: 1`. Load custom fonts in **your** app before passing `theme.fontFamily`.
-
----
-
-## Message data model
-
-### `Message`
-
-| Field             | Type                              | Description                                |
-| ----------------- | --------------------------------- | ------------------------------------------ |
-| `id`              | `string`                          | Unique id                                  |
-| `senderId`        | `string`                          | Who sent it                                |
-| `time`            | `string`                          | Display time (you format it)               |
-| `status`          | `'sent' \| 'delivered' \| 'read'` | Checkmarks on **your** messages only       |
-| `text`            | `string`                          | Body text                                  |
-| `audio`           | `string`                          | Audio file URI                             |
-| `image`           | `string`                          | Single image (legacy; prefer `mediaItems`) |
-| `video`           | `string`                          | Single video (legacy)                      |
-| `mediaItems`      | `MessageMediaItem[]`              | Album in one bubble                        |
-| `fileAttachments` | `MessageFileAttachment[]`         | PDF, doc, etc.                             |
-| `senderName`      | `string`                          | Group name + audio avatar initial          |
-| `senderAvatar`    | `string`                          | Image URI for audio bubble avatar          |
-
-### `MessageMediaItem`
-
-```ts
-{
-  uri: string;
-  kind: 'image' | 'video' | 'audio';
-}
-```
-
-### `MessageFileAttachment`
-
-```ts
-{
-  uri: string;
-  type: string;
-  name: string;
-}
-```
-
-### `PreviewAttachment` (composer)
-
-```ts
-{ uri: string; type: string; name?: string }
-```
-
-### `RecordingResult` (`onAudioRecordEnd`)
-
-```ts
-{ uri: string; duration: number; mimeType?: string; size?: number }
-```
-
----
-
-## Message list order
-
-The list is **inverted**. Newest message must be **index 0**:
-
-```ts
-setMessages((prev) => [newMessage, ...prev]);
-```
-
-Avatars and bubble tails show only on the **first** message in a consecutive run from the same `senderId`.
-
----
-
-## ChatScreen API
-
-Default export: `ChatScreen`. All props are optional except `messages`, `currentUserId`, and `onSendMessage`.
-
-### Core
-
-| Prop                      | Type                                                  | Description                                     |
-| ------------------------- | ----------------------------------------------------- | ----------------------------------------------- |
-| `messages`                | `Message[]`                                           | Newest first                                    |
-| `currentUserId`           | `string`                                              | Sent vs received layout                         |
-| `onSendMessage`           | `(Omit<Message, 'id' \| 'time' \| 'status'>) => void` | Send button                                     |
-| `onMessageLongPress`      | `(message: Message) => void`                          | Long-press bubble                               |
-| `placeholder`             | `string`                                              | Input placeholder (default `"Message"`)         |
-| `keyboardVerticalOffset`  | `number`                                              | **iOS only** — passed to `KeyboardAvoidingView` |
-| `disableKeyboardAvoiding` | `boolean`                                             | Turn off built-in keyboard lift                 |
-
-### Feature flags (default `false`)
-
-`showAvatars`, `showUserNames`, `showBubbleTail`, `showMessageStatus`, `showEmojiButton`, `showAttachmentsButton`, `showCameraButton`, `showVoiceRecordButton`
-
-### Callbacks
-
-| Prop                            | Description                                         |
-| ------------------------------- | --------------------------------------------------- |
-| `onTypingStart` / `onTypingEnd` | Input text empty ↔ non-empty                       |
-| `onAttachmentPress`             | Paperclip — open your picker                        |
-| `onCameraPress`                 | Camera icon                                         |
-| `onAudioRecordStart`            | Recording began                                     |
-| `onAudioRecordEnd`              | `(RecordingResult?) => void` when done or cancelled |
-| `onFileAttachmentPress`         | File chip in bubble (default: `Linking.openURL`)    |
-
-### Composer preview
-
-| Prop                  | Description                                  |
-| --------------------- | -------------------------------------------- |
-| `previewItems`        | Multiple attachments before send             |
-| `previewData`         | Single attachment (legacy)                   |
-| `onRemovePreviewItem` | `(uri) => void` — remove **one** card by URI |
-| `closePreview`        | Clears all if `onRemovePreviewItem` not set  |
-
-When preview or text exists, the **send** icon shows instead of the mic.
-
-### Voice recorder customization
-
-| Prop                         | Type                                                                        |
-| ---------------------------- | --------------------------------------------------------------------------- |
-| `CustomVoiceRecorder`        | `(VoiceRecorderExposedState) => ReactNode` — replace entire recorder UI     |
-| `theme.voiceRecorder.config` | `VoiceRecorderConfig` — `maxDuration`, lock, slide-to-cancel, etc.          |
-| `theme.voiceRecorder.ui`     | `RecordingUIProps` — colors/sizes for timer, lock pill, recorder play/pause |
-| `theme.voiceRecorder.styles` | `VoiceRecorderStyleOverrides`                                               |
-
-### Typing
-
-| Prop          | Type                     |
-| ------------- | ------------------------ |
-| `typingUsers` | `{ id, avatar, name }[]` |
-
----
-
-## Voice recording
-
-Requires **`react-native-audio-record`** and **`react-native-fs`** in the host app, plus a **native rebuild**.
-
-### Gestures
-
-| Action                    | Result                                                                       |
-| ------------------------- | ---------------------------------------------------------------------------- |
-| **Tap** mic               | Normal bar: trash, timer, waveform, play/pause preview, send                 |
-| **Long-press** mic        | Hold mode: “slide to cancel”, lock column above send                         |
-| Slide **left**            | Cancel (file deleted via `react-native-fs`)                                  |
-| Slide **up** to lock      | Switches to normal bar (`lockSlideDistance` in `theme.voiceRecorder.config`) |
-| **Release** without slide | Auto-send (`onAudioRecordEnd`)                                               |
-
-### Wiring
-
-```tsx
-<ChatScreen
-  showVoiceRecordButton
-  onAudioRecordEnd={(result) => {
-    if (!result) return;
-    setMessages((prev) => [
-      {
-        id: String(Date.now()),
-        senderId: currentUserId,
-        mediaItems: [{ uri: result.uri, kind: 'audio' }],
-        time: '10:56 PM',
-        status: 'sent',
-        senderAvatar: myAvatarUri,
-        senderName: myDisplayName,
-      },
-      ...prev,
-    ]);
-  }}
-/>
-```
-
-### Custom recorder UI
-
-```tsx
-CustomVoiceRecorder={(state) => (
-  <MyRecorder
-    duration={state.duration}
-    onStop={state.stopRecording}
-    onCancel={state.cancelRecording}
-  />
-)}
-```
-
----
-
-## Audio message bubbles
-
-WhatsApp-style row inside the bubble:
-
-| Side         | Layout (left → right)                        |
-| ------------ | -------------------------------------------- |
-| **Sent**     | Avatar or speed pill → play/pause → waveform |
-| **Received** | play/pause → waveform → avatar or speed pill |
-
-| State           | Avatar slot                                             |
-| --------------- | ------------------------------------------------------- |
-| Idle / finished | `senderAvatar` or first letter of `senderName`          |
-| Playing         | Pill showing **1x**, **1.5x**, or **2x** (tap to cycle) |
-| Ended           | Avatar again                                            |
-
-- Waveform bars with scrubber dot; tap or drag to seek
-- Duration under the waveform
-- Play/pause is icon-only (no filled circle)
-- Only one audio plays at a time (`AudioContext`)
-- Video in the gallery pauses other audio
-
-```tsx
-{
-  id: 'a1',
-  senderId: '2',
-  mediaItems: [{ uri: 'file:///data/user/0/.../voice.wav', kind: 'audio' }],
-  senderAvatar: 'https://cdn.example.com/u2.jpg',
-  senderName: 'Alex',
-  time: '10:23 pm',
-  status: 'read',
-}
-```
-
----
-
-## Media grids & gallery
-
-### Grid (`mediaItems`)
-
-| Count | Layout                 | Height |
-| ----- | ---------------------- | ------ |
-| 1     | Full width, cover      | 320px  |
-| 2     | Two columns            | 320px  |
-| 3     | One top, two bottom    | 320px  |
-| 4+    | 2×2, `+N` on last cell | 320px  |
-
-Tap opens `MediaViewer`. Thumbnail `Video` uses `pointerEvents="none"` so presses reach the parent.
-
-### Gallery behavior
-
-- Horizontal `FlatList`, `n / total` header
-- **Videos** play only if that video was the tapped item and the page is active
-- Tapping an **image** in a mixed album does not start other videos
-- Composer video previews **do** autoplay in the small preview card
-
-### Legacy single fields
-
-Legacy `image`, `video`, and `audio` fields on `Message` are normalized into `mediaItems` internally via `collectMediaItems()`.
-
----
-
-## Composer attachment preview
-
-Controlled from your app state:
-
-```tsx
-const [previews, setPreviews] = useState<PreviewAttachment[]>([]);
-
-<ChatScreen
-  previewItems={previews}
-  onRemovePreviewItem={(uri) =>
-    setPreviews((p) => p.filter((x) => x.uri !== uri))
-  }
-  onAttachmentPress={openYourDocumentPicker}
-  onSendMessage={handleSend}
-/>;
-```
-
-| Preview type  | UI                                  |
-| ------------- | ----------------------------------- |
-| 1 image/video | Single thumb + ×                    |
-| 2–3 media     | Fanned stack, × on each             |
-| 4+ media      | Fan of 3 + `+N`, × per visible card |
-| Documents     | Chips; scrollable after 3           |
-
-Use any picker you want (`react-native-document-picker`, `react-native-image-picker`, etc.) — movius-chats only displays `previewItems`.
-
----
-
-## Theme & styling
-
-Pass `theme` to `ChatScreen`. `theme.fontFamily` applies to **all** `Text` in the package (load the font in your app first).
-
-### `theme.colors` — per side (`sent*` / `received*`)
-
-| Keys                                                                      | Used for                              |
-| ------------------------------------------------------------------------- | ------------------------------------- |
-| `sentTimestampColor` / `receivedTimestampColor`                           | Message & file timestamps             |
-| `sentMessageTextColor` / `receivedMessageTextColor`                       | Bubble text                           |
-| `sentBubbleBackgroundColor` / `receivedBubbleBackgroundColor`             | Bubble background                     |
-| `sentMessageTailColor` / `receivedMessageTailColor`                       | Corner tail (`ArrowBack2RoundedIcon`) |
-| `sentFileAttachmentBackground` / `receivedFileAttachmentBackground`       | File chip                             |
-| `sentFileAttachmentTextColor` / `receivedFileAttachmentTextColor`         | File name                             |
-| `sentFileAttachmentSubtitleColor` / `receivedFileAttachmentSubtitleColor` | MIME line                             |
-| `sentAudioWaveformColor` / `receivedAudioWaveformColor`                   | Inactive waveform bars                |
-| `sentAudioWaveformActiveColor` / `receivedAudioWaveformActiveColor`       | Active bars + scrubber                |
-| `sentAudioTimestampColor` / `receivedAudioTimestampColor`                 | Duration under waveform               |
-| `sentAudioPlayIconColor` / `receivedAudioPlayIconColor`                   | Play icon                             |
-| `sentAudioPauseIconColor` / `receivedAudioPauseIconColor`                 | Pause icon                            |
-| `sentAudioSpeedTextColor` / `receivedAudioSpeedTextColor`                 | **1x / 1.5x / 2x** pill text          |
-| `sentMediaTimestampBackground` / `receivedMediaTimestampBackground`       | Timestamp pill on file-only bubbles   |
-
-**Not themeable:** image/video-only messages (no text, no audio) always use **white** (`#ffffff`) for the timestamp text.
-
-### Shared colors
-
-`inputsIconsColor`, `sendIconsColor`, `placeholderTextColor`, `inputTextColor`, `sentIconColor`, `deliveredIconColor`, `readIconColor`, `videoPlayIconColor`
-
-### `theme.sizes`
-
-`inputIconSize` — number (px) or twrnc class string; affects **emoji, paperclip, camera only** (not send/mic).
-
-### `theme.bubbleStyle`
-
-`sent`, `received`, `avatarTextStyle`, `userNameStyle`, `avatarImageStyle`, typing styles.
-
-### `theme.messageStyle`
-
-Text styles, file attachment styles, `progressBarStyle`, `activeProgressBarStyle`, `audioDurationStyle`, `audioSpeedButtonStyle`, `audioSpeedTextStyle`, media timestamp container styles.
-
-### `theme.inputStyles` / `theme.filePreviewStyle`
-
-Input row, send button, preview strip.
-
-### Example
-
-```tsx
-<ChatScreen
-  theme={{
-    fontFamily: 'Inter-Regular',
-    colors: {
-      sentBubbleBackgroundColor: '#005C4B',
-      receivedBubbleBackgroundColor: '#1F2C34',
-      sentAudioSpeedTextColor: '#FFFFFF',
-      receivedAudioSpeedTextColor: '#E5E7EB',
-      sentAudioWaveformActiveColor: '#53BDEB',
-      receivedAudioWaveformActiveColor: '#53BDEB',
-    },
-    sizes: { inputIconSize: 22 },
-  }}
-/>
-```
-
----
-
-## Keyboard behavior
-
-Built into `ChatScreen`:
-
-| Platform    | Behavior                                                                                          |
-| ----------- | ------------------------------------------------------------------------------------------------- |
-| **Android** | `useKeyboardInset` sets `marginBottom` on the input row (= keyboard height)                       |
-| **iOS**     | Same inset **plus** `KeyboardAvoidingView` with `behavior="padding"` and `keyboardVerticalOffset` |
-
-If your navigator already avoids the keyboard:
-
-```tsx
-<ChatScreen disableKeyboardAvoiding />
-```
-
----
-
-## Custom components & icons
-
-| Prop                                        | Replaces                                              |
-| ------------------------------------------- | ----------------------------------------------------- |
-| `renderCustomInput`                         | Entire input + recorder (you handle preview yourself) |
-| `renderCustomTyping`                        | “Typing…” content                                     |
-| `renderCustomVideoBubbleError`              | Inline video error in grid                            |
-| `CustomVoiceRecorder`                       | Built-in recorder bars                                |
-| `CustomEmojiIcon`                           | Emoji button                                          |
-| `CustomAttachmentIcon`                      | Paperclip                                             |
-| `CustomCameraIcon`                          | Camera                                                |
-| `CustomSendIcon`                            | Send                                                  |
-| `CustomMicrophoneIcon`                      | Mic                                                   |
-| `CustomPlayIcon` / `CustomPauseIcon`        | Audio (and related) playback                          |
-| `CustomFileIcon`                            | Document chip icon                                    |
-| `CustomImagePreview` / `CustomVideoPreview` | Composer thumbnails                                   |
-
-### File attachments - Custom handlers
-
-Default tap uses React Native `Linking.openURL`. For local files or share sheets, you can implement custom handlers in your app:
-
-```tsx
-import { Linking } from 'react-native';
-// or: react-native-share, react-native-blob-util, etc.
-
-onFileAttachmentPress={async (file) => {
-  const uri = file.uri.startsWith('file://') ? file.uri : `file://${file.uri}`;
-  await Linking.openURL(uri);
-}}
-```
-
----
-
-## TypeScript
-
-```ts
-import ChatScreen from 'movius-chats';
-
-import type {
-  Message,
-  MessageMediaItem,
-  MessageFileAttachment,
-  PreviewAttachment,
-  RecordingResult,
-  ChatScreenProps,
-  VoiceRecorderExposedState,
-  VoiceRecorderConfig,
-  VoiceRecorderStyleOverrides,
-  RecordingUIProps,
-} from 'movius-chats/lib/typescript/types';
-```
-
-Source types while developing against the repo: `movius-chats/src/types` (field `"react-native": "src"` in package.json).
-
----
-
-## Troubleshooting
-
-| Problem                                            | What to do                                                                                  |
-| -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `Cannot read property 'init' of null`              | Install `react-native-audio-record`, run `pod install`, **rebuild** the app                 |
-| Recording never starts                             | Mic permission; iOS `NSMicrophoneUsageDescription`; Android `RECORD_AUDIO`                  |
-| No audio playback                                  | Ensure `react-native-video` is linked; URI must be `file://` or `http(s)://`                |
-| `NoSuchMethodError` `DefaultLoadControl` (Android) | Force `androidx.media3` to **1.3.1** in the app `android/build.gradle` `resolutionStrategy` |
-| Reanimated error                                   | `react-native-reanimated/plugin` must be **last** in Babel plugins                          |
-| Font not applied                                   | Register font in the **host** app; pass exact `fontFamily` string                           |
-| `inputIconSize` ignored on send/mic                | By design                                                                                   |
-| Keyboard covers input (Android)                    | `android:windowSoftInputMode="adjustResize"`; parent `flex: 1`                              |
-| × clears all previews                              | Implement `onRemovePreviewItem`                                                             |
-| Wrong audio avatar                                 | Set `senderAvatar` and `senderName` on the `Message`                                        |
-| Messages upside down                               | Newest at `messages[0]`                                                                     |
-
----
-
-## License
-
-ISC — see [package.json](./package.json).