Build and test safari extension and publish
- Dominant language
- Rust
- Stars
- 528
- Forks
- 38
- Avg merge
- 5h 26m
- Merged PRs (30d)
- 131
Description
Help us build, test, and validate the Hydra Safari extension across different macOS versions and hardware configurations.
## What we need
- ✅ Build verification on various macOS versions (currently targeting Safari 16.4+)
- ✅ End-to-end testing of extension features
- ✅ Bug reports and compatibility findings
- ✅ User experience feedback
## Prerequisites
Before you start, you'll need:
- **macOS** (10.15+, tested on 12.x+)
- **Full Xcode** installed (not just Command Line Tools)
```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```
- **Rust** (with Apple Silicon or Intel target support)
- Git and the hydra repository cloned locally
## Build Instructions
1. Clone and navigate to the repo:
```bash
git clone https://github.com/your-org/hydra.git
cd hydra
```
2. Run the Safari extension build script:
```bash
scripts/build-safari-extension.sh
```
The script will:
- Sync resources from the shared Chrome extension code
- Generate the Safari wrapper app
- Install the native handler (SafariWebExtensionHandler.swift)
- Configure sandbox exceptions and ATS settings
- Build the final extension
3. Install in Safari:
- Open the built app from `target/release/` once
- Go to **Safari → Settings → Extensions → Hydra**
- Enable the Hydra extension
- For unsigned dev builds: enable **Develop → Allow Unsigned Extensions** (Safari clears this on restart)
## Testing Checklist
### Basic Features (All Platforms)
- [ ] Right-click menu → "Download with Hydra" works on links
- [ ] Selection pill appears when hovering over links (visual indicator)
- [ ] "Download all links on page" menu option functions
- [ ] Extension popup opens and shows status
- [ ] Status badge appears on extension icon
- [ ] Toggle capture on/off from popup
### Integration with Hydra App
- [ ] Clicking "Download with Hydra" launches the app (if not running)
- [ ] App receives download requests via WebSocket
- [ ] Extension communicates with local app on port 6799
- [ ] Status updates reflect in both app and extension
### Known Limitations (Expected Behavior)
- [ ] ⚠️ Automatic download capture does NOT work (Safari limitation: no downloads API)
- *This is expected and cannot be fixed — use right-click menu or selection pill instead*
## Reporting Issues
When filing a bug report, please include:
```markdown
**macOS Version:** (e.g., 12.5, 13.2)
**Safari Version:** (e.g., 16.4)
**Hardware:** (Intel / Apple Silicon)
**Hydra App Version:** [hash or version]
**Feature Tested:**
**Expected Behavior:**
**Actual Behavior:**
**Steps to Reproduce:**
1.
2.
3.
**Screenshots/Recordings:** (if applicable)
```
## Technical Details
The Safari extension uses a unique architecture:
- **Shared code**: Extension source in `extensions/chrome/` is browser-neutral (binds `browser` namespace, handles both messaging dialects)
- **Platform manifest**: Safari-specific config in `extensions/safari/manifest.json`
- **Resources sync**: `scripts/sync-extension-resources.sh safari` regenerates `extensions/safari/Resources/`
- **Native handler**: `SafariWebExtensionHandler.swift` forwards requests to the Hydra app via line-protocol socket
- **Transport**: Extension talks to Hydra over WebSocket on loopback port 6799
**Important**: Edit `extensions/chrome/*`, not `extensions/safari/Resources/*` — the latter is auto-generated.
## Platform Support Matrix
| Feature | Status | Notes |
|---------|--------|-------|
| Right-click download | ✅ Works | Core feature, fully functional |
| Selection pill | ✅ Works | Visual UI element working |
| Download all links | ✅ Works | Batch download support |
| Status badge | ✅ Works | Icon indicator functional |
| Media sniffing | ⚠️ Partial | Works where Safari exposes `webRequest` |
| **Auto-capture downloads** | ❌ N/A | Safari API limitation, not a bug |
Contributor guide
Research direction
Start with scripts/build-safari-extension.sh and scripts/sync-extension-resources.sh, then inspect extensions/chrome/, extensions/safari/manifest.json, and SafariWebExtensionHandler.swift. Run the build on the available macOS and hardware setup, install the result in Safari, and work through the listed feature and Hydra integration checklist. Done means build results, compatibility findings, and reproducible bug reports are recorded.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, macos, rust, swift
- Domain
- build-system, desktop, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100