npm - @realtimexsco/live-chat - Versions diffs - 1.3.1 → 1.3.2 - Mend

@realtimexsco/live-chat 1.3.1 → 1.3.2

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

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,1853 +1,73 @@
 # @realtimexsco/live-chat
-> Complete real-time chat UI for **React** and **Next.js** — DMs, groups, reactions, replies, forwarding, pins, stars, attachments, search, light/dark theme, locale/timezone, and **full UI customization** (replace the whole chat or any single component).
+> Drop-in real-time chat UI for React and Next.js — direct messages, group chats, reactions, replies, forwarding, pinned/starred messages, and more. Built on Socket.IO, Zustand, Tailwind CSS v4, and Radix UI.
+[![npm version](https://img.shields.io/npm/v/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
+[![npm downloads](https://img.shields.io/npm/dm/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
+[![license](https://img.shields.io/npm/l/@realtimexsco/live-chat.svg)](./LICENSE)
 | | |
 |---|---|
-| **Package name** | `@realtimexsco/live-chat` |
-| **Registry** | [npm](https://www.npmjs.com/) (public — no `.npmrc` required) |
-| **Styles entry** | `@realtimexsco/live-chat/styles.css` |
+| **Package** | [`@realtimexsco/live-chat`](https://www.npmjs.com/package/@realtimexsco/live-chat) |
+| **Styles** | `@realtimexsco/live-chat/styles.css` |
 | **Requires** | React 17+, Tailwind CSS **v4**, Zustand 4+ |
-| **Current version** | `1.1.0` |
-Socket.IO client, REST API client, Zustand store, Radix UI, emoji picker, and all chat UI are **bundled inside the package**. Your app only installs a few peer dependencies.
----
-## Start here (5-minute overview)
-1. **Install** the package + peers (`react`, `react-dom`, `zustand`, `tailwindcss` v4).
-2. **Import CSS** — `@import "@realtimexsco/live-chat/styles.css"` and add Tailwind `@source` for the package `dist` files.
-3. **Create** `chat.config.ts` with `clientId`, `accessToken`, `loggedUserDetails`, `apiUrl`, `socketUrl`.
-4. **Render** `<ChatMain {...chatConfig} />` — the package includes a built-in viewport wrapper. For admin templates use `viewportHeight="calc(100dvh - 4rem)"`; for full-page chat use `viewportHeight="screen"`.
-5. **Optional** — pass `components`, `classNames`, or `features` to customize. **Omit any slot → package default is used automatically.**
-```tsx
-// Full page
-<ChatMain {...chatConfig} viewportHeight="screen" />
-// Admin shell with 4rem header (Elstar, Metronic, etc.)
-<ChatMain {...chatConfig} viewportHeight="calc(100dvh - 4rem)" />
-// Inside your own bounded flex column (parent must have height + min-h-0)
-<div className="flex min-h-0 flex-1 overflow-hidden">
-  <ChatMain {...chatConfig} viewportHeight="full" />
-</div>
-```
-**Do not** pass empty or placeholder components for slots you want to keep default — simply omit those keys from `components`.
----
-## Table of contents
-1. [Chat features included](#chat-features-included)
-2. [What you install vs what is bundled](#what-you-install-vs-what-is-bundled)
-3. [Backend credentials](#backend-credentials)
-4. [Installation step by step](#installation-step-by-step)
-5. [Tailwind CSS v4 setup (required)](#tailwind-css-v4-setup-required)
-6. [Project config file](#project-config-file)
-7. [Quick start — minimum working chat](#quick-start--minimum-working-chat)
-8. [Complete ChatMain example](#complete-chatmain-example)
-9. [Customization — three ways](#customization--three-ways)
-10. [Default component fallback (important)](#default-component-fallback-important)
-11. [Which slots are wired](#which-slots-are-wired)
-12. [Production integration pattern (admin templates)](#production-integration-pattern-admin-templates)
-13. [Customization examples (Case 1–3)](#customization-examples-case-13)
-14. [Phone & video calling](#phone--video-calling)
-15. [Theme, light/dark, date/time](#theme-lightdark-datetime)
-16. [Layout sections (`layout` prop)](#layout-sections-layout-prop)
-17. [All component slots + examples](#all-component-slots--examples)
-18. [All classNames keys](#all-classnames-keys)
-19. [Wrapping package defaults (`packageDefaultComponents`)](#wrapping-package-defaults-packagedefaultcomponents)
-20. [API query params](#api-query-params)
-21. [ChatMain props reference](#chatmain-props-reference)
-22. [Chat provider (composable mode)](#chat-provider-composable-mode)
-23. [Hooks & store](#hooks--store)
-24. [React (Vite) — full setup](#react-vite--full-setup)
-25. [Next.js — full setup](#nextjs--full-setup)
-26. [Environment variables](#environment-variables)
-27. [Dev proxy (CORS)](#dev-proxy-cors)
-28. [Architecture](#architecture)
-29. [All exports](#all-exports)
-30. [Troubleshooting](#troubleshooting)
-31. [Setup checklist](#setup-checklist)
-32. [Package development (maintainers)](#package-development-maintainers)
-33. [License](#license)
+| **License** | [MIT](./LICENSE) |
----
-## Chat features included
-| Feature | Supported |
-|---------|-----------|
-| Direct messages (1-to-1) | Yes |
-| Group chats | Yes |
-| Real-time messages (Socket.IO) | Yes |
-| Optimistic send (instant UI) | Yes |
-| Reactions, replies, forward | Yes |
-| Edit / delete (me / everyone) | Yes |
-| Pin & star messages | Yes |
-| Attachments (images, files) | Yes |
-| In-chat message search | Yes |
-| Typing indicators | Yes |
-| Read receipts (sent / delivered / read) | Yes |
-| New chat / user list modal | Yes |
-| Group members, admins, permissions | Yes |
-| Light / dark mode | Yes |
-| Locale & timezone formatting | Yes |
-| Phone / video call hooks | Yes (you wire WebRTC) |
-| Full UI customization | Yes |
----
-## What you install vs what is bundled
-### You must install (peer dependencies)
-| Package | Version | When | Why |
-|---------|---------|------|-----|
-| `react` | ≥ 17 | Always | UI framework |
-| `react-dom` | ≥ 17 | Always | DOM rendering |
-| `zustand` | ≥ 4 | Always | Chat state store |
-| `tailwindcss` | **v4** | Always | Package uses Tailwind utilities |
-| `@tailwindcss/vite` | v4 | Vite only | Tailwind plugin |
-| `@tailwindcss/postcss` | v4 | Next.js only | Tailwind PostCSS plugin |
-| `next` | ≥ 13 | Next.js only | App Router |
-| `react-hot-toast` | ≥ 2 | Optional | Only if you use `showNotification` helper |
-### Bundled inside the package (do not install separately)
-`axios`, `socket.io-client`, `radix-ui`, `lucide-react`, `emoji-picker-react`, `clsx`, `tailwind-merge`, `class-variance-authority`, and all chat components.
----
-## Backend credentials
-| Field | Example | Notes |
-|-------|---------|-------|
-| `clientId` | `"6a35339216e46130366cda93"` | RealtimeX tenant / client id |
-| `accessToken` | JWT string | User access token |
-| `loggedUserDetails._id` | `"6a3533c416e46130366cda98"` | **Must match `_id` inside JWT** |
-| `loggedUserDetails.name` | `"chat1"` | Display name |
-| `loggedUserDetails.email` | `"chat1@example.com"` | Used for client-user login |
-| `apiUrl` | `https://realtimex.softwareco.com/api/v1` | REST API — **must end with** `/api/v1` (**required**, pass from your app) |
-| `socketUrl` | `https://realtimex.softwareco.com` | Socket host — **no** `/api/v1`; connects at `/connection`. Optional — derived from `apiUrl` if omitted |
-| `themeColor` | `"#6366f1"` | Brand accent (optional) |
-> **Important:** If `loggedUserDetails._id` does not match the JWT `_id`, messages may appear on the wrong side, contacts may be empty, or session sync can fail. Decode your JWT or use the id returned from the login API.
+Socket.IO, REST client, Zustand store, Radix UI, emoji picker, and chat UI are **bundled**. Your app only installs peer dependencies.
 ---
-## Installation step by step
-### 1. Install the package and peers
-**npm:**
+## Install
 ```bash
 npm install @realtimexsco/live-chat react react-dom zustand tailwindcss
 ```
-**pnpm:**
-```bash
-pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss
-```
-### 2. Install Tailwind v4 plugin for your framework
-**Vite:**
-```bash
-pnpm add -D @tailwindcss/vite @vitejs/plugin-react vite
-```
-**Next.js:**
-```bash
-pnpm add -D @tailwindcss/postcss
-# next is usually already installed
-```
-### 3. Verify install
-```bash
-npm ls @realtimexsco/live-chat
-ls node_modules/@realtimexsco/live-chat/dist/index.d.ts   # TypeScript types must exist
-```
-### 4. Configure CSS, config file, and chat page (see sections below)
-### 5. Run your app and open the chat route
-No `.npmrc` or private token is required — the package is on the public npm registry.
----
-## Tailwind CSS v4 setup (required)
-The package will look unstyled without these three steps:
-1. `@import` Tailwind + package `styles.css`
-2. `@source` the package `dist` files so Tailwind scans bundled classes
-3. Define `--chat-theme*` CSS variables in `:root`
-### Vite — `src/index.css`
-```css
-@import "tailwindcss";
-@import "@realtimexsco/live-chat/styles.css";
-@source "../node_modules/@realtimexsco/live-chat/dist/index.mjs";
-@source "../node_modules/@realtimexsco/live-chat/dist/index.cjs";
-@source "../**/*.{js,jsx,ts,tsx}";
-:root {
-  --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --border: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --input: oklch(0.922 0 0);
-  /* Overridden at runtime by ChatMain `themeColor` */
-  --chat-theme: #6366f1;
-  --chat-theme-5: #6366f10D;
-  --chat-theme-10: #6366f11A;
-  --chat-theme-20: #6366f133;
-  --chat-theme-40: #6366f166;
-  --chat-theme-60: #6366f199;
-}
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-border: var(--border);
-  --color-ring: var(--ring);
-  --color-destructive: var(--destructive);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-input: var(--input);
-  --color-chat-theme: var(--chat-theme);
-  --color-chat-theme-5: var(--chat-theme-5);
-  --color-chat-theme-10: var(--chat-theme-10);
-  --color-chat-theme-20: var(--chat-theme-20);
-  --color-chat-theme-40: var(--chat-theme-40);
-  --color-chat-theme-60: var(--chat-theme-60);
-}
-@layer base {
-  html, body, #root { height: 100%; }
-  body { @apply bg-background text-foreground; }
-}
-```
-### Next.js — `src/app/globals.css`
-> `globals.css` is inside `src/app/`, so `@source` uses **`../../node_modules`** (not `../`).
-```css
-@import "tailwindcss";
-@import "@realtimexsco/live-chat/styles.css";
-@source "../../node_modules/@realtimexsco/live-chat/dist/index.mjs";
-@source "../../node_modules/@realtimexsco/live-chat/dist/index.cjs";
-/* Copy :root, @theme inline, and @layer base from the Vite example above */
-```
-### `@source` path cheat sheet
-| CSS file location | `@source` prefix |
-|-------------------|------------------|
-| `src/index.css` (Vite) | `../node_modules/...` |
-| `src/app/globals.css` (Next.js) | `../../node_modules/...` |
-Wrong path = broken or unstyled chat UI.
-### Vite — `vite.config.ts`
-```ts
-import path from "path";
-import { fileURLToPath } from "url";
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import tailwindcss from "@tailwindcss/vite";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-  resolve: {
-    alias: { "@": path.resolve(__dirname, "src") },
-    dedupe: ["react", "react-dom", "zustand", "socket.io-client", "@realtimexsco/live-chat"],
-  },
-  optimizeDeps: {
-    exclude: ["@realtimexsco/live-chat"],
-    include: ["zustand", "socket.io-client"],
-  },
-});
-```
-### Next.js — `next.config.ts`
-```ts
-import type { NextConfig } from "next";
-const nextConfig: NextConfig = {
-  transpilePackages: ["@realtimexsco/live-chat"],
-};
-export default nextConfig;
-```
-### Next.js — `postcss.config.mjs`
-```js
-const config = { plugins: { "@tailwindcss/postcss": {} } };
-export default config;
-```
+**Vite:** `npm i -D @tailwindcss/vite` · **Next.js:** `npm i -D @tailwindcss/postcss`
 ---
-## Project config file
-Create `src/configs/chat.config.ts`:
-```ts
-/** Optional: read _id from JWT so it always matches the token */
-function userIdFromToken(token: string): string | undefined {
-  try {
-    const payload = JSON.parse(
-      atob(token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/"))
-    );
-    return payload._id || payload.id;
-  } catch {
-    return undefined;
-  }
-}
-const accessToken = "YOUR_JWT_ACCESS_TOKEN";
-export const chatConfig = {
-  clientId: "YOUR_CLIENT_ID",
-  accessToken,
-  loggedUserDetails: {
-    _id: userIdFromToken(accessToken) ?? "YOUR_USER_ID",
-    name: "Your Name",
-    email: "you@example.com",
-  },
-  apiUrl: "https://realtimex.softwareco.com/api/v1",
-  socketUrl: "https://realtimex.softwareco.com", // optional — auto-derived from apiUrl
-  themeColor: "#6366f1",
-} as const;
-```
----
+## Quick start
-## Quick start — minimum working chat
+1. Import CSS — `@import "@realtimexsco/live-chat/styles.css"` and add Tailwind `@source` for the package `dist` files.
+2. Create `chat.config.ts` with `clientId`, `accessToken`, `loggedUserDetails`, `apiUrl`, `socketUrl`.
+3. Render `<ChatMain {...chatConfig} />`.
 ```tsx
-"use client"; // Next.js only — required on any file that imports chat
 import ChatMain from "@realtimexsco/live-chat";
 import { chatConfig } from "@/configs/chat.config";
 export default function ChatPage() {
   return (
     <div className="h-dvh min-h-0 overflow-hidden">
-      <ChatMain
-        clientId={chatConfig.clientId}
-        accessToken={chatConfig.accessToken}
-        loggedUserDetails={chatConfig.loggedUserDetails}
-        apiUrl={chatConfig.apiUrl}
-        socketUrl={chatConfig.socketUrl}
-        themeColor={chatConfig.themeColor}
-      />
-    </div>
-  );
-}
-```
-**Container height is required.** `ChatMain` includes a built-in viewport (`chat-package-viewport`). Set `viewportHeight="screen"` for full page, or `viewportHeight="calc(100dvh - 4rem)"` below a fixed header. Alternatively wrap with `h-dvh min-h-0 overflow-hidden` and use default `viewportHeight="full"`.
----
-## Complete ChatMain example
-All common props: theme, locale, layout, customization, calls, alerts.
-```tsx
-"use client";
-import { useState } from "react";
-import ChatMain, {
-  type ChatColorMode,
-  type ChatComponents,
-  type ChatClassNames,
-  type ChatFeatures,
-  type AvatarSlotProps,
-  defaultChatLayoutConfig,
-} from "@realtimexsco/live-chat";
-import { chatConfig } from "@/configs/chat.config";
-const MyAvatar = ({ src, name, size }: AvatarSlotProps) => (
-  <img
-    src={src || undefined}
-    alt={name}
-    className={`rounded-full object-cover avatar--${size}`}
-    style={{ width: 36, height: 36 }}
-  />
-);
-const components: ChatComponents = {
-  Avatar: MyAvatar,
-  // ChatLayout: MyFullCustomUI,     // Case 1 — replace entire UI
-  // MessageItem: MyMessageBubble,   // Case 2 — single slot
-};
-const classNames: ChatClassNames = {
-  sidebar: "bg-slate-950",
-  channelHeader: "border-b-2 border-indigo-500",
-  messageBubbleSender: "rounded-3xl shadow-md",
-  messageBubbleReceiver: "rounded-3xl",
-};
-const features: ChatFeatures = {
-  showPhoneCall: true,
-  showVideoCall: true,
-  onPhoneCall: ({ activeChannel, conversationId }) => {
-    console.log("Voice call", activeChannel.name, conversationId);
-  },
-  onVideoCall: ({ activeChannel, conversationId }) => {
-    console.log("Video call", activeChannel.name, conversationId);
-  },
-};
-export default function ChatPage() {
-  const [colorMode, setColorMode] = useState<ChatColorMode>("light");
-  const [error, setError] = useState<string | null>(null);
-  return (
-    <div className="h-dvh min-h-0 overflow-hidden">
-      <ChatMain
-        clientId={chatConfig.clientId}
-        accessToken={chatConfig.accessToken}
-        loggedUserDetails={chatConfig.loggedUserDetails}
-        apiUrl={chatConfig.apiUrl}
-        socketUrl={chatConfig.socketUrl}
-        themeColor={chatConfig.themeColor}
-        colorMode={colorMode}
-        onColorModeChange={setColorMode}
-        showColorModeToggle={false}
-        locale="en-US"
-        timeZone="Asia/Kolkata"
-        hour12={false}
-        showDateTimeSettings
-        layout={{ ...defaultChatLayoutConfig }}
-        components={components}
-        classNames={classNames}
-        features={features}
-        error={error}
-        onErrorDismiss={() => setError(null)}
-      />
-    </div>
-  );
-}
-```
----
-## Customization — three ways
-You can combine all three.
-| Case | Prop | What it does |
-|------|------|--------------|
-| **1** | `components.ChatLayout` | Replace the **entire** chat UI shell |
-| **2** | `components.*` | Replace **one** component (avatar, header, message bubble, drawer, etc.) |
-| **3** | `classNames.*` | Override **Tailwind classes** per region — no new React components |
-Omit any slot or className key → **package default is used automatically**.
----
-## Default component fallback (important)
-Customization is **opt-in per slot**. You never need to register every component.
-### How it works internally
-```
-ChatMain components={{ MembersDrawer: MyDrawer }}
-        ↓
-ChatCustomizationProvider merges your config
-        ↓
-At render: resolveComponent("MembersDrawer", PackageMembersDrawer)
-        ↓
-Custom passed?  → use MyDrawer
-Not passed?     → use PackageMembersDrawer (built-in default)
-```
-Rules:
-| You pass | Result |
-|----------|--------|
-| No `components` prop at all | **Full default chat UI** |
-| `components={{ Avatar: MyAvatar }}` | Custom avatar only; **all other slots use defaults** |
-| `components={{ MembersDrawer: undefined }}` | Treated as not passed → **default drawer** |
-| `classNames={{ sidebar: "..." }}` | Your classes **merge on top of** package defaults |
-### Code pattern inside the package
-Every wired slot follows this pattern:
-```tsx
-const MembersDrawerSlot = resolveComponent("MembersDrawer", MembersDrawer);
-return <MembersDrawerSlot isOpen={...} onOpenChange={...} ... />;
-```
-Your custom component receives the **same props** as the package default (`MembersDrawerSlotProps`, etc.). Import the prop type from the package for TypeScript.
-### Wrapping instead of rebuilding
-Use `packageDefaultComponents` when you only need to restyle or add a wrapper:
-```tsx
-import { packageDefaultComponents, type MembersDrawerSlotProps } from "@realtimexsco/live-chat";
-const MyMembersDrawer = (props: MembersDrawerSlotProps) => (
-  <div className="my-drawer-shell">
-    <packageDefaultComponents.MembersDrawer! {...props} />
-  </div>
-);
-```
----
-## Which slots are wired
-All slots below are **honored at runtime** when you pass them on `ChatMain` `components` (or `Chat` `uiConfig.components`). Slots not listed as wired may still be typed for future use or require replacing a parent slot (e.g. `ChannelHeader`).
-| Slot | Wired in | Fallback when omitted |
-|------|----------|------------------------|
-| `ChatLayout` | `ChatLayout.tsx` | `DefaultChatLayout` |
-| `LoggedUserDetails` | `DefaultChatLayout` | Package default |
-| `ChannelList` | `DefaultChatLayout` | Package default |
-| `ChannelHeader` | `DefaultChatLayout` | Package default |
-| `MessageList` | `DefaultChatLayout` | Package default |
-| `MessageInput` | `DefaultChatLayout` | Package default |
-| `ForwardModal` | `DefaultChatLayout` | Package default |
-| `ChatPanelAlerts` | `DefaultChatLayout` | Package default |
-| `ChannelListItem` | `ChannelListItem` wrapper | `DefaultChannelListItem` |
-| `Avatar` | `ChatAvatar` | `DefaultChatAvatar` |
-| `HeaderCallActions` | `HeaderCallActions` | Built-in phone/video group |
-| `PhoneCallButton` | `HeaderCallActions` | Built-in button |
-| `VideoCallButton` | `HeaderCallActions` | Built-in button |
-| `HeaderLeftSide` | `ChannelHeaderView` | Package default |
-| `HeaderRightSide` | `ChannelHeaderView` | Package default |
-| `ChatActionModal` | `ChannelHeaderView` | Package default |
-| `ChannelDetailsDrawer` | `ChannelHeaderView` | Package default |
-| `MembersDrawer` | `ChannelHeaderView` | Package default |
-| `AdminsDrawer` | `ChannelHeaderView` | Package default |
-| `PermissionDrawer` | `ChannelHeaderView` | Package default |
-| `AttachmentsDrawer` | `ChannelHeaderView` | Package default |
-| `PinnedMessagesDrawer` | `ChannelHeaderView` | Package default |
-| `StarredMessagesDrawer` | `ChannelHeaderView` | Package default |
-> **Replace entire header:** Pass `components.ChannelHeader` with your own component (use `useChannelHeader` hook for state/handlers). That replaces the full header **and** all drawers inside it.
-### Advanced slots (replace parent component)
-These slots are **typed and exported** but used inside inner components. To customize them, either replace the parent slot or copy the parent and wire your component:
-| Slot | Customize by replacing |
-|------|------------------------|
-| `MessageItem` | `MessageList` (pass your list that renders custom items) |
-| `MessageToolbar`, `MessageStatus`, `MessageAttachments`, `MessageReactions`, `MessageReplySnippet` | `MessageItem` or `MessageList` |
-| `HeaderSearchOverlay` | `HeaderRightSide` or `ChannelHeader` |
-| `ChatThemeToggle`, `ChatDateTimeSettings`, `ChatSocketStatus` | Used inside header/sidebar — replace parent or `ChannelHeader` |
-For most apps, `components` + `classNames` on the [wired slots](#which-slots-are-wired) table is enough without touching advanced slots.
----
-## Production integration pattern (admin templates)
-Recommended structure for apps like **Elstar**, **Metronic**, or any admin shell:
-```
-src/
-├── configs/
-│   ├── chat.config.ts              # credentials only
-│   ├── chat.customization.config.ts # components + classNames
-│   └── chat.layout.config.ts       # layout section toggles
-├── components/chat/custom/
-│   ├── ElstarMembersDrawer.tsx     # custom drawer example
-│   ├── ElstarChatAvatar.tsx
-│   └── index.ts
-└── views/Chat.tsx                  # wires ChatMain
-```
-### `chat.config.ts` — credentials only
-```ts
-export const chatConfig = {
-  clientId: "YOUR_CLIENT_ID",
-  accessToken: "YOUR_JWT",
-  loggedUserDetails: { _id: "...", name: "...", email: "..." },
-  apiUrl: "https://api.example.com/api/v1",
-  socketUrl: "https://api.example.com",
-  themeColor: "#6366f1",
-} as const;
-```
-### `chat.customization.config.ts` — UI overrides
-```ts
-import type { ChatClassNames, ChatComponents } from "@realtimexsco/live-chat";
-import {
-  ElstarChatAvatar,
-  ElstarHeaderCallActions,
-  ElstarMembersDrawer,
-  ElstarPhoneCallButton,
-  ElstarVideoCallButton,
-} from "@/components/chat/custom";
-/** Only register slots you want to customize. All others use package defaults. */
-export const chatComponents: ChatComponents = {
-  Avatar: ElstarChatAvatar,
-  HeaderCallActions: ElstarHeaderCallActions,
-  PhoneCallButton: ElstarPhoneCallButton,
-  VideoCallButton: ElstarVideoCallButton,
-  MembersDrawer: ElstarMembersDrawer,
-};
-export const chatClassNames: ChatClassNames = {
-  shell: "chat-container-root",
-  channelListItemActive: "bg-indigo-50 ring-1 ring-indigo-200",
-  messageBubbleSender: "rounded-2xl shadow-sm",
-  drawer: "z-[60]",
-  drawerContent: "rounded-l-2xl",
-};
-```
-### `views/Chat.tsx` — single entry
-```tsx
-import ChatMain, { type ChatColorMode } from "@realtimexsco/live-chat";
-import { chatConfig } from "@/configs/chat.config";
-import { chatComponents, chatClassNames } from "@/configs/chat.customization.config";
-import { chatLayoutConfig } from "@/configs/chat.layout.config";
-export default function ChatPage() {
-  return (
-    <div className="h-dvh min-h-0 overflow-hidden">
-      <ChatMain
-        {...chatConfig}
-        layout={chatLayoutConfig}
-        components={chatComponents}
-        classNames={chatClassNames}
-        showColorModeToggle={false}
-        colorMode="light" // sync with your app theme
-      />
-    </div>
-  );
-}
-```
-### Full custom `MembersDrawer` example
-Use the package store inside your drawer — same data/actions as the default drawer:
-```tsx
-import { useState, useMemo } from "react";
-import {
-  useChatStore,
-  type MembersDrawerSlotProps,
-} from "@realtimexsco/live-chat";
-import Drawer from "@/components/ui/Drawer"; // your design system
-const MyMembersDrawer = ({
-  isOpen,
-  onOpenChange,
-  conversationId,
-  conversationInfo,
-}: MembersDrawerSlotProps) => {
-  const allUsers = useChatStore((s) => s.allUsers);
-  const manageGroupMembers = useChatStore((s) => s.manageGroupMembers);
-  const loggedUserDetails = useChatStore((s) => s.loggedUserDetails);
-  const participants = conversationInfo?.participants ?? [];
-  return (
-    <Drawer isOpen={isOpen} onClose={() => onOpenChange(false)} title="Members">
-      {/* Your UI — add/remove members via manageGroupMembers */}
-      <ul>
-        {participants.map((p) => (
-          <li key={typeof p === "string" ? p : p._id}>{typeof p === "string" ? p : p.name}</li>
-        ))}
-      </ul>
-    </Drawer>
-  );
-};
-export default MyMembersDrawer;
-```
-Register it: `components={{ MembersDrawer: MyMembersDrawer }}`. If you **remove** that line, the package default members drawer appears again.
----
-## Customization examples (Case 1–3)
-### Case 1 — Replace entire chat UI
-```tsx
-import ChatMain, {
-  useChatController,
-  DefaultChatLayout,
-  type ChatLayoutSlotProps,
-} from "@realtimexsco/live-chat";
-// Option A: wrap the default layout
-function MyChatShell(props: ChatLayoutSlotProps) {
-  return (
-    <div className="flex h-full flex-col">
-      <header className="shrink-0 border-b px-4 py-2 font-semibold">My App Chat</header>
-      <div className="min-h-0 flex-1">
-        <DefaultChatLayout {...props} shellClassName="rounded-none shadow-none" />
-      </div>
-    </div>
-  );
-}
-// Option B: build from scratch with useChatController()
-function MyFullChatUI(_props: ChatLayoutSlotProps) {
-  const {
-    activeChannel,
-    conversationId,
-    conversationMessages,
-    handleChannelSelect,
-    handleSendMessage,
-    setActiveChannel,
-    state,
-    updateState,
-  } = useChatController();
-  return (
-    <div className="flex h-full">
-      {/* Your sidebar, header, messages, input — full control */}
+      <ChatMain {...chatConfig} viewportHeight="screen" />
     </div>
   );
 }
-<ChatMain
-  {...chatConfig}
-  clientId={chatConfig.clientId}
-  components={{ ChatLayout: MyChatShell }}
-/>;
-```
-### Case 2 — Replace individual components
-```tsx
-<ChatMain
-  {...chatConfig}
-  clientId={chatConfig.clientId}
-  components={{
-    Avatar: MyAvatar,
-    ChannelListItem: MyConversationRow,
-    MessageItem: MyMessageBubble,
-    MessageInput: MyComposer,
-    PhoneCallButton: MyPhoneBtn,
-    MembersDrawer: MyMembersPanel,
-  }}
-/>
-```
-### Case 3 — Style with classNames only
-```tsx
-<ChatMain
-  {...chatConfig}
-  clientId={chatConfig.clientId}
-  classNames={{
-    channelListItemActive: "bg-indigo-50 ring-1 ring-indigo-200",
-    messageBubbleSender: "rounded-2xl shadow-sm",
-    messageBubbleReceiver: "rounded-2xl bg-white",
-    messageInput: "border-t border-gray-200",
-  }}
-/>
 ```
 ---
-## Phone & video calling
-Call buttons appear in **DM chats only** (hidden for groups).
-### Option A — Keep default buttons, add callbacks
-```tsx
-features={{
-  showPhoneCall: true,
-  showVideoCall: true,
-  onPhoneCall: ({ activeChannel, conversationId }) => {
-    yourVoiceSDK.start(activeChannel.id, conversationId);
-  },
-  onVideoCall: ({ activeChannel, conversationId }) => {
-    yourVideoSDK.start(activeChannel.id, conversationId);
-  },
-}}
-```
-### Option B — Replace the call button group
-```tsx
-components={{
-  HeaderCallActions: ({ onPhoneCall, onVideoCall, activeChannel }) => (
-    <div className="flex gap-2">
-      <button type="button" onClick={onPhoneCall}>Call {activeChannel.name}</button>
-      <button type="button" onClick={onVideoCall}>Video</button>
-    </div>
-  ),
-}}
-```
-> Do **not** import `HeaderCallActions` from the package inside your custom `HeaderCallActions` — that causes infinite recursion. Render your own buttons instead.
-### Option C — Replace individual buttons
-```tsx
-components={{
-  PhoneCallButton: ({ onPhoneCall, className }) => (
-    <button type="button" className={className} onClick={onPhoneCall}>📞</button>
-  ),
-  VideoCallButton: ({ onVideoCall, className }) => (
-    <button type="button" className={className} onClick={onVideoCall}>📹</button>
-  ),
-}}
-```
-### Hide calls
+## Features
-```tsx
-features={{ showPhoneCall: false, showVideoCall: false }}
-```
+DMs · groups · Socket.IO · reactions · replies · forward · edit/delete · pin/star · attachments · search · typing · read receipts · light/dark · locale/timezone · full UI customization
 ---
-## Theme, light/dark, date/time
-### Brand color
-```tsx
-<ChatMain {...chatConfig} clientId={chatConfig.clientId} themeColor="#7c3aed" />
-```
-Runtime updates `--chat-theme` CSS variables automatically.
-### Light / dark mode
-| Pattern | Props |
-|---------|-------|
-| Your app controls theme (e.g. admin template) | `colorMode={mode}` `onColorModeChange={setMode}` `showColorModeToggle={false}` |
-| Chat manages its own theme | `defaultColorMode="light"` (built-in toggle shown) |
-| Start dark | `defaultColorMode="dark"` |
-### Date / time
-```tsx
-<ChatMain
-  {...chatConfig}
-  clientId={chatConfig.clientId}
-  locale="en-GB"
-  timeZone="Europe/London"
-  hour12={false}
-  showDateTimeSettings={false}
-  onDateTimePreferencesChange={(prefs) => console.log(prefs)}
-/>
-```
----
-## Layout sections (`layout` prop)
-Toggle parts of the default UI without writing new components.
-```ts
-import { defaultChatLayoutConfig } from "@realtimexsco/live-chat";
-export const chatLayoutConfig = {
-  ...defaultChatLayoutConfig,
-  // sidebar: true,           // left panel wrapper
-  // loggedUserDetails: true, // profile + new chat button
-  // channelList: true,       // conversation list
-  // header: true,            // channel header bar
-  // messageList: true,       // message bubbles
-  // input: true,             // composer
-  // forwardModal: true,      // forward dialog
-};
-```
-Examples:
-```tsx
-layout={{ input: false }}         // read-only (no composer)
-layout={{ sidebar: false }}        // hide sidebar — messages only
-layout={{ forwardModal: false }}   // disable forward modal
-layout={{ loggedUserDetails: false, channelList: true }}  // list without profile block
-```
----
-## All component slots + examples
-Pass only the slots you want to override via `components` on `ChatMain` (or `uiConfig` on `Chat`).
-Import prop types from the package for TypeScript, e.g. `AvatarSlotProps`, `MessageItemSlotProps`.
-| Slot | Replaces | Prop type |
-|------|----------|-----------|
-| `ChatLayout` | Entire chat shell | `ChatLayoutSlotProps` |
-| `LoggedUserDetails` | Sidebar profile + new chat | `LoggedUserDetailsSlotProps` |
-| `ChannelList` | Conversation list | `ChannelListSlotProps` |
-| `ChannelListItem` | One conversation row | `ChannelListItemSlotProps` |
-| `ChannelHeader` | Full header bar | `ChannelHeaderSlotProps` |
-| `HeaderLeftSide` | Back, name, pin/star | `HeaderLeftSideSlotProps` |
-| `HeaderRightSide` | Search, menu, settings | `HeaderRightSideSlotProps` |
-| `HeaderCallActions` | Phone + video group | `HeaderCallActionsSlotProps` |
-| `PhoneCallButton` | Voice call button | `PhoneCallButtonSlotProps` |
-| `VideoCallButton` | Video call button | `VideoCallButtonSlotProps` |
-| `HeaderSearchOverlay` | Message search dropdown | `HeaderSearchOverlaySlotProps` |
-| `MessageList` | Scrollable messages area | `ActiveChannelMessagesSlotProps` |
-| `MessageItem` | Single message bubble | `MessageItemSlotProps` |
-| `MessageInput` | Composer | `ChannelMessageBoxSlotProps` |
-| `ForwardModal` | Forward dialog | `ForwardModalSlotProps` |
-| `ChatPanelAlerts` | Error/info banner | `ChatPanelAlertsSlotProps` |
-| `ChatActionModal` | Clear/delete/block confirm | `ChatActionModalSlotProps` |
-| `ChannelDetailsDrawer` | Channel details sheet | `ChannelDetailsDrawerSlotProps` |
-| `MembersDrawer` | Group members sheet | `MembersDrawerSlotProps` |
-| `AdminsDrawer` | Group admins sheet | `AdminsDrawerSlotProps` |
-| `PermissionDrawer` | Permissions sheet | `PermissionDrawerSlotProps` |
-| `AttachmentsDrawer` | Attachments sheet | `AttachmentsDrawerSlotProps` |
-| `PinnedMessagesDrawer` | Pinned messages sheet | `PinnedMessagesDrawerSlotProps` |
-| `StarredMessagesDrawer` | Starred messages sheet | `StarredMessagesDrawerSlotProps` |
-| `Avatar` | Avatar everywhere | `AvatarSlotProps` |
-| `MessageToolbar` | Reply/forward/edit menu | `MessageToolbarSlotProps` |
-| `MessageStatus` | Sent/delivered/read ticks | `MessageStatusSlotProps` |
-| `MessageAttachments` | Files/images in bubble | `MessageAttachmentsSlotProps` |
-| `MessageReactions` | Emoji chips | `MessageReactionsSlotProps` |
-| `MessageReplySnippet` | Quoted reply in bubble | `MessageReplySnippetSlotProps` |
-| `ChatThemeToggle` | Light/dark toggle | `{ className?: string }` |
-| `ChatDateTimeSettings` | Date/time settings button | `Record<string, never>` |
-| `ChatSocketStatus` | Connection indicator | `{ className?: string }` |
-### Code examples for common slots
-**MembersDrawer** (full custom drawer — Elstar-style)
-```tsx
-import { useChatStore, type MembersDrawerSlotProps } from "@realtimexsco/live-chat";
-const MyMembersDrawer = ({
-  isOpen,
-  onOpenChange,
-  conversationId,
-  conversationInfo,
-}: MembersDrawerSlotProps) => {
-  const manageGroupMembers = useChatStore((s) => s.manageGroupMembers);
-  const participants = conversationInfo?.participants ?? [];
-  if (!isOpen) return null;
-  return (
-    <aside className="members-drawer">
-      <header>
-        <h2>Members ({participants.length})</h2>
-        <button type="button" onClick={() => onOpenChange(false)}>Close</button>
-      </header>
-      <ul>
-        {participants.map((p, i) => {
-          const id = typeof p === "string" ? p : p._id;
-          const name = typeof p === "string" ? "User" : p.name;
-          return <li key={`${id}-${i}`}>{name}</li>;
-        })}
-      </ul>
-    </aside>
-  );
-};
-```
-**ChannelDetailsDrawer**
-```tsx
-import type { ChannelDetailsDrawerSlotProps } from "@realtimexsco/live-chat";
-const MyDetailsDrawer = ({ isOpen, onOpenChange, activeChannel, conversationInfo }: ChannelDetailsDrawerSlotProps) => (
-  <dialog open={isOpen} onClose={() => onOpenChange(false)}>
-    <h2>{activeChannel.name}</h2>
-    <p>{conversationInfo?.groupDescription ?? "Direct message"}</p>
-  </dialog>
-);
-```
-**Avatar**
-```tsx
-import type { AvatarSlotProps } from "@realtimexsco/live-chat";
-const MyAvatar = ({ src, name, size = "md", isOnline, showOnline }: AvatarSlotProps) => (
-  <div className="relative">
-    <img src={src || undefined} alt={name} className={`avatar avatar--${size}`} />
-    {showOnline && isOnline && <span className="online-dot" />}
-  </div>
-);
-```
-**MessageItem** (custom bubble)
-```tsx
-import type { MessageItemSlotProps } from "@realtimexsco/live-chat";
-const MyMessageItem = ({ isSender, message, createdAt }: MessageItemSlotProps) => (
-  <div className={isSender ? "text-right" : "text-left"}>
-    <div className={isSender ? "bubble-sent" : "bubble-received"}>{message}</div>
-    <time className="text-xs opacity-60">{createdAt}</time>
-  </div>
-);
-```
-**ChannelListItem**
-```tsx
-import type { ChannelListItemSlotProps } from "@realtimexsco/live-chat";
-const MyRow = ({ channel, isActive, onSelect }: ChannelListItemSlotProps) => (
-  <button
-    type="button"
-    className={isActive ? "row-active" : "row"}
-    onClick={() => onSelect(channel)}
-  >
-    {channel.name}
-    {channel.unreadCount ? ` (${channel.unreadCount})` : ""}
-  </button>
-);
-```
-**MessageInput**
-```tsx
-import type { ChannelMessageBoxSlotProps } from "@realtimexsco/live-chat";
-const MyInput = ({ onSendMessage, replyTo, onCancelReply }: ChannelMessageBoxSlotProps) => {
-  const [text, setText] = useState("");
-  return (
-    <div>
-      {replyTo && <button type="button" onClick={onCancelReply}>Cancel reply</button>}
-      <input value={text} onChange={(e) => setText(e.target.value)} />
-      <button type="button" onClick={() => { onSendMessage?.(text, [], replyTo); setText(""); }}>
-        Send
-      </button>
-    </div>
-  );
-};
-```
----
-## All classNames keys
-Merged with package defaults — your classes extend styling without replacing components.
-| Key | UI region |
-|-----|-----------|
-| `shell` | Outermost chat wrapper |
-| `mainPanel` | Inner rounded panel |
-| `sidebar` | Left sidebar |
-| `loggedUserDetails` | Profile block at top |
-| `channelList` | Conversation list container |
-| `channelListItem` | Each conversation row |
-| `channelListItemActive` | Selected conversation row |
-| `channelHeader` | Header bar |
-| `headerLeft` | Header left section |
-| `headerRight` | Header right section |
-| `headerCallActions` | Call buttons wrapper |
-| `phoneCallButton` | Phone button |
-| `videoCallButton` | Video button |
-| `messageList` | Messages scroll area |
-| `messageItem` | Message row wrapper |
-| `messageBubble` | Bubble (both sides) |
-| `messageBubbleSender` | Outgoing bubble |
-| `messageBubbleReceiver` | Incoming bubble |
-| `messageInput` | Composer container |
-| `messageInputTextarea` | Textarea element |
-| `avatar` | Avatar wrapper |
-| `avatarFallback` | Initials fallback |
-| `dateDivider` | "Today" / date separator |
-| `emptyState` | No messages placeholder |
-| `forwardModal` | Forward dialog |
-| `chatPanelAlerts` | Error/info alert bar |
-| `drawer` | Drawer overlay/shell |
-| `drawerContent` | Drawer panel body |
-| `searchOverlay` | In-header search results |
-```tsx
-classNames={{
-  shell: "chat-container-root",
-  channelListItemActive: "bg-indigo-50 dark:bg-indigo-500/10",
-  messageBubbleSender: "rounded-2xl shadow-sm",
-  messageBubbleReceiver: "rounded-2xl",
-  drawer: "z-[60]",
-}}
-```
----
-## Wrapping package defaults (`packageDefaultComponents`)
-The package exports every built-in slot component so you can wrap defaults with your theme instead of rebuilding from scratch.
-```tsx
-import {
-  packageDefaultComponents,
-  type ChatComponents,
-} from "@realtimexsco/live-chat";
-function withTheme<P extends object>(
-  Default: React.ComponentType<P>,
-  className: string
-): React.ComponentType<P> {
-  return (props) => (
-    <div className={className}>
-      <Default {...props} />
-    </div>
-  );
-}
-const components: ChatComponents = {
-  MessageItem: withTheme(packageDefaultComponents.MessageItem!, "my-message"),
-  ChannelListItem: withTheme(packageDefaultComponents.ChannelListItem!, "my-row"),
-  Avatar: MyFullyCustomAvatar, // or use DefaultChatAvatar from package
-};
-```
-Also exported for reference:
-- `packageDefaultComponents` — map of all slot defaults
-- `DefaultChatAvatar` — inner avatar (use when customizing `Avatar` slot)
-- `DefaultChannelListItem` — inner list row (use when customizing `ChannelListItem` slot)
----
-## API query params
-Pass extra query string params from your app into package HTTP requests. Params are merged in the axios interceptor (built-in params like `limit` / `page` / `conversationId` still win if they conflict).
-**Default behavior:** `queryParams` apply to **all GET APIs** only (`queryParamApis` defaults to `['get']`). Login, create group, and other POST/PATCH calls are **not** affected unless you opt in with `queryParamApis={['all']}`.
----
-### 1. Default — same params on every GET API
-**When to use:** Your app needs the same filter (e.g. `branchId`) on every list/fetch GET call inside the chat package.
-**Explanation:** You only pass `queryParams`. You do **not** need `queryParamApis` — it defaults to `['get']`, so every GET endpoint below receives these params. POST/PATCH stay clean.
-```tsx
-<ChatMain
-  {...chatConfig}
-  queryParams={{ branchId: "12" }}
-  // queryParamApis default = ['get']
-/>
-```
-**What happens on the network:**
-| Request | Query string |
-|---------|----------------|
-| `GET /user/list` | `?branchId=12` |
-| `GET /conversation/list` | `?limit=20&page=1&branchId=12` |
-| `GET /message/get-all-from-conversation` | `?conversationId=…&limit=…&branchId=12` |
-| `GET …/pinned-messages` | `?conversationId=…&branchId=12` |
-| `POST /user/login/client-user` | *(no extra query params)* |
-**GET APIs covered by default (`CHAT_GET_API_KEYS`):**
-| Key | Endpoint |
-|-----|----------|
-| `users` | `GET /user/list` |
-| `conversations` | `GET /conversation/list` |
-| `conversationInfo` | `GET /conversation/get/information/:id` |
-| `messages` | `GET /message/get-all-from-conversation` |
-| `pinnedMessages` | `GET message/pinned-messages` |
-| `starredMessages` | `GET message/starred-messages` |
-| `searchMessages` | `GET /message/search-messages` |
-| `searchMessagesContext` | `GET /message/searched-message/context` |
-```tsx
-import { CHAT_GET_API_KEYS, CHAT_API_KEYS } from "@realtimexsco/live-chat";
-```
----
-### 2. Different params per GET API
-**When to use:** Each endpoint needs its own query keys (e.g. conversations need `branchId`, messages need `locale`, users need `orgId`).
-**Explanation:** Use `queryParamsByApi` with named API keys. Only the APIs you list get params — and each can have a different object. You do not need `queryParams` or `queryParamApis` for this pattern.
-```tsx
-<ChatMain
-  {...chatConfig}
-  queryParamsByApi={{
-    conversations: { branchId: "12" },
-    messages: { locale: "en" },
-    users: { orgId: "x" },
-  }}
-/>
-```
-**What happens on the network:**
-| Request | Query string |
-|---------|----------------|
-| `GET /conversation/list` | `?…&branchId=12` |
-| `GET /message/get-all-from-conversation` | `?…&locale=en` |
-| `GET /user/list` | `?orgId=x` |
-| Other GET APIs (not listed) | *(no extra params from this prop)* |
----
-### 3. Only one GET API
-**When to use:** You want shared-style `queryParams`, but only on a single endpoint (e.g. conversation list), not on messages or users.
-**Explanation:** Pass `queryParams` for the values, and restrict with `queryParamApis={['conversations']}`. Other GET APIs will not receive `branchId`.
-```tsx
-<ChatMain
-  {...chatConfig}
-  queryParams={{ branchId: "12" }}
-  queryParamApis={["conversations"]}
-/>
-```
-**What happens on the network:**
-| Request | Query string |
-|---------|----------------|
-| `GET /conversation/list` | `?limit=20&page=1&branchId=12` |
-| `GET /message/get-all-from-conversation` | *(no `branchId`)* |
-| `GET /user/list` | *(no `branchId`)* |
-You can also target multiple selected GETs:
-```tsx
-<ChatMain
-  {...chatConfig}
-  queryParams={{ orgId: "x" }}
-  queryParamApis={["messages", "users"]}
-/>
-```
----
-### Bonus: shared + per-API together
-**Explanation:** Shared params apply to the APIs in `queryParamApis`. Per-API params from `queryParamsByApi` merge on top for that endpoint.
-```tsx
-<ChatMain
-  {...chatConfig}
-  queryParams={{ tenant: "abc" }}
-  queryParamApis={["conversations", "messages"]}
-  queryParamsByApi={{
-    conversations: { branchId: "12" },
-    messages: { locale: "en" },
-  }}
-/>
-```
-- conversations → `?tenant=abc&branchId=12`
-- messages → `?tenant=abc&locale=en`
----
-### `queryParamApis` options
-| Value | Meaning |
-|-------|---------|
-| `['get']` | **Default.** All GET endpoints in the table above |
-| `['all']` | Every `apiClient` request (GET + POST + PATCH) |
-| Specific keys | Only those endpoints (e.g. `['conversations']`) |
-### Imperative helpers
-```tsx
-import {
-  setChatQueryParams,
-  setChatQueryParamApis,
-  setChatQueryParamsByApi,
-} from "@realtimexsco/live-chat";
-setChatQueryParams({ branchId: "12" });
-setChatQueryParamApis(["conversations"]);
-setChatQueryParamsByApi({ messages: { locale: "en" } });
-```
-Socket connection query and S3 presigned uploads are **not** changed by these props.
----
-## ChatMain props reference
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `clientId` | `string` | — | **Required.** Tenant / client id |
-| `accessToken` | `string` | — | **Required.** JWT access token |
-| `loggedUserDetails` | `object` | — | **Required.** `{ _id, name, email }` — `_id` must match JWT |
-| `apiUrl` | `string` | — | **Required.** REST API ending with `/api/v1` (pass from your env/config) |
-| `socketUrl` | `string` | derived | Optional socket host (no `/api/v1`). Defaults to `apiUrl` without `/api/v1` |
-| `queryParams` | `Record<string, string \| number \| boolean>` | — | Shared query params for selected APIs (see `queryParamApis`) |
-| `queryParamApis` | `ChatApiKey[]` | `['get']` | Which APIs receive `queryParams`. Default = all GET endpoints |
-| `queryParamsByApi` | `ChatQueryParamsByApi` | — | Different query params per API key |
-| `viewportHeight` | `"full" \| "screen" \| string` | `"full"` | Chat root height. Use `"screen"` for full page, or `"calc(100dvh - 4rem)"` below fixed header |
-| `viewportClassName` | `string` | — | Extra classes on the built-in viewport wrapper |
-| `colorMode` | `"light" \| "dark"` | — | Controlled light/dark (use with your app theme) |
-| `defaultColorMode` | `"light" \| "dark"` | `"light"` | Initial mode when uncontrolled |
-| `onColorModeChange` | `(mode) => void` | — | Called when theme changes |
-| `showColorModeToggle` | `boolean` | `true` | Show built-in light/dark toggle |
-| `locale` | `string` | browser | BCP 47 locale, e.g. `"en-US"` |
-| `timeZone` | `string` | browser | IANA timezone, e.g. `"Asia/Kolkata"` |
-| `hour12` | `boolean` | locale | `true` = 12-hour clock |
-| `defaultLocale` | `string` | — | Initial locale when uncontrolled |
-| `defaultTimeZone` | `string` | — | Initial timezone when uncontrolled |
-| `defaultHour12` | `boolean` | — | Initial 12/24h when uncontrolled |
-| `onDateTimePreferencesChange` | `(prefs) => void` | — | User changed date/time settings |
-| `showDateTimeSettings` | `boolean` | `true` | Show in-panel date/time button |
-| `layout` | `ChatLayoutConfig` | all `true` | Toggle UI sections |
-| `components` | `ChatComponents` | — | Replace UI components (Case 1 & 2) |
-| `classNames` | `ChatClassNames` | — | Per-region CSS classes (Case 3) |
-| `features` | `ChatFeatures` | — | Phone/video call flags & callbacks |
-| `uiConfig` | `UIConfig` | — | Advanced: merged with `components` / `classNames` / `features` |
-| `error` | `string \| null` | — | Error message in alert bar |
-| `info` | `string \| null` | — | Info message in alert bar |
-| `onErrorDismiss` | `() => void` | — | Dismiss error |
-| `onInfoDismiss` | `() => void` | — | Dismiss info |
----
-## Chat provider (composable mode)
-Use `Chat` + `ChatLayout` when you need a custom page wrapper but not a full `ChatMain` replacement.
-```tsx
-"use client";
-import { Chat, ChatLayout, type ChatComponents } from "@realtimexsco/live-chat";
-import { chatConfig } from "@/configs/chat.config";
-const components: ChatComponents = {
-  Avatar: MyAvatar,
-};
-export default function ChatPage() {
-  return (
-    <div className="h-dvh min-h-0 overflow-hidden">
-      <Chat
-        client={{ id: chatConfig.clientId }}
-        accessToken={chatConfig.accessToken}
-        loggedUserDetails={chatConfig.loggedUserDetails}
-        apiUrl={chatConfig.apiUrl}
-        socketUrl={chatConfig.socketUrl}
-        themeColor={chatConfig.themeColor}
-        uiConfig={{
-          components,
-          classNames: { sidebar: "bg-slate-900" },
-          features: {
-            onPhoneCall: (ctx) => console.log("call", ctx),
-          },
-        }}
-      >
-        <ChatLayout themeColor={chatConfig.themeColor} />
-      </Chat>
-    </div>
-  );
-}
-```
-### `Chat` provider props
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `client` | `{ id: string }` | Yes | Client id |
-| `accessToken` | `string` | Yes | JWT |
-| `loggedUserDetails` | `object` | Yes | User profile |
-| `apiUrl` | `string` | No | REST base URL |
-| `socketUrl` | `string` | No | Socket host |
-| `queryParams` | `ChatQueryParams` | No | Shared query params (default target: all GET APIs) |
-| `queryParamApis` | `ChatApiKey[]` | No | Which APIs receive `queryParams` (default `['get']`) |
-| `queryParamsByApi` | `ChatQueryParamsByApi` | No | Per-API query params |
-| `themeColor` | `string` | No | Accent color |
-| `uiConfig` | `UIConfig` | No | `components`, `classNames`, `features` |
-| `onMessageReceived` | `(msg) => void` | No | Background message callback |
-| `onSocketConnected` | `(id) => void` | No | Socket connected |
-| `onSocketError` | `(err) => void` | No | Socket error |
-| `children` | `ReactNode` | Yes | Usually `<ChatLayout />` |
----
-## Hooks & store
-| Hook / export | Purpose |
-|---------------|---------|
-| `useChatController()` | State + handlers inside custom `ChatLayout` (Case 1) |
-| `useChatStore()` | Zustand store — messages, conversations, socket actions |
-| `useChatCustomization()` | Current `components` / `classNames` inside custom children |
-| `useChatFeatures()` | Phone/video flags and callbacks |
-| `useChatTheme()` | `themeColor`, `isDark`, CSS variables |
-| `useChatLocale()` | Format dates/times with current locale |
-| `useChatAlerts()` | Error/info alert state |
-| `useChatContext()` | Low-level chat provider context |
-```tsx
-import { useChatStore } from "@realtimexsco/live-chat";
-const conversations = useChatStore((s) => s.conversations);
-const emitDmSend = useChatStore((s) => s.emitDmSend);
-```
----
-## React (Vite) — full setup
-### 1. Create project
-```bash
-pnpm create vite my-chat-app --template react-ts
-cd my-chat-app
-```
-### 2. Install
-```bash
-pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss
-pnpm add -D @tailwindcss/vite @vitejs/plugin-react
-```
-### 3. File structure
-```
-src/
-├── main.tsx
-├── App.tsx
-├── index.css          ← Tailwind + package CSS (see above)
-└── configs/
-    └── chat.config.ts
-```
-### 4. `src/main.tsx`
-```tsx
-import { createRoot } from "react-dom/client";
-import "./index.css";
-import App from "./App";
-createRoot(document.getElementById("root")!).render(<App />);
-```
-### 5. `src/App.tsx`
-```tsx
-import ChatMain from "@realtimexsco/live-chat";
-import { chatConfig } from "./configs/chat.config";
-export default function App() {
-  return (
-    <div className="h-dvh min-h-0 overflow-hidden">
-      <ChatMain
-        clientId={chatConfig.clientId}
-        accessToken={chatConfig.accessToken}
-        loggedUserDetails={chatConfig.loggedUserDetails}
-        apiUrl={chatConfig.apiUrl}
-        socketUrl={chatConfig.socketUrl}
-        themeColor={chatConfig.themeColor}
-      />
-    </div>
-  );
-}
-```
-### 6. Run
-```bash
-pnpm dev
-```
----
-## Next.js — full setup
-### 1. Create project
-```bash
-pnpm create next-app@latest my-chat-app --typescript --tailwind --app --src-dir
-cd my-chat-app
-```
-### 2. Install
-```bash
-pnpm add @realtimexsco/live-chat zustand
-pnpm add -D @tailwindcss/postcss
-```
-### 3. `src/app/chat/page.tsx`
-```tsx
-"use client";
-import ChatMain from "@realtimexsco/live-chat";
-import { chatConfig } from "@/configs/chat.config";
-export default function ChatPage() {
-  return (
-    <div className="h-dvh min-h-0 overflow-hidden">
-      <ChatMain
-        clientId={chatConfig.clientId}
-        accessToken={chatConfig.accessToken}
-        loggedUserDetails={chatConfig.loggedUserDetails}
-        apiUrl={chatConfig.apiUrl}
-        socketUrl={chatConfig.socketUrl}
-        themeColor={chatConfig.themeColor}
-      />
-    </div>
-  );
-}
-```
-### 4. Run
-```bash
-pnpm dev
-```
-Open `http://localhost:3000/chat`
----
-## Environment variables
-Optional — use in `chat.config.ts`:
-```env
-# .env.local (Next.js) or .env (Vite with VITE_ prefix)
-NEXT_PUBLIC_CHAT_CLIENT_ID=your-client-id
-NEXT_PUBLIC_API_V1_BASE_URL=https://realtimex.softwareco.com/api/v1
-NEXT_PUBLIC_SOCKET_URL=https://realtimex.softwareco.com
-```
-```ts
-export const chatConfig = {
-  clientId: process.env.NEXT_PUBLIC_CHAT_CLIENT_ID ?? "",
-  accessToken: "YOUR_JWT_ACCESS_TOKEN",
-  apiUrl: process.env.NEXT_PUBLIC_API_V1_BASE_URL ?? "",
-  socketUrl:
-    process.env.NEXT_PUBLIC_SOCKET_URL ??
-    (process.env.NEXT_PUBLIC_API_V1_BASE_URL ?? "").replace(/\/api\/v1\/?$/, ""),
-  // ...
-};
-```
-Vite uses `import.meta.env.VITE_*` instead of `NEXT_PUBLIC_*`.
----
-## Dev proxy (CORS)
-If the API blocks browser requests during local dev, proxy through your dev server.
-**Vite `vite.config.ts`:**
-```ts
-server: {
-  proxy: {
-    "/chat-api": {
-      target: "https://YOUR_API_HOST",
-      changeOrigin: true,
-      rewrite: (path) => path.replace(/^\/chat-api/, "/api/v1"),
-    },
-  },
-},
-```
-Then set `apiUrl: "/chat-api"` in `chat.config.ts` for local development.
----
-## Architecture
-```
-ChatMain
-  ├── ChatThemeProvider        (themeColor, light/dark)
-  ├── ChatLocaleProvider       (locale, timezone, hour12)
-  ├── Chat
-  │     ├── Auth + REST API + Socket.IO + Zustand store
-  │     └── ChatCustomizationProvider   (components, classNames, features)
-  │           └── ChatLayout  (resolveComponent → DefaultChatLayout or custom)
-  │                 ├── Sidebar: LoggedUserDetails + ChannelList
-  │                 └── Main: ChannelHeader + MessageList + MessageInput
-  │                       └── ChannelHeaderView
-  │                             ├── resolveComponent → drawers (Members, Details, …)
-  │                             └── resolveComponent → modals (Clear, Delete, Block)
-  └── ChatAlertsProvider       (error / info banner)
-```
-**Customization flow:**
-1. You pass `components` / `classNames` / `features` on `ChatMain`.
-2. `ChatCustomizationProvider` merges your config (unset slots stay empty).
-3. Each render site calls `resolveComponent(slot, PackageDefault)` — custom wins, else default.
-4. No `components` prop → every slot uses package defaults (full default chat UI).
-**Runtime flow:**
-1. `ChatMain` runs client-user login, sets JWT, connects socket.
-2. User picks a conversation → messages fetch + socket room join.
-3. Send is optimistic — message appears immediately, reconciles on server ack.
-4. Socket events update Zustand → UI re-renders automatically.
----
-## All exports
-```ts
-import ChatMain, {
-  // ── Providers & layout ──
-  Chat,
-  ChatLayout,
-  DefaultChatLayout,
-  Channel,
-  ChatThemeProvider,
-  ChatLocaleProvider,
-  ChatAlertsProvider,
-  ChatCustomizationProvider,
-  // ── UI components (standalone or customization reference) ──
-  ChannelList,
-  ChannelHeader,
-  MessageList,
-  MessageInput,
-  LoggedUserDetails,
-  ForwardModal,
-  MessageItem,
-  ChatAvatar,
-  DefaultChatAvatar,
-  ChannelListItem,
-  DefaultChannelListItem,
-  HeaderCallActions,
-  packageDefaultComponents,
-  // ── Hooks ──
-  useChatStore,
-  useChatController,
-  useChatContext,
-  useChatCustomization,
-  useChatCustomizationOptional,
-  useChatFeatures,
-  useChatFeaturesOptional,
-  useChatTheme,
-  useChatLocale,
-  useChatAlerts,
-  // ── Layout helpers ──
-  mergeChatLayoutConfig,
-  defaultChatLayoutConfig,
-  mergeChatCustomization,
-  defaultChatClassNames,
-  defaultChatComponents,
-  defaultChatFeatures,
-  // ── API / socket helpers ──
-  setChatClientId,
-  setChatAccessToken,
-  setChatBaseURL,
-  setChatSocketUrl,
-  setChatQueryParams,
-  getChatQueryParams,
-  setChatQueryParamApis,
-  getChatQueryParamApis,
-  setChatQueryParamsByApi,
-  getChatQueryParamsByApi,
-  CHAT_API_KEYS,
-  CHAT_GET_API_KEYS,
-  resolveChatApiKey,
-  socketService,
-  getSocketConfig,
-  showNotification,
-  downloadFile,
-  // ── Types ──
-  type ChatApiKey,
-  type ChatGetApiKey,
-  type ChatQueryParams,
-  type ChatQueryParamsByApi,
-  type ChatComponents,
-  type ChatClassNames,
-  type ChatFeatures,
-  type ChatCallContext,
-  type ChatLayoutConfig,
-  type ChatColorMode,
-  type ChatCustomizationConfig,
-  type UIConfig,
-  type IChannel,
-  type IMessage,
-  type IAttachment,
-  type AvatarSlotProps,
-  type MessageItemSlotProps,
-  type ChannelHeaderSlotProps,
-  type ChannelListItemSlotProps,
-  type ChatLayoutSlotProps,
-  type HeaderCallActionsSlotProps,
-  type PhoneCallButtonSlotProps,
-  type VideoCallButtonSlotProps,
-  type ActiveChannelMessagesSlotProps,
-  type ChannelMessageBoxSlotProps,
-  type ForwardModalSlotProps,
-  type MembersDrawerSlotProps,
-  // … all *SlotProps types are exported
-} from "@realtimexsco/live-chat";
-```
-**CSS import (not from JS):**
-```css
-@import "@realtimexsco/live-chat/styles.css";
-```
----
-## Troubleshooting
-| Problem | Cause | Fix |
-|---------|-------|-----|
-| Unstyled / broken UI | Missing Tailwind `@source` | Add `@source` to package `dist/index.mjs` and `dist/index.cjs` |
-| No styles at all | Missing `styles.css` import | `@import "@realtimexsco/live-chat/styles.css"` |
-| Wrong `@source` depth | Next.js vs Vite path | Use `../../node_modules` in `src/app/globals.css` |
-| TypeScript: no declaration file | Published tarball missing `dist/index.d.ts` | Reinstall latest version; verify `dist/index.d.ts` exists |
-| Next.js build error | Package not transpiled | `transpilePackages: ["@realtimexsco/live-chat"]` |
-| `use client` error | Server Component import | Add `"use client"` to chat page |
-| Whole page scrolls, not messages | Missing height chain | Set `viewportHeight="screen"` or `viewportHeight="calc(100dvh - 4rem)"` on `<ChatMain />` |
-| Messages don't load | Wrong credentials / CORS | Check `apiUrl`, JWT, proxy in dev |
-| Socket won't connect | Wrong `socketUrl` | No `/api/v1` on socket URL |
-| Duplicate React hooks error | Duplicate React copies | `dedupe: ["react", "react-dom"]` in Vite |
-| Sent message on **left** and **right** | `_id` mismatch or duplicate echo | Ensure `loggedUserDetails._id` matches JWT `_id` |
-| Custom layout has no data | Missing hook | Call `useChatController()` inside custom `ChatLayout` |
-| Custom `MembersDrawer` still shows package UI | Old package version (< 1.1.55) | Upgrade to **1.1.55+** — drawer slots now use `resolveComponent` |
-| Custom drawer works but other slots are default | Expected behavior | Only pass slots you want to override in `components` |
-| Passed `components` but slot unchanged | Slot not wired or parent replaced | See [Which slots are wired](#which-slots-are-wired); use `ChannelHeader` to replace all header drawers |
-| Custom `HeaderCallActions` crashes | Recursive import | Don't import package `HeaderCallActions` inside your slot |
-| Vite stale UI after upgrade | Cached prebundle | `rm -rf node_modules/.vite && pnpm dev` |
-| Rate limit banner | API returned 429 | Wait for cooldown; reduce rapid API calls in dev |
----
-## Setup checklist
-Copy this list when integrating into a new project:
-- [ ] Node.js 18+
-- [ ] `pnpm add @realtimexsco/live-chat react react-dom zustand tailwindcss`
-- [ ] Tailwind v4 plugin installed (`@tailwindcss/vite` or `@tailwindcss/postcss`)
-- [ ] `index.css` / `globals.css` imports `tailwindcss` + `@realtimexsco/live-chat/styles.css`
-- [ ] `@source` points to `dist/index.mjs` and `dist/index.cjs` (correct depth for your CSS path)
-- [ ] `:root` has `--chat-theme` and `--chat-theme-5` … `--chat-theme-60`
-- [ ] `@theme inline` maps `--color-chat-theme*` variables
-- [ ] `chat.config.ts` with real `clientId`, `accessToken`, `apiUrl`, `socketUrl`
-- [ ] `loggedUserDetails._id` matches JWT `_id`
-- [ ] Chat page wrapped in `h-dvh min-h-0 overflow-hidden`
-- [ ] Next.js: `"use client"` on chat page + `transpilePackages`
-- [ ] Vite: `optimizeDeps.exclude` includes `@realtimexsco/live-chat`
-- [ ] Optional: `components` for custom UI (Case 1 / 2)
-- [ ] Optional: `classNames` for theme tweaks (Case 3)
-- [ ] Optional: `features` for phone/video callbacks
-- [ ] Optional: `layout` to hide sections
-- [ ] Optional: `colorMode` synced with your app theme
-- [ ] Verify: `node_modules/@realtimexsco/live-chat/dist/index.d.ts` exists
-- [ ] Use package **≥ 1.1.56** for drawer customization + default fallback fixes
----
-## Package development (maintainers)
-This package is built from the **live-chat-frontend** reference app. Source lives in `src/`; published output is `dist/`.
-### Sync from frontend
-```bash
-cd chat-ui-package
-pnpm sync    # copies app/chat → src/chat, patches API client & types, fixes imports
-pnpm build   # tsup → dist/
-```
-`scripts/sync-from-frontend.mjs` copies UI from the frontend repo. Protected files (not overwritten):
-- `src/index.ts`, `ChatMain.tsx`, `ChatContext.tsx`, `DefaultChatLayout.tsx`
-- `src/chat/channel-header/ChannelHeaderView.tsx` (customization wiring)
-- Store/context entrypoints
-After UI changes in **live-chat-frontend**, run `pnpm sync` then `pnpm build`, bump version, publish.
-### Local install in consumer app (e.g. Elstar)
-```bash
-cd chat-ui-package && pnpm pack --pack-destination .
-```
-In consumer `package.json`:
-```json
-"@realtimexsco/live-chat": "file:../path/to/realtimexsco-live-chat-1.1.0.tgz"
-```
-Then `pnpm install` in the consumer app.
-### Version history (customization)
+## More information
-| Version | Change |
-|---------|--------|
-| **1.1.56** | Hardened default fallback (`resolveComponent` null check); drawer slots use optional customization hook |
-| **1.1.55** | Drawer slots (`MembersDrawer`, `ChannelDetailsDrawer`, etc.) wired through `resolveComponent` |
-| **1.1.53** | UI polish synced from frontend (bubble curves, drawer headers, destructive menu icons) |
+| Topic | Link |
+|-------|------|
+| Full setup guide (Tailwind, Vite, Next.js, config) | [docs/full-guide.md](./docs/full-guide.md) |
+| Customization (`components`, `classNames`, `features`) | [Customization](./docs/full-guide.md#customization--three-ways) |
+| ChatMain props & API | [Props reference](./docs/full-guide.md#chatmain-props-reference) |
+| Hooks & store | [Hooks & store](./docs/full-guide.md#hooks--store) |
+| Dev proxy (CORS) | [Dev proxy](./docs/full-guide.md#dev-proxy-cors) |
+| npm package | [npmjs.com/package/@realtimexsco/live-chat](https://www.npmjs.com/package/@realtimexsco/live-chat) |
+| License | [MIT License](./LICENSE) |
 ---
 ## License
-[MIT](LICENSE)
+[MIT](./LICENSE) © RealtimeX