refactor: migrate storage listeners to wxt/browser and refactor provider state management

providers/ThemeModeProvider.tsx

@@ -7,6 +7,7 @@ import {
   useMemo,
   useState,
 } from 'react';
+import { browser } from 'wxt/browser'; // 💡 1. 规范回归：引入 WXT 标准多端一致性代理，消灭裸奔的 chrome 空间
 import { storageUtil } from '@/utils/chromeStorage';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
@@ -26,6 +27,9 @@ const SNAPSHOT_KEY = 'snapshot/app/themeMode';
 const VALID_MODES: ThemeMode[] = ['light', 'dark', 'system'];
 const isValidMode = (v: unknown): v is ThemeMode => VALID_MODES.includes(v as ThemeMode);
 
+/**
+ * 同步追溯 localStorage 级快照（首屏 0 闪烁核心防线）
+ */
 const getSyncSnapshot = (): ThemeMode => {
   try {
     const raw = localStorage.getItem(SNAPSHOT_KEY);
@@ -37,6 +41,9 @@ const getSyncSnapshot = (): ThemeMode => {
   }
 };
 
+/**
+ * 实时嗅探系统底层操作系统的明暗色轴
+ */
 const getSystemMode = (): ResolvedThemeMode => {
   if (typeof window === 'undefined') return 'light';
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
@@ -52,20 +59,32 @@ export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
     mode === 'system' ? getSystemMode() : mode,
   );
 
+  // 统一的实态转换调度中枢
   const updateResolved = useCallback((nextMode: ThemeMode) => {
     setResolvedMode(nextMode === 'system' ? getSystemMode() : nextMode);
   }, []);
 
+  // 主动切流触发大闸
   const setMode = useCallback(
     (next: ThemeMode) => {
       setModeState(next);
       updateResolved(next);
-      storageUtil.set(THEME_MODE_KEY, next).catch(console.error);
-      localStorage.setItem(SNAPSHOT_KEY, JSON.stringify(next));
+
+      // 💡 修复点：对异步微任务链追加标准的显式 void 断链安全隔离，彻底净化 Linter 悬空 Promise 警告
+      void storageUtil.set(THEME_MODE_KEY, next).catch((err) => {
+        console.error('[Theme Storage Error] Failed to persistent theme state:', err);
+      });
+
+      try {
+        localStorage.setItem(SNAPSHOT_KEY, JSON.stringify(next));
+      } catch (err) {
+        console.error('[Theme Snapshot Error] LocalStorage quota exceeded:', err);
+      }
     },
     [updateResolved],
   );
 
+  // 副作用 1：冷启动时异步对齐来自长期存储的权威配置，自愈快照偏差
   useEffect(() => {
     let cancelled = false;
     storageUtil
@@ -77,12 +96,15 @@ export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
           updateResolved(saved);
         }
       })
-      .catch(console.error);
+      .catch((err) => {
+        console.error('[Theme Restore Thread Failed]', err);
+      });
     return () => {
       cancelled = true;
     };
   }, [updateResolved]);
 
+  // 副作用 2：当处于跟随系统模式下，动态监听操作系统级别的高级霓虹换色
   useEffect(() => {
     if (mode !== 'system') return;
     const mq = window.matchMedia('(prefers-color-scheme: dark)');
@@ -93,22 +115,37 @@ export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
     return () => mq.removeEventListener('change', handler);
   }, [mode]);
 
+  // 副作用 3：跨上下文广播事件同步大闸（Popup <-> Sidepanel 联动核心）
   useEffect(() => {
-    const handleStorageChange = (changes: { [key: string]: chrome.storage.StorageChange }) => {
+    // 💡 2. 强类型对齐修复：对齐标准的 browser.storage.onChanged.addListener 签名规范
+    const handleStorageChange = (changes: Record<string, { newValue?: unknown }>) => {
       if (changes[THEME_MODE_KEY]) {
-        const next = changes[THEME_MODE_KEY].newValue as unknown;
-        if (isValidMode(next) && next !== mode) {
-          setModeState(next);
-          updateResolved(next);
+        const next = changes[THEME_MODE_KEY].newValue;
+        if (isValidMode(next)) {
+          // 💡 3. 架构解耦：改用函数式状态更新，彻底将本 Effect 从当前的 [mode] 依赖中解脱出来！
+          // 这能保证多视口监听器在初始化时【只注册一次】，彻底消灭高频切流时的事件撕裂与重复注销。
+          setModeState((currentMode) => {
+            if (next !== currentMode) {
+              updateResolved(next);
+              return next;
+            }
+            return currentMode;
+          });
         }
       }
     };
-    chrome.storage.onChanged.addListener(handleStorageChange);
-    return () => chrome.storage.onChanged.removeListener(handleStorageChange);
-  }, [mode, updateResolved]);
 
+    browser.storage.onChanged.addListener(handleStorageChange);
+    return () => {
+      browser.storage.onChanged.removeListener(handleStorageChange);
+    };
+  }, [updateResolved]); // 👈 完美剔除 mode 脏依赖！
+
+  // 副作用 4：宿主 DOM 的 class 样式原子映射注入（一帧直出）
   useEffect(() => {
-    document.documentElement.classList.toggle('dark', resolvedMode === 'dark');
+    if (typeof document !== 'undefined') {
+      document.documentElement.classList.toggle('dark', resolvedMode === 'dark');
+    }
   }, [resolvedMode]);
 
   const contextValue = useMemo(
@@ -122,7 +159,9 @@ export function ThemeModeProvider({ children }: ThemeModeProviderProps) {
 export function useThemeMode(): ThemeModeContextType {
   const ctx = useContext(ThemeModeContext);
   if (!ctx) {
-    throw new Error('useThemeMode must be used within a ThemeModeProvider');
+    throw new Error(
+      'useThemeMode must be used within a valid ThemeModeProvider sandboxed container',
+    );
   }
   return ctx;
 }