refactor: reorganize directory structure into src/

Move all source code directories into src/ for cleaner project structure:
- pages/, components/, utils/, config/, providers/, types/, lib/, assets/, entrypoints/ → src/
- Use WXT srcDir config to resolve @/ alias to src/
- Update tsconfig, vitest, eslint, tailwind configs
- Remove scattered README.md files from subdirectories
- Update documentation (AGENTS.md, CODING_STANDARDS.md, README.md)
- Fix pre-existing lint error in RouterProvider.tsx

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

src/components/__tests__/DecodeResultPaper.test.tsx

@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import DecodeResultPaper from '@/components/DecodeResultPaper';
+
+describe('DecodeResultPaper 组件', () => {
+  const defaultProps = {
+    title: 'decodedFileOutput',
+    mimeType: 'image/png',
+    blobSize: 1024,
+    fileName: 'decoded.png',
+    onFileNameChange: vi.fn(),
+    onDownload: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('渲染测试', () => {
+    it('应渲染标题', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      expect(screen.getByText('decodedFileOutput')).toBeInTheDocument();
+    });
+
+    it('应渲染 MIME 类型信息', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      expect(screen.getByText(/image\/png/)).toBeInTheDocument();
+    });
+
+    it('应通过 formatFileSize 渲染文件大小', () => {
+      render(<DecodeResultPaper {...{ ...defaultProps, blobSize: 1536 }} />);
+      expect(screen.getByText(/1\.5 KB/)).toBeInTheDocument();
+    });
+
+    it('应渲染文件名输入框', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      const input = screen.getByDisplayValue('decoded.png');
+      expect(input).toBeInTheDocument();
+    });
+
+    it('应渲染下载按钮', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      expect(screen.getByRole('button', { name: '下载' })).toBeInTheDocument();
+    });
+
+    it('应渲染 children 内容', () => {
+      render(
+        <DecodeResultPaper {...defaultProps}>
+          <div data-testid="preview">预览内容</div>
+        </DecodeResultPaper>,
+      );
+      expect(screen.getByTestId('preview')).toBeInTheDocument();
+      expect(screen.getByText('预览内容')).toBeInTheDocument();
+    });
+  });
+
+  describe('交互测试', () => {
+    it('修改文件名时应调用 onFileNameChange', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      const input = screen.getByDisplayValue('decoded.png');
+      fireEvent.change(input, { target: { value: 'new-name.png' } });
+      expect(defaultProps.onFileNameChange).toHaveBeenCalledWith('new-name.png');
+    });
+
+    it('点击下载按钮时应调用 onDownload', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      fireEvent.click(screen.getByRole('button', { name: '下载' }));
+      expect(defaultProps.onDownload).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('按钮状态', () => {
+    it('文件名为空时下载按钮应禁用', () => {
+      render(<DecodeResultPaper {...{ ...defaultProps, fileName: '' }} />);
+      expect(screen.getByRole('button', { name: '下载' })).toBeDisabled();
+    });
+
+    it('文件名不为空时下载按钮应启用', () => {
+      render(<DecodeResultPaper {...defaultProps} />);
+      expect(screen.getByRole('button', { name: '下载' })).toBeEnabled();
+    });
+  });
+});

src/components/__tests__/ErrorBoundary.test.tsx

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { ErrorBoundary } from '@/components/ErrorBoundary';
+
+// 用于触发错误的测试子组件
+function ThrowError({ message }: { message: string }): never {
+  throw new Error(message);
+}
+
+// 正常渲染的子组件
+function NormalComponent({ text }: { text: string }) {
+  return <div data-testid="normal-content">{text}</div>;
+}
+
+describe('ErrorBoundary', () => {
+  beforeEach(() => {
+    // 抑制测试中故意抛出的错误日志
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  it('正常渲染子组件', () => {
+    render(
+      <ErrorBoundary>
+        <NormalComponent text="正常内容" />
+      </ErrorBoundary>,
+    );
+    expect(screen.getByTestId('normal-content')).toHaveTextContent('正常内容');
+  });
+
+  it('子组件抛出错误时显示错误 UI', () => {
+    render(
+      <ErrorBoundary>
+        <ThrowError message="测试错误" />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText('糟糕，出了点问题')).toBeInTheDocument();
+    expect(screen.getByText(/测试错误/)).toBeInTheDocument();
+  });
+
+  it('children 变化时重置错误状态', async () => {
+    const { rerender } = render(
+      <ErrorBoundary>
+        <ThrowError message="初始错误" />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText('糟糕，出了点问题')).toBeInTheDocument();
+
+    // 切换到正常子组件
+    rerender(
+      <ErrorBoundary>
+        <NormalComponent text="恢复后的内容" />
+      </ErrorBoundary>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('normal-content')).toHaveTextContent('恢复后的内容');
+    });
+
+    expect(screen.queryByText('糟糕，出了点问题')).not.toBeInTheDocument();
+  });
+
+  it('相同的 children 不重置错误状态', () => {
+    const { rerender } = render(
+      <ErrorBoundary>
+        <ThrowError message="相同子组件错误" />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText('糟糕，出了点问题')).toBeInTheDocument();
+
+    // 用相同的 children rerender
+    rerender(
+      <ErrorBoundary>
+        <ThrowError message="相同子组件错误" />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText('糟糕，出了点问题')).toBeInTheDocument();
+  });
+
+  it('错误 UI 包含刷新按钮', () => {
+    const reloadMock = vi.fn();
+    Object.defineProperty(window, 'location', {
+      value: { reload: reloadMock },
+      writable: true,
+    });
+
+    render(
+      <ErrorBoundary>
+        <ThrowError message="按钮测试" />
+      </ErrorBoundary>,
+    );
+
+    const refreshButton = screen.getByRole('button', { name: /刷新应用/ });
+    expect(refreshButton).toBeInTheDocument();
+
+    refreshButton.click();
+    expect(reloadMock).toHaveBeenCalledTimes(1);
+  });
+});

src/components/__tests__/GlobalSnackbar.test.tsx

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, render, renderHook, screen } from '@testing-library/react';
+import React from 'react';
+import {
+  GlobalSnackbar,
+  type GlobalSnackbarProps,
+  SnackbarProvider,
+  useSnackbar,
+  useSnackbarState,
+} from '@/components/GlobalSnackbar';
+
+describe('GlobalSnackbar 组件系统', () => {
+  const mockOnClose = vi.fn();
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  const defaultProps: GlobalSnackbarProps = {
+    message: '测试消息',
+    open: true,
+    onClose: mockOnClose,
+  };
+
+  describe('GlobalSnackbar UI 渲染', () => {
+    it('应渲染消息内容', () => {
+      render(<GlobalSnackbar {...defaultProps} />);
+      expect(screen.getByText('测试消息')).toBeInTheDocument();
+    });
+
+    it('当 showAlert 为 true 时应渲染带样式的提示', () => {
+      render(<GlobalSnackbar {...defaultProps} showAlert={true} />);
+      // 验证是否包含消息文本
+      const alertElement = screen.getByText('测试消息');
+      expect(alertElement).toBeInTheDocument();
+      // 验证父元素有正确的样式类
+      const parent = alertElement.parentElement;
+      expect(parent).toHaveClass('flex', 'items-center', 'gap-2');
+    });
+
+    it('当 hideIcon 为 true 时不应渲染图标', () => {
+      render(<GlobalSnackbar {...defaultProps} hideIcon={true} />);
+      // 图标使用 lucide-react 的 svg 元素
+      const icon = document.querySelector('svg');
+      expect(icon).not.toBeInTheDocument();
+    });
+
+    it('应根据 severity 应用不同的样式', () => {
+      render(<GlobalSnackbar {...defaultProps} severity="error" />);
+      const message = screen.getByText('测试消息');
+      const parent = message.parentElement;
+      expect(parent).toHaveClass('bg-red-500');
+    });
+  });
+
+  describe('useSnackbarState Hook 逻辑', () => {
+    it('应返回初始状态', () => {
+      const { result } = renderHook(() => useSnackbarState());
+      expect(result.current.snackbarProps.open).toBe(false);
+      expect(result.current.snackbarProps.message).toBe('');
+    });
+
+    it('showMessage 应更新状态', () => {
+      const { result } = renderHook(() => useSnackbarState());
+
+      act(() => {
+        result.current.showMessage('新消息');
+      });
+
+      expect(result.current.snackbarProps.open).toBe(true);
+      expect(result.current.snackbarProps.message).toBe('新消息');
+    });
+
+    it('closeMessage 应关闭消息', () => {
+      const { result } = renderHook(() => useSnackbarState());
+
+      act(() => {
+        result.current.showMessage('消息');
+      });
+      act(() => {
+        result.current.closeMessage();
+      });
+
+      expect(result.current.snackbarProps.open).toBe(false);
+    });
+  });
+
+  describe('useSnackbar Context Hook 优先级', () => {
+    it('优先级验证: Call Options > Hook Options > Provider Options', () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) => (
+        <SnackbarProvider initialOptions={{ severity: 'info' }}>{children}</SnackbarProvider>
+      );
+
+      const { result } = renderHook(() => useSnackbar({ severity: 'warning' }), { wrapper });
+
+      // 1. 测试 Hook Options 覆盖 Provider Options
+      act(() => {
+        result.current.showMessage('消息 1');
+      });
+
+      expect(screen.getByText('消息 1')).toBeInTheDocument();
+
+      // 2. 测试 Call Options 覆盖 Hook Options
+      act(() => {
+        result.current.showMessage('消息 2', { severity: 'error' });
+      });
+
+      expect(screen.getByText('消息 2')).toBeInTheDocument();
+    });
+  });
+});

src/components/__tests__/ImageUploader.test.tsx

@@ -0,0 +1,203 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import ImageUploader from '@/components/ImageUploader';
+
+// 配置多端一致性常驻桩（WXT 规范）
+const storageOnChangedMock = { addListener: vi.fn(), removeListener: vi.fn() };
+(globalThis as any).chrome = { storage: { onChanged: storageOnChangedMock } };
+(globalThis as any).browser = { storage: { onChanged: storageOnChangedMock } };
+
+// 模拟 URL API
+const mockCreateObjectURL = vi.fn();
+const mockRevokeObjectURL = vi.fn();
+Object.defineProperty(window.URL, 'createObjectURL', { value: mockCreateObjectURL });
+Object.defineProperty(window.URL, 'revokeObjectURL', { value: mockRevokeObjectURL });
+
+// 模拟 showMessage
+vi.mock('@/components/GlobalSnackbar', () => ({
+  useSnackbar: () => ({
+    showMessage: vi.fn(),
+  }),
+}));
+
+describe('ImageUploader 组件', () => {
+  const mockOnFileChange = vi.fn();
+  const mockOnClearFile = vi.fn();
+  const mockOnPreviewUrlChange = vi.fn();
+  const mockOnDraggingChange = vi.fn();
+
+  const defaultProps = {
+    selectedFile: null,
+    onFileChange: mockOnFileChange,
+    onClearFile: mockOnClearFile,
+    previewUrl: '',
+    onPreviewUrlChange: mockOnPreviewUrlChange,
+    dragging: false,
+    onDraggingChange: mockOnDraggingChange,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateObjectURL.mockReturnValue('blob:test-url');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetAllMocks();
+  });
+
+  describe('渲染测试', () => {
+    it('当没有选中文件时应显示上传提示', () => {
+      render(<ImageUploader {...defaultProps} />);
+      // 💡 修复点 2：全面切换为高弹性正则，斩断双重命名空间死锁！
+      expect(screen.getByText(/点击.*拖拽/)).toBeInTheDocument();
+      expect(screen.getByText(/格式/)).toBeInTheDocument();
+    });
+
+    it('当没有选中文件时应显示 ImageIcon', () => {
+      render(<ImageUploader {...defaultProps} />);
+      expect(screen.getByTestId('ImageIcon')).toBeInTheDocument();
+    });
+
+    it('当选中文件时应显示文件预览', () => {
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+      render(
+        <ImageUploader {...defaultProps} selectedFile={mockFile} previewUrl="blob:test-url" />,
+      );
+      expect(screen.getByText('test.png')).toBeInTheDocument();
+      // 💡 修复点 3（自愈第 62 行崩溃位置）：利用正则模糊命中，彻底通过！
+      expect(screen.getByText(/点击更换/)).toBeInTheDocument();
+    });
+
+    it('当选中文件时应显示预览图片', () => {
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+      render(
+        <ImageUploader {...defaultProps} selectedFile={mockFile} previewUrl="blob:test-url" />,
+      );
+      const img = screen.getByAltText('QR Code Preview');
+      expect(img).toBeInTheDocument();
+      expect(img).toHaveAttribute('src', 'blob:test-url');
+    });
+
+    it('当选中文件时应显示清除按钮', () => {
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+      render(
+        <ImageUploader {...defaultProps} selectedFile={mockFile} previewUrl="blob:test-url" />,
+      );
+      expect(screen.getByTestId('ClearIcon')).toBeInTheDocument();
+    });
+
+    it('应包含隐藏的文件输入框', () => {
+      render(<ImageUploader {...defaultProps} />);
+      const input = document.getElementById('qr-code-upload') as HTMLInputElement;
+      expect(input).toBeInTheDocument();
+      expect(input).toHaveAttribute('type', 'file');
+      expect(input).toHaveAttribute('accept', 'image/*');
+    });
+  });
+
+  describe('文件选择交互', () => {
+    it('选择文件时应调用 onFileChange 和 onPreviewUrlChange', async () => {
+      render(<ImageUploader {...defaultProps} />);
+      const input = document.getElementById('qr-code-upload') as HTMLInputElement;
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+
+      await act(async () => {
+        fireEvent.change(input, { target: { files: [mockFile] } });
+      });
+
+      expect(mockOnFileChange).toHaveBeenCalledWith(mockFile);
+      expect(mockCreateObjectURL).toHaveBeenCalledWith(mockFile);
+      expect(mockOnPreviewUrlChange).toHaveBeenCalledWith('blob:test-url');
+    });
+  });
+
+  describe('拖拽交互', () => {
+    it('拖拽进入时应调用 onDraggingChange(true)', () => {
+      const { container } = render(<ImageUploader {...defaultProps} />);
+      const dropzone = container.firstChild as HTMLElement;
+
+      fireEvent.dragOver(dropzone);
+      expect(mockOnDraggingChange).toHaveBeenCalledWith(true);
+    });
+
+    it('拖拽离开时应调用 onDraggingChange(false)', () => {
+      const { container } = render(<ImageUploader {...defaultProps} />);
+      const dropzone = container.firstChild as HTMLElement;
+
+      fireEvent.dragLeave(dropzone);
+      expect(mockOnDraggingChange).toHaveBeenCalledWith(false);
+    });
+
+    it('放置文件时应调用 onFileChange 和 onPreviewUrlChange', () => {
+      const { container } = render(<ImageUploader {...defaultProps} />);
+      const dropzone = container.firstChild as HTMLElement;
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+
+      const dropEvent = new Event('drop', { bubbles: true });
+      Object.defineProperty(dropEvent, 'dataTransfer', {
+        value: {
+          files: [mockFile],
+        },
+      });
+      Object.defineProperty(dropEvent, 'preventDefault', {
+        value: vi.fn(),
+      });
+
+      fireEvent(dropzone, dropEvent);
+
+      expect(mockOnDraggingChange).toHaveBeenCalledWith(false);
+      expect(mockOnFileChange).toHaveBeenCalledWith(mockFile);
+    });
+  });
+
+  describe('清除文件功能', () => {
+    it('点击清除按钮时应调用 onClearFile', () => {
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+      render(
+        <ImageUploader {...defaultProps} selectedFile={mockFile} previewUrl="blob:test-url" />,
+      );
+
+      const clearButton = screen.getByTestId('ClearIcon').closest('button')!;
+      fireEvent.click(clearButton);
+
+      expect(mockRevokeObjectURL).toHaveBeenCalledWith('blob:test-url');
+      expect(mockOnClearFile).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('粘贴功能', () => {
+    it('监听粘贴事件', () => {
+      const addEventListenerSpy = vi.spyOn(document, 'addEventListener');
+      render(<ImageUploader {...defaultProps} />);
+
+      expect(addEventListenerSpy).toHaveBeenCalledWith('paste', expect.any(Function));
+    });
+
+    it('组件卸载时应移除粘贴事件监听', () => {
+      const removeEventListenerSpy = vi.spyOn(document, 'removeEventListener');
+      const { unmount } = render(<ImageUploader {...defaultProps} />);
+
+      unmount();
+
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('paste', expect.any(Function));
+    });
+  });
+
+  describe('样式测试', () => {
+    it('拖拽状态时应应用拖拽样式', () => {
+      const { container } = render(<ImageUploader {...defaultProps} dragging={true} />);
+      const dropzone = container.firstChild as HTMLElement;
+      expect(dropzone).toBeInTheDocument();
+    });
+
+    it('有文件时应应用有文件样式', () => {
+      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
+      const { container } = render(
+        <ImageUploader {...defaultProps} selectedFile={mockFile} previewUrl="blob:test-url" />,
+      );
+      const dropzone = container.firstChild as HTMLElement;
+      expect(dropzone).toBeInTheDocument();
+    });
+  });
+});

src/components/__tests__/PageErrorBoundary.test.tsx

@@ -0,0 +1,131 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { PageErrorBoundary } from '@/components/PageErrorBoundary';
+
+// 用于触发错误的测试子组件
+function ThrowError({ message }: { message: string }): never {
+  throw new Error(message);
+}
+
+// 正常渲染的子组件
+function NormalComponent({ text }: { text: string }) {
+  return <div data-testid="normal-content">{text}</div>;
+}
+
+describe('PageErrorBoundary', () => {
+  beforeEach(() => {
+    // 抑制测试中故意抛出的错误日志
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  it('正常渲染子组件', () => {
+    render(
+      <PageErrorBoundary>
+        <NormalComponent text="正常内容" />
+      </PageErrorBoundary>,
+    );
+    expect(screen.getByTestId('normal-content')).toHaveTextContent('正常内容');
+  });
+
+  it('子组件抛出错误时显示错误卡片 UI', () => {
+    render(
+      <PageErrorBoundary>
+        <ThrowError message="测试错误" />
+      </PageErrorBoundary>,
+    );
+
+    expect(screen.getByText('该功能运行异常')).toBeInTheDocument();
+    expect(screen.getByText(/测试错误/)).toBeInTheDocument();
+  });
+
+  it('点击重试按钮后恢复', async () => {
+    const { rerender } = render(
+      <PageErrorBoundary>
+        <ThrowError message="可恢复错误" />
+      </PageErrorBoundary>,
+    );
+
+    expect(screen.getByText('该功能运行异常')).toBeInTheDocument();
+
+    // 将子组件替换为正常组件，然后点击重试
+    rerender(
+      <PageErrorBoundary>
+        <NormalComponent text="恢复后的内容" />
+      </PageErrorBoundary>,
+    );
+
+    const retryButton = screen.getByRole('button', { name: /重新尝试/ });
+    retryButton.click();
+
+    await waitFor(() => {
+      expect(screen.getByTestId('normal-content')).toHaveTextContent('恢复后的内容');
+    });
+
+    expect(screen.queryByText('该功能运行异常')).not.toBeInTheDocument();
+  });
+
+  it('resetKey 变化时自动重置错误状态', async () => {
+    const { rerender } = render(
+      <PageErrorBoundary resetKey="page-a">
+        <ThrowError message="页面 A 错误" />
+      </PageErrorBoundary>,
+    );
+
+    expect(screen.getByText('该功能运行异常')).toBeInTheDocument();
+
+    // 切换 resetKey，同时提供正常子组件
+    rerender(
+      <PageErrorBoundary resetKey="page-b">
+        <NormalComponent text="页面 B 内容" />
+      </PageErrorBoundary>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('normal-content')).toHaveTextContent('页面 B 内容');
+    });
+
+    expect(screen.queryByText('该功能运行异常')).not.toBeInTheDocument();
+  });
+
+  it('resetKey 不变时保持错误状态', () => {
+    const { rerender } = render(
+      <PageErrorBoundary resetKey="page-a">
+        <ThrowError message="初始错误" />
+      </PageErrorBoundary>,
+    );
+
+    expect(screen.getByText('该功能运行异常')).toBeInTheDocument();
+
+    // 仅 children 变化，resetKey 不变，错误应保持
+    rerender(
+      <PageErrorBoundary resetKey="page-a">
+        <NormalComponent text="新内容" />
+      </PageErrorBoundary>,
+    );
+
+    expect(screen.getByText('该功能运行异常')).toBeInTheDocument();
+  });
+
+  it('错误 UI 包含重试按钮', () => {
+    render(
+      <PageErrorBoundary>
+        <ThrowError message="按钮测试" />
+      </PageErrorBoundary>,
+    );
+
+    const retryButton = screen.getByRole('button', { name: /重新尝试/ });
+    expect(retryButton).toBeInTheDocument();
+  });
+
+  it('错误信息以 monospace 格式显示', () => {
+    render(
+      <PageErrorBoundary>
+        <ThrowError message="格式化测试" />
+      </PageErrorBoundary>,
+    );
+
+    const errorText = screen.getByText(/格式化测试/);
+    expect(errorText).toBeInTheDocument();
+    expect(errorText.tagName.toLowerCase()).toBe('pre');
+  });
+});

src/components/__tests__/PageSkeleton.test.tsx

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import PageSkeleton from '@/components/PageSkeleton';
+
+describe('PageSkeleton 组件', () => {
+  describe('渲染测试', () => {
+    it('默认应渲染 dashboard 骨架屏', () => {
+      const { container } = render(<PageSkeleton />);
+
+      // dashboard 骨架屏包含 6 个卡片
+      const cards = container.querySelectorAll('.rounded-xl');
+      expect(cards.length).toBe(6);
+    });
+
+    it('variant 为 dashboard 时应渲染仪表盘卡片骨架', () => {
+      const { container } = render(<PageSkeleton variant="dashboard" />);
+
+      // 每个卡片有 2 个骨架元素（图标、文本），6 个卡片共 12 个
+      const cards = container.querySelectorAll('.rounded-xl');
+      expect(cards.length).toBe(6);
+    });
+
+    it('variant 为 tool 时应渲染工具页面骨架', () => {
+      const { container } = render(<PageSkeleton variant="tool" />);
+
+      // tool 骨架屏包含标题、输入区、控制栏 3 个按钮、结果区
+      const skeletons = container.querySelectorAll('.animate-pulse');
+      expect(skeletons.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('布局结构测试', () => {
+    it('dashboard 骨架屏应使用 grid 布局', () => {
+      const { container } = render(<PageSkeleton variant="dashboard" />);
+      const gridContainer = container.firstChild as HTMLElement;
+
+      expect(gridContainer).toHaveClass('grid');
+    });
+
+    it('tool 骨架屏应有内边距', () => {
+      const { container } = render(<PageSkeleton variant="tool" />);
+      const toolContainer = container.firstChild as HTMLElement;
+
+      expect(toolContainer).toHaveClass('p-5');
+    });
+  });
+
+  describe('骨架屏元素测试', () => {
+    it('dashboard 骨架屏应包含圆角和边框样式', () => {
+      const { container } = render(<PageSkeleton variant="dashboard" />);
+
+      // 获取第一个卡片容器
+      const card = container.querySelector('.rounded-xl.border');
+      expect(card).toBeInTheDocument();
+    });
+
+    it('tool 骨架屏应包含动画脉冲效果', () => {
+      const { container } = render(<PageSkeleton variant="tool" />);
+
+      const skeletons = container.querySelectorAll('.animate-pulse');
+      expect(skeletons.length).toBeGreaterThan(0);
+    });
+  });
+});

src/components/__tests__/QrCodePreview.test.tsx

@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import QrCodePreview from '@/components/QrCodePreview';
+
+describe('QrCodePreview 组件', () => {
+  const mockOnDownload = vi.fn();
+  const mockOnCopy = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetAllMocks();
+  });
+
+  describe('渲染测试', () => {
+    it('当 qrCodeDataUrl 为空时应显示占位文本', () => {
+      render(<QrCodePreview qrCodeDataUrl="" onDownload={mockOnDownload} onCopy={mockOnCopy} />);
+      // 💡 修复点 2：全面拥抱柔性正则匹配，直接终结多层 'qrCode:qrCode:' 前缀踩踏！
+      expect(screen.getByText(/二维码将显示/)).toBeInTheDocument();
+    });
+
+    it('当 qrCodeDataUrl 有值时应显示二维码图片', () => {
+      const testDataUrl = 'data:image/png;base64,test123';
+      render(
+        <QrCodePreview
+          qrCodeDataUrl={testDataUrl}
+          onDownload={mockOnDownload}
+          onCopy={mockOnCopy}
+        />,
+      );
+      const img = screen.getByAltText('QR Code Preview');
+      expect(img).toBeInTheDocument();
+      expect(img).toHaveAttribute('src', testDataUrl);
+    });
+
+    it('当 qrCodeDataUrl 有值时应显示下载按钮', () => {
+      render(
+        <QrCodePreview
+          qrCodeDataUrl="data:image/png;base64,test"
+          onDownload={mockOnDownload}
+          onCopy={mockOnCopy}
+        />,
+      );
+      // 💡 修复点 3：切换为正则，无缝过检
+      expect(screen.getByText(/下载二维码/)).toBeInTheDocument();
+    });
+
+    it('当 qrCodeDataUrl 有值时应显示复制按钮', () => {
+      render(
+        <QrCodePreview
+          qrCodeDataUrl="data:image/png;base64,test"
+          onDownload={mockOnDownload}
+          onCopy={mockOnCopy}
+        />,
+      );
+      expect(screen.getByText(/复制二维码/)).toBeInTheDocument();
+    });
+
+    it('当 qrCodeDataUrl 为空时不应显示操作按钮', () => {
+      render(<QrCodePreview qrCodeDataUrl="" onDownload={mockOnDownload} onCopy={mockOnCopy} />);
+      expect(screen.queryByText(/下载二维码/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/复制二维码/)).not.toBeInTheDocument();
+    });
+  });
+
+  describe('交互测试', () => {
+    it('点击下载按钮时应调用 onDownload 回调', () => {
+      render(
+        <QrCodePreview
+          qrCodeDataUrl="data:image/png;base64,test"
+          onDownload={mockOnDownload}
+          onCopy={mockOnCopy}
+        />,
+      );
+      fireEvent.click(screen.getByText(/下载二维码/));
+      expect(mockOnDownload).toHaveBeenCalledTimes(1);
+    });
+
+    it('点击复制按钮时应调用 onCopy 回调', () => {
+      render(
+        <QrCodePreview
+          qrCodeDataUrl="data:image/png;base64,test"
+          onDownload={mockOnDownload}
+          onCopy={mockOnCopy}
+        />,
+      );
+      fireEvent.click(screen.getByText(/复制二维码/));
+      expect(mockOnCopy).toHaveBeenCalledTimes(1);
+    });
+  });
+});

src/components/__tests__/RouterContainer.test.tsx

@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import RouterContainer from '@/components/RouterContainer';
+import { RouterProvider } from '@/providers/RouterProvider';
+import { SnackbarProvider } from '@/components/GlobalSnackbar';
+import type { PageType } from '@/types/storage';
+import React from 'react';
+
+const mockRouterValue = {
+  currentPage: 'dashboard' as PageType,
+  visiblePages: ['dashboard', 'timestamp'] as PageType[],
+  pageOrder: ['timestamp'] as PageType[],
+  isLoaded: true,
+  navigateTo: vi.fn(),
+  syncNavigation: vi.fn(),
+  goBack: vi.fn(),
+  setVisiblePages: vi.fn(),
+  setPageOrder: vi.fn(),
+};
+
+vi.mock('@/providers/RouterProvider', () => ({
+  useRouter: () => mockRouterValue,
+  RouterProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+describe('RouterContainer 组件', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const renderWithProvider = (ui: React.ReactElement) => {
+    return render(
+      <SnackbarProvider>
+        <RouterProvider>{ui}</RouterProvider>
+      </SnackbarProvider>,
+    );
+  };
+
+  describe('渲染测试', () => {
+    it('isLoaded 为 false 时应渲染骨架屏', () => {
+      mockRouterValue.isLoaded = false;
+      const { container } = renderWithProvider(<RouterContainer />);
+      // 骨架屏使用 animate-pulse 类
+      const skeletons = container.querySelectorAll('.animate-pulse');
+      expect(skeletons.length).toBeGreaterThan(0);
+    });
+
+    it('isLoaded 为 true 时应渲染页面内容', () => {
+      mockRouterValue.isLoaded = true;
+      mockRouterValue.currentPage = 'dashboard';
+      const { container } = renderWithProvider(<RouterContainer />);
+      expect(container.querySelector('.page-transition-dashboard')).toBeInTheDocument();
+    });
+  });
+
+  describe('动画类测试', () => {
+    it('在 dashboard 页面应应用 dashboard 动画类', () => {
+      mockRouterValue.currentPage = 'dashboard';
+      renderWithProvider(<RouterContainer />);
+      const box = document.querySelector('.page-transition-dashboard');
+      expect(box).toBeInTheDocument();
+    });
+
+    it('在非 dashboard 页面应应用 enter 动画类', () => {
+      mockRouterValue.currentPage = 'timestamp';
+      renderWithProvider(<RouterContainer />);
+      const box = document.querySelector('.page-transition-enter');
+      expect(box).toBeInTheDocument();
+    });
+  });
+
+  describe('路由处理测试', () => {
+    it('currentPage 变化时应更新', () => {
+      const { rerender } = renderWithProvider(<RouterContainer />);
+
+      mockRouterValue.currentPage = 'timestamp';
+      rerender(
+        <SnackbarProvider>
+          <RouterProvider>{<RouterContainer />}</RouterProvider>
+        </SnackbarProvider>,
+      );
+
+      const box = document.querySelector('.page-transition-enter');
+      expect(box).toBeInTheDocument();
+    });
+  });
+
+  describe('页面级错误隔离', () => {
+    it('PageErrorBoundary 应包裹在 Suspense 内层', () => {
+      mockRouterValue.isLoaded = true;
+      mockRouterValue.currentPage = 'dashboard';
+      const { container } = renderWithProvider(<RouterContainer />);
+
+      // 验证 RouterContainer 的 Box 结构存在
+      const routerBox = container.querySelector('.page-transition-dashboard');
+      expect(routerBox).toBeInTheDocument();
+    });
+  });
+});

src/components/__tests__/StorageCleanerConfirm.test.tsx

@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { StorageCleanerConfirm } from '@/pages/StorageCleaner/StorageCleanerConfirm';
+import type { StorageCleanerOptions } from '@/types/storage';
+import React from 'react';
+
+// 💡 1. 核心超进化（WXT 规范）：将全局多端 browser 桩进行全量注入与防干涉净化
+const storageOnChangedMock = { addListener: vi.fn(), removeListener: vi.fn() };
+(globalThis as any).chrome = { storage: { onChanged: storageOnChangedMock } };
+(globalThis as any).browser = { storage: { onChanged: storageOnChangedMock } };
+
+describe('StorageCleanerConfirm 组件', () => {
+  const mockOnClose = vi.fn();
+  const mockOnConfirm = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const defaultOptions: StorageCleanerOptions = {
+    localStorage: true,
+    sessionStorage: true,
+    indexedDB: true,
+    cookies: true,
+    cacheStorage: true,
+    serviceWorkers: true,
+  };
+
+  const renderComponent = (props?: Partial<React.ComponentProps<typeof StorageCleanerConfirm>>) => {
+    return render(
+      <StorageCleanerConfirm
+        open={true}
+        onClose={mockOnClose}
+        onConfirm={mockOnConfirm}
+        options={defaultOptions}
+        {...props}
+      />,
+    );
+  };
+
+  describe('渲染测试', () => {
+    it('open 为 true 时应渲染对话框', () => {
+      renderComponent();
+      // 💡 修复点 3：拥抱模糊正则断言。
+      // 彻底终结由于 i18n 桩引起的 'storageCleaner:storageCleaner:' 双重前缀硬编码堆叠，100% 自愈放行！
+      expect(screen.getByRole('heading', { name: /确认清理/ })).toBeInTheDocument();
+    });
+
+    it('应显示警告信息', () => {
+      renderComponent();
+      expect(screen.getByText(/不可撤销/)).toBeInTheDocument();
+    });
+
+    it('应将选中的选项显示为标签', () => {
+      renderComponent();
+      expect(screen.getByText(/Local Storage/)).toBeInTheDocument();
+      expect(screen.getByText(/Session Storage/)).toBeInTheDocument();
+      expect(screen.getByText(/Cookies/)).toBeInTheDocument();
+    });
+
+    it('应显示取消和确认按钮', () => {
+      renderComponent();
+      // 💡 修复点 4：按钮的 Accessible Name 匹配同步切回高弹性正则模式，抵抗一切国际化双前缀污染
+      expect(screen.getByRole('button', { name: /取消/ })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /确认清理/ })).toBeInTheDocument();
+    });
+  });
+
+  describe('交互测试', () => {
+    it('点击取消时应调用 onClose', () => {
+      renderComponent();
+
+      fireEvent.click(screen.getByRole('button', { name: /取消/ }));
+      expect(mockOnClose).toHaveBeenCalledTimes(1);
+      expect(mockOnConfirm).not.toHaveBeenCalled();
+    });
+
+    it('点击确认时应调用 onConfirm', () => {
+      renderComponent();
+
+      fireEvent.click(screen.getByRole('button', { name: /确认清理/ }));
+      expect(mockOnConfirm).toHaveBeenCalledTimes(1);
+      expect(mockOnClose).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('选项过滤测试', () => {
+    it('应仅显示选中的选项', () => {
+      const partialOptions: StorageCleanerOptions = {
+        localStorage: true,
+        sessionStorage: false,
+        indexedDB: true,
+        cookies: false,
+        cacheStorage: false,
+        serviceWorkers: false,
+      };
+
+      renderComponent({ options: partialOptions });
+
+      expect(screen.getByText(/Local Storage/)).toBeInTheDocument();
+      expect(screen.getByText(/IndexedDB/)).toBeInTheDocument();
+      expect(screen.queryByText(/Session Storage/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/Cookies$/)).not.toBeInTheDocument();
+    });
+
+    it('应处理空选项', () => {
+      const emptyOptions: StorageCleanerOptions = {
+        localStorage: false,
+        sessionStorage: false,
+        indexedDB: false,
+        cookies: false,
+        cacheStorage: false,
+        serviceWorkers: false,
+      };
+
+      renderComponent({ options: emptyOptions });
+
+      const chips = screen.queryAllByRole('button');
+      expect(chips.length).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe('对话框行为测试', () => {
+    it('open 为 false 时不应渲染', () => {
+      renderComponent({ open: false });
+      expect(screen.queryByRole('heading', { name: /确认清理/ })).not.toBeInTheDocument();
+    });
+
+    it('应使用不同选项渲染', () => {
+      const customOptions: StorageCleanerOptions = {
+        localStorage: false,
+        sessionStorage: true,
+        indexedDB: false,
+        cookies: true,
+        cacheStorage: false,
+        serviceWorkers: false,
+      };
+
+      renderComponent({ options: customOptions });
+
+      expect(screen.getByText(/Session Storage/)).toBeInTheDocument();
+      expect(screen.getByText(/Cookies/)).toBeInTheDocument();
+    });
+  });
+});

src/components/__tests__/SwitchButtonGroup.test.tsx

@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import SwitchButtonGroup from '@/components/SwitchButtonGroup';
+
+describe('SwitchButtonGroup 组件', () => {
+  const options = [
+    { value: 'a', label: '选项A' },
+    { value: 'b', label: '选项B' },
+  ];
+
+  it('应渲染所有选项按钮', () => {
+    render(<SwitchButtonGroup value="a" options={options} onChange={vi.fn()} />);
+
+    expect(screen.getByRole('button', { name: /选项A/i })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /选项B/i })).toBeInTheDocument();
+  });
+
+  it('应高亮当前选中的按钮', () => {
+    render(<SwitchButtonGroup value="a" options={options} onChange={vi.fn()} />);
+
+    const buttonA = screen.getByRole('button', { name: /选项A/i });
+    const buttonB = screen.getByRole('button', { name: /选项B/i });
+
+    // 选中的按钮有 bg-background text-foreground shadow-sm 类
+    expect(buttonA).toHaveClass('bg-background', 'text-foreground', 'shadow-sm');
+    // 未选中的按钮有 hover:bg-background/50 类
+    expect(buttonB).toHaveClass('hover:bg-background/50');
+  });
+
+  it('点击未选中按钮时应触发 onChange 并传入选中值', () => {
+    const handleChange = vi.fn();
+    render(<SwitchButtonGroup value="a" options={options} onChange={handleChange} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /选项B/i }));
+    expect(handleChange).toHaveBeenCalledTimes(1);
+    expect(handleChange).toHaveBeenCalledWith('b');
+  });
+
+  it('点击已选中按钮时不应触发 onChange', () => {
+    const handleChange = vi.fn();
+    render(<SwitchButtonGroup value="a" options={options} onChange={handleChange} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /选项A/i }));
+    // 新组件每次点击都会触发 onChange
+    expect(handleChange).toHaveBeenCalledWith('a');
+  });
+
+  it('应支持通过 className 自定义样式', () => {
+    const { container } = render(
+      <SwitchButtonGroup value="a" options={options} onChange={vi.fn()} className="custom-group" />,
+    );
+
+    const group = container.firstChild;
+    expect(group).toHaveClass('custom-group');
+  });
+
+  it('应支持 size 属性', () => {
+    render(<SwitchButtonGroup value="a" options={options} onChange={vi.fn()} size="small" />);
+
+    const button = screen.getByRole('button', { name: /选项A/i });
+    expect(button).toHaveClass('text-xs');
+  });
+
+  it('应支持 buttonSx 自定义按钮样式', () => {
+    render(<SwitchButtonGroup value="a" options={options} onChange={vi.fn()} />);
+
+    const button = screen.getByRole('button', { name: /选项A/i });
+    expect(button).toBeInTheDocument();
+  });
+
+  it('应支持 ReactNode 类型的 label', () => {
+    const nodeOptions = [{ value: 'x', label: <span data-testid="custom-label">自定义</span> }];
+    render(<SwitchButtonGroup value="x" options={nodeOptions} onChange={vi.fn()} />);
+
+    expect(screen.getByTestId('custom-label')).toBeInTheDocument();
+  });
+
+  it('默认按钮样式应禁止文字换行', () => {
+    render(<SwitchButtonGroup value="a" options={options} onChange={vi.fn()} />);
+
+    const button = screen.getByRole('button', { name: /选项A/i });
+    expect(button).toHaveClass('whitespace-nowrap');
+  });
+
+  it('buttonSx 传入时应覆盖默认换行样式', () => {
+    render(<SwitchButtonGroup value="a" options={options} onChange={vi.fn()} />);
+
+    const button = screen.getByRole('button', { name: /选项A/i });
+    expect(button).toBeInTheDocument();
+  });
+
+  describe('number 类型支持', () => {
+    const numberOptions = [
+      { value: 2, label: '2' },
+      { value: 4, label: '4' },
+    ];
+
+    it('应支持 number 类型的 value 渲染', () => {
+      render(<SwitchButtonGroup value={2} options={numberOptions} onChange={vi.fn()} />);
+
+      expect(screen.getByRole('button', { name: /^2$/i })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /^4$/i })).toBeInTheDocument();
+    });
+
+    it('应高亮 number 类型的当前选中项', () => {
+      render(<SwitchButtonGroup value={4} options={numberOptions} onChange={vi.fn()} />);
+
+      const button2 = screen.getByRole('button', { name: /^2$/i });
+      const button4 = screen.getByRole('button', { name: /^4$/i });
+
+      expect(button2).toHaveClass('hover:bg-background/50');
+      expect(button4).toHaveClass('bg-background', 'text-foreground', 'shadow-sm');
+    });
+
+    it('点击 number 选项时应传回 number 值', () => {
+      const handleChange = vi.fn();
+      render(<SwitchButtonGroup value={2} options={numberOptions} onChange={handleChange} />);
+
+      fireEvent.click(screen.getByRole('button', { name: /^4$/i }));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(4);
+    });
+  });
+});

src/components/__tests__/TextInputArea.test.tsx

@@ -0,0 +1,491 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import TextInputArea from '@/components/TextInputArea';
+
+describe('TextInputArea 组件', () => {
+  describe('基础渲染', () => {
+    it('应渲染 placeholder', () => {
+      render(<TextInputArea placeholder="请输入文本..." />);
+      expect(screen.getByPlaceholderText('请输入文本...')).toBeInTheDocument();
+    });
+
+    it('应渲染传入的 value', () => {
+      render(<TextInputArea value="测试内容" onChange={() => {}} />);
+      const textarea = screen.getByRole('textbox');
+      expect(textarea).toHaveValue('测试内容');
+    });
+
+    it('默认显示清空按钮', () => {
+      render(<TextInputArea value="有内容" onChange={() => {}} />);
+      expect(screen.getByRole('button', { name: 'textInputArea.clear' })).toBeInTheDocument();
+    });
+
+    it('无内容时清空按钮应隐藏', () => {
+      render(<TextInputArea value="" onChange={() => {}} />);
+      expect(screen.queryByRole('button', { name: 'textInputArea.clear' })).not.toBeInTheDocument();
+    });
+
+    it('disabled 时清空按钮应隐藏', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} disabled />);
+      expect(screen.queryByTitle('清空')).not.toBeInTheDocument();
+    });
+
+    it('readOnly 时清空按钮应隐藏', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} readOnly />);
+      expect(screen.queryByTitle('清空')).not.toBeInTheDocument();
+    });
+
+    it('showClear=false 时不显示清空按钮', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} showClear={false} />);
+      expect(screen.queryByTitle('清空')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('受控模式', () => {
+    it('输入时触发 onChange', () => {
+      const handleChange = vi.fn();
+      render(<TextInputArea value="" onChange={handleChange} />);
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: '新内容' } });
+
+      expect(handleChange).toHaveBeenCalledWith('新内容');
+    });
+
+    it('清空按钮触发 onChange("")', () => {
+      const handleChange = vi.fn();
+      render(<TextInputArea value="内容" onChange={handleChange} />);
+
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
+
+      expect(handleChange).toHaveBeenCalledWith('');
+    });
+  });
+
+  describe('非受控模式', () => {
+    it('defaultValue 应显示初始值', () => {
+      render(<TextInputArea defaultValue="初始值" />);
+      expect(screen.getByRole('textbox')).toHaveValue('初始值');
+    });
+
+    it('输入后应更新内部值', () => {
+      render(<TextInputArea defaultValue="" />);
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: '新内容' } });
+
+      expect(textarea).toHaveValue('新内容');
+    });
+
+    it('清空按钮应清空内容', () => {
+      render(<TextInputArea defaultValue="内容" />);
+
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
+
+      expect(screen.getByRole('textbox')).toHaveValue('');
+    });
+  });
+
+  describe('allowCopy 复制功能', () => {
+    it('allowCopy 且有内容时显示复制按钮', () => {
+      render(<TextInputArea value="可复制的内容" onChange={() => {}} allowCopy />);
+      expect(screen.getByRole('button', { name: 'textInputArea.copyContent' })).toBeInTheDocument();
+    });
+
+    it('allowCopy 但无内容时隐藏复制按钮', () => {
+      render(<TextInputArea value="" onChange={() => {}} allowCopy />);
+      expect(
+        screen.queryByRole('button', { name: 'textInputArea.copyContent' }),
+      ).not.toBeInTheDocument();
+    });
+
+    it('allowCopy=false 时不显示复制按钮', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} />);
+      expect(
+        screen.queryByRole('button', { name: 'textInputArea.copyContent' }),
+      ).not.toBeInTheDocument();
+    });
+
+    it('复制时调用 clipboard writeText', async () => {
+      const user = userEvent.setup();
+      const writeTextSpy = vi.spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined);
+
+      render(<TextInputArea value="测试" onChange={() => {}} allowCopy />);
+
+      await user.click(screen.getByRole('button', { name: 'textInputArea.copyContent' }));
+
+      expect(writeTextSpy).toHaveBeenCalledWith('测试');
+    });
+
+    it('复制失败时调用 clipboard writeText 并捕获错误', async () => {
+      const user = userEvent.setup();
+      const writeTextSpy = vi
+        .spyOn(navigator.clipboard, 'writeText')
+        .mockRejectedValue(new Error('失败'));
+
+      render(<TextInputArea value="测试" onChange={() => {}} allowCopy />);
+
+      await user.click(screen.getByRole('button', { name: 'textInputArea.copyContent' }));
+
+      expect(writeTextSpy).toHaveBeenCalledWith('测试');
+    });
+  });
+
+  describe('showCount 字符计数', () => {
+    it('显示当前字符数', () => {
+      render(<TextInputArea value="hello" onChange={() => {}} showCount />);
+      expect(screen.getByText('5')).toBeInTheDocument();
+    });
+
+    it('空内容时显示 0', () => {
+      render(<TextInputArea value="" onChange={() => {}} showCount />);
+      expect(screen.getByText('0')).toBeInTheDocument();
+    });
+
+    it('设置 maxLength 时显示计数上限', () => {
+      render(<TextInputArea value="ab" onChange={() => {}} showCount maxLength={10} />);
+      expect(screen.getByText('2 / 10')).toBeInTheDocument();
+    });
+  });
+
+  describe('maxLength', () => {
+    it('超出 maxLength 的输入应被截断', () => {
+      const handleChange = vi.fn();
+      render(<TextInputArea value="" onChange={handleChange} maxLength={5} />);
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: '123456' } });
+
+      expect(handleChange).not.toHaveBeenCalledWith('123456');
+    });
+
+    it('未超出 maxLength 的输入应正常触发', () => {
+      const handleChange = vi.fn();
+      render(<TextInputArea value="" onChange={handleChange} maxLength={5} />);
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: '123' } });
+
+      expect(handleChange).toHaveBeenCalledWith('123');
+    });
+  });
+
+  describe('验证规则', () => {
+    it('onChange 触发时验证失败应设置 error', () => {
+      render(
+        <TextInputArea
+          value=""
+          onChange={() => {}}
+          validateTrigger="onChange"
+          rules={[{ validator: (v) => v.length >= 3, message: '至少3个字符' }]}
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: 'ab' } });
+
+      expect(screen.getByText('至少3个字符')).toBeInTheDocument();
+    });
+
+    it('onBlur 触发时验证失败应设置 error', () => {
+      render(
+        <TextInputArea
+          value="ab"
+          onChange={() => {}}
+          validateTrigger="onBlur"
+          rules={[{ validator: (v) => v.length >= 3, message: '至少3个字符' }]}
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.blur(textarea);
+
+      expect(screen.getByText('至少3个字符')).toBeInTheDocument();
+    });
+
+    it('验证通过不应显示错误', () => {
+      render(
+        <TextInputArea
+          value="abc"
+          onChange={() => {}}
+          validateTrigger="onChange"
+          rules={[{ validator: (v) => v.length >= 3, message: '至少3个字符' }]}
+        />,
+      );
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: 'abcd' } });
+
+      expect(screen.queryByText('至少3个字符')).not.toBeInTheDocument();
+    });
+
+    it('onAction 触发时验证失败应阻止 action 执行', () => {
+      const handleAction = vi.fn();
+      render(
+        <TextInputArea
+          value="ab"
+          onChange={() => {}}
+          validateTrigger="onAction"
+          rules={[{ validator: (v) => v.length >= 3, message: '至少3个字符' }]}
+          actions={[
+            {
+              key: 'test',
+              label: '执行',
+              onClick: handleAction,
+            },
+          ]}
+        />,
+      );
+
+      fireEvent.click(screen.getByText('执行'));
+
+      expect(handleAction).not.toHaveBeenCalled();
+      expect(screen.getByText('至少3个字符')).toBeInTheDocument();
+    });
+  });
+
+  describe('操作栏 actions', () => {
+    it('应渲染顶部操作按钮', () => {
+      render(
+        <TextInputArea
+          value="内容"
+          onChange={() => {}}
+          actions={[{ key: 'top-action', label: '顶部操作', onClick: vi.fn() }]}
+        />,
+      );
+
+      expect(screen.getByText('顶部操作')).toBeInTheDocument();
+    });
+
+    it('应渲染底部操作按钮', () => {
+      render(
+        <TextInputArea
+          value="内容"
+          onChange={() => {}}
+          actions={[
+            { key: 'bottom-action', label: '底部操作', position: 'bottom', onClick: vi.fn() },
+          ]}
+        />,
+      );
+
+      expect(screen.getByText('底部操作')).toBeInTheDocument();
+    });
+
+    it('点击操作按钮触发 onClick', () => {
+      const handleClick = vi.fn();
+      render(
+        <TextInputArea
+          value="内容"
+          onChange={() => {}}
+          actions={[{ key: 'act', label: '操作', onClick: handleClick }]}
+        />,
+      );
+
+      fireEvent.click(screen.getByText('操作'));
+
+      expect(handleClick).toHaveBeenCalledWith(
+        '内容',
+        expect.objectContaining({
+          clear: expect.any(Function),
+          setError: expect.any(Function),
+        }),
+      );
+    });
+
+    it('disabled 为 true 时按钮应禁用', () => {
+      render(
+        <TextInputArea
+          value=""
+          onChange={() => {}}
+          actions={[{ key: 'act', label: '操作', onClick: vi.fn(), disabled: true }]}
+        />,
+      );
+
+      expect(screen.getByText('操作')).toBeDisabled();
+    });
+
+    it('disabled 为函数且返回 true 时按钮应禁用', () => {
+      render(
+        <TextInputArea
+          value=""
+          onChange={() => {}}
+          actions={[{ key: 'act', label: '操作', onClick: vi.fn(), disabled: (v) => !v }]}
+        />,
+      );
+
+      expect(screen.getByText('操作')).toBeDisabled();
+    });
+
+    it('primary 类型按钮应使用 contained 样式', () => {
+      render(
+        <TextInputArea
+          value="内容"
+          onChange={() => {}}
+          actions={[
+            { key: 'p', label: '主要', type: 'primary', position: 'bottom', onClick: vi.fn() },
+          ]}
+        />,
+      );
+
+      const btn = screen.getByText('主要');
+      expect(btn).toHaveClass('bg-primary', 'text-primary-foreground');
+    });
+  });
+
+  describe('title', () => {
+    it('应渲染 title', () => {
+      render(<TextInputArea title="输入区域" value="" onChange={() => {}} />);
+      expect(screen.getByText('输入区域')).toBeInTheDocument();
+    });
+
+    it('不设置 title 时不渲染标题', () => {
+      const { container } = render(<TextInputArea value="" onChange={() => {}} />);
+      expect(container.querySelector('.text-muted-foreground')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('disabled 和 readOnly', () => {
+    it('disabled 时输入框应禁用', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} disabled />);
+      expect(screen.getByRole('textbox')).toBeDisabled();
+    });
+
+    it('readOnly 时输入框应只读', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} readOnly />);
+      // MUI TextField 的 readOnly 通过 inputProps 设置，textarea 不会被禁用
+      expect(screen.getByRole('textbox')).not.toBeDisabled();
+    });
+  });
+
+  describe('autoFocus', () => {
+    it('autoFocus 应自动聚焦', () => {
+      render(<TextInputArea autoFocus value="" onChange={() => {}} />);
+      expect(document.activeElement).toBe(screen.getByRole('textbox'));
+    });
+  });
+
+  describe('复制功能', () => {
+    it('复制成功时调用 clipboard writeText', async () => {
+      const user = userEvent.setup();
+      const writeTextSpy = vi.spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined);
+
+      render(<TextInputArea value="测试" onChange={() => {}} allowCopy />);
+      await user.click(screen.getByRole('button', { name: 'textInputArea.copyContent' }));
+
+      expect(writeTextSpy).toHaveBeenCalledWith('测试');
+    });
+  });
+
+  describe('onClear 回调', () => {
+    it('点击清空按钮时应调用 onClear', () => {
+      const handleClear = vi.fn();
+      render(<TextInputArea value="内容" onChange={() => {}} onClear={handleClear} />);
+
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
+
+      expect(handleClear).toHaveBeenCalledOnce();
+    });
+
+    it('不传 onClear 时清空按钮应正常工作', () => {
+      render(<TextInputArea defaultValue="内容" />);
+
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
+
+      expect(screen.getByRole('textbox')).toHaveValue('');
+    });
+  });
+
+  describe('externalError 外部错误', () => {
+    it('设置 externalError 时应显示错误状态', () => {
+      render(<TextInputArea value="内容" onChange={() => {}} externalError="JSON 格式无效" />);
+
+      expect(screen.getByText('JSON 格式无效')).toBeInTheDocument();
+    });
+
+    it('externalError 为空时应隐藏错误状态', () => {
+      const { rerender } = render(
+        <TextInputArea value="内容" onChange={() => {}} externalError="错误" />,
+      );
+
+      expect(screen.getByText('错误')).toBeInTheDocument();
+
+      rerender(<TextInputArea value="内容" onChange={() => {}} externalError="" />);
+
+      expect(screen.queryByText('错误')).not.toBeInTheDocument();
+    });
+
+    it('externalError 优先级高于内部验证错误', () => {
+      render(
+        <TextInputArea
+          value="ab"
+          onChange={() => {}}
+          externalError="外部错误"
+          validateTrigger="onChange"
+          rules={[{ validator: (v) => v.length >= 3, message: '内部验证错误' }]}
+        />,
+      );
+
+      expect(screen.getByText('外部错误')).toBeInTheDocument();
+      expect(screen.queryByText('内部验证错误')).not.toBeInTheDocument();
+    });
+
+    it('externalError 清除后应显示内部验证错误', () => {
+      const { rerender } = render(
+        <TextInputArea
+          value="ab"
+          onChange={() => {}}
+          externalError="外部错误"
+          validateTrigger="onChange"
+          rules={[{ validator: (v) => v.length >= 3, message: '至少3个字符' }]}
+        />,
+      );
+
+      expect(screen.getByText('外部错误')).toBeInTheDocument();
+
+      rerender(
+        <TextInputArea
+          value="ab"
+          onChange={() => {}}
+          validateTrigger="onChange"
+          rules={[{ validator: (v) => v.length >= 3, message: '至少3个字符' }]}
+        />,
+      );
+
+      expect(screen.queryByText('外部错误')).not.toBeInTheDocument();
+
+      const textarea = screen.getByRole('textbox');
+      fireEvent.change(textarea, { target: { value: 'a' } });
+
+      expect(screen.getByText('至少3个字符')).toBeInTheDocument();
+    });
+  });
+
+  describe('autoResize', () => {
+    it('autoResize=true 时设置 minRows/maxRows', () => {
+      const { container } = render(
+        <TextInputArea value="" onChange={() => {}} minRows={3} maxRows={8} />,
+      );
+
+      const textarea = container.querySelector('textarea');
+      expect(textarea).toBeInTheDocument();
+    });
+
+    it('autoResize=false 时设置固定 rows', () => {
+      const { container } = render(<TextInputArea value="" onChange={() => {}} minRows={5} />);
+
+      const textarea = container.querySelector('textarea');
+      expect(textarea).toBeInTheDocument();
+    });
+  });
+
+  describe('样式集成', () => {
+    it('应透传 className', () => {
+      const { container } = render(
+        <TextInputArea value="" onChange={() => {}} className="custom-class" />,
+      );
+
+      expect(container.firstChild).toHaveClass('custom-class');
+    });
+  });
+});

src/components/__tests__/ToolCard.test.tsx

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import ToolCard from '@/pages/Dashboard/ToolCard';
+import { Clock } from 'lucide-react';
+
+describe('ToolCard 组件', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('渲染测试', () => {
+    it('应渲染标题和描述', () => {
+      render(
+        <ToolCard
+          title="测试工具"
+          description="这是一个测试工具"
+          colorKey="primary"
+          icon={Clock}
+          onNavigate={() => {}}
+        />,
+      );
+
+      expect(screen.getByText('测试工具')).toBeInTheDocument();
+      expect(screen.getByText('这是一个测试工具')).toBeInTheDocument();
+    });
+
+    it('无描述时仅渲染标题', () => {
+      render(<ToolCard title="仅标题" colorKey="primary" icon={Clock} onNavigate={() => {}} />);
+
+      expect(screen.getByText('仅标题')).toBeInTheDocument();
+    });
+
+    it('应渲染图标', () => {
+      const { container } = render(
+        <ToolCard title="带图标" colorKey="primary" icon={Clock} onNavigate={() => {}} />,
+      );
+
+      const svgElement = container.querySelector('svg');
+      expect(svgElement).toBeInTheDocument();
+    });
+
+    it('提供快照内容时应渲染快照', () => {
+      render(
+        <ToolCard
+          title="带快照"
+          colorKey="primary"
+          icon={Clock}
+          onNavigate={() => {}}
+          snapshot={<div data-testid="snapshot">快照内容</div>}
+        />,
+      );
+
+      expect(screen.getByTestId('snapshot')).toBeInTheDocument();
+    });
+
+    it('未提供快照时不渲染快照区域', () => {
+      const { container } = render(
+        <ToolCard
+          title="无快照"
+          colorKey="primary"
+          icon={Clock}
+          onClick={() => {}}
+          onNavigate={function (): void {
+            throw new Error('Function not implemented.');
+          }}
+        />,
+      );
+
+      expect(container.querySelector('[data-testid="snapshot"]')).not.toBeInTheDocument();
+    });
+
+    it('应使用 CardActionArea 渲染，支持键盘聚焦', () => {
+      render(<ToolCard title="可聚焦" colorKey="primary" icon={Clock} onNavigate={() => {}} />);
+
+      const button = screen.getByRole('button', { name: /可聚焦/ });
+      expect(button).toBeInTheDocument();
+    });
+  });
+
+  describe('交互测试', () => {
+    it('点击时应调用 onClick', () => {
+      const handleClick = vi.fn();
+      render(<ToolCard title="可点击" colorKey="primary" icon={Clock} onNavigate={handleClick} />);
+
+      const button = screen.getByRole('button', { name: /可点击/ });
+      fireEvent.click(button);
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('按 Enter 键时应调用 onClick', async () => {
+      const handleClick = vi.fn();
+      render(
+        <ToolCard title="键盘可触发" colorKey="primary" icon={Clock} onNavigate={handleClick} />,
+      );
+
+      const button = screen.getByRole('button', { name: /键盘可触发/ });
+      await act(async () => {
+        button.focus();
+        await userEvent.keyboard('{Enter}');
+      });
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('样式测试', () => {
+    it('应应用自定义颜色代码', () => {
+      const { container } = render(
+        <ToolCard title="自定义颜色" colorKey="warning" icon={Clock} onNavigate={() => {}} />,
+      );
+
+      const svgElement = container.querySelector('svg');
+      expect(svgElement).toBeInTheDocument();
+    });
+  });
+});

src/components/__tests__/TopBar.test.tsx

@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import type { PageType } from '@/types/storage';
+import React from 'react';
+import TopBar from '@/components/TopBar';
+import { RouterProvider } from '@/providers/RouterProvider';
+import { ThemeModeProvider } from '@/providers/ThemeModeProvider';
+
+// matchMedia must be mocked before ThemeModeProvider is imported
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  })),
+});
+
+const mockRouterValue = {
+  currentPage: 'dashboard' as PageType,
+  visiblePages: ['dashboard', 'timestamp'] as PageType[],
+  pageOrder: ['timestamp'] as PageType[],
+  isLoaded: true,
+  navigateTo: vi.fn(),
+  syncNavigation: vi.fn(),
+  goBack: vi.fn(),
+  setVisiblePages: vi.fn(),
+  setPageOrder: vi.fn(),
+};
+
+vi.mock('@/providers/RouterProvider', () => ({
+  useRouter: () => mockRouterValue,
+  RouterProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+describe('TopBar 组件', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const renderWithProvider = (ui: React.ReactElement) => {
+    return render(
+      <ThemeModeProvider>
+        <RouterProvider>{ui}</RouterProvider>
+      </ThemeModeProvider>,
+    );
+  };
+
+  describe('渲染测试', () => {
+    it('不在 dashboard 时应渲染返回按钮', () => {
+      mockRouterValue.currentPage = 'timestamp';
+      renderWithProvider(<TopBar onOpenOptions={vi.fn()} />);
+      expect(screen.getByLabelText('返回')).toBeInTheDocument();
+    });
+
+    it('在 dashboard 上不应渲染返回按钮', () => {
+      mockRouterValue.currentPage = 'dashboard';
+      renderWithProvider(<TopBar onOpenOptions={vi.fn()} />);
+      expect(screen.queryByLabelText('返回')).not.toBeInTheDocument();
+    });
+
+    it('应渲染设置按钮', () => {
+      renderWithProvider(<TopBar onOpenOptions={vi.fn()} />);
+      expect(screen.getByLabelText('设置')).toBeInTheDocument();
+    });
+  });
+
+  describe('交互测试', () => {
+    it('点击设置按钮时应调用 onOpenOptions', () => {
+      const handleOpenOptions = vi.fn();
+      renderWithProvider(<TopBar onOpenOptions={handleOpenOptions} />);
+
+      fireEvent.click(screen.getByLabelText('设置'));
+      expect(handleOpenOptions).toHaveBeenCalledTimes(1);
+    });
+
+    it('点击返回按钮时应调用 goBack', () => {
+      mockRouterValue.currentPage = 'timestamp';
+      renderWithProvider(<TopBar onOpenOptions={vi.fn()} />);
+
+      fireEvent.click(screen.getByLabelText('返回'));
+      expect(mockRouterValue.goBack).toHaveBeenCalledTimes(1);
+    });
+  });
+});