Fix dark mode toolbar icon not displaying correctly on Safari launch

Problem:
The toolbar icon defaulted to light mode on fresh Safari launch because
background scripts don't have access to window.matchMedia for detecting
the system color scheme. The cachedIsDark variable was initialized to
false and only updated when the popup was opened.

Solution:
Use native messaging to query the macOS container app for the system
appearance on extension startup. The Swift SafariWebExtensionHandler
uses NSApp.effectiveAppearance to reliably detect dark mode and returns
it to the background script.

Additionally, the content script now detects and reports the color
scheme on every page load and listens for appearance changes, providing
live updates when the user toggles dark/light mode.

Detection now happens through multiple mechanisms:
1. On startup: Native messaging queries Swift for NSApp.effectiveAppearance
2. On page load: Content script sends prefers-color-scheme state
3. On appearance change: Content script listener fires
4. On popup open: Popup reports color scheme (fallback)

Changes:
- Add nativeMessaging permission to manifest.json
- Add getAppearance handler to SafariWebExtensionHandler.swift
- Add initializeAppearance() in background.js to query native app
- Add color scheme detection to content.js
- Add debug logging throughout for troubleshooting
- Remove dark mode issue from KNOWN_ISSUES.md (now resolved)

Author: bartTC

CF Cache Status/CF Cache Status Extension/Resources/background.js

@@ -36,13 +36,41 @@ const ICONS = {
   }
 };
 
-/** Cached color scheme (updated by popup which has DOM access) */
+/** Cached color scheme (updated by native app or popup) */
 let cachedIsDark = false;
 
 function isDarkMode() {
   return cachedIsDark;
 }
 
+// Request appearance from native app on startup
+async function initializeAppearance() {
+  console.log('[CF Cache Status] initializeAppearance() called');
+  try {
+    console.log('[CF Cache Status] Sending native message to com.cfcachestatus.CF-Cache-Status');
+    const response = await browser.runtime.sendNativeMessage(
+      'com.cfcachestatus.CF-Cache-Status',
+      { type: 'getAppearance' }
+    );
+    console.log('[CF Cache Status] Native message response:', JSON.stringify(response));
+    if (response && typeof response.isDark === 'boolean') {
+      cachedIsDark = response.isDark;
+      console.log('[CF Cache Status] Set cachedIsDark to:', cachedIsDark);
+      const icon = getDefaultIcon();
+      console.log('[CF Cache Status] Setting icon to:', JSON.stringify(icon));
+      browser.action.setIcon({ path: icon });
+    } else {
+      console.log('[CF Cache Status] Invalid response format, isDark not found');
+    }
+  } catch (e) {
+    console.error('[CF Cache Status] Native messaging error:', e.message || e);
+  }
+}
+
+// Initialize appearance on extension load
+console.log('[CF Cache Status] Background script loaded at', new Date().toISOString());
+initializeAppearance();
+
 function getDefaultIcon() {
   return isDarkMode() ? ICONS.dark : ICONS.light;
 }
@@ -85,6 +113,7 @@ function updateBadge(tabId, status) {
 
   // Reset to default icon (respects dark/light mode)
   const icon = getDefaultIcon();
+  console.log('[CF Cache Status] updateBadge called, tabId:', tabId, 'status:', status, 'cachedIsDark:', cachedIsDark, 'icon:', icon['16']);
   browser.action.setIcon({ path: icon });
   browser.action.setBadgeText({ text: badgeText });
   browser.action.setBadgeBackgroundColor({ color });
@@ -276,10 +305,15 @@ browser.tabs.onActivated.addListener((activeInfo) => {
 // --- Window Events ---
 
 browser.windows.onFocusChanged.addListener(async (windowId) => {
-  if (windowId === browser.windows.WINDOW_ID_NONE) return;
+  console.log('[CF Cache Status] onFocusChanged, windowId:', windowId, 'cachedIsDark:', cachedIsDark);
+  if (windowId === browser.windows.WINDOW_ID_NONE) {
+    console.log('[CF Cache Status] Window lost focus (WINDOW_ID_NONE), ignoring');
+    return;
+  }
 
   try {
     const tabs = await browser.tabs.query({ active: true, windowId });
+    console.log('[CF Cache Status] Active tab:', tabs?.[0]?.id, 'hasData:', tabData.has(tabs?.[0]?.id));
     if (tabs?.[0]) {
       const data = tabData.get(tabs[0].id);
       if (data) {
@@ -293,7 +327,7 @@ browser.windows.onFocusChanged.addListener(async (windowId) => {
       }
     }
   } catch (e) {
-    // Ignore errors during window switching
+    console.error('[CF Cache Status] onFocusChanged error:', e);
   }
 });
 
@@ -305,9 +339,12 @@ browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
   }
 
   if (message.type === 'colorScheme') {
+    console.log('[CF Cache Status] Received colorScheme message, isDark:', message.isDark, 'from:', sender.tab?.url || sender.url || 'popup');
     const changed = cachedIsDark !== message.isDark;
     cachedIsDark = message.isDark;
+    console.log('[CF Cache Status] cachedIsDark updated to:', cachedIsDark, 'changed:', changed);
     if (changed) {
+      console.log('[CF Cache Status] Updating all tab icons');
       updateAllTabIcons();
     }
   }

CF Cache Status/CF Cache Status Extension/Resources/manifest.json

@@ -32,7 +32,8 @@
     "webRequest",
     "webNavigation",
     "activeTab",
-    "storage"
+    "storage",
+    "nativeMessaging"
   ],
   "host_permissions": [
     "<all_urls>"

CF Cache Status/CF Cache Status Extension/SafariWebExtensionHandler.swift

@@ -7,6 +7,11 @@
 
 import SafariServices
 import os.log
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
 
 class SafariWebExtensionHandler: NSObject, NSExtensionRequestHandling {
 
@@ -29,14 +34,39 @@ class SafariWebExtensionHandler: NSObject, NSExtensionRequestHandling {
 
         os_log(.default, "Received message from browser.runtime.sendNativeMessage: %@ (profile: %@)", String(describing: message), profile?.uuidString ?? "none")
 
+        // Handle appearance request
+        var responseData: [String: Any] = [:]
+
+        if let msg = message as? [String: Any], let type = msg["type"] as? String {
+            if type == "getAppearance" {
+                let isDark = Self.isDarkMode()
+                responseData = ["isDark": isDark]
+                os_log(.default, "Returning appearance: isDark = %{public}@", isDark ? "true" : "false")
+            } else {
+                responseData = ["echo": message as Any]
+            }
+        } else {
+            responseData = ["echo": message as Any]
+        }
+
         let response = NSExtensionItem()
         if #available(iOS 15.0, macOS 11.0, *) {
-            response.userInfo = [ SFExtensionMessageKey: [ "echo": message ] ]
+            response.userInfo = [SFExtensionMessageKey: responseData]
         } else {
-            response.userInfo = [ "message": [ "echo": message ] ]
+            response.userInfo = ["message": responseData]
         }
 
-        context.completeRequest(returningItems: [ response ], completionHandler: nil)
+        context.completeRequest(returningItems: [response], completionHandler: nil)
+    }
+
+    /// Detect current system appearance (dark or light mode)
+    private static func isDarkMode() -> Bool {
+        #if os(macOS)
+        let appearance = NSApp?.effectiveAppearance ?? NSAppearance.currentDrawing()
+        return appearance.bestMatch(from: [.darkAqua, .aqua]) == .darkAqua
+        #else
+        return UITraitCollection.current.userInterfaceStyle == .dark
+        #endif
     }
 
 }

CF Cache Status/CF Cache Status Extension/content.js

@@ -74,3 +74,32 @@ if (document.readyState === 'complete') {
     setTimeout(sendMetrics, 100);
   });
 }
+
+// =============================================================================
+// Color Scheme Detection
+// =============================================================================
+
+/**
+ * Sends the current color scheme to the background script.
+ * Content scripts have DOM access, so they can detect system appearance.
+ */
+function sendColorScheme() {
+  const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+  console.log('[CF Cache Status] Content script sending colorScheme, isDark:', isDark);
+  browser.runtime.sendMessage({
+    type: 'colorScheme',
+    isDark: isDark
+  }).catch((e) => {
+    console.log('[CF Cache Status] Content script colorScheme error:', e.message || e);
+  });
+}
+
+// Send color scheme on page load
+console.log('[CF Cache Status] Content script loaded');
+sendColorScheme();
+
+// Listen for color scheme changes (user toggles dark/light mode)
+window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+  console.log('[CF Cache Status] Color scheme changed event, isDark:', e.matches);
+  sendColorScheme();
+});

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Fixed
+- Dark mode toolbar icon now displays correctly on Safari launch (previously defaulted to light icon until popup was opened)
+
+### Added
+- Native messaging to detect system appearance on extension startup
+- Content script color scheme detection for live dark/light mode switching
+
 ## [v1.0.0] - 2026-01-08
 
 First stable release.

KNOWN_ISSUES.md

@@ -37,16 +37,3 @@ Safari's webRequest API has several known misalignments with Chrome and Firefox:
 ### Reporting to Apple
 
 If you encounter this issue, consider filing a bug report via [Apple Feedback Assistant](https://feedbackassistant.apple.com) to help prioritize a fix.
-
-## Dark Mode Icon Switching
-
-**Issue:** The toolbar icon does not automatically switch between light and dark variants when the system appearance changes.
-
-**Cause:** Safari extension background scripts do not have access to `window.matchMedia`, so the extension cannot detect color scheme changes directly. The color scheme is detected via the popup, which has proper DOM access.
-
-**Workaround:** Click the extension icon once after switching between light and dark mode. The icon will update to the correct variant.
-
-**Technical Details:**
-- Background scripts in Safari run in a limited environment without full DOM access
-- The popup detects the color scheme and sends it to the background script
-- Icons are updated when the popup is opened or when tab data changes