ai-terminal-assistant/packages/web/README.md

# @ai-assistant/web

Modern web interface for AI Terminal Assistant - built with React, Vite, and Tailwind CSS.

## 📦 Installation

```bash
# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build
```

## 🌟 Features

- **Modern UI** - Clean, responsive interface with dark/light themes
- **Real-time Chat** - WebSocket-based instant messaging
- **Code Editor** - Syntax highlighting with Monaco Editor
- **File Browser** - Browse and edit project files
- **Terminal Integration** - Embedded terminal for command execution
- **Markdown Rendering** - Rich text formatting for AI responses
- **PWA Support** - Install as desktop/mobile app
- **Mobile Responsive** - Optimized for all screen sizes
- **Keyboard Shortcuts** - Efficient navigation and actions

## 🏗️ Architecture

```
src/
├── components/
│   ├── Chat/              # Chat interface components
│   │   ├── ChatWindow.tsx
│   │   ├── MessageList.tsx
│   │   ├── MessageInput.tsx
│   │   └── CodeBlock.tsx
│   ├── Editor/            # Code editor components
│   │   ├── MonacoEditor.tsx
│   │   └── EditorToolbar.tsx
│   ├── FileBrowser/       # File navigation
│   │   ├── FileTree.tsx
│   │   └── FilePreview.tsx
│   ├── Terminal/          # Terminal emulator
│   │   └── XTerminal.tsx
│   ├── Layout/            # Layout components
│   │   ├── Sidebar.tsx
│   │   ├── Header.tsx
│   │   └── Tabs.tsx
│   └── Common/            # Shared components
│       ├── Button.tsx
│       ├── Modal.tsx
│       └── Loading.tsx
├── hooks/                 # Custom React hooks
│   ├── useChat.ts
│   ├── useWebSocket.ts
│   ├── useTheme.ts
│   └── useKeyboard.ts
├── services/              # API and service layer
│   ├── api.ts
│   ├── websocket.ts
│   └── storage.ts
├── store/                 # State management
│   ├── chat.store.ts
│   ├── editor.store.ts
│   └── settings.store.ts
├── styles/                # Global styles
│   └── index.css
├── types/                 # TypeScript definitions
├── utils/                 # Utility functions
├── App.tsx                # Main app component
└── main.tsx              # Entry point
```

## 🚀 Quick Start

### Development

```bash
# Start development server
pnpm dev

# The app will be available at http://localhost:5173
# Hot module replacement is enabled for instant updates
```

### Production Build

```bash
# Create optimized build
pnpm build

# Preview production build
pnpm preview

# Build output in dist/ directory
```

## 🎨 User Interface

### Main Features

#### Chat Interface
- **Message History** - Scrollable chat with persistent history
- **Code Highlighting** - Syntax highlighting for code blocks
- **File Attachments** - Drag & drop file support
- **Message Actions** - Copy, edit, regenerate responses
- **Streaming Responses** - Real-time AI response streaming

#### Code Editor
- **Monaco Editor** - VS Code's editor engine
- **Multi-file Tabs** - Work with multiple files
- **Syntax Highlighting** - 100+ language support
- **IntelliSense** - Code completion and hints
- **Diff View** - Side-by-side code comparison

#### File Browser
- **Tree View** - Hierarchical file structure
- **Quick Actions** - Create, rename, delete files
- **Search** - Fast file search with fuzzy matching
- **Preview** - Quick file preview without opening
- **Context Menu** - Right-click actions

#### Terminal
- **XTerm.js** - Full terminal emulation
- **Command History** - Navigate previous commands
- **Copy/Paste** - Standard clipboard operations
- **Themes** - Multiple color schemes

## 🎯 Component Examples

### Using the Chat Component

```tsx
import { Chat } from '@ai-assistant/web/components';

function App() {
  return (
    <Chat
      serverUrl="http://localhost:3000"
      sessionId="my-session"
      onMessage={(message) => console.log('New message:', message)}
      theme="dark"
    />
  );
}
```

### Custom Hook Usage

```tsx
import { useChat } from '@ai-assistant/web/hooks';

function MyComponent() {
  const { messages, sendMessage, isLoading } = useChat({
    serverUrl: 'http://localhost:3000',
    sessionId: 'my-session'
  });

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage('Hello AI!')}>
        Send Message
      </button>
    </div>
  );
}
```

## ⚙️ Configuration

### Environment Variables

Create `.env` file:

```env
# API Configuration
VITE_API_URL=http://localhost:3000
VITE_WS_URL=ws://localhost:3000
VITE_AUTH_TOKEN=your-token-here

# Feature Flags
VITE_ENABLE_TERMINAL=true
VITE_ENABLE_FILE_BROWSER=true
VITE_ENABLE_CODE_EDITOR=true

# Theme
VITE_DEFAULT_THEME=dark
```

### Build Configuration

`vite.config.ts`:

```typescript
export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://localhost:3000'
    }
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
    minify: 'esbuild'
  }
});
```

## 🎹 Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl/Cmd + Enter` | Send message |
| `Ctrl/Cmd + K` | Clear chat |
| `Ctrl/Cmd + /` | Toggle sidebar |
| `Ctrl/Cmd + ,` | Open settings |
| `Ctrl/Cmd + Shift + P` | Command palette |
| `Ctrl/Cmd + B` | Toggle file browser |
| `Ctrl/Cmd + J` | Toggle terminal |
| `Esc` | Close modal/popup |

## 📱 Progressive Web App

The app can be installed as a PWA:

1. Open in Chrome/Edge
2. Click install icon in address bar
3. Or use browser menu: "Install App"

Features:
- Offline support with service worker
- Desktop/mobile app experience
- Push notifications (coming soon)
- Background sync

## 🧪 Testing

```bash
# Run unit tests
pnpm test

# Run with coverage
pnpm test:coverage

# Run E2E tests
pnpm test:e2e

# Component testing
pnpm test:components
```

### Testing Examples

```tsx
import { render, screen } from '@testing-library/react';
import { Chat } from './Chat';

test('renders chat interface', () => {
  render(<Chat serverUrl="http://localhost:3000" />);
  expect(screen.getByPlaceholderText('Type a message...')).toBeInTheDocument();
});
```

## 🎨 Theming

### Custom Theme

```css
/* src/styles/themes/custom.css */
:root[data-theme="custom"] {
  --primary: #6366f1;
  --background: #0f172a;
  --foreground: #f8fafc;
  --border: #334155;
  --accent: #8b5cf6;
}
```

### Apply Theme

```tsx
import { useTheme } from '@ai-assistant/web/hooks';

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme('custom')}>
      Use Custom Theme
    </button>
  );
}
```

## 📊 Performance

### Optimization Tips

1. **Code Splitting** - Routes are lazy loaded
2. **Image Optimization** - WebP with fallbacks
3. **Bundle Size** - Tree shaking enabled
4. **Caching** - Service worker caching
5. **Virtual Scrolling** - For long lists

### Bundle Analysis

```bash
# Analyze bundle size
pnpm build:analyze

# Opens visualization in browser
```

## 🚀 Deployment

### Vercel

```bash
# Deploy to Vercel
vercel deploy --prod
```

### Docker

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
```

### Static Hosting

Build output in `dist/` can be served by any static host:
- Netlify
- GitHub Pages
- CloudFlare Pages
- AWS S3 + CloudFront

## 🤝 Contributing

See the main repository's contributing guide for details.

## 📄 License

MIT License - see [LICENSE](../../LICENSE) for details.

## 🔗 Links

- [Main Repository](https://github.com/username/ai-terminal-assistant)
- [Component Storybook](https://storybook.example.com)
- [Design System](https://design.example.com)