Safari Development Guide

English | 简体中文

Developer guide for building and extending Voyager for Safari.

# Install dependencies
bun install

# Build for Safari
bun run build:safari

This creates a dist_safari/ folder with the extension files.

# Convert to Safari format
xcrun safari-web-extension-converter dist_safari --macos-only --app-name "Gemini Voyager"

# Open in Xcode
open "Gemini Voyager/Gemini Voyager.xcodeproj"

In Xcode:

1. Select Signing & Capabilities → Choose your Team
2. Set target to My Mac
3. Press ⌘R to build and run

bun run dev:safari

This watches for file changes and rebuilds automatically. After each rebuild:

1. Press ⌘R in Xcode to reload
2. Safari will refresh the extension

# After code changes
bun run build:safari

# Then rebuild in Xcode (⌘R)

This project includes Swift code for native macOS features. Adding it is optional but recommended.

safari/
├── App/
│   └── SafariWebExtensionHandler.swift  # Native message handler
└── Models/
    └── SafariMessage.swift              # Message definitions

1. Open the Xcode project
2. Right-click "Gemini Voyager Extension" target
3. Select Add Files to "Gemini Voyager Extension"...
4. Navigate to safari/App/ and safari/Models/
5. Check "Copy items if needed"
6. Ensure target is "Gemini Voyager Extension"

Once added, you can:

• Access macOS Keychain (future)
• Use native notifications
• Access file system with native pickers
• Sync via iCloud (future)
• Enhanced debugging logs

From JavaScript:

// Health check
browser.runtime.sendNativeMessage({ action: 'ping' }, (response) => {
  console.log(response); // { success: true, data: { status: "ok", message: "pong" } }
});

// Get version
browser.runtime.sendNativeMessage({ action: 'getVersion' }, (response) => {
  console.log(response.data); // { version: "1.0.0", platform: "macOS" }
});

Available Actions:

• ping - Health check
• getVersion - Get extension version info
• syncStorage - Sync storage (placeholder for future)

Web Console:

• Safari → Develop → Web Extension Background Pages → Gemini Voyager

Native Logs:

log stream --predicate 'subsystem == "com.gemini-voyager.safari"' --level debug

"Module 'SafariServices' not found"

• Ensure Swift files are added to "Gemini Voyager Extension" target, not the main app

Native messaging not working

• Check Info.plist has SafariWebExtensionHandler as principal class

Swift files not compiling

• Verify Target Membership in Xcode file inspector

1. Product → Archive in Xcode
2. Window → Organizer
3. Select archive → Distribute App
4. Follow prompts to export

Requires:

• Apple Developer account ($99/year)
• App Store Connect setup
• App review submission

See Apple's official guide for details.

├── dist_safari/              # Built extension (gitignored)
├── safari/                   # Native Swift code
│   ├── App/                 # Extension handlers
│   ├── Models/              # Data models
│   └── Resources/           # Example code
├── src/                     # Main extension source
└── vite.config.safari.ts    # Safari build config

bun run build:safari   # Production build
bun run dev:safari     # Development with auto-reload
bun run build:all      # Build for all browsers

By default, update reminders are disabled for Safari builds to avoid conflicts with App Store auto-updates.

To enable update reminders (for manual distribution):

ENABLE_SAFARI_UPDATE_CHECK=true bun run build:safari

Note: Only enable this if you're distributing the extension manually (not via App Store). App Store versions should use the default (disabled) to rely on automatic updates.

Due to Safari's technical architecture and security restrictions, the following features are currently unavailable in the Safari version:

• (a) Nano Banana Watermark Removal: Watermark detection and removal for Gemini™-generated images is not supported.
• (b) Image Export: Direct export to image format is not supported (including in Chat Export). Recommendation: Use PDF Export instead.

• Safari Web Extensions Docs
• Native Messaging Guide
• Converting Extensions for Safari

See CONTRIBUTING.md for contribution guidelines.

When adding native features:

1. Define action in SafariMessage.swift
2. Implement handler in SafariWebExtensionHandler.swift
3. Add JavaScript API in web extension
4. Document in this README