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 - 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
• ✅ Status Bar Feedback - Live status messages during drag/open operations
• ✅ Path Whitelist - Security-conscious file system access control
• ✅ Configuration Management - JSON config, setup save/load, 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
• ✅ Adaptive Input Handling - Optional touch detection override for hybrid/mobile-like devices
• ✅ Window Geometry Persistence - Optional automatic save of window size on exit
• ✅ 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 - Native file logging and optional WebView JS console forwarding

Quick Start

Requirements

• Python 3.10+
• 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)

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

# macOS - Homebrew (with custom tap)
brew tap HIM-public/tap https://git.him-tools.de/HIM-public/homebrew-tap
brew install --cask webdrop-bridge

brew update
brew upgrade --cask webdrop-bridge  # Update to latest version

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

# Replace X.Y.Z with a release version (e.g., 0.9.2)
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.2:
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.2/WebDropBridge-0.9.2-win-x64.msi

Option 3: Automated script (auto-detects platform)

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

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

For more installation options and details, see QUICKSTART.md and PACKAGE_MANAGER_SUPPORT.md

For multi-brand packaging and release workflows, see BRANDING_AND_RELEASES.md.

Installation from Source

# 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

# 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/
│   ├── brands/                  # Runtime branding templates
│   ├── scripts/                 # Build/release automation scripts
│   ├── macos/                   # macOS packaging assets
│   └── chocolatey/              # Chocolatey package definitions
├── 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
• Translations Guide (i18n)

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
• Setups Tab - Save/load named local setups and import/export complete configurations

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.

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
AUTO_SAVE_WINDOW_GEOMETRY=true
DISABLE_TOUCH_DEVICE_DETECTION=false
ENABLE_LOGGING=true
ENABLE_JS_CONSOLE_LOGGING=true
ENABLE_CHECKOUT=false

For the full JSON structure and branding workflow, see CONFIG_README.md and BRANDING_AND_RELEASES.md.

Testing

WebDrop Bridge includes comprehensive test coverage with unit and integration tests.

# 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
• Channel/Manifest Aware: Supports update channels and release manifest based rollout
• 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.

Building Installers

Windows MSI Installer

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

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

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

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 📦 Releases

---

Development Phase: Phase 5 Release Candidates | Last Updated: July 3, 2026 | Current Version: 0.9.2 | Python: 3.10+ | Qt: PySide6 (Qt 6)