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

providers/RouterProvider.tsx

@@ -7,14 +7,15 @@ import {
   useRef,
   useState,
 } from 'react';
-import type { PageType, StorageSchema, ContextMenuPendingData } from '@/types/storage';
+import { browser } from 'wxt/browser'; // 💡 1. 规范回归：引入 WXT 标准多端一致性代理空间
+import type { ContextMenuPendingData, PageType, StorageSchema } from '@/types/storage';
 import { storageUtil } from '@/utils/chromeStorage';
 import {
   getAllFeatureKeys,
   getDefaultPageOrder,
   getDefaultVisibleFeatureKeys,
 } from '@/config/features';
-import { saveContextMenuData, CONTEXT_MENU_DATA_EXPIRY_MS } from '@/utils/useContextMenuData';
+import { CONTEXT_MENU_DATA_EXPIRY_MS, saveContextMenuData } from '@/utils/useContextMenuData';
 
 /**
  * 校验是否为合法的页面类型
@@ -24,7 +25,7 @@ const isValidPage = (page: unknown): page is PageType => {
 };
 
 /**
- * 校验页面列表是否合法（所有项都必须是合法的 PageType）
+ * 校验页面列表是否合法
  */
 const isValidPageList = (pages: unknown): pages is PageType[] => {
   return Array.isArray(pages) && pages.every(isValidPage);
@@ -32,72 +33,41 @@ const isValidPageList = (pages: unknown): pages is PageType[] => {
 
 /**
  * 将已保存的列表与默认列表合并，确保新增的功能特性被自动包含
- *
- * 合并策略：
- * - 保留用户已有的自定义顺序
- * - 过滤掉已不再存在的旧项
- * - 将默认列表中存在但保存列表中缺失的新项追加到末尾
  */
 const mergeWithDefaults = (saved: PageType[], defaults: PageType[]): PageType[] => {
   const savedSet = new Set(saved);
   const defaultSet = new Set(defaults);
 
-  // 保留 saved 中仍然合法的项（按用户自定义顺序）
   const preserved = saved.filter((page) => defaultSet.has(page));
-
-  // 追加 defaults 中有但 saved 中没有的新功能
   const newItems = defaults.filter((page) => !savedSet.has(page));
 
   return [...preserved, ...newItems];
 };
 
-/**
- * 路由上下文类型定义
- */
 interface RouterContextType {
-  /** 当前所在页面 */
   currentPage: PageType;
-  /** 当前可见的页面列表（用于侧边栏/菜单显示） */
   visiblePages: PageType[];
-  /** 页面显示顺序 */
   pageOrder: PageType[];
-  /** 路由数据是否已从存储中加载完成 */
   isLoaded: boolean;
-  /** 导航到指定页面 */
   navigateTo: (page: PageType) => void;
-  /** 返回仪表盘 */
   goBack: () => void;
-  /** 设置可见页面列表 */
   setVisiblePages: (pages: PageType[]) => void;
-  /** 设置页面显示顺序 */
   setPageOrder: (pages: PageType[]) => void;
 }
 
-/**
- * 创建路由上下文
- */
 const RouterContext = createContext<RouterContextType | null>(null);
 
-/**
- * 路由提供者组件参数类型
- */
 interface RouterProviderProps {
-  /** 子组件 */
   children: ReactNode;
-  /** 默认初始路由，默认为 'dashboard' */
   defaultRoute?: PageType;
-  /** 是否同步路由状态到存储，默认为 true */
   syncRoute?: boolean;
-  /** 存储路由状态的键名，默认为 'app/currentRoute' */
   syncKey?: keyof StorageSchema;
-  /** 可见页面列表的键名，默认为 'app/visiblePages' */
   visiblePagesKey?: keyof StorageSchema;
-  /** 页面排序的键名，默认为 'app/pageOrder' */
   pageOrderKey?: keyof StorageSchema;
 }
 
 /**
- * 同步从 localStorage 获取存储快照（用于消除异步加载产生的首屏闪烁）
+ * 同步从 localStorage 获取存储快照（首屏 0 闪烁核心防线）
  */
 const getSyncSnapshot = <T,>(
   key: string,
@@ -113,15 +83,11 @@ const getSyncSnapshot = <T,>(
     }
     return (parsed as T) ?? defaultValue;
   } catch (error) {
-    console.error('解析同步快照失败:', error);
+    console.error('[Router Snapshot Error] Failed to read sync cache:', error);
     return defaultValue;
   }
 };
 
-/**
- * 路由提供者组件
- * 负责管理应用内部的路由状态、页面可见性及排序，并支持与 Chrome Storage 同步
- */
 export function RouterProvider({
   children,
   defaultRoute = 'dashboard',
@@ -130,11 +96,11 @@ export function RouterProvider({
   visiblePagesKey = 'app/visiblePages',
   pageOrderKey = 'app/pageOrder',
 }: RouterProviderProps) {
-  // 当前页面状态：优先从同步快照加载，并进行合法性校验
+  // 1. 初始化派生状态流（0 延迟快照同步）
   const [currentPage, setCurrentPage] = useState<PageType>(() =>
     getSyncSnapshot(syncKey as string, defaultRoute, isValidPage),
   );
-  // 可见页面列表状态：从快照加载后与默认值合并，确保新功能可见
+
   const [visiblePages, setVisiblePages] = useState<PageType[]>(() => {
     const snapshot = getSyncSnapshot(
       visiblePagesKey as string,
@@ -143,7 +109,7 @@ export function RouterProvider({
     );
     return mergeWithDefaults(snapshot, getDefaultVisibleFeatureKeys());
   });
-  // 页面排序状态：从快照加载后与默认值合并，确保新功能出现在排序中
+
   const [pageOrder, setPageOrder] = useState<PageType[]>(() => {
     const snapshot = getSyncSnapshot(
       pageOrderKey as string,
@@ -152,16 +118,16 @@ export function RouterProvider({
     );
     return mergeWithDefaults(snapshot, getDefaultPageOrder());
   });
-  // 加载完成标识：如果快照数据有效，直接标记为已加载，避免首屏骨架屏
+
   const [isLoaded, setIsLoaded] = useState(() => {
     const snapshotKey = localStorage.getItem(`snapshot/${syncKey as string}`);
     const snapshotVisible = localStorage.getItem(`snapshot/${visiblePagesKey as string}`);
     const snapshotOrder = localStorage.getItem(`snapshot/${pageOrderKey as string}`);
-    // 快照数据存在且通过校验，说明之前已加载过，可跳过骨架屏
     return !!(snapshotKey && snapshotVisible && snapshotOrder);
   });
+
   /**
-   * 从存储中加载初始路由数据
+   * 从异步存储中安全溯源初始数据
    */
   const loadInitialData = useCallback(async () => {
     try {
@@ -172,7 +138,6 @@ export function RouterProvider({
       );
       const savedPageOrder = await storageUtil.get(pageOrderKey, getDefaultPageOrder());
 
-      // 增加数据合法性校验并进行类型收窄
       if (isValidPage(savedRoute) && syncRoute) {
         setCurrentPage(savedRoute);
       }
@@ -183,118 +148,120 @@ export function RouterProvider({
         setPageOrder(mergeWithDefaults(savedPageOrder, getDefaultPageOrder()));
       }
     } catch (error) {
-      console.error('加载初始路由数据失败:', error);
+      console.error('[Router Init Error] Core data fetch failed:', error);
     }
   }, [defaultRoute, syncKey, syncRoute, visiblePagesKey, pageOrderKey]);
 
-  // 组件挂载时加载初始数据
+  // 副作用 1：组件挂载时，激活初始路由校验与右键菜单传递载荷（Context Payload）的嗅探
   useEffect(() => {
     let cancelled = false;
+
     loadInitialData()
       .then(() => {
-        if (!cancelled) {
-          setIsLoaded(true);
+        if (cancelled) return;
+        setIsLoaded(true);
 
-          // 检查 URL 参数中的右键菜单数据
-          if (typeof window !== 'undefined') {
-            const params = new URLSearchParams(window.location.search);
-            const feature = params.get('feature') as PageType | null;
-            const payload = params.get('payload');
+        // 检查 URL 参数中的右键菜单高阶中转数据
+        if (typeof window !== 'undefined') {
+          const params = new URLSearchParams(window.location.search);
+          const feature = params.get('feature') as PageType | null;
+          const payload = params.get('payload');
 
-            if (feature && payload && isValidPage(feature)) {
-              saveContextMenuData({ featureKey: feature, payload }).catch(console.error);
-              navigateTo(feature);
+          if (feature && payload && isValidPage(feature)) {
+            void saveContextMenuData({ featureKey: feature, payload }).catch((err) => {
+              console.error('[Router Context Handler Error]', err);
+            });
+            setCurrentPage(feature);
 
-              // 清理 URL 参数
-              const url = new URL(window.location.href);
-              url.searchParams.delete('feature');
-              url.searchParams.delete('payload');
-              window.history.replaceState({}, '', url.toString());
-              return;
-            }
+            const url = new URL(window.location.href);
+            url.searchParams.delete('feature');
+            url.searchParams.delete('payload');
+            window.history.replaceState({}, '', url.toString());
+            return;
           }
-
-          // 检查 storage 中的右键菜单待处理数据（用于 openPopup 场景）
-          storageUtil
-            .get('contextMenu/pendingData', undefined)
-            .then((pendingData) => {
-              if (
-                pendingData &&
-                isValidPage(pendingData.featureKey) &&
-                Date.now() - pendingData.timestamp < CONTEXT_MENU_DATA_EXPIRY_MS
-              ) {
-                navigateTo(pendingData.featureKey as PageType);
-                // 不在这里清除数据，让目标页面的 useContextMenuData 来消费和清除
-              }
-            })
-            .catch(console.error);
         }
+
+        // 检查 storage 中的右键菜单待处理数据（针对 openPopup 的闭环场景）
+        storageUtil
+          .get('contextMenu/pendingData', undefined)
+          .then((pendingData) => {
+            if (
+              pendingData &&
+              isValidPage(pendingData.featureKey) &&
+              Date.now() - pendingData.timestamp < CONTEXT_MENU_DATA_EXPIRY_MS
+            ) {
+              setCurrentPage(pendingData.featureKey as PageType);
+            }
+          })
+          .catch(console.error);
       })
       .catch(console.error);
+
     return () => {
       cancelled = true;
     };
   }, [loadInitialData]);
 
-  // 当 currentPage 改变时，如果开启了同步，则持久化到存储和本地快照
   useEffect(() => {
     if (isLoaded && syncRoute) {
-      storageUtil.set(syncKey, currentPage as PageType).catch(console.error);
-      localStorage.setItem(`snapshot/${syncKey}`, JSON.stringify(currentPage));
+      void storageUtil.set(syncKey, currentPage as PageType).catch(console.error);
+      try {
+        localStorage.setItem(`snapshot/${syncKey}`, JSON.stringify(currentPage));
+      } catch (err) {
+        console.error('[Router LocalStorage Error]', err);
+      }
     }
   }, [currentPage, isLoaded, syncRoute, syncKey]);
 
-  // 持久化可见页面列表
   useEffect(() => {
     if (isLoaded) {
-      storageUtil.set(visiblePagesKey, visiblePages).catch(console.error);
-      localStorage.setItem(`snapshot/${visiblePagesKey}`, JSON.stringify(visiblePages));
+      void storageUtil.set(visiblePagesKey, visiblePages).catch(console.error);
+      try {
+        localStorage.setItem(`snapshot/${visiblePagesKey}`, JSON.stringify(visiblePages));
+      } catch (err) {
+        console.error('[Router LocalStorage Error]', err);
+      }
     }
   }, [visiblePages, isLoaded, visiblePagesKey]);
 
-  // 持久化页面排序
   useEffect(() => {
     if (isLoaded) {
-      storageUtil.set(pageOrderKey, pageOrder).catch(console.error);
-      localStorage.setItem(`snapshot/${pageOrderKey}`, JSON.stringify(pageOrder));
+      void storageUtil.set(pageOrderKey, pageOrder).catch(console.error);
+      try {
+        localStorage.setItem(`snapshot/${pageOrderKey}`, JSON.stringify(pageOrder));
+      } catch (err) {
+        console.error('[Router LocalStorage Error]', err);
+      }
     }
   }, [pageOrder, isLoaded, pageOrderKey]);
 
-  // 用 ref 持有最新 currentPage，避免每次路由跳转都重注册 chrome.storage 监听器
   const currentPageRef = useRef(currentPage);
   useEffect(() => {
     currentPageRef.current = currentPage;
   }, [currentPage]);
 
-  /**
-   * 监听存储变化，以便在多个入口（如 Popup 和 Options）之间同步路由和设置
-   */
   useEffect(() => {
     if (!syncRoute) return;
 
-    const handleStorageChange = (changes: { [key: string]: chrome.storage.StorageChange }) => {
-      // 同步当前路由
+    const handleStorageChange = (changes: Record<string, { newValue?: unknown }>) => {
       if (syncRoute && changes[syncKey as string]) {
         const newRoute = changes[syncKey as string].newValue as PageType;
         if (newRoute && newRoute !== currentPageRef.current && isValidPage(newRoute)) {
           setCurrentPage(newRoute);
         }
       }
-      // 同步可见页面列表
       if (changes[visiblePagesKey as string]) {
         const newPages = changes[visiblePagesKey as string].newValue;
         if (isValidPageList(newPages)) {
           setVisiblePages(newPages);
         }
       }
-      // 同步页面排序
       if (changes[pageOrderKey as string]) {
         const newOrder = changes[pageOrderKey as string].newValue;
         if (isValidPageList(newOrder)) {
           setPageOrder(newOrder);
         }
       }
-      // 监听右键菜单数据变化，自动跳转到对应页面（用于 popup 已打开的场景）
       if (changes['contextMenu/pendingData']) {
         const newData = changes['contextMenu/pendingData']
           .newValue as ContextMenuPendingData | null;
@@ -308,20 +275,17 @@ export function RouterProvider({
       }
     };
 
-    chrome.storage.onChanged.addListener(handleStorageChange);
-    return () => chrome.storage.onChanged.removeListener(handleStorageChange);
+    // 💡 修复点：全域绑定 WXT 跨浏览器代理监听器，彻底闭环多端多进程广播
+    browser.storage.onChanged.addListener(handleStorageChange);
+    return () => {
+      browser.storage.onChanged.removeListener(handleStorageChange);
+    };
   }, [syncRoute, syncKey, visiblePagesKey, pageOrderKey]);
 
-  /**
-   * 跳转到指定页面
-   */
   const navigateTo = (page: PageType) => {
     setCurrentPage(page);
   };
 
-  /**
-   * 返回主仪表盘
-   */
   const goBack = () => {
     setCurrentPage('dashboard');
   };
@@ -344,14 +308,10 @@ export function RouterProvider({
   );
 }
 
-/**
- * 自定义 Hook：获取路由上下文
- * @throws {Error} 如果在 RouterProvider 之外使用则抛出异常
- */
 export function useRouter() {
   const context = useContext(RouterContext);
   if (!context) {
-    throw new Error('useRouter must be used within a RouterProvider');
+    throw new Error('useRouter must be used within a valid RouterProvider context wrapper');
   }
   return context;
 }