convert-ui/README.md

# Convert UI

A modern, browser-based file conversion application built with Next.js 16, Tailwind CSS 4, and WebAssembly. Convert videos, images, and documents directly in your browser without uploading files to any server.

## Features

- **🎬 Video Conversion** - Convert between MP4, WebM, AVI, MOV, MKV, and GIF
- **🎵 Audio Conversion** - Convert between MP3, WAV, OGG, AAC, and FLAC
- **🖼️ Image Conversion** - Convert between PNG, JPG, WebP, GIF, BMP, TIFF, and SVG
- **📄 Document Conversion** - Convert between PDF, Markdown, HTML, and Plain Text
- **🔒 Privacy First** - All conversions happen locally in your browser, no server uploads
- **⚡ Fast & Efficient** - Powered by WebAssembly for near-native performance
- **🎨 Beautiful UI** - Modern, responsive design with dark/light theme support
- **🔍 Smart Search** - Fuzzy search for quick format selection
- **📝 Conversion History** - Track your recent conversions
- **🎯 Drag & Drop** - Easy file upload with drag-and-drop support

## Tech Stack

- **Next.js 16** - React framework with App Router and static export
- **React 19** - Latest React with concurrent features
- **TypeScript 5** - Type-safe development
- **Tailwind CSS 4** - Utility-first CSS with OKLCH color system
- **FFmpeg.wasm** - Video and audio conversion
- **ImageMagick WASM** - Image processing and conversion
- **Marked** - Markdown to HTML conversion
- **Turndown** - HTML to Markdown conversion
- **DOMPurify** - HTML sanitization
- **jsPDF** - PDF generation
- **PDF.js** - PDF text extraction
- **docx** - DOCX document generation
- **mammoth** - DOCX document reading
- **Fuse.js** - Fuzzy search for format selection
- **Lucide React** - Beautiful icon library

## Getting Started

### Prerequisites

- Node.js 22+ (managed via nvm)
- pnpm (enabled via corepack)

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd convert-ui

# Install dependencies
pnpm install

# Run development server
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000) to view the app.

### Build for Production

```bash
# Build static export
pnpm build

# Output will be in the /out directory
```

## Project Structure

```
convert-ui/
├── app/                              # Next.js App Router
│   ├── layout.tsx                   # Root layout with theme
│   ├── page.tsx                     # Main page
│   └── globals.css                  # Global styles
├── components/
│   ├── converter/                   # Converter components
│   │   ├── FileConverter.tsx        # Main state manager
│   │   ├── FileUpload.tsx          # Drag-and-drop upload
│   │   ├── FormatSelector.tsx      # Format selection with search
│   │   ├── ConversionPreview.tsx   # Preview and download
│   │   └── ConversionOptions.tsx   # Format-specific options
│   ├── layout/
│   │   └── ThemeToggle.tsx         # Dark/light theme toggle
│   └── ui/                         # Reusable UI components
│       ├── Button.tsx
│       ├── Card.tsx
│       ├── Toast.tsx
│       ├── Progress.tsx
│       ├── Skeleton.tsx
│       └── Input.tsx
├── lib/
│   ├── converters/                 # Conversion services
│   │   ├── ffmpegService.ts       # Video/audio conversion
│   │   ├── imagemagickService.ts  # Image conversion
│   │   └── pandocService.ts       # Document conversion (placeholder)
│   ├── wasm/
│   │   └── wasmLoader.ts          # WASM module lazy loading
│   ├── storage/
│   │   └── history.ts             # Conversion history
│   └── utils/
│       ├── cn.ts                  # Class name utility
│       ├── fileUtils.ts           # File operations
│       ├── formatMappings.ts      # Supported formats
│       └── debounce.ts            # Debounce utility
└── types/
    └── conversion.ts              # TypeScript interfaces
```

## Supported Formats

### Video (FFmpeg)
- **Input/Output:** MP4, WebM, AVI, MOV, MKV, GIF

### Audio (FFmpeg)
- **Input/Output:** MP3, WAV, OGG, AAC, FLAC

### Images (ImageMagick)
- **Input/Output:** PNG, JPG, WebP, GIF, BMP, TIFF, SVG

### Documents
- **PDF → Text/Markdown** - Extract text from PDF files with page-by-page processing
- **Markdown/HTML/Text → PDF** - Generate formatted PDF documents
- **DOCX → Text/HTML/Markdown** - Extract content from Word documents
- **Markdown/HTML/Text → DOCX** - Create formatted Word documents with headings
- **Markdown → HTML** - Full GitHub Flavored Markdown support with styling
- **HTML → Markdown** - Clean conversion with formatting preservation
- **Markdown ↔ Plain Text** - Strip or add basic formatting
- **HTML → Plain Text** - Extract text content
- **Plain Text → HTML** - Convert to formatted HTML document

**Supported PDF Operations:**
- Read PDFs and extract all text content
- Convert extracted text to Markdown or plain text
- Create PDFs from Markdown, HTML, or plain text
- Automatic pagination and formatting

**Supported DOCX Operations:**
- Read DOCX files and extract text, HTML, or Markdown
- Create DOCX files from Markdown with proper heading levels (H1-H3)
- Create DOCX files from HTML or plain text
- Automatic paragraph formatting and spacing

**Note:** Uses PDF.js for reading and jsPDF for generation. Uses mammoth for DOCX reading and docx library for generation. Lightweight JavaScript libraries (marked, turndown) used instead of Pandoc WASM for fast, reliable conversions.

## How It Works

1. **File Upload** - Users can drag-and-drop or click to select a file
2. **Format Detection** - The app automatically detects the input format
3. **Format Selection** - Choose from compatible output formats
4. **Conversion** - WASM modules are loaded on-demand and process the file
5. **Download** - Preview and download the converted file

### WASM Architecture

- **Lazy Loading** - WASM modules are only loaded when needed
- **Memory Management** - Proper cleanup after each conversion
- **Progress Tracking** - Real-time progress updates during conversion
- **Error Handling** - Graceful error handling with user-friendly messages

## Browser Compatibility

- **Chrome/Edge** - Full support
- **Firefox** - Full support
- **Safari** - Full support (with SharedArrayBuffer)

**Note:** Some features require SharedArrayBuffer support. The app sets the required COOP/COEP headers for this.

## Performance

- **File Size Limit** - 500MB (configurable)
- **Conversion Speed** - Varies by file size and format
  - Images: < 5s for typical files
  - Videos: Depends on length and quality
- **Memory Usage** - Managed automatically with cleanup

## Development

### Scripts

```bash
# Development server with Turbopack
pnpm dev

# Build for production
pnpm build

# Run production server
pnpm start

# Lint code
pnpm lint
```

### Adding New Formats

1. Add format to `lib/utils/formatMappings.ts`
2. Implement converter in appropriate service
3. Update type definitions in `types/conversion.ts`

### Customizing Theme

Colors are defined in `app/globals.css` using OKLCH color space. Modify CSS variables to change the theme:

```css
:root {
  --primary: oklch(22.4% 0.053 285.8);
  --background: oklch(100% 0 0);
  /* ... other colors */
}
```

## Docker Deployment

```bash
# Build Docker image
docker build -t convert-ui .

# Run container
docker run -p 80:80 convert-ui
```

The Dockerfile uses a multi-stage build with Nginx to serve the static export.

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

MIT License - See LICENSE file for details

## Acknowledgments

- [FFmpeg.wasm](https://github.com/ffmpegwasm/ffmpeg.wasm) - Video/audio conversion
- [ImageMagick WASM](https://github.com/dlemstra/magick-wasm) - Image processing
- [Next.js](https://nextjs.org/) - React framework
- [Tailwind CSS](https://tailwindcss.com/) - Styling
- [Fuse.js](https://fusejs.io/) - Fuzzy search

## Support

For issues, questions, or suggestions, please open an issue on GitHub.

---

**Made with ❤️ using Next.js 16 and WebAssembly**