Enhance form recognition, optimize UI, and unify components (#19)

- **docs**: 完善组件注释、README 目录结构及 AGENTS.md 文档。
- **refactor**:
  - 提取通用 `PageHeader`、`Button`、`DashboardCard` 及 `ErrorBoundary` 组件。
  - 重构消息通信机制，采用 `@webext-core/messaging` 实现类型安全。
  - 将全局通知系统重构为 `SnackbarProvider` (后合并至 `GlobalSnackbar`)。
  - 迁移样式系统至 MUI 主题，移除冗余 CSS。
  - 优化路由配置，支持独立标签页模式及页面懒加载。
  - 移除未使用文件、URL 工具及表单映射相关功能。
- **feat**:
  - 新增配置导出功能（JSON）及状态提示。
  - 新增侧边栏状态变化通知机制。
  - 新增文本统计及 JWT 解析工具。
  - 优化二维码生成与解析逻辑，换用更轻量的 `qrious` 和 `qr-scanner`。
  - 增强高亮器功能，支持闪烁效果及 Shadow DOM 穿透。
- **style**: 优化仪表盘响应式网格布局及 UI 细节。
- **fix**: 修复 `useStorageState` 依赖缺失及路由初始化性能问题。
- **test**: 更新单元测试以覆盖新增的工具函数及功能特性。

providers/RouterProvider.tsx

@@ -64,6 +64,10 @@ interface RouterProviderProps {
   syncRoute?: boolean;
   /** 存储路由状态的键名，默认为 'app/currentRoute' */
   syncKey?: keyof StorageSchema;
+  /** 可见页面列表的键名，默认为 'app/visiblePages' */
+  visiblePagesKey?: keyof StorageSchema;
+  /** 页面排序的键名，默认为 'app/pageOrder' */
+  pageOrderKey?: keyof StorageSchema;
 }
 
 /**
@@ -97,6 +101,8 @@ export function RouterProvider({
   defaultRoute = 'dashboard',
   syncRoute = true,
   syncKey = 'app/currentRoute',
+  visiblePagesKey = 'app/visiblePages',
+  pageOrderKey = 'app/pageOrder',
 }: RouterProviderProps) {
   // 当前页面状态：优先从同步快照加载，并进行合法性校验
   const [currentPage, setCurrentPage] = useState<PageType>(() =>
@@ -104,11 +110,11 @@ export function RouterProvider({
   );
   // 可见页面列表状态
   const [visiblePages, setVisiblePages] = useState<PageType[]>(() =>
-    getSyncSnapshot('app/visiblePages', getDefaultVisibleFeatureKeys(), isValidPageList),
+    getSyncSnapshot(visiblePagesKey as string, getDefaultVisibleFeatureKeys(), isValidPageList),
   );
   // 页面排序状态
   const [pageOrder, setPageOrder] = useState<PageType[]>(() =>
-    getSyncSnapshot('app/pageOrder', getDefaultPageOrder(), isValidPageList),
+    getSyncSnapshot(pageOrderKey as string, getDefaultPageOrder(), isValidPageList),
   );
   // 加载完成标识
   const [isLoaded, setIsLoaded] = useState(false);
@@ -119,10 +125,10 @@ export function RouterProvider({
     try {
       const savedRoute = await storageUtil.get(syncKey, defaultRoute);
       const savedVisiblePages = await storageUtil.get(
-        'app/visiblePages',
+        visiblePagesKey,
         getDefaultVisibleFeatureKeys(),
       );
-      const savedPageOrder = await storageUtil.get('app/pageOrder', getDefaultPageOrder());
+      const savedPageOrder = await storageUtil.get(pageOrderKey, getDefaultPageOrder());
 
       // 增加数据合法性校验并进行类型收窄
       if (isValidPage(savedRoute) && syncRoute) {
@@ -139,7 +145,7 @@ export function RouterProvider({
     } finally {
       setIsLoaded(true);
     }
-  }, [defaultRoute, syncKey, syncRoute]);
+  }, [defaultRoute, syncKey, syncRoute, visiblePagesKey, pageOrderKey]);
 
   // 组件挂载时加载初始数据
   useEffect(() => {
@@ -157,18 +163,18 @@ export function RouterProvider({
   // 持久化可见页面列表
   useEffect(() => {
     if (isLoaded) {
-      storageUtil.set('app/visiblePages', visiblePages).catch(console.error);
-      localStorage.setItem('snapshot/app/visiblePages', JSON.stringify(visiblePages));
+      storageUtil.set(visiblePagesKey, visiblePages).catch(console.error);
+      localStorage.setItem(`snapshot/${visiblePagesKey}`, JSON.stringify(visiblePages));
     }
-  }, [visiblePages, isLoaded]);
+  }, [visiblePages, isLoaded, visiblePagesKey]);
 
   // 持久化页面排序
   useEffect(() => {
     if (isLoaded) {
-      storageUtil.set('app/pageOrder', pageOrder).catch(console.error);
-      localStorage.setItem('snapshot/app/pageOrder', JSON.stringify(pageOrder));
+      storageUtil.set(pageOrderKey, pageOrder).catch(console.error);
+      localStorage.setItem(`snapshot/${pageOrderKey}`, JSON.stringify(pageOrder));
     }
-  }, [pageOrder, isLoaded]);
+  }, [pageOrder, isLoaded, pageOrderKey]);
 
   /**
    * 监听存储变化，以便在多个入口（如 Popup 和 Options）之间同步路由和设置
@@ -185,15 +191,15 @@ export function RouterProvider({
         }
       }
       // 同步可见页面列表
-      if (changes['app/visiblePages']) {
-        const newPages = changes['app/visiblePages'].newValue;
+      if (changes[visiblePagesKey as string]) {
+        const newPages = changes[visiblePagesKey as string].newValue;
         if (isValidPageList(newPages)) {
           setVisiblePages(newPages);
         }
       }
       // 同步页面排序
-      if (changes['app/pageOrder']) {
-        const newOrder = changes['app/pageOrder'].newValue;
+      if (changes[pageOrderKey as string]) {
+        const newOrder = changes[pageOrderKey as string].newValue;
         if (isValidPageList(newOrder)) {
           setPageOrder(newOrder);
         }
@@ -202,7 +208,7 @@ export function RouterProvider({
 
     chrome.storage.onChanged.addListener(handleStorageChange);
     return () => chrome.storage.onChanged.removeListener(handleStorageChange);
-  }, [syncRoute, currentPage, syncKey]);
+  }, [syncRoute, currentPage, syncKey, visiblePagesKey, pageOrderKey]);
 
   /**
    * 跳转到指定页面

providers/__tests__/RouterProvider.test.tsx

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor, act } from '@testing-library/react';
+import { RouterProvider, useRouter } from '../RouterProvider';
+import { storageUtil } from '@/utils/chromeStorage';
+import React from 'react';
+
+// Mock storageUtil
+vi.mock('@/utils/chromeStorage', () => ({
+  storageUtil: {
+    get: vi.fn(),
+    set: vi.fn(() => Promise.resolve()),
+  },
+}));
+
+// Helper component to test useRouter
+const TestComponent = () => {
+  const { currentPage, navigateTo, visiblePages, pageOrder } = useRouter();
+  return (
+    <div>
+      <div data-testid="current-page">{currentPage}</div>
+      <div data-testid="visible-pages">{visiblePages.join(',')}</div>
+      <div data-testid="page-order">{pageOrder.join(',')}</div>
+      <button onClick={() => navigateTo('timestamp')} data-testid="navigate-btn">
+        Navigate
+      </button>
+    </div>
+  );
+};
+
+describe('RouterProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+    // Mock chrome.storage.onChanged
+    (global as any).chrome = {
+      storage: {
+        onChanged: {
+          addListener: vi.fn(),
+          removeListener: vi.fn(),
+        },
+      },
+    };
+  });
+
+  it('应该使用默认值初始化路由', async () => {
+    (storageUtil.get as any).mockImplementation((key: string, defaultValue: any) =>
+      Promise.resolve(defaultValue),
+    );
+
+    render(
+      <RouterProvider defaultRoute="dashboard">
+        <TestComponent />
+      </RouterProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-page')).toHaveTextContent('dashboard');
+    });
+  });
+
+  it('应该从指定的 syncKey 加载路由', async () => {
+    (storageUtil.get as any).mockImplementation((key: string, defaultValue: any) => {
+      if (key === 'app/sidepanelRoute') return Promise.resolve('timestamp');
+      return Promise.resolve(defaultValue);
+    });
+
+    render(
+      <RouterProvider syncKey="app/sidepanelRoute">
+        <TestComponent />
+      </RouterProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-page')).toHaveTextContent('timestamp');
+    });
+  });
+
+  it('导航时应该更新指定的 syncKey', async () => {
+    (storageUtil.get as any).mockImplementation((key: string, defaultValue: any) =>
+      Promise.resolve(defaultValue),
+    );
+
+    render(
+      <RouterProvider syncKey="app/popupRoute">
+        <TestComponent />
+      </RouterProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-page')).toHaveTextContent('dashboard');
+    });
+
+    const btn = screen.getByTestId('navigate-btn');
+    await act(async () => {
+      btn.click();
+    });
+
+    expect(screen.getByTestId('current-page')).toHaveTextContent('timestamp');
+    expect(storageUtil.set).toHaveBeenCalledWith('app/popupRoute', 'timestamp');
+  });
+
+  it('应该支持独立的标签页路由同步', async () => {
+    (storageUtil.get as any).mockImplementation((key: string, defaultValue: any) => {
+      if (key === 'app/tabRoute') return Promise.resolve('qrCode');
+      return Promise.resolve(defaultValue);
+    });
+
+    render(
+      <RouterProvider syncKey="app/tabRoute">
+        <TestComponent />
+      </RouterProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-page')).toHaveTextContent('qrCode');
+    });
+  });
+
+  it('应该独立支持 visiblePagesKey 和 pageOrderKey', async () => {
+    (storageUtil.get as any).mockImplementation((key: string, defaultValue: any) => {
+      if (key === 'app/sidepanelVisiblePages')
+        return Promise.resolve(['timestamp', 'storageCleaner']);
+      if (key === 'app/sidepanelPageOrder') return Promise.resolve(['storageCleaner', 'timestamp']);
+      return Promise.resolve(defaultValue);
+    });
+
+    render(
+      <RouterProvider
+        visiblePagesKey="app/sidepanelVisiblePages"
+        pageOrderKey="app/sidepanelPageOrder"
+      >
+        <TestComponent />
+      </RouterProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('visible-pages')).toHaveTextContent('timestamp,storageCleaner');
+      expect(screen.getByTestId('page-order')).toHaveTextContent('storageCleaner,timestamp');
+    });
+  });
+});