# 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-Phase%205%20RC%20In%20Progress-green) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.9%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** - Professional cross-platform desktop app via PySide6 for Windows and macOS
- ✅ **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
- ✅ **Configuration Management** - JSON config, profile import/export, and validation
- ✅ **Runtime Branding** - Switch branding templates and packaged variants without code changes
- ✅ **Multilingual UI** - Built-in translations for English, German, French, Italian, Russian, and Chinese
- ✅ **Settings Dialog** - Language, branding, web source, path, URL, logging, and window configuration
- ✅ **Auto-Update System** - Automatic release detection via Forgejo API
- ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS
- ✅ **Comprehensive Testing** - Unit and integration coverage across core modules
- ✅ **Continuous Testing** - Automated CI validation
- ✅ **Structured Logging** - File-based logging with configurable levels

## Quick Start

### Requirements
- Python 3.9+
- Windows 10/11 or macOS 12+
- 200 MB disk space (includes Chromium from PyInstaller)

### Installation from Pre-Built Release (Recommended)

**Option 1: Package Manager (Recommended for most users)**

```powershell
# Windows - Chocolatey
choco install webdrop-bridge
choco upgrade webdrop-bridge  # Update when new version available
```

```bash
# macOS - Homebrew (with custom tap)
brew tap HIM-public/webdrop-bridge https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git
brew install webdrop-bridge
brew upgrade webdrop-bridge  # Update to latest version
```

**Option 2: Direct wget (if you know the version)**

```bash
# Replace X.Y.Z with a release version (e.g., 0.9.1)
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-win-x64.msi

# Example for v0.9.1:
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi
```

**Option 3: Automated script (auto-detects platform)**

```bash
# Windows (PowerShell)
.\build\scripts\download_release.ps1

# macOS / Linux  
./build/scripts/download_release.sh
```

For more installation options and details, see [QUICKSTART.md](QUICKSTART.md#installing-from-release-wget) and [PACKAGE_MANAGER_SUPPORT.md](docs/PACKAGE_MANAGER_SUPPORT.md)

For multi-brand packaging and release workflows, see [BRANDING_AND_RELEASES.md](docs/BRANDING_AND_RELEASES.md).

### Installation from Source

```bash
# Clone repository
git clone https://git.him-tools.de/HIM-public/webdrop-bridge.git
cd webdrop-bridge

# Create and activate virtual environment
python -m venv venv
# venv\Scripts\activate.ps1       # Windows (PowerShell)
# venv\Scripts\activate.bat       # Windows (cmd.exe)

# Install dependencies
pip install -r requirements.txt
pip install -e .

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

### Development Setup

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

# Run tests
pytest tests -v

# Run all quality checks (lint, type, format)
tox

# Build installers
python build/scripts/build_windows.py --msi    # Windows MSI
```

## 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
│   └── 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
```

## Documentation

- [Architecture Guide](docs/ARCHITECTURE.md)
- [Translations Guide (i18n)](docs/TRANSLATIONS_GUIDE.md)

## 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

WebDrop Bridge supports persisted JSON configuration plus optional bootstrap environment defaults.

### 1. Settings Dialog / JSON Config (Recommended)
Launch the application and access the Settings menu to configure:
- **General Tab** - Select the UI language or follow the system locale automatically
- **Branding Tab** - Switch, import, export, and preview runtime branding templates
- **Web Source Tab** - Configure the embedded web application URL
- **Paths / URLs / Logging / Window Tabs** - Control filesystem access, allowed sites, log output, and initial window size
- **Profiles Tab** - Save, load, import, and export complete configuration profiles

Saved settings are written to the brand-specific application config directory as `config.json`.

### 2. Bootstrap Environment Variables (`.env`)
A `.env` file is still supported for local development and branded packaged defaults. It is used when no JSON config exists yet.

```bash
APP_NAME=WebDrop Bridge
BRAND_ID=webdrop_bridge
WEBAPP_URL=https://dev.agravity.io/
ALLOWED_ROOTS=Z:/,C:/Users/Public
ALLOWED_URLS=
LANGUAGE=auto
LOG_LEVEL=INFO
WINDOW_WIDTH=1024
WINDOW_HEIGHT=768
ENABLE_LOGGING=true
```

For the full JSON structure and branding workflow, see [CONFIG_README.md](CONFIG_README.md) and [BRANDING_AND_RELEASES.md](docs/BRANDING_AND_RELEASES.md).

## Testing

WebDrop Bridge includes comprehensive test coverage with unit, integration, and end-to-end tests.

```bash
# Run all tests
pytest tests -v

# Run with coverage report
pytest tests --cov=src/webdrop_bridge --cov-report=html

# Run specific test categories
pytest tests/unit -v                    # Unit tests only
pytest tests/integration -v             # Integration tests only

# Run specific test
pytest tests/unit/test_validator.py -v

# Run tests matching a pattern
pytest tests -k "config" -v
```

**Test Coverage**: 
- Current target: 80%+
- Coverage report: `htmlcov/index.html`

Integration tests cover:
- Drag-and-drop workflow
- Update flow and release detection
- End-to-end application scenarios

## Auto-Update System

WebDrop Bridge includes an intelligent auto-update system that:

- **Automatic Detection**: Periodically checks Forgejo/GitHub releases API
- **Smart Caching**: Avoids redundant network calls with smart caching
- **User Notification**: Alerts users of available updates via UI
- **Release Notes**: Displays release notes and changes
- **Safe Deployment**: Only triggers on newer versions

The update system is fully integrated with the application and runs in the background without blocking the UI.

For technical details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#update-system).

## Building Installers

### Windows MSI Installer

```bash
# Build with MSI installer (recommended)
python build/scripts/build_windows.py --msi

# Build with code signing (requires certificate)
python build/scripts/build_windows.py --msi --code-sign
```

Output:
- Portable executable: `build/dist/windows/webdrop_bridge/WebDropBridge/WebDropBridge.exe`
- Professional MSI installer: `build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi`
- SHA256 checksum: `build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi.sha256`

### macOS DMG Installer

```bash
bash build/scripts/build_macos.sh
```

Output:
- Application bundle: `build/dist/macos/webdrop_bridge/WebDropBridge.app`
- DMG installer: `build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg`
- SHA256 checksum: `build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg.sha256`

### Creating Releases

For Forgejo/GitHub releases:

```bash
# Windows - Create release with MSI installer
powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1
```

## 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.9+ is installed
- Check the application log in your platform-specific app data directory
- 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 | Primary target with MSI packaging and update support |
| macOS | 12, 13, 14 | ✅ Supported | Universal DMG builds for Intel and Apple Silicon |

**Note**: Release candidates currently target both Windows and macOS. For branded production releases, validate signing assets and installer behavior on the target platform before shipping.

## 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

## Support

- 📖 [Documentation](https://git.him-tools.de/HIM-public/webdrop-bridge/wiki)
- 🐛 [Issue Tracker](https://git.him-tools.de/HIM-public/webdrop-bridge/issues)
- 📦 [Releases](https://git.him-tools.de/HIM-public/webdrop-bridge/releases)

---

**Development Phase**: Phase 5 Release Candidates | **Last Updated**: April 16, 2026 | **Current Version**: 0.9.1 | **Python**: 3.9+ | **Qt**: PySide6 (Qt 6)