superezzdev · superezzdev · Aug 28, 2026 · Aug 28, 2026
diff --git a/README.md b/README.md
@@ -19,25 +19,38 @@
 
 ## ⚡ Highlights & Features
 
-- **📹 1-on-1 Random Video Chat:** Instantly connect face-to-face with strangers using ultra-low latency WebRTC peer-to-peer streaming.
-- **👥 Group Video Chat (Up to 5 Users):** Meet multiple strangers in real-time group chat rooms.
+### 🎥 Video Calling & Multi-Party Layouts
+- **📹 1-on-1 Full-Bleed Video Chat:** WhatsApp-style immersive full-bleed video interface with floating Picture-in-Picture (PiP), multi-corner movement, and tap-to-swap views.
+- **👥 Adaptive Group Video Grid (Up to 5 Users):** Responsive, dynamic multi-party grid layout optimized for mobile portrait, mobile landscape, tablet, and desktop viewports.
+- **📌 Spotlight / Pin Mode:** Tap any participant in a group call to spotlight them in a large primary stage while keeping other participants in a smooth thumbnail filmstrip.
+- **🔍 Full-Frame "Fit View" vs. "Fill View" Toggle:** Instant toggle between edge-to-edge fill (`object-cover`) and 100% full uncropped camera frame (`object-contain` with ambient backdrop blur).
+- **🎙️ Active Speaker Detection:** Real-time Web Audio API frequency analysis that highlights the active speaker with an animated glowing green ring.
+- **👑 Room Host Controls:** Automatic host assignment and failover, allowing the room host to mute participants or kick disruptive users.
+- **🔄 Rear & Front Camera Switcher:** Seamlessly toggle between selfie and rear cameras on mobile devices with live camera enumeration.
+- **🖥️ Screen Sharing:** One-click screen sharing with dynamic WebRTC track replacement.
+
+### 💬 Chat, Matching & Privacy
 - **💬 Text-Only Chat Mode:** Anonymously connect and chat with random users without using your camera or microphone.
 - **🎯 Interest & Topic Matching:** Enter your favorite interests (e.g. `coding`, `music`, `gaming`, `anime`) to match with like-minded people.
 - **🔒 Privacy First & Zero Registration:** No accounts, emails, passwords, or phone numbers needed. No chat logs or media recorded.
 - **🛡️ Community Safety & Moderation:** Instant skip, user report mechanisms, and automated bot prevention via [Arcjet](https://arcjet.com/) and [Zod](https://zod.dev/).
 - **⚡ Real-Time Presence:** Live online user counter, typing indicators, and instant matchmaking over native WebSockets.
-- **✨ Modern Responsive UI:** Built with React 19, Tailwind CSS, Lucide Icons, and Framer Motion.
+- **✨ Modern Responsive UI:** Built with React 19, Tailwind CSS, Lucide Icons, and Motion.
 
 ---
 
 ## 🥊 Why Randall? (Omegle Alternative Comparison)
 
 | Feature | 🚫 Omegle (Defunct) | 👥 Traditional Chat Apps | 🎥 Randall (Open Source) |
 | :--- | :--- | :--- | :--- |
-| **Open Source** | ❌ Proprietary | ❌ Proprietary | ✅ **100% MIT Open Source** |
-| **Group Video Calls** | ❌ No | ⚠️ Requires Accounts | ✅ **Yes (Up to 5 people)** |
+| **Open Source** | ❌ Proprietary | ❌ Proprietary | ✅ **100% AGPL-3.0 Open Source** |
+| **Group Video Calls** | ❌ No | ⚠️ Requires Accounts | ✅ **Yes (Adaptive 1-5 Grid)** |
+| **Spotlight / Pin Mode** | ❌ No | ⚠️ Heavy Client Apps | ✅ **Yes (Instant Stage Focus)** |
+| **Fit vs. Fill No-Crop** | ❌ Fixed Crop | ❌ Fixed Crop | ✅ **Per-Tile & Global Toggle** |
+| **Active Speaker Glow** | ❌ No | ⚠️ Heavy Apps | ✅ **Web Audio API Frequency Analysis** |
+| **Host Moderation** | ❌ None | ⚠️ Admin-only / Accounts | ✅ **Mute / Kick / Auto-Failover** |
 | **No Account Needed** | ✅ Yes | ❌ Requires Sign-up | ✅ **Instant 1-Click Access** |
-| **Peer-to-Peer Encrypted**| ⚠️ Partial | ❌ Relayed Servers | ✅ **WebRTC P2P Direct** |
+| **Peer-to-Peer Encrypted**| ⚠️ Partial | ❌ Relayed Servers | ✅ **WebRTC P2P Direct + STUN/TURN** |
 | **Bot Protection** | ❌ Poor | ⚠️ Captchas | ✅ **Arcjet Shield & Zod** |
 | **Modern Responsive UI** | ❌ 2000s Web Layout | ⚠️ Heavy Apps | ✅ **Vibrant, Clean & Fast** |
 
@@ -48,10 +61,10 @@
 | Layer | Technology | Purpose |
 | :--- | :--- | :--- |
 | **Frontend** | React 19 + Vite | Fast, responsive Single Page Application (SPA). |
-| **P2P Video / Audio** | WebRTC (`RTCPeerConnection`) | Direct browser-to-browser media streaming with no server recording. |
-| **Real-time Signaling**| WebSockets (`ws`) | Instant user matching, signaling negotiation, and text messages. |
-| **Backend Server** | Node.js + Express | Lightweight API server and WebSocket broker. |
-| **Styling & UI** | Tailwind CSS + Framer Motion | Modern design with micro-animations. |
+| **P2P Video / Audio** | WebRTC (`RTCPeerConnection`) | Direct browser-to-browser media streaming with zero server recording. |
+| **Real-time Signaling**| WebSockets (`ws`) | Instant user matching, multi-peer signaling negotiation, and text messages. |
+| **Backend Server** | Node.js + Express | Lightweight API server, WebSocket broker, and TURN credential provider. |
+| **Styling & UI** | Tailwind CSS + Motion + Lucide | Responsive design with micro-animations and adaptive grid geometry. |
 | **Security & Validation**| Arcjet + Zod | Bot detection, rate limiting, and schema validation. |
 
 ---
@@ -66,9 +79,9 @@
 ```
 
 1. **Signaling Connection:** When you visit [randall.superezz.dev](https://randall.superezz.dev), your browser connects to the central WebSocket signaling server.
-2. **Matchmaking:** The server pairs you with a waiting user based on your selected mode (1-on-1, Group, or Text) and overlapping interests.
+2. **Matchmaking:** The server pairs you with waiting users based on your selected mode (1-on-1, Group, or Text) and overlapping interests.
 3. **Offer & Answer (SDP):** The browsers exchange WebRTC session descriptions (SDP offer/answer) and ICE candidates via the WebSocket signaling channel.
-4. **Peer-to-Peer Streaming:** Once handshaking completes, video and audio flow directly between the two browsers. Randall's servers never capture, touch, or store your video frames.
+4. **Peer-to-Peer Streaming:** Once handshaking completes, video and audio flow directly between the browsers. Randall's servers never capture, touch, or store your video frames.
 
 ---
 
@@ -87,42 +100,48 @@
    cd randall
    ```
 
-2. **Install backend dependencies:**
+2. **Install root & UI dependencies:**
    ```bash
    npm install
+   npm --prefix ui install
    ```
 
-3. **Install frontend dependencies:**
-   ```bash
-   cd ui
-   npm install
-   cd ..
-   ```
-
-4. **Set up Environment Variables:**
+3. **Set up Environment Variables:**
    ```bash
    cp .env.example .env
    ```
    Open `.env` and configure your port and security keys:
    ```env
-   PORT=3000
+   PORT=8000
    ARCJET_KEY=your_arcjet_key_here
    ```
 
-5. **Run the Development Servers:**
+4. **Run the Development Servers:**
 
-   **Terminal 1 (Backend):**
+   **Option A: Run both backend and frontend together:**
    ```bash
    npm run dev
    ```
 
-   **Terminal 2 (Frontend UI):**
-   ```bash
-   cd ui
-   npm run dev
-   ```
+   **Option B: Run in separate terminals:**
+   - **Terminal 1 (Backend):**
+     ```bash
+     node src/index.js
+     ```
+   - **Terminal 2 (Frontend UI):**
+     ```bash
+     cd ui
+     npm run dev
+     ```
+
+5. Open `http://localhost:5173` in two browser windows or on separate devices to test video matching!
+
+### Testing Integration & Signaling
 
-6. Open `http://localhost:5173` in two browser windows or on separate devices to test video matching!
+Run the comprehensive matchmaking, group calling, and host control integration test suite:
+```bash
+node test-matchmaking.js
+```
 
 ---
 
@@ -133,20 +152,21 @@ randall/
 ├── src/                    # Backend server & WebSockets
 │   ├── index.js            # Express server entry point
 │   ├── arcjet.js           # Security & bot protection configuration
-│   ├── routes/             # REST endpoints (/api/users, /matches)
-│   └── ws/                 # WebSocket signaling & matchmaking rooms
+│   ├── routes/             # REST endpoints (/api/turn-credentials, /api/users)
+│   └── ws/                 # WebSocket signaling, group rooms & matchmaking
 ├── ui/                     # Frontend React 19 application
 │   ├── public/             # Static assets, robots.txt, sitemap.xml, llms.txt
 │   ├── src/
-│   │   ├── components/     # UI components (Home, VideoChat, Controls)
-│   │   ├── hooks/          # Custom WebRTC and WebSocket hooks (useVideoChat)
+│   │   ├── components/     # UI components (Home, VideoChat, Controls, Header)
+│   │   ├── hooks/          # Custom WebRTC & WebSocket hooks (useVideoChat)
 │   │   ├── pages/          # Static pages (About, Safety, Terms, Privacy, Contact)
 │   │   ├── App.jsx         # App shell & routing
 │   │   └── index.css       # Tailwind & theme styles
 │   ├── index.html          # SEO-optimized HTML template & JSON-LD
 │   └── vite.config.js      # Vite build configuration
-├── drizzle/                # Database migrations & schemas
+├── test-matchmaking.js     # Automated WebSockets & WebRTC integration test suite
 ├── CONTRIBUTING.md         # Contribution guidelines
+├── LICENSE                 # GNU Affero General Public License v3.0
 └── README.md
 ```
 
@@ -164,7 +184,7 @@ Yes! Randall is 100% free with no subscriptions, premium tiers, or hidden fees.
 No. Randall uses peer-to-peer WebRTC connections. All media streams flow directly between users and are never recorded or stored on any server.
 
 ### Can I host my own instance of Randall?
-Yes! Randall is open-source under the MIT license. You can clone the repository, customize the branding, and deploy it to your own server or cloud provider.
+Yes! Randall is open-source under the AGPL-3.0 license. You can clone the repository, customize the branding, and deploy it to your own server or cloud provider in compliance with the AGPL-3.0 terms.
 
 ---
 
@@ -195,5 +215,3 @@ Distributed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. See
 Built with ❤️ by **ARYA RCB** ([@superezzdev](https://github.com/superezzdev))
 - Website: [randall.superezz.dev](https://randall.superezz.dev)
 - GitHub: [@superezzdev](https://github.com/superezzdev)
-
-
diff --git a/ui/README.md b/ui/README.md
@@ -1,16 +1,31 @@
-# React + Vite
+# Randall UI 🎥
 
-This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+The frontend web application for **Randall**, built with React 19, Vite, Tailwind CSS, Motion, and Lucide Icons.
 
-Currently, two official plugins are available:
+## 🚀 Getting Started
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+### Install Dependencies
+```bash
+npm install
+```
 
-## React Compiler
+### Run Development Server
+```bash
+npm run dev
+```
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+### Build for Production
+```bash
+npm run build
+```
 
-## Expanding the Oxlint configuration
+### Lint Code
+```bash
+npm run lint
+```
 
-If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and Oxlint's TypeScript related rules in your project.
+## 📂 Architecture
+
+- **`src/components/`**: React UI components including `VideoChat.jsx`, `Home.jsx`, controls, and overlays.
+- **`src/hooks/`**: WebRTC P2P signaling (`useVideoChat.js`), draggable viewport (`useDraggable.js`), and mobile visual viewport handling.
+- **`src/pages/`**: Static pages (`About.jsx`, `Privacy.jsx`, `Terms.jsx`, `Safety.jsx`, `Contact.jsx`).