# WebDrop Bridge

> Professional Qt-based desktop application for intelligent drag-and-drop file handling between web applications and desktop clients (InDesign, Word, Notepad++, etc.)

![Status](https://img.shields.io/badge/Status-Development-yellow) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.10%2B-blue)

## Overview

WebDrop Bridge is a sophisticated desktop bridge application that intercepts text-based drag-and-drop operations from embedded web applications and converts them into native file-drag operations recognized by professional desktop applications.

### The Problem
Modern web applications can transmit file paths via drag-and-drop, but desktop applications expect native file handles. Traditional solutions fail because:
- Browsers sandbox cross-origin drag-and-drop
- Web apps can't access the file system directly
- Native apps need OS-level file handles (CF_HDROP on Windows, NSFilenamesPboardType on macOS)

### The Solution
WebDrop Bridge embeds a web application in a Qt container with full filesystem access, intelligently intercepting and converting drag operations at the OS boundary.

## Features

- ✅ **Qt-based Architecture** - Native Windows & macOS support via PySide6
- ✅ **Embedded Web App** - QtWebEngine provides Chromium without browser limitations
- ✅ **Drag Interception** - Converts text paths to native file operations
- ✅ **Path Whitelist** - Security-conscious file system access control
- ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS
- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests
- ✅ **CI/CD Ready** - GitHub Actions workflows included

## Quick Start

### Requirements
- Python 3.10+
- Windows 10/11 or macOS 12+
- 100 MB disk space

### Installation from Source

```bash
# Clone repository
git clone https://github.com/yourusername/webdrop-bridge.git
cd webdrop-bridge

# Create virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Run application
python -m webdrop_bridge.main
```

### Development Setup

```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run linting checks
tox -e lint

# Build for your platform
tox -e build-windows   # Windows
tox -e build-macos     # macOS
```

## Project Structure

```
webdrop-bridge/
├── src/webdrop_bridge/          # Main application package
│   ├── core/                    # Core logic (drag interception, config)
│   ├── ui/                      # UI components (main window, widgets)
│   ├── utils/                   # Utilities (logging, validation)
│   ├── main.py                  # Entry point
│   └── config.py                # Configuration management
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   ├── fixtures/                # Test data and fixtures
│   └── conftest.py              # Pytest configuration
├── build/
│   ├── windows/                 # Windows-specific build configs
│   ├── macos/                   # macOS-specific build configs
│   └── scripts/                 # Build automation scripts
├── webapp/                      # Embedded web application
├── resources/
│   ├── icons/                   # Application icons
│   └── stylesheets/            # Qt stylesheets
├── docs/                        # Documentation
├── pyproject.toml               # Modern Python packaging
├── pytest.ini                   # Test configuration
├── tox.ini                      # Test automation
└── README.md                    # This file
```

## Architecture

```
┌────────────────────────────────────────┐
│  Qt Main Window (PySide6)              │
│  ┌──────────────────────────────────┐  │
│  │  QtWebEngineView                 │  │
│  │  ┌────────────────────────────┐  │  │
│  │  │  Web Application (HTML/JS) │  │  │
│  │  │  • Drag with file paths    │  │  │
│  │  │  • Native drag operations  │  │  │
│  │  └────────────────────────────┘  │  │
│  └──────────────────────────────────┘  │
│         ↓ Drag Leave Event              │
│  ┌──────────────────────────────────┐  │
│  │  DragInterceptor                 │  │
│  │  • Validates path (whitelist)    │  │
│  │  • Creates QUrl + QMimeData      │  │
│  │  • Starts native file drag       │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘
         ↓ Native File Drag
   ┌─────────────────┐
   │ InDesign/Word   │
   │ (receives file) │
   └─────────────────┘
```

## Configuration

Create `.env` file from `.env.example`:

```bash
cp .env.example .env
```

Key settings:
- `WEBAPP_URL` - Local or remote web app URL
- `ALLOWED_ROOTS` - Comma-separated whitelist of allowed directories
- `LOG_LEVEL` - DEBUG, INFO, WARNING, ERROR
- `WINDOW_WIDTH` / `WINDOW_HEIGHT` - Initial window size

## Testing

- Unit tests: `pytest tests/unit/ -v`
- Integration tests: `pytest tests/integration/ -v`
- Coverage: `pytest --cov=src/webdrop_bridge`

Integration tests for the update workflow are in [tests/integration/test_update_flow.py](tests/integration/test_update_flow.py).

## Auto-Update System

WebDrop Bridge supports automatic updates via the Forgejo Releases API. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for technical details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release notes.

## Building Installers

### Windows MSI

```bash
pip install pyinstaller
python build/scripts/build_windows.py
```

Output: `build/dist/WebDropBridge.exe`

### macOS DMG

```bash
pip install pyinstaller
bash build/scripts/build_macos.sh
```

Output: `build/dist/WebDropBridge.dmg`

## Development Workflow

1. **Create feature branch**
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Write tests first**
   ```bash
   pytest tests/unit/test_my_feature.py
   ```

3. **Implement feature**
   ```bash
   # Edit src/webdrop_bridge/...
   ```

4. **Run quality checks**
   ```bash
   tox -e lint,type  # Run linting and type checking
   ```

5. **Submit pull request**

## Troubleshooting

### Application won't start
- Ensure Python 3.10+ is installed
- Check `logs/webdrop_bridge.log` for errors
- Verify all dependencies: `pip list`

### Drag-and-drop not working
- Verify paths in `.env` are valid
- Check `ALLOWED_ROOTS` whitelist includes your test directory
- On macOS, check System Preferences → Security & Privacy → Accessibility

### Build errors
- Clean build directory: `rm -rf build/temp build/dist`
- Reinstall dependencies: `pip install --force-reinstall -r requirements.txt`
- Check platform-specific requirements (Windows SDK, Xcode for macOS)

## Platform Support

| Platform | Version | Status | Notes |
|----------|---------|--------|-------|
| Windows | 10, 11 | ✅ Full | Tested on x64 |
| macOS | 12, 13, 14 | ✅ Full | Intel & Apple Silicon |
| Linux | Ubuntu 22.04+ | ⚠️ Partial | Limited testing |

## Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Write/update tests
4. Submit a pull request
5. Ensure CI passes

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## License

MIT License - see [LICENSE](LICENSE) file for details

## Credits

- Built with [PySide6](https://wiki.qt.io/Qt_for_Python)
- Inspired by professional desktop integration practices
- Special thanks to the Qt community

## Roadmap

- [ ] v1.0 - Stable Windows & macOS release
- [ ] v1.1 - Advanced filtering and logging UI
- [ ] v1.2 - API for custom handlers
- [ ] v2.0 - Plugin architecture
- [ ] v2.1 - Cloud storage integration (OneDrive, Google Drive)

## Support

- 📖 [Documentation](https://webdrop-bridge.readthedocs.io)
- 🐛 [Issue Tracker](https://github.com/yourusername/webdrop-bridge/issues)
- 💬 [Discussions](https://github.com/yourusername/webdrop-bridge/discussions)

---

**Status**: Alpha Development | **Last Updated**: January 2026