trilium/apps/web-clipper/MANIFEST_V3_CONVERSION.md

Trilium Web Clipper - Manifest V3 Conversion Summary

✅ Completed Conversion Tasks

1. Manifest.json Updates

• ✅ Updated manifest_version from 2 to 3
• ✅ Converted browser_action to action
• ✅ Updated background.scripts to background.service_worker with ES module support
• ✅ Separated permissions and host_permissions
• ✅ Added scripting permission for dynamic content script injection
• ✅ Updated content_security_policy to V3 format
• ✅ Added web_accessible_resources with proper structure
• ✅ Removed static content_scripts (now using dynamic injection)

2. Background Script Conversion

• ✅ Converted from background.js to ES module service worker
• ✅ Replaced all browser.* API calls with chrome.*
• ✅ Converted browser.browserAction to chrome.action
• ✅ Updated browser.tabs.executeScript to chrome.scripting.executeScript
• ✅ Added dynamic content script injection with error handling
• ✅ Updated message listener to return true for async responses
• ✅ Converted utility and facade imports to ES modules

3. Utils.js ES Module Conversion

• ✅ Added export statements for all functions
• ✅ Maintained backward compatibility

4. Trilium Server Facade Conversion

• ✅ Replaced all browser.* calls with chrome.*
• ✅ Added proper ES module exports
• ✅ Updated storage and runtime message APIs

5. Content Script Updates

• ✅ Replaced all browser.* calls with chrome.*
• ✅ Added inline utility functions to avoid module dependency issues
• ✅ Maintained compatibility with dynamic library loading

6. Popup and Options Scripts

• ✅ Updated all browser.* API calls to chrome.*
• ✅ Updated storage, runtime, and other extension APIs

🔧 Key Technical Changes

Dynamic Content Script Injection

Instead of static registration, content scripts are now injected on-demand:

await chrome.scripting.executeScript({
    target: { tabId: activeTab.id },
    files: ['content.js']
});

ES Module Service Worker

Background script now uses ES modules:

import { randomString } from './utils.js';
import { triliumServerFacade } from './trilium_server_facade.js';

Chrome APIs Everywhere

All browser.* calls replaced with chrome.*:

• browser.tabs → chrome.tabs
• browser.storage → chrome.storage
• browser.runtime → chrome.runtime
• browser.contextMenus → chrome.contextMenus

Host Permissions Separation

{
  "permissions": ["activeTab", "tabs", "storage", "contextMenus", "scripting"],
  "host_permissions": ["http://*/", "https://*/"]
}

🧪 Testing Checklist

Basic Functionality

• Extension loads without errors
• Popup opens and displays correctly
• Options page opens and functions
• Context menus appear on right-click

Core Features

• Save selection to Trilium
• Save whole page to Trilium
• Save screenshots to Trilium
• Save images to Trilium
• Save links to Trilium
• Keyboard shortcuts work

Integration

• Trilium Desktop connection works
• Trilium Server connection works
• Toast notifications appear
• Note opening in Trilium works

📝 Migration Notes

Files Changed

• manifest.json - Complete V3 conversion
• background.js - New ES module service worker
• utils.js - ES module exports added
• trilium_server_facade.js - Chrome APIs + ES exports
• content.js - Chrome APIs + inline utilities
• popup/popup.js - Chrome APIs
• options/options.js - Chrome APIs

Files Preserved

• background-v2.js - Original V2 background (backup)
• All library files in /lib/ unchanged
• All UI files (HTML/CSS) unchanged
• Icons and other assets unchanged

Breaking Changes

• Browser polyfill no longer needed for Chrome extension
• Content scripts loaded dynamically (better for performance)
• Service worker lifecycle different from persistent background

🚀 Next Steps

1. Load extension in Chrome developer mode
2. Test all core functionality
3. Verify Trilium Desktop/Server integration
4. Test keyboard shortcuts
5. Verify error handling and edge cases