WebDrop Bridge

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

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

# 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

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

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

# Run all tests
pytest

# Run specific test type
pytest tests/unit/          # Unit tests only
pytest tests/integration/   # Integration tests only

# With coverage report
pytest --cov=src/webdrop_bridge --cov-report=html

# Run on specific platform marker
pytest -m windows           # Windows-specific tests
pytest -m macos            # macOS-specific tests

Building Installers

Windows MSI

pip install pyinstaller
python build/scripts/build_windows.py

Output: build/dist/WebDropBridge.exe

macOS DMG

pip install pyinstaller
bash build/scripts/build_macos.sh

Output: build/dist/WebDropBridge.dmg

Development Workflow

1. Create feature branch

   git checkout -b feature/my-feature
   

2. Write tests first

   pytest tests/unit/test_my_feature.py
   

3. Implement feature

   # Edit src/webdrop_bridge/...
   

4. Run quality checks

   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 for detailed guidelines.

License

MIT License - see LICENSE file for details

Credits

• Built with PySide6
• 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
• 🐛 Issue Tracker
• 💬 Discussions

---

Status: Alpha Development | Last Updated: January 2026