Build and test safari extension and publish

[ja7ad]

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)

  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:

   git clone https://github.com/your-org/hydra.git
   cd hydra

2. Run the Safari extension build script:

   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:

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