@jean2/client 0.2.1 → 0.3.0

package/README.md

@@ -1,11 +1,178 @@
 # Jean2 Client
 
-A Tauri-based desktop application for macOS. React + Vite frontend with a modern chat interface for AI interactions.
+Cross-platform frontend for the Jean2 AI Agent. Connects to a Jean2 server over WebSocket and REST API for real-time AI chat sessions with tool execution, multi-workspace support, and multi-server management.
 
-## Installation
+Three deployment targets:
 
-Download the latest release from GitHub releases for macOS.
+- **Tauri Desktop** — Native macOS application with multi-window support
+- **Tauri iOS** — Native iPhone application
+- **Web CLI** — Run locally via `npx @jean2/client`
 
-## Usage
+## Features
 
-Launch the application from your Applications folder. Connect to a Jean2 server instance to start using the AI agent.
+- Streaming chat with real-time message updates and token usage display
+- Multi-model and multi-provider selection (budget/standard/premium tiers)
+- Session management — create, close, reopen, rename, fork, compact, and revert
+- Multi-server and multi-workspace support with quick switching
+- Tool permission approval flow with allow-once and always-allow options
+- File tree browser and file path autocomplete
+- MCP (Model Context Protocol) server management
+- Queued messages when a session is busy streaming
+- Offline detection with exponential backoff auto-reconnect
+- Dark and light themes (persists per platform)
+- Responsive layout — works on desktop and mobile viewports
+
+## Prerequisites
+
+- [Bun](https://bun.sh/)
+- For Tauri desktop builds: [Rust](https://www.rust-lang.org/tools/install) and Xcode Command Line Tools (`xcode-select --install`)
+- For iOS builds: Xcode, Apple Developer account — see [README-ios.md](README-ios.md)
+
+## Development
+
+```bash
+# Install dependencies (from repo root)
+bun install
+
+# Start Vite dev server (port 5173, proxies to server on port 3000)
+bun run dev
+```
+
+The Vite dev server proxies `/api` and `/ws` to `http://localhost:3000`.
+
+### Tauri Desktop (Live Reload)
+
+```bash
+# Opens native window with hot module replacement
+bun run tauri:dev
+```
+
+### Tauri iOS (Live Reload)
+
+```bash
+bun run tauri:ios:dev
+```
+
+## Building
+
+### Web
+
+```bash
+bun run build
+# Output: dist/
+```
+
+### Tauri Desktop
+
+```bash
+# macOS (Apple Silicon)
+bun run tauri:build:macos
+
+# Generic (all targets)
+bun run tauri:build
+```
+
+### macOS Gatekeeper (Unsigned Builds)
+
+Apps downloaded from GitHub releases are not code-signed. macOS will block opening them by default. Remove the quarantine attribute:
+
+```bash
+xattr -cr /Applications/Jean2.app
+```
+
+### Tauri iOS
+
+See [README-ios.md](README-ios.md) for full build and deployment instructions.
+
+### CLI / npx
+
+```bash
+bun run build:npx
+# Output: dist/cli.mjs (bundled Node.js server)
+```
+
+## Running via npx
+
+```bash
+npx @jean2/client
+# Opens browser to http://localhost:3774
+
+# Custom port
+npx @jean2/client --port 8080
+```
+
+The CLI bundles the built web assets and serves them with a static Node.js HTTP server.
+
+## Project Structure
+
+```
+packages/client/
+  src/
+    App.tsx              Root component, WebSocket + REST state management
+    main.tsx             Entry point, ThemeProvider wrapper
+    cli.ts               npx CLI — static file server
+    index.css            Tailwind v4, theme tokens, responsive utilities
+    components/
+      chat/              ChatView, MessageBubble, MessageInput, ToolCall, etc.
+      layout/            AppSidebar, QuickSwitcher, WorkspaceSwitcher, FilesPanel
+      modals/            SettingsDialog, MCPManagementDialog, AddServerDialog
+      visualizations/    CodeBlock, DiffViewer, TerminalOutput, TodoList, etc.
+      shared/            MarkdownRenderer, ThemeToggle, EmptyState, OfflineState
+      files/             FileTree, FileTreeNode, FileAutocomplete
+      providers/         ThemeProvider
+      ui/                shadcn/ui primitives (button, dialog, sidebar, etc.)
+    contexts/
+      ServerContext.tsx   Multi-server state, quick connections
+    hooks/
+      useApi.ts          Authenticated fetch helper
+      useFileSearch.ts   File search utility
+      useLocalStorage.ts LocalStorage hook
+      use-mobile.ts      Mobile viewport detection
+    config/
+      auth.ts            Token validation, URL normalization
+      servers.ts         Server CRUD in localStorage
+    lib/
+      utils.ts           cn() and Tailwind merge
+      storage.ts         Platform-agnostic storage (Tauri Store / localStorage)
+      path.ts            Path utilities
+    utils/
+      diff.ts            Diff parsing utilities
+  src-tauri/
+    tauri.conf.json      Tauri configuration
+    src/
+      lib.rs             Platform gate (desktop vs mobile)
+      desktop.rs         Desktop entry — multi-window, plugins
+      mobile.rs          iOS entry — plugins only
+  components.json        shadcn/ui configuration (radix-nova style)
+  vite.config.ts         Vite — React, Tailwind, path aliases, dev proxy
+  package.npm.json       Minimal manifest for npm publish (CLI mode)
+  VERSION                Client version (0.2.1)
+```
+
+## Technology Stack
+
+| Layer        | Technology                                  |
+| ------------ | ------------------------------------------- |
+| Framework    | React 19                                    |
+| Build        | Vite 6, TypeScript                          |
+| Styling      | Tailwind CSS v4, shadcn/ui, Radix UI        |
+| Fonts        | Geist Variable                              |
+| Icons        | Lucide React                                |
+| Desktop      | Tauri 2 (Rust)                              |
+| Mobile       | Tauri 2 iOS                                 |
+| Markdown     | react-markdown + remark-gfm                 |
+| Code blocks  | prism-react-renderer                        |
+| Storage      | @tauri-apps/plugin-store / localStorage     |
+| CLI          | esbuild bundle, Node.js http module         |
+
+## Architecture
+
+The client connects to a Jean2 server via WebSocket (`ws://host:port/ws?token=...`) for real-time events and REST (`http://host:port/api`) for initial data loading. All communication is authenticated with a bearer token.
+
+**WebSocket protocol** handles session CRUD, message streaming (including delta-based text append), part creation/updates, permission requests, queue management, usage tracking, and compaction events. The `App.tsx` handler dispatches all `ServerMessage` types into React state.
+
+**Multi-server support** allows connecting to multiple Jean2 server instances. Servers are persisted in localStorage. Switching servers clears all session state and reconnects.
+
+**Multi-workspace support** isolates sessions by workspace. The active workspace is persisted and restored on reload.
+
+**Platform abstraction** — the `storage` module (`lib/storage.ts`) transparently uses Tauri Store on native platforms and falls back to localStorage on web. The Tauri Rust layer adds native-only features like multi-window (`Cmd+N`).