# ✦ Moltbot Mobile

A React Native / Expo chat client for the Moltbot gateway. Works in **Expo Go** on both iOS and Android — no custom builds needed.

## Features

- 🔌 Real-time WebSocket connection to Moltbot gateway (protocol v3)
- 💬 Streaming chat responses with live text updates
- 🎨 Black & gold Moltbot brand theme
- ⚙️ Settings screen to configure gateway URL and auth token
- 📱 Safe area + keyboard-aware layout for all devices
- 🔄 Auto-reconnect on connection drop
- 📜 Chat history loading on connect

## Quick Start

### Prerequisites
- [Node.js](https://nodejs.org/) 18+
- [Expo Go](https://expo.dev/go) app on your phone (iOS or Android)
- A running Moltbot gateway

### Setup

```bash
cd moltbot-mobile
npm install
npx expo start
```

### Connect via Expo Go

1. Run `npx expo start` — you'll see a QR code in the terminal
2. **iOS**: Open Camera app → scan QR code → tap the Expo link
3. **Android**: Open Expo Go app → scan QR code
4. The app will load and attempt to connect to the gateway

### Configure Gateway URL

The default gateway URL is `ws://localhost:3033`. To connect to your gateway:

1. Tap the ⚙️ icon in the top-right corner
2. Enter your gateway WebSocket URL:
   - **Local (same WiFi)**: `ws://YOUR_COMPUTER_IP:3033`
   - **Remote (Tailscale)**: `ws://TAILSCALE_IP:3033`
   - **Secure**: `wss://your-domain.com:3033`
3. Add an auth token if your gateway requires one
4. Tap **Save Settings** → **Reconnect to Gateway**

### Finding Your Local IP

- **Windows**: `ipconfig` → look for IPv4 Address
- **macOS**: `ifconfig en0` → look for `inet` address
- **Linux**: `ip addr show` → look for `inet` address

Make sure your phone is on the same WiFi network as your computer.

## Tech Stack

- **Expo SDK 54** (managed workflow, Expo Go compatible)
- **React Navigation** (native stack)
- **AsyncStorage** for settings persistence
- **WebSocket** (built-in, no native modules)

## Gateway Protocol

Connects using the Moltbot Gateway WebSocket protocol v3:

- **Handshake**: Sends `connect` request with operator role
- **Chat**: Uses `chat.send` / `chat.history` methods
- **Streaming**: Receives `chat` events with delta/final states
- **Keepalive**: Automatic ping based on server tick interval

## Project Structure

```
moltbot-mobile/
├── App.js                    # Root app with navigation
├── src/
│   ├── constants/
│   │   ├── theme.js          # Colors, fonts, spacing
│   │   └── gateway.js        # Protocol constants
│   ├── hooks/
│   │   └── useGateway.js     # WebSocket connection hook
│   ├── components/
│   │   ├── ConnectionStatus.js
│   │   ├── MessageBubble.js
│   │   └── ChatInput.js
│   ├── screens/
│   │   ├── ChatScreen.js
│   │   └── SettingsScreen.js
│   └── utils/
│       └── storage.js        # AsyncStorage helpers
└── README.md
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Disconnected" status | Check gateway URL in Settings, ensure gateway is running |
| Can't connect from phone | Use computer's local IP, not `localhost`. Ensure same WiFi |
| Auth errors | Add your gateway token in Settings |
| Blank screen on load | Shake device → "Reload" in Expo dev menu |
