claudi
ac10fdcbdd
Some checks failed
Tests & Quality Checks / Test on Python 3.11 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.11-1 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12-1 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.10 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.11-2 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12-2 (push) Has been cancelled
Tests & Quality Checks / Build Artifacts (push) Has been cancelled
Tests & Quality Checks / Build Artifacts-1 (push) Has been cancelled
377 lines
14 KiB
Markdown
377 lines
14 KiB
Markdown
# 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
|
|
- ✅ **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)
|