Skip to content

firefox.md

Latest commit

 

History

History
408 lines (284 loc) · 12.1 KB

firefox.md

File metadata and controls

408 lines (284 loc) · 12.1 KB

Firefox Compatibility Guide

This document details Firefox-specific implementation notes, API compatibility findings, and known differences between the Chrome and Firefox versions of the Summarize extension.

Chrome API Usage Investigation

Standard WebExtensions APIs (Compatible)

The following Chrome APIs are used throughout the extension and have direct Firefox equivalents via the browser.* namespace. WXT automatically polyfills these:

Core Extension APIs

  • chrome.runtime: Message passing, extension info, connections

    • runtime.onMessage, runtime.sendMessage
    • runtime.onConnect, runtime.connect, runtime.Port
    • runtime.getURL, runtime.getManifest
    • runtime.openOptionsPage
    • ✅ Firefox compatible (all methods supported)

  • chrome.tabs: Tab management and queries

    • tabs.query, tabs.get, tabs.create, tabs.update
    • tabs.sendMessage
    • tabs.onActivated, tabs.onUpdated
    • ✅ Firefox compatible

  • chrome.storage: Persistent and session storage

    • storage.local.get, storage.local.set
    • storage.session (used for ephemeral data)
    • storage.onChanged
    • ⚠️ Mostly compatible - storage.session requires Firefox 115+

  • chrome.scripting: Dynamic content script injection

    • scripting.executeScript
    • ✅ Firefox compatible (MV3)

  • chrome.windows: Window management

    • windows.getCurrent, windows.create, windows.update
    • ✅ Firefox compatible

  • chrome.webNavigation: Navigation events

    • webNavigation.onHistoryStateUpdated
    • ✅ Firefox compatible

  • chrome.permissions: Runtime permissions

    • permissions.contains, permissions.request
    • ✅ Firefox compatible

Chrome-Specific APIs (Requires Attention)

1. Side Panel API (Primary Incompatibility)

Chrome usage (wxt.config.ts:56, 77-79, background.ts:1583):

// Manifest
side_panel: {
  default_path: 'sidepanel/index.html',
}

// Runtime API
chrome.sidePanel?.setPanelBehavior?.({ openPanelOnActionClick: true })

Firefox equivalent: sidebar_action API (Firefox 131+)

// Manifest override needed
sidebar_action: {
  default_panel: 'sidepanel.html',
  default_title: 'Summarize',
  default_icon: 'assets/icon-128.png'
}

Migration notes:

  • Firefox sidebar is always visible in the sidebar (not a side panel that slides in)
  • No equivalent to setPanelBehavior - sidebar is opened manually
  • Same HTML content can be reused (sidepanel.html)
  • UI may need minor adjustments for Firefox sidebar dimensions

Files affected:

  • wxt.config.ts - Needs Firefox manifest override
  • src/entrypoints/background.ts:1583 - setPanelBehavior call should be Chrome-only

2. Debugger API (Advanced Features)

Usage (background.ts:407-480, automation/tools.ts:336-366):

chrome.debugger.attach({ tabId }, "1.3");
chrome.debugger.sendCommand({ tabId }, method, params);
chrome.debugger.detach({ tabId });

Firefox compatibility: ✅ Supported but may have behavioral differences

  • Firefox has browser.debugger with same API surface
  • Used for automation features (CDP commands)
  • Requires debugger permission (already declared)
  • Testing needed: Verify CDP protocol compatibility

3. UserScripts API (Optional)

Usage (automation/userscripts.ts:14-16, background.ts, automation/repl.ts:142-171):

chrome.userScripts;
chrome.permissions.contains({ permissions: ["userScripts"] });

Firefox compatibility: ⚠️ Limited support

  • Firefox has experimental browser.userScripts support
  • Available in Firefox 128+ behind extensions.userScripts.enabled pref
  • Less mature than Chrome implementation
  • Implementation: Feature-detect and gracefully degrade (see automation/userscripts.ts)
    • getUserScriptsStatus() checks API availability
    • buildUserScriptsGuidance() provides user-friendly error messages
    • Automation features show clear guidance if API unavailable

Storage Quota Considerations

Current usage pattern: Caching summaries, settings, and session data

Chrome quotas:

  • storage.local: ~10 MB (can request more with unlimitedStorage)
  • storage.session: ~10 MB

Firefox quotas:

  • storage.local: 10 MB default (same as Chrome)
  • storage.session: 10 MB (Firefox 115+)

Action required:

  • Monitor cache size in production
  • Implement LRU eviction if approaching limits
  • Consider adding warnings at 80% capacity

Manifest Differences

Required Changes for Firefox

Chrome manifest (current):

{
  "permissions": ["sidePanel", ...],
  "side_panel": {
    "default_path": "sidepanel/index.html"
  }
}

Firefox manifest override (needed):

{
  "permissions": ["tabs", "activeTab", "storage", ...],
  "sidebar_action": {
    "default_panel": "sidepanel/index.html",
    "default_title": "Summarize"
  }
}

Permissions to verify:

  • Remove sidePanel (Chrome-only)
  • Verify debugger permission works in Firefox
  • Verify userScripts in optional_permissions is handled gracefully

Service Worker vs Background Page

Current: Chrome MV3 service worker (background.ts)

Firefox MV3: Also uses service workers (Firefox 109+)

  • Same lifecycle as Chrome
  • Same event-driven model
  • SSE connection handling should work identically

Testing priorities:

  1. Verify service worker restarts properly
  2. Test SSE streaming during worker lifecycle
  3. Verify port-based communication (sidepanel ↔ background)

Content Script Timing

Current injection strategy:

  • extract.content.ts: Readability-based extraction
  • hover.content.ts: Hover summaries
  • automation.content.ts: Automation features

Firefox compatibility: ✅ Should work identically

  • WXT handles content script registration
  • Same run_at timing behavior
  • Same message passing APIs

SSE/EventSource Support

Usage: Streaming summaries from daemon via SSE (src/lib/sse.ts)

Testing needed:

  • Verify EventSource works in Firefox background context
  • Test reconnection logic on Firefox
  • Verify CORS headers work with Firefox origin

Known Behavioral Differences

1. Sidebar vs Side Panel UX

Chrome Side Panel:

  • Slides in from the right
  • Programmatically opened via sidePanel.setPanelBehavior()
  • Toggles on toolbar icon click

Firefox Sidebar:

  • Always visible in sidebar area (left side by default)
  • Programmatically controlled via sidebarAction.toggle(), open(), close()
  • Toggles on toolbar icon click (implemented)
  • Keyboard shortcut: Ctrl+Shift+U (customizable by user)
  • Different width constraints than Chrome

Impact: Minimal - both browsers now support programmatic control and icon-click toggling

2. Extension Context URLs

Chrome: chrome-extension://<id>/... Firefox: moz-extension://<id>/...

Impact: Minimal - WXT handles this via runtime.getURL()

3. Developer Tools Integration

Chrome: DevTools open via chrome://extensions Firefox: DevTools open via about:debugging

Impact: Documentation only

Testing Strategy

Browser Compatibility Tags

Add tags to Playwright tests:

// @cross-browser - Runs on both Chrome and Firefox
test('@cross-browser should generate pairing token', ...)

// @firefox - Firefox-specific tests
test('@firefox should use sidebar API', ...)

// @chrome - Chrome-specific tests
test('@chrome should use Side Panel API', ...)

Test Execution

# All tests (both browsers)
pnpm test

# Firefox only
pnpm test:firefox

# Chrome only
pnpm test:chrome

Critical Test Scenarios

  1. Pairing flow: Token generation and daemon connection
  2. Summary streaming: SSE stream rendering in sidebar
  3. Content extraction: Readability on various sites
  4. Auto-summarize: Navigation triggers
  5. Settings persistence: storage.local across restarts
  6. Permissions: Debugger and userScripts optional permissions

Development Workflow

Building for Firefox

# Development mode (watch)
pnpm dev:firefox

# Production build
pnpm build:firefox

# Output location
.output/firefox-mv3/

Loading in Firefox

  1. Open about:debugging#/runtime/this-firefox
  2. Click "Load Temporary Add-on"
  3. Select apps/chrome-extension/.output/firefox-mv3/manifest.json

Note: Temporary add-ons are removed on browser restart

Debugging

Console logs:

  • Background script: about:debugging → This Firefox → Inspect
  • Content scripts: Regular DevTools Console (per-page)
  • Sidebar: Right-click sidebar → Inspect

Common issues:

  • "Error: Extension is invalid": Check manifest syntax
  • "Loading failed": Check console for missing permissions
  • Sidebar not rendering: Verify sidebar_action in manifest

Distribution

Temporary Installation (Current)

  • Use about:debugging → Load Temporary Add-on
  • Extension removed on Firefox restart
  • Suitable for development and early beta testing

Future: AMO (Add-ons.mozilla.org)

When ready for public distribution:

  1. Submit to AMO for review
  2. Code signing required (automatic via AMO)
  3. Update mechanism via AMO (similar to Chrome Web Store)

Implementation Checklist

  • Investigate Chrome API usage
  • Document Chrome-specific APIs
  • Create WXT Firefox target configuration
  • Add sidebar_action manifest override
  • Implement toolbar icon click handler with sidebarAction.toggle()
  • Add keyboard shortcut support (Ctrl+Shift+U)
  • Handle userScripts gracefully if unavailable (checks availability, shows guidance)
  • Add browser compatibility test tags
  • Configure Playwright for Firefox
  • Run full test suite on Firefox build
  • Verify Firefox build succeeds (.output/firefox-mv3/)
  • Verify manifest permissions are correct
  • Update user-facing documentation (README.md installation guide)
  • Manual testing in Firefox Developer Edition
  • Test sidebar rendering in Firefox
  • Verify SSE streaming works
  • Test debugger API for automation features

References

Open Questions

  1. UserScripts API: Automation features require userScripts - graceful degradation implemented with user guidance
  2. Sidebar width: May need CSS adjustments for Firefox sidebar dimensions (requires manual testing)
  3. Testing coverage: Aiming for 100% feature parity where browser APIs allow
  4. Distribution timeline: When to submit to AMO?
  5. Keyboard shortcut conflicts: Does Ctrl+Shift+U conflict with common Firefox shortcuts?

Last updated: 2026-01-02 Status: ✅ Implementation complete - Ready for manual testing in Firefox

Recent Changes (2026-01-02)

Sidebar Control Implementation

Firefox DOES support programmatic sidebar control via the sidebarAction API! The implementation includes:

  • Toolbar Icon Click (background.ts:1589-1599):

    • Detects Firefox builds using import.meta.env.BROWSER === 'firefox'
    • Adds action.onClicked listener that calls browser.sidebarAction.toggle()
    • Toggles sidebar visibility just like Chrome's side panel behavior

  • Keyboard Shortcut (wxt.config.ts:105-115):

    • Added _execute_sidebar_action command to manifest
    • Default: Ctrl+Shift+U (Windows/Linux)
    • Mac: Command+Shift+U
    • Users can customize this in Firefox settings: about:addons → Extensions → Manage Extension Shortcuts

  • Manifest Changes (wxt.config.ts:61):

    • Firefox builds use standard WebExtensions permissions (no special permissions needed)
    • Chrome builds continue to use sidePanel permission

User Experience:

  1. Click toolbar icon: Toggles sidebar open/close
  2. Keyboard shortcut: Ctrl+Shift+U (or Cmd+Shift+U on Mac) toggles sidebar
  3. Customizable: Users can change the shortcut in Firefox's extension settings