BROWSER_COMPATIBILITY.md

Browser Compatibility Guide

This guide explains how to adapt the AWS Pricing Helper extension for different browsers.

Overview

The core extension logic (config.js, content.js, styles.css) is browser-agnostic and works across all browsers. The main differences are in the manifest files and distribution methods.

Browser Support Matrix

Browser	Manifest Version	Manifest File	Distribution	Notes
Chrome	V3	manifest.json	Chrome Web Store	Reference implementation
Brave	V3	manifest.json	Chrome Web Store	Same as Chrome
Edge	V3	manifest.json	Microsoft Store	Same as Chrome
Firefox	V2	manifest-firefox.json	Firefox Add-ons	Different manifest format
Safari	V3	manifest-safari.json	App Store	Requires Apple Developer account

Key Differences

1. Manifest Version Differences

Chrome/Brave/Edge (Manifest V3)

{
  "manifest_version": 3,
  "permissions": ["activeTab", "storage"],
  "host_permissions": ["https://*.console.aws.amazon.com/*"],
  "action": { "default_popup": "popup.html" }
}

Firefox (Manifest V2)

{
  "manifest_version": 2,
  "permissions": ["activeTab", "storage", "https://*.console.aws.amazon.com/*"],
  "browser_action": { "default_popup": "popup.html" }
}

2. Permission Handling

• Chrome/Brave/Edge/Safari: Separate permissions and host_permissions
• Firefox: All permissions in single permissions array

3. Action vs Browser Action

• Chrome/Brave/Edge/Safari: Uses "action"
• Firefox: Uses "browser_action"

Implementation Steps

For Firefox

1. Rename manifest file:

   cp manifest.json manifest-chrome.json
   cp manifest-firefox.json manifest.json

2. Test in Firefox:

   • Open Firefox
   • Go to about:debugging
   • Click "This Firefox"
   • Click "Load Temporary Add-on"
   • Select your manifest.json

3. Package for distribution:

   zip -r aws-pricing-helper-firefox.zip . -x "manifest-chrome.json" "manifest-safari.json"

For Safari

1. Use Safari manifest:

   cp manifest-safari.json manifest.json

2. Requirements:

   • Apple Developer account ($99/year)
   • Xcode for development
   • Safari App Extensions framework

3. Development process:

   • Create Safari App Extension in Xcode
   • Import your extension files
   • Test in Safari
   • Submit to App Store

For Brave

1. Use Chrome manifest (no changes needed)
2. Install from Chrome Web Store or load unpacked extension
3. Brave automatically supports Chrome extensions

Code Compatibility

JavaScript Compatibility

The extension uses standard web APIs that work across all browsers:

✅ DOM APIs: document.querySelector, addEventListener, etc.
✅ ES6+ Features: Arrow functions, const/let, template literals
✅ Web APIs: MutationObserver, setTimeout, etc.

CSS Compatibility

The styles use standard CSS that works in all browsers:

✅ Flexbox: Modern layout system
✅ CSS Variables: Custom properties
✅ Transitions: Smooth animations
✅ Positioning: Fixed positioning for overlay

Testing Strategy

1. Automated Testing

// Add to your test suite
describe('Browser Compatibility', () => {
  test('should work in Chrome', () => {
    // Test Chrome-specific features
  });
  
  test('should work in Firefox', () => {
    // Test Firefox-specific features
  });
  
  test('should work in Safari', () => {
    // Test Safari-specific features
  });
});

2. Manual Testing Checklist

• Extension loads without errors
• Pricing messages display correctly
• Click events work properly
• Auto-hide functionality works
• URL change detection works
• Popup opens correctly
• Icons display properly

Distribution

Chrome Web Store

• Submit manifest.json (V3)
• Pay one-time $5 registration fee
• Review process takes 1-3 days

Firefox Add-ons

• Submit manifest-firefox.json (V2)
• Free registration
• Review process takes 1-2 weeks

Safari App Store

• Requires Apple Developer account
• Must be distributed as macOS app
• Review process takes 1-2 weeks

Direct Installation

• Users can load unpacked extensions
• Works in Chrome, Brave, Edge
• Not supported in Firefox/Safari

Troubleshooting

Common Issues

1. Firefox: "manifest_version" error

   • Solution: Use Manifest V2 format

2. Safari: Extension not loading

   • Solution: Check Apple Developer account and certificates

3. Brave: Extension blocked

   • Solution: Enable "Allow extensions from other stores" in settings

4. Cross-browser CSS differences

   • Solution: Use CSS prefixes or autoprefixer

Debug Tips

1. Check browser console for JavaScript errors
2. Verify manifest syntax with browser's extension validator
3. Test permissions by checking if content scripts load
4. Use browser dev tools to inspect extension elements

Future Considerations

Manifest V3 Migration (Firefox)

Firefox is planning to support Manifest V3. When available:

1. Update Firefox manifest to V3
2. Use same format as Chrome
3. Remove V2-specific code

Web Extensions API

Consider using the Web Extensions API for better cross-browser compatibility:

// Instead of browser-specific APIs
if (typeof browser !== 'undefined') {
  // Firefox
  browser.runtime.sendMessage(data);
} else {
  // Chrome/Brave/Edge/Safari
  chrome.runtime.sendMessage(data);
}

Conclusion

The extension is well-designed for cross-browser compatibility. The main work involves:

1. Creating browser-specific manifest files
2. Testing in each browser
3. Following browser-specific distribution processes

The core functionality will work identically across all supported browsers!